Local action execution definition file
- Organization of this page
Format
# Common block [cmn [usr JP1-user-name] [var environment-variable-file-name] [evt [{yes|no}]/[{yes|no}]] [cnt-opt [queue=number-of-actions-in-queue] , [exec=number-of-actions-simultaneously-execute]] end-cmn] # Action block act action-name Event filter end-cnd [det same-action-suppress-time] [usr JP1-user-name] [var environment-variable-file-name] cmd command-to-execute [evt [{yes|no}]/[{yes|no}]] [cmd-opt usrprofile={0|1}] end-act : |
Storage destination directory
- In Windows:
-
installation-folder\conf\lcact
shared-folder\jp1base\conf\lcact (in a cluster system)
- In UNIX:
-
/etc/opt/jp1base/conf/lcact/
shared-directory/jp1base/conf/lcact/ (in a cluster system)
Description
This file defines the commands and their execution conditions for the local action function. The file consists of a common block and an action block. The common block defines the parameters commonly set in all actions blocks. The action block defines, in pairs, the JP1 event conditions for actions and the actions to execute when the JP1 event conditions are satisfied.
The local action function checks the execution conditions from the higher-level action block, and execute the action once the conditions are satisfied. If an action blocks on a level lower than the action block satisfies the conditions, the action block is ignored without being checked. Therefore, define conditions in the sequence according to their priority.
Application of settings
Start or reload JP1/Base to apply the settings.
Definition details
The following conventions apply to entries in the local action execution definition file:
-
A hash mark (#) (code 0x23) at the start of a line indicates a comment.
-
The maximum length of a line is 4,200 bytes.
-
Separate parameter with a space (code 0x20) or a tab (code 0x09).
-
Letters are case sensitive.
Only one common block can be specified before an action block. When a parameter is specified in both the common block and the action block, specification in the action block takes effect. The coding conventions for the common block are as follows:
- cmn to end-cmn
-
Indicates the start and end of the common block.
- usr JP1-user-name
-
Specifies the JP1 user maps to the OS user who executes the action. If this parameter is omitted, the same parameter is required in the action block.
- var environment-variable-file-name
-
Specifies the environment variable file names to refer to when executing an action. Enter a file name that is no more than 255 bytes.
- evt [{yes|no}]/[{yes|no}]
-
Specifies whether to issue JP1 events indicating action start and action end. The event before the forward slash (/) is the action start event, and the event after is the action end event. When yes is specified, the system will issue a JP1 event. When no is specified or this parameter is omitted, the system will not issue a JP1 event.
- cnt-opt [queue=number-of-action-in-queue] , [exec=number-of-action-simultaneously-execute]
-
Specifies the number of actions in the queue and the number of actions to be executed simultaneously. Separate the queue option and the exec option with a comma.
- queue=number-of-action-in-queue
-
Specifies the maximum number of actions to be in the queue after the action conditions are satisfied. If the actions exceed the maximum number specified in this parameter, the actions will not be executed. As a result, specify a sufficient number. The specifiable range is from 0 to 65535. The default is 1024.
- exec=number-of-action-simultaneously-execute
-
Specifies the maximum number of actions to be executed simultaneously. When the number of actions in execution has reached the maximum, other actions will wait in the queue. The specifiable range is from 1 to 48. The default is 1.
You can specify no more than 1,000 action blocks. Action blocks cannot be omitted. When a parameter is specified in both the common block and the action block, the specification in the action block takes effect. The coding format for the action block is shown below.
- act action-name to end-act
-
Indicates start and end of the action block. Specify any action name that is 50 bytes or less after the act parameter. Action names are output to the local action execution log.
- cnd to end-cnd
-
This parameter indicates the start and end of the block that specifies the JP1 event conditions for executing an action. Specify this block right after the act parameter. Specify the action conditions in the format of an event filter. For details on the writing format of an event filter, see Event filter syntax.
Note that only the following JP1 events registered on the local event server are subject to the execution condition of the local action (event filter):
-
Event issued from the local event server to the local event server (JP1 event registered reason: 1)
-
Event issued from another event server to the local event server (JP1 event registered reason: 3)
An example is an event registered by using the jevsend command (with the -d option specified) or the jevsendd command from another event server of the local host to the local event server.
JP1 events forwarded from another event server (JP1 event registered reason: 4) are not applicable.
-
- [det same-action-suppress-time]
-
Specifies in seconds the length of time during which same action is not executed. The specifiable range is 1 to 3,600 (seconds). If this parameter is omitted, the same action will not be suppressed.
- usr JP1-user-name
-
Specifies the JP1 user who maps to the OS user who executes the action. You can specify an attribute variable name to JP1 users. If this parameter is omitted, the same parameter is required in the common block.
- var environment-variable-file-name
-
Specifies the environment variable file names to refer to when executing an action. Enter a file name that is no more than 255 bytes. You can specify an attribute variable name in the environment variable file.
- cmd Command-to-execute
-
Specifies the command to be executed for an action. Enter a name that is no more than 4,096 bytes. You can specify an attribute variable name in the command to be executed. For details on the format of the commands to be executed, see 2.8.2 Commands for local actions.
- evt [{yes|no}]/[{yes|no}]
-
Specifies whether to issue JP1 events indicating action start and action end. The event before the forward slash (/) is the action start event, and after is the action end event. When yes is specified, the system will issue a JP1 event. When no is specified or this parameter is omitted, the system will not issue a JP1 event.
- cmd-opt usrprofile={0|1}
-
Specifies whether to load the user profile when executing a command.
The default is 0.
0: Do not load the profile of the user who maps to the OS user.
1: Load the profile of the user who maps to the OS user.
Attribute variable name
You can specify an attribute variable name in specific items of the action block. You can specify an attribute variable name in three items: JP1-user-name, environment-variable-file-name, and command-to-execute. Before the execution of an action, the JP1 event that satisfies the action requirements acquires and expands the attribute value corresponding to the attribute variable name. The acquired information will be expanded in multiple locations, but the character string after the expansion is not expanded. Names of the specifiable attribute variables are shown in the following table.
Type of information |
Attribute variable name |
Contents |
---|---|---|
Information contained in the basic attributes of JP1 events |
EVID |
Event ID (basic-code:extended-code) |
EVPID |
Source process ID |
|
EVUSRID |
User ID of the source process |
|
EVGRPID |
Group ID of the source process |
|
EVUSR |
Source user name |
|
EVGRP |
Source group name |
|
EVHOST |
Host name of the source name |
|
EVIPADDR |
Source IP address |
|
EVMSG |
Entire message text |
|
Information contained in the basic attributes of JP1 events |
EVSEV |
Severity of the event extended information (Emergency, Alert, Critical, Error, Warning, Notice, Information, Debug) |
EV"Extended attribute name" |
Any extended attribute |
The following provides some examples of specifying an attribute variable name.
cmd abcd.bat $EVUSR
This example specifies the attribute variable name EVUSR (attribute value: USER01) in the cmd parameter. In this example, attribute value is expanded to abcd.bat USER01.
Note the following points when specifying an attribute variable name:
-
An action cannot be executed when the length of the character string after an expansion exceeds the limit.
-
Irrelevant attribute variable values are NULL. Depending on the type of JP1 events, some items might not have an attribute variable name, and other might contain unrecognizable character codes (codes excluded from the character set of ASCII code) in attribute information. In such a case, actions cannot be executed, or the result might be incorrect even if an action is executed. Refer to the manual of the product that issues JP1 events when you specify an attribute variable.
-
Do not write alphanumeric characters or underscores (_) right after an attribute variable name. Otherwise, the variable cannot be properly converted. If you want to write characters after the attribute variable name, enclose the name with { and }. The following shows an example, whereas the event ID ($EVID) is assumed to be 100:0, and the extended attribute is EX ($EV"EX") ABC.
Action definition -> Information converted $EVID abc -> 100:0 abc $EVIDabc -> $EVIDabc (in Windows), None (in UNIX) ${EVID}abc -> 100:0abc $EVID_abc -> $EVID_abc (in Windows), None (in UNIX) ${EVID}_abc -> 100:0_abc $EV"EX" abc -> ABC abc $EV"EX"abc -> ABCabc
-
If the characters to be converted include any of the following prohibited characters, the prohibited character is converted into a space (0x20) before proceeding.
Prohibited characters to be converted into a space: 0x01 to 0x1F (except tab characters: 0x09) and 0x7F.
For example, depending on the setting of $EVMSG, if the acquired message contains a linefeed code (0x0A), the linefeed code will be converted into a space (0x20) before being proceeded.
Example: For action echo $EVMSG, assume that the received event message contains a linefeed character: line 1 0x0A line 2, the command executed as an action is: echo line 1 line2, whereas represents a space
-
In UNIX, the final expansion depends on the shell interpretation. If the expanded data contains a character that has specific meaning in a shell, for example, an asterisk *, will be replaced by the pre-defined meaning. To disable the replacement, enclose the entire variable with double quotation marks ("), for example, "$EVMSG".