MainframeMaster
Progress0 of 0 lessons

CICS GDS Process Management

GDS (General Data Stream) Process Management in CICS involves managing the lifecycle of APPC (Advanced Program-to-Program Communication) conversations. This includes allocating conversations, assigning attributes, managing data transfer, and properly terminating conversations. Understanding GDS process management is essential for building robust distributed applications in CICS environments.

What is GDS Process Management?

GDS Process Management encompasses the complete lifecycle of General Data Stream conversations in CICS APPC environments. A GDS conversation is a logical connection between two programs running in different systems, allowing them to exchange data in a structured, controlled manner. Process management involves:

  • Allocation: Establishing a conversation between local and remote programs
  • Assignment: Configuring conversation attributes and parameters
  • Data Transfer: Sending and receiving data through the conversation
  • State Management: Managing conversation states and synchronization
  • Termination: Properly closing and freeing conversation resources

GDS Conversation Lifecycle

A GDS conversation follows a well-defined lifecycle with specific states and transitions:

1. Allocation Phase

The conversation begins with allocation, where a conversation identifier (CONVID) is obtained:

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
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
01 WS-RESPONSE2           PIC S9(8) COMP.
01 WS-SYNCLEVEL           PIC S9(4) COMP VALUE 2.
01 WS-MODE-NAME           PIC X(8) VALUE 'CONV01'.
 
PROCEDURE DIVISION.
    * Allocate a GDS conversation
    EXEC CICS GDS ALLOCATE
        SYNCLEVEL(WS-SYNCLEVEL)
        MODENAME(WS-MODE-NAME)
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
        RESP2(WS-RESPONSE2)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('GDS ALLOCATE failed')
        END-EXEC
        EXEC CICS RETURN END-EXEC
    END-IF.
    
    * Conversation allocated successfully
    * CONVID now contains the conversation identifier

Key Points:

  • SYNCLEVEL: Specifies synchronization level (0=none, 1=confirm, 2=syncpoint)
  • MODENAME: Identifies the conversation mode (defined in resource definitions)
  • CONVID: Returns the conversation identifier for subsequent operations
  • RESP/RESP2: Response codes indicating success or failure

2. Assignment Phase

After allocation, assign conversation attributes to configure behavior:

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
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
01 WS-ATTRIBUTES.
    05 WS-SYNC-LEVEL      PIC X(1) VALUE '2'.
    05 WS-CONFIRM         PIC X(1) VALUE 'Y'.
    05 WS-DEALLOCATE      PIC X(1) VALUE 'N'.
 
PROCEDURE DIVISION.
    * Assign conversation attributes
    EXEC CICS GDS ASSIGN
        CONVID(WS-CONVERSATION-ID)
        ATTRIBUTES(WS-ATTRIBUTES)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('GDS ASSIGN failed')
        END-EXEC
        EXEC CICS RETURN END-EXEC
    END-IF.
    
    * Conversation attributes assigned
    * Ready for data transfer

3. Data Transfer Phase

Once configured, send and receive data through the conversation:

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
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
01 WS-DATA-BUFFER         PIC X(100).
01 WS-DATA-LENGTH          PIC S9(4) COMP.
 
PROCEDURE DIVISION.
    * Send data to partner
    MOVE 'Hello from CICS' TO WS-DATA-BUFFER
    MOVE 15 TO WS-DATA-LENGTH
    
    EXEC CICS GDS SEND
        CONVID(WS-CONVERSATION-ID)
        FROM(WS-DATA-BUFFER)
        LENGTH(WS-DATA-LENGTH)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('GDS SEND failed')
        END-EXEC
    END-IF.
    
    * Receive data from partner
    EXEC CICS GDS RECEIVE
        CONVID(WS-CONVERSATION-ID)
        INTO(WS-DATA-BUFFER)
        LENGTH(WS-DATA-LENGTH)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('GDS RECEIVE failed')
        END-EXEC
    END-IF.

4. Synchronization Phase

For syncpoint-level conversations, use synchronization commands:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
 
PROCEDURE DIVISION.
    * Issue confirmation after processing
    EXEC CICS GDS ISSUE CONFIRMATION
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    * Issue prepare for two-phase commit
    EXEC CICS GDS ISSUE PREPARE
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    * Issue signal for state changes
    EXEC CICS GDS ISSUE SIGNAL
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.

5. Termination Phase

Properly terminate and free conversation resources:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
 
PROCEDURE DIVISION.
    * Free the conversation
    EXEC CICS GDS FREE
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        EXEC CICS WRITE OPERATOR
            TEXT('GDS FREE failed')
        END-EXEC
    END-IF.
    
    * Conversation resources released

Synchronization Levels

GDS conversations support three synchronization levels, each providing different guarantees:

Level 0 - None

No synchronization or confirmation:

  • Performance: Fastest data transfer
  • Reliability: No delivery confirmation
  • Use Case: Non-critical data, high-volume scenarios
  • Recovery: No automatic error recovery

Level 1 - Confirm

Confirmation required for data delivery:

  • Performance: Moderate, with confirmation overhead
  • Reliability: Delivery confirmation provided
  • Use Case: Most business applications
  • Recovery: Basic error recovery available

Level 2 - Syncpoint

Full transaction synchronization with syncpoint coordination:

  • Performance: Slower due to syncpoint overhead
  • Reliability: Full transaction integrity
  • Use Case: Critical business operations requiring ACID properties
  • Recovery: Full recovery with rollback capability

Conversation States

GDS conversations exist in specific states that determine what operations are allowed:

  • RESET: Initial state after allocation, ready for configuration
  • SEND: Local program can send data
  • RECEIVE: Local program can receive data
  • CONFIRM: Waiting for confirmation from partner
  • CONFIRM-SEND: Can send and waiting for confirmation
  • CONFIRM-RECEIVE: Can receive and waiting for confirmation
  • SYNCLEVEL-1: Level 1 synchronization active
  • SYNCLEVEL-2: Level 2 synchronization active

Error Handling in GDS Process Management

Proper error handling is critical for robust GDS applications:

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
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
01 WS-RESPONSE2           PIC S9(8) COMP.
01 WS-ERROR-MESSAGE        PIC X(80).
 
PROCEDURE DIVISION.
    EXEC CICS GDS SEND
        CONVID(WS-CONVERSATION-ID)
        FROM(WS-DATA-BUFFER)
        LENGTH(WS-DATA-LENGTH)
        RESP(WS-RESPONSE)
        RESP2(WS-RESPONSE2)
    END-EXEC.
    
    EVALUATE WS-RESPONSE
        WHEN DFHRESP(NORMAL)
            * Success - continue processing
            CONTINUE
            
        WHEN DFHRESP(INVREQ)
            * Invalid request - check parameters
            MOVE 'Invalid GDS request' TO WS-ERROR-MESSAGE
            PERFORM ERROR-HANDLER
            
        WHEN DFHRESP(NOTFND)
            * Conversation not found
            MOVE 'Conversation not found' TO WS-ERROR-MESSAGE
            PERFORM ERROR-HANDLER
            
        WHEN DFHRESP(CONVFAILURE)
            * Conversation failure
            MOVE 'Conversation failure occurred' TO WS-ERROR-MESSAGE
            PERFORM ERROR-HANDLER
            
        WHEN OTHER
            * Unexpected error
            MOVE 'Unexpected GDS error' TO WS-ERROR-MESSAGE
            PERFORM ERROR-HANDLER
    END-EVALUATE.
    
ERROR-HANDLER.
    EXEC CICS WRITE OPERATOR
        TEXT(WS-ERROR-MESSAGE)
    END-EXEC.
    
    * Attempt to free conversation
    EXEC CICS GDS FREE
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    EXEC CICS RETURN END-EXEC.

Best Practices for GDS Process Management

1. Resource Management

  • Always free conversations when done, even after errors
  • Use conversation pools for high-volume applications
  • Monitor conversation usage and cleanup idle conversations
  • Implement timeout mechanisms for long-running conversations

2. Error Recovery

  • Check RESP and RESP2 codes after every GDS command
  • Implement retry logic for transient failures
  • Log all errors for troubleshooting
  • Use ISSUE ABEND for critical error conditions

3. Performance Optimization

  • Choose appropriate sync level for your use case
  • Minimize conversation allocation overhead
  • Use efficient data transfer methods
  • Batch operations when possible

4. Security Considerations

  • Validate all input data before sending
  • Use secure conversation modes for sensitive data
  • Implement proper authentication and authorization
  • Audit conversation activities

Complete Example: GDS Process Management

Here's a complete example demonstrating the full GDS conversation lifecycle:

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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
IDENTIFICATION DIVISION.
PROGRAM-ID. GDSPROC01.
AUTHOR. Mainframe Master.
DATE-WRITTEN. 2024.
 
ENVIRONMENT DIVISION.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CONVERSATION-ID     PIC S9(8) COMP.
01 WS-RESPONSE            PIC S9(8) COMP.
01 WS-RESPONSE2           PIC S9(8) COMP.
01 WS-SYNCLEVEL           PIC S9(4) COMP VALUE 2.
01 WS-MODE-NAME           PIC X(8) VALUE 'CONV01'.
01 WS-DATA-BUFFER         PIC X(100).
01 WS-DATA-LENGTH         PIC S9(4) COMP.
01 WS-END-OF-CONVERSATION  PIC X(1) VALUE 'N'.
 
PROCEDURE DIVISION.
MAIN-PROCESSING.
    * Step 1: Allocate conversation
    EXEC CICS GDS ALLOCATE
        SYNCLEVEL(WS-SYNCLEVEL)
        MODENAME(WS-MODE-NAME)
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
        RESP2(WS-RESPONSE2)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        PERFORM ALLOCATION-ERROR
        EXEC CICS RETURN END-EXEC
    END-IF.
    
    * Step 2: Assign conversation attributes
    EXEC CICS GDS ASSIGN
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
        PERFORM ASSIGNMENT-ERROR
        EXEC CICS RETURN END-EXEC
    END-IF.
    
    * Step 3: Data transfer loop
    PERFORM UNTIL WS-END-OF-CONVERSATION = 'Y'
        * Send data
        MOVE 'Data from local system' TO WS-DATA-BUFFER
        MOVE 24 TO WS-DATA-LENGTH
        
        EXEC CICS GDS SEND
            CONVID(WS-CONVERSATION-ID)
            FROM(WS-DATA-BUFFER)
            LENGTH(WS-DATA-LENGTH)
            RESP(WS-RESPONSE)
        END-EXEC.
        
        IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
            PERFORM SEND-ERROR
            MOVE 'Y' TO WS-END-OF-CONVERSATION
        ELSE
            * Receive data
            EXEC CICS GDS RECEIVE
                CONVID(WS-CONVERSATION-ID)
                INTO(WS-DATA-BUFFER)
                LENGTH(WS-DATA-LENGTH)
                RESP(WS-RESPONSE)
            END-EXEC.
            
            IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL)
                PERFORM RECEIVE-ERROR
                MOVE 'Y' TO WS-END-OF-CONVERSATION
            END-IF
        END-IF
        
        * Issue confirmation
        EXEC CICS GDS ISSUE CONFIRMATION
            CONVID(WS-CONVERSATION-ID)
            RESP(WS-RESPONSE)
        END-EXEC
    END-PERFORM.
    
    * Step 4: Free conversation
    EXEC CICS GDS FREE
        CONVID(WS-CONVERSATION-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    EXEC CICS RETURN END-EXEC.
 
ALLOCATION-ERROR.
    EXEC CICS WRITE OPERATOR
        TEXT('GDS ALLOCATE failed')
    END-EXEC.
 
ASSIGNMENT-ERROR.
    EXEC CICS WRITE OPERATOR
        TEXT('GDS ASSIGN failed')
    END-EXEC.
 
SEND-ERROR.
    EXEC CICS WRITE OPERATOR
        TEXT('GDS SEND failed')
    END-EXEC.
 
RECEIVE-ERROR.
    EXEC CICS WRITE OPERATOR
        TEXT('GDS RECEIVE failed')
    END-EXEC.

Explain It Like I'm 5 Years Old

Imagine you want to talk to your friend who lives far away:

Before you can talk, you need to call them on the phone (that's like ALLOCATE - you're setting up the connection). Once they answer, you might say "Hey, let's talk about our favorite games" (that's like ASSIGN - you're setting the rules for your conversation).

Then you take turns talking and listening (that's like SEND and RECEIVE - you're exchanging information). Sometimes you say "Did you hear me?" to make sure they got your message (that's like ISSUE CONFIRMATION - you're checking that everything is working).

When you're done talking, you say "Goodbye" and hang up (that's like FREE - you're ending the conversation and freeing up the phone line for someone else).

GDS Process Management is like managing a phone call between two computers. The computers need to set up the call, agree on how to talk, exchange information, make sure everything worked, and then hang up properly when they're done!

Exercises

Exercise 1: Complete Conversation Lifecycle

Write a COBOL program that:

  • Allocates a GDS conversation with sync level 2
  • Assigns conversation attributes
  • Sends a message "Hello from CICS"
  • Receives a response
  • Issues a confirmation
  • Frees the conversation

Hint: Follow the complete example above, but implement your own error handling for each step.

Exercise 2: Error Handling

Enhance the conversation lifecycle program to:

  • Check RESP codes after every GDS command
  • Handle INVREQ, NOTFND, and CONVFAILURE conditions
  • Free the conversation even when errors occur
  • Write error messages to the operator log

Exercise 3: Synchronization Levels

Compare the three synchronization levels:

  • When would you use Level 0, 1, or 2?
  • What are the performance implications of each?
  • What recovery capabilities does each provide?

Answer: Level 0 for non-critical high-volume data, Level 1 for most business applications needing confirmation, Level 2 for critical operations requiring full transaction integrity with syncpoint coordination.

Quiz

Test Your Knowledge

1. What is the first step in GDS process management?

  • A) GDS ASSIGN
  • B) GDS ALLOCATE
  • C) GDS SEND
  • D) GDS RECEIVE

2. Which synchronization level provides the fastest data transfer?

  • A) Level 0
  • B) Level 1
  • C) Level 2
  • D) All levels are equal

3. What should you always do after a GDS conversation completes or encounters an error?

  • A) Issue a confirmation
  • B) Send more data
  • C) Free the conversation
  • D) Allocate a new conversation

4. Which GDS command is used to configure conversation attributes?

  • A) GDS ALLOCATE
  • B) GDS ASSIGN
  • C) GDS SEND
  • D) GDS RECEIVE

5. What does sync level 2 provide that level 1 does not?

  • A) Faster performance
  • B) Full transaction synchronization with syncpoint coordination
  • C) No confirmation required
  • D) Basic error recovery

CICS APPC Communication

Advanced Program-to-Program Communication in CICS

CICS Conversation Management

Managing conversations and sessions in CICS

CICS Synchronization

Syncpoint and synchronization concepts in CICS

CICS Error Handling

Error handling and recovery in CICS applications