LOCATE
Position the record pointer within a result set.
>>-LOCATE--| pointer_group |--RESULT--(--cpsm-token--)----------> >--THREAD--(--cpsm-token--)--RESPONSE--(--data-ref--)-----------> >--REASON--(--data-ref--)-------------------------------------->< pointer_group |--+-| POSITION_group |-+---------------------------------------| '-| FILTER_group |---' POSITION_group .-TOP------------------------. |--+----------------------------+-------------------------------| +-BOTTOM---------------------+ +-POSITION--(--data-value--)-+ +-FORWARD--(--data-value--)--+ '-BACKWARD--(--data-value--)-' FILTER_group .-FIRST-. |--+-FILTER--(--cpsm-token--)----+--+-------+-------------------| +-MARKED----------------------+ +-LAST--+ +-NOTFILTER--(--cpsm-token--)-+ +-NEXT--+ '-NOTMARKED-------------------' '-PREV--'
Description
- API commands that manipulate records or update the data in a result set
affect the position of the record pointer:
- After a GET command, the pointer is positioned to the top of the result set.
- After a FETCH command, the pointer is positioned to the next record in the result set (that is, the record following the last record fetched in whichever direction the pointer was moving, forward or backward). If no records were fetched (because no records matched the specified criteria), the pointer is positioned to the top or bottom of the result set, depending on which direction it was moving.
- The LOCATE command skips over any deleted records in the result set. If you try to position the record pointer to a deleted record, you receive a RESPONSE value of NODATA.
Related commands
COPY, DELETE, FETCH, GETDEF, GROUP, MARK, ORDER, PERFORM OBJECT, PERFORM SET, REFRESH, SET, SPECIFY FILTER, UNMARK
Options
- BACKWARD(data-value)
- Moves the record pointer backward by the specified number of resource
table records.
If the pointer reaches the top of the result set, it remains positioned on the first resource table record. The pointer does not continue moving backward to the bottom of the result set.
- BOTTOM
- Moves the record pointer to the the last resource table record in the result set.
- FILTER(cpsm-token)
- Identifies a filter to be used for this operation.
The FILTER option positions the record pointer to a resource table record that meets the specified filter criteria. The FIRST, LAST, NEXT, or PREV option determines where in the result set the search begins and in what direction it continues.
The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.
- FIRST
- Begins a search based upon filter or marking criteria with the first resource table record in the result set. The search continues in a forward direction through the result set until a match is found.
- FORWARD(data-value)
- Moves the record pointer forward by the specified number of resource table
records.
If the pointer reaches the bottom of the result set, it remains positioned on the last resource table record. The pointer does not continue moving forward to the top of the result set.
- LAST
- Begins a search based upon filter or marking criteria with the last resource table record in the result set. The search continues in a backward direction through the result set until a match is found.
- MARKED
- Positions the record pointer to a resource table record that is marked.
The FIRST, LAST, NEXT, or PREV option determines where in the result set the
search begins and in what direction it continues.
You can mark resource table records by using the MARK and UNMARK commands.
- NEXT
- Begins a search based upon filter or marking criteria with the current resource table record in the result set. The search continues in a forward direction through the result set until a match is found.
- NOTFILTER(cpsm-token)
- Identifies a filter to be used for this operation.
The NOTFILTER option positions the record pointer to a resource table record that does not meet the specified filter criteria. The FIRST, LAST, NEXT, or PREV option determines where in the result set the search begins and in what direction it continues.
The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.
- NOTMARKED
- Positions the record pointer to a resource table record that is not marked.
The FIRST, LAST, NEXT, or PREV option determines where in the result set the
search begins and in what direction it continues.
You can mark resource table records by using the MARK and UNMARK commands.
- POSITION(data-value)
- Moves the record pointer to the nth resource table record in the result
set.
This value must be a number that identifies the record's relative position in the result set. The first record in a result set is identified by the number 1.
For example, to move the record pointer to the fifth resource table record in a result set, you would specify POSITION(5).
- PREV
- Begins a search based upon filter or marking criteria with the previous resource table record in the result set. The search continues in a backward direction through the result set until a match is found.
- REASON(data-ref)
- Names a variable to receive the fullword reason value returned by this command.
- RESPONSE(data-ref)
- Names a variable to receive the fullword response value returned by this command.
- RESULT(cpsm-token)
- Identifies the API result set to be processed by this operation. The result
set can be one produced by any of these commands:
- COPY
- GET
- GETDEF
- GROUP
- PERFORM OBJECT.
- THREAD(cpsm-token)
- Identifies the API thread to be used for this operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.
- TOP
- Moves the record pointer to the first resource table record in the result set.
Conditions
- OK
- The command completed processing successfully.
- NODATA
- No records were found that matched the specified search criteria, for
one of the following reasons:
- BACKWARD
- There are no more records that satisfy the search criteria in the backward direction.
- FORWARD
- There are no more records that satisfy the search criteria in the forward direction.
- BUSY
- A busy condition occurred for the following reason:
- RESULT
- The result set specified on the RESULT option is being processed by another command.
- ENVIRONERROR
- An environment error occurred for one of the following reasons:
- NOSERVICE
- The application stub program could not load the API service module.
- NOSTORAGE
- The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
- SOCRESOURCE
- A required resource that is owned by the CMAS is not available.
- SOLRESOURCE
- A required resource that is locally owned (that is, owned by the address space where the processing thread is running) is not available.
- FAILED
- The command failed for one of the following reasons:
- ABENDED
- Command processing abended.
- EXCEPTION
- Command processing encountered an exceptional condition.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid is returned
as the reason value:
- BACKWARD
- FILTER
- FORWARD
- NOTFILTER
- POSITION
- RESULT
- THREAD.
- NOTAVAILABLE
- A not available condition occurred for one of the following reasons:
- APITASK
- The API control subtask is not active.
- CPSMAPI
- The CMAS to which the processing thread was trying to connect is not available for API processing.
- SERVERGONE
- The CMAS to which the processing thread was connected is no longer active.
- VERSIONINVL
- A version conflict occurred for one of the following reasons:
- NOTSUPPORTED
- The version of the application stub program used for this command is not supported.
- NOTVSNCONN
- The version of the application stub program used for this command is not the same as the version used with the CONNECT command.
