Return and Reason Codes

When the system returns control to your program:

GPR 15 (and RETCODE, if specified) contains a return code.
If the return code is not zero, GPR 0 (and RSNCODE, if specified) contains a reason code.

Note: The return and reason codes will also be put into the answer area (mapped by IXLYCAA), if there is one, when the request completes.

The IXLYCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:

0: IXLRETCODEOK
4: IXLRETCODEWARNING
8: IXLRETCODEPARMERROR
C: IXLRETCODEENVERROR
10: IXLRETCODECOMPERROR

The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.

Table 1. Return and Reason Codes for the IXLCACHE REQUEST=WRITE_DATA Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Equate Symbol Meaning and Action
0	None.	Meaning: If you specified a MODE value of ASYNCECB, ASYNCEXIT, or ASYNCTOKEN, the request has been successfully initiated. The answer area (ANSAREA) fields will not contain valid information until the asynchronous processing has completed. For any other MODE value, the request has successfully completed. Action: If you specified MODE=ASYNCECB, wait on the ECB you specified in REQECB. If you specified MODE=ASYNCEXIT, the connection's complete exit will be given control when the request has completed. If you specified MODE=ASYNCTOKEN, use REQTOKEN when calling IXLFCOMP to determine when the request has completed.
4	xxxx0402	Equate Symbol: IXLRSNCODEASYNCH Meaning: The request could not be processed synchronously. It will be processed asynchronously. The answer area (ANSAREA) fields will not contain valid information until the asynchronous processing has completed. If you specified MODE=SYNCECB, the ECB specified in REQECB will be posted when the request has finished. If you specified MODE=SYNCEXIT, the connection's complete exit will be given control when the request has finished. If you specified MODE=SYNCTOKEN, the REQTOKEN contains an asynchronous request token that may be used on the IXLFCOMP macro to determine when the request has completed. Action: If you specified MODE=SYNCECB, wait on the ECB you specified in REQECB. If you specified MODE=SYNCEXIT, the connection's completion exit will be given control when the request has completed. If you specified MODE=SYNCTOKEN, use REQTOKEN when calling IXLFCOMP to determine when the request has completed.
4	xxxx042C	Equate Symbol: IxlRsnCodeLocalRegWrtSuppress Meaning: For a WRITE_DATA request with WHENREG=NO, ASSIGN=NO, LOCALREGCNTL=YES and CHANGED=YES specified, the user's connection was the only registered interest in the directory entry for NAME in the cache structure, and no subsystem data for the directory entry is cached. The write operation is suppressed. No data was written for the data item. Action: When the subsystem data is not written to the cache structure, the local cache buffer contains the only valid copy of the subsystem data. Hardening of the subsystem data to permanent storage should be performed to ensure availability and successful recovery of data in the event of a failure.
8	xxxx0801	Equate Symbol: IXLRSNCODEBADPARMLIST Meaning: The parameter list (mfctrl) for this request is not addressable. The answer area (ANSAREA) fields are not valid. Action: Verify the parameter list address. The parameter list must be addressable in the caller's primary address space or from the caller's PASN access list. If you are issuing this macro while disabled, the parameter list must reside in either page-fixed or DREF storage. If you are issuing this macro in AR-mode and you specified the parameter list address using explicit register notation, the corresponding access register must be updated appropriately. If you are issuing this macro in AR-mode, SYSSTATE ASCENV=AR must be issued before this macro.
8	xxxx0804	Equate Symbol: IXLRSNCODEBADVERSION# Meaning: The version number in the macro parameter list is not compatible with the level of XES currently being used. The answer area (ANSAREA) fields are not valid. Action: Verify that your program did not overlay the parameter list storage. Verify that your program was assembled with the correct macro library for the release of MVS™ on which your program is running. Verify that your program is running on an MVS system that supports the version of the macro you are using.
8	xxxx080A	Equate Symbol: IXLRSNCODEBADCONTOKEN Meaning: Program error. The specified connect token (CONTOKEN) was not valid for one of the following reasons: The user with the connection identifier represented by the token has disconnected from the structure. The connector's task (the task that issued IXLCONN) ended. The specified token is not the token that was returned from IXLCONN. The request was issued from an address space other than the address space in which IXLCONN was issued. The connect token was invalidated during rebuild. The connect token was invalidated by XES. Note: The answer area (ANSAREA) fields are not valid. Action: Verify that the CONTOKEN value specified was valid and for the correct structure. The numbers on the following actions correspond to the numbers above. Discontinue use. Perform recovery and cleanup for the structure and check protocol for use of structure to determine why you did not know of the disconnection. Discontinue use. Perform recovery and cleanup for the structure and check protocol for use of structure to determine why you did not know that the task ended. Issue IXLCONN to connect to the structure. The contoken is returned in the CONACONTOKEN field of the answer area specified on the IXLCONN request. Issue your request from the same address space the IXLCONN was issued. Participate in the rebuild. When it is complete, try again. Discontinue use. Perform recovery and cleanup for the structure and check protocol for use of structure. You may want to issue IXCQUERY to get more information about the structure.
8	xxxx0819	Equate Symbol: IXLRSNCODEBADVECTOROP Meaning: The VECTORINDEX specified is not valid. Request processing was suppressed. Action: Specify a vector index that is within the current range of the number of vector entries for the local vector requested for this structure. The number of vector entries is determined by the VECTORLEN parameter specified on the IXLCONN macro and may be changed by issuing the IXLVECTR macro.
8	xxxx0824	Equate Symbol: IXLRSNCODEWRONGSTRTYPE Meaning: The connect token specified by CONTOKEN is not to a cache structure. Action: Verify the connect token for this cache structure. Note: The connect token can be found in the IXLCONN answer area. Verify the value specified on the TYPE= parameter of the IXLCONN request for this structure.
8	xxxx0825	Equate Symbol: IXLRSNCODENOENTRY Meaning: Program error. The request with WHENREG=YES specified failed for one of the following reasons: The entry designated by name is not in the cache structure. The user's connection did not have registered interest in the entry. With CFLEVEL=2, if VECTORINDEX was specified, the vector index did not match the vector index with which the user currently has a registered interest in the data item. The currently-registered vector index is returned in the cache answer area (field CAALCVINUM, which is valid only if CAALCVI is set on). The request with WHENREG=NO,ASSIGN=NO specified resulted in the suppression of the creation of a new data entry because the entry did not previously exist. (CFLEVEL=9 or higher) Action: If this is expected, then your copy of the entry is invalid and you must get the latest copy. Re-read the data item into your local cache buffer and apply your changes again. Then try the write again. If this is unexpected, try the following: Verify that NAME is uncorrupted. Verify that the CONTOKEN is for the correct structure. Verify that the VECTORINDEX is the same as that for which you have previously registered interest in the entry. You might want to rerun the request with WHENREG=NO to allocate a directory entry for this NAME.
8	xxxx0826	Equate Symbol: IXLRSNCODEINCOMPATSTATE Meaning: Program error. The request failed because the state of the named data item is incompatible with the request. The following fields are returned in the answer area: CAACHANGED CAAINVLCVINUM (if WHENREG=NO was specified) CAACOLOCKSTATE CAACOLOCKVAL Action: Check for the following conditions: GETCOLOCK was specified for an entry that contains changed data (see CAACHANGED, CAACOLOCKSTATE, and CAACOLOCKVAL to determine if this is the case). WHENREG=NO was specified and there is registered interest in the data item specified by NAME (see CAAINVLCVINUM).
8	xxxx082D	Equate Symbol: IXLRSNCODEBADSTGCLASS Meaning: Program error. The storage class specified by STGCLASS exceeds the maximum number of storage classes defined for the cache structure. Action: The number of storage classes allowed for a structure are defined on the IXLCONN macro by the NUMSTGCLASS parameter. Correct the STGCLASS parameter to specify a valid storage class.
8	xxxx082E	Equate Symbol: IXLRSNCODEBADCOCLASS Meaning: Program error. The cast-out class specified by COCLASS exceeds the maximum number of cast-out classes defined for the cache structure. Action: Correct the COCLASS parameter to specify a valid cast-out class. The valid range for COCLASS is from 1 to the maximum value specified by the NUMCOCLASS parameter on the IXLCONN macro.
8	xxxx082F	Equate Symbol: IXLRSNCODEBADPARITY Meaning: Program error. The parity value specified by PARITY is not valid. Action: The value specified in the request contained parity bits that were not valid. The value for the parity bits may be 00, 01, or 11 in bits 2 and 3 of the PARITY specification (xxpp xxxx where pp is the parity bits). See the explanation for the PARITY keyword in this topic.
8	xxxx0833	Equate Symbol: IXLRSNCODEBADPGBLATTR Meaning: Program error. The storage area specified by BUFFER, or one of the buffers in the BUFLIST list is specified as being pageable (PAGEABLE=YES) but is not. Action: Change the buffer area(s) to pageable storage, or specify PAGEABLE=NO. See the PAGEABLE parameter description for specification instructions.
8	xxxx0834	Equate Symbol: IXLRSNCODEBADNONPGBLATTR Meaning: Program error. The storage area specified by BUFFER, or one of the buffers in the BUFLIST list is specified as being nonpageable (PAGEABLE=NO) but is either pageable or not addressable. Action: Ensure that: The type of storage in the buffer area corresponds to the value you specified on the PAGEABLE parameter. See the PAGEABLE parameter description for specification instructions. The correct buffer address was used. The buffer area(s) were not previously freed. If BUFLIST was specified and your program is running in AR mode, ensure that: The BUFALET specification is correct. You specified SYSSTATE ASCENV=AR before issuing the macro. If the caller is running in AR-mode and the BUFFER or BUFLIST parameter was specified using explicit register notation, the corresponding access register was updated appropriately.
8	xxxx0835	Equate Symbol: IXLRSNCODEBADDATAADDR Meaning: Program error. The storage area specified by BUFFER, or one of the buffers in the BUFLIST list, is not addressable. Action: Ensure that: The correct buffer address was used for BUFFER or for a buffer within the BUFLIST. The buffer area(s) were not previously freed. The buffer area(s) were allocated in a storage key that matches the key specified using the BUFSTGKEY parameter, or, if BUFSTGKEY is omitted, the caller's PSW key. If the caller is running in AR-mode and the BUFFER or BUFLIST parameter was specified using explicit register notation, the corresponding access register was updated appropriately. If the caller is running in AR-mode, SYSSTATE ASCENV=AR must be specified before issuing this macro. If BUFLIST was specified and your program is running in AR mode the BUFALET specification is correct.
8	xxxx0836	Equate Symbol: IXLRSNCODEBADREALADDR Meaning: Program error. Real storage addresses were provided in a BUFLIST list, but one of the buffers is not addressable in central storage. Action: Verify that BUFADDRTYPE was specified as you intended. Ensure that the real buffer addresses specified by BUFLIST are valid.
8	xxxx0837	Equate Symbol: IXLRSNCODEBADWRITEADJDATA Meaning: Program error. The request specified that adjunct data was to be written, but the area specified by ADJAREA is not addressable. There was no change to the structure. Action: Verify the ADJAREA address. ADJAREA must be addressable in the caller's primary address space or from the caller's PASN access list. If you are calling IXLCACHE while disabled, ADJAREA must reside in either page-fixed or DREF storage. If you are calling IXLCACHE in AR-mode and you specified the ADJAREA address using explicit register notation, the corresponding access register must be updated appropriately. If you are calling IXLCACHE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLCACHE macro.
8	xxxx0838	Equate Symbol: IXLRSNCODEBADANSAREA Meaning: Program error. The storage area specified by ANSAREA is not addressable. Action: Verify the ANSAREA address. ANSAREA must be addressable in the caller's primary address space or from the caller's PASN access list. If you are calling IXLCACHE while disabled, ANSAREA must reside in either page-fixed or DREF storage. If you are calling IXLCACHE in AR-mode and you specified the ANSAREA address using explicit register notation, the corresponding access register must be updated appropriately. If you are calling IXLCACHE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLCACHE macro.
8	xxxx0839	Equate Symbol: IXLRSNCODEBADREQTOKENAREA Meaning: Program error. The storage area specified by REQTOKEN is not addressable. Action: Ensure that the request token area specified by REQTOKEN is valid: Verify the REQTOKEN address. If you are calling IXLCACHE while disabled, REQTOKEN must reside in either page-fixed or DREF storage. If you are calling IXLCACHE in AR-mode and you specified the REQTOKEN address using explicit register notation, the corresponding access register must be updated appropriately. If you are calling IXLCACHE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLCACHE macro.
8	xxxx083D	Equate Symbol: IXLRSNCODEBADANSLEN Meaning: Program error. The length of the answer area, as specified by ANSLEN, is not sufficient to contain answer area information. The answer area (ANSAREA) fields do not contain valid information. Action: Increase the size of the answer area provided for the request, and rerun your program. Depending on the macro version number, specify the length of the answer area as follows: CAALEVEL0LEN indicates the level 0 mapping of the answer area. CAALEVEL1LEN indicates the level 1 mapping of the answer area. IXLCACHE macro invocations at the version 4 and higher level require an answer area length of CAALEVEL1LEN.
8	xxxx083F	Equate Symbol: IXLRSNCODEBADENTRYVERSION Meaning: Program error. The specified structure entry has a version number which does not meet the criteria specified in the request. Action: None necessary.
8	xxxx0851	Equate Symbol: IXLRSNCODENOSUSPENDISABLE Meaning: Program error. The request failed because MODE=SYNCSUSPEND was specified, but the caller is disabled and cannot be suspended. Action: Either specify another MODE value or become enabled (release the CPU lock); then reissue the request.
8	xxxx0865	Equate Symbol: IXLRSNCODEBADBUFSPEC Meaning: Program error. There is an error in the buffer specification. Action: Check the following: If BUFLIST was specified, check the requirements for BUFLIST, BUFNUM, and BUFINCRNUM. If BUFFER was specified, check the requirements for BUFFER and BUFSIZE. Buffer pointer(s) in BUFLIST. Buffer boundaries.
8	xxxx0866	Equate Symbol: IXLRSNCODEBADBUFKEY Meaning: Program error. The buffer storage key specified by BUFSTGKEY is incorrect or BUFSTGKEY was not specified and the caller's PSW key does not match the key of the buffers. The data cannot be fetched from the specified buffer area. Action: Check the following: Determine if the key of the storage being used for the buffers is different from the PSW key. If BUFSTGKEY was specified, verify that the key was put in the correct bits (see the explanation of this parameter for more information).
8	xxxx0867	Equate Symbol: IXLRSNCODEBADBUFLIST Meaning: Program error. The 128-byte storage area specified by BUFLIST is not addressable. Action: Ensure that: The correct BUFLIST address was used. The BUFLIST area was not previously freed. If the caller is running in AR-mode and the BUFLIST parameter was specified using explicit register notation, the corresponding access register was updated appropriately. If the caller is disabled, then the BUFLIST must reside in either nonpageable or disabled reference storage. If your program is running in AR mode, ensure that you specified SYSSTATE ASCENV=AR before issuing the macro.
8	xxxx086A	Equate Symbol: IXLRSNCODEBADELEMNUM Meaning: Program error. The value specified for ELEMNUM is not valid. Action: Check the element information specified on the IXLCONN for this structure. The number of elements is affected by MAXELEMNUM on IXLCONN.
8	xxxx08AD	Equate Symbol: IXLRSNCODEBADHIGHSHAREDVIRT Meaning: Program error. The request specified a high shared virtual storage area (above 2GB). Action: None required.
C	xxxx0C06	Equate Symbol: IXLRSNCODENOCONN Meaning: Environmental error. No connectivity to the cache structure exists. This may occur due to operator commands such as VARY PATH,OFFLINE or CONFIG CHP,OFFLINE or hardware errors such as facility or path failures. The CONTOKEN is invalidated. The request fails. Action: Either disconnect from the structure (using IXLDISC) or initiate a rebuild of the structure, if allowed (using IXLREBLD).
C	xxxx0C13	Equate Symbol: IXLRSNCODEREQPURGED Meaning: Environmental error. The request was purged prior to completion of the request. Possible reasons include: The connector failed. The connector disconnected. The requestor failed. The request was purged by IXLPURGE. Requests were purged when the connector provided an IXLEERSP response for the Rebuild Quiesce, Rebuild Stop, or Rebuild Cleanup event. The connector invoked IXLREBLD REQUEST=COMPLETE. The secondary address space was no longer valid. Action: None if this is expected. Otherwise, determine why the connector failed.
C	xxxx0C14	Equate Symbol: IXLRSNCODESTATUSUNKNOWN Meaning: Environmental error. The IXLCACHE request has completed, but the final disposition of the request cannot be determined. The answer area (ANSAREA) fields do not contain valid information. Action: Verify the validity of your data by comparing the expected results with what is in the coupling facility.
C	xxxx0C17	Equate Symbol: IXLRSNCODESTRFULL Meaning: Environmental error. Allocation of a directory entry and/or data entry was necessary, but was unavailable or could not be reclaimed. The answer area field, CAASTGCLFULL, contains the storage class from which the reclaiming operation failed. Action: Determine if any data items may be cast-out to make room for this item. Check your usage of storage classes to see if some data items can be moved to a different storage class (preferably with a lower priority) so some entries in the structure can be freed. Determine if a rebuild of the structure is necessary to make room for more data entries/items.
C	xxxx0C25	Equate Symbol: IXLRSNCODESTRFAILURE Meaning: Environmental error. The cache structure failed prior to completion of the request. Action: Attempt to rebuild the structure using IXLREBLD, or disconnect from the structure using IXLDISC.
C	xxxx0CA0	Equate Symbol: IXLRSNCODEQUIESCEDSUSPENDFAIL Meaning: Environmental error. The request is failed because the structure is quiesced for a system-managed process and SUSPEND=FAIL is specified on the IXLCONN. Action: None, if this is expected.
C	xxxxFFFF	Equate Symbol: IXLRSNCODENOTAVAILABLE Meaning: Environmental error. XES functions are not available. The coupling facility hardware might not be present. Action: XES may not be used when XCF is running local mode. XES requires that the coupling facility be installed.
10	xxxx10xx	Equate Symbol: IXLRSNCODECOMPERROR Meaning: System error. XES processing failure. The state of the structure and the disposition of the request are unpredictable. The answer area (ANSAREA) fields do not contain valid information. Action: Save the reason code information, and contact the IBM® support center.