DBORDERINFO()
Return and optionally change information about orders and index files
------------------------------------------------------------------------------
Syntax
DBORDERINFO(<nInfoType>, [<cIndexFile>],
[<cOrder> | <nPosition>],
[<expNewSetting>]) --> uCurrentSetting
Arguments
<nInfoType> determines the type of information as specified by the
constants below. Note, however, that not all constants are supported
for all RDDs. These constants are defined in the Dbinfo.ch header file,
which must be included (#include) in your application.
Order/Index Information Type Constants
------------------------------------------------------------------------
Constant Description
------------------------------------------------------------------------
DBOI_CONDITION For condition of the specified order as a
string.
DBOI_CUSTOM Logical flag indicating whether the
specified order is custom-built (for RDDs
that support custom-built orders). Note
that although you can turn the custom-
built flag on for a standard order by
specifying true (.T.) for the <uNewSetting>
argument, you cannot turn a custom-built
order into a standard order. Specifying
false (.F.) for <uNewSetting> is the same
as not specifying the argument at all--
both return the current setting.
DBOI_EXPRESSION Order key expression of the specified
order as a string.
DBOI_FILEHANDLE Handle of the specified index file as a
number.
DBOI_HPLOCKING Logical flag indicating whether the
specified index file uses the high
performance index locking schema.
DBOI_INDEXEXT (DBOI_BAGEXT) Default index file extension as a string.
DBOI_INDEXNAME (DBOI_BAGNAME) Name of the specified index file as a
string.
DBOI_ISCOND Logical flag that determines whether the
specified order was defined using a FOR
condition.
DBOI_ISDESC Logical flag that determines if the
specified order is descending. For
drivers that support dynamically setting
the descending flag at runtime, specify
the new value as a logical, using
DBORDERINFO(DBOI_ISDESC, [<cIndexFile>],
[<cOrder> | <nPosition>], <lNewSetting>).
The current setting is returned before it
is changed.
DBOI_KEYADD Logical flag indicating whether a key has
been successfully added to the specified
custom-built order.
DBOI_KEYCOUNT Number of keys in the specified order.
DBOI_KEYDEC Number of decimals in the key of the
specified order.
DBOI_KEYDELETE Logical flag indicating whether a key has
been successfully deleted from the
specified custom-built order.
DBOI_KEYGOTO Logical flag indicating whether the record
pointer has been successfully moved to a
record specified by its logical record
number in the controlling order.
DBOI_KEYSINCLUDED Number of keys included in the specified
order so far. This is primarily useful
for conditional orders. It can be used
during the status display process (with
the EVAL clause of the INDEX command).
DBOI_KEYSIZE Size of the key in the specified order as
a number.
DBOI_KEYTYPE Data type of the key in the specified
order as a string.
DBOI_KEYVAL Key value of the current record from the
controlling order.
DBOI_LOCKOFFSET Locking offset for the specified index
file as a numeric value.
DBOI_NAME Name of the specified order as a string.
DBOI_NUMBER Numeric position of the specified order in
the order list.
DBOI_ORDERCOUNT Number of orders in the specified index
file.
DBOI_POSITION Logical record number of the current
record within the specified order.
DBOI_RECNO Physical record number of the current
record within the specified order.
DBOI_SCOPEBOTTOM Bottom boundary of the scope (as a number)
for the specified order.
DBOI_SCOPEBOTTOMCLEAR Clears the bottom boundary of the scope
for the specified order.
DBOI_SCOPETOP Top boundary of the scope (as a number)
for the specified order.
DBOI_SCOPETOPCLEAR Clears the top boundary of the scope for
the specified order.
DBOI_SETCODEBLOCK Key for the specified order as a code
block.
DBOI_SKIPUNIQUE Logical flag indicating whether the record
pointer has been successfully moved to the
next or previous unique key in the
controlling order.
DBOI_UNIQUE Logical flag indicating whether the
specified order has the unique attribute
set.
------------------------------------------------------------------------
Important! DBOI_USER is a constant that returns the minimum value
that third-party RDD developers can use for defining new <nInfoType>
parameters. Values less than DBOI_USER are reserved for Computer
Associates development.
<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.
<cOrder> | <nPosition> is the name of the order about which you
want to obtain information or a number representing its position in the
order list. For single-order index files, the order name is the
eight-letter index file name. Using the order name is the preferred
method since the position may be difficult to determine using
multiple-order index files. Invalid values are ignored. If no index
file or order is specified, the controlling order is assumed.
<expNewSetting> is reserved for RDDs that allow the file information
to be changed, in addition to being retrieved. None of the RDDs
supplied with Clipper support this argument. It can be omitted or
specified as NIL.
Returns
If <expNewSetting> is not specified, DBORDERINFO() returns the current
setting. If <expNewSetting> is specified, the previous setting is
returned.
Description
DBORDERINFO() retrieves information about the orders and index files.
By default, DBORDERINFO() operates on the currently selected work area.
It can be made to operate on an unselected work area by specifying it
within an aliased expression.
Examples
. This example uses DBOI_NAME to save the current controlling
order. After changing to a new controlling order, it uses the saved
value to restore the original order:
#include Dbinfo.ch
USE Customer INDEX Name, Serial NEW
cOrder := DBORDERINFO(DBOI_NAME) // Name
Customer->DBSETORDER("Serial")
? DBORDERINFO(DBOI_NAME) // Serial
Customer->DBSETORDER(cOrder)
? DBORDERINFO(DBOI_NAME) // Name
. This example uses aliased expressions to return the default
index file extension (using DBOI_INDEXEXT) in two different work
areas:
#include Dbinfo.ch
USE Sales INDEX All_Sales VIA "DBFCDX" NEW
USE Customer INDEX Name, Serial VIA "DBFNTX" NEW
? Sales->DBORDERINFO(DBOI_INDEXEXT) // .CDX
? Customer->DBORDERINFO(DBOI_INDEXEXT) // .NTX
. In this example, DBORDERINFO(DBOI_INDEXEXT) checks for the
existence of the Customer index file independent of the RDD linked
into the current work area:
#include Dbinfo.ch
USE Customer NEW
IF !FILE( "Customer" + DBORDERINFO(DBOI_INDEXEXT))
Customer->DBCREATEINDEX("Customer", "CustName",;
{||Customer->CustName} )
ENDIF
. This example accesses the key expression of several orders
from the same index file:
#include Dbinfo.ch
USE Customer INDEX All_Cust VIA "DBFMDX" NEW
Customer->DBSETORDER("Serial")
? DBORDERINFO(DBOI_EXPRESSION,, "Name")
// Result: key expression for name order
? DBORDERINFO(DBOI_EXPRESSION,, "Serial")
// Result: key expression for serial order
. This example uses DBORDERINFO() as part of a TOTAL ON key
expression. Since DBORDERINFO() returns the expression as a string,
it is specified using a macro expression to force evaluation of the
key expression:
#include Dbinfo.ch
USE Sales INDEX Salesman NEW
TOTAL ON &(DBORDERINFO(DBOI_EXPRESSION)) ;
FIELDS SaleAmount TO Summary
. In this example, All_Cust.mdx contains three orders named
CuAcct, CuName, CuZip. The DBOI_INDEXNAME constant is used to
display the name of the index file using one of its orders:
#include Dbinfo.ch
USE Customer VIA "DBFNTX" NEW
Customer->DBSETINDEX("All_Cust")
? DBORDERINFO(DBOI_INDEXNAME,, "CuName")
// Returns: All_Cust
. The following example searches for CuName in the order list:
#include Dbinfo.ch
USE Customer VIA "DBFNTX" NEW
Customer->DBSETINDEX("CuAcct")
Customer->DBSETINDEX("CuName")
Customer->DBSETINDEX("CuZip")
? DBORDERINFO(DBOI_NUMBER,, "CuName") // 2
. This example retrieves the FOR condition from an order:
#include Dbinfo.ch
USE Customer NEW
INDEX ON Customer->Acct TO Customer ;
FOR Customer->Acct > "AZZZZZ"
? DBORDERINFO(DBOI_CONDITION,, "Customer")
// Returns: Customer->Acct > "AZZZZZ"
Files Library is CLIPPER.LIB, header file is Dbinfo.ch.
See Also: DBFIELDINFO() DBINFO() DBRECORDINFO()
