DRLIST C-3

drlist - set up user record fields

Drlist declares a list of fields that comprise the user record of an RMSfile. Drlist allows a program to define the fields to be accessed from each record in the RMSfile.

Fldptrs is a pointer to an array of structures that describes the fields to be accessed. Each structure element names a field in the RMSfile, the data type, length, and number of elements of the field in the user record, and the conversions that are permitted between the user record and the field in the RMSfile. The order of the fields in fldptrs must match the order of the fields in your user record structure exactly.

Fcb is the file block pointer returned by dlopen(C-3) or dopen(C-3).

The value returned is the size of the new user record in bytes. All fields are properly aligned for each field's data type.

After your program calls drlist, all further calls to RMS up to the next drlist or dblist(C-3) call use the field list of this call. On a find call, only the fields requested are returned. On an update call, only the fields specified are altered. Finally, when adding records to the RMSfile, only those fields specified are put into the RMSfile; all other fields in that record are zeroed.

The structure passed to drlist as fldptrs is defined in the include file <cbase/dirio.h> as shown below:

Dr_name names the field in the RMSfile to be accessed. Dr_type gives the type of the field in the user record. This should match the data type of the field in the RMSfile. Dr_size gives the total size of the field in the user record (add sizes for all elements of the field). Dr_nelem gives the number of elements of the field in the user record. Dr_size divided by Dr_nelem gives the element size for the user record. This does not have to match the element size of the field in the RMSfile depending on the conversion options used below. If the conversion is not specified as truncation (see below), the number of elements in the user record (dr_nelem) must match the number of elements in the RMSfile. Dr_conv specifies what types of conversions can be done between the user record and the RMSfile. Conversions are possible when moving data from the user record to the RMSfile buffer (finds, inserts, updates, etc.). A conversion may also be done when moving data from the RMSfile buffer into the user record (finds). The following table lists the possible values for dr_conv (as defined in <cbase/dirio.h>) along with the conversion performed:

Value Conversion

DRNOCONV No conversion allowed. Data types, sizes, and number of elements must match exactly.

DRCONVPRE Element sizes may differ on STRING_TYPE or CHAR_TYPE fields, but values must bepreserved.

DRCONVTRUNC Element sizes may differ on STRING_TYPE or CHAR_TYPE fields, values may be truncated to fit. Number of elements may differ between user record and RMSfile. Data may be lost.

When you specify a conversion of DRCONVPRE in a field list, RMS calls involving a user record (buffer) may fail due to lengths of string fields. This can occur only when the sizes of the user record field and the RMSfile field are different.

dblist(C-3), dlopen(C-3), dopen(C-3)

Chapter 4,

Drlist returns a value of BAD (-1) if the dictionary for the RMSfile cannot be found or if one of the fields in the list is not in the dictionary. BAD is also returned if there is a mismatch between data types, element sizes, or number of elements without the correct conversion options.

Drlist is an improved version of dblist(C-3) that handles differences between the data type and size of fields in your user record structure and the fields in the RMSfile.