For handling the various exit routines, the callers of the exit routine (FTP client or FTP server) pass the address of a parameter list to the entry point YAPFEXIT. The structure YAPFX_pl_mdl from this parameter list is supplied in the header file YAPFX.H of the SYSLIB.TCP-IP-AP.nnn library. The YAPFEXIT signature is as follows:
void YAPFEXIT (struct YAPFX_pl_mdl*)
Structure of YAPFX_pl_mdl
The YAPFX_pl_mdl structure is defined as follows:
/* Return codes */
/* ENUM rc_s */
#define YAPFXok 0 /* Ok */
#define YAPFXbufTooShort 1 /* Buffer too short */
#define YAPFXother 255 /* Other error */
/* Caller */
/* ENUM caller_s */
#define YAPFXclient 1 /* Client */
#define YAPFXserver 2 /* Server */
/* Action */
/* ENUM action_s */
#define YAPFXrecv 1 /* Receive */
#define YAPFXsend 2 /* Send */
/* Action modifier */
/* ENUM actionm_s */
#define YAPFXnone 0 /* None */
#define YAPFXfirst 1 /* First */
#define YAPFXlast 2 /* Last */
/* Parameter area */
struct YAPFX_pl_mdl {
/* Input parameters */
struct {
unsigned long caller; /* Calling instance */
unsigned short action; /* Action */
unsigned short actionm; /* Action modifier */
void *selector; /* Selector */
char hostname[33]; /* Host name */
char reserved1[7]; /* Reserved */
unsigned long portNo; /* Port number */
unsigned long connId; /* Connection Id (only server) */
void *inBuf; /* Address of input buffer */
unsigned long inBufLen; /* Length of data in input buffer */
void *outBuf; /* Address of output buffer * */
unsigned long outBufLen; /* Length of output buffer */
} in_data;
/* Output parameters */
struct {
unsigned long outDataLen; /* Lengh of data in output buffer */
unsigned long rc; /* Return code */
} out_data;
};
Description of parameters
caller
Indicates whether the routine was called from the FTP client or FTP server.
action
Indicates whether the call was made before data was sent (YAPFXsend) or after it was received (YAPFXrecv).
actionm
Indicates whether the call is the first or last that belongs to the current transfer (see also the connId parameter). Where the files are very small, both flags can also be set at the same time.
selector
selector allows you to choose the desired action from several available actions. A string can be given to the conversion routine for this purpose to which selector points. You can then decide freely which strings are used with which meaning. A fixed meaning is only assigned to the strings "*" and "*NONE".
hostName
Supplies the name of the respective client host (terminated with a null byte).
portNo
Supplied in the case of caller = YAPFXserver and specifies the port number under which the calling server offers its services. It is possible to distinguish in this way between several servers started at the same time.
connId
Where there are several active connections, this option allows the individual connections to be identified by the pair (portNo, connId). This is necessary, for example, if connection-specific status information is to be stored and then retrieved beyond the duration of a call. If only the first byte of a string containing two characters is supplied as the last byte in a call, for example, this byte must be buffered until it can be dealt with in the next call.
The flags in actionm determine how to use this type of buffered information:
Status information from previous calls must be deleted with YAPFXfirst.
All buffered data must be returned with YAPFXlast.
inBuf
Contains the address of the buffer containing the data for conversion (input buffer).
inBufLen
Specifies the length (number of valid bytes) in the receive buffer.
outBuf
Contains the address of the output buffer.
outBuflen
Specifies the length of the output buffer.
outDataLen
Before returning to the caller, the routine must indicate in outDataLen the number of valid bytes in the output buffer that thus have to be transferred.
rc
The conversion routine uses rc to indicate whether the conversion was terminated successfully.
Writing user-defined FTP exits under POSIX
As the POSIX FTP is created by linking the LLMs FTP and FTPEXIT, you can also work with the FTP exits under POSIX. The interNet Services package contains the dummy module FTPEXIT, which only executes a return.
You write your own FTP exits as follows:
- Create the version of the FTPEXIT you require.
- Link this version to FTP from SYSLNK.TCP-IP-AP.nnn.
- Write the resultant LLM to the SINLIB.TCP-IP-AP.nnn library under the name FTP.
- Then install POSIX-FTP (see the section “Installing and uninstalling FTP and TELNET clients in POSIX”).
Results and return codes for exit routines
If the output buffer is too small for the complete conversion, the exit routine must supply the return code YAPFXbufTooShort. The exit routine is called again in this case with the same data but a larger output buffer. This may happen several times until the output buffer is large enough or an internal limit on the part of the caller is exceeded.
In the case of all other errors, the exit routine must supply the return code YAPFXother. The caller then aborts the transfer and initiates a suitable error handling.