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

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

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

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.

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.