SSH, Kerberized SSH2, Telnet, SCP, FTP, SFTP, and Session-based CLI adapters permit a connection to persist for multiple requests across processes. A connection is named when established, and subsequent requests can then specify this named connection. The connection is available to a request for reuse till it either expires based on the value specified in the
<connection-ttl> element, or is terminated with a
The named connection is defined in an adapter request in the
<target> block by using a
<connection> block that contains a
<name> tag and a
<terminate-on-exit> tag. The
<name> tag is required. The
<terminate-on-exit> tag is optional, and its default value is false, maintaining the connection. The SSH, SCP, FTP, and SFTP adapters also contain a
<connection-ttl> element that specifies the time (in seconds) for which a named connection should persist.
The named connection is an optional function. If there is no
<connection> block, the connection opens and closes in the request and must be reopened for each subsequent request of that target.
Because named connections are used across processes, concurrent jobs can access a named connection concurrently and can disrupt an existing connection by a call from another process. Also, named connections cannot be shared across multiple peers.
The following figure shows an XML sample of a named connection used in conjunction with a dynamic target. This connection terminates on completion of the request.
XML sample of a named connection used in conjunction with a dynamic target
... <target> <host>sample.target1.com</host> <port>23</port> <user\-name>user1</user\-name> <password>pass1</password> <prompt>user1$</prompt> <connection> <name>target1_connection</name> <connection-ttl>xx</connection-ttl> <terminate-on-exit>true</terminate-on-exit> </connection> </target> ...
When using a named connection with a dynamic target, you must define the dynamic target completely in each request. You cannot reference it as a
name attribute with the
<target> in subsequent requests. Only targets defined in the adapter configuration can be referenced with a
name attribute in an adapter request.
The following figure shows an XML sample of a named connection used in conjunction with a target name reference from the adapter configuration. In the absence of the
<terminate-on-exit> element, this connection remains open on completion of the request.
XML sample of a named connection in conjunction with a target name reference
... <target name="target2"> <connection> <name>target2_connection</name> </connection> </target> ...
Each subsequent request that uses a named connection is configured in the same manner, with either a complete dynamic target or a target name reference to the adapter configuration that contains a
<connection> block. The connection is reused if open, or reestablished if it has been closed.