[ts-gen] Modes and options

[pippin at owlriver.net]

An anonymous user asks about using modes and options to control message
data flow:

> On a somewhat-related note, the 'pipe' option doesn't seem to work (or am I
> incorrect in assuming that usage would be as simple as ./shim --data pipe >
> shimlog.txt ?) Nothing is written to the log.

True.  The short answer is, given previous use of the "save" option, look
in the file ShimBits for a copy of the binary form of the message text, and
the file ShimText for the log format version of that same data.

Now, in more detail, I'll talk first about modes and options.  Modes appear
first, begin with two hyphens, and there must be exactly one, while options
are ... surprise ...  optional, have no hyphens, and follow the mode.

If you leave the mode off, the shim will give a usage message listing the
modes.  Many are related to testing, and only two involve straight-forward
real-time access to the tws, "--data" and "--risk".  The only difference
between those two at this time is that the order command is not supported
in "--data" mode.
_______________________________________________________________________________

sql$ ../shim

Usage: shim <mode> [optional feature list]
Modes:

    --help     # print this explanation and list the optional features

               # real modes, requiring access to an IB tws:
    --data     # process subscriptions and log resulting tick stream events
    --risk     # accept full command set, send requests, and log all events
    --leaf **  # shsh experimental use, subject to rapid and drastic change

               # test modes, with no connection to the tws:
    --play     # read events from the image file and send text to stdout
               # echo modes; read from stdin and echo the related:
    --cmds     #     downstream commands
    --msgs     #     tws messages
    --reqs     #     tws requests
    --unit     # for internal use; unstable though otherwise harmless

           * -- not yet implemented
          ** -- for now, expect to read the code if you wish to use 

_______________________________________________________________________________

It may also occur in the future that the load and tick commands will vary
somewhat between the two real modes, e.g., the load command may be limited
to "--data" mode only, though that hasn't happened yet; it will depend on
whether tick and load interact badly for purposes of subscription management.

The other test modes are too idiosyncratic to formally document now; feel
free to play with them, but their true purpose is in support of unit and
functional testing, and right now you can just use the bin/regress script
for that purpose.

Now, about the options:
_______________________________________________________________________________

sql$ ../shim --help

               # allowed options may be listed following the mode:
               # real modes only:
      init *   # prompt for the dbms and link commands during startup
      load     # load SubRequest at startup even without a load command
      cast *   # multi-cast tick, depth, history, and bulletin messages
      dump *   # read the database tables and list their rows to stdout
      save     # save events to image and text files for later playback
      pipe     # send events as text down a pipe to provide a local log
           **  # leaf mode only, and must be suffix of the option list:
      part     # introduce the message partition definition; each event
               # type listed will be split to a separate output stream:
      past     # history
      tick     # market data and market depth
      news     # news bulletins
      mkts     # all of the above

               # test modes only:
      fast     # cut startup time; this saves just one second, works with
               # Linux only, and is used primarily to speedup the offline
               # parts of the test suite

           * -- not yet implemented
          ** -- for now, expect to read the code if you wish to use this
_______________________________________________________________________________

Much of the above is not yet implemented, in particular everything from "leaf
mode only" to "all of the above"; and what follows is testing specific.

The important options for now, therefor, are "load" and "save".  As
explained earlier, "load" provides an implicit load operation at startup,
while "save" causes local file logging of messages in both binary and
text form; see the files ShimBits and ShimText in the current directory for
the null terminated and log formatted text, respectively.

As for "pipe" mode, it is supposed to write the message text to a named pipe,
although in practice you should ignore it for now, since it is meant to be
used with "--leaf" mode, which is very much experimental.  The "save" option",
in contrast, is less likely to change without notice.

Thanks,

Bill