2.38 pdinfoget (Acquire error information and estimate its volume)

Organization of this section
(1) Function
(2) Executor
(3) Format
(4) Options
(5) Rules
(6) Notes

(1) Function

The pdinfoget command acquires error information when a failure occurs in the HiRDB system in order to determine the cause of the failure. It can also be used to estimate the amount of information to be acquired.

Acquiring error information
If a failure has occurred in HiRDB, you can execute the pdinfoget command to acquire error information for HiRDB and the OS on the host where the command is executed. The pdinfoget command outputs the acquired information to an initial information file or to a detail information file, and it outputs the execution status to the execution log.
Estimating the amount of error information
Acquisition of error information requires a considerable amount of disk space. Depending on the disk configuration, a disk space shortage might occur, resulting in adverse effects on system performance. To avoid this, you should first estimate the amount of space that will be required for the error information (in megabytes). The value provided by the pdinfoget command is the maximum amount of disk space that will be needed for acquisition of error information during execution; it is not the volume of error information that has been acquired.

(2) Executor

HiRDB administrator who is authorized to reference information files output by HiRDB as well as OS information files

(3) Format

(a) Acquiring error information

 pdinfoget -e initial-information-file-output-directory-name
 
         -d detail-information-file-output-directory-name
 
         [-w work-directory-name]
 
         [-s event-log-file-name]
 
         [-l Dr.-Watson-log-file-name]
 
         [-c crash-dump-file-name]
 
         [-b XDS-shared-memory-dump-file-output-directory-name]

(b) Estimating the amount of error information

 pdinfoget -m
 
         [-s event-log-file-name]
 
         [-l Dr.-Watson-log-file-name]
 
         [-c crash-dump-file-name]

(4) Options

(a) -e initial-information-file-output-directory-name

Specifies the absolute path name of an existing directory to which the initial information file (containing information needed to determine the cause of a failure) is to be output. The maximum length of a directory name is as follows.

Length of a directory name (bytes):
Maximum length of a path name in the OS - initial information file name (maximum 62)

If the specified directory does not exist or the write privilege for it has not been granted, the command outputs an error message and cancels processing.

The command outputs the initial information file and the execution log to the specified initial information file output directory. The initial information file is an archive file that consists of multiple files. The names of the files are formatted as shown below:

Initial information file: pdinfoget_host-name_init_date-and-time.exe#
If the host name is longer than 32 bytes, only the first 32 bytes of the host name are used as the file name.
Execution log: pdinfoget_comlog_date-and-time.txt#
#: date-and-time is formatted as MMDDhhmmss (month, date, hour, minute, second).

For details about the error information that is collected in the initial information file, see Table 2-8.

(b) -d detail-information-file-output-directory-name

Specifies the absolute path name of an existing directory to which the detail information file (containing information needed for further investigation after the cause of an error has been determined) is to be output. The maximum length of a directory name is as follows:

Length of a directory name (bytes):
Maximum length of a path name in the OS - detail information file name (maximum 64)

If the specified directory does not exist or the write privilege for it has not been granted, the command outputs an error message and cancels processing.

The detail information file is an archive file that consists of multiple files. The names of the files are formatted as shown below:

Detail information file name: pdinfoget_host-name_detail_date-and-time.exe#
If the host name is longer than 32 bytes, only the first 32 bytes of the host name are used as the file name.
#: date-and-time is formatted as MMDDhhmmss (month, date, hour, minute, second).

For details about the error information that is collected in the detail information file, see Table 2-8.

(c) -w work-directory-name

After acquiring error information, the pdinfoget command archives or compresses the error information by executing a HiRDB or OS command. This option specifies the absolute path name of an existing directory that is to be used to store temporary work files. The maximum length of a directory name is as follows:

Length of a directory name (bytes):
Maximum length of a path name in the OS - work file name (maximum 53)

If the specified directory does not exist or the write privilege for it has not been granted, the command outputs an error message and cancels processing.

The command creates work directory pdinfoget_work_date-and-time under the specified directory and then stores work files in that directory. If there is already a directory named pdinfoget_work_date-and-time, the command terminates with an error.

Estimate the file capacity beforehand and allocate a sufficient amount of disk space. The following shows the estimation formula:

Max (A,B)
A: Estimated size of initial information file displayed with the -m option
B: Estimated size of detail information file displayed with the -m option

If this option is omitted, the following directory is assumed:

-w optionpd_tmp_directory operand in system definition
SpecifiedOmitted
TMP environment variable#
SpecifiedOmitted
SpecifiedDirectory specified in the -w option
OmittedDirectory specified in pd_tmp_directoryDirectory specified in TMP%PDDIR%\tmp directory
#: Environment variable specified for the command execution environment.

If this option is omitted, the temporary files created when the error information is archived or compressed are stored in the directory shown in the table below. In this table, 1 indicates the highest priority for the output destination directory:

ProcessingOutput directoryFile name
Archiving
  1. Directory specified in the TMP environment variable
  2. Directory specified in the TEMP environment variable
  3. Output destination directory for initial information files or detail information files
AFI*
Compression
  1. Directory specified in the TMP environment variable
  2. Output destination directory for initial information files or detail information files
cab*

These files are deleted when the processing terminates.

Note that if an error occurs during the processing, the files might not be deleted. If this happens, delete the files manually.

(d) -s event-log-file-name

Specifies the absolute path name of the event-log-file that is set to be acquired by default by the pdinfoget command. If you specify event log files, specify the event logs that have been saved to a file by a program such as Event Viewer.

By default, the pdinfoget command acquires the following event log files to which event logs existing when the pdinfoget command is executed are backed up:

#
date-and-time indicates the backup time, formatted as MMDDhhmmss (MM: month, DD: date, hh: hour, mm: minute, ss: second).

You might need to use the -s option to acquire a file in the following case:

(e) -l Dr.-Watson-log-file-name

Specifies the absolute path name of a Dr. Watson log file that is to be acquired as initial information.

If this option is omitted, Dr. Watson logs are not acquired.

(f) -c crash-dump-file-name

Specifies the absolute path name of a crash dump file that is to be acquired as detail information.

If this option is omitted, a crash dump files is not acquired.

(g) -b XDS-shared-memory-dump-file-output-directory-name

This option is related to memory databases. Normally, you must not specify this option.

Specifies the absolute path name of an existing directory to which an XDS shared memory dump file is to be output. If this option is omitted, an XDS shared memory dump file is not acquired. The maximum length of a directory name is as follows:

Length of a directory name (bytes):
Maximum length of a path name in the OS - XDS shared memory dump file name (maximum 25)

If the specified directory does not exist or the write privilege for it has not been granted, the command outputs an error message and cancels processing.

For the destination of the XDS shared memory dump file, allocate an amount of space that is at least equal to the value displayed by the -m option as the estimated amount of error information.

If the-m option was not able to provide a value for the estimated amount of error information (because, for example, an error occurred), you must allocate at least twice the sum of the sizes of the database areas for all XDSs in the server machine where the pdinfoget command is executed. For details about estimating the sizes of the database areas for XDSs, see Estimating memory requirements in the HiRDB Version 9 Memory Database Installation and Operation Guide.

Do not specify for the output directory any directory under $PDDIR. If such a directory is specified, HiRDB might terminate abnormally due to a shortage of space.

An XDS shared memory dump file is output when the conditions shown in the table below are satisfied:

ConditionWhether XDS shared memory dump file is output
-b optionXDS status
SpecifiedRunningOutput
InactiveOutput
However, if there is no information in the shared memory, the XDS shared memory dump file is not output.
(h) -m

Specifies that an estimate of the size of the error information to be acquired is to be output. The size estimates are output to the standard output in the following format:

File typeDisplay format (megabytes)
Initial information fileinit_directory = xxx Mbyte
Detail information filedetail_directory = yyyy Mbyte
XDS shared memory dump filedump_directory = zzzz Mbyte#

Legend: xxx, yyyy, zzzz: Numeric values

#: If any of the following is true, 0 Mbyte is displayed:
  • A memory database is not used.
  • A memory database is used, but there is no XDS shared memory dump.
  • A memory database is used, but an error occurred while a XDS shared memory dump was being acquired (4 is set as the %ERRORLEVEL%).

If you also specify the -s, -l, or -c option to acquire error information, the estimate includes the size of that error information. For this reason, always specify the -s, -l, or -c option. If an option other than -s, -l, or -c is specified together with -m, the command will terminate with an error.

Table 2-8 List of error information acquired by the pdinfoget command

Information item to be acquiredWhether acquiredInitial informationDetail information
HiRDB commandInformation about HiRDB status acquired by executing a HiRDB commandUnit and internal component statusYYN
Server process statusYYN
HiRDB server's schedule statusYYN
HiRDB server settingsYYN
HiRDB server status in unitYYN
Information about transaction being executedYYN
User identifier informationYYN
Lock informationYYN
Lock pool usage statusYYN
Internal lock informationYYN
Semaphore informationYYN
Message queue informationYYN
Unit and server statusYYN
Shared memory informationYYN
HiRDB version informationYYN
Server process communication control informationYYN
Global buffer usage informationYYN
RDAREA status displayYYN
SQL object informationYYN
HiRDB setup informationYYN
System switchover facility informationYYN
XDS summary error informationYYN
XDS database statusY#3N
HiRDB information fileDefinition referenced by HiRDB and resulting output fileAll directories and files under %PDDIR%\spoolYNY
Files under %PDDIR%\spoolCommand log fileYYN
Message log fileYYN
Error log fileYYN
Remote command information fileYYN
System switchover facility information fileYYN
Error snap information fileYYN
Abort information fileYYN
cwaitover information fileYYN
System definition information (conf/*, %PDCONFPATH%)YYN
Simple setup tool information (pdistup/*)binNNN
confNNN
iniNNN
sampleYYN
tmpYYN
spoolYYN
pdi_log.txtYYN
HiRDB database environment information (%PDDIR%\.dbenv\*)YYN
Under HiRDB internal work directory (%PDDIR%\tmp\*)YNY
Client trace information (files under %PDCLTPATH%)SQL trace informationY#1#1
Error log fileYYN
pdess* fileYYN
UAP statistical informationYYN
All information about specification difference handling libraries (%PDDIR%\UXPLDIR\*)YNY
Files under specification difference handling library information directorySpecification difference handling library error informationYYN
OS commandInformation about OS status acquired by executing a commandProcess information#2YN
Disk informationYYN
Status of inter-process communication facilityYYN
CPU usage rate and disk status#2YN
Host nameYYN
IP configurationYYN
OS information fileDefinition referenced by OS and resulting output fileOS version informationYYN
Machine informationYYN
Processor informationYYN
Installed memory informationYYN
Registry informationYYN
Environment variable informationYYN
Network informationYYN
Event log fileYYN
Dr. Watson log fileYYN
Crash dump fileYNY
Legend:
Y: This information is acquired.
N: This information is not acquired.
#1
If the total size of files for SQL trace information (pdsql1.trc and pdsql2.trc) does not exceed 100 megabytes, the information is output to the initial information file. If the total size exceeds 100 megabytes, the information is output to the detail information file.
#2
Acquired if the OS is Windows XP or later. This information is not acquired in a Windows version earlier than Windows XP because the required command is not available.
#3
Whether XDS database status information is to be acquired in the initial information file depends on the condition shown in the table below:
ConditionWhether XDS database status information is acquired
XDS statusSystem used to execute command
RunningRunning systemAcquired
Standby systemNot acquired
InactiveRunning systemNot acquired
Standby systemNot acquired

(5) Rules

  1. In order to execute the pdinfoget command, the following environment variables must have been specified in advance:
    PDDIR
    Specifies the HiRDB directory.
    PDCONFPATH
    Specifies the directory for storing the HiRDB system definition files. If this environment variable is omitted, %PDDIR%\conf is assumed.
  2. You can execute the pdinfoget command regardless of whether HiRDB is active.
  3. The output directory specified for the initial information file must not be the same as the output directory specified for the detail information file. If the same directory name is specified for both, the command outputs an error message and terminates.
  4. If a directory name specified in the applicable option exceeds the maximum length, file or directory creation or copy processing results in an error. If this happens, 4 or 8 is set as the pdinfoget command's return code.
  5. If the output directory for the initial information file or for the detail information file contains any of the directories shown in the table below, the command outputs an error message and terminates.

    Table 2-9 Directories that cause an error if located in an output directory

    Output directoryDirectories that cause an error if located in the output directory
    Output directory for initial information fileCLTDIR
    PDDIR
    spool
    conf
    .dbenv
    pdistup
    uxpldir
    OSFILE
    SYSLOG
    COREINF
    Output directory for detail information filePDDIR
    spool
    tmp
    uxpldir
    CLTDIR
    COREINF
    If an error occurs, take one of the following actions, and then re-execute the command:
    • Specify another directory as the output directory for the initial information file or the detail information file.
    • If the existing contents in the directory are not needed, delete them.
  6. If the message shown below is displayed during execution of the pdinfoget command, you can still retrieve the error information from the corresponding initial information file because the command had completed acquisition of the information before it displayed the message. If there is a large amount of detail information and it takes a long time to acquire it, it is possible that you will be able to retrieve and use only the initial information file because the pdinfoget command will have terminated before output to the detail information file was completed.

    KFPN10403-I init information file output, file=initial-information-file-path-name

(6) Notes

  1. The result of the pdinfoget command's execution is set in %ERRORLEVEL%. The following table lists and describes the results and the actions to be taken:
    %ERRORLEVEL%Termination statusMeaning and action
    0Normal terminationTerminated normally.
    If the KFPN10451-I message has been issued, archiving or compression of the error information has not been completed.
    When the error information has already been acquired:
    Acquire the error information as is.
    When the error information has not been acquired:
    Copy the error information to the output destination directory. If an error occurs during the copy processing, check the error messages output to the execution log and the console, eliminate the cause of the error, and then re-execute the command or acquire the information separately.
    4Warning termination
    1. When acquiring error information
      The command was unable to acquire some of the information. Possible reasons are as follows:
      [Figure]A file to be acquired was not found.
      [Figure]A required environment variable was not specified correctly.
      If you need the error information that was not acquired, check the error messages that have been output to the execution log and the console, eliminate the cause of the error, and then re-execute the command or acquire the information separately.
    2. When estimating the amount of error information
      An error occurred when the command output the estimated size of the error information, as specified by the -m option.
      If you are attempting to acquire an XDS shared memory dump file but the attempt failed because the value estimated for the shared memory dump output directory was 0, then allocate at least twice the sum of the sizes of the database areas for all XDSs in the server machine where the pdinfoget command is being executed.
    8Abnormal terminationProcessing was canceled because of an error.
    1. An invalid option was specified.
      Specify the correct options and then re-execute the command.
    2. The same output directory is specified for the initial information file and the detail information file.
      Specify different output directories and then re-execute the command.
    3. Creation of the output directory for the initial information file or for the detailed information file failed, or the command executor did not have the access privilege.
      Grant the write privilege for the specified output directory or specify a directory for which the command executor has the write privilege, and then re-execute the command.
    4. The output directory for the initial information file or for the detail information file contains a directory listed in Table 2-9.
      Check the contents of the specified directory, delete the contents, and then re-execute the command. If you need the contents, specify a different directory and then re-execute the command.
    5. The HiRDB directory (%PDDIR%) has not been specified.
      Specify the HiRDB directory (%PDDIR%) and then re-execute the command.
  2. You must allocate a sufficient amount of disk space for the output destinations of the initial information and detail information files. Note that if you specify a directory under %PDDIR% as the output directory for error information and execute the pdinfoget command during HiRDB operation, HiRDB might terminate abnormally due to a shortage of space.