HP 3000 Manuals HP 3000 Manuals
MYCOMMAND
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.
Table 4-25. (cont.)
Bits Value/Meaning
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