 |
» |
|
|
|
NM and CM callable (difference noted below). Parses (delineates and defines) parameters for a user-defined
command image. Syntax | |
I16 CA CA
entrynum:=MYCOMMAND(cmdimage,delimiters,
I16V I16 I32A
maxparms,numparms,params,
CA @*
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 - Commands
None - Manuals
None
|
