[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP OpenVMS DCL Dictionary

Previous Contents Index

ANALYZE/IMAGE

Analyzes the contents of an executable image file or a shareable image file on OpenVMS VAX and Alpha systems, and an Executable and Linkable Format (ELF) image file or sharable image file on OpenVMS I64 systems, identifying obvious errors in the file. This analysis includes translated images on I64 and Alpha systems. The /IMAGE qualifier is required.

For general information about image files, see the description of the linker in the HP OpenVMS Linker Utility Manual. (Use the ANALYZE/OBJECT command to analyze the contents of an object file.)

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 on OpenVMS VAX and Alpha systems, and of an Executable and Linkable Format (ELF) image file or sharable image file on OpenVMS I64 systems. 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.

On OpenVMS I64 systems, the ANALYZE/IMAGE command automatically distinguishes between I64, Alpha, and VAX images by examining the header information.

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.

Notes
For I64 images and objects, the Analyze utility determines whether the file it analyzes is an image file or object file. Although Analyze allows you to specify ANALYZE/OJBECT on an ELF image file, use ANALYZE/IMAGE for ELF image files and ANALYZE/OJBECT for ELF object files.

When parsing output from ANALYZE/IMAGE, be aware that the output for ELF images may change.

When using ANALYZE without a qualifier, the default is /OBJECT. Therefore, when using this default to analyze an image in the output file, the utility correctly identifies itself as "Analyze Object File".

The OpenVMS VAX and Alpha versions of ANALYZE/IMAGE do not have the capability of analyzing all non-platform images. For example, ANALYZE/IMAGE cannot analyze I64 images on VAX or Alpha images on older versions of VAX.

When you analyze I64 images on I64 platforms, ANALYZE/IMAGE accepts VAX-only or Alpha-only qualifiers, but ignores any effect of these qualifiers.

Depending on the platform, the ANALYZE/IMAGE command distinguishes I64 images from VAX and ALpha images by examining the meta information (for example, ELF, EIHD, or IHD).

The ANALYZE/IMAGE command provides the following information for image files:

  • Image architecture and type --- The OpenVMS platform and whether the image is executable or shareable.
  • Image name --- The name of the image or shareable image.
  • Image identification --- The identification given in a link operation.
  • Creating linker identification --- The linker that generated the image.
  • Link date and time --- The date and time of the link operation.
  • Image transfer addresses --- The addresses to which control is passed at image execution time.
  • Image version --- The revision level (major ID and minor ID) of the image.
  • Location and size of the image's symbol vector (Alpha and I64 only).
  • List of required sharable images --- The dependencies on sharable images.
  • Location of the debugger symbol table (DST) --- 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. (VAX and Alpha only.)
  • Location and interpretation of the debug and traceback information --- The sections that contain the information and formats the data (DWARF) (I64 only).
  • Location of the global symbol table (GST)--- The location of the GST in the image file. GST information is present only in shareable image files. (VAX and Alpha only.)
  • Location of the global symbol table (.symtab) --- The location of the GST in the image file. GST information is present only in shareable image files (I64 only.)
  • 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. (VAX and Alpha only.)
  • 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. (VAX only.)
  • Summary of internal tables --- Lists the program segments and sections of which the image consists. (I64 only.)
  • Fixup vectors --- Contain information that the image activator needs to ensure the position independence of shareable image references. (VAX and Alpha only.)
  • Fixup information --- Information that the image activator needs to ensure the position independence of shareable image references. (I64 only.)
  • System version categories --- For an image that is linked against the executive (the system shareable image on I64 and 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. For VAX and Alpha images, 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.

The default behavior for analyzing ELF images differs from the behavior for analyzing Alpha or VAX images. For ELF images, a summary of the major ELF tables is displayed. With this information, you can select specific segments and/or sections for analysis. To locate errors, analyze the entire image by selecting all sections and segments.

Qualifiers

/FIXUP_SECTION (VAX and Alpha only)

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.

/FLAGVALUES=(keyword[,...]) (I64 only)

Several fields in an ELF module represent bit flags. Where possible, these bit-flag values are examined and displayed individually. By default, only the flag values that are set to 1 (ON) are displayed.

The keywords are as follows:

Keyword Description
ON The keyword ON displays all flags whose value is 1.
OFF The keyword OFF displays all flags whose value is 0.
ALL The keyword ALL displays all flag values. The keywords ON and OFF, in contrast, indicate the value of each specific flag bit.

/GST (VAX and Alpha only)

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 (VAX and Alpha only)

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.

/MODULE [=(module_name[,...]) ] (I64 only)

Selectively formats debug or traceback information for the named module or list of modules. You must request debug or traceback information by using the /SECTIONS qualifier with keywords ALL, DEBUG or TRACE. If debug or traceback information is selectively formatted, then the module name is a subselection.

If you do not specify a module name, only debug or traceback meta information about the available modules is printed. In this case, any other debug or traceback selection is deactivated.

Note
This qualifier is only valid for ANALYZE/IMAGE. Although ANALYZE/OBJECT can be used to format I64 images, Analyze rejects the /MODULE qualifier.

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

/PAGE_BREAK=keyword (I64 only)

Specifies if and where page breaks (form feeds) are inserted in the report file. This qualifier is only useful if /OUTPUT is used to write a report file. It is ignored if /INTERACTIVE is used to specify an interactive analysis.

The keywords are as follows:

Keyword Description
NONE Creates a report without any page break.
PRINTABLE_REPORT Creates a printable report with page breaks as in listing files. The number of lines per page is the default number of lines on a printer page. This is the default behavior for ANALYZE_IMAGE when no qualifier is specified.
SEPARATE_INFORMATION Inserts a page break between different section information.

/PATCH_TEXT (VAX only)

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.

/SECTIONS [=(keyword[,...])] (I64 only)

Selects individual program sections or section types to display.

Note
This qualifier and its keywords can only be used to form an inclusion list of sections to be displayed. This qualifier is not negatable and cannot be used to form an exclusion list. If no values are specified, the default keyword is HEADERS.

The keywords are as follows:

Keyword Description
ALL Displays a detailed analysis of every section in the module. Note that this keyword can generate a large amount of output.
CODE Displays all of all sections of type SHT_PROGBITS where the executable flag is set (SHDR$M_SHF_EXECINSTR in the section header). The section data will be displayed as machine instructions.
DEBUG
[=(suffix[,...])] 		Analyzes and displays sections consisting of debug information.

In addition, you can use a list of debug section name suffixes to selectively format DEBUG information. The debug section names, which appear as ".debug_suffix", can be viewed in the summary table. The suffix can be specified as follows:

  • ABBREV---Format DEBUG abbreviations
  • ARANGES---Formats DEBUG address lookup tables
  • FRAME---Formats DEBUG frame descriptors for unwinding
  • INFO---Formats DEBUG symbols
  • LINE---Formats DEBUG source line info
  • PUBNAMES---Formats DEBUG name lookup tables
  • PUBTYPES---Formats DEBUG type lookup tables
EXTENSIONS Analyzes and displays sections of type SHT_IA64_EXT. The data is displayed in hexadecimal format.
GROUP Analyzes and displays sections of type SHT_GROUP. Sections of this type consist of a list of the section numbers of sections belonging to that group.
HEADERS The default keyword. Displays the ELF header and the section header details.
LINKAGES Analyzes and displays sections of type SHT_VMS_LINKAGES.The data is displayed as a list of linkage descriptors.
NOBITS Analyzes and displays sections of type SHT_NOBITS. There is no module data associated with sections of this type.
NOTE Analyzes and displays sections of type SHT_NOTE. The data for this section is displayed as a list of formatted OpenVMS note entries.
NULL Displays all sections of type PT_NULL. No data will be displayed for segments of this type.
NUMBERS=
(number [,...]) 		Displays individual sections, as follows:
  • The selected sections will have a detailed display of their header and their contents. An informational message is displayed for section numbers that do not exist in the module.
  • One or more numeric values may be specified.
  • Section numbers may be specified in decimal, octal (using the %O prefix), or hexadecimal (using the %X prefix).
STRTAB Analyzes and displays sections of type SHT_STRTAB. The data for this section is displayed as a string table.
SYMTAB Displays sections of type SHT_SYMTAB. The data for this section is displayed as a symbol table.
SYMBOL_VECTOR Sections of this type will only appear in sharable image files. If present, they point to the same data as the dynamic segment DT_VMS_SYMVEC tags.
TRACE
[=(suffix[,...])] 		Analyzes and displays sections consisting of traceback information.

In addition, you can use a list of trace section name suffixes to selectively format TRACE information. The trace section names, which appear as ".trace_suffix", can be viewed in the summary table. The suffix can be specified as shown below. In addition, because there is one common debug and traceback section, ".debug_line", the suffix "line" can be specified as shown below as well:

  • ABBREV---Formats TRACE abbreviations
  • ARANGES---Formats TRACE address lookup tables
  • INFO---Formats TRACE symbols
  • LINE---Formats TRACE source line info
UNWIND Analyzes and displays sections of type SHT_IA64_UNWIND. Each section of this type has an associated Unwind Information section of type SHT_PROGBITS. This associated section is also displayed.

/SEGMENTS [=(keyword[,...])] (I64 only)

Selects individual program segments or program segments of a specified type to be displayed.

Note
This qualifier and its keywords can only be used to form an inclusion list of segments to be displayed. This qualifier is not negatable and cannot be used to form an exclusion list. If no values are specified, the default keyword is HEADERS.

The keywords are as follows:

Keyword Description
ALL Analyzes and displays information for every program segment. Note that this can generate a large amount of output.
CODE Analyzes and displays all executable segments (PHDR$M_PF_X bit set in the segment header). Segment data is displayed as machine instructions.
DYNAMIC Analyzes and displays the segment of type PT_DYNAMIC.
EXTENSIONS Analyzes and displays segments of type IA_64_ARCHEXT.
HEADERS The default keyword. Analyzes and displays the ELF header and segment header details.
LOAD Analyzes and displays segments of type PT_LOAD. If the segment header indicates this is an executable segment (PHDR$M_PF_X bit set in the segment header), the contents will be formatted as machine instructions, otherwise the contents are formatted as hexadecimal data.
NULL Analyzes and displays segments of type PT_NULL. No a data will be displayed for segments of this type.
NUMBERS=
(number [,...]) 		Analyzes and displays individual segments, as follows:
  • The selected segments have a detailed display of header and content information. For section numbers that do not exist in the module, an informational message is displayed.
  • One or more numeric values may be specified.
  • Segment numbers may be specified in decimal, octal (using the %O prefix), or hexadecimal (using the %X prefix).

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

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

Analyze creates DCL symbols for all selectable information with the /SELECT qualifier. The symbol names consist of the prefix ANALYZE$ and a descriptive name of the information they hold. The symbol value is the selected information, usually printed to SYS$OUTPUT. Effectively, all of the printed information is duplicated in the symbols. For unselected information, the corresponding symbols will contain the null string.

The keywords are as follows:

Keyword Description
ARCHITECTURE Writes the architecture information into the DCL symbol ANALYZE$ARCHITECTURE. Returns "OpenVMS IA64" if the file is an OpenVMS I64 image file. Returns "OpenVMS Alpha" if the file is an OpenVMS Alpha image file. Returns "OpenVMS VAX" if the file is an OpenVMS VAX image file.
BUILD_IDENTIFICATION Writes build identification information into the DCL symbol ANALYZE$BUILD_IDENTIFICATION. For OpenVMS I64 and Alpha image files, returns the image build identification stored in the image file, enclosed in quotation marks. For OpenVMS VAX image files, the null string that is represented by adjacent quotation marks is returned.
FILE_TYPE Writes file type information into the DCL symbol ANALYZE$FILE_TYPE. Returns "Image" if the file is an OpenVMS I64, Alpha, or VAX image file.
IDENTIFICATION
[=keyword] 		The possible keywords are as follows:
  • IMAGE (default) --- Writes the image identification information into the DCL symbol ANALYZE$IDENTIFICATION. Returns the image identification that is stored in the image file, enclosed in quotation marks. Otherwise, returns "Unknown".
  • LINKER --- Writes the linker identification information into the DCL symbol ANALYZE$LINKER_IDENTIFICATION. Returns the identification of the linker used to link the image.
IMAGE_TYPE Writes image type information into the DCL symbol ANALYZE$IMAGE_TYPE. Returns "Shareable" if the file is a shareable image file. Returns "Executable" if the file is either an OpenVMS I64, Alpha, or OpenVMS VAX executable (nonshareable) image file.
LINK_TIME Writes link time information into the DCL symbol ANALYZE$LINK_TIME. Returns the image link time that is stored in the image file, enclosed in quotation marks.
NAME Writes the image name into the DCL symbol ANALYZE$NAME. For image files, returns the image name that is stored in the image header, enclosed in quotation marks.
VERSION_NUMBERS (Alpha/I64 only) If an image depends on the system base image and system components, ANALYZE writes the version numbers from the image into DCL symbols. The symbols are named after the components. The symbol values contain the minor and major version numbers. When the image is for the same platform on which ANALYZE is running, the version numbers from the running system are also written and compared.

Note
The Analyze utility can work on several files. Because there is only one set of DCL symbols, the symbols only contain information from the last analyzed file. When an error occurs, symbol values are undefined. Check for Analyze errors first, then use the symbols.

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.

#2 

$ ANALYZE/IMAGE/OUTPUT=LIALPHEX/FIXUP_SECTION/PATCH_TEXT
 LINEDT, ALPRIN (VAX and Alpha only)

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"
14-JUN-2004 07:16:19.24
DISK:[DIRECTORY]VAX.EXE;1
OpenVMS VAX
Image
"Test image VAX"
"V11-27"
""
15-JUN-2004 13:18:40:70

On an Alpha system, this example displays the information requested about the executable files ALPHA.EXE and VAX.EXE.

#4 

$ ANALYZE/IMAGE/SELECT=(ARCHITECTURE,IDENT,NAME) HELLO (1)
USER:[JOE]HELLO.EXE;1
OpenVMS IA64
"V1.0"
"HELLO"
$
$ SHOW SYMBOL ANALYZE$*
  ANALYZE$ARCHITECTURE = "OpenVMS IA64"
  ANALYZE$BUILD_IDENTIFICATION = ""
  ANALYZE$FILE_TYPE = ""
  ANALYZE$IDENTIFICATION = ""V1.0""
  ANALYZE$IMAGE_TYPE = ""
  ANALYZE$LINKER_IDENTIFICATION = ""
  ANALYZE$LINK_TIME = ""
  ANALYZE$NAME = ""HELLO""
$
$ ANALYZE/IMAGE/SELECT=(IDENT=(IMAGE,LINKER),IMAGE,LINK) HELLO (2)
USER:[JOE]HELLO.EXE;1
"V1.0"
"Linker I01-54"
Executable
 7-JUN-2004 11:47:08.10
$
$ SHOW SYMBOL ANALYZE$*
  ANALYZE$ARCHITECTURE = ""
  ANALYZE$BUILD_IDENTIFICATION = ""
  ANALYZE$FILE_TYPE = ""
  ANALYZE$IDENTIFICATION = ""V1.0""
  ANALYZE$IMAGE_TYPE = "Executable"
  ANALYZE$LINKER_IDENTIFICATION = ""Linker I01-54""
  ANALYZE$LINK_TIME = " 7-JUN-2004 11:47:08.10"
  ANALYZE$NAME = ""
$
$ ANALYZE/IMAGE/SELECT=FILE HELLO.* (3)
USER:[JOE]HELLO.C;1
%ANALYZE-E-ILLFIL, Illegal file format encountered
USER:[JOE]HELLO.EXE;1
Image
USER:[JOE]HELLO.MAP;1
%ANALYZE-E-ILLFIL, Illegal file format encountered
USER:[JOE]HELLO.OBJ;1
Object
$
$ SHOW SYMBOL ANALYZE$*
  ANALYZE$ARCHITECTURE = ""
  ANALYZE$BUILD_IDENTIFICATION = ""
  ANALYZE$FILE_TYPE = "Object"
  ANALYZE$IDENTIFICATION = ""
  ANALYZE$IMAGE_TYPE = ""
  ANALYZE$LINKER_IDENTIFICATION = ""
  ANALYZE$LINK_TIME = ""
   ANALYZE$NAME =
$

This I64 example displays the information requested for the executable file, HELLO.EXE. The following text is keyed to the callout numbers at the ends of each ANALYZE/IMAGE command line in the example:

  1. Only the selected information can be found in the DCL symbols. The information in the symbols is identical to what is printed to SYS$OUTPUT, that is, if quoted strings are printed, there are quoted strings in the symbol.
  2. If the new linker identification is selected, it is necessary to use IDENT with a keyword list.
  3. When using wildcards, errors in the analyzed file (for example, illegal file format errors) do not terminate Analyze. Only the information from the last analyzed file can be found in the DCL symbols.

Previous Next Contents Index