Console commands to MPD

Establish a console session with an mpd using the "mpd -console" command:

mpd -console -port x -phrase x -getphrase

mpd -console host -port x -phrase x -getphrase

The option -console creates a console session with an mpd on the local host or the host specified.  If the mpd is listening on a port other than the default, the option -port x can be used to specify what port to connect to.  If -phrase x or -getphrase are not specified the mpd searches for the passphrase specified at install time and then reverts to the default passphrase if mpd is not installed on the local host.

Quick reference:

Return value Command
Database operations
name,DBS_FAIL dbcreate
DBS_SUCCESS,DBS_FAIL dbcreate name or name=x
DBS_SUCCESS,DBS_FAIL dbdestroy name or name=x
DBS_SUCCESS,DBS_FAIL dbput name:key:value or name=x key=x value=x
value,DBS_FAIL dbget name:key or name=x key=x
DBS_SUCCESS,DBS_FAIL dbdelete name:key or name=x key=x
key=value,DBS_END,DBS_FAIL dbfirst name or name=x
key=value,DBS_END,DBS_FAIL dbnext name or name=x
name=x,DBS_END dbfirstdb
name=x,DBS_END dbnextdb
Process operations
launchid launch h=host c=cmd e=env d=dir a=account p=password 0=stdin 1=stdout 2=stderr or 12=stdouterr or 012=inouterr k=rank
ERROR_SUCCESS,LAUNCH_PENDING,error message geterror launchid
process id,-1 getpid launchid
exitcode,ACTIVE,FAIL getexitcode launchid
exitcode,FAIL getexitcodewait launchid
  freeprocess launchid
  kill launchid
  kill host=x pid=x
  killall
pid:command line... ps
Ring operations
hostA,hostB,hostC,... hosts
  extract
  insert host
  set nodes
  set key=value
  shutdown
  restart
  exitall
  done or quit
Local operations
  lset key=value
value lget key
  ldelete key
release.major.minor date version
release.major.minor data mpich version
key=value... config
internal state print
internal state stat ps launch config tmp forwarders barrier context
File operations
  fileinit account=x password=x
SUCCESS,error message putfile local=fullfilename remote=fullfilename replace=yes/no createdir=yes/no
SUCCESS,error message getfile remote=fullfilename local=fullfilename replace=yes/no createdir=yes/no
folders and sizes and filenames getdir path=fullpath
filename createtmpfile host=x
SUCCESS,FAIL deletetmpfile host=x file=x
integer mpich1readint host=x file=x
SUCCESS,FAIL - error message map host=x drive=x share=x account=x password=x
SUCCESS,FAIL - error message unmap host=x drive=x

DATABASE OPERATIONS

A ring of mpds can maintain a set of in-memory databases.  The databases store key/value pairs of strings.  The data is distributed around the ring.  Puts occur locally while gets travel around the ring.  The data is not persistent, so when a ring is taken down, all the databases are destroyed.  Mpd is not a database application.  This capability is provided so parallel applications can pass small amounts of data between processes.  It is not intended to hold user data.

dbcreate

Description:

This command creates a database and returns the name.

Return values:

The name of the database or "DBS_FAIL" if an error occurred.

dbcreate name or name=x

Description:

This command creates a database with the specified name.  DBS_SUCCESS is returned if the database is created or if it already exists.

Return values:

"DBS_SUCCESS" or "DBS_FAIL"

dbdestroy name or name=x

Description:

This command removes an entire database.

Return values:

"DBS_SUCCESS" or "DBS_FAIL"

dbput name:key:value or name=x key=x value=x

Description:

This command inputs a key/value pair into the specified database.  The key values need to be unique.  It is not allowed to call dbput with the same key more than once into the same database.

Return values:

"DBS_SUCCESS" or "DBS_FAIL"

dbget name:key or name=x key=x

Description:

This command retrieves the value of the key in the specified database.

Return values:

The value of the key in the specified database or "DBS_FAIL"

dbdelete name:key or name=x key=x

Description:

This command deletes a key from the specified databse.

Return values:

"DBS_SUCCESS" or "DBS_FAIL"

dbfirst name or name=x

Description:

This command starts the iterator on the specified database.  It returns the first key/value pair in the database or "DBS_END" if the database is empty.

Return values:

"key=value" or "DBS_END" or "DBS_FAIL"

dbnext name or name=x

Description:

This command returns the next key/value pair in the specified database.  Repeat this command until it returns "DBS_END" to iterate through the entire database.  You must call "dbfirst" before this command to start the iteration.

Return values:

"key=value" or "DBS_END" or "DBS_FAIL"

dbfirstdb

Description:

This command starts the iterator on the entire database namespace.  It returns the name of the first database in the space or "DBS_END" if there are no existing databases.

Return values:

"name=name" or "DBS_END"

dbnextdb

Description:

This command returns the name of the next database in the namespace.  Repeat this command until it returns "DBS_END" to iterate through the names of all available databases.  You must call "dbfirstdb" before this command to start the iteration.

Return values:

"name=name" or "DBS_END"

 

PROCESS OPERATIONS

launch h=host c=cmd e=env d=dir a=account p=password 0=stdin 1=stdout 2=stderr or 12=stdouterr or 012=inouterr k=rank

Description:

With the default installation, the mpds run as services on each of the nodes.  When a launch command reaches the requested node, the mpd uses the account and password parameters to launch the requested process in the security context of that user.  If the mpd has been started in single user mode, then the mpd runs in the security context of a single user.  The mpd runs in single user mode if it was installed with a specific username and password or if it is run from a command prompt, "mpd -d ...".  When in single user mode all processes are launched in the security context of the same user.  There is no need to pass the account and password.  If they are provided they are ignored. 

Return values:

launchid

geterror launchid

Description:

This command returns the current error message for the launch command corresponding to the provided launchid.  ERROR_SUCCESS signifies that the launch was successful.  If the launch command is still in progress, the return value is LAUNCH_PENDING.  If there is an error associated with the launch, the specific error message will be returned.

Return values:

"ERROR_SUCCESS", "LAUNCH_PENDING", "specific error message"

getpid launchid

Description:

This command blocks until the process associated with launchid has been started.  If there was an error in the startup of the process, this command will return -1 and geterror can be used to get the specific error message.

Return values:

process id or -1

getexitcode launchid

Description:

This command returns the exit code of the process associated with launchid.  If the process is still running, ACTIVE is returned.  If there was a error launching the process, FAIL will be returned and geterror can be called to retrieve the error message.

Return values:

exitcode,  "ACTIVE", "FAIL"

getexitcodewait launchid

Description:

This command blocks until the process associated with launchid exits.  If there is an error and the process was not launched, FAIL will be returned and geterror can be called to retrieve the error message.

Return values:

exitcode, "FAIL"

freeprocess launchid

Description:

This command frees the local structures used to store the process id, exit code and state.  freeprocess should be called after there is no need to get any further information about a process, usually after a successful call to one of the getexitcode commands.  After this command, the launchid becomes invalid and cannot be used in any other calls.

Return values:

nothing

kill launchid

Description:

This command kills the process associated with launchid.  "kill launchid" will only work if there is a valid process id in the local launchid structure.  If the state is LAUNCH_PENDING or an error has occurred, kill will not succeed.  This is important because if a launch command is issued and immediately followed by a kill command, the kill will not succeed if the state of the process is LAUNCH_PENDING. To guarantee that the process has started before trying to kill it you should call getpid first.

Return values:

nothing

kill host=x pid=x

Description:

This command attempts to kill the process on host x associated with pid x.  kill can only kill processes launched by the mpd. 

Return values:

nothing

killall

Description:

This command travels around the ring and attempts to kill all the processes launched by the mpds.

Return values:

nothing

ps

Description:

This command returns a list of the active processes started by all the mpds in the ring.

Return values:

pid:command line...

RING OPERATIONS

The ring operations manage a ring of mpds.  By default, an mpd is installed on a node in a single ring with itself.

hosts

Description:

This command travels around the ring of mpds and gets the name of each host.

Return value:

hostA,hostB,hostC,...

extract

Description:

This command removes the current host from the ring and forms a new ring with itself.

Return values:

nothing

insert host

Description:

This command merges the ring that the console session is attached to with the ring that host belongs to.  If the current host and the specified host belong to the same ring, the ring is split into two rings.

Return values:

nothing

set nodes

Description:

This command marches around the ring of mpds and lets everyone know who their neighbors are.  Then when the mpds shutdown and startup again, they try to connect to their neighbors.  This way the ring always tries to remain intact.

Return values:

nothing

set key=value

Description:

This command sets key/value pairs in the mpd section of the registry.  For example, "set temp=c:\temp" sets the temp directory for mpd files on all the nodes.

Return values:

nothing

shutdown

Description:

This command stops the mpd and closes the console connection.  Do not use this command unless you want to stop the mpd.  You will have to run "mpd -start" to get the mpd to start again.  Use "done" to close a console session.

Return values:

nothing

restart

Description:

This command restarts the mpd and closes the console connection.  You will have to reconnect to the mpd.  Use "done" to close a console session.

Return values:

"Restarting mpd..."

exitall

Description:

This command shuts down all the mpds in the ring and closes the console connection.  Do not use this command unless you want to stop the mpds.  After this command completes you will have to go to each node and start the mpds again (mpd -start).  Use "done" to close a console session.

Return values:

nothing

done or quit

Description:

This command closes the current console session with the mpd.

Return values:

nothing

LOCAL OPERATIONS

The local operations only act on the mpd and host that the console is connected to.  This is unlike the ring operations above that act on all the hosts and mpds in the ring.

lset key=value

Description:

This command sets the key/value pair in the mpd section of the registry on the host local to the mpd only.  The command does not traverse the ring like the "set key=value" command does.

Return values:

nothing

lget key

Description:

This command gets the value of the key provided from the mpd section of the registry on the host local to the mpd.

Return values:

value

ldelete key

Description:

This command removes the specified key from the mpd section of the registry on the host local to the mpd.

Return values:

nothing

version

Description:

This command returns the version numbers and date of the mpd the console session is connected to.  For example: 1.2.3 Mar  2 2002

Return values:

release.major.minor date

mpich version

Description:

This command returns the version numbers and date of the mpich dll on the host the console session is connected to.  For example: 1.2.4 Apr  12 2002

Return values:

release.major.minor date

config

Description:

This command returns all the mpd registry key/value pairs on the host local to the mpd.

Return values:

key=value...

print

Description:

This command spits out a lot of internal state useful only for debugging mpd.

Return values:

internal state

stat param

Description:

This command reports internal information on the specified parameter:

Return values:

internal state

FILE OPERATIONS

The file operations are for moving files between hosts, creating temporary files and one custom function for mpich.nt

fileinit account=x password=x

Description:

This command is the first command that must be issued before the other commands can be used.  File operations are done under the security context of this user.  If the password option is omitted, you will be prompted to input the password.

Return values:

nothing

putfile local=fullfilename remote=fullfilename replace=yes/no createdir=yes/no

Description:

This command copies the file described by the local option to the location described by the remote option.  Both the local and remote options must specify complete paths including file names.  The replace and createdir options refer to the remote file.  replace=yes overwrites the remote file if it exists.  createdir=yes causes the path described by the remote option to be created if it doesn't exist.  If replace and createdir are not specified, the defaults are replace=yes and createdir=yes.

Return values:

"SUCCESS" or "error message"

getfile remote=fullfilename local=fullfilename replace=yes/no createdir=yes/no

Description:

This command copies the file described by the remote option to the location described by the local option.  Both the remote and local options must specify complete paths including file names.  The replace and createdir options refer to the local file.  replace=yes overwrites the local file if it exists.  createdir=yes causes the path described by the local option to be created if it doesn't exist.  If replace and createdir are not specified, the default values are replace=yes createdir=no.

Return values:

"SUCCESS" or "error message"

getdir path=fullpath

Description:

This command returns the names of the folders and files found in the directory on the remote host described by the path option.  The path must be a full path.  The file names are returned preceded by their file size like this: 1022 cathy.txt

Return values:

folders and sizes and filenames or and error message: "ERROR: error message..."

createtmpfile host=x

Description:

This command createtmpfile creates a temporary file on the host specified and returns the file name.

Return values:

filename

deletetmpfile host=x file=x

Description:

This command deletes the file described by the file option on the host described by the host option.  The file option must specify the complete path to the file.

Return values:

"SUCCESS" or "FAIL"

mpich1readint host=x file=x

Description:

This command is a custom function provided to allow mpd to launch mpich 1.2.x applications.  It reads an integer from the file that was written by the root process during MPI_Init.

Return values:

integer

map host=x drive=x share=x account=x password=x

Description:

This command maps a network share to the drive specified on the host specified.  If the mapping already exists this call returns success.  If a different mapping already exists or an error occurs, the call returns fail.

Return values:

"SUCCESS" or "FAIL - error message"

unmap host=x drive=x

Description:

This command unmaps a drive previously mapped with a map call.  Drives mapped by the interactive user cannot be unmapped by this call.  Only mappings created by mpd can be unmapped.

Return values:

"SUCCESS" or "FAIL - error message"