14.2.2 Options

Organization of this subsection
(1) -k edit-item
(2) -m interval
(3) -t [start-time][,end-time]
(4) -u UAP-name[,UAP-name]...
(5) -x host-name[,host-name]...
(6) -s server-name[,server-name]...
(7) -f foreign-server-name[,foreign-server-name]...
(8) -i {input-statistics-unload-file-name|HiRDB-file-system-area-name|input-statistics-unload-file-storage-directory-name}
(9) -o DAT-format-file-output-destination-directory-name
(10) -w work-file-directory-name
(11) -d control-statement-file-name
(12) -b
(13) -e extended-format-specification-value[,extended-format-specification-value]

(1) -k edit-item

[Figure]<<sys>>

Specifies the information that is to be edited.

If you specify sop, dop, pcd, obj, sqh, cnc, fsv, or hba, make sure that the -o option is also specified (otherwise, an error results).

When sop, dop, pcd, obj, sqh, cnc, fsv, or hba is specified, the utility outputs statistical information to a DAT-format file, but it does not edit the statistical information. If you specify all and omit the -o option, the utility continues processing without detecting an error.

sys: System activity statistical information

svr: System activity statistical information by server

uap: UAP statistical information

sql: SQL statistical information

buf: Global buffer pool statistical information

fil: Statistical information on HiRDB files for database manipulation

dfw: Deferred write processing statistical information

idx: Index statistical information

sop: SQL static optimization information

dop: SQL dynamic optimization information

pcd: SQL object execution information

obj: SQL object transfer statistical information

sqh: SQL statement statistical information

cnc: CONNECT/DISCONNECT statistical information

fsv: Foreign server operation statistical information
hba: Foreign server utilization statistical information

all: All the above (if sop, dop, pcd, obj, sqh, cnc, fsv, or hba is specified, the statistical information is output to a DAT-format file only)

(2) -m interval

[Figure]<unsigned integer> ((1-1440)) <<60>>

Specifies in minutes the interval at which totaled values are to be output for the selected types of statistical information. Totaled values for each selected type of statistical information are output at this interval.

(3) -t [start-time][,end-time]

Specifies a log record output start time and end time as the period for which statistical information is to be output. The permitted value range for both the start time and the end time is from 00:00:00 on January 1, 1970, to the current time on the current date.

When this option is omitted, all statistical information in the input statistics unload files and system log files is edited.

When the start time is omitted, editing is from the beginning of the input statistics unload files or system log files to the specified end time. When the end time is omitted, editing is from the specified start time to the end of the statistics input unload files or system log files.

When the option flag is specified, a start time or an end time (or both) must be specified. A time is specified in the format hhmmss[MMDD[YYYY]]:

hh: Hour ((00-23))
mm: Minute ((00-59))
ss: Second ((00-59))
MM: Month ((01-12)) (if omitted, the current month is assumed)
DD: Date ((01-31))
If omitted, the current date is assumed. If an invalid date specified (such as specifying 31 for the month that has only 30 days), the utility carries over the extra days to the next month.
For example, the utility interprets a specification of 00000006312000 as 00:00:00 on July 1, 2000.
YYYY: Year ((1970-9999)) (if omitted, the current year is assumed)

(4) -u UAP-name[,UAP-name]...

[Figure]<character string> ((1-30))

Specifies the names of UAPs that are to be subject to information editing (ID name of a UAP as specified in PDCLTAPNAME in the client environment definition) when the editing is to be of UAP or SQL statistical information, foreign server operation statistical information, or foreign server utilization statistical information.

A maximum of 16 UAP names can be specified. When this option is omitted, the utility edits UAP or SQL statistical information according to the range specified with the -t option.

(5) -x host-name[,host-name]...

[Figure]<identifier> ((1-32))

Specifies the names of the hosts that are to be subject to information editing. A maximum of 32 host names can be specified. When this option is omitted, all hosts become subject to information editing.

(6) -s server-name[,server-name]...

[Figure]<identifier> ((1-8))

Specifies the names of the servers that are to be subject to information editing. A maximum of 32 server names can be specified. When this option is omitted, all servers become subject to information editing.

(7) -f foreign-server-name[,foreign-server-name]...

[Figure]<identifier> ((1-30))

Specifies the names of foreign servers in order to edit statistical information about their operation (foreign server operation statistical information) or utilization (foreign server utilization statistical information).

You can specify a maximum of 32 foreign server names. When this option is omitted, all foreign servers are subject to editing of statistical information.

(8) -i {input-statistics-unload-file-name|HiRDB-file-system-area-name|input-statistics-unload-file-storage-directory-name}

Specifies the input statistics unload files that are to be used as the input information for statistical analysis.

The host executing pdstedit must be able to reference the specified input statistics unload files. An input statistics unload file means an unload statistics log file or an unload log file.

When this option is omitted, the utility assumes the standard input.

input-statistics-unload-file-name [Figure]<path name>
Specifies the name of an input statistics unload file.
HiRDB-file-system-area-name[Figure]<path name> ((up to 165 characters))
Specifies the name of a HiRDB file system area when the desired input statistics unload files are located in a HiRDB file system area.
The utility analyzes all input statistics unload files contained in the specified HiRDB file system area.
input-statistics-unload-file-storage-directory-name[Figure]<path name>
Specifies the name of a directory containing input statistics unload files.
When a directory name is specified, the files under its subdirectories are subject to editing (if there is a HiRDB file system area, the files contained in the HiRDB file system area are subject to editing).
(a) Notes
  1. Specification of relative path
    If you specify a relative path (beginning with a character other than the forward slash (/)) in the -i option, the utility links the executor's PDDIR environment variable to the specified relative path to locate the files or directory subject to analysis. If no such file or directory is found, the utility uses the file under the current directory or the current directory itself.
  2. Output mode for unload statistics log files
    You cannot use the statistics analysis utility on a 32-bit-mode HiRDB to edit an unload statistics log file output by a 64-bit-mode HiRDB.
  3. File type
    Analysis processing may be placed on hold or skipped depending on the type of file or directory specified in the -i option. The following table describes whether or not analysis processing occurs depending on the file type:
    Entity specified by -i optionFile typeAnalysis processing
    FileRegular fileProcessing continues.
    RAW fileProcessing continues.
    Pipe file (FIFO)*Analysis processing is placed on hold until the specified file is opened in write mode by another process.
    OtherAnalysis processing on the specified file is skipped.
    DirectoryFile under the directoryRegular fileProcessing continues.
    RAW fileProcessing continues.
    Pipe file (FIFO)Warning message is output.
    OtherAnalysis processing on the specified file is skipped.

    * You can specify a pipe file (FIFO) when there is only one statistics log file.


(b) Notes on input of unload log files

When you use the pdlogunld command to unload a system log file, specify the -n option (to prevent the system log status from being changed). If the system log status changes, the system log file may not be unloaded for the following reasons:

(c) Notes on input of unload log files in HiRDB file system areas in character special files

It is difficult to collect unload log files in HiRDB file system areas in character special files at a single location because they cannot be transferred to another host by a method such as rcp. In such a case, use the following method to transfer unload log files to another host:

  1. Use the pdfbkup command to create a backup of the HiRDB files in a HiRDB file system area that is subject to analysis.
  2. Use a command such as rcp to transfer the backup file to the other host where pdstedit is to be executed.
  3. Use the pdfmkfs command to create a HiRDB file system area in a regular file for use as input for statistics analysis. To analyze other files at the same time, create a HiRDB file system area in the same directory as for those files.
  4. Use the pdfrstr command to restore the contents of the backup file transferred in step 2 into the HiRDB file system area created in step 3.
  5. When executing pdstedit, specify in the -i option the name of the HiRDB file system area restored in step 4 or the name of the directory containing the HiRDB file system area.

When multiple files are to be analyzed by pdstedit, all the files subject to analysis are placed in a single directory and that directory is specified. However, if an unload log file is located in a HiRDB file system area in a character special file, it is difficult to input it together with other files because it cannot be copied by a command such as cp.

In such a case, by symbolically linking the directory containing the files to be analyzed to the HiRDB file system area in the character special file that contains the unload log files to be analyzed, you can analyze all the files without having to copy the latter.

(9) -o DAT-format-file-output-destination-directory-name

[Figure]<pathname> ((1-128))

When a DAT-format file is to be created by collecting statistical information from an input statistics unload file, specifies the name of the directory under which the DAT-format file is to be created.

(10) -w work-file-directory-name

[Figure]<pathname> ((1-128))

Specifies the name of the directory under which work files are to be created for the statistics analysis utility. When this option is omitted, /tmp or /usr/tmp is assumed. An error results if work files cannot be created in /tmp or /usr/tmp for some reason.

The statistics analysis utility calls a sort program internally. In this case as well, the sort program creates temporary work files in /tmp or /usr/tmp. You can use the TMPDIR environment variable to change the directory where the temporary work files are created.

If the statistics analysis utility is cancelled during execution, such as by forced or abnormal termination of the process, the temporary work files may remain in the directory. If such temporary work files are not needed, the user should delete them. The following files are created in the directory for temporary work files:

-k option valueNames of files that are created
sysPID.syi, PID.syo
uapPID.uai, PID.uao
sqlPID.sqi, PID.sqo
bufPID.bui, PID.buo
filPID.fii, PID.fio
dfwPID.dfi, PID.dfo
idxPID.ixi, PID.ixo, PID.isi, PID.iso
sopPID.soi, PID.soo
dopPID.doi, PID.doo
pcdPID.pci, PID.pco
objPID.obi, PID.obo
sqhPID.qhi, PID.qho
cncPID.cni, PID.cno
fsvPID.fsi, PID.fso
hbaPID.hbi, PID.hbo
Legend:
PID: Process ID
Note
If -k all is specified, all the files listed above are created.

(11) -d control-statement-file-name

[Figure]<pathname>

Specifies the name of the control statements file in which are specified the names of the file groups that store the system log information that is to be input to the statistics analysis utility.

When the -i option is not specified, the status changes to the standard input standby status even if the -d option is specified.

Following is the format of the control statements file (file_group statements); a maximum of 32 control statements can be specified in this file:

file_group server-name:file-group-name[,file-group-name]...

server-name[Figure]<identifier> ((1-8))
Specifies the name of the server corresponding to the file groups. When the -s option is specified and the server name specified here is different from the server name specified in the -s option, the server cannot be analyzed and is ignored. An error will result if the same server name is specified more than once in the control statements file.
file-group-name[Figure]<identifier> ((1-8))
Specifies a file group of physical files that can be referenced from the host that starts the statistics analysis utility.
A maximum of 200 file group names can be specified.
An error results if a file group at another host is specified.
If any file in a file group on a shared disk is specified, however, that file is subject to analysis.
Rules
  1. Specify one control statement per line.
  2. Do not specify spaces or tabs between specification values.
  3. Any text enclosed between /* and */ is treated as a comment.
  4. If the current file group or any inconsistent file group is specified, the utility outputs a warning message and edits statistical information up to immediately before the error was detected (in the case of a duplicate specification, two warning messages may be output).
    The possible causes of warning errors are as follows:
    • End-of-file was detected.
    • File contents are invalid.
  5. If the specified file group has been initialized but not used, the utility outputs a warning message without editing the statistical information (in the case of a duplicate specification, two warning messages may be output).
  6. If a specified file is not a system log file, the utility outputs a warning message without editing the corresponding file group.
  7. If the -i and -d options are both specified, the file group in the control statement file specified in the -d option has already been unloaded, and that unload log file is specified in the -i option, the utility edits the information in the specified file group twice.

(12) -b

Specifies that a title bar is to be output to the DAT-format file. Specification of this option is ignored if the -o option is not specified.

(13) -e extended-format-specification-value[,extended-format-specification-value]

Specifies that the output format is to be changed when a DAT-format file is output. When this option is specified, the -o option must also be specified.

You can specify sec or er1 as an extended format specification value.

sec:
Specifies that the statistics log acquisition time is to be displayed down to the level of the second for the following statistical information:
  • Global buffer pool statistical information
  • Statistical information on HiRDB files for database manipulation
  • Statistical information on deferred write processing
When this option is omitted, the statistics log acquisition time is output in the format MM/DD/hh:mm. When this option is specified, the statistics log acquisition time is output in the format MM/DD/hh:mm:ss.
er1:
Specifies that only significant digits are to be output for overflow data1 or uneditable data.2 When er1 is specified, one asterisk (*) is stored as the value in the case of overflow data or uneditable data.
1 This indicates the error data in microseconds of an overflow exceeding 4,200 seconds.
2 If the HiRDB version from which the input statistics log information was obtained is older than the HiRDB version used to execute pdstedit, the statistics log information may not contain some of the target output items. Such an item that is not included in the statistics log information is referred to as uneditable data.