.\" 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 "ECACCESS-ASSOCIATION-GET 1p"
.TH ECACCESS-ASSOCIATION-GET 1p "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"
ecaccess\-association\-get \- Get the Association Descriptive File
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBecaccess-association-get \-version|\-help|\-manual\fR
.PP
\&\fBecaccess-association-get [\-debug] [\-gateway\fR \fIname\fR\fB] [\-template]\fR \fIassociation-name\fR \fItarget-file\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Get the Descriptive File for the ECtrans Association specified by the \fIassociation-name\fR parameter.
Once downloaded, the \fItarget-file\fR can be modified and processed through the \fBecaccess-association-put\fR
command.
.PP
When using the \fB\-template\fR option, if the Association already exists in the ECaccess Gateway Database,
then the command return with an error. In order to create a new Association similar to an existing one
the \fBecaccess-association-get\fR command can be used to retrieve the Descriptive File of the existing
Association. The file can then be updated and pushed to the ECaccess Gateway Database with the
\&\fBecaccess-association-put\fR command.
.PP
An ECtrans Association Descriptive File contains parameters for ECtrans of the general form \f(CW$name\fR='value'.
Each ECtrans Association has their own Descriptive File, and parameters in any given Descriptive File will be
passed to the ECtrans container whenever a transfer is requested to the corresponding Association.
.PP
Blank lines and leading spaces and tabs are ignored when they do not occur in single quoted strings. Lines
whose first non-space character is a pound-sign (#) are comments, and are ignored. Note that comments are
not allowed on the same line as parameters and don't persist when the Descriptive File is retrieved from
the Gateway (they might however be used when Descriptive Files are archived on your system).
.PP
The parameters are the following:
.IP "\fIactive\fR" 8
.IX Item "active"
This is a boolean which indicate if the Association can be used by ECtrans or not (e.g. 'yes' or 'no'). You might
want to deactivate an Association but still keep it in the ECaccess Gateway Database for later.
.IP "\fIcomment\fR" 8
.IX Item "comment"
This is a comment about your Association (e.g. 'Access to the archive system').
.IP "\fIgrantedUserList\fR" 8
.IX Item "grantedUserList"
This is the list of \s-1ECMWF\s0 user identifiers which are allowed (other that you) to use this Association. Multiple users
should be separated by a column (e.g. 'abc,def,ghi').
.IP "\fIdirectory\fR" 8
.IX Item "directory"
This is the directory where to download/upload the files from/to (e.g. '/tmp/data').
.IP "\fIhostName\fR" 8
.IX Item "hostName"
This is the name of the host to connect to (e.g. 'hostname.example.ms').
.IP "\fIlogin\fR" 8
.IX Item "login"
This is the login to use to connect to the host specified in the \fIhostName\fR parameter (e.g. 'anonymous').
.IP "\fIprotocol\fR" 8
.IX Item "protocol"
This is the protocol ECtrans will use to connect to the host specified in the \fIhostName\fR parameter. The list of available
protocols for a Gateway can be displayed with the \fBecaccess-protocol-list\fR command (e.g. 'genericFtp').
.IP "\fIdata\fR" 8
.IX Item "data"
This parameter can be split over multiple lines and contains various options for the \fIprotocol\fR which have been selected
for the Association (these options are passed verbatim to the Module which implement the \fIprotocol\fR). In order to get the
list of available options for a protocol please use the command \fBecaccess-association-protocol\fR with the name of the \fBprotocol\fR.
The availabe options depends of the version of the ECaccess Gateway which is used to host the Association so it might be
that some options are available for some Gateways and not available for others. An unknown option will be silently ignored
by ECtrans. The format of an option is {protocol\-shortname}.{option}={value} (e.g. ftp.port=\*(L"21\*(R" would set the port option
of the genericFtp module to \*(L"21\*(R"). An example of this parameter is given in the \s-1EXAMPLES\s0 section below.
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
.IP "\fIassociation-name\fR" 8
.IX Item "association-name"
The name of the Association to retrieve the corresponding Descriptive File.
.IP "\fItarget-file\fR" 8
.IX Item "target-file"
The name of the file where to download the Descriptive File.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-gateway\fR \fIname\fR" 8
.IX Item "-gateway name"
This is the name of the ECaccess Gateway where the Association is installed.
It is by default the Gateway you are connected to. In order to get the name
of your current Gateway you can use the \fBecaccess-gateway-name\fR command. When
using the commands at \s-1ECMWF\s0 the default Gateway is always \*(L"ecaccess.ecmwf.int\*(R".
.IP "\fB\-template\fR" 8
.IX Item "-template"
Allow creating a new Association Descriptive File for the \fBecaccess-association-put\fR command.
If the Association already exists then the command fails.
.IP "\fB\-version\fR" 8
.IX Item "-version"
Display version number and exits.
.IP "\fB\-help\fR" 8
.IX Item "-help"
Print a brief help message and exits.
.IP "\fB\-manual\fR" 8
.IX Item "-manual"
Prints the manual page and exits.
.IP "\fB\-retry\fR \fIcount\fR" 8
.IX Item "-retry count"
Number of \s-1SSL\s0 connection retries per 5s to \s-1ECMWF.\s0 This parameter only apply to the
initial \s-1SSL\s0 connection initiated by the command to the \s-1ECMWF\s0 server. It does not
apply to all the subsequent requests made afteward as it is mainly targeting errors
that can happen from time to time during the \s-1SSL\s0 handshake. Default is no retry.
.IP "\fB\-debug\fR" 8
.IX Item "-debug"
Display the \s-1SOAP\s0 and \s-1SSL\s0 messages exchanged.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\fBecaccess-association-get \-template\fR \fItest\fR \fI./test\fR
.PP
Create a new Association Descriptive File for an Association named \fItest\fR and store it in your
current directory (file \fI./test\fR). The file can then be edited and updated accordingly to your
requirements.
.PP
\&\fBecaccess-association-put \-password\fR \fI./test\fR
.PP
Create the Association with the previously updated \fI./test\fR Association Descriptive File.
.PP
\&\fBecaccess-association-get \-gateway\fR \fIecaccess.ecmwf.int\fR \fIginko\fR \fI./ginko\fR
.PP
Get the Descriptive File for the existing \fIginko\fR Association on the \fIecaccess.ecmwf.int\fR
Gateway.
.PP
\&\fBecaccess-association-put \-gateway\fR \fIecaccess.ecmwf.int\fR \fI./ginko\fR
.PP
Push the Association back (once updated).
.PP
This is an example of an Association Descriptive File:
.PP
.Vb 10
\&  ##############################################################
\&  # Main Parameters
\&  ##############################################################
\&  $active=\*(Aqyes\*(Aq
\&  $comment=\*(AqAccess to the archive system\*(Aq
\&  $grantedUserList=\*(Aqabc,def,jhi\*(Aq
\&  $directory=\*(Aq/tmp/data\*(Aq
\&  $hostName=\*(Aqhostname.example.ms\*(Aq
\&  $login=\*(Aqanonymous\*(Aq
\&  $protocol=\*(AqgenericFtp\*(Aq
\&
\&  ##############################################################
\&  # Data
\&  ##############################################################
\&  $data=\*(Aq
\&  ftp.mkdirs="yes"
\&  ftp.passive="no"
\&  ftp.port="21"
\&  ftp.suffix=".tmp"
\&  ftp.usetmp="yes"\*(Aq
.Ve
.PP
Please note the multiple lines in the \fIdata\fR parameter.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBecaccess-association-delete\fR, \fBecaccess-association-list\fR, \fBecaccess-association-protocol\fR,
\&\fBecaccess-association-put\fR and \fBecaccess\fR.