|
|
NM and CM callable (difference noted below).
Parses (delineates and defines) parameters for a user-defined command image.
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
|