Page Last Updated 2/22/2000
 Select Feed Plus
User Manual

Table of Contents

System Diagram
Synopsis
General
Critical-Message Notification

System Command

Environment Variables

Files and File Formats

Log File
RIC Request File
RIC Update Flag File
RIC Data Archive
Network IO Config File
Script Files
Special Script Transformations

Operator Interaction

System Startup
System Shutdown
Oneshot Mode
Daemon Mode
Interactive Mode
Signal Handling

Periodic Cleanup



Select Feed Plus
User Manual

System Diagram

Synopsis

gensfp tcid script_ext once max_secs

General

Genesis Select Feed Plus (gensfp) is a general purpose programmable client for a Reuters Select Feed Plus TCP-IP feed or an SSL-compliant Select Feed Plus data source (such as Reuters Triarch).

On startup gensfp either

(a) opens a port to a Reuters Select Feed Plus server, establishes an on-line session or

(b) connects to an SSL compliant data source.

Once connected, both versions send a set of RIC requests (read from a file). The returned data are read and, for each data record received, a Genesis Script is executed to format and send the required field values to a target Bank system.

Gensfp runs on any hardware and operating system that supports an ANSI C compiler.

The parameters for gensfp are as follows:

tcid a four or less character code (usually "RSFP") which will be used to ID associated logfiles and data record files

script_ext the 3 character filename extension of the set of scripts that will be associated with this SFP client.

once If this argument is the string "once" gensfp will issue all RIC requests as "oneshot" (current value only (type-340 records)) i.e. no update (type-316) records. Once all the requested RIC responses have been gathered, gensfp is automatically shut down.

max_secs t The number of seconds that gensfp will wait for RICS from the Reuters feed before automatically shutting itself down. If not all the RICS have arrived within this time, gensfp will re-request the late RICS and remain active for some additional time to allow these RICS to be delivered.

Critical-Message Notification

System Command

Critical Messages are delivered by a “system” command which is driven by the environment variable MRG_ECMD. The shell command specified in this variable is executed with a minimum granularity of 10 minutes and is passed any critical messages issued since the last time the command was executed. Unsent critical messages are stored in the file <TCID>.msg which is passed on the standard-input to the command in the MRG_ECMD environment variable. The execution of this command is noted in the logfile (see later). To prevent unnecessary repetition of identical messages, critical messages stored in <TCID>.msg may be processed with “uniq” for example, as follows:

setenv MRG_ECMD “(uniq -6 | mail -S \"Critical Softek Message\" salist)”

Each line in the <TCID>.msg file is timestamped and its process-origin is identified. <TCID>.msg is deleted each time after the command in MRG_ECMD is executed.

To prevent short-term error conditions from producing “orphaned notifications” a 45 second delay is implemented for new batches of error notifications.

Environment Variables

The default behaviour for certain interface functions may be modified by the use of “environment variables”. These variables must be set prior to the interface execution (usually in a “shell” or “batch” file). Equivalent command parameters take precendence over equivalent environment variables. The environment variables, used by the interface, all start with “MRG_” or "SEN_" and are as follows:

MRG_SCREXT Script extension specifier, usually set as an argument to gensfp
MRG_ONCE If this variable has the value "once" or "ONCE", gensfp will keep track of which and how many RICS have been requested and will exit once all the requests have been satisfied.
MRG_MAXSECS The number of seconds that gensfp will wait for RICS from the Reuters feed before automatically shutting itself down. If not all the RICS have arrived within this time, gensfp will re-request the late RICS and remain active for some additional time to allow these RICS to be delivered.
MRG_ECMD The command to be used to process critical (information and error) messages (including all arguments to run the command) is taken from this variable. The command must take its input from the "standard input" stream.
MRG_MSGDIR The directory where transitory work files will be stored. Both critical messages and conversation details (Reuters only) make a temporary appearance in this directory.
MRG_LOGDIR The directory that will be used to store the logfiles generated by this program.
MRG_DLSDIR The directory that will be used to store the RIC Data received by this program.

SEN_LCKDIR see System Startup
SEN_EXE see System Startup
SEN_EXECDIR see System Startup

Files and File Formats

Log File

A logfile named <TCID><mmdd>.log in the directory pointed to by the MRG_DLSDIR environment variable (where <mmdd> stands for the digits representing the month and day that the file was created) is appended to as log-events occur. All "critical" and non-critical messages are logged.

If gensfp is left running overnight, a new logfile is automatically created as soon as necessary after midnight.

RIC Request File

When gensfp starts up it looks in its execution directory for a file named "rics.ini". This file contains a list of RICs, one per line (lines beginning with '#' are ignored), that are requested from the Reuters Select Feed Plus server. Over time, these RIC requests will result in data records being sent to gensfp from the Reuters server. Each time a Reuters response record is received a record-type specific script file is executed by gensfp.

RIC Update Flag File

If, during the execution of gensfp, a file called "rics.lck" appears in its execution directory, gensfp re-reads the RIC Request File and re-issues requests to the Reuters Select Feed Plus server for all the contained RICs.

RIC Data Archive

As each RIC data response record is received it is timestamped and its field contents are recorded in a file called <TCID><mmdd>.rcs (where <TCID> is the code given as argument #1 to gensfp and <mmdd> represents the 2 digit month-number and the 2 digit day-number corresponding to today's system date).

Each record in this file comprises 3 parts as follows:

  1. a timestamp on a line by itself (together with the word "Start RIC" and the name of the RIC).
  2. the fields of the record (each field begins a new line and starts with the Reuters field identifier (a number) followed by a colon (':') character and then followed by the field data.) If the field data contains newline characters, these are also output,
  3. the timestamp in 1. repeated (together with the word "End RIC" and the name of the RIC).


Critical Message File

(UNIX and NT installations only, see “Critical-Message Notification” above)
The file <tcid><mmdd>.msg contains one line for each critical message. Each line comprises four sections:

  1. <application name>
  2. [<DateTime>]
  3. <a critical message>
  4. #<a critical message number>. Error numbers produced by ctksi are in the 120,000 to 129,999 range.

For Example:
cicsfp [Wed Sep 29 12:02:24 1999] RIC RZDET= does not exist #121302

Network IO Config File

When gensfp starts, it reads the file ipmerge.ini (in the current execution directory) which contains information about where to look for input and where to deliver output. Each line of the file ipmerge.ini contains a machine/port-number pair as follows:

<machinename>:<portname>

Where <portname> is the number of a port, or the name of a port (found in /etc/services) that, on the machine named <machinename>, should be serving RIC data in the proper format. If necessary, numbers may be used instead of names for both the above data items. e.g.

192.168.2.1:6500

would be a legal designation for a Reuters Select Feed Plus server. Gensfp is a client to these RIC-data servers. Gensfp is itself a server for two ports whose details are also given in the ipmerge.ini file. When gensfp reads a line of the form:

_OUTPUT_:<portname>

or

_CONTROL_:<portname>

gensfp configures the port whose number is may be derived by looking up <portname> in /etc/services (or whose number is <portname>) to deliver RIC data. Gensfp executes limited control commands sent to it (e.g., via telnet) on the port tagged with the token _CONTROL_.

Lines, in the file ipmerge.ini, starting with the "hash" character (#) are ignored (they are comments or temporarily disabled configuration lines). Both _OUTPUT_ and _CONTROL_ configuration lines must be present, although they may appear anywhere in ipmerge.ini.

Gensfp uses a special form of the _OUTPUT_ designator to indicate that the output should be processed through script files. The special form is:

_OUTPUT_:_SCRIPT_


Script Files

Currently a different script file from gensfp's working directory is executed for each of the Reuters main message types that gensfp handles according to the following table.

Message Type

Name of Script File

340 (Current Value on request)

sfp340.<ext>

316 (Asynchronous Data Update)

sfp316.<ext>

4 (News Item)

sfp4.<ext>

407 (Status Response)

sfp407.<ext>

These additional script files are invoked under the following conditions:

Condition

Name of Script File

gensfp startup

startup.<ext>

gensfp shutdown

shutdown.<ext>

"r" typed at intractive console

operator.<ext>

Special Script Transformations

To facilitate record formatting, some Script Transformations have been developed that are specific to the kind of data received by gensfp.

optionyear
The single character in the workarea is interpreted as an "Option Year Code". The resulting 4-character year is loaded back into the workarea. The initially loaded code should be taken from the last character of an Option RIC.

optionmonthindex

The single character in the workarea is interpreted as an "Option Month Specifier". The resulting 1-based month index is loaded back into the workarea. This transform automatically distinguishes between "call" or "put" option codes. The initially loaded character should be loaded from the character before last of an Option RIC.

expiremonthindex

The single character in the workarea is interpreted as an "Option Expiry Month". The resulting 1-based month index is loaded back into the workarea. The initially loaded character should be taken from the character before last of the relevant RIC, perhaps using the sequence:
save:2
loadric:
transform:lastchars
save:1,1
transform:substr
ifn:transform:expiremonthindex
goto:baddata

optioncallorput

The single character in the workarea is interpreted as an "Option Month Specifier " and then converted into the upper-case word "CALL" or "PUT" depending on which type of instrument this "Month Specifier" would represent.

swapperiod

The RIC in the workarea is decoded to establish its "swap-period". First a RIC delimiter (character in the set [!=.*>:+-,\]) is located, the preceeding character is checked and must be 'Y', the decimal digits preceeding the 'Y' are collected and the string " year" is appended. The resulting string (e.g. "10 year") is loaded back into the workarea. If the initial string (RIC), that is loaded into the workarea, is not of the appropriate form (a swap RIC designator), this transform will fail (see the if script-statement). For example:
USDAM3L15Y=ICAP

in the workarea would be replaced with "15 year".

firstxperiod

The RIC in the workarea is decoded to establish its first time period. The magnitude of the period is isolated and set apart from its period-type by a space. For example:
USD3MX1Y=TTKL

in the workarea would be replaced with "3 M".

secondxperiod

The RIC in the workarea is decoded to establish its first time period. The magnitude of the period is isolated and set apart from its period-type by a space. For example:
USD3MX1Y=TTKL

in the workarea would be replaced with "1 Y".

cashinstrument

swapinstrument

futureinstrument

numslash2tab

FxOptionVol

AddDotToOptionPrice

Operator Interaction

System Startup

On a UNIX system the command i_start should be used to start gensfp in Daemon Mode.

On the NT, an executable binary called ExecIt is provided. Since it takes no arguments, given a suitable program wrapper (not provided) ExecIt may be run as an NT service. Alternatively, ExecIt may be configured to start up on user log-in. ExecIt is configured via the following environment variables:

SEN_LCKDIR
SEN_EXE
SEN_EXECDIR

When ExecIt detects a file "softek.lck" in the directory pointed at by the conents of the SEN_LCKDIR environment variable, ExecIt executes the command, whose name is given by the contents of the SEN_EXE environment variable, found in the directory pointed at by the contents of the SEN_EXECDIR environment variable, (phew!!).

The usual target, on the NT, for ExecIt is a ".cmd" script e.g.

::run all ric directories one after the other
echo off
cd c:\Softek\cicsfp\production
cd ric_fx
del *.log *.rcs *.inp
C:\softek\bin\sed < %SEN_LCKDIR%\..\softek_input\ric_fx.txt > rics.ini -e s/\012/\015/
..\..\debug\cicsfp FX cic once 30
copy *.log %SEN_LCKDIR%\..\log
copy *.rcs %SEN_LCKDIR%\..\log
copy *.inp %SEN_LCKDIR%\..\softek_output
cd ..
del %SEN_LCKDIR%\softek.lck
exit

Note that the ".cmd" script deletes the "softek.lck" file once it has finished processing, thereby providing a signal back to a remote host (that is hosting the "lock" directory) that the data gathering task has finished.

System Shutdown

When gensfp is run interactively (i.e. a command console is available) the operator may issue a 'q' to shut gensfp down. A control+C should also work in this mode. When run in Daemon Mode (UNIX only), the command i_kill should be used. Shutdowns are logged as critical messages and, when an automatic (timed) shutdown is invoked the following statistics are reported.

Number of Rics requested
Number of Rics retrieved
Number of Rics in error (broken down into)
Number rejected,
Number not-permissioned,
Number not-found,
Number of data(script)-errors

Number of Rics not received in time

 

Oneshot Mode

If the third argument to gensfp is the string "ONCE" or "once", or the Environment Variable MRG_ONCE is set to either of these values, gensfp will issue all RIC requests as "oneshot" (current value only (type-340 records)) i.e. no update (type-316) records. Once all the requested RIC responses have been gathered, gensfp is automatically shut down.

Daemon Mode

The program automatically detects if it is to be run non-interactively. If the standard-input is closed during program execution or is redirected to /dev/null at startup, ctksi stops reading the standard-input and stops delivering output to the standard-output and standard-error channels.

Interactive Mode

When the program is run in interactive mode, the following commands are available, all operating systems except MacOS and Windows NT require a <CR> to be appended for the command to be accepted:

  • q or Q quit the program gracefully
  • r or R run the script-file named operator.<ext>
  • k or K list on the controlling window a status line concerning each of the ports specified in the ipmerge.ini file. Information is given about any valid sockets associated with these ports and their states (readable (r), writeable (w), or exception (x)).
  • eof gensfp enters Daemon Mode (see above).

Interactive Mode is intended for use as a debugging aid, since all messages will appear on the screen as they are output. The use of Interactive Mode is strongly discouraged in production since simple keyboard entry may be used to shut the process down.

Signal Handling

On UNIX operating systems, the program catches SIGINT, SIGHUP, and SIGTERM. When one of these signals is detected, the program exits cleanly, closing sockets and writing shutdown information to the logfile. A Critical Message is also generated. On MacOS, only SIGINT is caught, causing clean program termination. Under MSWindows, both SIGINT and SIGTERM receive this treatment.

On UNIX operating systems, SIGPIPE is caught and its passage is noted in the logfile.

Periodic Cleanup

Disk space is consumed according to the number of errors detected by gensfp. Each day that gensfp is executed, a new file (a Log File) may be created in the gensfp log directory. It is suggested that such files are archived and deleted from the drive every few months.