 |
OpenVMS Utility Routines Manual
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).
|
