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:
| -w | display the http code on stdout (\ncode=%{http_code}\n) |
| -k | disable 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 Unauthorized | authentication error when trying to download a new certificate |
| 400 Bad request | error when downloading a data file or job output/input file. |
| 403 Forbidden | access is only allowed through a secure connection (https). |
| 412 Precondition failed | missing mandatory URL parameter or unknown JSON parameter. |
| 404 Not Found | the requested service does not exists. |
On a successful request the http status code returned by the server is the following:
| 200 OK | the 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.
| Type | Name | Comment |
| String | name | |
| Boolean | active | default FALSE |
| String | comment | |
| String | grantedUserList | multiple users separated by a ',' |
| String | data | |
| String | directory | |
| String | hostName | |
| String | login | |
| String | password | |
| String | protocol |
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.
| Type | Name | Comment |
| String | scheduledDate | in the form 'yyyy-MM-dd HH:mm' |
| String | userMailAddress | |
| Boolean | sendMailOnStart | |
| Boolean | sendMailOnSuccess | |
| Boolean | sendMailOnFailure | |
| Boolean | sendMailOnRetry | |
| Boolean | containsDirectives | default TRUE |
| String | queueName | default is ecgate |
| String | name | |
| String | transferGatewayName | default is current Gateway |
| String | transferRemoteLocation | in the format association-name[@protocol] |
| String | transferOutputFile | |
| String | transferErrorFile | |
| String | transferInputFile | |
| Boolean | transferKeepInSpool | default FALSE |
| String | eventIds | list separated by ';' or ',' |
| Boolean | renewSubscription | default FALSE |
| Boolean | errorToOutput | default FALSE |
| String | manPageContent | |
| Integer | lifeTime | in days |
| Integer | retryCount | default 0 |
| Integer | retryFrequency | in seconds |
| String | inputFile | file 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.
| Type | Name | Comment |
| String | name | |
| String | comment | |
| Boolean | isPublic | default FALSE |
| Boolean | overwrite | default FALSE |
| String | title | |
| String | metadata |
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.
| Type | Name | Comment |
| Boolean | subscribe | default FALSE |
| Boolean | notify | default FALSE |
| String | userList | multiple 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.
| Type | Name | Comment |
| String | env | multiple variables separated by a ';' |
| String | delay | specified in [w]eeks, [d]ays, [h]ours, [m]inutes or [s]econds (e.g. 1w or 2d) |
| String | at | in the format 'yyyy-MM-dd HH:mm' |
| Integer | seq |
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.
| Type | Name | Comment |
| String | gatewayName | default current Gateway |
| String | remoteLocation | in the format association-name[@protocol] |
| String | sourceFileName | |
| String | targetFileName | |
| Integer | retryCount | |
| Integer | retryFrequency | frequency of retries in seconds (default: 600 seconds) |
| String | maximumDuration | e.g. 10m or 1h, <0 to deactivate (default 12h) |
| String | minimumDuration | e.g. 30s or 10m, <0 to deactivate (default 10m) |
| Long | minimumRate | bytes/s (default 10240) |
| Integer | priority | |
| String | lifeTime | in [w]eeks, [d]ays, [h]ours, [m]inutes or [s]econds (e.g. 1w or 2d) |
| Boolean | deleteSource | default FALSE |
| Boolean | keepInSpool | default FALSE |
| String | userMailAddress | |
| Boolean | sendMailOnSuccess | |
| Boolean | sendMailOnFailure | |
| Boolean | sendMailOnRetry | |
| String | ifTargetFileExists | '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