Syntax diagram for file transfer job types

Purpose

If you set JOBTYPE to (/file transfer), you can choose between the following transfer types for transferring binary and text files:
  • Upload: Sends a file to a server.
  • Download: Downloads a file from a server.
This section provides detailed information about the syntax diagram for both the upload and download transfer types. The following syntax rules apply:
  • The syntax of the selected protocol applies.

Format


1  JOBREC?  APPENDTEXT (
2.1! NO
2.1 YES
1 )?  DELETEAFTERDOWNLOAD (
2.1! NO
2.1 YES
1 )?  DELETEAFTERUPLOAD (
2.1! NO
2.1 YES
1 )?  EXTRACOMMANDS (  FTP SIte subcommand )  JOBPWD (
2.1! NO
2.1 YES
1 )  JOBTYPE (
2.1 /file transfer
1 )  JOBUSR (  user name )?  LOCALCODEPAGE (  code page )  LOCALFILE (  file name )?  LOCALPWD
2.1! NO
2.1 YES?  LOCALUSR (  local user name )?  MAXPORT (  max_port )?  MINPORT (  min_port )?  PASSIVEMODE (
2.1! NO
2.1 YES
1 )?  PROTOCOL (
2.1 FTP
2.1 FTPS
2.1 FTPES
2.1 WINDOWS
2.1 SSH
1 )?  REMOTECODEPAGE (  code page )  REMOTEFILE (  file name )  SERVER (  host name )?  TIMEOUT (  seconds )?  TRANSFERMODE (
2.1 TEXT
2.1 BINARY
1 )  TRANSFERTYPE (
2.1 UPLOAD
2.1 DOWNLOAD
1 )

Parameters

The MINPORT and the MAXPORT options define the port range to use on the client side of TCP data connections. When the active mode is enabled, the MINPORT and the MAXPORT options restrict the port numbers sent by the PORT command. These options are meant to accommodate highly restrictive firewall rules.

If you do not specify the MINPORT and the MAXPORT options, the operating system determines the port numbers to be used. If you specify one of these parameters, the other parameter is required.

APPENDTEXT(YES|NO)

Specify this attribute and set it to YES 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 TEXT. Omit this attribute if you do not want to append the data to an existing file. The default value is NO.

DELETEAFTERDOWNLOAD(YES|NO)

Set this attribute to YES to delete the transferred files from the server after the download. The default value is NO.

DELETEAFTERUPLOAD(YES|NO)

Set this attribute to YES if the source files must be deleted after the transfer. The default value is NO.

EXTRACOMMANDS(FTP SIte subcommand)
Specify a SIte subcommand to send information that is used by the remote host to provide services specific to that host system. Valid for an upload file transfer using the FTP protocol when the target workstation is a z/OS system. For example, you can specify a subcommand to define how to allocate the data set (LR,BLK, VOL, to name a few).
JOBPWD(YES|NO)
Specifies that the user name set in JOBUSR or by using the job-submit exit EQQUX001 is associated with a password.

If you set JOBPWD to YES, HCL Workload Automation for Z searches for the user password in the USRPSW keyword of the USRREC statement (for details, see USRREC).

Typically, the password is required for users who schedule jobs to run on Windows workstations. Set JOBPWD to NO if the user works with UNIX workstations.

JOBTYPE(/xajob/access method name|/j2ee/ejb|/j2ee/jms|/web service|/file transfer|/database|/java)
To run a file transfer job, specify /file transfer. For information about the other types of job, see the specific section for each job type. This keyword is required.
/file transfer
Set this value to submit a file transfer job.
JOBUSR(user name)
The user name for accessing the FTP, FTPS, FTPES, SSH, or Windows server.
If the user schedules jobs to run on Windows workstations, ensure that a user password is also defined (see the JOBPWD keyword). Use the following syntax:
To define a Windows domain user
JOBUSR(domainName\userName)
To define a Windows domain user in the username@web_domain format
JOBUSR('userName@web_domain')

To specify the user name, you can also use the job-submit exit EQQUX001. This user name overrides the value specified for JOBUSR. In turn, the value specified for JOBUSR overrides the value specified for USRNAM in the USRREC statement.

LOCALCODEPAGE(code page)
The name of the code page used on the local system. This keyword is required only when transferring text files from a distributed to a z/OS environment and vice versa. If you specify this parameter, the REMOTECODEPAGE parameter is required.
LOCALFILE(file name)
Required. The name of the local file that you want to transfer. When uploading, this is the source file, when downloading, this is the target file.
LOCALPWD(YES|NO)
Specifies that the user name set for LOCALUSR is associated with a password. Typically, the password is required for users who schedule jobs to run on Windows workstations. LOCALPWD must be set to YES also if TRANSFERTYPE is set to UPLOAD and the file transfer is towards a z/OS server.

By setting LOCALPWD to YES, HCL Workload Automation for Z searches for the user password in the USRPSW parameter of the USRREC statement (for details, see USRREC).

LOCALUSR(local user name)
Specifies the local user, if the scheduled jobs run on Windows workstations. The value specified for LOCALUSR overrides the value specified for USRNAM in the USRREC statement. If you set LOCALUSR, the LOCALPWD parameter must also be set to YES.
Use the following syntax:
To define a Windows domain user
LOCALUSR(domainName\userName)
To define a Windows user in the username@web_domain format
LOCALUSR('userName@web_domain)
MAXPORT(max_port)
The maximum port value to use on the client side of TCP data connections. For example, if you specify MAXPORT=8009, HCL Workload Automation for Z restricts the port number to be lesser than or equal to the port 8009. The default value is 1035.
MINPORT(min_port)
The minimum port value to use on the client side of TCP data connections. For example, if you specify MINPORT=8000, HCL Workload Automation for Z restricts the port number to be greater than or equal to the port 8000.
PASSIVEMODE(YES|NO)
Specifies whether the server is passive or active in establishing connections for data transfers. If you set this option to NO, the server establishes the data connection with the client (active mode), if you set this option to YES, the client establishes the data connection with the server (passive mode). The default value is NO.
PROTOCOL(FTP|FTPS|FTPES|WINDOWS|SSH)
The protocol to be used for the file transfer. Allowed values are:
FTP
A standard network protocol used to exchange files over a TCP/IP-based network, such as the Internet.
FTPS
An extension to the File Transfer Protocol (FTP) that adds support for the Transport Layer Security (TLS) and the Secure Sockets Layer (SSL) cryptographic protocols. Specifically, the supported protocol is TLS security for FTP sessions with implicit secure TLS login and with private security level for the data connection.
FTPES
An extension to the File Transfer Protocol (FTP). Specifically, the supported protocol is TLS security for FTP sessions with explicit TLS security and private security level for the data connection.
WINDOWS
The Microsoft file sharing protocol. Specify the root shared directory in the REMOTEFILE keyword. Specify the address of the workstation hosting the shared directory in the SERVER keyword.
SSH
A network protocol that provides file access, file transfer, and file management functions over any data stream.
REMOTECODEPAGE(file name)
The name of the code page used on the remote system. This keyword is required only when transferring text files from a distributed to a z/OS environment and vice versa. If you specify this parameter, the LOCALCODEPAGE parameter is required. If you want to use a custom code page, define the REMOTECODEPAGE parameter as follows:
REMOTECODEPAGE(USER:custom_code_page)
where custom_codepage 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:
REMOTECODEPAGE(USER:tcpip.ftpd.ftpxlbin.frence3)
REMOTEFILE(file name)
The name of the remote file that you want to transfer. When uploading, this is the target file, when downloading, this is the source file. This keyword is required.
SERVER(host name)
The host name of the server where the file transfer is to be performed or where the database is located. This keyword is required if you set JOBTYPE to (/file transfer) or (/database).
TIMEOUT(seconds)
Specifies the number of seconds to be used for the file transfer operation. The default value is 60 seconds.
TRANSFERMODE(TEXT|BINARY)
The mode of file transfer that you want to perform, either text or binary.
TRANSFERTYPE(UPLOAD|DOWNLOAD)
The type of file transfer that you want to perform; either upload or download. This keyword is required.

Examples

The following is an example of a JOBREC statement to transfer a file using the FTP protocol:
//JOBREC                
JOBTYPE(/file transfer)
TRANSFERTYPE(DOWNLOAD) 
SERVER(server address)   
LOCALFILE(C:\file1.txt)
REMOTEFILE(/file1.txt) 
PROTOCOL(FTP)          
JOBUSR(username)  
JOBPWD(YES)            
//END JOBREC            
The following is an example of a JOBREC statement to transfer a file using the SSH protocol:
//JOBREC                                      
JOBTYPE(/file transfer)                       
TRANSFERTYPE(DOWNLOAD)                        
SERVER(server address)           
LOCALFILE(C:\file1.txt)                       
REMOTEFILE(/home/provaftp/file1.txt)
PROTOCOL(SSH)                                 
JOBUSR(username)                                
JOBPWD(YES)                                   
//END JOBREC
The following is an example of a JOBREC statement to transfer a file using the WINDOWS protocol:
//JOBREC                     
JOBTYPE(/file transfer)      
TRANSFERTYPE(UPLOAD)         
SERVER(server address)         
LOCALFILE(C:\file3.txt)      
REMOTEFILE(shared directory\file88.txt) 
PROTOCOL(WINDOWS)            
JOBUSR(username)        
JOBPWD(YES)                  
//END JOBREC   
The following example shows a JOBREC statement to transfer a native z/OS file from a z/OS workstation to a Windows workstation:
//JOBREC
JOBTYPE(/file transfer)
TRANSFERTYPE(DOWNLOAD)
TRANSFERMODE(TEXT)
SERVER(9.168.101.41)
LOCALFILE(d:\MyFTPRemoteTextFile.txt)
REMOTEFILE(’TWSZ.REMOTE.TEXTFILE’)
LOCALCODEPAGE(ISO8859-1)
REMOTECODEPAGE(IBM-037)
JOBUSR(root)
JOBPWD(YES)
PROTOCOL(FTP)
//END JOBREC
The following example shows a passive mode transfer with a timeout of 10 seconds. The system determines which port to use between 1034 and 1035:
//JOBREC
JOBTYPE(/file transfer)
TRANSFERTYPE(DOWNLOAD)
TRANSFERMODE(TEXT)
SERVER(9.168.107.126)
LOCALFILE(d:\MyFTPRemoteTextFile11.txt)
REMOTEFILE(’TWS851.REMOTE.TEXTFILE’)
LOCALCODEPAGE(ISO8859-1)
REMOTECODEPAGE(IBM-037)
TIMEOUT(10)
MINPORT(1034)
MAXPORT(1035)
PASSIVEMODE(YES)
JOBUSR(LNDN_USER)
JOBPWD(YES)
PROTOCOL(FTPES)
//END JOBREC