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'