HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

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

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.

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.

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:

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.

If the new linker identification is selected,
it is necessary to use IDENT with a keyword list.

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.