User-Defined Line Commands

cspm142
CA SYSVIEW provides users and site administrators the ability to externally define new line commands and associate the new definition with an existing CA SYSVIEW primary command. The newly defined line commands can link in context to a new display command or perform an action.
An external line command definition can execute a REXX exec to dynamically create a command string to be executed.
If a command is defined to support line command input, the following process is performed when a line command is entered.
  1. An internal line command table is searched for the specified line command. If found, the internally defined action is taken and additional processing stops.
  2. If an internal match was not found, externally defined line commands will be searched for a match.
Where are the Line Commands Defined?
External line commands are defined in SYSVIEW parmlib members. The majority of the supplied out-of-the-box line commands are defined in this manner.
Users and site administrators have the ability to extend the product by adding additional line commands. Since the definitions can come from three different locations, it is important to understand the order of precedence for locating a definition.
Order of Precedence
  1. External PRODUCT Definitions
    Source:
    sysview
    .CNM4BPRM(GSVXLCMD)
    This member contains the product supplied out-of-the-box definitions. The data in this member should not be altered. It is a good source of example definitions.
  2. USER Definitions
    Source: user.parmlib(LINECMDS)
    A user can define a set of external line commands. These line commands are specific to the user. This is only available if the user has a user parmlib data set specified. Data sets in use can be viewed using the SYSVIEW LIBS command.
  3. SYSTEM or SITE Definitions
    Source:
    sysview
    .CNM4BPRM(LINECMDS)
    A site administrator can define a set of external line commands that will be available to all users.
Additional Configuration Options
Parmlib member:
sysview
.CNM4BPRM(OPTIONS)
Configuration Option
Description
ExternalLineCommands
Specify if external line commands defined in the parmlib member LINECMDS are to be supported.
NONE - Externally user defined line commands are not to be used. Product supplied line command definitions are always available.
USER - External line commands defined in the user's LINECMDS member can be used.
SYSTEM - External line commands defined in the system LINECMDS member can be used.
ALL - External line commands defined in the user and system LINECMDS members can be used.
Default = ALL
Where Can I see a List of Active Definitions?
Line Command Assistant
The line command "?" invokes the line command assistant to display all available line commands defined to the active command.
The list of available line commands contains:
  • The command's internally defined line commands
  • Product supplied external line commands
  • Site defined external line commands
  • User defined external line commands
The line command assistant provides additional line command help as well as the ability to execute line commands.
Command Help
The command's help contains a line command section that lists each internal and product supplied external line command. You can use the HELP command to navigate to a command's help or  place the cursor in the line command area and hit the PF1 key (the PF1 key is defined as HELP unless otherwise altered) to navigate directly to the line command section.
LISTLCMD command
The command LISTLCMD displays a list of all line commands for all commands, including line commands that are designated as global to all commands.
Where can I find Example Definitions?
Example external line command definitions can be found in the parmlib member LINECMDS.
What is the Syntax for Creating a Definition?
An external Line command entry contains multiple parts:
  • The external line command definition "key"
  • Option keywords
  • The command string to be associated with the "key"
The external line command definition can be coded on a single line or multiple lines. The following parameters MUST be coded on the first line of each definition:
  • Command
  • Linecmd
  • Min
The options and command string can start on the first or second line of a definition.
Card 1 ....+....1....+....2....+....3....+....4....+....5....+....6 *Command.Screen... Linecmd. Min Options-CmdString.......... command.screen linecmd min <OPTS options> CMD string
command
- The name of the command to which this definition applies. The maximum length is 8 characters. This value is not case sensitive.
screen
- The screen name within a specific command. For most commands, the screen name is left blank. The maximum length is 8 characters. This value is not case sensitive. The syntax for specifying a screen name is:
command.screen
linecmd
- The external line command name. The maximum length is 8 characters. This value is not case sensitive.
min
- The minimum allowable length of the external line command name (linecmd). The minimum value is 1 and the maximum value is 8. Any other value is invalid and is ignored and 8 is used instead.
options
- The options to be associated with the entry. Option keywords must be preceded by the keyword "OPTS". This indicates that option keywords are to follow.
Valid option keywords:
PAD pad
- Pad fields containing all blanks. Specifies a string to be used during variable substitution if the field contains all blanks.
XSYS
- XSSYSTEM entry only. This definition will only be used for cross system data lines where the XSSYSTEM name is different than the current system name.
string
- The command string must be preceded by the keyword "CMD". The command string to be executed when the line command is processed. The command string can
start on line 1 or line 2 of a definition. If the string requires multiple lines, a continuation character must be used. The string can start or continue in any column from 1 to 72.
Card 2-n ....+....1....+....2....+....3....+....4....+....5....+....6 CMD command_string
The command string can be a single command or multiple commands that can span several lines. The total command string is limited to 250 characters. Multiple commands must be separated using the command delimiter.
The command string can be continued by coding a continuation character as the last non-blank character on a line.
The hyphen ("-") continuation character indicates that leading blanks in the next record are not ignored.
The plus sign ("+") continuation character indicates that leading blanks in the next record are ignored.
The only restriction on the number of continuation records is that the total length of the actual resulting command string cannot exceed 250 characters. Any excess characters are truncated without any warning.
Data or Variable Substitution
The command string can contain variables or symbolics. Dynamic variable substitution occurs at run-time.
DATA Fields
Fields from the selected data row can be inserted at run-time using specially named variables. The following examples show how to code a field name for substitution:
&F_jobname &FLD_jobname
If a field or column with the name "jobname" is found on the current screen, the data value for that column or field from the selected row will be used to replace the variable.
INFO Fields
Fields from the information section can be inserted at run-time using specially named variables. The following examples show how to code a field name for substitution:
&I_Dsn &INFO_Dsn
If a field name "dsn" is found in the information section on the current screen, the associated data value for that field is used to replace the variable.
The list of available information section field names display by issuing the INFOFLDS command from the desired display.
Examples:
....+....1....+....2....+....3....+....4....+....5....+....6.||7.. *Command. Linecmd. Min CmdString................................. ACTIVITY ENQUEUE 1 CMD ENQUEUE;SELECT RNAME EQ &F_JOBNAME ACTIVITY ENQUEUE 1 CMD ENQUEUE + ;SELECT RNAME EQ &F_JOBNAME ACTIVITY ASID 8 CMD ASID &F_JOBNAME ACTIVITY ASID 8 OPTS XSYS CMD ACTIVITY;ASID &F_JOBNAME + FIND &F_JOBNAME JOBNAME ACTIVITY CANCEL 1 CMD CONFIRM Cancel job: &F_JOBNAME + ;ASCANCEL &F_JOBNAME + NODUMP NOCONFIRM NOMSG LISTDIR DELETE 3 CMD CONFIRM &I_Dsn(&F_NAME) + ;XTSO DELETE '&I_Dsn(&F_NAME)'
Command Confirmation
If command confirmation is desired, use the "CONFIRM" command as the first command within the command string. If a positive confirmation is returned, the remaining portion of the command string will be executed. Otherwise, the remaining portion of the command string is discarded.
Link To Commands or Drill-Down
When using a line command, it is assumed that the user wants to "link" or drill-down to the next command level. By default, the first command in the command string is linked to if the  command is not a function command. Function commands do not have associated screen displays. Some function commands display messages or cause other screen activity to occur. An example of a function command is ASID. If the first command in a command string is a function command such as ASID, you should insert a "LINK" command in front of the next primary command.
Dynamic Command String Generation Using REXX
An external line command definition can execute a REXX exec to dynamically create a command string to be executed. The information contained in the data fields can be passed to the REXX  exec. This data can be used by the REXX exec to determine the nature of the command string to be returned.
When using a REXX exec to create a command string, the following syntax must be used. Only one REXX invocation is allowed per definition AND it must be the first command string.
The REXX exec must return a result string to be executed. The string can contain multiple commands separated by the command delimiter.
The returned result replaces the calling command string "REXX execname parameters".
Several REXX functions provided by SYSVIEW are available to the REXX exec executed as part of an external line command definition. Issue a "HELP REXXFUNC" command to display a summary of these REXX functions.
Syntax:
....+....1....+....2....+....3....+....4....+....5....+....||7.. *Command. Linecmd. Min CmdString............................... command linecmd min CMD REXX execname parameters
Examples:
....+....1....+....2....+....3....+....4....+....5....+....||7.. *Command. Linecmd. Min CmdString............................... ACTIVITY TEST 8 CMD REXX ACTTEST &F_JOBNAME &F_TYPE