DATA/FETCH

Description

This command retrieves records from the result set identified by the stub value returned to your client application in response to a DATA/GET or DATA/FETCH command.

The contents of the records selected from result set are contained in additional records in the data interface response, following the response header record (see Figure 1 for an illustration of an HTTP response package). Each data record encodes a single result set record, in the order that they appeared in the result set, starting from the record specified by the POSITION= option in the DATA/FETCH request.

Each result set record is described as a series for attribute-value pairs. The attribute name corresponds to the attribute name in the CICSPlex System Manager Resource Tables Reference and the value is represented as described above. The order that theses attributes appear in a particular result set record is undefined and the client application has to search for specific attributes by attribute name. If the FIELDS= option is specified, the DATA/FETCH command returns only the attributes named by the FIELDS= option, in the order specified by the client. If the FIELDS= option is not specified, all attributes of the resource will be returned and the order that these attributes appear in a particular result set record is undefined. In this case, the client application must search for specific attributes in each record by attribute name.

If a requested attribute on a DATA/GET request is not valid for the release of CICS® from which the result set is created, the attribute is not included in the data interface record.

When your client application is finished with a result set, it can use the DATA/DISCARD command with the correct STUB value to discard it.

Options

COUNT=value

Specifies the number of records you want the server to return to your client application from the results set. If you omit this option, the server returns all the records, which could have an adverse affect on performance if the results set is large. The number of records for the result set is in the COUNT header field returned from the DATA/GET command.

FIELDS=attribute list

Specifies one or more attributes of the resource type that are to be retrieved by this DATA/FETCH request. Each record in the response contains only the attributes required and those attributes appear in the order specified by the FIELDS= option.

The list of attributes must be separated by a comma and terminated with a period. There must be no white space characters between the attribute names and the separating commas or period. Any characters in the FIELDS= value that appear after the period will be ignored.

For example, to request that only the originating CICS name, the transaction ID, and enable status attributes be retrieved for each local transaction (LOCTRAN) record, specify:

FIELDS=EYU_CICSNAME,TRANID,STATUS.

If an attribute name is repeated in the list, the attribute will be repeated in the response records. However, the total number of attributes specified in the attribute list must not exceed the number of attributes defined for the resource type.

If the attribute list is not formatted correctly, contains too many attributes, or contains an unknown attribute name, the DATA/FETCH command RESPONSE header will contain INVALIDPARM and the REASON header will contain FIELDS. No data records will be returned.

If the FIELDS= option is not specified, the response will contain all the attributes of each record in an undefined order.

Note: The FIELDS= option is only supported when the INTERFACELEVEL header returned on the DATA/CONNECT command is greater than or equal to 1. If a client attempts to use the FIELDS= option on an earlier support level of the data interface, the option is ignored.

POSITION={1∨value}

Specifies the record number in the result set of the first record to be retrieved by this fetch command. The default number is 1, which indexes the first record in the result set.

STUB=value

Specifies the result set from which you want the server to return records. The value you specify must be obtained from the result of one of the the following commands:

• The stub value returned from the GET command that created the result set
• The stub value returned from a previous FETCH command.

Note: Your client application can use a stub value received from Web User Interface server once only. Once you specify a stub value on a request to a Web User Interface server, you cannot use the same value again, but must use the next stub returned for the result set. For example, when you specify a stub value on a DATA/FETCH command, the response from the server includes a new stub to enable you to retrieve more records from the set.

STATUS values

BADCOMMAND

The command passed to the data interface by the Web User Interface is not recognized.

BADSTUB

The stub value is not valid for the request. This could be for one of the following reasons:

• You have have specified a stub value that does not belong to the user session on which you have issued the command.
• The stub value is out of sequence.

BUSYSTUB

The Web User Interface server is still processing a previous request for this stub.

CMASGONE

The Web User Interface has lost its connection with the CMAS. As a result, the client application's user session is terminated.