Fetch Generic (FG)

Command title

Fetch Generic

Description

The Fetch Generic command retrieves a row whose key matches a partial or generic key provided in the xxxx-KEY-AREA parameter and places it in xxxx-ROW-AREA.

Successive use of the Fetch Generic command allows for the retrieval of all rows matching the partial key.

COBOL syntax

MOVE 'FG'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            xxxx-ROW-AREA
                            [xxxx-KEY-AREA].

C syntax

memcpy( tbCommArea.tbCommand, "FG", 2 );
TBLBASE( &tbParm, &tbCommArea, pRowArea, pKeyArea );

Parameters

xxxx-ROW-AREA

xxxx-KEY-AREA (optional: see Warning below)—If the xxxx-KEY-AREA parameter is not present, the generic key is taken from the key location within xxxx-ROW-AREA.

The FG-KEY-LENGTH field of xxxx-COMMAND-AREA is used to indicate the length of the search key. tableBASE will use the delimiter method if the FG-KEY-LENGTH field is zero.

Earlier releases of tableBASE used a delimiter character in the xxxx-KEY-AREA to mark the end of the generic key. This approach continues to be supported in Version 6 and beyond for backward compatibility with earlier releases.

The Fetch Generic key delimiter is ‘*’ when distributed with the product, although this may be changed at tableBASE install time. See the Warning below for more details.

If FG-KEY-LENGTH is zero and there is no delimiter in the input xxxx-KEY-AREA, a row’s key will have to match the input xxxx-KEY-AREA exactly for the row to be found.

Explanation

The table is examined for a matching key, starting at the row pointed to by the COUNT value. If the row indicated by COUNT matches the generic key, the next row in the table will be returned if it also has a matching partial key. If the COUNT value points to the last matching row, FOUND is set to N (no row is returned).

If the row indicated by COUNT does not match the generic key, the COUNT is reset to zero and a search is made in the table for the first row that matches. If a matching row is found, it is returned. If not, no row is returned.

If COUNT points outside the table, it is set to point to the first row. Please see an Exception to this below.

The COUNT field should be set to zero before the first FG operation; thus, if a matching row is found, it will always be the first occurrence.

Return value

Error 0004 occurs when the table organization is not Sequential.

Repeated use of this command in a programmed loop returns the first and all subsequent rows in the table that have matching keys, until FOUND is returned as N.

FOUND is set to Y if the row is found.

If a row is returned, COUNT is set to the subscript of the returned row. The row is returned in the xxxx-ROW-AREA. If no row is returned, COUNT will contain the appropriate subscript for a potential insertion.

Notes

The FETCH GENERIC command may be used only with tables having a Sequential (ascending or descending) organization.

FG can be used in conjunction with Date-Sensitive Processing.

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.

Exceptions

If the delimiter is located in the first position of the input xxxx-KEY-AREA, all rows in the table will match. In this case the command will function like the GN command and the row following the value in the COUNT will be retrieved. If the COUNT points outside the table, FOUND is set to N.

See also

Date-sensitive processing

3. FOUND (1 byte)

8. COUNT (fullword binary)

Warning

Although the xxxx-KEY-AREA parameter is optional, it is highly recommended when using a delimiter in the generic key. If xxxx-KEY-AREA is omitted and a match occurs with a partial search key specified in xxxx-ROW-AREA, the retrieved row overlays the search key. Subsequent use of the FG command to search for matching rows, using a search key now lacking the asterisk (*), will return only rows that exactly match the key of the first retrieved row.

The preferred approach is to use the FG-KEY-LENGTH field, avoiding use of a delimiter. If you are using a delimiter and a table key itself contains a delimiter within it, erratic results are possible. Such a situation could occur if the key contains binary values or text that contains the wildcard character. The delimiter may be changed system-wide to some other character. Please see the tableBASE Installation Guide for more information on the FGDELIM parameter.