Retrieval commands

You can locate and retrieve rows from a table by using the following Search, Fetch, and Get commands:

Following the execution of any retrieval command, the FOUND code in the xxxx-COMMAND-AREA is set to show the result of the access request (see 3. FOUND (1 byte)). All retrieval commands set the COUNT field in xxxx-COMMAND-AREA, except the Fetch by Count (FC) command.

If a retrieval request succeeds in finding the desired row in the table, a copy of the row is moved to the xxxx-ROW-AREA parameter. The exception is SK, which does not retrieve a row.

Commands that use a full-key search, like SK and FK, always find the first row of a group of rows having duplicate keys (SK just finds the row; FK finds and returns it).

The number of bytes returned by a successful retrieval request is normally determined by the row size defined in the table definition. This can be overridden for the request by setting the ROW-OVERRIDE-LENGTH value in the xxxx-COMMAND-AREA.

If ROW-OVERRIDE-LENGTH is set to zero, the request returns the number of bytes specified in the table definition. Otherwise, ROW-OVERRIDE-LENGTH determines the number of bytes returned. If ROW-OVERRIDE-LENGTH is greater than zero and less than the defined row size for the table, then a truncated row is returned. If ROW-OVERRIDE-LENGTH is greater than the defined row size, then an entire row is retrieved from the table and the remainder of the row is padded with low values to the right of the row.

On completion of the request, tableBASE sets the ROW-ACTUAL-LENGTH field of the xxxx-COMMAND-AREA to indicate the actual row size.

If the table has not been explicitly opened, and IMPLICIT_OPEN is set to Y, a retrieval command will cause tableBASE to attempt an automatic open of the table. If the open is successful, COUNT is reset to zero for all retrieval commands except FC. It is this value which would be used in the execution of the retrieval command. This could affect the operation of count-dependent commands, like FG, FN, GN, GP, which may have started with specific values in COUNT for the first access to a table.

Note:

In a multi-tasking or multi-user online environment, results for commands that utilize a count or sequential accessing of table rows may get unexpected results if another task/user is updating or deleting rows in the same table.

Note:

GET commands GF, GL, GN and GP return empty rows in Hash tables if the HASH EMPTIES-RETURNED switch of the STATUS-SWITCHES is set to Y. Your program can check for empty rows by examining the key portion of xxxx-ROW-AREA for low values.

If the HASH-EMPTIES-RETURNED switch is set to N, empty rows are skipped automatically. COUNT reflects the physical location of the retrieved row in the table. The Change Status (CS) command may be used to suppress the return of empty rows, often resulting in more streamlined code. More information about the CS command is found in Change Status (CS).