Document revision date: 30 March 2001

## OpenVMS DCL Dictionary

Previous | Contents | Index

The ALLOCATE command in this example requests the allocation of any RL02 disk device and assigns the logical name WORK to the device. The completion message identifies the allocated device and indicates that the assignment of the logical name WORK supersedes a previous assignment of that name.

#4
    $ ALLOCATE $TAPE1
    %DCL-I-ALLOC, _MUA0: allocated

> The ALLOCATE command in this example allocates the tape device MUA0, which is associated with the logical name $TAPE1.

#5
    $ ALLOCATE /GENERIC RX50 ACCOUNTS

> The ALLOCATE command in this example allocates the first free diskette drive and makes its name equivalent to the process logical name ACCOUNTS.

## ANALYZE/AUDIT

> Invokes the Audit Analysis utility, which selectively extracts and displays information from security audit log files or security archive files.

> For more information about the Audit Analysis utility, refer to the OpenVMS System Management Utilities Reference Manual or online help.

### Format

> ANALYZE/AUDIT [filespec]

## ANALYZE/CRASH_DUMP

> Invokes the System Dump Analyzer utility, which analyzes a system dump file. The /CRASH_DUMP qualifier is required.

> For more information about the System Dump Analyzer utility on Alpha, refer to the OpenVMS Alpha System Analysis Tools Manual or online help. For more information about the System Dump Analyzer utility on VAX, refer to the OpenVMS VAX System Dump Analyzer Utility Manual or online help.

### Format

> ANALYZE/CRASH_DUMP filespec

### Description

> Invokes the System Dump Analyzer utility, which analyzes a system dump file. The /CRASH_DUMP qualifier is required.

> For OpenVMS Alpha Systems

> You can also use the ANALYZE/CRASH_DUMP command with process dumps. However, the preferred command is ANALYZE/PROCESS, which provides complete access to the information in the dump.

## ANALYZE/DISK_STRUCTURE

> Invokes the Analyze/Disk_Structure utility, which does the following:
> - Checks the readability and validity of Files-11 On-Disk Structure Level 1, 2, and 5 disk volumes
> - Reports errors and inconsistencies

> The /DISK_STRUCTURE qualifier is required.

> For more information about the Analyze/Disk_Structure utility, refer to the OpenVMS System Management Utilities Reference Manual or online help.

### Format

> ANALYZE/DISK_STRUCTURE device-name[:]

## ANALYZE/IMAGE

> Analyzes the contents of an executable image file or a shareable image file on Alpha, VAX, and translated VAX images, and checks for obvious errors in the image file. The /IMAGE qualifier is required. For general information about image files, refer to the description of the linker in the OpenVMS Linker Utility Manual. (Use the ANALYZE/OBJECT command to analyze the contents of an object file.)

> Note The OpenVMS VAX Version 6.1 and 6.2 ANALYZE/IMAGE command cannot analyze an OpenVMS Alpha image.

### Format

> ANALYZE/IMAGE filespec[,...]

### Parameter

> #### filespec[,...]

> Specifies the name of one or more image files that you want analyzed. You must specify at least one file name. If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+). The default file type is .EXE.

> The asterisk (*) and percent sign (%) wildcard characters are allowed in the file specification.

### Description

> The ANALYZE/IMAGE command provides a description of the components of an executable image file or shareable image file. It also verifies that the structure of the major parts of the image file is correct. However, the ANALYZE/IMAGE command cannot ensure that program execution is error free.

> If errors are found, the first error of the worst severity is returned. For example, if a warning (A) and two errors (B and C) are found, the first error (B) is returned as the image exit status. The image exit status is placed in the DCL symbol $STATUS at image exit.

> The ANALYZE/IMAGE command distinguishes Alpha system image files from VAX system image files by examining the extended image header (EIHD).

> The ANALYZE/IMAGE command provides the following information:

> - Image type---Identifies whether the image is executable or shareable.
> - Image transfer addresses---Identify the addresses to which control is passed at image execution time.
> - Image version---Identifies the revision level (major ID and minor ID) of the image.
> - Location and size of the image's symbol vector (Alpha only).
> - Location of the debugger symbol table (DST)---Identifies the location of the DST in the image file. DST information is present only in executable images that have been linked with the /DEBUG or the /TRACEBACK command qualifier.
> - Location of the global symbol table (GST)---Identifies the location of the GST in the image file. GST information is present only in shareable image files.
> - Patch information---Indicates whether the image has been patched (changed without having been recompiled or reassembled and relinked). If a patch is present, the actual patch code can be displayed.
> - Image section descriptors (ISD)---Identify portions of the image binary contents that are grouped in OpenVMS Cluster systems according to their attributes. An ISD contains information that the image activator needs when it initializes the address space for an image. For example, an ISD tells whether the ISD is shareable, whether it is readable or writable, whether it is based or position independent, and how much memory should be allocated.
> - Fixup vectors---Contain information that the image activator needs to ensure the position independence of shareable image references.
> - System version categories---For an image that is linked against the executive (the system shareable image on Alpha or the system symbol table on VAX), displays both the values of the system version categories for which the image was linked originally and the values for the system that is currently running. You can use these values to identify changes in the system since the image was linked last.

> The ANALYZE/IMAGE command has command qualifiers and positional qualifiers. By default, if you do not specify any positional qualifiers (for example, /GST or /HEADER), the entire image is analyzed. If you do specify a positional qualifier, the analysis excludes all other positional qualifiers except the /HEADER qualifier (which is always enabled) and any qualifier that you request explicitly.

### Qualifiers

> #### /FIXUP_SECTION

> Positional qualifier.

> Specifies that the analysis should include all information in the fixup section of the image.

> If you specify the /FIXUP_SECTION qualifier after the ANALYZE/IMAGE command, the fixup section of each image file in the parameter list is analyzed.

> If you specify the /FIXUP_SECTION qualifier after a file specification, only the information in the fixup section of that image file is analyzed.

> #### /GST

> Positional qualifier.

> Specifies that the analysis should include all global symbol table records. This qualifier is valid only for shareable images.

> If you specify the /GST qualifier after the ANALYZE/IMAGE command, the global symbol table records of each image file in the parameter list are analyzed.

> If you specify the /GST qualifier after a file specification, only the global symbol table records of that file are analyzed.

> #### /HEADER

> Positional qualifier.

> Specifies that the analysis should include all header items and image section descriptions. The image header items are always analyzed.

> #### /INTERACTIVE

> #### /NOINTERACTIVE (default)

> Specifies whether the analysis is interactive. In interactive mode, as each item is analyzed, the results are displayed on the screen and you are asked whether you want to continue.

> #### /OUTPUT=filespec

> Identifies the output file for storing the results of the image analysis. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the file specification. If you specify a file type and omit the file name, the default file name ANALYZE is used. The default file type is .ANL. If you omit the qualifier, the results are output to the current SYS$OUTPUT device.

> #### /PATCH_TEXT

> Positional qualifier.

> Specifies that the analysis include all patch text records. If you specify the /PATCH_TEXT qualifier after the ANALYZE/IMAGE command, the patch text records of each image file in the parameter list are analyzed.

> If you specify the /PATCH_TEXT qualifier after a file specification, only the patch text records of that file are analyzed.

> #### /SELECT=(keyword[,...])

> Allows for the collection of specific image or object file information and displays the selected keyword items in the order specified.

> The keywords are as follows:

> Keyword | Description
> --- | ---
> ARCHITECTURE | Returns "OpenVMS Alpha" if the file is either an OpenVMS Alpha image or object file. Returns "OpenVMS VAX" if the file is either an OpenVMS VAX image or object file. Otherwise, returns "Unknown".
> BUILD_IDENTIFICATION | For OpenVMS Alpha image files, returns the image build identification stored in the image header, enclosed in quotation marks. For OpenVMS VAX image files, the null string that is represented by adjacent quotation marks is returned. Otherwise, returns "Unknown".
> FILE_TYPE | Returns "Image" if the file is an OpenVMS VAX or Alpha image file. Returns "Object" if the file is an OpenVMS VAX or Alpha object file. Otherwise, returns "Unknown".
> IDENTIFICATION | For both OpenVMS Alpha and VAX image files, returns the image identification that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".
> IMAGE_TYPE | Returns "Shareable" if the file is either an OpenVMS Alpha or OpenVMS VAX sharable image file. Returns "Executable" if the file is either an OpenVMS Alpha or OpenVMS VAX executable (nonsharable) image file. Otherwise, returns "Unknown".
> LINK_TIME | For both OpenVMS Alpha and VAX image files, returns the image link time that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".
> NAME | For both OpenVMS Alpha and VAX image files, returns the image name that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".

### Examples

#1
    $ ANALYZE/IMAGE  LINEDT

> The ANALYZE/IMAGE command in this example produces a description and an error analysis of the image LINEDT.EXE. Output is sent to the current SYS$OUTPUT device. By default, the entire image is analyzed.

#2
    $ ANALYZE/IMAGE/OUTPUT=LIALPHEX/FIXUP_SECTION/PATCH_TEXT  LINEDT, ALPRIN

> The ANALYZE/IMAGE command in this example produces a description and an error analysis of the fixup sections and patch text records of LINEDT.EXE and ALPRIN.EXE in file LIALPHEX.ANL. Output is sent to the file LIALPHEX.ANL.

#3
    $ ANALYZE/IMAGE/SELECT=(ARCH,FILE,NAME,IDENT,BUILD,LINK) *.EXE
    DISK:[DIRECTORY]ALPHA.EXE;1
    OpenVMS ALPHA
    Image
    "Test image ALPHA"
    "A11-27"
    "X5SC-SSB-0000"
    13-APR-1998 07:16:19.24
    DISK:[DIRECTORY]NO_HEADER.EXE;1
    Unknown
    Unknown
    Unknown
    Unknown
    Unknown
    Unknown
    DISK:[DIRECTORY]VAX.EXE;1
    OpenVMS VAX
    Image
    "Test image VAX"
    "V11-27"
    ""
    4-NOV-1999 13:18:40:70

> This example displays the information requested about the executable file, ALPHA.EXE, the unknown file, NO_HEADER.EXE, and the executable file, VAX.EXE.

## ANALYZE/MEDIA

> Invokes the Bad Block Locator utility, which analyzes block-addressable devices and records the location of blocks that cannot store data reliably.

> For more information about the Bad Block Locator utility, refer to the OpenVMS Bad Block Locator Utility Manual (available on the Documentation CD-ROM) or online help.

### Format

> ANALYZE/MEDIA device

## ANALYZE/OBJECT

> Analyzes the contents of an object file. Also, checks for any obvious errors. The /OBJECT qualifier is required. (Use the ANALYZE/IMAGE command to analyze the contents of an image file.)

### Format

> ANALYZE/OBJECT filespec[,...]

### Parameter

> #### filespec[,...]

> Specifies the object files or object module libraries you want analyzed (the default file type is .OBJ). Use commas (,) or plus signs (+) to separate file specifications. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification.

### Description

> The ANALYZE/OBJECT command describes the contents of one or more object modules contained in one or more files. It also performs a partial error analysis. This analysis determines whether all records in an object module conform in content, format, and sequence to the specifications of the Alpha or VAX Object Language.

> The ANALYZE/OBJECT command automatically distinguishes Alpha objects from VAX objects by examining the format of the extended object modules header (EOMH).

> ANALYZE/OBJECT is intended primarily for programmers of compilers, debuggers, or other software involving the operating system's object modules. It checks that the object language records generated by the object modules are acceptable to the Linker utility, and it identifies certain errors in the file. It also provides a description of the records in the object file or object module library. For more information on the linker and on the Alpha and VAX object languages, refer to the OpenVMS Linker Utility Manual.

> The ANALYZE/OBJECT command analyzes the object modules in order, record by record, from the first to the last record in the object module. Fields in each record are analyzed in order from the first to the last field in the record. After the object module is analyzed, you should compare the content and format of each type of record to the required content and format of that record as described by the OpenVMS Alpha or OpenVMS VAX Object Language. This comparison is particularly important if the analysis output contains a diagnostic message.

> Linking an object module differs from analyzing an object module. Object language commands are not executed in an analysis, but they are executed in a linking operation. As a result, even if the analysis is error free, the linking operation may not be. In particular, the analysis does not check the following:

> - That data arguments in TIR commands are in the correct format
> - That "Store Data" TIR commands are storing within legal address limits

> Therefore, as a final check, you should still link an object module whose analysis is error free.

> If an error is found, however, the first error of the worst severity that is discovered is returned. For example, if a warning (A) and two errors (B and C) are signaled, then the first error (B) is returned as the image exit status, which is placed in the DCL symbol $STATUS at image exit.

> ANALYZE/OBJECT uses positional qualifiers; that is, qualifiers whose function depends on their position in the command line. When a positional qualifier precedes all of the input files in a command line, it affects all input files. For example, the following command line requests that the analysis include the global symbol directory records in files A, B, and C:

>     $ ANALYZE/OBJECT/GSD A,B,C

> Conversely, when a positional qualifier is associated with only one file in the parameter list, only that file is affected. For example, the following command line requests that the analysis include the global symbol directory records in file B only:

>     $ ANALYZE/OBJECT A,B/GSD,C

> Typically, all records in an object module are analyzed. However, when the /DBG, /EOM, /GSD, /LNK, /MHD, /TBT, or /TIR qualifier is specified, only the record types indicated by the qualifiers are analyzed. All other record types are ignored.

> By default, the analysis includes all record types unless you explicitly request a limited analysis using appropriate qualifiers.

> Note End-of-module (EOM) records and module header (MHD) records are always analyzed, no matter which qualifiers you specify.

### Qualifiers

> #### /DBG

> Positional qualifier.

> Specifies that the analysis should include all debugger information records. If you want the analysis to include debugger information for all files in the parameter list, insert the /DBG qualifier immediately following the /OBJECT qualifier. If you want the analysis to include debugger information selectively, insert the /DBG qualifier immediately following each of the selected file specifications.

> #### /EOM

> Positional qualifier.

> Specifies that the analysis should be limited to MHD records, EOM records, and records explicitly specified by the command. If you want this to apply to all files in the parameter list, insert the /EOM qualifier immediately following the /OBJECT qualifier.

> To make the /EOM qualifier applicable selectively, insert it immediately following each of the selected file specifications.

> Note End-of-module records can be EOM or EOMW records. Refer to the OpenVMS Linker Utility Manual for more information.

> #### /GSD

> Positional qualifier.

> Specifies that the analysis should include all global symbol directory (GSD) records.

> If you want the analysis to include GSD records for each file in the parameter list, specify the /GSD qualifier immediately following the /OBJECT qualifier.

> If you want the analysis to include GSD records selectively, insert the /GSD qualifier immediately following each of the selected file specifications.

> #### /INCLUDE[=(module[,...])]

> When the specified file is an object module library, use this qualifier to list selected object modules within the library for analysis. If you omit the list or specify an asterisk (*), all modules are analyzed. If you specify only one module, you can omit the parentheses.

> #### /INTERACTIVE

> #### /NOINTERACTIVE (default)

> Controls whether the analysis occurs interactively. In interactive mode, as each record is analyzed, the results are displayed on the screen, and you are asked whether you want to continue.

> #### /LNK

> Positional qualifier.

> Specifies that the analysis should include all link option specification (LNK) records.

> If you want the analysis to include LNK records for each file in the parameter list, specify the /LNK qualifier immediately following the /OBJECT qualifier.

> If you want the analysis to include LNK records selectively, insert the /LNK qualifier immediately following each of the selected file specifications.

> #### /MHD

> Positional qualifier.

> Specifies that the analysis should be limited to MHD records, EOM records, and records explicitly specified by the command. If you want this analysis to apply to all files in the parameter list, insert the /MHD qualifier immediately following the /OBJECT qualifier.

> To make the /MHD qualifier applicable selectively, insert immediately following each of the selected file specifications.

> #### /OUTPUT[=filespec]

> Directs the output of the object analysis (the default is SYS$OUTPUT). If you specify a file type and omit the file name, the default file name ANALYZE is used. The default file type is .ANL.

> The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the file specification.

> #### /SELECT=(keyword[,...])

> Allows for the collection of specific image or object file information and displays the selected keyword items in the order specified.

> The keywords are as follows:

> Keyword | Description
> --- | ---
> ARCHITECTURE | Returns "OpenVMS Alpha" if the file is either an OpenVMS Alpha image or object file. Returns "OpenVMS VAX" if the file is either an OpenVMS VAX image or object file. Otherwise, returns "Unknown".
> BUILD_IDENTIFICATION | For OpenVMS Alpha image files, returns the image build identification stored in the image header, enclosed in quotation marks. For OpenVMS VAX image files, the null string that is represented by adjacent quotation marks is returned. Otherwise, returns "Unknown".
> FILE_TYPE | Returns "Image" if the file is an OpenVMS VAX or Alpha image file. Returns "Object" if the file is an OpenVMS VAX or Alpha object file. Otherwise, returns "Unknown".
> IDENTIFICATION | For both OpenVMS Alpha and VAX image files, returns the image identification that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".
> IMAGE_TYPE | Returns "Shareable" if the file is either an OpenVMS Alpha or OpenVMS VAX sharable image file. Returns "Executable" if the file is either an OpenVMS Alpha or OpenVMS VAX executable (nonsharable) image file. Otherwise, returns "Unknown".
> LINK_TIME | For both OpenVMS Alpha and VAX image files, returns the image link time that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".
> NAME | For both OpenVMS Alpha and VAX image files, returns the image name that is stored in the image header, enclosed in quotation marks. Otherwise, returns "Unknown".

> #### /TBT

> Positional qualifier.

> Specifies that the analysis should include all module traceback (TBT) records.

> If you want the analysis to include TBT records for each file in the parameter list, specify the /TBT qualifier immediately following the /OBJECT qualifier.

> If you want the analysis to include TBT records selectively, insert the /TBT qualifier immediately following each of the selected file specifications.

> #### /TIR

> Positional qualifier.

> Specifies that the analysis should include all text information and relocation (TIR) records.

> If you want the analysis to include TIR records for each file in the parameter list, specify the /TIR qualifier immediately following the /OBJECT qualifier.

> If you want the analysis to include TIR records selectively, insert the /TIR qualifier immediately following the selected file specifications.

### Examples

#1
    $ ANALYZE/OBJECT/INTERACTIVE  LINEDT

> In this example, the ANALYZE/OBJECT command produces a description and a partial error analysis of the object file LINEDT.OBJ. By default, all types of records are analyzed. Output is to the terminal, because the /INTERACTIVE qualifier has been used. As each item is analyzed, the utility displays the results on the screen and asks if you want to continue.

#2
    $ ANALYZE/OBJECT/OUTPUT=LIOBJ/DBG  LINEDT

> In this example, the ANALYZE/OBJECT command analyzes only the debugger information records of the file LINEDT.OBJ. Output is to the file LIOBJ.ANL.

#3
    $ ANALYZE/OBJECT/SELECT=(ARCH,FILE) *.OBJ
    DISK:[DIRECTORY]ALPHA.OBJ;1
    OpenVMS ALPHA
    Object
    DISK:[DIRECTORY]MISNAMED.OBJ;1
    Unknown
    Unknown
    DISK:[DIRECTORY]VAX.OBJ;1
    OpenVMS VAX
    Object

> This example displays the information requested about the object file, ALPHA.OBJ, the unknown file, MISNAMED.OBJ, and the object file, VAX.OBJ.

## ANALYZE/PROCESS_DUMP

> Invokes the OpenVMS Debugger to analyze a process dump file that was created when an image failed during execution. (Use the /DUMP qualifier with the RUN or the SET PROCESS command to generate a dump file.)

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 9996PRO_002.HTML