Tkpvm Commands

The latest version of this file can be found at
http://www.nici.kun.nl/tkpvm/commands.html

The following commands are currently implemented.

   * addhost
   * bind
   * delhost
   * dialog
   * halt
   * id (obsolete, use "tid" instead)
   * joingroup
   * kill
   * leavegroup
   * parent
   * patchlevel
   * recv
   * reset
   * send
   * spawn
   * tasks
   * term
   * tid
   * version

Data types

In Tcl, string is the only known data type. In Pvm any data type can be
used. Therefore in the send command the following method is used to do a
conversion. If these is no format specifier, an automatic conversion is done
using the following rules:

   * Any string that is a sequence of digits from 0..9 will be converted
     automatically to an integer. Octal and Hexadecimal representations as
     in the C language (preceded by "0" resp. "0x") are accepted too.
   * If the string is in a valid floating point representation, containing
     al least a dot "." or the character "e", it will be converted to a
     double.
   * All other strings are not converted. Strings not preceded by a format
     specifier cannot start with "-[a-z]" ([a-z] means any lowercase
     character from 'a' to 'z'), because then the string will be treated as
     format specifier.

This means that a string containing "1.0" will be sent as a double, even if
it is not meant to be. If the receiving process expects a string, this will
go wrong. If you want to override these rules (not possible yet with this
beta release 2), use the following format specifiers:

-char
     Character
-byte
     Byte (0..255)
-short
     Short integer (usually -32768 .. 32767)
-int
     Integer (usually -2147483648 .. 2147483647)
-long
     Long integer (usually the same as integer)
-tid
     Task identifier (the same as integer)
-float
     Floating point
-double
     Double floating point
-string
     A string, always sent as an integer (The number of characters,
     including the final '\0'), followed by the bytes. You can read a byte
     array (see later) as if it is a string. If it doesn't end with '\0', a
     '\0' will automatically be appended to it.
-xxxx()
     Any of the above followed by "()" means that the next argument is
     treated as a list, which is sent as an array. In PVM, an array is
     always sent as an integer (the number of elements), followed by the
     elements. For a byte array, the second argument is treated as a string.
-xxxx(number)
     The next argument is treated as a list. The first number elements of
     this list are sent (not preceded by an integer!!!!). Except xxxx(1) is
     the same as xxxx. If the list has more elements, it will be truncated,
     if there are less than number, zero elements are appended. (0 for
     integers, "0.0" for floats and doubles, "" for strings, '\0' for
     characters).

For example:

send tid/group msgtag -float 5.4 -double() {3.14 2.17}
     Send a float (5.4), an integer (2) and two doubles (3.14 and 2.17)
send tid/group msgtag -int 5 -byte(7) "abcdefghijkl"
     Send an integer (5) and 7 bytes (abcdefg) (The string is truncated)
send tid/group msgtag -string "hello" -byte() "hello"
     Send an integer (6) followed by 6 bytes ("hello\0"), and another
     integer (5) followed by 5 bytes ("hello").

Task identifiers

In Pvm each process has a unique number, which is called the task identifier
(tid). This number is used when sending or receiving packages through Pvm.
The keywords id or parent are accepted as tid too. This allows the use of
send parent ... in stead of send [parent] ...

Message tags

Each package that is sent or receives also has a message tag (msgtag). This
can be seen as a channel number, which can be checked at the receiving side
for many different purposes. Always use non-negative numbers for this (0 is
valid).

----------------------------------------------------------------------------

Addhost

SYNOPSIS
     addhost hostname ?hostname .....?
DESCRIPTION
     Add hosts to the virtual machine.

Bind

SYNOPSIS
     bind tid msgtag ?command?
     bind tid any ?command?
     bind tid kill ?command?
DESCRIPTION
     Bind the given command to the given tid/msgtag combination. Any time
     later when data is received through Pvm, the command wil be executed.
     The keyword 'any' matches any tid or msgtag, but not the keyword kill.
     kill can be used to execute any command as soon as the process tid is
     killed.

     During execution of command, only data that matches tid and msgtag can
     be received, So the recv command doesn't need to specify it any more.
     Inside the command there are 3 macro's that can be used to find out
     additional information about the received data:
     %t   tid
     %m   msgtag
     %n   total number of bytes received.
     This is usefull if tid ormsgtag (or both) have the value any.

     If command is the empty string, the binding is deleted. If the command
     is missing, the currently bound command is returned.

Delhost

SYNOPSIS
     delhost hostname ?hostname .....?
DESCRIPTION
     Delete hosts from the virtual machine.

Dialog

SYNOPSIS
     dialog host title text bitmap default string ?string .....?
DESCRIPTION
     Pops up dialog with a button for each string argument. Returns index of
     button user presses, starting from 0 or the leftmost button. The index
     default specifies the default button.

Halt

SYNOPSIS
     halt
DESCRIPTION
     Halt the virtual machine, killing all processes and daemons.

Joingroup

SYNOPSIS
     joingroup groupname
DESCRIPTION
     Join the group groupname. The instance number (starting with 0) is
     returned.

Kill

SYNOPSIS
     kill tid ?tid .....?
DESCRIPTION
     Kill the processes with the given tid's.

Leavegroup

SYNOPSIS
     leavegroup groupname
DESCRIPTION
     Leave the group groupname.

Parent

SYNOPSIS
     parent ?tid?
DESCRIPTION
     Returns the parent of tid. If this process has no parent, the result
     will be empty
     If tid is not specified, id is assumed.

Patchlevel

SYNOPSIS
     patchlevel package
DESCRIPTION
     Returns the patch-levels of loaded libraries such as Tcl, Tk, Tkpvm and
     Pvm.

Recv

SYNOPSIS
     recv arg ?arg...?
DESCRIPTION
     Receive data from another process. The arguments indicate the expected
     format of the received data, and can have the following values:
          char
               character
          string
               string
          short
               short integer
          int  integer
          long
               long integer
          tid  task identifier. This is in fact the same as an integer, only
               the value is returned in hexadecimal notation
          float
               floating point
          double
               double
          xxxx()
               Any of the above followed by "()" means that an array is
               received. In PVM, an array is always sent as an integer (the
               number of elements), followed by the elements. For a byte
               array, the result is returned as a string. For other types it
               is returned as a list. NOT IMPLEMENTED YET IN BETA RELEASE 3.
          xxxx(number)
               number times an element of type "xxxx" will be received. The
               result is returned as a string in case of bytes, otherwise it
               will be returned as a list. NOT IMPLEMENTED YET IN BETA
               RELEASE 3.
          The data will be received from the channel that currently is open.
          Generally this is specified by the bind command.

     Reset

     SYNOPSIS
          reset
     DESCRIPTION
          Kill all processes, except myself and the PVM daemons.

     Send

     SYNOPSIS
          send tid msgtag arg ?arg...?
          send groupname msgtag arg ?arg...?
     DESCRIPTION
          Send all arguments to tid or groupname through channel msgtag. If
          arguments are not preceeded by format specifiers, they are sent as
          integers, doubles or string accordancing to the above conversion
          rules. For the syntax of format specifiers, see data types

     Spawn

     SYNOPSIS
          spawn ?options? name ?options?
     DESCRIPTION
          The given process will be spawned. Options:
          -ntask num
               number of taskes
          -host hostname
               which host
          -arch arch
               which architecture
          -output fileId/msgtag
               redirect output of spawned processes to a file (e.g. stdout),
               or redirect it with a msgtag (new in beta release 2).
          All options after name are options for the spawned process. These
          are not interpreted by pvmsh or pvmwish.

          The spawn command returns a list of tid's that later can be used
          in other commands. An error is genereted if no processes can be
          spawned.

     Tasks

     SYNOPSIS
          tasks
     DESCRIPTION
          Returns a list of all tid's running in the virtual machine.
          Additional options can specify a subset of this list. (new in beta
          release 2)
          -name name
               Only return those tid's that match the name given. name can
               be a regular expression. Processes spawned by UNIX always
               have an empty name ("").
          -host hostname
               Only return tid's on specified host
          -arch arch
               Only return tid's on specified architecture
          -group group
               Only return tid's in specified group
          Combinations of these options are allowed.

     Term

     SYNOPSIS
          term name host ?command?
     DESCRIPTION
          Pops up a text display. A new command name is defined that puts
          text on this display. If the user presses return anywhere, the
          content of the current line will be appended to command and
          executed.
     EXAMPLE
          term t1 "" puts stdout
          t1 "This text is displayed"
          Everything the user types on the text display will be written to
          stdout.

     Tid

     SYNOPSIS
          tid (was id in beta 2 and earlier)
     DESCRIPTION
          Returns my own tid.

     Version

     SYNOPSIS
          version package
     DESCRIPTION
          Returns the versions of loaded libraries such as Tcl, Tk, Tkpvm
          and Pvm.
     Back to Home
     -----------------------------------------------------------------------
     written by J. Nijtmans for the [MIAMI]  project
