Document revision date: 19 July 1999

Ends an interactive session.

Format

EXIT

Example

ANALYZE> EXIT
$
 
      

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

Displays the first structure on the current level.

Format

FIRST

Example

ANALYZE> FIRST
 
      

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

Displays help information about the interactive commands.

Format

HELP [keyword...]

Parameter

keyword

Specifies the interactive command you want help with.

Examples

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.

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

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.

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

ANALYZE> NEXT
 
      

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.

ANALYZE> NEXT 3
 
      

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.

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

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.

Sequentially displays structures at the current level.

Format

REST

Example

ANALYZE> REST
 
      

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.

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.

Displays the data structures at the next higher level.

Format

UP

Example

ANALYZE> UP
 
      

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

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

$ ANALYZE/RMS_FILE/NOOUTPUT *.*;*
 
      

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

$ 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 *

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

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

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

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.

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.

	privacy and legal statement
6027PRO_002.HTML