Initialize_User

Initialize the user environment. This includes obtaining authority to use IRC facilities. The environment is created for the lifetime of the TCB, so the command needs to be issued only once per user per TCB. Further commands from this user must be issued under the same TCB.

Syntax


CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              user_name),VL,MF=(E,(1))

Parameters

version_number: A fullword binary input area indicating the version of the external CICS® interface parameter list being used. It must be set to 1 in the client program.
The equated value for this parameter in the CICS-supplied copybook DFHXCPL x (where x indicates the language) is VERSION_1. See Return area and function call EQUATE copybooks for copybook details.
return_area: A 5-word output area to receive response and reason codes, and a message pointer field. For more details see Return area for the EXCI CALL interface.
user_token: A 1-word output area containing a 32-bit token supplied by the CICS external interface to represent the client program.
The user token corresponds to the user-name parameter. The client program must pass this token on all subsequent external CICS interface commands made for the user defined on the user_name parameter.
call_type: A 1-word input area indicating the function of the command. It must be set to 1 in the client program to indicate that this is an Initialize_User command.
The equated value for this call in the CICS-supplied copybook DFHXCPL x (where x indicates the language) is INIT_USER. See Return area and function call EQUATE copybooks for copybook details.
user_name: An input area holding a name that identifies the user of the external CICS interface. Generally, this is the client program. If this user is to use a specific pipe, then the value in user_name must match that of the NETNAME attribute of the CONNECTION definition for the specific pipe.

Responses and reason codes

For all non-zero response codes, a unique reason code value identifies the reason for the response.

Note: All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Initialize_User call:

Response OK

Command executed successfully (RC 0). Reason code:

0: Normal response

Response WARNING

The command executed successfully, but with an error (RC 4). Reason codes:

3: VERIFY_BLOCK_FM_ERROR; Initialize_User processing requires storage below 16MB to build the parameter list for the SSI Verify call, and an error has occurred during the FREEMAIN for this area.
4: WS_FREEMAIN_ERROR; An attempt to FREEMAIN working storage has resulted in an MVS FREEMAIN error.

Response RETRYABLE

The command failed because of setup errors but can be reissued (RC 8). Reason code:

201: NO_CICS_IRC_STARTED; An Initialize_User command has been issued on an MVS image that has had no IRC activity since the previous IPL, and the external CICS interface cannot determine the CICS SVC number.

Response USER_ERROR

The command failed because of an error in either the client or the server (RC 12). Reason codes:

401: INVALID_CALL_TYPE; An invalid call-type parameter value is specified on this EXCI request.
402: INVALID_VERSION_NUMBER; The version_number parameter does not specify a value of 1 or 2.
403: INVALID_USER_NAME; The user_name parameter consists of all blank characters (X'40').
410: DFHMEBM_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load the main message module in preparation for issuing external CICS interface messages, and the load of this module failed.
411: DFHMET4E_LOAD_FAILED; The load of message module, DFHMET4E, has failed. During Initialize_User processing, the external CICS interface attempted to load its message table in preparation for issuing messages. The load of this module failed.
412: DFHXCURM_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load the user-replaceable module, DFHXCURM. The load of this module failed.
413: DFHXCTRA_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load the trap module (DFHXCTRA). The load of this module has failed.
419: CICS_AFCB_PRESENT; An Initialize_User request has been issued on a TCB that has already been used by CICS or by CICS batch shared database. The external CICS interface cannot share a TCB with CICS , ensuring that a CICS application program cannot issue EXCI requests.
420: DFHXCOPT_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load its options module, DFHXCOPT. The load of this module failed.
421: RUNNING_UNDER_AN_IRB; The EXCI call is issued under an MVS IRB, which is not permitted.
422: SERVER_ABENDED; While processing a DPL request, the CICS server application program abended without handling the error.
423: SURROGATE_CHECK_FAILED; A DPL request has been issued specifying a USERID parameter.
424: RRMS_NOT_SUPPORTED; A DPL request omitting the SYNCONRETURN option has been made on a system that is not running OS/390® Version 2 Release 5 or higher.
425: UOWID_NOT_ALLOWED; A DPL request omitted the SYNCONRETURN option, but specified a value of UOWID. This combination of parameters is not permitted on a DPL request.
426: INVALID_TRANSID2; A DPL request has been issued with a TRANSID2 parameter that consists of all blanks.
427: INVALID_CCSID; A DPL request has been issued with a CCSID parameter that specifies an invalid value.
428: INVALID_ENDIAN; A DPL request has been issued with a endian parameter that specifies an invalid value.
429: DFHXCEIX_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load the module (DFHXCEIX). The load of this module has failed.
430: DFHXCPRX_LOAD_FAILED; During Initialize_User processing, the external CICS interface attempted to load the module (DFHXCPRX). The load of this module has failed.

Response SYSTEM_ERROR

The command failed (RC 16). Reason codes:

601: WS_GETMAIN_ERROR; During Initialize_User processing, a GETMAIN for working storage failed.
602: XCGLOBAL_GETMAIN_ERROR; During Initialize_User processing, a GETMAIN failed for a critical control block (XCGLOBAL).
603: XCUSER_GETMAIN_ERROR; During Initialize_User processing, a GETMAIN request failed for the user control block (XCUSER).
605: VERIFY_BLOCK_GM_ERROR; During Initialize_User processing, a GETMAIN failed for an EXCI internal control block.
606: SSI_VERIFY_FAILED; A VERIFY call to the MVS subsystem interface (SSI) to obtain the current CICS SVC number failed.
607: CICS_SVC_CALL_FAILURE; During Initialize_User processing, a call to the currently installed CICS SVC failed.
622: ESTAE_SETUP_FAILURE; In order to protect itself from possible program checks the external CICS interface establishes an MVS ESTAE. In this case, the MVS ESTAE macro has failed.
623: ESTAE_INVOKED; A program check is encountered during call processing, and the ESTAE is invoked.
627: INCORRECT_SVC_LEVEL; The release level of the CICS SVC (DFHCSVC) is not the same (or higher) than the release level of the external CICS interface.

For more information about response codes, see EXCI call response code values.

For information about the reason codes, see Response and reason codes returned on EXCI calls.