| Previous | Contents | Index |
The CLI$PRESENT routine examines the parsed command string to determine whether the entity referred to by the entity_desc argument is present.
CLI$PRESENT entity_desc
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 that this routine can return are listed under Conditon Values Returned.
entity_desc
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Character string containing the label (or name if no label is defined) of the entity. The entity_desc argument is the address of a string descriptor that points to an entity that may appear on a command line. An entity can be expressed as one of the following:
- A parameter, qualifier, or keyword name or label
- A keyword path
A keyword path is used to reference keywords that are accepted by parameters, qualifiers, or other keywords. A keyword path contains a list of entity names separated by periods. See the description of the entity_desc argument in the CLI$GET_VALUE routine for more information about specifying keyword paths as arguments for CLI routines.
The entity_desc argument can contain parameter, qualifier, or keyword names, or can contain labels that were assigned with the LABEL clause in the command definition file. If the LABEL clause was used to assign a label to a qualifier, parameter, or keyword, you must specify the label in the entity_desc argument. Otherwise, you must use the actual name of the qualifier, parameter, or keyword.
If the entity_desc argument does not exist in the command table, CLI$PRESENT signals a syntax error (by means of the signaling mechanism described in the HP OpenVMS Programming Concepts Manual).
The CLI$PRESENT routine examines the parsed command string to determine whether the entity referred to by the entity_desc argument is present.When CLI$PRESENT tests whether a qualifier is present, the condition value indicates whether the qualifier is used globally or locally. You can use a global qualifier anywhere in the command line; you use a local qualifier only after a parameter. A global qualifier is defined in the command definition file with PLACEMENT=GLOBAL; a local qualifier is defined with PLACEMENT=LOCAL.
When you test for the presence of a global qualifier, CLI$PRESENT determines if the qualifier is present anywhere in the command string. If the qualifier is present in its positive form, CLI$PRESENT returns CLI$_PRESENT; if the qualifier is present in its negative form, CLI$PRESENT returns CLI$_NEGATED.
You can test for the presence of a local qualifier when you are parsing parameters that can be followed by qualifiers. After you call CLI$GET_VALUE to fetch the parameter value, call CLI$PRESENT to determine whether the local qualifier is present. If the local qualifier is present in its positive form, CLI$PRESENT returns CLI$_LOCPRES; if the local qualifier is present in its negative form, CLI$PRESENT returns CLI$_LOCNEG.
A positional qualifier affects the entire command line if it appears after the verb but before the first parameter. A positional qualifier affects a single parameter if it appears after a parameter. A positional qualifier is defined in the command definition file with the PLACEMENT=POSITIONAL clause.
To determine whether a positional qualifier is used globally, call CLI$PRESENT to test for the qualifier before you call CLI$GET_VALUE to fetch any parameter values. If the positional qualifier is used globally, CLI$PRESENT returns either CLI$_PRESENT or CLI$_NEGATED.
To determine whether a positional qualifier is used locally, call CLI$PRESENT immediately after a parameter value has been fetched by CLI$GET_VALUE. The most recent CLI$GET_VALUE call to fetch a parameter defines the context for a qualifier search. Therefore, CLI$PRESENT tests whether a positional qualifier was specified after the parameter that was fetched by the most recent CLI$GET_VALUE call. If the positional qualifier is used locally, CLI$PRESENT returns either CLI$_LOCPRES or CLI$_LOCNEG.
CLI$_ABSENT Specified entity not present, and it is not present by default. CLI$_DEFAULTED Specified entity not present, but it is present by default. CLI$_INVREQTYP Calling process did not have a CLI to perform this function, or the CLI did not support the request. CLI$_LOCNEG Specified qualifier present in negated form (with /NO) and used as a local qualifier. CLI$_LOCPRES Specified qualifier present and used as a local qualifier. CLI$_NEGATED Specified qualifier present in negated form (with /NO) and used as a global qualifier. CLI$_PRESENT Specified entity present in the command string. This status is returned for all entities except local qualifiers and positional qualifiers that are used locally.
This chapter describes the common file qualifier (UTIL$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.
5.1 Introduction to the Common File Qualifier Routines
The common file qualifier routines begin with the characters UTIL$CQUAL. Your program calls these routines using the OpenVMS Calling Standard. When you call a UTIL$CQUAL routine, you must provide all the required arguments. Upon completion, the routine returns its completion status as a condition value. Section 5.3 provides detailed descriptions of the routines.
The following table lists the common file qualifier routines.
| Routine Name | Description |
|---|---|
| UTIL$CQUAL_FILE_PARSE | Parses the command line for the file qualifiers listed in Table 5-2, and obtains associated values. Returns a context value that is used when calling the matching and ending routines. |
| UTIL$CQUAL_FILE_MATCH | Compares the routine file input to the command line data obtained from the parse routine call. |
| UTIL$CQUAL_FILE_END | Deletes all virtual memory allocated during the command line parse routine call. |
| UTIL$CQUAL_CONFIRM_ACT | Prompts a user for a response from SYS$COMMAND. |
Follow these steps to use the common file qualifier routines:
You may optionally call UTIL$CQUAL_CONFIRM_ACT to ask for user
confirmation without calling the other common qualifier routines.
5.2.1 Calling UTIL$CQUAL_FILE_PARSE
When you call UTIL$CQUAL_FILE_PARSE, specify the qualifiers listed in Table 5-2 that you want to parse by setting bits in a flags longword and passing the longword address as the first parameter.
| Qualifier | Description |
|---|---|
| BEFORE= | Selects a file before the specified time. |
| CONFIRM | Prompts the user for confirmation. |
| SINCE= | Selects a file on or after the specified time. |
| MODIFIED | Specifies that the file's revision time (time of last modification) is used for comparison with the time specified in either the /BEFORE or /SINCE qualifier. |
| CREATED (default) | Specifies that the file's creation time is used for comparison with the time specified in either the /BEFORE or /SINCE qualifier. |
| BACKUP | Specifies that the file's most recent backup time is used for comparison with the time specified in either the /BEFORE or /SINCE qualifier. |
| EXPIRED | Specifies that the file's expiration date is used for comparison with the time specified in either the /BEFORE or /SINCE qualifier. |
| BY_OWNER= | Selects a file based on the file owner's user identification code. The default is the UIC of the current process. |
| EXCLUDE= | Selects a file only if it does not match the specification or list of specifications given with this qualifier. |
The following segment from a sample C program shows the flags longword set to search for the common file qualifiers supported by this package:
input_flags = UTIL$M_CQF_CONFIRM | UTIL$M_CQF_EXCLUDE |
UTIL$M_CQF_BEFORE | UTIL$M_CQF_SINCE |
UTIL$M_CQF_CREATED | UTIL$M_CQF_MODIFIED |
UTIL$M_CQF_EXPIRED | UTIL$M_CQF_BACKUP |
UTIL$M_CQF_BYOWNER;
|
Optionally, you can provide the flags longword address for UTIL$CQUAL_FILE_PARSE to return an indication of what common file qualifiers were present on the command line. For example, if /CONFIRM is enabled and was found on the command line, the application can determine if confirmation prompts need to be built. The following is an example call in C:
status = UTIL$CQUAL_FILE_PARSE (&input_flags,
&context,
&output_flags);
|
The context variable contains the address of the common file qualifier
value which is used in other common file qualifier routine calls.
5.2.1.1 Specifying Times
The times specified with the /SINCE= and /BEFORE= qualifiers must be in either absolute or combination time format. When DCL gathers these times from the command line, it converts truncated time values, combination time values, and keywords (such as BOOT, LOGIN, TODAY, TOMORROW, or YESTERDAY) into absolute time format. Files are selected based on the times entered on the command line, and are compared to the time of the file's backup date, creation date (default), expiration date, or last modification date as indicated by the modifier qualifiers /BACKUP, /CREATED, /EXPIRED, and /MODIFIED respectively.
For complete information on specifying time values, see the OpenVMS
User's Manual or the topic DCL_TIPS Date_Time in online help.
5.2.1.2 Specifying Exclude Pattern Strings
Pattern strings are used to exclude specific files from being processed. The pattern strings may contain a combination of a directory specification, filename, filetype, and version number. Node names and device names are not permitted. Relative directory specifications are allowed (such as [.subdirectory] or [-]), but relative version numbers have no meaning as a pattern string component. UTIL$CQUAL_FILE_PARSE assumes relative version numbers are a wildcard, and matches all versions. An FID or DID specification is also not allowed.
To exclude more than one specification, use a comma-separated list
enclosed within parentheses.
5.2.2 Calling UTIL$CQUAL_FILE_MATCH
When calling UTIL$CQUAL_FILE_MATCH, specify a file that you want checked against criteria in the common file qualifier context. The context address was returned as the first parameter in a prior call to UTIL$CQUAL_FILE_PARSE, and is the first parameter for UTIL$CQUAL_FILE_MATCH.
To specify a file, provide either a string descriptor containing the specification or an RMS FAB. The FAB must contain an NAM block that has been filled in by RMS, so that comparisons with excluded file specifications can occur. If the FAB indicates that the file is open, and any of the /BEFORE, /SINCE or /BY_OWNER qualifiers are to be evaluated, then the appropriate XAB blocks must be in the XAB chain (XABDAT and XABPRO). The XAB blocks must be filled in by RMS during the file open.
The files passed in with a DID or an FID specification may cause the common qualifier package to stop processing if that portion of the file specification needs to be matched against a pattern string from the /EXCLUDE qualifier. |
5.2.2.1 Specifying Prompts
You can provide one or two prompts when specifying prompts as
confirmation messages. If confirmation is active, at least one prompt
string must be specified. When providing two prompts, use the shorter
prompt as the prompt_string_1 parameter. Table 5-5
lists the valid confirmation prompt responses. CONDENSED and EXPANDED
are used when switching between prompts.
The user responding CONDENSED (or just C) displays the prompt_string_1 string. For a more descriptive or detailed prompt, use prompt_string_2 in your call. For example, the OpenVMS utilities construct prompts from the short and long fields of an RMS NAML block. The prompt from the short field is passed through prompt_string_1, and the prompt from the long field is passed through prompt_string_2.
You have the option of specifying a prompt routine. The first parameter for the prompt routine will contain a string descriptor of the prompt to be displayed. The second parameter will contain the address of a buffer for the user's response. You must modify the response buffer to reflect the length of the user's response. Table 5-5 lists the valid prompt routine responses. All other responses display an invalid response warning, and call the prompt routine again.
When two prompts are supplied to UTIL$CQUAL_FILE_MATCH, the optional parameter current_form can be used to determine which prompt string is displayed first. Table 5-4 lists the valid current_form values.
If the value stored in current_form is not in the values listed, then UTIL$K_CQF_SHORT is assumed. If the value is UTIL$K_CQF_UNSPECIFIED, or this parameter is absent from the call, then the form stored in the common file qualifier database is used. The value currently stored in the common file qualifier database is the final form active when UTIL$CQUAL_FILE_MATCH returned from the previous call with the current database context. If there was no previous call, UTIL$K_CQF_SHORT is stored in the database.
If the current_form parameter can be written to, the final active form is stored before UTIL$CQUAL_FILE_MATCH returns.
If only one prompt string is provided to UTIL$CQUAL_FILE_MATCH, the final form will be the form corresponding to that prompt string even if the user requests the alternate form. For example, if only the short prompt string is provided and the user requests the long prompt, the user receives the short prompt. UTIL$K_CQF_SHORT is returned through the current_form parameter if that parameter is writable. |
5.2.2.2 Ignoring Qualifiers
The final parameter, which is also optional, is a flags longword used
to ignore certain qualifier processing when calling
UTIL$CQUAL_FILE_MATCH. The modifier qualifiers for date comparisons
(/CREATED, /MODIFIED, /BACKUP, and /EXPIRED) cannot be ignored. If
either the /SINCE or /BEFORE modifier qualifiers are active, then the
date comparison modifier qualifiers must be active to determine which
dates to compare. For example, to operate on the top two versions of a
file set when confirmation is active, an application can keep track of
the first two instances and prompt the user. Once the application
reaches that number, it sets the UTIL$M_CQF_CONFIRM bit in the
disable parameter flags longword, and the user is not
prompted for confirmation during that call. The following is an example
call in C:
status = UTIL$CQUAL_FILE_MATCH (&context,
0,
&result_desc,
&short_prompt,
&long_prompt,
0,
&prompt_form,
&ignore_flags);
|
When calling UTIL$CQUAL_FILE_END, specify the context variable that contains the common file qualifier database context to be terminated. The database location was returned in a prior call to UTIL$CQUAL_FILE_PARSE. The UTIL$CQUAL_FILE_END call deallocates all virtual memory held by the common file qualifier value in the context parameter. The context variable is zeroed before this routine returns. The following is an example call in C:
status = UTIL$CQUAL_FILE_END (&context);
|
Similar to UTIL$CQUAL_FILE_MATCH, the parameter list used when calling UTIL$CQUAL_CONFIRM_ACT is a subset of the UTIL$CQUAL_FILE_MATCH parameter list.
When specifying prompts as confirmation messages, you can provide one or two prompts. At least one prompt string must be specified. When providing two prompts, use the shorter of the two prompts as the prompt_string_1 parameter. Table 5-5 lists valid responses to a confirmation prompt, and lists CONDENSED and EXPANDED to switch between prompts.
The user responding CONDENSED (or just C) causes the prompt_string_1 string to be displayed. To give the user a more descriptive or detailed prompt, use prompt_string_2 in your call. For example, the OpenVMS utilities construct prompts from the short and long fields of an RMS NAML block. The prompt from the short field is passed through prompt_string_1, and the prompt from the long field is passed through prompt_string_2.
You have the option of specifying a prompt routine. The first parameter for the prompt routine is a string descriptor of the prompt to be displayed. The second parameter contains the address of a buffer for the user's response. You must modify the response buffer to reflect the length of the user's response. Table 5-5 lists valid prompt routine responses. All other responses display an invalid response warning, and call the prompt routine again.
When two prompts are supplied to UTIL$CQUAL_CONFIRM_ACT, the optional parameter current_form can be used to determine which prompt string is displayed first. The valid values are listed in Table 5-4. If the value stored is other than the values listed, UTIL$K_CQF_SHORT is assumed. If the value is UTIL$K_CQF_UNSPECIFIED or this parameter is absent from the call, then UTIL$K_CQF_SHORT is used.
If the current_form parameter can be written to, the final active form is stored before UTIL$CQUAL_CONFIRM_ACT returns.
If only one prompt string is passed into the UTIL$CQUAL_CONFIRM_ACT call, the final form will be the form corresponding to that prompt string even if the user requests the alternate form. For example, if only the short prompt string is provided and the user requests the long prompt, the user receives the short prompt again. UTIL$K_CQF_SHORT is returned through the current_form parameter if that parameter is writable. |
The following is an example call in C:
status = UTIL$CQUAL_CONFIRM_ACT (&short_prompt,
&long_prompt,
0,
&prompt_form);
|
For UTIL$CQUAL_FILE_PARSE to function properly, you need the following Command Language Definition (CLD) file template in the command tables being examined:
define verb foo
image foo
parameter p1,prompt="File",value(list,impcat,required,type=$infile)
qualifier confirm
qualifier exclude,value(required,list)
qualifier before,value(default=today,type=$datetime)
qualifier since,value(default=today,type=$datetime)
qualifier created
qualifier modified
qualifier expired
qualifier backup
qualifier by_owner,value(type=$uic)
|
For example, if the line qualifier expired was omitted, a call to UTIL$CQUAL_FILE_PARSE would result in:
$ foo *.c
%CLI-F-SYNTAX, error parsing 'EXPIRED'
-CLI-E-ENTNF, specified entity not found in command tables
%TRACE-F-TRACEBACK, symbolic stack dump follows
image module routine line rel PC abs
...
|
A default value for the /SINCE= and /BEFORE= qualifiers is provided in the CLD file. If you do not require a value, specify a default or you may not get the desired result. |
The following example shows a C program that retrieves files from the command line, and lists which ones will be processed, if processing is required.
| Example 5-1 Using UTIL$CQUAL Routines to Process Files |
|---|
$ create foo.c
#include <stdio.h>
#include <string.h>
#include <rms.h>
#include <starlet.h>
#include <descrip.h>
#include <lib$routines.h>
#include <libfildef.h>
#include <cli$routines.h>
#include <cqualdef.h>
#include <util$routines.h>
#ifdef NAML$C_BID /* determine if HFS support is here */
#define HFS_Support 1
#else
#define HFS_Support 0
#endif
#if !HFS_Support /* compensate for lack of HFS support */
#define naml$l_rsa nam$l_rsa
#define naml$b_rsl nam$b_rsl
#define naml$l_long_result nam$l_rsa
#define naml$l_long_result_size nam$b_rsl
#define NAML$C_MAXRSS NAM$C_MAXRSS
#define LIB$M_FIL_LONG_NAMES 0
#endif
unsigned int input_flags;
unsigned int output_flags;
unsigned int ignore_flags = 0;
unsigned int *context;
char get_value[NAM$C_MAXRSS];
char *prompt_string = "Confirmation for ";
char *prompt_end = " [N] ? ";
char *process = " Will process ";
char *noprocess = " Will not process ";
char short_string[NAM$C_MAXRSS+80];
unsigned int prompt_form = 0;
unsigned int status;
struct fabdef *find_file_context;
unsigned int find_file_flags;
unsigned short ret_length;
$DESCRIPTOR(parm_1, "P1");
$DESCRIPTOR(get_val_desc, get_value);
$DESCRIPTOR(short_prompt, short_string);
$DESCRIPTOR(result_desc, "");
char long_string[NAML$C_MAXRSS+80];
char outstring[NAML$C_MAXRSS+80];
$DESCRIPTOR(long_prompt, long_string);
#if HFS_Support
struct namldef *nam_block;
#else
struct namdef *nam_block;
#endif
extern UTIL$_QUICONACT; /* external literal */
extern UTIL$_QUIPRO; /* external literal */
int main(void) {
input_flags = UTIL$M_CQF_CONFIRM | UTIL$M_CQF_EXCLUDE |
UTIL$M_CQF_BEFORE | UTIL$M_CQF_SINCE |
UTIL$M_CQF_CREATED | UTIL$M_CQF_MODIFIED |
UTIL$M_CQF_EXPIRED | UTIL$M_CQF_BACKUP |
UTIL$M_CQF_BYOWNER;
if (!(status = UTIL$CQUAL_FILE_PARSE ( &input_flags,
&context,
&output_flags) & 1)) {
return status;
};
find_file_flags = LIB$M_FIL_MULTIPLE | LIB$M_FIL_LONG_NAMES;
get_val_desc.dsc$w_length = sizeof(get_value);
status = cli$get_value(&parm_1, &get_val_desc, &ret_length);
result_desc.dsc$b_class = DSC$K_CLASS_D;
result_desc.dsc$a_pointer = 0;
while (status & 1) {
get_val_desc.dsc$w_length = ret_length;
while ((status != (int)&UTIL$_QUIPRO) && /* treat as external literal*/
(LIB$FIND_FILE(&get_val_desc, &result_desc,
&find_file_context, 0, 0, 0,
&find_file_flags) & 1)) {
#if HFS_Support
nam_block = find_file_context->fab$l_naml;
#else
nam_block = find_file_context->fab$l_nam;
#endif
if ((output_flags && UTIL$M_CQF_CONFIRM) != 0) {
strcpy(short_string, prompt_string);
strncat(short_string, nam_block->naml$l_rsa,
(int)nam_block->naml$b_rsl);
strcat(short_string, prompt_end);
short_prompt.dsc$w_length = strlen(short_string);
strcpy(long_string, prompt_string);
strncat(long_string, nam_block->naml$l_long_result,
(int)nam_block->naml$l_long_result_size);
strcat(long_string, prompt_end);
long_prompt.dsc$w_length = strlen(long_string);
}
else {
short_prompt.dsc$w_length = 0;
long_prompt.dsc$w_length = 0;
};
if ((status = UTIL$CQUAL_FILE_MATCH(&context,
0,
&result_desc,
&short_prompt,
&long_prompt,
0,
&prompt_form,
&ignore_flags)) & 1) {
strcpy(outstring, process);
}
else {
strcpy(outstring, noprocess);
};
if (prompt_form == UTIL$K_CQF_SHORT) {
strncat(outstring, nam_block->naml$l_rsa,
(int)nam_block->naml$b_rsl);
}
else {
strncat(outstring, nam_block->naml$l_long_result,
(int)nam_block->naml$l_long_result_size);
};
printf("%s\n", outstring);
if (status == (int)&UTIL$_QUICONACT) { /* treat as external literal*/
output_flags &= ~UTIL$M_CQF_CONFIRM;
};
};
if (status != (int)&UTIL$_QUIPRO) {
get_val_desc.dsc$w_length = sizeof(get_value);
status = cli$get_value(&parm_1, &get_val_desc, &ret_length);
};
};
status = UTIL$CQUAL_FILE_END (&context);
return status;
}
$ cc/list foo.c
$ link foo.c
$ set command foo.cld
$ define foo sys$disk:[]foo.exe
$ directory/noexclude
Directory MDA2000:[main]
EDTINI.EDT;1 FOO.BAR;1 FOO.C;2
FOO.C;1 FOO.CLD;2 FOO.CLD;1
FOO.EXE;3 FOO.EXE;2 FOO.EXE;1
FOO.LIS;1 FOO.OBJ;1 LAST.COM;1
LOGIN.COM;1 MAIL.MAI;1 MDA0.DAT;1
NOTE.DAT;1 QUEUE.COM;1 TPUINI.TPU;1
Total of 18 files.
$ foo/exclude=*.c *.*;*
Will process MDA2000:[main]EDTINI.EDT;1
Will process MDA2000:[main]FOO.BAR;1
Will not process MDA2000:[main]FOO.C;2
Will not process MDA2000:[main]FOO.C;1
Will process MDA2000:[main]FOO.CLD;2
Will process MDA2000:[main]FOO.CLD;1
Will process MDA2000:[main]FOO.EXE;3
Will process MDA2000:[main]FOO.EXE;2
Will process MDA2000:[main]FOO.EXE;1
Will process MDA2000:[main]FOO.LIS;1
Will process MDA2000:[main]FOO.OBJ;1
Will process MDA2000:[main]LAST.COM;1
Will process MDA2000:[main]LOGIN.COM;1
Will process MDA2000:[main]MAIL.MAI;1
Will process MDA2000:[main]MDA0.DAT;1
Will process MDA2000:[main]NOTE.DAT;1
Will process MDA2000:[main]QUEUE.COM;1
Will process MDA2000:[main]subdir.DIR;1
Will process MDA2000:[main]TPUINI.TPU;1
$ foo/confirm *.*
Confirmation for MDA2000:[main]EDTINI.EDT;1 [N] ? n
Will not process MDA2000:[main]EDTINI.EDT;1
Confirmation for MDA2000:[main]FOO.BAR;1 [N] ? n
Will not process MDA2000:[main]FOO.BAR;1
Confirmation for MDA2000:[main]FOO.C;2 [N] ? y
Will process MDA2000:[main]FOO.C;2
Confirmation for MDA2000:[main]FOO.CLD;2 [N] ? q
Will not process MDA2000:[main]FOO.CLD;2
$ foo/since=yesterday/modified/exclude=(*.*;2,l*) foo.*;*,*.com;*
Will process MDA2000:[main]FOO.BAR;1
Will not process MDA2000:[main]FOO.C;2
Will process MDA2000:[main]FOO.C;1
Will not process MDA2000:[main]FOO.CLD;2
Will process MDA2000:[main]FOO.CLD;1
Will process MDA2000:[main]FOO.EXE;3
Will not process MDA2000:[main]FOO.EXE;2
Will process MDA2000:[main]FOO.EXE;1
Will process MDA2000:[main]FOO.LIS;1
Will process MDA2000:[main]FOO.OBJ;1
Will not process MDA2000:[main]LAST.COM;1
Will not process MDA2000:[main]LOGIN.COM;1
Will process MDA2000:[main]QUEUE.COM;1
$ _
|
| Previous | Next | Contents | Index |