CRTCMD (Create Command)

CRTCMD Command syntax diagram

 

Purpose

The Create Command (CRTCMD) command creates a new user-defined command (that is, a command definition) that can use the command processing support used by IBM-supplied commands. The command definition is an object that can be stored in the general purpose library (the QGPL library) or in a user library. The CRTCMD command also can be used to update an existing command; for example, to change the name of one of its parameter keywords. To do this, the command must first be deleted by the Delete Command (DLTCMD) command and then created again by the CRTCMD command. However, some of the values can be changed by the Change Command (CHGCMD) command.

To create a command, a set of command definition statements are entered into a source file. The CRTCMD command is used to process the source file and create a command definition object. The following command definition statements are used as needed:

Descriptions of the five command definition statements are in command definition statements. Additional information about command definitions is in the CL Programming Link to PDF book.

Restriction: The CRTCMD command can be used only to create the command definition of an actual CL command. That is, it cannot be used to create definitions of statements, such as the command definition statements themselves.

 

Required Parameters

CMD
Specifies the qualified name of the command being created.

The name of the command can be qualified by one of the following library values:

*CURLIB: The command is created in the current library for the job. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the command is created.

command-name: Specify the name of the command being created.

PGM
Specifies the qualified name of the compiled program.

Note: The CPP is not required to exist until command run time.

The name of the CPP can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the program that is to process the command.

Other Single Values

*REXX: The CPP for this command is the REXX procedure identified by the REXSRCMBR and REXSRCFILE parameters.

The parameters passed to the CPP are the ones defined by the command definition statements in the source file specified by the SRCFILE parameter.

 

Optional Parameters

SRCFILE
Specifies the qualified name of the source file that contains the command definition statements.

The name of the source file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QCMDSRC: The IBM-supplied source file, QCMDSRC, contains the command definition statements.

source-file-name: Specify the name of the source file that contains the command definition statements for the command being created.

SRCMBR
Specifies the name of the source file member that contains the command definition statements used to create the command.

*CMD: When the file specified in the SRCFILE parameter is a database file, the name of the source file member is the name specified in the CMD parameter of this command.

source-file-member-name: Specify the name of the source file member that contains the command definition statements used to create the command.

REXSRCFILE
Specifies the qualified name of the source file containing the REXX procedure that is the command processing program.

The name of the source file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QREXSRC: The IBM-supplied source file, QREXSRC, contains the source member that is used.

source-file-name: Specify the name of the source file containing the source member (the member that holds the REXX procedure) that is used.

REXSRCMBR
Specifies the source member containing the REXX procedure that is the command processing program.

*CMD: The source member name is the same as the command name (the name specified on the CMD parameter).

source-member-name: Specify the name of the source member that contains the REXX procedure.

REXCMDENV
Specifies the command environment that is active when the REXX CPP starts to run. If the iSeries 400 control language (CL) environment is not used, a program can be specified to process commands found in the REXX procedure. The REXX interpreter calls this program to process commands encountered in the procedure. This environment can be changed with the REXX ADDRESS instruction.

*COMMAND: The iSeries 400 control language (CL) command environment is used.

*CPICOMM: The Common Programming Interface (CPI) for Communications command environment is used. CPICOMM is the command environment used for CL commands that are imbedded within a REXX procedure.

*EXECSQL: The Structured Query Language (SQL) Command envrionment is used. EXECSQL is the command environment used for CL commands that are imbedded within a SQL procedure.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the program to process commands found in the REXX procedure.

REXEXITPGM
Specifies the exit programs to be used when the REXX interpreter is started. This parameter can be specified as a single value (*NONE) or as a list of two values (elements).

*NONE: There are no exit programs for this call of the CPP.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

Element 1: Program Name

program-name: Specify the name of the exit program.

Element 2: Exit Code

exit-code: Specify one of the following values for the exit code:

Exit-code
Description
2
The associated program is called whenever an external function or subroutine has been called by the REXX program. The exit program is then responsible for locating and calling the requested routine.
3
The associated program is called whenever the interpreter is going to call a command. The exit program is responsible for locating and calling the command given the command string and the current environment name.
4
The associated program is called whenever a REXX instruction or function attempts an operation on the REXX external data queue.
5
The associated program is called when session input or output operations are attempted.
7
The associated program is called after running each clause of the REXX procedure to determine whether it must be halted.
8
The associated program is called after running each clause of the REXX program to check if tracing must be turned on or off.
9
The associated program is called before interpretation of the first instruction of a REXX procedure (including REXX procedures called as external functions and subroutines).
10
The associated program is called after interpretation of the last instruction of a REXX procedure (including REXX procedures called as external functions and subroutines).

VLDCKR
Specifies, each time the command is used, the qualified name of a program that performs additional user-defined validity checking on the parameters in the command being created. The same parameters that are passed to the CPP (these are identified in the PGM parameter) are also passed to the validity checking program. The validity checker performs additional user-defined validity checking beyond that specified by the command definition statements in the source file, and beyond normal control language syntax checking. More information on validity checking is in the CL Programming book.

*NONE: No separate user-defined validity checking is done for this command. All validity checking is done by the command analyzer and the command processing program.

The name of the user-defined validity checking program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the user-defined validity checking program that checks the validity of the command being created. The validity checker is not required to exist until command run time.

MODE
Specifies the modes of operating environment to which the newly defined command applies. One or more of the modes can be specified.

*ALL: The command is valid in all the types of operation: production, debug, and service modes.

*PROD: The command is valid for production mode operations.

*DEBUG: The command is valid for debug mode operations.

*SERVICE: The command is valid for service mode operations.

ALLOW
Specifies where the CRTCMD command can be processed. One or more of the following options can be specified.

*ALL: The command can be processed in a batch input stream, in a CL program, in a REXX procedure, in a CL ILE module, or when processed interactively. It can also be passed to the system program QCMDEXC (or QCAEXEC) for processing.

Note: User-created commands created in releases prior to REXX must be modified to work in REXX.

*BATCH: The command can be processed in a batch input stream, external to a compiled CL program.

*INTERACT: The command can be processed interactively, external to a compiled CL program.

*BPGM: The command can be processed in a compiled OPM-CL or ILE-CL program that is called from batch entry.

*IPGM: The command can be processed in a compiled OPM-CL or ILE-CL program that is called from interactive entry.

*BREXX: The command can be used in a REXX procedure that is run in batch job.

*IREXX: The command can be used in a REXX procedure that is run in an interactive job.

*BMOD: The command can be used in a batch CL ILE module only.

*IMOD: The command can be used in an interactive CL ILE module only.

*EXEC: The command can be processed as a parameter on the CALL command, and can be passed as a character string to the system program QCMDEXC (or QCAEXEC) for processing. If *EXEC is specified, either *BATCH or *INTERACT must also be specified.

ALWLMTUSR
Specifies whether a user whose profile is set for limited capabilities is allowed to use the command by typing it in the command line on a menu.

*NO: A user whose profile is set for limited capabilities is not allowed to use the command by typing it in the command line on a menu.

*YES: A user whose profile is set for limited capabilities is allowed to use the command by typing it in the command line on a menu.

MAXPOS
Specifies the maximum number of parameters that can be coded positionally for this command. This parameter value must be greater than the number of nonconstant required parameters and less than the total number of nonconstant parameters. Parameters of TYPE(*ZEROELEM), parameters with the CONSTANT attribute, and lists and qualified names whose ELEMs and QUALs have the CONSTANT attribute or are of TYPE(*ZEROELEM) are not included in the number of parameters that can be coded positionally for this command.

*NOMAX: The system maximum is used.

positional-limit: Specify the maximum number of parameters that can be coded positionally for this command. Valid values range from 0 through 75.

PMTFILE
Specifies the qualified name of the message file from which the prompt text for the command is retrieved.

*NONE: No message file is needed for the prompt text. The text, if any, is supplied in the definition statements that define the command.

The name of the message file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-file-name: Specify the name of the message file to use.

MSGF
Specifies the qualified name of the message file from which messages identified on the DEP statements used to define the command are retrieved. These messages are those that can be sent if the command, while running, finds a parameter dependency error. The messages referred to by this MSGF parameter are those whose message identifiers are specified in the MSGID parameter of one or more DEP definition statements, but whose identifiers do not have the 3-character prefix, CPF. QCPFMSG is always used for messages that have the CPF prefix.

The name of the message file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QCPFMSG: Dependency error messages are retrieved from the IBM-supplied CPF message file, QCPFMSG.

message-file-name: Specify the name of the message file to use.

HLPSHELF
Specifies a bookshelf name, or a list of bookshelves, that is to be used when the InfoSeeker key is pressed from the help display.

*NONE: No bookshelf is specified. InfoSeeker will not be available from the help display.

*LIST: The list of bookshelves in the user's bookpath will be displayed.

bookshelf-name: Specify the bookshelf name.

Note: If both a HLPSHELF and HLPSCHIDX parameter value are specified, an error message is issued when the command is created.

HLPPNLGRP
Specifies the qualified name of the help panel group for this command.

*NONE: No help panel group is specified.

Note: If *NONE is specified on this parameter and a value is specified on the HLPID parameter, an error message is issued when the command is created.

The name of the panel group can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

panel-group-name: Specify the name of the help panel group for this command.

HLPID
Specifies the name of the general help module for the names of the help identifiers for this command.

*CMD: The name of the command is the name of the general help module.

*NONE: No help identifier is specified.

Note: If *NONE is specified on this parameter and a value is specified on the HLPID parameter, an error message is issued when the command is created.

help-ID-name: Specify the name of the general help module for the help identifiers for this command.

HLPSCHIDX
Specifies the qualified name of the help search index to be used when the search index function key is pressed.

*NONE: No search index is specified.

The name of the search index can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

search-index-name: Specify the name of the search index to be used when the search index function key is pressed.

Note: If both a HLPSHELF and HLPSCHIDX parameter value are specified, an error message is issued when the command is created.

CURLIB
Specifies the name of the library being used as the current library for jobs initiated by this user profile.

Note: This library is also the current library when the validity checker program (if any) is processed for the command.

*NOCHG: The current library does not change for the processing of this command. If the current library is changed during processing of the command, the change remains in effect after command processing is complete.

*CRTDFT: No current library is active during processing of the command. The current library that was active before command processing began is restored when processing is completed.

If *CURLIB was specified as the to-value for any single values or special values for this command, or for any command processed while no current library is active, the QGPL library is used as the current library.

library-name: Specify the name of the library used as the current library. The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the current library is restored to its previous value. If the current library is changed during command processing by the Change Library List (CHGLIBL) command or Change Current Library (CHGCURLIB) command, the change is effective only until the command is processed. QTEMP cannot be specified for the current library.

PRDLIB
Specifies the name of the product library that is in effect during the processing of the command.

Note: The product library for a command or menu remains in the library list while a command or menu is active, unless another command or menu changes the product library. When a command or menu that changed the product library ends, the product library is restored to what it was when the command or library started.

*NOCHG: The product library does not change when command processing starts. If the product library is changed during the processing of the command, the change remains in effect after command processing is complete.

*NONE: There is no product library in the job's library list. The product library is restored to its previous value on completion of command processing.

library-name: Specify the name of the library used as the current library. The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the current library is restored to its previous value. If the current library is changed during command processing by the Change Library List (CHGLIBL) command or Change Current Library (CHGCURLIB) command, the change is effective only until the command is processed. QTEMP cannot be specified for the current library.

PMTOVRPGM
Specifies the qualified name of the prompt override program (POP) that replaces (on the prompt display) the default values with the current actual values for the parameter. If a POP is specified, the key parameters (specified as KEYPARM(*YES) on the PARM statement in the command definition source) are the only parameters visible on the initial prompt display. When values are input for the key parameters, the remaining parameters are shown on the display with the actual values instead of the default values.

*NONE: No prompt override program is specified.

Note: If *NONE is specified when key parameters exist in the command definition source (KEYPARM(*YES) specified on the PARM statement), a warning message is issued when the command is created, and KEYPARM(*NO) is assumed for all parameters.

The name of the prompt override program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the prompt override program for the command.

AUT
Specifies the authority given to users who do not have specific authority to the command, who are not on an authorization list, and whose user group has no specific authority to the command. More information on this parameter is in Commonly used parameters.

*LIBCRTAUT: The public authority for the command is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the command). The public authority is determined when the command is created. If the CRTAUT value for the library changes after the command is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the command.

*USE: The user can perform basic operations on the command, such as running a program or reading a file. The user cannot change the command. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the command.

authorization-list-name: Specify the name of the authorization list used.

REPLACE
Specifies the replacement of an existing command with a new version of the same name, type, and library, without first issuing a DLTCMD command to remove the old one.

The old version is renamed, moved to library QRPLOBJ, and then cleared on the next IPL of the system.

*YES: If the create operation is successful, existing commands are replaced by new versions of the same command.

*NO: No replacement occurs.

ENBGUI
Specifies whether the command prompt panels are enabled for conversion to a graphical user interface.

*NO: The command prompt panels are not enabled for conversion to a graphical user interface.

*YES: The command prompt panels are enabled for conversion to a graphical user interface by including information about the panel content in the 5250 data stream.

THDSAFE
Specifies whether a command can be safely used in a multithreaded job. If you specified PGM(*REXX), specify THDSAFE(*NO).

*NO: The command is not threadsafe. The MLTTHDACN parameter defines the action to be taken by the command analyzer when the command is used in a multithreaded job.

*YES: The command is threadsafe.

*COND: The command is threadsafe under some conditions. The documentation for the command should describe the conditions under which the command is threadsafe.

MLTTHDACN
Specifies the action to take if the command is not threadsafe and it is being used in a multithreaded job.

*SYSVAL: The action specified in the system value QMLTTHDACN will be taken.

*RUN: The command is run, and no message is sent to the caller of the command.

*MSG: The command is run, and an informational message is sent to the caller of the command.

*NORUN: The command is not run, and an escape message is sent to the caller of the command.

TEXT
Specifies the text that briefly describes the command and its function. More information on this parameter is in Commonly used parameters.

Note: The text in the command description can be displayed by the Display Object Description (DSPOBJD) command.

*SRCMBRTXT: The text is taken from the source file member being used to create the CL command. If the source file is an inline file or a device file, the text is blank.

*CMDPMT: The text is taken from the text defined for the PROMPT keyword of the CMD statement in the command definition source.

*BLANK: No text is specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Example for CRTCMD 

CRTCMD   CMD(PAYROLL)  PGM(PAY076)
  SRCFILE(PAYSOURCE)  AUT(*EXCLUDE)

The command named PAYROLL is created from the source file PAYSOURCE. The command is private and calls the command processing program (CPP) named PAY076. It is a valid command when entered in a batch input stream, when compiled in a control language program, when entered interactively, or when passed to the QCMDEXC program.

Error messages for CRTCMD

*ESCAPE Messages

CPF0201
Command &2 not created in library &3.
CPF0210
Cannot open printer file.
CPF0212
Unable to open source file.