SIMONE API

Remote Library
August 2010

Copyright LIWACOM Informationstechnik GmbH and SIMONE Research Group. All rights reserved.
2
Contents

1 Introduction .......................................................................................................................... 2

2 Concepts ................................................................................................................................ 2
2.1 SIMONE Remote API Library .................................................................................................................................. 2
2.2 SIMONE API Server .................................................................................................................................................... 2

3 REMOTE API Extensions........................................................................................................ 3

3.1 Remote Sessions ........................................................................................................................................................ 3
3.2 Configuration environment................................................................................................................................... 3
3.3 Additional Error Codes ............................................................................................................................................ 4
3.4 Additional SIMONE API Functions ....................................................................................................................... 4

4 SIMONE API Server ................................................................................................................ 6

SIMONE Remote API 2

1 Introduction
The Remote API allows calling SIMONE API functions transparently over the network. This
eliminates the need to execute a SIMONE API program on the same computer as the SIMONE
Installation resides.
It also provides cross platform access between a SIMONE API program and a SIMONE Installation.
For example the SIMONE Remote API allows using a SIMONE API program on Microsoft Windows to
create input and retrieve results from a SIMONE Installation running on UNIX or Linux and vice
versa.
The use of the SIMONE Remote API requires the special option “Remote API” to be licensed!

2 Concepts
The SIMONE Remote API consists of two components:
• The SIMONE Remote API Library
• The SIMONE API Server
Both components are described in detail below.

2.1 SIMONE Remote API Library

The SIMONE Remote API Library is a DLL on Microsoft Windows (simone_remote_api.dll) and a
shared library on UNIX (simone_remote_api.so).
On Linux the standard library is a 32 bit library for use with 32 bit SIMONE API client programs, a 64
bit library simone_remote_api64.so is provided to support 64 bit clients respectively.

The SIMONE Remote API Library acts as a proxy between the SIMONE API program and the SIMONE
API Server effectively delivering all SIMONE API function calls transparently over the network from
the SIMONE API program to the SIMONE API Server.
If the API program (linked against the SIMONE Remote API) calls a SIMONE API routine, for example
simone_api_version(), the SIMONE Remote API contacts the SIMONE API Server and instructs it to
call the routine simone_api_version() of the local SIMONE API library the SIMONE API Server is
linked against. The SIMONE API Server then transfers the result of the called routine back to the
SIMONE Remote API over the network which itself the delivers the result of the call to
simone_api_version() to the caller.
Due to the fact that the SIMONE Remote API Library exports the same functions as the standard
local SIMONE API library, any of both libraries can be used by the same program without relinking.
If for example a SIMONE API program was created on MS Windows and linked against the default
SIMONE API Library simone_api.dll, it can also make use of the SIMONE Remote API by simply
renaming the SIMONE Remote API Library simone_remote_api.dll to simone_api.dll and making
sure the API program loads the renamed version of the SIMONE Remote API library. The same of
course is possible on UNIX.
As the SIMONE Remote API library does not contain any reference to other SIMONE components, it
can also be used on any machine without a valid SIMONE installation. (The 32 bit version of the
SIMONE Remote API may use an additional SIMONE library trnlogdata.dll, or libtrnlogdata.so on
UNIX, which can simply be copied from a SIMONE installation)

2.2 SIMONE API Server

The SIMONE API Server is a standalone program which locally executes calls to the SIMONE API
requested over the network by a program using the SIMONE Remote API library.
To be able to use the local SIMONE API the SIMONE API Server must be started in an environment
of a valid SIMONE installation and have access to a valid SIMONE configuration database.
Once the SIMONE API Server is started it waits for a connection from a SIMONE Remote API client
and then serves the requests from the Remote API Client to call local SIMONE API functions.

Copyright LIWACOM Informationstechnik GmbH and

SIMONE Research Group. All rights reserved
SIMONE Remote API 3

3 REMOTE API Extensions

There are some extensions required for the SIMONE Remote API as compared to the standard local
SIMONE API.

The SIMONE Remote API needs to know which SIMONE API Server it should contact. This
information can be explicitly provided by using the new routine
simone_set_remote_connection(servername, port) or by setting the environment variables
SIMONE_API_SERVER_HOST and SIMONE_API_SERVER_PORT.
Otherwise the default connection values ‘localhost’ for the API Server name and 6615 for the
default port number are used. For more details refer to the description of routine
simone_set_remote_connection below.

3.1 Remote Sessions

The SIMONE Remote API will initially contact the SIMONE API Server implicitly when calling one of
the following SIMONE API routines:

• simone_api_version()
• simone_init (…)
• simone_init_ex (…)

If successful, this will establish a remote session served by a dedicated Slave API server that
provides the context for servicing further requests. To terminate the remote session the remote API
client has to call simone_end(). This instructs the Slave SIMONE API Server to release all resources
and to shut down itself.
If the client fails to call simone_end(), the explicitly created Slave SIMONE API Server will keep
running, holding all allocated resources. To avoid this to last forever (e.g. in case of a crash of a
client) the SIMONE API Server and the SIMONE Remote API Library use a ‘keepalive’ mechanism
(see below).
Of course a SIMONE Remote API client - after having called simone_end() - can call simone_init()
again to initiate a new connection which will create a new Slave SIMONE API Server for the client.

3.2 Configuration environment

The environment used for the API application is defined when calling simone_init() or
simone_init_ex(). Some special considerations are required in the remote case. Though the
configuration file is specified remotely, it must be accessible using this specification by the slave
API server locally.
If either of simone_init() or simone_init_ex() is called with an empty or NULL init_file parameter,
the SIMONE Remote API library will try to determine the configuration from the environment the
SIMONE Remote API client is running in and send it to the API server, which in turn will effectively
call the respective routine using this as the init_file parameter.
Setting up the environment for a remote client is done the same way as within a SIMONE
installation:
On UNIX this has to be done by setting the environment variable SIMINI accordingly.
On MS Windows this can be done by either using the ‘–i <inifile>’ switch on the command line of
the Remote API Client or by setting the environment variable ‘ZZZIniPath’ to the complete
pathname of a valid SIMONE init file.
If no environment has been set up for the remote client and no init_file parameter is supplied, the
remote API will send an empty string to the server. In this case a temporary copy of the server’s
local configuration will be used for the session.

Copyright LIWACOM Informationstechnik GmbH and

SIMONE Research Group. All rights reserved
SIMONE Remote API 4

3.3 Additional Error Codes

The SIMONE remote API introduces 3 additional error codes which now may be returned by
SIMONE API routines:

simone_status_remotefail Indicates that the SIMONE Remote API was not able to
reach the SIMONE API Server
simone_status_exception An exception has occurred during the call of a SIMONE
API routine in the the Remote API Library. The
exception was caught in the Remote API Library but the
requested SIMONE API function was not called
successfully.
simone_status_not_implemented The requested SIMONE API function is not
implemented in the SIMONE API (or SIMONE Remote
API) the API program is currently running with.

3.4 Additional SIMONE API Functions

simone_get_runmode

INT32 DllExport simone_get_runmode()

This routine returns either SIMONE_RUNMODE_LOCAL if the API program actually uses the local
SIMONE API library or returns SIMONE_RUNMODE_REMOTE if using the SIMONE Remote API
library

simone_api_remote_version

INT32 DllExport simone_api_remote_version()

This routine returns the version number of the SIMONE Remote API library if the API program is
actually running with the SIMONE Remote API.
If the API program actually operates in local mode running with the local SIMONE API library the
routine returns -1.

simone_set_remote_connection

INT32 DllExport simone_set_remote_connection(

/* INPUT */ char *serverhost,
/* INPUT */ int port)

This routine allows to specify the connection information to contact the SIMONE API Server.
serverhost is either the name of the computer the SIMONE API Server is running or the IP-address
as a string in dotted notation like ‘192.168.1.1’.
port is the TCP/IP port number the SIMONE API Server is listening for incoming requests.

If this routine is not called as the first SIMONE API routine in a program using the SIMONE Remote
API the Remote API uses the following default strategy to figure out reasonable default values:

Copyright LIWACOM Informationstechnik GmbH and

SIMONE Research Group. All rights reserved
SIMONE Remote API 5

1. the SIMONE Remote API looks whether the environment variables

SIMONE_API_SERVER_HOST and SIMONE_API_SERVER_PORT are defined. If these
environment variables are defined the values are used to contact the SIMONE API Server.
2. If the above environment variables are not defined or if SIMONE_API_SERVER_PORT does not
contain a valid port number (an integer value > 0), the fixed value localhost is used as the
servername and 6615 is used as port number to contact the SIMONE API Server.

The routine only saves the supplied values for later usage and therefore always returns
simone_status_ok. It does not connect to the API Server directly. However, the API Server is
contacted transparently on calling the first SIMONE API routine which needs to be executed
remotely like simone_init().

If this routine is called while running with the local SIMONE API, it returns
simone_status_not_implemented.

Copyright LIWACOM Informationstechnik GmbH and

SIMONE Research Group. All rights reserved
SIMONE Remote API 6

4 SIMONE API Server

The SIMONE API Server is a standalone SIMONE program which usually resides in the exe-directory
of a SIMONE installation. The SIMONE API Server must be running if a SIMONE API client program
wants to use the SIMONE Remote API library.
Due to the fact that the SIMONE API Server needs the local SIMONE API Library and other SIMONE
shared libraries (or DLL’s on MS Windows), the user has to configure the system in such a way that
the SIMONE API Server is able to load all required external libraries, for example by changing the
environment variable LD_LIBRARY_PATH on UNIX to contain the SIMONE shlib directory.

The SIMONE API Server can be started with the command line switch –h or -? which will then show
all supported switches as explained below:

Simone_api_server –h ↵

simone_api_server [-port <port>][-loglevel <0-9>][-i <inifile>]

[-nslaves <number>] [-keepalive <sec>]
-port set the tcp port the server should listen
-loglevel set granularity of log message
-nslaves set max number of parallel running slave servers
-keepalive set keepalive interval for clients in seconds
supplying 0 disables keepalive handling
-i set INI-file to use

-port <portnumber> will advise the SIMONE API Server to open and listen on TCP/IP port
<portnumber> for incoming requests from SIMONE Remote API clients. Without specifying this
switch the SIMONE API Server will use port number 6615 by default.

-loglevel <number> sets the granularity for log messages regarding the remote network
communication only. <number> should be a value between 0-5 while higher values will generate
more detailed logging output.

-nslaves <number> sets the upper limit of concurrently running Slave API Servers. For any
SIMONE API client to be served the SIMONE API Server will create a new, dedicated Slave API Server
serving only this single remote API client.
By default <number> is set to 10 allowing max 10 Remote API Clients to be running concurrently. If
more clients try to connect to the API Server the Server will deny any connection until it is started
with higher values for –nslaves.

-keepalive <seconds> sets the ‘keepalive’ interval in seconds. The SIMONE API Server and the
SIMONE Remote API Library use a ‘keepalive’ mechanism to allow the API Server to decide whether
a Remote API client is still working properly or not. If a Slave SIMONE API Server assumes that a
client is ‘dead’, the Slave API Server will terminate to avoid wasting resources like memory, locks on
SIMONE resources like networks and scenarios and reaching the nslaves limit described above.
A client could be ‘dead’ due to a program crash of the SIMONE remote API client or due to network
problems.
Setting keepalive to 0 seconds effectively disables the keepalive handling completely which
might cause that Slave API Servers will keep running forever and holding locks on SIMONE
resources after API clients terminating without properly closing the SIMONE API session by
calling simone_end().

Copyright LIWACOM Informationstechnik GmbH and

SIMONE Research Group. All rights reserved
Copyright LIWACOM Informationstechnik GmbH and
SIMONE Research Group s.r.o. All rights reserved.