xHarbour Reference Documentation > Function Reference

DbInfo()

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

Syntax

DbInfo( <nDefine>, [<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 in a work area and begin with the prefix DBI_ (see below).

<xNewSetting>

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

Return

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

Description

DbInfo() is a universal function managing numerous work area settings available in xHarbour. Many of these settings can be changed via commands or functions, which is the recommended way. If a work area is not used, DbInfo() generates a runtime error. Also, if an RDD does not support a setting, it may create a runtime error or simply ignore the function call upon its own discretion. In the latter case, the return value of DbInfo() is NIL.

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

DBI_ALIAS

--> cAliasName (READONLY)

See also: function Alias(). The return value is a character string holding the symbolic alias name of the work area.

DBI_BLOB_DIRECT_EXPORT

{ <nBlobID>, <cTargetFile>, [<nMode>] } --> lSuccess

See also: function BlobDirectExport(). DbInfo() expects as second parameter an array with three elements. They are identical with the arguments of function BlobDirectExport(). The return value is of logical data type and indicates a successful operation.

DBI_BLOB_DIRECT_GET

{ <nBlobID>, [<nStart>], [<nCount>] } --> xBlobData

See also: function BlobDirectGet(). DbInfo() expects as second parameter an array with three elements. They are identical with the arguments of function BlobDirectGet(). The return value is the data of the retrieved binary large object (BLOB).

DBI_BLOB_DIRECT_IMPORT

{ <nOldBlobID>, <cSourceFile> } --> nNewBlobID

See also: function BlobDirectImport(). DbInfo() expects as second parameter an array with two elements. They are identical with the arguments of function BlobDirectImport(). The return value is the numeric BLOB identifier of the new BLOB.

DBI_BLOB_DIRECT_LEN

<nBlobID> --> nBytes

The second parameter must be the numeric identifier of a binary large object (BLOB) which can be queried using DbFieldInfo( DBS_BLOB_POINTER, <nFieldPos> ). The return value is the number of bytes occupied by the BLOB in the BLOB file.

DBI_BLOB_DIRECT_PUT

{ <nOldblobID>, <xBlobData> } --> nNewBlobID

See also: function BlobDirectPut(). DbInfo() expects as second parameter an array with two elements. They are identical with the arguments of function BlobDirectPut(). The return value is the numeric BLOB identifier of the new BLOB.

DBI_BLOB_DIRECT_TYPE

<nBlobID> --> cDataType

The second parameter must be the numeric identifier of a binary large object (BLOB) which can be queried using DbFieldInfo( DBS_BLOB_POINTER, <nFieldPos> ). The return value is a single letter indicating the data type stored in the BLOB. This letter has the same meaning as the return value of function Valtype().

DBI_BLOB_INTEGRITY

--> lSuccess

This setting causes DbInfo() to test the integrity of internal tables referring to the data stored in a BLOB file. If the test fails, the return value is .F. (false) and the internal tables can be rebuild using Dbinfo( DBI_BLOB_RECOVER ).

DBI_BLOB_OFFSET

<nBlobID> --> nFileOffset

The second parameter must be the numeric identifier of a binary large object (BLOB) returned from function BlobDirectPut(). It can also be queried using DbFieldInfo( DBS_BLOB_POINTER, <nFieldPos> ). The return value is the numeric file offset where the BLOB is stored in the BLOB file.

DBI_BLOB_RECOVER

--> lSuccess

Rebuilds the internal tables referring to the data stored in a BLOB file. This should only be called when DbInfo(DBI_BLOB_INTEGRITY) returns .F. (false). DbInfo() can only recover the internal tables referring to the data, it cannot recover the data when a BLOB file becomes corrupted.

DBI_BLOB_ROOT_GET

--> xBlobData

See also: function BlobRootGet(). The return value is the data stored in the root area of a BLOB file.

DBI_BLOB_ROOT_LOCK

--> lSuccess

See also: function BlobRootLock(). The return value is .T. (true) when a write lock is obtained for the root area of a BLOB file in concurrent file access. The root area must be locked before DbInfo(DBI_BLOB_ROOT_PUT) is executed. The lock is later released using DbInfo(DBI_BLOB_ROOT_UNLOCK).

DBI_BLOB_ROOT_PUT

<xBlobData> --> lSuccess

See also: function BlobRootPut(). DbInfo() expects as second parameter the data to be stored in the root area of a BLOB file. The return value is .T. (true) when data is successfully written.

DBI_BLOB_ROOT_UNLOCK

--> NIL

See also: function BlobRootUnlock(). Releases a lock placed on the root area of a BLOB file with DbInfo(BLOB_ROOT_LOCK). The return value is NIL.

DBI_BOF

--> lIsBeginOfFile (READONLY)

See also: function Bof(). The return value is the logical begin-of-file status of a work area.

DBI_CANPUTREC

--> lCanWriteData

See also: function RddList(). The return value is .T. (true) when the RDD maintaining the file open in a work area supports writing data to the file. This is the case for all RDDs listed by RddList(RDT_FULL).

DBI_CHILDCOUNT

--> nChildCount

See also: command SET RELATION. The return value is numeric, indicating the number of child work areas related to the current work area.

DBI_DBFILTER

--> cFilter

See also: function DbFilter(). Returns the filter expression of the work area as a character string.

DBI_DB_VERSION

[<nOne>] --> cRddVersionInfo

Returns version information of the RDD maintaining files in a work area. When 1 is passed for the optional second parameter, the returned character string contains extended version information.

DBI_EOF

--> lIsEndOfFile (READONLY)

See also: function Eof(). The return value is the logical end-of-file status of a work area.

DBI_FCOUNT

--> nFieldCount (READONLY)

See also: function FCount(). The return value is the numeric field count in a work area.

DBI_FILEHANDLE

--> nFileHandle (READONLY)

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

DBI_FOUND

--> lIsFound (READONLY)

See also: function Found(). The return value is the logical found status of the last search operation in a work area.

DBI_FULLPATH

--> cFullFileName

The return value is a character string holding the fully qualified file name of the database open in a work area if the file resides in the directory specified with SET DEFAULT. When the file is located in another directory, a character string holding the file name without directory information is returned.

DBI_GETHEADERSIZE

--> nBytes (READONLY)

See also: function Header(). The return value is the number of bytes occupied by the file header of the database open in a work area.

DBI_GETLOCKARRAY

--> aLockedRecords (READONLY)

See also: function DbRLockList(). The return value is an array holding the record numbers of currently locked records.

DBI_GETRECSIZE

--> nRecordSize (READONLY)

See also: function RecSize(). The return value is the number of bytes required to store a single record in the database open in a work area.

DBI_ISDBF

--> lIsDbf (READONLY)

See also: function RddList(). The return value is .T. (true) when the the file open in a work area is a full functional database. This is the case for all RDDs listed by RddList(RDT_FULL).

DBI_ISFLOCK

--> lIsFileLock (READONLY)

See also: function FLock(). The return value is .T. (true) when a file lock is placed on a database open in SHARED mode in the current work area.

DBI_ISREADONLY

--> lIsReadOnly (READONLY)

See also: command USE. The return value is .T. (true) when a database file is open in READONLY mode in the current work area.

DBI_LASTUPDATE

--> dLastUpdate (READONLY)

See also: function LUpdate(). The return value is the date of the last update of the database open in the current work area.

DBI_LOCKCOUNT

--> nLockedRecords (READONLY)

See also: function DbRlockList(). The return value is the number of currently locked records.

DBI_LOCKOFFSET

--> nLockOffset (READONLY)

See also: command SET DBFLOCKSCHEME. The return value is a numeric value indicating the virtual lock offset used to place write locks on records in concurrent database access. The virtual lock offset must be identical for all applications accessing the same database files. The lock offset can be changed using DbInfo(DBI_LOCKSCHEME).

DBI_LOCKSCHEME

[<nNewLockScheme>] --> nOldLockScheme

See also: command SET DBFLOCKSCHEME. The second parameter is optional and can be a numeric value between 0 and 5. It selects the locking scheme to use for aquiring write locks on records in concurrent file access. #define constants are available in DbInfo.ch for <nNewLockScheme>. They begin with the prefix DBFLOCK_.

DBI_MEMOBLOCKSIZE

[<nNewBlockSize>] --> nOldBlockSize

See also: command SET MEMOBLOCK. The second parameter is optional and defines the block size for memo fields used by the RDD that opens database files in a work area. The return value is the current memo block size as a numeric value. Note that changing the memo block size is not supported by all RDDs.

DBI_MEMOEXT

[<cNewExtension>] --> <cOldExtension>

See also: command SET MFILEEXT. The second parameter is optional and file extension for memo files used by the RDD that opens database files in a work area. The return value is the current memo file extension as a character string.

DBI_MEMOHANDLE

--> <nMemoFileHandle> (READONLY)

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

DBI_MEMOTYPE

--> nMemoType (READONLY)

See also: function RddInfo(). The return value is numeric and indicates the type of a memo file associated with a database open in a work area. #define constants are available in DbInfo.ch that identify a memo file type. They begin with the prefix DB_MEMO_.

DBI_MEMOVERSION

--> nMemoVersion (READONLY)

See also: function RddInfo(). The return value is numeric and indicates the version of a memo file associated with a database open in a work area. #define constants are available in DbInfo.ch that identify a memo file version. They begin with the prefix DB_MEMOVER_.

DBI_PASSWORD

[<cPassword>] --> NIL

This setting defines a password of up to eight characters in length which is used for data encryption in the database file. Note that only data in a DBF file is encrypted. Data stored in index and/or memo files are not encrypted with the password.

DBI_RDD_VERSION

[<nvalue>] --> cVersion

Returns version information of the RDD maintaining files in a work area. When 1 is passed for the optional second parameter, the returned character string contains extended version information.

DBI_ROLLBACK

--> NIL

See also: command REPLACE. Voids the last changes applied to a record with REPLACE or FieldPut(), which is like an Undo operation. Changes are discarded and the original values are assigned back to a record. This is possible until DbCommit() is executed, a write lock is released using DbUnlock(), or the record pointer is moved.

DBI_SCOPEDRELATION

<nRelation> --> lIsScoped (READONLY)

See also: function DbSetRelation(). DbInfo() expects as second parameter a numeric value indicating the ordinal position in the list of relations to query the SCOPED attribute for. Relations are numbered in the sequence they are defined, beginning with 1. The return value is .T. (true) when the relation to the child work area is scoped, when the .T. was passed for the fourth parameter of DbSetRelation().

DBI_SHARED

--> lIsShared (READONLY)

See also: command USE. The return value is .T. (true) when a database is open in SHARED mode with the USE command.

DBI_TABLEEXT

--> cFileExtension (READONLY)

See also: function DbTableExt(). The return value is the file extension of the database file open in a work area as a character string.

DBI_TABLETYPE

--> nTableType (READONLY)

See also: function RddInfo(). The return value is numeric, indicating the type of the database file open in a work area. #define constants are avaialble in DbInfo.ch to identify the database type. They begin with the prefix DB_DBF_.

DBI_VALIDBUFFER

--> lBufferIsValid (READONLY)

The return value is .T. (true) when the internal memory buffer holding data of a record on disk is valid. A valid buffer is unchanged, i.e. it contains the same data as stored in the database file.

Info

See also:	Alias(), DbFieldInfo(), DbOrderInfo(), DbRecordInfo(), DbUseArea(), RddInfo(), Select()
Category:	Database functions , Info functions
Header:	Dbinfo.ch
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates some DbInfo() settings and how
// to undo changes applied to a record.

   #include "DbInfo.ch"

   PROCEDURE Main
      USE Customer ALIAS Cust SHARED

      ? DbInfo( DBI_SHARED )                  // result: .T.
      ? DbInfo( DBI_ISREADONLY )              // result: .F.

      ? FIELD->LastName                       // result: Miller
      ? DbInfo( DBI_VALIDBUFFER )             // result: .T.

      RLock()
      ? ValToPrg( DbInfo(DBI_GETLOCKARRAY) )  // result: { 1 }

      REPLACE FIELD->LastName WITH "JONES"

      ? FIELD->LastName                       // result: JONES
      ? DbInfo( DBI_ROLLBACK )                // result: NIL
      ? FIELD->LastName                       // result: Miller

      DbUnlock()

      USE
   RETURN