The C/Base functions dblist(C-3) and drlist(C-3) declare a list
of fields that are read or written to an RMSfile. Dblist and drlist
build a mapping between the physical record structure (in the RMSfile) and the
user record structure in your program. Subsequent RMS calls use this mapping
to transfer the physical record to or from the user record.
You pass the dblist function a pointer to a list of strings containing the names of fields from an RMSfile the calling program wants to access. All subsequent finds, inserts and updates to the RMSfile only access the fields specified in the field list. The members of your user record structure must correspond exactly with the list of field names passed to dblist. In addition, the data type, size, and number of elements of each member in your record structure must match exactly the corresponding field in the RMSfile. Dblist has no way to verify that these rules are met. If you violate them, your program will exhibit unpredictable behavior.
For example, if an RMSfile contains a name field of 20 characters, your user record structure would also have 20 characters for the field in the structure. If the name field is expanded to 35 characters in the RMSfile, all source files that access the user record structure must change the size of the field to 35 characters and be recompiled.
The drlist function is an enhanced version of dblist. You pass a pointer to a list of structures to drlist. Each structure describes a field in your user record structure, and specifies the field name, type, size, number of elements, and conversion options. With this additional information, drlist can adjust for, or at least detect, differences between the field list and the physical RMS record. Note that you still must insure that the field list you pass to drlist matches your user record structure.
You can specify a conversion option for each field as shown below:
DRNOCONV No conversion. If the field type, size, or number of elements does no match, drlist returns an error.
DRCONVPRE Perform conversion if values are preserved, otherwise return an error.
DRCONVTRUNC Perform conversion even if precision may be lost.
For example, suppose we have an RMSfile that has a name field. The name field is defined as a 30 character string field. The source program could define the user record structure for the name field as a 50 character string and specify DRCONVPRE in the field list passed to drlist. The program would properly access the RMSfile even if the name field were lengthened (up to 50 characters) in the RMSfile .
For more information on dblist(C-3) and drlist(C-3), see Chapter 8, C/Base Functions. For general RMS programming information, see Chapter 4,
RMS Programming Guide.