StarExecCommand User Guide
--------------------------

StarExecCommand is a program that can be used to communicate with the StarExec server from the
command line. StarExecCommand can be used on any system with Java installed, and can be run by
using the following command at a command prompt.

java -jar StarexecCommand.jar

After starting the program, a shell accepting commands will start up. Typically, the command "login"
will be the first you will want to run-- the login command will take in credentials and start a connection
to StarExec. See the documentation on commands for more information.

Syntax
------

StarexecCommand runs user commands one by one. All commands have a
command followed by a set of parameters, using the following syntax

{command} {parameters}

Where {command} specifies a particular action and where parameters are space-separated key/value
pairs of the form {key}={value}. There should be no spaces between {key} and "="--there may be any
number of spaces in {value}. Some parameters may not have values, in which case {value} can be the
empty string. Neither commands nor parameter keys are case sensitive--parameter values ARE case
sensitive.  Parameters can be specified in any order. The parameters accepted by StarExecCommand are
described below. An example command using this syntax is...

'getjobinfo id=472 out=somefilelocation.zip'

Many other examples are given in the sections explaining specific commands. Note that quote marks are used for clarity only--
they should NOT be included in commands.

Parameters
----------

The following parameters are used in various commands. Quotation marks here are used for emphasis-- they should not
be included when specifying parameters. Parameters are NOT case sensitive.

"addr"--Specifies the base URL at which to log into Starexec. The URL should be absolute and should end with a '/'.

"attr" -- Include benchmark attributes in the XML. Used for space XML downloads.

"allPerm"--Indicated that all permissions should be enabled for an upload. All permissions are disabled
by default. allPerm has no value.

{"addSolver", "addUser", "addSpace", "addJob", "addBench", "removeSolver" ,"removeUser",
"removeSpace", "removeJob", "removeBench"} - These are ten separate parameters specify that the
corresponding permission should be set to true. None requires a value.

"bt" -Specifies the ID of the benchmark type that should be used for a benchmark upload.

"comp" -When downloading hob information, indicates only completed pairs should be included in the csv

"cpu" -Specifies the cpu timeout that should be used for a new job, in seconds.

"copyprimitives" -When set to true copyspace command copies primitives instead of linking

"d" -Specifies a description. When optional, the empty string is used as a default.

"recycleprims" -When removing a subspace from an existing space, specifies that all the solvers and benchmarks
			   present in the space hierarchy rooted at the subspace being removed should be moved to the recycle bin,
			   Only the primitives you have permission to recycle will be recycled

"dep" -Specifies a dependency for a benchmark upload.

"df" -Specifies a path to a local file that will contain a description.

"downloadable" -Specifies that a benchmark upload should be downloadable.

"f" -Specifies a path to a  local file.

"from" -When copying a primitive, specifies the ID of the source space.

"hier" -On a benchmark upload, means that the archive structure should be converted to a space
structure. By default, all benchmarks are placed in the space being uploaded to.

"id" -Specifies the ID of a primitive, whether that be a space, job, benchmark, etc.

"incids" -When downloading a job CSV file, indicates that IDs for job pairs, solvers, configurations, and benchmarks
			should be included.

"interval" -Specifies the results interval parameter when creating jobs. 0 (no incremental results) is the default.

"limit" -When printing primitives to the command line, specifies the maximum number to retrieve and print.

"link" -When uploading benchmarks with dependencies, indicates that the first directory in the path
corresponds to a dependent bench space.

"lock" -Sets a newly created subspace as locked.

"longpath" - When set to "true" uses a alternative zip directory path for getjobpair command. The longer path
            format is: Job##_output/SpaceName/SolverName/PairId/
            whereas the shorter path format is: Job##_output/

"mem" -Sets the maximum memory, in gigabytes, that each pair of a job is allowed to utilize.

"n" -Specifies a name. When optional, the default is the date.

"nosolve" -When downloading a space, indicates solvers should not be downloaded

"nobench" -When downloading a space, indicates benchmarks should not be downloaded

"out" -Specifies a filepath to which a file should be downloaded.

"ow" -Indicates that the file at the path given by "out", if it exists, should be overwritten with the new file.

"pause" -When creating a job, indicates that the job should be paused on startup.

"pid" -Specifies a post processor id in job creation. Specifies an update processor when downloading space XML

"preid" -Specifies a pre processor id (used only in job creation).

"qid" -Specifies a queue id (used only in job creation).

"run" -Says that a test job should be created for a solver immediately upon uploading it

"seed" -An integer that will be passed into the preprocessor when it is used for a particular job.

"set" -The ID of a settings profile that can be used when uploading a solver

"since" -When downloading job info, specifies the earliest completed pair after which to get info.

"suppresstime" -When creating a job, do not include timestamps in the lines of job output.

"t" -When using 'sleep,' specifies the amount of time in seconds. Decimal values are permitted.

"to" -When copying a primitive, specifies the ID of the destination space, or the root of the
	  destination hierarchy.

"trav" -When creating a job, specifies the type of traversal that shold be used. The value "d" is
		used to specify depth-first traversal, whereas "r" is for a round-robin traversal.

"type" -When uploading a solver, specifies the type of executable being uploaded. 1=solver,
		2= preprocessor, 3=result checker, 4=other. Defaults to 1 if not specified.

"u" -When logging in, specifies the username to log in with. When listing primitives, causes a user's own
	 primitives to be retrieved instead of the primitives of a space.

"url" -Specifies the URL of a remote file.

"val" -Specifies a new value for a user setting.

"verbose" -Tells StarExec that status should be printed to the standard output in batch mode.

"w" -Specifies the wallclock timeout that should be used for a new job, in seconds.

Commands
--------

The following notes describe each command recognized by StarExec. Different commands
expect different parameters, and many paramters are optional. Required parameters
are listed for every command, as are optional parameters.

General Commands
----------------

These commands have a range of functions.

--Exit -Logs the user out of StarExec and exits StarexecCommand.
REQUIRED: None
OPTIONAL: None

--ignoreids -Instructs StarExecCommand to stop printing the IDs of newly uploaded solvers and processors and
			 newly created jobs and spaces. This command does nothing if this behavior is already disabled.
REQUIRED: None
OPTIONAL: None

--login -Logs the user into StarExec.
REQUIRED: "u", "p". If "u" equals "guest" then "p" is not required.
OPTIONAL: "addr"
EXAMPLES:

'login u=fake@example.com p=password'

'login u=guest'

By default, StarExecCommand attempts to log into www.starexec.org, but an alternative instance can also be specified.
An example for connecting to an alternate instance of starexec would be

'login u=fake@example.com p=password addr=http://stardev.cs.uiowa.edu/starexec/'

In this case, 'addr' must be in this exact format-- it should point to the home page, not to any
deeper page, and it should end with a '/'

--logout -Logs the user out of StarExec.
REQUIRED: None
OPTIONAL: None

--pausejob -Pauses a job that is currently running on starexec. "id" refers to a job ID.
REQUIRED: "id"
OPTIONAL: None

--rerunjob -Reruns an entire job. "id" refers to a job id. Only completed jobs may be run.
REQUIRED: "id"
OPTIONAL: None

--rerunpair -Reruns a single job pair. "id" refers to a pair id.
REQUIRED: "id"
OPTIONAL: None

--resumejob -Resumes a job that was paused previously. "id" refers to a job ID.
REQUIRED: "id"
OPTIONAL: None

--runfile -Given a file containing a sequence of commands, runs all the commands in succession.
REQUIRED: "f"
OPTIONAL: "verbose"

--sleep -Given "t" sleep for the specified number of seconds
REQUIRED: "t"
OPTIONAL: None

--returnids -Instructs StarexecCommand to print the IDs of newly uploaded solvers and processors and newly
			 created jobs and spaces in the form "id={newId}\n" The default behavior at the start of a session
			 is not to do this. This command does nothing if this behavior is already enabled.
REQUIRED: None
OPTIONAL: None

--viewuploadstatus -Instructs StarexecCommand to print the status of the benchmark upload request
					specified by the given ID. "id" refers to a benchmark upload ID, which is returned
					whenever you upload benchmarks with the "returnids" option enabled
REQUIRED: "id"
OPTIONAL: None


Download Commands
-----------------

Every download command retrieves an archive from the server and saves it in a specified location.
Downloaded archives will be in the .zip format.
Most of them expect two parameters. "id", and "out", a If a file already exists at the path specified
by "out," the parameter "ow" should be included. "ow" requires no value. An example download command is...

'getspacexml id=1 out=xmlfile.zip'

Another example, which will cause the output file to be overwritten, is...

'getspacexml id=1 out=xmlfile.zip ow='

The following commands can be used for downloading

--getbench -Downloads the benchmark associated with the given benchmark id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getbenchproc -Downloads all benchmark processors associated with the given community id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getjobinfo -Get the CSV pertaining to the job associated with the given id.
REQUIRED: "id" "out"
OPTIONAL: "ow" "incids" "comp"
EXAMPLE: 'getjobinfo id=6 out=C:/Users/JohnSmith/Desktop/fakefile.zip incids='

--getjobout -Gets the output for all the job pairs associated with the job with the given id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getjobpair -Downloads the output from the job pair associated with the given id.
REQUIRED: "id" "out"
OPTIONAL: "ow", "longpath"

--getjobpairs -Downloads the output from every pair in the given list. Every pair must belong to the same job.
The value of the "id" parameter should be a comma-separated list of job pair ids.
REQUIRED: "id" "out"
OPTIONAL: "ow"
EXAMPLE: "getjobpairs id=5,20,30 out=outputs.zip"

--getnewjobinfo -Get the CSV pertaining to the job associated with the given id containing only
info related to job pairs that have been completed since the last time the command was used.
in the current session. When used with "since," info for every pair completed after "since" will be downloaded.
REQUIRED: "id" "out"
OPTIONAL: "ow" "since"

--getnewjobout -Get the output for the job pairs associated with the given job that have been
completed since the last time the command was used in the current session. When used with "since,"
retrieve all pairs completed after "since."
REQUIRED: "id" "out"
OPTIONAL: "ow" "since"

--getpostproc -Downloads all post processors associated with the given community id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getpreproc -Downloads all pre processors associated with the given community id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getsolver -Downloads the solver associated with the given community id.
REQUIRED: "id" "out"
OPTIONAL: "ow"

--getspace -Donwloads the space at the given ID. Solvers and benchmarks are both included by default,
but can be excluded by using "nosolve" and "nobench"
REQUIRED: "id" "out"
OPTIONAL: "ow" "nosolve" "nobench"

--getspacehierarchy -Downloads the space hierarchy associated with the given space id.
REQUIRED: "id" "out"
OPTIONAL: "ow" "nosolve" "nobench"

--getspacexml -Downloads an XML file representing the space hierarchy.
REQUIRED: "id" "out"
OPTIONAL: "ow" "attr" "pid"

--getjobxml -Downloads an XML file representing a specific job
REQUIRED: "id" "out"
OPTIONAL: "ow"

--polljob -Downloads both job output and job info at the specified interval until the job is complete. Saved
archives will have name given plus "-info" or "-output" and an integer. Time is in seconds.
REQUIRED: "id", "out", "t"
OPTIONAL: "ow"

Set Commands
------------

These commands are used to change user settings for the current user. The first four of the following
commands expect one parameter of the form "val={newval}", where "newval" will be the new value of
the selected setting. The last two commands expect the parameter "id," where "id" is a space ID, and
also accept the optional parameter "hier".

--setfirstname -Sets the user's first name
REQUIRED: "val"
OPTIONAL: None
EXAMPLE: 'setfirstname val=newname'

--setinstitution -Sets the user's institution.
REQUIRED: "val"
OPTIONAL: None
EXAMPLE: 'setinstitution val=The University of Iowa'

--setlastname -Sets the user's last name
REQUIRED: "val"
OPTIONAL: None

--setspaceprivate -Sets the space with the given id as private--with "hier," sets entire hierarchy private
REQUIRED: "id"
OPTIONAL: "hier"
EXAMPLE: 'setspaceprivate id=1 hier='

--setspacepublic -Sets the space with the given id as public--with "hier," sets entire hierarchy public.
REQUIRED: "id" "hier"
OPTIONAL: None

Push Commands
-------------

These commands allow users to push benchmarks, solvers, and processors to the server. They are more
individually unique than previous commands, and many accept a large number of optional parameters.

--pushsolver -This command is used for uploading a solver. The parameter "id" refers to a space ID.
			  The ID of the newly uploaded solver will be printed if "returnids" has been called.
REQUIRED: ("f" OR "url") "id"
OPTIONAL: "n" ("d" OR "df") "downloadable" "run" "set" "type"
EXAMPLE: 'pushsolver id=153 f=solverdirectory.tar n=fakesolver d=Solver Description downloadable='

--pushbenchmarks -Uploads a benchmark archive to an existing space. "id" refers to a space ID.
				  The ID of newly uploaded benchmarks will NOT be printed, even if "returnids" has been called.
				  Instead, an ID for this upload request will be returned. This upload ID can be used to query the
				  status of the benchmark upload to see its progress using "viewuploadstatus". In addition the
                  upload status of an upload request can be seen through the web interface at
                  https://www.starexec.org/starexec/secure/details/uploadStatus.jsp?id=XX
                  Where XX is the upload request ID.
REQUIRED: ("f" OR "url") "id" "bt"
OPTIONAL: ("d" OR "df") "dep" "downloadable" "hier" "link" "allPerm" (also all other permission parameters)
EXAMPLE: 'pushbenchmarks id=231 url=http://example.com/benchmarks.zip df=descriptionfile.tar bt=1 '

--pushbenchproc -This command uploads a benchmark processor to a community. The parameter "id"
				 refers to a community id. The ID of the newly uploaded processor will be printed if "returnids" has been called.
REQUIRED: "f" "id"
OPTIONAL: "n" "d"
EXAMPLE: 'pushbenchproc id=142 f=procdirectory.tgz d=Processor Description n=newproc'

--pushconfig -This command is used for uploading a configuration for an existing solver. The parameter
			  "id" refers to a solver ID. The ID of the newly uploaded configuration will be printed if "returnids" has been called.
REQUIRED: "f" "id"
OPTIONAL: "n" "d"
EXAMPLE: 'pushbenchproc id=4 f=configdirectory.tgz d=New Configuration n=config'

--pushpostproc -This command uploads a post processor to a community. The parameter "id" refers to a
				community id. The ID of the newly uploaded processor will be printed if "returnids" has been called.
REQUIRED: "f" "id"
OPTIONAL: "n" "d"

--pushpreproc -This command uploads a pre processor to a community. The parameter "id" refers to a
				community id. The ID of the newly uploaded processor will be printed if "returnids" has been called.
REQUIRED: "f" "id"
OPTIONAL: "n" "d"

--pushspacexml -This command is used for uploading  a space XML. The parameter "id" refers to a space
				ID and is required. The ID of the newly created spaces will NOT be printed, even if "returnids" has been called.
REQUIRED: "f" "id"
OPTIONAL: None

--pushjobxml -This command is used for uploading  a job XML. The parameter "id" refers to a space

REQUIRED: "f" "id"
OPTIONAL: None


Delete Commands
---------------

These commands are all used to delete primitives from Starexec. All of them accept a single parameter,
"id." You may delete multiple primitives at once by putting all the ids in a comma-seperated list. Delete commands all look like the following example.

'deleteconfig id=5,47,23'

--deletebench -Deletes the benchmark with the given ID.
REQUIRED: "id"
OPTIONAL: None

--deletebenchproc -Deletes the benchmark processor with the given ID.
REQUIRED: "id"
OPTIONAL: None

--deleteconfig -Deletes the configuration with the given ID.
REQUIRED: "id"
OPTIONAL: None

--deletejob -Deletes a job with the given ID and all of its output
REQUIRED: "id"
OPTIONAL: None

--deletesolver -Deletes the solver with the given ID.
REQUIRED: "id"
OPTIONAL: None

--deletepostproc -Deletes the post processor with the given ID.
REQUIRED: "id"
OPTIONAL: None

Remove Commands
---------------

This set of commands can be used to remove the associations between primitives
and spaces. You may remove multiple primitives at the same time by putting ids in a comma-seperated list, as illustrated
in the examples below.

-- removebench -Removes a benchmark from a given space. "id" is the benchmark ID.
REQUIRED: "id" "from"
OPTIONAL: None
EXAMPLE: 'removebench id=54,241,1 from=3'

-- removejob -Removes a job from a given space. "id" is the job ID.
REQUIRED: "id" "from"
OPTIONAL: None

-- removesolver -Removes a solver from a given space. "id" is the solver ID.
REQUIRED: "id" "from"
OPTIONAL: None

-- removesubspace -Removes a subspace from a given space. "id" is the subspace ID. If "recycleprims" is present,
				   all solvers and benchmarks present in the space hierarchy rooted at the given space that
				   you have permission to recycle will be recycled.
REQUIRED: "id"
OPTIONAL: "recycleprims"
EXAMPLE: 'removesubspace id=10 recycleprims='

-- removeuser -Removes a user from a given space. "id" is the user ID.
REQUIRED: "id" "from"
OPTIONAL: None

Create Commands
---------------

These commands create some new information on StarExec. Like push commands, they also accept a
varied set of parameters.

--createjob -This command is used for creating a new job in a given space. "id" refers to the id of
			 the space that the job should be created in. Currently, only jobs that run every benchmark and solver and keep
			 the hierarchy structure can be created from StarExecCommand. By default, job-pairs are run in a depth-first manner,
			 the optional parameter "trav" can be used to alter this behavior. To immediately start polling this job
			 for results, simply include the polljob parameters "t" and "out" and optionally "ow".
			 The ID of the newly created job will be printed if "returnids" has been called.
REQUIRED: "id"  "qid"
OPTIONAL: "n" "d" "w" "cpu" "trav" ("t" AND "out") "ow" "pid" "preid" "mem" "pause" "seed" "suppresstime" "interval"
EXAMPLE: 'createjob id=5 pid=2 qid=3 n=commandjob w=200 cpu=100 trav=r pause='

--createsubspace -Creates a subspace of an existing space. "id" refers to the id of an existing space.
				  The ID of the newly created subspace will be printed if "returnids" has been called.
REQUIRED: "id"
OPTIONAL: "n" "d" "lock" "allPerm" (also all the other permissions parameters)
EXAMPLE: 'createsubspace id=5'

Copy Commands
-------------

These commands can be used to either copy or link primitives from one space to another. To 'copy'
a primitive means to create a deep copy-- you will become the owner of a copied solver or benchmark,
and it will count towards your disk usage. To 'link' a primitive means that you are using a primitive
that still belongs to another user. If they choose to delete a solver or benchmark that you have linked,
then you will lose access to it. You may also copy or link primitives that you own. You may copy or link
multiple primitives at the same time by putting ids in a comma-seperated list, as illustrated in the examples
below.

--copybench -Copies a benchmark from one space to another. If "from" is not given, you must own the benchmarks you want to copy.
If "from" is given, the benchmarks will be copied from the specified space, and you may copy benchmarks you do not own given you have permission to copy from the
given space. "id" is a benchmark id, and "from" and "to" are space ids.
REQUIRED: "id" "to"
OPTIONAL: "from"
EXAMPLE: 'copybench id=42,10,1 from=643 to=56"

--linkbench -links an existing benchmark and associates it with a space. If "from" is not given, you must own the benchmarks you want to link.
If "from" is given, the benchmarks will be linked from the specified space, and you may link benchmarks you do not own given you have permission to link from the
given space. "id" is a benchmark id, and "from" and "to" are
space ids.
REQUIRED: "id" "to"
OPTIONAL: "from"
EXAMPLE: 'linkbench id=6 from=63 to=124

--copysolver -Copies a solver and places it into a new space or hierarchy.
You may copy any solver that you have permission to download.
If "from" is given, the solvers will be copied from the specified space, and you may copy solvers you do not own given you have permission to copy from the
given space. "id" is a solver id, and "from" and "to" are space ids
REQUIRED: "id" "to"
OPTIONAL: "hier" "from"

--linksolver -links an existing solver and associates it with a new space or hierarchy.
You may link any solver that you have permission to download.
If "from" is given, the solvers will be linked from the specified space, and you may copy solvers you do not own given you have permission to link from the
given space. "id" is a solver id, and "from"
and "to" are space ids
REQUIRED: "id" "to"
OPTIONAL: "hier" "from"

--linkjob -Links an existing job in a new space space. If "from" is not given, you must own the jobs you want to link.
If "from" is given, the jobs will be linked from the specified space, and you may link jobs you do not own given you have permission to link from the
given space. "id" is a job id, and "from" and "to" are space ids.
REQUIRED: "id" "to"
OPTIONAL: "from"

--copyspace -Copies an existing space or space hierarchy rooted at "id" from to the space space given by "to"
REQUIRED: "id" "to"
OPTIONAL: "hier","copyprimitives"

--linkuser -Associates an existing user with a space. "id" is a user id, and "to" is a
space id.
REQUIRED: "id" "to"
OPTIONAL: None

List Commands
-------------

These commands will print the contents of a given space to the console. IDs and names will be printed.
All lists are terminated by the newline character "\n".
Every command in this category requires the "id" parameter, specifying a space. The parameter "limit"
is optional, and indicates that at most "limit" primitives should be printed. An example is given below

'lsjobs id=4 limit=100'

This will print at most 100 jobs present in space 4. An example  of getting your own primitives is

'lssolvers u='

The list commands are shown below.

--lsbenchmarks -Lists the IDs and names of all benchmarks in the space.
REQUIRED: ("id" OR "u")
OPTIONAL: "limit"

--lsjobs -Lists the IDs and names of all jobs in the space.
REQUIRED: ("id" OR "u")
OPTIONAL: "limit"

--lssolvers -Lists the IDs and names of all solvers in the space.
REQUIRED: ("id" OR "u")
OPTIONAL: "limit"

--lsconfigs -Lists the IDs and names of all configurations of a solver (id refers to a solver's id)
REQUIRED: "id"
OPTIONAL: "limit"

--lssubspaces -Lists the IDs and names of all subspaces in the space the current user is authorized to see
REQUIRED: "id"
OPTIONAL: "limit"

--lsusers -Lists the IDs and names of all users in the space.
REQUIRED: "id"
OPTIONAL: "limit"


View Commands
-------------

The following commands will print out information about Starexec primitives to the console.
For each command, the following format is used to display information. The order of the printed attributes
is not guaranteed.

id= "1" : name= "example name" : description= "example description"

View commands can print out either every attribute or a limited set of attributes. By default, only
the id, name, and description (if applicable) is printed out for each primitive. The first two commands
listed below can be used to change this setting.


--viewall -Makes all subsequent "view" commands print out every attribute for the requested primitive
REQUIRED: None
OPTIONAL: None

--viewlimit -Makes all subsequent "view" commands print out only the id, name, and description for the requested primitive
REQUIRED: None
OPTIONAL: None



--viewbench -Displays the ID, name, and description of the given benchmark
REQUIRED: "id"
OPTIONAL: None

--viewconfig -Displays the ID, name, and description of the given benchmark
REQUIRED: "id"
OPTIONAL: None

--viewjob -Displays the ID, name, and description of the given job
REQUIRED: "id"
OPTIONAL: None

--viewproc -Displays the ID, name, and description of the given processor
REQUIRED: "id"
OPTIONAL: None

--viewqueue -Displays the ID, name, and description of the given queue
REQUIRED: "id"
OPTIONAL: None

--viewsolver -Displays the ID, name, and description of the given solver
REQUIRED: "id"
OPTIONAL: None

--viewspace -Displays the ID, name, and description of the given space
REQUIRED: "id"
OPTIONAL: None

Shell Mode
----------

In shell mode, commands are issued one at a time to an interactive prompt. StarExecCommand will start
in shell mode by default during every session.


Batch Mode
----------

In batch mode, which is initiated by the runfile command StarExecCommand will read commands from a text file
and execute them in succession. Commands have the same syntax as they do in shell mode, and should be placed one per line. By
default, StarExecCommand will execute silently in batch mode--to see information regarding the
progress of the execution, add the additional argument "verbose" after the filepath when starting
StarExecCommand. An example of a shell startup would be...

runfile f=fileofcommands.txt verbose=

This would run StarExecCommand on the file 'fileofcommands.txt,' and it would also
instruct the program to print out status to standard output.

Scripting
---------

StarExecCommand supports variables to enable basic scripting capabilities. This
way, the "id" returned from a Create command can be passed as a parameter to a
later command.

Variable names start with a dollar sign ($) followed by letters (a to z or A to Z), numbers
(0 to 9) or the underscore character (_). Variable names are case sensitive.

Variables are set by prefixing a Create command with a variable name and an
equal sign (=):

EXAMPLE: '$NewSpace=createsubspace id=5'

Variables can later be accessed by passing a variable name as a parameter to
another function.

EXAMPLE: 'linkbench id=6 from=63 to=$NewSpace'
