Get Next Extended (36)

The Get Next Extended operation (B_GET_NEXT_EXTENDED) examines one or more records, starting at the logical next position and proceeding toward the end of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only.

Get Next Extended can also extract specified portions from records and return only those portions to an application.

Parameters


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

Prerequisites

The file must be open.

The file cannot be a data-only file.

You must have an established logical next position based on the specified key. You can establish logical positioning by issing any non-extended Get operation, such as a Get Equal.

Procedure

Set the Operation Code to 36. Optionally, you can include a lock bias:

+100-Single wait record lock.

+200-Single no-wait record lock.

+300-Multiple wait record lock.

+400-Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.

Pass the Position Block for the file.

Specify a large enough Data Buffer to accommodate either the input Data Buffer or the returned Data Buffer, whichever is larger. Initialize the Data Buffer according to the structure shown in Table 2-14.

Specify the Data Buffer Length as either the length of the input structure (Table 2-14) or the length of the returned structure (Table 2-15), whichever is larger.

Specify the key value from the previous operation in the Key Buffer. Pass the Key Buffer exactly as the transactional interface returned it on the previous call, because the transactional interface may need the information previously stored there to determine its current position in the file.

Set the Key Number parameter to the key path used on the previous call. You cannot change key paths using a Get Next Extended operation.

Details

The following table shows the structure of the input data buffer.

Table 2-14 Input Data Buffer Structure for Extended Get and Step Operations
Element	Length (in Bytes)	Description
Header	2	Total length of the Data Buffer.
Header	2	One of two string constant values (fixed length, do not null-terminate): "EG"-Begin with the record after the one at which you are positioned. "UC"-Begin with the record at which you are positioned. For Step Next Extended operations, always set this value to "EG".
Filter (Fixed Portion)	2	Maximum Reject Count, which is the number of records that the transactional interface can skip while searching for records that satisfy the filter condition. You can set the value from 0 to 65,535. (0 means the transactional interface uses the system-defined maximum reject count, which is 4,095.)
Filter (Fixed Portion)	2	Number of Terms in the logic expression of the filter condition. (0 means the transactional interface performs no filtering.) The only limit to the number of terms is the size of the data buffer. In Pervasive.SQL 2000i SP3 only, the limit for the number of terms is 119.
Filter (Repeat this segment once for each term in the logic expression)	1	Data Type of the field. Use one of the codes shown in Table 2-4.
	2	Field Length.
	2	Field Offset (zero relative).
	1	Specifies a Comparison Code: 1-Equal 2-Greater than 3-Less than 4-Not equal 5-Greater than or equal 6-Less than or equal Add a +8 bias to compare strings using one of the file's existing ACSs. Add a +32 bias to compare strings using the file's default ACS, which is the first ACS defined in the file. If you use both a +8 bias and a +32 bias, the +32 bias is ignored.
		Add a +64 bias if the second operand is another field of the record, rather than a constant. Add a +128 bias to compare strings without case sensitivity.
	1	Indicates an AND/OR logic expression: 0-Identifies the last term 1-Next term is connected with AND 2-Next term is connected with OR
	2 or n	When comparing two fields: a 2-byte, zero-relative offset to the second field. (The second field must be the same type and length.) or When comparing a field to a constant: the actual value of the constant. The length of the constant (n) must equal the length of the field.
	0, 5, 9, or 17	When specifying an ACS by name (bias +8), the ACS identifier using one of the name formats shown in Table 2-5.
Descriptor (Fixed Portion)	2	Number of Records to retrieve. To retrieve only one record instead of a set of records, specify 1.
Descriptor (Fixed Portion)	2	Number of Fields to extract from each record.
Descriptor (Repeat this segment for each extracted field)	2	Field Length to extract.
Descriptor (Repeat this segment for each extracted field)	2	Field Offset (zero relative).

The transactional interface interprets the AND and OR operators used in a filter with the extended Get and Step operations in strict left-to-right order. The transactional interface evaluates an expression in the filter and proceeds as follows:

If the expression is true when applied to the current record and the next operator is OR, the transactional interface accepts this record as meeting the filter condition.

If the expression is true and the next operator is AND, the transactional interface continues to evaluate each expression until one of the following situations occurs:

The transactional interface reaches an OR expression.

One of the expressions evaluates to false.

The transactional interface reaches the end of the filter.

If the expression is false and the next operator is OR, the transactional interface continues and evaluates the next expression in the filter.

If the expression is false and the next operator is AND, the transactional interface rejects the record.

The search for records stops if any one of the following conditions is met:

The transactional interface finds the requested number of records that satisfy the filter.

While the transactional interface searches for records to satisfy the filter condition, the number of records it examines exceeds the Maximum Reject Count you specify.

The current key path is used as a filtering field and the transactional interface reaches a rejected record after which no records can satisfy the filtering condition in the rest of the file.

The transactional interface reaches the end of the file.

Examples

To get the next entire record that satisfies the filtering condition, set the filter portion as desired and set the descriptor fields as follows:

Set the Number of Records to 1.

Set the Number of Fields to 1.

Set the Field Length to the length of the entire record to retrieve.

Set the Field Offset to 0.

To retrieve the next 12 records without using a filtering condition and extract 4 fields from each record, set the filter Number of Terms to 0 and set the descriptor fields as follows:

Set the Number of Records to 12.

Set the Number of Fields to 4.

Set the Field Length and Field Offset parameters for each of the 4 fields extracted.

Retrieving Fields from Records

When retrieving one or more fields (portions) of records with an extended operation, you must ensure that the Data Buffer can accommodate the information that the operation returns.

Table 2-15 illustrates the structure of the Data Buffer that the transactional interface returns.

Table 2-15 Returned Data Buffer Structure for Extended Get and Step Ops
Element	Length (in Bytes)	Description
Number of Records	2	Number of records returned.
Repeating portion (one for each record retrieved)
Length 0	2	Length of the first record image (all fields combined).
Position 0	4	Physical currency (address) of the first record.
Record 0	n	Image of the first record (all fields combined).
. . .
Length x	2	Length in bytes of the last record image (all fields combined).
Position x	4	Physical currency (address) of the last record.
Record x	n	Image of the last record (all fields combined).

If all returned records (or fields of records) are fixed length, your application can easily calculate the location of data within the returned Data Buffer. However, your application may need to perform extra steps to extract the variable-length portion of records from the Data Buffer that an extended operation returns.

The transactional interface does not pad any record image in the returned Data Buffer when returning the variable-length portion of a record. Consequently, if you allow room in the returned Data Buffer for the maximum number of bytes that the variable-length portion of a record could occupy, but the actual data returned is less than that maximum, the transactional interface starts the field description for the next returned field immediately following the data for the current field.

For example, suppose your fixed-record length is 100 bytes, your variable-length portion is up to 300 bytes, and you want to return just the variable-length portion of 5 records. You would use the descriptor element of the input buffer to set a Field Length of 300 and a Field Offset of 100. For the returned buffer, you need 2 bytes for the Number of Records plus 306 bytes for each record (that is, 2 bytes for the length, 4 bytes for the address, and 300 bytes for the data), as shown in the following calculation:

2 + ((2 bytes + 4 bytes + 300 bytes) * 5) = 1532 bytes

However, suppose that the variable-length portion of the first record returned contains only 50 bytes of data. This means the 2-byte length for the second record returned is stored at offset 58 in the Data Buffer, immediately following the image of the first record's field. In such a situation, your application must parse the length, position, and data from the Data Buffer that the transactional interface returns.

Result

If the Get Next Extended operation is successful, the transactional interface returns the following:

In the Data Buffer, one or more fields from one or more records. (See Table 2-15.)

In the Data Buffer Length, the total number of bytes received.

In the Key Buffer, the key value for the last data record received.

If the Get Next Extended operation is unsuccessful, the transactional interface returns one of the following status codes:


3	The file is not open.
6	The key number parameter is invalid.
7	The key number has changed.
8	The current positioning is invalid.
9	The operation encountered the end-of-file.
22	The data buffer parameter is too short.
60	The specified reject count has been reached.
61	The work space is too small.
62	The descriptor is incorrect.
64	The filter limit has been reached.
65	The field offset is incorrect.
82	The transactional interface lost positioning.
134	The transactional interface cannot read the International Sorting Rule.
135	The specified International Sort Rule table is corrupt or otherwise invalid.
136	The transactional interface cannot find the specified Alternate Collating Sequence in the file.

It is possible for the transactional interface to return a nonzero status code and also return valid data in the Data Buffer. In this case, the last record returned may be incomplete. If the Data Buffer Length parameter returned is greater than 0, check the Data Buffer for extracted data.

If a field can only be partially filled because the data buffer is too short, then the transactional interface returns what it can of the record to and including the partial field. If the partial field is the last field to be extracted, then the transactional interface continues the operation. Otherwise, the transactional interface aborts the operation and returns a Status Code 22.

For example, consider a Get Next Extended operation that retrieves 3 fields from 2 variable-length records. The first record is 55 bytes long and the second is 50 bytes long. The Data Buffer allows 50 bytes for return data. The 3 fields to be retrieved are defined as follows:

Field 1 begins at offset 2 and is 2 bytes long.

Field 2 begins at offset 45 and is 10 bytes long.

Field 3 begins at offset 6 and is 2 bytes long.

When the transactional interface performs the Get Next Extended operation, it returns the first record without any problem. However, when attempting to extract field 2's 10 bytes from the second record, the transactional interface finds that only 5 bytes are available (between offset 45 and the end of the record, at offset 49). At this point, the transactional interface does not pad the missing 5 bytes of field 2, and thus cannot extract field 3. Instead, the transactional interface returns Status Code 22 and places all of field 1 and the first 5 bytes of field 2 in the return Data Buffer.

Depending on the fields and the operators used in the filtering condition, the transactional interface may be able to optimize your request. After reaching a certain rejected record, it returns Status Code 64, indicating that no records can satisfy the filtering conditions in the rest of the file.

Positioning

The Get Next Extended operation establishes the complete logical and physical currencies. The last record examined becomes the current record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected, but is still not past the optimization limit. For example, if the extended operation returns status 9, the current record is that last record in the file. If status 60 (reject count reached) is retuned, then the current record is the last record rejected. If status 64 (Filter Limit Reached) is returned, then the current record is the last record that satisfies the optimization criteria. Even thought the transactional interface had to look at the next record after this to determine that the optimization limit was exceeded, it sets the current record back to the previous record that did satisfy that criteria.

Note
The transactional interface does not allow Delete or Update operations after a Get Next Extended operation. Because the current record is the last record examined, there is no way to ensure that your application would delete or update the intended record.