Retrieving FEEDBACK records

In addition to the specific values returned by a command’s RESPONSE and REASON options, CICSPlex® SM also provides diagnostic data in the form of FEEDBACK resource table records. This data can help you evaluate the results of an API command, especially if the command did not complete successfully.

Using the FEEDBACK command

You can retrieve diagnostic data about a previously issued API command by issuing the FEEDBACK command. The type of command for which you want diagnostic data affects how you specify the FEEDBACK command and where the data is placed:

A command that processed a result set
Use the RESULT option of the FEEDBACK command to retrieve data about the last command that processed a specific result set.

If the command that processed the result set returned a RESPONSE 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. You can use the FIRST, NEXT, and COUNT options of the FEEDBACK command to retrieve multiple FEEDBACK records.

The diagnostic data in a result set 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:
No FEEDBACK records are produced if the command that processed the result set returned a RESPONSE of OK.
A command that did not process a result set
Use the FEEDBACK command without the RESULT option to retrieve data about the command issued immediately before FEEDBACK.

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.

Evaluating a FEEDBACK record

The diagnostic data for a CICSPlex SM API command is presented in a FEEDBACK resource table record. The attributes of that resource table provide a variety of information about the completion status of an API command.

Note:
This section provides general information about FEEDBACK records. The FEEDBACK resource table copy book that is supplied by CICSPlex SM provides a detailed description of the contents and structure of a FEEDBACK record. You should refer to the CICSPlex System Manager Resource Tables Reference or the supplied copy book when writing a program that uses the FEEDBACK command.

To identify which API operation the FEEDBACK record applies to, check the values in these fields:

COMMAND
A numeric code that identifies the command to which this FEEDBACK record applies. The API commands and their numeric equivalents are given in Table 8.
OBJECT
The CICSPlex SM object that the command was issued against.
OBJECT_ACT
The action that was being performed against the CICSPlex SM object.
RSLTRECID
If the FEEDBACK record applies to a result set, the numeric ID of the result set record associated with this FEEDBACK record.
Table 8. Numeric codes and API commands
Numeric code Mnemonic Command
02 CANCEL Cancel
03 CONNECT Connect
04 COPY Copy
05 CREATE Create
06 DELETE Delete
07 DISCARD Discard
08 DISCONN Disconnect
09 FETCH Fetch
10 GET Get
11 LOCATE Locate
12 MARK Mark
13 ORDER Order
14 PERFSET Perform Set
15 PERFOBJ Perform Object
16 QUALIFY Qualify
17 QUERY Query
18 RECEIVE Receive
19 REMOVE Remove
20 FILTER Specify Filter
21 UNMARK Unmark
22 ADDRESS Address
23 GETDEF Getdef
24 LISTEN Listen
25 REFRESH Refresh
26 SET Set
27 VIEW Specify View
28 TERM Terminate
29 TRANS Translate
30 GROUP Group by
31 UPDATE Update

To determine what type of problem the FEEDBACK record describes, check the values in these fields:

ATTRDATAVAL
Indicates whether attribute data is available for the command. Attribute data is included only if the command itself did not complete successfully.

If the ATTRDATAVAL value is Y, the FEEDBACK record identifies as many as five attributes (ATTR_NM1 through ATTR_NM5) that contributed to the error. Each attribute is identified by its name and its offset and relative number within the resource table record. The data type and length of each attribute is also included.

If the ATTRDATAVAL value is N, you can ignore the ATTR_ fields.

CEIBDATAVAL
Indicates whether CICS® EIB data is available for the command. EIB data is included only if the command encountered a CICS error.

If the CEIBDATAVAL value is Y, the FEEDBACK record includes the EIBFN, RESP, and RESP2 values as provided by CICS. Note that if the RESP value indicates a NOTAUTH condition that was raised due to CICSPlex SM simulated security, EIBFN is not set.

If the CEIBDATAVAL value is N, you can ignore the CEIBFN, CEIBRESP, and CEIBRESP1 fields.

ERRCODEVAL
Indicates whether a CICSPlex SM error code is available for the command. An error code is included only if the command itself did not complete successfully.

If the ERRCODEVAL value is Y, the FEEDBACK record includes a numeric ERROR_CODE value. Each resource table copy book includes a list of the error codes for that object and their meanings.

If the ERRCODEVAL value is N, you can ignore the ERROR_CODE field, as well as the RESPONSE and REASON fields.

For some API operations that affect BAS resources, the FEEDBACK record may point to additional diagnostic data in an error result set. For more information about using the diagnostic data in error result sets, see Additional processing for BAS.

Availability of FEEDBACK records

In general, FEEDBACK records are produced for all API commands, whether they are successful or not. However, for some API commands and in some situations, FEEDBACK records are not produced because they would not provide useful diagnostic data.

FEEDBACK records are not available for these commands:

DISCONNECT and TERMINATE
When you disconnect an API processing thread from CICSPlex SM, any remaining diagnostic data is discarded.
FEEDBACK
The FEEDBACK command cannot report on its own processing.
TBUILD and TPARSE
These REXX-specific commands issue a series of API commands internally and reuse the same feedback area. Therefore, the feedback area cannot represent the entire sequence of events.

FEEDBACK records are also not available in these situations:

An example of FEEDBACK for a result set

As an example of how you can use FEEDBACK data, Figure 17 illustrates the results of issuing a SET command. In this case, SET was issued to modify the service status of CONNECT records in the result set referenced by TOKENC.

Figure 17. Using SET to modify result set records
 This figure illustrates the results of issuing the SET command SET MODIFY ('SERVICESTATUS=OUTSERVICE.') RESULT(TOKENC)...

One of the connections (C002 in MAS1B) was not successfully taken out of service by the SET command. The ServStatus field is still set to INSERVICE and there is a pointer to FEEDBACK data.

Figure 18 shows how you can use the FEEDBACK command to retrieve the FEEDBACK records associated with the result set referenced by TOKENC.

Figure 18. Using FEEDBACK to retrieve diagnostic data for a result set
 This figure illustrates the use of the command FEEDBACK RESULT(TOKENC) INTO(AREA5)... to retrieve diagnostic data for a result set.

The FEEDBACK record shown in Figure 18 reveals the cause of the problem. CICSPlex SM returned RESPONSE and REASON values of TABLEERROR DATAERROR, which means the value associated with one or more resource table attributes is invalid. Furthermore, CICS responded to the SET request for this connection with RESP(16) RESP2(2). A check of the CICS response codes indicates that the attempt to take the connection out of service was invalid because the connection is currently acquired.

Note:
The LASTOPER and STATUS attributes of the OBJSTAT resource table and some of the FEEDBACK attributes are actually binary fields (that is, they are represented by a bit being set on or off). For detailed information about the attribute values for a given resource table, refer to the CICSPlex System Manager Resource Tables Reference or the supplied copy books.

Additional processing for BAS

For API operations that affect BAS resources, the diagnostic data in a FEEDBACK record may not be enough to fully describe an error condition. In these cases, the FEEDBACK record points to an error result set. An error result set is identified by the following fields:

ERR_RESULT
A 4-byte token identifying an error result set.
ERR_COUNT
The number of records in the error result set referenced by ERR_RESULT.
ERR_OBJECT
The type of records in the error result set referenced by ERR_RESULT. This value is the 1- to 8-character name of a CICSPlex SM resource table, and may be BINSTERR, BINCONRS, BINCONSC, or FEEDBACK.
Note:
For details of the BINSTERR, BINCONRS, and BINCONSC resource tables, see the CICSPlex System Manager Resource Tables Reference.

Evaluating error result set records

If the ERR_OBJECT field of the FEEDBACK record contains FEEDBACK, the error result set contains errors that arose when CICSPlex SM attempted to update CICS resources. In response to the API command:

    UPDATE RESULT(token) MODIFY(string)

CICSPlex SM tries to update multiple CICS definition records in a result set according to the supplied modification string. For each CICS definition that could not be modified, an error record is created in the error result set. The RESPONSE and REASON values returned are TABLEERROR and DATAERROR.

The records are standard FEEDBACK records. To access the error result records, use the FEEDBACK command to retrieve diagnostic data about each of the CICS definitions in the ERR_RESULT result set. The ERR_COUNT value in the original FEEDBACK record for the UPDATE command indicates how many records are in the ERR_RESULT result set and therefore the number of times you should issue the FEEDBACK command against the ERR_RESULT result set.

Evaluating BINSTERR resource table records

If the ERR_OBJECT field of the FEEDBACK record contains BINSTERR, errors were encountered while CICS resources were being installed. In response to one of the following API commands:

    PERFORM OBJECT ACTION(INSTALL)
    PERFORM SET ACTION(INSTALL)

CICSPlex SM tries to install CICS resources in one or more active systems running CICS/ESA 4.1 or later. A BINSTERR record is created for each CICS resource that cannot be installed. The RESPONSE and REASON values returned are TABLEERROR and DATAERROR.

The BINSTERR records that you receive contain the following information:

CMASNAME
The 1- to 8-character name of a CMAS that manages the specified CICSplex.
PLEXNAME
The 1- to 8-character name of the CICSplex to which the specified CICS system belongs.
CICSNAME
The 1- to 8-character name of the CICS system into which the resource could not be installed.
RESNAME
The name of the CICS resource that could not be installed.
RESVER
The version of the CICS definition that represents the resource being installed.
ERRCODE
A numeric CICSPlex SM error code. See BINSTERR. The BINSTERR resource table copy book also contains a list of the error codes and their meanings.
CRESP1
The RESP value as returned by CICS.
CRESP2
The RESP2 value as returned by CICS.
CEIBFN
The EIBFN value as returned by CICS.

To access the error result set records, use the FETCH command to retrieve the BINSTERR records from the ERR_RESULT result set. The ERR_COUNT value in the FEEDBACK record for the PERFORM command indicates how many records are in the ERR_RESULT result set and therefore the number of times you should issue the FETCH command against the ERR_RESULT result set.

Evaluating BINCONRS resource table records

If the ERR_OBJECT field of the FEEDBACK record contains BINCONRS, inconsistent resource set errors were encountered when attempting to update or create the specified definition. In response to one of the following API commands:

    CREATE OBJECT(basdef)
    UPDATE OBJECT(basdef)

CICSPlex SM tries to create or update one of the following Business Application Services definitions:

A BINCONRS resource table record is created for each CICS definition that would cause an inconsistent set error. The RESPONSE and REASON values returned are TABLEERROR and DATAERROR.

The BINCONRS records that you receive contain the following information:

CMASNAME
The 1- to 8-character name of a CMAS that manages the specified CICSplex.
PLEXNAME
The 1- to 8-character name of the CICSplex to which the specified CICS system belongs.
CICSNAME
The 1- to 8-character name of the CICS system that experienced inconsistent resource set errors.
RESTYPE
The type of CICS resource.
ERROP
A numeric value that identifies the operation being performed when the error occurred (such as updating a RASGNDEF). See BINCONRS. The BINCONRS resource table copy book also contains a list of the ERROP values and their meanings.
CANDNAME
The name of the candidate resource
CANDVER
The version of the candidate resource
CANDRGRP
The group of the candidate resource
CANDRASG
The assignment of the candidate resource
CANDRDSC
The description of the candidate resource
CANDUSAGE
The candidate assignment usage
CANDSGRP
The candidate system group
CANDTYPE
The candidate system type
CANDASGOVR
The candidate assignment override
EXISTNAME
The name of the existing resource
EXISTVER
The version of the existing resource
EXISTRGRP
The group of the existing resource
EXISTRASG
The assignment of the existing resource
EXISTRDSC
The description of the existing resource
EXISTUSAGE
The existing assignment usage
EXISTSGRP
The existing system group
EXISTTYPE
The existing system type
EXISTASGOVR
The existing assignment override

To access the error result records, use the FETCH command to retrieve the BINCONRS records from the ERR_RESULT result set. The ERR_COUNT value in the FEEDBACK record for the CREATE or UPDATE command indicates how many records are in the ERR_RESULT result set and therefore the number of times you should issue the FETCH command against the ERR_RESULT result set.

Evaluating BINCONSC resource table records

If the ERR_OBJECT field contains BINCONSC, inconsistent scope errors were encountered while attempting to update or create the specified definition. In response to one of the following API commands:

    CREATE OBJECT(basdef)
    UPDATE OBJECT(basdef)

CICSPlex SM tries to create or update one of the following Business Application Services definitions:

A BINCONSC resource table record is created for each CICS definition that would cause an inconsistent scope error. The RESPONSE and REASON values returned are TABLEERROR and DATAERROR.

BINCONSC records contain the following information:

CMASNAME
The 1- to 8-character name of a CMAS that manages the specified CICSplex.
PLEXNAME
The 1- to 8-character name of the CICSplex to which the specified CICS system belongs.
CICSNAME
The 1- to 8-character name of the CICS system that experienced inconsistent scope errors.
ERROP
A numeric value that identifies the operation being performed when the error occurred (such as updating a RASGNDEF). See BINCONSC. The BINCONSC resource table copy book also contains a list of the ERROP values and their meanings.
ERRCODE
A numeric CICSPlex SM error code. See BINCONSC. The BINCONSC resource table copy book contains a list of the error codes and their meanings.
TARGSCOPE
The name of the target scope
TARGRASG
The assignment for the target scope
TARGRDSC
The description for the target
RELSCOPE
The name of the related scope
RELRASG
The assignment for the related scope
RELRDSC
The description for the related scope

To access the error result records, use the FETCH command to retrieve the BINCONSC records from the ERR_RESULT result set. The ERR_COUNT value in the FEEDBACK record for the CREATE or UPDATE command indicates how many records are in the ERR_RESULT result set and therefore the number of times you should issue the FETCH command against the ERR_RESULT result set.

An example of a BAS error result set

As an example of how you can the FEEDBACK data to obtain BAS error result set information, Figure 19 illustrates the results of issuing a PERFORM OBJECT command. In this case, PERFORM OBJECT ACTION(INSTALL) was issued to install the CONNDEF definitions in the result set referenced by TOKENC.

Figure 19. Using PERFORM OBJECT to install BAS definitions
 This figure illustrates the results of issuing the PERFORM command PERFORM OBJECT ACTION(INSTALL) RESULT (TOKENC)

One of the connection definitions (CON02,VTAM®) was not successfully installed by the PERFORM OBJECT command. There is a pointer to the FEEDBACK data.

Figure 20 shows how you can use the FEEDBACK command to retrieve the FEEDBACK records associated with the result set referenced by TOKENC.

Figure 20. Using FEEDBACK to retrieve diagnostic data for a result set
 This figure illustrates the results of issuing the FEEDBACK command FEEDBACK RESULT(TOKENC) INTO (AREA5)...

The FEEDBACK data shown in Figure 20 reveals the cause of the problem. CICSPlex SM returned RESPONSE and REASON values of TABLEERROR DATAERROR, which means that one or more connection definitions did not install successfully. Furthermore, the ERR_RESULT attribute points to an error result set which contains a single BINSTERR resource table record.

Figure 21. BINSTERR error result set
 This figure illustrates the BINSTERR resource table record.

The BINSTERR error result set referenced by TOKENE, and shown in Figure 21 is accessed using a FETCH command.

Figure 22. Using FETCH to retrieve BINSTERR records
 This figure illustrates the use of the FETCH command FETCH RESULT(TOKENE) INTO (AREA5)... to retrieve BINSTERR records.

Figure 22 shows how you can use the FETCH command to retrieve the BINSTERR records associated with the error result set referenced by TOKENE.

[[ Contents Previous Page | Next Page Index ]]