Complete CL

Complete CL

by Ted Holt

NOOK BookFifth Edition, Fifth edition (eBook - Fifth Edition, Fifth edition)

$46.49 $79.99 Save 42% Current price is $46.49, Original price is $79.99. You Save 42%.
View All Available Formats & Editions
Available on Compatible NOOK Devices and the free NOOK Apps.
LendMe® See Details
Want a NOOK ? Explore Now


Complete CL by Ted Holt

Updated with the latest innovations to this quintessential programming language, the new edition of this comprehensive resource to Command Language (CL) covers all aspects of the language from basics to advanced topics. New functions have been added to CL by IBM and this manual provides detailed coverage on topics such as the INCLUDE command, new constants, overlaid variables, pointers and based variables, the Power System, and the new operating system IBM i. There is now a section on programming subroutines, with practices and examples, as well as explanations for file handling commands and techniques.

Product Details

ISBN-13: 9781583476826
Publisher: Mc Press
Publication date: 03/01/2012
Sold by: Barnes & Noble
Format: NOOK Book
Pages: 520
File size: 9 MB

About the Author

Ted Holt has worked in the information technology industry since 1981, primarily with IBM midrange systems, and has taught at community colleges, universities, vocational, and technical schools. He is the author of several books on programming topics, including Encyclopedia of Tips, Techniques, and Programming Practices for iSeries and AS/400, Open Query File Magic!, Power CL, and Qshell for iSeries. He lives in Corinth, Mississippi.

Read an Excerpt

Complete CL

The Definitive Control Language Programming Guide

By Ted Holt

MC Press

Copyright © 2009 MC Press Online, LP
All rights reserved.
ISBN: 978-1-58347-682-6



Control Language (CL) is a programming language used primarily for control purposes with the IBM i operating system (formerly known as OS/400 and i5/OS). Originating in the early 1980s with the System/38 and continued on the AS/400 eServer iSeries, and System i, CL has undergone a series of improvements (and it still does to this day). While CL is not a general-purpose, high-level language (HLL), its flexibility does allow it to be used for much more than simple control operations. CL is based on commands. All program statements are nothing more than commands. Many of the commands are the same ones you would use manually, from the keyboard, to operate the computer.


CL is for everyone. Because commands can be included in a CL program, you can automate most i5 operations by writing a CL program that contains the necessary commands.

All i5 shops are, by necessity, at least bilingual, because they must support at least two programming languages — and CL is one of them. The other language should be a high-level language such as COBOL or RPG.


Because CL is part of the computer's operating system (formerly known as i5/OS, but now called IBM i), every system that runs IBM i has CL. Because every system that runs IBM i has CL, it should be the programming language of choice for any programs that do not require the higher functions provided by high-level languages like RPG. This would allow you to take the same program to another i5 with 100 percent certainty that the program will be usable. Such is not the case with other programming languages, such as RPG and COBOL, because most shops install only the compilers they need or wish to use. Yet, CL is absolutely everywhere.


With CL you can do any of the following:

* Control system power up and power down.

* Change the configuration of the system through changes in system values or line, controller, and device descriptions.

* 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.

* Control system security by performing security checks or by actually changing user and object authorities.

* Control all forms of communications between your i5 and other systems (peers, hosts, PCs, remote controllers).

* Manage objects in libraries. Objects can be created, duplicated, changed, deleted, reorganized, cleared, renamed, and allocated with CL programs.

The preceding list is not all-inclusive. CL contains more than 1,000 commands with diverse functions.


As previously noted, CL is not an HLL. CL cannot accomplish everything a language such as RPG can accomplish.

* Database manipulations are limited to reading files. You cannot directly update or write individual records in database files.

* CL supports only five data types: character, decimal, logical, signed integer, and unsigned integer.



What better way to begin a study of CL programming than by looking at a typical CL procedure?


A procedure is a compilable set of CL commands. Dissecting and analyzing the various parts of a CL procedure serve as a good introduction to CL. Figure 2.1 shows a typical CL procedure. The lines that make up a CL procedure can be called CL statements or CL commands. The two terms are interchangeable.

Figure 2.2 illustrates the structure of a typical CL procedure. The sections that follow explain each individual part of the procedure.

The PGM Command

The Program (PGM) command (Figure 2.3) identifies the beginning of the procedure.

The PARM parameter lists the parameters coming into (or going out of) the procedure. The example shown in Figure 2.3 contains only one parameter, called &GREETING, which is a CL variable.


The COPYRIGHT command (Figure 2.4) provides a way to embed copyright information within a CL module. It is optional. If used, the COPYRIGHT command must follow the PGM command, and it must precede the global MONMSG commands and all executable commands.

To view the copyright information, use the Display Module (DSPMOD) command.

The Declarations

Figure 2.5 shows some examples of declaration (DCL) commands.

Each Declare (DCL) command defines a single variable to the CL procedure. All variables must be declared at the beginning of the procedure.

The DCL command has four parameters, but only the first two are required. The first parameter, VAR, names the variable being declared. The second parameter, TYPE, indicates whether it is a character, decimal, unsigned integer, signed integer, or logical variable. The third parameter, LEN, indicates the variable's length. In addition, the fourth parameter, VALUE, gives the variable its initial value.

In Figure 2.5, the parameter keywords VAR, TYPE, and LEN have been omitted to keep the procedure uncluttered. You could also code the DCLs as shown in Figure 2.6.

Also, notice that all variables are the *CHAR (character) type. Besides DCL, the declaration section of the procedure can contain up to five Declare File (DCLF) commands. The examples shown in Figures 2.5 and 2.6 do not include any DCLF commands.


Although the Monitor Message (MONMSG) command is described at length in Chapter 6, it deserves a brief mention now. An example is shown in Figure 2.7.

The MONMSG command is used to take corrective action when an error is detected by the system after executing any command in a CL procedure. When MONMSG is coded between the declarations and the body of the procedure, it acts as a global error trap because it remains in effect throughout the execution of the procedure. If placed anywhere else, it applies only to the command that immediately precedes it.

The Body of a Procedure

Figure 2.8 shows an example of the body of a typical CL procedure.

The body of the procedure is where the action takes place. It is the meat and potatoes of the CL procedure. Although the PGM and DCL commands are needed in almost all CL procedures, they perform no real function. The commands included in the body of the procedure are another matter altogether.

In the example provided (see Figure 2.8), the first command in the body of the procedure is a Retrieve User Profile (RTVUSRPRF) command, preceded by the label "begin:". Labels are mandatory only if they point to the destination of a GOTO, LEAVE, or ITERATE command. However, you can use them anywhere you like. In this case, "begin:" marks the first executable command as the beginning of the body of the procedure.

The ENDPGM Command

The End Program (ENDPGM) command indicates the end of the procedure. The CL compiler ignores source code that follows an ENDPGM command. If you choose not to use ENDPGM, your procedure stops executing when it runs out of commands in the body of the procedure. An ENDPGM command makes your source code look better and removes uncertainty about where a procedure ends. An example is shown in Figure 2.9.

The Include CL Source (INCLUDE) Command

Before IBM i 6.1, all CL source code for a procedure had to be stored in one source member. Now it is possible to store source code in two or more members. This is especially handy for reusable code, such as error -handling procedures, that are the same for many CL procedures.

One source member must be the primary source member for a procedure. This source member may use the Include CL Source (INCLUDE) command to copy other source members into the stream of source code during compilation. This feature is similar to RPG'S /COPY and /INCLUDE compiler directives, the COBOL COPY feature, and C's #include.

INCLUDE has two parameters — SRCMBR and SRCFILE, in which you provide the names of the source member and the file containing the source code to be copied. Figure 2.10 has an example of the INCLUDE command.

The SRCFILE parameter may also have the special value *INCFILE. This value tells the compiler to retrieve the source file name from the INCFILE parameter of the command that was used to invoke the compiler.


Before you start the Source Entry Utility (SEU) to enter CL source code, choose a library in which to keep the source. Make sure the library you select has a source physical file to contain the CL source code.

The Source Physical File

CL source is stored, by IBM's default, in a source physical file called QCLSRC. You don't need to use that name. You can call your file CLSOURCE, SOURCE_CL, or even FRED. It really makes no difference. However, the commands used to compile CL source members have a default value of QCLSRC in the parameter that asks for the name of the source physical file. You save time by using QCLSRC.

If you don't have a QCLSRC file, create it by executing the command shown in Figure 2.11. MYLIB stands for the name of the library where you want to place the file.

Starting SEU

You must enter the source code for the procedure with SEU. You can start SEU either manually or from the Program Development Manager (PDM). To start SEU manually, type STRSEU at the command line and press F4. The panel shown in Figure 2.12 appears.

Type in the parameter values shown and press Enter.

To start SEU from PDM, go to the Work with Members Using PDM (WRKMBRPDM) panel and press F6 to create a new member.

Formatting the Statements with F4

CL procedures consist of free-format statements. As it does with DDS or other programming languages like RPG, the meaning of the code doesn't depend upon a columnar (or linear) location. This gives you a sense of freedom to write the code the way you want it. With CL, nothing prevents you from entering the source for the HELLO procedure as shown in Figure 2.13.

You can enter the CL code this way if you prefer. The compiler does not differentiate between easy- and hard-to-read source code. The compiler will compile the procedure just the same, and your procedure will work just as well.

Because humans have a sense of aesthetics, it is easier (and more pleasant) to work with source code that looks good and is easy to read rather than to deal with a monster like the one just presented. On the other hand, you could press the F4 key and the Enter key on each statement and end up with another style. See Figure 2.14.

Most programmers like leaving the formatting to the command prompter (activated when you press F4 while entering the source code). The source code shown in Figure 2.14 was formatted with the command prompter.

All you need to do to activate the prompter is type the name of the command anywhere on a blank line and press the F4 key. Now you can fill in the blanks and press Enter. The F4 key works this way because you have specified a source type of CLLE, which activates the CL programming syntax checker and the command prompter. You also can type the command using free format (including parameters with or without keywords) and then press F4 followed by Enter.

For example, the command prompter will format the Change Variable (CHGVAR) command from the format shown in Figure 2.15 to the format shown in Figure 2.16.

The command prompter does the following for you:

* Starts labels in column 2.

* Forces the command name in column 14.

* Starts parameters in column 25.

* Adds keywords to all parameters.

* Indents all continuation lines two positions to the right, beginning in column 27.

* Inserts or deletes lines as needed to make the command occupy as much of the display as possible, never exceeding column 71.

* Translates all labels, command names, and keywords to capital letters if entered in lowercase letters.

* Translates unquoted single-word character strings into capital letters.

* Automatically surrounds unquoted multiple-word character strings with single quotes.

* Doubles any embedded single quotes.

* Enables you to change an existing line by placing the cursor on the line and pressing F4. The command prompter shows the command with the parameters as they are coded. Now you can change some of the parameters and press Enter. The command prompter reformats the command and, if necessary, adds or deletes lines in the CL source code.

More experienced CL programmers would choose not to use the command prompter (and you might do so with time). When you stop using the prompter, the responsibility of formatting the CL source code will be entirely yours.

Uppercase or Lowercase?

The CL compiler does not interpret commands, keywords, labels, or unquote character literals differently because they are written in lowercase letters instead of uppercase. The source code compiles either way. You must decide which case to use.

Because the command prompter translates to uppercase, you might want to stick to uppercase lettering. If you don't use the prompter, then it is up to you. You can execute the SET CAPS OFF command at the SEU===> command line to enable lowercase entry or SET CAPS ON to return to all uppercase. The HELLO source code looks different in lowercase letters. See Figure 2.17.

Positional Parameters or Keywords?

Command parameters can be entered in two forms: positionally or with keywords.

Because they are easier to type, positional parameters are the method of choice when commands are executed manually. After all, no one has to read the command after it has been executed from the keyboard.

When you enter commands into a CL source member, the procedure executes just as well either with or without keywords. However, the statements might be easier to read when keywords are included. This decision is up to you; whether it's easier with or without keywords is a matter of opinion.

To give you an idea of the difference, consider the example shown in Figure 2.18. The first Create Duplicate Object (CRTDUPOBJ) command is coded without keywords (positionally); the second is coded with keywords. The second version is more readily understood.

On the other hand, some commands you'll use all the time, such as the Change Variable (CHGVAR) command, have two parameters. Figure 2.19 shows two versions (without keywords and with keywords).

In this case, both versions are easy to understand. Another case is the GOTO command as shown in Figure 2.20.

The inclusion of the CMDLBL keyword does little (if anything) to enhance code clarity.

The style of source code you write is a matter of personal choice or of adherence to your shop's standards. Appendix B describes the subject of code style in some detail.

Continuing on the Next Line

When a CL command has more parameters than a single line can hold, it must be continued on one or more next physical lines. This is accomplished in CL by ending a line with a plus (+) or a minus (—) sign.

If you use the command prompter (F4 key) to format your statements, these signs are entered automatically wherever they are needed. If you don't use the prompter, it is your responsibility to enter the continuation symbols yourself.

The difference between + and — is how the next line is interpreted by the compiler. If you use a + sign, the compiler ignores all leading blanks in the next line. The continuation line effectively begins with the first non-blank character. If you use a — sign, however, the compiler includes all leading blanks of the continuation line, and makes these blanks part of the statement.

This difference is important only when you separate the statement somewhere in the middle of a character constant. The example shown in Figure 2.21 clarifies this point.

Variable &x will contain 'AB CD' (one blank between AB and CD) because there is a blank space between the B and the + sign. All leading blanks on the next line are ignored. Figure 2.22 shows the same command using a — sign as the continuation character.

In this case, &x will contain 'AB CD' (ten blanks between AB and CD). There is one blank between the B and the — sign, and the next line has nine leading blanks.

Indented or Unindented?

You can take advantage of CL's free-format nature to indent your code. When you indent your CL source code, the scope of DO/ENDDO groups becomes more readily apparent and source statements are much easier to understand. The more complex your procedure, the greater the benefit obtained by indenting the code.

Incidentally, using the command prompter (F4) to format your code destroys whatever indentation you create in your code. As mentioned earlier, the prompter forces the command to start at position 14 and parameters begin at position 25.


Excerpted from Complete CL by Ted Holt. Copyright © 2009 MC Press Online, LP. Excerpted by permission of MC Press.
All rights reserved. No part of this excerpt may be reproduced or reprinted without permission in writing from the publisher.
Excerpts are provided by Dial-A-Book Inc. solely for the personal use of visitors to this web site.

Table of Contents


Title Page,
Copyright Page,
MC PRESS on line,
System i Books from MC Press,

Customer Reviews

Most Helpful Customer Reviews

See All Customer Reviews