FEEDBACK

Retrieve diagnostic data.

Description

This command retrieves diagnostic data about a previously issued API command.

The diagnostic data is returned as FEEDBACK resource table records.
If the previous command involved processing a result set and it returned a RESPONSE value other than OK, a FEEDBACK resource table record is appended to the end of each resource table record in the result set that had an error associated with it causing the non-OK RESPONSE to be sent. The diagnostic data is available to the FEEDBACK command until another command processes the same result set. At that point, the data is replaced with FEEDBACK records for the subsequent command.
Note: If a command that processed a result set returned a RESPONSE value of OK, FEEDBACK records are produced if CICS returns additional information in the EIBRESP2 field.
If the previous command did not process a result set, the FEEDBACK resource table records are returned in a separate feedback area. The records in that feedback area are cleared and refreshed for each command that is not result set-oriented. So for commands that place their diagnostic data in the feedback area rather than in a result set, FEEDBACK can retrieve data only for the most recently issued command.
Once you have issued the FEEDBACK command to retrieve diagnostic data for a command, the feedback record or area is cleared. You cannot request the same FEEDBACK resource table records more than once.
If a command is processed asynchronously (that is, you specify the NOWAIT option) the diagnostic data for that command is returned in the ASYNCREQ notification resource table. No FEEDBACK resource table records are produced for an asynchronous request.
Diagnostic data is not available for these commands:
- DISCONNECT
- FEEDBACK
- TERMINATE
The TBUILD and TPARSE commands supplied for use in REXX programs do not provide any useful FEEDBACK information.

For a complete description of the FEEDBACK resource table, see FEEDBACK Resource Table.

Options

COUNT(data-ref)

Specifies the number of feedback records to be retrieved from the result set named in the RESULT option. If you do not specify the COUNT option, only one feedback record is retrieved.

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

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

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.

FIRST

Retrieves the first feedback record from the result set named in the RESULT option.

If you specify the COUNT option, FIRST retrieves the specified number of records, beginning with the first record in the result set.

INTO(data-area)

Identifies a buffer (or stem variable, in REXX) to receive the feedback data. This buffer must be long enough to hold all the feedback data 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 FEEDBACK command:

OK: The actual length of the data returned in the INTO buffer.
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.

NEXT

Retrieves the next available feedback record from the result set named in the RESULT option.

If you specify the COUNT option, NEXT retrieves the specified number of records, beginning with the next record in the result set.

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 an API result set to be processed by this operation. The result set can be one produced by any of these commands:

COPY
GET
GROUP
PERFORM OBJECT.

Use the RESULT option to retrieve feedback data about a previously issued command that processed a result set. Use FEEDBACK without the RESULT option to retrieve data about the most recently issued command that did not process a result set.

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 FEEDBACK 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, or a command that processed a result set returned a RESPONSE of OK.

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.

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
INTO
LENGTH
RESULT
THREAD.

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.