Step Next Extended (38)

Step Next Extended (38)

The Step Next Extended operation (B_STEP_NEXT_EXT) examines one or more records, starting at the next physical position and proceeding toward the end of the file. 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.

Step Next Extended can also extract specified fields from existing records and return a new set of records that contain only the extracted fields.


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

•

The file must be open.

•

You must have established a next physical position. (For example, a Step Next Extended operation cannot follow a Delete operation.)

1

Set the Operation Code to 38. 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.

2

Pass the Position Block for the file.

3

Specify a Data Buffer large enough 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 21.

4

Specify the Data Buffer Length from the preceding step.

The transactional interface sets up a buffer as a workspace for extended operations. You configure the size of this buffer using the Extended Operation Buffer Size option. The sum of the Data Buffer structure, plus the longest record to be retrieved, plus 355 bytes of requester overhead, cannot exceed the configured buffer size. (Requester overhead is not applicable in DOS workstation engines.)

The Step Next Extended operation shares the same “Details” as the Get Next Extended operation. Refer to Details for more information.

If the Step Next Extended operation is successful, the transactional interface returns one or more fields from one or more records to the Data Buffer (as shown in Table 22). The transactional interface also sets the Data Buffer Length parameter to the number of bytes it returned to the Data Buffer.

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


3	The file is not open.
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 record 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 Step Next Extended operation that retrieves three fields from two variable-length records. The first record is 55 bytes long, and the second is 50 bytes. The 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 Step Next Extended operation, it returns the first record without any problem. However, when attempting to extract 10 bytes from field 2 of 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 first 5 bytes of field 2 in the return Data Buffer.

The Step Next Extended operation does not establish any logical currency, but the last record examined (not necessarily retrieved) becomes the current physical 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.

Note: The transactional interface does not allow Delete or Update operations after a Step 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.