DBFETCHP

9.0, PLBCMP GUI or PLBLinux Only

The DBFETCHP instruction retrieves the previous row (record) of a query result. The instruction uses the following format.

Where:

label

Optional. A Program Execution Label.

db

Required. A DBFILE or DBSTATEMENT variable defining the database associated with the connection.

timeout

Required. A Numeric Variable Literal or Expression defining the timeout value to use during the data retrieval.

list

Required. A comma-delimited list of controls and variables that receive the information returned.

;

Optional. A semi-colon that causes the database pointer to not skip to the beginning of the next row or record.

Flags Affected: EOS, LESS, OVER

Note the following:

1. In a database environment, the information is described similar to a spread sheet application. Each record is described as a row and each field is described as a column in the row.

2. The DBSEND/DBEXECUTE sequence of instructions selects a set of rows of data. The DBFETCH instruction then retrieves the rows of data that were just selected one row at a time.

3. The DBFETCHP instruction is similar to READKP or READKGP instructions and retrieves the records previously DBFETCHed in the reverse order.

4. The {timeout} value is specified in seconds. If the value is "-1", the timeout feature is disabled. The LESS flag is set if a timeout occurs.

5. The supported list controls are as follows:

 

Control	Function
*LC	Disable *UC (default)
*LL	Set the length pointer to the last non-blank character received
*PL	Blank-fill after the last character through the Physical Length (default)
*UC	Convert lower case data to upper case

6. The OVER flag is set if there are no more rows to fetch.

7. If the instruction ends with a ';', the row pointer is left pointing to the current row and a subsequent DBFETCH instruction continues retrieving data from the ending position of the prior instruction.

8. Each column fetched is converted to a text string. If the column fetched may not be converted to a text string, the interpreter gives a D209 error. If not enough memory is available to convert the column, the interpreter gives a D210 error. The Windows column types that may be converted are BIGINT, BIT, CHAR, DATE, DECIMAL, DOUBLE, FLOAT, INTEGER, LONG VARCHAR, NUMERIC, REAL, SMALLINT, TIME, TIMESTAMP, TINYINT, and VARCHAR.

9. If the fetch list item is a numeric variable, the converted text string must be a valid number in decimal or fixed point notation, or one of the strings TRUE or FALSE. If the converted text string is a valid number, the number is stored in the variable. If the number contains more integer or fractional digits than the numeric variable, the number is truncated and the EOS flag is set.

10. If the fetch list item is a character variable, each character from the converted text string is placed in the character variable, starting at the first character position of the character variable. Storage of data fetched is determined by the currently active list controls.

11. If there are no more columns in the row (record), any remaining numeric variables in the list are set to a value of zero. Any remaining character variables in the list have Form Pointer and Length Pointer set to zero and the entire character variable is blank filled.

12. The DBFETCHP statement will produce a D215 error if the cursor type is a forward-only cursor.

See Also: Example Code, SQL Instructions