rtsedit (Edit and output RTS log files)

rtsedit {[-m]|[-e item-ID[,item-ID]...[-q]]
        [-t[start-time][,end-time]]
        [-u editing-unit[-s server-name][-v service-name]]
        [-i editing-interval]
        [-o output-destination-file-name[-l number-of-lines]]}
          RTS-log-file-name[[RTS-log-file-name]...]

The rtsedit command gets real-time statistics from an RTS log file, edits the statistics, and outputs the result to a file or the standard output in CSV format.

-m

Outputs management information about the RTS log file specified in the command argument to the standard output.

When you specify the -m option, you cannot specify other options.

-e item-ID~<unsigned integer> ((1000-2147483647))

Specifies the ID of the item to be edited.

For details about item IDs, see E.5 Real-time statistics.

-q

Outputs hyphens (-) for the number of items, maximum value, minimum value, and average in a time slot that has no real-time statistics for the item ID specified in the -e option.

This option is valid only when the -e option is specified.

If you do not specify this option, no hyphens (-) are output for the time slots that have no real-time statistics.

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

Specifies the period for which data is to be edited. For start-time, specify the time at which editing of the target real-time statistics is to start. For end-time, specify the time at which editing of the target real-time statistics is to end.

For start-time, you can specify a time from 00:00:00 on January 1, 1970, to the current time of the current year, month, and day.

You must specify either a start time or an end time, or both. If you omit the start time, the command outputs real-time statistics from the start of the RTS log file until the specified end time. If you omit the end time, the command outputs real-time statistics from the specified start time until the end of the RTS log file.

Specify the start time and the end time in the hhmmss ([MMDD[YYYY]]) format.

hh: Hour (00 hh 23); Cannot be omitted.

mm: Minutes (00 mm 59); Cannot be omitted.

ss: Seconds (00 ss 59); Cannot be omitted.

MM: Month (01 MM 12); Cannot be omitted.^#

DD: Day (01 DD 31); Cannot be omitted.^#

YYYY: Year (specify a year after 1970 using four digits); Cannot be omitted.^#

#: If the year is omitted from the start or end time, the specified month, day, and time of the current year are assumed. If the year, month, and day are omitted, the current year, month, and day, and the specified time are assumed. You cannot omit only the month and day, or the month or the day. Doing so causes an option error. If you want to omit the month or the day, omit the year, the month, and the day (all three).

If you omit the -t option, all the information in the specified file is edited and output.

-u editing-unit~<all>

Specifies the unit of editing.

sys: Edits the acquired real-time system-wide statistics.

svc: Edits the acquired real-time statistics for each server or service.

all: Edits all the real-time statistics (system-wide, all servers, and all services).

-s server-name~<string of 1-8 characters>

Specifies the name of the server, port number, logical terminal, or first acquisition target whose real-time statistics you wish to edit.

The specification of the -s option is valid when svc is specified in the -u option.

-v service-name~<string of 1-63 characters>

Specifies the name of the service, port number, logical terminal, or second acquisition target whose real-time statistics you wish to edit.

The specification of the -v option is valid when svc is specified in the -u option.

The following table shows the combinations of the -u, -s, and -v options, and the statistics edited as a result.

Table 13-7 Combinations of rtsedit command options and the statistics to be edited

Specification of -u option	Specification of -s option	Specification of -v option	Real-time statistics to be edited
sys	--	--	System-wide statistics
service	Server name	Service name	Statistics for the specified server and service
	Server name	Not specified	Statistics for the specified server
	Port number^#	IP address^#	Statistics for the node for which the specified service information is referenced
	Logical terminal name^#	Not specified^#	Statistics for the specified logical terminal
	Not specified	Service name	Statistics for the specified service
		Service group name^#	Statistics for the specified service group
		Not specified	All non-system-wide statistics
all	--	--	All statistics

Legend:: --: Cannot be specified.

#: Indicates a specification for editing the statistics of an acquisition target that is registered by specifying obj for the -u option in the rtsput definition command or the rtsstats command of the real-time statistics service definition.

-i editing-interval~<unsigned integer> ((10-31536000))

Specifies in seconds the interval for editing statistics and outputting them to a CSV file.

If you do not specify the -i option, the system assumes the output interval specified when real-time statistics are acquired in an RTS log file (value specified in the rts_trcput_interval operand in the real-time statistics service definition) as the value of the -i option.

If you do not specify the -i option and specify multiple RTS log files in the command argument, the system assumes the value of the -i option to be the largest interval among those for outputting real-time statistics to an RTS log file.

The following table lists example valid intervals for outputting edited real-time statistics to a CSV file.

Table 13-8 Examples of valid intervals for outputting edited real-time statistics to a CSV file

Example	Interval for outputting real-time statistics to an RTS log file (seconds)			Value specified for -i option	Valid interval for outputting edited real-time statistics to CSV file (seconds)
Example	RTS log file 1	RTS log file 2	RTS log file 3	Value specified for -i option
1	600	300	200	1000	1000
2	600	300	200	100	100
3	100	200	300	Not specified	300

To check the interval for outputting real-time statistics to an RTS log file, execute the rtsedit command with the -m option specified.

-o output-destination-file-name~<path name of 1-65 characters>

Specifies the name of a file in CSV format to which the edited real-time statistics are to be output.

If you do not specify this option, the command outputs the edited real-time statistics to the standard output.

-l number-of-lines~<unsigned integer> ((1024-65535))

Specifies the number of lines to be output to one file (file in CSV format specified in the -o option).

The range for generation numbers of CSV-format files is from 1 to 999999. When all the lines specified in the -l option have been output, the generation number for a CSV-format file is incremented by one, and output continues. When real-time statistics are output to a file with generation number 999999, the command ends the output processing.

The specification of the -l option is valid only when the -o option is specified.

If you do not specify the -l option, the command does not update the generation numbers of CSV-format files and outputs all of the data to one file.

RTS-log-file-name~<path name of 1-65 characters>

Specifies the name of a RTS log file.

(1) When the -m option is specified (standard output)

[Figure]

1. Displayed repeatedly for each RTS log file

aa...aa: Name of the RTS log file that is read

bbbb: Node identifier

cccc/cc/cc cc:cc:cc: Time when the RTS log file was updated

dd...dd: Output interval; The interval for output of RTS log files is shown in seconds.

ee...ee: The version number of the RTS log file that was read.; "1" indicates an RTS log file acquired by version 07-00 of TP1/Server Base, and "2" indicates an RTS log acquired by version 07-01 or later of TP1/Server Base.

(2) When the -m option is not specified (CSV format)

[Figure]

1 and 2: Displayed as a single line each.

2. Displayed for each server or service for which real-time statistics are acquired for the number of items in the statistics

aa...aa: Name of the RTS log file that is read

bbbb/bb/bb bb:bb:bb: Time when the output file was created

cccc/cc/cc cc:cc:cc: Start time specified in the -t option; Hyphens (-) are displayed if the -t option is not specified.

dddd/dd/dd dd:dd:dd: End time specified in the -t option; Hyphens (-) are displayed if the -t option is not specified.

ee...ee: Editing interval; Valid interval for outputting edited real-time statistics to a CSV file. This interval is set based on the interval for outputting real-time statistics to an RTS log file and the value specified in the -i option.

ffff: Node identifier

gggg/gg/gg gg: gg: gg: Time at which editing of the real-time statistics starts

hhhh/hh/hh hh:hh:hh: Time at which editing of the real-time statistics ends

ii...ii: Name of the server whose real-time statistics are edited; When the server name is _SYSTEM and the service name is , the target statistics are system-wide statistics. If ---- appears in this field, the real-time statistics were acquired without specifying a first acquisition target.

jj...jj: Name of the service whose real-time statistics are edited; When **** is displayed, the target statistics are the real-time statistics acquired from each applicable unit of processing other than services. When is displayed, the target statistics are the real-time statistics acquired from each server. If ---- appears in this field, the real-time statistics were acquired without specifying a second acquisition target.

kk...kk: Type of real-time statistics

ll...ll: Item name

mm...mm: Item ID

nn...nn: Number of items; If there are no real-time statistics to be edited^#, hyphens (-) are displayed. If an overflow error occurs, **** is displayed.

oo...oo: Maximum value; If there are no data values to be edited, hyphens (-) are displayed. If an overflow error occurs, **** is displayed.

pp...pp: Minimum value; If there are no data values to be edited, hyphens (-) are displayed. If an overflow error occurs, **** is displayed.

qq...qq: Average; If there are no data values to be edited, hyphens (-) are displayed. If an overflow error occurs, **** is displayed.

rr...rr: Unit of real-time statistics

vv-rr: Version number - revision number

#

If you specify the -e and -q options when, for the following reasons, there are no real-time statistics to be edited, the system displays hyphens (-) for the number of items, maximum value, minimum value, and average.

The value specified in the -i option (editing interval) is smaller than the interval for outputting real-time statistics to an RTS log file.
Although the value specified in the -i option (editing interval) is equal to the interval for outputting real-time statistics to an RTS log file, there is no data to be edited within the time slot of the editing interval due to a delay in acquiring real-time statistics.
There is a time slot in which no real-time statistics have been acquired because, for example, the output of real-time statistics is temporarily stopped or some items to be acquired have been deleted.
Multiple RTS log files are specified in the command argument and the acquisition times for those RTS log files are not sequential.

Message ID	Description	Output destination
KFCA32714-E	Processing cannot continue due to insufficient process memory.	Standard error output
KFCA32719-E	The command was used incorrectly.	Standard error output
KFCA32720-E	The value specified in a command option is invalid.	Standard error output
KFCA32721-E	The value specified in a command argument is invalid.	Standard error output
KFCA32725-E	An error occurred during file operations.	Standard error output
KFCA32726-E	The specified file already exists.	Standard error output
KFCA32727-E	The specified file is not an RTS log file.	Standard error output
KFCA32728-E	The combination of version and revision of the RTS log file is incorrect.	Standard error output
KFCA32729-E	The command terminated because all the generations of output files were used.	Standard error output
KFCA32730-E	Invalid data was detected while an RTS log file was being accessed.	Standard error output
KFCA32731-E	The specified file does not exist.	Standard error output
KFCA32735-I	Help message	Standard output
KFCA32744-E	The user is not authorized to access the file.	Standard error output
KFCA32745-E	The specified file name is incorrect.	Standard error output
KFCA32759-E	Editing is not possible because the contents of the RTS log file already exist.	Standard error output

If you specify an RTS log file acquired using version 07-00 of TP1/Server Base for editing, zeroes (0) are displayed instead of hyphens (-) as the maximum value, minimum value, and average value for the write (item ID: 1104) and read (item ID: 1107) items in the journal information.
When editing RTS log files acquired using version 07-00 of TP1/Server Base together with RTS log files acquired using later versions, if you specify an editing interval that is longer than the output interval of the RTS log files, zeroes (0) are displayed as the minimum value of the write (item ID: 1104) and read (item ID: 1107) items in the journal information. Also, the average value displayed for these items may be less than the actual average.
If you specify an RTS log file that is in use in a command argument, the command may not be able to output correct information.
If a KFCA32729-E message is output, either increase the value specified in the -i option or decrease the number of RTS log files specified in the command argument, and then re-execute the rtsedit command.
If you specify multiple RTS log files that were acquired on different OpenTP1 systems, make sure that they do not have the same node ID. If you specify RTS log files that have the same node ID, statistics may be compiled on the assumption that the data refers to the same node, or command processing may terminate with the message KFCA32759-E.
Figure 13-1 shows the relationship between RTS log files and the -t and -i options in the following situation:
- Interval for outputting real-time statistics to an RTS log file: 30 minutes
- Value specified in the -t option: 084500, 105500
  
  Figure 13-1 Relationship between RTS log files and specified options