4 Database Manipulation

Advanced Access Statements

The DBASE IS Statement

DBASE IS base name

The parameter is:

base name

The same string variable identifying the database name when the database was opened.

The IN DATA SET Statement

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.

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:

• All letters except the first one are converted to lowercase.

• All dashes (-) are converted to underscores (_).

• If the schema item is a string, a dollar sign ($) is appended to the name.

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

• The data item types.

• The dimension types (simple or one-dimensional array).

• In the case of strings, the maximum string length.

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$)
   ...

   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$)
   ...