Coding a CICS online program in PL/I

The following code example is a skeleton CICS® online program in PL/I. It shows you how to define and establish addressability to the UIB.

The numbers to the right of the program refer to the notes that follow. This kind of program can run in a CICS environment using DBCTL.

Sample call-level PL/I program (CICS online)

 PLIUIB: PROC OPTIONS(MAIN);                                                	NOTES
  DCL PSB_NAME CHAR(8) STATIC INIT('PLIPSB  ');                           	 1 
  DCL PCB_FUNCTION CHAR(4) STATIC INIT('PCB ');                
  DCL TERM_FUNCTION CHAR(4) STATIC INIT('TERM');               
  DCL GHU_FUNCTION CHAR(4) STATIC INIT('GHU ');
  DCL REPL_FUNCTION CHAR(4) STATIC INIT('REPL');
  DCL SSA1 CHAR(9) STATIC INIT('AAAA4444 ');                              	 2 
  DCL PARM_CT_1 FIXED BIN(31) STATIC INIT(1);                  
  DCL PARM_CT_3 FIXED BIN(31) STATIC INIT(3);                  
  DCL PARM_CT_4 FIXED BIN(31) STATIC INIT(4);
  DCL GOOD_RETURN_CODE BIT(8) STATIC INIT('0'B);
  DCL GOOD_STATUS_CODE CHAR(2) STATIC INIT('  ');
  %INCLUDE DLIUIB;                                                        	 3 
  DCL 1 PCB_POINTERS BASED(UIBPCBAL),                                     	 4 
        2 PCB1_PTR POINTER; 
  DCL 1 DLI_IO_AREA,                                                      	 5 
        2 AREA1 CHAR(3),                                       
        2 AREA2 CHAR(37);
  DCL 1 PCB1 BASED(PCB1_PTR),                                            	 6 
        2 PCB1_DBD_NAME CHAR(8),                               
        2 PCB1_SEG_LEVEL CHAR(2),                              
        2 PCB1_STATUS_CODE CHAR(2),                            
        2 PCB1_PROC_OPTIONS CHAR(4),
        2 PCB1_RESERVE_DLI FIXED BIN (31,0),
        2 PCB1_SEGNAME_FB CHAR(8),
        2 PCB1_LENGTH_FB_KEY FIXED BIN(31,0),
        2 PCB1_NUMB_SENS_SEGS FIXED BIN(31,0),
        2 PCB1_KEY_FB_AREA CHAR(17);
      /* SCHEDULE PSB AND OBTAIN PCB ADDRESSES */
CALL PLITDLI (PARM_CT_3,PCB_FUNCTION,PSB_NAME,UIBPTR);                    	 7 
IF UIBFCTR = GOOD RETURN CODE THEN DO;
   /* ISSUE DL/I CALL: GET A UNIQUE SEGMENT */
   CALL PLITDLI (PARM_CT_4,GHU_FUNCTION,PCB1,DLI_IO_AREA,SSA1);           	 8 
   IF UIBFCTR = GOOD_RETURN_CODE& PCB1_STATUS_CODE = GOOD_STATUS_CODE THEN DO;	 9 
      /* PERFORM SEGMENT UPDATE ACTIVITY */
 	   AREA1 = ......;
 	   AREA2 = ......; 
	   /* ISSUE DL/I: REPLACE SEGMENT AT CURRENT POSITION */
      PLITDLI (PARM_CT_3,REPL_FUNCTION,PCB1,DLI_IO_AREA);               		 10 
	   IF UIBFCTR ^= GOOD_RETURN_CODE
		   | PCB1_STATUS_CODE ^= GOOD_STATUS_CODE THEN DO;    
		   /* INSERT REPL ERROR DIAGNOSTIC CODE */ 
	   END;
   END; 
   ELSE DO;  
      /* INSERT GHU ERROR DIAGNOSTIC CODE */ 
   END; 
END;
ELSE DO;   
   /* ANALYZE UIB PROBLEM */
   /* ISSUE UIB DIAGNOSTIC MESSAGE */
END;  
/* RELEASE THE PSB */ 
CALL PLITDLI(PARM_CT_1,TERM_FUNCTION);                                    	 11 
EXEC CICS RETURN;                                                         	 12  
END PLIUIB;

Note:

Each of these areas defines the DL/I call functions the program uses. Each character string is defined as four alphanumeric characters and has a value assigned for each function. You can define other constants in the same way. You can store standard definitions in a source library and include them by using a %INCLUDE statement.
A structure definition defines each SSA the program uses. The unaligned attribute is required for SSA. The SSA character string must reside contiguously in storage. If a call requires two or more SSA, you may need to define additional areas.
The %INCLUDE DLIUIB statement will be expanded.
The UIB returns the address of an area containing the PCB addresses. The definition of PCB pointers is necessary to obtain the actual PCB addresses. Do not alter the addresses in the area.
The I/O areas that are used to pass segments to and from the database are defined as structures.
The PCBs are defined based on the addresses that are passed in the UIB.
The PCB call schedules a PSB for your program to use.
This unqualified GHU call retrieves a segment from the database. The segment is placed in the I/O area that is referenced in the call. Before issuing the call, the program must initialize the key or data value of the SSA so that it specifies the particular segment to be retrieved.
CICS online programs must test the return code in the UIB before testing the status code in the DB PCB.
The REPL call replaces the segment that was retrieved in the most recent Get Hold call. The I/O area that is referenced in the call contains the segment to be replaced.
The TERM call terminates the PSB that the program scheduled earlier.
The program issues the EXEC CICS RETURN statement when it has finished processing.

Related reading: For more information about installing application programs, see CICS Transaction Server for z/OS® CICS Application Programming Guide.