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

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