User Tools

Site Tools


Sidebar

Overview

Navigation

Scenarios

Components

Manuals

  • Basic components
  • Application support
  • Additional components
    • 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