Submitting FTP requests in batch

FTP is usually run interactively by starting and entering commands from your terminal. You can also run FTP as a batch job, but you must supply the JCL file. You can use batch when you know what functions you want to perform, when you want a hardcopy of the results, or when you want to perform an FTP function many times.

Rules: When coding the data set, file, or input stream for the ddname INPUT statement as described in Figure 1, the following rules apply:

When you specify a data set for input as shown in Figure 1, the SEQNUMSUPPORT statement that is coded in the client FTP.DATA file determines the disposition of sequence numbers that are in the data set:
- If the FTP.DATA file has SEQNUMSUPPORT FALSE coded (this is the default), the file, data set, or input stream that is designated in the DDNAME INPUT statement that contains the FTP commands cannot contain sequence line numbers. You must save the FTP command file as an unnumbered file.
- If the FTP.DATA file has SEQNUMSUPPORT TRUE coded, the file, data set, or input stream that is designated in the DDNAME INPUT statement that contains the FTP commands can contain sequence numbers. These sequence numbers are removed.
You can add comments to the command input file. The support includes standalone comment records and comments that are appended to the end of the line.
To add standalone comments, use a semicolon (;) as the first non-space character on a line. For example:
```
; This is a stand-alone comment record
```
To add a command-line comment, append a space and a semicolon to the end of the command line, followed by the comment. For example:
```
USER userx ; This is an appended comment
```
When a user ID, password, or password phrase is expected (including passwords that are required for read or write access to files or disks) and the value is intended to be retrieved from the NETRC file, the entire line must be blank. The following example shows a blank password between the user ID and a comment line.
```
    USER userx  

    ; The line above is a blank password   
```
The following example shows a blank user ID between a comment line and password.
```
     ; This below is a blank userid 

     mypasswd  
```
If a command is too long to insert on a line, enter a plus sign (+) in place of the next command option and then enter the remaining options on the next line. For example:
```
     put local_file +
     remote_file 
```
Use a blank followed by a plus sign (+) at the end of an FTP subcommand line as a continuation indicator for all FTP subcommands, except as noted under Restrictions. When the continuation indicator is encountered at the end of an FTP subcommand line, the next line is appended to the subcommand. For example, the following command is interpreted as PUT SOURCE.DS.NAME DEST.DS.NAME:
```
PUT SOURCE.DS.NAME +
DEST.DS.NAME
```

Tips:

You can run FTP in batch mode either by specifying data sets for input and output as in Figure 1, or without referring to data sets for input and output as in Figure 1. See Allocating FTP input and output data sets for the attributes that are allowed on the INPUT and OUTPUT DD statements.
Use the EXIT parameter or code the CLIENTEXIT TRUE statement in the FTP.DATA file to display an error return code, and exit when certain errors are detected. See FTP return codes for more information.

Requirements:

To have the FTP client perform DB/2 queries in a batch job, the DSNLOAD library must be in the link list or appear on a STEPLIB DD statement for the job.
When connecting to a server such as a UNIX server where user IDs, passwords, directory names, and file names are case sensitive, the data in the FTP batch job must be in the correct case.

Restrictions:

When the FTP Client API is used by an application program invoked from a batch job, the ddnames in the batch job are not available to the created FTP client process.
You cannot use a plus sign to continue a QUOTE subcommand.
You cannot use a plus sign to continue a password or password phrase on another line. You must take this into consideration when assigning password phrases used to log in to the FTP server from batch jobs.

See Logging in to FTP, and each subcommand that you code in your batch job for additional information.

Figure 1 shows an example of the JCL required to submit a batch job by referring to data sets for input and output.

Figure 1. JCL to run FTP in batch using data sets

//USER28F  JOB ,CARTER,MSGLEVEL=(1,1)
//FTPSTP1  EXEC PGM=FTP,REGION=2048K,
//             PARM='9.67.112.25 (EXIT TIMEOUT 20'
//NETRC    DD  DSN=ANYHLQ.NETRC,DISP=SHR
//OUTPUT   DD  SYSOUT=H
//INPUT    DD  *
type e
mode b
put idss.parts
/*

Notes:

REGION=2048K is a minimum requirement. The requirement could increase depending on the block size of the data set being transmitted.
The first JCL statement is a standard job statement. The next JCL statement is an EXEC statement. It has PGM=FTP (a region parameter) because FTP might use more storage than your default region size, and a PARM field.
For PARM=, you can specify any parameter that is valid when invoking FTP from your terminal. See Using FTP for more information. These parameters are supported only on the PARM= field of the EXEC card.

As shown in Figure 1, to run FTP in batch mode, you must include the following three DD statements:

SYSPRINT DD: Alternative name for the OUTPUT DD statement. You can use SYSPRINT DD in place of the OUTPUT DD statement.
OUTPUT DD: Specifies the data set where FTP is to place the client messages and server replies generated during the FTP session.
INPUT DD: Specifies the data set where the FTP subcommands to be performed are located.

You can use the user_id.NETRC data set, as defined by the NETRC DD statement in Figure 1, to provide user ID, password or password phrase, and account information for a batch-processed remote login. You can also specify the user ID, password or password phrase, and account information in the INPUT DD data set.

Figure 2 shows the records in an INPUT DD data set that contains the FTP subcommands to be executed.

Figure 2. Contents of an INPUT DD data set

HOSTNAME
USERID PASSWD
DIR
PUT MYFILE.LISTING
QUIT

The first line of Figure 2 contains the name of the remote host that you want FTP to log into. The second line contains the user ID followed by its password. The next three lines contain the FTP subcommands that you want FTP to perform. In this example,

FTP lists its current working directory at the FTP server host.
FTP sends the file MYFILE.LISTING to the server.
FTP ends the session and disconnects from the server.

Any client messages and server replies to the subcommands you execute appear in the OUTPUT DD data set. The SYSPRINT can contain some additional messages that relate to the execution of your FTP session.

Tip: If you do not want your password or password phrase to be copied to the output file, specify your user ID, and password or password phrase on separate input lines. See Figure 1 for an example.