User Tools

Site Tools


manual:soapif

SOAP interface of the 3G Bridge

The 3G Bridge has two interfaces, one of them is a gSOAP based web-service interface. There is a command line client for this interface, called wsclient. To develop your own client for this web interface, you must download the latest or a matching release version of the WSDL from Sourceforge.

This manual describes the use of the wsclient command.

Generic options

Option Description
-h, --help Show a short help text and exit.
--help-add Show a short help about submitting a job and exit.
-V, --version Show the command's version and exit. (Not the same as -m version !)

Remote commands

To perform a remote command, two options are mandatory: the endpoint, and the mode. Other options are mandatory only for the relevant modes.

Option Description
-e, --endpoint URL The URL of the web-service interface.
-m, --mode MODE Mode, which can be:
add Submit a new job.
status Query the status of specified jobs.
griddata Query the griddata attribute of the given job.
output Query the locations (URLs) of the output files of finished jobs.
delete Remove jobs from the 3G Bridge; cancel them first if necessary.
finished Query the identifiers of finished (either successful or failed) jobs.
version Query the version of the server.
gridalgs Query the algorithms registered to a grid.
-T, --timeout NUM Specify the connection timeout in seconds

The version mode does not need any other options to be specified.

Modes manipulating jobs require either a single job identifier or a list of them. These modes are: status, griddata, output, delete.

Option Description
-j, --jid ID Specify a job identifier to be used.
-f, --jidfile PATH Specify a file containing a list of identifiers (each id a separate line).

The add mode needs several options to describe the job to be submitted.

Option Description
-n, --name NAME Name of the algorithm.
-g, --grid NAME Backend grid.
-a, --args STR Arguments for the job.
-i, --in INSPEC Specify an input file for the job.
-o, --out NAME Specify an output file of the job.
-E, --env NAME=STR Specify an environmental variable for the job.
-t, --tag STR Specify a tag for the job. (Not necessary, but useful.)
--repeat NUM Submit multiple jobs with the same specification.

The name and grid are mandatory options for job submission. Together, they specify a queue in the Bridge.

Option --args specifies the command line arguments for the job. Don't forget to enclose them in quotes!

The --env option can be specified multiple times. Each occurrence adds a definition of an environmental variable for the job. The back-end grid must support it; otherwise, it's not used.

The --tag option can be used to add an arbitrary tag to the job. It is only stored, but not interpreted by the Bridge. It's optional, but can be useful to identify batches of jobs later.

The --out option can be specified multiple times; at least one must be specified. Each occurrence specifies an output file for the job. Only the logical name has to be specified. The given file will be transferred to the Bridge upon completion, and it will be accessible through http. When the job has finished, the URLs of the output files of a job can be queried with --mode output.

The --in option can be specified multiple times; at least one must be specified. Each occurence specifies an input file for the job. The syntax of input file specification of the Bridge is as follows:

INSPEC ::= LOCAL_FILE | REMOTE_FILE
LOCAL_FILE ::= <absolute path>
REMOTE_FILE ::= <logical_name> '=' <URL> [ '=' <MD5> [ '=' <SIZE> ] ] 

If a local file is to be used, the absolute path must be specified (i.e., starting with '/' ). Remote file specification must contain a URL, and may contain the MD5 sum and the size (in bytes) of the file, separated with '=' characters. For example:

-i input.txt=/home/user/inputs/1.txt
-i input.txt=http://example.com/inputs/1.txt=8aeaaa6a031e3de597906d67d0701a1b=8478

If the MD5 and size attributes are specified, the URL will pass through the 3G Bridge and BOINC; the DG clients will download the input files directly. If only the URL is specified, and the DownloadManager plugin is set up, the Bridge will download these files and submit them to BOINC as local input files. If the DonwloadManager plugin is not set up, these jobs will not run.

Specifying URL with MD5 sum and size upon submission is highly encouraged for scalability reasons.

The --repeat option tells the 3G Bridge to create several jobs with the same specification. In this case, all created jobs' identifiers will be returned. NOTE A technical limitation: --repeat must not be specified if local input files are used. If this option is specified, all input files must be specified with remote URL.

The gridalgs mode requires the --grid option to be specified. It will list all available algorithm names for the specified grid.

Output specification

The wsclient prints its result to the standard output.

Mode Output
add List of JobIDs.
status List of (JobID, Status) pairs.
griddata List of (JobID, string) pairs.
output List of (JobID, LogicalFilename, URL) triplets.
delete
finished List of (JobID, Status) pairs.
version “3G Bridge <VERSION>” (sans quotes).
gridalgs List of algorithm names.

The exact definition of these terms are:

  • “List”: lines separated with '\n'.
  • “Pair” and “triplet”: separated with a single space.
  • “JobID”: a unique id (UUID) of a submitted job.
  • “<VERSION>”: a standard, dotted version number.

Examples

wsclient -V
wsclient -m version -e 'http://example.com:8091/'
3G Bridge 1.9
wsclient -m gridalgs -e 'http://example.com:8091/' -g test
dsp
autodock
app
Submit a job
wsclient -m add -e 'http://example.com:8091/' \
  -g test -n app \
  -i alpha.txt=/home/user/inputs/alpha_1.txt \
  -i beta.txt=http://example.com/inputs/beta_1.txt \
  -a '--in1=aplha.txt --in2=beta.txt'
  -o result.txt
  -o stats.txt
0354f5c6-af97-4916-9d00-315d1c8a6229
Check a job's status
wsclient -m status -e 'http://example.com:8091/' -j 0354f5c6-af97-4916-9d00-315d1c8a6229
0354f5c6-af97-4916-9d00-315d1c8a6229 RUNNING
Check multiple jobs' status

Assuming jobs.txt contains UUIDs; one id each line.

wsclient -m status -e 'http://example.com:8091/' -f jobs.txt
0354f5c6-af97-4916-9d00-315d1c8a6229 RUNNING
f99a10e8-5afe-4e0d-99b4-c707690fe9c3 INIT
283f7841-9934-4636-ac32-e20b7b635113 ERROR
69009fc2-8ee0-4362-a27d-7ae7e66f824a FINISHED
Check grid data of a job
wsclient -m griddata -e 'http://example.com:8091/' -j 0354f5c6-af97-4916-9d00-315d1c8a6229
0354f5c6-af97-4916-9d00-315d1c8a6229 Uninterpreted string set by the back-end plugin
Check the output of a job
wsclient -m output -e 'http://example.com:8091/' -j 0354f5c6-af97-4916-9d00-315d1c8a6229
0354f5c6-af97-4916-9d00-315d1c8a6229 result.txt http://example.com/output/03/0354f5c6-af97-4916-9d00-315d1c8a6229/result.txt
0354f5c6-af97-4916-9d00-315d1c8a6229 stats.txt http://example.com/output/03/0354f5c6-af97-4916-9d00-315d1c8a6229/stats.txt
Get the list of finished jobs
wsclient -m finished -e 'http://example.com:8091/'
283f7841-9934-4636-ac32-e20b7b635113 ERROR
69009fc2-8ee0-4362-a27d-7ae7e66f824a FINISHED
Delete a job
wsclient -m delete -e 'http://example.com:8091/' -j 0354f5c6-af97-4916-9d00-315d1c8a6229
manual/soapif.txt · Last modified: 2013/01/22 10:49 by a.visegradi