MYCOMMAND
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| Edition 7 E0701 | |
| Edition 7 E0300 ♥ | |
| Edition 6 E0195 |
Syntax
I16 CA CA I16V I16
entrynum := MYCOMMAND (cmdimage, delimiters, maxparms, numparms,
I32A CA @*
params, dictionar, definition);
Functional Return
- entrynum
16-bit signed integer (assigned functional return)
Returns the command entry number. If the dictionary parameter is not specified, 0 is returned.
Parameters
- cmdimage
character array (required)
A cmdimage must begin with an alphabetic character. The first non-alphanumeric character (or space) encountered terminates the command name. Whatever follows is interpreted as an element of the parameter list.
Passes one of two things:
Command name (if the dictionary parameter is specified), then parameters and a carriage-return character (%15). The command name is delimited by the first nonalphanumeric character and cannot be preceded by any leading blanks. One or more blanks is expected after the command name, preceding the parameter list. The parameters are formatted and referenced in the params array and cmdimage is converted to uppercase, and the character array specified by dictionary is searched for a name matching the command.
Command parameters (if the dictionary parameter is not specified), then a carriage-return character (%15). These parameters are formatted. Leading and trailing blanks are ignored. Lowercase is upshifted.
- delimiters
character array (optional)
Passes a string of up to 32 legal delimiters, each of which is an ASCII special character. The last character must be a carriage return. Each delimiter is identified later by its position in this string.
Default: The delimiter array ",=; (carriage return)".
- maxparms
16-bit signed integer by value (required)
Passes the maximum number of parameters expected in cmdimage. Accepts values from 0 to 8192.
- numparms
16-bit signed integer by reference (required)
Returns the number of parameters found in cmdimage.
- params
32-bit signed integer array (required)
Returns an array of maxparms entries. Numparms entries are returned that delineate the parameters. Each entry consists of two 32-bit words. When the intrinsic is executed, the first numparms entries are returned to your process in this array, with the first entry corresponding to the first parameter, the second entry corresponding to the second parameter, and so forth. The parameter fields of cmdimage are delimited by the delimiters specified in delimiters. The pointer in the first word of each entry points to the parameter in cmdimage. The string in cmdimage is upshifted. The second word of params contains the delimiter number and parameter information. Each word in the array named by params contains the following information:
Word 1: The pointer to the first character of the parameter. If the parameter is empty or all blanks, the pointer indicates the location of the delimiter.
Word 2: Bits that describe the parameter:
- Bits
Value/Meaning
- 27:5
The zero-relative position of the delimiter in delimiters. For example, if you use the default delimiters array and the current parameter is delimited by a semicolon, this field contains 2.
- 26:1
Special characters indicator bit (set by MYCOMMAND):
- 0
The parameter contains no special characters.
- 1
The parameter contains special characters other than those listed in delimiters.
- 25:1
Numeric character indicator:
- 0
The parameter does not contain numeric characters.
- 1
The parameter contains numeric characters.
- 24:1
Alphabetic characters indicator:
- 0
The parameter does not contain alphabetic characters.
- 1
The parameter contains alphabetic characters.
- 16:8
The length of the parameter in bytes. This value is zero if you omit the parameter.
- 0:16
Always zero.
- dictionary
character array (optional)
Passes the character array that is to be searched for the command name in cmdimage. The format must be identical to that of the dictionary parameter in the SEARCH intrinsic. The command, delimited by a blank, is extracted from cmdimage, and the SEARCH intrinsic is called with the command name used as the buffer parameter of SEARCH. If the command name is found in dictionary, the functional return is its entry number. If the command is not found, or if the dictionary parameter is not specified, the functional return is zero. If dictionary is specified, but the command name is not found in dictionary, the parameters specified in cmdimage are not formatted.
If this parameter is omitted, the functional return is 0.
- definition
(NM) 32-bit address (optional)
(CM) 16-bit address (optional)
Returns a pointer to the byte following the command in dictionary. This should be the definition, but may be invalid if definition is not used for a command. Check the return status before the pointer is used.
Operation Notes
The MYCOMMAND intrinsic analyzes the command string, identifying the location and characteristics of each parameter. If the dictionary is specified, the first parameter is considered a command name. The array specified in dictionary is searched for the command name. This dictionary is specially formatted as a SEARCH intrinsic array. (Refer to the SEARCH intrinsic for the format of the array.) The entry number for the match is returned in entrynum. If a definition exists for the matching entry, its address is returned in definition. All remaining entries in the command string are analyzed as parameters. (If dictionary is not entered, all input is considered parameter data.) A parameter consists of all characters from the current pointer position to the next delimiter. A pointer to first character is determined. Valid delimiters are defined in delimiters or by the default delimiter ",=;(carriage return)". The delimiter type is identified by its position in the defined delimiter list, for example, a comma is identified as 1, and a semicolon as 3. The contents of the parameter are identified as special characters, numeric, or alphanumeric characters. Results of the analysis are returned in the array params. Two words of information are specified for each parameter. The location pointer is entered in word 1, and the delimiter and character information are entered in word 2 for each parameter. A maximum of maxparms parameters are analyzed. The actual number of parameters found are returned to numparms. The params array can then be referred to in subsequent commands to access the parameter data. If the number of characters in cmdimage exceeds 255 characters and no delimiter is present, the calling process is aborted and the following error message is printed:
PARSED PARAM OF COMIMAGE > 255 CHARACTERS
Condition Codes
- CCE (2)
Request granted. The parameters were formatted, without exception. If dictionary was specified, the functional return is the command entry number.
- CCG (0)
Request granted. More parameters were found in cmdimage than were allowed by maxparms. Only the first maxparms of these parameters were formatted in params and returned.
- CCL (1)
Request denied. The dictionary parameter was specified, but the command name was not located in the array dictionary. The parameters in cmdimage were not formatted.
Related Information
- Intrinsics
SEARCH
|
MERGETITLE |
NLAPPEND |