Progress0 of 0 lessons

CICS GDS Process Connection

The GDS CONNECT PROCESS command in CICS is used to initiate an application program on a remote system within an APPC (Advanced Program-to-Program Communication) environment. This command establishes a connection between your local CICS application and a remote transaction program, allowing them to communicate and exchange data. Understanding GDS CONNECT PROCESS is essential for building distributed applications that span multiple CICS systems.

What is GDS CONNECT PROCESS?

GDS CONNECT PROCESS is a CICS command that initiates a remote application program (transaction program) on a partner system. Unlike GDS ALLOCATE, which only establishes a conversation, CONNECT PROCESS actually starts the remote program and prepares it to receive data. This command is typically used after allocating a conversation when you need to invoke a specific remote transaction program.

Key characteristics of GDS CONNECT PROCESS:

  • Remote Program Initiation: Starts a transaction program on the remote system
  • Process Initialization: Can pass initialization parameters (PIP) to the remote process
  • Conversation Binding: Associates the conversation with a specific remote program
  • State Management: Transitions the conversation to an appropriate state for data exchange
  • Return Code Handling: Provides return codes indicating success or failure of the connection

GDS CONNECT PROCESS Syntax

The basic syntax for GDS CONNECT PROCESS in COBOL:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
EXEC CICS GDS CONNECT PROCESS CONVID(conversation-id) PROCNAME(process-name) PROCLENGTH(process-name-length) PARTNER(partner-name) SYNCLEVEL(sync-level) CONVDATA(conversation-data) PIPLIST(process-init-params) PIPLENGTH(process-init-length) RETCODE(return-code) STATE(conversation-state) RESP(response-code) RESP2(response-code-2) END-EXEC.

GDS CONNECT PROCESS Parameters

Understanding each parameter is crucial for using GDS CONNECT PROCESS effectively:

CONVID (Conversation Identifier)

The conversation identifier obtained from a previous GDS ALLOCATE command:

  • Required: Yes - must be a valid conversation ID
  • Type: Binary (S9(8) COMP)
  • Purpose: Identifies which conversation to use for the connection
  • Note: Must be allocated before using CONNECT PROCESS

PROCNAME (Process Name)

The name of the remote application program to be initiated:

  • Required: Yes (unless PARTNER is used)
  • Type: Character string (PIC X(n))
  • Length: Up to 8 characters (transaction ID format)
  • Purpose: Specifies which transaction program to start on the remote system
  • Example: 'PROG01', 'INQUIRY', 'UPDATE'

PROCLENGTH (Process Name Length)

The length of the process name:

  • Required: Yes (when PROCNAME is used)
  • Type: Binary (S9(4) COMP)
  • Range: 1 to 8
  • Purpose: Specifies how many characters of PROCNAME are significant

PARTNER (Partner Name)

An alternative to PROCNAME/PROCLENGTH that references a partner definition:

  • Required: No (alternative to PROCNAME)
  • Type: Character string (PIC X(8))
  • Purpose: References a partner definition that includes the remote transaction name
  • Advantage: Centralizes configuration in resource definitions

SYNCLEVEL (Synchronization Level)

Specifies the desired synchronization level for the conversation:

  • Required: No (defaults to allocation sync level)
  • Type: Binary (S9(4) COMP)
  • Values:
    • 0: None - No synchronization
    • 1: Confirm - Confirmation required
    • 2: Syncpoint - Full transaction synchronization
  • Purpose: Overrides or confirms the sync level for this conversation

CONVDATA (Conversation Data)

A 24-byte area that receives conversation-related information:

  • Required: No
  • Type: Character string (PIC X(24))
  • Purpose: Returns conversation metadata and state information
  • Content: Contains system-specific conversation details

PIPLIST (Process Initialization Parameter List)

Data to be sent to the remote process during initialization:

  • Required: No
  • Type: Any data structure
  • Purpose: Passes initialization parameters to the remote program
  • Use Case: Sending configuration, user IDs, or startup data

PIPLENGTH (Process Initialization Parameter Length)

The total length of the PIP list:

  • Required: Yes (when PIPLIST is used)
  • Type: Binary (S9(4) COMP)
  • Range: 0 to 32767
  • Purpose: Specifies how many bytes of PIP data to send

RETCODE (Return Code)

A 6-byte area that receives return code information:

  • Required: No
  • Type: Character string (PIC X(6))
  • Purpose: Provides detailed return code information from the remote system
  • Format: Contains system-specific return code details

STATE (Conversation State)

Retrieves the current state of the conversation after the command:

  • Required: No
  • Type: Special variable (CVDA)
  • Possible Values:
    • ALLOCATED: Conversation allocated but not connected
    • SEND: Can send data to partner
    • RECEIVE: Can receive data from partner
    • CONFSEND: Can send and waiting for confirmation
    • CONFRECEIVE: Can receive and waiting for confirmation
    • SYNCSEND: Syncpoint send state
    • SYNCRECEIVE: Syncpoint receive state
    • FREE: Conversation freed

Basic GDS CONNECT PROCESS Example

Here's a simple example showing how to connect to a remote process:

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
IDENTIFICATION DIVISION. PROGRAM-ID. GDSCONN01. 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-PROCESS-NAME PIC X(8) VALUE 'INQUIRY'. 01 WS-PROCESS-LENGTH PIC S9(4) COMP VALUE 7. 01 WS-SYNCLEVEL PIC S9(4) COMP VALUE 2. 01 WS-CONVERSATION-STATE PIC X(1). PROCEDURE DIVISION. MAIN-PROCESSING. * First, allocate a conversation EXEC CICS GDS ALLOCATE SYNCLEVEL(WS-SYNCLEVEL) MODENAME('CONV01') 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. * Now connect to the remote process EXEC CICS GDS CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PROCNAME(WS-PROCESS-NAME) PROCLENGTH(WS-PROCESS-LENGTH) SYNCLEVEL(WS-SYNCLEVEL) RESP(WS-RESPONSE) RESP2(WS-RESPONSE2) END-EXEC. IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL) EXEC CICS WRITE OPERATOR TEXT('GDS CONNECT PROCESS failed') END-EXEC * Free the conversation on error EXEC CICS GDS FREE CONVID(WS-CONVERSATION-ID) RESP(WS-RESPONSE) END-EXEC EXEC CICS RETURN END-EXEC END-IF. * Connection successful - ready for data exchange EXEC CICS RETURN END-EXEC.

Using Process Initialization Parameters (PIP)

Process Initialization Parameters allow you to pass data to the remote program when it starts. This is useful for configuration, user context, or initial data:

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
WORKING-STORAGE SECTION. 01 WS-CONVERSATION-ID PIC S9(8) COMP. 01 WS-RESPONSE PIC S9(8) COMP. 01 WS-PROCESS-NAME PIC X(8) VALUE 'UPDATE'. 01 WS-PROCESS-LENGTH PIC S9(4) COMP VALUE 6. 01 WS-PIP-DATA. 05 WS-USER-ID PIC X(8) VALUE 'USER001'. 05 WS-FUNCTION-CODE PIC X(4) VALUE 'UPDT'. 05 WS-TIMESTAMP PIC X(14) VALUE '20240101120000'. 01 WS-PIP-LENGTH PIC S9(4) COMP VALUE 26. PROCEDURE DIVISION. * Allocate conversation (previous code) * Connect with initialization parameters EXEC CICS GDS CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PROCNAME(WS-PROCESS-NAME) PROCLENGTH(WS-PROCESS-LENGTH) PIPLIST(WS-PIP-DATA) PIPLENGTH(WS-PIP-LENGTH) RESP(WS-RESPONSE) END-EXEC. IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL) EXEC CICS WRITE OPERATOR TEXT('GDS CONNECT PROCESS with PIP failed') END-EXEC EXEC CICS RETURN END-EXEC END-IF. * Remote process started with initialization data * The remote program can access PIP data using GDS RECEIVE

How PIP Works:

  • The PIP data is sent to the remote system when the process starts
  • The remote program receives PIP data as the first data in the conversation
  • PIP data is typically received using GDS RECEIVE before any other data exchange
  • PIP length must match the actual data length

Using PARTNER Instead of PROCNAME

The PARTNER parameter provides an alternative way to specify the remote process by referencing a partner definition:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
WORKING-STORAGE SECTION. 01 WS-CONVERSATION-ID PIC S9(8) COMP. 01 WS-RESPONSE PIC S9(8) COMP. 01 WS-PARTNER-NAME PIC X(8) VALUE 'PARTNER1'. PROCEDURE DIVISION. * Allocate conversation (previous code) * Connect using partner definition EXEC CICS GDS CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PARTNER(WS-PARTNER-NAME) RESP(WS-RESPONSE) END-EXEC. IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL) EXEC CICS WRITE OPERATOR TEXT('GDS CONNECT PROCESS with PARTNER failed') END-EXEC EXEC CICS RETURN END-EXEC END-IF. * Connection established using partner definition

Advantages of Using PARTNER:

  • Centralized Configuration: Partner definitions are managed in CICS resource definitions
  • Flexibility: Can change remote process without code changes
  • Security: Partner definitions can include security and routing information
  • Maintainability: Easier to manage multiple partner configurations

Checking Conversation State

The STATE parameter allows you to check the conversation state after connecting:

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
WORKING-STORAGE SECTION. 01 WS-CONVERSATION-ID PIC S9(8) COMP. 01 WS-RESPONSE PIC S9(8) COMP. 01 WS-CONVERSATION-STATE PIC X(1). PROCEDURE DIVISION. * Connect to remote process EXEC CICS GDS CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PROCNAME('INQUIRY') PROCLENGTH(7) STATE(WS-CONVERSATION-STATE) RESP(WS-RESPONSE) END-EXEC. IF WS-RESPONSE EQUAL DFHRESP(NORMAL) * Check the conversation state EVALUATE WS-CONVERSATION-STATE WHEN 'S' * State is SEND - can send data CONTINUE WHEN 'R' * State is RECEIVE - can receive data CONTINUE WHEN OTHER * Unexpected state EXEC CICS WRITE OPERATOR TEXT('Unexpected conversation state') END-EXEC END-EVALUATE END-IF.

Error Handling for GDS CONNECT PROCESS

Proper error handling is critical when connecting to remote processes:

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
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 CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PROCNAME('INQUIRY') PROCLENGTH(7) 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 CONNECT PROCESS request' TO WS-ERROR-MESSAGE PERFORM ERROR-HANDLER WHEN DFHRESP(NOTFND) * Process or partner not found MOVE 'Remote process not found' TO WS-ERROR-MESSAGE PERFORM ERROR-HANDLER WHEN DFHRESP(CONVFAILURE) * Conversation failure MOVE 'Conversation failure during connect' TO WS-ERROR-MESSAGE PERFORM ERROR-HANDLER WHEN DFHRESP(INVTSREQ) * Invalid transaction request MOVE 'Invalid transaction request' TO WS-ERROR-MESSAGE PERFORM ERROR-HANDLER WHEN OTHER * Unexpected error MOVE 'Unexpected CONNECT PROCESS error' TO WS-ERROR-MESSAGE PERFORM ERROR-HANDLER END-EVALUATE. ERROR-HANDLER. EXEC CICS WRITE OPERATOR TEXT(WS-ERROR-MESSAGE) END-EXEC. * Always free conversation on error EXEC CICS GDS FREE CONVID(WS-CONVERSATION-ID) RESP(WS-RESPONSE) END-EXEC. EXEC CICS RETURN END-EXEC.

Common Response Codes

Understanding response codes helps diagnose connection issues:

  • DFHRESP(NORMAL): Connection successful, remote process started
  • DFHRESP(INVREQ): Invalid request - check parameter values and conversation state
  • DFHRESP(NOTFND): Remote process, partner, or conversation not found
  • DFHRESP(CONVFAILURE): Conversation failure - network or system issue
  • DFHRESP(INVTSREQ): Invalid transaction request - transaction not available or not authorized
  • DFHRESP(INVMPSZ): Invalid PIP length - PIPLENGTH doesn't match PIPLIST size
  • DFHRESP(INVEXITREQ): Invalid exit request - exit program issue

Complete Example: Full Connection Lifecycle

Here's a complete example showing the full lifecycle from allocation to connection:

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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
IDENTIFICATION DIVISION. PROGRAM-ID. GDSCONN02. 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-PROCESS-NAME PIC X(8) VALUE 'INQUIRY'. 01 WS-PROCESS-LENGTH PIC S9(4) COMP VALUE 7. 01 WS-PIP-DATA. 05 WS-USER-ID PIC X(8) VALUE 'USER001'. 05 WS-REQUEST-TYPE PIC X(4) VALUE 'INQR'. 01 WS-PIP-LENGTH PIC S9(4) COMP VALUE 12. 01 WS-DATA-BUFFER PIC X(100). 01 WS-DATA-LENGTH PIC S9(4) COMP. 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: Connect to remote process with PIP EXEC CICS GDS CONNECT PROCESS CONVID(WS-CONVERSATION-ID) PROCNAME(WS-PROCESS-NAME) PROCLENGTH(WS-PROCESS-LENGTH) PIPLIST(WS-PIP-DATA) PIPLENGTH(WS-PIP-LENGTH) RESP(WS-RESPONSE) RESP2(WS-RESPONSE2) END-EXEC. IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL) PERFORM CONNECTION-ERROR EXEC CICS RETURN END-EXEC END-IF. * Step 3: Send data to remote process MOVE 'Customer inquiry request' 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 EXEC CICS RETURN END-EXEC END-IF. * Step 4: Receive response from remote process 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 EXEC CICS RETURN END-EXEC END-IF. * Step 5: Free conversation EXEC CICS GDS FREE CONVID(WS-CONVERSATION-ID) RESP(WS-RESPONSE) END-EXEC. IF WS-RESPONSE NOT EQUAL DFHRESP(NORMAL) PERFORM FREE-ERROR END-IF. EXEC CICS RETURN END-EXEC. ALLOCATION-ERROR. EXEC CICS WRITE OPERATOR TEXT('GDS ALLOCATE failed') END-EXEC. CONNECTION-ERROR. EXEC CICS WRITE OPERATOR TEXT('GDS CONNECT PROCESS failed') END-EXEC. * Free conversation on connection error EXEC CICS GDS FREE CONVID(WS-CONVERSATION-ID) RESP(WS-RESPONSE) 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. FREE-ERROR. EXEC CICS WRITE OPERATOR TEXT('GDS FREE failed') END-EXEC.

Best Practices for GDS CONNECT PROCESS

1. Always Allocate Before Connecting

  • GDS CONNECT PROCESS requires an allocated conversation
  • Allocate with appropriate sync level for your use case
  • Check allocation response before attempting connection
  • Free conversation if allocation fails

2. Validate Process Names

  • Ensure process names match remote transaction IDs exactly
  • Verify process names are defined on remote system
  • Check authorization for remote processes
  • Use partner definitions for better maintainability

3. Handle PIP Data Carefully

  • Ensure PIP length matches actual data length
  • Format PIP data according to remote program expectations
  • Validate PIP data before sending
  • Document PIP structure for remote programs

4. Error Recovery

  • Always check RESP and RESP2 codes
  • Free conversations on all error paths
  • Log errors for troubleshooting
  • Implement retry logic for transient failures

5. Resource Management

  • Free conversations promptly after use
  • Don't leave conversations allocated unnecessarily
  • Monitor conversation usage
  • Implement timeout mechanisms

GDS CONNECT PROCESS vs GDS ALLOCATE

Understanding when to use each command:

  • GDS ALLOCATE: Establishes a conversation but doesn't start a remote program. Use when you need a conversation for general data exchange.
  • GDS CONNECT PROCESS: Starts a specific remote transaction program. Use when you need to invoke a particular remote application.
  • Combined Use: Typically, you allocate first, then connect to a specific process. This gives you control over which remote program runs.

Explain It Like I'm 5 Years Old

Imagine you want to play a game with your friend who lives in another house:

First, you need to call them on the phone to set up the connection (that's like GDS ALLOCATE - you're making the phone call). Once they answer, you say "Hey, let's play the INQUIRY game!" (that's like GDS CONNECT PROCESS - you're telling them which specific game to start).

When you say "let's play INQUIRY," your friend goes to get that specific game and gets ready to play (the remote computer starts the INQUIRY program). You might also tell them some rules before you start, like "I'm player USER001" (that's like sending PIP data - you're giving them information they need to start the game).

Once they're ready, you can start playing - taking turns asking questions and getting answers (that's like sending and receiving data). When you're done, you say "Goodbye" and hang up (that's like GDS FREE - you're ending the connection).

GDS CONNECT PROCESS is like telling your friend which specific game to start, while GDS ALLOCATE is just making the phone call. You need both to play together!

Exercises

Exercise 1: Basic Connection

Write a COBOL program that:

  • Allocates a GDS conversation with sync level 2
  • Connects to a remote process named 'INQUIRY'
  • Checks for errors and handles them appropriately
  • Frees the conversation when done

Hint: Follow the basic example above, but add comprehensive error handling for each step.

Exercise 2: Using PIP Data

Enhance your connection program to:

  • Send PIP data containing a user ID and request type
  • Validate PIP length matches data length
  • Handle PIP-related errors
  • Document the PIP structure

Exercise 3: Using PARTNER

Modify your program to:

  • Use PARTNER instead of PROCNAME/PROCLENGTH
  • Explain the advantages of using PARTNER
  • Compare PARTNER vs PROCNAME approaches

Answer: PARTNER provides centralized configuration, easier maintenance, and better security through resource definitions, while PROCNAME is more direct but requires code changes for different partners.

Quiz

Test Your Knowledge

1. What is the purpose of GDS CONNECT PROCESS?

  • A) To allocate a conversation
  • B) To initiate a remote application program
  • C) To send data to a remote system
  • D) To free a conversation

2. Which parameter is required when using PROCNAME?

  • A) PARTNER
  • B) PROCLENGTH
  • C) PIPLIST
  • D) RETCODE

3. What is the purpose of PIPLIST and PIPLENGTH?

  • A) To receive return codes
  • B) To pass initialization data to the remote process
  • C) To specify conversation state
  • D) To allocate the conversation

4. What should you do if GDS CONNECT PROCESS fails?

  • A) Try again immediately
  • B) Free the conversation and handle the error
  • C) Continue processing
  • D) Allocate a new conversation

5. What is the difference between PROCNAME and PARTNER?

  • A) PROCNAME is faster
  • B) PARTNER references a resource definition
  • C) PROCNAME is more secure
  • D) There is no difference