The FTP system exit is called for the events described below. Each event is uniquely identified by the main event name and the subevent name. At present, there is only one main event FTP for the FTP system exit routine, with the subevents FTPLOG, FTPBYE, FTPCMD and FTPCMDE.
When programming exit routines, you should bear in mind that there could be more main events and subevents in future versions of the exit.
Each call to the exit is issued with the port number of the FTP server and a "connection ID". If multiple FTP servers (with different port numbers) are started, a separate behavior can be implemented in the exit routine for each server by means of the port number. The "connection ID" enables all FTPCMD, FTPCMDE, FTPBYE subevents associated with a particular FTP session to be identified, i.e. all events with a certain "connection ID" belong to the last preceding FTPLOG event with the same "connection ID". This enables the exit routine to temporarily save and retrieve information that is needed by the same FTP session in subsequent calls.
Subevent FTPLOG
The subevent FTPLOG is called at each FTP login attempt. The exit routine can decide on the basis of the supplied parameters (user ID, account, password, partner system) whether or not this login attempt should be allowed. In addition, the exit routine can log all access attempts and return some parameters (user ID, account, password) changed by using the "Modify call" return code. This can be used, for example, to make the output of interactive access authorizations unnecessary, since the exit routine can map special FTP login passwords, which do not enable interactive access, to actual interactive passwords.
Subevent FTPBYE
The subevent FTPBYE is called when an FTP session is ended. The exit routine can then create a closing log of the FTP session, for example, and delete any buffered data, if necessary. In addition to the data that is always supplied, the user id, account, password, partner system and ftp login are always supplied as action classes with this call.
Subevent FTPCMD
The subevent FTPCMD is called on receiving certain FTP commands. Not only the name of the FTP (protocol) command is supplied, but also an associated action class (see the table below). Note that the decision to grant or deny permission should preferably be based on the action class instead of the command name to avoid unnecessary updates in case the set of verified FTP commands is changed in future versions.
The command parameter (file or directory name) is also supplied.
Command | Action class |
RETR | YAPXREAD |
STOR | YAPXWRT |
STOU | YAPXWRT |
APPE | YAPXWRT |
RNFR | YAPXMODA |
DELE | YAPXDEL |
FILE | YAPXCREA |
PWD | YAPXSHDR |
XPWD | YAPXSHDR |
CWD | YAPXSHDR |
XCWD | YAPXSHDR |
LIST | YAPXSHDR |
NLST | YAPXSHDR |
CDUP | YAPXSHDR |
XDUP | YAPXSHDR |
MKD | YAPXCRDR |
XMKD | YAPXCRDR |
RMD | YAPXDLDR |
XRMD | YAPXDLDR |
SIZE | YAPXSHDR |
MDTM | YAPXSHDR |
MLSD | YAPXSHDR |
MLST | YAPXSHDR |
The system exit is not called for any of the other FTP commands.
If the exit is caused by a command that results in a write access from the viewpoint of the server, a parameter is used to specify whether this access is to extend, replace or create a new file. In addition, the name of the file or directory on which the command works is also supplied. This name could potentially be modified (by adding a prefix, for example) and returned, and the FTP server could then use only this modified name thereafter. The "Modify call" return code should be used here.
Subevent FTPCMDE
The subevent FTPCMDE is called with the same parameters as FTPCMD when a command has been processed. It is also established whether the command has been terminated without errors (YAPXCMDR field with the values YAPXOK or YAPXERR).
Register values
On entering the exit routine, registers 4 to 11 are undefined, and the remaining registers have the following values:
R0 R1 R2 R3 R12 R13 R14 R15 | = = = = = = = = | Exit number '023' A(YAPXPARL) = FTP system exit parameter list; see below A(Task Control Block) A(Executive Vector Table) A(TPR Program Manager) A(Save area of the calling component) A(Indirect return) A(Exit routine) |
Registers 12, 13 and 14 must not be destroyed by the exit routine.
Return information
The exit routine supplies return information to the calling FTP component in register 15 in the following format:
R15 BB | = = | X'BB0000RR' Return information of the basic mechanism | |
| 00 04 08 | No error Exit routine not active Invalid call | ||
| RR | = | Return information of the exit routine to the calling FTP component. | |
| The following values are possible: | |||
| 00 04 08 | Reject call Accept call Modify call | ||
The YAPSEPA macro can be used to create a DSECT for the FTP system exit parameter list.
Layout of operand list
(macro resolution with MF=D and default values for PREFIX and MACID)
[label] YAPSEPA MF=D [,PREFIX=Y | <prefix>]
-
[,MACID=APX | <mac-id>]
---
Example
YAPSEPA MF=D 1 MFTST MF=D,PREFIX=Y,MACID=APX,ALIGN=F, C 1 DMACID=APX,SUPPORT=(D,C,M,L),DNAME=APXPARL 2 YAPXPARL DSECT , 2 *,##### PREFIX=Y, MACID=APX ##### 1 * Parameter area 1 * 1 YAPXHDR DS 0XL16 Header 1 YAPXVERS DS F Interface version 1 * VERSION 1 YAPXVER1 EQU 1 Internet Services V1.0 1 YAPXVER2 EQU 2 Internet Services V2.0 1 * 1 YAPXMCAS DS F Exit main case 1 * Exit main case 1 YAPXFTP EQU 1 FTP 1 * 1 YAPXSCAS DS F Exit sub case 1 * Exit sub case 1 YAPXFLOG EQU 1 FTP login 1 YAPXFCMD EQU 2 FTP command 1 YAPXFCDE EQU 3 FTP command end 1 YAPXFBYE EQU 4 FTP logout 1 * 1 YAPXRSLT DS F Internally used 1 * 1 * 1 YAPXIND DS 0XL856 Input parameters 1 YAPXPORT DS F FTP server port number 1 YAPXCNID DS F Connection id 1 YAPXACT DS F FTP action class 1 * Action class 1 YAPXWRT EQU 1 write 1 YAPXREAD EQU 2 read 1 YAPXSHAT EQU 4 show attributes 1 YAPXDEL EQU 8 delete 1 YAPXCREA EQU 16 create 1 YAPXMODA EQU 32 modify attributes 1 YAPXSHDR EQU 64 show directory 1 YAPXMOVE EQU 128 move 1 YAPXCRDR EQU 256 create directory 1 YAPXDLDR EQU 512 delete directory 1 YAPXMDDR EQU 1024 modify directory 1 YAPXLOG EQU 2048 ftp login 1 * 1 YAPXWRMD DS F Write mode 1 * Write mode 1 YAPXNEW EQU 1 New 1 YAPXREPL EQU 2 Replace 1 YAPXEXT EQU 4 Extend 1 * 1 YAPXPRTN DS CL256 Partner system 1 YAPXUSER DS CL9 User id 1 YAPXACCT DS CL9 Account 1 YAPXPASS DS CL35 Password 1 YAPXFILE DS CL500 File name 1 YAPXCMD DS CL5 FTP command 1 YAPXRSV1 DS XL2 Reserved 1 YAPXCMDR DS F FTP command rc 1 * Command rc 1 YAPXOK EQU 0 Ok 1 YAPXERR EQU 1 Error 1 * 1 YAPXRSV2 DS XL20 Reserved 1 * 1 * 1 YAPXOUTD DS 0XL576 Output parameters 1 YAPXUSRO DS CL9 User id 1 YAPXACCO DS CL9 Account 1 YAPXPASO DS CL35 Password 1 YAPXFILO DS CL500 File name 1 YAPXRSV3 DS XL23 Reserved 1 * 1 YAPX# EQU *-YAPXVERS
Alternatively, there is also a corresponding C include YAPSEPA.H:
#ifndef _YAPSEPA_H
#define _YAPSEPA_H
#if 0
/*********************************************************************
BEGIN-INTERFACE YAPSEPA
TITLE (/ TCP-IP-AP System exit parameter list /)
NAME YAPSEPA.H
DOMAIN TCP-IP-AP
LANGUAGE C
COPYRIGHT (C) Fujitsu Technology Solutions GmbH 2010
ALL RIGHTS RESERVED
COMPILATION-SCOPE USER
INTERFACE-TYPE CALL
RUN-CONTEXT TU
PURPOSE (/ YAPSEPA describes the parameter list for
the FTP system exit.
/)
END-INTERFACE YAPSEPA.
*********************************************************************/
#endif
/* Version */
/* ENUM version_s */
#define YAPSEPAvers1 1 /* Internet Services V1.0 */
#define YAPSEPAvers2 2 /* Internet Services V2.0 */
/* Exit main case */
/* ENUM mainCase_s */
#define YAPSEPAFTP 1 /* FTP */
/* Exit sub case */
/* ENUM subCase_s */
#define YAPSEPAFTPLOG 1 /* FTP login */
#define YAPSEPAFTPCMD 2 /* FTP command */
#define YAPSEPAFTPCMDE 3 /* FTP command end */
#define YAPSEPAFTPBYE 4 /* FTP logout */
/* Action class */
/* ENUM action_s */
#define YAPSEPAwrite 1 /* write */
#define YAPSEPAread 2 /* read */
#define YAPSEPAshow_attr 4 /* show attributes */
#define YAPSEPAdelete 8 /* delete */
#define YAPSEPAcreate 16 /* create */
#define YAPSEPAmod_attr 32 /* modify attributes */
#define YAPSEPAshow_dir 64 /* show directory */
#define YAPSEPAmove 128 /* move */
#define YAPSEPAcre_dir 256 /* create directory */
#define YAPSEPAdel_dir 512 /* delete directory */
#define YAPSEPAmod_dir 1024 /* modify directory */
#define YAPSEPAlogin 2048 /* ftp login */
/* Write mode */
/* ENUM writeMode_s */
#define YAPSEPAnew 1 /* New */
#define YAPSEPAreplace 2 /* Replace */
#define YAPSEPAextend 4 /* Extend */
/* Command rc */
/* ENUM commandRc_s */
#define YAPSEPAok 0 /* Ok */
#define YAPSEPAerror 1 /* Error */
/* Parameter area */
struct YAPSEPA_pl_mdl {
/* Header */
struct {
unsigned long version; /* Interface version */
unsigned long mainCase; /* Exit main case */
unsigned long subCase; /* Exit sub case */
unsigned long result; /* Internally used */
} header;
/* Input parameters */
struct {
unsigned long portNum; /* FTP server port number */
unsigned long connId; /* Connection id */
unsigned long action; /* FTP action class */
unsigned long writeMode;
/* Write mode */
char partner[256]; /* Partner system */
char userId[9]; /* User id */
char account[9]; /* Account */
char password[35]; /* Password */
char fileName[500]; /* File name */
char command[5]; /* FTP command */
char reserved_1[2]; /* Reserved */
unsigned long commandRc;
/* FTP command rc */
char reserved_2[20]; /* Reserved */
} in_data;
/* Output parameters */
struct {
char userId[9]; /* User id */
char account[9]; /* Account */
char password[35]; /* Password */
char fileName[500]; /* File name */
char reserved_3[23]; /* Reserved */
} out_data;
};
#endif /* _YAPSEPA */