1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
|
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../../displayToc.js"></script>
<script language="JavaScript" src="../../../tocParas.js"></script>
<script language="JavaScript" src="../../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../../scineplex.css">
<title>ECMWF::ECaccess - Perl extension to access the ECMWF ECaccess Web Services</title>
<link rel="stylesheet" href="../../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<!-- INDEX BEGIN -->
<div name="index">
<script>writelinks('__top__',3);</script>
<h1><a>ECMWF::ECaccess - Perl extension to access the ECMWF ECaccess Web Services</a></h1>
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#what_are_the_ecaccess_web_services">WHAT ARE THE ECACCESS WEB SERVICES?</a></li>
<ul>
<li><a href="#gateways_requests">Gateways Requests</a></li>
<li><a href="#certificates_and_tokens_requests">Certificates and Tokens Requests</a></li>
<li><a href="#files_requests">FILEs Requests</a></li>
<li><a href="#jobs_requests">JOBs Requests</a></li>
<li><a href="#events_requests">Events Requests</a></li>
<li><a href="#ectrans_associations_requests">ECtrans Associations Requests</a></li>
<li><a href="#ectrans_transfers_requests">ECtrans Transfers Requests</a></li>
<li><a href="#ios_requests__on_files_and_jobs_transfers_">IOs Requests (on FILEs and JOBs transfers)</a></li>
<li><a href="#cosinfo_request">CosInfo Request</a></li>
</ul>
<li><a href="#how_to_use_it">HOW TO USE IT?</a></li>
<ul>
<li><a href="#ecaccess_authentication">ECaccess Authentication</a></li>
<li><a href="#ecaccess_token">ECaccess Token</a></li>
<li><a href="#control_channel">Control Channel</a></li>
<li><a href="#data_channel">Data Channel</a></li>
<li><a href="#upload_download_files">Upload/Download FILEs</a></li>
<li><a href="#release_token">Release Token</a></li>
<li><a href="#ecaccess_file_system">ECaccess File System</a></li>
</ul>
<li><a href="#where_can_i_find_examples">WHERE CAN I FIND EXAMPLES?</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#copyright_and_license">COPYRIGHT AND LICENSE</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>ECMWF::ECaccess - Perl extension to access the ECMWF ECaccess Web Services (or ECaccess API)</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
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</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>ECMWF::ECaccess is a Perl module which provides access to the ECMWF ECaccess
Web Services (or ECaccess API).</p>
<p>
</p>
<hr />
<h1><a name="what_are_the_ecaccess_web_services">WHAT ARE THE ECACCESS WEB SERVICES?</a></h1>
<p>The SOAP ECaccess API was created for developers and researchers interested in using ECMWF facilities in their applications.
Developers write software programs that connect remotely to the SOAP ECaccess Service. Communication is performed via SOAP,
an XML-based mechanism for exchanging typed information.</p>
<p>Developers can issue requests to the following SOAP ECaccess Methods:</p>
<p>
</p>
<h2><a name="gateways_requests">Gateways Requests</a></h2>
<pre>
<span class="variable">String</span> <span class="variable">getGatewayName</span><span class="operator">();</span>
<span class="variable">Boolean</span> <span class="variable">gatewayIsConnected</span><span class="operator">();</span>
<span class="variable">GatewayResponse</span> <span class="variable">getGateway</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">gateway</span><span class="operator">);</span>
<span class="variable">GatewayResponse</span><span class="operator">[]</span> <span class="variable">getGatewayList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="certificates_and_tokens_requests">Certificates and Tokens Requests</a></h2>
<pre>
<span class="variable">byte</span><span class="operator">[]</span> <span class="variable">createCertificate</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">ecuser</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">passcode</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getTokenFromCertificate</span><span class="operator">(</span><span class="variable">byte</span><span class="operator">[]</span> <span class="variable">certificate</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getTokenFromUserPasscode</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">ecuser</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">passcode</span><span class="operator">);</span>
<span class="variable">OperationResponse</span><span class="operator">[]</span> <span class="variable">getOperationList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
<span class="variable">OperationResponse</span> <span class="variable">getOperation</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">operationName</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">releaseToken</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="files_requests">FILEs Requests</a></h2>
<pre>
<span class="variable">Boolean</span> <span class="variable">changeFileMode</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="variable">mode</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">path</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">deleteFile</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">,</span> <span class="variable">Boolean</span> <span class="variable">force</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">makeDirectory</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">dir</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">removeDirectory</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">dir</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getFileLastModified</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">);</span>
<span class="variable">Long</span> <span class="variable">getFileSize</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">copyFile</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">target</span><span class="operator">,</span> <span class="variable">Boolean</span> <span class="variable">erase</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">moveFile</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">target</span><span class="operator">);</span>
<span class="variable">DirResponse</span><span class="operator">[]</span> <span class="variable">getDirList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">path</span><span class="operator">,</span> <span class="variable">Boolean</span> <span class="variable">dir</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getInputFileHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">source</span><span class="operator">,</span> <span class="variable">Long</span> <span class="variable">offset</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getOutputFileHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">target</span><span class="operator">,</span> <span class="variable">Long</span> <span class="variable">offset</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="keyword">umask</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getTemporaryFile</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="jobs_requests">JOBs Requests</a></h2>
<pre>
<span class="variable">String</span> <span class="variable">getJobOutputHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobid</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getJobInputHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobid</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">getJobErrorHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobid</span><span class="operator">);</span>
<span class="variable">JobResponse</span> <span class="variable">getJob</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobid</span><span class="operator">);</span>
<span class="variable">JobResponse</span><span class="operator">[]</span> <span class="variable">getJobList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">deleteJob</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobid</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">submitJob</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">JobRequest</span> <span class="variable">request</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">restartJob</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">jobId</span><span class="operator">);</span>
<span class="variable">QueueResponse</span><span class="operator">[]</span> <span class="variable">getQueueList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
<span class="variable">QueueDetailResponse</span><span class="operator">[]</span> <span class="variable">getQueueDetail</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">queueName</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="events_requests">Events Requests</a></h2>
<pre>
<span class="variable">EventResponse</span><span class="operator">[]</span> <span class="variable">getEventList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
<span class="variable">EventResponse</span> <span class="variable">getEvent</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">eventId</span><span class="operator">);</span>
<span class="variable">Integer</span> <span class="variable">sendEvent</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">EventRequest</span> <span class="variable">request</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="ectrans_associations_requests">ECtrans Associations Requests</a></h2>
<pre>
<span class="variable">AssociationResponse</span><span class="operator">[]</span> <span class="variable">getAssociationList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span><span class="variable">String</span> <span class="variable">gateway</span><span class="operator">);</span>
<span class="variable">AssociationResponse</span> <span class="variable">getAssociation</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">gateway</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">name</span><span class="operator">,</span> <span class="variable">Boolean</span> <span class="variable">template</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">putAssociation</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">gateway</span><span class="operator">,</span> <span class="variable">AssociationRequest</span> <span class="variable">association</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">deleteAssociation</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">gateway</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">name</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="ectrans_transfers_requests">ECtrans Transfers Requests</a></h2>
<pre>
<span class="variable">TransferResponse</span><span class="operator">[]</span> <span class="variable">getTransferList</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
<span class="variable">TransferResponse</span> <span class="variable">getTransfer</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">transferId</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">deleteTransfer</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">transferId</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">requestTransfer</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">TransferRequest</span> <span class="variable">request</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">restartTransfer</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">,</span> <span class="variable">TransferRequest</span> <span class="variable">request</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">transferId</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="ios_requests__on_files_and_jobs_transfers_">IOs Requests (on FILEs and JOBs transfers)</a></h2>
<pre>
<span class="variable">Boolean</span> <span class="variable">writeStringHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">string</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">writeBytesHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">byte</span><span class="operator">[]</span> <span class="variable">bytes</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">readStringHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="variable">size</span><span class="operator">);</span>
<span class="variable">byte</span><span class="operator">[]</span> <span class="variable">readBytesHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="variable">size</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">closeHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="cosinfo_request">CosInfo Request</a></h2>
<pre>
<span class="variable">String</span> <span class="variable">getCosInfo</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">token</span><span class="operator">);</span>
</pre>
<p>The following link provides the WSDL file you can use to generate code if your environment supports it:</p>
<pre>
<a href="http://ecaccess.ecmwf.int/axis2/services/ECaccessService?wsdl">http://ecaccess.ecmwf.int/axis2/services/ECaccessService?wsdl</a></pre>
<p>
</p>
<hr />
<h1><a name="how_to_use_it">HOW TO USE IT?</a></h1>
<p>
</p>
<h2><a name="ecaccess_authentication">ECaccess Authentication</a></h2>
<p>Using the ECMWF::ECaccess Module requires a valid certificate. Certificates
can be created with the "ecaccess-certificate-create" command from an ECMWF
user identifier and a PASSCODE (using a security token), it generates a
certificate in ".eccert.crt" in the user's home directory.</p>
<p>You need to ensure the following environment parameters are set with
the correct values:</p>
<pre>
http_ecaccess=gateway.meteo.ms:9080
https_ecaccess=gateway.meteo.ms:9443</pre>
<p>(e.g. if your local ECaccess Gateways name is "gateway.meteo.ms" and
you are using the default ECaccess http/s ports 9080/9443)</p>
<p>The default values are pointing to the ecaccess.ecmwf.int server.</p>
<p>If you access your ECaccess Gateway through a proxy then you should
also set the following:</p>
<pre>
http_proxy=<a href="http://proxy.meteo.ms:port">http://proxy.meteo.ms:port</a>
https_proxy=https://proxy.meteo.ms:port</pre>
<p>
</p>
<h2><a name="ecaccess_token">ECaccess Token</a></h2>
<p>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).</p>
<p>When you obtain an ECacces Token for a user, you must use that ECaccess Token
for all future interactions with the API on behalf of the user.</p>
<p>In order to obtain an ECaccess Token you must use the following code:</p>
<pre>
<span class="keyword">use</span> <span class="variable">ECMWF::ECaccess</span><span class="operator">;</span>
<span class="keyword">my</span> <span class="variable">$ecaccess</span> <span class="operator">=</span> <span class="variable">ECMWF::ECaccess</span><span class="operator">-></span><span class="variable">new</span><span class="operator">();</span> <span class="comment"># Create the ECaccess Controler</span>
<span class="keyword">my</span> <span class="variable">$token</span> <span class="operator">=</span> <span class="variable">$ecaccess</span><span class="operator">-></span><span class="variable">getToken</span><span class="operator">();</span> <span class="comment"># Get an ECaccess Token</span>
</pre>
<p>
</p>
<h2><a name="control_channel">Control Channel</a></h2>
<p>Once you have an ECaccess Token you must request a Control Channel to access
the API:</p>
<pre>
<span class="keyword">my</span> <span class="variable">$controlChannel</span> <span class="operator">=</span> <span class="variable">$ecaccess</span><span class="operator">-></span><span class="variable">getControlChannel</span><span class="operator">();</span> <span class="comment"># Get the Control Channel</span>
</pre>
<p>This Control Channel will allow you to call any method of the API. For example,
let's move a FILE from ECfs to the super-computer:</p>
<pre>
<span class="variable">controlChannel</span><span class="operator">-></span><span class="variable">moveFile</span><span class="operator">(</span><span class="variable">$token</span><span class="operator">,</span><span class="string">'ec:test/a.out'</span><span class="operator">,</span><span class="string">'c2a:/c2a/tmp/systems/syi/a.out'</span><span class="operator">);</span>
</pre>
<p>Or let's get the CosInfo from ECMWF:</p>
<pre>
<span class="keyword">print</span> <span class="variable">$controlChannel</span><span class="operator">-></span><span class="variable">getCosInfo</span><span class="operator">(</span><span class="variable">$token</span><span class="operator">)-></span><span class="variable">result</span><span class="operator">.</span><span class="string">"\n"</span><span class="operator">;</span>
</pre>
<p>
</p>
<h2><a name="data_channel">Data Channel</a></h2>
<p>In order to Download/Upload Data to/from ECMWF you are required to use a
Data Channel:</p>
<pre>
<span class="keyword">my</span> <span class="variable">$dataChannel</span> <span class="operator">=</span> <span class="variable">$ecaccess</span><span class="operator">-></span><span class="variable">getDataChannel</span><span class="operator">();</span> <span class="comment"># Get the Data Channel</span>
</pre>
<p>The methods available on the Data Channel are the following:</p>
<pre>
<span class="variable">Boolean</span> <span class="variable">writeStringHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">String</span> <span class="variable">string</span><span class="operator">);</span>
<span class="variable">Boolean</span> <span class="variable">writeBytesHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">byte</span><span class="operator">[]</span> <span class="variable">bytes</span><span class="operator">);</span>
<span class="variable">String</span> <span class="variable">readStringHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="variable">size</span><span class="operator">);</span>
<span class="variable">byte</span><span class="operator">[]</span> <span class="variable">readBytesHandle</span><span class="operator">(</span><span class="variable">String</span> <span class="variable">handle</span><span class="operator">,</span> <span class="variable">Integer</span> <span class="variable">size</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="upload_download_files">Upload/Download FILEs</a></h2>
<p>Suppose you want to Upload a text FILE you would do the following:</p>
<pre>
<span class="variable">$handle</span> <span class="operator">=</span> <span class="variable">$controlChannel</span><span class="operator">-></span><span class="variable">getOutputFileHandle</span><span class="operator">(</span><span class="variable">$token</span><span class="operator">,</span><span class="string">'home:/test.txt'</span><span class="operator">,</span><span class="number">0</span><span class="operator">,</span><span class="number">600</span><span class="operator">)-></span><span class="variable">result</span><span class="operator">;</span>
<span class="keyword">open</span> <span class="variable">FILE</span><span class="operator">,</span> <span class="string">'test.txt'</span> <span class="keyword">or</span> <span class="keyword">die</span> <span class="variable">$!</span><span class="operator">;</span>
<span class="keyword">while</span> <span class="operator">(</span><span class="keyword">read</span><span class="operator">(</span><span class="variable">FILE</span><span class="operator">,</span> <span class="variable">$data</span><span class="operator">,</span> <span class="number">524288</span><span class="operator">)</span> <span class="operator">></span> <span class="number">0</span><span class="operator">)</span> <span class="operator">{</span>
<span class="variable">$dataChannel</span><span class="operator">-></span><span class="variable">writeStringHandle</span><span class="operator">(</span><span class="variable">$handle</span><span class="operator">,</span><span class="variable">$data</span><span class="operator">);</span>
<span class="operator">}</span>
<span class="variable">$controlChannel</span><span class="operator">-></span><span class="variable">closeHandle</span><span class="operator">(</span><span class="variable">$handle</span><span class="operator">);</span>
<span class="keyword">close</span> <span class="variable">FILE</span><span class="operator">;</span>
</pre>
<p>In order to Download a binary FILE you would do the following:</p>
<pre>
<span class="variable">$handle</span> <span class="operator">=</span> <span class="variable">$controlChannel</span><span class="operator">-></span><span class="variable">getInputFileHandle</span><span class="operator">(</span><span class="variable">$token</span><span class="operator">,</span><span class="string">'home:/a.out'</span><span class="operator">,</span><span class="number">0</span><span class="operator">)-></span><span class="variable">result</span><span class="operator">;</span>
<span class="keyword">open</span> <span class="variable">FILE</span><span class="operator">,</span> <span class="string">">"</span><span class="operator">,</span> <span class="variable">$target</span> <span class="keyword">or</span> <span class="keyword">die</span> <span class="variable">$!</span><span class="operator">;</span>
<span class="keyword">binmode</span> <span class="variable">FILE</span><span class="operator">;</span>
<span class="keyword">while</span> <span class="operator">(</span><span class="keyword">length</span><span class="operator">(</span><span class="variable">$data</span> <span class="operator">=</span> <span class="variable">decode_base64</span><span class="operator">(</span><span class="variable">$dataChannel</span><span class="operator">-></span><span class="variable">readBytesHandle</span><span class="operator">(</span><span class="variable">$handle</span><span class="operator">,</span> <span class="number">524288</span><span class="operator">)-></span><span class="variable">result</span><span class="operator">))</span> <span class="operator">></span> <span class="number">0</span><span class="operator">)</span> <span class="operator">{</span>
<span class="keyword">print</span> <span class="variable">FILE</span> <span class="variable">$data</span><span class="operator">;</span>
<span class="operator">}</span>
<span class="variable">$controlChannel</span><span class="operator">-></span><span class="variable">closeHandle</span><span class="operator">(</span><span class="variable">$handle</span><span class="operator">);</span>
<span class="keyword">close</span> <span class="variable">FILE</span><span class="operator">;</span>
</pre>
<p>In both cases you get a FILE 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.</p>
<p>
</p>
<h2><a name="release_token">Release Token</a></h2>
<p>Once you have finished with your session you must release your token using the following
code:</p>
<pre>
<span class="variable">$ecaccess</span><span class="operator">-></span><span class="variable">releaseToken</span><span class="operator">(</span><span class="variable">$token</span><span class="operator">);</span> <span class="comment"># Logout</span>
</pre>
<p>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).</p>
<p>
</p>
<h2><a name="ecaccess_file_system">ECaccess File System</a></h2>
<p>When accessing FILEs at ECMWF the following domains are available to the user logged-in:</p>
<pre>
<span class="variable">HOME</span><span class="operator">:</span> <span class="variable">the</span> <span class="variable">$HOME</span> <span class="variable">directory</span> <span class="operator">(</span><span class="variable">home</span><span class="operator">:)</span>
<span class="variable">SCRATCH</span><span class="operator">:</span> <span class="variable">the</span> <span class="variable">$SCRATCH</span> <span class="variable">directory</span> <span class="operator">(</span><span class="variable">scratch</span><span class="operator">:)</span>
<span class="variable">ECFS</span><span class="operator">:</span> <span class="variable">the</span> <span class="variable">ECFS</span> <span class="variable">directory</span> <span class="operator">(</span><span class="variable">ec</span><span class="operator">:)</span>
<span class="variable">ECTMP</span><span class="operator">:</span> <span class="variable">the</span> <span class="variable">ECTMP</span> <span class="variable">directory</span> <span class="operator">(</span><span class="variable">ectmp</span><span class="operator">:)</span>
<span class="variable">HOST</span><span class="operator">:</span> <span class="variable">any</span> <span class="variable">server</span> <span class="variable">at</span> <span class="variable">ECMWF</span> <span class="operator">(</span><span class="operator">{</span><span class="variable">host</span><span class="operator">-</span><span class="variable">name</span><span class="operator">}</span><span class="operator">:)</span>
</pre>
<p>The format of the path is the following: [domain:][/user-id/]path</p>
<p>If no user-id is specified then the current user-id is selected by default. The user-id
parameter is not valid with the HOST domain.</p>
<p>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 HOME directory of the
current user.</p>
<p>A few examples:</p>
<pre>
"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</pre>
<p>
</p>
<hr />
<h1><a name="where_can_i_find_examples">WHERE CAN I FIND EXAMPLES?</a></h1>
<p>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 API and show the options available as well as
the format of the messages which are return by the server.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>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:</p>
<pre>
<a href="http://www.soaplite.com/">http://www.soaplite.com/</a></pre>
<p>The Server Side is based on Apache Axis2 (part of the ECaccess Gateway).
Documentation is also available at the following place:</p>
<pre>
<a href="http://ws.apache.org/axis2/">http://ws.apache.org/axis2/</a></pre>
<p>If you have questions please contact: <a href="mailto:ecaccess@ecmwf.int">ecaccess@ecmwf.int</a></p>
<p>To download the latest ECMWF::ECaccess Perl Module please go to:</p>
<pre>
<a href="http://www.ecmwf.int/services/ecaccess/download/">http://www.ecmwf.int/services/ecaccess/download/</a></pre>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Laurent Gougeon, <<a href="mailto:Laurent.Gougeon@ecmwf.int">Laurent.Gougeon@ecmwf.int</a>></p>
<p>
</p>
<hr />
<h1><a name="copyright_and_license">COPYRIGHT AND LICENSE</a></h1>
<p>Copyright (C) 2010 by ECMWF (<a href="mailto:Laurent.Gougeon@ecmwf.int">Laurent.Gougeon@ecmwf.int</a>)</p>
<p>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.</p>
</body>
</html>
|
