HP OpenVMS Systems Documentation

Analyzes the contents of an executable image file or a shareable image file on OpenVMS Alpha systems, and an Executable and Linkable Format (ELF) image file or sharable image file on OpenVMS Integrity server systems, identifying obvious errors in the file. This analysis includes translated images on Integrity servers 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 Alpha systems, and of an Executable and Linkable Format (ELF) image file or sharable image file on OpenVMS Integrity server 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 Integrity server systems, the ANALYZE/IMAGE command automatically distinguishes between Integrity servers and Alpha 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 Integrity servers 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 Alpha version of ANALYZE/IMAGE does not have the capability of analyzing all non-platform images.

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

Depending on the platform, the ANALYZE/IMAGE command distinguishes Integrity servers images from 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 Integrity servers 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. (Alpha only.)
• Location and interpretation of the debug and traceback information --- The sections that contain the information and formats the data (DWARF) (Integrity servers 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. (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 (Integrity servers 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. (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.
• Summary of internal tables --- Lists the program segments and sections of which the image consists. (Integrity servers only.)
• Fixup vectors --- Contain information that the image activator needs to ensure the position independence of shareable image references. (Alpha only.)
• Fixup information --- Information that the image activator needs to ensure the position independence of shareable image references. (Integrity servers only.)
• System version categories --- For an image that is linked against the executive (the system shareable image on Integrity servers and Alpha), 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 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 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 (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[,...]) (Integrity servers 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 (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 (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[,...]) ] (Integrity servers 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 Integrity servers 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 (Integrity servers 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.

/SECTIONS [=(keyword[,...])] (Integrity servers 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[,...])] (Integrity servers 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 Integrity servers image file. Returns an OpenVMS Alpha image file."OpenVMS Alpha" if the file is an OpenVMS Alpha image file.
BUILD_IDENTIFICATION	Writes build identification information into the DCL symbol ANALYZE$BUILD_IDENTIFICATION. For OpenVMS Integrity servers and Alpha image files, returns the image build identification stored in the image file, enclosed in quotation marks.
FILE_TYPE	Writes file type information into the DCL symbol ANALYZE$FILE_TYPE. Returns "Image" if the file is an OpenVMS Integrity servers or Alpha 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 Integrity servers or Alpha 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/Integrity servers 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.

Examples

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

$ ANALYZE/IMAGE/OUTPUT=LIALPHEX/FIXUP_SECTION/PATCH_TEXT 
 LINEDT, ALPRIN (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.

$ ANALYZE/IMAGE/SELECT=(ARCH,FILE,NAME,IDENT,BUILD,LINK) *.EXE
DISK:[DIRECTORY]ALPHA.EXE;1 
OpenVMS Alpha 
Image 
"MAIL" 
"V1.06" 
"XBCA-0080070002" 
19-MAR-2008 11:17:50.76
 
 
      

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

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