Modifies the characteristics of one or more files.
See the qualifier descriptions for restrictions.
For help about the RMS Journaling SET FILE commands, read the
following subtopics:
o /AI_JOURNAL - Marks one or more RMS files for after-image
journaling.
o /BI_JOURNAL - Marks one or more RMS files for before-image
journaling.
o /RU_ACTIVE - Designates the recoverable facility that controls
active recovery units for the file.
o /RU_FACILITY - Allows you to identify the recoverable facility
that controls active recovery units on the file.
o /RU_JOURNAL - Marks an RMS file for recovery unit journaling.
Format
SET FILE filespec[,...]
1 – 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.
2 – Qualifiers
2.1 /ATTRIBUTE
/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:
OpenVMS RMS File
Keyword ACP-QIO File Attribute Attribute
ATTDATE=dateFAT$C_ATTDATE XAB$Q_ATT
ACCDATE=dateFAT$C_ACCDATE XAB$Q_ACC
BAKDATE=dateFAT$C_BAKDATE XAB$Q_BDT
BKS:value FAT$B_BKTSIZE=byte FAB$B_BKS=byte
CREDATE=dateFAT$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=dateFAT$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=dateFAT$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=dateFAT$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
2.2 /BACKUP
/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.
2.3 /BEFORE
/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.
2.4 /BY_OWNER
/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
VSI OpenVMS Guide to System Security.
2.5 /CACHING_ATTRIBUTE
/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:
o When you create a new directory or file, it inherits its
caching attribute from its parent directory.
o 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.
2.6 /CONFIRM
/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.
2.7 /CREATED
/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.
2.8 /DATA_CHECK
/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.
2.9 /END_OF_FILE
Resets the end-of-file (EOF) mark to the highest block allocated.
2.10 /ENTER
/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
VSI 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:
o Use SET FILE /REMOVE to remove an alias; do not use the DELETE
command to remove an alias.
o 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.
2.11 /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.
2.12 /EXCLUDE
/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.
2.13 /EXPIRATION_DATE
/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.
2.14 /EXTENSION
/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.
2.15 /GLOBAL_BUFFER
/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:
o COUNT=n-The value n sets the longword count of the number of
global buffers.
o 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.
o 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:
o /GLOBAL_BUFFER=n
o /GLOBAL_BUFFER=COUNT=n
o /GLOBAL_BUFFER=PERCENT=n
o /GLOBAL_BUFFER=DEFAULT
o /NOGLOBAL_BUFFER
o /[NO]STATISTICS
2.16 /LOG
/LOG
/NOLOG (default)
Displays the file specification of each file modified as the
command executes.
2.17 /MODIFIED
/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.
2.18 /MOVE
/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.
2.19 /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
VSI OpenVMS System Management Utilities Reference Manual.
2.20 /OWNER_UIC
/OWNER_UIC[=uic]
This qualifier has been superseded by the SET SECURITY/OWNER
command.
2.21 /PROTECTION
/PROTECTION[=(ownership[:access][,...])]
This command has been superseded by the SET SECURITY/PROTECTION
command.
2.22 /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.
2.23 /SEMANTICS
/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.
2.24 /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:
o /[NO]GLOBAL_BUFFER=n
o /[NO]STATISTICS
2.25 /SHELVABLE
/SHELVABLE
/NOSHELVABLE
Controls whether the file is shelvable.
2.26 /SINCE
/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.
2.27 /STATISTICS
/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.
2.28 /STYLE
/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 Displays the file name representation of what is
(default) 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.
2.29 /SYMLINK
/SYMLINK=keyword
/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.
The valid keywords for this qualifier are [NO]WILDCARD,
[NO]ELLIPSIS, and [NO]TARGET. Descriptions are as follows:
Keyword Explanation
NOWILDCARD Indicates that symlinks are disabled during directory
wildcard searches.
WILDCARD Indicates that symlinks are enabled during wildcard
searches.
NOELLIPSIS Indicates that symlinks are matched for all wildcard
fields except for ellipsis.
ELLIPSIS Equivalent to WILDCARD (included for command
symmetry).
TARGET Indicates that if the target file of the file
specification is a symlink, then the target file
is followed.
NOTARGET Indicates that the command operates on the target
file even if it is a symlink.
If the file named in the SET FILE command is a symlink, the
command by default operates on the symlink target.
2.30 /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.
2.31 /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 inaccessible 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 VSI 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
2.32 /VERSION_LIMIT
/VERSION_LIMIT[=n]
Sets the maximum number of versions that a specified file can
have in a directory. If you do not set a version limit, a value
of 0 is used, indicating that the number of file versions is
limited only to the Files-11 architectural limit of 32,767.
When creating a file, if the total number of versions of that
file name exceeds the specified version limit, then the file
with the lowest version number is deleted from the directory
without notification to the user.
If you set the version limit to 3 when there are already five
versions of that file in a directory, there will continue to be
five versions of that file unless you specifically delete some
or purge the directory. Once the number of file versions is
equal to or less than the current version limit, this version
limit is maintained.
The version limit applies to all existing versions of a
specified file in a directory regardless of whether or not
you specified any version in the command.
To view the version limit on a file, use the DIRECTORY/FULL
command on a file name and look at the File Attributes field
of the output or use the F$FILE_ATTRIBUTES(filename,"VERLIMIT")
lexical function.
3 – 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
.
.
.
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.
9.$ DIRECTORY NEWFILE.TXT
Directory WORK:[DOCUMENTS]
NEWFILE.TXT;3 NEWFILE.TXT;2 NEWFILE.TXT;1
Total of 3 files.
$ SET FILE/VERSION_LIMIT=10/LOG NEWFILE.TXT;
%SET-I-MODIFIED, WORK:[DOCUMENTS]NEWFILE.TXT;3 modified
This example sets the version limit of 10 on all three
existing versions of NEWFILE.TXT. Note that in this case,
the /LOG qualifier shows only the highest version file
specification as modified though the version limit has
been applied to all file versions.
4 /AI_JOURNAL
Requires read (R), write (W), and control access. Being the owner
of the file is one way to get control access.
Marks one or more RMS files for after-image journaling. You can
also specify certain characteristics of the journal with this
command, including its file specification, whether it is to be
created, its initial size, and its default extension quantity.
The SET FILE/NOAI_JOURNAL command unmarks a file for after-image
journaling.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/[NO]AI_JOURNAL=(FILE=journal-filespec[,...])
data-filespec[,...]
4.1 – Parameter
data-filespec[,...]
Identifies the file to be marked for after-image journaling. If
you specify more than one file, separate the file specifications
with commas. The asterisk (*) and the percent sign (%) wildcard
characters are allowed. The file specification cannot include a
node name, since the SET FILE command is not valid for network
access.
4.2 – Description
The SET FILE/AI_JOURNAL command marks one or more RMS files
for after-image journaling. You can also specify certain
characteristics of the journal with this command, including its
file specification, whether it is to be created, its initial
size, and its default extension quantity. The SET FILE/NOAI_
JOURNAL command unmarks a file for after-image journaling. After
a data file is marked for after-image journaling with the SET
FILE/AI_JOURNAL command, the following events occur whenever the
file is opened by RMS for write operations:
o The journal is opened.
o All subsequent modifications to the data file are recorded in
the journal.
NOTE
To be able to recover the data file at a later time,
you must make a backup copy of the data file, even if it
contains no data.
You must use the FILE keyword to specify a journal. By default,
any portions of the file specification that you omit will be the
same as the data file that is to be journaled, but with the file
type RMS$JOURNAL. That is, if you issue the following command,
then, by default, the file specification for the after-image
journal is JOURNAL_DISK:PAYROLL.RMS$JOURNAL:
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) FINANCE_DISK:PAYROLL.DAT
You should always keep the journal for after-image applications
on a different volume from that of your data file. If recovery
becomes necessary, you will be able to perform after-image
recovery only if a backup copy of the data file is available.
Use the FILE keyword to specify the journal location.
Use the SET FILE/NOAI_JOURNAL command to unmark a file for after-
image journaling. After you use the SET FILE/NOAI_JOURNAL command
for a file, modifications to that data file will no longer be
written to the journal.
You must use the SET FILE/NOAI_JOURNAL command before you can
delete a file that has been marked for after-image journaling.
4.3 – Keywords
Four keywords are used as parameters to the SET FILE/AI_JOURNAL
command: ALLOCATION, [NO]CREATE, EXTENSION, and FILE. You must
always use the FILE keyword; you can also use any, all, or none
of the other three keywords.
Use an equal sign (=) immediately after the SET FILE/AI_JOURNAL
command to use a keyword. If you use more than one of the
keywords, enclose the list in parentheses and separate the items
in the list with commas.
ALLOCATION=n
Specifies the initial size, in blocks, of the journal. The
ALLOCATION keyword is meaningful only when the CREATE keyword
is also used.
The default allocation is 0 blocks.
CREATE
Specifies that a new journal is to be created. If no journal
exists, using this keyword creates a new one. If a journal (with
the file specification given in this command) already exists,
using this keyword creates a new version of the journal. In the
latter instance, the data file named in this SET FILE command
is journaled to the new journal. Any other files that are being
journaled to the previous version of the journal will continue to
be journaled to that previous version.
If a journal does not already exist, be sure to use the CREATE
keyword with the SET FILE/AI_JOURNAL command. If you do not
specify the CREATE keyword and the file that you specify with
the FILE keyword does not exist, a journal will not automatically
be created and an error message is displayed.
When you create a journal for after-image journaling, the file
protection for the journal is determined as follows:
o If a version of the journal that you specify with the CREATE
keyword already exists, then the new version of the journal
has the same file protection and access control list (ACL) as
the most recent version.
o If there is no existing journal (that is, if you are creating
version 1 of the journal), then the file protection and
ACL of the journal are the default file protection for the
process that creates the journal, except that none of the four
ownership categories (system, owner, group, world) is given
delete access.
Also, every time that you use the CREATE keyword, be sure to make
a backup copy of the data file. (If it is the first time that
the data file is marked for after-image journaling, then you must
make a backup copy of the data file, regardless of whether the
CREATE keyword is used.)
NOTE
To be able to recover the data file at a later time, you
must mark the file for journaling, and then make a backup
copy of the data file, even if it contains no data.
In most cases (in particular, when you are using after-image
journaling to protect against loss of data from a device
failure), you should keep the backup copy on a different volume
from the data file. If recovery becomes necessary, you will be
able to perform after-image recovery only if a backup copy of the
data file is available.
If you want to use a single journal for both after-image and
before-image journaling, do not use the CREATE keyword with both
the /AI_JOURNAL and /BI_JOURNAL qualifiers, because that will
create two separate journals. When you create a journal that
will be used for more than one data file or more than one type
of journaling (after-image or before-image), you should first
use a SET FILE command to create the journal for a single type
of journaling and for a single data file. After the journal is
created, then you can use a single SET FILE command for multiple
data files and both after-image and before-image journaling. For
example, you might use the following sequence of commands:
$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:,CREATE) [WEEKLY]SALES.DAT
$ SET FILE/BI_JOURNAL=(FILE=JNL_DISK:[WEEKLY]SALES) -
_$INVOICES.DAT,COMMISSIONS.DAT
EXTENSION=n
Specifies the default extension quantity, in blocks, for the
journal. You can specify a value from 0 to 65,535.
The EXTENSION keyword is meaningful only when you use the CREATE
keyword. If the file is extended, the value that you specify is
used. If you do not use the EXTENSION keyword when you create a
journal, RMS calculates its own EXTENSION value for the journal.
FILE=journal-filespec
Specifies the journal where all modifications to the named data
file will be recorded. The default file specification for the
journal is the file specification of the data file that you name,
but with a file type of RMS$JOURNAL. If you provide a partial
file specification for the journal, any unspecified portions are
taken from the default file specification. The FILE keyword is
required when you use the SET FILE/AI_JOURNAL command.
If you are using after-image journaling to protect against the
loss of data due to a device failure (such as a head crash),
you should keep the journal on a different volume from the
one on which the data file is kept. Only by keeping the data
file and journals on separate volumes can you use after-image
recovery to restore the data file if its recording medium becomes
corrupted (for example, by a disk head crash). If you issue the
SET FILE/AI_JOURNAL command and the journal is on the same volume
as the data file being marked for after-image journaling, the
INVAIJDEV warning message is issued.
The file specification cannot include a node name, since the SET
FILE command is not valid for network access.
You can use a single journal for multiple data files for after-
image journaling, and you can also use a single journal for both
after-image and before-image journaling.
4.4 – Qualifier
4.4.1 /LOG
/LOG
/NOLOG (default)
Controls whether the SET FILE command displays the file
specification and the type of journaling that has been set. By
default, this information is not displayed.
4.5 – EXAMPLES
1.$ SET FILE /AI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE) -
_$FINANCE_DISK:[PAYROLL]WEEKLY.DAT
In this example, the file FINANCE_DISK:[PAYROLL]WEEKLY.DAT is
marked for after-image journaling. The required FILE keyword
is used to place the journal on the disk JOURNAL_DISK, and
the CREATE keyword generates a new version of the journal.
The file specification for the journal will be JOURNAL_
DISK:[PAYROLL]WEEKLY.RMS$JOURNAL.
The next step in the after-image journaling process after
issuing this command is to back up the data file.
2.$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE)/LOG SALES.DAT
%SET-I-JCREATED, journal JOURNAL_DISK:[REGION_1]SALES.RMS$JOURNAL;1
created
%SET-I-FILMARKAI, FINANCE_DISK:[REGION_1]SALES.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JOURNAL_DISK:[REGION_1]SALES.RMS$JOURNAL;1
%SET-I-MODIFIED, FINANCE_DISK:[REGION_1]SALES.DAT;1 modified
In this example, the file SALES.DAT in default directory
FINANCE_DISK:[REGION_1] is marked for after-image journaling
and the /LOG qualifier causes the result of the SET FILE
command to be displayed on the terminal.
3.$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:,CREATE)/LOG OVERDUE.DAT
%SET-I-JCREATED, journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
created
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
$ SET FILE/BI_JOURNAL=(FILE=JNL_DISK:)/RU_JOURNAL/LOG OVERDUE.DAT
%SET-I-FILMARKBI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
before-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
In this example, the file OVERDUE.DAT is marked for all three
types of journaling using two SET FILE commands. A single
journal (JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL) will be used
for after-image and before-image journaling.
The first SET FILE command uses the /CREATE
qualifier to create a new after-image journal,
JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL. The file specification
uses the current default directory [PAYABLE] and the default
file extension RMS$JOURNAL.
The second SET FILE command checks the disk JNL_DISK to see
whether a journal already exists, and uses the existing journal
for before-image journaling, as well as after-image journaling.
4.$ SET FILE/NOAI_JOURNAL/NOBI_JOURNAL -
_$ WORK_DISK:[PAYABLE]OVERDUE.DAT,VENDORS.DAT
In this example, the files OVERDUE.DAT and VENDORS.DAT are
unmarked for both after-image and before-image journaling. It
is not necessary to specify the journals that were used. If
more than one journaling type was applied to the data files
(as in the previous example), then you must cancel each of the
journaling types before you can delete the data files.
5.$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK,CREATE)-
_$ /RU_JOURNAL [FIELD]SALARY.DAT
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:[FIELD]SALARY)-
_$ /RU_JOURNAL CHECKS.DAT
In this example, the files SALARY.DAT and CHECKS.DAT are both
marked for after-image and for recovery unit journaling. The
after-image journaling for both files is written to the same
journal, JOURNAL_DISK:[FIELD]SALARY.RMS$JOURNAL.
5 /BI_JOURNAL
Requires read (R), write (W), and control access. Being the owner
of the file is one way to get control access.
Marks one or more RMS files for before-image journaling. You can
also specify certain characteristics of the journal with this
command, including its file specification, whether it is to be
created, its initial size, and its default extension quantity.
The SET FILE/NOBI_JOURNAL command unmarks a file for before-image
journaling.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/[NO]BI_JOURNAL[=(keyword[,...])] data-filespec[,...]
5.1 – Parameter
data-filespec[,...]
Identifies the file to be marked for before-image journaling. If
you specify more than one file, separate the file specifications
with commas. The asterisk (*) and the percent sign (%) wildcard
characters are allowed. The file specification cannot include a
node name, since the SET FILE command is not valid for network
access.
5.2 – Description
The SET FILE/BI_JOURNAL command marks one or more RMS files
for before-image journaling. You can also specify certain
characteristics of the journal with this command, including its
file specification, whether it is to be created, its initial
size, and its default extension quantity. The SET FILE/NOBI_
JOURNAL command unmarks a file for before-image journaling.
After a data file is marked for before-image journaling with the
SET FILE/BI_JOURNAL command, the following events occur whenever
the data file is opened by RMS for write operations:
o The journal is opened.
o All subsequent modifications to the data file are recorded in
the journal.
By default, the journal has the same file specification as
the data file that is to be journaled, but with the file type
RMS$JOURNAL. That is, if you issue the following command, then,
by default, the file specification for the before-image journal
is FINANCE_DISK:PAYROLL.RMS$JOURNAL:
$ SET FILE/BI_JOURNAL FINANCE_DISK:PAYROLL.DAT
If erroneous or corrupt data is introduced into the data file,
you can use the RMS Recovery Utility to "roll back" the data file
that has been marked for before-image journaling. This will allow
you to restore the data file to a previous state by removing data
until a specified time (prior to the introduction of bad data).
Use the SET FILE/NOBI_JOURNAL command to unmark a file for
before-image journaling. After you use the SET FILE/NOBI_JOURNAL
command for a file, modifications to that data file will no
longer be written to the journal.
You must use the SET FILE/NOBI_JOURNAL command before you can
delete a file that has been marked for before-image journaling.
5.3 – Keywords
Four keywords are used as optional parameters to the SET FILE/BI_
JOURNAL command: ALLOCATION, [NO]CREATE, EXTENSION, and FILE. You
can use any, all, or none of these keywords.
Use an equal sign (=) immediately after the SET FILE/BI_JOURNAL
command to use a keyword. If you use more than one of the
keywords, enclose the list in parentheses and separate the items
in the list with commas.
ALLOCATION=n
Specifies the initial size, in blocks, of the journal. The
ALLOCATION keyword is meaningful only when the CREATE keyword
is also used.
The default allocation is 0 blocks.
CREATE
Specifies that a new journal is to be created. If no journal
exists, using this keyword creates a new one. If a journal (with
the file specification given in this command) already exists,
using this keyword creates a new version of the journal. In the
latter instance, the data file named in this SET FILE command
is journaled to the new journal. Any other files that are being
journaled to the previous version of the journal will continue to
be journaled to that previous version.
If a journal does not already exist, be sure to use the CREATE
keyword with the SET FILE/BI_JOURNAL command. If you do not
specify the CREATE keyword and a journal does not exist, a
journal is not automatically created and an error message is
displayed.
When you create a journal for before-image journaling, the file
protection for the journal is determined as follows:
o If a version of the journal that you specify with the CREATE
keyword already exists, then the new version of the journal
has the same file protection and access control list (ACL) as
the most recent version.
o If there is no existing journal (that is, if you are creating
version 1 of the journal), then the file protection and
ACL of the journal are the default file protection for the
process that creates the journal, except that none of the four
ownership categories (system, owner, group, world) is given
delete access.
If you want to use a single journal for both after-image and
before-image journaling, do not use the CREATE keyword with both
the /AI_JOURNAL and /BI_JOURNAL qualifiers, because that will
create two separate journals. When you create a journal that
will be used for more than one data file or more than one type
of journaling (after-image or before-image), you should first
use a SET FILE command to create the journal for a single type
of journaling and for a single data file. After the journal is
created, then you can use a single SET FILE command for multiple
data files and both after-image and before-image journaling. For
example, you might use the following sequence of commands:
$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:,CREATE) [WEEKLY]SALES.DAT
$ SET FILE/BI_JOURNAL=(FILE=JNL_DISK:[WEEKLY]SALES) -
_$INVOICES.DAT,COMMISSIONS.DAT
EXTENSION=n
Specifies the default extension quantity, in blocks, for the
journal. You can specify a value from 0 to 65,535.
The EXTENSION keyword is meaningful only when you use the CREATE
keyword. If the file is extended, the value that you specify is
used. If you do not use the EXTENSION keyword when you create a
journal, RMS calculates its own EXTENSION value for the journal.
FILE=journal-filespec
Specifies the journal where all before-image journal entries for
the data file will be recorded. The default file specification
for the journal is the file specification of the data file that
you name, but with a file type of RMS$JOURNAL. Use the FILE
keyword if you wish to modify this default file specification
for the journal. If you provide a partial file specification for
the before-image journal, any unspecified portions are taken from
the default file specification.
The file specification cannot include a node name, since the SET
FILE command is not valid for network access.
The FILE keyword is optional with the SET FILE/BI_JOURNAL
command.
You can use a single journal for multiple data files for before-
image journaling, and you can also use the same journal for both
before-image and after-image journaling.
5.4 – Qualifier
5.4.1 /LOG
/LOG
/NOLOG (default)
Controls whether the SET FILE command displays the file
specification and the type of journaling that has been set. By
default, this information is not displayed.
5.5 – EXAMPLES
1.$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE) -
_$FINANCE_DISK:[PAYROLL]WEEKLY.DAT
In this example, the file FINANCE_DISK:[PAYROLL]WEEKLY.DAT is
marked for before-image journaling. The FILE keyword, together
with the defaults obtained from the file specification of the
data file, provides the journal with a file specification of
JOURNAL_DISK:[PAYROLL]WEEKLY.RMS$JOURNAL. Because the CREATE
keyword was used, this journal is created when this SET FILE
command is given.
2.$ SET FILE/BI_JOURNAL=CREATE/LOG SALES.DAT
%SET-I-JCREATED,journal FINANCE_DISK:[REGION_1]SALES.RMS$JOURNAL;1
created
%SET-I-FILMARKBI, FINANCE_DISK:[REGION_1]SALES.DAT marked for RMS
before-image journaling
-SET-I-JFILE,using journal FINANCE_DISK:[REGION_1]SALES.RMS$JOURNAL;1
%SET-I-MODIFIED, FINANCE_DISK:[REGION_1]SALES.DAT modified
In this example, the file SALES.DAT in default directory
FINANCE_DISK:[REGION_1] is marked for before-image journaling
and the /LOG qualifier causes the result of the SET FILE
command to be displayed on the terminal.
3.$ SET FILE/BI_JOURNAL=(FILE=JNL_DISK:, CREATE)/LOG OVERDUE.DAT
%SET-I-JCREATED, journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
created
%SET-I-FILMARKBI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
before-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:)/RU_JOURNAL/LOG OVERDUE.DAT
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
In this example, the file OVERDUE.DAT is marked for all three
types of journaling using two SET FILE commands. A single
journal (JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL) will be used
for after-image and before-image journaling.
The first SET FILE command uses the /CREATE
qualifier to create a new before-image journal,
JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL. The file specification
uses the current default directory [PAYABLE] and the default
file extension RMS$JOURNAL.
The second SET FILE command checks the disk JNL_DISK to see
whether a journal already exists, and uses the existing journal
for after-image journaling, as well as before-image journaling.
4.$ SET FILE/NOBI_JOURNAL/NOAI_JOURNAL-
_$ WORK_DISK:[PAYABLE]OVERDUE.DAT,VENDORS.DAT
In this example, the files OVERDUE.DAT and VENDORS.DAT are
unmarked for both before-image and after-image journaling. It
is not necessary to specify the journals that were used. If
more than one journaling type was applied to the data files
(as in the previous example), then you must cancel each of the
journaling types before you can delete the data files.
5.$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK,CREATE)/RU_JOURNAL
[FIELD]SALARY.DAT
$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK:[FIELD]SALARY)
/RU_JOURNAL CHECKS.DAT
In this example, the files SALARY.DAT and CHECKS.DAT are both
marked for before-image and for recovery unit journaling. The
before-image journaling for both files is written to the same
journal, JOURNAL_DISK:[FIELD]SALARY.RMS$JOURNAL.
6 /RU_ACTIVE
Requires read (R), write (W), and control access. Being the owner
of the file is one way to get control access.
Designates the recoverable facility that controls active recovery
units for the file. Alternatively, when used with the /RU_
FACILITY qualifier, the SET FILE/RU_ACTIVE command lets you clear
the designated recoverable facility that controls active recovery
units for the specified file.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/[NO]RU_ACTIVE=ru-facility data-filespec[,...]
6.1 – Parameters
ru-facility
Specifies the number or name of a recoverable facility. It can
be an integer from 0 through 255, or it can be the name of an
VSI-registered recoverable facility.
Facility numbers 1 through 127 are reserved by VSI; facility
numbers 128 through 255 are available for user-written
recoverable facilities. RMS is recoverable facility 1; specifying
the number 1 is equivalent to using the text * corresponds to
no recoverable facility and is equivalent to using the qualifier
/NORU_ACTIVE. Currently, the only VSI-defined recoverable facility
is 1 (RMS).
data-filespec[,...]
Specifies the file that is 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. The file specification cannot include a node name, since
the SET FILE command is not valid for network access.
6.2 – Description
The SET FILE/RU_ACTIVE command designates the recoverable
facility that controls active recovery units for the file.
Alternatively, when used with the /RU_FACILITY qualifier, the SET
FILE/RU_ACTIVE command lets you clear the designated recoverable
facility that controls active recovery units for the specified
file. This is useful if a data file is unavailable due to active
recovery units and an unavailable recovery unit journal.
CAUTION
When you clear the RU_ACTIVE attribute (using the command
SET FILE/RU_ACTIVE=0/RU_FACILITY=1), the data in the file is
likely to be in an inconsistent state. Do not use the data
file unless you can ensure that the data is consistent.
After clearing the RU_ACTIVE attribute, you can unmark
the file for journaling, delete the file, and re-create a
consistent file using a backup copy.
You can determine the recoverable facility that controls active
recovery units (if any) for the file by entering the DCL command
DIRECTORY/FULL or DUMP/HEADER. You can use the ANALYZE/RMS_
FILE/RU_JOURNAL command to determine the state of any active
recovery units.
6.3 – Qualifier
6.3.1 /LOG
/LOG
/NOLOG(default)
Controls whether the SET FILE command displays the file
specification and the type of facility that has been specified.
By default, this information is not displayed.
6.4 – EXAMPLES
1.$ SET FILE/RU_FACILITY=1/RU_ACTIVE=0-
_$ FINANCE_DISK:[PAYROLL]WEEKLY.DAT
If the file WEEKLY.DAT is unavailable due to active recovery
units and an unavailable recovery unit journal, you can use
this command to gain access to the file. In this example, the
recoverable facility is defined as RMS by the /RU_FACILITY=1
qualifier. The RU_ACTIVE attribute that indicates active RMS
recovery units for the file WEEKLY.DAT is cleared by the /RU_
ACTIVE=0 qualifier.
CAUTION
The data in the file may be inconsistent if there are active
recovery units. VSI recommends that you not use the contents
of the data file unless you can verify that the data is
consistent.
VSI also recommends that you make a new copy of the file
using the Convert Utility and that you use the converted
copy in place of the original.
7 /RU_FACILITY
Allows you to identify the recoverable facility that controls
active recovery units on the file.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/RU_FACILITY=ru-facility data-filespec[,...]
7.1 – Parameters
ru-facility
Specifies the number or name of a recoverable facility. It can
be an integer from 0 through 255, or it can be the name of an
VSI-registered recoverable facility.
Facility numbers 1 through 127 are reserved by VSI; facility
numbers 128 through 255 are available for user-written
recoverable facilities. RMS is recoverable facility 1; specifying
the number 1 is equivalent to using the text RMS. The number
0 corresponds to no recoverable facility. Currently, the only
VSI-defined recoverable facility is 1 (RMS).
The recoverable facility that you specify is an input parameter
that is used only to open the file; it does not actually modify
any file attributes.
data-filespec[,...]
Specifies the file that is 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. The file specification cannot include a node name, since
the SET FILE command is not valid for network access.
7.2 – Description
The SET FILE/RU_FACILITY command allows you to identify the
recoverable facility that controls active recovery units on the
file. You can use any other SET FILE qualifier with the /RU_
FACILITY qualifier.
When a data file has active recovery units and RMS journaling
cannot resolve the recovery units (for example, if the recovery
unit journal is unavailable), the data file cannot be opened
or deleted. The presence of active recovery units prevents you
from unmarking (or marking) a file for any journaling type. With
the SET FILE/RU_FACILITY/RU_ACTIVE command, you can clear the
designated recoverable facility that controls active recovery
units for the data file.
CAUTION
When you clear the RU_FACILITY attribute (with the command
SET FILE/RU_ACTIVE=0/RU_FACILITY=1), the data in the file is
likely to be in an inconsistent state. Do not use the data
file unless you can ensure that the data is consistent.
After clearing the RU_ACTIVE attribute, you can unmark
the file for journaling, delete the file, and re-create a
consistent file using a backup copy.
You can determine the recoverable facility that controls active
recovery units (if any) for the file by entering the DCL command
DIRECTORY/FULL or DUMP/HEADER. You can use the ANALYZE/RMS_
FILE/RU_JOURNAL command to determine the state of any active
recovery units.
7.3 – Examples
1.$ SET FILE/RU_FACILITY=1/NORU_JOURNAL/NOAI_JOURNAL/LOG SAVINGS.DAT
%SET-I-FILUNMARKAI, $DISK1:[PERSONAL]SAVINGS.DAT;1 unmarked for RMS
after-image journaling
%SET-I-FILUNMARKRU, $DISK1:[PERSONAL]SAVINGS.DAT;1 unmarked for RMS
recovery-unit journaling
%SET-I-MODIFIED, $DISK1:[PERSONAL]SAVINGS.DAT;1 modified
$ DELETE SAVINGS.DAT;*
This example shows the use of the /RU_FACILITY qualifier to
allow SET FILE access to a data file. The SET FILE command
identifies the recoverable facility holding the file and
it also unmarks the file for recovery unit and after-image
journaling. After these steps, it is then possible to delete
the data file.
CAUTION
If it becomes necessary to use the /RU_FACILITY qualifier
because of active recovery units, the data in the file may
be inconsistent. VSI recommends that you not use the data
file unless you can verify that the data is consistent.
VSI also recommends that you make a new copy of the file
using the Convert Utility and that you use the converted
copy in place of the original.
2.$ SET FILE/RU_FACILITY=RMS/RU_ACTIVE=0 SALES.DAT
In this example, the recoverable facility for the file
SALES.DAT is identified as RMS by the /RU_FACILITY=RMS
qualifier, and the RU active file attribute (which indicates
active RMS recovery units) is cleared by the /RU_ACTIVE=0
qualifier. If the file SALES.DAT is unavailable due to active
recovery units and an unavailable recovery unit journal, you
can use this command to gain access to the file.
As in the previous example, this operation leaves the data
file in an inconsistent state. In general, use this command to
delete the data file, then restore the file from a backup copy.
8 /RU_JOURNAL
Requires read (R), write (W), and control access. Being the owner
of the file is one way to get control access.
Marks an RMS file for recovery unit journaling.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/[NO]RU_JOURNAL[=volume-name] data-filespec[,...]
8.1 – Parameters
volume-name
Specifies the volume on which the recovery unit journals will be
located, using one of the following keywords:
o DEVICE=device_name specifies a device name or logical name.
o LABEL=volume-label specifies a volume label.
By default, recovery unit journals are created temporarily in the
[SYSJNL] directory on the same volume as the file that is being
journaled. (If such a directory does not exist, RMS journaling
creates it automatically.) You can change the device on which the
recovery unit journals are created by using either the DEVICE or
LABEL keyword.
Use the DEVICE keyword to specify the location of recovery unit
journals using a device name or a logical name. Use the LABEL
keyword to specify the location of recovery unit journals using a
volume label. You can only use one of these two keywords (LABEL
or DEVICE) to specify the recovery unit journal location. In
either case, only the volume label is actually stored with the
file.
At run time, RMS attempts to translate the logical name
DISK$volume_label when creating a recovery unit journal. This
is the default logical name created by the Mount Utility when you
mount the disk using the /SYSTEM or /CLUSTER qualifier. If you do
not mount the disk using the /SYSTEM or /CLUSTER qualifier, you
must define the logical name DISK$volume_label using the DEFINE
command with the /SYSTEM and /EXECUTIVE_MODE qualifiers. You
must have the SYSNAM (system logical name) or the SYSPRV (system
privilege) privilege to use the /SYSTEM qualifier.
NOTE
The logical name DISK$volume_label can point to any
disk device on the system that is mounted and has for
its volume label an executive-mode logical name in the
form DISK$volume_label with the concealed and terminal
attributes.
data-filespec[,...]
Specifies the file that is to be marked for recovery unit
journaling. If a data file has been marked for recovery unit
journaling with this command, DECdtm transaction services
($START_TRANS, $END_TRANS, and $ABORT_TRANS) must be used by
an application program to define transactions whenever data in
this file is modified.
If you specify more than one file, separate the file
specifications with commas. The asterisk (*) and the percent
sign (%) wildcard characters are allowed. The file specification
cannot include a node name, since the SET FILE command is not
valid for network access.
8.2 – Description
The SET FILE/RU_JOURNAL command marks an RMS file for recovery
unit journaling. To use recovery unit journaling for a data file,
a data file must be marked for recovery unit journaling with the
SET FILE/RU_JOURNAL command, and transactions must be defined
in an application program using DECdtm transaction services. You
can also use this command to specify the default volume on which
recovery unit journals will be created for this file.
Use the SET FILE/NORU_JOURNAL command to unmark a file for
recovery unit journaling. After you use the SET FILE/NORU_JOURNAL
command for a file, modifications to that data file will no
longer be written to a recovery unit journal.
If you wish to delete a file that has been marked for recovery
unit journaling, you must use the SET FILE/NORU_JOURNAL command
before you can delete the file.
There is no reason other than performance to keep recovery unit
journals on a different volume from the file being journaled.
Unlike after-image journaling, which protects against a system
failure such as a head crash that causes a loss of data, recovery
unit journaling ensures that a predefined set of operations are
either done in their entirety, or not done at all. In the event
of an abnormal termination of the application, such as a system
crash or a Ctrl/Y, any incomplete transactions are automatically
rolled back (undone). Because all recovery unit journals must
be available before the data files can be rolled back, locating
recovery unit journals on a volume where availability might be
low could reduce the availability of the data files that use
those recovery unit journals.
Specifying a location for recovery unit journals for a file
does not guarantee that the recovery unit journals will always
be located on the named device or volume. For any active
transaction, there is always only one recovery unit journal for
local files. Thus, if many files are involved in a transaction, a
single recovery unit journal is used, even if different locations
for the journals had been specified (for individual files) with
different SET FILE/RU_JOURNAL commands.
Remote files are an exception to this rule. Each remote file
associated with a transaction has its own recovery unit and
recovery unit journal. The recovery unit journal resides on the
remote system. The volume is chosen in the same way as for local
files. Remote files have no effect in determining where the local
recovery unit journal resides.
A journal is not deleted when the transaction has been completed.
Recovery unit journals are automatically deleted only when
all of the files involved in the transaction are closed and
the application exits. RMS journaling automatically creates a
recovery unit journal at run time, whenever the first record
stream associates with a transaction. All record streams in
the process associated with the same transaction share a single
recovery unit journal. Once a recovery unit journal is created,
it can be reused for another transaction by the process that
created it. A recovery unit journal is created only when there is
no available recovery unit journal opened by the process for the
current transaction.
8.3 – Examples
1.$ SET FILE/RU_JOURNAL FINANCE_DISK:[PAYROLL]WEEKLY.DAT
This command marks the file WEEKLY.DAT for recovery unit
journaling. Any operation within an application that modifies
this file must be in a defined transaction (defined by DECdtm
transaction services).
2.$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:, CREATE)-
_$ /RU_JOURNAL/LOG OVERDUE.DAT
%SET-I-JCREATED, journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
created
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:OVERDUE)-
_$ /RU_JOURNAL/LOG CURRENT.DAT
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]CURRENT.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]CURRENT.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]CURRENT.DAT;1 modified
In this example, the files OVERDUE.DAT and CURRENT.DAT are
marked for after-image and recovery unit journaling using two
SET FILE commands. In this example, a single journal (JNL_
DISK:[PAYABLE]OVERDUE.RMS$JOURNAL) is used for after-image
journaling.
The first SET FILE command uses the /CREATE
qualifier to create a new after-image journal, JNL_
DISK:[PAYABLE]OVERDUE.RMS$JOURNAL, for the file OVERDUE.DAT.
The file specification uses the current default directory
[PAYABLE] and the default file extension RMS$JOURNAL.
The second SET FILE command marks the file CURRENT.DAT for
after-image and recovery unit journaling, checks the disk JNL_
DISK to see whether an after-image journal already exists, and
uses the existing journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL
for the file CURRENT.DAT.