HCL Technologies Ltd.

Control Language

Rashmi Pratap

Agenda
What is Control Language Use of Control Language

Control Language

Control language (CL) is the primary interface to the operating system and can be used at the same time by users at different work stations. Single control language statement is called a command.

Use of Control Language

Control system power up and power down. Change the configuration of the system Manage work on the system by controlling subsystems, job queues, job priorities, memory pools, time slices and so on. Start other jobs by calling programs directly or by submitting jobs to batch processing.

Use of Control language

Control system security by actually changing user and object authorities. Control all forms of communications between your AS/400 and other systems (peers, hosts, PCs, remote controllers). Manage objects in libraries.

Programming

Programming

Creating a CL program Interactive The iSeries server provides the Programmer Menu, the Command Entry display, command prompt displays, and the Programming Development Manager (PDM) Menu. The most frequently used source entry method is the source entry utility (SEU).

Programming(contd)

Batch To ensure best performance for interactive jobs, work that is batch in nature should be removed and executed separately as batch jobs. Use WRKSBMJOB command to monitor batch jobs. A batch job is submitted using the SBMJOB command.

Parts of a CL procedure
Start Declare Program-Level Monitor message IBM Commands PGM (Optional) (DCL, DCLF) MONMSG MONMSG IF ELSE COMMAND MONMSG MONMSG

Command-Level Monitor Messages And/or User commands End

ENDPGM (optional)

Working with Variables

DCL VAR(&NAME) TYPE() LEN()
TYPE LEN

VALUE()
VALUE

*DEC

DEFAULT(15 5) MAX(15 9)
DEFAULT(32) MAX(9999) 1

DEFAULT(0)

*CHAR

DEFAULT(Blank)

*LGL

CHGVAR

Used to change the contents of a variable. Can also be used to perform arithmetic calculations.

CHGVAR VAR(CL-variable) VALUE(operand +,-,/,* operand)

Control processing with in a CL procedure

If-Then Structure IF COND(condition) THEN(CL-command)

Nested If Structure IF COND(condition) THEN(IF COND(condition) THEN(CL command)

If-Then-Else IF COND(condition) THEN(CL command) ELSE CMD(CL command)

Control processing with in a CL procedure(contd)

Relational and Logical Expressions Expression: Operand Operator Operand Result: 1 True or 0False Operands: Constant, Variable or Another Expression Symbols Operators Description < *LT Less Than = *EQ Equal To > *GT Greater Than <= *LE Less than or Equal to > *NL Not Less Than >= *GE Greater Than or Equal to < *NG Not Greater Than = *NG Not Equal to & *AND True if both operands are 1 | *OR True if both or either operands is 1 *NOT True if the condition is false

Control processing with in a CL procedure(contd)

DO Group IF COND(condition) DO Statement1 Statement2 ENDDO ELSE DO Statement3 Statement4 ENDDO

Control processing with in a CL procedure(contd)

GOTO Construct As DOWHILE or DOUNTIL constructs are not available in CL, loops are created using GOTO structures
CHGVAR &count 0 LOOP: IF (&count = 3) GOTO ENDLOOP SNDPGMMSG(This is one of three messages) CHGVAR &count (&count + 1) GOTO LOOP ENDLOOP:

Control processing with in a CL procedure(contd)

Concatenation Concatenation allows multiple character values to be joined and stored as a single value in a variable
*CAT concatenate without editing *TCAT training blanks in first string are truncated *BCAT trailing blanks in the first character string are truncated. One blank is inserted and the two strings are concatenated.

Control processing with in a CL procedure(contd)

Substring Used to extract part of a character value Can also be used to extract values from a data area Example: PGM DCL &time *CHAR 6 RTVSYSVAL QTIME &time SNDPGMMSG MSG(The current time is *BCAT + (%SST(&time 1 2)) *CAT : *CAT + (%SST(&time 3 2)) *CAT : *CAT + (%SST(&time 5 2))) RETURN ENDPGM

Control processing with in a CL procedure(contd)

Convert Date (CVTDAT) Used to convert the date format to another format different from the systems native date format. Example: CVTDAT DATE(date-to-be-converted) + TOVAR(CL-variable-name) + FROMFMT(from-date-format) + TOFMT(to-date-format) + TOSEP(separator-character)

Retrieving External Attributes

Return variables are used to return a value in a CL program RTV group of commands are used to return external information into the program

RTVSYSVAL RTVJOBA RTVOBJD

Working with CL procedures

Compiling and executing CL procedures Use the CRTBNDCL command to create a bound program with one module in single step. Specify list options and whether the program should operate under the program owners user profile. A program can run using either the owners user profile or the users user profile. CRTCLMOD command creates a module. The module is bound into a program or service program using the Create Program(CRTPGM) or Create Service Program (CRTSRVPGM) command.

Working with CL procedures (contd)

Errors encountered during compilation
The following types of errors stop the procedure from being created: Value errors Syntax errors Errors related to dependencies between parameters within a command Errors detected during validity checking. Even after an error that stops the procedure from being created is encountered, the compiler continues to check the source for errors.

Communication between Programs

CALL Command

Calls a program named on the command, & passes control to it.

CALL PGM(library-name/program-name) PARM(parameter-values)

When called program finishes running, control returns to the next command in the calling program. CL Program can call itself.

CALL Command (contd.)

The sequence of CALL commands in a set of programs calling each other is the call stack.

CALL Command (contd.)

The call stack is:

RETURN Command

Removes the procedure or OPM program containing RETURN command, from the call stack. If the procedure containing the RETURN command was called by a CALLPRC command, control is returned to the next sequential statement after that CALLPRC command in the calling program.

RETURN Command (cont.)

If a MONMSG command specifies an action that ends with a RETURN command, control is returned to the next sequential statement after the statement that called the procedure or program containing the MONMSG command.
Has no parameters

TFRCTL COMMAND

The TFRCTL program, passes control to the program, then removes the calling program from the call stack. Control is returned to the next higher program in the call stack.
All subsequent statements in the calling program are ignored and the calling program itself ends.

Passing parameters between Programs

Information to be passed specified on the PARM parameter on the CALL command. Example: Program A: CALL PROGB PARM(&AREA) then it calls PROGB and passes value &AREA to it. Program B: PGM PARM(&AREA)

Passing parameters between Programs (contd.)

Parameters are passed by position. Parameters listed in the receiving procedure or program must be declared as the same length and type as they are in the calling procedure or program. When calling an OPM CL program, the number of parameters that are passed to it must exactly match the number that is expected by the program.

Controlling flow between Programs

Interprogram Communication

When you spread the work among several programs, however, you quickly realize that you need a method to pass information between them. One program must be able to communicate with others.

Interprogram Communication (contd..)

Information can be passed between programs using any of the following: Database files Parameters. Data areas, including the local data area (LDA) Switches. Messages Data queues

Data Area

Data areas are objects of type *DTAARA that you can create and delete at will.
A data area is an area of storage with a name, but without any structure. You cannot define fields within data areas. Used to store information. One program can write information to it and another can read that information at a later time Asynchronous Communication

Data Area (contd.)

Allow to establish communication between two or more programs that may be running in different jobs Possible because data areas are permanent objects (type *DTAARA) that are independent of any job.

Types of Data Area

*LDA (Local Data Area):

1024 bytes Automatically created for each job. Type: *char Cannot be deleted Available till the job ends. CRTDTAARA and DLTDTAARA do not apply to it

Types of Data Area (contd.)

*GDA (Group Data Area):

512 byte group data area. Automatically created for each group job. Type: *char Cannot be deleted when job stops being a group job (or when it ends), the *GDA is deleted by system. CRTDTAARA and DLTDTAARA do not apply to it

Types of Data Area (contd.)

*PDA (Program Initialization Parameter (PIP) Data Area):

2000 characters long. Automatically created. Type: *char CRTDTAARA and DLTDTAARA do not apply to it

Creating Data Areas

Create Data Area (CRTDTAARA) command.

Requires: Qualified name optional 50-character text description Type - *CHAR, *DEC, *LGL length of up to 2,000 for *CHAR or up to (24 9) for *DEC Optional initial value

Creating Data Areas (contd.)

Example:
CRTDTAARA DTAARA(AMERITOR/TEMPDTA) TYPE(*CHAR) LEN(100) VALUE('Sample Data Area) This creates a character type data area: TEMPDTA of length 100 in library AMERITOR. It has been assigned an initial value: Sample Data Area.

Displaying Data Areas

Display Data Area (DSPDTAARA) command.

The output can be directed to the display or to a printer, depending on the value given to the OUTPUT parameter.

Displaying Data Areas (contd.)

Example:
DSPDTAARA DTAARA(AMERITOR/TEMPDTA)

The output to the above command will be as follows:

Value Offset *...+....1....+....2....+....3....+....4....+....5 0 'Sample Data Area ' 50 ' '

Changing Data Areas

Contents of Data area can be changed using: Change Data Area (CHGDTAARA) command.
Requires:

Qualified name of data area Position within the data area to be changed length of the data to be changed New data to be placed.

Changing Data Areas (contd.)

Example: A data area is created as follows: CRTDTAARA DTAARA(AMERITOR/TEMPDTA) TYPE(*CHAR) LEN(100) VALUE('Sample Data Area)
Now to replace its 5th and 6th characters with numbers 1 and 2 issue: CHGDTAARA DTAARA(AMERITOR/TEMPDTA (5 2)) VALUE(12') The new value thus becomes: Samp12 Data Area

Retrieving Data Areas

The Retrieve Data Area (RTVDTAARA) command can be used in a CL program to place the contents of a data area (or a portion thereof) into a CL variable. To retrieve the second, third and fourth characters of data area TEMPDTA into variable &PART as follows: RTVDTAARA DTAARA(AMERITOR/TEMPDTA (2 3)) RTNVAR(&PART)

Retrieving Data Areas (contd.)

This is what happens:

AMERITOR/TEMPDTA PGM DCL VAR(&PART) TYPE(*CHAR) LEN(10) RTVDTAARA DTAARA(AMERITOR/TEMPDTA(2 3)) + RTNVAR(&PART) ENDPGM

Samp12 Data Area

amp

Data Area Locking & Allocation

The CHGDTAARA command uses a *SHRUPD (shared for update) lock on the data area during command processing.
The RTVDTAARA and DSPDTAARA commands use a *SHRRD (shared for read) lock on the data area during command processing. To perform more than one operation on a data area, use the Allocate Object (ALCOBJ) command to prevent other users from accessing the data area until your operations are completed.

Data Queues

Permanent objects of type *DTAQ

Used for Asynchronously communicating a stream of values between programs or jobs. Types of data queues: *FIFO *LIFO *KEYED

Data Queues (cont.)

Create Data Queue (CRTDTAQ) This command creates a data queue and stores it in a specified library. CRTDTAQ DTAQ(MYLIB/MYDTAQ) MAXLEN(512) Delete Data Queue (DLTDTAQ) This command deletes the specified data queue(s) from the system.
DLTDTAQ DTAQ(MYLIB/MYDTAQ)

Data Queues (cont.)

Send Data Queue (QSNDDTAQ) This API sends data to the specified data queue. Receive Data Queue (QRCVDTAQ) This API receives data from the specified data queue.

Comparison of Data Queues with DB Files

Data queues have been improved to communicate between active procedures and programs. For storing large volumes of data or large numbers of entries use database files. When using data queues, you should include abnormal end routines in your programs to recover any entries not yet completely processed before the system is ended.

Comparison-Data Queue to Message Queue

DTAQ similar to MSGQ in that procedures and programs can send data to the queue that is received later by another procedure or program.
More than one program can have a receive pending on a data queue at the same time, while only one program can have a receive pending on a message queue at the same time.

Working with Files

Referring to Files

Files are accessed during compiling of DCLF commands when CL modules and programs are created so that variables can be declared for each field in the file.
If library list used at compile time, the file must be in a library on the library list at run time.

Opening & Closing Files

Only 1 file can be referred The file referred to is implicitly opened when first send, receive, or send/receive operation performed. An opened display file remains open until the procedure or OPM 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 procedure or OPM program in which it was opened returns or transfers control.

Opening & Closing Files (contd.)

Once closed, a DB file cannot be opened again during the same call of the procedure or OPM program. By default first member of DB file opened unless OVRDBF used. If procedure or program ends in error, the files close. File remains open until the procedure or OPM program in which that file was opened ends=>an easy way to share ODPs between running procedures and programs.

Opening & Closing Files (contd.)

Conditions for ODP sharing: The file was created with or has been changed to have the SHARE(*YES) attribute. An override for that file by specifying SHARE(*YES) is in effect.
Display file opened in a CL proc or OPM program always opens for both input and output. DB file opened in a CL proc or OPM program opens for input only.

Declaring a File

DCLF command - for both DSPF and DB files. Only 1 DCLF allowed in a CL proc/pgm. Parameters: DCLF FILE(library-name/file-name) RCDFMT(record-format-names) Only 1 DCLF allowed in a CL proc/pgm. File must exist before the module or program is compiled.

Declaring a File (contd.)

When processing a DCLF command, 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 field name preceded by an ampersand (&). For an option indicator, the CL variable name is the indicator that is preceded by &IN. 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.

Sending & Receiving Data with a Display file

Commands used: SNDF, RCVF, SNDRCVF. SNDF: format contents of vars. associated with output or output/input variables. RCVF: contents of fields. associated with input or output/input fields. placed in corresponding vars. SNDRCVF: sends contents of CL vars. to display (SNDF). Then obtains updated fields. from display (RCVF).

Receiving Data from a DB File

When RCVF command is run, the next record on the files access path is read, and the values of the fields defined in the database record format are placed in the corresponding CL variables. When EOF reached, message: CPF0864 is sent to the procedure or OPM program CL vars. declared for record format. not changed by processing of RCVF command. Attempt to run additional RCVF commands after end of file has been reached=> message CPF0864 is sent again.

Working With Messages

Agenda
Messages Creating a Message File Adding Messages Sending Messages From a CL Monitoring Messages in CL Message Logging

Messages
Communication between Procedures or programs Jobs Users Users and procedures or program occurs through messages.

Messages
Types of messages: Predefined Messages: Created before they are used. These messages are placed in a message file when they are created, and retrieved from that file when they are used.

Immediate Messages: Created by the program or system user when they are sent and are not permanently stored in the system.

Creating a Message File

To create your own predefined messages,

Use Create Message File (CRTMSGF) For Example: CRTMSGF MSGF(QGPL/USRMSG) + TEXT('Message file for user-created messages')

Adding Messages
Add Message Description (ADDMSGD) Describes the pre-defined messages. Adds them to the message file created. Specifications for ADDMSGD command
Message identifier Message description Message file name

Sending Messages From a CL

Command to send a message from a CL procedure or program. SNDUSRMSG You can send an inquiry message or an informational message to a display station user, the system operator, or a user-defined message queue. SNDPGMMSG To sends a message to named message queue or to a call message queue.

Sending Messages From a CL

SNDMSG Used by a display station user to send an immediate message from his display station to one or more message queues.
SNDBRKMSG Used to send an immediate message to one or more work station message queues.

Message Queue

When a message is sent to a procedure, a program, or a system user, it is placed on a message queue associated with that procedure, program, or user.
OS/400 provides message queues for: Work station on the system User enrolled on the system System operator System history log

Messages Types

Inquiry and Informational Messages Inquiry message is sent and the message queue receiving the message must reply to it.

SNDPGMMSG MSGID(USR4310) + MSGF(QGPL/USRMSG)+ MSGDTA(&CUSNO) TOPGMQ(*EXT) + MSGTYPE(*INFO)

Messages Types

Completion and Diagnostic Messages Completion message indicates the status of the work that is successfully performed. Diagnostic messages provide information about errors detected by the program.

SNDPGMMSG MSG('WPAY job submitted')+ MSGTYPE(*COMP)

Messages Types

Status Messages The status message describes the status of work performed by the sending program.

SNDPGMMSG MSGID(CPF9898) + MSGF(QCPFMSGF) MSGDTA (Status) + TOPGMQ(*EXT) MSGTYPE(*STATUS)

Messages Types

Escape and Notify Messages

Notify message describes a condition for which corrective action must be taken. Escape message describes an irrecoverable error condition.

SNDPGMMSG MSGID(CPF9898) + MSGF(QCPFMSG) MSGTYPE(*ESCAPE) + MSGDTA ('Procedure detected failure')

Receiving Messages
Receive Message (RCVMSG) To receive messages from a message queue for your procedure or program. Messages can be received in the following ways: By message type By message reference key By its location on the message queue. By both message type and message reference key

Retrieving Messages
Retrieve Message (RTVMSG) To retrieve the text of a message from a message file into a variable.
Example:
DCL &FILE TYPE(*CHAR) LEN(10) VALUE(INVENT) DCL &LIB TYPE(*CHAR) LEN(10) VALUE(QGPL) DCL &A TYPE(*CHAR) LEN(20) DCL &MSG TYPE(*CHAR) LEN(50) CHGVAR VAR(&A) VALUE(&FILE||&LIB) RTVMSG MSGID(USR1001) MSGF(QGPL/USRMSG) + MSGDTA(&A) MSG(&MSG)

Removing Messages from Message Queue

Removing Messages using:

RMVMSG , CLRMSGQ,

You can remove: 1. A single message 2. All messages 3. All except unanswered messages 4. All old messages 5. All new messages 6. All messages from all inactive programs

Monitoring Messages in CL
You can monitor for messages using two levels of MONMSG commands: Procedure level Specific command level
Messages that are monitored are: Escape messages Notify messages Status messages

Message Logging
The two types of logs for messages are:

Job log History log Job log contains information related to requests entered for a job. QHST log contains system data, such as a history of job start and end activity on your system.

JOB Log

Each job has an associated job log that can contain the following for the job:

Commands in the job. Commands in a CL program if the CL program was created with the LOG(*YES) option or with the LOG(*JOB). All messages and message help sent to the requester.

JOB Log

Using LOG parameter on the CRTJOBD, user can control what information the system writes in the job log.
Values make up the LOG parameter are: Message level Message severity Message text level

Logging CL Command

LOGCLPGM controls weather CL commands are logged or not. LOGCLPGM is a parameter in the jobs job description.
User can change it using CHGJOBD or CHGJOB command.

Displaying the Job Log

Displaying a job log depends on the status of the job. If the job has ended and the job log is not yet printed, use the DSPSPLF command. DSPSPLF FILE(QPJOBLOG)JOB(001293/FRED/W)
If the job is still active or is on a job queue and has not yet started, use the DSPJOBLOG command. DSPJOBLOG JOB(nnnnnn/JSMITH/WS1)

History Log

History log (QHST) consists of Message queue Physical file known as log-version History log (QHST) contains System Information, Subsystem Information, Job start/completion Device status, QSYSOPR messages.

Use of various Commands in CL

Add Library List Entry (ADDLIBLE) Adds a library name to the user portion of the library list. User can specify whether the library is added to the beginning, to the end, or to the library list before, after or replacing a library that is currently in the user portion of the library list. ADDLIBLE LIB(LIBA) POSITION(*FIRST) Remove Library List Entry (RMVLIBLE) This command removes a library name from the user portion of the library list. RMVLIBLE LIB(LIBA)

Use of various Commands in CL

Retrieve Member Description (RTVMBRD) Used to retrieve information about a member of a database file for use in your applications. RTVMBRD FILE(MYLIB/MYFILE) MBR(AMEMBER *NEXT) RTNLIB(&LIB) + RTNSYSTEM(&SYS) RTNMBR(&MBR) + FILEATR(&MTYPE) CRTDATE(&CRTDATE) + TEXT(&TEXT) NBRCURRCD(&NBRRCD) + DTASPCSIZ(&SIZE) USEDATE(&USEDATE) + USECOUNT(&USECNT) RESETDATE(&RESET)

Retrieve Job Attributes (RTVJOBA) Used in a CL program to retrieve the values of one or more job attributes and place the values into the specified CL variable.
RTVJOBA JOB(&JOB) USER(&USER) NBR(&NBR)

Use of various Commands in CL

Retrieve System Value (RTVSYSVAL) Used in a CL program to retrieve the value from the specified system value so that it can be used in the program. RTVSYSVAL SYSVAL(QTIME) RTNVAR(&TIME) Retrieve User Profile (RTVUSRPRF) Used in a CL program to get one or more of the values that are stored and associated with a user.

RTVUSRPRF RTNUSRPRF(&USRPRF)

Use of various Commands in CL

Check Object (CHKOBJ) The Check Object (CHKOBJ) command checks object existence and verifies the user's authority to the object before trying to access it. CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) Clear Physical File Member (CLRPFM) This command removes all the data (including deleted records) from the specified member of a physical file.

CLRPFM FILE(MYLIB/MYFIL) MBR(MYMBR)

Use of various Commands in CL

Override with Data Base File (OVRDBF) This command is used to (1) Override (replace) the file named in the program. (2) Override certain parameters of a file that are used by the program.

Open Query File (OPNQRYF) This command opens a file to a set of database records that satisfies a database query request.

Use of various Commands in CL

Display File Description (DSPFD) This command shows one or more types of information retrieved from the file descriptions of one or more database and/or device files. The information is provided for each access. The information can be shown, printed, or directed to a database output file (OUTFILE). Display File Field Description (DSPFFD) This command shows, prints, or places in a database file field-level information for one or more files in a specific library or all the libraries to which the user has access.

Use of various Commands in CL

Display Program (DSPPGM) This command displays information about a program. The display includes information about the compiler, the source from which the program was created, certain processing attributes of the program, the size of the program, and the number of parameters that must be passed to the program when it is called.

Use of various Commands in CL

Display Program References (DSPPGMREF) This command provides a list of the system objects referred to by the specified programs. The following list shows the system objects provided for the respective program types: RPG *FILE, *DTAARA, and *PGM RPGLE *FILE, *PGM, *DTAARA, and *SRVPGM
This information can be displayed, printed, or placed in a database output file.

QUESTION?