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.
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:
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.
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.
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.
To identify which API operation the FEEDBACK record applies to, check the values in these fields:
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:
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.
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.
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.
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:
FEEDBACK records are also not available in these situations:
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.
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.
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.
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:
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.
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:
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.
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:
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.
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:
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.
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.
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.
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.
The BINSTERR error result set referenced by TOKENE, and shown in Figure 21 is accessed using a FETCH command.
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 ]]