/sys$common/syshlp/HELPLIB.HLB  —  CQUAL Routines
    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).
Close Help