OpenVMS Record Management Utilities Reference Manual
OpenVMS Record Management Utilities Reference
Manual
Order Number:
AA--PV6QC--TK
January 1999
This manual describes the Record Management utilities, including the
Analyze/RMS_File utility, the Convert utility, the Convert/Reclaim
utility, the Create/FDL utility, and the Edit/FDL utility. The manual
also describes the File Definition Language (FDL) facility and the File
Definition Language.
Revision/Update Information:
This manual supersedes the OpenVMS Record Management Utilities Reference Manual, OpenVMS Alpha Version 7.1 and
OpenVMS VAX Version 7.1
Software Version:
OpenVMS Alpha Version 7.2
OpenVMS VAX Version 7.2
Compaq Computer Corporation Houston, Texas
January 1999
Compaq Computer Corporation makes no representations that the use of
its products in the manner described in this publication will not
infringe on existing or future patent rights, nor do the descriptions
contained in this publication imply the granting of licenses to make,
use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this
publication is authorized only pursuant to a valid written license from
Compaq or an authorized sublicensor.
Compaq conducts its business in a manner that conserves the environment
and protects the safety and health of its employees, customers, and the
community.
The following are trademarks of Compaq Computer Corporation: Alpha,
Bookreader, Compaq, DECdirect, DECnet, DECwindows, DIGITAL, OpenVMS,
RMS--11, RSX--11, RSX--11M, RSX--11M-PLUS, RT--11, VAX, VAX DOCUMENT,
VAXcluster, VMS, and the Compaq logo.
The following are third-party trademarks:
All other trademarks and registered trademarks are the property of
their respective holders.
ZK6027
The OpenVMS documentation set is available on CD-ROM.
This document was prepared using VAX DOCUMENT, Version V3.2n.
This manual is intended for all programmers who use OpenVMS RMS data
files, including high-level language programmers who use only their
language's input and output statements.
Document Structure
Chapter 1 describes the Analyze/RMS_File utility (ANALYZE/RMS_FILE)
and consists of five sections:
Description---Provides a full description of the Analyze/RMS_File
utility.
Usage Summary---Outlines the following ANALYZE/RMS_FILE information:
--Invoking the utility
--Exiting from the utility
--Directing output
--Restrictions or privileges required
Qualifiers---Describes ANALYZE/RMS_FILE qualifiers, including
format, parameters, and examples.
Commands---Describes ANALYZE/RMS_FILE commands, including format,
parameters, and examples.
Chapter 2 describes the Convert utility (CONVERT) and consists of
four sections:
Description---Provides a full description of the Convert utility.
Usage Summary---Outlines the following CONVERT information:
--Invoking the utility
--Exiting from the utility
--Directing output
--Restrictions or privileges required
Qualifiers---Describes the CONVERT qualifiers, including format,
parameters, and examples.
Examples---Provides additional CONVERT examples.
Chapter 3 describes the Convert/Reclaim utility (CONVERT/RECLAIM) and
consists of four sections:
Description---Provides a full description of the Convert/Reclaim
utility.
Usage Summary---Outlines the following CONVERT/RECLAIM information:
--Invoking the utility
--Exiting from the utility
--Directing output
--Restrictions or privileges required
Qualifiers---Describes the CONVERT/RECLAIM qualifier, /STATISTICS.
Examples---Provides CONVERT/RECLAIM examples implementing the
/STATISTICS qualifier.
Chapter 4 describes in detail the File Definition Language facility
(FDL). This chapter provides an overview and detailed descriptions
about the File Definition Language. It describes in detail each file
section and associated file attributes.
Chapter 5 describes the Create/FDL utility (CREATE/FDL) and consists
of four sections:
Description---Provides a description of the utility.
Usage Summary---Outlines the following information:
--Invoking the utility
--Exiting from the utility
--Directing output
--Restrictions or privileges required
Qualifiers---Describes the sole CREATE/FDL qualifier, /STATISTICS.
Examples---Provides additional examples of implementing CREATE/FDL.
Chapter 6 describes the Edit/FDL utility (EDIT/FDL) and consists of
four sections:
Description---Provides a description of the Edit/FDL utility.
Usage Summary---Outlines the following EDIT/FDL information:
--Invoking the utility
--Exiting from the utility
--Directing output
--Restrictions or privileges required
Qualifiers---Describes the EDIT/FDL commands and qualifiers,
together with related examples.
Examples---Provides additional examples of implementing EDIT/FDL.
Related Documents
The following manuals contain information that relates to the
information in this manual:
Guide to OpenVMS File Applications
OpenVMS Record Management Services Reference Manual
RMS Journaling for OpenVMS Manual
For additional information on the Open Systems Software Group (OSSG)
products and services, access the following OpenVMS World Wide Web
address:
http://www.openvms.digital.com
Reader's Comments
Compaq welcomes your comments on this manual.
Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send
us your comments by:
Use the following World Wide Web address to order additional
documentation:
http://www.openvms.digital.com:81/
If you need help deciding which documentation best meets your needs,
call 800-DIGITAL (800-344-4825).
Conventions
The following conventions are used in this manual:
Ctrl/
x
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
PF1
x
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
button.
[Return]
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
...
A horizontal ellipsis in examples indicates one of the following
possibilities:
Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.
.
.
.
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
( )
In command format descriptions, parentheses indicate that you must
enclose the options in parentheses if you choose more than one.
[ ]
In command format descriptions, brackets indicate optional elements.
You can choose one, none, or all of the options. (Brackets are not
optional, however, in the syntax of a directory name in an OpenVMS file
specification or in the syntax of a substring specification in an
assignment statement.)
[|]
In command format descriptions, vertical bars separating items inside
brackets indicate that you choose one, none, or more than one of the
options.
{ }
In command format descriptions, braces indicate required elements; you
must choose one of the options listed.
bold text
This text style represents the introduction of a new term or the name
of an argument, an attribute, or a reason.
italic text
Italic text indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
UPPERCASE TEXT
Uppercase text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
Monospace text
Monospace text indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the
following elements: keywords, the names of independently compiled
external functions and files, syntax summaries, and references to
variables or identifiers introduced in an example.
-
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
following line.
numbers
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
indicated.
The Analyze/RMS_File utility (ANALYZE/RMS_FILE) allows you to examine,
either with or without an interactive terminal dialogue, the internal
structure of a Record Management Services (RMS) file. The
Analyze/RMS_File utility can check the structure of the file for
errors, generate a statistical report on the structure and use of the
file, or generate a File Definition Language (FDL) file from a data
file.
The Analyze/RMS_File utility also provides information about RMS
Journaling for OpenVMS (RMS journaling) files marked for after-image
journaling, before-image journaling, and, where applicable, information
about the state of recovery units affecting RMS journaling files.
The Analyze/RMS_File utility provides a set of commands that you may
use to analyze a file interactively.
FDL files created with the Analyze/RMS_File utility have special
sections that contain statistics about the structure of the specified
data file. You can use FDL files created with the Analyze/RMS_File
utility in conjunction with other Record Management
utilities.
On Alpha systems, the Analyze/RMS_File utility and its qualifiers and
commands contain capabilities that allow them to use the features
provided by extended file specifications. Extended file specifications
features offer extended file naming and handling capabilities that
enable OpenVMS Alpha systems to store, manage, serve, and access files
across OpenVMS and Windows NT systems in a PATHWORKS environment.
Specifically, extended file specifications provide the following
features:
Support a Files-11 volume structure, On-Disk Structure Level 5
(ODS-5), that provides a volume structure for creating and storing
files with expanded file names
Support additional character sets for naming files from file names
that use the 8-bit ISO Latin-1 character set to the 16-bit Unicode
(UCS-2) character set
Support extended file names with file specifications exceeding the
traditional 39.39 character limit up to a maximum of 255 characters
Support preserving the case of file specifications created with the
ODS-5 attributes
Support deep, multilevel directory structures up to a maximum of
512 characters
For more information, see the OpenVMS Guide to Extended File Specifications.
One of the most useful features of the Analyze/RMS_File utility is its
interactive mode. You enter the interactive mode by specifying the
/INTERACTIVE qualifier to the ANALYZE/RMS_FILE command; you then begin
an interactive session, during which you can examine the structure of
an RMS file. Enter the HELP command at the ANALYZE> prompt for help
about the various commands available to you for traversing the file.
The Analyze/RMS_File utility treats the internal RMS file as a
multilevel entity. All RMS files are identical, relative to the first
two levels. Level 1 contains the file header and level 2 contains the
file attributes.
Files marked for RMS journaling, level 2, include information relative
to before-image journaling and after-image journaling, where applicable.
Some differentiation occurs at level 3. For sequential files, level 3
is the lowest level and it contains data records (see Figure 1-1)
that ANALYZE/RMS_FILE can display individually. For relative files and
indexed files, level 3 contains the file prolog.
Figure 1-1 Structure of Sequential Files
For relative files, level 4 contains data buckets that are accessible
individually (see Figure 1-2). Using the Analyze/RMS_File utility,
you can view the contents of each individual data bucket.
Figure 1-2 Structure of Relative Files
For indexed files, the Analyze/RMS_File utility presents you with two
options at level 4: you can proceed down the path that begins with a
level of area descriptors (see Figure 1-3) or you can choose the path
that begins with a level of key descriptors (see Figure 1-4).
Figure 1-3 AREA DESCRIPTOR Path
Level 5 is the final level in a relative file. This level contains the
record cells that are accessible individually. For indexed files, the
contents of level 5 depend on whether you have chosen the area
descriptor path or the key descriptor path:
If you select the area descriptor path, level 5 is the lowest level
and it contains reclaimed data records---that is, records that are
effectively empty and are available for storing new data.
If you select the key descriptor path, the Analyze/RMS_File utility
gives you the option of viewing the index root bucket or the data
bucket for the selected key, or traversing the level laterally and
viewing another key.
Figure 1-4 KEY DESCRIPTOR Path
When you choose to view the index root bucket, the next level down
contains the index record for the selected key. After you view the
index record, the Analyze/RMS_File utility provides you with direct
access to the first data bucket for the selected key.
At the data bucket level, you can either view the data record or
traverse the data level laterally and select another data bucket for
the selected key.
The structure of an indexed file is more complicated than that of
sequential and relative files. From the PROLOG level, the structure
branches to the AREA DESCRIPTORs and the KEY DESCRIPTORs. Each AREA
DESCRIPTOR describes the attributes and the virtual block numbers for
the different file areas. The KEY DESCRIPTOR path contains the primary
index structures (and data records) as well as the alternate index
structures.
There are two types of record structures: primary records and alternate
records. If you follow the primary index structure (key = 0), you find
the primary record structures, which contain the actual data records
(see Figure 1-5). You can examine the actual bytes of data in the
record. If the record has been moved to another bucket as a result of a
bucket split, you can examine the bucket to which the record reference
vector (RRV) points. An RRV is a forwarding pointer that a record
leaves behind in its former bucket location when it moves to a new
bucket.
Figure 1-5 Structure of Primary Records
If you follow any of the alternate index structures, you find the
alternate record structures, which contain the secondary index data
records (SIDRs). A SIDR consists of an alternate key value and one or
more pointers to the actual data records in the primary index structure
(see Figure 1-6).
Figure 1-6 Data Buckets in the Alternate Index
Structures
The ANALYZE/RMS_FILE command is supported only for the examination of
files accessible to OpenVMS RMS or RMS--11.
You use the ANALYZE/RMS_FILE command over a network to analyze the
internal structure of a remote file in exactly the same way that you
use it to analyze the internal structure of a local file. For example,
you can specify the /FDL qualifier to generate an FDL file from the
data file. Using other qualifiers, you can check the file structure for
errors, generate a statistical report on the file's structure and use,
or enter interactive mode to explore the structure of the file.
However, you can specify only one of these qualifiers in each command.
Note that you need the NETMBX privilege to execute the ANALYZE/RMS_FILE
command over a network.
You handle the Analyze/RMS_File utility errors for two general error
categories: nonjournaling errors and journaling errors. Even if you do
not have RMS Journaling software, you may find that you have imported
files marked for RMS Journaling from another system or from other nodes
within an OpenVMS Cluster.
If you receive any of the Analyze/RMS_File utility error messages while
analyzing a file interactively, the file has been corrupted by a
serious error. Note that the Analyze/RMS_File utility errors are not
listed in the OpenVMS system messages documentation because in all cases the user response to
errors signaled by the Analyze/RMS_File utility is identical, as
described in the following paragraphs.
If the application program encounters errors during noninteractive
analysis, the Analyze/RMS_File utility returns to the program, as
exit status, the first occurrence of the most severe error it
encounters. For example, if a warning (A) and two errors (B and C) are
signaled, then the first error (B) is placed in the DCL symbol $STATUS
at image exit.
If you have had a hardware problem (for example, a power or disk head
failure), then the hardware most likely caused the corruption.
If you have no hardware problems, then a software error may have been
introduced through either the user software or the system software.
First, verify the user software and computer operations. Possibly, data
files may have been corrupted by a process being stopped abnormally;
for example, if a STOP/ID or DELETE/ENTRY occurs in the midst of data
processing.
One test of whether the problem is in the system software is to note
the situations where errors occur. For example, if a particular
application uses an unusual I/O sequence that seems to result in file
corruption, it may be that the problem is in the system software. In a
situation like this, you should attempt to reproduce the problem and
note precisely the I/O sequence. This information, together with
appropriate supporting information, should be submitted with a Software
Performance Report (SPR).
In either case, try to fix the problem with the Convert utility, using
the same file specification for both the input file and the output
file. If this procedure does not yield the result you want, use the
Backup utility to restore a backup copy of the file.
If RMS Journaling software is not installed on your system and you
attempt to write to a file marked for journaling, the system issues the
following error message:
%RMS-F-JNS, operation not supported by RMS Journaling
If RMS Journaling software is installed and you receive this message,
you attempted an operation that is not supported by RMS Journaling. For
more information on handling RMS Journaling errors, see the
RMS Journaling for OpenVMS Manual.
To turn off journaling in either case, use the following DCL command:
$ SET FILE/NOAI_JOURNAL/NOBI_JOURNAL/NORU_JOURNAL
Note that the SET FILE commands for turning off journaling are
available to users who do not have RMS Journaling software as well as
to users who do.
Another error condition may occur if you import a file marked for
recovery-unit journaling that has active recovery units. This can
happen when a file is not recovered properly before the volume is moved
to your system.
If you try to back up the file, RMS issues the following error message:
%BACKUP-E-OPENIN, error opening DISK$DATA:[USER]FILE.DAT;1 as input
-SYSTEM-F-RUCONFLICT, another facility has active recovery units on file
To turn off the active recovery units, use the following DCL command:
$ SET FILE/RU_FACILITY=RMS/NORU_ACTIVE
Note that this may leave the file in an inconsistent state with respect
to recovery units because active recovery units are not rolled back
(aborted).
![[Site home]](../../images/buttons/bn_site_home_off.gif){kind=small}
![[Send comments]](../../images/buttons/bn_comments_off.gif){kind=small}
![[Help with this site]](../../images/buttons/bn_site_help_off.gif){kind=small}
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif){kind=small}
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif){kind=small}
![[Compaq site]](../../images/buttons/bn_compaq_off.gif){kind=small}
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)
![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
Level 5 is the final level in a relative file. This level contains the
record cells that are accessible individually. For indexed files, the
contents of level 5 depend on whether you have chosen the area
descriptor path or the key descriptor path:
When you choose to view the index root bucket, the next level down
contains the index record for the selected key. After you view the
index record, the Analyze/RMS_File utility provides you with direct
access to the first data bucket for the selected key.
Buffalo State College 
Twin Rise 200