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)