FTP client API guidelines and requirements

This topic lists the usage guidelines, requirements, and restrictions for the FTP Client Application Programming Interface (API) for user application programs.

Table 1 describes the programming requirements that apply to the FTP client API.
Table 1. Programming requirements for the FTP client API
Function Restriction
Authorization Supervisor state or problem state, any PSW key
Dispatchable unit mode Task
SRB mode The API can be invoked only in TCB mode (task mode).
Cross-memory mode The API can be invoked only in a non-cross-memory environment (PASN=SASN=HASN).
ASC mode Primary address space control (ASC) mode
Interrupt status Enabled for interrupts
Locks No locks should be held when issuing these calls.
Control parameters Parameter lists and the FCAI control block must be in primary storage that is accessible by the API to prevent ABENDs in the EZAFTPKS interface program.
Functional Recovery Routine (FRR) Do not invoke the API with an FRR set. This can cause system recovery routines to be bypassed and severely damage the system.
Storage Storage acquired for the purpose of containing data returned from an FTP client API call must be obtained in the same key as the application program status word (PSW) at the time of the call.
Nested FTP client API calls You cannot issue nested FTP client API calls within the same task. If a request block (RB) issues an FTP client API call and is interrupted by an interrupt request block (IRB) in an STIMER exit, no additional FTP client API calls can be issued by the IRB.
Addressability mode (AMODE) considerations The API must be invoked while the caller is in 31-bit addressability mode.
Guidelines:
  • The FTP client API is re-entrant.
  • The user program can have more than one FTP Client Application Interface control block initialized and active in a single address space (see FTP Client Application Interface (FCAI) control block).
  • The FTP client API creates a child process for the z/OS® FTP client. If you have a signal handler, you might see the SIGCHILD signal raised when the FTP client terminates; no action is required.
  • The z/OS FTP client contains handlers for various asynchronous signals. The FTP client API does not contain any signal handlers, nor does it block or explicitly raise any signals. See Programming notes for the FTP client API for more information about errors in the z/OS FTP client process.
Requirements:
  • The application must supply an accessible parameter list and FCAI in primary storage to the FTP client API. ABENDs can occur in the interface if the application fails to comply with this requirement.
  • Other ABENDS that occur due to inaccessible storage are trapped by the interface and returned to the application program as an interface error (see FCAI_IE and its associated values in FTP Client Application Interface (FCAI) control block). To enable the interface to trap these ABENDs, specify TRAP(ON,NOSPIE) to disable invocation of the ESPIE macro when the application program executes within a Language Environment enclave. For example, specify the following execution parameter for a COBOL application program: 
    PARM='TRAP(ON,NOSPIE)/'

    For instructions on specifying runtime options and parameters for Language Environment languages, see the information about using runtime options in z/OS Language Environment Programming Guide.

  • All of the requests using the same FCAI control block must be made from the same thread.
  • The user program must use a standard call interface. Samples are provided for COBOL, C, PL/I, and assembler (see FTP client API sample programs).
  • The user program must run in 31-bit addressing mode (AMODE 31). Other addressing modes are not supported by the interface. The program can be at any location (RMODE can be 24 or ANY).
  • The application must have an OMVS segment defined (or defaulted).
  • The interface module EZAFTPKI must be accessible to the application in the linklist or in a STEPLIB or JOBLIB DD statement.
  • You can either statically link the FTP client API stub program (EZAFTPKS) into the user application program or load it dynamically for execution. The stub program is in SYSn.CSSLIB and is designed to maintain upward compatibility.
  • For a PL/I program, include this statement before your first call instruction:

    DCL EZAFTPKS ENTRY OPTIONS(RETCODE,ASM,INTER) EXT;

Restriction: Do not set TRACE RESOLVER in the TCPIP DATA file that an FTP client API application is using. If you need a resolver trace, pass the environment variable RESOLVER_TRACE to the FTP client on the INIT request.