# jsihey man page

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

## SYNOPSIS

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

## DESCRIPTION

           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 `plex:udp:foo.com/8192').  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
           are:

           getsuites
                  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
                  Execute a property, and just like  create,  any  of
                  the  verb  arguments  are  given  after  a with and
                  should be name/value pairs.

           shutdown
           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
           "name=pat").

           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
           be:

           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
                  indeces.

           forinstance
                  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.

           nothing
                  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.

## EXAMPLES

           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.
                  teams

           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

## RETURN VALUES

           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.

## FILES

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

## NOTES

           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
           http://www.cs.utah.edu/flux/janos.

## AUTHOR

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

## COPYING

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