SysWorks©

SysWorks
Command Reference Manual
Previous Contents Index

UTLTOOLS DEFINE/V1

Associates an equivalence name with a logical name. If you specify an existing logical name, the new equivalence name replaces the existing equivalence name.

Format

UTLTOOLS DEFINE/V1 logical-name check-ind equivalence-name[,...]

Parameters

logical-name

Specifies the logical name string, which is a character string containing from 1 to 255 characters. The following rules apply:

check-ind

Specifies whether the equivalence object (eg. directory or file) must exist. A value of NO indicates that the object doesn't need to exist. A value of YES indicates that the object must exist, and that an error message should be displayed if it doesn't. In either case, the logical name is not defined if the object is not found.

The one exception to this rule is where the equivalence is a file, the check indicator NO is specified, the file doesn't exist but the directory for the file does. In this case the logical name is defined with an equivalence of the parsed directory and file. Thus, so long as an appropriate directory exists, the logical name may be used to create the file and it will be placed in the first appropriate directory since pasring results in the first found directory in a search list.

equivalence-name

Specifies a character string containing from 1 to 255 characters. The following rules apply:

The UTLTOOLS DEFINE command allows you to assign the same logical name to more than one equivalence name. For example, you can use the same logical name to access different directories on different disks or to access different files in different directories.

When you specify more than one equivalence name for a logical name, you create a search list. See the OpenVMS User's Manual for more information on search lists.

Qualifiers

The qualifiers for UTLTOOLS DEFINE/V1 are the same as for UTLTOOLS DEFINE with the exception of the /CHECK[=code] qualifier which is not supported.

Examples

#1 

$ UTLTOOLS DEFINE/V1 TM1 YES $DISK1:[ACCOUNTS.MEMOS]WATER.TXT

In this example, the UTLTOOLS DEFINE/V1 command defines TM1 as equivalent to a file specification. The file must exist for the definition to succeed. An error message is displayed if the file is not found.

UTLTOOLS DEFINE/VARIABLE

Associates a SysWorks variable value with a logical name. If you specify an existing logical name, the new value replaces the existing value.

The logical name defined will either be the variable name, or the variable name prefaced with a code and an underscore. If the definition is placed in a context logical name table (i.e. /CONTEXT is used), the prefix code is that associated with the context. If the definition is placed in the SysWorks database logical name table (i.e. /TABLE=LNM_SWRK_DATABASE is used), the prefix code is SWRK.

Format

UTLTOOLS DEFINE/VARIABLE variable-name default-value

Parameters

variable-name

Specifies the logical name string, which is a character string containing from 1 to 28 uppercase alphanumerics, dollar sign, or underscore characters.

default-value

Specifies the default value to be used for the variable if either the variable is not found or has a blank value. If no default value is supplied and either of these conditions occurs, an error message will be displayed.

Qualifiers

/CONTEXT

Requires write (W) access to the context table to specify the name.

Places the logical name in the context logical name table. Other users who use the same context can access the logical name. Using /CONTEXT qualifier is similar to using the /TABLE=LNM$CONTEXT qualifier.

See CONTEXT for details about contexts.

This qualifier is incompatible with the /GROUP, /JOB, /PROCESS, /SYSTEM and /TABLE qualifiers.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege to create an executive-mode logical name.

Creates an executive-mode logical name in the specified table.

If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM privilege, the UTLTOOLS DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.

This qualifier is incompatible with the /KERNEL_MODE, /SUPERVISOR_MODE and /USER_MODE qualifiers.

/GROUP

Requires GRPNAM (group logical name) or SYSNAM (system logical name) privilege to place a name in the group logical name table.

Places the logical name in the group logical name table. Other users who have the same group number in their user identification codes (UICs) can access the logical name. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.

This qualifier is incompatible with the /CONTEXT, /JOB, /PROCESS, /SYSTEM and /TABLE qualifiers.

/JOB

Places the logical name in the jobwide logical name table. All processes in the same job tree as the process that created the logical name can access the logical name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier.

This qualifier is incompatible with the /CONTEXT, /GROUP, /PROCESS, /SYSTEM and /TABLE qualifiers.

/KERNEL_MODE

Requires SYSNAM (system logical name) privilege to create an kernel-mode logical name.

Creates an kernel-mode logical name in the specified table.

If you specify the /KERNEL_MODE qualifier and you do not have SYSNAM privilege, the UTLTOOLS DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.

This qualifier is incompatible with the /EXECUTIVE_MODE, /SUPERVISOR_MODE and /USER_MODE qualifiers.

/LOG (default)

/NOLOG

Displays a message when a new logical name supersedes an existing name.

/NAME_ATTRIBUTES[=(keyword[,...])]

Specifies attributes for a logical name. By default, no attributes are set. Possible keywords are as follows:
CONFINE The logical name is not copied into a spawned subprocess. This qualifier is relevant only for logical names in a private table.

The logical name inherits the CONFINE attribute from the logical name table where it is entered; if the logical name table is "confined," then all names in the table are "confined."

NO_ALIAS A logical name cannot be duplicated in the specified table in a less privileged access mode; any previously created identical names in an outer (less privileged) access mode within the specified table are deleted.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.

/PROCESS (default)

Places the logical name in the process logical name table. The /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.

This qualifier is incompatible with the /CONTEXT, /GROUP, /JOB, /SYSTEM and /TABLE qualifiers.

/QUOTE (default)

/NOQUOTE

Specifies whether equivalence values written to DCL command procedures are enclosed in quotation marks.

By default, equivalence values are placed in quotation marks.

/SUPERVISOR_MODE (default)

Creates a supervisor-mode logical name in the specified table. The mode of the logical name must be the same as or less privileged than the mode of the table in which you are placing the name.

This qualifier is incompatible with the /EXECUTIVE_MODE, /KERNEL_MODE and /USER_MODE qualifiers.

/SYSTEM

Requires write (W) access or SYSNAM (system logical name) privilege to place a name in the system logical name table.

Places the logical name in the system logical name table. All system users can access the logical name. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.

This qualifier is incompatible with the /CONTEXT, /GROUP, /JOB, /PROCESS and /TABLE qualifiers.

/TABLE=name

Requires write (W) access to the table to specify the name of a shareable logical name table.

Specifies the name of the logical name table in which the logical name is to be entered. You can use the /TABLE qualifier to specify a user-defined logical name table (created with the CREATE/NAME_TABLE command); to specify the process, job, group, or system logical name tables; or to specify the process or system logical name directory tables.

If you specify the table name using a logical name that has more than one translation, the logical name is placed in the first table found. For example, if you specify UTLTOOLS DEFINE/TABLE=LNM$FILE_ DEV and LNM$FILE_DEV is equated to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the logical name is placed in LNM$PROCESS.

The default is the /TABLE=LNM$PROCESS qualifier.

This qualifier is incompatible with the /CONTEXT, /GROUP, /JOB, /PROCESS and /SYSTEM qualifiers.

/USER_MODE

Creates a user-mode logical name in the specified table.

User-mode logical names created within the process logical name tables are used for the execution of a single image; for example, you can create a user-mode logical name to allow an image executing in a command procedure to redefine SYS$INPUT. User-mode entries are deleted from the process logical name table when any image executing in the process exits (that is, after a DCL command or user program that executes an image completes execution). Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

This qualifier is incompatible with the /EXECUTIVE_MODE, /KERNEL_MODE and /SUPERVISOR_MODE qualifiers.

Examples

#1 

$ UTLTOOLS DEFINE/VARIABLE/TABLE=LNM_SWRK_DATABASE SITE_HEADING "Default"

In this example, the UTLTOOLS DEFINE/VARIABLE command defines the logical name swrk_site_heading in the LNM_SWRK_DATABASE logical name table.

UTLTOOLS DELETE

Deletes one or more files. This command is similar to the DCL DELETE command with the addition of some extra qualifiers.

Format

UTLTOOLS DELETE filespec[,...]

Parameters

filespec[,...]

Specifies the names of one or more files to be deleted from a mass storage disk volume. The first file specification must contain an explicit or default directory specification plus an explicit file name, file type, and version number. Subsequent file specifications need contain only a version number; the defaults will come from the preceding specification. The asterisk (*) and the percent sign (%) wildcard characters can be used in any of the file specification fields.

If you omit the directory specification or device name, the current default device and directory are assumed.

If the file specification contains a null version number (a semicolon (;) followed by no file version number), a version number of 0, or one or more spaces in the version number, the latest version of the file is deleted.

To delete more than one file, separate the file specifications with either commas (,) or plus signs (+).

Qualifiers

/BACKUP

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /BACKUP selects files according to the dates of their most recent backups. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /CREATED, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/BEFORE[=time]

Selects only those files dated prior to the specified time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

See the OpenVMS DCL Concepts Manual for complete information on specifying time values.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC using standard UIC format as described in the OpenVMS DCL Concepts Manual.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each delete operation to confirm that the operation should be performed on that file. The following responses are valid: 


     YES      NO       QUIT 
     TRUE     FALSE    [Ctrl/Z]
     1        0        ALL 
              [Return]

You 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. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CREATED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /CREATED selects files based on their dates of creation. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/EXCLUDE=(file-spec[,...])

Excludes the specified files from the delete operation. You can include a directory but not a device in the file specification. Wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you provide only one file specification, you can omit the parentheses.

/EXPIRED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /EXPIRED selects files according to their expiration dates. (The expiration date is set with the SET SECURITY/EXPIRED command.) The /EXPIRED qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/LOG[=(option[,...]) (default)

/NOLOG

Outputs messages to the output file depending upon the option(s) specified.

The following log options are available:
Option Meaning
[NO]ALL Log all information. This is the default action.
[NO]ERROR Log errors.
[NO]NONE Don't log any information. This is the equivalent to /NOLOG.
[NO]NOTFOUND Log files that were not found.
[NO]SUCCESS Log files that were deleted.

/MODIFIED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /MODIFIED selects files according to the dates on which they were last modified. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /CREATED and /EXPIRED. If you specify none of these four time modifiers, the default is /CREATED.

/SELECT=(keyword[,...])

Allows you to select files based on a number of criteria. Choose one of the following keywords:
ACL
NOACL 		Selects files that have an associated ACL or files that do not (NOACL keyword).
ATTRIBUTES=(option[,...]) Selects files which have particular attributes. The following options are supported:
Option Description
[NO]BACKUP Selects files which have backups enabled (BACKUP) or disabled (NOBACKUP)
LRL=MAXIMUM=size Selects files which have a longest record size less than or equal to the specified value.
LRL=MINIMUM=size Selects files which have a longest record size greater than or equal to the specified value.
ORG=type Selects files which have the specified organization. Valid organizations include:
  • DIRECT
  • INDEXED
  • RELATIVE
  • SEQUENTIAL
RFM=type Selects files which have the specified record format. Valid record formats include:
  • STREAM
  • STREAMCR
  • STREAMLF
  • UNDEFINED
  • VARIABLE
  • VFC
FILE=(option[,...]) Selects portions of the file specification for display purposes. The /SELECT=FILE qualifier is used to turn off specific portions by explicit or implicit specification of the options. Possible options are:
  • [NO]NODE
  • [NO]DEVICE
  • [NO]DIRECTORY
  • [NO]NAME
  • [NO]TYPE
  • [NO]VERSION

/SELECT=FILE qualifier cannot be used with the /FULL qualifier.

ONLINE
NOONLINE 		Selects files that are online or shelved.
PRESHELVED
NOPRESHELVED 		Selects files that are preshelved or not preshelved.
SHELVABLE
NOSHELVABLE 		Selects files that are shelvable or not shelvable.
SIZE=(option[,...]) Selects files according to their size. Possible options are:
Option Description
MAXIMUM=n Selects files that have fewer blocks than the value of n, which defaults to 1,073,741,823. Use with MINIMUM=n to specify a size range for files to be selected.
MINIMUM=n Selects files that have blocks equal to or greater than the value of n. Use with MAXIMUM=n to specify a size range for files to be selected.
(MINIMUM=n, MAXIMUM=n) Selects files whose block size falls within the specified MINIMUM and MAXIMUM range.

/SINCE=[time]

Selects only those files dated after the specified time. You can specify time as an absolute time, a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

See the OpenVMS DCL Concepts Manual for complete information on specifying time values.

Examples

#1 

$ UTLTOOLS DELETE FIN_LIB_DIR:*.MMS_INC;*

UTLTOOLS DIFFERENCES/NAMES

Match lists and/or directories of files for differences and generate appropriate commands to synchronise the files.

Format

UTLTOOLS DIFFERENCES/NAMES input-file-or-list output-directory

Qualifiers

/ARCHITECTURE (Default)

/NOARCHITECTURE

Specifies ...

By default, /ARCHITECTURE is assumed.

/BACKUP

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /BACKUP selects files according to the dates of their most recent backups. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /CREATED, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/BEFORE[=time]

Selects only those files dated prior to the specified time. You can specify time as an absolute time, as a combination of absolute and delta times, or as one of the following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED or /MODIFIED.

See the OpenVMS DCL Concepts Manual for complete information on specifying time values.

/BY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC using standard UIC format as described in the OpenVMS DCL Concepts Manual.

/COMMAND=option

Specifies the type of file update command to use in order to bring a target file in synch with its equivalent source file. Note that this qualifier only specifies the action to be used when a source file is present. See the /DELETE qualifier for managing target files which do not have a corresponding source file.
Option Usage
COPY Generate DCL or UTLTOOLS COPY comamnds.
KEPT_VMSINSTAL Generate a VMSINSTAL provide file with the kept flag.
MOVE Generate UTLTOOLS MOVE commands.
NONE Don't generate any file update command. This option is typically used with the /DELETE qualifier to generated a set of DCL DELETE commands to remove target files not present in the source list.
RENAME Generate DCL or UTLTOOLS RENAME commands.
VMSINSTAL Generate a VMSINSTAL profile file.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each differences by name operation to confirm that the operation should be performed on that file. The following responses are valid: 


     YES      NO       QUIT 
     TRUE     FALSE    [Ctrl/Z]
     1        0        ALL 
              [Return]

You 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. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CONVERT=option

Specifies which target file specification convesions to apply if any.
Option Usage
DIRECTORY Convert the target directories into a logical name. The first directory is assumed to be the application code and the second is assumed to be the logical name code. For example [FIN.SFT] would be converted to FIN_SFT_DIR:.
PREFIX Specifies an alternative application code prefix to be used in place of the first directory.

/CREATED

Modifies the time value specified with the /BEFORE or /SINCE qualifier. /CREATED selects files based on their dates of creation. This qualifier is incompatible with the other qualifiers that also allow you to select files according to time attributes: /BACKUP, /EXPIRED and /MODIFIED. If you specify none of these four time qualifiers, the default is /CREATED.

/DELETE

/NODELETE (Default)

Specifies whether DCL DELETE commands are used to remove target files not present in the source list. Anf DCL DELETE commands generated are always placed in the output file after the file update commands specified by the /COMMAND qualifier.

Previous Next Contents Index