Fetch Generic (FG)

Fetch Generic

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.

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

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

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.

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.

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.

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.

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.

Date-sensitive processing

3. FOUND (1 byte)

8. COUNT (fullword binary)