FETCH

Description

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 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)

Specifies 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.

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

Retrieves 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 Developing CICSPlex SM applications. For a description of the GROUP command, which creates summarized result sets, see GROUP.

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 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 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 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 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: 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.

QUERYERROR

Indicates that this request is to return MASQRYER resources generated by the last GET, PERFORM, or SET command to act on the result set.

Note: The data selection options FILTER, NOFILTER, MARKED, NOTMARKED, and CICSNAME are ignored if you specify the QUERYERROR option.

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