CL Programming

CHAPTER 1: INTRODUCTION

***

CL: Control Language – is a language that interfaces with the OS400

Is a command based language
CL programs consists of commands
Not a high level language
Compiler comes in build with the AS400 OS
Can be used:
1. At command line directly
2. In a batch program

CL Command: individual CL statement

CL Procedure: a CL program or group of CL statements

USE – automation and in batch process

LIMITATION – in file operation, can only perform READ, cannot WRITE or UPDATE

CHAPTER 2: A FIRST LOOK AT CL

***
 Default Source File – QCLLESRC / QCLSRC
 Default Source file type – CLLE

Program Structure:
PGM
DECLARATIONS – DCL, DCLF
GLOBAL MONMSG
BODY OF PROGRAM
ENDPGM

PGM:
 PGM PARM(&VAR-NAME1, &VAR-NAME2)
 PROGRAM COMMAND
 Indicates the beginning of CL
 PARM parameter is used to pass data to the program
 Source code can be free format or fixed format
  COMMAND PROMPTER can be used to enter command. Enter the command in any blank line
and press f4.
 Default is CAPS. Use SET CAPS ON / SET CAPS OFF to switch between uppercase and lower case

 COMMENT - /*………*/
 CONTINUATION - + or – (+ does not consider blanks before 1st character in next line, - does)

 To Compile – CRTBNDCL (LIB/PGM) SRCFILE (LIB/SRC)

 To Run – CALL (LIB/PGM) PARM (VALUE)

CHAPTER 3: CONSTANTS AND VARIABLES

***
Constants –
 Character
 Decimal
 Integer
 Hexadecimal
 Logical – always ‘0’ (false) or ‘1’ (true)
Always 1 byte
Always enclosed within single quotes

Variables –
DCL COMMAND:
 DECLARATION COMMAND
 Used to declare variables
 DCL VAR(&VAR_NAME) TYPE(*TYPE) LEN(LENGTH) VALUE(‘INITIAL-VALUE’)

&VAR_NAME –
 Name of the variable
 Max 11 bytes long including &

*TYPE –
 *CHAR: CHARACTER  MAX LEN 32767  DEFAULT LEN 32
 *DEC: DECIMAL  MAX LEN (15 9)  DEFAULT LEN (15 5)
 *INT: INTEGER  MAX LEN 4  DEFAULT LEN 4
 *UINT: UNSIGNED INTEGER  MAX LEN 4  DEFAULT LEN 4
 *LGL: LOGICAL  MAX LEN 1  DEFAULT LEN 1

IF LEN IS NOT SPECIFIED, DEFAULT LEN IS ASSUMED

IF LEN IS NOT SPECIFIED AND VALUE IS SPECIFIED, LENGTH OF ‘VALUE’ IS ASSUMED
SMALLER VARIABLE CAN BE MOVED TO LONGER VARIABLE

CHAPTER 4: BASIC OPERATORS

***
CHGVAR COMMAND:
 CHANGE VARIABLE COMMAND
 Used to assign new value to a variable
 CHGVAR VAR(&VAR_NAME) VALUE(NEW_VAL)
 &VAR_NAME – THE NAME OF VAR TO BE CHANGED
 NEW_VAL – CONSTANT / VARIABLE / EXPRESSION
EXPRESSION –
 ARITHMETIC - *, /, +, -
 LOGICAL - *NOT, *AND, *OR
 Can be used on logical variables only
 Used to manipulate result
 CHARACTER –
 *CAT – CONCATINATE 2 STRINGS AS IS
 *BCAT - CONCATINATE 2 STRINGS: 1 SPACE BETWEEN LAST CHAR OF 1ST AND 1ST CHAR
OF 2ND
 *TCAT - CONCATINATE 2 STRINGS: NO SPACE BETWEEN 1ST AND 2ND
 SUBSTRING FUNCTION - %SST(VAR, STARTING POS, LENGTH)

CVTDAT COMMAND:
 CONVERT DATE COMMAND
 Used to change the date from 1 format to another
 CVTDAT DATE(&VAR_NAME TO BE CONVERTED) TOVAR(&VAR_NAME TO STORE CONVERTED
RESULT) FROMFMT(*FORMAT) TOFMT(*FORMAT) TOSEP(*DATESEP)

CHAPTER 5: CONTROL STATEMENTS

***
CONDITIONAL –
IF:
 IF COND(EXP) THAN(CMD)
 EXPRESSION –
 SIMPLE –
 &VAR-NAME  NAME OF VARIABLE TO BE TESTED
 CONDITION  *EQ, *NE, *GT, *LT, *GE, *LE
  VALUE / ANOTHER &VAR-NAME
 COMPLEX –
 COMBINES 2 OR MORE SIMPLE EXPRESSIONS BY *NOT, *AND, *OR
 IF COND(EXP) THAN(DO)
CL CMD
ENDDO
 IF COND(EXP) THAN(CMD) ELSE(CMD)
 IF COND(EXP) THAN(DO)
CL CMD
ENDDO
ELSE(DO)
CL CMD
ENDDO
 Nesting can be done up to 10 levels

SELECT:
 SELECT
WHEN(EXP1) CMD1
WHEN(EXP2) CMD2
WHEN(EXP3)DO
CL CMD
ENDO
OTHERWISE CMD(CL COMMAND)
ENDSELECT

LOOPS –
DOWHILE: CHECKS BEFORE EXECUTION
 DOWHILE(EXP)
CL CMD
ENDDO

DOUNTIL: CHECKS AFTER EXECUTION

 DOUNTIL(EXP)
CL CMD
ENDDO

DOFOR: CHECKS BEFORE EXECUTION FOR A SPECIFIC NO OF TIMES

 DOFOR VAR(&VAR_NAME) FROM(VAL/VAR) TO(VAL/VAR) BY(VAL/VAR)
CL CMD
ENDDO
LOOP CONTROLS -
LEAVE – immediately leaves the loop
ITERATE – takes the control to the bottom of the loop
GOTO – takes the control to a particular level
 GOTO CMDLVL(LEVEL_NAME)

PROGRAM CONTROL –
CALL:
 CALL (LIB/PGM) PARM(‘VALUES’)
 IF VALUE IS PASSED THROUGH VARIABLE – THE VARIABLES IN BOTH CALLER AND CALLED
PROGRAM SHOULD BE SAME IN TERMS OF ‘TYPE’ AND ‘LEN’
 IF VALUE IS PASSED THROUGH CONSTANT – THE RECEIVING VARIABLE IN CALLED
PROGRAM SHOULD BE 32 FOR *CHAR, (15 5) FOR *DEC, 1 FOR *LGL

ENDPGM – ends the CL and returns control to caller

RETURN – returns control to caller, may not be end of the CL

TRFCLT:
 TRANSFER CONTROL COMMAND
 Works like CALL, but does not return the control to caller on ENDPGM or RETURN
 Cannot be used in ILE CL

6. MESSAGE MANAGEMENT
Message is a free format text communication between 2 entities like
 2 user
 2 programs
 A user and a program
Can be
 Impromptu
 Pre-defined

Message Q
 Permanent message Q
 Object of type *MSGQ
 CRTMSGQ – create MSGQ
 CHGMSGQ – change MSGQ
 Temporary message Q
 Job message Q
>> Object of type *EXT
>> is created when a job starts execution
>> remains active as long as the job executes
  Program message Q
>> Object of type *EXT
>> is created when a program is called
>> remains active as long as the program is in the call stack
 System permanent message Q – QSYSOPR

Types of messages:
1. Request *REQ request to execute a command to QSYS/QCMD
2. Inquiry *INQ
3. Reply *RPY
4. Completion *COMP
5. Diagnostic *DIAG
6. Escape *ESCAPE
7. Notify *NOTIFY
8. Status *STATUS
9. Information *INFO

Impromptu message:
 Message text is hardcoded in the CL source
 Cannot be *ESCAPE, *NOTIFY or *STATUS

Pre-defined message:
 Create a message file
CRTMSGF
CRTMSGF MSGF(lib/fname) TEXT(‘description’)
 Add pre-defined message
ADDMSGD
ADDMSGD MSGID(xxxnnnn)
MSGF(lib/fname)
MSG(‘text’)
SECLVL(‘text’)
SEV(nn)
FMT(*TYPE LEN)
MSG - message text
SECLVL - secondary message text to be displayed if F1 is pressed
SEV - error severity to display the message. Can be 00 to 99
FMT - type and length of placeholder variable. MSG(‘………..&1….’)
 CHGMSGD
 RMVMSGD
SNDPGMMSG:
 Send Program Message
 Can only be used in CL program, and not in command line
Impromptu message –
SNDPGMMSG MSG(‘Text’)
Pre-defined message –
SNDPGMMSG MSGID(xxxnnnn) MSGF(lib/msgf) MSGDTA(‘Text’)
MSGDTA – used to pass data to placeholder if any

TOPGMQ – send message to program message q

(*PRV *) - caller of the current program/ procedure
(*PRV name) - caller of the named program/ procedure
(*SAME *) - current program/ procedure
(*SAME name) - named program/ procedure
(*EXT *) - QSYSOPR

TOUSR – send message to user

*SYSOPR - to QSYSOPR
*REQUESTOR - to QSYSOPR in case of batch and to user in case of interactive
*ALL - all user logged in
Name

TOMSGQ – send message to message q

*EXT - QSYSOPR
Name

To send message to console:

SNDPGMMSG MSGID(CPF9898) MSGF(CPFMSG)
MSG(‘Text’)
TOPGMQ(*EXT)
MSGTYP(*STATUS)

To send Inquiry message and get a reply:

DCL VAR(&MSGKEY) TYPE(*CHAR) LEN(4)

SNDPGMMSG MSG(‘Text’) TOPGMQ(*EXT) MSGTYP(*INQ)

RPYMSGQ(*PGMQ)
KEYVAR(&MSGKEY)
RCVMSG MSGKEY(&MSGKEY) MSGTYP(*RPY) WAIT(*MAX)
MSG(&VAR to hold the reply)
SNDUSRMSG
 Send User Message
 Can only be used in CL program, and not in command line
 Can send only *INFO and *INQ messages
 Maximum msg len 512 and for console display 72
 Same as SNDPGMMSG
 Cannot use TOPGMQ. Only TOUSR and TOMSGQ

To send Inquiry message and get a reply:

SNDUSRMSG MSG(‘Text’) TOMSGQ(*EXT) MSGTYP(*INQ)
MSGRPY(&VAR)
VALUE(A B C D) DFT(A) TRNTBL(QSYSTRNTBL)

Command line commands:

1. SNDMSG – sends *INFO or *INQ messages
2. SNDBRKMSG - sends *INFO or *INQ messages. Stop user from current work and send the
message
3. SNDRPY – sends reply to a *INQ message

MONMSG
 Monitor Message command
 Monitors for error message and if found ignores

Command level MONMSG

CL command
MONMSG CPFnnnn
 Should immediately follow the command

Global MONMSG
DCL / DCLF
MONMSG CPF0000 EXEC(GOTO LBL)
 Should immediately follow DCL / DCLF

 1st preference in command level MONMSG

7. INTERPROGRAM COMMUNICATIONS
 Parameters
 Data Area
 Switches
 Messages
 Data Queue

PARAMETERS:
CALL PGM(lib/pgmname) PARM(A B C D)
Similarly can use
TRFCTL
CALLPRC
 Max 255 parameters

DATA AREA:
1. Create a Data Area
CRTDTAARA DTAARA(lib/dtaara_name) TYPE(*TYPE) LENGTH(length) VALUE(‘value’)
2. Change Data Area
CHGDTAARA DTAARA(lib/dtaara_name (str_pos len)) VALUE(var/cons)
3. Retrieve Data Area
RTVDTAARA DTAARA(lib/dtaara_name (str_pos len)) RTNVAR(&var_name)
4. Display – DSPDTAARA
5. Delete – DLTDTAARA
Special Data Area:
*LDA Local Data Area *CHAR 1054 for all jobs while execution
*GDA Group Data Area *CHAR 500 for Group jobs
*PDA Program Initialization parameter data area *CHAR 2000 for pre start jobs
 CRTDTAARA and DLTDTAARA is not allowed for special data areas
 Special data area can also accessed by using %SST as
CHGVAR %SST(*LDA str_pos length)

SWITCHES:
 Each job is assigned 8 bytes switches
 1 – ON
0 – OFF
X – no change
1. Change Switch
CHGJOB SWS(‘1XXXXXXX’)
2. Retrieve switch
DCL VAR(&SWITCH) TYPE(*CHAR) LENGTH(8)
RTVJOBA SWS(&SWITCH)
 3. Test Switch
IF COND(&SWITCH *EQ ‘value’)
Or
IF COND(%SWITCH *EQ (value))

MESSAGES:
1. Sending program –
Sends message text to a named program
SNDPGMMSG MSG(‘Text’)
TOPGMQ(*SAME NAME)
MSGTYP(*INFO)
Sends message to QSYSOPR
SNDPGMMSG MSG(‘Text’)
TOMSGQ(*SYSOPR)
MSGTYP(*INFO)
2. Receiving program –
RCVMSG MSGTYP(*INFO)
WAIT(*MAX)
MSG(&VAR)

DATA QUEUE:
 Object of type *DTAQ
 Not very useful as:
 Complex coding
 Data is lost once retrieved. So if program ab ends data is lost permanently
 File better option

8. SYSTEM INTERFACE
1. ADD / REMOVE LIBRARY LIST ENTRY
ADDLIBLE library [POSITION *FIRST]
*LAST
*AFTER library
*BEFORE library
*REPLACE LIBRARY
RMVLIBLE
 2. RETRIEVE / CHANGE SYSTEM VALUE
RTVSYSVAL QDATE(&VAR)
QTIME
QDAY
QMONTH
QYEAR
QHOUR
QMIN
QSECONDS
CHGSYSVAL QDATE(‘MMDDYY’)

3. RETRIEVE JOB ATTRIBUTES

RTVJOBA JOB(&VAR)  Job name
SWS  Switches
RUNPTY  run priority

4. RETRIEVE USER PROFILE

RTVUSRPRF USRPRF(*CURRENT) TEXT(&VAR)

9. FILES
DCLF:
 Declare File command
DCLF FILE(lib/fname) [RCDFMT(record format) OPNID(X)]
*ALL *NONE
Optional parameters –
1. RCDFMT
 Record format name
 Useful for files with multiple record format
 Useful for display files
 *ALL – Default: refers all record formats
2. OPNID
 Prefix
 *NONE – Default
 If used, file field is referenced as
&X_file field
If a file is created without using a DDS
CRTPF FILE(lib/fname) RCDLEN(nnn)
 File field name - &fname
 File field length – nnn
RCVF:
 Receive File command
 Used to retrieve/ read a file
RCVF [DEV(device) RCDFMT(record format) OPNID(X) WAIT(*YES)
*FILE *ALL *NONE *NO
Optional parameters –
1. DEV
 Device name
 *FILE –Default
 Used for display file
2. WAIT
 Used for display file
 *YES – wait for user response / *NO – do not wait

Sequential Read:
 Execute RCVF in a loop
 End of file – CPF(0864)
Random Read:
OVRDBF lib/fname POSITION(*RRN rrn-no)
(*KEYA no. of keys record format ‘value’)
*KEYB 0 *N
RCVF

SNDRCVF:
 Send Receive File command
 Works like EXFMT
DCLF FILE(lib/fname)
SNDRCVF RCDFMT

PHYSICAL FILE:
 Create
CRTPF
CRTPF FILE(lib/fname) RCDLEN(nnn)
 Delete
DLTF

PHYSICAL FILE / LOGICAL FILE MEMBER:

 A physical file / logical file can have many member
 Useful if one file is used in multiple jobs for multiple output
 Add
 ADDPFM
ADDLFM
ADDPFM FILE(lib/fname) MBR(name)
 Change
CHGPFM
CHGLFM
 Delete (remove member)
RMVM
 Clear
CLRPFM
 Re-organize
RCZPFM

OVRDBF:
 Override Database File command
 Used for positioning to a record for random read
OVRDBF lib/fname POSITION(*RRN rrn-no)
(*KEYA no. of keys record format ‘value’)
*KEYB 0 *N
RCVF
 Used to use the same file at a different library
OVRDBF lib/fname TOFILE(QTEMP/fname)

OPNQRYF:
 Open Query File command
 Used to run a query and create a temp input file
OVRDBF lib/fname SHARE(*NO)
OPNQRYF lib/fname QRYSLT(ffield *EQ ‘value’) +
KEYFLD((ffield1) (ffield2))
CALL
CLOF lib/fname
DLTOVR lib/fname
*ALL

QTEMP – temporary library that is created when the job starts and deleted when job ends

10. QUOTES
 Constants – ‘….’
 Constants with quotes – ‘……’’..’
11. MANAGING OBJECTS
Create Object:
CRTxxxx

Delete Object:
DLTxxxx

Check Object:
CHKOBJ
 Checks if the object is present in the library
 If not present, issue error message
CHKOBJ OBJ(lib/obj_name) TYPE(*type)
CHKOBJ OBJ(lib/fname) TYPE(*FILE) MBR(member_name)
 CPF9801 - object not present
 CPF9010 - library not present
 CPF9815 - member not present

Retrieving Object Description:

RTVOBJD
DCL &OBJ *CHAR 10
DCL &OBJTYP *CHAR 10
DCL &RTNLIB *CHAR 10
RTBOBJD &OBJ &OBJTYP RTNLIB(&RTNLIB)
 Returns the name of library where the object is present

Copying Object:
CRTDUPOBJ

Moving Object:
MOVOBJ

Renaming Object:
RNMOBJ

Change Object Description:

CHGOBJD

Allocate Object:
 Allocate an Object, usually a file to a job
 Used to lock the file
 Useful for situations where same file is used by both interactive and batch job
ALCOBJ OBJ(lib/fname *FILE *lock_type) WAIT(*YES/*NO)
DLCOBJ OBJ(lib/fname *FILE *lock_type)

Lock Types:
 EXCL - Exclusive
 EXCLRD - Exclusive Read only
 SHRUPD - Share with Update
 SHRNUP - Share No update

12. BATCH JOBS

SBMJOB:
 Submit Job command
 Use to run a Cl command in batch
SBMJOB CMD(command)  CL command like – CALL PGM(pgm) PARM(A B C)
JOB(job_name)  Job name / Program name / JOBD
JOBQ(QBATCH)  QBATCH / JOBD
JOBD(description)  description / USRPRF

 Can use RQSDTA in place of CMD

CMD RQSDTA
 Can code command directly can code command within quotes
 Prompter can be used for command prompter cannot be used
 Command hardcoded command can be with a variable

Once the Batch Job is submitted, to monitor the job:

WRKSBMJOB - work with submitted job - jobs submitted by current user
WRKUSRJOB - work with user name job
WRKSBSJOB - work with subsystem job - usualy QBATCH
WRKACTJOB - work with active job

To see error message in case a batch job Ab-ends:

DSMMSG MSGQ(QSYSOPR) MSGTYP(*INQ)