VMS Help CQUAL Routines, UTIL$CQUAL_FILE_MATCH  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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