Command Creation

Command creation

Command creation

(Reference: CL Programmers Guide SC41-8077-0 and CL Reference Manual SC41-0030-0)

Introduction

Defining your own commands enables you to use the powerful system facilities for parameter checking. By defining your own commands you can provide default values, perform validity checking and provide prompt text for parameter values. And, more importantly, you provide a consistent interface to your programming.

The validity checking performed by OS/400 ensures:

•Required parameters are entered

•Each parameter meets data type and length requirements

•Each parameter value meets such specifications as a list of values, a range of values and a relational comparison to a given value is met

•Conflicting parameters are not entered.

If you need more validity checking than OS/400 performs, you can write your own validity checking program to extend OS/400 checking. OS/400 will pass entered parameters to your program.

1 cmd01

A command consists of the following components:

•a Command Definition Object (CDO) that defines validity checking for OS/400 to perform,

•a Command Processing Program (CPP) that performs the actual function,

•and optionally a Validity Checking Program (VCP) that provides extra validation of the input parameters before the CPP is invoked.

You write command source in a source file. The default source file is *LIBL/QCMDSRC.

2 cmd02

3 cmd03

Writing the Command Definition Statements

4 cmd04

CMD

The CMD statement is the only required statement and defines the prompt text seen by the user if it is prompted for.

For example:

CMD 'Display Overnight Queues'

Assuming this command is going to be called DSPOVRNQ, the title displayed by OS/400 when the command is prompted for by the user would be:

Display Overnight Queues (DSPOVRNQ)

PARM

The PARM statement defines a parameter. The order of the PARM statements (max 75) is the order in which the parameters are passed to the CPP. A number of keywords are intended for IBM commands and can safely be ignored. The two required keywords are KWD and TYPE:

PARMKWD(QNAME) /* Name of keyword on DSPOVRNQ command */

TYPE (*CHAR) /* Character variable */

LEN(10) /* Of length 10 */

RSTD(*YES) /* Only some values are valid */

VALUES(*ALL QBATCH OVRNSBSQ ORDENTNQ PRDCTLNQ)

/* Various queues involved */

PROMPT('Name of Single Queue or *ALL')

MIN(1) /* A value MUST be specified */

The system, if the command is prompted for, will display:

Display Overnight Queues (DSPOVRNQ)

Type choices, press Enter.

Name of single queue or *ALL: . ? *ALL, QBATCH, OVRNSBSQ...

Bottom

F3=Exit F4=List F5=Refresh F11=Keywords F12=Cancel

F13=How to use this display

5 cmd.001

And because values are restricted, the system will display the following if the user types in a ? in the field provided (utilising the PROMPT text for this keyword):

Specify Value for Parameter QNAME

Type choice, press Enter.

Name of single queue or *ALL: .

*ALL

QBATCH

OVRNSBSQ

ORDENTNQ

PRDCTLNQ

F3=Exit F5=Refresh F12=Cancel F13=How to use this display

6 cmd.002

There are other command statements for complex commands:

ELEM

Defines elements in a mixed list. If there is only one type of element for a parameter it is defined on the PARM statement. Otherwise the name of a label is placed in the TYPE parameter and each type is defined in an ELEM statement. The label is placed against the first ELEM statement. This enables a group of ELEM statements to be used by more than one PARM statement.

PARM KWD(TWINS) TYPE(LABEL1)

/* Go to label1 for definition of keyword TWINS */

(...other lines of code...)

LABEL1:

ELEM TYPE(*CHAR) /* First element is character */

ELEM TYPE(*CHAR)

/* Second element is also character */

QUAL

To define qualified names such as library/objectname. If a parameter or an element in a parameter list is to be qualified then it requires a QUAL statement. The structure is similar to the PARM:ELEM relationship. A label is placed in the TYPE parameter of a PARM or ELEM statement and attached to the first QUAL statement. There must be one QUAL statement for each part of the qualified name.

PARM KWD(OBJNAM) TYPE(LABEL2)

/* Go to label2 for definition of keyword OBJNAM */

(...other lines of code...)

LABEL2:

QUAL TYPE(*NAME)

/* First element is type name */

QUAL TYPE(*NAME)

/* Second element is also a name */

DEP

Defines a required relationship between parameters and other values. For instance, you could specify that if parameter 1 is entered, parameter 2 must be entered and be (say) not less than 0 and not greater than parameter 1. A DEP statement must follow the parameters it references so DEP statement are usually placed near the end of the command definition. With the DEP statement you can specify:

•the controlling conditions required before the dependency is to be checked

•the parameter relationship to be tested

•the number of parameter relationships which must br true before the dependency is fulfilled

•the id of the error message to be sent if the condition is unfulfilled

PARM KWD(FROMFILE) TYPE(*NAME)

PARM KWD(TOFILE) TYPE(*NAME)

DEP CTL(*ALWAYS) PARM(&FROMFILE *NE &TOFILE) MSGID(USR0001) /* Send error message USR0001 if files have same name */

PMTCTL

Prompt control enables you to control the parameters which are shown when the prompt (F4) key is used. You may specify that a parameter is not prompted for unless a particular value for another parameter is entered. You can specify that less common parameters are only displayed if a command key is pressed (F10 for additional parameters on most IBM commands). On the PARM statement specify a label for the PMTCTL parameter and at the end of the command definition add the label and the PMTCTL statement.

PARM KWD(ALSO) PMTCTL(*PMTRQS)

/* keyword ALSO is prompted for only if F10 pressed */

PARM KWD(BUTIF) PMTCTL(LABEL3)

/* Goto label3 to see prompting criteria for BUTIF */

(...other lines of code...)

LABEL3:

PMTCTL CTL(FILE) COND((*EQ *SELECT))

/* prompt for BUTIF if FILE=*SELECT ...*/

PMTCTL CTL(LIBRARY) COND((*NE *NONE)) LGLREL(*AND)

/* ... and LIBRARY is not *NONE */

Remember that these statements are not always used, and they have keywords that can only be used in IBM commands.

Writing the Command Processing Program

This is much like writing any other kind of program. The command analyser will pass the parameters according to the specifications in the CDO.

The parameters defined in the command are passed individually in the order in which the PARM statements were written.

Decimal values are passed in packed decimal format of length specified in the CDO but will appear to programs as zoned decimal if that is how they are defined.

Assume the CPP for the example CDO just illustrated:

PGM PARM(&QNAME) /* CPP for DSPOVRNQ command. */

DCL &QNAME *CHAR 10

SNDPGMMSG CMD0001 MSGF(CMDMSGSMF) MSGTYPE(*STATUS) +

TOPGMQ(*EXT)/* Tell user, CMD is executing. */

IF (%SUBSTRING(&QNAME 1 4) *EQ '*ALL') DO

WRKJOBQ QBATCH

WRKJOBQ OVRNSBSQ

WRKJOBQ ORDENTNQ

WRKJOBQ PRDCTLNQ

ENDDO

ELSE WRKJOBQ &QNAME

ENDPGM

Creating the Command

You use the CRTCMD command to create the CDO and link it with its CPP and specify the following attributes for the command to assume:

VLDCKRThe name of the validity checking program

MODEMode in which the command may be used

*ALL, *PROD, *DEBUG, *SERVICE

ALLOWThe environment in which the command may be used

*ALL, *BATCH, *INTERACT, *BPGM (Batch program), *IPGM (Interactive program), *EXEC (Executed through QCMDEXC)

MAXPOSThe maximum number of parameters which can be entered positionally. The default is *NOMAX.

PRDLIBThe name of the production library which is to be in effect during execution of the command.

For example:

CRTCMD DSPOVRNQ PGM(QGPL/DSPOVRNQ) +

SRCFILE(MYLIB/QCMDSRC) +

ALLOW(*INTERACT *IPGM *EXEC) +

TEXT('Display work on overnight queues. CPP is CL.')

Summary

Creating your own commands means you can employ all the syntax checking and prompt facilities available with IBM commands except cursor-sensitive help. Once created, user-

defined commands can be used alongside, or in place of the OS/400 commands.

DO NOT COPY

Command creation

This page intentionally left blank

DO NOT COPY