Daily Archives: July 16, 2013

C5_ORDKEYNO

Posted on by vivaclipper 
 ORDKEYNO()
 Get the logical record number of the current record
------------------------------------------------------------------------------
 Syntax

     ORDKEYNO([<cOrder> | <nPosition>],
        [<cIndexFile>]) --> nKeyNo

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid order will raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

 Returns

     ORDKEYNO() returns the relative position of the current record in the
     specified order as a numeric value.  ORDKEYNO() respects the scope and
     for condition of the order by returning zero if the record pointer is
     positioned on an invalid record or if EOF() is true (.T.).

 Description

     ORDKEYNO() returns the logical record number of a key in an order.  This
     is in contrast to the physical record number (returned using the RECNO()
     function), which is the relative position of the record in the physical
     database file.

     Tip:  This function can be useful for displaying scroll bars and
     messages, such as "Record 9 of 123," when viewing records in a browser.

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example shows the difference between physical and logical
        record number:

        USE Customer            // Assuming 1000 records
        SET INDEX TO First      // Make records in first order

        GO TOP                  // Position the data pointer at
                                // the first record

        ? ORDKEYNO()            // Result: 1

        DBSKIP(10)
        ? ORDKEYNO()            // Result: 11
        ? RECNO()               // Result: Physical record number

        DBGOBOTTOM()
        ? ORDKEYNO()            // Result: 1000
        ? RECNO()               // Result: Physical record number

 Files   Library is CLIPPER.LIB.

See Also: ORDKEYCOUNT() ORDKEYGOTO() ORDSCOPE() RECNO()




			

			
						

	
	



		
			


	

		
C5_ORDKEYGOTO


		

		Posted on  by vivaclipper		

	


		

		
 ORDKEYGOTO()
 Move to a record specified by its logical record number in the controlling
 order
------------------------------------------------------------------------------
 Syntax

     ORDKEYGOTO(<nKeyNo>) --> lSuccess

 Arguments

     <nKeyNo> is the logical record number.  If the value specified does
     not satisfy the scope or for condition for the order, the record pointer
     is positioned at the end of file.

 Returns

     ORDKEYGOTO() returns true (.T.) if successful; otherwise, it returns
     false (.F.).

 Description

     ORDKEYGOTO() is the complement to ORDKEYNO().  ORDKEYNO() returns the
     logical record number (i.e., its position in the controlling order) of
     the current record, and ORDKEYGOTO() moves the record pointer to the
     specified logical record.

     Tip:  This function can be useful when displaying scroll bars.  If
     the user clicks on a certain position on the scroll bar, you can move to
     the corresponding record by calling ORDKEYGOTO().

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example shows the difference between physical and logical
        record number:

        USE Customer
        SET INDEX TO First   // Make records in first name
                             // order
        ORDKEYGOTO(100)      // Go to the 100th logical record
        ? RECNO()            // Returns the physical record
                             // number
        ? ORDKEYNO()         // Returns 100, the logical
                             // record no

 Files   Library is CLIPPER.LIB.




See Also: ORDKEYCOUNT() ORDKEYNO()


 



        
    
			

	
	



		
			


	

		
C5_ORDKEYDEL


		

		Posted on  by vivaclipper		

	


		

		
 ORDKEYDEL()
 Delete a key from a custom built order
------------------------------------------------------------------------------
 Syntax

     ORDKEYDEL([<cOrder> | <nPosition>],
        [<cIndexFile>],
        [<expKeyValue>]) --> lSuccess

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid order, such as one that is not custom built, will
     raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

     <expKeyValue> is a specific key value that you want to delete for
     the current record.  The data type must match that of the order.  If not
     specified, the order's key expression is evaluated for the current
     record and deleted from the order.

 Returns

     ORDKEYDEL() returns true (.T.) if successful; otherwise, it returns
     false (.F.).

 Description

     ORDKEYDEL() deletes a key from a custom built order which is an order
     that is not automatically maintained by the DBFCDX driver.  You can
     determine if an order is custom built using DBORDERINFO(DBOI_CUSTOM,
     ...).  When you create such an order, it is initially empty.  You must
     then manually add and delete keys using ORDKEYADD() and ORDKEYDEL().

     Note:  An existing order can be changed to a custom built order by
     using the DBORDERINFO() function.

     ORDKEYDEL() evaluates the key expression (or <expKeyValue>, if
     specified), and then deletes the key for the current record from the
     order.

     ORDKEYDEL() will fail if:

     .  The record pointer is positioned on an invalid record (for
        example, EOF() returns true (.T.) or the record pointer is positioned
        on a record that falls outside the order's scope or for condition)

     .  The specified order is not custom built

     .  The specified order does not exist

     .  No order was specified and there is no controlling order

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example creates a custom index, adds every fiftieth
        record to it, and deletes every hundredth record:

        USE Customer VIA "DBFCDX"
        // Create custom-built order that is initially empty
        INDEX ON LastName TO Last CUSTOM

        // Add every 50th record
        FOR n := 1 TO RECCOUNT() STEP 50
           GOTO n
           ORDKEYADD()
        NEXT

        // Remove every 100th record
        FOR n := 1 TO RECCOUNT() STEP 100
           GOTO n
           ORDKEYDEL()
        NEXT

 Files   Library is CLIPPER.LIB.




See Also: ORDFOR() ORDKEYADD() ORDSCOPE()


 

			

	
	



		
			


	

		
C5_ORDKEYCOUNT


		

		Posted on  by vivaclipper		

	


		

		
 ORDKEYCOUNT()
 Return the number of keys in an order
------------------------------------------------------------------------------
 Syntax

     ORDKEYCOUNT([<cOrder> | <nPosition>],
        [<cIndexFile>]) --> nKeys

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid order will raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

 Returns

     ORDKEYCOUNT() returns the number of keys in the specified order.

 Description

     ORDKEYCOUNT() counts the keys in the specified order and returns the
     result as a numeric value.  If the order is not conditional and no scope
     has been set for it, ORDKEYCOUNT() is identical to RECCOUNT(), returning
     the number of records in the database file.  However, for a conditional
     order, there may be fewer keys than there are records, since some
     records may not meet the order's for condition or may not fall inside
     the scope specified by ORDSCOPE()--in counting the keys, ORDKEYCOUNT()
     respects the currently defined scope and for condition.

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example demonstrates using ORDKEYCOUNT() with various
        orders:

        USE customer
        // Assume 1000 total records,
        // 500 less than thirty years old, and
        // 895 making less than 50,000

        INDEX ON Age TO Age

        INDEX ON First TO First FOR Age < 30
        INDEX ON Last TO Last FOR Salary < 50000

        // Age is the controlling order
        SET INDEX TO Age, First, Last

        ? RECCOUNT()                     // Result: 1000
        ? ORDKEYCOUNT()                  // Result: 1000

        ? ORDKEYCOUNT("First")         // Result: 500
        ? ORDKEYCOUNT(3)               // Result: 895

 Files   Library is CLIPPER.LIB.




See Also: ORDKEYGOTO() ORDKEYNO() ORDSCOPE()





			

	
	



		
			


	

		
C5_ORDKEYADD


		

		Posted on  by vivaclipper		

	


		

		
 ORDKEYADD()
 Add a key to a custom built order
------------------------------------------------------------------------------
 Syntax

     ORDKEYADD([<cOrder> | <nPosition>],
        [<cIndexFile>],[<expKeyValue>]) --> lSuccess

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid order, such as one that is not custom built, will
     raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

     <expKeyValue> is a specific key value that you want to add for the
     current record.  The data type must match that of the order.  If not
     specified, the order's key expression is evaluated for the current
     record and added to the order.

 Returns

     ORDKEYADD() returns true (.T.) if successful; otherwise, it returns
     false (.F.).

 Description

     ORDKEYADD() adds keys to a custom built order which is an order that is
     not automatically maintained by the DBFCDX driver.  You can determine if
     an order is custom built using DBORDERINFO(DBOI_CUSTOM, ...).  When you
     create such an order, it is initially empty.  You must then manually add
     and delete keys using ORDKEYADD() and ORDKEYDEL().

     Note:  An existing order can be changed to a custom built order by
     using the DBORDERINFO() function.

     ORDKEYADD() evaluates the key expression (or <expKeyValue>, if
     specified), and then adds the key for the current record to the order.
     If the order has a for condition, the key will be added only if that
     condition is met, and then only if it falls within the current scoping
     range.

     Note:  You can add several keys for the same record with consecutive
     calls to ORDKEYADD().

     ORDKEYADD() will fail if:

     .  The record pointer is positioned on an invalid record (i.e.,
        at EOF())

     .  The specified order is not custom built

     .  The specified order does not exist

     .  No order was specified and there is no controlling order

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example creates a custom index and adds every fiftieth
        record to it:

        USE Customer VIA "DBFCDX"
        // Create custom-built order that is initially empty
        INDEX ON LastName TO Last CUSTOM

        // Add every 50th record
        FOR n := 1 TO RECCOUNT() STEP 50
           GOTO n
           ORDKEYADD()
        NEXT

 Files   Library is CLIPPER.LIB.




See Also: ORDFOR() ORDKEYDEL() ORDSCOPE()


 

			

	
	



		
			


	

		
C5_ORDKEY


		

		Posted on  by vivaclipper		

	


		

		
 ORDKEY()
 Return the key expression of an order
------------------------------------------------------------------------------
 Syntax

     ORDKEY(<cOrderName> | <nOrder>
        [, <cOrderBagName>]) --> cExpKey

 Arguments

     <cOrderName> is the name of an order, a logical ordering of a
     database.

     <nOrder> is an integer that identifies the position in the order
     list of the target order whose cExpKey is sought.

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

 Returns

     Returns a character string, cExpKey.

 Description

     ORDKEY() is an order management function that returns a character
     expression, cExpKey, that represents the key expression of the specified
     order.

     You may specify the order by name or with a number that represents its
     position in the order list.  Using the order name is the preferred
     method.

     The active RDD determines the order capacity of an order bag.  The
     default DBFNTX and the DBFNDX drivers only support single-order bags,
     while other RDDs may support multiple-order bags (e.g., the DBFCDX and
     DBFMDX drivers).

     Note: ORDKEY(0) works as ORDKEY(INDEXORD()).

 Examples

     .  This example retrieves the index expression from an order:

        USE Customer NEW
        INDEX ON  Customer->Acct   ;
           TO  Customer      ;
           FOR Customer->Acct > "AZZZZZ"

        ORDKEY("Customer")      // Returns: Customer->Acct




See Also: ORDFOR() ORDKEY() ORDNAME() ORDNUMBER()


 

			

	
	



		
			


	

		
C5_ORDISUNIQUE


		

		Posted on  by vivaclipper		

	


		

		
 ORDISUNIQUE()
 Return the status of the unique flag for a given order
------------------------------------------------------------------------------
 Syntax

     ORDISUNIQUE([<cOrder> | <nPosition>],
        [<cIndexFile>]) --> lUnique

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid order will raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

 Returns

     ORDISUNIQUE() returns the status of the indicated order's unique flag as
     a logical value.

 Description

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example shows the return value of ORDISUNIQUE() using
        various orders:

        USE Customer VIA "DBFCDX"
        INDEX ON LastName TAG Last UNIQUE
        INDEX ON FirstName TAG First
        INDEX ON Age TO j:\test\tmp\age UNIQUE

        SET ORDER TO TAG Last

        ? ORDISUNIQUE()                // Result: .T. for Last
        ? ORDISUNIQUE("First")         // Result: .F.
        ? ORDISUNIQUE("Age")           // Result: .T.

 Files   Library is CLIPPER.LIB.




See Also: ORDDESCEND() ORDFOR() ORDKEY()


 

			

	
	



		
			


	

		
C5_ORDFOR


		

		Posted on  by vivaclipper		

	


		

		
 ORDFOR()
 Return the FOR expression of an order
------------------------------------------------------------------------------
 Syntax

     ORDFOR(<cOrderName> | <nOrder> [, <cOrderBagName>])
        --> cForExp

 Arguments

     <cOrderName> is the name of the target order whose cForExp is
     sought.

     <nOrder> is an integer that identifies the position in the order
     list of the target order whose cForExp is sought.

     <cOrderBagName> is the name of an order bag containing one or more
     orders.  You may specify <cOrderBagName> as the file name with or
     without the path name or appropriate extension.  If you do not include
     the extension as part of <cOrderBagName>, Clipper uses the default
     extension of the current RDD.

 Returns

     ORDFOR() returns a character expression, cForExp, that represents the
     FOR condition of the specified order.  If the order was not created
     using the FOR clause, the return value will be an empty string ("").  If
     the database driver does not support the FOR condition, it may either
     return an empty string ("") or raise an "unsupported function" error,
     depending on the driver.

 Description

     ORDFOR() is an order management function that returns the character
     string, cForExp, that represents the logical FOR condition of
     <cOrderName> or <nOrder>.

     Note:  ORDFOR(0) works as ORDFOR(INDEXORD()).

 Examples

     .  This example retrieves the FOR condition from an order:

        USE Customer NEW
        INDEX ON  Customer->Acct   ;
           TO  Customer      ;
           FOR Customer->Acct > "AZZZZZ"

        ORDFOR("Customer")      // Returns: Customer->Acct > "AZZZZZ"




See Also: INDEX ORDKEY() ORDCREATE() ORDNAME() ORDNUMBER()


 

			

	
	



		
			


	

		
C5_ORDDESTROY


		

		Posted on  by vivaclipper		

	


		

		
 ORDDESTROY()
 Remove a specified order from an order bag
------------------------------------------------------------------------------
 Syntax

     ORDDESTROY(<cOrderName> [, <cOrderBagName>]) --> NIL

 Arguments

     <cOrderName> is the name of the order to be removed from the current
     or specified work area.

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

 Returns

     ORDDESTROY() always returns NIL.

 Description

     ORDDESTROY() is an order management function that removes a specified
     order from multiple-order bags.

     The active RDD determines the order capacity of an order bag.  The
     default DBFNTX and the DBFNDX drivers only support single-order bags,
     while other RDDs may support multiple-order bags (e.g., the DBFCDX and
     DBPX drivers).

     Note:  RDD suppliers may define specific behaviors for this command.

     Warning!  ORDDESTROY() is not supported for DBFNDX and DBFNTX.

 Examples

     .  This example demonstrates ORDDESTROY() with the FoxPro driver,
        DBFCDX:

        USE Customer VIA "DBFCDX" NEW
        SET INDEX TO Customer, CustTemp
        ORDDESTROY("CuAcct", "Customer")




See Also: DELETE TAG ORDCREATE()





			

	
	



		
			


	

		
C5_ORDDESCEND


		

		Posted on  by vivaclipper		

	


		

		
 ORDDESCEND()
 Return and optionally change the descending flag of an order
------------------------------------------------------------------------------
 Syntax

     ORDDESCEND([<cOrder> | <nPosition>],[<cIndexFile>],
        [<lNewDescend>]) --> lCurrentDescend

 Arguments

     <cOrder> | <nPosition> is the name of the order or a number
     representing its position in the order list.  Using the order name is
     the preferred method since the position may be difficult to determine
     using multiple-order index files.  If omitted or NIL, the controlling
     order is assumed.

     Specifying an invalid value will raise a runtime error.

     <cIndexFile> is the name of an index file, including an optional
     drive and directory (no extension should be specified).  Use this
     argument with <cOrder> to remove ambiguity when there are two or more
     orders with the same name in different index files.

     If <cIndexFile> is not open by the current process, a runtime error is
     raised.

     <lNewDescend> is a logical value that if true (.T.) dynamically
     turns on the descending flag for the order, resulting in descending
     order.  False (.F.) dynamically turns the flag off, resulting in
     ascending order.

 Returns

     If <lNewDescend> is not specified, ORDDESCEND() returns the current
     setting.  If <lNewDescend> is specified, the previous setting is
     returned.

 Description

     ORDDESCEND() changes the ascending/descending flag at runtime only--it
     does not change the descending flag stored in the actual index file.  To
     change the descending flag in the index file, see the INDEX command in
     the Reference Guide, Volume 1.

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  The following example illustrates ORDDESCEND().  Every order
        can be both ascending and descending:

        USE Customer VIA "DBFCDX"
        INDEX ON LastName TAG Last
        INDEX ON FirstName TAG First DESCENDING

        SET ORDER TO TAG Last
        // Last was originally created in ascending order

        // Swap it to descending
        ORDDESCEND(,, .T.)
        // Last will now be processed in descending order

        SET ORDER TO TAG First
        // First was originally created in descending order

        // Swap it to ascending
        ORDDESCEND(,, .F.)
        // First will now be processed in ascending order

 Files   Library is CLIPPER.LIB.




See Also: INDEX