HP OpenVMS Systems Documentation

OpenVMS Record Management Utilities Reference Manual

Order Number: AA-PV6QD-TK

April 2001

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.2 and OpenVMS VAX Version 7.2

Software Version: OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

Compaq, AlphaServer, VAX, VMS, and the Compaq logo Registered in U.S.
Patent and Trademark Office.

Alpha, OpenVMS, PATHWORKS, DECnet, and DEC are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

UNIX and X/Open are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6027

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

Intended Audience

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
--Copying and analyzing shared files
Qualifiers---Describes ANALYZE/RMS_FILE qualifiers, including format, parameters, and examples.
Commands---Describes ANALYZE/RMS_FILE commands, including format, parameters, and examples.
Examples---Provides additional ANALYZE/RMS_FILE 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
--Executing commands over a network
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
--Executing commands over a network
Qualifiers---Describes the CONVERT/RECLAIM qualifier, /STATISTICS.

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
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
Qualifiers---Describes the EDIT/FDL commands and qualifiers, together with related examples.
Examples---Provides additional examples of implementing EDIT/FDL.

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

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 choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents 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.

Chapter 1
Analyze/RMS_File Utility

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.

1.1 Analyzing RMS File Structure Interactively

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 either 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

1.2 Using the Analyze/RMS_File Utility with DECnet for OpenVMS

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.

1.3 Handling Error Conditions

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.

1.3.1 Nonjournaling Errors

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.

1.3.2 Journaling Errors

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