API settings file
- Organization of this page
Format
|
server event-server-name communication-type [address [port]] client event-server-name connection-source-address log-keep number-of-log-files log-size file-size bridge name-of-host-that-uses-bridge |
Parameters by type
- Required parameters:
-
-
server (event-server-name and communication-type)
-
- Custom parameters:
-
-
server (address and port)
-
client
-
bridge
-
Storage destination directory
- In Windows:
-
installation-folder\conf\event\
- In UNIX:
-
/etc/opt/jp1base/conf/event/
Description
Defines the method for connecting from the application program to the event server and the port to use for the connection. Under normal circumstances, there is no need to change the default settings. You can add additional information if you want to execute an application program on the local host that obtains JP1 events from an event server on another host.
If you changed the ports parameter of the event server settings file (conf) from the default value, change the API settings file accordingly.
Application of settings
The settings are applied when the JP1/Base event converter or programs linked to an event service, such as JP1/IM or JP1/AJS, starts or restarts.
Definition details
The following conventions apply to entries in the API settings file (api):
-
Each line of the text file is no more than 1,024 bytes and the file size is no more than 2 GB.
-
Separate parameter keywords with a space (code 0x20) or a tab (code 0x09).
-
Do not insert a space or any other characters in front of the parameter name and hash mark (#) (code 0x23) at the start of a line.
-
A hash mark (#) (code 0x23) at the start of a line indicates a comment. You can enter a comment or line space anywhere in a file.
-
Letters are case sensitive.
- server event-server-name communication-type [address [port]]
-
Specify how to connect to the event server. You can specify multiple server parameters if the value in event-server-name is different in each case.
- event-server-name
-
Specify the event server name in either of the following ways:
-
event-server-name
Specify a specific event server name that is no more than 255 bytes.
-
*
Specify a value for the event servers that have not been individually specified.
If this setting is omitted, an application program cannot connect to any event servers that are not individually specified.
-
- communication-type
-
Specify the method for connecting to the specified remote server:
-
keep-alive
Keeps the TCP/IP connection open for reuse unless explicitly disconnected by the application program.
-
close
Closes the TCP/IP connection after acquiring each JP1 event. Specify close if you are using a telephone line, for example, and you do not want to keep the connection open all of the time. Note that specifying close reduces efficiency.
-
- Notes
-
-
Be sure to specify keep-alive if you want to link with the event service in JP1/AJS, JP1/IM, or JP1/Power Monitor.
-
In the following cases, even if you set close, keep-alive is used for the setting:
The IP address resolved from the OS by the physical host name (returned by the hostname command) is the same as the IP address of the event service to which a linked program (such as JP1/AJS, JP1/IM, or JP1/Power Monitor) is trying to connect to.
-
- address
-
Specify the IP address of the connection destination in one of the formats shown below. The specified address must match the value set in the ports parameter for the event server specified in the event server settings file (conf). The default host name is the event server name. We recommend that you specify <jp1hosts2>, unless there is a good reason to do otherwise.
-
IP-address
Specify numbers separated by periods (example: 172.16.50.50).
-
<jp1hosts2>
Specify <jp1hosts2> if you want application programs to connect to the event server using the JP1/Base communication protocol, and if you want to communicate using IPv6 addresses. When the IP address of the destination host is resolved, jp1hosts2 information is referenced, but jp1hosts information is not referenced.
-
host-name
Specify a name that is no more than 255 bytes and can be converted into an IP address by the system's hosts file or name server.
-
0.0.0.0
This value prevents application programs from issuing or acquiring events. (This includes JP1 programs, but excludes application programs that use functions or commands from the pre-Version 6 JP1 programs, JP1/SES and JP1/AJS.)
JP1/AJS and most other programs will still issue events if you specify 0.0.0.0. But by specifying this value, you can reduce the overhead for processing issued events, and speed up event processing.
-
- port
-
Specify the port number using one of the methods below. The specified address must match the value set in the ports parameter for the event server specified in the event server settings file (conf). When no port is specified, the service name is assumed to be jp1imevtapi.
-
port-number
Use numbers to specify the port number.
-
Service name
Specify the tcp service name defined in the system's services file.
-
- client event-server-name connection-source-address
-
Specify the connection source address to be used when connecting to the event server. By default, the client parameter is omitted and the OS automatically assigns the source connection address. In an environment where multiple NICs are assigned, you need to define this parameter to explicitly specify which source connection address to use. You can specify multiple values for this parameter.
- event-server-name
-
Specify the destination event server name in one of the following ways:
-
event-server-name
Specify a specific event server name that is no more than 255 bytes.
-
*
Specify a value for the event servers that have not been individually specified.
The default connection source address is 0.0.0.0.
-
- Connection source address
-
Specify the IP address in one of the following formats:
-
IPv4 address
Specify numbers separated by periods (example: 172.16.50.50). The IP address specified here must be the IP address assigned to the local host.
-
IPv6 address
Specify hexadecimal numbers separated by colons (example: 2001:db8::28). The IP address specified here must be the IP address assigned to the local host.
-
0.0.0.0
The OS automatically assigns the connection source IP to be used.
-
- log-keep number-of-log-files
-
- Number of log files
-
Specify the number of event service API log files (IMEvapi.*) to be saved. The current log file is switched when its size reaches the limit specified in log-size. When the number of log files reaches the maximum you specify here, the oldest file is deleted. Specify a number from 0 to 50. The default is 5. When 0 is specified, logs are not kept.
- log-size file-size
-
- File size
-
Specify the maximum size (in bytes) of an event service API log file (IMEvapi.*). Specify a number from 65536 to 2147483647. The default is 1,000,000. Log information is output only when the API is loaded and when an error occurs.
- bridge name-of-host-that-uses-bridge
-
Specify the name of the local event server that is up and running when SSL communication is enabled for event services and the JP1 event acquisition function (JevGetEvent) is being used on a remote host. For details on the JP1 event acquisition function (JevGetEvent), see the manual JP1/Base Function Reference.
Specify this parameter only if the event service of a physical host is not up and running. If you omit this parameter, it is assumed that a physical host is set.