If you are NOT using the ECMWF Gateways (ecaccess or msaccess) then please refer to the previous user guide for accessing the ECaccess Web Services V1. This documentation is about ECaccess Web Services V2 which is currently only available at ECMWF. At heart, ECaccess Web Services APIs use JSON as a data format and HTTPS as a protocol for data transmission. ECMWF has released a full-featured Perl client library to make interacting with ECaccess Web Services APIs easier. However, if Perl is not available on your platform or you are not able to install additional software then CURL is an alternative to interact with the ECaccess Web Services. CURL is a command-line application for performing requests using a variety of protocols including HTTPS, required to interact with the APIs at a low level. In this document we assume that you are already familiar with the ECaccess Services. If this is not the case then please have refer to other sections in this User Guide to learn about the concepts behind Gateways, Operations, Associations, Protocols, Files, Jobs, Events, Queues and Transfers.

Obtaining CURL

CURL is commonly available on a default install of many UNIX/Linux platforms. Try typing curl in your favourite shell to see if it is installed and in your PATH. If you don't have the tool installed, visit the download page on the CURL website to obtain the official source or a user-contributed binary package: http://curl.haxx.se/download.html

Note that the command-line tool uses the libcurl library, which may be offered as a separate download package, so, if you're not compiling from the source, be sure to download a binary package instead of a libcurl package. The SSL-enabled packages are required to use the ECaccess Web Services.

Environment

You need to ensure the following environment variables are set with the correct values:

> export ECACCESS_URLV2="https://ecaccess.ecmwf.int/ecaccess/v2"
> export ECACCESS_OPTS="-w \ncode=%{http_code}\n -k"

If you are using the RMDCN network to access ECMWF then please use msaccess.ecmwf.int instead of ecaccess.ecmwf.int. The curl options used are the following:

-wdisplay the http code on stdout (\ncode=%{http_code}\n)
-kdisable certificate checking

If you don't want or can't setup these environment parameters then just replace $ECACCESS_URLV2 and $ECACCESS_OPTS by their contents in the rest of the document.

Input/output

For each ECaccess Service available an example is given in the rest of this document with the CURL syntax to use, the list of parameters and the expected output.

Most of the services will return a JSON message. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.

Each JSON message should include a field "success" set to "yes". If an error occurs then this field is set to "no" and an "error" field gives the error message returned by the service.

For more information concerning JSON see http://www.json.org/

There are a few occasions when an error will not be indicated via a JSON message but with an http error code (e.g. when a binary stream is expected rather than a message):

401 Unauthorizedauthentication error when trying to download a new certificate
400 Bad requesterror when downloading a data file or job output/input file.
403 Forbiddenaccess is only allowed through a secure connection (https).
412 Precondition failedmissing mandatory URL parameter or unknown JSON parameter.
404 Not Foundthe requested service does not exists.

On a successful request the http status code returned by the server is the following:

200 OKthe request has produced a JSON message.

If you get an HTML document then that could be a problem with a proxy. In this case the HTML message should give you an indication of what the problem is.

Authentication

Certificates

Accessing the ECaccess Web Services API requires a valid certificate. Certificates can be created with the CURL command

> curl $ECACCESS_OPTS -c $HOME/.eccert.txt \
  "$ECACCESS_URLV2/cookie?ecuser=uid&passcode=XXXXXXXX"

which (if successful) returns

{
  "success" : "yes"
}
code=200

In this request just replace uid by your ECMWF identifier and XXXXXXXX by your PASSCODE obtained from your security token. It generates a certificate in ".eccert.txt" in your user's home directory. The ECaccess Certificate is valid for one week and should be renewed after expiration.

Tokens

Requests to the ECaccess Web Services are performed by adding an HTTP header to the request which contains an Authentication token. Authentication tokens are generated for each session and require a valid certificate. To get an Authentication token (e.g. LOGIN) use the command

> curl $ECACCESS_OPTS -b $HOME/.eccert.txt "$ECACCESS_URLV2/cookie/token"

which returns

{
  "token" : "ahs4w294",
  "success" : "yes"
}
code=200

Your new token is ahs4w294. You can now use this token for several requests to the ECaccess Web Services. Once you have finished with your token and don't plan to use it any more then you can release it (e.g. LOGOUT) with

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" "$ECACCESS_URLV2/token"

which returns

{
  "success" : "yes"
}
code=200

The Authentication token is now released and can't be used for any subsequent requests.

Cosinfo

Cosinfo provides ECMWF computer operations system information, such as scheduled or unscheduled downtime of servers, applications or hardware. The command

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/cosinfo"

returns e.g.

{
  "cosinfo" :
"********************************************************************\n*
*\n*
*\n*  Welcome to AIX Version 5.3! 
*\n*
*\n*
*\n*  Please see the README file in /usr/lpp/bos for information pertinent to    
*\n*  this release of the AIX Operating System. 
*\n*
*\n*
*\n********************************************************************\n\n\nDear
colleagues,\n\n\nThe following system sessions have been announced for\n\n
Wednesday 5th of October 2012\n\n\n08:00-10:00 UTC   DHS system
session\nImpact:   MARS and ECFS may be affected\n\n\n13:00-14:30 UTC
ECPDS system session\nImpact:   none\n\n\nHave a nice day,\nSylvia for
Calldesk\n\n\n\nTo reread the message please use: more /etc/motd or cat
/etc/motd\n\n===================================================================\n",
  "success" : "yes"
}
code=200

Gateways

To display the name of the Gateway you are connected to (please note this command does not need a token), command

> curl $ECACCESS_OPTS "$ECACCESS_URLV2/gateway/name"

returns

{
  "gateway" : "ecaccess.ecmwf.int",
  "success" : "yes"
}
code=200

To display the connection status of the ECaccess Gateway you are connected to (please note this command does not need a token),

> curl $ECACCESS_OPTS "$ECACCESS_URLV2/gateway/connected"

returns

{
  "connected" : true,
  "success" : "yes"
}
code=200

All ECaccess Gateways can be listed with

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/gateways"

which returns

{
  "gateways" : [ {
    "name" : "forte.meteo.fr",
    "comment" : "HP-UX B.11.00 - Java HotSpot(TM) Server VM 1.4.2
    1.4.2.08-050401-19:15-PA_RISC1.1 PA1.1 mixed mode Hewlett-Packard
    Company",
    "version" : "3.1.0_2007011001",
    "active" : false,
    "lastReport" : "Aug 22 13:15"
  }, {
    "name" : "ecaccess.knmi.nl",
    "comment" : "Linux 2.6.18-92.1.13.el5 - Java HotSpot(TM) Server VM
    11.0-b16 mixed mode Sun Microsystems Inc.",
    "version" : "3.3.0_2009021801",
    "active" : true,
    "lastReport" : "Sep 27 15:46"
  (...)
  } ],
  "success" : "yes"
}
code=200

When a gateway name is specified in the URL then the details for this Gateway only are displayed:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/gateways/forte.meteo.fr"

returns

{
  "gateway" : {
    "name" : "forte.meteo.fr",
    "comment" : "HP-UX B.11.00 - Java HotSpot(TM) Server VM 1.4.2
    1.4.2.08-050401-19:15-PA_RISC1.1 PA1.1 mixed mode Hewlett-Packard
    Company",
    "version" : "3.1.0_2007011001",
    "active" : false,
    "lastReport" : "Aug 22 13:15"
  },
  "success" : "yes"
}
code=200

Operations

To list all the ECaccess Operations/Services available with the current token use

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/operations"

which returns

{
  "operations" : [ {
    "name" : "submitJob",
    "comment" : "job submission",
    "duration" : "168h",
    "startDate" : "Sep 30 11:40",
    "validity" : 7,
    "endDate" : "Oct 07 11:40",
    "standard" : "168h"
  }, {
    "name" : "getJobList",
    "comment" : "job list",
    "duration" : "168h",
    "startDate" : "Sep 30 11:40",
    "validity" : 7,
    "endDate" : "Oct 07 11:40",
    "standard" : "168h"
  (...)
  } ],
  "success" : "yes"
}
code=200

If you specify an operation name in the URL then the information for this operation only will be displayed, e.g.

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/operations/submitJob"

returns

{
  "operation" : {
    "name" : "submitJob",
    "comment" : "job submission",
    "duration" : "168h",
    "startDate" : "Sep 30 11:40",
    "validity" : 7,
    "endDate" : "Oct 07 11:40",
    "standard" : "168h"
  },
  "success" : "yes"
}
code=200

Associations

All your ECtrans Associations for a Gateway (e.g. the "ecaccess.ecmwf.int" Gateway) can be listed with

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \ 
  "$ECACCESS_URLV2/associations/ecaccess.ecmwf.int"

which returns

{
  "associations" : [ {
    "name" : "test2",
    "protocol" : "",
    "hostName" : "193.40.11.180",
    "owner" : "uid",
    "comment" : "test association",
    "active" : false,
    "data" : "(...)",
    "login" : "test",
    "directory" : "test",
    "grantedUserList" : ""
  (...)
  } ],
  "success" : "yes"
}
code=200

When an association name is specified in the URL then the details for this Association only are displayed (e.g. test2):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \ 
  "$ECACCESS_URLV2/associations/ecaccess.ecmwf.int/test2"

returns

{
  "association" : {
    "name" : "test2",
    "protocol" : "",
    "hostName" : "193.40.11.180",
    "owner" : "uid",
    "comment" : "test association",
    "active" : false,
    "data" : "(...)",
    "login" : "test",
    "directory" : "test",
    "grantedUserList" : ""
  },
  "success" : "yes"
}
code=200

To update or create an ECtrans Association (e.g. if the name test3 exists then the Association is updated otherwise it is created) use

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" -H "Content-Type: application/json" \ 
-d '{ \
  "name":"test3", \
  "protocol":"genericFtp", \
  "hostName":"ecaccess", \
  "comment":"test association", \
  "active":true, \
  "login":"uid",\
  "password" : "********" \ 
}' $ECACCESS_URLV2/associations/ecaccess.ecmwf.int

which returns

{
  "success" : "yes"
}
code=200

To delete an ECtrans Association (once deleted the Association can not be retrieved and its associated History is removed from the ECaccess Gateway Database) use

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/associations/ecaccess.ecmwf.int/test3"

which returns

{
  "success" : "yes"
}
code=200

The table below lists all parameters for the ECtrans Association. For additional information please see the ecaccess-association-put manpage.

TypeNameComment
Stringname 
Booleanactivedefault FALSE
Stringcomment 
StringgrantedUserListmultiple users separated by a ','
Stringdata 
Stringdirectory 
StringhostName 
Stringlogin 
Stringpassword 
Stringprotocol 

Protocols

To list all the ECtrans Protocols supported by a Gateway (e.g. ecaccess.ecmwf.int) command

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/protocols/ecaccess.ecmwf.int"

returns

{
  "protocols" : [ {
    "name" : "genericFile",
    "value" :
    "${ecmwf.dir}/gateway/ectrans/$msuser[name]/$msuser[dir]$target",
    "comment" : "Save files on the gateway",
    "active" : true,
    "archive" : "${ecmwf.dir}/gateway/lib/ectrans",
    "module" : "file",
    "activeModule" : true
  (...)
  } ],
  "success" : "yes"
}
code=200

When a protocol-name is specified in the URL then the details for this Protocol only are displayed (.e.g. genericFtp):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \ 
  "$ECACCESS_URLV2/protocols/ecaccess.ecmwf.int/genericFtp"

returns

{
  "protocol" : {
    "name" : "genericFtp",
    "value" :
    "$msuser[login]:$msuser[passwd]@$msuser[host]/$msuser[dir]$target",
    "comment" : "Generic FTP access from the gateway",
    "active" : true,
    "archive" : "${ecmwf.dir}/gateway/lib/ectrans",
    "module" : "ftp",
    "activeModule" : true
  },
  "success" : "yes"
}
code=200

Files

The ECaccess files are in the form [domain:][/user-id/]path. Please refer to File Management for more information on the ECaccess File System. To download a source ecaccess file, e.g. c2a:/tmp/test.tar.gz), use

> curl $ECACCESS_OPTS -H "Token: ahs4w294" -o test.tar.gz \
 "$ECACCESS_URLV2/file?source=c2a:/tmp/test.tar.gz&offset=0"

The file will be downloaded as ./test.tar.gz To upload a file (e.g. test.tar.gz):

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" \
 -T test.tar.gz "$ECACCESS_URLV2/file?target=test.tar.gz&offset=0&umask=777"

The file will be uploaded as test.tar.gz on ecgate. To delete an ecaccess-file (.e.g. test.tar.gz) use

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" \ 
  "$ECACCESS_URLV2/file?source=test.tar.gz"

returns

{
  "success" : "yes"
}
code=200

To change the file mode of an ecaccess-file, .e.g. set the mode of test.tar.gz to 640,

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/chmod?source=test.tar.gz&mode=640"

returns

{
  "success" : "yes"
}
code=200

To create a new directory (e.g. c2a:/tmp/TESTDIR):

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/mkdir?directory=c2a:/tmp/TESTDIR"

returns

{
  "success" : "yes"
}
code=200

To delete a directory (e.g. c2a:/tmp/TESTDIR):

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" \
   "$ECACCESS_URLV2/rmdir?directory=c2a:/tmp/TESTDIR"

returns

{
  "success" : "yes"
}
code=200

To get the last modified date and time of an ecaccess-file (e.g. README):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \ 
  "$ECACCESS_URLV2/mdtm?source=README"

returns

{
  "mdtm" : "Sep 14 14:14",
  "success" : "yes"
}
code=200

To get the size of an ecaccess-file (e.g. README):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/size?source=README"

returns

{
  "success" : "yes",
  "size" : 5205
}
code=200

To copy an ecaccess-file to another ecaccess-file. In this case the original ecaccess-file is not deleted (e.g. README -> README2)

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" \
 "$ECACCESS_URLV2/copy?source=README&target=README2&erase=false"

returns

{
  "success" : "yes"
}
code=200

Copy and delete the original ecaccess-file (e.g. README->README2):

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" \
 "$ECACCESS_URLV2/copy?source=README&target=README2&erase=true"

returns

{
  "success" : "yes"
}
code=200

Move an ecaccess-file (e.g. README -> README2)

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/move?source=README&target=README2"

returns

{
  "success" : "yes"
}
code=200

Get a list of files and directories (e.g. in scratch:dir):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/dir?path=scratch:dir"

returns

{
  "dir" : [ {
    "name" : "Le Sapin de Noel.doc",
    "permissions" : "-rw-r--r--",
    "size" : "24064",
    "path" : "",
    "comment" : "",
    "time" : "Dec 14  2009",
    "domain" : "scratch:",
    "user" : "uid",
    "dir" : false,
    "group" : "systems",
    "link" : ""
  (...)
  } ],
  "success" : "yes"
}
code=200

Create a temporary file:

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" \
  "$ECACCESS_URLV2/mktmp"

returns

{
  "mktmp" : "tmp:roqZya",
  "success" : "yes"
}
code=200

This temporary file "tmp:roqZya" can be used to upload a temporary file (e.g. when submitting the input file for an ECaccess Job).

Jobs

To submit a new ECaccess Job, e.g. myjob.ksh which is a shell script without Loadleveler directives located in the ECMWF home directory:

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" \
   -H "Content-Type: application/json" \
   -d '{ \
         "queueName":"ecgate", \
         "inputFile":"home:myjob.ksh", \
         "containsDirectives":false \
       }' \
 "$ECACCESS_URLV2/jobs"

returns

{
  "jobId" : "2368129",
  "success" : "yes"
}
code=200

The table below lists all Job Request parameters. For additional information please see the ecaccess-job-submit manpage.

TypeNameComment
StringscheduledDatein the form 'yyyy-MM-dd HH:mm'
StringuserMailAddress 
BooleansendMailOnStart 
BooleansendMailOnSuccess 
BooleansendMailOnFailure 
BooleansendMailOnRetry 
BooleancontainsDirectivesdefault TRUE
StringqueueNamedefault is ecgate
Stringname 
StringtransferGatewayNamedefault is current Gateway
StringtransferRemoteLocationin the format association-name[@protocol]
StringtransferOutputFile 
StringtransferErrorFile 
StringtransferInputFile 
BooleantransferKeepInSpooldefault FALSE
StringeventIdslist separated by ';' or ','
BooleanrenewSubscriptiondefault FALSE
BooleanerrorToOutputdefault FALSE
StringmanPageContent 
IntegerlifeTimein days
IntegerretryCountdefault 0
IntegerretryFrequencyin seconds
StringinputFilefile on ECMWF file system

To list all your ECaccess Jobs:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs"

returns

{
  "jobs" : [ {
    "name" : "",
    "hostName" : "ecgate.ecmwf.int",
    "comment" : "",
    "status" : "DONE",
    "jobId" : "2368129",
    "tryCount" : 1,
    "tryDone" : 1,
    "scheduledDate" : "Sep 30 13:51",
    "eventIds" : [ ],
    "queueName" : "ecgate",
    "errorFileSize" : 122,
    "expirationDate" : "-",
    "inputFileSize" : 43,
    "outputFileSize" : 1451,
    "schedulerJobId" : "ecga00.ecmwf.int.1956629",
    "schedulerName" : "LoadLeveler"
  (...)
  } ],
  "success" : "yes"
}
code=200

To get an ECaccess Job Output (e.g. 2368129):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129/output"

will return the Job Output. To get an ECaccess Job Error (e.g. 2368129):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129/error"

will return the Job Error. To get an ECaccess Job Input (e.g. 2368129):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129/input"

will return the Job Input. To get the details for a specific ECaccess Job (e.g. 2368129) just add the ECaccess Job Identifier in the URL:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129"

returns

{
  "job" : {
    "name" : "",
    "hostName" : "ecgate.ecmwf.int",
    "comment" : "",
    "status" : "DONE",
    "jobId" : "2368129",
    "tryCount" : 1,
    "tryDone" : 1,
    "scheduledDate" : "Sep 30 13:51",
    "eventIds" : [ ],
    "queueName" : "ecgate",
    "errorFileSize" : 122,
    "expirationDate" : "Oct 07 13:51",
    "inputFileSize" : 43,
    "outputFileSize" : 1451,
    "schedulerJobId" : "ecga00.ecmwf.int.1956629",
    "schedulerName" : "LoadLeveler"
  },
  "success" : "yes"
}
code=200

To restart an existing ECaccess Job (e.g. 2368129):

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129"

returns

{
  "success" : "yes"
}
code=200

To delete an ECaccess Job (e.g. 2368129):

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" "$ECACCESS_URLV2/jobs/2368129"

returns

{
  "success" : "yes"
}
code=200

Events

To list all the ECaccess Events which are available to your ECMWF user identifier

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/events"

returns

{
  "events" : [ {
    "name" : "an00h000",
    "comment" : "At this stage, the analysis at 00UTC is complete.",
    "metadata" : "",
    "eventId" : "167",
    "title" : "",
    "isPublic" : true,
    "ownerUserId" : "emos",
    "notifyUserList" : "",
    "subscribeUserList" : ""
  (...)
  } ],
  "success" : "yes"
}
code=200

To get the details for a specific event, e.g. an00h000, just add the event name or identifier (eventId) in the URL, e.g.

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/events/an00h000"

returns

{
  "event" : {
    "name" : "an00h000",
    "comment" : "At this stage, the analysis at 00UTC is complete.",
    "metadata" : "",
    "eventId" : "167",
    "title" : "",
    "isPublic" : true,
    "ownerUserId" : "emos",
    "notifyUserList" : "",
    "subscribeUserList" : ""
  },
  "success" : "yes"
}
code=200

To create an ECaccess Event:

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" -H "Content-Type: application/json" \ 
 -d '{ \ 
   "name":"myEvent", \ 
   "comment":"This is for test", \ 
   "isPublic":false}' \ 
 "$ECACCESS_URLV2/events"

returns

{
  "eventId" : "807",
  "success" : "yes"
}
code=200

All parameters for the Event Request are listed in table 12. Table 12: Parameters for an Event Request. For additional information please see the ecaccess-event-create manpage.

TypeNameComment
Stringname 
Stringcomment 
BooleanisPublicdefault FALSE
Booleanoverwritedefault FALSE
Stringtitle 
Stringmetadata 

To grant an ECaccess Event (e.g. 807):

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" -H "Content-Type: application/json" \ 
  -d '{"subscribe":true,"notify":true,"userList":"uid,abc"}' \
  "$ECACCESS_URLV2/events/807/grant"

returns

{
  "success" : "yes"
}
code=200

All parameters for the Grant Event Request are listed in table 13. Table 13: Parameters for a Grant Event Request. For additional information please see the ecaccess-event-grant manpage.

TypeNameComment
Booleansubscribedefault FALSE
Booleannotifydefault FALSE
StringuserListmultiple users separated by a ','

To trigger an ECaccess Event (e.g. 807):

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" -H "Content-Type: application/json" \
 -d '{"env":"TEST=TEST","seq":"1"}' "$ECACCESS_URLV2/events/807/send"

returns

{
  "count" : 0,
  "success" : "yes"
}
code=200

All parameters for the Send Event Request are listed in table 14. Table 14: Parameters for the Send Event Request. For additional information please see the ecaccess-event-send manpage.

TypeNameComment
Stringenvmultiple variables separated by a ';'
Stringdelayspecified in [w]eeks, [d]ays, [h]ours, [m]inutes or [s]econds (e.g. 1w or 2d)
Stringatin the format 'yyyy-MM-dd HH:mm'
Integerseq 

To clear an ECaccess Event (e.g. 807):

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" "$ECACCESS_URLV2/events/807/clear"

returns

{
  "success" : "yes"
}
code=200

To delete an ECaccess Event (e.g. 807):

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" "$ECACCESS_URLV2/events/807"

returns

{
  "success" : "yes"
}
code=200

Queues

To list the available ECaccess Queues:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/queues"

returns

{
  "queues" : [ {
    "hostName" : "ecgate.ecmwf.int",
    "comment" : "submission on ecgate",
    "active" : true,
    "queueName" : "ecgate",
    "schedulerName" : "LoadLeveler",
    "numberOfJobsInDoneState" : 7203,
    "numberOfJobsInExecState" : 13,
    "numberOfJobsInInitState" : 1275,
    "numberOfJobsInStopState" : 84,
    "numberOfJobsInWaitState" : 1
  (...)
  } ],
  "success" : "yes"
}
code=200

To get the details for a specific ECaccess Queue (e.g. ecgate) just add the queue name in the URL:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/queues/ecgate"

returns

{
  "queue" : [ {
    "name" : "pvwave",
    "comment" : "For jobs using PV-Wave - restricted access"
  }, {
    "name" : "timecrit",
    "comment" : "Suitable for time critical jobs - restricted access"
  (...)
  } ],
  "success" : "yes"
}
code=200

Transfers

In order to list all your ECtrans Transfers in the ECtrans Spool:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/transfers"

returns

{
  "transfers" : [ ],
  "success" : "yes"
}
code=200

To get the details for a specific ECtrans Transfer (e.g. 32595048) just add the Transfer Identifier in the URL:

> curl $ECACCESS_OPTS -H "Token: ahs4w294" "$ECACCESS_URLV2/transfers/32595048"

returns

{
  "transfer" : {
    "hostName" : "ecaccess.ecmwf.int",
    "comment" : "",
    "sourceFileName" : "/home/group/uid/ecmwf.properties",
    "status" : "STOP",
    "keepInSpool" : true,
    "fileSize" : 5205,
    "tryCount" : 145,
    "tryDone" : 1,
    "scheduledDate" : "Sep 30 14:26",
    "targetFileName" : "ecmwf.properties",
    "ownerUserId" : "test",
    "lastErrorMessage" : "user not granted by uid for test",
    "transferId" : "32595048"
  },
  "success" : "yes"
}
code=200

In order to request a new ECtrans transfer:

> curl $ECACCESS_OPTS -X POST -H "Token: ahs4w294" -H "Content-Type: application/json" \
 -d '{ \ 
   "remoteLocation":"test", \
   "sourceFileName":"ecmwf.properties", \
   "gatewayName":"ecaccess.ecmwf.int", \
   "keepInSpool":true}' \ 
 "$ECACCESS_URLV2/transfers"

returns

{
  "transferId" : "32595048",
  "success" : "yes"
}
code=200

All parameters for the ECtrans Request are listed in table 15. Table 15: Parameters for the ECtrans Request. For additional information please see the ecaccess-ectrans-request manpage.

TypeNameComment
StringgatewayNamedefault current Gateway
StringremoteLocationin the format association-name[@protocol]
StringsourceFileName 
StringtargetFileName 
IntegerretryCount 
IntegerretryFrequencyfrequency of retries in seconds (default: 600 seconds)
StringmaximumDuratione.g. 10m or 1h, <0 to deactivate (default 12h)
StringminimumDuratione.g. 30s or 10m, <0 to deactivate (default 10m)
LongminimumRatebytes/s (default 10240)
Integerpriority 
StringlifeTimein [w]eeks, [d]ays, [h]ours, [m]inutes or [s]econds (e.g. 1w or 2d)
BooleandeleteSourcedefault FALSE
BooleankeepInSpooldefault FALSE
StringuserMailAddress 
BooleansendMailOnSuccess 
BooleansendMailOnFailure 
BooleansendMailOnRetry 
StringifTargetFileExists'reject', 'append', 'resume' or 'overwrite'

To restart an ECtrans Transfer:

> curl $ECACCESS_OPTS -X PUT -H "Token: ahs4w294" -H "Content-Type: application/json" \
 -d '{ \ 
   "remoteLocation":"test2", \
   "sourceFileName":"ecmwf.properties", \
   "gatewayName":"ecaccess.ecmwf.int", \
   "keepInSpool":true}' \
 "$ECACCESS_URLV2/transfers/32595048"

returns

{
  "success" : "yes"
}
code=200

For a list of parameters for the restart of an ECtrans Request see table 15. To delete an ECtrans Transfer:

> curl $ECACCESS_OPTS -X DELETE -H "Token: ahs4w294" "$ECACCESS_URLV2/transfers/32595048"

returns

{
  "success" : "yes"
}
code=200