OpenVMS DCL Dictionary

Document revision date: 19 July 1999

OpenVMS DCL Dictionary

Contents

Index

When the tape device is no longer needed, the DEALLOCATE command deallocates it and the DEASSIGN command deletes the logical name. Note that the logical name TAPE was specified with a colon on the ALLOCATE command, but that the logical name table entry does not have a colon.

#3

$ ALLOCATE/GENERIC RL02 WORK %DCL-I-ALLOC, _DLA1: allocated %DCL-I-SUPERSEDE, previous value of WORK has been superseded

#3
$ ALLOCATE/GENERIC RL02 WORK %DCL-I-ALLOC, _DLA1: allocated %DCL-I-SUPERSEDE, previous value of WORK has been superseded

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 floppy disk 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 Dump Analyzer Utility 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

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 and Files-11 On-Disk Structure Level 2 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/ERROR_LOG

Invokes the Errorlog Report Formatter, which selectively reports the contents of an error log file. The /ERROR_LOG qualifier is required.
For more information about the Error Log utility, refer to the OpenVMS System Management Utilities Reference Manual or online help.

Format

ANALYZE/ERROR_LOG [filespec[,...]]

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.

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.

ANALYZE/MEDIA

Invokes the Bad Block Locator utility, which analyzes block-addressable devices and records the location of blocks that cannot reliably store data.
For more information about the Bad Block Locator utility, refer to the OpenVMS Bad Block Locator Utility Manual 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.
/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.

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.)
The ANALYZE/PROCESS_DUMP command can display a process dump file for either an Alpha or a VAX image. For a complete description of the debugger, including information about the DEBUG command, refer to the OpenVMS Debugger Manual.
Requires read (R) access to the dump file.

Format

ANALYZE/PROCESS_DUMP dump-file

Parameter

dump-file
Specifies the dump file to be analyzed with the debugger.

Description

The ANALYZE/PROCESS_DUMP command examines the dump file of an image that failed during execution. The OpenVMS Debugger is invoked automatically. To cause a dump file to be created for a process, you must use the /DUMP qualifier with the RUN command when invoking the image, or you must use the SET PROCESS/DUMP command before invoking the image.

Note
Compaq strongly recommends that you analyze a process dump on the system where the dump was generated. It is highly unlikely that you can analyze a dump successfully if you move the dump file to a different system.
Different configurations can cause the process executing the ANALYZE/PROCESS_DUMP command to fail to successfully load the dumped image. For example, if the systems have different versions of the operating system, the analysis might work, but it is not guaranteed.

Other restrictions include the configuration of the control regions in P1 space, the process running at the time of the dump, and the process performing the ANALYZE/PROCESS_DUMP command. The location of the base of the user stack for each process, which depends on the size of allocated space, determines whether the processes are compatible. The size of allocated space for the process analyzing the dump must be less than the size of allocated space for the process that created the dump. If you are analyzing the dump on a different system, but with the same version of the operating system, you can decrease the size of allocated space by modifying one or more of the system parameters that affect the size of allocated space.
You can modify the system parameter IMGIOCNT dynamically. Other parameters to adjust allocated space require a reboot of the system.
On Alpha systems, the SYSGEN parameter IMGREG_PAGES is likely to cause a problem with allocated size. When a dump comes from a system without DECwindows and is examined on a system with DECwindows, a P1 message is displayed. DECwindows requires IMGREG_PAGES to be at least 2000 pages, which means that the value is too large by 1200 to 1400 pages.
Also on Alpha systems, in some cases, the OpenVMS Debugger is incapable of analyzing the dumped image. For example, when the dumped image's PC is set to an invalid address or when the dumped image's stack is corrupted by a bad process descriptor, you must use the Delta Debugger (DELTA) to analyze the dump. To use DELTA as the debugger, you must install the SYS$LIBRARY:DELTA image by invoking the Install utility. For complete information on the Install utility, refer to the OpenVMS System Management Utilities Reference Manual.

Qualifiers

/FULL
Displays all known information about the failing process.
/IMAGE=image-name

/NOIMAGE
Specifies the image to be activated to set up the process context for the analysis. If you use the /NOIMAGE qualifier, the DELTA debugger will be used for the analysis.
By default on VAX systems, symbols are taken from the image with the same name as the image that was running at the time of the dump.
On Alpha systems, the image file supplies more than just symbols. Therefore, you must supply the image that created the dump file. Use one of the following methods:

Place the image file in the same directory as the dump file.
Point to the image file with the /IMAGE qualifier.

/INTERACTIVE

/NOINTERACTIVE (default)
Causes the display of information to pause when your terminal screen is filled. Press the Return key to display additional information. By default, the display is continuous.
/MISCELLANEOUS
Displays process information and registers at the time of the dump. Refer to the $GETJPI system service for further explanation of the process information displayed.
/RELOCATION
Displays the addresses to which data structures saved in the dump are mapped in P0 space. (Examples of such data structures are the stacks.) The data structures in the dump must be mapped into P0 space so that the debugger can use those data structures in P1 space.

Examples

#1
$ ANALYZE/PROCESS/FULL ZIPLIST R0 = 00018292 R1 = 8013DE20 R2 = 7FFE6A40 R3 = 7FFE6A98 R4 = 8013DE20 R5 = 00000000 R6 = 7FFE7B9A R7 = 0000F000 R8 = 00000000 R9 = 00000000 R10 = 00000000 R11 = 00000000 SP = 7FFAEF44 AP = 7FFAEF48 FP = 7FFAEF84 FREE_P0_VA 00001600 FREE_P1_VA 7FFAC600 Active ASTs 00 Enabled ASTs 0F Current Privileges FFFFFF80 1010C100 Event Flags 00000000 E0000000 Buffered I/O count/limit 6/6 Direct I/O count/limit 6/6 File count/limit 27/30 Process count/limit 0/0 Timer queue count/limit 10/10 AST count/limit 6/6 Enqueue count/limit 30/30 Buffered I/O total 7 Direct I/O total 18 Link Date 27-DEC-1998 15:02:00.48 Patch Date 17-NOV-1998 00:01:53.71 ECO Level 0030008C 00540040 00000000 34303230 Kernel stack 00000000 pages at 00000000 moved to 00000000 Exec stack 00000000 pages at 00000000 moved to 00000000 Vector page 00000001 page at 7FFEFE00 moved to 00001600 PIO (RMS) area 00000005 pages at 7FFE1200 moved to 00001800 Image activator context 00000001 page at 7FFE3400 moved to 00002200 User writable context 0000000A pages at 7FFE1C00 moved to 00002400 Creating a subprocess VAX DEBUG Version 5.4 DBG>

$ ANALYZE/PROCESS/FULL ZIPLIST
 R0 = 00018292  R1 = 8013DE20  R2 = 7FFE6A40   R3 = 7FFE6A98 
 R4 = 8013DE20  R5 = 00000000  R6 = 7FFE7B9A   R7 = 0000F000 
 R8 = 00000000  R9 = 00000000  R10 = 00000000  R11 = 00000000 
 SP = 7FFAEF44  AP = 7FFAEF48  FP  = 7FFAEF84 
 FREE_P0_VA  00001600    FREE_P1_VA  7FFAC600 
 Active ASTs  00         Enabled ASTs 0F 
 Current Privileges  FFFFFF80  1010C100 
 Event Flags  00000000  E0000000 
 Buffered I/O count/limit 6/6 
 Direct I/O count/limit   6/6 
 File count/limit         27/30 
 Process count/limit      0/0 
 Timer queue count/limit  10/10 
 AST count/limit          6/6 
 Enqueue count/limit      30/30 
 Buffered I/O total 7      Direct I/O total 18 
 
 Link Date  27-DEC-1998 15:02:00.48   Patch Date  17-NOV-1998 00:01:53.71 
 ECO Level  0030008C  00540040  00000000  34303230 
 Kernel stack 00000000 pages at 00000000 moved to 00000000 
 Exec stack 00000000 pages at 00000000 moved to 00000000 
 Vector page 00000001 page at 7FFEFE00 moved to 00001600 
 PIO (RMS) area 00000005 pages at 7FFE1200 moved to 00001800
 Image activator context 00000001 page at 7FFE3400 moved to 00002200 
 User writable context 0000000A pages at 7FFE1C00 moved to 00002400 
Creating a subprocess 
         VAX DEBUG Version 5.4 
DBG>

Previous Next Contents Index

privacy and legal statement

9996PRO_002.HTML