xHarbour Reference Documentation > Function Reference

DbOrderInfo()

Queries and/or changes information about indexes open in a work area.

Syntax

DbOrderInfo( <nDefine>             , ;
            [<cIndexFile>]         , ;
            [<nOrder>|<cIndexName>], ;
            [<xNewSetting>]          ) --> xCurrentSetting

Arguments

<nDefine>

This is a numeric parameter for which #define constants exist in the file DbInfo.ch. They identify the numerous settings that can be queried or changed for indexes and begin with the prefix DBOI_ (see below).

<cIndexFile>

<cIndexFile> is a character string with the name of the file that stores the index. It is only required when multiple index files are open that contain indexes having the same <cIndexName>.

<nOrder>

A numeric value specifying the ordinal position of the index open in a work area to query information for. Indexes are numbered in the sequence of opening, beginning with 1. The value zero identifies the controlling index.

<cIndexName>

Alternatively, a character string holding the symbolic name of the index to query can be passed. It is the string passed to the TAG option of the INDEX command and analogous to the alias name of a work area. Support for <cIndexName> depends on the RDD used to open the index. Usually, RDDs that are able to maintain multiple indexes in one index file support symbolic index names, such as DBFCDX, for example.

<xNewSetting>

<xNewSetting> is an optional argument specifying a new value for the index setting identified by <nDefine>. The data type for <xNewSetting> depends on the index setting to change (see below). If the index setting is READONLY, the parameter is ignored.

Return

The function returns the value of the specified index setting which is set before the function is called.

Description

DbOrderInfo() is a universal function managing numerous index settings available in xHarbour. Note, however, that not all settings are supported by all RDDs. If a setting is not supported by an RDD, a call to DbOrderInfo() may be ignored or may rise a runtime error.

When DbOrderInfo() is called in an unused work area, a runtime error is raised.

The constants that can be used for <nDefine> are listed below:

DBOI_BAGCOUNT

--> nOpenIndexFiles (READONLY)

See also: command SET INDEX. This setting is supported by the DBFNTX RDD and returns the number of NTX index files open in a work area. Note that if an NTX index file is created with multiple TAG names, it may contain multiple indexes.

DBOI_BAGEXT

--> cFileExtension (READONLY)

See also: function OrdBagExt(). The return value is the index file extension used by the RDD that opened a database in a work area as a character string.

DBOI_BAGNAME

--> cIndexFilename (READONLY)

See also: function OrdBagName(). The return value is the name of the index file that contains the specified index as a character string.

DBOI_BAGNUMBER

--> nIndexFilePosition (READONLY)

See also: command SET INDEX. This setting is supported by the DBFNTX RDD and returns the ordinal position of a single NTX index file in the list of open index files. Index files are numbered in the sequence they are opened beginning with one. DBOI_BAGNUMBER may yield a different result from DBOI_NUMBER when an NTX index file is created with multiple TAG names. In this case, the number of open NTX files may be different from the number of indexes available in a work area.

DBOI_BAGORDER

--> nFirstIndex (READONLY)

The return value is the ordinal position of the firs index within a multi-key index file.

DBOI_CONDITION

--> cForCondition (READONLY)

See also: function OrdFor(). The return value is a character string holding the FOR condition of the specified index. If the index is created without FOR condition, an empty string ("") is returned.

DBOI_CUSTOM

[<lMakeCustomIndex>] --> lIsCustomIndex

See also: command INDEX. This setting is equivalent with the CUSTOM option of the INDEX command. When it is set to .T. (true) before an index is created, a custom index will be created with function OrdCreate(). If DBOI_CUSTOM is queried for an existing index file, its custom flag is returned as a logical value. This flag cannot be changed after index creation so that <lMakeCustomIndex> is ignored for existing indexes.

DBOI_EVALSTEP

--> nEvalStep (READONLY)

See also: command INDEX. The return value is numeric and represents the value for the EVERY option when an index is created. The setting is supported by the DBFNTX and DBFCDX RDDs.

DBOI_EXPRESSION

--> cIndexKey (READONLY)

See also: function OrdKey(). The return value is the key expression of the specified index as a character string.

DBOI_FILEHANDLE

--> nFileHandle (READONLY)

See also: function FOpen(). The return value is the numeric low-level file handle of the index file open in a work area.

DBOI_FINDREC

<nRecno> --> lFound

See also: function OrdFindRec(). This setting is equivalent with function call OrdFindRec( nRecno, .F. ).

DBOI_FINDRECCONT

<nRecno> --> lFound

See also: function OrdFindRec(). This setting is equivalent with function call OrdFindRec( nRecno, .T. ).

DBOI_FULLPATH

--> cFullFileName (READONLY)

The return value is a character string holding the name of an index file, including file extension, that contains the specified index.

DBOI_INDEXEXT

--> cIndexFileExtension (READONLY)

DBOI_INDEXEXT is a synonym for DBOI_ORDBAGEXT and returns the file extension for an index file.

DBOI_INDEXNAME

--> cIndexFileName (READONLY)

DBOI_INDEXNAME is a synonym for DBOI_ORDBAGNAME and returns the file name for an index file.

DBOI_ISCOND

--> lIsForCondition (READONLY)

See also: command INDEX. The return value is .T. (true) when the specified index is created with a FOR condition. Otherwise .F. (false) is returned.

DBOI_ISDESC

[<lNewDescending>] --> lOldDescending

See also: command INDEX. The return value is .T. (true) when the specified index is created with the DESCENDING option. If an RDD supports to change ascending and descending indexes dynamically "on the fly", this setting works exactly the same as function OrdDescend().

DBOI_ISMULTITAG

--> lIsMultiTag (READONLY)

This setting is supported by the DBFNTX RDD. The return value is .T. (true) when an NTX file can contain multiple indexes, otherwise .F. (false) is returned. Multiple indexes can be created when indexes with different TAG names are created for the same index file.

DBOI_ISREADONLY

--> lIsReadOnly (READONLY)

See also: command USE. This setting is supported by the DBFNTX RDD. The return value is .T. (true) when the database file, that is associated with the index, is open in READONLY mode in the current work area. The READONLY status is valid for both, datbase ans index files.

DBOI_ISREINDEX

--> lIsReindexing (READONLY)

See also: function OrdListRebuild(). The return value is .T. (true) while reindexing is in progress, otherwise .F. (false) is returned.

DBOI_KEYADD

[<xNewKeyValue>] --> lKeyIsAdded

See also: function OrdKeyAdd(). This setting can only be used with custom built indexes, i.e. when an index is created with the CUSTOM option of the INDEX command. If the index is not a custom index, a runtime error is raised. The return value is .T. (true), when the new key value <xNewKeyValue> is successfully added to a custom index. Otherwise, .F. (false) is returned. If <xNewKeyValue> is omitted, it is created from the index key for the current record.

DBOI_KEYCOUNT

--> nKeyCount (READONLY)

See also: function OrdKeyCount(). This setting returns the number of index keys included in the specified index as a numeric value.

DBOI_KEYDEC

--> nDecimals (READONLY)

This setting can only be queried for DBFNTX. It returns the number of decimal places in a numeric index.

DBOI_KEYDELETE

[<xDelKeyValue>] --> lKeyIsDeleted

See also: function OrdKeyDel(). This setting can only be used with custom built indexes, i.e. when an index is created with the CUSTOM option of the INDEX command. If the index is not a custom index, a runtime error is raised. The return value is .T. (true), when the specified key value <xDelKeyValue> is successfully removed from a custom index. Otherwise, .F. (false) is returned. If <xDelKeyValue> is omitted, the index key of the current record is removed from the index.

DBOI_KEYGOTO

<nLogicalRecord> --> lSuccess

See also: function OrdKeyGoTo(). This setting moves the record pointer to the logical record position specified with <nLogicalRecord>. The return value is .T. (true) when the record pointer is successfully positioned, otherwise .F. (false). Note that if a filter condition is active in a work area, all records matching the filter are excluded.

DBOI_KEYGOTORAW

<nLogicalRecord> --> lSuccess

See also: function OrdKeyGoto(). This setting differs from DBOI_KEYGOTO only by ignoring any filter condition that may be set in a work area. DBOI_KEYGOTORAW includes records that match a filter condition.

DBOI_KEYNO

--> nOrdKeyNo (READONLY)

See also: function OrdKeyNo(). This setting returns a numeric value representing the logical record number of the current record. If a filter is active in the work area, all records matching the filter condition are excluded.

DBOI_KEYNORAW

--> nOrdKeyNo (READONLY)

See also: function OrdKeyNo(). This setting differs from DBOI_KEYNO only by ignoring any filter condition that may be set in a work area. DBOI_KEYNORAW includes records that match a filter condition.

DBOI_KEYSINCLUDED

--> nAddedKeys (READONLY)

See also: command INDEX. This setting is only relevant during index creation. It returns the number of index keys already added to an index. The setting is used to display indexing progress by calling a user defined routine via the EVAL option of the index command.

DBOI_KEYSIZE

--> nKeySize (READONLY)

See also: function OrdKey(). This setting returns the number of bytes an index value of a single record occupies in the index file.

DBOI_KEYTYPE

--> cKeyType (READONLY)

See also: function OrdKey(). This setting returns a single letter representing the data type of an index expression. The returned letter is equivalent with the return value of Valtype().

DBOI_KEYVAL

--> xIndexVal (READONLY)

See also: function OrdKeyVal(). The setting returns the index value of the current record.

DBOI_LOCKOFFSET

--> nLockOffset (READONLY)

See also: command SET DBFLOCKSCHEME. This setting returns the locking offset used by the selected locking scheme as a numeric value.

DBOI_NAME

--> cIndexName (READONLY)

See also: function OrdName(). This setting returns the symbolic name of an index as a character string. The name is specified with the TAG option of the INDEX command when the index is created.

DBOI_NUMBER

--> nOrder (READONLY)

See also: function OrdNumber(). This setting returns the ordinal position of an index in the list of open indexes based on its symbolic name. The name is specified with the TAG option of the INDEX command when the index is created.

DBOI_ORDERCOUNT

--> nIndexCount (READONLY)

See also: function OrdCount(). This setting returns the number of indexes open in a work area as a numeric value.

DBOI_POSITION

[<nNewIndexKeyNo>] --> nIndexKeyNo

See also: function OrdKeyGoto() and OrdKeyNo(). This setting queries and/or changes the logical position of the record pointer. If <nNewIndexKeyNo> is specified, it must be a numeric value in the range between 1 and OrdKeyCount().

DBOI_RELKEYPOS

[<nNewRelativePos>] --> nRelativePos

See also: function OrdKeyRelPos(). This setting queries and/or changes the relative position of the record pointer. If <nNewRelativePos> is specified, it must be a numeric value in the range between 0 and 1.

DBOI_SCOPEBOTTOM

[<xNewBottomScope>] --> xBottomScope

See also: function OrdScope(). This setting queries and/or changes the bottom scope value for navigating the record pointer. If <xNewBottomScope> is specified, it must be of the same data type as the value of the index expression.

DBOI_SCOPEBOTTOMCLEAR

--> xBottomScope

See also: function OrdScope(). This setting releases the bottom scope value for navigating the record pointer. The return value is the previously set bottom scope value.

DBOI_SCOPECLEAR

--> NIL

See also: command SET SCOPE. This setting releases both, the top and bottom scope value for navigating the record pointer. It is equivalent with SET SCOPE TO and no arguments apecified. The return value is always NIL.

DBOI_SCOPESET

[<xBothScopes>] --> NIL

See also: function OrdScope(). This setting allows for defining the same value for both, the top and bottom scope, with one function call. If <xBothScopes> is specified, its data type must be the same as the value of the index expression. The return value is always NIL.

DBOI_SCOPETOP

[<xNewTopScope>] --> xTopScope

See also: function OrdScope(). This setting queries and/or changes the top scope value for navigating the record pointer. If <xNewTopScope> is specified, it must be of the same data type as the value of the index expression.

DBOI_SCOPETOPCLEAR

--> xTopScope

See also: function OrdScope(). This setting releases the top scope value for navigating the record pointer. The return value is the previously set top scope value.

DBOI_SKIPUNIQUE

[<nDirection>] --> lSuccess

This setting is equivalent with function OrdSkipUnique().

DBOI_SKIPWILD

<cWildCardString> --> lFound

See also: function OrdWildSeek(). This setting is equivalent with function call OrdWildSeek( cWildCardString, .F., .F. ).

DBOI_SKIPWILDBACK

<cWildCardString> --> lFound

See also: function OrdWildSeek(). This setting is equivalent with function call OrdWildSeek( cWildCardString, .F., .T. ).

DBOI_UNIQUE

--> lIsUnique (READONLY)

See also: function OrdIsUnique(). The return value is .T. (true) when the specified index is created with the UNIQUE option of the INDEX command, otherwise .F. (false) is returned.

Info

See also:	DbInfo(), DbRecordInfo(), OrdBagExt(), OrdKey(), OrdName(), RddInfo()
Category:	Database functions , Info functions
Header:	Dbinfo.ch
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll