'\" t
'       # that line tells man to use tbl && col
.\" @(#)$Header: /usr/aws/aws/src/mlinkS/src/RCS/mlinkS.man1,v 1.25 1998/09/15 02:02:05 dank Exp $
.\" **************************************************************
.\" Use this man page as a template for section 1 man pages in 2.0
.\" **************************************************************
.TH mlinkS 1J  $Date: 1998/09/15 02:02:05 $
.UC 4
.SH NAME
.\" * name of component followed by a dash and a description (initial cap,
.\" *   no period)
mlinkS \- Server that watches instruments in pre-specified producer groups and
sends updates to Reuters Marketlink
.PP
Part of the JPA Publishing Suite
.SH SYNOPSIS
.\" * command syntax: put command name and parameters in bold and 
.\" *   options in italics
.B mlinkS
[\fB\-trace \fITrace\fR{on | off | 0 - 3}\fR]
[\fB\-log \fILogging\fR{on | off | 0 - 2}\fR]
[\fB\-tp \fITracePath\fR]
[\fB\-lp \fILogPath\fR]
[\fB\-ep \fIEtcPath\fR]
[\fB\-host \fIHost\fR]
[\fB\-port \fIPort\fR]
[\fB\-ps \fISpeed\fR]
[\fB\-wt \fIWaitTime\fR]
[\fB\-cc \fIContribCode\fR]
[\fB\-ms \fIMaxSend\fR]
[\fB\-it \fIInterTimeout\fR]
[\fB\-at \fIAckTimeout\fR]
[\fB\-xt \fIXoffTimeout\fR]
[\fB\-tf \fITemplateField\fR]
[\fB\-pf \fIPageField\fR]
[\fB\-rf \fIRowField\fR]
[\fB\-cid \fICtrlID\fR]
[\fB\-pi \fIPeerIDs\fR]
[\fB\-hi \fIHashOnInput\fR]
[\fB\-ht \fIHoldTimeout\fR]
[\fB\-bmx \fIBatchMaxTimeout\fR]
[\fB\-bmn \fIBatchMinTimeout\fR]
[\fB\-bc \fIBatchChangeTimeout\fR]
[\fB\-cd \fIClearOnDelete\fR]
[\fB\-st \fISyncTimeout\fR]
[\fB\-dt \fIDeleteOnNoTemplate\fR]
[\fB\-bt \fIBounceTimeout\fR]
[\fB\-mode \fIMode\fR]
[\fB\-uf \fIUseFIDFile\fR]
[\fB\-ut \fIUseTemplates\fR]
[\fB\-uc \fIUseChains\fR]
[\fB\-si \fISampleInterval\fR]
[\fB\-bf \fIBandwidthFull\fR]
[\fB\-li \fILogInterval\fR]
[\fB\-cp \fICompPath\fR]
[\fB\-ce \fICompExt\fR]
[\fB\-ff \fIForceFore\fR]
[\fB\-zb \fIZeroBack\fR]
[\fB\-nf \fINozeroFore\fR]
[\fB\-rs \fIRequestStatus\fR]
.SH DESCRIPTION
.PP
The
.I mlinkS
server watches all the instruments in a number of
pre-configured BTRS producer
groups, and sends any relevant updates to Reuters using the Marketlink
protocol.
.PP
The BTRS producer groups are specified in the instrument file,
.I mlinkInstrs.txt,
along with the translation templates that are used
to select fields and (if required) map onto Reuters field names.
.PP
The server starts off by reading in the instrument file, and then attempts
to make a connection to the pre-configured asynchronous port.
.PP
The selection of translation template to be used for each instrument
is made according to
the value of a pre-configured field.
.SH OPTIONS
.\" * parameters (in bold) and options (in italics) followed by a description
.IP "\fB\-trace \fITrace\fR{on | off | 0 - 3}"
Specifies the level of trace to be dumped out. The trace file is called
.I mlinkS.out,
and is located in the directory specified by the parameter
.I TracePath
(see below). Normally, trace should be left off, unless otherwise directed
by JPA. The trace level may also be changed dynamically, by requesting the
instrument
.I trace=<level>
from the producer
.I CTRLmlinkS
(see below). The request will be denied, but the trace level will be changed.
.IP "\fB\-log \fILogging\fR{on | off | 0 - 2}"
Specifies whether significant events and errors are to be logged.
The log level may also be changed dynamically, by requesting the
instrument
.I log=<level>
from the producer
.I CTRLmlinkS
(see below). The request will be denied, but the logging level will be changed.
The log file is called
.I mlinkS.log,
and is located in the directory specified by the parameter
.I LogPath
(see below).
.IP "\fB\-tp \fITracePath\fR"
Specifies the location of the trace file,
.I mlinkS.out.
.IP "\fB\-lp \fILogPath\fR"
Specifies the location of the log file,
.I mlinkS.log.
.IP "\fB\-ep \fIEtcPath\fR"
Specifies the location of the instrument file,
.I mlinkInstrs.txt,
FID file,
.I appa.txt,
and suspended record file,
.I mlinkSusp.txt
(see below).
.IP "\fB\-host \fIHost\fR"
Specifies the name of the TCP/IP host to connect to. This is not used for
asynchronous connections.
.IP "\fB\-port \fIPort\fR"
Specifies the name of the asynchronous port or number of the TCP/IP port.
.IP "\fB\-ps \fISpeed\fR"
Specifies the speed of the asynchronous port.
.IP "\fB\-wt \fIWaitTime\fR"
Specifies the time in seconds to wait before retrying to fetch the folder for
a producer group.
.IP "\fB\-cc \fIContribCode\fR"
Specifies the Marketlink contributor code.
.IP "\fB\-ms \fIMaxSend\fR"
Specifies the maximum number of times that a packet can be re-sent before
the connection is dropped.
.IP "\fB\-ht \fIInterTimeout\fR"
Specifies the inter-character timeout in milliseconds.
.IP "\fB\-at \fIAckTimeout\fR"
Specifies the time in seconds that can elapse before an unacknowledged packet is
re-sent.
.IP "\fB\-pt \fIXoffTimeout\fR"
Specifies the time in seconds that can elapse after an XOFF is received before
the server assumes an XON and starts sending again.
.IP "\fB\-tf \fITemplateField\fR"
Specifies the field containing the name of the template to be used.
.IP "\fB\-pf \fIPageField\fR"
Specifies the field containing the name of the page to be contributed to (this
is only used for page-based contribution).
.IP "\fB\-rf \fIRowField\fR"
Specifies the field containing the name of the row to be contributed to (this
is only used for page-based contribution).
.IP "\fB\-cid \fICtrlID\fR"
Specifies the identifier of the control producer group. This producer can be
used to control and monitor the operation of the server. If there is more than
one instance of the server running on the same brf, this identifier can be used
to distinguish the different instances. If this identifier is unset, the
producer has the name "CTRLmlinkS". If it is set to n, the producer has the
name "CTRLmlinkS.n". The various monitoring and control commands are described
below. This producer group is also used for maintaining synchronisation
between peer servers. This feature is explained below.
.IP"\fB\-pi \fIPeerIDs\fR"
Specifies a list of peer server identifiers. Two or more peer servers may be
used to balance the load between two Marketlink lines. If this is done, a
hashing mechanism is used to select which page or record is sent out by
which server. If one server drops out for whatever reason, the load is
re-balanced between the remaining servers. The list of server identifiers
is given as a comma-separated list of numeric control producer group
identifiers. If the current server is omitted from the list, it is added.
The setting of this parameters must be consistent across all participating
servers.
.IP"\fB\-hi \fIHashOnInput\fR"
Specifies whether or not the hashing to determine which pages are to be sent
out by this server is to be carried out on input (i.e. on the constitutent
record names) or on output (i.e. on the page name itself). Again,
the setting of this parameters must be consistent across all participating
servers.
.IP"\fB\-ht \fIHoldTimeout\fR"
Specifies the time in seconds that an update that would not normally be sent out
by this server (because of the hashing algorithm) is held. If the server that
would normally send out this update drops out within this period, and this
server takes over some or all of its updates, any updates that have been made
and held are sent out. It is assumed that any updates that are older than
this timeout period have been successfully output by the original server.
.IP"\fB\-bmx \fIBatchMaxTimeout\fR"
Specifies the maximum timeout in milliseconds before a batch of updates for
a given page is
sent out. This mechanism ensures that a series of updates for a page are all
sent out as one Marketlink message, rather than a series of individual
messages. The timeout starts out at this maximum value, and then drops to
the minimum value (see below) after a pre-specified interval (see below).
.IP"\fB\-bmn \fIBatchMinTimeout\fR"
Specifies the minimum timeout in milliseconds before a batch of updates for
a given page is sent out.
.IP"\fB\-bc \fIBatchChangeTimeout\fR"
Specifies the time in seconds before the batch timeout switches from the
maximum amount to the minimum one.
.IP"\fB\-cd \fIClearOnDelete\fR"
Specifies whether or not the area corresponding to the data for a given
record is to be cleared from its target page when the record is deleted
from its producer group.
.IP"\fB\-st \fISyncTimeout\fR"
Specifies the time in seconds that the server waits before proceeding to
allow for other peer servers to get going, so that the load balancing can
start correctly in a synchronised manner.
.IP"\fB\-dt \fIDeleteOnNoTemplate\fR"
Specifies whether or not the server is to stop watching a record if its
initial image has no template specified.
.IP"\fB\-bt \fIBounceTimeout\fR"
Specifies the time in seconds that the server waits following a producer
down status before deleting all the records for that producer. This is to
allow for producer bouncing where there are duplicate feeds.
.IP"\fB\-mode \fIMode\fR"
Specifies whether the Marketlink protocol in use is broadcast or interactive.
.IP"\fB\-uf \fIUseFIDFile\fR"
Specifies whether or not the FID list is to be read in from the standard
Reuters appa.txt file. If not, they are read from the instrument configuration
file (described below).
.IP"\fB\-ut \fIUseTemplates\fR"
Specifies whether or not template meta-data is to be found in the incoming
records. If not, the first template found in the instrument configuration
file is used instead.
.IP"\fB\-uc \fIUseChains\fR"
Specifies whether or not chains are being generated. If so, an appropriate
Reuters chain template is generated for each producer group, so that incoming
chain data can be sent through to Marketlink.
.IP"\fB\-si \fISampleInterval\fR"
Specifies the interval in seconds between each statistics collection.
.IP"\fB\-bf \fIBandwidthFull\fR"
Specifies the threshold (as a percentage of the available bandwidth) at which
point the used bandwidth is flagged as being full.
.IP"\fB\-li \fILogInterval\fR"
Specifies the interval in seconds between successive writes of statistics to
the log file.
.IP"\fB\-cp \fICompPath\fR"
Specifies the pathname where composites are to be found, if contribution is
to be driven by composites. If this is set, composites are used. If it is
not, templates (either static or specified in meta-data) are used instead.
.IP"\fB\-ce \fICompExt\fR"
Specifies the extension appended to the name of each composite file.
.IP"\fB\-ff \fIForceFore\fR"
Specifies the foreground colour in composites used to designate that a
field always has to have a sign, whether positive or negative.
.IP"\fB\-zb \fIZeroBack\fR"
Specifies the background colour in composites used to designate that a
field should have leading zeroes.
.IP"\fB\-nf \fINozeroFore\fR"
Specifies the foreground colour in composites used to designate that a
field is left blank if its value is zero.
.SH DEFAULTS
.\" * table of X11 defaults
The following defaults are recognized by
.I mlinkS:
.sp
.TS
box;
c s s s
c c c c
l|l|l|l.
DF Defaults
=
Xdefault	Command Line	Type	Default Value
_
Trace	\-trace	String	off
Logging	\-log	String	off
TracePath	\-tp	Path	/usr/aws/jpa/publish/out
LogPath	\-lp	Path	/usr/aws/jpa/publish/log
EtcPath	\-ep	Path	/usr/aws/jpa/publish/etc
Host	\-host	String	NULL
Port	\-port	String	NULL
Speed	\-ps	Integer	1200
WaitTime	\-wt	Integer	30 seconds
ContribCode	\-cc	String	NULL
MaxSend	\-ms	Integer	10
InterTimeout	\-ht	Integer	1 millisecond
AckTimeout	\-at	Integer	3 seconds
XoffTimeout	\-xt	Integer	5 seconds
TemplateField	\-tf	String	Template_Name
PageField	\-pf	String	PAGE
RowField	\-rf	String	ROW
CtrlID	\-cid	Integer	0 (unset)
PeerIDs	\-pi	String	NULL
HashOnInput	\-hi	Boolean	false
BatchMaxTimeout	\-bmx	Integer	0 milliseconds (no batching)
BatchMinTimeout	\-bmn	Integer	0 milliseconds (no batching)
BatchChangeTimeout	\-bc	Integer	0 seconds (no batching)
ClearOnDelete	\-cd	Integer	0 (unset)
SyncTime	\-st	Integer	0 seconds (no synchronisation)
DeleteOnNoTemplate	\-dt	Integer	0 (unset)
BounceTimeout	\-bt	Integer	0 seconds (no timeout)
Mode	\-mode	String	interactive
UseFIDFile	\-uf	String	yes
UseTemplates	\-ut	String	yes
UseChains	\-ut	String	yes
SampleInterval	\-si	Integer	60 seconds
BandwidthFull	\-bf	Integer	95%
LogInterval	\-li	Integer	0 seconds (no write to log file)
CompPath	\-cp	String	NULL
CompExt	\-ce	String	NULL
ForceFore	\-ff	String	none
ZeroBack	\-zb	String	none
NozeroFore	\-nf	String	none
.TE
.SH CONTROL PRODUCER GROUP
The control producer group, CTRLmlinkS (or CTRLmlinkS.n if more than one
is in use), has three functions. Firstly, it is used by multiple instances
to keep themselves in synchronisation, by means of the 
.I state
record.
.PP
Secondly, it is used to broadcast statistical information about the server.
This is carried in the
.I Stats
record. The following fields are available:
.IP"\fIXOFFtotal\fR"
This gives the total number of XOFFs received by the server since the count
was last reset.
.IP"\fIXOFF5min\fR"
This gives the number of XOFFs received by the server in the last 5 minutes.
.IP"\fIXOFF10min\fR"
This gives the number of XOFFs received by the server in the last 10 minutes.
.IP"\fIXOFF30min\fR"
This gives the number of XOFFs received by the server in the last 30 minutes.
.IP"\fIXmitRate\fR"
This gives the current transmission rate.
.IP"\fIXmitRatePC\fR"
This gives the current transmission rate as a percentage of the available
bandwidth.
.IP"\fIBandwidthFull\fR"
This gives a value of 1 or 0 depending on whether or not the bandwidth
is currently exceeding the specified "full" threshold.
.IP"\fIBandwidthCount\fR"
This gives the current count of the number of sample intervals for which
the bandwidth has consistently exceeded the threshold.
.IP"\fIBandwidthCountMax\fR"
This gives the peak count of concurrent sample intervals for which the bandwidth
has exceeded the threshold.
.PP
Finally, it can be used to control the operation of the server.
Commands may be issued to this producer group by requesting an instrument
such as <command>[=<value>]. The server will refuse to produce the instrument,
with a suitably informative error message. The following commands may be
issued:
.IP "\fIsuspend=<instrument>\fR"
This interrogates the server to see if a given instrument (page or record)
is currently suspended after being throttled. The server will respond with
either "Page/Record suspended for n seconds" or "Not suspended"
as appropriate.
.IP "\fIversion\fR"
This interrogates the server to see what the current version is.
The server responds with "Version is <version>".
.IP "\fIlog=<level>\fR"
This switches logging or off dynamically.
.IP "\fIpage=<page>\fR"
This dumps out the current state of a page to the log file.
.IP "\fIresend=<page>\fR"
This resends a complete image for a page to Marketlink. The page must
already be known to the server.
.IP "\fIclear=<page>\fR"
This sends a "clear page" command to Marketlink. The page must already be
known to the server.
.IP "\fIcontrib\fR"
This logs the contribution status of every single page and record to the
log file. The status can either be "not contributing", "contributing on
this node" or "contributing on another node". The contribution status for
pages is shown by either incoming record or outgoing page, depending on whether
the
.I HashOnInput
flag is set or unset.
.IP "\fIqueue\fR"
This returns a message indicating how many packets are currently waiting
to be sent, as well as whether or not the server is currently XOFF'd.
.IP "\fIstats\fR"
This writes out the current statistics counts to the log file.
.IP "\fIreset=stats\fR"
This resets the cumulative XOFF total and peak bandwidth duration value.
.IP "\fIreset=XOFF\fR"
This resets the cumulative XOFF total.
.IP "\fIreset=bandwidth\fR"
This resets the peak bandwidth duration value.
.IP "\fIpatch=<page>/<startRow>[-<endRow>]/<startCol>[-<endCol>][/<text>]\fR"
This patches the specified row and column ranges in the specified page with
the specified text. If the area selected is larger than the length of the
text, the text is repeated sufficient times to fill the area. If no text is
assumed, the area is blanked out instead.
.SH FILES
.\" * tab-separated list of files used by the component and a description
The instrument configuration file,
.I mlinkInstrs.txt
specifies which producers are to
be watched, and what translations are to be made between incoming BTRS field
names and outgoing Marketlink field names. These translations are defined in
terms of templates, each of which roughly corresponds to a BTRS schema.
For each producer, a number of templates may be defined, and for each template,
a number of field translations may be defined.
.PP
This is an editable ASCII text file. Each line of this file consists
of a keyword, followed by
one or more parameters, separated by space or TAB characters.
The following keywords may be used:
.IP "\fIProducer\fR"
This takes a single parameter: the name of a BTRS producer group to watch. All
subsequent lines up to the next
.I Producer
keyword relate to this producer group.
.IP "\fITemplate [Page]\fR"
This takes one mandatory parameter: the name of the template.
If the optional keyword
.I Page
is not present, the template is assumed to be used for record-based
contributions. If the keyword
.I Page
is present, two more parameters - the width and height of the pages -
must be provided.
All subsequent lines up to the next
.I Template
keyword relate to this template.
.IP "\fIField\fR"
For fields in templates that are being used for record-based contribution,
this takes two mandatory parameters: the inbound name of the BTRS field, and the
outbound name of the Marketlink field. This field is further translated, using
the appa.txt file, which converts Reuters field names to FIDs.
For fields in templates that are being used for page-based contribution,
this parameter takes three mandatory parameters: the inbound name of the BTRS
field, the offset from the start of the row and the field width.
Optionally, a justification may be provided. This may take the form L, R, Dnn or
Znn. L implies left justification and R implies right justification.
Dnn implies a right-justified decimal number, with nn digits after the decimal
point. Znn is similar, except that the number is zero-padded.
If no justification is specified, left justification is assumed.
.IP "\fIFID\fR"
If the Reuters FID file, appa.txt, is not used, this keyword can be used
to specify the FID mappings instead. It takes two parameters - the FID name
and the FID number.
.IP "\fIComposite\fR"
If composites are in use, this keyword is used to specify the names of the
composites to be read in and used to drive contributions. It takes one
mandatory parameter, the name of the composite, and one optional parameter,
the name of the page to which the data is to be contributed. If the page
name is not specified, it is assumed to be the same as the composite name.
.PP
The suspended record file,
.I mlinkSusp.txt
maintains a disk-based list of suspended (i.e. throttled) records, so
that in the event of the server being stopped and restarted, knowledge of
throttling is not lost. This file is written to and read by the server alone,
and should not be tampered with.
.SH SEE ALSO
publishP(1J)
.IP "Other documentation"
The JPA Marketlink Publishing Suite Programmer's Guide
.IP
Reuters Marketlink User Guide