Job Management Partner 1/Base User's Guide

jevlogstart

Function

The jevlogstart command starts the log file trapping. This command searches the specified log file for lines that satisfy the conditions specified in the action definition file for log file trapping. It converts each of the matched lines into a JP1 event, and then registers each event in the event server. Before executing this command, you must create an action definition file for log file trapping.

Log files that use different output data formats cannot be handled together by the log file trapping function. In such a case, execute the log file trapping function for each individual log file.

Format

jevlogstart [-f action-definition-file-for-log-file-trapping]
                [-t file-monitoring-interval-in-seconds]
                [-m data-size-for-conversion-in-bytes]
                [-h] 
                [-n display-command-name-for-UNIX only]
                [-p log-data-source-program-name]
                [-r] 
                [-s destination-event-server-name]
                [-a monitoring-target-name]
                log-file-name1[...log-file-name32(100)]

Required execution permission

In Windows: Administrators (If User Account Control (UAC) for Windows is enabled, you must execute the command from the administrator console.)

In UNIX: Superuser

Command directory

In Windows:

installation-folder\bin\

In UNIX:

/opt/jp1base/bin/

Arguments

-f action-definition-file-name

Specify the name of the action definition file for log file trapping in no more than 256 bytes. If you specify a relative path, make sure that the full path when the directory name is added will not exceed 256 bytes. Specify a path relative to the current directory where you execute the command. You can omit this option if you have already created a jevlog.conf file in the conf folder, and have specified the action definitions in that file.

The jevlog.conf file resides in the following directory.

In Windows:

installation-folder\conf\

In UNIX:

/etc/opt/jp1base/conf/

-t file-monitoring-interval (in seconds)

Specify the interval for monitoring the log file. The specifiable range is 1 to 86,400 seconds (24 hours). If you omit this option, the default is 10.

Monitoring a log file in WRAP1, WRAP2, or HTRACE format

If the wrap-around frequency is too high or if the monitoring interval is too long, the file might be overwritten before the log file trap reads the data and some entries might be missed. To prevent entries from being missed, use the following equation to estimate the monitoring interval:

log-file-size (bytes) x number-of-log-files > output-size-per-second (bytes) x monitoring-interval (seconds)

-m data-size-for-conversion (in bytes)

Specify how much data is to be converted into a JP1 event each time a specified log file is read. Specify the number of bytes (1 to 1,024) from the start of a line. The end-of-line character is converted into an end-of-line symbol (\0). This symbol is included in the specified data size. If a line read from a log file exceeds the specified number of bytes, the size of the converted data equals the number of bytes specified by -m, minus one byte.

The value specified in this option indicates the valid range of a line of data in the input log files. Thus, for regular expressions specified in the MARKSTR and ACTDEF parameters in the action definition file for log file trapping, the system check applies only to the regular expressions that are within the range specified in the -m option. Regular expressions that select columns outside this range are not checked. If you omit this option, the default is 512. The end-of-line character is converted into an end-of-line symbol (\0).

-h

Specify this option to read the log from the start of the file. If you execute the jevlogstart command after the program has started, the log already output by the program will not be read. By specifying the -h option, however, you can read the log data from the start of the file. If the log file is a wrap-around file, the trapping service first reads all the log data from the start of the file to the end of the file (EOF), and then finds the current pointer and reads the latest data.

-n display-command-name (for UNIX only)

This option is available for UNIX only.

Specify the display name of the command for the log file trapping. The command name specified in this option is displayed in the result of the ps command. Specify the command name in no more than 256 bytes. If you omit this option, log-file-name1 is assumed as the display command name.

-p log-data-source-program-name

Specify the name of the program that outputs the log data. This name will appear in the Event Console window of JP1/IM - View.

The program name is shown as follows.

In Windows:

/HITACHI/JP1/NT_LOGTRAP/log-data-source-program-name

In UNIX:

/HITACHI/JP1/UX_LOGTRAP/log-data-source-program-name

If you omit this option, the program name is shown as /HITACHI/JP1/NT_LOGTRAP (in a Windows system) or /HITACHI/JP1/UX_LOGTRAP (in a UNIX system).

-r

When the -r option is specified, if a specified log file does not exist when the log file trapping starts, the system keeps trying to access the file, according to the interval specified in the -t option, until the file is created. When file open processing succeeds, the trapping service starts searching the log data.

When the -r option is omitted, the log file trapping cancels access and terminates the processing if a specified log file does not exist when the log file trapping starts.

-s destination-server-name

Specify this option to change the destination server for JP1 event registration to the server specified here. Only an event server running on the local host can be specified. If you omit this option, the local host name is assumed as the event server name (host name returned by the hostname command). Specify a destination server name in no more than 255 bytes. Specify the destination server name in no more than 255 bytes.

This option is primarily for use in a cluster system.

If an event service on a physical host starts with FQDN in an environment with a short name for the local host name, you can use this option to explicitly specify the event server name in the FQDN format.

-a monitoring-target-name

Specify a monitoring target name as an alias for the ID number. You can enter a character string that is no more than 30 bytes for the target name. You can use alphanumeric characters, hyphens, and underscores for the target name. However, the name must start with an alphanumeric character. Event server names are case sensitive.

log-file-name1[...log-file-name32(100)]

Specify each name of the monitored log file in no more than 256 bytes. If you specify a relative path, make sure that the full path when the directory name is added will not exceed 256 bytes. Specify a path relative to the current directory where you execute the command. A log file name cannot start with hyphen (-).

You can specify no more than 32 log files in a Windows system, or 100 for UNIX. Remember that since the number of files that can be accessed concurrently is system-dependent, the maximum number of files that can be actually specified might be fewer than 32 (or 100) in some cases. In a UNIX system, one process is required for monitoring one log file. Therefore, the ps command lists the command names in the form log-file-name.child.

Some types of log files cannot be monitored. For details on the formats of log files that can or cannot be monitored, see 1.5.1 (1) Types of log files that can be monitored.

Notes

Start the log file trapping before you start the program that outputs the log you want to monitor. Trapping will not be performed correctly if the trapping is started while data is already being output to the specified log file. If you wish to specify a log file that does not yet exist, use the -r option to keep the log file trapping waiting for the file.

Before executing the jevlogstart command, ensure that the log-file trap management service (in Windows) or log-file trap management daemon (in UNIX) is running.

Return values

0 Normal end

1 Invalid argument

2 The log-file trap management service or log-file trap management daemon is inactive.

3 The event service is inactive.

4 A monitoring target with the same name has already been started (output only when the -a option is specified).

255 Other error

The jevlogstart command outputs an ID number to the standard output. The ID number is required to stop log file trapping.

Example

These examples are for Windows.
Example 1

Search for and read data from log file c:\log\logfile1.log. Use the defaults for all arguments except the log file name. The action definition file for log file trapping is jevlog.conf in the JP1/Base conf folder, the monitoring interval is 10 seconds, and the data size for event conversion is 512 bytes.
jevlogstart c:\log\logfile1.log
Example 2

Search for and read data from log file c:\log\logfile1.log, using the action definition file for log file trapping c:\conf\configfile.conf.
jevlogstart -f c:\conf\configfile.conf c:\log\logfile1.log
Example 3

Search for and read data from log files c:\log\logfile1.log and c:\log\logfile2.log, using a monitoring interval of 5 seconds.
jevlogstart -t 5 c:\log\logfile1.log c:\log\logfile2.log

[Contents][Back][Next]

[Trademarks]

0	Normal end
1	Invalid argument
2	The log-file trap management service or log-file trap management daemon is inactive.
3	The event service is inactive.
4	A monitoring target with the same name has already been started (output only when the -a option is specified).
255	Other error