User-Defined Commands
Part 23
Presentation Copyright 2008, Bryan Meyers, www.bmeyers.net
Why Commands?
Simplify user interface
Bypass menus
Parameter prompting
Parameter validation
Integrated help
Simplify administration
Integrated security
Simplify user training
Simplify application design
Automatic data validation, conversion
Command Components
Command Definition Object (CDO) is actual
*CMD object
Description of command
Includes parameter keywords, descriptions,
default values, validity checking rules
Links to called programs
Command Processing Program (CPP) is *PGM
object that actually performs work of
command
Receives parameters from CDO, processes them
Command Definition Source
/* ******************************************************** */
/* Command - EXCCMD - Execute commands in a source member */
/* ******************************************************** */
EXCCMD: CMD PROMPT('Execute Commands from Source') +
ALLOW(*INTERACT *BPGM *IPGM) +
TEXT('Execute commands from source')
PARM KWD(MBR) TYPE(*NAME) LEN(10) +
MIN(1) PROMPT('Member')
PARM KWD(SRCFILE) TYPE(Q1) +
PROMPT('Source file name')
PARM KWD(IFERROR) TYPE(*CHAR) LEN(7) +
RSTD(*YES) DFT(*CANCEL) VALUES(*CANCEL *IGNORE) +
PROMPT('Command error action')
Q1: QUAL TYPE(*NAME) LEN(10) +
DFT(QCLSRC)
QUAL TYPE(*NAME) LEN(10) +
DFT(*LIBL) SPCVAL((*LIBL)) +
Common
Command Definition Statements
CMD
Command properties specification
PARM
Parameter definition
QUAL
Qualified name definition
CMD Statement
CMD statement defines command properties
Prompter, object text
Where allowed to run
Allow limited capability users
Maximum positional parameters
0-99
Current library, product library
EXCCMD: CMD PROMPT('Execute Commands from Source') +
ALLOW(*INTERACT *BPGM *IPGM) +
TEXT('Execute commands from source)
ALLOW Parameter
Indicates where command can be executed
from
ALLOW Parameter Meaning
*ALL Command may be used in any environment (default)
*BATCH Command may appear in batch CL job stream
*BMOD Command may appear in batch ILE CL module
*BPGM Command may appear in batch CL program
*BREXX Command may appear in batch REXX procedure
*EXEC Command may be executed by QCMDEXC API
*IMOD Command may appear in interactive CL module
*INTERACT Command may execute from command line
*IPGM Command may appear in interactive CL program
*IREXX Command may appear in interactive REXX procedure
PARM Statement
Defines a command parameter
May have up to 99 parameters
Specify PARM statements in same order as
received by command processing program
KWD specifies parameter keyword used for
keyword notation
MIN(1) indicates required parameter
PROMPT specifies prompter text
PARM KWD(MBR) TYPE(*NAME) LEN(10) MIN(1) PROMPT('Member')
Parameter Types
Default Maximum Allowed
TYPE Length Length Values
*CHAR 32 5000 Any character string
*CMDSTR 256 20000 Any CL command
*DATE Character string representing date ('123199')
*DEC (15 5) (24 9) Decimal number
*GENERIC 10 256 Partial name, followed by *, to identify a group of
objects
*HEX 1 256 Hexadecimal value, using digits 0-F
*INT2, *INT4, Numeric integer value
*UINT2, *UINT4
*LGL 1 1 Logical value ('0' or '1')
*NAME 10 256 Character string representing object name
*TIME Character string representing time of day ('125959')
Restricted Values
RSTD restricts valid parameter values
RSTD(*YES) restricts values to VALUE or SPCVAL
values
VALUES describes specific allowable values
SPCVAL provides special values for parameter
Allow values that dont match type
Allow translation of entered values
DFT provides default parameter value
PARM KWD(IFERROR) TYPE(*CHAR) LEN(7) +
RSTD(*YES) DFT(*CANCEL) VALUES(*CANCEL *IGNORE) +
PROMPT('Command error action')
QUAL Statement
Defines individual parts of qualified parameter
PARM statement ties to QUAL statement group
label through TYPE parameter
Up to 300 qualifiers allowed per parameter
PARM KWD(SRCFILE) TYPE(Q1) +
PROMPT('Source file name')
Q1: QUAL TYPE(*NAME) LEN(10) +
DFT(QCLSRC)
QUAL TYPE(*NAME) LEN(10) +
DFT(*LIBL) SPCVAL((*LIBL)) +
PROMPT('Library')
Other
Command Definition Statements
ELEM
Describes individual elements in a mixed list
parameter
DEP
Defines dependencies between parameters
PMTCTL
Defines conditions under which parameter is
displayed by prompter
CRTCMD Command
Create Command (CRTCMD) compiles
command definition source
Source type CMD
Associates CDO with command processing
program
Creates command definition object
CRTCMD CMD(EXCCMD) +
PGM(EXCCMDC) +
SRCFILE(MYLIB/QCMDSRC) +
SRCMBR(EXCCMD)
Executing the Command
Command Processing Program must exist
before command can be executed
EXCCMD MBR(JOBSTREAM) +
FILE(*LIBL/QCLSRC) +
IFERROR(*CANCEL)
