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]
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 – 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).
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.
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).