Deployment Options
Deployment OptionsDeployment options determine the operational mode for an interface, which includes
where it gets its input
where it sends its output
who its client is
whether it is single client (cient/server) connection
whether it is a service for multiple clients (a web service)
These are all determined by program command line options.
In this mode, the translator is a standalone console process.
Input
Command input is taken from stdin.
If stdin is an interactive keyboard session, the -prompt switch will prompt the operator for commands with the name of the translator, e.g
fxarc>
Output to stdout
By default, eim output is directed to stdout, which of course can be redirected to a file. By convention, files containing eim data have the file extension .eim.
Output to a Fire session
The translator sends eim data via a socket connection to an existing Fire session running on the same host as the translator. Fire will listen for connections on a dedicated port, determined by the Fire string identifier network_socket. The string value is of the form "host:port".
A translator can be made to connect to this port by starting it with a command line option -mx=host:port.
This type of connection is commonly referred to as a peer-to-peer connection.
Although the translator and Fire communicate via the socket, this is only used for synchronization.Eim data is actually passed to Fire through shared memory.
When Fire gets data from a translator, it processes it asynchronously.
Initialization Examples
The following will run a translator (in this case fxarc) from the keyboard, will prompt for command input and direct output to an eim file. This is useful for translator testing.
fxarc -prompt >arc.eim
This example will run a translator, reading command input from a script file and directing output to an eim file.
fxarc <data.ifx >arc.eim
The next one will run a translator from the keyboard, will prompt for command input and direct output to Fire listening on its network_socket stingray:3218
fxarc -prompt -mx=stingray:3218
In this mode, the translator is a child process of a Fire session initiated by a Fire open command, e.g.
open mychan,-s='fxarc'
As a child process of Fire it is therefore running on the same host.
Where the translator is a database interface, the child process would be started by
database mydb,-nam='mydb_dsn',-prop=odbc
Input
Command input is taken from the translator's stdin piped from Fire.
Output
The translator synchronizes communication with Fire via its stdout which is piped back to Fire. Eim data is passed to Fire via shared memory.
Initialization
A translator is started in this mode by Fire (in response to a Fire open command) with two command-line parameters, e.g
fxarc -mx=stingray:3218,-key=0x42000d
Only Fire can run a translator in this mode. A user should never initiate a translator via such command line parameters, Fire will do this for you.
In this mode, the translator is always a network service and is a stand-alone process serving multiple client data requests. The translator gets registered with a Service Broker resident on a web server, not necessarily on the same host.
The translator receives commands from the Service Broker, which has received them from a client (typically Fire on another machine or across the web) wrapped in http.
Fire will initiate the connection to a translator by the following:
open mychan,-req="http://wrasse/xmarc/Broker?service=FXARC_SVC"
or to a database interface by the following:
database mydb,-req="http://wrasse/xmarc/Broker?service=FX_ODBC"
In these example, Fire connects to a remote service FXARC_SVC or FXODBC_SVC registered with the Service Broker on host wrasse.
The translator returns eim data to the Service Broker, which passes it on to the client wrapped in http.
Communication between the service broker and translator is a socket connection.
A translator is started as a network service with the command line parameter
-url="http://<brokerhost>[:<port>]/xmarc/Broker/register?
service=<svcname>[&host=<host>[&port=<port>]]
[&timeout=<queuetime>:<idletime>]&pwd=<password>"
This is typically done behind the scenes when a service is launched by the Service Manager.
Note: the above code should be one continuous command.
where
<brokerhost[:host]> - the server and optional port number on which the Service Broker is listening. If no port number is supplied, then the default port number of 80 is used.
<svcname> - the name (id) of the service. A unique name must be used to register a logical service or group of services.
<host> - Optional. The server or hostname of the machine that the service is running on. If host is not set, the service will determine ther server's hostname.
<port> - Optional. The port number that the service will comunicate (listen) on. If port is not set, the service will get the host system to allocate one automatically.
<timeout> - Optional. The timeout value determines both the queue and idle times measured in milliseconds. <queuetime> specifies how long a request to a service is queued if all servers for the requested service are busy. <idletime> specifies how long the Service Broker will wait for a response from a service once the request has been forwarded. If timeout has not been set, a default of 30000 ms (30 seconds) is used.
<pwd> - Registering a service requires verification via a password which has been set for the Service Broker by the Service Manager.
Example:
fxarc -url="http://wrasse/xmarc/Broker/register?
service=FXARC_SVC&host=stingray&pwd=secret"
Note: In versions of Fire previous to Fire 5, Fire communicated with the Service Broker via a client-side connector program fxnetsvc. This connector program is no longer necessary, since its functions have been incorporated into Fire versions 5 and later.
Remote services can be managed in 2 ways:
via the Xmarc Service Manager which starts and stops services automatically at machine boot time
on Windows NT systems only, by registering each service as an NT service, managed by the Windows NT operating system.
Xmarc Service Manager
This is a browser-based management tool enabling remote services to be started, stopped and monitored. This tool is discussed in another document Xmarc Service Manager.
Translators as NT Services
On Windows NT platforms, translators can be run as NT services by adding various other command options. Each running translator program can be registered with NT with a default name, or an instance name. This enables multiple NT services to be running the same executable translator. The default name for a translator is Xmarc Service: <progname>
Run / Register
{-reg} {-svc} {-name=xxx}
-svc Run it as a service (does not register without -reg)
-reg Register it as a service (does not run without -svc)
-name=xxx Service name to enter into registry. Omitting it uses the default name.Stop / Unregister
-unreg {-name=xxx}
-unreg Stops the program, unregisters it as a service.
-name=xxx Service name to remove from registry. Omitting it removes the default name.
-v
Display program version information. This does not run the translator.
-h
Display help information. This does not run the translator.
-start=<text_file>
Specifies an initialization script, to be executed before any client connections.
-cd=<directory>
For file-based interfaces, this specifies the initial working directory. All data files in the directory (and sub-directories) become available for client selection.
-con=<connect string>
For database interfaces, this specifies the connection to the database (e.g. Oracle, ODBC etc.). For security purposes, the value of <connect string> may be encoded (created by the fxencode utility).
-if=<text_file>
Take input from a script file of commands. This is an alternative to redirecting stdin.
-of=<eim_file>
Direct eim output to an eim file. This is an alternative to redirecting stdout.
-timreg=<n>
When combined with -url option, specifies a timeout (in seconds) when waiting for the service broker to respond. The default is 30 seconds.
-no_q
Do not run the translator in "quiet" mode, in which some messages get suppressed. The default is to run in quiet mode.
-debug
Run the translator in "debug" mode. This can be useful in tracking down errors in command scripts or tracing possible network connection errors.
-comp=<n>
Run the translator with specific Fire compatibility. Some eim instructions are not compatible with early versions of Fire. To run a translator with versions of Fire prior to release 5, use -comp=<n>, where n is typically 3 or 4.