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