Page Last Updated 10/23/2002Reuters 2000 and EBS
Interface User ManualTable of Contents
System Diagram
Synopsis
General
ConnectivitySerial
NetworkSystem Command
PrinterEnvironment Variables
File FormatsLog File
Deals File
Sequence File
Critical Message File
Conversation File
Database Access File
Timing Tuning FileDaemon Mode
Interactive Mode
Signal HandlingScript Files
Script Language
Control Flow
Data Manipulation
Screen Manipulation
Additional I/O Functions
OtherNotes for Specific Installations
Deal Integration Warning
System Startup
Use of Script Files
System Shutdown
Periodic Cleanup
TCP-IP Data Transfer
Sybase Table Loading
ZeroBase Table Loading
ODBC Table Loading
Reuters Server and Serial Port Use
Reuters 2000 and EBS
Interface User Manual
ebs [serial-port [server-tcid [scriptt-ext [port [baud]]]]]General
Please note: Both r2k and ebs are network communications programs with identical facilities. For brevity, only r2k is described in this document. The rare cases where differences between r2k and ebs exist are noted. This product loads deals into both front and back office systems; therefore this document uses these terms interchangeably.
The Reuters 2000 Interface (r2k) gathers deal data from a Reuters 2000 serial port and delivers it to a connected host machine. r2k reads Reuters network-protocol packets from the serial-port, sending messages to the server whose TCID is specified as server-tcid. r2k executes a script file whose extension is given by script-ext with deal data loaded from the current deal available on the connected deal-server.
When connected to a Front or Back Office System (FOS or BOS), r2k delivers deals as they arrive (in real time). Interactions are accomplished via user-editable scripts. A description of the script language is given below.
Arguments are position dependent and may be omitted from the right. Default values for these arguments may be machine dependent.
serial-port the name of the host device connected to the Reuters feed.
Operating System
Default
Operating System
Default
UNIX
/dev/ttya
VMS
LTA8001:
MSWindows
COM2:
MacOS
modem
server-tcid the four character TCID of the connected Reuters server. For r2k, an example value of TCID is MLAG. For ebs, the usual value of TCID is QUOT.
script-ext a different script file is executed whenever a deal is received from a connected deal server. The root name of the executed script file depends on the deal type that has just been received, e.g. dofx for FX deals, doswap for swap deals, etc. The script-file filename extension that is used for the current interface session may be changed. For example, an argument of xxx, will cause script files dofx.xxx, doswap.xxx, etc. to be used when deals are received.
port for TCP-IP connectivity use this port number (or name) as the base TCP-IP port for control and data.
baud an attempt will be made to set the serial port to the rate designated by this optional argument. If the rate can't be set, 9600 baud will be used. For backward compatibility, if this argument is the word "fast" or "FAST" then the 19200 baud will be set.
Connectivity
Serial
The Reuters server must be connected to the host computer via an RS232 serial port with hardware flow-control (sometimes known as modem flow-control) capabilities enabled. One copy of r2k is required per RS232 feed and each feed requires a separate RS232 port. On non-VMS operating systems the serial port characteristics are set by r2k. On VMS, the serial port should be set to 9600:8:n:1. On some installations an auxiliary serial port is available and is accessible, for deal-data output, using the sersend script statement (see later).
Network
In TCP-IP-capable network installations, r2k serves two sequential TCP-IP ports whose base number is given in the DL_PORT environment variable. By default r2k uses ports 1601 and 1602 while ebs uses ports 1701 and 1702. In each case the two ports represent “control” and “data” respectively. The “control” port acts on commands, e.g., sent to it by telnet. Data may be sent out both “control” and “data” ports under script control (see script statements netsend and auxsend). Data may be read, under script control using the netload script statement (see later). Connects and disconnects by client processes to these TCP-IP ports are logged. The following commands are recognized on the “control” port.quit<CR> The interface program terminates.
setseq <number><CR> The next ticket requested by the interface will be <number>.
status<CR> The interface reports back three numbers representing the first ticket in the deal server's database, the last ticket in the deal server's database and the next ticket that this interface program will attempt to retrieve. Interfaces delivered since 6/2001 report an additional number representing the elapsed time, in seconds, since a character was last received on the serial line from the deal server. If this number exceeds 130, there is a problem.
Critical-Message Notification
System Command
On UNIX or NT installations critical messages may be delivered by a “system” command which is run in a “shell” and is driven by the environment variable DL_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 DL_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 DL_ECMD “(uniq -6 | cat > /dev/console)”
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 DL_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.
Printer
Certain MSWindows installations are connected to a dedicated printer to which critical messages are immediately sent. Printer-enabled installations may use the environment variable DL_PRINT to control this option. If DL_PRINT has the value “no” e.g. by putting the command
set DL_PRINT=no
or
set DL_PRINT=NO
in AUTOEXEC.BAT or in the command file that invoked an interface executable, then printing is turned off. If DL_PRINT has the value “file”, or no such environment variable is set, then printer output is sent to the file whose name is built from the following elements concatenated together
the contents of the environment variable DL_DLSDIR,
the 4 character TCID for the interface,
the month and day number (in MMDD format) and
the extension “.dpr”
WARNING, on MSWindow 3.x installations, if MSWindows appears to hang, please check that the printer has paper and is on-line.
NOTE, the absence of the DL_PRINT environment variable causes the interface to append all printable information to the ".dpr" file, just as if DL_PRINT had the value "file".
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). Command parameters take precendence over equivalent environment variables. The environment variables, used by the interface, all start with “DL_” and are as follows:DL_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. For example, DL_ECMD may be set to the Softek std2arg command.
DL_LOGDIR The directory where logfiles (see later) will be created.
DL_DLSDIR The directory where deals files (see later) will be created.
DL_SEQDIR The directory where the interface is to look for its sequence file.
DL_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.
DL_PRINT Printable items configuration, see earlier.
DL_PORT The base port number to be used, by the interface, for network communications (network-capable interfaces only).
DL_BAUD An attempt will be made to set the serial-line baud rate to the value of this environment variable. If the attempt fails, 9600 baud is used. For backwards compatibility, if this variable is set to "fast" or "FAST", 19200 baud is set.
DL_TUNING The name of the file containing timing tuning information.
File Formats
Each time the r2k interface is invoked a logfile is written. If the logfile does not exist, it is created, otherwise it is appended to. The name of the logfile is <TCID>mmdd.log , where <TCID> represents the server TCID named in the second argument (without the “<>”characters). Each deal that is received from the server is written to a dealfile named <TCID>mmdd.dls and causes a script to be run. Each time a script is run successfully, the deal’s ticket number is written to the file r2k_<TCID>.seq (r2k_<TCID>.seq;1 on VMS). Although best efforts are made to ensure that the same deal is not transmitted more then once, it is essential that the customer’s data-reading application checks for sequential duplicate ticket numbers as data is assimilated.
The format for information in each of these file-types is as follows.
Log File
Each line in the logfile has three main components:
- which function in the program was responsible for the generation of this message,
- the information part of the message and,
- a timestamp section bracketed by “[]” characters and also containing the name of the source file and the line number within that file that was responsible for the generation of this message.
If the line starts with “****”, the message is critical and indicates possible data loss.
Each time r2k is invoked and shutdown, a minimum of 3 messages are written to the logfile:
- a startup message indicating the starting dealfile name (and consequently the server being targeted),
- an indication of when the r2k program is scheduled to terminate and,
- a shutdown message indicating the last dealfile name written and the number of conversation texts and deal records that were written to the dealfile series.
Deals File
Each dealfile contains pairs of records separated by a blank line. Each pair of records corresponds to the deal data and then the conversation text that resulted in the deal data. Each record (deal data or conversation text) comprises three main parts,
- a timestamp on a line by itself (together with the word “START” and the ticket number).
- the fields of the record (each field begins a new line and starts with the Reuters field identifier (a three character number) followed by a colon (‘:’) character and then followed by the field data.) If the field data contains newline characters, these are also output,
- the timestamp in 1. repeated (together with the word “END” and the ticket number).
Sequence File
The file r2k_<TCID>.seq contains the ASCII representation of the ticket number (followed by the normal end-of-line character(s) for the operating system) for the last complete deal reported in the dealfile. Subsequent invocations of r2k with the same TCID will look for ticket numbers greater than the number stored in this file. For maintenance purposes, this file may be edited by any text editor. NOTE: VMS users should ensure that the resulting (edited) file has version number ;1.
Critical Message File
(UNIX and NT installations only, see “Critical-Message Notification” above)
The file <TCID><ddmm>.msg contains one line for each critical message. Each line comprises four sections:
- <application name>
- [<DateTime>]
- <a critical message>
- #<a critical message number>. Error numbers for r2k are in the 10,000 to 19,999 range, ebs errors are in the range 20,000 to 29,999.
For Example:
Reuters(MLAG) [Tue Nov 14 19:03:06 1995] ****Reuters ticket numbers reset, BEWARE, possible duplicate deals #10045
Conversation File
This temporary file named <TCID>.cnv is written by the Reuters “conversation script” doconv.sip and contains a copy of the conversation associated with the current deal being processed. The file is rewritten with each new deal that is processed and may be deleted without consequence when the interface is not active.
Database Access File
Sybase accesses are controlled through a file called db.conf located in the execution directory of the interface. This file contains one line of white-space separated tokens in the folowing order:
username, password, server, tablename, use_name and an optional “character set” parameter.
On more recent Sybase implementations, the tablename is omitted from this configuration file and is specified in the controlling script. For details on writing data to Sybase tables see later.
An even more recent implementation, used to load a ZeroBase database (using the insertzerobase transform), replaces the "character set" parameter with the name of a stored procedure that will do the actual data load into the specified table.
ODBC accesses are controlled through a file called odbc.conf located in the execution directory of the interface. This file contains one line of white-space separated tokens in the folowing order:
username, password, DSN and tablename.
Since username and password information is contained in these file, protected access to this file should be implemented
Timing Tuning File
This text file (which is located in the interface execution directory and whose name is given in the environment variable DL_TUNING) contains four white-space separated decimal numbers representing certain timing values used by the interface. The configurable variables and their default vaules are shown in the table below. Any lines starting with the character '#' are ignored (comment lines). If the environment variable DL_TUNING is not specified or meaningful values cannot be parsed out of the file, the defaults are used. The values should appear on one line in order of appearance in the table.The default values are in accordance with the TOF and ASI specification and should be overridden only if you are **sure** you know what you are doing.
When used at EBS, to test the ASI under simulated dubious network conditions, some extra parameters are available. These extra parameters are not available to banking customers (they progressively degrade the interface). In the case of "probability" parameters "1" means always and, as a special case, "0" means never
Variable
Default (in seconds)
EBS
Reuters
KeepAliveTime: The programmable time between idle messages sent by the EBS deal server. For R2k this represents how often the interface will proactively confirm that the deal-server is still available.
120 120 WaitForACK: The number of seconds the interface will wait for a low-level ACK character to be sent by the deal server in response to a message sent by the interface.
15 5 WaitForMessage: The number of seconds the interface will wait for a message that has been requested of the deal server before remedial action is taken.
60 35 WaitForChar: The number of seconds that the interface will wait for an expected message-byte to arrive.
5 1 Extra Variables For EBS Only OutLowLevelAckDelay/PlusMinusTenths/IgnoreOneIn: 3 numbers separated by a '/' character. 1) The base amount of time the interface will delay sending out a low-level ACK. 2) The number of tenths of a second up to which will be randomly added or subtracted to/from the base number. 3) The probability (1 in this number) that the transmission of this ACK will be skipped altogether.
0/0/0 - HighLevelDealAckDelay/PlusMinusTenths/IgnoreOneIn: 3 numbers separated by a '/' character. 1) The base amount of time the interface will delay sending out a high-level Deal-ACK message. 2) The number of tenths of a second up to which will be randomly added or subtracted to/from the base number. 3) The probability (1 in this number) that the transmission of this message will be skipped altogether.
0/0/0
- InLowLevelAckIgnoreOneIn: The probability (1 in this number) that an incoming low-level ACK will be ignored by the interface (causing the interface to re-resend a message to the ASI).
0 - OutAckToNackOneIn: The probability (1 in this number) that an outgoing ACK will be sent as a NACK (causing the ASI to resend a message to the interface).
0 -
Operator Interaction
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, r2k stops reading the standard-input and stops delivering output to the standard-output and standard-error channels. This mode of operation is NOT recommended for non-UNIX installations.
Interactive Mode
When the program is run in interactive mode, the following commands are available, all operating systems except MacOS require a <CR> to be appended for the command to be accepted:
q or Q quit the program gracefully
e or E cause all logfile messages to be duplicated to the screen (not just critical ones). Default is “off”, subsequent use of this command will act as a toggle.
o or O cause the individual ticket messages to be displayed on the screen, each field contained within “[]” characters and space separated. Default is “off”, subsequent use of this command will act as a toggle
.
i or I cause the program to ignore subsequent operator input and toggles the “e” and “o” commands to “off”. BEWARE, once you specify this command, there is no way to turn it back on. Program execution will continue until killed or the program timer has expired.
r or R cause the script operator.xxx, found in the r2k application directory, to be run. For Svenska installations, this script is set to delete the WinTrade-synchronization lock file, use with extreme caution.
eof r2k enters Daemon Mode (see above).
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 comms. ports and 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.
Scripts
Interaction with the BOS/FOS is accomplished through the use of user-editable scripts. Each script is contained within a text file. Scripts are initially activated from r2k, but the script language allows users to instruct that commands be taken from additional script files.
Script Files
When r2k starts up, the script startup.xxx is run. Whenever a deal is processed, a different script is invoked for each deal type. For example, the file dofx.xxx is invoked when an FX deal needs to be loaded into the BOS. To facilitate interface monitoring the script file rstatus.xxx or estatus.xxx (Reuters resp. EBS) are run whenever an interface "heartbeat" record is processed. These scripts normally contain just the "exit:" statement, but may be used to proactively inform external systems at regular intervals that an interface is alive and kicking.
Script Language
The interpreted script system (ISS) implements a language somewhat similar to, but much simpler than, the language called BASIC. Each instruction starts and finishes on the same line. Instructions comprise one or two parts separated by a colon (“:”) character. White space before a command is ignored (as are blank lines and lines that start with a hash (“#”) character). This language is “case significant”, upper and lower-case are distinct. On modest processors this language has been benchmarked to execute at several thousand lines per second. A large script comprises about a hundred lines. Script overhead is minimal.
The form of an ISS language statement is[command]:argumentWhere the “[]” characters indicate an optional component (the “[]” characters are not typed and do not form part of the command). When a statement has no command, just an argument, that statement represents a label that is used for control flow e.g.,
:this_is_a_label
Note that the colon character that precedes an argument must be present even if the argument itself is absent, e.g., for a statement like exit: that has no argument.
Commands may be divided into the following categories:
Control Flow
Commands are normally taken from the script file in the order they are presented (from the first line to the last line). It is sometimes necessary to modify this order e.g. to achieve loops (or sequences of repeated instructions). Like BASIC, flow of control is mainly achieved using the commandgoto:labelwith an optional argument that is identical to a label elsewhere in the same script file. Labels may be placed before or after the corresponding goto command and many gotos may reference a single label. Beware, if you use identical label statement in multiple places, only the first occurrence will be used. No error/warning message will be produced and the result may be language statements that are unreachable (and never executed).
Within the goto statement the label (argument) is optional. If it is not provided, the contents of the workarea is used as the target. If the workarea contains an empty string, then the script system invents a label called :BAD_DYNAMIC_LABEL and jumps to it. Thus, by manipulating the content of the workarea the destination of the goto may be calculated (providing a crude form of case statement).
Another command, essential to script flow of control, is theif:<command:arg>statement. An if statement takes as its argument another command (including its argument <command:arg>.) If <command> is successful, then the statement on the line following the if is executed, otherwise, the statement on the line following the if is ignored. Failure of an if argument occurs if the execution of the argument fails for any reason, even if the argument constitutes an illegal command. Thus the command
if:<any garbage here>
ignored statementwill ensure the statement marked “ignored statement” is not executed. This is not a recommended method for causing statements to be ignored, preceding the statement with a “#” (hash), would have a similar effect by turning the statement into a comment.
ifn:<command:arg>performs the “if not” test on <command:arg>. The
exit:[number]statement causes execution of the current script file to stop, returning control to the calling script file or, if there is none, to r2k. The exit statement takes an optional numeric argument. If the argument is non zero then the script appears to fail. This feature can be useful for imbedding a run:script statement (see later) in an if expression.
Finally, the statementrun:<filename>causes subsequent commands to be taken from the filename given as argument. Once this new set of commands have been executed and an exit statement reached, control is passed back to the calling script where execution resumes immediately after the run command. Run can take a special argument
“CON:”the effect of which is to read script statements from the user terminal until the user types
exit:<CR>or causes the execution of an illegal statement. run: statements may be nested and may call themselves (recursion). Beware, each nested use of the run: statement causes several kbytes of stack space to be used. Running out of stack under MSWindows causes unpredictable behavior and may lead to abnormal termination (most commonly of the type known as Protection Violations). Modify your recursive scripts to iterate, or combine several scripts into one to get around this problem.
Data Manipulation
ISS has a workarea into which a string of characters may be loaded. Within this workarea, the string may be transformed and subsequently it may be output to the hosts screen (or Presentation Space) or just written to an output stream. A secondary storage area called the savearea is also available The commands for manipulating these data storage areas are:load:<string>
The characters in <string> are loaded into the workarea. Note the "<>" characters are not significant and simply serve to introduce a connected sequence of characters. They are not typed into the script.The <string> is loaded directly into the savearea without disrupting the contents of the workarea. Two special tokens, each %s may be used in the argument string to refer to the contents of the workarea and the savearea respectively. Thus:load:0, 1, 2, 3
save:-3, -2, -1, %swill result in
-3, -2, -1, 0, 1, 2, 3being placed in the savearea. A further
save:%s, %swill result in the savearea being set to
0, 1, 2, 3, -3, -2, -1, 0, 1, 2, 3
If the optional argument is not provided, the contents of the workarea are copied into the savearea (equivalent to save:%s).
The original contents of the savearea are lost.loadtcid:
The Reuters TCID (Deal Server Identifier) is loaded into the workarea.loadrfield:<number>
The contents of the Reuters field number <number> is loaded into the workarea.loadrticket:
The Reuters ticket number of the current deal is loaded into the workarea.loadpsfield:<number >
The number of characters <number> from the current presentation space’s cursor position are loaded into the workarea.The function <function> is executed on the workarea. The results are placed back into the workarea, replacing its original contents. Certain functions require more than one item of data to operate, such functions obtain this data from a savearea which can be loaded using the save: statement. The save: statement copies the current contents of the workarea to the savearea. The following functions are currently supported. More may be added by Softek or bank technical support staff as necessary.Replaces a date in the workarea that is in the form mmddyy with a date that has century information added in the form "mmddyyyy".buildconv
The workarea is set equal to the name of the "conversation file" for this interface, usually <TCID>.cnv.chopstring
Useful for database loading. This transform expects a string of the form "n,b" (without the quotes) in the savearea and the data to be manipulated in the workarea. After the script statement has completed, the workarea contains n comma separated, double quoted strings of data, each with a maximum number of bytes given by b. The resulting quoted strings will have had any imbedded single quotes removed and all imbedded double quotes will have been converted to single quotes.crto251
All occurrences of ASCII CR (0x0d) and ASCII NL (0x0a) found in the workarea are replaced by decimal 251 characters (0xfb). This is used to ensure that the only line-termination characters used in a record indicate the end of the record. The BOS or FOS data assimilation functions should assume that any decimal 251 characters found in a text field were originally NL characters.ctime2r2k
Replaces a date in the workarea that is in the ANSI ctime() format with a date in Reuters format "dd mmm yyyy". The workarea may be loaded with a ctime() date by calling the date script statement (see below).dmy2mdy
Replaces a date in the workarea that is in the form "dd mmm yyyy" with a date of the form "mmm dd yyyy".elocaldate
Replaces a GMT EBS date/time with its equivalent local-time Reuters-format date. A GMT data/time (EBS defines a 12 character format) must be loaded into the workarea . Available to EBS interfaces only.elocaltime
Replaces a GMT EBS date/time with its equivalent local-time Reuters-format date. A GMT data/time (EBS defines a 12 character format) must be loaded into the workarea . Available to EBS interfaces only.escapequotes
Instances of the double-quote character (") found in the workarea are prepended with two backslash characters (\\). These should be sufficient to pass the double-quote characters through one level of script text manipulation (through, say, an appendbuf command).getenv
The contents of the workarea is replaced by the system environment variable whose name was originally in the workarea. If no such variable is found, the statement will return a failure and the original workarea is left unchanged. See the if statement.The string in the workarea is replaced by its last n characters. The number n being given by the contents of the savearea. Used for picking the last few characters off the end of a string.masklong
The "C" style long decimal printf designation (e.g., %0.4ld) stored in the savearea is applied to the string representation of a long integer stored in the workarea. The resulting, formatted, number is stored back in the workarea.maskldbl
The "C" style long double printf designation (e.g., %.2Lf) stored in the savearea is applied to the string representation of a long double stored in the workarea. The resulting, formatted, number is stored back in the workarea.The current deal record is checked to determine if it is the first seen member of a multi-part matching deal. This function will succeed if the current deal is *NOT* the first seen deal of this type (in other words, this function returns "true" to an if expression if the current deal is *NOT* associated with a brokerage charge).The comma separated fields, quoted as necessary, loaded into the savearea, are passed to an ODBC table loading function. If the load did not succeed a failure value is returned. For a more complete description see later .The SQL statement in the workarea is executed via the ODBC SQLExecDirect API call. see later for a little more detail.omspackage
The State Street data record stored in the workarea is formatted, together with the ticket number (stored in the savearea) to form a State Street TCP-IP record. The format of header and trailer for this record is as follows (tokens in italics represent values, spaces are not part of the header/trailer, tokens separated by "|" means one of the tokens in the set. All other tokens are literal): <S R|E TCID TicketNum DataByteCount Data R|E TCID TicketNum DataByteCount E>rlocaldate
Replaces a GMT Reuters date with its equivalent local-time date. A Reuters GMT data must be loaded into the workarea and a Reuters GMT time must be loaded into the savearea . Available to Reuters interfaces only.rlocaltime
Replaces a GMT Reuters time with its equivalent local-time date. A Reuters GMT time must be loaded into the workarea. Available to Reuters interfaces only.strchr
The workarea is searched for the first character loaded into the savearea. If a match is found, the workarea is changed to point at the location of the match.striptrails
Trailing spaces are stripped from the workarea.striptrailzs
Trailing zeros are stripped from the number in the workarea. If the workarea contains a floating point number, at least one zero is left to the right of the decimal point.The pattern of the form "x,y" loaded into the savearea, it applied to carve from the workarea a substring starting at position "x" (1 based) and of string length "y". The resulting substring is loaded back into the woarkarea.system
The string loaded into the workarea is executed by the operating system's command interpreter.The comma separated fields, quoted as necessary, loaded into the savearea, are passed to a Sybase table loading function. If the load did not succeed a failure value is returned. For a more complete description see later .Fields that comprise a Reuters or EBS field number followed by an equal sign ("=") and followed by three digits that represent the length of the data for this field, followed by the data itself are loaded into the savearea.These fields (loaded into the savearea), are passed to a CtLib Sybase table loading function. If the load did not succeed a failure value is returned. For a more complete description see later .
Screen Manipulation
NOTE: These functions are not available unless HLLAPI BOS data loading is implemented.
ISS performs screen manipulation functions using the HLLAPI “Presentation Space” concept. A HLLAPI Presentation Space corresponds to a screen that is connected to a host. The connected screen must be identified by the “short name” of “K” (use the menu dialog “Session:EHLLAPI Configuration...” in the RUMBA terminal emulator to set this parameter). ISS uses a variable called the “location” in some of the following Presentation Space manipulation commands. NOTE: 1) Due to the difference between buffered and asynchronous input (3270 vs. RS232) some important ISS statements will not work on a VAX-hosted BOS. ISS statements of this type are marked with a Ý. 2) The location is manipulated independently of the cursor position.The location is set to the start of the string <string> found in the Presentation Space. The search of the Presentation Space always starts at the top left of the screen and proceeds by rows until the bottom of the screen is reached.locatenext:<string>
Similar to locate except the search of the Presentation Space starts from one plus the value of the location.advance:<number>
The current cursor position is advanced <number> characters.Output the string <string> to the Presentation Space. Characters will appear at the current cursor position.setcursor:Ý
Set the cursor to the current location.putafter:<string> 1Ý
Put the contents of the workarea after the string <string> located in the Presentation Space.putafternext:<string>Ý
Similar to putafter except the search of the Presentation Space starts from one plus the value of the location.findfield:<relative position> Ý
Set the location to the field specified by <relative position> which is a two character string, the first character specifying the relative position of the target and the second specifying the type of field to be referenced. The first character (field position) may be one of the following:<space> or “T” meaning the current field (go figure),“P” meaning the previous field, or
“N” meaning the next field.
The second character (field type) may be one of the following:
<space> meaning any type of field
“P” meaning a protected field, or
“U” meaning an unprotected field.For example.
findfield:NUwill set the location to the next unprotected field after the current value of the location.
setafter:<string>Ý
Put the string of characters <string> in the next unprotected field after the current value of the location, setting location and the current cursor position to the beginning of this field.put:
This is like send: except that the characters to be placed in at the current cursor position in the presentation space are taken from the workarea.The argument is printed on the attached printer. Two special tokens are available within the argument string, Both are introduced by the character sequence %s. The first time this sequence is encountered within the argument string the contents of the workarea are substituted, the second time, the contents of the savearea are substituted. This command is useful for sending critical alerts to the bank supervisor. Normal “C” language “\” (backslash) escapes are available e.g. \n means newline, \t means tab, \nnn means output the character whose ASCII code corresponds to the number represented by octal nnn, etc. If the character “\” (backslash) itself is required to be output, use “\\” (two backslashes).display:<string>
The same as the print: statement except that the results are displayed on the user’s terminal (in the r2k execution window). This statement is most useful for debugging purposes.log:<string>
The same as the print: statement except that the results are logged to the current logfile (see above).critical:<string>
The same as the print: statement except that the results are sent through the “Critical Message” route (see earlier). The message is displayed on the user’s terminal (in the r2k execution window) and, if a printer is available, the message is printed.write:<string>
The same as the print: statement except that the results written to the currently open script file (see open:, append:, and close:)printticket:
The information contained in the current ticket being processed is dumped in “Reuters field delimited format.” Each field within the current ticket record is printed, preceded by the Reuters identifying field number. A representation for the ticket header precedes this dump.printconv:
The Reuters conversation that initiated the current ticket is printed.The file named filename is opened for writing. If filename is not supplied, the contents of the workarea is used. If the file does not exist, it is created. The filename may include workarea and savearea tokens ("%s").The file named filename is opened for append. If filename is not supplied, the contents of the workarea is used. If the file does not exist, it is created. The filename may include workarea and savearea tokens ("%s").The open file is closed. NOTE: Files opened by the append or open statements are automatically closed on script exit.delete:[<filename>]
The file named filename is deleted. If filename is not supplied, the contents of the workarea is used. This statement succeeds only if the target file can be deleted. For safety, use this statement in an if statement. The filename may include workarea and savearea tokens ("%s").sersend:<string>
The same as the print: statement except that the results written to the auxiliary serial port (not available in all installations).The same as the print: statement except that the results written to the primary (control) TCP-IP port (only available in TCP-IP installations).The same as the print: statement except that the results written to the secondary (data) TCP-IP port (only available in TCP-IP installations).Data is read from the secondary (data) TCP-IP port. If no data is available after <number> seconds, the statement fails. If <number> is not supplied, a default value of 5 is used. BEWARE, only about 200 bytes of memory is available for use. Data that has been read is placed in the workarea which is empty on statement failure. This statement is intended for use as a mechanism to receive small data-acknowledgment messages from a data sink (only available in TCP-IP installations).resetbuf:
2500 bytes of buffer space is available for the collection of information that should be processed in one chunk, for example, network sends are more efficient if not performed in small pieces. This statement loads the NULL (empty) string into this buffer space.The same as the print: statement except that the results are appended to the buffer space. NOTE. Any individual appendbuf that would overflow the buffer space is silently ignored.loadbuf:
The contents of the buffer space are loaded into the workarea for further processing e.g. with auxsend: or transform:.loadfile:[<filename>]
The contents of the file named filename is loaded into the workarea. If filename is not supplied, the contents of the workarea is first used as the filename. Up to 2500 bytes may be loaded into the workarea. Extra bytes in the file are silently ignored.
Other
NOTE: functions marked with a “*” are only available with HLLAPI support.
Some of the other language functions available in ISS are:wait:[<string>] *
The script will wait for the “input inhibit” flag to clear in the Presentation Space. If the optional argument is present, this statement will wait up to 1 minute for the string to appear in the Presentation Space. This, second form of wait is useful for hosts where the HLLAPI wait primitive is not supported, i.e. non-buffered host operating systems such as VAX/VMS.
vwait:<string> *
The script will wait for <string> to appear in the Presentation Space for the number of seconds given in the workarea.
pause:<secs>
The script will sleep for <secs> seconds.
equals:<string>
Used as an argument to an if statement, this statement will succeed only if string exactly matches the contents of the workarea.getcursor: *
The workarea is loaded with the character representation of the cursor position.at:<position> *
Used in an if: statement, this statement returns TRUE if the current cursor position matches position (as would have been returned in the workarea by a call to getcursor.)atprompt:<prompt>
Used in an if: statement, this statement returns TRUE if the current cursor position is one character space to the right of the prompt <prompt> in the presentation space.Keyboard entry is prevented from reaching the Presentation Space, characters typed, while the keyboard “focus” is on the Presentation Space, are discarded.kbdon: *
Keyboard entry is allowed to reach the Presentation Space. NOTE: This statement will fail if not preceded by a kbdoff: statement.Load the workarea with the results of calling the ANSI ctime() function. The trailing newline character is removed.DieNow:
The only mixed-case statement. Causes execution of the interface to terminate. Cause of termination is logged.
Notes for Specific Installations
In some installations the Softek deal interface may communicates with bank systems via direct database inserts. In addition to program arguments (see above) an extra environment variable is available to configure database interaction:
DL_SYBASE_IFILE Specifies the full path/name to a substitute Sybase interface file, used in place of the one that might be found in the $SYBASE directory.
Deal Integration Warning
One of the necessary consequences of the fail-safe end-to-end acknowledgement that is a design feature of this interface (and allows us to guarantee that deals will not be lost by this deal reader), is a pathological condition that can cause the same deal to be fed to the Front Office more than once. This duplication can only occur "sequentially", meaning the same deal may be re-fed but without any other deal interposing between the duplicates. It is essential that the bank's Front Office loader is capable of detecting and accepting sequential duplicates, i.e. sequentially presented deals with the same Reuters or EBS ticket number. If a sequentially duplicate deal is received by the bank's Front Office system, the deal should be accepted from us as if it were the original (i.e. any acknowledging actions performed by the bank's Front Office to us should be executed as if without error) and the deal may then be ignored by the bank's downstream processing (perhaps with a warning message noting the occurrence).
System Startup
On UNIX installations, after booting the Interface Machine, the Interfaces should be started by executing the script i_start located in the ~softek/bin directory. A single interface may be started interactively by executing the shell command corresponding to its TCID, e.g. MLAG. QUOT is sometimes used to represent the TCID of an EBS interface.
More recent installations have been provided with a central customization shell script in the file ~softek/bin/set_my_env. Although the preferred method of system startup is still the i_start command, in these installations, each interface may be interactively started (usually for testing purposes) by issuing the command:GENESIS_REUTERS TCIDfor Reuters interfaces (where TCID is the server ID of the Reuters interface you wish to start) or
GENESIS_EBS TCIDfor EBS interfaces (TCID is usually the fixed ID of QUOT for our EBS interfaces). For these interfaces to come up properly, the set_my_env file must have a small block of environment variables properly set for each TCID.
Use of Script Files
When r2k starts it calls the script startup.xxx. (where xxx stands for the script extension argument given as a parameter).startup.xxx is currently empty but may be used as a temporary home for special one-off script commands that need to be executed at interface startup.
When r2k sees a deal, it calls a script corresponding to the type of deal according to the following table.
deal type
script name
FX
dofx.xxx
Swap
doswap.xxx
Money Market
dodep.xxx
FRA
dofra.xxx
Additionally, each of the above scripts calls alldeals.xxx which contains script commands common to all deal types and is responsible for releasing the deal data. The script file doconv.xxx deals with the receipt of conversation text associated with all deal types. The script file dounsol.xxx is called in the event that a deal is received that was not specifically requested by the Reuters Interface. dounsol.xxx is currently empty. When Softek directly crafts multi-leg deals from a single source deal (i.e. for Swap deals), other script files may be called to handle this additional processing. Typically three more script files are used in this case, called commonswap.xxx, swapa.xxx, and swapb.xxx.
When ebs sees a deal, it calls a script corresponding to the type of deal according to the following table.
deal type
script name
FX
fxebs.xxx
Swap
swapebs.xxx
Money Market
depebs.xxx
FRA
fraebs.xxx
HK T-Bill
hkebs.xxx
The EBS deal server currently only implements pure FX deals. The script fxebs.xxx calls allebs.xxx to complete its data processing.
System Shutdown
System shutdown is accomplished by running the shell script i_kill, found in the production ~softek/bin directory.
Periodic Cleanup
Disk space is consumed on the interface filestore at the rate of about 1kb per deal. At 400 deals per day, processed through the Reuters system, the available disk space on the Interface Sparc will be consumed at the rate of about 400kbytes per day. Each day two new files (a deal record file and a log file) would be created per interface. The files comprise a “last resort” audit trail of all deals that passed through the Interface and serious thought should be given to archiving this information. Each day that stsr2k is executed, 2 new files per server are created in the r2k execution directory, currently, ~softek/r2k. It is suggested that these files are archived and deleted from this directory every couple of month. The same cleanup consideration should be given the the ebs interface in the ~softek/ebs directory.
TCP-IP Data Transfer
The Softek interface is a server on two TCP-IP port numbers (see Synopsys and Environment Variables). The ports are in a listen state until a client connects at which point the interface performs a TCP-IP accept and bidirectional communications are established. For testing purposes a client application may use telnet to establish the connect. Once the client is connected, the script statements netsend, auxsend, and auxload become available.
Sybase Table Loading
The file dbload.c contains the sources for the functions responsible for database manipulation. The script transformation function sy_Insert() (called from the script statement sy_insert: and found in the source file trforms.c) calls Sybase_Insert()(found in dbload.c). Sybase_Insert() performs whatever actions that are necessary to load the data into the sybase table. On older implementations sy_insert requires the ticket number to be loaded into the script workarea and the tablename to be present in the db.conf file. Newer implementations have provision for multiple table loads and these use the workarea to store the table name into which to write. An easy way to determine which implementation you have is to examine the db.conf file and check the presence of the tablename. Both implementations use the savearea for the data to be loaded. The newer implementation expects the deal ticket number to be placed in the savearea before the data to be inserted and separated from this data by a '|' character. This ticket number and the '|' character are stripped off and stored in memory before the rest of the data are passed to the dblib data loading function. Necessary actions may include establishing a database connection, which is accomplished according to data found in the file db.conf (see earlier). Since username and password information is contained in this file, a protected uid should be used to run the interface and read access to db.conf should only be allowed to this uid. If this security measure is implemented it will be neccessary to set the interface group-id to allow read/write permissions on the files in the other directories that the interface uses.
ZeroBase Table Loading
An even more recent version uses the workarea to store the current ticket number, the savearea to store the deal data, and an extra last parameter in the db.conf file to indicate the name of a CtLib stored procedure that is used to populate the target Sybase database. This mechanism is used to load the ZeroBase Front Office System.
ODBC Table Loading
The file odbc_db.c contains the source for the functions responsible for ODBC database manipulation. The script transformation function OdbcInsert() (called from script statement odbc_insert) performs all the steps necessary to load the values found in the workarea into the database targetted by the odbc.conf file. An additional function OdbcSqlExec() (called from script statement odbc_sqlexecdirect) executes the entire string found in the workarea as an SQL statement. Except through the critical error notification mechanism, no provision is currently available to return the results of either of these statements.
Reuters Server and Serial Port Use
Under normal conditions, the Softek interface (r2k) should be left running throughout the trading day. If, for some reason, the interface is turned off for a significant portion of the trading week, a situation may arise where the Reuters server, trying to preserve deals that have not been uploaded, takes away working memory from the trading system and causes trading slowdowns. This is a problem with the way Reuters store their deals in their Server machine. To ensure that the use of the Ticket Output Feed (TOF) does not impact trading. Please make sure that the Reuters server TOF function is disabled if the Softek interface is not to be invoked during a trading day (type alt F8<Space> on the corresponding Reuters server keyboard to toggle the TOF state). The Reuters server deal-storecard has enough memory for a little over 400 new deals before trading speed is compromised. So trading speed should not be immediately affected. The EBS server does not suffer from this problem.
1 Ý Not available with VAX-hosted BOS
