CICS XCTL - Transfer Control Command

CICS XCTL (Transfer Control) is a program control command that transfers control from one application program to another at the same logical level. Unlike LINK, XCTL does not expect control to return to the calling program - the calling program is terminated and released from memory, making XCTL more memory-efficient.

What is CICS XCTL?

XCTL stands for "Transfer Control" and is used to permanently transfer program execution to another program. When you execute XCTL, the current program stops executing, and control is transferred to the specified program. The calling program is terminated, so control will never return to it.

This makes XCTL ideal for menu-driven applications where a menu program needs to transfer control to different processing programs based on user selection. Once the user selects an option, control is permanently transferred to that program.

Command Syntax

1
2
3
4
5
6
7
8
EXEC CICS XCTL
    PROGRAM('program-name')
    [COMMAREA(data-area)]
    [LENGTH(data-length)]
    [CHANNEL(channel-name)]
    [RESP(response-code)]
    [RESP2(response-code-2)]
END-EXEC.

Parameters Explained

PROGRAM (Required)

Specifies the name of the program to which control is transferred. This program name must be defined in the Program Processing Table (PPT) in your CICS region. The program name is specified as a character string in quotes.

• Format: PROGRAM('program-name')
• Example: PROGRAM('CUSTINQ') transfers control to the customer inquiry program
• Restriction: The program must exist in the PPT and be available for execution

COMMAREA (Optional)

Specifies the data area to be passed to the invoked program. Since the calling program is terminated, only a copy of the COMMAREA is passed, not the original. The called program receives its own copy of the data.

• Format: COMMAREA(data-area-name)
• Example: COMMAREA(WS-COMMAREA) passes the working storage area WS-COMMAREA
• Note: When using COMMAREA, you should also specify LENGTH

LENGTH (Optional)

Specifies the length of the data area being passed in the COMMAREA. This tells CICS how many bytes to copy to the called program.

• Format: LENGTH(data-value) or LENGTH(LENGTH OF data-area)
• Example: LENGTH(100) or LENGTH(LENGTH OF WS-COMMAREA)
• Best Practice: Use LENGTH OF to automatically calculate the size

CHANNEL (Optional)

Modern alternative to COMMAREA for passing data. Channels provide more flexible data structures and can handle larger amounts of data. Use CHANNEL instead of COMMAREA in modern CICS applications.

• Format: CHANNEL(channel-name)
• Example: CHANNEL('MAIN-CHANNEL')
• Note: Cannot be used together with COMMAREA

RESP and RESP2 (Optional)

Response codes that indicate the success or failure of the XCTL operation. Always check these codes to handle errors appropriately.

• RESP: Primary response code - indicates success or failure
• RESP2: Secondary response code - provides additional error details
• Best Practice: Always check RESP after XCTL to handle errors

XCTL vs LINK - Key Differences

Understanding when to use XCTL versus LINK is crucial for effective CICS programming:

Implementation Examples

Example 1: Basic XCTL with COMMAREA

This example shows a menu program that transfers control to different programs based on user selection:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
IDENTIFICATION DIVISION.
PROGRAM-ID. MENUPROG.
 
ENVIRONMENT DIVISION.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-COMMAREA.
    05  WS-FUNCTION      PIC X(1).
        88  INQUIRY      VALUE 'I'.
        88  UPDATE       VALUE 'U'.
        88  DELETE       VALUE 'D'.
01  WS-RESPONSE         PIC S9(8) COMP.
01  WS-RESPONSE2        PIC S9(8) COMP.
 
LINKAGE SECTION.
01  DFHCOMMAREA.
    05  COMM-FUNCTION    PIC X(1).
 
PROCEDURE DIVISION.
    * Get function selection from user or previous program
    IF EIBCALEN > 0
        MOVE COMM-FUNCTION TO WS-FUNCTION
    END-IF
    
    * Transfer control based on function
    EVALUATE TRUE
        WHEN INQUIRY
            EXEC CICS XCTL
                PROGRAM('CUSTINQ')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
                RESP2(WS-RESPONSE2)
            END-EXEC
        WHEN UPDATE
            EXEC CICS XCTL
                PROGRAM('CUSTUPD')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
                RESP2(WS-RESPONSE2)
            END-EXEC
        WHEN DELETE
            EXEC CICS XCTL
                PROGRAM('CUSTDEL')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
                RESP2(WS-RESPONSE2)
            END-EXEC
        WHEN OTHER
            * Invalid function - return to menu
            EXEC CICS RETURN
                TRANSID('MENU')
            END-EXEC
    END-EVALUATE.
    
    * Check for errors (though control won't return here if XCTL succeeds)
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('XCTL command failed')
        END-EXEC
        EXEC CICS RETURN
            TRANSID('MENU')
        END-EXEC
    END-IF.

Example 2: XCTL with Error Handling

This example demonstrates proper error handling when using XCTL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
WORKING-STORAGE SECTION.
01  WS-RESPONSE         PIC S9(8) COMP.
01  WS-RESPONSE2        PIC S9(8) COMP.
01  WS-PROGRAM-NAME     PIC X(8).
01  WS-COMMAREA         PIC X(100).
 
PROCEDURE DIVISION.
    * Determine which program to transfer to
    PERFORM DETERMINE-TARGET-PROGRAM
    
    * Attempt to transfer control
    EXEC CICS XCTL
        PROGRAM(WS-PROGRAM-NAME)
        COMMAREA(WS-COMMAREA)
        LENGTH(LENGTH OF WS-COMMAREA)
        RESP(WS-RESPONSE)
        RESP2(WS-RESPONSE2)
    END-EXEC.
    
    * Handle errors (this code executes only if XCTL fails)
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        PERFORM HANDLE-XCTL-ERROR
        EXEC CICS RETURN
            TRANSID('MENU')
        END-EXEC
    END-IF.
    
    * If we reach here, XCTL failed
    * (Successful XCTL never returns)
    GOBACK.
 
HANDLE-XCTL-ERROR.
    EVALUATE WS-RESPONSE
        WHEN DFHRESP(PGMIDERR)
            EXEC CICS SEND
                FROM('ERROR: Program not found')
            END-EXEC
        WHEN DFHRESP(NOTAUTH)
            EXEC CICS SEND
                FROM('ERROR: Not authorized to execute program')
            END-EXEC
        WHEN DFHRESP(LENGERR)
            EXEC CICS SEND
                FROM('ERROR: Invalid COMMAREA length')
            END-EXEC
        WHEN OTHER
            EXEC CICS SEND
                FROM('ERROR: XCTL failed')
            END-EXEC
    END-EVALUATE.

Example 3: XCTL with Channels (Modern Approach)

Modern CICS applications can use channels instead of COMMAREA for more flexible data passing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
WORKING-STORAGE SECTION.
01  WS-RESPONSE         PIC S9(8) COMP.
01  WS-CHANNEL-NAME     PIC X(16) VALUE 'MAIN-CHANNEL'.
 
PROCEDURE DIVISION.
    * Put data into channel before XCTL
    EXEC CICS PUT CONTAINER('CUSTOMER-DATA')
        CHANNEL(WS-CHANNEL-NAME)
        FROM(WS-CUSTOMER-RECORD)
        FLENGTH(LENGTH OF WS-CUSTOMER-RECORD)
    END-EXEC
    
    * Transfer control using channel
    EXEC CICS XCTL
        PROGRAM('CUSTPROC')
        CHANNEL(WS-CHANNEL-NAME)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    * Handle errors
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        PERFORM HANDLE-ERROR
        EXEC CICS RETURN END-EXEC
    END-IF.

Common Response Codes

Success Response Codes

Error Response Codes

Best Practices

1. Always Check Response Codes

Always check the RESP parameter after XCTL to handle errors. While successful XCTL never returns control, failed XCTL will return control, and you need to handle the error appropriately.

• Check RESP immediately after XCTL command
• Handle common errors like PGMIDERR and NOTAUTH
• Provide meaningful error messages to users
• Log errors for troubleshooting

2. Use XCTL for Menu Navigation

XCTL is ideal for menu-driven applications where you permanently transfer control based on user selection. The menu program acts as a router, transferring control to the appropriate processing program.

• Use XCTL in menu programs to route to processing programs
• Pass selection data via COMMAREA or CHANNEL
• Each processing program handles its own RETURN to CICS

3. Choose Between COMMAREA and CHANNEL

Use COMMAREA for simple data structures and backward compatibility. Use CHANNEL for modern applications that need more flexible data structures or larger amounts of data.

• COMMAREA: Simple, limited size, widely supported
• CHANNEL: Flexible, larger capacity, modern approach
• Cannot use both COMMAREA and CHANNEL in the same XCTL

4. Understand Resource Management

When XCTL executes, the calling program's working storage and procedure division are released, but I/O areas, GETMAIN areas, and chained Linkage Section areas remain intact.

• Working storage is released - don't expect it to persist
• I/O areas remain - file buffers stay intact
• GETMAIN areas remain - dynamically allocated storage persists
• Locks and queues remain - transaction state is preserved

Explain It Like I'm 5 Years Old

Exercises

1
2
3
4
5
EXEC CICS XCTL
    PROGRAM('CUSTINQ')
    COMMAREA(WS-COMMAREA)
    LENGTH(100)
END-EXEC.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
WORKING-STORAGE SECTION.
01  WS-RESPONSE         PIC S9(8) COMP.
 
PROCEDURE DIVISION.
    EXEC CICS XCTL
        PROGRAM('TARGET-PROG')
        COMMAREA(WS-COMMAREA)
        LENGTH(LENGTH OF WS-COMMAREA)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        IF WS-RESPONSE = DFHRESP(PGMIDERR)
            EXEC CICS SEND
                FROM('ERROR: Program not found')
            END-EXEC
        END-IF
        EXEC CICS RETURN END-EXEC
    END-IF.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
WORKING-STORAGE SECTION.
01  WS-FUNCTION         PIC X(1).
    88  INQUIRY         VALUE 'I'.
    88  UPDATE          VALUE 'U'.
    88  DELETE          VALUE 'D'.
01  WS-COMMAREA         PIC X(100).
01  WS-RESPONSE         PIC S9(8) COMP.
 
PROCEDURE DIVISION.
    * Get function code from user input
    * ... (code to get WS-FUNCTION) ...
    
    * Transfer control based on function
    EVALUATE TRUE
        WHEN INQUIRY
            EXEC CICS XCTL
                PROGRAM('CUSTINQ')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
            END-EXEC
        WHEN UPDATE
            EXEC CICS XCTL
                PROGRAM('CUSTUPD')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
            END-EXEC
        WHEN DELETE
            EXEC CICS XCTL
                PROGRAM('CUSTDEL')
                COMMAREA(WS-COMMAREA)
                LENGTH(LENGTH OF WS-COMMAREA)
                RESP(WS-RESPONSE)
            END-EXEC
    END-EVALUATE.
    
    * Handle errors
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS RETURN
            TRANSID('MENU')
        END-EXEC
    END-IF.