FETCH

Retrieve data and status information for resource table records.

Read syntax diagramSkip visual syntax diagram>>-FETCH--INTO(data-area)--LENGTH(data-ref)--------------------->
 
>--+-+-----------------------+--+----------------------+-+------>
   | +-FILTER(cpsm-token)----+  '-CICSNAME(data-value)-' |
   | '-NOTFILTER(cpsm-token)-'                           |
   +-ALL-------------------------------------------------+
   +-MARKED----------------------------------------------+
   '-NOTMARKED-------------------------------------------'
 
                                                  .-DATA---.
>--+----------------------+--+-----------------+--+--------+---->
   '-POSITION(data-value)-'  '-COUNT(data-ref)-'  +-BOTH---+
                                                  '-STATUS-'
 
                                 .-FORWARD--.
>--+--------------------------+--+----------+------------------->
   '-DETAIL--+--------------+-'  '-BACKWARD-'
             '-APPLYSUMMARY-'
 
>--RESULT(cpsm-token)--THREAD(cpsm-token)--RESPONSE(data-ref)--->
 
>--REASON(data-ref)--------------------------------------------><
 

Description

This command retrieves data and status information for one or more resource table records in a result set.

Related commands

COPY, GET, GETDEF, GROUP, LOCATE, MARK, ORDER, PERFORM OBJECT, QUERY, SPECIFY FILTER

Options

ALL
Retrieves all the resource table records in the result set. When you specify ALL, the POSITION and COUNT options are ignored.
APPLYSUMMARY
Apply any, some, or all of the following options to the summary records and retrieve the detail records associated with the summary records selected.
  • MARKED
  • NOTMARKED
  • FILTER
  • NOTFILTER
The APPLYSUMMARY option is only valid if the DETAIL option is also specified.

If the DETAIL option is specified without the APPLYSUMMARY option the result will be as described under the DETAIL option.

If neither the DETAIL option nor the APPLYSUMMARY option are specified but any combination of some or all of the following record selection options: MARKED, NOTMARKED, FILTER, and NOTFILTER are issued against a summary result set, the record selection options are applied to the summary result set and the selected summary records are retrieved.

BACKWARD
Begins the retrieval process with the last record fetched and continues in a backward direction through the specified result set.
BOTH
Retrieves both the resource table data and the OBJSTAT status information about the last action performed against the resource table. Each record contains OBJSTAT information followed by resource table data.
CICSNAME(data-value)
Specifies a 1- to 8-character specific or generic CICS system name to be used for this operation.

The CICSNAME option indicates that only those resource table records that originate from CICS systems that match the specified name pattern should be considered for retrieval. When CICSNAME is specified in conjunction with FILTER or NOTFILTER, only records which meet the FILTER or NOTFILTER requirements and also match the CICSNAME pattern will be considered. The number of records actually retrieved is determined by the COUNT option.

When you specify CICSNAME, the result set named on the RESULT option must not be a summarized result set and must contain resource table records that have an EYU_CICSNAME attribute. If the result set specifed by RESULT contains summarized records or resource table records that do not have an EYU_CICSNAME attribute, you receive an INVALIDPARM response for the CICSNAME option.

COUNT(data-ref)
Start of changeSpecifies the number of resource table records to be processed.

The COUNT option applies to the result set named in the RESULT option. When you also specify the DETAIL option, COUNT provides the number of summary records in the summarized result set in RESULT for which source records are returned. The OBJSTAT table for each summary record contains the number of source records that will be returned for that record if the DETAIL option is specified.

If you do not specify the COUNT option, the default is one.

If the COUNT option is specified, COUNT contains the number of records processed. In most cases this is also the number of records returned. However, if you also specify the DETAIL option, all source records associated with the requested number of summary record are retrieved. This is normally greater than the number specified in the COUNT option.

If you are retrieving multiple records, they are placed one after another in the INTO buffer. The INTO buffer should be long enough to hold all the records being retrieved.

The value that CICSPlex SM returns in this field depends on the RESPONSE value for the FETCH command as follows:

OK
The actual number of records returned in the INTO buffer.
WARNING AREATOOSMALL
The number of records returned in the INTO buffer, which is not the total number of records requested.
INVALIDPARM LENGTH
The field is not set because the INTO buffer was not long enough to hold even one resource table record.
End of change
DATA
Retrieves only the specified resource table data. The records do not contain any OBJSTAT status information about the last action performed against the resource table.
Note:
The OBJSTAT information includes a summary count field that is set when resource table records are summarized using the GROUP command. If you plan to GROUP the resource table records and you want to know how many records are combined to form a summary record, you should specify BOTH to obtain both data and OBJSTAT information when the records are fetched.
DETAIL
Start of changeRetrieves the source records associated with specific summary resource table records.

When you specify DETAIL, the result set named in the RESULT option must be a summarized result set. DETAIL expands the summary record by retrieving the resource table records associated with it from the source result set. If you do not specify DETAIL when a summarized result set is being processed, the summary records themselves are retrieved. If the result set is not a summarized result set, this option has no meaning and is ignored.

You can use the FORWARD or BACKWARD options along with DETAIL to select which summary record you want to expand. The FORWARD and BACKWARD options also control the direction in which records are retrieve from the source result set.

By default, all the source records associated with the summary record or records are retrieved. However, you can use the FILTER or NOTFILTER option to limit the records retrieved from the source result set. You can also use the MARKED or NOTMARKED option to retrieve only those records associated with the summary record that are marked (or not marked) in the source result set.

You cannot explicitly position the record pointer in the source result set. When you specify DETAIL, the POSITION option refers to the record in the summary result set. If the APPLYSUMMARY option is specified, FILTER, NOTFILTER, MARKED, and NOTMARKED options are applied to records in the summary result set rather than to the source records.

For more information on processing summarized result sets, see CICSPlex® System Manager Application Programming Guide. For a description of the GROUP command, which creates summarized result sets, see GROUP.

End of change
FILTER(cpsm-token)
Identifies a filter to be used for this operation. The FILTER option indicates that only those resource table records that meet the specified filter criteria should be considered for retrieval. The number of records that are actually retrieved is determined by the COUNT option.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

FORWARD
Begins the retrieval process with the next record (that is, the record that follows the last record fetched) and continues in a forward direction through the specified result set.
INTO(data-area)
Identifies a buffer (or stem variable, in REXX) to receive the resource table records. This buffer must be long enough to hold all the records being retrieved.
LENGTH(data-ref)
A fullword value that specifies the length of the INTO buffer.

The value that CICSPlex SM returns in this field depends on the RESPONSE value for the FETCH command:

OK
The actual length of the data returned in the INTO buffer.
NODATA
The length is set to zero.
WARNING AREATOOSMALL
The buffer length that would be required to hold all the requested records.
INVALIDPARM LENGTH
The field is not set because the INTO buffer was not long enough to hold even one resource table record.
MARKED
Indicates that only those resource table records that are marked in the result set should be considered for retrieval. The number of records that are actually retrieved is determined by the COUNT option.

You can mark resource table records by using the MARK and UNMARK commands.

NOTFILTER(cpsm-token)
Identifies a filter to be used for this operation. The NOTFILTER option indicates that only those resource table records that do not meet the specified filter criteria should be considered for retrieval. The number of records that are actually retrieved is determined by the COUNT option.

The cpsm-token value that identifies a filter is returned by the SPECIFY FILTER command.

NOTMARKED
Indicates that only those resource table records that are not marked in the result set should be considered for retrieval. The number of records that are actually retrieved is determined by the COUNT option.

You can mark resource table records by using the MARK and UNMARK commands.

POSITION(data-value)
Begins the retrieval process with 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 begin the retrieval process with the fifth resource table record in a result set, you would specify POSITION(5).

Note:
Start of change
When the POSITION option is used with the DETAIL option to retrieve source records for a specific summarized result set record, the value of the COUNT option is forced to one (1). In this case, the value returned by the COUNT option is the number of source records summarized in the specified result set record.
End of change
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.
STATUS
Retrieves only the OBJSTAT status information for the last action performed against the resource table. The records do not contain any resource table data.
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.

Conditions

The following is a list of the RESPONSE values that can be returned by the FETCH command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.

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.
WARNING
The command completed processing with a warning, for the following reason:
AREATOOSMALL
The INTO buffer is not long enough to hold the number of records requested and available.
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:
  • COUNT
  • FILTER
  • INTO
  • LENGTH
  • NOTFILTER
  • POSITION
  • RESULT
  • THREAD
  • CICSNAME
Check the command description for valid parameter syntax.
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 is connected 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.
[[ Contents Previous Page | Next Page Index ]]