Document revision date: 19 July 1999

The Analyze/RMS_File utility (ANALYZE/RMS_FILE) allows you to examine the internal structure of an RMS file by performing the following functions:

• Checking the structure of a file for errors.
• Generating a statistical report on the file's structure and use.
• Entering an interactive mode through which you can explore a file's structure. This analysis can determine whether the file is properly designed for its application and can point out improvements to make in the file's File Definition Language (FDL) specification.
• Generating an FDL file from a data file.
• Generating a summary report on the file's structure and use.
• Generating information related to the file's journaling status.

Format

ANALYZE/RMS_FILE filespec[,...]

filespec[,...]

Specifies the data file to be analyzed. The default file type is .DAT. You can use multiple file specifications and wildcard characters with the /CHECK qualifier, the /RU_JOURNAL qualifier, the /STATISTICS qualifier, and the /SUMMARY qualifier, but not with the /FDL qualifier or the /INTERACTIVE qualifier.

Invoke the utility by entering the ANALYZE/RMS_FILE command at the DCL command level. This command can perform only one of the utility functions at a time; in other words, you must enter a new ANALYZE/RMS_FILE command each time you choose a different function.

If you specify the /INTERACTIVE qualifier, exit the Analyze/RMS_File utility by entering the EXIT command. Otherwise, let the utility run to successful completion.

If the Analyze/RMS_File utility terminates with an error message, you should try converting the file and then running the utility again. If the error condition persists, verify the integrity of the hardware and software. If the hardware and software appear to be functioning properly, submit a Software Performance Report (SPR) about the condition.

You can control the Analyze/RMS_File utility output by using the /OUTPUT qualifier. For a more detailed explanation of the /OUTPUT qualifier, refer to the ANALYZE/RMS_FILE Qualifiers section.

During the time that you are using the Analyze/RMS_File utility to examine the system authorization file (SYSUAF.DAT), you prevent other users from logging in to 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.

ANALYZE/RMS_FILE Qualifiers

This section describes the ANALYZE/RMS_FILE qualifiers and how you use them to select the utility functions. Unless otherwise noted, these qualifiers do not take a qualifier value.

/CHECK

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

Format

/CHECK

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, you only get a message indicating whether the file has errors.

The check function is active by default when you use the ANALYZE/RMS_FILE command without any qualifiers. The /CHECK qualifier is not compatible with the /FDL qualifier, the /INTERACTIVE qualifier, the /STATISTICS qualifier, or the /SUMMARY qualifier.

Example

$ ANALYZE/RMS_FILE/CHECK CUSTFILE
 
      

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

Generates an FDL file describing the RMS data file being analyzed.

Format

/FDL

Description

By default, the /FDL qualifier creates a file with the file type .FDL 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 is corrupted, the FDL file contains the Analyze/RMS_File utility error messages.

For indexed files, the FDL file contains special analysis sections 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, see Chapter 4.

You cannot use wildcards or multiple file specifications with the /FDL qualifier. The /FDL qualifier is not compatible with the /CHECK qualifier, the /INTERACTIVE qualifier, the /STATISTICS qualifier, the /SUMMARY qualifier, or the /UPDATE_HEADER qualifier.

Example

$ ANALYZE/RMS_FILE/FDL ADDRFILE
 
      

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

Begins an interactive examination of the file's structure. You cannot use wildcards or multiple file specifications. For help with the interactive commands, enter the HELP command at the ANALYZE> prompt.

Do not use this qualifier with the /CHECK, /FDL, /STATISTICS, /SUMMARY, or /UPDATE_HEADER qualifiers. For a list of interactive commands, see the ANALYZE/RMS_FILE Commands section.

Format

/INTERACTIVE

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.

Identifies the destination file for the results of the analysis. The /NOOUTPUT qualifier specifies that no output file is to be created. In all cases, the Analyze/RMS_File utility displays a message indicating whether the data file has errors.

Format

/OUTPUT [=output-filespec]

/NOOUTPUT

Qualifier Value

output-filespec

Identifies the output file for the results of the analysis. The use of the output file depends on which of the other qualifiers you specify.

/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-filespec 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-filespec parameter, no transcript of your interactive session is produced.
/RU_JOURNAL	Places the recovery-unit journal information in the output file. The default file type is .ANL, and the default file name is ANALYZE. If you omit the output-filespec parameter, output is written to the current SYS$OUTPUT device, which is generally your terminal.
/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-filespec 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-filespec parameter, output is written to the current SYS$OUTPUT device, which is generally your terminal.

Examples

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

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

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

Provides information about recovery-unit journaling where applicable.

Format

/RU_JOURNAL

Description

You can use the /RU_JOURNAL qualifier on any file, but it is inoperative on files not marked for recovery-unit journaling.

This qualifier provides the only way of accessing a file that would otherwise be inaccessible because of unresolved recovery units. This situation might be the result of an unavailable recovery-unit journal file or of unavailable data files that were included in the recovery unit.

To use the /RU_JOURNAL qualifier, your process must have both CMEXEC privilege and access to the [SYSJNL] directory (either SYSPRV privilege or access for UIC [1,4]).

This qualifier is compatible with all of the ANALYZE/RMS_FILE qualifiers, and you can use it with wildcards and multiple file specifications.

When you specify the /RU_JOURNAL qualifier, the Analyze/RMS_File utility provides you with the following data for each active recovery unit:

• The journal file specification and the journal creation date
• The recovery-unit identification, recovery-unit start time, cluster system identification number (CSID), and process identification (PID)
• Information about the files involved in the recovery unit, including the file specification, the name of the volume where the file resides, the file identification, the date and time the file was created, and the current status of the file
• The state of the recovery unit --- active, none, started, committed, or not available (for more information, see the RMS Journaling for OpenVMS Manual)
• An error statement

Example

$ ANALYZE/RMS_FILE/RU_JOURNAL SAVINGS.DAT
 
      

This command generates information regarding the journaling status of the data file SAVINGS.DAT.

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

Format

/STATISTICS

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.

The /STATISTICS qualifier is not compatible with the /CHECK qualifier, the /FDL qualifier, the /INTERACTIVE qualifier, or the /SUMMARY qualifier.

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.

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

Format

/SUMMARY

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 qualifier, the /FDL qualifier, the /INTERACTIVE qualifier, the /STATISTICS qualifier, or the /UPDATE_HEADER qualifier.

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.

Attempts to update the following attributes in the header of the file: longest record length (LRL) and/or file length hint attribute.

You must use this qualifier in combination with either /STATISTICS or /CHECK (the default).

This qualifier only applies to sequential file organizations and is ignored for any other file organization.

Format

/UPDATE_HEADER ALL is default if qualifier is specified with no values

/UPDATE_HEADER=ALL Both LRL and HINT

/UPDATE=([LRL],[HINT])

Description

The /UPDATE_HEADER qualifier attempts to update the LRL and/or file hint attribute in the file header if the calculated value(s) differ from the current value(s) in the file header. The /UPDATE_HEADER qualifier applies to:

• An LRL request - if the file is sequential and has a record format other than undefined (UDF).
• A HINT request - if the file is sequential, the record format is either variable (VAR) or variable with fixed control (VFC), and the file is located on an ODS-5 disk device.

It is not supported for remote accesses; requests are ignored.

The /UPDATE_HEADER qualifier requires either the STATISTICS or CHECK (default) functions since calculating new values for the LRL and/or file length hint presumes that all the records in the sequential file are processed. It is not compatible with the /FDL qualifier, the /INTERACTIVE qualifier, or the /SUMMARY qualifier.

Any errors returned by the file system when an attempt to update the file header fails are ignored. If the update succeeds, the updated values are displayed at the end of the report.

Example

$ ANALYZE/RMS_FILE/UPDATE_HEADER=HINT A.A
FILE HEADER 
 
     File Spec: DISK$REGRES:[REGRES]A.A;3 
     ... 
                  
   RMS FILE ATTRIBUTES 
 
            File Organization: sequential 
            Record Format: variable 
            Record Attributes:  carriage-return 
            Maximum Record Size: 0 
            Longest Record: 52 
            Blocks Allocated: 4, Default Extend Size: 0 
            End-of-File VBN: 1, Offset: %X'008E' 
            File Monitoring: disabled 
            File Length Hint (Record Count):    6 (invalid) 
            File Length Hint (Data Byte Count): 42 (invalid) 
            Global Buffer Count: 0 
 
       The analysis uncovered NO errors. 
 
            UPDATED File Length Hint (Record Count) to:    10 
            UPDATED File Length Hint (Data Byte Count) to: 118 
 
 ANALYZE/RMS_FILE/UPDATE_HEADER=HINT A.A
      

ANALYZE/RMS_FILE Commands

This section describes the the Analyze/RMS_File utility commands that you use in the interactive mode. Unless otherwise noted, these commands do not take parameters or qualifiers.

In the interactive mode, you use various commands to move through the file structure, examining its various components. Interactive sessions always begin at the FILE HEADER level.

AGAIN

Redisplays the structure you are currently viewing.

Format

AGAIN

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 redisplays the FIXED PROLOG structure.

Displays a previous structure at the current level, if one exists.

Format

BACK [n]

Parameter

n

Specifies the number of times that the structure pointer moves back.

Description

You can use the optional parameter n instead of entering multiple BACK commands. For example, the command BACK 6 has the same effect as six BACK commands.

Examples

ANALYZE> BACK
 
      

This command displays the previous structure at the current level. For example, if you are currently viewing the second key descriptor of the primary key, this command displays the primary key descriptor.

ANALYZE> BACK 3
 
      

This command displays the third structure back at the current level.

Moves the structure pointer down to the next level. From the FILE HEADER level, the first command you enter is the DOWN command, which moves the structure pointer to the FILE ATTRIBUTE level.

Format

DOWN [branch]

Parameter

branch

Specifies the branch you want to follow when the current level has several branches. If there are several branches from the current level and you do not specify a value for the branch parameter, the Analyze/RMS_File utility prompts you by displaying a list of possible branches.

You can also use a question mark after the DOWN command to obtain a list of the possible branches.

Examples

ANALYZE> DOWN ?
%ANLRMS-I-DOWNHELP, The following is a list of paths down from this structure:
%ANLRMS-I-DOWNPATH, AREAS          Area descriptors
%ANLRMS-I-DOWNPATH, KEYS           Key descriptors
 
      

This command displays the branches available to you from the current location in the file structure. In this case, you can specify the AREAS branch or the KEYS branch.

ANALYZE> DOWN AREAS
AREA DESCRIPTOR #0 (VBN 3, offset %X'0000')
 
        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 displays information about the descriptor structure for the first area in the file.

Displays a hexadecimal dump of the specified virtual block.

Format

DUMP n

Parameter

n

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

Example

ANALYZE> DUMP 10
DUMP OF VIRTUAL BLOCK 10:
          7  6  5  4  3  2  1  0          01234567
        ------------------------          --------
         73 20 73 27 65 6C 69 66|  0000  |file's s|
         65 72 75 74 63 75 72 74|  0008  |tructure|
         20 75 6F 59 00 43 00 2E|  0010  |..C.You |
         20 65 73 75 20 6E 61 63|  0018  |can use |
         66 20 4C 44 46 20 6E 61|  0020  |an FDL f|
         64 6F 72 70 20 65 6C 69|  0028  |ile prod|
         20 79 62 20 64 65 63 75|  0030  |uced by |
         2F 45 5A 59 4C 41 4E 41|  0038  |ANALYZE/|
         45 4C 49 46 5F 53 4D 52|  0040  |RMS_FILE|
         74 6F 20 68 74 69 77 20|  0048  | with ot|
         20 53 4D 52 20 72 65 68|  0050  |her RMS |
         65 69 74 69 6C 69 74 75|  0058  |utilitie|
         20 20 20 20 20 20 00 73|  0060  |s.      |
 
      

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

	privacy and legal statement
6027PRO_001.HTML