HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The CLI$PRESENT routine examines the parsed command string to determine whether the entity referred to by the entity_desc argument is present.

Format

CLI$PRESENT entity_desc

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 that this routine can return are listed under Conditon Values Returned.

Argument

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 OpenVMS Programming Concepts Manual).

Description

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.

Condition Values Returned

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.

Follow these steps to use the common file qualifier routines:

1. Call UTIL$CQUAL_FILE_PARSE to parse the command line for the common file qualifiers. (See Table 5-2 for a list of the qualifiers.)
2. Call UTIL$CQUAL_FILE_MATCH for each checked file. UTIL$CQUAL_FILE_MATCH returns an indication that the file is, or is not, to be processed.
3. Call UTIL$CQUAL_FILE_END to release the virtual memory held by the common file qualifier package.

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.

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.

5.2.2.1 Specifying 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.

5.2.2.2 Ignoring Qualifiers

        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.

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

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.

$ 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
$ _