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.
Man(1) output converted with man2html