2.41 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]
 
         [-n]

         [-s syslogfile-name]
 
         [-b XDS-shared-memory-dump-file-output-directory-name]

(b) Estimating the amount of error information

 pdinfoget -m
 
         [-n]

         [-s syslogfile-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 66)

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.tar#
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#
#: date-and-time is formatted as MMDDhhmmss (month, date, hour, minute, second).
If the file size exceeds 2 gigabytes, the file is divided into multiple segments and then output. When this happens, a period (.) followed by a sequencing value is added at the end of each file name, such as .aa, .ab, .ac, .ad, .ae, and so on. Send all such files to customer support.

For details about the error information that is collected in the initial information file, see Table 2-10 List of error information acquired by the pdinfoget command.

(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 68)

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.tar
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).
If the file size exceeds 2 gigabytes, the file is divided into multiple segments and then output. When this happens, a period (.) followed by a sequencing value is added at the end of each file name, such as .aa, .ab, .ac, .ad, .ae, and so on. Send all such files to customer support.

For details about the error information that is collected in the detail information file, see Table 2-10 List of error information acquired by the pdinfoget command.

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

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

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

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 syslogfile-name

Specifies the absolute path name of the syslogfile that is set to be acquired by default by the pdinfoget command.

The table below shows the syslogfile that is acquired by the pdinfoget command by default.

PlatformFile acquired by default
HP-UX/var/adm/syslog/syslog.log
AIX/tmp/syslog.out
Solaris/var/log/syslog
Linux/var/log/messages

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

(e) -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.
(f) -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#
Performance trace informationprf_directory = wwww Mbyte#

Legend: xxx, yyyy, zzzz, wwww: Numeric value

#: 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 return code).
  • Performance trace information files are not acquired.

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

(g) -n

Specifies that the size of performance trace information files is not to be estimated or acquired. Specify this option in the following cases:

Table 2-10 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
Real Time SAN Replication 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
Configuration interface under $PDDIRYYN
Files under $PDDIR/spoolCommand log fileYYN
Message log fileYYN
Error log fileYYN
Failure snap information fileYYN
Abort information fileYYN
cwaitover information fileYYN
Performance trace informationYNY
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
Performance trace information file (output to the directory specified in the pd_prf_output_directory operand)YNY
Configuration information for performance trace information file (configuration information for the directory specified in the pd_prf_output_directory operand)YYN
OS commandInformation about OS status acquired by executing a commandProcess informationYYN
Disk informationYYN
Status of inter-process communication facilityYYN
CPU usage rate and disk statusYYN
Process's CPU activity and memory statusYYN
Virtual memory statusYYN
Kernel parameterYYN
Host nameYYN
Information about the maximum values for system resourcesYYN
OS performance informationYYN
OS information fileDefinition referenced by OS and resulting output fileOS version informationYYN
Machine informationYYN
Processor informationYYN
Installed memory informationYYN
Environment variable informationYYN
Network informationYYN
Network status information#2YN
Disk information#2YN
syslogfileYYN
Back trace informationYYN
Legend:
Y: This information is acquired.
N: This information is not acquired.
#1
If the total size of the files for SQL trace information (pdsql1.trc, pdsql2.trc, pd2sql1.trc, and pd2sql2.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 only in Linux.
#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.
    If the root directory (/) is specified, the KFPN10433-W message is issued. In this case, 4 is set as the pdinfoget command's return code.
  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-11 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
    OSFILE
    SYSLOG
    COREINF
    PRF
    Output directory for detail information filePDDIR
    spool
    tmp
    CLTDIR
    PRF
    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 is displayed during execution of the pdinfoget command, you can still retrieve the error information from the corresponding initial information file because the command 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 can be determined from the command's return code or error messages in the execution log. The following table lists and describes the pdinfoget command's return codes and the actions to be taken:
    Return codeTermination 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, 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.
    3. When the root directory is specified in %PDCONFPATH%
      Processing resumes. Because the error information other than HiRDB's system definition information has already been acquired, obtain the system definition information under %PDCONFPATH%.
    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-11 Directories that cause an error if located in an output directory.
      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.
    12Termination by interrupt (signal generation)Processing was canceled by an interrupt (signal generation).
  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. If the size of the target initial information file or detail information file is smaller than estimated when error information was acquired, the command displays the KFPN00407-W message. If files were not compressed due to a shortage of space, acquire uncompressed files. If the available amount of space indicated in the message can be allocated at another output destination, change the error information output destination, and then re-execute the command.
  3. During execution, the pdinfoget command outputs in message KFPN00451-I the size and number of files subject to archiving and compression. If the size or number of files is large, the processing might take a long time.