HP OpenVMS DCL Dictionary

SET FILE

Modifies the characteristics of one or more files.
See the qualifier descriptions for restrictions.

Format

SET FILE filespec[,...]

Parameter

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.

Description

The SET FILE command modifies a number of file characteristics.

Qualifiers

/ATTRIBUTE=(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²

ATTDATE=date FAT$C_ATTDATE XAB$Q_ATT

ACCDATE=date FAT$C_ACCDATE XAB$Q_ACC

BAKDATE=date FAT$C_BAKDATE XAB$Q_BDT

BKS:value FAT$B_BKTSIZE=byte FAB$B_BKS=byte

CREDATE=date FAT$C_CREDATE XAB$Q_CDT

DEQ:value FAT$W_DEFEXT=word FAB$W_DEQ=word

EBK:value FAT$L_EFBLK=longword XAB$L_EBK=longword

EXPDATE=date FAT$C_EXPDATE XAB$Q_EDT

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

MODDATE=date FAT$C_MODDATE XAB$Q_MOD

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

REVDATE=date FAT$C_REVDATE XAB$Q_RDT

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

Keyword	ACP-QIO File Attribute¹	OpenVMS RMS File Attribute²
ATTDATE=date	FAT$C_ATTDATE	XAB$Q_ATT
ACCDATE=date	FAT$C_ACCDATE	XAB$Q_ACC
BAKDATE=date	FAT$C_BAKDATE	XAB$Q_BDT
BKS:value	FAT$B_BKTSIZE=byte	FAB$B_BKS=byte
CREDATE=date	FAT$C_CREDATE	XAB$Q_CDT
DEQ:value	FAT$W_DEFEXT=word	FAB$W_DEQ=word
EBK:value	FAT$L_EFBLK=longword	XAB$L_EBK=longword
EXPDATE=date	FAT$C_EXPDATE	XAB$Q_EDT
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
MODDATE=date	FAT$C_MODDATE	XAB$Q_MOD
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
REVDATE=date	FAT$C_REVDATE	XAB$Q_RDT
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

¹For further information, see the HP OpenVMS I/O User's Reference Manual.
²For further information, see the OpenVMS Record Management Services Reference Manual.

/BACKUP

/NOBACKUP

Specifies that the Backup utility (BACKUP) records the contents of the file. The /NOBACKUP qualifier causes BACKUP to record the attributes of the file but not its contents. This qualifier is valid only for Files-11 Structure On-Disk Level 2 and 5 files.

The /NOBACKUP qualifier is useful for saving files that contain unimportant data, such as SWAPFILES.

/BEFORE[=time]

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

For complete information on specifying time values, see the OpenVMS User's Manual or the online help topic Date.

/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 by using standard UIC format as described in the HP OpenVMS Guide to System Security.

/CACHING_ATTRIBUTE=keyword

Use this qualifier to control which files are cached by the Extended File Cache. It sets the caching attribute for a file or directory in a Files-11 ODS-2 or ODS-5 volume.

The caching attribute of a file is the default caching option that is used by the Extended File Cache when an application accesses the file without specifying which caching option it wants to use.

The keyword can be either WRITETHROUGH or NO_CACHING. Use WRITETHROUGH for files that you want to be cached. Use NO_CACHING for files that you don't want to be cached.

The Extended File Cache does not cache directories. The caching attribute of a directory controls only how the caching attribute is inherited by new files and subdirectories created in the directory:

When you create a new directory or file, it inherits its caching attribute from its parent directory.
When you create a new version of an existing file, the new file inherits its caching attribute from the highest version of the existing file.

When you use the INITIALIZE command to create a new Files-11 volume, the caching attribute of its root directory (000000.DIR;1) is set to write-through. This means that by default, all the files and directories you create in the volume will inherit a caching attribute of write-through unless you use SET FILE /CACHING_ATTRIBUTE.

When you change the caching attribute of a directory, it does not affect the caching attribute of any existing files and subdirectories in the directory.

When you change the caching attribute of a file, it does not affect the type of caching being used by any applications that are currently accessing the file.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each SET FILE 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 Return. 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 (default)

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /MODIFIED qualifier, which also allows you to select files according to time attributes. The /CREATED qualifier is the default qualifier.

/DATA_CHECK[=([NO]READ,[NO]WRITE)]

Specifies whether a read data check (rereading each record), a write data check (reading each record after it is written), or a combination of the two is performed on the file during transfers. By default, a write data check is performed.

/END_OF_FILE

Resets the end-of-file (EOF) mark to the highest block allocated.

/ENTER=new-filespec

The new-filespec parameter is used to create either an alias or a hard link for the file specified in the SET FILE command. For detailed information about using hard links and aliases, see the HP OpenVMS System Manager's Manual.

Normally you would use /ENTER to create an alias or a hard link in a directory different from the one where the original filename resides. If the names are not in different directories, you or another user could subsequently lose data during a delete or purge operation. The DELETE and PURGE commands and the file version limit feature can behave unpredictably if the original name and the new name are in the same directory.

To remove an alias or hard link, use the SET FILE /REMOVE command. Exercise caution when using the DELETE and SET FILE /REMOVE commands, or you could end up with either an inaccessible file that has no name or a name that does not refer to a file. Follow these guidelines to avoid such problems:

Use SET FILE /REMOVE to remove an alias; do not use the DELETE command to remove an alias.
Do not use SET FILE /REMOVE to remove the original file name.

If you do not follow these guidelines and encounter problems, use ANALYZE /DISK /REPAIR to move inaccessible files to the SYSLOST directory and remove names that no longer refer to files.

/ERASE_ON_DELETE

Specifies that the specified files are erased from the disk (not just written over) when the DELETE or PURGE command is issued for the files. See the DELETE/ERASE command for more information.

/EXCLUDE=(filespec[,...])

Excludes the specified file from the SET FILE operation. You can include a directory name but not a device name in the file specifications. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.

/EXPIRATION_DATE=date

/NOEXPIRATION_DATE

Requires read (R), write (W), and control access. Being the owner of the file is one way to get control access.

Controls whether an expiration date is assigned to the specified files.

Specify the date according to the rules described in the OpenVMS User's Manual or the online help topic Date. Absolute date keywords are allowed. If you specify zero as the date, today's date is used.

/EXTENSION[=n]

Sets the extend quantity default for the file. The value of the parameter n can range from 0 to 65,535. If you omit the value specification or specify a value of 0, OpenVMS Record Management Services (OpenVMS RMS) calculates its own value for the /EXTENSION qualifier.

See the SET RMS_DEFAULT command for a description of the /EXTEND_QUANTITY qualifier.

/GLOBAL_BUFFER[=keyword[=n]]

/NOGLOBAL_BUFFER

For OpenVMS versions prior to Version 8.3, sets the OpenVMS Record Management Services (OpenVMS RMS) global buffer count (the number of buffers that can be shared by processes accessing the file) for the specified files. The value n must be an integer in the range from 0 to 32,767. A value of 0 disables buffer sharing.

The /SHARE qualifier can be used to enable or disable global buffers on a file currently being accessed; however, any new global buffer settings will only be applied to new accessors of the file. If a file is already open with global buffers, any new number of global buffers will not take effect until the file is closed by all accessors of the file.

For OpenVMS V8.3 and later, sets the OpenVMS RMS global buffer count for the specified files. Note, you can specify only one type of global buffer qualifier in the same command string.

The keyword can be:

COUNT=n---The value n sets the longword count of the number of global buffers.
PERCENT=p---The value p expresses the size of the global cache as a percent of the total number of used blocks currently used in the file.
DEFAULT---Requests RMS at runtime to recalculate the global cache size based on an algorithm that makes use of two global buffer SYSGEN parameters, GB_CACHEALLMAX and GB_DEFPERCENT.

The following qualifiers can also be used with the /SHARE qualifier:

/GLOBAL_BUFFER=n
/GLOBAL_BUFFER=COUNT=n
/GLOBAL_BUFFER=PERCENT=n
/GLOBAL_BUFFER=DEFAULT
/NOGLOBAL_BUFFER
/[NO]STATISTICS

/LOG

/NOLOG (default)

Displays the file specification of each file modified as the command executes.

/MODIFIED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /CREATED qualifier, which also allows you to select files according to time attributes. If you do not specify the /MODIFIED qualifier, the default is the /CREATED qualifier.

/MOVE

/NOMOVE

Controls whether movefile operations are enabled on the specified file.

When you create a file, movefile operations are enabled on that file. You should disable movefile operations on specialized files that are accessed other than through the XQP (such as files accessed through logical I/O to a disk).

Note that movefile operations are automatically disabled on critical system files. Do not enable movefile operations on these files.

/NODIRECTORY

Use with extreme caution. Requires SYSPRV (system privilege).

Removes the directory attributes of a file and allows you to delete the corrupted directory file even if other files are contained in the directory. When you delete a corrupted directory file, the files contained within it are lost.

Use ANALYZE/DISK_STRUCTURE/REPAIR to place the lost files in [SYSLOST]. You can then copy the lost files to a new directory. This qualifier is valid only for Files-11 On-Disk Structure Level 2 files. For more information about the Verify utility, see the HP OpenVMS System Management Utilities Reference Manual.

/OWNER_UIC[=uic]

This qualifier has been superseded by the SET SECURITY/OWNER command.

/PROTECTION[=(ownership[:access][,...])]

This command has been superseded by the SET SECURITY/PROTECTION command.

/REMOVE

Use with caution.

Enables you to remove one of the names of a file that has more than one name, without deleting the file. If you have created an additional name for a file with the /ENTER qualifier of SET FILE, you can use the /REMOVE qualifier to remove either the original name or the alias. The file still exists and can be accessed by whatever name or names remain in effect.

However, if you accidentally remove the name of a file that has only one name, you cannot access that file with most DCL commands; use the ANALYZE/DISK_STRUCTURE utility to retrieve the file.

/SEMANTICS=semantics-tag

/NOSEMANTICS

Use the /SEMANTICS qualifier to create or change a semantics tag. Use the /NOSEMANTICS qualifier to remove a semantics tag from a file. For more information, see the Guide to OpenVMS File Applications.

/SHARE

Allows you to enable or disable global buffers or statistics on a file currently being accessed by other users.

Requires SYSPRV privilege.

Only new accessors of the file acquire the new settings. For example, if a file is opened with no global buffers specified and the SET FILE/GLOBAL=n/SHARE command is issued, only new accessors of the file will use global buffers. If /STATISTICS is enabled on an active file, only operations performed by new accessors of the file are measured.

If a file is already open with global buffers, any new number of global buffers will not take effect until the file is closed by all accessors of the file.

The /SHARE qualifier is valid only with the following qualifiers:

/[NO]GLOBAL_BUFFER=n
/[NO]STATISTICS

/SHELVABLE

/NOSHELVABLE

Controls whether the file is shelvable.

/SINCE[=time]

Selects only those files dated on or after the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, JOB_LOGIN, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify the /CREATED or the /MODIFIED qualifier to indicate the time attribute to be used as the basis for selection. The /CREATED qualifier is the default.

For complete information on specifying time values, see the OpenVMS User's Manual or the online help topic Date.

/STATISTICS

/NOSTATISTICS (default)

Enables the gathering of RMS statistics on the specified file. These statistics can then be viewed by using the Monitor utility, which is invoked with the DCL command MONITOR. The SET FILE/STATISTICS command applies an application ACE to the specified file. The ACE does not affect access control and is only meaningful to the application assigning it.

The /SHARE qualifier can be used to enable or disable statistics on a file currently being accessed. However, only statistics of new accessors of the file will be measured.

/STYLE=keyword

Specifies the file name format for display purposes.

The valid keywords for this qualifier are CONDENSED and EXPANDED. Descriptions are as follows:

Keyword Explanation

CONDENSED (default) Displays the file name representation of what is generated to fit into a 255-length character string. This file name may contain a DID or FID abbreviation in the file specification.

EXPANDED Displays the file name representation of what is stored on disk. This file name does not contain any DID or FID abbreviations.

Keyword	Explanation
CONDENSED (default)	Displays the file name representation of what is generated to fit into a 255-length character string. This file name may contain a DID or FID abbreviation in the file specification.
EXPANDED	Displays the file name representation of what is stored on disk. This file name does not contain any DID or FID abbreviations.

The keywords CONDENSED and EXPANDED are mutually exclusive. This qualifier specifies which file name format is displayed in the output message, along with the confirmation if requested.

File errors are displayed with the CONDENSED file specification unless the EXPANDED keyword is specified.

See the OpenVMS User's Manual for more information.

/SYMLINK

/NOSYMLINK (default)

If an input file is a symbolic link, the file referred to by the symbolic link is the file that is set.

The /SYMLINK qualifier indicates that the symbolic link itself is set.

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

/UNLOCK

Clears a file marked as deaccess locked. Deaccess locking is required by and used by those few applications that maintain their own locking and consistency, typically without the use of the OpenVMS distributed lock manager, and potentially also without the use of RMS. When an application using deaccess locking does not correctly deaccess the file (often due to an application or system failure), the file is marked as locked, and is thus inaccessable until the integrity of the contents of the file are verified and the SET FILE/UNLOCK command is used.

This command does not affect the state of files that are locked using RMS or the distributed lock manager.

For details on file deaccess locking, see the HP OpenVMS I/O User's Reference Manual, the ACP-QIO interface documentation, and specifically the FIB$V_DLOCK option available on the IO$_CREATE and IO$_ACCESS functions.

The SET FILE/UNLOCK command can clear the cause of the following error message:

%SYSTEM-W-FILELOCKED, file is deaccess locked

However, this command cannot resolve the cause of the error message:

%RMS-W-FLK, file currently locked by another user

/VERSION_LIMIT[=n]

Specifies the maximum number of versions for the specified file. If you do not specify a version limit, a value of 0 is used, indicating that the number of versions of a file is limited only to the Files-11 architectural limit of 32,767. When you exceed that limit, the earliest version of the file is deleted from the directory without notification to the user. For example, if you set the version limit to three when there are already five versions of that file in your directory, there will continue to be five versions of the file unless you specifically delete some or purge the directory. Once the number of versions is equal to or less than the current version limit, the version limit is maintained.

Examples

#1
$ SET FILE/EXPIRATION_DATE=19-DEC-2001:11:00 BATCH.COM;3

The SET FILE command requests that the expiration date of the file BATCH.COM;3 be set to 11:00 A.M., December 19, 2001.

#2
$ SET FILE/BEFORE=31-DEC/ERASE_ON_DELETE PERSONNEL*.SAL

This SET FILE command calls for all files that match the file specification PERSONNEL*.SAL and are dated before December 31 of the current year to have their disk locations erased whenever one of them is deleted with commands such as DELETE or PURGE.

#3
$ SET FILE/OWNER_UIC=[360,020]/VERSION_LIMIT=100 MYFILE.DAT

The SET FILE command modifies the characteristics of the file MYFILE.DAT, changing the owner user identification code (*). You must have system privilege (SYSPRV) to change the owner UIC.

#4
$ SET FILE/NOMOVE TEST.FDL $DIRECTORY/FULL TEST.FDL Directory SYS$SYSDEVICE:[BERGMANN] TEST.FDL;1 File ID: (10,8,0) . . . File attributes: Allocation: s, Extend: 0, Global buffer count: 0 No version limit, MoveFile disabled . . .

$ SET FILE/NOMOVE TEST.FDL
$DIRECTORY/FULL TEST.FDL
Directory SYS$SYSDEVICE:[BERGMANN]
TEST.FDL;1   File ID:  (10,8,0) 
   .
   .
   .
File attributes: Allocation: s, Extend: 0, Global buffer count: 0
   No version limit, MoveFile disabled
   .
   .
   .

Movefile operations are disabled on the file TEST.FDL. A DIRECTORY/FULL command on the file TEST.FDL affirms that the file attribute Movefile is disabled.

#5
$ SET FILE/ATTRIBUTES=ORG:SEQ - _$ TEST$:[DATA]SET_ATTRIBUTES.DATA_FILE/LOG %SET-I-MODIFIED, TEST$:[DATA]SET_ATTRIBUTES.DATA_FILE;1 MODIFIED

The command, SET FILE/ATTRIBUTES, changes the file organization of the specified file.

#6
$ SET FILE/PROTECTION=(S:RWE,O=RWE,G:RE,W:RE) TEMP.DIR $ DIRECTORY/PROTECTION TEMP.DIR Directory DKB0:[FULGHUM] TEMP.DIR;1 (RWE,RWE,RE,RE)

This example sets the protection on the TEMP.DIR file with the SET FILE command and then displays the protection of the file with the DIRECTORY command.

#7
$ SET FILE/SHARE/GLOBAL_BUFFER=5000/STATISTICS INVENTORY.IDX

This example sets 5000 global buffers on the INVENTORY.IDX file and enables statistics. If the file is open and the SET FILE command is issued without the /SHARE qualifier, the following error is returned: SYSTEM-W-ACCONFLICT (file access conflict). The /SHARE qualifier allows the global buffers and statistics to be enabled on an open file; however, these settings only apply to new accessors of the file.

#8
$ SET FILE/GLOBAL_BUFFER=100 NEWFILE.DAT $ SET FILE/GLOBAL_BUFFER=COUNT=100000 NEWFILE.DAT

In a clustered environment with mixed OpenVMS versions, the same file can be opened on different nodes with different global buffer counts. For nodes prior to Version 8.3, use the old compatibility setting, and for Version 8.3 nodes and later use the new values.

Contents

Index