Digital PDFs

AA-Z404B-TE

April 1986

46 pages

Original

4.5MB

Document:	VMS 4.4 VAX VMS Analyse RMS File Utility Reference Manual
Order Number:	AA-Z404B-TE
Revision:
Pages:	46
Original Filename:	https://archive.org/download/stx_AA-Z404B-TE_VMS_4.4_VAX_VMS_Analyse_RMS_File_Utility_Reference_Manual_Apr86/AA-Z404B-TE_VMS_4.4_VAX_VMS_Analyse_RMS_File_Utility_Reference_Manual_Apr86.pdf

OCR Text

VAX/VMS
Analyze/ RMS_File
Utility Reference Manual
Order Number: AA-Z404B-TE

April 1986

This document describes the VAX/VMS Analyze/RMS_File Utility.

Revision/Update Information:

This manual supercedes the
VAX/VMS Analyze/RMS-File Utility
Reference Manual Version 4.0.

Software Version:

VAX/VMS Version 4.4

digital equipment corporation
maynard, massachusetts

April 1986

The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.

Copyright ©1986 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

BBSDE3SD
ZK-3031

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO RICO*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.
This document was prepared using an in-house documentation production system. All page
composition and make-up was performed by T^X, the typesetting system developed by
Donald E. Knuth at Stanford University. T^X is a registered trademark of the American Mathematical
Society.

ANALYZE/RMS-FILE Contents
PREFACE
NEW AND CHANGED FEATURES

vii

FORMAT

ARMS-1

COMMAND SUMMARY

ARMS-2

DESCRIPTION

ARMS-2

ANALYZING VAX RMS FILE STRUCTURE
INTERACTIVELY

ARMS-2

USING ANALYZE/RMS-FILE WITH DECNET-VAX

ARMS-6

HANDLING EXCEPTION CONDITIONS

ARMS-7

COMMAND QUALIFIERS
/CHECK

ARMS-8
ARMS-9

/FDL

ARMS-10

/INTERACTIVE

ARMS-11

/OUTPUT

ARMS-12

/STATISTICS

ARMS-13

/SUMMARY

ARMS-14

COMMANDS

ARMS-15

AGAIN

ARMS-16

BACK

ARMS-17

DOWN

ARMS-18

DUMP

ARMS-19

EXIT

ARMS-20

FIRST

ARMS-21
iii

ANALYZE/RMS-FILE Contents

HELP

ARMS-22

ARMS-23

POSITION/BUCKET

ARMS-24

POSITION/RECORD

ARMS-26

REST

ARMS-27

TOP

ARMS-28

ARMS-29

EXAMPLES

ARMS-30

INDEX
FIGURES
ARMS—1

Tree Structure for Sequential Files

ARMS-3

ARMS—2

Tree Structure for Relative Files

ARMS-3

ARMS—3

AREA DESCRIPTOR Path

ARMS-4

ARMS—4

KEY DESCRIPTOR Path

ARMS-5

ARMS—5

Structure of Primary Records

ARMS-6

ARMS—6

Data Buckets in the Alternate Index Structures

ARMS-6

Preface
Intended Audience
This manual is intended for all programmers using VAX RMS data files. This
audience includes high-level language users who use only their language's
input/output statements.

Structure of This Document
This document is composed of five major sections.
The Format Section is an overview of the Analyze/RMS_File Utility and is
intended as a quick reference guide. DCL commands that invoke the Analyze
/RMS_File Utility as well as all command qualifiers and parameters are listed
in the format summary section. The usage summary describes how to invoke
and exit from the Analyze/RMS_File Utility, how to direct output, and any
restrictions you should be aware of.
The Description Section explains how to use the Analyze/RMS_File Utility.
The Qualifier Section describes each DCL command qualifier. Qualifiers
appear in alphabetical order.
The Command Section describes each interactive Analyze/RMS_File Utility
command. Commands appear in alphabetical order.
The Examples Section contains examples of common operations that you
perform with the Analyze/RMS_File Utility.

Associated Documents
To use the Analyze/RMS_File Utility, you should also be familiar with the
following manuals:
•

Guide to VAX/VMS File Applications

•

VAX/VMS Convert and Convert/Reclaim Utility Reference Manual

•

VAX/VMS File Definition Language Facility Reference Manual

Preface

Conventions Used in This Document

Convention

Meaning

[ret]

A symbol with a one- to three-character
abbreviation indicates that you press a key on
the terminal, for example, 1 RET| .

|CTRL/x|

The phrase CTRL/x indicates that you must press
the key labeled CTRL while you simultaneously
press another key, for example, CTRL/C, CTRL/Y,
CTRL/O.

$ SHOW TIME
05-JUN-1985 11:55:22

Command examples show all output lines or
prompting characters that the system prints
or displays in black letters. All user-entered
commands are shown in red letters.

$ TYPE MYFILE.DAT

Vertical series of periods, or ellipsis, mean either
that not all the data that the system would display
in response to the particular command is shown or
that not all the data a user would enter is shown.

file-spec,...

Horizontal ellipsis indicates that additional
parameters, values, or information can be entered.

[logical-name]

Square brackets indicate that the enclosed item
is optional. (Square brackets are not, however,
optional in the syntax of a directory name in a
file specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer to
double quotation marks ("). The term apostrophe
(7) is used to refer to a single quotation mark.

•
•

New and Changed Features
The following new interactive commands have been added to the Analyze
/RMS_file Utility, and their descriptions are included in this manual:
•

The BACK command moves the structure pointer to the previous node if
one exists within the current level, and displays that node. You can also
specify the number of structures that the pointer is to be moved by using
the optional parameter BACK n, where n is an integer.

•

The NEXT command now accepts the optional parameter n (NEXT n) to
specify the number of structures that the pointer is to be moved forward.

•

The POSITION/BUCKET command lets you position the pointer to a
specific bucket of your file. You can use this command to bypass the
step-by-step positioning, and you can also use it to position the pointer at
a bucket that would otherwise be inaccessible due to structural errors in
the file.

•

The POSITION/RECORD command lets you position the pointer at a
specific record in the current bucket, allowing you to access subsequent
structures more easily.

ANALYZE / RMS-FILE

ANALYZE/RMS-FILE
The Analyze/RMS—File Utility (ANALYZE/RMS—FILE) allows you to
examine the internal structure of a VAX RMS file.
ANALYZE/RMS_FILE can perform the following five functions:

FORMAT

•

Check the structure of a file for errors.

•

Generate a statistical report on the file's structure and use.

•

Enter an interactive mode through which you can explore a
file's structure. This analysis can determine whether or not
the file is properly designed for its application and can point out
improvements to make in the file’s File Definition Language (FDL)
specification.

•

Generate an FDL file from a data file.

•

Generate a summary report on the file's structure and use.

ANALYZE/RMS-FILE file-spec[,...]
Command Qualifiers

Defaults

/CHECK
/FDL
/INTERACTIVE
/[NO]OUTPUT[= file-spec]
/STATISTICS
/SUMMARY

See text.
See text.
See text.
/OUTPUT
See text.
See text.

Command Parameters

file-spec
Specifies the data file to be analyzed. By default, the file type is assumed to
be DAT. You can use multiple file specifications and wildcard characters with
the /CHECK, /STATISTICS, and /SUMMARY qualifiers, but not with the
/FDL and /INTERACTIVE qualifiers.

usage summary

invoking
Invoke the utility by typing the ANALYZE/RMS—FILE command at the
DCL command level. This command can perform only one of the five utility
functions at a time; in other words, you must issue a new ANALYZE/RMSFILE command each time you choose a different function.

Exiting
Exit the utility by typing the EXIT command if the /INTERACTIVE qualifier
was specified. Otherwise, let the utility run to successful completion.

Directing Output
You can control ANALYZE/RMS—FILE output with the /OUTPUT command
qualifier. For a more detailed explanation of the /OUTPUT qualifier, refer to
the Command Qualifiers Section.

ARMS—1

ANALYZE/RMS-FILE
Description

Privileges/Restrictions
During the time that you use ANALYZE/RMS—FILE to examine the system
authorization file (SYSUAF.DAT), you prevent other users from logging into
the system. Similarly, while you are analyzing your mail file, you cannot
receive mail. So if you need to analyze these or other shared files, you may
want to make a copy of the file and analyze the copy to avoid this problem.
NETMBX privilege is required if you want to analyze a file over a network.

commands

Syntax
ANALYZE> command [parameter]
ANALYZE/RMS—FILE Commands
AGAIN
BACK [n]
DOWN [branch]
DUMP n
EXIT
FIRST
HELP [keyword...]
NEXT [n]
POSITION/BUCKET bucket-vbn [/INDEX=n]
POSITION/RECORD record-offset
REST
TOP
UP

DESCRIPTION

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 VAX RMS file. It can check the structure of the file for errors,
generate a statistical report on the structure and use of the file, or generate an
FDL file from a data file.
The commands listed above can be used when you analyze a file interactively.
You can use these commands by specifying the /INTERACTIVE qualifier in
your DCL command line.
FDL files created with ANALYZE/RMS—FILE have special sections that
contain statistics about the data file's structure. You can use an FDL file
produced by ANALYZE/RMS—FILE with the other VAX RMS utilities.

Analyzing VAX RMS File Structure Interactively
One of the most useful features of ANALYZE/RMS—FILE is its interactive
mode. You enter interactive mode by specifying the /INTERACTIVE qualifier;
you then begin an interactive session during which you can examine the
structure of a VAX RMS file.
ANALYZE/RMS—FILE imposes a hierarchical tree structure on the internal
VAX RMS file structure. Each data structure in the file (each element in the
tree) is a node, with a branch for each pointer in the data structure. The
file header is always the root node. Each of the three file organizations
(sequential, relative, and indexed) has its own tree structure.
The tree structures for sequential and relative files are shown in
Figures ARMS-1 and ARMS-2.

ARMS—2

ANALYZE/RMS-FILE
Description

Figure ARMS-1

Tree Structure for Sequential Files

ZK-327-81

Figure ARMS-2

Tree Structure for Relative Files

ZK-328-81

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.

ARMS—3

ANALYZE/RMS—FILE
Description

The full structure following the AREA DESCRIPTOR path is shown in
Figure ARMS-3.

Figure ARMS-3

AREA DESCRIPTOR Path

ZK-329-81

The structure following the KEY DESCRIPTOR path appears in
Figure ARMS-4.

ARMS—4

ANALYZE/RMS-FILE
Description

Figure ARMS-4

KEY DESCRIPTOR Path

ZK-330-81

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

ARMS—5

ANALYZE / RMS—FILE
Description

Figure ARMS-5

Structure of Primary Records

ZK-332-81

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 ARMS-6).
Figure ARMS-6

Data Buckets in the Alternate Index Structures

ZK-333-81

Using ANALYZE/RMS-FILE with DECnet-VAX
You can use the ANALYZE/RMS—FILE command over a network to analyze
the internal structure of a remote VAX RMS or RMS-11 file. This command
is, however, supported only for the examination of files generated by VAX
RMS or RMS-11. Otherwise, using ANALYZE/RMS—FILE over a network is
no different than using it on your home node. You can, for instance, specify
the /FDL command qualifier to generate an FDL (File Definition Language)
file from the data file. Using other command 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 command qualifiers in each command.
Remember that NETMBX privilege is required to execute ANALYZE/RMS—
FILE over a network.

ARMS-6

ANALYZE/RMS-FILE
Description

Handling Exception Conditions
If you receive any ANALYZE/RMS-FILE exception conditions, the file has
been corrupted by a serious error. If you have had a hardware problem (for
example, a power failure or a disk head crash), then the hardware may be
more likely to have caused the corruption. If you have not had any hardware
problems, then a software error may be more likely to have caused the
problem.
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 that you want, use the Backup Utility to restore the
backup copy of the file.
Also, if ANALYZE/RMS—FILE finds an error while you are analyzing your
file noninteractively, it returns the first error of the worst severity that it
discovers as the image exit status. In other words, 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.

ARMS—7

ANALYZE / RMS—FILE
Command Qualifiers

COMMAND
QUALIFIERS

ARMS—8

The ANALYZE/RMS—FILE command qualifiers allow you to choose which of
the five functions you want the utility to perform.

ANALYZE / RMS—FILE
/CHECK

/CHECK
Checks the integrity of the file and generates a report of any errors
in its structure.

FORMAT

/CHECK

qualifier values

None.

DESCRIPTION The report produced by the /CHECK qualifier includes a list of any errors

and a summary of the file's structure. If you do not specify an output file,
the report is written to the current SYS$OUTPUT device, which is generally
your terminal. You can use wildcards and multiple file specifications. If you
specify /NOOUTPUT, no report is generated. Instead, only the message
telling whether or not the file has errors is displayed.
The /CHECK function is the default when you issue the ANALYZE/RMS—
FILE command without any qualifiers. Do not use this qualifier with /FDL,
/INTERACTIVE, /STATISTICS, or /SUMMARY; the function of /CHECK
with these qualifiers is not compatible.

EXAMPLE
$ ANALYZE/RMS_FILE/CHECK CUSTFILE

This command checks the file CUSTFILE.DAT for errors. It displays the check
report on the terminal.

ARMS—9

ANALYZE/RMS-FILE
/FDL

/FDL
Generates an FDL file that describes the VAX RMS data file being
analyzed.

FORMAT

/FDL

qualifier values

None.

DESCRIPTION By default, the /FDL qualifier creates a file with the FDL file type and

the same file name as the input data file. To assign a different type or
name to the FDL file, use the /OUTPUT qualifier. If the data file has been
corrupted, then the FDL file generated will contain ANALYZE/RMS—FILE
error messages.
For indexed files, the FDL file contains special analysis sections that you
can use with the EDIT/FDL Optimize script to make better design decisions
when you reorganize the file. For more information on these special analysis
sections, refer to the descriptions of the ANALYSIS_OF_AREA and the
ANALYSIS_OF_KEY sections of the VAX/VMS File Definition Language
Facility Reference Manual.
You cannot use wildcards or multiple file specifications. Also, do not use this
qualifier with /CHECK, /INTERACTIVE, /STATISTICS, or /SUMMARY; the
functions of /FDL are incompatible with these qualifiers.

EXAMPLE
« ANALYZE/RMS.FILE/FDL ADDRFILE

This command generates an FDL file named ADDRFILE.FDL from the data
file ADDRFILE.DAT.

ARMS—10

ANALYZE/RMS—FILE
/INTERACTIVE

/INTERACTIVE
Begins an interactive examination of the file's structure. You cannot
use wildcards or multiple file specifications. For a list of interactive
commands, see the Command Section.

FORMAT

/INTERACTIVE

qualifier values

None.

EXAMPLE
$ ANALYZE/RMS.FILE/INTERACTIVE SUPPLIERS.DAT

This command begins an interactive session during which you can examine
the structure of the data file SUPPLIERS.DAT.

ARMS—11

ANALYZE/RMS—FILE
/OUTPUT

/OUTPUT
Identifies the output file in which to place the results of the analysis.

FORMAT

qualifier value

/OUTPUT /=output-file-spec]
/NOOUTPUT
output-file-spec
Identifies the output file in which to place the results of the analysis. The use
of the output file depends on which of the other qualifiers you specified.

DESCRIPTION

/CHECK

Places the integrity report in the output file. The default file
type is ANL, and the default file name is ANALYZE. If you
omit the output-file-spec parameter, output is written to the
current SYS$OUTPUT device, which is generally your terminal.

/FDL

Places the resulting FDL specification in the output file. The
default file type is FDL, and the default file name is that of the
input file.

/INTERACTIVE

Places a transcript of the interactive session in the output
file. The default file type is ANL, and the default file name
is ANALYZE. If you omit the output-file-spec parameter, no
transcript of your interactive session is produced.

/STATISTICS

Places the statistics report in the output file. The default file
type is ANL, and the default file name is ANALYZE. If you
omit the output-file-spec parameter, output is written to the
current SYS$OUTPUT device, which is generally your terminal.

/SUMMARY

Places the summary report in the output file. The default file
type is ANL, and the default file name is ANALYZE. If you
omit the output-file-spec parameter, output is written to the
current SYSSOUTPUT device, which is generally your terminal.

/NOOUTPUT specifies that no output is to be produced. However, a
message indicating whether or not the file has errors is still displayed.

EXAMPLES
Q

$ ANALYZE/RMS_FILE/STATISTICS/OUTPUT=.TXT SEQ.ADD

This command generates a statistics report named ANALYZE.TXT from the
data file SEQ.ADD.
E

$ ANALYZE/RMS_FILE/NOOUTPUT/CHECK PARTS_INVENTORY.DAT

This command checks the structure of the data file PARTS—
INVENTORY.DAT. No output is produced except the message telling whether
the data file had any errors.

ARMS—12

ANALYZE/RMS—FILE
/STATISTICS

/STATISTICS
Specifies that a report is to be produced containing statistics about
the file.

FORMAT

/STATISTICS

qualifier values

None.

DESCRIPTION

The /STATISTICS qualifier is used mainly on indexed files.
By default, if you do not specify an output file with the /OUTPUT qualifier,
the statistics report is written to the current SYS$ OUTPUT device, which is
generally your terminal.
Do not use this qualifier with /CHECK, /FDL, INTERACTIVE, or
/SUMMARY. The function of /STATISTICS is incompatible with these
qualifiers.

EXAMPLE
$ ANALYZE/RMS.FILE/STATISTICS SEQ.DAT

This command generates a statistics report from the data file SEQ.DAT and
displays the report on the current SYS$OUTPUT device (which is generally
your terminal).

ARMS—13

ANALYZE/RMS-FILE
/SUMMARY

/SUMMARY
Specifies that a summary report containing information about the
file's structure and use is to be produced.

FORMAT

/SUMMARY

qualifier values

None.

DESCRIPTION

The /SUMMARY qualifier generates a summary report containing information
about the file's structure and use.
If the file has no errors, the output generated from the /SUMMARY qualifier
is identical to that produced by the /CHECK qualifier. Unlike the /CHECK
qualifier, however, the /SUMMARY qualifier does not check the structure of
your file, so output is generated more quickly.
Do not use this qualifier with the /CHECK, /FDL, /INTERACTIVE, or
/STATISTICS qualifiers. The function of /SUMMARY is incompatible with
these qualifiers.

EXAMPLE
$ ANALYZE/RMS_FILE/SUMMARY INVENTORY.DAT

This command generates a summary report from the data file
INVENTORY.DAT and displays the report on the current SYS$OUTPUT
device (which is generally your terminal).

ARMS—14

ANALYZE/RMS-FILE
Commands

COMMANDS

To use the interactive mode, you issue commands to move the structure
pointer to nodes within the tree structure. The utility will display the contents
of the current node, changing its display as you change the current location.
Sessions always begin at the FILE HEADER.
From the header level, the first command to give is always the DOWN
command, which moves the current location to the FILE ATTRIBUTE level.
The DOWN command moves you down one level in the total structure, the
UP command moves you up one level, and the TOP command returns you
immediately to the FILE HEADER level from anywhere in the structure.
When the current location is set to a level with multiple nodes on it, you can
use the REST command to display the nodes in sequence, or you can use
the NEXT command to display them one at a time. The FIRST command
moves the current location back to the first structure on a level. The AGAIN
command displays the current structure again.
The DUMP command will display a hexadecimal dump of a specified bucket,
and the EXIT command ends the interactive session.

ARMS—15

ANALYZE/RMS—FILE
AGAIN

AGAIN
Displays the current structure one more time.

FORMAT

AGAIN

command
parameters
command
qualifiers

None.

EXAMPLE
FIXED PROLOG
Number of Areas: 8, VBN of First Descriptor: 3
Prolog Version : 3
ANALYZE> AGAIN
FIXED PROLOG
Number of Areas: 8, VBN of First Descriptor: 3
Prolog Version : 3

This command displays the current structure one more time.

ARMS—16

ANALYZE / RMS—FILE
BACK

BACK
Moves the structure pointer to the previous node if one exists within
the current level, and displays that node.

FORMAT
command
parameter
command
qualifiers

BACK [n]
n
Specifies the number of structures that the pointer is to be moved backward.

None.

DESCRIPTION You can use the optional parameter n instead of typing many BACK

commands. For example, the command BACK 6 has the same effect as
six consecutive BACK commands.

EXAMPLES
Q

ANALYZE> BACK

This command positions you at the previous node of the level you are
currently examining. For example, if you are examining the second key
descriptor of your primary key, this command positions you at, and displays,
the primary key descriptor.
0

ANALYZE> BACK 3

This command positions you at the third node back from the one that you are
examining without displaying the intermediate nodes.

ARMS—17

ANALYZE/RMS-FILE
DOWN

DOWN
Moves the structure pointer down to the next level.

FORMAT
command
parameter

DOWN [branch]

branch
Specifies the branch that you wish to follow if the current node has more
than one branch. ANALYZE/RMS_FILE prompts you with a list of possible
branches if you do not specify a required branch value.
You can also use a question mark after the DOWN command to obtain a list
of the possible branches see Examples.

command
qualifiers

None.

EXAMPLE
ANALYZE> DOWN ?
'/, ANLRMS -1 - DOWNHELP, The following is a list of paths down from this structure:
•/.ANLRMS-I-DOWNPATH, AREAS
Area descriptors
%ANLRMS-I-DOWNPATH, KEYS
Key descriptors
ANALYZE> DOWN AREAS
AREA DESCRIPTOR #0 (VBN 3. offset ‘/.X'OOOO')
Bucket Size: 1
Reclaimed Bucket VBN: 0
Current Extent Start: 1, Blocks: 9, Used: 4, Next: 5
Default Extend Quantity: 2
Total Allocation: 9

This command first displays the available branches or paths you can follow
from your current position in the file structure. In this case, you can either
examine areas or keys.
After you have specified that you want to examine the area descriptors of
your file, ANALYZE/RMS—FILE displays information about the first area.

ARMS—18

ANALYZE/RMS-FILE
DUMP

DUMP
Displays a hexadecimal dump of the specified virtual block.

FORMAT

DUMP

command
parameter

Specifies the virtual block number of which you want a dump. The number
can be decimal or hexadecimal. The format for a hexadecimal number is
%Xnumber.

command
qualifiers

None.

EXAMPLE
ANALYZE> DUMP 10
DUMP OF VIRTUAL BLOCK 10:
7 6 5 4 3 2
73
65
20
20
66
64
20
2F
45
68
2D
31
69
52

20
72
75
65
20
6F
79
45
4C
74
72
31
74
2E

73
75
6F
73
4C
72
62
5A
49
20
65
2D
75
73

27
74
59
75
44
70
20
59
46
68
68
58
20
65

65
63
00
20
46
20
64
4C
5F
74
74
41
53
69

6C
75
43
6E
20
65
65
41
53
69
6F
56
4D
74

69
72
00
61
6E
6C
63
4E
4D
77
20
00
52
69

661
741
2E|
631
611
691
751
411
521
201
651
151
201
6C|

01234567
0000
0008
0010
0018
0020
0028
0030
0038
0040
0048
0050
0058
0060
0068

Ifile's s
1tructure
1..C.You
lean use
Ian FDL f
lile prod
luced by
1 ANALYZE/
1RMS.FILE
1 with th
|e other1..VAX-11
1 RMS uti
Ilities.R

This command shows the first part of a dump of virtual block number (VBN)
10. The left column shows the bytes of the block in hexadecimal, read from
right to left. The middle column shows the byte offset in hexadecimal from
the beginning of the blocks. In the right column, the character equivalents of
each byte are displayed. Nonprintable characters are represented by a
period (.).

ARMS—19

ANALYZE/RMS—FILE
EXIT

EXIT
Ends the interactive session.

FORMAT

EXIT

command
parameters

None.

command
qualifiers

None.

EXAMPLE
ANALYZE> EXIT

$
This command terminates the interactive session and returns you to the DCL
command level.

ARMS—20

ANALYZE/RMS-FILE
FIRST

FIRST
Moves the structure pointer to the first node on the current level and
displays the node.

FORMAT

FIRST

command
parameters
command
qualifiers

None.
None.

EXAMPLE
ANALYZE> FIRST

This command returns you to the first node of the level you are currently
examining. For example, if you are examining the primary and alternate
key descriptors, this command positions you at, and displays, the first key
descriptor.

ARMS—21

ANALYZE/RMS-FILE
HELP

HELP
Displays help information about the interactive commands.

FORMAT

HELP [keyword...]

command
parameter

Specifies the interactive command about which you want more information.

keyword

command
qualifiers

None.

EXAMPLE
ANALYZE> HELP
Information available:
AGAIN
FIRST
REST

BACK
HELP
TOP

DOWN
DUMP
New_features
UP

EXIT
NEXT

File_Structure
POSITION
Radix

Topic? AGAIN
AGAIN
This command displays the current structure one more time.
Topic?

This command shows the available help topics. It then displays the help
information about the interactive command AGAIN.

ARMS—22

ANALYZE/RMS-FILE
NEXT

NEXT
Moves the structure pointer to the next node if one exists within the
current level, and then displays that node. Since NEXT is the default
command, pressing the RETURN key is equivalent to executing a
NEXT command.

FORMAT

NEXT [n]

command
parameter

Specifies the number of structures that the pointer is to be moved forward

command
qualifiers

None.

DESCRIPTION

You can use the optional parameter n instead of typing many NEXT
commands. For example, the command NEXT 6 has the same effect as
six consecutive NEXT commands (or six consecutive RETURNs).

EXAMPLES
Q

ANALYZE> NEXT

This command positions you at the next node of the level you are currently
examining. For example, if you are examining your primary and alternate
key descriptors, this command positions you at, and displays, the next key
descriptor.
0

ANALYZE> NEXT 3

This command positions you three nodes from the one that you are
examining, without displaying the intermediate nodes. For example, if you
were at the first node, then giving this command (NEXT 3) would position
you at and display the fourth node.

ARMS—23

ANALYZE/RMS-FILE
POSITION/BUCKET

POSITION/BUCKET
Positions the pointer to a specific bucket of an indexed or relative
file.

FORMAT
command
parameter

command
qualifiers

POSITION/BUCKET

bucket—vbn [/INDEX =n]

bucket—vbn
The virtual block number (VBN) of the bucket at which the pointer is to be
positioned. If the bucket has a length greater than one block, use the VBN of
the beginning of the bucket.

[/ll\IDEX=n]
Specifies the relative key for the bucket for an indexed file. This qualifier
is necessary only when the index number information is unavailable in the
bucket header. For example, you would use this qualifier if you are analyzing
a PROLOG 1 or 2 file, if the bucket header in a PROLOG 3 file has been
corrupted, or if you wanted to override the index number in a PROLOG 3 file
bucket header.
The number that you use specifies the key. For example, /INDEX=0 specifies
that the bucket is a primary index or primary data bucket, and /INDEX=1
specifies that the bucket is found in the first alternate index structure.

DESCRIPTION The POSITION/BUCKET command lets you position the pointer to a specific
bucket of your file. You can use this command to bypass the step-by-step
positioning, and you can also use it to position the pointer at a bucket that
would otherwise be inaccessible due to structural errors in the file.

Once you are positioned at the beginning of the bucket, you can step forward
or down through the index structure using the NEXT or DOWN commands.
However, if you issue an UP command when positioned at the beginning of
the bucket, the pointer will go to the key descriptor of the bucket. If you issue
a BACK command, an error message is displayed and the pointer remains at
the beginning of the bucket.
Using the POSITION/BUCKET command allows you to specify a particular
bucket header, from which key descriptor and valid path information are
derived. However, no check is made to verify that the VBN you specify is, in
fact, the beginning block of a bucket. If a series of error messages is displayed
after you issue the POSITION/BUCKET command, it is probably due either
to specifying a VBN that is not a beginning of a bucket, or specifying an
incorrect index number with the /INDEX qualifier.

ARMS—24

ANALYZE/RMS—FILE
POSITION/BUCKET

EXAMPLE
ANALYZE> POSITION/BUCKET 4
BUCKET HEADER (VBN 4)
Check Character: 7.X'93'
Key of Reference: 0
VBN Sample: 4
Free Space Offset: 7,X'0055'
Free Record ID: 24
Next Bucket VBN: 36
Level: 0
Bucket Header Flags:
(0)
BKT$V_LASTBKT
0

This command positions you at VBN 4, and displays the information for the
bucket that begins at that VBN. The /INDEX=n qualifier is not used because
the file is PROLOG 3 and, therefore, that information is already available in
the bucket header (Key of Reference: 0).

ARMS—25

ANALYZE/RMS-FILE
POSITION/RECORD

POSITION/RECORD
Positions the pointer at a specific record in an indexed or relative
file.

FORMAT

POSITION/RECORD record-offset

command
parameter

record-offset
The offset (in bytes) from the beginning of the current bucket to the desired
record. By default, the offset that you use is a decimal number. If you wish
to use hexadecimal notation to specify the record offset, use the format %Xn.

command
qualifiers

None.

DESCRIPTION Use this command to position the pointer at a specific record in the current
bucket. Once you are positioned at the record, you can move down and
forward through structures; however, you cannot move to previous records
within that bucket.

This command positions the pointer at the byte-offset specified, whether or
not that position is, in fact, the beginning of a valid record. If it is not at the
beginning of a valid record, a series of error messages will be generated. The
POSITION/RECORD command is valid only when you are positioned at a
bucket header.

EXAMPLE
ANALYZE> POSITION/RECORD %XE
PRIMARY DATA RECORD (VBN 4. offset 7.X'OOOE')
Record Control Flags:
(2)
IRC$V_DELETED
0
(3)
IRC$V_RRV
0
(4)
IRC$V_NOPTRSZ
0
(5)
IRC$V_RU_DELETE 0
(6)
IRC$V_RU_UPDATE 0
Record ID: 11
RRV ID: 11, 4-Byte Bucket Pointer: 4
Key:
76543210
00 00 00 00 00 00 00 021

0000

01234567
I.I

This command positions you at byte-offset %XE, which is the location of
the beginning of a record. This command was valid because the pointer
was positioned at a bucket header before the POSITION/RECORD %XE
command was issued.

ARMS—26

ANALYZE/RMS—FILE
REST

REST
Moves the structure pointer along the remainder of the nodes on the
current level, and displays each in turn.

FORMAT

REST

command
parameters
command
qualifiers

None.

EXAMPLE
ANALYZE> REST

This command positions you at each successive node of the structure you are
currently examining. For example, suppose you are examining your primary
and alternate key descriptors. The REST command positions you at and
displays each key descriptor, and it then moves on to the next key descriptor,
if it exists.

ARMS—27

ANALYZE/RMS-FILE
TOP

TOP
Moves the structure pointer up to the file header. The file header is
displayed.

FORMAT

TOP

command
parameters

None.

command
qualifiers

None.

EXAMPLE
ANALYZE> TOP
FILE HEADER
File Spec: DISK$:[JONES.PROGRAM]INVENTORY.DAT;6
File ID: (6367,16,1)
Owner UIC: [277,377]
Protection: System: RWE, Owner: RWED, Group: R, World:
Creation Date:
5-JUL-1986 09:10:29.83
Revision Date:
5-JUL-1986 09:10:37:16, Number: 4
Expiration Date: none specified
Backup Date:
none posted
Contiguity Options:
none
Performance Options: none
Reliability Options: none

This command positions you at and displays the file header of your file.

ARMS—28

AN ALYZE / RMS-FILE
UP

UP
Moves the structure pointer up to the next higher level. The node at
that level is displayed.

FORMAT

command
parameters

None.

command
qualifiers

None.

EXAMPLE
ANALYZE> UP

This command positions you at the next higher level of the file's structure.
For example, if you are currently examining the RMS FILE ATTRIBUTES
level, issuing the UP command positions you at the FILE HEADER level and
displays that level.

ARMS—29

ANALYZE/RMS-FILE
Examples

EXAMPLES
□

$ ANALYZE/RMS_FILE/INTERACTIVE/OUTPUT=INVENTORY INVENTORY.DAT

This command begins an interactive session during which you can examine
the structure of the data file INVENTORY.DAT. A transcript of the session is
placed in the output file INVENTORY.ANL.
S

$ ANALYZE/RMS.FILE/NOOUTPUT *.*;*

This command verifies the structural integrity of all files in the current default
directory.
E

$ ANALYZE/RMS.FILE/FDL PARTS.DAT

This command produces the FDL file PARTS.FDL from the data file
PARTS.DAT. Assuming that PARTS.DAT is an indexed file, the new FDL
file contains two special sections—ANALYSIS_OF_AREA and ANALYSIS—
OF—KEY—that FDL files created with the Edit/FDL Utility do not have.
These sections can be used with the EDIT/FDL Optimize script to tune your
original data file PARTS.DAT. To complete the tuning cycle, you would issue
the following commands:
EDIT/FDL/ANALYSIS=PARTS/SCRIPT=OPTIMIZE PARTS
CONVERT/FDL=PARTS PARTS.DAT *
2

$ ANALYZE/RMS.FILE DENVER::DB1:[PROD]RUN.DAT

This command analyzes the structure of the file RUN.DAT residing at remote
node DENVER.
E

$ ANALYZE/RMS_FILE/FDL/OUTPUT=TEST.FDL
$_File(s): DENVER::DB1:[PROD]RUN.DAT

This command analyzes the structure of the file RUN.DAT at remote node
DENVER and generates the FDL file TEST.FDL at the local node.

ARMS—30

Index

A
AGAIN command •ARMS-15, ARMS-16
ALTERNATE DATA RECORD node* ARMS-5
Alternate index structure • ARMS-3
Alternate key*ARMS-6
Alternate record • ARMS-6
Analysis sections
FDL* ARMS-10
ANALYZE/RMS—FILE
See Analyze/RMS_File Utility
Analyze/RMS_File Utility (ANALYZE/RMS_FILE)
analyzing file structure interactively • ARMS-2
creating FDL files* ARMS-2
directing output • ARMS-1
examples
analyzing a file interactively • ARMS-30
analyzing a remote file* ARMS-30
creating an FDL file* ARMS-30
creating an FDL file from a remote file*
ARMS-30
exception conditions • ARMS-7
exiting from • ARMS-1
invoking • ARMS-1
restrictions • ARMS-2
with DECnet-VAX* ARMS-6
ANALYZE default file name* ARMS-12
ANL file type* ARMS-12
AREA DESCRIPTOR node* ARMS-3, ARMS-4

B
BACK command • ARMS-17
Branch
within tree structure • ARMS-2
Bucket* ARMS-3
examining • ARMS-5
split • ARMS-5

c
Cell* ARMS-3
/CHECK qualifier* ARMS-9

Command
interactive • ARMS-15
Corrupted file* ARMS-10

D
Data
corruption • ARMS-10
Data record • ARMS-5
DATA RECORD node* ARMS-5
Data structure* ARMS-2
DAT file type* ARMS-1
DECnet-VAX
using the Analyze/RMS_File Utility with*
ARMS-6
Default output
AN ALYZE/RMS_FILE • ARMS-12
DOWN command* ARMS-15, ARMS-18
Dump
hexadecimal* ARMS-15, ARMS-19
DUMP command* ARMS-15, ARMS-19

E
Error
in file structure • ARMS-9
Example
analyzing a file interactively • ARMS-30
analyzing a remote file* ARMS-30
creating an FDL file* ARMS-30
creating an FDL file from a remote file* ARMS30
Exception conditions* ARMS-7
EXIT command • ARMS-20
Exiting from ANALYZE/RMS_FILE • ARMS-1

F
FDL (File Definition Language)
file type • ARMS-12
FDL file
ANALYZE/RMS_FILE • ARMS-10
creating • ARMS-1

Index—1

Index

FDL file (cont'd.)
creation of • ARMS-10
/FDL qualifier
AN ALYZE/RMS_FILE • ARMS-10
File
analysis* ARMS-1
corrupted • ARMS-10
creating FDL files* ARMS-1
integrity • ARMS-9
internal structure • ARMS-2
organization • ARMS-2
tree structure of*ARMS-2
FILE ATTRIBUTES node* ARMS-4, ARMS-15
File Definition Language
See FDL
File header* ARMS-2
FILE HEADER node*ARMS-4
File structure* ARMS-2
analyzing interactively • ARMS-2
examining • ARMS-11
File type
ANL* ARMS-12
DAT* ARMS-1
FDL* ARMS-12
FIRST command* ARMS-15, ARMS-21
Format
of hexadecimal • ARMS-19

H
HELP command • ARMS-22
Hexadecimal dump* ARMS-15, ARMS-19
Hierarchical tree structure • ARMS-2

i
Indexed file
structure • ARMS-3
tree structure* ARMS-2
INDEX RECORD node* ARMS-5
INDEX ROOT BUCKET node* ARMS-5
Integrity of file • ARMS-9
Interactive commands • ARMS-15
Interactive mode* ARMS-1, ARMS-2, ARMS-11,
ARMS-15
/INTERACTIVE qualifier• ARMS-2, ARMS-11
Internal structure
of file* ARMS-2
Invoking ANALYZE/RMS_FILE • ARMS-1

Index—2

K
KEY DESCRIPTOR node*ARMS-3, ARMS-5

INI
NEXT command • ARMS-15, ARMS-23
Node
within tree structure* ARMS-2, ARMS-15
/NOOUTPUT qualifier* ARMS-12

o
Organization
tree* ARMS-2
Output
directing* ARMS-1
/OUTPUT qualifier* ARMS-12

p
Pointer
structure • ARMS-15
POSITION/BUCKET command • ARMS-24
POSITION/RECORD command • ARMS-26
Primary data record • ARMS-5
PRIMARY DATA RECORD node* ARMS-5
Primary index structure* ARMS-3
Prolog
relative file • ARMS-3
PROLOG node • ARMS-4

R
RECLAIMED BUCKET node* ARMS-4
Record • ARMS-5
Record structure* ARMS-5
Relative file
structure • ARMS-3
tree structure • ARMS-2
REST command* ARMS-15, ARMS-27
Restrictions of ANALYZE/RMS_FILE • ARMS-2
Root node* ARMS-2

Index

_ w
s
RRV (record reference vector) • ARMS-5

Wildcard character
using with Analyze/RMS_File* ARMS-1

Sequential file
tree structure • ARMS-2
SIDR (secondary index data record) • ARMS-6
Special analysis sections • ARMS-10
Statistical report • ARMS-1
/STATISTICS qualifier
AN ALYZE/RMS_FILE • ARMS-13
Structure
error* ARMS-9
examining* ARMS-11
indexed file* ARMS-3
of file* ARMS-1, ARMS-2
pointer* ARMS-15
relative file* ARMS-3
sequential file* ARMS-2
/SUMMARY qualifier
ANALYZE/RMS—FILE • ARMS-14
Summary report • ARMS-1
SYSSOUTPUT • ARMS-12

x
%X format* ARMS-19

TOP command* ARMS-15, ARMS-28
Tree structure • ARMS-2, ARMS-15
indexed • ARMS-3
relative* ARMS-3
sequential • ARMS-2

UP command* ARMS-15, ARMS-29

VBN
See Virtual block number
Virtual block
dump* ARMS-19
Virtual block number • ARMS-3

Index-3

VAX/VMS
Analyze/RMS_File
Utility Reference Manual
AA-Z404B-TE

READER'S
COMMENTS

Note: This form is for document comments only. DIGITAL will use comments
submitted on this form at the company's discretion. If you require a written reply
and are eligible to receive one under Software Performance Report (SPR) service,
submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
□
□
□
□
□
□

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _

Name _Date_
Organization _
Street _
City _State_Zip Code_
or Country

Do Not Tear - Fold Here and Tape
No Postage
Necessary
if Mailed in the
United States

GUDDSD
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

.1,11
Do Not Tear - Fold Here

Cut Along Dotted Line

- — —

BUSINESS REPLY MAIL

VAX/VMS
Analyze/RMS_File
Utility Reference Manual
AA-Z404B-TE

READER'S
l*UIVIIVIClM I O

Note: This form is for document comments only. DIGITAL will use comments
submitted on this form at the company's discretion. If you require a written reply
ancj are eligible to receive one under Software Performance Report (SPR) service,
submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
□
□
□
□
□
□

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _

Name _Date_
Organization _
Street _
City _State_Zip Code_
or Country

—

Do Not Tear - Fold Here and Tape

No Postage

SDSDDSD

Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

III.IMLJIhhI.II.M.ImI.MI.1,11
—

—

Do Not Tear - Fold Here

Cut Along Dotted Line