5th Chapter 5 - C L Programming

1

CL Programming

Copyright 2009 by Janson Industries

Introduction to IBM i

Copyright 2009 by Janson Industries2

Objectives Explain general programming

concepts

Explain CL’s strengths and weaknesses as a programming language

Show how to create a CL program

Explain what a compilation report is and how to use it to find program errors


Creating CL Programs

Library

PF-SRC

CRTMBRCLP

Compile

CRTMBR*PGM

CLP

LPEXSEU

Programmer

CLCommands


Programs Programs are comprised of many

programming language instructions

Instructions are written on lines or statements.

Each statement/line in a member is assigned a statement/line number.

CL commands (instructions) can span many lines


Program Processing

Programs can execute instructions 3 ways

The default method is sequential, I.e. in statement number order

Execution can also be conditional and iterative.


CL Command Syntax The format for a CL Command is:

There is at least one space between the: Command First parameter Each succeeding parameter

Commands are continued from one line to another by placing a plus sign after the command or a parameter

COMMAND PARAMETER PARAMETER ….


CL Command Syntax The + must be preceded by at least a

space if the continuation is between: A command and a parameter Two parameters

COMMAND + PARAMETER PARAMETER

COMMAND+ PARAMETER PARAMETER

COMMAND PARAMETER PARAMETER + PARAMETER PARAMETER + PARAMETER

COMMAND PARAMETER PARAMETER+ PARAMETER PARAMETER


Continuing a CL Command

COMM+AND PARAMETER

PARMETER

COMMAND PARAMETER PARA+ METER

COMM +AND PARAMETER

PARMETER

COMMAND PARAMETER PARA + METER

The + is not preceded by space(s) if the continuation is in the middle of the: Command word Parameter keyword


Continuing a CL Command 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)


Continuing a CL Command 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)


CL Programs Begin with a PGM command and end

with an ENDPGM command

Comments (non-executable text) may precede the PGM statement

Comments begin with a forward slash & an asterisk and end with an asterisk & a forward slash

/* This is an example of a comment. */


Programs Programs read and write data Data can come from storage, the OS,

or the person who calls the program Programs can write data to storage, a

printer or a workstation

Program

Storage

Operating System

User

PrintoutData

Data Data

Data


User Supplied Program Data You can supply data when calling the

program as follows:

To receive the data, the program must have a PARM keyword in the PGM statement.

The PARM keyword identifies the program variables that will hold the data

CALL pgm1 (‘chardata’ numeric ‘chardata’….)

PGM PARM(&CUSTNAME &ORDAMT)


User Supplied Program Data The parameters specified on the call

must match the parameters specified in the PARM keyword

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:


Program Variables Programs store input and output in

program variables

Just like a data base field, a program variable has a: Name Length Data type

Program variables exist for as long as the program is running


CL Program Variables Are defined with a DCL (declare)

command A CL program variable name must:

Begin with an ampersand (&) Has a max length of 11 Cannot contain spaces

DCL statements must be at the beginning of the program following the PGM statement

000100 PGM PARM(&CUSTNAME &ORDAMT)000200 DCL VAR(&CUSTNAME) TYPE(*CHAR) LEN(15) 000300 DCL VAR(&ORDAMT) TYPE(*DEC) LEN(9 2)


Retrieving Data from IBM i RTVSYSVAL - retrieves and stores system

parameter values in program variables: Date Time System Default Printer

RTVJOBA - retrieves and stores job information in program variables:

Job name User running job Output queue

RTVSYSVAL SYSVAL(QTIME) RTNVAR(&CURTIME)

RTVJOBA USER(&USERID)


Sending Data to a User SNDUSRMSG - sends a message to the person

running the program or a specified users message queue

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)


String Functions Concatenation - joins two strings together

*CAT *TCAT - eliminates trailing spaces *BCAT - one trailing space between strings

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 I'll be back at14:09:08 I'll be back at 14:09:08


String Functions Substring - identifies a subset of a string

%SST(string start-location size)

When used with a CHGVAR command, new strings can be created.

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


CL Program

000100 START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) 000200 000300 /* Create info is supplied and the variables defined*/ 000400 000500 DCL VAR(&FILENAME) TYPE(*CHAR) LEN(10) 000600 DCL VAR(&MEMNAME) TYPE(*CHAR) LEN(10) 000700 DCL VAR(&LIBNAME) TYPE(*CHAR) LEN(10) 000800 DCL VAR(&MEMTYPE) TYPE(*CHAR) LEN(3)000900 001000 /* The member is created */ 001100 001200 CRTMBR: STRSEU SRCFILE(&LIBNAME/&FILENAME) + 001300 SRCMBR(&MEMNAME) + 001400 TYPE(&MEMTYPE) 001500 001600 /* Message to confirm member creation is sent */ 001700 001800 SNDUSRMSG MSG('IT''S DONE, PAPPY!')001900 002000 /* The program is ended */ 002100 002200 END: ENDPGM


Compilations

Library

PF-SRC

CRTMBRCLP Compile

CRTMBR*PGM

CLP

CompilationReport

MSGQ

Completion M

sg


RDi Unsuccessful Compilations

Library

PF-SRC

CRTMBRCLP Compile

CRTMBR*PGM

CLP

Error MsgsCRTMBR

___

EVFEVENT*FILE

PF-DTA


The EVFEVENT member will be displayed in Error List

Error msgs displayed in Commands log

24

RDi Unsuccessful Compilations


Verifying in RDi Does everything compiling does

except create the object

Why bother? To compile you must be able to

communicate to the IPS Verifying doesn't require

communicating to the IPS Verifying faster than compiling

No verifier for CL programs!!



Compilation Reports

In a spool file with the same name as member

Can be viewed Using Navigator's Viewer WRKSPLF


Display spool files and double click the spool file



Work with All Spooled Files Type options, press Enter. 1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages 8=Attributes 9=Work with printing status Device or Total Cur Opt File User Queue User Data Sts Pages Page Copy TESTPGM USFL1AD001 PRT01 RDY 4 1 TESTPGM USFL1AD001 PRT01 RDY 4 1 QPJOBLOG USFL1AD001 QEZJOBLOG TESTPGM RDY 1 1 TESTPGM USFL1AD001 PRT01 RDY 4 1 QPJOBLOG USFL1AD001 QEZJOBLOG TESTPGM RDY 1 1 5 TESTPGM USFL1AD001 PRT01 RDY 4 1 QPJOBLOG USFL1AD001 QEZJOBLOG QDFTJOBD RDY 1 1 Bottom Parameters for options 1, 2, 3 or command ===> F3=Exit F10=View 4 F11=View 2 F12=Cancel F22=Printers F24=More keys

WRKSPLF


Compilation Reports

General Information

Source Code Listing

Cross reference table

Error message summary


General information area Display Spooled File File . . . . . : COMPILEEX Page/Line 1/1 Control . . . . . ________ Columns 1 - 78 Find . . . . . . ______________________________ *...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+... 5763SS1 V6R1M0 100517 Control Language GRA Program . . . . . . . . . . . . . . . . . . . : COMPILEEX Library . . . . . . . . . . . . . . . . . . : GRADES Source file . . . . . . . . . . . . . . . . . : GRADES Library . . . . . . . . . . . . . . . . . . : GRADES Source member name . . . . . . . . . . . . . : COMPILEEX 10/30/09 17:06: Source printing options . . . . . . . . . . . : *SOURCE *XREF *GEN *NOSE Program generation options . . . . . . . . . : *NOLIST *NOXREF *NOPATCH User profile . . . . . . . . . . . . . . . . : *USER Program logging . . . . . . . . . . . . . . . : *JOB Allow RTVCLSRC command . . . . . . . . . . . : *YES Replace program . . . . . . . . . . . . . . . : *YES Target release . . . . . . . . . . . . . . . : V6R2M0 Authority . . . . . . . . . . . . . . . . . . : *LIBCRTAUT Sort sequence . . . . . . . . . . . . . . . . : *HEX Language identifier . . . . . . . . . . . . . : *JOBRUN


Searching the report Control field commands provide quick

movement through the spool file

P+5 Move forward 5 pagesP-5 Move backwards 5 pagesP5 Move to page 5+5 Move forward 5 lines-5 Move backwards 5 linesW+5 Move to the right 5 columnsW-5 Move to the left 5 columnsW5 Move to the fifth columnB or *BOT Move to the end of the spool fileT or *TOP Move to the beginning of the spool file


Find Area Allows you to search for a character

string within the compilation report

Case sensitive

To find a string: Enter the text in the find area Press F16

To find other occurrences of the string continue to press F16


Source Code Listing Displays source code Error messages placed after incorrect

statements

Control Language Source SEQNBR *...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 100- DCL VAR(&JOB) TYPE(*CHAR) LEN(7)* CPD0740 10 PGM command missing. 200- DCL VAR(&USR) TYPE(*CHAR) LEN(10) 300- RTVJOBA JOB(&JOB)* CPD0784 30 Variable &JOB for parameter JOB must be *CHAR, minimum length 10 400- RTVJOBA USER(&USER)* CPD0727 40 Variable '&USER ' is referred to but not declared. 500- SNDUSRMSG MSG('The job number is' *cat &job *cat + 600 'and the user is ' *cat &user *cat + 700 '.') TOUSR(&USER)* CPD0727 40 Variable '&USER ' is referred to but not declared.* CPD0727 40 Variable '&USER ' is referred to but not declared. 800- GOTO CMDLBL(END)* CPD0725 10 End of source file reached without ENDPGM command. * * * * * E N D O F S O U R C E * * * *


Error messages

Comprised of three parts: Error code Error message Severity level

CPD0740 10 PGM command missing.


Cross Reference table For every variable and label, the statement

numbers that reference each are displayed Errors messages listed here also

5763SS1 V6R1M0 090517 Control Language GRA Cross Reference Declared Variables Name Defined Type Length References &JOB 100 *CHAR 7 300 500 &USR 200 *CHAR 10 * CPD0726 10 Variable '&USR ' declared but not referred to. Defined Labels Label Defined References END ****** 800 * CPD0715 30 Label 'END ' does not exist. * * * * * E N D O F C R O S S R E F E R E N C E


Error Message Summary Error message total Subtotals by severity level Successful or not message Max severity

Message Summary Severity Total 0-9 10-19 20-29 30-39 40-49 50-59 60-69 70-79 80-89 90 8 0 3 0 2 3 0 0 0 0 Program COMPILEEX not created in library GRADES. Maximum error severity 40. * * * * * E N D O F M E S S A G E S U M

Severity 20 errors (and higher) stop the compile


Run Time Errors Source code that compiles can still

have fail when run

Why? Non-syntax errors

Endless loop User input errors Missing resources

A required library or file does not exist

If there is a run time error, the system generates at least one message Often many messages


JOBLOG What message(s) are displayed and

where depends on the interface

However, all messages are written to the JOBLOG

How to see the JOBLOG depends on the interface being used


5250 Run Time Errors The system generated message will be

displayed at the bottom of the screenProgramming Development Manager (PDM)

Select one of the following: 1. Work with libraries 2. Work with objects 3. Work with members 9. Work with user-defined options Selection or command ===> call library99/testpgm parm("library98")___________________________________ _______________________________________________________________________________ F3=Exit F4=Prompt F9=Retrieve F10=Command entry F12=Cancel F18=Change defaults Parameters passed on CALL do not match those required. +

+ means there's more to the message


5250 Run Time Errors Click on message and press Page Down

to display more of the message textProgramming Development Manager (PDM)

Select one of the following: 1. Work with libraries 2. Work with objects 3. Work with members 9. Work with user-defined options Selection or command ===> call library99/testpgm parm("library98")___________________________________ _______________________________________________________________________________ F3=Exit F4=Prompt F9=Retrieve F10=Command entry F12=Cancel F18=Change defaults Error found on CALL command.


5250 Run Time Errors For more info about the problem:

Move the cursor to the message Press F1 Additional Message Information will

be displayed for the message

Additional Message Information will display The original message Reasons for the error Step to correct the error


5250 Run Time ErrorsAdditional Message Information

Message ID . . . . . . : CPD0172 Date sent . . . . . . : 05/15/09 Time sent . . . . . . : 10:41:52 Message . . . . : Parameters passed on CALL do not match those required. Cause . . . . . : The parameters passed on the CALL command do not match the parameters required by program TESTPGM in library LIBRARY99. Correct program not found or correct parameters not passed. The number of parameters or the type of parameters passed on the CALL command must match those expected by the program called. Recovery . . . : If correct program not found, change or specify the library name on the command or in a library list. Change the CALL command and then try the command again.

Bottom Press Enter to continue. F1=Help F3=Exit F6=Print F9=Display message details F10=Display messages in job log F12=Cancel F21=Select assistance level


JOBLOG Most of the time, Additional Message

Information will be enough to understand the problem

If not, all messages need to be checked. Not just the one displayed by the system

Display the JOBLOG by Pressing F10 at the Additional Message

Information screen Or issue the DSPJOBLOG command

then F10 and Page Up


JOBLOGDisplay All Messages

System: Job . . : QPADEV0004 User . . : USFL1AD001 Number . . . : 098011 4>> call library99/testpgm parm("library98") Parameters passed on CALL do not match those required. Error found on CALL command. Parameters passed on CALL do not match those required. Error found on CALL command. Bottom Press Enter to continue. F3=Exit F5=Refresh F12=Cancel F17=Top F18=Bottom


RDi Run Time Errors The Commands log will display:

The original command All the JOBLOG messages Additional message info for the messages


Run Time Errors As mentioned, some run time errors are

not the result of incorrect programming: Incorrect user input Lack of authority No data

The program should not end when these types of errors occur

The program should check for these conditions and provide user friendly messages


Monitoring for Messages MONMSG - allows the program, NOT

the OS, to handle specified message(s)

The CL command in the EXEC keyword is executed when the error occurs

If MONMSG placed right after DCL’s: EXEC performed regardless of the

program statement causing the error

If MONMSG follows a command: EXEC performed only if the preceding

command caused the specified error


MONMSG MSGID(CPF9810) EXEC(CRTLIB &LIBNAME)

MONMSG MSGID(CPF9812) EXEC(CALLSUBR SUBR(NOFILE))

MONMSG MSGID(CPF9812)

50

Monitoring for Messages CPF9810 - library does not exist

CPF9812 - file does not exist

The above MONMSG invokes an error handling subroutine called NOFILE

No EXEC keyword means the error will be ignored


Defining a Subroutine SUBR/ENDSUBR commands surround

the subroutine code

SUBR keyword in SUBR commands assigns a name

000100 START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) 000200 000300 CALLSUBR SUBR(NOFILE) 000400 : : 020500 SUBR SUBR(NOFILE) 020600 /* Subroutine executable statements */ 020700 /* Subroutine executable statements */ 020800 ENDSUBR020900


Defining a Subroutine Subroutines defined at end of code Will only be executed when called

Not executed as sequential statements

After the subroutine executes, control returns to next sequential statement after the CALLSUBR command (line 400)

000100 START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) 000200 000300 CALLSUBR SUBR(NOFILE) 000400 : : 020500 SUBR SUBR(NOFILE) 020600 /* Subroutine executable statements */ 020700 /* Subroutine executable statements */ 020800 ENDSUBR020900


Error Handling Routines Can further investigate the cause of

the problem

Perform complex functions to solve the problem

Allow the user to select a course of action from program defined options


Message Replies

Messages can be sent that require a reply

The reply can be stored in a program variable

The reply value can be the basis for conditional statement execution


Message Replies MSGRPY - Identifies the program

variable to hold the reply

VALUES - Defines the valid values that can be entered as a reply

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)


Creating CL Commands Creating a CL command entails

identifying a program and prompt screen to be called when the command is issued.

So, a program and prompt screen must be created before creating a command

CL command objects have type = *CMD

A prompt screen makes it easier for a user to supply data to a program


Creating a CL Command

Library

PF-SRC

PRMPTSCRCMD

CRTCMD

NEWCMD*CMD

RDiSEU

Programmer

Programmer specifies:Name of new commandPrompt screen memberProgram to run for command

PGMTORUN*PGM

CLP

CL commands

NEWCMDPRMPTSCRPGMTORUN


Prompt Screen The prompt screen for the following

program must have 4 data entry fields

000100 START: PGM PARM(&LIBNAME &FILENAME &MEMNAME &MEMTYPE) 000200 000300 DCL VAR(&FILENAME) TYPE(*CHAR) LEN(10) 000400 DCL VAR(&MEMNAME) TYPE(*CHAR) LEN(10) 000500 DCL VAR(&LIBNAME) TYPE(*CHAR) LEN(10) 000600 DCL VAR(&MEMTYPE) TYPE(*CHAR) LEN(3)000700 000800 CRTMBR: STRSEU SRCFILE(&LIBNAME/&FILENAME) + 000900 SRCMBR(&MEMNAME) + 001000 TYPE(&MEMTYPE) 001100 001100 SNDUSRMSG MSG('IT''S DONE, PAPPY!')001300 001400 END: ENDPGM


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

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

F24=More keys


Prompt Screens

Special CL commands to define prompt screens

CMD - only required command. The keyword PROMPT defines the screen title

PARM - used to define an entry


PARM command PARM keywords used to define a field:

KWD - defines the fields keyword

TYPE - type of data the field will accept

LEN - length of field

CHOICE - text that will appear to the right of the field regarding value choices

PROMPT - text that will appear to the left of the field, describes the field

DFT - defines a default value for the field

VALUES/RSTD - identifies the only valid values for the field


Prompt Screen Source ExampleCMD 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')


CMD PROMPT('CREATE MEMBER')

PARM KWD(TYPE) TYPE(*CHAR) LEN(3) + CHOICE('CLP RPG PF CBL LF') + PROMPT('MEMBER TYPE')

63

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


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)



Points to Remember CL commands can be “grouped”

into programs

Compilation reports are used to diagnose compile errors

The JOBLOG helps diagnose run time errors

Users can create their own CL commands and prompt screens

5th Chapter 5 - C L Programming

Documents