Day-27.

CL Programming:

 Overview:

This module enables the student to understand the concept of File Handling in CL.

Outline:

Topics covered,

·         File Handling

·         TFRCTL

Objective:

By the end of this module, the student should be able to:

·         File Handling

·         TFRCTL

 File Handling:

Two types of files are supported in CL programs, display files and database files. You can send data to a workstation and receive input from the workstation and receive input from the workstation for use in the program, or you can read from a database file in the program.

The following statements apply only to database files used with CL programs:

·          A CL program may use only database files with a single record format.

·          The file may be either a physical of or logical file, and a logical file may be defined over multiple physical file members.

·          Only input operations, with the RCVF command, are allowed. The SNDF, SNDRCVF commands are not allowed for database files.

·          DDS is not required to create a physical file, which is referred to in a CL program. If DDS is not used to create a physical file, the file has a record format with the same name as the file, and there is one field in the record format with the same name as the file, and with the same length as the record length of the file (RCDLEN parameter of the CRTPF command).

·          The file need not have a member when it is created for the program. It must, however, have a member when the program processes the file.

·          The file is opened for input only when the first RCVF command is processed. The file must exist and have a member at that time.

·          The file remains open until the program returns or when the end of file is reached. When end of file is reached, message CPF0864 is sent to the CL program, and additional operations are not allowed for the file. The program should monitor for this message and take appropriate action when end of file is reached.

·          The database file is read in arrival sequence.

·          We can write a query on database file in CL Program using command OPNQRYF.

The following statements apply only to display files used with CL programs:

·          Display files may have up to 99 record formats.

·          All data manipulation commands (SNDF, SNDRCVF, RCVF) are allowed for display files.

·          The display file must be defined with the DDS.

·          The display file is opened for both input and output when the first SNDF, SNDRCVF, or RCVF command is processed. The file remains open until the program returns.

Note: The open does not occur for both types of files until the first send or receive occurs.

Opening and Closing Files in a CL Procedure

When you use CL support, you can refer to only one file in a program. The file referred to is implicitly opened when you do your first send, receive, or send/receive operation. An opened display file remains open until the program in which it was opened returns or transfers control. An opened database file is closed when end of file is reached, or when the program in which it was opened returns or transfers control. Once a database file has been closed, it cannot be opened again during the same call of program.

When a display file is opened in a CL programs, it is always opened for both input and output. When a database file is opened in a CL program, it is opened for input only.

Referring to Files in a CL Procedure

Files are accessed during compiling of DCLF commands when CL program is created. If you have qualified the name of the file at compile time, the file must be in a library at run time. If you have used the library list at compile time, the file must be in a library on the library list at run time.

Declaring a File

The Declare File (DCLF) command is used to declare a display or database file to your CL procedure or program. The DCLF command cannot be used to declare files such as tape, diskette, printer, and mixed files. Only one DCLF command id allowed in a CL program.

The DCLF command has the following parameters:

o      DCLF FILE (library-name/file-name)

o      RCDFMT (record-format-names)

Note that the file must exist before the program is compiled. If you are using a file in your program you may have to specify input/output fields in your DDS. These fields are handled as variables in the program. When a DCLF command is used, the CL compiler declares CL variables for each field and option indicator in each record format in the file. For a field, the CL variable name is the indicator preceded by & IN.

For example, if a field named INPUT and indicator 10 are defined in DDS, the DCLF command automatically declares them as &INPUT and &IN 10. This declaration is performed when the CL module or program is compiled. Up to 50 record format names can be specified on one command, But none can be variables. Only one record format may be specified for a database file.

If the following DDS were used to create display file CNTRLDSP in library MCGANN:

Three variables viz. &IN01, &TEXT and &RESPONSE would be available from the display file. In a CL procedure referring to this display file, you would enter only the DCLF source statement:

DCLF PB01U01S/CLP1

The compiler will expand this statement to individually declare all display file variables.

The expanded declaration in the compiler list looks like:

Sending and Receiving Data with a Display File

The only commands you can use with a display file to send or receive data in CL programs are the SNDF, RCVF and SNDRCVF commands.

When you run an SNDF command the content of the variables associated with the output or out/input fields in the record format you specify is formatted by system and sent to the display device. Similarly, when you run an RCVF command, the values of the fields associated with input or output /input fields in the record format on the display are placed in the corresponding CL variables.

The SNDRCVF command sends the contents of the CL variables to the display and then performs the equivalent of an RCVF command to obtain the updated fields from the display.

Lab Session:

In following example we will see how to use workstation file in CL program. This is simple calculation program:

Following is the DDS where we use calculations:

Columns . . . :    1  71            Edit                         PB01U01D/MYDDS

 SEU==>                                                                  DSPCAL

        *************** Beginning of data *************************************

0000.10      A*%%TS  SD  20050312  170110  PB01U01     REL-V5R2M0  5722-WDS    

0000.20      A*%%EC                                                            

0000.30      A                                      DSPSIZ(24 80 *DS3)         

0000.40      A          R REC1                                                  

0000.50      A*%%TS  SD  20050312  170110  PB01U01     REL-V5R2M0  5722-WDS    

0000.60      A                                      CF03(03 'exit')            

0000.70      A                                      CF04(04 'cat')             

0000.80      A                                      CF05(05)                   

0000.90      A                                      CF06(06)                   

0001.00      A                                  3 25'CAT Opraters'             

0001.10      A                                  7 14'First No   :'             

0001.20      A                                 10 14'Second No  :'             

0001.30      A                                 13 14'Result :'                  

0001.40      A                                 17 15'F3:Exit'                  

0001.50      A            FNO            5S 0B  7 30                           

0001.60      A            SNO            5S 0B 10 30                           

0001.70      A            RES            7S 0B 13 30                           

0001.80      A                                  8 43'Opc :'                    

0001.90      A            OPT            1A  B  8 50                           

        ****************** End of data ****************************************

                                                                               

Now In CL program how to declare file using DCLF as discussed above-

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                    CALCI

        *************** Beginning of data *************************************

0001.00 /*PROGRAM : SETMYLIBL*/                                                 

0002.00 PGM 

0002.01 /* DECLARE THE WORKSTATION FILE */                                                                                                        

''''''' DCLF                                                                    

        ****************** End of data ****************************************

                                                                               

                                                                                                                                                  

Press F4 AND write Filename, Library name, Record format name as given below,

                                                                             Declare File (DCLF)                             

                                                                               

 Type choices, press Enter.                                                    

                                                                                

 Label  . . . . . . . . . . . . .                                              

 File . . . . . . . . . . . . . .   DSPCAL        Name                         

   Library  . . . . . . . . . . .     PB01U01O    Name, *LIBL, *CURLIB         

 Record format  . . . . . . . . .   REC1          Name, *ALL                   

                + for more values                                              

 Allow variable length fields . .   *NO           *NO, *YES                    

 Allow field value of null  . . .   *NO           *NO, *YES                    

 Allow graphic fields . . . . . .   *NO           *NO, *YES                    

 Comment  . . . . . . . . . . . .                                               

                                                                               

                                                                                                                                                  

                                                                               

                                                                         Bottom

 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display   

 F24=More keys                                                                 

                                                                               

Press enter,

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                   CALCI

        *************** Beginning of data *************************************

0001.00 /*PROGRAM : SETMYLIBL*/                                                

0002.00 PGM 

0002.01 /* DECLARE THE WORKSTATION FILE */                                                                                                        

0003.00              DCLF       FILE(PB01U01O/DSPCAL) RCDFMT(REC1)             

'''''''                                                                         

        ****************** End of data ****************************************

                                                                               

                                                                                                                                                    

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                  CALCI

        *************** Beginning of data *************************************

0001.00 /*PROGRAM : SETMYLIBL*/                                                

0002.00 PGM                                                                     

0002.01 /* DECLARE THE WORKSTATION FILE */                                     

0003.00              DCLF       FILE(PB01U01O/DSPCAL) RCDFMT(REC1)             

0004.00 /* EXECUTE THE RECORD FORMAT OF DISPLAY SCREEN */                      

''''''' SNDRCVFMT                                                              

        ****************** End of data ****************************************

                                                                                                                                                  

Press F4 and enter the RECORD format name

                                                                   Send/Receive File (SNDRCVF)                         

                                                                                

 Type choices, press Enter.                                                    

                                                                               

 Label  . . . . . . . . . . . . .   A                                           

 Display device . . . . . . . . .   *FILE         Name, *FILE                  

 Record format  . . . . . . . . .   REC1          Name, *FILE                  

 Wait . . . . . . . . . . . . . .   *YES          *YES, *NO                    

 Comment  . . . . . . . . . . . .                                              

                                                                                                                                                        

                                                                               

                                                                         Bottom

 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display   

 F24=More keys                                                                 

                                                                               

Hit enter,

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                  CALCI

        *************** Beginning of data *************************************

0001.00 /*PROGRAM : CALCI */                                                

0002.00 PGM                                                                    

0002.01 /* DECLARE THE WORKSTATION FILE */                                     

0003.00              DCLF       FILE(PB01U01O/DSPCAL) RCDFMT(REC1)             

0004.00 /* EXECUTE THE RECORD FORMAT OF DISPLAY SCREEN */                      

0005.00  A:          SNDRCVF    RCDFMT(REC1)                                   

        ****************** End of data ****************************************

                                                                         

And do the following coding as shown below:

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                    CALCI

        *************** Beginning of data *************************************

0001.00 /*PROGRAM : CALCI*/                                                 

0002.00 PGM                                                                    

0002.01 /* DECLARE THE WORKSTATION FILE */                                     

0003.00              DCLF       FILE(PB01U01O/DSPCAL) RCDFMT(REC1)             

0004.00 /* EXECUTE THE RECORD FORMAT OF DISPLAY SCREEN */                      

0005.00  A:          SNDRCVF    RCDFMT(REC1)                                   

0006.00              IF         COND(&IN03 = '1') THEN(GOTO CMDLBL(B))         

0007.00              ELSE       CMD(IF COND(&OPT = '+') THEN(CHGVAR +          

0008.00                           VAR(&RES) VALUE(&FNO + &SNO)))               

0009.00              ELSE       CMD(IF COND(&OPT = '-') THEN(CHGVAR +          

0010.00                           VAR(&RES) VALUE(&FNO - &SNO)))               

0011.00              ELSE       CMD(IF COND(&OPT = '*') THEN(CHGVAR +          

0012.00                           VAR(&RES) VALUE(&FNO * &SNO)))               

0013.00              ELSE       CMD(IF COND(&OPT = '/') THEN(CHGVAR +          

0014.00                           VAR(&RES) VALUE(&FNO / &SNO)))               

0015.01              ELSE       CMD(CHGVAR VAR(&RES) VALUE(0))                 

0016.00              GOTO       CMDLBL(A)                                       

0017.00  B:          ENDPGM                                                    

        ****************** End of data ****************************************

                                                                                                                                                          

In this way file handling is done in CL. Only one file can be handle at a time either workstation file or database fie.

Transfer Control:

The Transfer Control (TFRCTL) command calls the program specified on the command, passes control to it, and removes the transferring program from the call stack. Reducing the number of programs on the call stack can have a performance benefit. When a CALL command is used, the program called returns control to the program containing the CALL command. When a TFRCTL command is used, control returns to the first program in the call stack. The first program then initiates the next sequential instruction following the CALL command. The TRFCTL command is not valid in ILE CL: procedures. The TFRCTL command can be used to pass parameters to the program being called in the same way the CALL command passes parameters, but with these restrictions:

o      The parameters passed must be CL variables.

o      The CL variables passed by the transferring program must have been received as parameters by that program.

o      This command is valid only within OPM CL programs.

Following example contains the transfer control example-

Steps 1: This step contain TFR1 where we call TFR2 and  checks the control of program:        

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                    TFR2

        *************** Beginning of data *************************************

0001.00 PGM                                                                     

0002.00              DCL        VAR(&CITY) TYPE(*CHAR) LEN(10) VALUE(MUMBAI)   

0003.00              SNDUSRMSG  MSG('object exist-----')                          

0004.00              CALL       PGM(PB01U01S/ TFR2) PARM(&CITY)                    

0005.00              SNDUSRMSG  MSG('control back---- ' *cat (&CITY))          

0006.00 ENDPGM                                                                 

        ****************** End of data ****************************************

                                                                                                        

CALL & RETURN Commands:

You can use the CALL and RETURN commands to pass control back and forth between programs. Information may be passed to called programs as parameters when control is passed. The CALL command calls a program named on the command, and passes control to it. When the called program finishes running, control returns to the next command in the calling program. The sequence of CALL commands in a set of programs calling each other is the call stack. A maximum of 40 parameters can be passed to the called program.

Because parameters are passed by position, not name , the position of the value passed in the CALL command must be the same as its position on the receiving PGM command. In addition to the position of the parameters, You must pay careful attention to their length and type, Parameters listed in the receiving procedure of program must be declared as the same length and type as they are in the calling procedure or program. Referring to locally defined variables incurs fewer overheads than referring to passed variables. Therefore, if the called procedure or program frequently refers to passed variables and referring to the locally defined value rather than the passed value. The names of the variables passed do not have to be same as the names on the receiving parameter list. The names of the variables receiving the values in the called program must be declared to the called program, but the order of the declare commands is not important. When a variable is passed, the called program can change the value of the variable, and the change is reflected in the calling program. The new value does not have to be returned to the calling program. The new value does not have to be returned to the calling program for later use; it is already there. Thus no special coding is needed for a variable that is to be returned to the calling program.

Parameters can be passed and received as follows:

·          Character string constants of 32 bytes or less are always passed with a length of 32 bytes (padded on the right with blanks). If a character constant is longer than 32 bytes, the entire length of the constant is passed.

·          Decimal constants are always passed in a packed form with a length of 15 with 5 decimal places.

Logical constants are passed with a length of 32 bytes. The logical value 0 or 1 is in the first byte, and the remaining bytes are blank.

Step 2: we will transfer control in to third program TFR3

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                    TFR2

        *************** Beginning of data *************************************

0001.00              PGM        PARM(&PRM1)                                    

0002.00              DCL        VAR(&PRM1) TYPE(*CHAR) LEN(10)                 

0003.00              DCL        VAR(&VAR1) TYPE(*CHAR) LEN(10) VALUE(PUNE)     

0004.00              SNDUSRMSG  MSG('control in second program_____' *cat &PRM1)   

0005.00              CHGVAR     VAR(&PRM1) VALUE(&VAR1)                        

0006.00              TFRCTL     PGM(PB01U01S/ TFR3) PARM(&PRM1)                    

0007.00 ENDPGM                                                                 

        ****************** End of data ****************************************

                                                                               

Step 3:

Columns . . . :    1  71            Edit                         PB01U01S/MYCLP

 SEU==>                                                                    TFR3

        *************** Beginning of data *************************************

0001.00              PGM        PARM(&PRM1)                                    

0002.00              DCL        VAR(&PRM1) TYPE(*CHAR) LEN(10)                 

0003.00              DCL        VAR(&VAR1) TYPE(*CHAR) LEN(10) VALUE(PUNE1)    

0004.00              SNDUSRMSG  MSG('control in THIRD program_____' *cat &PRM1)    

0006.00              CHGVAR     &PRM1 &VAR1                                    

0007.00              RETURN                                                    

0008.00 ENDPGM                                                                  

        ****************** End of data ****************************************

                                                                                                                                              

Compile above program see the output call TFR1 which call the program TFR2 and TFR2 sends the control In third program TFR3. The output of above program is given below which shows you how the control moves between programs.

                                                          Display Program Messages                            

                                                                                

 Job 089841/PB01U03/ABC started on 04/04/05 at 10:44:37 in subsystem QINTER i  

 control in second program_____MUMBAI                                              

 *N                                                                             

 control in THIRD program_____PUNE                                                 

 *N                                                                            

 control back---- PUNE1                                                         

                                                                               

                                                                                                                                                           

                                                                                

 Type reply, press Enter.                                                      

   Reply . . .                                                                 

                                                                                

                                                                               

 F3=Exit   F12=Cancel