Daily Archives: February 17, 2014

SKIP

Posted on by vivaclipper

SKIP

Move the record pointer to a new position

Syntax

      SKIP [<nRecords>] [ALIAS <idAlias> | <nWorkArea>]

Arguments

<nRecords> is a numeric expression specifying the number of records to move the record pointer from the current position. A positive value moves the record pointer forward and a negative value moves the record pointer backward.

ALIAS <idAlias>|<nWorkArea> specifies the alias name as a literal identifier or the work area as a numeric expression.

SKIP specified with no arguments moves the record pointer forward one record.

Description

SKIP moves the record pointer to a new position relative to the current position in the current work area and within the current filter, if there is one. SKIP is generally used for operations, such as reporting, that need to go to the next record in a database file.

If the alias clause is specified, the pointer can be moved in another work area without SELECTing that work area. SKIP can move either forward or backward. If there is no active index, SKIP moves the record pointer relative to the current position in the target database file. If there is an active index, SKIP moves the pointer relative to the current position in the index instead of the database file.

Attempting to SKIP forward beyond the end of file positions the record pointer at LASTREC() + 1, and EOF() returns true (.T.). Attempting to SKIP backward beyond the beginning of file moves the pointer to the first record, and BOF() returns true (.T.).

In a network environment, any record movement command, including SKIP, makes changes to the current work area visible to other applications if the current file is shared and the changes were made during an RLOCK(). To force an update to become visible without changing the current record position, use SKIP 0. If, however, the changes were made during an FLOCK(), visibility is not guaranteed until the lock is released, a COMMIT is performed, or the file is closed. Refer to the “Network Programming” chapter for more information.

Examples

      .  This example uses SKIP with various arguments and shows their
         results:

      USE Customers NEW
      SKIP
      ? RECNO()                  // Result: 2
      SKIP 10
      ? RECNO()                  // Result: 12
      SKIP -5
      ? RECNO()                  // Result: 7

      .  This example moves the record pointer in a remote work area:

      USE Customers NEW
      USE Invoices NEW
      SKIP ALIAS Customers

      .  This example prints a report using SKIP to move the record
         pointer sequentially through the Customer database file:

      LOCAL nLine := 99
      USE Customers NEW
      SET PRINTER ON
      DO WHILE !EOF()
         IF nLine > 55
            EJECT
            nLine := 1
         ENDIF
            ? Customer, Address, City, State, Zip
            nLine++
            SKIP
         ENDDO
      SET PRINTER OFF
      CLOSE Customers

Seealso

BOF(), COMMIT, DBSKIP(), EOF(), GO, LOCATE, RECNO(), SEEK

SET ORDER

Posted on by vivaclipper

SET ORDER

Select the controlling order

Syntax

      SET ORDER TO [<nOrder> | [TAG <cOrderName>]
            [IN <xcOrderBagName>]]

Arguments

TAG is an optional clause that provides compatibility with RDDs that access multiple-order order bags. You must use this keyword anytime you specify <cOrderName>.

<cOrderName> is the name of an order, a logical arrangement of a database according to a keyed pair. This order will become the controlling order in the order list. If you specify <cOrderName>, you must use the keyword TAG.

Note: This differs from dBASE and FoxPro where TAG is totally optional.

<nOrder> is the number of the target order in the order list. You may represent the order as an integer or as a character string enclosed in quotes.

IN <xcOrderBagName> is the name of a disk file containing one or more orders. You may specify <xcOrderBagName> as the file name with or without the path name or appropriate extension. If you do not include the extension as part of <xcOrderBagName>, Harbour uses the default extension of the current RDD.

Description

When you SET ORDER TO a new controlling order (index), all orders are properly updated when you either append or edit records. This is true even if you SET ORDER TO 0. After a change of controlling order, the record pointer still points to the same record.

SET ORDER TO 0 restores the database access to natural order, but leaves all orders open. SET ORDER TO with no arguments closes all orders and empties the order list

Though you may use <cOrderName> or <nOrder> to specify the target order, <nOrder> is only provided for compatibility with earlier versions of Harbour. Using <cOrderName> is a surer way of accessing the correct order in the order list.

If you supply <xcOrderBagName>, only the orders belonging to <xcOrderBagName> in the order list are searched. Usually you need not specify <xcOrderBagName> if you use unique order names throughout an application.

To determine which order is the controlling order use the ORDSETFOCUS() function.

In RDDs that support production or structural indices (e.g., DBFCDX), if you specify a tag but do not specify an order bag, the tag is created and added to the index. If no production or structural index exists, it will be created and the tag will be added to it. When using RDDs that support multiple order bags, you must explicitly SET ORDER (or ORDSETFOCUS()) to the desired controlling order. If you do not specify a controlling order, the data file will be viewed in natural order.

SET ORDER can open orders in a network environment instead of the INDEX clause of the USE command. Generally, specify USE, and then test to determine whether the USE succeeded. If it did succeed, open the associated orders with SET ORDER. See the example below.

Examples

      USE Customer NEW
      IF (! NETERR())
         SET ORDER TO Customer
      ENDIF

      SET ORDER TO "CuAcct"         // CuAcct is an Order in Customer

Seealso

INDEX, INDEXORD(), SEEK, SET INDEX, USE

SET MBLOCKSIZE

Posted on by vivaclipper

SET MBLOCKSIZE

Change the block size for memo files

Syntax

      SET MBLOCKSIZE TO <nSize>

Arguments

<nSize> is the memo file block size in bytes. The initial memo file block size depends on the RDD. For most drivers that support the .dbt memo file format, it is 512 bytes. However, if you are using BLOB files (.dbv memo file format) via inheritance from the DBFMEMO driver, the default is 1.

Description

SET MBLOCKSIZE is functionally equivalent to calling DBINFO( DBI_MBLOCKSIZESIZE, <nSize>). Refer to this function for more information. SET MBLOCKSIZE sets the block size for the memo file associated with the database.

The block size is the minimum amount of space in bytes allocated in memo files when storing character strings in memo fields.

The initial memo block size depends on the replaceable database driver used to open a database in a work area.

The following table lists the default sizes for memo blocks of RDDs shipped with Harbour:

Default memo block sizes

         Memo type Block size Changeable
         --------- ---------- ----------
             DBT      512     No
             FPT       64     Yes
             SMT       64     Yes

Examples

      .  The following example illustrates the SET MBLOCKSIZE command:
      USE Inventor NEW
      SET MBLOCKSIZE TO 256
      ? DBINFO(DBI_MBLOCKSIZESIZE)         // Result: 256

Seealso

DBINFO(), RddSetDefault(), Set()

SET MARGIN

Posted on by vivaclipper

SET MARGIN

Set the page offset for all printed output

Syntax

      SET MARGIN TO [<nPageOffset>]

Arguments

TO <nPageOffset> is a positive number that defines the number of column positions to indent from the left side of the page for subsequent printed output. A negative value resets the MARGIN to zero.

SET MARGIN TO with no argument resets the page offset to zero, the default value.

Description

SET MARGIN is valid for all output directed to the printer from console commands and @…SAY. With console output, the <nPageOffset> indent is output whenever there is a new line. With @…SAY, <nPageOffset> is added to each column value. SET MARGIN has no effect on screen output.

Note

Printing with @…SAY and PCOL() with a MARGIN SET in most cases adds the MARGIN to each column position. This happens because PCOL() accurately reflects the print column position including the last <nPageOffset> output. The best approach is to avoid the use of SET MARGIN with PCOL() for relative column addressing.

Examples

      .  This example sets a page offset of 5, and then prints a list
         from Sales.dbf:

      USE Sales NEW
      SET MARGIN TO 5
      LIST Branch, Salesman TO PRINTER
      SET MARGIN TO

Seealso

@…SAY, PCOL(), SET DEVICE, SET PRINTER

SET INDEX

Posted on by vivaclipper

SET INDEX

Open one or more order bags in the current work area

Syntax

      SET INDEX TO [<xcOrderBagName list>] [ADDITIVE]

Arguments

<cOrderBagName list> specifies order bags to be emptied into the order list of the current work area.

ADDITIVE adds order bags to an existing order list.

Description

By default, SET INDEX, without the ADDITIVE clause, clears the currently active order list, and then constructs a new order list from the orders in the specified order bags in the current work area. When several order bags are opened, the first order in the first order bag becomes the controlling order (has focus). The record pointer is initially positioned at the first logical identity in this order.

If an order list exists when you SET INDEX … ADDITIVE, the orders in the new order bag are added to the end of the order list. The previous controlling order continues to be the controlling order.

If no order list exists when you SET INDEX … ADDITIVE, the first order in the first order bag in <cOrderBagName list> becomes the controlling order.

During database processing, all open orders are updated whenever a key value is appended or changed, unless the order was created using a scoping condition and the key value does not match. To change the controlling order without issuing another SET INDEX command, use SET ORDER or ORDSETFOCUS(). To add orders without closing the currently open orders, use the ADDITIVE clause.

Examples

      .  This example opens a database and its associated indexes:

      USE Sales NEW
      SET INDEX TO Sales, Sales1, Sales2

      .  This example opens an index without closing any indexes that
         are already open:

      SET INDEX TO Sales3 ADDITIVE

SET FORMAT

Posted on by vivaclipper

SET FORMAT*

Activate a format when READ is executed

Syntax

      SET FORMAT TO [<idProcedure>[.<ext>]]

Arguments

TO <idProcedure> is a format (.fmt) file, a program (.prg) file, or a procedure.

<ext> is the extension of the format file. If not specified, the default extension is (.fmt).

SET FORMAT TO with no argument deactivates the current format.

Description

SET FORMAT defines a procedure to execute when a READ is invoked. Unlike the interpreted environment, formats are not opened and executed at runtime. Instead, the Harbour compiler treats SET FORMAT the same as a DO command. The compiler first looks to see whether it has already compiled a procedure with the same name as <idProcedure>. If it has, it uses that procedure for the reference. If <idProcedure> is not found, the compiler looks to disk for a file with the same name. If this file is not found, an external reference is generated that must be resolved at link time.

SET FORMAT is a compatibility command and not recommended.

Notes

. Active format procedures: Unlike other dialects where each work area can have an active format, Harbour supports only one active format procedure for all work areas.

. Screen CLEARing: Harbour does not clear the screen when a format procedure is executed.

. Legal statements: Format procedures allow statements and commands in addition to @…SAY and @…GET.

. Multiple pages: Harbour does not support multiple-page format procedures.

Examples

      .  This example uses a format procedure to add records to a
         database file until the user presses Esc:

      USE Sales NEW
      SET FORMAT TO SalesScr
      DO WHILE LASTKEY() != 27
         APPEND BLANK
         READ
      ENDDO
      RETURN

      PROCEDURE SalesScr
         @ 12, 12 SAY "Branch     : " GET  Branch
         @ 13, 12 SAY "Salesman   : " GET  Salesman
         RETURN

Seealso

@…GET, @…SAY, PROCEDURE, READ

SET FILTER

Posted on by vivaclipper

SET FILTER

Hide records not meeting a condition

Syntax

      SET FILTER TO [<lCondition>]

Arguments

TO <lCondition> is a logical expression that defines a specific set of current work area records accessible for processing.

SET FILTER TO without an argument deactivates the filter condition.

Description

When a FILTER condition is SET, the current work area acts as if it contains only the records that match the specified condition. A filter condition is one of the properties of a work area. Once a FILTER has been SET, the condition can be returned as a character string using the DBFILTER() function.

Most commands and functions that move the record pointer honor the current filter with the exception of those commands that access records by record number. This includes GOTO, commands specified with the RECORD clause, and RELATIONs linked by numeric expression to a work area with no active index.

Once a FILTER is SET, it is not activated until the record pointer is moved from its current position. You can use GO TOP to activate it.

As with SET DELETED, a filter has no effect on INDEX and REINDEX.

Note

Although SET FILTER makes the current work area appear as if it contains a subset of records, it, in fact, sequentially processes all records in the work area. Because of this, the time required to process a filtered work area will be the same as an unfiltered work area.

Examples

      .  This example filters Employee.dbf to only those records where
         the age is greater than 50:

      USE Employee INDEX Name NEW
      SET FILTER TO Age > 50
      LIST Lastname, Firstname, Age, Phone
      SET FILTER TO

Seealso

DBFILTER(), DBSETFILTER(), SET DELETED

SET EXCLUSIVE

Posted on by vivaclipper

SET EXCLUSIVE*

Establish shared or exclusive USE of database files

Syntax

      SET EXCLUSIVE ON | off | <xlToggle>

Arguments

ON causes database files to be opened in exclusive (nonshared) mode.

OFF causes database files to be opened in shared mode.

<xlToggle> is a logical expression that must be enclosed in parentheses. A value of true (.T.) is the same as ON, and a value of false (.F.) is the same as OFF.

Description

In a network environment, SET EXCLUSIVE determines whether a USE command specified without the EXCLUSIVE or SHARED clause automatically opens database, memo, and index files EXCLUSIVE. When database files are opened EXCLUSIVE, other users cannot USE them until they are CLOSEd. In this mode, file and record locks are unnecessary.

When EXCLUSIVE is ON (the default), all database and associated files open in a nonshared (exclusive) mode unless the USE command is specified with the SHARED clause. Use EXCLUSIVE only for operations that absolutely require EXCLUSIVE USE of a database file, such as PACK, REINDEX, and ZAP.

When EXCLUSIVE is OFF, all files are open in shared mode unless the USE command is specified with the EXCLUSIVE clause. Control access by other users programmatically using RLOCK() and FLOCK().

SET EXCLUSIVE is a compatibility command and not recommended. It is superseded by the EXCLUSIVE and SHARED clauses of the USE command.

Refer to the “Network Programming” chapter for more information.

Notes

. Error handling: Attempting to USE a database file already opened EXCLUSIVE by another user generates a runtime error and sets NETERR() to true (.T.). After control returns to the point of error, you can test NETERR() to determine whether the USE failed.

Seealso

FLOCK(), NETERR(), RLOCK(), USE, DBUSEAREA()

SET EXACT

Posted on by vivaclipper

SET EXACT*

Toggle exact matches for character strings

Syntax

      SET EXACT on | OFF | <xlToggle>

Arguments

ON enforces exact comparison of character strings including length.

OFF resumes normal character string comparison.

<xlToggle> is a logical expression that must be enclosed in parentheses. A value of true (.T.) is the same as ON, and a value of false (.F.) is the same as OFF.

Description

SET EXACT determines how two character strings are compared using the relational operators (=, >, <, =>, =<). When EXACT is OFF, strings are compared according to the following rules. assume two character strings cLeft and cRight where the expression to test is (cLeft = cRight):

. If cRight is a null string (“”), return true (.T.).

. If LEN(cRight) is greater than LEN(cLeft), return false (.F.).

. Otherwise, compare all characters in cRight with cLeft. If all characters in cRight equal cLeft, return true (.T.); otherwise, return false (.F.).

With EXACT ON, all relational operators except the double equal operator (==) treat two strings as equal, if they match exactly, excluding trailing spaces. With the double equal operator (==), all characters in the string are significant, including trailing spaces.

SET EXACT is a compatibility command and not recommended.

Notes

. Compatibility: In Harbour, unlike other dialects, SET EXACT has no affect on operations other than relational operators. This includes the SEEK and FIND commands. If you need to seek exact matches of character keys, use the example user-defined function SeekExact() in the SEEK command reference.

Examples

      .  These examples show various results of the equal operator (=)
         with SET EXACT:

      SET EXACT OFF
      ? "123" = "12345"            // Result: .F.
      ? "12345" = "123"            // Result: .T.
      ? "123" = ""                 // Result: .T.
      ? "" = "123"                 // Result: .F.
      ? "123" = "123  "            // Result: .F.
      //
      SET EXACT ON
      ? "123" = "12345"            // Result: .F.
      ? "12345" = "123"            // Result: .F.
      ? "123" = ""                 // Result: .F.
      ? "" = "123"                 // Result: .F.
      ? "123" = "123  "            // Result: .T.

Seealso

SEEK, Operators

SET UNIQUE

Posted on by vivaclipper

SET UNIQUE*

Toggle inclusion of non-unique keys into an index

Syntax

      SET UNIQUE on | OFF | <xlToggle>

Arguments

ON causes index files to be created with a uniqueness attribute.

OFF causes index files to be created without a uniqueness attribute.

<xlToggle> is a logical expression that must be enclosed in parentheses. A value of true (.T.) is the same as ON, and a value of false (.F.) is the same as OFF.

Description

SET UNIQUE is a database command that controls whether indexes are created with uniqueness as an attribute. With UNIQUE ON, new indexes are created including only unique keys. This is the same as creating an index with the INDEX…UNIQUE command.

If, during the creation or update of an unique index, two or more records are encountered with the same key value, only the first record is included in the index. When the unique index is updated, REINDEXed, or PACKed, only unique records are maintained, without regard to the current SET UNIQUE value.

Changing key values in a unique index has important implications. First, if a unique key is changed to the value of a key already in the index, the changed record is lost from the index. Second, if there is more than one instance of a key value in a database file, changing the visible key value does not bring forward another record with the same key until the index is rebuilt with REINDEX, PACK, or INDEX…UNIQUE.

With UNIQUE OFF, indexes are created with all records in the index. Subsequent updates to the database files add all key values to the index independent of the current UNIQUE SETting.

SET UNIQUE is a compatibility command not recommended. It is superseded by the UNIQUE clause of the INDEX command.

Seealso

DBCREATEIND(), INDEX, PACK, REINDEX, SEEK