Retrieval commands will return a copy of a single row from the table to an application’s ROW-AREA. The length of the ROW-AREA may be less than the length of a row in the table. The ROW-OVERRIDE-LENGTH field of the COMMAND-AREA determines the number of bytes returned in the ROW-AREA.
Update commands will delete, replace, or insert a single row in the table. Data used for replace and insert commands resides in an application ROW-AREA. The length of the ROW-AREA may be less than the length of a row in the table. The number of bytes in ROW-AREA can be overridden by the ROW-OVERRIDE-LENGTH field of the COMMAND-AREA. The length of a row in the table is determined by the RSZ field of the table definition.
- For IK and RK commands, if the ROW-OVERRIDE-LENGTH is less than RSZ in the table, then the first ROW-OVERRIDE-LENGTH bytes of the row are replaced, and the remaining bytes in the table row are filled with low values.
- For tables with duplicate keys, after commands that reload the data, insert new rows or change the definition of the table are performed, the order of the rows containing the duplicate keys may not be preserved.
Accessing a table
A table is accessed for four primary reasons:
- inserting a row
- reading a row
- updating a row
- deleting a row.
Inserting a row was discussed above. Reading a row is equally straightforward. A row can be read by key or by row number. Or, you may cycle through a table from row to row. You may even read rows using a partial key, so that, for example, you may read all rows whose key starts with PAY3 in the first 4 bytes.
Figure 90 is an example of how you would retrieve all rows whose key starts with PAY3 in bytes 1-4 of the key field.
The FG command performs a generic fetch. It will retrieve all rows which match the first portion (PAY3) of the key that you have placed in ACCTG-KEY-AREA. We follow the tableBASE call with a test to determine whether the row exists. Note also that setting a 4 in the ACCTG-FG-KEY-LENGTH field of the command area ensures that the first row matching the partial key is retrieved. tableBASE sets various flags in the COMMAND-AREA to keep you informed of the results of your request; the FOUND-CODE is one of the flags set by tableBASE.
To obtain a particular row number by position, use the FC (Fetch by Count) command. To search on an entire key, use FK (Fetch by Key) or FN (Fetch Next). Use the Get-series of commands to cycle through a table: Get First (GF), Get Next (GN), Get Last (GL), and Get Previous (GP).
Updating involves replacing, inserting, and deleting. Updates to a table are based on either a key or a row number. To insert a row based on a key use the IK command. To insert a row based on row number, use the IC (Insert by Count) command. The replace and delete functions operate in a fashion similar to insert. For each function there are two options—key and row number. The commands are RK (Replace by Key), RC (Replace by Count), DK (Delete by Key), and DC (Delete by Count).
Store processing
To ensure that any changes made to a table are persistent, you must store the table to a tableBASE library (see Store Table (ST)). When a table is stored, a new generation of the table is created. Unless a table is diverted for storage to another tableBASE library by means of the Table Control command DV (or its associate, DW), a new table generation will always be stored in the library from which it was originally loaded.
Since a new generation is stored before the oldest one is deleted, there must be enough space in the library to temporarily accommodate one additional generation. This means there must be enough space available to hold one more generation of the largest table on the library. When the number of generations required to be kept is exceeded, the oldest generation will be deleted.