.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ECMWF::ECaccess 3pm"
.TH ECMWF::ECaccess 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ECMWF::ECaccess \- Perl extension to access the ECMWF ECaccess Web Services (or ECaccess API)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\&  What are the ECaccess Web Services?
\&  How to use it?
\&    ECaccess Authentication
\&    ECaccess Token
\&    Control Channel
\&    Data Channel
\&    Upload/Download FILEs
\&    Release Token
\&    ECaccess File System
\&  Where can I find examples?
\&  See Also
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
ECMWF::ECaccess is a Perl module which provides access to the \s-1ECMWF\s0 ECaccess
Web Services (or ECaccess \s-1API\s0).
.SH "WHAT ARE THE ECACCESS WEB SERVICES?"
.IX Header "WHAT ARE THE ECACCESS WEB SERVICES?"
The \s-1SOAP\s0 ECaccess \s-1API\s0 was created for developers and researchers interested in using \s-1ECMWF\s0 facilities in their applications.
Developers write software programs that connect remotely to the \s-1SOAP\s0 ECaccess Service. Communication is performed via \s-1SOAP,\s0
an XML-based mechanism for exchanging typed information.
.PP
Developers can issue requests to the following \s-1SOAP\s0 ECaccess Methods:
.SS "Gateways Requests"
.IX Subsection "Gateways Requests"
.Vb 4
\&  String getGatewayName();
\&  Boolean gatewayIsConnected();
\&  GatewayResponse getGateway(String token, String gateway);
\&  GatewayResponse[] getGatewayList(String token);
.Ve
.SS "Certificates and Tokens Requests"
.IX Subsection "Certificates and Tokens Requests"
.Vb 6
\&  byte[] createCertificate(String ecuser, String passcode);
\&  String getTokenFromCertificate(byte[] certificate);
\&  String getTokenFromUserPasscode(String ecuser, String passcode);
\&  OperationResponse[] getOperationList(String token);
\&  OperationResponse getOperation(String token, String operationName);
\&  Boolean releaseToken(String token);
.Ve
.SS "FILEs Requests"
.IX Subsection "FILEs Requests"
.Vb 12
\&  Boolean changeFileMode(String token, Integer mode, String path);
\&  Boolean deleteFile(String token, String source, Boolean force);
\&  Boolean makeDirectory(String token, String dir);
\&  Boolean removeDirectory(String token, String dir);
\&  String getFileLastModified(String token, String source);
\&  Long getFileSize(String token, String source);
\&  Boolean copyFile(String token, String source, String target, Boolean erase);
\&  Boolean moveFile(String token, String source, String target);
\&  DirResponse[] getDirList(String token, String path, Boolean dir);
\&  String getInputFileHandle(String token, String source, Long offset);
\&  String getOutputFileHandle(String token, String target, Long offset, Integer umask);
\&  String getTemporaryFile(String token);
.Ve
.SS "JOBs Requests"
.IX Subsection "JOBs Requests"
.Vb 10
\&  String getJobOutputHandle(String token, String jobid);
\&  String getJobInputHandle(String token, String jobid);
\&  String getJobErrorHandle(String token, String jobid);
\&  JobResponse getJob(String token, String jobid);
\&  JobResponse[] getJobList(String token);
\&  Boolean deleteJob(String token, String jobid);
\&  String submitJob(String token, JobRequest request);
\&  String restartJob(String token, String jobId);
\&  QueueResponse[] getQueueList(String token);
\&  QueueDetailResponse[] getQueueDetail(String token, String queueName);
.Ve
.SS "Events Requests"
.IX Subsection "Events Requests"
.Vb 3
\&  EventResponse[] getEventList(String token);
\&  EventResponse getEvent(String token, String eventId);
\&  Integer sendEvent(String token, EventRequest request);
.Ve
.SS "ECtrans Associations Requests"
.IX Subsection "ECtrans Associations Requests"
.Vb 4
\&  AssociationResponse[] getAssociationList(String token,String gateway);
\&  AssociationResponse getAssociation(String token, String gateway, String name, Boolean template);
\&  Boolean putAssociation(String token, String gateway, AssociationRequest association);
\&  Boolean deleteAssociation(String token, String gateway, String name);
.Ve
.SS "ECtrans Transfers Requests"
.IX Subsection "ECtrans Transfers Requests"
.Vb 5
\&  TransferResponse[] getTransferList(String token);
\&  TransferResponse getTransfer(String token, String transferId);
\&  Boolean deleteTransfer(String token, String transferId);
\&  String requestTransfer(String token, TransferRequest request);
\&  Boolean restartTransfer(String token, TransferRequest request, String transferId);
.Ve
.SS "IOs Requests (on FILEs and JOBs transfers)"
.IX Subsection "IOs Requests (on FILEs and JOBs transfers)"
.Vb 5
\&  Boolean writeStringHandle(String handle, String string);
\&  Boolean writeBytesHandle(String handle, byte[] bytes);
\&  String readStringHandle(String handle, Integer size);
\&  byte[] readBytesHandle(String handle, Integer size);
\&  Boolean closeHandle(String handle);
.Ve
.SS "CosInfo Request"
.IX Subsection "CosInfo Request"
.Vb 1
\&  String getCosInfo(String token);
.Ve
.PP
The following link provides the \s-1WSDL\s0 file you can use to generate code if your environment supports it:
.PP
.Vb 1
\&  http://ecaccess.ecmwf.int/axis2/services/ECaccessService?wsdl
.Ve
.SH "HOW TO USE IT?"
.IX Header "HOW TO USE IT?"
.SS "ECaccess Authentication"
.IX Subsection "ECaccess Authentication"
Using the ECMWF::ECaccess Module requires a valid certificate. Certificates
can be created with the \*(L"ecaccess-certificate-create\*(R" command from an \s-1ECMWF\s0
user identifier and a \s-1PASSCODE\s0 (using a security token), it generates a
certificate in \*(L".eccert.crt\*(R" in the user's home directory.
.PP
You need to ensure the following environment parameters are set with
the correct values:
.PP
.Vb 2
\&  http_ecaccess=gateway.meteo.ms:9080
\&  https_ecaccess=gateway.meteo.ms:9443
.Ve
.PP
(e.g. if your local ECaccess Gateways name is \*(L"gateway.meteo.ms\*(R" and
you are using the default ECaccess http/s ports 9080/9443)
.PP
The default values are pointing to the ecaccess.ecmwf.int server.
.PP
If you access your ECaccess Gateway through a proxy then you should
also set the following:
.PP
.Vb 2
\&  http_proxy=http://proxy.meteo.ms:port
\&  https_proxy=https://proxy.meteo.ms:port
.Ve
.SS "ECaccess Token"
.IX Subsection "ECaccess Token"
You should generally request a token for the majority of methods available. For
example, if your application requires submitting a new job, you should usually
request a token from your certificate which grants access to the jobs management
methods (e.g. submitJob, getJobList, deleteJob or getJobResult).
.PP
When you obtain an ECacces Token for a user, you must use that ECaccess Token
for all future interactions with the \s-1API\s0 on behalf of the user.
.PP
In order to obtain an ECaccess Token you must use the following code:
.PP
.Vb 3
\&  use ECMWF::ECaccess;
\&  my $ecaccess = ECMWF::ECaccess\->new(); # Create the ECaccess Controler
\&  my $token = $ecaccess\->getToken(); # Get an ECaccess Token
.Ve
.SS "Control Channel"
.IX Subsection "Control Channel"
Once you have an ECaccess Token you must request a Control Channel to access
the \s-1API:\s0
.PP
.Vb 1
\&  my $controlChannel = $ecaccess\->getControlChannel(); # Get the Control Channel
.Ve
.PP
This Control Channel will allow you to call any method of the \s-1API.\s0 For example,
let's move a \s-1FILE\s0 from ECfs to the super-computer:
.PP
.Vb 1
\&  controlChannel\->moveFile($token,\*(Aqec:test/a.out\*(Aq,\*(Aqc2a:/c2a/tmp/systems/syi/a.out\*(Aq);
.Ve
.PP
Or let's get the CosInfo from \s-1ECMWF:\s0
.PP
.Vb 1
\&  print $controlChannel\->getCosInfo($token)\->result."\en";
.Ve
.SS "Data Channel"
.IX Subsection "Data Channel"
In order to Download/Upload Data to/from \s-1ECMWF\s0 you are required to use a
Data Channel:
.PP
.Vb 1
\&  my $dataChannel = $ecaccess\->getDataChannel(); # Get the Data Channel
.Ve
.PP
The methods available on the Data Channel are the following:
.PP
.Vb 4
\&  Boolean writeStringHandle(String handle, String string);
\&  Boolean writeBytesHandle(String handle, byte[] bytes);
\&  String readStringHandle(String handle, Integer size);
\&  byte[] readBytesHandle(String handle, Integer size);
.Ve
.SS "Upload/Download FILEs"
.IX Subsection "Upload/Download FILEs"
Suppose you want to Upload a text \s-1FILE\s0 you would do the following:
.PP
.Vb 7
\&  $handle = $controlChannel\->getOutputFileHandle($token,\*(Aqhome:/test.txt\*(Aq,0,600)\->result;
\&  open FILE, \*(Aqtest.txt\*(Aq or die $!;
\&  while (read(FILE, $data, 524288) > 0) {
\&    $dataChannel\->writeStringHandle($handle,$data);
\&  }
\&  $controlChannel\->closeHandle($handle);
\&  close FILE;
.Ve
.PP
In order to Download a binary \s-1FILE\s0 you would do the following:
.PP
.Vb 8
\&  $handle = $controlChannel\->getInputFileHandle($token,\*(Aqhome:/a.out\*(Aq,0)\->result;
\&  open FILE, ">", $target or die $!;
\&  binmode FILE;
\&  while (length($data = decode_base64($dataChannel\->readBytesHandle($handle, 524288)\->result)) > 0) {
\&    print FILE $data;
\&  }
\&  $controlChannel\->closeHandle($handle);
\&  close FILE;
.Ve
.PP
In both cases you get a \s-1FILE\s0 Handle through the Control Channel and then you
access the Data through the Data Channel. Once the Download/Upload is completed you
close the Handle with the 'closeHandle' method.
.SS "Release Token"
.IX Subsection "Release Token"
Once you have finished with your session you must release your token using the following
code:
.PP
.Vb 1
\&  $ecaccess\->releaseToken($token); # Logout
.Ve
.PP
Please note that you can also use the Control Channel to Download/Upload Data if
you require a secure connection for Data Transfers (https vs. http).
.SS "ECaccess File System"
.IX Subsection "ECaccess File System"
When accessing FILEs at \s-1ECMWF\s0 the following domains are available to the user logged-in:
.PP
.Vb 5
\&  HOME: the $HOME directory (home:)
\&  SCRATCH: the $SCRATCH directory (scratch:)
\&  ECFS: the ECFS directory (ec:)
\&  ECTMP: the ECTMP directory (ectmp:)
\&  HOST: any server at ECMWF ({host\-name}:)
.Ve
.PP
The format of the path is the following: [domain:][/user\-id/]path
.PP
If no user-id is specified then the current user-id is selected by default. The user-id
parameter is not valid with the \s-1HOST\s0 domain.
.PP
If no domain is specified then an absolute path will translate to an absolute path on the
ecgate server and a relative path will translate to a path in the \s-1HOME\s0 directory of the
current user.
.PP
A few examples:
.PP
.Vb 7
\&  "bin/a.out"                           a.out file in the $HOME/bin directory of the current user
\&  "home:bin/a.out"                      a.out file in the $HOME/bin directory of the current user
\&  "/tmp/a.out"                          a.out file in the /tmp directory on ecgate
\&  "home:/syi/bin/a.out"                 a.out file in the $HOME/bin directory of user syi
\&  "ec:bin/a.out"                        a.out file in the ECFS bin directory of the current user
\&  "ec:/syi/bin/a.out"                   a.out file in the ECFS bin directory of user syi
\&  "c2a:/c2a/tmp/systems/syi/a.out"      a.out file in the /c2a/tmp/systems/syi/ directory of c2a
.Ve
.SH "WHERE CAN I FIND EXAMPLES?"
.IX Header "WHERE CAN I FIND EXAMPLES?"
The scripts which are provided along with this Module are good examples of
what can be achieved with the ECMWF::ECacces Module. They use all the methods
available through the ECaccess \s-1API\s0 and show the options available as well as
the format of the messages which are return by the server.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The ECMWF::ECaccess Module is based on the SOAP-Lite Module and therefore
you might be interested in looking at the documentation related to this
Module:
.PP
.Vb 1
\&  http://www.soaplite.com/
.Ve
.PP
The Server Side is based on Apache Axis2 (part of the ECaccess Gateway).
Documentation is also available at the following place:
.PP
.Vb 1
\&  http://ws.apache.org/axis2/
.Ve
.PP
If you have questions please contact: ecaccess@ecmwf.int
.PP
To download the latest ECMWF::ECaccess Perl Module please go to:
.PP
.Vb 1
\&  http://www.ecmwf.int/services/ecaccess/download/
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Laurent Gougeon, <Laurent.Gougeon@ecmwf.int>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2010 by \s-1ECMWF\s0 (Laurent.Gougeon@ecmwf.int)
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.