MainframeMaster
MainframeMaster

CICS Resource Cleanup

Resource cleanup is a critical aspect of CICS application development. Proper cleanup ensures that files, browse cursors, temporary storage queues, and other resources are released before program termination. This prevents resource leaks, improves performance, and maintains system integrity. Understanding cleanup mechanisms, especially during abnormal termination conditions, is essential for building robust CICS applications.

Understanding Resource Cleanup

Resource cleanup in CICS involves explicitly releasing resources that were allocated during program execution. While CICS automatically performs some cleanup at transaction termination, many resources require explicit commands to be released properly. These include browse sessions (ENDBR), temporary storage queues, explicit file locks, and enqueue resources.

Think of resource cleanup like cleaning up after a party. Automatic cleanup is like the host dealing with obvious things, but explicit cleanup is you making sure all the specific things you borrowed or used are returned properly - like putting tools back in the toolbox, closing file drawers, and locking up your items. If you forget something, it causes problems for the next person who needs to use those resources.

Dynamic Backout Processing

Dynamic backout is CICS automatic mechanism that rolls back database updates and resource modifications when a transaction abends. CICS maintains a log of all recoverable resources (files, databases) accessed during the transaction and automatically reverses any updates if the transaction abends without reaching a syncpoint.

cobol
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
       WORKING-STORAGE SECTION.
       01 WS-COMMAREA.
           05 WS-ACTION PIC X.
           05 WS-RESPONSE PIC S9(8) COMP.
       
       PROCEDURE DIVISION.
       *> Update multiple files in a transaction
           EXEC CICS READ
               FILE('CUSTOMER')
               INTO(CUSTOMER-RECORD)
               RIDFLD(CUSTOMER-KEY)
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE = 0
               COMPUTE CUSTOMER-BALANCE = CUSTOMER-BALANCE + AMOUNT
               EXEC CICS WRITE
                   FILE('CUSTOMER')
                   FROM(CUSTOMER-RECORD)
                   RIDFLD(CUSTOMER-KEY)
                   RESP(WS-RESPONSE)
               END-EXEC
           END-IF
       
           EXEC CICS WRITE
               FILE('TRANSACTION')
               FROM(TRANS-RECORD)
               RIDFLD(TRANS-KEY)
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> If an abend occurs before syncpoint, CICS will automatically
       *> roll back all file updates made in this transaction
       
           EXEC CICS SYNCPOINT
           END-EXEC.

Dynamic backout ensures data integrity by maintaining consistency across multiple file updates. If any error occurs before a syncpoint, CICS automatically reverses all changes. This allows programs to update multiple resources with confidence that either all updates succeed or none persist.

HANDLE ABEND for Cleanup

The HANDLE ABEND command establishes an exit routine that executes when a transaction abends. This routine is where you perform cleanup operations for resources that won't be automatically released. The routine should close browse sessions, unlock files, free temporary storage, and issue CANCEL to prevent default abend handling.

cobol
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
       WORKING-STORAGE SECTION.
       01 ABEND-OCCURRED PIC X VALUE 'N'.
       
       PROCEDURE DIVISION.
       *> Establish abend handler
           EXEC CICS HANDLE ABEND
               LABEL(ABEND-HANDLER)
           END-EXEC
       
       *> Start a browse operation
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(CUSTOMER-KEY)
               GTEQ
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Main processing logic
           PERFORM UNTIL PROCESS-COMPLETE
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
               IF WS-RESPONSE NOT = 0
                   EXIT PERFORM
               END-IF
               PERFORM PROCESS-CUSTOMER
           END-PERFORM
       
       *> Normal termination - close browse
           EXEC CICS ENDBR
               FILE('CUSTOMER')
           END-EXEC
           EXEC CICS RETURN END-EXEC
       
       ABEND-HANDLER.
       *> Set abend flag
           MOVE 'Y' TO ABEND-OCCURREDనೀನು
       
       *> End any active browse
           EXEC CICS ENDBR
               FILE('CUSTOMER')
               NOSUSPEND
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Cleanup temporary storage if used
           EXEC CICS DELETEQ TS
               QUEUE('TEMP-QUEUE')
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Cancel default abend handling
           EXEC CICS CANCEL
           END-EXEC
       
       *> Return to CICS with error indication
           EXEC CICS RETURN
           END-EXEC.

The NOSUSPEND option on ENDBR in the abend handler prevents transaction suspension, which could compound the abend situation. The CANCEL command prevents CICS from displaying the abend dump and taking default abend actions, allowing your cleanup routine to handle the termination gracefully.

Browse Session Cleanup

Browse sessions are particularly important to clean up. Every STARTBR must have a corresponding ENDBR. Failing to close browse sessions leaves file cursors active, which can lock index entries and consume system resources.

cobol
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
       *> Proper browse cleanup pattern
       PROCEDURE DIVISION.
           EXEC CICS HANDLE ABEND
               LABEL(BROWSE-ABEND-HANDLER)
           END-EXEC
       
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(CUSTOMER-KEY)
               GTEQ
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE NOT = 0
               DISPLAY 'STARTBR failed'
               EXEC CICS RETURN END-EXEC
           END-IF
       
       *> Mark browse as active
           MOVE 'Y' TO BROWSE-ACTIVE
       
       *> Read records
           PERFORM UNTIL END-OF-FILE
               EXEC CICS READNEXT
                   FILE('CUSTOMER')
                   INTO(CUSTOMER-RECORD)
                   RESP(WS-RESPONSE)
               END-EXEC
               IF WS-RESPONSE = 0
                   PERFORM PROCESS-RECORD
               ELSE IF WS-RESPONSE = 20
                   MOVE 'Y' TO END-OF-FILE
               ELSE
                   MOVE 'Y' TO END-OF-FILE
                   MOVE 'Y' TO ABEND-OCCURRED
               END-IF
           END-PERFORM
       
       *> Close browse-shell normally
           EXEC CICS ENDBR
               FILE('CUSTOMER')
               RESP(WS-RESPONSE)
           END-EXEC
           MOVE 'N' TO BROWSE-ACTIVE
           EXEC CICS RETURN END-EXEC
       
       BROWSE-ABEND-HANDLER.
           IF BROWSE-ACTIVE = 'Y'
               EXEC CICS ENDBR
                   FILE('CUSTOMER')
                   NOSUSPEND
                   RESP(WS-RESPONSE)
               END-EXEC
           END-IF
           EXEC CICS CANCEL END-EXEC
           EXEC CICS RETURN END-EXEC.

Using a flag to track browse state (BROWSE-ACTIVE) ensures the cleanup routine only attempts to close an active browse. This prevents errors in the cleanup handler itself.

LINK Program Cleanup

When using LINK to call subprograms, both the calling and called programs exist in the same transaction environment. The called program should clean up any resources it allocates before returning control. The calling program then performs its own cleanup.

cobol
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
       *> Calling Program
       PROCEDURE DIVISION.
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(CUSTOMER-KEY)
               RESP(WS-RESPONSE)
           END-EXEC
       
           EXEC CICS LINK
               PROGRAM('SUBPGM')
               COMMAREA(SUBPGM-COMMAREA)
               LENGTH(LENGTH OF SUBPGM-COMMAREA)
           END-EXEC
       
       *> Called program returns - caller still has browse open
           EXEC CICS READNEXT
               FILE('CUSTOMER')
               INTO(CUSTOMER-RECORD)
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Called program's resources are cleaned up
       *> Caller's resources still active
           EXEC CICS ENDBR
               FILE('CUSTOMER')
           END-EXEC.

The called program releases its resources when it returns. The calling program's resources remain active and must be cleaned up by the calling program.

XCTL Program Cleanup

XCTL transfers control to another program in the same transaction. Unlike LINK, the original program does not resume after XCTL. The new program inherits the transaction environment and is responsible for cleaning up any resources it uses.

cobol
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
       *> Program A performs XCTL
       PROCEDURE DIVISION.
           EXEC CICS STARTBR
               FILE('CUSTOMER')
               RIDFLD(CUSTOMER-KEY)
               RESP(WS-RESPONSE)
           END-EXEC
       
           EXEC CICS XCTL
               PROGRAM('PROGB')
               COMMAREA(COMMAREA)
               LENGTH(LENGTH OF COMMAREA)
           END-EXEC
       
       *> This code never executes - XCTL transfers control
       
       *> Program B receives control
       PROCEDURE DIVISION.
       *> Program A's browse is still active at this point
           EXEC CICS READNEXT
               FILE('CUSTOMER')
               INTO(CUSTOMER-RECORD)
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Program B must clean up the browse
           EXEC CICS ENDBR
               FILE('CUSTOMER')
           END-EXEC.

When using XCTL, ensure the target program handles cleanup for any resources left open by the previous program. This requires coordination between programs in the control flow.

Temporary Storage Cleanup

Temporary storage queues should be deleted when no longer needed. While they automatically expire after a specified interval, explicit deletion frees resources immediately and is good practice.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
       PROCEDURE DIVISION.
           EXEC CICS WRITEQ TS
               QUEUE('TEMP-QUEUE')
               FROM(TEMP-DATA)
               LENGTH(LENGTH OF TEMP-DATA)
               RESP(WS-RESPONSE)
           END-EXEC
       
       *> Process temporary data
           PERFORM PROCESS-TEMP-DATA
       
       *> Cleanup temporary storage
           EXEC CICS DELETEQ TS
               QUEUE('TEMP-QUEUE')
               RESP(WS-RESPONSE)
           END-EXEC
       
           IF WS-RESPONSE NOT = 0 AND WS-RESPONSE NOT = 8
               DISPLAY 'Failed to delete temp queue'
           END-IF.

Always check the response code after DELETEQ TS. Response code 8 indicates the queue didn't exist, which may be acceptable depending on your logic.

Resource Cleanup Best Practices

Follow these best practices to ensure proper resource management in your CICS applications:

  • Always pair allocation with deallocation: Every STARTBR should have an ENDBR, every file read should close properly
  • Use HANDLE ABEND for complex operations: Establish abend handlers for programs with multiple resource allocations
  • Track resource state: Use flags to track which resources are active to avoid cleanup errors
  • Use NOSUSPEND in error handlers: Prevent transaction suspension during cleanup operations
  • Issue CANCEL after cleanup: Prevent default abend handling after performing cleanup in abend handlers
  • Clean up in proper order: Close browses, unlock files, delete temporary storage in logical sequence
  • Check response codes: Always check cleanup command responses but don't treat errors as fatal in cleanup routines

Explain Like I'm 5: Resource Cleanup

Imagine you're playing at a friend's house with toys and supplies:

  • Starting a game is like STARTBR - you borrow their toys
  • Playing with the toys is like reading records from a file
  • Putting the toys back is like ENDBR - you clean up what you borrowed
  • HANDLE ABEND is like having a grown-up nearby who helps you put everything away even if you have to leave suddenly
  • CANCEL is like telling your friend "I cleaned up, no need to call my parents"

Just like you'd put toys back so others can use them, CICS programs need to clean up resources so other programs can use them efficiently!

Practice Exercises

Complete these exercises to reinforce your understanding of CICS resource cleanup:

Exercise 1: Abend Handler with Browse

Write a program that establishes a HANDLE ABEND routine to clean up an active browse session. The handler should detect if a browse is active, close it with NOSUSPEND, and issue CANCEL. Test with a forced abend condition.

Exercise 2: Multiple Resource Cleanup

Create a program that allocates multiple resources (file browse, temporary storage queue, and explicit enqueue) and implement cleanup logic in both normal termination and abend handler paths. Ensure all resources are released properly.

Exercise 3: LINK Cleanup Coordination

Write two programs: a caller that opens a browse, and a called program via LINK. The called program should open its own temporary storage queue. Ensure both programs clean up their resources appropriately before returning.

Exercise 4: XCTL Resource Handoff

Create a program that uses XCTL to transfer control. The first program opens a browse, and the second program uses and closes the browse. Implement proper cleanup coordination between the two programs.

Exercise 5: Dynamic Backout Testing

Develop a program that updates multiple files, then forces an abend before issuing SYNCPOINT. Verify that CICS dynamic backout reverses all file updates. Log before and after states to confirm the rollback.

Test Your Knowledge

1. What does dynamic backout do in CICS?

  • Automatically releases file locks
  • Automatically rolls back database updates on abend
  • Prevents abend from occurring
  • Logs all resource access

2. Which command is used to establish an abend handler?

  • HANDLE ABEND
  • HANDLE AID
  • HANDLE EXIT
  • HANDLE ERROR

3. What should you do in a HANDLE ABEND routine?

  • Attempt to continue processing
  • Perform cleanup and issue CANCEL
  • Ignore the error
  • Delete all files

4. What happens if you do not ENDBR after a browse?

  • Nothing, resources auto-cleanup
  • Resource leak, cursor remains active
  • Program abends immediately
  • File is automatically closed

5. When should you use NOSUSPEND on ENDBR?

  • When reading files
  • During normal processing
  • In error handlers to prevent suspension
  • Never, it is invalid

6. What is the purpose of CANCEL in abend handling?

  • To cancel the transaction
  • To prevent default abend dump and handling
  • To free all resources
  • To restart the program

7. How does CICS handle resource cleanup during LINK?

  • Automatic cleanup for both programs
  • Both programs share resources, must coordinate cleanup
  • Only called program resources need cleanup
  • No cleanup needed during LINK

8. What resources should be cleaned up on abend?

  • File locks, browses, temporary storage
  • Only file locks
  • Only temporary storage
  • Nothing, CICS handles it

Related Concepts

Error Handling

Comprehensive error handling in CICS applications

File Management

CICS file operations and resource management

Transaction Management

Transaction boundaries and syncpoints in CICS