Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

FTP system exit events

&pagelevel(5)&pagelevel

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 */