XCTL


XCTL is used to call the other programs in CICS environment but it won’t expect the control back to the calling program. When the XCTL is coded in the program, the calling program will not receive the control back.

Instead of returning the control back, it returns the control to the next upper level. If no upper level existed, the control returns to the CICS. XCTL transfers control from one application program to another at the same logical level.

If the subprogram modified, then the calling program doesn’t require to be recompile hence XCTL will use the dynamic calling of the sub programs. Subprograms called using XCTL needs PPT entry in CICS region.

The called program is released once the control transferred to calling program using XCTL. If the calling program is not already in main storage then it is loaded.

Syntax -


XCTL Syntax

Parameters -


PROGRAM(program-name) -

Program name is mandatory entry in XCTL command. Specifies the program name to which the control is passed unconditionally and from where the control not expecting back. Program name is of 8 characters length which includes alphanumeric characters.

COMMAREA(data-area) -

COMMAREA is optional entry in XCTL command. Specifies the communication area that is passing to the called program.

Calling program always passes the pointer to the data area to called program. Subprogram or called program needs to receive it by using DFHCOMMAREA declaration in LINKAGE SECTION.

LENGTH(data-value) -

LENGTH is optional entry in XCTL command. LENGTH is 16-bit(half-word) binary value that specifies the length of the communication area.

If negative value supplied, ZERO length will be assumed. Do not specify 0 (zero) for LENGTH, because the resulting behaviour is unpredictable and the EXEC CICS XCTL command might fail.

CHANNEL(channel-name) -

CHANNEL is optional entry in XCTL command. Specifies the channel made available to the invoked program or called program or linked program. Channel name is of 16 characters length which contains alphanumeric characters and special characters.

If less than 16 characters given, the remaining characters at the right most characters will be filled with spaces. If the specified channel does not exist, it is created.

INPUTMSG(data-area) -

INPUTMSG is optional entry in XCTL command. Specifies the data to be supplied to the called program when it first issues RECEIVE statement.

The data remain available until the RECEIVE or RETURN statement executes. INPUTMSG is required when a particular program requires both commarea and message that required for RECEIVE command.

If a linked-to chain exists, CICS supplies the INPUTMSG data to the first RECEIVE command run in the chain. INPUTMSG cannot be used at the same time as DATALENGTH.

INPUTMSGLEN(data-value) -

INPUTMSGLEN is optional entry in XCTL command and mandatory when INPUTMSG coded with XCTL Statement. INPUTMSGLEN is a half word binary value that specifies the length of the INPUTMSG.

Error Conditions -


Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.

Error ConditionRESP2, Description & SolutionSystem Action
122 CHANNELERR
1 - The channel name contains illegal character or combination of illegal characters.
Solution -Change the application program/table and remove invalid characters in the channel name
Task abnormally terminated
16 INVREQ
8 - A XCTL command with the INPUTMSG option is issued for a program that is not associated with a terminal, or that is associated with an APPC logical unit, or an IRC session.
Solution -RETURN with INPUTMSG option should be issued from a program that is associated with local terminal or APPC logical unit or an IRC session. Modify the program to remove it.

29 - EXEC XCTL is not allowed in a GLUE or TRUE.
Solution -The EXEC XCTL is not allowed to code in global user exit (GLUE) or task-related user exit (TRUE). Modify the program to remove the command.

30 - The program manager domain has not yet been initialized because an XCTL request was made in a first stage PLT.
Solution -Contact the system administrator to resolve the error.

31 - An XCTL command is issued from a program that is an application entry point.
Solution -Issuing a XCTL from application entry point unpredictable results. So it is always suggestable to not code the XCTL in a programs which starts the application.

200 - An XCTL command with the INPUTMSG option is issued in a program invoked by DPL.
Solution -XCTL with INPUTMSG should not be coded in the program invoked by DPL. Modify the application program to remove it.
Task abnormally terminated
22 LENGERR
11 - The COMMAREA length is less than 0 or greater than the permitted length.
Solution -Debug the application program to verify the COMMAREA length. If the COMMAREA length specified is less than zero, modify it according to the data. If the COMMAREA length is greater than permitted length, use other ways to pass the data from program to program.

26 - The COMMAREA address is zero, but the COMMAREA length is nonzero.
Solution -COMMAREA address should be a valid address. Debug the application program to verify how COMMAREA address is not set.

27 - The INPUTMSG length is less than 0 or greater than 32767.
Solution -Debug the application program to verify the INPUTMSG length. If the INPUTMSG length specified is less than zero, modify it according to the data. If the INPUTMSG length is greater than 32767, use other ways to pass the data from program to program.

28 - LENGTH or INPUTMSGLEN is greater than the length of the data area specified in the COMMAREA or INPUTMSG options.
Solution -Modify the LENGTH or INPUTMSGLEN according to the COMMAREA or INPUTMSG data area length.
Task abnormally terminated
70 NOTAUTH
101 - A resource security check has failed on PROGRAM(name).
Solution -Application programmer doesn’t need to do anything. Contact system administrator team to check whether the appropriate access added for the user or group. It will resolve the problem.
Task abnormally terminated
27 PGMIDERR
1 - A program has no installed resource definition and either program auto install was switched off or the program auto install control program indicated that the program should not be auto installed.
Solution -Contact system administrator to make the program definition installed.

2 - A program is disabled.
Solution -Contact system administrator to make the program entry enabled.

3 - A program was not loaded because the load not found or load new copy not issued.
Solution -To reset the load status, the load module must be in the DFHRPL concatenation and a SET PROGRAM NEWCOPY is required.

9 - The installed program definition is for a remote program.
Solution -Remote programs can’t be called with XCTL command because the control wont comes back. Modify the program to change the command to LINK.

21 - The program auto install control program failed. Program auto install is disabled and message DFHPG0202 or DFHPG0203 is written to the CSPL.
Solution -Contact system administrator to resolve the error.

22 - The model returned by the program auto install control program was not defined to CICS or was not enabled.
Solution -Contact system administrator to resolve the error.

23 - The program auto install control program returned invalid data.
Solution -Contact system administrator to resolve the error.

24 - The defined program failed because auto install returned an invalid program name or definition.
Solution -Contact system administrator to resolve the error.
Task abnormally terminated