This information helps you define your own CL commands and provide documentation for them.
A CL command is a statement that requests that the system perform a function. Entering the command starts a program that performs the function.
When you define and create your own CL commands, you might also want to provide documentation for them.
You can define a CL command by entering command definition statements into a source file and running a Create Command (CRTCMD) command using the source file as input.
Defining a CL command
To create a command, you must first define the command through command definition statements.
The general format of the command definition statements and a summary of the coding rules follow.
For example, we will create a command SPOOL to see spool files of a specific user id.
SPOOL is the name of the new command (specified by the CMD parameter).
SPOOLCL is the name of the command processing program (specified by the PGM parameter) and also the name of the source member that contains the command definition statement (specified by the SRCMBR parameter).
1. Enter the command definition source statement into the source file QCMDSRC using the member name of SPOOL .
CMD PROMPT('DISPLAY SPOOL FILES')
PARM KWD(USERID) TYPE(*CHAR) LEN(10) PROMPT('User +
Id')
2. Enter the source statements for the SPOOLCL program (the command processing program).
PGM PARM(&USERID)
DCL VAR(&USERID) TYPE(*CHAR) STG(*AUTO) LEN(10)
WRKSPLF SELECT(&USERID)
ENDPGM
3. Create the program using the Create Bound CL Program (CRTBNDCL) command.
CRTBNDCL SPOOLCL
4. Create the command by entering the following command
CRTCMD CMD(TESTLIB/SPOOL) PGM(TESTLIB/SPOOLCL) SRCFILE(TESTLIB/QCMDSRC)
Type WRKOBJ to see the object SPOOL. It is of object type *CMD
Type DSPCMD to display the command details.
DSPCMD SPOOL
Now run the command SPOOL on command line. Type SPOOL and F4.
If we change the code as below to give possible values for the parameter in the code as below. QUAL is used to list the possible values of a Parmeter.
When the command is prompted, we see the possible values here.
When F4 is taken on USER ID, it appears liek this:
Examples: Changing CL command defaults:
These examples show how to change default values for CL commands.
To provide a default value of *NOMAX for the MAXMBRS keyword of command Create Physical File (CRTPF), do the following:
CRTPF FILE(FILE1) RCDLEN(96) MAXMBRS(1)
.
.
CHGCMDDFT CMD(CRTPF) NEWDFT(’MAXMBRS(*NOMAX)’)
To provide a default value of 10 for the MAXMBRS keyword of the command Create Physical File (CRTPF), do the following:
CRTPF FILE(FILE1) RCDLEN(96) MAXMBRS(*NOMAX)
.
.
CHGCMDDFT CMD(CRTPF) NEWDFT(’MAXMBRS(10)’)
The following provides a default value of 'Isn't this print text' for the PRTTXT keyword of the command Change Job (CHGJOB). Because the NEWDFT keyword has embedded single quotation marks, you must not double these single quotation marks, or the process will not run correctly.
CHGJOB PRTTXT(’Isn’’t this print text’)
.
.
CHGCMDDFT CMD(CHGJOB) +
NEWDFT(’PRTTXT(’’Isn’’’’t this print text’’)’)
Command to display an output queue:
This example shows how to define and create a CL command that displays an output queue.
You can create a command to display an output queue that defaults to display the output queue PGMR. The following command, Display Output Queue (DSPOQ), also allows the display station user to display any queue on the library list and provides a print option.
The command definition statements for the Display Output Queue (DSPOQ) command are:
CMD PROMPT(’WRKOUTQ.-Default to PGMR’)
PARM KWD(OUTQ) TYPE(*NAME) LEN(10) DFT(PGMR) +
PROMPT(’Output queue’)
PARM KWD(OUTPUT) TYPE(*CHAR) LEN(6) DFT(*) RSTD(*YES)
VALUES(* *PRINT) PROMPT(’Output’)
The RSTD parameter on the second PARM statement specifies that the entry can only be one of the list of values.
The command processing program for the Display Output Queue (DSPOQ) command is:
PGM PARM(&OUTQ &OUTPUT)
DCL &OUTQ TYPE(*CHAR) LEN(10)
DCL &OUTPUT TYPE(*CHAR) LEN(6)
WRKOUTQ OUTQ(*LIBL/&OUTQ) OUTPUT(&OUTPUT)
ENDPGM
The Create Command (CRTCMD) command is:
CRTCMD CMD(DSPOQ) PGM(DSPOQ) SRCMBR(DSPOQ)
The following command, DSPOQ1, is a variation of the preceding command.
The command definition statements for the DSPOQ1 command are:
CMD PROMPT(’WRKOUTQ.-Default to PGMR’)
PARM KWD(OUTQ) TYPE(QUAL1) +
PROMPT(’Output queue:’)
PARM KWD(OUTPUT) TYPE(*CHAR) LEN(6) RSTD(*YES) +
VALUES(* *PRINT) DFT(*) +
PROMPT(’Output’)
QUAL1: QUAL TYPE(*NAME) LEN(10) DFT(PGMR)
QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) +
SPCVAL(*LIBL)
The QUAL statements are used to define the qualified name that the user can enter for the OUTQ parameter. If the user does not enter a name, *LIBL/PGMR is used. The SPCVAL parameter is used because any library name must follow the rules for a valid name (for example, begin with A through Z), and the value *LIBL breaks these rules. The SPCVAL parameter specifies that if *LIBL is entered, the IBM i operating system is to ignore the name validation rules.
The command processing program for the DSPOQ1 command is:
PGM PARM(&OUTQ &OUTPUT)
DCL &OUTQ TYPE(*CHAR) LEN(20)
DCL &OBJNAM TYPE(*CHAR) LEN(10)
DCL &LIB TYPE(*CHAR) LEN(10)
DCL &OUTPUT TYPE(*CHAR) LEN(6)
CHGVAR &OBJNAM %SUBSTRING(&OUTQ 1 10)
CHGVAR &LIB %SUBSTRING(&OUTQ 11 10)
WRKOUTQ OUTQ(&LIB/&OBJNAM) OUTPUT(&OUTPUT)
ENDPGM
CL commands and command online help:
Command prompting and online command help are powerful features of CL commands.
The first step is to understand how the connections work between commands and command help.
- Command help information is stored in panel group objects. The symbolic object type for a panel group is *PNLGRP. A help panel group consists of help modules. Each help module has a help module name.
- There are two parameters on the Create Command (CRTCMD) command that make the connection between a command (*CMD) object and an online help panel group: HLPID (Help identifier) and HLPPNLGRP (Help panel group).
- There are four types of command help modules in an online help panel group:
1. Command-level help module
2. Parameter-level help module
3. Command examples help module
4. Command error messages help module
After you understand how a CL command (*CMD) object can be connected to an online help panel group (*PNLGRP) object, you can write the help text that goes into the four types of help modules for a command.
Online help for CL commands is written in a tag language known as user interface manager (UIM). The UIM source is compiled using the Create Panel Group (CRTPNLGRP) command to create a *PNLGRP object.
Generating UIM source for CL command help:
As a simpler alternative to learning UIM syntax, you can use the Generate Command Documentation (GENCMDDOC) command to generate online help for CL commands. With this command, you can create a file that contains UIM source. The file provides a template for the online command help.
To create the UIM source, you need to specify *UIM for the GENOPT (Generation Options) parameter. The information used to create the template is retrieved from the command object (*CMD) you specify. Using Generate Command Documentation (GENCMDDOC) to create the UIM source can simplify writing online help for your CL commands.
The following is an example of using the Generate Command Documentation (GENCMDDOC) command to generate a UIM template:
GENCMDDOC CMD(MYLIB/MYCMD)
TODIR(’/QSYS.LIB/MYLIB.LIB/QPNLSRC.FILE’) TOSTMF(*CMD)
GENOPT(*UIM)
After you have edited the UIM source to tailor it to your command, you can create the online help panel group by using the Create Panel Group (CRTPNLGRP) command. The following example shows how to use the Create Panel Group (CRTPNLGRP) command: CRTPNLGRP PNLGRP(MYLIB/MYCMD) SRCFILE(MYLIB/QPNLSRC) SRCMBR(MYCMD)
Proxy CL commands
Proxy commands are used to create shortcuts to target CL commands. A proxy command differs from a typical IBM i command in its ability to run a target command, rather than a command processing program.
Use the Create Proxy Command (CRTPRXCMD) to create a proxy command. Create Proxy Command (CRTPRXCMD) requires a Command name (CMD) and a Target command (TGTCMD).
Optional parameters include a Text description (TEXT), Authority (AUT) and a Replace command (REPLACE) option.
For example, to create a proxy command that has a target command of QSYS/DSPJOB, enter the following command:
CRTPRXCMD CMD(MYLIB/PCMD1) TGTCMD(QSYS/DSPJOB) TEXT('dspjob proxy’)
Specifying a proxy command for the TGTCMD parameter is allowed.
A proxy chain can be up to five proxy commands in length, ending with a sixth non-proxy command. Running a proxy command with a chain of more than five proxy commands causes a CPD0196 error “Number of chained proxy commands exceeds 5.”
Use the Change Proxy Command (CHGPRXCMD) command, to change a proxy command. Use the Delete Command (DLTCMD) command to delete a proxy command.