The IBM i Control Language, or CL, is the human interface to one of the most successful computing platforms ever. Mastery of this language is necessary to get the greatest benefit from the IBM i server. This book helps programmers and system administrators using IBM i get the most out of the platform by writing useful CL programs. This new edition has been updated for IBM i 7.3 and includes new built-in functions, new data types, and new support for SQL. Upon completion of the book, readers will be able to write and compile robust, production-grade programs in the IBM i Control Language, guided by a CL expert.
|Publisher:||MC Press, LLC|
|Product dimensions:||7.00(w) x 9.00(h) x 1.00(d)|
About the Author
Ted Holt holds a Master of Science degree in computer science from the University of Southern Mississippi and has taught at universities, community colleges, and vocational-technical schools. He has written numerous articles and technical tips for print and online publications, and is the author or coauthor of eight books, among them Complete CL, Power CL, and Qshell for iSeries.
Read an Excerpt
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 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.
Who Needs CL?
CL is for everyone. Because commands can be included in a CL program, you can automate most IBM i operations by writing a CL program that contains the necessary commands.
All IBM i 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.
Who Has CL?
Because CL is part of the computer's operating system, 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 IBM i system 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.
Capabilities of CL
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 IBM i system 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.
Limitations of CL
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 use CL commands to directly update or write individual records in database files. CL procedures can call APIs and run SQL commands to interact with databases, but not with the ease that HLLs can.
CL supports only six data types: character, decimal, logical, signed integer, unsigned integer, and pointer.
A First Look at CL
What better way to begin a study of CL programming than by looking at a typical CL procedure?
The Parts of a 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 PGM (Program) 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
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 (Monitor Message) commands and all executable commands.
To view the copyright information, use the DSPMOD (Display Module) command.
Figure 2.5 shows some examples of DCL (Declare CL Variable) commands.
Each 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 eight 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, logical, or pointer variable. The LEN parameter, indicates the variable's length. In addition, the VALUE parameter gives the variable its initial value. The other four parameters are used much less frequently than these.
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 DCLF(Declare File) commands. The examples shown in Figures 2.5 and 2.6 do not include any DCLF commands.
You may also include a DCLPRCOPT (Declare Processing Options) command in the declarations. Use this command to specify compiler options. In this way, you will ensure that future compilations are created with the proper option values and avoid nasty surprises that could arise if the wrong option values were used. Options that are specified in DCLPRCOPT override the options in the CRTBNDCL (Create Bound CL Program), CRTCLMOD (Create CL Module), and CRTCLPGM (Create CL Program) commands.
Although the 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, MONMSG 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 RTVUSRPRF (Retrieve User Profile) 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 body may also include subroutines, which allow a task to be broken into smaller, more manageable tasks. Because of the nature of the work they are written to preform, CL procedures typically do not include subroutines.
The ENDPGM Command
The ENDPGM (End Program) 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 Command
It is possible to generate one CL procedure from 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.
A CL source member may use the INCLUDE (Include CL Source) 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 shows 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.
Entering the Source Code
To enter source code into an IBM i system, you must use an editing program ("editor" for short). The editor that has been used since the first AS/400 systems is Source Entry Utility (SEU). It is a text-based full-screen editor that was designed for terminals.
The new editor is Rational Developer for i (RDi). It is a graphical editor that runs on a client system and provides many advantages over SEU. It is better to use RDi than SEU for program development and maintenance. However, there are at least two reasons you should know how to use SEU.
You may have to work on a system for which RDi is not available.
You may find it easier to use SEU for small, quick changes to a source member.
Before you start 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.
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 traditional 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 CHGVAR (Change Variable) 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 at some point). 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 unquoted 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 CRTDUPOBJ (Create Duplicate Object) 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 that you'll use all the time, such as the CHGVAR (Change Variable) 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 line. 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.
Excerpted from "Complete CL"
Copyright © 2017 Ted Holt.
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
Chapter 1: Introduction,
Chapter 2: A First Look at CL,
Chapter 3: Constants and Variables,
Chapter 4: Basic Operators and Functions,
Chapter 5: Control Statements,
Chapter 6: Message Management,
Chapter 7: Interprogram and Intermodule Communications,
Chapter 8: Job and System Interface,
Chapter 9: Using Files,
Chapter 10: Using Quotes,
Chapter 11: Managing Objects,
Chapter 12: Batch Job Processing,
Chapter 13: Advanced Topics,
Chapter 14: Security Considerations,
Chapter 15: Sign-on Programs,
Chapter 16: Debugging,
Chapter 17: CL and the Integrated Language Environment,
Appendix A: Some Utility Commands,
Appendix B: CL Coding Style,
Appendix C: Sample Sign-on Program,
Appendix D: The Original Program Model,