hdstrcedit (edit an activity trace file)

Function

The hdstrcedit command edits a trace file that has been output during source or target Datareplicator operation and outputs the edited contents to another file (or to the standard output). The command analyzes the entire contents of the activity trace file, and then outputs to the file.

If there are multiple errors based on the specified options, the command outputs as many error messages as it can check. Because the command stores the option analysis results in its local memory.

Format

hdstrcedit -f activity-trace-filename [,activity-trace-filename]
         [ -l { glbl|perf1|perf2 }]
         [ -p process-ID [ -p process-ID ] ...] |
         [ -t start-date-and-time [,end-date-and-time ]]
         [ -o destination-filename ][ -O shortfmt ]

Options

-f activity-trace-filename[,activity-trace-filename]

~ <character string of 1-255 bytes>

Specify the names of the activity trace files that are to be input to the hdstrcedit command. You can specify the following Datareplicator activity trace files:

Source Datareplicator:: Extraction master trace files and extraction node master trace files

Target Datareplicator:: Import trace files

A filename can be the relative or the absolute pathname. You can also use an environment variable, such as $HDSPATH/filename. If you specify a relative pathname, you must execute the command in the current directory.

You can specify no more than two files. If you specify two files, use the comma (,) as the delimiter and ensure that both files are in the same activity range (information collected during Datareplicator operation from the same start command to termination command). When you specify two files, do not specify any spaces before or after the delimiter comma. When two files are specified, the command compares their creation dates and begins by reading the one with the earlier creation date.

The following will result in a command error and processing will be cancelled:

The -f option is omitted.
The file specified in the -f option is not found (if two files are specified and only one of them exists, an error results).
A specified value exceeds 255 bytes.
The -f option is specified more than once.

-l { glbl|perf1|perf2 }

~ <<glbl>>

Specify the type of information you want to output as a result of editing the trace file(s). Specify this value as lowercase letters; otherwise, an error results.

The following table shows the information that is output depending on the -l option specification:

Trace file information that is output	-l option value
Trace file information that is output	glbl	perf1	perf2
Startup information Information indicating execution of processing during startup or termination. Used only once per normal process startup, this information indicates the start and termination of processing and its status.	Y	Y	Y
Global information Information collected at certain points during large-volume processing. This information is used periodically, such as for the unit of transfer or transactions, but its frequency is comparatively low.	Y	Y	Y
Local event information Information indicating changes in Datareplicator's internal processing. This information identifies changes in processing and is used for comparatively low-frequency processing whose volume is smaller than that of the global information.	Y	Y	Y
Performance information (1) Information collected over a comparatively large range (global information + some local events) for the purpose of performance analysis. This information is useful for determining overall performance.	--	Y	Y
Performance information (2) Performance analysis information collected over a smaller range, such as SQL1. When you choose to include this information, be aware that the amount of output can be very large. This provides almost complete performance information.	--	--	Y
Error information Information collected when errors occurred.	Y	Y	Y

Y: The information is output.

--: The information is not output.

Note that you must have specified the selected information for collection in the trace files. For details about the trace file information collection specification, see the source system definition or the target system definition.

The following will result in a command error and processing will be cancelled:

Specifying a value that is not permitted.
Specifying multiple options.

-p process-ID [ -p process-ID ]: ~ <string of numeric characters>; Specify the process IDs for which trace file editing results are to be output. You can specify a maximum of eight process IDs in the format -p process-ID -p process-ID ....; See the error information files for the process IDs. The command does not check the validity of a specified process ID. If a specified ID contains a nonnumeric character, the command assumes the string of numeric characters up to that point as the process ID.; If you specify more than eight process IDs, the command results in an error and cancels processing.

-t start-date-and-time[,end-date-and-time]

~ <YYYYMMDDHHMMSS>

Year (YYYY), month (MM), date (DD), hour (HH), minute (MM), second (SS)

<<all are subject to editing>>

Specify the dates and times defining a period that is to be subject to trace file editing and output. Specify each in the format year (4 digits), month (2 digits), date (2 digits), hour (2 digits), minute (2 digits), and second (2 digits). The specified range must be in the format start-date-and-time[,end-date-and-time].

If you specify only a start date and time, all trace information collected after the specified date and time is edited. If you specify both start and end dates and times, all trace information collected between the specified dates and times is edited. Datareplicator does not check for a leap year or a leap second.

When you specify both start and end dates and times, do not specify any spaces before or after the delimiter comma. If any spaces are specified, Datareplicator will not recognize the specified information correctly.

The following will result in a command error and processing will be cancelled:

The specification format is invalid.
The start-date-and-time are the same as or later than the end-date-and-time.
The -t option is specified more than once.

-o destination-filename

~ <character string of 1-225 bytes> <<standard output>>

Specify the name of the file to which the edited trace information is to be output. If you omit the -o option, Datareplicator outputs the information to the standard output. The specified file does not need to exist. If it already exists, the file is overwritten.

The filename can be the relative or the absolute pathname. You can also use an environment variable, such as $HDSPATH/filename. If you specify a relative pathname, you must execute the command in the current directory.

The following will result in a command error and the processing will be cancelled:

The specified value exceeds 255 bytes.
The -o option is specified more than once.

-O shortfmt: Specifies that the trace information is to be edited and output in the simple format of one entry per line. Datareplicator ignores any value other than shortfmt that is specified in the -O option (a warning message is issued).

Rules

To determine the command's execution results, check the command's return value or check for an error message. The following are the command's return values:

Return value	Termination status	Description
0	Normal termination	Datareplicator has finished reading and editing all data in the input trace files.
1	Abnormal termination	An input trace file resulted in an I/O error; or, the edited results output operation resulted in an I/O error. The contents of an input trace file were not valid. A specified option was invalid and it was not possible to continue command processing.
Undefined	Abnormal termination	Signal interrupt occurred (hdstrcedit command does not handle signals).

Notes

If an input activity trace file ends in the middle of a record, Datareplicator edits the file as follows:
When only one activity trace filename is specified in the -f option:

Datareplicator ignores the incomplete record and handles it as the end of the data.

When two activity trace filenames are specified in the -f option:

Datareplicator concatenates the incomplete record with the first record of the next file.

If the OS returns an error (system call) during the record input operation, Datareplicator handles it as follows:
When the OS returns an error:

Datareplicator outputs an error message and terminates the command.

To execute this command, use the user name that was used to initialize the source Datareplicator (hdestart -i command).

Output format

If the records collected in the activity trace file are normal, Datareplicator edits and outputs them. The following is an example of the results of trace file editing:

Explanation of the output items

When the -O shortfmt option is specified, Nos. 3 through 8 are not output.

Header information (character string identifying this as an activity trace and the command's execution date and time)
Record sequence number, trace level (Lvl), process ID (Pid), identification name (Cpn), trace collection date and time
Values displayed for the trace level (Lvl):
ST: Startup information
GL: Global information
LE: Local event information
P1: Performance information (1)
P2: Performance information (2)
For a list of the process codes (, zzzz) displayed following the process ID (Pid), see Table 7-17 Process codes.
For the relationship between the value (zzzzzz) displayed as the identification name (Cpn) and the displayed information, see Table 7-18 Relationship between the process code and identification name.
The date and time are displayed in the format 4-digit-year-2-digit-month-2-digit-date 2-digit-hour:2-digit-minute:2-digit-second.6-digit-microsecond (the 2-digit hour is in 24-hour time). This format also applies to all subsequent date and time information.
Number of items Datareplicator was unable to send and additional character string information.
Add-strings displays a summary of the activity trace information. It is a character string of up to 24 bytes indicating the purpose of the activity trace, the status, and output source information (internal information).
Start time and end time
This information is displayed only for the performance-related information.
Target identifier (Sndid), data linkage identifier (Ujid), and data sequence ID (Seqn)
In the case of a target system, the target identifier is --------. This information is displayed only for the performance-related information.
Return information
This is a function's return information or information about SQL execution. In the case of a function's return information, the actual return value is displayed; in the case of an SQL execution, SQLCODE and SQLWARN6 or SQLWARN7 are output.
If there is any detail information in binary format, it is displayed in this format.

If there is any detail information in character string format, it is displayed in this format.
Additional-data provides details about the activity trace information. This is internal information and is referenced in the event of an error.

Table 7-17 Process codes

Process code	Process name
TRCR^#	Trace information collection process
MSTR	Extraction master process or import master process
NMST	Extraction node master process
SNDR	Transmission process
SNDM
SNDC
CAPT	Extraction process
RCVT	Reception process (TCP/IP communication)
RCVO	Reception process (OSI communication)
DEFS	Import definition server process
RFCT	Import process
SQLE	Import SQL process
UOCG	Import UOC process

#: Output only once immediately after startup.

Table 7-18 Relationship between the process code and identification name

Process code	Value displayed for Cpn	Trace level	Description	Additional information that is output simultaneously
TRCR	QRCVST	GL	Start of activity trace collection	Message queue ID
MSTR	R_INIT	GL	INITENV (initialization) request issuance trace collection	Request type, object of request
	R_STRT	GL	START request issuance trace collection	Request type, object of request
	R_STOP	GL	STOP request issuance trace collection	Request type, object of request
	R_STTE	GL	STATE request issuance trace collection	Request type, object of request
	R_WTCH	GL	WATCH (monitoring) request issuance trace collection	Request type, object of request
NMST	R_INIT	GL	INITENV (initialization) request reception trace collection	N/A
	R_STRT	GL	START request reception trace collection	Request type, object of request
	R_STOP	GL	STOP request reception trace collection	Request type, object of request
	R_STTE	GL	STATE request reception trace collection	Request type, object of request
	R_WTCH	GL	WATCH (monitoring) request reception trace collection	Request type, object of request
SNDR	SNDSTR	ST	Start of transmission process	Displays hdesender start.
	SNDPPT	P1	Collection of port check transmission performance	Displays Sendperformance: portcheck send.
	SNDPDF	P1	Collection of extraction definition transmission performance	Displays Sendperformance: extract definition send.
	SNDPTW	P2	Collection of transaction management performance	Displays Sendperformance: transaction watch.
	SNDPEX	P1	Collection of update information transmission performance (transmission of all data during the transmission interval).	Displays Sendperformance: sendinterval.
	SNDEND	ST	Termination of transmission process	Displays hdesender stop.
	SNCPSD	P1	Collection of update information transmission performance (transmission of only one data segment)	Displays the transmission split type, number of transmitted transactions, number of update information items, and length in bytes.
	SNCPAU	P2	Collection of the ADT constructor information creation UOC performance	Displays ADT UOC call.
SNDR	SNCPLB	P2	Collection of the queue file storage format assembly performance	Displays EB Log.
	SNCPLC	P2	Collection of the queue file storage format assembly performance	Displays EC Log.
	SNCPUC	P2	Collection of the transmission checking UOC performance	Displays the UOC's return value.
	SNCPCV	P2	Collection of the send data editing performance (repetition column)	Displays hde_edt_extcnv2() call.
	SNCPCV	P2	Collection of the send data editing performance	Displays hde_edt_extcnv() call.
	SNDLYT	P1	Collection of the transmission delay period	Delay period
SNDM	SNMSTR	ST	Start of the extraction node master process	Displays hdesenmst start.
SNDM	SNMEND	ST	Termination of the extraction node master process	Displays hdesenmst end.
SNDC	SNPSTR	ST	Start of the transmission process	Displays hdesndprc start.
	SNPPEX	P1	Collection of the update information transmission performance (transmission of all data during the transmission interval)	Displays Sendperformance: sendinterval.
	SNPEND	ST	Termination of the transmission process	Displays hdesndprc end.
	SNPPPT	P1	Collection of the port check transmission performance	Displays Sendperformance: portcheck send.
	SNPPDF	P1	Collection of the extraction definition transmission performance	Displays Sendperformance: extract definition send.
	SNDLYT	P1	Collection of the transmission delay period	Delay period
CAPT	REDINI	ST	Collection of the READ start point immediately after the start of process	READ point information (binary format)
	SYNCQU SYNCRD	LC	Trace of READ and WRITE point synchronization processing	System log READ point and queue file WRITE point
	CMDTRC	LC	Trace of command acceptance	Details about the command request
	CPDLYT	P1	Collection of the extraction delay period	Delay period
RCVT	RCVDP1	P1	Data reception	Data reception status
	TCPSOP	ER	socket open error	Function's return value, errno
	TCPSOP	GL	Termination of socket open	Function's return value
	TCPSBN	ER	bind error	Function's return value, errno
	TCPSBN	GL	Termination of bind	Function's return value
	TCPSLI	GL	Result of listen	Function's return value
	TCPSCP	GL	Wait for accept	N/A
	TCPSCP	GL	accept return	Function's return value, errno
	TCPFRK	GL	fork error	Function's return value, errno
RCVO	OSITOP	GL	Result of t_open	Function's return value, errno
	OSITBN	GL	Termination of t_bind	Function's return value, errno
	OSITAL	GL	Termination of t_alloc	Function's return value, errno
	OSITLI	GL	Wait for t_listen	N/A
	OSITLI	GL	Result of t_listen	Function's return value, errno
	OSITOP	GL	Result of t_open	Function's return value, errno
	OSITBN	GL	Result of t_bind	Function's return value, errno
	OSITAC	GL	Result of t_accept	Function's return value, errno
	OSIFRK	GL	Result of fork	Function's return value, errno
DEFS	DFINIT	ST	Start of process	Data linkage identifier
	DFEXIT	ST	Termination of process	N/A
	DEFMKP	LE	Start of subprocess (INIT)	Event code, process ID
	DEFMKP	LC	Start of subprocess (NORMAL)	Event code, process ID
	DEFMKP	LC	Start of subprocess (RERUN)	Event code, process ID
	DEFCOM	LC	Detection of command entry	Command name
	DEFMKP	LC	Start of subprocess (event)	Event code, process ID
	DEFMKP	LC	Start of subprocess (hdsstop)	Event code, process ID
RFCT	RFINIT	ST	Start of import process	Datareplicator identifier, data linkage identifier
	EVSTOP	GL	Termination due to the previous event termination	Event ID
	IMSTOP	GL	Immediate termination during start processing	N/A
	RFSTRT	GL	Start of import processing	Start mode, queue file offset
	RFSIGS	LE	Signal reception	Received signal
	RFQGET	P1	Detection of end of queue file	Queue file offset
	RFQGET	P1	Input of queue file data	Queue file offset, update information (first 128 bytes)
	RFTRNC	P1	Transaction entry in the update information	Transaction counter, number of update information items in transaction
	EVENTC	LE	Event detection	Event ID, process status code 1, 2
	RFTERM	ST	Termination of import process	Termination mode, queue file offset
	RFPIPR	P2	Reception of SQL execution result	Destination entry, read size or return code
	RFPIPW	P2	Transmission of SQL execution instruction to the SQL process or UOC process	Destination entry, write size, SQL assembly information (first 128 bytes)
	RFRCVR	P1	Transaction recovery result during rerun (2-phase commit only)	Return code
RFCT	RFCOMT	P1	Result of COMMIT	Reason for commit, return code
	RFENDC	P1	Result of END/DISCONNECT	Type, return code
	RFEXIT	ST	Termination of import process	Type, return code
	RFDLYT	P1	Collection of the import delay period	Delay period
SQLE	SQINIT	ST	Start of process	Start mode (dsid, group name, segment number)
	SQEXIT	ST	Termination of process	Termination mode (NORMAL, FORCE, ERROR)
	SQEREQ	GL	Acceptance of termination request	N/A
	XARERN	LC	Recovery execution (2-phase commit method)	Recovery type
	TRETRY	LC	Transaction retry	N/A
	CNCT_S	P2	Before execution of connect	N/A
	CNCT_E	P2	After execution of connect	SQLCODE
	PINS_S	P2	Before execution of prepare (insert)	SQL statement (127 bytes maximum)
	PINS_E	P2	After execution of prepare (insert)	SQLCODE
	PUPD_S	P2	Before execution of prepare (update)	SQL statement (127 bytes maximum)
	PUPD_E	P2	After execution of prepare (update)	SQLCODE
	PDEL_S	P2	Before execution of prepare (delete)	SQL statement (127 bytes maximum)
	PDEL_E	P2	After execution of prepare (delete)	SQLCODE
	EINS_S	P2	Before execution of execute (insert)	Table name
	EINS_E	P2	After execution of execute (insert)	SQLCODE
	EUPD_S	P2	Before execution of execute (update)	Table name
	EUPD_E	P2	After execution of execute (update)	SQLCODE
SQLE	EDEL_S	P2	Before execution of execute (delete)	Table name
	EDEL_E	P2	After execution of execute (delete)	SQLCODE
	EXEI_S	P2	Before execution of execute immediate	SQL statement (127 bytes maximum)
	EXEI_E	P2	After execution of execute immediate	SQLCODE
	CMIT_S	P2	Before execution of commit	N/A
	CMIT_E	P2	After execution of commit	SQLCODE
	RLBK_S	P2	Before execution of rollback	N/A
	RLBK_E	P2	After execution of rollback	SQLCODE
	XAOP_S	P2	Before execution of xa_open()	N/A
	XAOP_E	P2	After execution of xa_open()	Return value of xa_open()
	XAPR_S	P2	Before execution of xa_prepare()	N/A
	XAPR_E	P2	After execution of xa_prepare()	Return value of xa_prepare()
	XACM_S	P2	Before execution of xa_commit()	N/A
	XACM_E	P2	After execution of xa_commit()	Return value of xa_commit()
	XARL_S	P2	Before execution of xa_rollback()	N/A
	XARL_E	P2	After execution of xa_rollback()	Return value of xa_rollback()
	DISC_S	P2	Before execution of disconnect	N/A
	DISC_E	P2	After execution of disconnect	SQLCODE
	SQPIPR	P2	Read update information	Request type, read size
	PWRT_A	P2	Transmission of PRE-C result	Execution result, write size
	SQPIPW	P2	Transmission of COMMIT result	Execution result, write size
SQLE	CUOC_S	P2	Before execution of column UOC	Column UOC function type
	CUOC_E	P2	After execution of column UOC	Column UOC function type, column UOC function execution result
	CUOC_S	P2	Before execution of column UOC	Column UOC function type
	CUOC_E	P2	After execution of column UOC	Column UOC function type, column UOC function execution result
	SQPIPW	P2	Transmission of update result (up to the synchronization point)	Execution result, write size
UOCG	UCINIT	ST	Start of process	Start mode
	UCEXIT	ST	Termination of process	Termination mode (NORMAL, FORCE, ERROR)
	UBE1_S	GL	Call to hds_ubegin()	N/A
	UEDT_S	GL	Call to hds_uedit()	N/A
	UEND_S	GL	Call to hds_uend()	N/A
	UCPIPR	P2	Read SQL execution instruction	N/A
	UBE1_E	P2	Return from hds_ubegin()	N/A
	UEDT_E	P2	Return from hds_uedit()	N/A
	UEND_E	P2	Return from hds_uend()	N/A
	UCPIPW	P2	Transmission of update result (up to the synchronization point)	N/A
	UCEREQ	GL	Acceptance of termination request	N/A

Output example

The following is an example of an activity trace collected at a target Datareplicator. This example collected the activity trace under the following conditions:

int_trc_lvl=p1 was specified in the target system definition.
hdstrcedit -f reftrc.trc1 -l perf1 -o reftrc.res was executed.

No.00000002, 00000007, 00000014, 00000018, and so on: Each of these processes was started by import processing.

No.00000003, 00000004, 00000025, and 00000026: Reception processing was executed. Perf-info displays the time reception processing started and the time data reception was completed.

No.00000016 and 00000019: Times at which data was read from the import queue file and time at which the transaction was completed (COMMIT). The records between identification name (Cpn) RFQGET, which indicates the import queue file read operation, and RFCOMT, which indicates commit, are the range of this import processing transaction. The interval between these times is the amount of transaction processing time at the target system.

No.00000031 to the end: Each process's termination processing at the target system. For each process ID, the time at which processing terminated is shown.

If you specify p2 for the activity trace collection level and -l perf2 in the hdstrcedit command, each SQL statement's issuance and completion time is displayed in addition to the information shown above.