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 IXLYLAA), 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 IXLLSTE Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Equate Symbol Meaning and Action
0	None.	Meaning: If you specified a MODE value of ASYNCECB, ASYNCEXIT, ASYNCTOKEN, or ASYNCNORESPONSE, 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 MODE=SYNCECB was specified, the ECB specified for REQECB will be posted when the request has finished. If MODE=SYNCEXIT was specified, the connection's complete exit will be given control when the request has finished. If MODE=SYNCTOKEN was specified, an asynchronous request token was returned in the area specified by REQTOKEN. This request token may be specified on the IXLFCOMP macro to determine when the request has finished. Action: If you specified MODE=SYNCECB, wait on the ECB you specified in REQECB. If you specified MODE=SYNCEXIT, the connection's complete 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	xxxx040D	Equate Symbol: IXLRSNCODEBADREADADJDATA Meaning: Program error. The IXLLSTE READ, MOVE, or DELETE request specified that adjunct data was to be read, but the storage area specified by ADJAREA is not addressable. All other requested data was retrieved. If supported and requested, the entry data was retrieved. If this was a MOVE request, the entry was moved. If this was a DELETE request, the entry was deleted. 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 IXLLSTE while disabled, ADJAREA must reside in either page-fixed or DREF storage. If you are calling IXLLSTE 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 IXLLSTE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLLSTE macro. If LAALCTL is not zeros, the request completed prematurely. See the action suggested for return code X'4' reason code X'xxxx0409'. Correct the address specified by ADJAREA, and rerun the request asking for adjunct data only.
4	xxxx0410	Equate Symbol: IXLRSNCODELOCKCOND Meaning: For a LOCKOPER=HELDBY request, or a LOCKMODE=COND request, or a request that specified LOCKCOMP, the request could not be completed successfully because the specified lock is not currently held as required. The connection identifier of the lock owner is returned in the answer area (LAACONID field). Action: Retry the request, or obtain the lock as required, and retry the request. If you are unable to get the lock, check the ID in the LAACONID field and determine if some recovery is necessary.
4	xxxx0412	Equate Symbol: IXLRSNCODELOCKHELDBYSYS Meaning: For a LOCKOPER=HELDBY or LOCKMODE=COND request, or a request that specified LOCKCOMP, the request could not be completed successfully because the specified lock is not currently held as required. Action: Retry the request, or obtain the lock as required, and retry the request.
8	xxxx0801	Equate Symbol: IXLRSNCODEBADPARMLIST Meaning: Program error. The parameter list for this request is not addressable. The answer area (ANSAREA) fields are not valid. Action: Verify that: The parameter list address is uncorrupted. The parameter list is addressable in the caller's primary address space. If you are issuing this macro while disabled, the parameter list resides 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 was updated appropriately. If you are issuing this macro in AR-mode, SYSSTATE ASCENV=AR must be issued before issuing this macro.
8	xxxx0804	Equate Symbol: IXLRSNCODEBADVERSIONNUM (or 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.
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: Take the action with the corresponding meaning. Discontinue use of the structure. Perform recovery and cleanup for the structure and check the protocol for the use of the structure to determine why you did not know of the disconnection. Discontinue use of the structure. Perform recovery and cleanup for the structure and check the protocol for the use of the structure to determine why you did not know that the task ended. 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 in. Wait for the rebuild to complete, and try again. Discontinue use of the structure. Perform recovery and cleanup for the structure.
8	xxxx0824	Equate Symbol: IXLRSNCODEWRONGSTRTYPE Meaning: Program error. The connection specified by CONTOKEN is not to a list structure. Action: Specify the appropriate CONTOKEN value, and rerun your program. The CONTOKEN is returned in the answer area provided on the IXLCONN invocation. The type of structure built is passed on the TYPE parameter of the IXLCONN macro.
8	xxxx0825	Equate Symbol: IXLRSNCODENOENTRY Meaning: Program error. The designated list entry does not exist; therefore, no entries were processed. Action: None necessary. However, if this return code and reason code are unexpected, you should check the way the list entry was created. Examine the parameters specified for locating the list entry on the invocation of this macro.
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 was not previously freed. If you are calling IXLLSTE while disabled, the buffers must reside in either page-fixed or DREF storage. The buffer areas were allocated in a storage key that matches the key specified by the BUFSTGKEY parameter, or, if BUFSTGKEY is omitted, the caller's PSW key. If BUFLIST was specified and your program is running in AR-mode: If the BUFFER or BUFLIST parameter was specified using explicit register notation, the corresponding access register was updated appropriately. The BUFALET specification is correct. You specified SYSSTATE ASCENV=AR before issuing the IXLLSTE macro.
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. The buffer area was not previously freed. The buffer area was 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 BUFLIST was specified and your program is running in AR mode: The BUFALET specification is correct. You specified SYSSTATE ASCENV=AR before issuing the macro.
8	xxxx0836	Equate Symbol: IXLRSNCODEBADREALADDR Meaning: Program error. Real storage addresses were provided in the 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 buffer addresses specified by BUFLIST are valid.
8	xxxx0837	Equate Symbol: IXLRSNCODEBADWRITEADJDATA Meaning: Program error. The IXLLSTE WRITE or MOVE request specified that adjunct data was to be written, but the area specified by ADJAREA is not addressable. No entry data was written. 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 IXLLSTE while disabled, ADJAREA must reside in either page-fixed or DREF storage. If you are calling IXLLSTE 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 IXLLSTE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLLSTE macro.
8	xxxx0838	Equate Symbol: IXLRSNCODEBADANSAREA Meaning: Program error. The storage area specified by ANSAREA is not addressable. Action: Ensure that: The answer area address specified by ANSAREA is valid. If the caller is running in AR-mode and the ANSAREA parameter was specified using explicit register notation, the corresponding access register was updated appropriately. The address specified for ANSAREA is addressable in the caller's primary address space or from the caller's PASN access list. If you are calling IXLLSTE while disabled, ANSAREA must reside in either page-fixed or DREF storage. If you are calling IXLLSTE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLLSTE 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. If the caller is running in AR-mode and the REQTOKEN parameter was specified using explicit register notation, the corresponding access register was updated appropriately. If you are calling IXLLSTE while disabled, REQTOKEN must reside in either page-fixed or DREF storage. If you are calling IXLLSTE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLLSTE 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, and rerun your program. The minimum size of the ANSAREA is in the LAA_LEN field of the IXLYLAA mapping macro.
8	xxxx083E	Equate Symbol: IXLRSNCODEMAXLISTKEY Meaning: Program error. The list key to be assigned to an entry that was being created or moved was not valid. Either the list key or the list key plus the list key increment value was greater than the maximum list key. Action: Ensure that you specified a correct list key increment. Depending on the protocol you are using for assigning list key values, you might want to issue a WRITE_LCONTROLS request to update either the list key value to a lower value or the maximum list key value to a higher value.
8	xxxx083F	Equate Symbol: IXLRSNCODEBADENTRYVERSION Meaning: The entry designated by the specified list entry controls has a version number that does not meet the criteria specified by VERSCOMP and VERSCOMPTYPE. The list entry controls for the entry are returned in the answer area (field LAALCTL). Action: None necessary. However, if this return code and reason code are unexpected, you might want to verify the values specified in VERSCOMP and VERSCOMPTYPE and look at the version returned in the answer area.
8	xxxx0840	Equate Symbol: IXLRSNCODEBADENTRYLIST Meaning: The entry designated by the specified list entry controls does not reside on the list specified by LISTNUM. The list entry controls for the entry are returned in the answer area (field LAALCTL). Action: None necessary. However, if you did not expect this return and reason code, you might want to verify what list this entry is on. Maybe the entry was moved, or you designated the wrong list in LISTNUM. Check the protocol for using this list. The information returned in the LAALCTL field of the answer area contains the number of the list that this list entry is on as well as other control information.
8	xxxx0841	Equate Symbol: IXLRSNCODEBADENTRYNAME Meaning: Program error. The name specified by ENTRYNAME is not a unique name within the structure, and therefore entry creation is suppressed. Action: Be sure to provide a unique entry name when creating entries to be written to structures that support entry names.
8	xxxx0842	Equate Symbol: IXLRSNCODEPERSISTENTLOCK Meaning: Program error. The request specifying an unconditional SET or NOTHELD lock operation failed because the lock was held by a connection that is in the failed-persistent state. The connection identifier of the lock owner is returned in the answer area (field LAACONID). Action: Either perform recovery for the connection, or wait until recovery for the connection is performed.
8	xxxx0845	Equate Symbol: IXLRSNCODENONAMES Meaning: Program error. A list entry was designated by entry name, but the structure does not support entry names. Action: Ensure that you are connected to the intended structure. Ensure that the correct specification was made for REFOPTION on the IXLCONN macro. You may want to issue IXLMG to get more information about the structure.
8	xxxx0846	Equate Symbol: IXLRSNCODEBADLOCKINDEX Meaning: Program error. The specified LOCKINDEX exceeds the size of the lock table for the structure. Action: Correct LOCKINDEX to specify an index that is contained within the lock table. The maximum value for the LOCKINDEX is one less than the value specified by the LOCKENTRIES parameter on the IXLCONN macro.
8	xxxx0847	Equate Symbol: IXLRSNCODEBADLISTNUMBER Meaning: Program error. The specified LISTNUM value exceeds the number of lists for the structure. Action: Correct LISTNUM to specify a list number that exists in the structure. The number of lists allocated for a structure is determined on the LISTHEADERS parameter of the IXLCONN macro. The list numbers go from 0 to n-1, where n is the number of lists specified.
8	xxxx0848	Equate Symbol: IXLRSNCODEBADRESET Meaning: Program error. LOCKOPER=RESET was specified for a lock not currently held by the invoker. The value of the connection ID holding the lock is returned in the answer area (field LAACONID). Action: Check your code to ensure that your connection did not already reset the lock.
8	xxxx084A	Equate Symbol: IXLRSNCODENOKEYS Meaning: Program error. The structure does not support the use of entry keys. The IXLLSTE request type either required the structure to support entry keys or designated a sublist, list entry, or list position by list number and entry key. Action: Ensure that you are connected to the intended structure. The use of keys for a structure is determined by the REFOPTION keyword on the IXLCONN macro.
8	xxxx084B	Equate Symbol: IXLRSNCODENOLOCKS Meaning: Program error. A locking operation was requested, but the structure does not contain a lock table. Action: Ensure that: You are connected to the intended structure. You intended to perform a locking operation. The use of locks is determined by the LOCKENTRIES keyword on the IXLCONN macro.
8	xxxx084E	Equate Symbol: IXLRSNCODEBADMOVETOLIST Meaning: Program error. The list number specified for MOVETOLIST exceeds the number of lists defined for the structure. Action: Correct MOVETOLIST to specify a list that exists in the structure. The maximum number of lists in a structure is determined by the LISTHEADERS parameter on the IXLCONN macro.
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	xxxx0854	Equate Symbol: IXLRSNCODEBADLOCKCOMP Meaning: Program error. The connection identifier specified for LOCKCOMP is not valid. Action: The connection identifier is returned in the answer area (mapped by IXLYCONA) when the IXLCONN macro was issued.
8	xxxx0859	Equate Symbol: IXLRSNCODEBADLISTAUTH Meaning: The list authority value for the specified list does not meet the criteria specified by AUTHCOMP and AUTHCOMPTYPE. The current list authority (field LAALISTAUTH) and description (field LAALISTDESC) are returned in the answer area. Action: None required; however you might want to take some action depending on your application. The list authority is set to binary zeros when the structure is allocated. When IXLLSTE is issued with the NEWAUTH keyword, the list authority is changed if the correct comparison list authority value is specified. Check the answer area to determine the list authority value for the list specified. Verify that the correct list number was specified.
8	xxxx0864	Equate Symbol: IXLRSNCODEBADBUFSIZE Meaning: Program error. The size of the BUFFER area or the buffer areas specified by BUFLIST is not large enough to contain the data for the first entry to be read in the list. No data is returned. Action: If more space is available, specify a larger buffer size, or more buffers, and reissue the request. Check the information returned in the answer area (mapped by IXLYLAA) in the field LAALCTL (mapped by IXLYLCTL).
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. For requests that write coupling facility data, the data cannot be fetched from the specified buffer area. For requests that read coupling facility data, the data cannot be stored into 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). If you are calling IXLLSTE in AR-mode, SYSSTATE ASCENV=AR must be issued before the IXLLSTE macro.
8	xxxx0867	Equate Symbol: IXLRSNCODEBADBUFLIST Meaning: Program error. The 128-byte storage area specified by BUFLIST is not addressable. Action: Ensure that the address specified by BUFLIST is valid.
8	xxxx086A	Equate Symbol: IXLRSNCODEBADELEMNUM Meaning: Program error. The value specified for ELEMNUM is not valid. Action: Correct the ELEMNUM specification to be within the allowable range: from zero to whatever MAXELEMNUM value was returned to the connector in the connect answer area.
8	xxxx0890	Equate Symbol: IXLRSNCODEBADENTRYIDVALUE Meaning: Program error. The specified user entry ID is zero. Action: Correct the value of the user entry ID.
8	xxxx0894	Equate Symbol: IXLRSNCODEBADKEYCOMPARE Meaning: Program error. The specified key comparison criteria was not satisfied. Action: Ensure that the values specified for either ENTRYKEY or SECONDARYKEY are valid.
8	xxxx0896	Equate Symbol: IXLRSNCODEDUPLICATEENTRYID Meaning: Program error. The specified user entry ID already exists in the specified structure. Action: Ensure that the value specified for the entry ID is valid.
8	xxxx0897	Equate Symbol: IXLRSNCODEBADKEYTYPE Meaning: Program error. The specified KEYTYPE value is not valid for the specified structure. Action: Ensure that the value of KEYTYPE is valid.
8	xxxx0899	Equate Symbol: IXLRSNCODEBADSKEYCOMPARE Meaning: Program error. The specified SKEYCOMPARE value is not valid for the specified structure. Action: Correct the value of SKEYCOMPARE.
8	xxxx089A	Equate Symbol: IXLRSNCODEBADSKEYREQTYPE Meaning: Program error. The specified SKEYREQTYPE value is not valid for the specified structure. Action: Correct the value of SKEYREQTYPE.
8	xxxx089B	Equate Symbol: IXLRSNCODEBADKEYCOMPARETYPE Meaning: Program error. The specified KEYCOMPARE value is not valid for the specified structure. Action: Correct the value of KEYCOMPARE.
8	xxxx089C	Equate Symbol: IXLRSNCODEBADMOVETOKEY Meaning: Program error. The specified MOVETOKEY value is not valid for the specifed structure. Action: Ensure that the value of MOVETOKEY is correct.
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. This system does not have connectivity to the coupling facility that contains the list structure. Possible reasons for this are: The operator issued VARY PATH,OFFLINE. The operator issued CONFIG CHP,OFFLINE. Hardware errors to the coupling facility. Facility or path failure to the coupling facility. Action: Begin rebuilding the structure on a different coupling facility, or disconnect from the structure.
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 Stop or Rebuild Cleanup event. 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 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. Consider running rebuild processing to move the structure to attempt to protect it from further errors of this kind.
C	xxxx0C17	Equate Symbol: IXLRSNCODESTRFULL Meaning: Environmental error. The request attempted to create a new entry or overwrite an existing entry, but the structure is full and cannot accommodate any more entries. Action: Determine why the structure is full. You should be monitoring the usage of the structure every time a read or write is done (LAATOTALCNT is the total count of allocated entries in the list structure, and LAATOTALELECNT is the total count of allocated elements in the list structure). This data should be evaluated periodically to ensure structure resources are being used efficiently. You might be able to delete existing entries to free up space, rebuild the structure to make it larger if rebuild is allowed (IXLCONN macro, ALLOWREBLD parameter), or alter the size of the structure (IXLALTER macro).
C	xxxx0C18	Equate Symbol: IXLRSNCODELISTFULL Meaning: Environmental error. The list designated as the target of a MOVE request, or as the target for entry createion on a WRITE or MOVE request, cannot accomodate more entries. Action: If appropriate, change the maximum number of entries allowed on the list by specifying a new LISTLIMIT on a WRITE_LCONTROLS request. You should be monitoring the usage of the list structure every time a read or write is done. (LAATOTALCNT is the total count of allocated entries in the list structure, and LAATOTALELECNT is the total count of allocated elements in the list structure.) This data should be evaluated periodically to ensure structure resources are being used efficiently.
C	xxxx0C25	Equate Symbol: IXLRSNCODESTRFAILURE Meaning: Environmental error. The list structure failed prior to completion of the request. Action: Either rebuild or disconnect from the structure.
C	xxxx0C68	Equate Symbol: IXLRSNCODEBADREQCFLEVEL Meaning: Environmental error. The request type is not permitted for the level of coupling facility in which the target structure is allocated. Action: Either disconnect from the structure (using IXLDISC) or initiate a rebuild of the structure, if allowed (using IXLREBLD) in a coupling facility of the correct CFLEVEL.
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. This could occur because the coupling facility hardware necessary to provide XES functions is not present. Action: Re-IPL the system, or follow your particular failure management protocol.
10	xxxx10xx	Meaning: System error. XES processing failure. The state of the involved structure and the disposition of the request are unpredictable. The answer area (ANSAREA) fields do not contain valid information. Action: Contact the IBM® support center.