DBF READ()

PURPOSE

Read a record

SYNONYM

api_dbf_read()

SYNOPSIS

#include "dbapi.h"
 
int	DBF_READ(recnum, readlock, position_indexes)
 
<input parameters>
long	recnum;			/* Record number		*/
int	readlock;			/* Lock record to read	*/
int	position_indexes;	/* Reposition indexes	*/
 
<output parameters>
none

DESCRIPTION

The DBF_READ() function will read the current record from the database into the record buffer of the selected workarea.

A value of -1 will be returned if no database is open in the current workarea or the record pointer is positioned either past the end or the beginning of the file. If the required record is locked by another user and 'readlock' is not zero, the DBF_READ() function will wait until the record is available.

The record number to be read must be specified in the first parameter.

A readlock can be specified with a value of 1 and if the database is opened for shared access, the current record is unlocked and the specified record is read and then locked for update.

You can specify if the indexes opened on the database should be read and repositioned by specifying a value of 1 for position_indexes. Recital will also check the consistency of the indexes and return an error if one is detected. If the database is opened for shared access and a readlock was specified then the indexes are also locked.

If the database is related, the related records are read with the same parameters passed to the DBF_READ() function. If the related database is related to another database then this related record will also be read, and so on until all the relationships are satisfied.

If the database is cached into memory then the DBF_READ() function will check the cache first.

Any calculated fields defined in the Applications Data Dictionary are recalculated first before the record is placed into the buffer.

EXAMPLE

The following example reads the current record into the record buffer and locks the record and repositions the index.

#include "dbapi.h"
 
dbapi_dbf_read()
{
    int	rc;
 
    rc = DBF_READ(DBF_RECNO(), 1, 1);
 
    _retni( rc );
}

SEE ALSO

BLOB_READ(), DBF_APPEND(), DBF_GATHER(), DBF_RECBUFFER(), DBF_RECNO(), DBF_RECSIZE(), DBF_SCATTER(), DBF_UPDATE(), FIELD_COUNT(), FIELD_LOOKUP(), FIELD_VALUE(), MEMO_READ()