Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## 5.3 UTIL$CQUAL Routines

This section describes the UTIL$CQUAL routines.

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

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

### 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 5-3 UTIL$CQUAL_FILE_PARSE Flags and Masks
> Qualifier | Mask Value | Field Specifier
> --- | --- | ---
> /CONFIRM | UTIL$M_CQF_CONFIRM | UTIL$V_CQF_CONFIRM
> /EXCLUDE | UTIL$M_CQF_EXCLUDE | UTIL$V_CQF_EXCLUDE
> /BEFORE | UTIL$M_CQF_BEFORE | UTIL$V_CQF_BEFORE
> /SINCE | UTIL$M_CQF_SINCE | UTIL$V_CQF_SINCE
> /CREATED | UTIL$M_CQF_CREATED | UTIL$V_CQF_CREATED
> /MODIFIED | UTIL$M_CQF_MODIFIED | UTIL$V_CQF_MODIFIED
> /EXPIRED | UTIL$M_CQF_EXPIRED | UTIL$V_CQF_EXPIRED
> /BACKUP | UTIL$M_CQF_BACKUP | UTIL$V_CQF_BACKUP
> /BY_OWNER | UTIL$M_CQF_BYOWNER | UTIL$V_CQF_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 Table 5-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 Table 5-3.

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

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

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

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

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

### Condition Values Returned

> Normal Completion Codes:

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

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

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

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

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

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.

Any unsuccessful code from LIB$FREE_VM.

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

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

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

### 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:
> - The current_form parameter is not specified
> - 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:

> - prompt_string_1 is not present or has a length of zero
> - 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 5-5 Prompt Responses
> Positive Response | Negative Response | Stop Processing | Stop Prompting | Switch 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.

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

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_005.HTML