z/OS FTP client behavior when invoked from the FTP client API

The z/OS® FTP client that is used by the FTP client API is described in the File Transfer Protocol (FTP) information in the z/OS Communications Server: IP User's Guide and Commands and in the File Transfer Protocol information in the z/OS Communications Server: IP Configuration Reference. The z/OS FTP client, when started with the FTP client API, operates essentially as it does when invoked in an interactive environment under the z/OS UNIX shell.

The following list shows the differences in the behavior of the z/OS FTP client when it is invoked by the FTP client API:

When the z/OS FTP client starts, options (parameters) are processed that affect the operation of the client. The user program uses the START-PARM parameter on the INIT request to pass its options to the FTP client API, which passes the options on to the client (see INIT). All of the options that are defined for the z/OS FTP client are accepted when the client is started with the FTP client API. However, the following conditions apply:
- The -e and the EXIT options are ignored by the FTP client API.
  These options are intended to affect the operation of the FTP client by causing it to stop when an eligible subcommand encounters an error. In the FTP client API, those errors are passed back to the user program as a client error code (see Table 1). The user program can process the error and decide whether to continue or to end the client process.
- The -i option to disable prompting for the subcommands MGET, MPUT, MDELETE has no effect on the API.
  See Prompts from the client for a discussion on how prompts are handled when the z/OS FTP client is invoked from the FTP client API.
- When the z/OS FTP client is invoked within the z/OS UNIX shell, a backslash (\) is required before the open parenthesis [(] that signals the start of the MVS-type parameters. Do not use the backslash when invoking the client with the FTP client API.
When the z/OS FTP client is invoked from a batch job or from TSO, data sets and files can be allocated to DD names for use by the client. When the z/OS FTP client is created from the FTP client API, DD names that are associated with the application are not available to the client process. Specifically, the use of the following DD names is not supported by the FTP client API:
- SYSFTPD and SYSTCPD
- NETRC
- INPUT (SYSIN) and OUTPUT
Transfer of data sets by DD name is not possible in the created client process. If the application sends a transfer subcommand (PUT, GET, and so on) that includes //DD:ddname, the client returns an error such as FCAI_CEC_FILE_ACCESS.
Changing local site defaults using FTP.DATA in z/OS Communications Server: IP User's Guide and Commands describes how to change local site defaults by using FTP.DATA. The search order for locating the FTP.DATA configuration file for the client under the FTP client API is as follows:
1. -f parameter
2. $HOME/ftp.data
3. userid.FTP.DATA
4. /etc/ftp.data
5. SYS1.TCPPARMS(FTPDATA)
6. tcpip_hlq.FTP.DATA
Restriction: The -f parameter cannot be a DD name when the FTP client is invoked from the FTP client API.

Tip: The $HOME variable is taken from the user's RACF® user profile OMVS segment. The $HOME variable can be modified with the environment variable list passed during FTP client API initialization. Initialization is performed with an ftpapi('init') request in the REXX environment; with a call to the EZAFTPKS stub program with the INIT keyword for assembler, COBOL, and PL/1; or with a call to the FAPI_INIT function for C/C++.
The FTP.DATA statements that can be used to change local site defaults for the z/OS FTP client are defined in the FTP.DATA statements information in the z/OS Communications Server: IP Configuration Reference. One of the statements is CLIENTERRCODES, which controls return code settings in the client. When the client is started by the FTP client API, the value on the CLIENTERRCODES statement does not affect the reporting of results. See Interpreting results from an interface request for a complete description of how results from the interface and the client are reported.
When the z/OS FTP client or server prompts for a password or accounting information, the prompt must be satisfied before any other subcommand or command is accepted. Under the FTP client API, the user program has the option to issue GETL or TERM even when a password or accounting information is expected. If the request is TERM, the interface generates a QUIT subcommand, which is accepted and stops the client process. See GETL, TERM, and Prompts from the client for more information about how the FTP client API handles prompts.
The FTP client API requires a secondary subcommand parameter with an SCMD PROXY request. See SCMD and Prompts from the client for more information.