JSIHEY(1)

NAME
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
    Sends a message to the program telling it to quit.

Most of the verbs aren't of much use without some object 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 keyword. 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 destination 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 message. 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:

print
    Print out a formatted string that can use values from the reply message. The format string can contain 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 separated 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 provides a more flexible way to process arrays then just the print action. The arguments to the forinstance 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 example, "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 anything unless theres an error.

EXAMPLES

To get the suites for the teams property.

    [dexter@lab janosvm] jsihey localhost/14000 getsuites 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.

    [dexter@lab janosvm] jsihey localhost/14000 list teams

To create a team with the name "THX" on the JanosVM listening 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 domination 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.