File transfer jobs
A file transfer job runs programs to transfer files to and from a server reachable using FTP, SSH, or other protocols
A description of the job properties and valid values are detailed in the context-sensitive help in the Dynamic Workload Console by clicking the question mark (?) icon in the top-right corner of the properties pane.Attribute | Description and value | Required |
---|---|---|
application name | filetransfer | ✓ |
File transfer type (upload or download) | An upload sends a file to a server. A download downloads a file from a server.
Enclose all the file transfer attributes between
|
✓ |
Permissions (Octal Notation) | If downloading, specify file permissions for the user on the local system. File permissions are expressed as octal notation. | |
Delete source files after transfer | If uploading, specify if source files must be deleted after transfer. | |
deleteAfterDownload | Set to true to delete the transferred file from the server after the download. The default is false. | |
server | The address of the file transfer server (and the port number, if other than
the standard port, when you choose FTP as protocol). If you want to specify a port number different
from the default one, use the following syntax: server_name:port_number |
✓ |
localfile and remotefile |
|
✓ |
localCredentials and remoteCredentials | The names and passwords of the authorized users on the local and remote
systems. As an alternative to hard-coding actual values, you can parametrize in one of the following ways:
Tip: The password of the remote user is not required if a keystore file
path and password are specified when using the SSH protocol. |
✓ |
keystore file path | The fully qualified path of the keystore file containing the private key used to make the connection. A keystore is a database of keys. Private keys in a keystore have a certificate chain associated with them which authenticates the corresponding public key on the remote server. A keystore also contains certificates from trusted entities. Applicable to SSH protocol only. | |
keystore password | The password that protects the private key and is required to make the connection. This attribute is required only if you specify a keystore file path. If the keystore file path and keystore password combination fail to make a connection, then an attempt is made using the userName and password that correspond to the user authorized to start a connection on the remote computer. | ✓ |
protocol | Can be:
|
|
transferMode | Can be binary (the default) or
ascii . |
|
appendText | Specify this attribute and set it to true to append the
data contained in the file being transferred to the end of the file on the destination system, if it
already exists. If the file does not already exist, it is created. This attribute applies to file
transfers of type download and when transferMode is set to ascii . Omit this
attribute if you do not want to append the data to an existing file. |
|
extracommands | Specify a SIte subcommand to send information that is used by the remote host to provide services specific to that host system. For example, you can specify a subcommand to define space allocation. Valid for an upload file transfer using the FTP protocol when the target workstation is a z/OS system. By default, this attribute is not specified. | |
remoteCodepage | The codepage used on the remote workstation. If you want
to use a custom code page, define the remoteCodepage parameter as
follows: where
CUSTOM_CP is the code page defined by the user.For example, to use
the tcpip.ftpd.ftpxlbin.frence3 custom code page, define the
remoteCodepage parameter as
follows:
|
Required if you specify localCodepage |
localCodepage | The codepage used on the local workstation. | Required if you specify remoteCodepage |
Timeout | Specifies the number of seconds to be used for the file transfer operation. The default value is 60 seconds. | |
portsRange | When the active mode is enabled, the portsRange section
restricts the port numbers sent by the FTP PORT command. This option accommodates highly restrictive
firewall rules. The portsRange section defines the port range to use on the client
side of TCP data connections. If you do not specify the portsRange section, the
operating system determines the port numbers to be used.The portsRange parameter
requires the following parameters:
For example, to limit the port range to use on the client side
between port 1035 and port 1040, specify the
following:
|
|
passiveMode | Specifies whether the server is passive or active in establishing connections
for data transfers. If you set this option to If you set this option to NO . |
<jsdl:application name="filetransfer">
<jsdlfiletransfer:filetransfer>
<jsdlfiletransfer:downloadInfo>
<jsdlfiletransfer:server>FTP_SERVER</jsdlfiletransfer:server>
<jsdlfiletransfer:localfile>LOCAL_FILE</jsdlfiletransfer:localfile>
<jsdlfiletransfer:remotefile>REMOTE_FILE</jsdlfiletransfer:remotefile>
<jsdlfiletransfer:remoteCredentials>
<jsdl:userName>USERNAME</jsdl:userName>
<jsdl:password>PASSWORD</jsdl:password>
</jsdlfiletransfer:remoteCredentials>
<jsdlfiletransfer:protocol>PROTOCOL</jsdlfiletransfer:protocol>
<jsdlfiletransfer:transferMode>ASCII_BINARY</jsdlfiletransfer:transferMode>
<jsdlfiletransfer:appendText>TRUE_FALSE</jsdlfiletransfer:appendText>
<jsdlfiletransfer:extracommands>SITE_SUBCOMMAND</jsdlfiletransfer:extracommands>
<jsdlfiletransfer:codepageConversion>
<jsdlfiletransfer:remoteCodepage>RM_CP</jsdlfiletransfer:remoteCodepage>
<jsdlfiletransfer:localCodepage>LC_CP</jsdlfiletransfer:localCodepage>
</jsdlfiletransfer:codepageConversion>
<jsdlfiletransfer:timeout>CONNECTION_TIMEOUT</jsdlfiletransfer:timeout>
<jsdlfiletransfer:portsRange>
<jsdlfiletransfer:min>MIN_PORT</jsdlfiletransfer:min>
<jsdlfiletransfer:max>MAX_PORT</jsdlfiletransfer:max>
</jsdlfiletransfer:portsRange>
<jsdlfiletransfer:passiveMode>YES_NO</jsdlfiletransfer:passiveMode>
</jsdlfiletransfer:downloadInfo>
</jsdlfiletransfer:filetransfer>
</jsdl:application>
The
following example shows a generalized task that downloads a file from a remote workstation with
address 10.0.0.8. The file is then deleted from the remote
workstation after the
download:$JOBS
AGENT#FILE_TRANSFER
TASK
<?xml version="1.0" encoding="UTF-8"?>
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdlfiletransfer"
name="FILETRANSFER">
<jsdl:application name="filetransfer">
<jsdlfiletransfer:filetransfer>
<jsdlfiletransfer:downloadInfo>
<jsdlfiletransfer:server>10.0.0.8</jsdlfiletransfer:server>
<jsdlfiletransfer:localfile>c:\MyTextFile.txt</jsdlfiletransfer:localfile>
<jsdlfiletransfer:remotefile>./MyRemoteFile.txt</jsdlfiletransfer:remotefile>
<jsdlfiletransfer:localCredentials>
<jsdl:userName>${agent:locluser}</jsdl:userName>
<jsdl:password>${agent:password.${agent:locluser}}</jsdl:password>1
</jsdlfiletransfer:localCredentials>
<jsdlfiletransfer:remoteCredentials>
<jsdl:userName>remuser</jsdl:userName>
<jsdl:password>${password:remuser}</jsdl:password>2
</jsdlfiletransfer:remoteCredentials>
<jsdlfiletransfer:protocol>FTP</jsdlfiletransfer:protocol>
<jsdlfiletransfer:transferMode>ascii</jsdlfiletransfer:transferMode>
<jsdlfiletransfer:codepageConversion>
<jsdlfiletransfer:remoteCodepage>IBM-280</jsdlfiletransfer:remoteCodepage>
<jsdlfiletransfer:localCodepage>ISO8859-1</jsdlfiletransfer:localCodepage>
</jsdlfiletransfer:codepageConversion>
<jsdlfiletransfer:deleteAfterDownload>true</jsdlfiletransfer:deleteAfterDownload>
</jsdlfiletransfer:downloadInfo>
</jsdlfiletransfer:filetransfer>
</jsdl:application>
</jsdl:jobDefinition>
- The local user name was defined on the agent that runs the job with a variable named
locluser
through theparam
utility command. So, the value defined forlocluser
will be retrieved at runtime from the variables file located in the agent. Likewise, the password for the value represented bylocluser
was defined on the agent with theparam
command and will be resolved at runtime from the local variables file. - The remote user name was defined with the
composer user
command and is stored in the database together with its password as user nameremuser
. The password forremuser
will be retrieved from the database at runtime.
<?xml version="1.0" encoding="UTF-8"?>
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/
jsdlfiletransfer" name="FTPES_DOWNLOAD_TEXT">
<jsdl:application name="filetransfer">
<jsdlfiletransfer:filetransfer>
<jsdlfiletransfer:downloadInfo>
<jsdlfiletransfer:server>myServerFtp</jsdlfiletransfer:server>
<jsdlfiletransfer:localfile>d:\MyLocalFile.txt</jsdlfiletransfer:localfile>
<jsdlfiletransfer:remotefile>/tmp/MyRemoteFile.txt</jsdlfiletransfer:remotefile>
<jsdlfiletransfer:remoteCredentials>
<jsdl:userName>myUser</jsdl:userName>
<jsdl:password>myPassword</jsdl:password>
</jsdlfiletransfer:remoteCredentials>
<jsdlfiletransfer:protocol>FTPES</jsdlfiletransfer:protocol>
<jsdlfiletransfer:transferMode>ascii</jsdlfiletransfer:transferMode>
<jsdlfiletransfer:appendText>true</jsdlfiletransfer:appendText>
<jsdlfiletransfer:timeout>10</jsdlfiletransfer:timeout>
<jsdlfiletransfer:portsRange>
<jsdlfiletransfer:min>1035</jsdlfiletransfer:min>
<jsdlfiletransfer:max>1038</jsdlfiletransfer:max>
</jsdlfiletransfer:portsRange>
</jsdlfiletransfer:downloadInfo>
</jsdlfiletransfer:filetransfer>
</jsdl:application>
</jsdl:jobDefinition>
The
following example shows a job definition to be used to transfer a text file using the SSH
protocol:<?xml version="1.0" encoding="UTF-8"?>
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/
jsdlfiletransfer" name="SSH_UPLOAD">
<jsdl:application name="filetransfer">
<jsdlfiletransfer:filetransfer>
<jsdlfiletransfer:uploadInfo>
<jsdlfiletransfer:server>myServer</jsdlfiletransfer:server>
<jsdlfiletransfer:localfile>d:\MyLocalFile.txt</jsdlfiletransfer:localfile>
<jsdlfiletransfer:remotefile>/tmp/MyRemoteFile.txt</jsdlfiletransfer:remotefile>
<jsdlfiletransfer:remoteCredentials>
<jsdl:userName>myUser</jsdl:userName>
<jsdl:password>myPassword</jsdl:password>
</jsdlfiletransfer:remoteCredentials>
<jsdlfiletransfer:protocol>SSH</jsdlfiletransfer:protocol>
<jsdlfiletransfer:transferMode>ascii</jsdlfiletransfer:transferMode>
</jsdlfiletransfer:uploadInfo>
</jsdlfiletransfer:filetransfer>
</jsdl:application>
</jsdl:jobDefinition>
The
following example shows a job definition to be used to transfer a text file using the WINDOWS
protocol:<?xml version="1.0" encoding="UTF-8"?>
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/
jsdlfiletransfer" name="WINDOWS_DOWNLOAD">
<jsdl:application name="filetransfer">
<jsdlfiletransfer:filetransfer>
<jsdlfiletransfer:downloadInfo>
<jsdlfiletransfer:server>myServer</jsdlfiletransfer:server>
<jsdlfiletransfer:localfile>d:\MyLocalFile.txt</jsdlfiletransfer:localfile>
<jsdlfiletransfer:remotefile>mySharedFolder\MyRemoteFile.txt
</jsdlfiletransfer:remotefile>
<jsdlfiletransfer:remoteCredentials>
<jsdl:userName>myUser</jsdl:userName>
<jsdl:password>myPassword</jsdl:password>
</jsdlfiletransfer:remoteCredentials>
<jsdlfiletransfer:protocol>WINDOWS</jsdlfiletransfer:protocol>
<jsdlfiletransfer:transferMode>ascii</jsdlfiletransfer:transferMode>
</jsdlfiletransfer: downloadInfo >
</jsdlfiletransfer:filetransfer>
</jsdl:application>
</jsdl:jobDefinition>
- RC=0
- File transfer completed successfully.
- RC=-1
- File transfer not performed. The job failed with the following error code:
Explanation: An error occurred during the file transfer operation.AWKFTE007E
Possible reasons: Remote file not found or permission denied.
- RC=-2
- File transfer not performed. The job failed with the following error code:
Explanation: Only for SSH or WINDOWS protocols. An error was returned while attempting to convert the code page.AWKFTE020E
Possible reasons: For SSH or WINDOWS protocols, the code page is automatically detected and converted. In this case, there is an error in the code page of the file to be transferred, which is not compliant with the code page of the local system.
- RC=-3
- File transfer not performed. The job failed with the following error code:
Explanation: An error occurred during the file transfer operation.WKFTE015E
Possible reasons: Local file not found.
- RC=-4
- File transfer performed with the default code page. The job failed with the following error
code:
Explanation: The specified code page conversion was not performed. The file transfer was performed with default code pages.AWKFTE023E
Possible reason: The specified code page is unavailable.
Scheduling and stopping a job in HCL Workload Automation
You schedule HCL Workload Automation file transfer jobs by defining them in job streams. Add the job to a job stream with all the necessary scheduling arguments and submit it.
You can submit jobs using the Dynamic Workload Console, Application Lab, or the conman command line.
After the submission, if the job that is running contains more files to transfer and the job is reported in EXEC status in HCL Workload Automation, you can stop it if necessary by using the kill command.
Restarting the job
If the HCL Workload Automation agent stops when you submit the file transfer job, or while the job is running, the job restarts automatically as soon as the agent restarts.
Job properties
You can see the job properties by running conman sj <File
transfer_job_name>;props
, where<File transfer_job_name> is
the file transfer job name.
Extra
Information
section of the output command, you see the following
properties:Extra Information
File.0.LocalFile = ./MyFile3.log
File.0.LocalUser = agtParis
File.0.Protocol = FTP
File.0.RemoteFile = /export/home/FileTransferRep/MyFile3.log
File.0.RemoteUser = ftpuser
File.0.Size = 983
File.0.TotalTransferTime = 0
File.1.LocalFile = ./MyFile.log
File.1.LocalUser = agtParis
File.1.Protocol = FTP
File.1.RemoteFile = /export/home/FileTransferRep/MyFile.log
File.1.RemoteUser = ftpuser
File.1.Size = 983
File.1.TotalTransferTime = 0
File.2.LocalFile = ./MyFile2.log
File.2.LocalUser = agtParis
File.2.Protocol = FTP
File.2.RemoteFile = /export/home/FileTransferRep/MyFile2.log
File.2.RemoteUser = ftpuser
File.2.Size = 983
File.2.TotalTransferTime = 0
File.3.LocalFile = ./MyFile1.log
File.3.LocalUser = agtParis
File.3.Protocol = FTP
File.3.RemoteFile = /export/home/FileTransferRep/MyFile1.log
File.3.RemoteUser = ftpuser
File.3.Size = 983
File.3.TotalTransferTime = 0
Number of transferred files = 4
where, for each trasferred
file, you have:- File.counter.LocalFile
- For the file number #, the name of the local file that you want to transfer.
- File.counter.LocalUser
- For the file number #, the user name for accessing the local workstation.
- File.counter.Protocol
- For the file number #, the protocol to be used for the file transfer.
- File.counter.RemoteFile
- For the file number #, the name of the remote file that you want to transfer.
- File.counter.RemoteUser
- For the file number #, the user name for accessing the remote workstation.
- File.counter.Size
- For the file number #, the size of the transferred file.
- File.counter.TotalTransferTime
- For the file number #, the total transfer time, in seconds.
- Number of transferred files
- The number of the files transferred with the job. You have only one value of this property for each job.
You can export the file transfer job properties
that you can see in the Extra Information
section,
to a successive job in the same job stream instance.
For more information about the list of job properties that you can export, see Properties for file transfer jobs.
See also
From the Dynamic Workload Console you can perform the same task as described in
For more information about how to create and edit scheduling objects, see