4 Database Manipulation

Advanced Access Statements

Two advanced access statements are described on the following pages. These statements facilitate the use of the Eloquence programming statements discussed earlier by loading or unloading information during DBGET, DBPUT, or DBUPDATE execution.

The DBASE IS Statement

The DBASE IS statement defines the database to be referenced by subsequent IN DATA SET and WORKFILE IS statements. WORKFILE IS is used in conjunction with the FIND and/or SORT statements.

DBASE IS base name

The parameter is:

base name
The same string variable identifying the database name when the database was opened.
DBOPEN must be executed prior to executing the DBASE IS statement. The database being referenced is reset either by specifying another DBASE IS statement or by closing the referenced database in mode 1.

The IN DATA SET Statement

Through IN DATA SET, data may be automatically transferred from program variables to the buffer variable prior to DBPUT and DBUPDATE. Data may also be automatically transferred from the buffer to program variables after DBGET.

IN DATA SET data set [IN COM] USE REMOTE LISTS line id list

IN DATA SET data set LIST item list

IN DATA SET data set LIST item list FREE

IN DATA SET data set USE STRUCT Instance name

IN DATA SET data set DEFINE TYPE type name

The parameters are:

data set
Either a string expression containing a left-justified data set name or a numeric expression containing a data set number corresponding to the data set position in the schema definition.
item list
A group of numeric, string, or array variables used to associate data items to Eloquence variables. If there are more items in the schema entry than variables in the list, the extra items are skipped. This can also be done by specifying SKP n in the item list, where n is the number of items you want to skip, or nX, where n is the number of bytes you want to skip (see PACKFMT). Note that you have to skip entire items. The variable names must be in the order as defined by the schema definition, and must be separated by commas.
line id list
A list of line numbers or line labels separated by commas.
During IN DATA SET execution, the data set must be a member of the database recently referenced through DBASE IS. Once the item list has been established for a data set, the default database may be changed through DBASE IS. The correct data-set/data-base relationship is maintained during DBGET and DBUPDATE operations.

In the USE ALL mode, all program variables are searched for a match against the data set's item names, as stored in the root file. Before a match can be determined the schema names undergo the following conversion:

NOTE: Item names containing native language characters (for example, Ae and E^) are not allowed as variable names; therefore, they are not automatically converted and cannot be accessed.

The converted schema name is then compared against all program variables. In addition to a name match, a match must exist for the following:

If the variable was not previously defined during program execution, it will be dimensioned according to the schema item definition.

If all of these conditions are satisfied, the program variable is automatically updated when a data set entry is read into the buffer by DBGET. Before an entry is added (DBPUT) or modified (DBUPDATE), data is automatically copied from the program variable to the buffer.

DIM ALL, like USE ALL, establishes a relationship between program variables and matching data set item names. If a match is not found, however, the data set's field is not treated as a skip field, as with the USE ALL mode. Instead, a variable is automatically created within the program with attributes (field type and length) and name matching the corresponding data item.

If an item list is specified, the variables in the list must exactly match the type and length of the corresponding fields in the referenced data set. Comparisons are made on a positional basis; that is, the first data set field is compared to the first variable in the list, the second field to the second variable and so on.

The SKP option may be used to skip unwanted fields. To skip two or more fields in a row, an appended integer may be used (SKP2 or 10X). This option is useful where only selected fields of a data set entry need to be accessed. Skipped fields are not modified by DBUPDATE and are assigned a null value by DBPUT. If a particular value is desired in a skipped field, this value can be assigned to the string before the DBPUT or DBUPDATE. Note that assigning a value to the buffer string does not change the value of the program variables specified in the IN DATA SET statement.

USE REMOTE LISTS is a means of referencing item lists that appear in other program lines. The lines referenced in the line id list (either by number or label) contain the actual item list. The item lists are evaluated in the order of the line id list. This option is a method of extending an item list length beyond the maximum program line length of 500 characters.

If the IN COM option is selected, an IN DATA SET statement executed in the main program remains active across all subprograms and functions. IN COM may be used with any of the previously described IN DATA SET options. However, all variables referenced must be explicitly dimensioned in common. This option can only appear in the main program, and not in subprograms or functions.

The FREE option releases the internal relationship between the data set and the program variables. Data is no longer transferred to and from the program variables. FREE is necessary only if the IN COM option is used in the main program and another link is desired. Otherwise FREE is implied with IN DATA SET.

DEFINE TYPE is used with user defined types to define a new type from a data set. The type name must not already been defined.

USE STRUCT is used with user defined types to bind the items in data set to the member variables. The specified variable must have been deimensioned.

For example:

DBOPEN(Db$,"",1,S(*))
   ...
   IN DATA SET "CUSTOMER" DEFINE TYPE Tcust
   NEW Cust:Tcust
   IN DATA SET "CUSTOMER" USE STRUCT Cust
   ...
   DBGET(Db$,"CUSTOMER",7,S(*),"@",Buf$,Key$)
   ...
Of course, types can also be defined statically in your program:

   TYPE Tcust
      DIM No$[6]
      DIM Name$[30]
      ...
   END TYPE
   DIM Cust:Tcust
!
   DBOPEN(Db$,"",1,S(*))
   ...
   IN DATA SET "CUSTOMER" USE STRUCT Cust
   ...
   DBGET(Db$,"CUSTOMER",7,S(*),"@",Buf$,Key$)
   ...
NOTE: Care must be taken when executing DBGET to establish the current record pointer for DBUPDATE. Since IN DATA SET automatically transfers the contents of the buffer to program variables during DBGET, these variables must be updated following the DBGET operations.


Eloquence Database Manual - 19 DEC 2002