jsihey man page

       jsihey  -  A  command  line scripting tool for the JanosVM
       Scripting Interface


       jsihey <destination> <verb>  [<specifiers>]  [<verb-args>]


       jsihey  is  used to send JanosVM Scripting Interface (JSI)
       messages to a running JanosVM  or  any  program  that  can
       understand  these  messages.   The arguments to jsihey are
       given in a near english form described by the  pseudo  BNF
       usage  statement it prints out when no arguments are given
       or there was a usage error.  The  first  argument  is  the
       destination  of  the message, given as either a registered
       name, a host/port pair for tcp connections, or a full  JSI
       protocol  specification  (e.g. `myjvm', `localhost/14000',
       or `').  Next, the verb and  property
       specifiers  are  given  to  indicate what action should be
       performed by an object in the program.  The set  of  verbs

              Get  the  suites for the given property or the root
              set of properties if nothing  is  specified.   Each
              suite  contains information about a property in the
              program, including what verbs it can be  used  with
              and  their  arguments.  So if you need help this is
              the first place to look.

       list   Get a list of properties contained within the given
              one  or a listing of the root properties if nothing
              is specified.

       get    Get the value of a property.

       set    Set the value of the property, the  verb  arguments
              for this is the keyword to followed by the value to
              give the property (e.g. set name to "pat").

       create Create a property, any  verb  arguments  are  given
              after  a  with  and  should  be a set of name/value
              pairs (e.g. create foo with name "willow").

       delete Delete a property.

              Execute a property, and just like  create,  any  of
              the  verb  arguments  are  given  after  a with and
              should be name/value pairs.

       to operate on, so we use the specifiers to indicate  which
       object  in  the  program  should handle the message.  Each
       specifier is made up of a name and possibly  a  value,  if
       only  a  name is needed then theres only a single property
       with that name, otherwise the name can be thought of as  a
       type  with  the  value being the name of an object of that
       type.  Of course, since objects can contain other  objects
       more  than  one specifier may be needed to get the message
       to its intended destination.  In  order  to  do  this  you
       stack  the  specifiers by separating each with the of key-
       word.  For example, "gc  of  team  1"  would  specify  the
       garbage collector property of team 1.

       In  addition  to the specifiers, some verbs and properties
       might require extra arguments in order  to  perform  their
       function.  In the case of the set verb, you need to follow
       it with the keyword to and the value to give the property.
       Also,  create and execute can pass arguments to the desti-
       nation properties if needed.  These arguments are given as
       name/value pairs where the pair is separated by a space or
       = on the command line (e.g. "name  pat"  is  the  same  as

       After jsihey builds the message from the arguments it will
       connect to the given destination, send  the  message,  and
       possibly  wait for a reply.  The default for most verbs is
       to wait for the reply and then  dump  its  contents.   For
       example,  the  reply for "jsihey janosvm list teams" might

       Normal reply:
                id = `1'
                name = `kernel'
                id = `2'
                name = `anonymous'

       The first line indicates whether it was a normal reply  or
       an  error,  next theres a listing of all items in the mes-
       sage.  The first column contains the names  of  each  data
       item,  followed by their value in single quotes.  The only
       verbs that don't use this default action are shutdown  and
       getsuites  since  they  require  special  attention.   The
       default for shutdown is pretty simple, the program doesn't
       reply  to  this  message  so  there's nothing to wait for.
       And, getsuites uses some specially  formatted  strings  to
       transfer  its  data around so a separate pretty printer is
       used to print out these replies.

       Unfortunately, the default printing  action  isn't  always
       desirable  when writing shell scripts so some simple extra
       actions have been defined:

              tain plain text, formatting escapes, and directives
              which  can  print out values contained in the reply
              message.  An escape starts with a backslash and  is
              followed  by  a  t, for tab, or n, for a line feed.
              Each directive starts with a %( and is followed  by
              the  name  of  a  value in the message, an optional
              index range if the value occurs more than  once  in
              the  message, then a : followed by a regular printf
              format conversion (with the  addition  of  the  `b'
              format  which  prints  all  the  bytes in hex), and
              finally the closing parentheses.  For example,  the
              format, "%(result[1]:d)", would print out the value
              of the second instance of  `result'  in  the  reply
              message  as  an integer.  In addition, its possible
              to print out a range of indeces for a  value  sepa-
              rated  by  a  string, this is done by putting a dot
              after the first index, followed by  the  string  to
              separate each index, then another dot and the final
              index.   For  example,  "%(result[1.  .5])",  would
              print out the second through sixth values of result
              separated by a space.  Also,  the  indeces  can  be
              left  out  to implicitly specify the first and last

              The forinstance reply action is  a  simple  way  to
              loop  over the values of the reply message and pro-
              vides a more flexible way to  process  arrays  then
              just the print action.  The arguments to the forin-
              stance are a temporary  variable  name  which  will
              store the current index followed by the in keyword,
              the name of the value to loop  over,  and  finally,
              the action to perform on each iteration.  For exam-
              ple,   "forinstance    lpc    in    result    print
              "%(result[lpc]:s)\n""  would print each instance of
              the result value on a separate line.

              Waits for the reply  but  doesn't  print  anything,
              even if the reply is an error.

       ignore Doesn't  wait  for the reply and doesn't print any-
              thing unless theres an error.


       To get the suites for the teams property.

              [dexter@lab janosvm]  jsihey  localhost/14000  get-
              suites of teams

       To  get  a listing of all the teams in the system from the
       JanosVM listening on TCP port 14000 of the local  machine.

       To create a team with the name "THX" on the  JanosVM  lis-
       tening on TCP port 14000 of the host named deedee and then
       print the new team's identifier.

              [dexter@lab  janosvm]  jsihey  deedee/14000  create
              team with name "THX" then print "%(result:d)"

       To turn on the xprofiler

              [dexter@lab  janosvm]  jsihey janosvm set xprofiler
              to on

       To execute the domination property of the world  property.

              brain@acmelabs janosvm$ jsihey janosvm execute dom-
              ination of world


       0      Everything worked fine.

       10     The reply message was an error.

       20     There was a communication error.

       30     There was a usage error.

       100    There was an internal error.


       $HOME/.janosvm/registry/*    Registered names and values


       jsihey is a very basic program and is only intended  as  a
       lowest  common  denominator  for  scripting the VM and any
       other programs built to understand these messages.  A real
       scripting  language with a JSI binding should be preferred
       to this feeble program.

       JanosVM  and  its  tools  are  avilable  on  the  web   at


       Jsihey  is  written by the Janos project in the University
       of Utah Flux Group.


       Jsihey is distributed under the GNU GPL. For full details,
       see  the file license.terms in the source distribution for
       full details.

Man(1) output converted with man2html