1 Intro to the AS/400 Chapter 5 - CL Programming Copyright 1999 by Janson Industries

2 Objectives n Explain general programming concepts n Explain CL’s strengths and weaknesses as a programming language n Show how to create a CL program n Explain what a compilation report is and how to use it to find program errors

3 Creating CL Programs Library PF-SRC CRTMBR CLP Compile CRTMBR *PGM CLP SEU Programmer CL Commands

4 Programs n Programs are comprised of many programming language instructions n Instructions are written on lines or statements. n Each statement/line in a member is assigned a statement/line number. n CL commands (instructions) can span many lines

5 Program Processing n Programs can execute instructions 3 ways n The default method is sequential, I.e. in statement number order n Execution can also be conditional and iterative.

6 CL Command Syntax n The format for a CL Command is: n There is at least one space between the: u Command u First parameter u Each succeeding parameter n Commands are continued from one line to another by placing a plus sign after the command or a parameter COMMAND PARAMETER PARAMETER ….

7 CL Command Syntax n The + must be preceded by at least a space if the continuation is between: u a command and a parameter u two parameters COMMAND + PARAMETER PARAMETER COMMAND+ PARAMETER PARAMETER COMMAND PARAMETER PARAMETER + PARAMETER PARAMETER + PARAMETER COMMAND PARAMETER PARAMETER+ PARAMETER PARAMETER

8 Continuing a CL Command COMM+ AND PARAMETER PARMETER COMMAND PARAMETER PARA+ METER COMM + AND PARAMETER PARMETER COMMAND PARAMETER PARA + METER n The + is not preceded by space(s) if the continuation is in the middle of the: u Command word u Parameter keyword

9 Continuing a CL Command n If a parameter value(s) allows spaces, then the + is preceded by space(s) GRTOBJAUT OBJ(YOURLIBXX/CLSRC) OBJTYPE(*FILE) + USER(INTRO35) AUT(*OBJALTER *OBJEXIST + *OBJMGT *OBJOPR *OBJREF *ADD) SNDMSG MSG('The rain in Spain falls manely on the + lions.') TOUSR(INTRO99)

10 Continuing a CL Command n If the continuation is in the middle of a value, no spaces precede the + GRTOBJAUT OBJ(YOURLIBXX/CLSRC) OBJTYPE(*FILE) + USER(INTRO35) AUT(*OBJALTER *OB+ JEXIST *OBJMGT *OBJOPR *OBJREF *ADD) GRTOBJAUT OBJ(YOURLIBXX/CLSRC) OBJTYPE(*FILE) + USER(INTRO35) AUT(*OBJALTER *OB + JEXIST *OBJMGT *OBJOPR *OBJREF *ADD)

11 CL Programs n Begin with a PGM command and end with an ENDPGM command n Comments (non-executable text) may precede the PGM statement n Comments begin with a forward slash & an asterisk and end with an asterisk & a forward slash /* This is an example of a comment. */

12 Programs n Programs read and write data n Data can come from storage, the OS, or the person who calls the program n Programs can write data to storage, a printer or a workstation Program Storage Operating System User Printout Data

13 User Supplied Program Data n You can supply data when calling the program as follows: n To receive the data, the program must have a PARM keyword in the PGM statement. n The PARM keyword identifies the program variables that will hold the data CALL pgm1 (‘chardata’ numeric ‘chardata’….) PGM PARM(&CUSTNAME &ORDAMT)

14 User Supplied Program Data n The parameters specified on the call must match the parameters specified in the PARM keyword n If they don’t match: CALL pgm1 (‘Walmart’ 275) PGM PARM(&CUSTNAME &ORDAMT) CALL pgm1 (275) Parameters passed on CALL do not match those required. The program will not be run and you will get the following message:

15 Program Variables n Programs store input and output in program variables n Just like a data base field, a program variable has a: u Name u Length u Data type n Program variables exist for as long as the program is running

16 CL Program Variables n Are defined with a DCL (declare) command n A CL program variable name must: u Begin with an ampersand (&) u Has a max length of 11 u Cannot contain spaces n DCL statements must be at the beginning of the program following the PGM statement *************** Beginning of data ********************** PGM PARM(&CUSTNAME &ORDAMT) DCL VAR(&CUSTNAME) TYPE(*CHAR) LEN(15) DCL VAR(&ORDAMT) TYPE(*DEC) LEN(9 2)

17 Retrieving Data from OS/400 n RTVSYSVAL - retrieves and stores system parameter values in program variables: F Date F Time F System Default Printer n RTVJOBA - retrieves and stores job information in program variables: F Job name F User running job F Output queue RTVSYSVAL SYSVAL(QTIME) RTNVAR(&CURTIME) RTVJOBA USER(&USERID)

18 Sending Data to a User n SNDUSRMSG - sends a message to the person running the program or a specified users message queue n You can build complex messages combining static text and program variables by using string functions SNDUSRMSG MSG('I''ll be back') SNDUSRMSG MSG(&CUSTNAME) MSGTYPE(*INFO) + TOUSR(INTRO99)

19 String Functions n Concatenation - joins two strings together u *CAT u *TCAT - eliminates trailing spaces u *BCAT - one trailing space between strings n Results in: SNDUSRMSG MSG('I''ll be back at ’ *CAT &CURTIME) SNDUSRMSG MSG('I''ll be back at ’ *TCAT &CURTIME) SNDUSRMSG MSG('I''ll be back at ’ *BCAT &CURTIME) I'll be back at 14:09:08

20 String Functions n Substring - identifies a subset of a string u %SST(string start-location size) n When used with a CHGVAR command, new strings can be created. n Results in: CHGVAR VAR(&NOSECTIME) VALUE(%SST(&CURTIME 1 5) SNDUSRMSG MSG('I''ll be back at ’ *BCAT &NOSECTIME) I'll be back at 14:09

21 CL Program START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) /* Create info is supplied and the variables defined*/ DCL VAR(&FILENAME) TYPE(*CHAR) LEN(11) DCL VAR(&MEMNAME) TYPE(*CHAR) LEN(11) DCL VAR(&LIBNAME) TYPE(*CHAR) LEN(11) DCL VAR(&MEMTYPE) TYPE(*CHAR) LEN(3) /* The member is created */ CRTMBR: STRSEU SRCFILE(&LIBNAME/&FILENAME) SRCMBR(&MEMNAME) TYPE(&MEMTYPE) /* Message to confirm member creation is sent */ SNDUSRMSG MSG('IT''S DONE, PAPPY!') /* The program is ended */ END: ENDPGM

22 Compilation Reports Library PF-SRC CRTMBR CLP Compile CRTMBR *PGM CLP Compilation Report MSGQ Completion Msg

23 Compilation Reports n General Information n Source Code Listing n Cross reference table n Error message summary

24 General information area

25 Searching the report n Control field commands provide quick movement through the spool file

26 Find Area n Allows you to search for a character string within the compilation report n Case sensitive n To find a string: u Enter the text in the find area u Press F16 n To find other occurrences of the string continue to press F16

27 Source Code Listing n Displays source code n Error messages placed after incorrect statements

28 Error messages n Comprised of three parts: u Error code u Error message u Severity level CPD PGM command missing.

29 Cross Reference table n For every variable and label, the statement numbers that reference each are displayed n Errors messages listed here also

30 Error Message Summary n Error message total n Subtotals by severity level n Successful or not message n Max severity Severity 20 errors (and higher) stop the compile

31 Run Time Errors n Source code that compiles can still have errors when run or have incorrect output n If there is a run time error, the system will display a short message n For more info about the problem: u Move the cursor to the message u Press F1 u Additional Message Information will be displayed for the message

32 JOBLOG n Most of the time, Additional Message Information will be enough to understand the problem n If not, all messages need to be checked. (Not just the one displayed by the system.) n Display the JOBLOG by u Pressing F10 at the Additional Message Information screen u Or issue the DSPJOBLOG command

33 Run Time Errors n Some run time errors are not the result of incorrect programming e.g. u Incorrect user input u Lack of authority u No data n The program should not end when these types of errors occur n The program should check for these conditions and provide user friendly messages

34 Monitoring for Messages n MONMSG - allows the program, NOT the OS, to handle specified message(s) n The CL command specified in the EXEC keyword is executed when the error occurs n If MONMSG placed right after DCL’s: u EXEC performed regardless of the program statement causing the error n If MONMSG follows a command: u EXEC performed only if the preceding command caused the specified error

35 Monitoring for Messages n CPF library does not exist n CPF file does not exist n This MONMSG results in an error handling routine being executed n No EXEC keyword means the error will be ignored MONMSG MSGID(CPF9810) EXEC(CRTLIB &LIBNAME) MONMSG MSGID(CPF9812) EXEC(GOTO CMDLBL(NOFILE)) MONMSG MSGID(CPF9812)

36 Error Handling Routines n Can further investigate the cause of the problem n Perform complex functions to solve the problem n Allow the user to select a course of action from program defined options

37 Message Replies n Messages can be sent that require a reply n The reply can be stored in a program variable n The reply value can be the basis for conditional statement execution

38 Message Replies n MSGRPY - Identifies the program variable to hold the reply n VALUES - Defines the valid values that can be entered as a reply n IF condition - if true, the statement(s) following THEN will be performed MONMSG MSGID(CPF9810) EXEC(SNDUSRMSG MSG('THE LIBRARY + SPECIFIED DOES NOT EXIST. TO CREATE THE LIBRARY, REPLY + WITH A "Y". TO END THE PROGRAM, REPLY WITH A "N".') + MSGRPY(&REPLY) VALUES(Y N)) IF COND(&REPLY *EQ N) THEN(GOTO END) IF COND(&REPLY *EQ Y) THEN(CRTLIB &LIBNAME)

39 Creating CL Commands n Creating a CL command entails identifying a program and prompt screen to be called when the command is issued. n So, you must create a program and prompt screen before creating a command n CL command objects have type = *CMD n A prompt screen makes it easier for a user to supply data to a program

40 Prompt Screen n The prompt screen for the following program must have 4 data entry fields START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) DCL VAR(&FILENAME) TYPE(*CHAR) LEN(10) DCL VAR(&MEMNAME) TYPE(*CHAR) LEN(10) DCL VAR(&LIBNAME) TYPE(*CHAR) LEN(10) DCL VAR(&MEMTYPE) TYPE(*CHAR) LEN(3) CRTMBR: STRSEU SRCFILE(&LIBNAME/&FILENAME) SRCMBR(&MEMNAME) TYPE(&MEMTYPE) SNDUSRMSG MSG('IT''S DONE, PAPPY!') END: ENDPGM

41 Prompt Screen Example CREATE MEMBER (CRTMBR) Type choices, press Enter. LIBRARY YOURLIB NAME SOURCE FILE ___________ NAME SOURCE MEMBER ___________ NAME MEMBER TYPE ___ CLP RPG PF CBL LF Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys

42 Prompt Screens n Special CL commands to define prompt screens n CMD - only required command. The keyword PROMPT defines the screen title n PARM - used to define an entry field

43 PARM command n PARM keywords used to define a field: u KWD - defines the fields keyword u TYPE - type of data the field will accept u LEN - length of field u CHOICE - text that will appear to the right of the field regarding value choices u PROMPT - text that will appear to the left of the field, describes the field u DFT - defines a default value for the field u VALUES/RSTD - identifies the only valid values for the field

44 Prompt Screen Source Example CMD PROMPT('CREATE MEMBER') PARM KWD(LIB) TYPE(*CHAR) LEN(11) + CHOICE('NAME') + PROMPT('LIBRARY') DFT(YOURLIB) PARM KWD(FILE) TYPE(*CHAR) LEN(11) + CHOICE('NAME') + PROMPT('SOURCE FILE') PARM KWD(MBR) TYPE(*CHAR) LEN(11) + CHOICE('NAME') + PROMPT('SOURCE MEMBER') PARM KWD(TYPE) TYPE(*CHAR) LEN(3) + CHOICE('CLP RPG PF CBL LF') + PROMPT('MEMBER TYPE')

45 Prompt Screen Example CREATE MEMBER (CRTMBR) Type choices, press Enter. LIBRARY YOURLIB NAME SOURCE FILE ___________ NAME SOURCE MEMBER ___________ NAME MEMBER TYPE ___ CLP RPG PF CBL LF CMD PROMPT('CREATE MEMBER') PARM KWD(TYPE) TYPE(*CHAR) LEN(3) + CHOICE('CLP RPG PF CBL LF') + PROMPT('MEMBER TYPE')

46 Creating the command - CRTCMD Create Command (CRTCMD) Type choices, press Enter. Command > CRTMBR Name Library > YOURLIBXX Name, *CURLIB Program to process command... > CRTMBR Name, *REXX Library > YOURLIBXX Name, *LIBL, *CURLIB Source file QCMDSRC Name Library > YOURLIBXX Name, *LIBL, *CURLIB Source member CRTMBR Name, *CMD Text 'description' *SRCMBRTXT Command to be created Program that will be called Prompt screen to display (source definition)

47 Points to Remember n CL commands can be “grouped” into programs n Compilation reports are used to diagnose compile errors n The JOBLOG helps diagnose run time errors n Users can create their own CL commands