OpenVMS Utility Routines Manual

Updated: 11 December 1998

OpenVMS Utility Routines Manual

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.

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

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.

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

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

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

Contents

Index

Legal

 
4493PRO_005.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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.

OpenVMS usage:	procedure
type:	longword (unsigned)
access:	function call
mechanism:	by value

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.

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