[ts-gen] .shimrc file [was: segmentation faults]

[Bill Pippin]

Paul notes:

> ... the .shimrc in the tarball is empty ...

The release script has been modified to again provide a
useful default .shimrc file in the root directory of the
tarball:

DbmsName        mysql
DbmsHost        localhost
TableSet        testing
UserName        shim
Password        0
FeedName        tws
FeedHost        localhost
FeedPort        7496
HqPeriod        11
ClientId         8
Upstream        paper

All variables have reasonable defaults, so that it's fine
to minimize this file to the connection values that vary
for your site, plus possibly your preferred value for
ClientId. 

The set of possible name value pairs was previously available
via help, though since that is currently disabled, the
determined user will have to look at the text of help.c to
see that information.

Rather than wait until I have fixes for help mode finished, I'm
posting this message.  It has the great advantage of immediate
availability, though admittedly the possible disadvantage of
vulnerability to bitrot, as the sources change and this message
does not.  In an attempt to reduce the impact of the latter,
I also refer herein to the sources, in particular help.c for
the definitions of those configuration variables whose purpose
should be obvious.

The set of configuration variables implemented by the shim is
a subset of those accepted as part of the .shimrc language,
that is some are not yet fully implemented.  If you change the
value of a configuration variable and the shim still works
as before, it's entirely possible that nothing in the shim
yet uses that variable. 

The language accepted while parsing rc files is determined by:
(1) the parsing code in bind.c, following the signpost "Config";
(2) the declarations of the pair names, in kind.h, which indicate
whether the pair value is a string or natural number, as the 
type template parent type is a TxtValue or NatValue; and,
(3) the definition of the set of pair names acceptable in actual use,
by the list of names in the table returned by tag::RcpK::instances()
of syms.c, where the tag type acronym stands for "rc-pair-keyed set",
and the current list from that file is:

  a.  DbmsName DbmsHost TableSet UserName Password
  b.  FeedName FeedHost FeedPort
  c.  ShimText CmdEvent ReqEvent MsgEvent
  d.  Locality Currency Account Upstream

  e.  cVersion ClientId
  f.  NumTries DataSubs BookSubs HqPeriod
  g.  sVersion PollTime NumWords InitTime

The first five, in (a), are dbms and database connection parameters;
those in (b), IB tws connection parameters; (c), log and trace file
names; (d), upstream session and account context --- all of these are
strings, although I should note that strings may be numbers, e.g., a
database password value of 0 indicates the empty password, and the
FeedPort may be either a port number, e.g., 7496, or for more exotic
setups, a service name.  The variables in (a), (b), and (c) have
been around for quite awhile, and are fully implemented as intended.

The values in (e) also provide upstream session and account context;
those in (f), resource limits; and (g), somewhat obscure internal
timeout delays, counts, and other configuration values used only
during startup, so that none of this last group are of interest
once the shim has finished printing its banner.

I'll leave (a) and (b) to your common sense, accumulated experience,
or, as needed, perusal of help.c .  The defaults are typically fine
for the log file names, (c), and timeouts, (g).

The resource limits (f) are described in a NEWS stanza within the
current series:

>       The NumTries, DataSubs, and BookSubs configuration variables
>       have been added to control the number of connection attempts,
>       number of market data subscriptions, and number of market
>       depth subscriptions per shim, e.g., with a DataSubs value of 12,
>       eight shims sharing the same config file could make up to 96
>       market data subscriptions.  The "once" cmd line option flag
>       overrides the NumTries variable, so that say in risk mode,
>       and where you want to have exact control over the ClientId,
>       the shim will quit after the first connection attempt if
>       there is a client id collision.  The HqPeriod variable,
>       renamed from PastSlot, can be used to divide up the history
>       query bandwidth; e.g., with a HqPeriod of 81 seconds,
>       eight shims should be able to comfortably share one IB tws.

That leaves the upstream session context, (d) and (e):

  d.  Locality Currency Account Upstream
  e.  cVersion ClientId

Although most of these are also covered in NEWS, I'll reiterate here
since that file does by its nature become outdated.

The ClientId variable, which applies only to risk mode [data mode shims
are clamped to the lower single digits, from 1 to at most 8], is
perhaps the most interesting of the newer configuration variables.
Use of the client id and region variables, (names "ClientId"
and "Locality") are explained in a previous post:

    http://www.trading-shim.org/pipermail/ts-general/2008-August/000228.html

Currency, Account, and Upstream are currently ignored, that is not
used during configuration.  Currency would provide a default currency
once symbolic product expressions were added to the command language,
while Account and Upstream would allow you to limit which IB tws
instances the shim could connect to, according to the account code
or class (paper, live, demo, or paper/demo).

The client version variable,  cVersion, should be left alone for now;
it will eventually allow you to select api request and message formats
according to the api client version.  Attempts to set this variable
will be ignored, with the table lookups in tabs.c using an internally
defined value.

Thanks,

Bill