4 Database Manipulation
The DBPUT Statement
DBPUT adds new data entries to a manual or detail set.
DBPUT (base name, data set, mode, status, list, buffer)
The parameters are:
- base name
- The same string variable used when opening the database.
- 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's position in the schema definition.
- mode
- A numeric expression equal to 1.
- status
- An integer array variable that returns status information after DBPUT is executed. The array must contain at least ten elements in its right-most dimension.
- list
- A string variable containing @$\triangle$ or @; or @ ($\triangle$ represents a space). This value means that only entire records can be accessed and is referred to as the full record mode.
- buffer
- A simple string variable containing data that is to be placed into the specified set.
The buffer parameter must contain values for all items in the data entry to be added. Eloquence DBMS determines the physical record placement of the entry within the data set.
When the data set is a manual-master data set, Eloquence DBMS verifies that no existing data entry has a search item value identical to the new data entry. If this test fails, an error condition is returned in the status array; otherwise, the new data entry is added.
When the data set parameter is a detail data set, Eloquence DBMS verifies the following:
- The related manual-master data sets have entries with search item values that match the corresponding detail search item values.
- All necessary entries in the related automatic-master data sets are present.
If any of these tests fail, an error condition is returned in the first element of the status array. Otherwise, the data entry is added to the detail data set with Eloquence DBMS performing all linkage maintenance and, when necessary, creating entries in the automatic-master data sets.
Eloquence DBMS determines the physical location of the entry within the data set. If the detail data set is related to one or more master data sets, however, the entry is logically linked to the end of each chain.
Data may not be added directly (DBPUT) to automatic masters. Data is added or deleted automatically as detail data set entries are added or deleted.
NOTE: Even though entries might have been put into the database in sequence, there is no guarantee they will appear in this sequence in the database.
DBPUT Status Array
A DBPUT error assigns a non-zero conditional word (CW) to the first element of the status array. A list of all CW values and their meanings appears in page 197 . For a successful DBPUT, the status array contents are as described under DBGET, except that the second element represents the number of words transferred from the buffer to the data set.
Eloquence Database Manual - 19 DEC 2002