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.
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:
The basic syntax for GDS CONNECT PROCESS in COBOL:
1234567891011121314EXEC 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.
Understanding each parameter is crucial for using GDS CONNECT PROCESS effectively:
The conversation identifier obtained from a previous GDS ALLOCATE command:
The name of the remote application program to be initiated:
The length of the process name:
An alternative to PROCNAME/PROCLENGTH that references a partner definition:
Specifies the desired synchronization level for the conversation:
A 24-byte area that receives conversation-related information:
Data to be sent to the remote process during initialization:
The total length of the PIP list:
A 6-byte area that receives return code information:
Retrieves the current state of the conversation after the command:
Here's a simple example showing how to connect to a remote process:
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859IDENTIFICATION 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.
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:
123456789101112131415161718192021222324252627282930313233WORKING-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 PARTNER parameter provides an alternative way to specify the remote process by referencing a partner definition:
1234567891011121314151617181920212223WORKING-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:
The STATE parameter allows you to check the conversation state after connecting:
12345678910111213141516171819202122232425262728293031WORKING-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.
Proper error handling is critical when connecting to remote processes:
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758WORKING-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.
Understanding response codes helps diagnose connection issues:
Here's a complete example showing the full lifecycle from allocation to connection:
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125IDENTIFICATION 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.
Understanding when to use each command:
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!
Write a COBOL program that:
Hint: Follow the basic example above, but add comprehensive error handling for each step.
Enhance your connection program to:
Modify your program to:
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.
1. What is the purpose of GDS CONNECT PROCESS?
2. Which parameter is required when using PROCNAME?
3. What is the purpose of PIPLIST and PIPLENGTH?
4. What should you do if GDS CONNECT PROCESS fails?
5. What is the difference between PROCNAME and PARTNER?