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 | version
key=value... | config
internal state | print

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.

> > - h=host - the hostname to launch the process on. If this option is not specified the process is launched on the local host.
> > - c=cmd - the path to the executable plus any arguments. For example: c=c:\my\favorite\path\myapp.exe arg1 arg2 or c=\\somehost\someshare\some\path\someapp.exe arg1 arg2.
> > - e=env - a string of environment variables to set. Single quote this list and separate values by the vertical bar character. Example: e='var1=val1|var2=val2|var3=val3'
> > - d=dir - the working directory to launch the process in
> > - a=account p=password - the account and password used to set the security context for the launched process. If the mpd is in single user mode, these parameters are not necessary and they are ignored.
> > - 0=stdin 1=stdout 2=stderr 12=stdouterr 012=stdinouterr k=rank- these options specify where to connect the standard input, output, and error of the launched process. The format is host:port. For example, 012=somehost:1234, would connect to the host "somehost" on port 1234 three times to redirect standard input, output and error. When connecting to this host, the mpd sends a five byte message first. The first byte is a 0, 1, or a 2 to signify stdin, stdout or stderr. The next 4 bytes are the integer specified by the k=rank option. If no k option is specified a value of zero is sent by default.

> 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 of the mpd the console session is connected to. For example: 1.2.2

> Return values:

> > release.major.minor

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

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"