HP OpenVMS Systems Documentation

OpenVMS DCL Dictionary

Note that on Alpha systems, you can also force a process to dump by using the DUMP/PROCESS command.

The ANALYZE/PROCESS_DUMP command invokes the OpenVMS debugger to 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. On Alpha systems, you can use the DUMP/PROCESS command.
For OpenVMS VAX Systems

This section also applies to Alpha systems running Version 7.2 or before.

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 load the dumped image successfully. 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 system 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.
For OpenVMS Alpha Systems

This section applies to OpenVMS Alpha systems running Version 7.3 or greater.
You can now analyze a dump file on a system other than where the dump was generated. However, if the base image link date and time are not the same, you will need to also copy the file, SYS$BASE_IMAGE.EXE from the generating system, and point to it using the logical, SDA$READ_DIR. For example:
$ COPY other_node::SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE my_disk$:[my_dir] $ DEFINE/USER SDA$READ_DIR my_disk$:[my_dir],SYS$SYSROOT:[SYS$LDR],SYS$SYSROOT:[SYSLIB] $ ANALYZE/PROCESS_DUMP mycrash.dmp
If you are analyzing a threaded process dump on a system other than the system on which it was generated, you may also need to copy and point to PTHREAD$RTL and PTHREAD$DBGSHR (DECthread debug assistant) on the generating system. For example:
$ COPY other_node::SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE my_disk$:[my_dir] $ COPY other_node::SYS$SHARE:PTHREAD$RTL.EXE my_disk$:[my_dir] $ COPY other_node::SYS$SHARE:PTHREAD$DBGSHR.EXE my_disk$:[my_dir] $ DEFINE/USER SDA$READ_DIR my_disk$:[my_dir],SYS$SYSROOT:[SYS$LDR],SYS$SYSROOT:[SYSLIB] $ DEFINE/USER PTHREAD$RTL my_disk$:[my_dir]PTHREAD$RTL.EXE $ DEFINE/USER PTHREAD$DBGSHR my_disk$:[my_dir]PTHREAD$DBGSHR.EXE $ ANALYZE/PROCESS_DUMP mycrash.dmp
If you are unable to analyze a process dump with the debugger, then you should attempt to use the System Dump Analyzer (SDA) utility. See the ANALYZE/CRASH command in online help for more information. For example:
$ ANALYZE/CRASH mycrash.dmp OpenVMS (TM) Alpha system dump analyzer ...analyzing a compressed process dump... Dump taken on 19-OCT-1999 12:03:40.95 SDA> .. . .

Qualifiers

/FULL
On VAX and Alpha systems, shows the information that is displayed by the following debugger commands: SHOW IMAGE, SHOW THREAD/ALL, and SHOW CALL.
/IMAGE=dump-file
On VAX systems, 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, symbols are taken from the image with the same name as the image that was running at the time of the dump.
/IMAGE_PATH[=directory-spec] dump-file

/NOIMAGE_PATH
On Alpha systems, specifies the search path the debugger is to use to find the debugger symbol table (DST) file. As in prior debuggers, the debugger builds an image list from the saved process image list. When you set an image (the main image is automatically set), the debugger attempts to open that image in order to find the DST file.
If you include the /IMAGE_PATH=directory-spec qualifier, the debugger searches for the DST file in the specified directory. The debugger first tries to translate directory-spec as the logical name of a directory search list. If that fails, the debugger interprets directory-spec as a directory specification, and searches that directory for matching .DSF or .EXE files. A .DSF file takes precedence over an .EXE file. The name of the .DSF or .EXE file must match the image.
If you do not include the /IMAGE_PATH=directory-spec qualifier, the debugger looks for the DST file first in the directory that contains the dump file. If that fails, the debugger searches directory SYS$SHARE and then directory SYS$MESSAGE. If the debugger fails to find a DST file for an image, the symbolic information available to the debugger is limited to global and universal symbol names.
Version 7.3 and later debuggers check for dumpfile image specification and DST file link date-time mismatches and issue a warning if one is discovered.
The dump-file parameter is the name of the process dump file to be analyzed. Note that the process dump file file type must be .DMP and the DST file type must be either .DSF or .EXE.
/INTERACTIVE

/NOINTERACTIVE (default)
On VAX systems, causes the display of information to pause when your terminal screen is filled. Press Return to display additional information. By default, the display is continuous.
/MISCELLANEOUS
On VAX systems, 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
On VAX systems, 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

$ 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-2001 15:02:00.48   Patch Date  17-NOV-2001 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>

This example shows the output of the ANALYZE/PROCESS command when used with the /FULL qualifier on a VAX system. The file specified, ZIPLIST, contains the dump of a process that encountered a fatal error. The DBG> prompt indicates that the debugger is ready to accept commands.

$ ANALYZE/PROCESS/FULL WECRASH.DMP

           OpenVMS Alpha Debug64 Version X7.3-010
%SYSTEM-F-IMGDMP, dynamic image dump signal at PC=001D0F8CB280099C, PS=001D0028
break on unhandled exception preceding WECRASH\th_run\%LINE 26412 in THREAD 8
%DEBUG-W-UNAOPNSRC, unable to open source file DSKD$:[IMGDMP]WECRASH.C;11
-RMS-F-DEV, error in device name or inappropriate device type for operation
 26412: Source line not available

 image name                      set    base address           end address
 CMA$TIS_SHR                     no     000000007B8CA000       000000007B8D7FFF
    CODE0                               FFFFFFFF80500000       FFFFFFFF805033FF
    DATA1                               000000007B8CA000       000000007B8CB3FF
    DATA2                               000000007B8CC000       000000007B8D13FF
    DATA3                               000000007B8D2000       000000007B8D21FF
    DATA4                               000000007B8D4000       000000007B8D41FF
    DATA5                               000000007B8D6000       000000007B8D63FF
 DECC$SHR                        no     000000007BE7A000       000000007BF0DFFF
    CODE0                               FFFFFFFF8055C000       FFFFFFFF806C9DFF
    DATA1                               000000007BE7A000       000000007BEACFFF
    DATA2                               000000007BEBA000       000000007BEC2DFF
    DATA3                               000000007BECA000       000000007BED77FF
    DATA4                               000000007BEDA000       000000007BEDA9FF
    DATA5                               000000007BEEA000       000000007BEEA1FF
    DATA6                               000000007BEFA000       000000007BEFE7FF
    DATA7                               000000007BF0A000       000000007BF0D1FF
 DPML$SHR                        no     000000007BB92000       000000007BBD1FFF
    CODE0                               FFFFFFFF80504000       FFFFFFFF8055B5FF
    DATA1                               000000007BB92000       000000007BBAC1FF
    DATA2                               000000007BBAE000       000000007BBBDBFF
    DATA3                               000000007BBBE000       000000007BBBE1FF
    DATA4                               000000007BBC0000       000000007BBCC9FF
    DATA5                               000000007BBCE000       000000007BBCE3FF
    DATA6                               000000007BBD0000       000000007BBD07FF
 LIBOTS                          no     000000007B5AA000       000000007B5B1FFF
    DATA1                               000000007B5AA000       000000007B5AC5FF
    DATA2                               000000007B5AE000       000000007B5AFBFF
    DATA3                               000000007B5B0000       000000007B5B01FF
 LIBRTL                          no     000000007B558000       000000007B5A9FFF
    CODE0                               FFFFFFFF8041C000       FFFFFFFF804BD7FF
    DATA1                               000000007B558000       000000007B5669FF
    DATA2                               000000007B568000       000000007B5697FF
    DATA3                               000000007B578000       000000007B5845FF
    DATA4                               000000007B588000       000000007B5881FF
    DATA5                               000000007B598000       000000007B59A5FF
    DATA6                               000000007B5A8000       000000007B5A99FF
 PTHREAD$RTL                     no     000000007BBD2000       000000007BC27FFF
    DATA0                               000000007BBD2000       000000007BBDA1FF
    DATA1                               000000007BBDC000       000000007BBDF3FF
    DATA2                               000000007BBE0000       000000007BBE2FFF
    DATA3                               000000007BBE4000       000000007BC1E1FF
    DATA4                               000000007BC20000       000000007BC20BFF
    DATA5                               000000007BC22000       000000007BC247FF
    DATA6                               000000007BC26000       000000007BC275FF
*WECRASH                         yes    0000000000010000       00000000000403FF

 total images: 7

  Thread Name                      State           Substate    Policy       Pri
  ------ ------------------------- --------------- ----------- ------------ ---
       1 default thread            blocked         join      2 SCHED_OTHER  11
       2 thread 0: counting        ready VP 0                  SCHED_OTHER  11
       3 thread 1: dumping         ready VP 0                  SCHED_OTHER  11
       4 thread 2                  blocked         delay       SCHED_OTHER  11
       5 thread 3                  blocked         delay       SCHED_OTHER  11
       6 thread 4                  blocked         delay       SCHED_OTHER  11
       7 thread 5: counting        ready VP 0                  SCHED_OTHER  11
       8 thread 6: dumping         running                     SCHED_OTHER  11
       9 thread 7                  blocked         delay       SCHED_OTHER  11
      10 thread 8                  blocked         delay       SCHED_OTHER  11
      11 thread 9                  blocked         delay       SCHED_OTHER  11

 module name    routine name     line           rel PC           abs PC
*WECRASH        th_run          26411       0000000000000244 0000000000030244
 SHARE$PTHREAD$RTL_DATA0                    000000000001F15C 000000007BC0315C
 SHARE$PTHREAD$RTL_DATA0                    000000000000F494 000000007BBF3494
                                            0000000000000000 0000000000000000
----- the above looks like a null frame in the same scope as the frame below
 SHARE$PTHREAD$RTL_DATA0                                   ?                ?

DBG>
DBG> set source/latest sys$disk:[]
DBG> examine/source .pc-4
module WECRASH
 26411:         lib$signal(SS$_IMGDMP);
DBG>

This example shows the output of the ANALYZE/PROCESS command on a multithreaded process dump, using the /FULL qualifier on an Alpha system.

ANALYZE/RMS_FILE

Invokes the Analyze/RMS_File utility, which is used to inspect and analyze the internal structure of an OpenVMS RMS file. The /RMS_FILE qualifier is required.
For more information about the Analyze/RMS_File utility, refer to the OpenVMS Record Management Utilities Reference Manual or online help.

Format

ANALYZE/RMS_FILE filespec[,...]

ANALYZE/SYSTEM

Invokes the System Dump Analyzer utility, which analyzes a running system. The /SYSTEM 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/SYSTEM

APPEND

Adds the contents of one or more specified input files to the end of the specified output file.

Format

APPEND input-filespec[,...] output-filespec

Parameters

input-filespec[,...]
Specifies the names of one or more input files to be appended. Multiple input files are appended to the output file in the order specified. If you specify more than one input file, separate each file specification with either a comma (,) or a plus sign (+).
The asterisk (*) and the percent sign (%) wildcard characters are allowed in the input file specifications.
output-filespec
Specifies the name of the file to which the input files will be appended.
You must specify at least one field in the output file specification. If you do not specify a device or directory, the APPEND command uses the current default device and directory. Other unspecified fields default to the corresponding fields of the first input file specification.
If you use the asterisk (*) wildcard character in any fields of the output file specification, the APPEND command uses the corresponding field of the input file specification. If you are appending more than one input file, the APPEND command uses the corresponding fields from the first input file.

Description

The APPEND command is similar in syntax and function to the COPY command. Normally, the APPEND command adds the contents of one or more files to the end of an existing file without incrementing the version number. The /NEW_VERSION qualifier causes the APPEND command to create a new output file if no file with that name exists.
Note that there are special considerations for using the APPEND command with DECwindows compound documents. For more information, refer to the Guide to OpenVMS File Applications.

Qualifiers

/ALLOCATION=number-of-blocks
Forces the initial allocation of the output file to the specified number of 512-byte blocks. If you do not specify the /ALLOCATION qualifier, or if you specify it without the number-of-blocks parameter, the initial allocation of the output file is determined by the size of the input file.
The allocation size is applied only if a new file is actually created by using the /NEW_VERSION qualifier.
/BACKUP
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/BEFORE[=time]
Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/BY_OWNER[=uic]
Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.
Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.
/CONFIRM

/NOCONFIRM (default)
Controls whether a request is issued before each append operation to confirm that the operation should be performed on that file. The following responses are valid:

YES NO QUIT

TRUE FALSE [Ctrl/Z]

1 0 ALL

[Return]

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing Return. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.
/CONTIGUOUS

/NOCONTIGUOUS
Specifies that the output file must occupy physically contiguous disk blocks. By default, the APPEND command creates an output file in the same format as the corresponding input file and does not report an error if not enough space exists for a contiguous allocation. This qualifier is relevant only with the /NEW_VERSION qualifier.
If an input file is contiguous, the APPEND command attempts to create a contiguous output file, but does not report an error if there is not enough space. If you append multiple input files of different formats, the output file may or may not be contiguous. Use the /CONTIGUOUS qualifier to ensure that the output file is contiguous.
/CREATED (default)
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/EXCLUDE=(filespec[,...])
Excludes the specified files from the append operation. You can include a directory but not a device in the file specification. Wildcard characters (* and %) are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.
/EXPIRED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/EXTENSION=number-of-blocks
Specifies the number of blocks to be added to the output file each time the file is extended. When you specify the /EXTENSION qualifier, the /NEW_VERSION qualifier is assumed and need not be typed on the command line. This qualifier is relevant only with the /NEW_VERSION qualifier.
The extension value is applied only if a new file is actually created.
/LOG

/NOLOG (default)
Controls whether the APPEND command displays the file specifications of each file appended. If the /LOG qualifier is specified, the command displays the file specifications of the input and output files as well as the number of blocks or records appended after each append operation.
/MODIFIED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.

/NEW_VERSION

/NONEW_VERSION (default)
Controls whether the APPEND command creates a new output file if the specified output file does not exist. (By default, the specified output file already exists.) If the specified output file does not already exist, use the /NEW_VERSION qualifier to create a new output file. If the output file does exist, the /NEW_VERSION qualifier is ignored and the input file is appended to the output file.
/PROTECTION=(ownership[:access][,...])
Specifies protection for the output file.

Specify the ownership parameter as system (S), owner (O), group (G), or world (W).
Specify the access parameter as read (R), write (W), execute (E), or delete (D).

The default protection, including any protection attributes not specified, is that of the existing output file. If no output file exists, the current default protection applies. This qualifier is relevant only with the /NEW_VERSION qualifier.
For more information on specifying protection codes, refer to the OpenVMS Guide to System Security.
/READ_CHECK

/NOREAD_CHECK (default)
Reads each record in the input files twice to verify that it has been read correctly.
/SINCE[=time]
Selects only those files dated on or after the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/WRITE_CHECK

/NOWRITE_CHECK (default)
Reads each record in the output file after the record is written to verify that it was appended successfully and that the output file can subsequently be read without error.

Examples

#1
$ APPEND TEST3.DAT TESTALL.DAT

The APPEND command appends the contents of the file TEST3.DAT from the default disk and directory to the file TESTALL.DAT, also located on the default disk and directory.

$ APPEND/NEW_VERSION/LOG *.TXT   MEM.SUM
%APPEND-I-CREATED, USE$:[MAL]MEM.SUM;1 created
%APPEND-S-COPIED, USE$:[MAL]A.TXT;2 copied to USE$:[MAL]MEM.SUM;1 (1 block)
%APPEND-S-APPENDED, USE$:[MAL]B.TXT;3 appended to USE$:[MAL]MEM.SUM;1 (3 records)
%APPEND-S-APPENDED, USE$:[MAL]G.TXT;7 appended to USE$:[MAL]MEM.SUM;1 (51 records)

The APPEND command appends all files with file types of .TXT to a file named MEM.SUM. The /LOG qualifier requests a display of the specifications of each input file appended. If the file MEM.SUM does not exist, the APPEND command creates it, as the output shows. The number of blocks or records shown in the output refers to the source file and not to the target file total.

#3
$ APPEND/LOG A.DAT, B.MEM C.* %APPEND-S-APPENDED, USE$:[MAL]A.DAT;4 appended to USE$:[MAL]C.DAT;4 (2 records) %APPEND-S-APPENDED, USE$:[MAL]B.MEM;5 appended to USE$:[MAL]C.DAT;4 (29 records)

Previous Next Contents Index