Return and Reason Codes

Open Application Program Interface › TUNCALL Verbs and Keywords › Return and Reason Codes

Return and Reason Codes

All requests sent to CA Mainframe Application Tuner that use TUNCALL have two levels of responses. The first level is from TUNCALL and this return code represents any errors that occurred when sending the request to the server.The following table lists the return codes.

Return code	Description
0	TUNCALL execution was successful. The results of the STATUS command execution will be reflected in the Reason Code in Register 0 or the parameter list (see below).
4	Server was found but was inactive.
8	Server was not found or has never been started.
12	TNUCALL release did not match that of the server.
16	Request ended with a nonzero return code. The results of the command execution will be reflected in the Reason Code in Register 0 or the parameter list (see below).
24	User is not authorized to access the requested server.
28	Insufficient storage available to queue request to server.
32	Internal error occurred. Error code in Register 0 indicates the type of error. Provide this code when contacting Customer Support.
36	An abend occurred while processing request within the server.
40	Request was sent to the server, but has timed out.

If the request has been successfully sent to the server, and the request was completed with a nonzero return code, TUNCALL ends by issuing a return code of 16. This response indicates that the return code field provided in the parameter list was not zero.

In general, if TUNCALL returns anything other than a 16 in Register 15, you do not need to examine the reason code in Register 0, or the return and reason code fields that are provided in the parameter list. However, the STATUS command will return a 0 in Register 15, and the status will be indicated by a reason code in register 0 and in the reason code field in the parameter list. If TUNCALL ends with register 15 containing 16, the return code and reason code fields provided in the parameter list indicate the reason for the failure.

The following table provides a complete list of command return and reason codes.

Return code	Reason code	MONITOR command	Description
0	0	INVOKE	Command successful. Monitor Token is provided in R0 and in messages when TUNCALL is invoked with a TSO command, CLIST, Rexx Exec, or batch job. Monitor Token is provided in R0 and return area pointed to by parameter 4 when TUNCALL is invoked from within a program.
0	0	CANCEL	Command successful. Monitor is cancelled.
0	0	STATUS	Monitor is waiting.
0	4	STATUS	Monitor is active.
0	8	STATUS	Monitor is inactive.
0	12	STATUS	Monitor was cancelled.
0	16	STATUS	Monitor has completed.
0	>16	STATUS	Monitor was not found.
16	4	INVOKE	Duplicate monitor already exists.
16	8	CANCEL	Matching monitor was not found.
16	12	INVOKE	Maximum number of queued or active monitor requests have been reached. This value is set in the TUNSSPxx member with the MAXREQ keyword.
16	16	All	The user's UIF (User Information File) could not be allocated or opened by the server. A message with additional information is sent to the user by way of TPUT if this condition is raised.
16	32	All	Syntax error was detected. The message areas pointed to by the parameter list contain detailed information on the nature of the syntax error.
16	Not listed above	All	A general failure of TUNCALL occurred. Review the messages returned in the message areas that are provided for detailed information regarding the failure.
24	NA	All	The user is not permitted access to the function requested.
28	NA	All	The server did not have enough storage to process request.
32	NA	All	An internal error occurred. Review messages that are provided in the areas passed in the parameter list for more information.
36	NA	All	An abend occurred while processing a request. A small indicative dump is provided by CA MAT. This indicative dump is written out to SYSLOG.
52	NA	All	When sending the request to a specific system within the sysplex, no matching systems were found.
56	NA	All	The request was queued when the system was being shut down and the request is not honored.

Assembler Example:

The following figure shows an example of TUNCALL being used from assembler coding.

...
LA      R14,=F'1'               Parameter List Type
LA      R15,CMD         Point to command.
LA      R0,CMDL         Point to command length.
LA      R1,RETOKEN              Point to area to receive token.
LA      R2,MSGS         Point to message areas.
LA      R3,OIRC         Point to return code area.
LA      R4,OIRS         Point to reason code area.
STM     R14,R4,PLIST    Save parameter list.
OI      PLIST+24,X'80'  Mark end of Parameter list.
LA      R1,PLIST        Point to start.
LINK    EP=TUNCALL      Invoke TUNCALL.
LTR     R15,R15         Worked ok?
BZ      CONT1           Yes, no need to check further.
CH      R15,=H'16'      Request accepted by CA MAT?
BE      REQFAIL         Yes, see why it failed in server.
        Request did not make it to Server.  Indicate why.
        Check return code in R15.

B       CONT2

        Request went to server but failed. Determine why.
REQFAIL DC      0H'0'

        MVC     WTOL+4(112),MSG1   Copy message one to WTO area
        WTO   mf=(E,WTOL)          Issue message in return area 1.
        MVC     WTOL+4(112),MSG2   Copy message two to WTO area.
        WTO   mf=(E,WTOL)          Issue message in return area 2.
        B       CONT2              Continue processing.
CMD             DC      C'MONITOR INVOKE PROFILE(PAYPROD)'
CMDL            DC      A(L'CMD)
RETOKEN DC      CL16' '
MSGS            DC      0CL224' '
MSG1            DC      CL112' '
MSG2            DC      CL112' '
OIRC            DC      F'0'
OIRS            DC      F'0'
PLIST           DC      7A(0)
WTOL    WTO   '                                        ',MF=L
...

Tell Technical Publications how we can improve this information