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

Format

UTLTOOLS SET FILE filespec[,...]

Parameters

filespec[,...]

Specifies one or more files to be modified. If you specify more than one file, separate the file specifications with commas (,). The asterisk (*) and the percent sign (%) wildcard characters are allowed.

Qualifiers

/ATTRIBUTES=(file-attribute[,...])

Sets the attributes associated with a file. The following table lists possible keywords and the relationship to both ACP-QIO and OpenVMS RMS File attributes:

Keyword	ACP-QIO File Attribute	OpenVMS RMS File Attribute
[NO]BACKUP	FCH$V_NOBACKUP	XAB$X_NOBACKUP
BKS={value}	FAT$B_BKTSIZE={byte}	FAB$B_BKS={byte}
DEQ={value}	FAT$W_DEFEXT={word}	FAB$W_DEQ={word}
EBK={value}	FAT$L_EFBLK={longword}	XAB$L_EBK={longword}
FFB={value}	FAT$W_FFBYTE={word}	XAB$W_FFB={word}
FSZ={value}	FAT$B_VFCSIZE={byte}	FAB$B_FSZ={byte}
GBC={value}	FAT$W_GBC={word}	FAB$W_GBC={word}
HBK={value}	FAT$L_HIBLK={longword}	XAB$L_HBK={longword}
LRL={value}	FAT$W_RSIZE={word}	XAB$W_LRL={word}
MRS={value}	FAT$W_MAXREC={word}	FAB$W_MRS={word}
ORG=IDX	FAT$V_FILEORG=FAT$C_INDEXED	FAB$B_ORG=FAB$C_IDX
ORG=REL	FAT$V_FILEORG=FAT$C_RELATIVE	FAB$B_ORG=FAB$C_REL
ORG=SEQ	FAT$V_FILEORG=FAT$C_SEQUENTIAL	FAB$B_ORG=FAB$C_SEQ
RAT=BLK	FAT$B_RATTRIB=FAT$M_NOSPAN	FAB$B_RAT=FAB$M_BLK
RAT=CR	FAT$B_RATTRIB=FAT$M_IMPLIEDCC	FAB$B_RAT=FAB$M_CR
RAT=FTN	FAT$B_RATTRIB=FAT$M_FORTRANCC	FAB$B_RAT=FAB$M_FTN
RAT=MSB	FAT$B_RATTRIB=FAT$M_MSBVAR	FAB$B_RAT=FAB$M_MSB
RAT=NONE	FAT$B_RATTRIB=0	FAB$B_RAT=0
RAT=PRN	FAT$B_RATTRIB=FAT$M_PRINTCC	FAB$B_RAT=FAB$M_PRN
RFM=FIX	FAT$V_RTYPE=FAT$C_FIXED	FAB$B_RFM=FAB$C_FIX
RFM=STM	FAT$V_RTYPE=FAT$C_STREAM	FAB$B_RFM=FAB$C_STM
RFM=STMCR	FAT$V_RTYPE=FAT$C_STREAMCR	FAB$B_RFM=FAB$C_STMCR
RFM=STMLF	FAT$V_RTYPE=FAT$C_STREAMLF	FAB$B_RFM=FAB$C_STMLF
RFM=UDF	FAT$V_RTYPE=FAT$C_UNDEFINED	FAB$B_RFM=FAB$C_UDF
RFM=VAR	FAT$V_RTYPE=FAT$C_VARIABLE	FAB$B_RFM=FAB$C_VAR
RFM=VFC	FAT$V_RTYPE=FAT$C_VFC	FAB$B_RFM=FAB$C_VFC
VRS={value}	FAT$W_VERSIONS={word}	XAB$W_VERLIMIT={word}

/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 modify 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 modify 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 modified.

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

/RETAIN=(item[,...])

/NORETAIN (Default)

Specifies whether certain file attributes are retained during the UTLTOOLS modify operation.

Valid items include:

Item	Usage
RDT	Revision date time

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

/TRUNCATE

Truncates the file at the end of the block containing the end-of-file (EOF) marker, that is, the qualifier releases allocated but unused blocks of the file.

By default, the modification date and time are reset. Specify /RETAIN=RDT to keep the modification date and time.

/UNTOUCH

/NOUNTOUCH (Default)

Specifies whether the modification date and time of the file are set back to the creation date and time.

By default, the modification date and time are not reset.

Examples

$UTLTOOLSSET FILE FIN_BCK_DIR:*.BCK/ATTRIBUTES=NOBACKUP
      

Lists the current context.

Format

UTLTOOLS SHOW CONTEXT

Qualifiers

/BRIEF

Specifies that the output listing is to include only the minimal context details.

/FULL

Specifies that the output listing is to include all context details.

/OUTPUT[=output-file-spec]

/NOOUTPUT

Specifies the output file specification for the command.

By default, /OUTPUT=SYS$OUTPUT is assumed. The /NOOUTPUT qualifier means that no output will be produced by the command.

/SUBCONTEXT

Specifies that the output listing is to include the subcontext details.

Examples

$ UTLTOOLS SHOW CONTEXT/FULL
 
  Your current context is: 
    Application DIST in DEV environment 
     + Application FIN in DEV environment 
    Scope is COMMON 
    Build default qualifiers are: /BATCH/COMBINED/MACHINE 
    Build memory qualifiers are: /FETCH
      

Lists the current subcontext.

Format

UTLTOOLS SHOW SUBCONTEXT

Qualifiers

/CONTEXT=(keyword=value,,,)

Specifies the context in which the command should execute.

By default the current context is assumed.

See the UTLTOOLS FETCH SUBCONTEXT command for more details about the keywords and their values.

/OUTPUT[=output-file-spec]

/NOOUTPUT

Specifies the output file specification for the command.

By default, /OUTPUT=SYS$OUTPUT is assumed. The /NOOUTPUT qualifier means that no output will be produced by the command.

/SUBCONTEXT=(keyword=value,,,)

Specifies the various alternative directories which may be checked for files to be ???.

By default the directories are those associated with the application.

Specifies the subcontext in which the command or commands within a subcontext block should execute.

See the UTLTOOLS FETCH SUBCONTEXT command for more details about the keywords and their values.

By default the directories are those associated with the application.

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

Specifies how templates are to be handled. Choose any combination of the following keywords:

ALL	Use templates for all directories.
PARSE	Parse any directories which used a template.
MISSING	Use templates for directories for which there is no current definition.

Examples

$ UTLTOOLS SHOW SUBCONTEXT
 
  Your current subcontext is: 
 
    Default is DISK_DEV4:[FIN.WRK.JOBES] 
    Architecture is ALPHA 
    Multi-architecture directory suffix is -ALPHA 
 
    Directories                       Code   Value 
    -----------                       ----   ----- 
    Architecture Independent Library  AIL    FIN_AIL_DIR: 
    Backup                            BCK 
    CDD/Repository                    CDD    FIN_CDD_DIR: 
    Data                              DAT    FIN_DAT_DIR: 
    Documentation                     DOC    FIN_DOC_DIR: 
    Generated Source                  GEN    FIN_GEN_DIR: 
    Journal                           JNL    FIN_JNL_DIR: 
    Kit                               KIT    FIN_KIT_DIR: 
    Library                           LIB    FIN_LIB_DIR: 
    Local Customisation               LCL    FIN_LCL_DIR: 
    Rdb After Image Journal           AIJ    FIN_JNL_DIR: 
    Rdb After Image Journal Backup    AIB    FIN_JNL_DIR: 
    Rdb Area Files                    RDA    FIN_DAT_DIR: 
    Rdb Recovery Unit Journals        RUJ    FIN_SCR_DIR: 
    Rdb Root File                     RDB    FIN_DAT_DIR: 
    Rdb Snapshot Files                SNP    FIN_DAT_DIR: 
    Runtime                           RUN    FIN_RUN_DIR: 
    Scratch                           SCR    FIN_SCR_DIR: 
    Software                          SFT    FIN_SFT_DIR: 
    Source                            SRC    FIN_SRC_DIR: 
    Work                              WRK    FIN_WRK_DIR: 
    Testing                           TST    FIN_TST_DIR: 
    Third Party Software              TPS 
 
    List                              AIL,CDD,DAT,DOC,GEN,JNL,KIT,LCL,LIB,RUN,SCR,SFT,SRC,TST,WRK 
 
    Libraries                         Value 
    ---------                         ----- 
    Help                              FIN_DOC_DIR:FINHLP.HLB 
    Image                             FIN_SFT_DIR:FINIMG.OLB 
    Macro                             FIN_SFT_DIR:FINMAC.MLB 
    MMS                               FIN_LIB_DIR:FINMMS.TLB 
    Object                            FIN_LIB_DIR:FINOBJ.OLB 
    Symbol                            FIN_SFT_DIR:FINSYM.OLB 
    Text                              FIN_LIB_DIR:FINTXT.TLB 
 
    Files                             Value 
    -----                             ----- 
    Message Help                      FIN_MSGHLP_LIB 
 
    Classes & Identifiers             Class        Identifier 
    ---------------------             -----        ---------- 
    Manager                           MGR          A_FIN_DEV_MGR 
    Owner                                          R_FIN_DEV 
    Report                            REP          A_FIN_DEV_REP 
    User                              USR          A_FIN_DEV_USR 
 
    List                              MGR,REP,USR 
 
    Templates                         Value 
    ---------                         ----- 
    Access Identifier Names           A_FIN_DEV_#C 
    CDD Logical Names                 FIN_#D 
    Directories                       DISK_DEV:[FIN.#D] 
    Directory Device                  DISK_DEV: 
    Directory Logical Names           FIN_#D_DIR 
    File Logical Names                FIN_#D_FILE 
    Generated Files                   FIN_GEN_* 
    Testing Files                     FIN_TST_* 
 
    Flags                             Value 
    -----                             ----- 
    Explicit Linking                  NO 
    Tracing                           None
      

Display the UTLTOOLS utility version.

Format

UTLTOOLS SHOW VERSION

Examples

$ UTLTOOLS SHOW VERSION
  SysWorks Version V3.4
      

Creates a subprocess of the current process. The context of the subprocess is copied from the current process. You can use the SPAWN command to leave the UTLTOOLS utility temporarily, perform other functions (such as displaying a directory listing or printing a file), and then return to UTLTOOLS.

Note that this command is only available for users with DCL access.

Format

UTLTOOLS SPAWN [command]

Parameters

command

Specifies the DCL command string that executes in the context of the created subprocess. When the command completes, the subprocess terminates and control is returned to the parent process. If this parameter is not specified, a subprocess is created that transfers control to DCL command level.

Qualifiers

/INPUT=file-spec

Specifies an input file containing one or more DCL command strings to be executed by the spawned subprocess. If you specify a command string along with an input file, the command string is processed before the commands in the input file. Once processing is complete, the subprocess is terminated.

/LOGICAL_NAMES

/NOLOGICAL_NAMES

Specifies that the logical names of the parent process are to be copied to the subprocess. When you do not want the subprocess to use the logical names of the parent process, enter the qualifier /NOLOGICAL_NAMES. The default is /LOGICAL_NAMES.

/OUTPUT=file-spec

Identifies the output file to which the results of the SPAWN operation are written. Whenever you use the /NOWAIT qualifier, you should also use the /OUTPUT qualifier to specify a new output destination. Doing so prevents output from being displayed while you are specifying new commands. If you omit the /OUTPUT qualifier, output is written by default to the current SYS$OUTPUT device.

/PROCESS=subprocess-name

Specifies the name of the subprocess to be created. The default name of the subprocess is USERNAME_n. If the subprocess name contains spaces or special characters, or is case-sensitive, then the subprocess name must be enclosed in quotation marks.

/SYMBOLS

/NOSYMBOLS

Determines whether the system passes DCL global and local symbols to the subprocess. The default is /SYMBOLS.

/WAIT/NOWAIT

Controls whether the system waits until the subprocess is completed before allowing more commands to be specified. The /NOWAIT qualifier allows you to specify new commands while the specified subprocess is running. If you specify /NOWAIT, you should also use the /OUTPUT qualifier to direct the output stream to a file, rather than displaying it on your terminal. Doing so prevents your terminal from being used by more than one process simultaneously.

Examples

UTLTOOLS> SPAWN SHOW TIME
      

This example shows how to create a subprocess that executes the DCL command SHOW TIME while you are using UTLTOOLS utility.

UTLTOOLS> SPAWN /NOLOGICAL_NAMES SET HOST
_Node: MARS 
   .
   .
   .
$ LOGOUT
CRAMMER logged out at ... 
 
%REM-S-END, control returned to node _BETA:: 
 
UTLTOOLS>
      

This example shows how to use the SPAWN command to create a subprocess in which you SET HOST to another node. When you want to leave node MARS and move back to node BETA, enter the DCL command LOGOUT. The /NOLOGICAL_NAMES qualifier prevents the logical names of the parent process from being copied to the subprocess.