Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Record Management Utilities Reference Manual

Previous Contents Index


Ends an interactive session.





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


Displays the first structure on the current level.





If you are examining the primary and alternate key descriptors, this command displays the first key descriptor.


Displays help information about the interactive commands.


HELP [keyword...]



Specifies the interactive command you want help with.



  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.


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

This command displays information about the AGAIN command.


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.


NEXT [n]



Specifies the number of times the structure pointer moves forward.


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




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.


Directly positions the structure pointer to a specific bucket of an indexed file or a relative file.





The virtual block number (VBN) of the selected bucket. If the bucket includes more than one block, specify the VBN of the first block.



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.


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.


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


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


POSITION/RECORD 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.


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.


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


Sequentially displays structures at the current level.





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.


Displays the FILE HEADER level.




        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.


Displays the data structures at the next higher level.





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.




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.



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



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:




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



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:

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:


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:

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

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement