Sidebar
Command disabled: revisions
manual:soapif
Table of Contents
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
Print the version of the wsclient command
wsclient -V
Print the version of the remote web-service
wsclient -m version -e 'http://example.com:8091/'
3G Bridge 1.9
Print the available algorithm for grid 'test'
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
Page Tools
