The UTIL$CQUAL routines allow you to parse the command line for
qualifiers related to certain file attributes, and to match files
you are processing against the selected criteria retrieved from
the command line.
1 – UTIL$CQUAL_FILE_PARSE
The UTIL$CQUAL_FILE_PARSE routine parses the command line for the
common file qualifiers.
Format
UTIL$CQUAL_FILE_PARSE flags ,context [,found_flags]
1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition Values Returned lists condition
values that this routine returns.
1.2 – Arguments
flags
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword of bit flags. UTIL$CQUAL_FILE_PARSE scans the command
line for the qualifiers whose associated bit is set in the flags
longword. The following table lists the allowed mask and field
specifier values.
Table 3-1 UTIL$CQUAL_FILE_PARSE Flags and Masks
Qualifier Mask Value Field Specifier
/CONFIRM UTIL$M_CQF_ UTIL$V_CQF_CONFIRM
CONFIRM
/EXCLUDE UTIL$M_CQF_ UTIL$V_CQF_EXCLUDE
EXCLUDE
/BEFORE UTIL$M_CQF_BEFORE UTIL$V_CQF_BEFORE
/SINCE UTIL$M_CQF_SINCE UTIL$V_CQF_SINCE
/CREATED UTIL$M_CQF_ UTIL$V_CQF_CREATED
CREATED
/MODIFIED UTIL$M_CQF_ UTIL$V_CQF_MODIFIED
MODIFIED
/EXPIRED UTIL$M_CQF_ UTIL$V_CQF_EXPIRED
EXPIRED
/BACKUP UTIL$M_CQF_BACKUP UTIL$V_CQF_BACKUP
/BY_ UTIL$M_CQF_ UTIL$V_CQF_BYOWNER
OWNER BYOWNER
context
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The address of a longword that receives the common file qualifier
database address. The address of the context variable must be
passed to the UTIL$CQUAL_FILE_MATCH and UTIL$CQUAL_FILE_END
routines when they are called.
found_flags
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Longword of bit flags. This optional parameter is the longword
address of the value that indicates which common file qualifiers
were present on the command line. The mask and field specifier
values are the same values as the flags parameter, and are listed
in UTIL$CQUAL_FILE_PARSE Flags and Masks.
1.3 – Description
Using the CLI$PRESENT and CLI$GET_VALUE routines, the UTIL$CQUAL_
FILE_PARSE routine searches the command line for the qualifiers
specified in the flags longword. When command line parsing
finishes, UTIL$CQUAL_FILE_PARSE returns a pointer to the common
file qualifier value in the context parameter.
The context parameter must be used when calling either the
UTIL$CQUAL_FILE_MATCH or UTIL$CQUAL_FILE_END routines. If a
third parameter is specified, UTIL$CQUAL_FILE_PARSE returns a
longword of flags indicating which qualifiers were found during
the command line parse. The mask and field specifiers are listed
in UTIL$CQUAL_FILE_PARSE Flags and Masks.
1.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
LIB$_INVARG Invalid argument. A bit in the flags parameter
was set without an associated qualifier.
CLI$_INVQUAVAL An unusable value was given on the command
line for any of the following qualifiers:
/EXCLUDE, /BEFORE, /SINCE, or /BY_OWNER (for
example, /BEFORE=mintchip).
SS$_CONFQUAL More than one of the following appeared on
the command line at the same time: /CREATED,
/MODIFIED, /EXPIRED, /BACKUP.
Any unsuccessful return from LIB$GET_VM.
2 – UTIL$CQUAL_FILE_MATCH
The UTIL$CQUAL_FILE_MATCH routine matches a file with the
selection criteria.
Format
UTIL$CQUAL_FILE_MATCH context [,user_fab] [,file_name]
[,prompt_string_1] [,prompt_string_2]
[,prompt_rtn] [,current_form] [,disable]
2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition Values Returned lists condition
values that this routine returns.
2.2 – Arguments
context
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The longword address that received the common file qualifier
database address from a prior call to UTIL$CQUAL_FILE_PARSE.
user_fab
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The FAB address of the file to be evaluated. This FAB must point
to a valid NAM or NAML block. If the file is open and the file
header criteria are to be evaluated, the appropriate XABs (XABPRO
or XABDAT) must be chained to the FAB and properly filled in by
RMS. If the file is not open when this routine is called, then
the XAB chain is not necessary, but may be present. This argument
is optional. If it is not present, the file_name parameter must
be present. Both arguments may not be present at the same time.
file_name
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The file name descriptor address of the file to be processed.
This parameter can be used instead of the user_fab argument. Both
arguments may not be present at the same time.
prompt_string_1
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword address of a prompt string descriptor. This prompt is
used when prompting to a terminal device and the current prompt
form is UTIL$K_CQF_SHORT.
prompt_string_2
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by descriptor
Longword address of a prompt string descriptor. This prompt is
used when prompting to a terminal device and the current prompt
form is UTIL$K_CQF_LONG.
prompt_rtn
OpenVMS usage:procedure
type: longword (unsigned)
access: function call
mechanism: by value
User-supplied longword routine address used for prompting and
accepting input from the user. The user routine is responsible
for end-of-file processing and must return RMS$_EOF when
appropriate.
current_form
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read write
mechanism: by reference
This optional parameter supplies the initial prompt form
displayed to the user. If it contains the value UTIL$K_CQF_
UNSPECIFIED, then the form last requested by the user is used
if that form is available. If there was no previous call to
UTIL$CQUAL_FILE_MATCH, and the current_form is unspecified,
UTIL$K_CQF_SHORT is assumed.
When exiting UTIL$CQUAL_FILE_MATCH, the current_form parameter
contains the last user requested prompt form. If a previous
call to UTIL$CQUAL_FILE_MATCH requested quit processing or quit
confirmation prompting, then this parameter is not modified.
disable
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword of bit flags. This optional parameter specifies which
common file qualifiers are ignored in the current call to
UTIL$CQUAL_FILE_MATCH. Qualifiers that cannot be ignored are
/CREATED, /MODIFIED, /EXPIRED, and /BACKUP).
2.3 – Description
UTIL$CQUAL_FILE_MATCH compares the file named in either the user_
fab or file_name parameter (only one can be specified) against
criteria specified by the common file qualifier database pointed
to by the context and the disable parameter flags. UTIL$CQUAL_
FILE_MATCH returns a status as to whether the file does or does
not match the criteria.
If a failure occurs during processing, such as those listed in
the Abnormal Completion Codes, the routine quits processing files
for the context under which the failure occurred. A processing
failure is the same as receiving a quit processing response from
a user prompt. Any additional calls to this routine with the
context that incurred the processing failure will return UTIL$_
QIOPRO. This applies even if the user responded ALL to a previous
confirmation prompt.
For a description of the /CONFIRM prompting, see UTIL$CQUAL_
CONFIRM_ACT.
NOTE
The UTIL$CQUAL_FILE_MATCH current_form parameter is
different from the same parameter in UTIL$CQUAL_CONFIRM_
ACT. UTIL$CQUAL_FILE_MATCH retains the user's last requested
form between calls.
2.4 – Condition Values Returned
Normal Completion Codes:
SS$_NORMAL File matches the criteria and can be
processed.
UTIL$_QUICONACT User requests that confirmation prompting
cease, but that other common file qualifier
criteria be applied on subsequent file
specifications.
UTIL$_FILFAIMAT File failed the evaluation, and should not be
processed.
UTIL$QUIPRO User requests that processing stops.
Abnormal Completion Codes:
LIB$INVARG Incorrect parameter list.
SS$_ACCVIO Unable to access one or more of the parameters
(such as the common file database or user_
fab).
UTIL$_FILFID File specification contains an FID. Due to
file specification aliases, converting an FID
to a file specification is inappropriate for
/EXCLUDE processing.
UTIL$_FILDID File specification contains a DID. Due to
directory specification aliases, converting a
DID to a directory patch is inappropriate for
/EXCLUDE processing when the directory patch
needs to be compared.
LIB$_INVXAB Invalid XAB chain. A necessary XAB (XABPRO or
XABDAT) is missing from the opened file's XAB
chain.
Any unsuccessful code from RMS, LIB$GET_VM, or any unsuccessful
return status from the user-supplied routine (other than RMS$_
EOF).
3 – UTIL$CQUAL_FILE_END
The UTIL$CQUAL_FILE_END routine returns all allocated virtual
memory from the call to UTIL$CQUAL_FILE_PARSE.
Format
UTIL$CQUAL_FILE_END context
3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition Values Returned lists condition
values that this routine returns.
3.2 – Arguments
context
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read write
mechanism: by reference
The longword address that received the common file qualifier
database address from a prior call to UTIL$CQUAL_FILE_PARSE.
3.3 – Description
UTIL$CQUAL_FILE_END deallocates the virtual memory obtained by
the common file qualifier package during the call to UTIL$CQUAL_
FILE_PARSE. The virtual memory held information for calls to
UTIL$CQUAL_FILE_MATCH.
3.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
Any unsuccessful code from LIB$FREE_VM.
4 – UTIL$CQUAL_CONFIRM_ACT
The UTIL$CQUAL_CONFIRM_ACT routine prompts the user for
confirmation, using the optional prompt routine if present, and
returns an indication of the user's response.
Format
UTIL$CQUAL_CONFIRM_ACT [prompt_string_1] [,prompt_string_2]
[,prompt_rtn] [,current_form]
4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition Values Returned lists condition
values that this routine returns.
4.2 – Arguments
prompt_string_1
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by descriptor
Longword address of a prompt string descriptor. The prompt is
used when prompting to a terminal device, and the current prompt
form is UTIL$K_CQF_SHORT.
prompt_string_2
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by descriptor
Longword address of a prompt string descriptor. The prompt is
used when prompting to a terminal device, and the current prompt
form is UTIL$K_CQF_LONG.
prompt_rtn
OpenVMS usage:procedure
type: longword (unsigned)
access: function call
mechanism: by value
Longword address of a user-supplied routine for prompting and
accepting user input. The user routine is responsible for end-of-
file processing and must return RMS$_EOF when appropriate.
current_form
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read write
mechanism: by reference
This optional parameter supplies the initial prompt form to be
displayed to the user. If present, this parameter receives the
form of the last prompt displayed. The following table shows the
valid prompting form values:
Table 3-2 Prompting Form Values
Value Description
UTIL$K_CQF_SHORT Use prompt_string_1.
UTIL$K_CQF_LONG Use prompt_string_2.
UTIL$K_CQF_UNSPECIFIED None specified; use default.
4.3 – Description
UTIL$CQUAL_CONFIRM_ACT prompts the user for confirmation. You
must supply at least one prompt string to this routine. If you
supply both strings, you should have an expanded and condensed
form of the prompt. The condensed form should be supplied through
the prompt_string_1 parameter; the expanded form through prompt_
string_2. The prompt string supplied by prompt_string_1 is
initially used if the prompt_string_1 is present, does not have a
length of zero, and either:
o The current_form parameter is not specified
o The current_form parameter is specified and contains:
- UTIL$K_CQF_SHORT
- UTIL$K_CQF_UNSPECIFIED
- A value greater than UTIL$K_CQF_MAX_FORM
The prompt string supplied by prompt_string_2 is used initially
if prompt_string_2 is present, does not have a length of zero,
and either:
o prompt_string_1 is not present or has a length of zero
o The current_form parameter is specified and contains the value
UTIL$K_CQF_LONG
Once the initial form is displayed, the user can switch between
the two forms by responding to the prompt with either CONDENSED
or EXPANDED. The user can only switch to another form if there
was a prompt string provided for that form. Responding with
either CONDENSED or EXPANDED causes a reprompt to occur, even
if the current display form was not switched.
If a prompt routine is provided, the routine is called with the
address of the prompt string descriptor in the first parameter,
and the string descriptor address to receive the user's response
in the second parameter. The routine returns a success status or
RMS$_EOF.
If an unsuccessful status other than RMS$_EOF is received, then
UTIL$CQUAL_CONFIRM_ACT exits without processing any response
in the response buffer (the second parameter that was passed to
the prompt routine). UTIL$CQUAL_CONFIRM_ACT returns the status
received from the user prompt routine. The prompt routine is
responsible for end-of-file processing, and must return RMS$_EOF
when appropriate. If an optional prompt routine is provided, it
should be provided for all calls to UTIL$CQUAL_CONFIRM_ACT. Not
doing so can cause unpredictable end-of-file processing.
When the user is prompted, they may respond with the following:
Table 3-3 Prompt Responses
Positive Negative
Stop Stop Switch
Response Response Processing Prompting Prompts
YES NO QUIT ALL CONDENSED
TRUE FALSE Ctrl/Z EXPANDED
1 0
<Return>
NOTE
Entering ALL assumes that subsequent files are a positive
response from the user, and no further prompting occurs.
The routine UTIL$CQUAL_FILE_MATCH properly handles this
response. Since UTIL$CQUAL_CONFIRM_ACT does not contain
context from a previous call, callers of this routine
should not call UTIL$CQUAL_CONFIRM_ACT if the user has
previously responded ALL unless the application needs
explicit confirmation on certain items.
The user can use any combination of uppercase and lowercase
letters for word responses. Word responses can be abbreviated
to one or more letters (for example, T, TR, or TRU for TRUE), but
these abbreviations must be unique.
After a valid response is received from the user, the procedure
returns the current_form parameter. The current_form parameter
contains the last form presented to the user if it was specified
and write access is permitted.
4.4 – Condition Values Returned
SS$_NORMAL Positive answer.
LIB$_NEGANS Negative answer.
UTIL$_QUIPRO Quit processing.
UTIL$_QUICONACT Continue processing, but cease prompting.
LIB$_INVARG Invalid argument list (no prompt strings).
SS$_ACCVIO Access violation (on user routine address).
Any unsuccessful return from RMS, SYS$ASSIGN, $QIOW, or from the
user-supplied routine (other than RMS$_EOF).