Command Parameters

Command Parameters

Most CL commands allow you to specify one or more command parameters to define what a CL command will do. A parameter is simply a value, specified along with the command, that tells the command explicitly what to do or how to do it. The CL command DSPTAP, the AS400 will not have enough information to process the command. The AS400 can have several different magnetic tape devices attached to it, and each tape device will have its own name. To display the contents of a tape, the computer needs to know specifically the name of the tape device you want to use. To direct the AS400 to use a certain tape device, you must specify, along with the DSPTAP command, the name of that device. You would need to enter the command as

DSPTAP DEV(TAP01)

where DSPTAP is the command to execute, DEV is the parameter keyword, and TAP01 is the parameter value — in this case the name of the tape device that will be used. You must separate the command and each of its parameters with one or more spaces. When you use parameter keywords like DEV, the actual parameter value must be enclosed in parentheses.

Required and Optional Parameters

Most CL commands have multiple parameters that may be specified to further define what the command should do. These parameters fall into two categories: required and optional. A required parameter is one that must be specified for the AS400 to execute a CL command. An optional parameter may be specified, but is not required for successful execution of the CL command. A few commands, such as DO and ENDDO, have no parameters.

In the earlier example above, the value for the DEV parameter keyword on the DSPTAP command must be explicitly supplied. Specifying a value for DEV indicates to the AS400 which tape device
to use for the command. The DEV parameter is an example of a required parameter.

The DSPTAP command has four other parameters for which a value may be supplied, but CL does not require that you do so. Parameters such as these are called optional parameters. CL assigns default values for optional parameters. The defaults are set to values that IBM assumes will be used most often. The default value will be used during the execution of the command unless you specifically enter a value for the optional parameter. The following example shows the DSPTAP command with the required DEV parameter and its four optional parameters. In this example, the IBM-supplied default values are shown for the optional parameters.
Think of all the lines in this example as a single command, entered on one line. The plus sign (+) is used for continuing a CL command onto more than one line, which we discuss in later topic.)

DSPTAP DEV(TAP01) +
LABEL(*ALL)       +
SEQNBR(1)         +
DATA(*LABELS)     +
OUTPUT(*)

As you can see, the last command parameter that you may specify for the DSPTAP command uses the parameter keyword OUTPUT. The default value for the parameter is *. When the parameter default of * is not changed, it tells the DSPTAP command to display the contents of the tape interactively on your workstation screen. However, if you want to send the output of the DSPTAP operation to a printed report instead of to your workstation screen, you may enter the display tape command as follows:

DSPTAP DEV(TAP01) +
OUTPUT(*PRINT)

This command syntax overrides the IBM-supplied default value for the OUTPUT parameter and causes a printed listing to be generated that reports on the contents of the magnetic tape.

Because specifying OUTPUT(*PRINT) is not required to execute the DSPTAP command, OUTPUT is considered an optional parameter. It is optional because the CL command can be successfully executed by
the AS400 using the IBM-supplied default value* for the parameter. You need to specify only the required parameters, and any optional parameters for which you do not want to use the IBM-supplied default values.

Therefore, using either of the following two command syntax forms will produce the same result:

Command syntax including the default values:

DSPTAP DEV(TAP01) +
LABEL(*ALL)       +
SEQNBR(1)         +
DATA(*LABELS)     +
OUTPUT(*PRINT)

or

Command syntax omitting the default values:
DSPTAP DEV(TAP01) +
OUTPUT(*PRINT)

If you use the second syntax shown, the AS400 assumes you want to use the default values shown in the first syntax structure for the LABEL, SEQNBR, and DATA parameters.

Entering Parameters with Keyword Notation 

In the previous examples we have presented CL commands in what is called keyword notation. Keyword notation presents all of the command parameters preceded by their corresponding keyword. For instance, in our example using the DSPTAP command,

DSPTAP DEV(TAP01) +
OUTPUT(*PRINT)

keywords DEV and OUTPUT are used to identify the associated parameter values, TAP01 and *PRINT. When keywords are used, the order in which the parameters are specified is not significant. The keyword itself identifies the parameter to the command. For example, the following two CL command syntax forms shown in keyword notation are equivalent:

DSPTAP DEV(TAP01) +
OUTPUT(PRINT)

or

DSPTAP OUTPUT(*PRINT) +
DEV(TAP01)



 

Entering Parameters with Positional Notation

Every CL command that has parameters allows those parameters to be entered in keyword notation. You also have the option to specify many, but not all, parameters in what is called positional notation. In positional notation, keywords are not used. Instead, parameters are specified in a predetermined positional order. When you use positional notation, you must specify the parameter values in the correct order. The DSPTAP command is first shown here with keyword notation, then with positional notation.

Keyword notation:

DSPTAP DEV(TAP01)

Positional notation:

DSPTAP TAP01

Because the DEV parameter is the first command parameter, it must be specified first in positional notation. Usually, commands with only one or two parameters specified are easy to read and understand when presented in positional notation. For example, even without knowing what they do, you can easily read and
understand the following CL commands:

DSPTAP TAP01
DSPLIB MYLIBRARY
GOTO   ENDOFPGM
CALL   PROGRAM1

When you specify multiple parameters in positional notation, however, readability suffers. In the following example, the CPYF (Copy File) command is presented. This is the CL command to copy data from one file to another. First the keyword notation is shown for specifying multiple parameters, then the positional notation.

Keyword notation:

CPYF FROMFILE (AFILE)  +
     TOFILE (BFILE)    +
     FROMMBR (MEMBER1) +
     TOMBR (MEMBER2)   + 
     MBROPT (*ADD)

Positional notation:
CPYF AFILE   +
     BFILE   +
     MEMBER1 +
     MEMBER2 +
     *ADD

You can see from this example of positional notation that, unless you are familiar with the CPYF command, it is difficult to understand the meaning of the command parameters. What makes it difficult is that you cannot see which keywords are being used for which parameters. The keywords provide a frame of reference to the parameters, and in most cases, make the command easier to read.

The Order of Parameters

As we mentioned earlier, when you use positional notation to specify command parameters, you must carefully consider the order in which you specify the parameters. IBM has created the AS/400 CL command set with a predefined order in which you must specify parameters when using positional notation. The IBM publication Control Language Reference provides the documentation regarding allowable parameter values and the order in which the parameters must be specified.

As an example of the predefined order of parameters, consider again the CPYF command. The CPYF command requires that when using positional notation, the parameters be specified in the order shown below:

CPYF from-file-name       +
     to-file-name         +
     from-member-name     +
     to-member-name       +
     add-replace-option   +
     create-tofile-option

1. The file to copy from (FROMFILE keyword). This is a required parameter.
2. The file to copy to (TOFILE keyword). This is a required parameter.
3. The file member to copy from (FROMMBR keyword). This parameter is optional; the default value is *FIRST.
4. The file member to copy to (TOMBR keyword). This parameter is optional; the default value is *FIRST.
5. Option to add or replace records (MBROPT keyword). This parameter is optional; the default value is *NONE.

Positional Keyword Limits

Every CL command limits the number of positional parameters that may be specified for the command. For example, the DSPTAP command allows you to use only one positional parameter. Therefore, if you want to specify more than one parameter value, you cannot enter the DSPTAP command in purely positional notation. You cannot enter the DSPTAP command as follows:

DSPTAP TAP01   +
       *ALL    +
       1       +
       *LABELS +
       *PRINT

Even if you could use the above format for the DSPTAP command, the resulting command would be difficult to understand. For the DSPTAP command, you can use positional notation only for the first parameter DSPTAP TAP01.

The CPYF command is one command that allows several positional parameters. This command allows up to six positional parameters. So you could enter the CPYF command as follows:

CPYF AFILE   +
     BFILE   +
     MEMBER1 +
     MEMBER2 +
     *ADD    +
     *YES

The CPYF command has many more parameters than are shown here, but six is the maximum number of parameters that may be specified using positional notation. This maximum is set individually for each command. You can determine the maximum number of positional parameters that can be used for a CL command by using the DSPCMD (Display Command) command to display a description of the command.

Note that even though some of the parameters for the CPYF command are optional, you may need to include an entry for them if you use positional notation. For example, if you want to specify a value for the fourth parameter (TOMBR), you will have to include a value for the third parameter (FROMMBR), even if that value is the default *FIRST. Otherwise, the fourth parameter will not be in the fourth position of the
parameter list.

Using *N 

What if you want to use positional notation for a command, and you want to use default values for some of the parameters? You could explicitly type the default values, but there is an alternative notation you can use to specify default values when using positional notation. The value *N may be used as a place holder within

a positional notation list of parameters. For example, instead of specifying the CPYF command as:

CPYF AFILE    +

     BFILE    +
     *FIRST   +
     *FIRST   +
     *REPLACE

you could use the place holder *N and specify

CPYF AFILE    +

     BFILE    +
     *N       +
     *N       +
     *REPLACE

This command syntax would cause the IBM-supplied default values to be used for parameters 3 and 4 (the FROMMBR and TOMBR keywords), corresponding to the positions of the value *N. The value *N is called a predefined value. IBM-supplied predefined parameter values in CL are always preceded by an asterisk (*), helping you to easily identify them.

Mixing Keyword and Positional Notation 

The predefined value *N is seldom used because it is not very easy to read or write. When you want to specify only certain parameters, keyword notation is often easier to read and write, and it has the added advantage of being somewhat self-documenting. An alternative to using the value of *N is available. It is possible to combine keyword notation and positional notation on the same command. Consider the following example:

CPYF AFILE             +

     BFILE             +
     MBROPT (*REPLACE)

The positional entries of AFILE and BFILE are followed by the keyword entry of MBROPT(*REPLACE). When positional entries are mixed with keyword entries, the positional entries must be specified first, in the correct order. Keyword entries may then follow in any order. Once you begin using keyword notation in a command, you must use keyword notation for all subsequent parameters for that command. Combining positional notation with keyword notation usually produces the best compromise between readability and ease-of-entry. The use of *N should be discouraged. There is not a need to memorize command or parameter, note that the prompting facility allows you to easily determine the parameters that may be specified for any CL command and will even help you find out which command to use to perform a

task.

Types of Command Parameters

CL commands allow several different types of parameters to be used. Certain parameters require that a character string be specified as the parameter value; others require decimal values. The parameter type will depend upon the context of the parameter; that is, what parameter information the command needs to function. For example, in the DSPTAP command the first parameter, DEV, requires that a device name be specified, as in DSPTAP DEV(TAP01). The third parameter, SEQNBR, requires that a numeric integer value of the tape sequence number be specified, as in DSPTAP DEV(TAP01) SEQNBR(1). Names and integer values are only two of the parameter types that may be used by a CL command

Parameter Special Values

When you use the DSPTAP command, you will notice that some of the parameter values begin with an asterisk (*).

DSPTAP DEV (TAP01)    +
       LABEL (*ALL)   +
       SEQNBR (1)     +
       DATA (*LABELS) +
       OUTPUT (*PRINT)

In the command above, you can see that we specified the LABEL parameter as *ALL, the DATA parameter as *LABELS, and the OUTPUT parameter as *PRINT. Parameter values such as these that begin with an asterisk (*) are called special values. A special value allows a parameter value to be outside the normal checking rules for parameters. For example, the DSPTAP command expects to see a file label name as the value for the LABEL parameter. But the command allows you to specify the value *ALL, instead of a valid file label name, to indicate that all files on the tape are to be processed. In this case, CL reserves the meaning of the value *ALL for a specific purpose. Many command parameters allow you to choose from one or more special values that are predefined for the parameter. Note that, although the predefined value *N begins with an *, it is not considered to be a special value; it is simply a place holder when positional notation is used.

Qualified Values

Occasionally, a command parameter allows you to specify a two- or three-part parameter value, known as a qualified value or qualified name. This form of parameter value is usually used when dealing with system objects such as file names or job names. For example, if you wanted to refer to the file named CUSTOMER in library ARLIB, you could specify a single entry, ARLIB/CUSTOMER. The slash (/) is the qualifier character, separating the two parts of the value. In the following example, the DSPPFM (Display Physical File Member) command uses a qualified parameter value to specify the file name:
DSPPFM FILE(ARLIB/CUSTOMER)

Parameter Value Lists

Some command parameters allow you to list more than one value. For example, the RSTOBJ (Restore Object) command allows you to specify the names of one or more (up to 300) objects that you want to restore from backup media. This command uses a simple list to identify these objects:

RSTOBJ OBJ(CUSTOMER INVOICES PAYMENTS) +
       SAVLIB(ARLIB)                   +
       DEV(TAP01)                      +
       OBJTYPE(*FILE)

In this example, we want to restore three files: CUSTOMER, INVOICES, and PAYMENTS. The elements of the list in the OBJ parameter must be separated by at least one blank.

When you use a parameter value list, you must enclose the list in parentheses, even if you use positional notation for the parameters. The following example, while it might seem correct at first glance, will not work:

RSTOBJ CUSTOMER INVOICES PAYMENTS +
       ARLIB                      +
       TAP01                      +
       *FILE

Because we are using positional notation, the AS400 reads the first three values as individual parameters, not as elements of the OBJ parameter list. Consequently, the AS400 will try to restore CUSTOMER to a library named INVOICES, using the tape on the non-existent device named PAYMENTS. In addition, the computer will not know how to handle what it sees as three additional positional parameter values: ARLIB, TAP01, and *FILE. The following example corrects the situation by enclosing the list parameter in parentheses:

RSTOBJ (CUSTOMER INVOICES PAYMENTS) +
       ARLIB                        +
       TAP01                        +
       *FILE

Complex Lists

In rare situations, you will have parameter values that include a list within another list, also called a complex list, as in the following example:

RSTOBJ OBJ(*ALL)                          +
       SAVLIB(ARLIB)                      +
       DEV(TAP01)                         +
       OBJTYPE(*ALL)                      +
       FILEMBR((CUSTOMER (COMP01 COMP02)) +
       (INVOICES (COMP01 COMP02))         +
       (PAYMENTS (COMP01 COMP02)))        +
       MBROPT(*ALL)

In this example, we are restoring only the file members COMP01 and COMP02 from each of the files CUSTOMER, INVOICES, and PAYMENTS. The major list and the sublist are each enclosed in their own sets of parentheses, so it's not a trivial task to read the command as it is written.





Control Language Command Names

Verbs and Subjects
 
CL command names are a shorthand form of the standard grammar for an English Language imperative statement. Each command is an instruction to the computer to perform an action. The command consist of a verb, or action, part and a noun, or receiver of the action, followed by the subject that will be acted upon(an object in the grammatical sense, but because object has specialized meaning on the AS400/i-Series, to avoid confusion we use the word subject).
 
Command names are limited to a maximum length of 10 characters. The verbs are ususally represented by 3 characters. The subject represented by 1 or 3 characters.
 
A general rule of thumb is that CL abbreviates words to their three most significant consonants. When a CL abbreviation include a vowel, it is usually the first vowel or the only vowel in a word. There are however exception to this rule, example LIB to represent Library.
 
Adjectives and Subject Phrases
 
At times, using a simple subject is not sufficient. In these cases, CL also allows you to specify an adjective to be associated with the subject. Example WRKACTJOB(Work with Active Jobs). Specifying the adjective ACT, CL shorthand for the adjective active, effectively limits the scope of the command to working with active jobs only.
 
In some cases, the names of the command does not fit into the verb/adjective/subject structure. For example, consider the DSPPFM (Display Physical File Member) command. This command combines the verb DSP(display) with a subject phrase containing an adjective, P (Physical), and two subjects, F (File) and M (Member). Other commands, like ADDPFM(Add Physical File Member), CHGPFM (Change Physical File Member), and RGZPFM (Reorganize Physical File Member) use the same subject phrase (PFM). This verb/subject phrase structure complicates selecting the correct name of a CL command, but the structure is not used heavily in CL.
 

What is CL(Control Language) ?

What CL Is

AS400/ i-Series Control Language (CL) is a set of commands that use to control operations and to request system related function on the IBM AS400 computer.

IBM provides CL as an integrated part of the OS/400 operating system, not as separate product.

CL commands can be used at least two ways:

1. by typing them individually onto an AS/400 command line, or
2. by grouping them together into a CL program

CL programs typically consist of multiple CL commands that define procedures or operations on the AS/400. By combining multiple commands within a CL program, you can automate most AS/400 operation.

What CL Is Not

• CL is not high level language(HLL)
• CL is not use to create business application(example perform add or update records in a database file/table)
• CL have limited printing capabilities
• CL does not support the use of sub files within the application displays
• CL does not support individual fields in program describe files/table

Manipulations using CL, are limited to reading files and only a single file can be opened for I/O(Input/Output) operations. This make CL unsuitable for developing a complete business application.

Controlling Workflow with CL

CL programs control the workflow of an application by allowing you to create job-streams, which consist of CL commands to be executed in order.

Within a CL program you can:

• alter the order of execution by testing various conditions that may exist during the execution of a job.
• have statement/command to monitor for errors that might occur while running a job and perform corrective actions or abort the job
• incorporate conditional logic and
• special functions that are not available when you enter individual commands on the command line.

CL program can :

• pass values to and from CL programs
• pass parameters to and from CL programs

to make them more flexible and to permit or restrict the execution of blocks of program code. You can test and debug CL program just like HLL program.

CL programs, unlike JCL(Job Control Language), are implemented as compiled program objects, rather than interpreted job streams. A CL program is a permanent object created by compiling a group of CL commands.

CL Execution Environment and Restrictions

CL command may be entered into the system interactively on command line or in a CL program. Individual CL commands and complied CL programs can be submitted for batch processing using the SBMJOB(Submit Job) command. Command can be included with a language procedure.

Another command SBMDBJOB(Submit Database Job) can be use for submitting for interpretation or compiled into a program object for batch processing.

Example of command that used interactively. STRSEU(Start Source Entry Utility).

Example of command that used within in batch process. CRTCLPGM(Complile a CL Program)

Example of commands that are valid within a CL program. GOTO and ENDPGM.

Example of a CL Program and is it output

Source member:


Output:

 

AS400/ i-Series - Programming - Control Language (CL)

AS400/ i-Series - Programming - Control Language (CL)

1. Introduction
• What is CL
• What is CL
• What CL Is Not
• Controlling Workflow with CL
• CL Execution Environment and Restriction
• Control Language Command Names
• Command Parameters
• The AS400/ i-Series User Interface
2. Basic CL Programming
• Create CL Programming
• Structure of a CL Source Member
• Declaring Program Variables
• Manipulating Variables with the CHGVAR Command
• CL Control Structure
• Expressions
• Controlling Workflow
• Basic Error Handling
3. Input/ Output in CL Programming
• Passimg Program Parameters
• Retrieving and Changing External Attributes
• Files and Data Area
4. Advance CL Programming
• Advance Message Handling
• Advance File Techniques
• Advance Command Prompting
• Using IBM Supplied APIs
• Displaying and Changing Command Attributes
• Understanding the Job Log
• Introduction to the Integrated Language Environment (ILE)
5. Creating your own command
• User Defined Commands
• Command Processing Programs
• Advance Command Facilities

AS400/ i-Series

1. Installation/ Setup
2. Operations
3. System Management
4. File Basics
5. Programming
• Data Description Specifications (DDS)
• Control Language (CL)
• RPG (Report Program Generator)
• SQL (Structure Query Language)
• JAVA

Operating System

1. AS400; AS/400; OS400; OS/400; i-Series