OpenVMS Record Management Utilities Reference
Manual
EXIT
Ends an interactive session.
Format
EXIT
Example
This command terminates the interactive session and returns you to the
DCL level.
FIRST
Displays the first structure on the current level.
Format
FIRST
Example
If you are examining the primary and alternate key descriptors, this
command displays the first key descriptor.
HELP
Displays help information about the interactive commands.
Format
HELP [keyword...]
Parameter
keyword
Specifies the interactive command you want help with.
Examples
| #1 |
ANALYZE> HELP
Information available:
AGAIN BACK DOWN DUMP EXIT File_Structure
FIRST HELP New_features NEXT POSITION Radix
REST TOP UP
|
This command shows the available help topics.
| #2 |
Topic? AGAIN
AGAIN
This command displays the current structure one more time.
Topic?
|
This command displays information about the AGAIN command.
NEXT
Displays the next structure at the current level, if one exists.
Because NEXT is the default command, pressing the Return key is
equivalent to executing a NEXT command.
Format
NEXT [n]
Parameter
n
Specifies the number of times the structure pointer moves forward.
Description
You can use the optional parameter n instead of entering
multiple NEXT commands. For example, the command NEXT 6 has the same
effect as six NEXT commands (or pressing the Return key six times).
Examples
This command displays the next structure at the current level. For
example, if you are viewing key descriptors, this command displays the
next key descriptor.
This command moves the location pointer forward three times. For
example, if you are viewing the first structure at the current level,
this command displays the fourth structure.
POSITION/BUCKET
Directly positions the structure pointer to a specific bucket of an
indexed file or a relative file.
Format
POSITION/BUCKET bucket_vbn [/INDEX=n]
Parameter
bucket_vbn
The virtual block number (VBN) of the selected bucket. If the bucket
includes more than one block, specify the VBN of the first block.
Qualifier
/INDEX=n
Specifies the relative key for the bucket of an indexed file. The
/INDEX qualifier is necessary only when the index number information is
unavailable in the bucket header. For example, you use this qualifier
to analyze a Prolog 1 or Prolog 2 file (no bucket header) or a Prolog 3
file with a corrupted bucket header. You can also use this qualifier to
override the index number in a Prolog 3 file bucket header.
The number 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 structure pointer to
a specific bucket of your file. You can use this command to bypass
step-by-step positioning. You can also use it to position the structure
pointer at a bucket that is inaccessible because of structural errors
in the file.
When the structure pointer is positioned at the beginning of the
bucket, you can step forward or down through the index structure using
the NEXT or DOWN command. If you enter an UP command when the structure
pointer is positioned at the beginning of the bucket, the
Analyze/RMS_File utility positions the pointer to the bucket's key
descriptor. If you enter a BACK command when the structure pointer is
positioned at the beginning of the bucket, the Analyze/RMS_File utility
displays an appropriate error message and the pointer remains
stationary.
Using the POSITION/BUCKET command allows you to specify a particular
bucket header from which key descriptor information and valid path
information are derived. The Analyze/RMS_File utility does not verify
that the specified VBN is at the beginning block of a bucket. If the
Analyze/RMS_File utility displays a series of error messages when you
enter the POSITION/BUCKET command, it may be that the structure pointer
is not positioned at the beginning of the bucket, or it may be that you
specified an incorrect index number with the /INDEX qualifier.
Example
|
ANALYZE> POSITION/BUCKET 4
BUCKET HEADER (VBN 4)
Check Character: %X'93'
Key of Reference: 0
VBN Sample: 4
Free Space Offset: %X'0055'
Free Record ID: 24
Next Bucket VBN: 36
Level: 0
Bucket Header Flags:
(0) BKT$V_LASTBKT 0
|
This command displays the information for the bucket that begins at
VBN4. Because this is a Prolog 3 file, you do not have to specify the
key using the /INDEX=n qualifier. In a Prolog 3 file, the key
information is available in the bucket header (Key of Reference: 0).
POSITION/RECORD
Positions the pointer at a specific record in an indexed or relative
file.
Format
POSITION/RECORD record-offset
Parameter
record-offset
The offset (in bytes) from the beginning of the bucket to the desired
record. By default, the offset is a decimal number. If you want to use
hexadecimal notation to specify the offset, use the format %Xn.
Description
Use this command to display a specific record in the bucket. When the
structure pointer is positioned at the desired record, you can move it
down and forward to display the various records in the bucket; you
cannot display previous records.
The POSITION/RECORD command is valid only when you are positioned at a
bucket header. The command positions the structure pointer at the
specified byte offset. If the pointer is not positioned at the
beginning of a valid record, a series of error messages is generated.
Example
|
ANALYZE> POSITION/RECORD %XE
PRIMARY DATA RECORD (VBN 4, offset %X'000E')
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:
7 6 5 4 3 2 1 0 01234567
------------------------ --------
00 00 00 00 00 00 00 02| 0000 |........|
|
This command positions the pointer at byte offset %XE, which is the
location of the beginning of a record. This command is valid because
the pointer was positioned at a bucket header before the
POSITION/RECORD %XE command was entered.
REST
Sequentially displays structures at the current level.
Format
REST
Example
This command displays each structure at the current level. For example,
if you are viewing the primary and alternate key descriptors, the REST
command displays each key descriptor sequentially.
TOP
Displays the FILE HEADER level.
Format
TOP
Example
|
ANALYZE> TOP
FILE HEADER
File Spec: DISK$:[JONES.PROGRAM]INVENTORY.DAT;6
File ID: (6367,16,1)
Owner UIC: [DOC,DOE]
Protection: System: RWE, Owner: RWED, Group: R, World:
Creation Date: 13-NOV-1993 09:10:29.83
Revision Date: 16-DEC-1993 14:10:37:16, Number: 4
Expiration Date: none specified
Backup Date: none posted
Contiguity Options: none
Performance Options: none
Reliability Options: none
Journaling Enabled: none
|
This command displays the file header information for the file
INVENTORY.DAT.
UP
Displays the data structures at the next higher level.
Format
UP
Example
This command positions the pointer at the next higher level of the
file's structure. For example, if you are currently examining the RMS
FILE ATTRIBUTES level, entering the UP command positions you at the
FILE HEADER level and displays that level.
ANALYZE/RMS_FILE Examples
| #1 |
$ 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.
| #2 |
$ ANALYZE/RMS_FILE/NOOUTPUT *.*;*
|
This command verifies the structural integrity of all files in the
current default directory.
| #3 |
$ 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 that FDL files created with the Edit/FDL
utility do not have: ANALYSIS_OF_AREA and ANALYSIS_OF_KEY. You can use
these sections with
the EDIT/FDL Optimize script to tune your original data file,
PARTS.DAT. To complete the tuning cycle, enter the following DCL
commands:
$ EDIT/FDL/ANALYSIS=PARTS/SCRIPT=OPTIMIZE PARTS
$ CONVERT/FDL=PARTS PARTS.DAT *
|
| #4 |
$ ANALYZE/RMS_FILE DENVER::DB1:[PROD]RUN.DAT
|
This command analyzes the structure of the file RUN.DAT residing at
remote node DENVER.
| #5 |
$ 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.
Chapter 2
Convert Utility
The Convert utility (CONVERT) can be used to reorganize files by
copying records from one or more source files to an output file, while
converting the records to be compatible with the output file's
organization and record format.
You can also use the Convert utility to improve the efficiency of
indexed files that have had many record deletions and insertions by
reformatting the file. In this case, the input file and the output file
use the same file name and have the same organization, but the output
file's version number is one greater than the highest previous version
of the input file. When it reorganizes an indexed file, the utility
establishes new record file addresses (RFAs) and may reorder duplicate
records along secondary keys.
You can use callable routines to perform the functions of the Convert
utility from within a program. For more information, refer to the the
Convert utility routines in the OpenVMS Utility Routines Manual.
On Alpha systems, the Convert utility and its qualifiers contain
capabilities that allow them to use the features provided by extended
file specifications. Extended file specifications offers extended file
naming and handling capabilities that enable OpenVMS Alpha systems to
store, manage, serve, and access files across both 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.
This chapter tells you how to use the Convert utility. Section 2.1
explains how to produce converted output files with the utility.
Section 2.2 describes converting between carriage control formats.
Section 2.3 discusses using the Convert utility with DECnet for
OpenVMS operations. Section 2.4 explains how to handle the Convert
utility exception conditions.
2.1 Output Files
There are two ways to use the Convert utility to reorganize a file:
- You can reorganize the input file to be organized like an existing
output file.
- You can reorganize the input file in a new file. If you want the
new file to be organized differently from the input file, use a File
Definition Language (FDL) file to specify the characteristics for the
new file. If you want the new file to be organized the same as the
input file, do not use an FDL file to create the new file.
Note
If you specify an input FDL file that uses a collating sequence from
the local system's National character set (NCS) library, be sure that
the collating sequence does not have the same name as the collating
sequence from the input index file. If the two collating sequences have
the same name, the output file might be sorted improperly.
Typically, this might happen when the input indexed file is created on
one system and is later transported to another system that already has
a collating sequence with the same name. Both NCS and RMS use collating
sequences that are identified by a character string that is processed
as part of the named collating sequence. You can avoid this problem by
renaming collating sequences that have conflicting names.
(For more information about NCS, see the OpenVMS National Character Set Utility Manual.)
|
You can use an existing output file that has records or an output file
that has no records. If the output file is sequential, specifying the
/APPEND qualifier causes the converted records from the input file to
be added sequentially to the end of the output file. Note that the
/APPEND qualifier is ignored if the output file is formatted for direct
access; that is, either a relative file or an indexed file. If the
output file is indexed and contains records, you can use the /MERGE
qualifier to insert the new records in their proper order.
Sorting the records from an input file can be costly in terms of
processing time and disk space. If the records in the output file are
to be ordered in
the same manner as the input file records, use the /NOSORT qualifier to
save processing time and space. For more information about sorting
indexed files, see both the /FAST_LOAD and the /SORT qualifiers in the
CONVERT Qualifiers section.
RMS appends records with duplicate key values to the end of a list of
duplicate keys so that the records are retrieved in chronological
order. However, the Convert utility does not preserve chronological
order for secondary keys. Instead, records having duplicate secondary
keys are reordered and retrieved by the collating value of the primary
key. For example, assume that you have a file of names that uses the
primary key (Key0) FIRST_NAME and a secondary key (Key1) LAST_NAME.
Assume,
too, that the application program inserts a group of records in the
following order:
Key0 Key1
. .
John Jones
Martin Smith
David Jones
Joseph Brown
Gary Adams
Adam Jones
. .
|
When an application program accesses the records sequentially by the
secondary key (Key1), the records are retrieved in the following order:
Key0 Key1
. .
Gary Adams
Joseph Brown
John Jones
David Jones
Adam Jones
Martin Smith
. .
|
When an application program accesses the records sequentially by the
secondary key (Key1) after the file is converted, the records are
retrieved in the following order:
Key0 Key1
. .
Gary Adams
Joseph Brown
Adam Jones
David Jones
John Jones
Martin Smith
. .
|
Note the revised order of retrieval for the people named Jones.
2.2 Converting Carriage Control Formats
A file can have one of four carriage control formats:
- CARRIAGE_RETURN
- FORTRAN
- PRINT
- NONE
These formats are all represented differently, so when you are
converting a file from one carriage control format to another, the
carriage control information has to be translated.
Translation is especially important when you are converting to or from
a file with the FORTRAN format. Records with the FORTRAN format contain
one byte of carriage control information at the beginning of each
record.
For most conversions, the FORTRAN carriage control information is
preserved as the first data byte of the record, and the printing
characteristics are lost. However, certain conversions can preserve the
printing characteristics of the FORTRAN carriage control information.
When FORTRAN carriage control is converted to the equivalent PRINT
carriage control, the information preceding each FORTRAN record is
changed but not lost.
When PRINT carriage control is converted to FORTRAN carriage control,
certain characters that supply carriage control information to the
printer cannot be translated exactly. These untranslatable characters
are represented as a single-spaced FORTRAN record.
When FORTRAN carriage control is converted to STREAM, control
characters affecting carriage returns (<CR>), line feeds
(<LF>), and form feeds (<FF>) are prefixed and appended to
each FORTRAN record. These characters may affect the STREAM output
because they are considered record delimiters for stream files. As a
result, you may have a different number of records in the STREAM output
file, and some of the records may be null.
The following table shows how FORTRAN carriage control information
translates to STREAM.
| |
STREAM Format Equivalent |
FORTRAN
Format |
Characters
Prefixed |
Characters
Appended |
|
1
|
<FF>
|
<CR>
|
|
0
|
<LF><LF>
|
<CR>
|
|
space
|
<LF>
|
<CR>
|
|
$
|
<LF>
|
Nothing appended
|
|
+
|
Nothing prefixed
|
<CR>
|
|
null
|
Nothing prefixed
|
Nothing appended
|
All other conversions from FORTRAN preserve the carriage
control information as data. All other conversions to FORTRAN
prefix the converted records with the ASCII space character to obtain
single spacing.
For more information about carriage control, see the description of the
File Definition Language (FDL) in Chapter 4.
|
