Der FTP-System-Exit wird bei den im Folgenden erläuterten Ereignissen aufgerufen. Jedes Ereignis wird eindeutig gekennzeichnet durch den Hauptereignis-Namen und den Unterereignis-Namen. Zur Zeit existiert nur ein Hauptereignis FTP für die FTP-System-Exit-Routine mit den Unterereignissen FTPLOG, FTPBYE, FTPCMD und FTPCMDE.
Bei der Programmierung der Exit-Routinen sollten Sie berücksichtigen, dass es in zukünftigen Versionen des Exits weitere Haupt- und Unterereignisse geben kann.
Bei jedem Aufruf des Exits wird die Portnummer des FTP-Servers und eine „Connection-Id“ mitgegeben. Falls mehrere FTP-Server (mit unterschiedlichen Portnummern) gestartet werden, kann mithilfe der Portnummer für jeden Server eine eigene Verhaltensweise der Exit-Routine realisiert werden. Die „Connection-Id“ erlaubt es, alle zu einer bestimmten FTP-Sitzung gehörenden Unterereignisse FTPCMD, FTPCMDE, FTPBYE zu identifizieren, mit anderen Worten, alle Ereignisse mit einer bestimmten „Connection-Id“ gehören zum jeweils letzten vorangegangenen FTPLOG-Ereignis mit der gleichen „Connection-Id“. Damit kann die Exit-Routine Informationen zwischenspeichern und wiederfinden, die bei späteren Aufrufen durch die gleiche FTP-Sitzung benötigt werden.
Unterereignis FTPLOG
Das Unterereignis FTPLOG wird bei jedem FTP-Login-Versuch aufgerufen. Die Exit-Routine kann anhand der mitgegebenen Parameter (User id, Account, Password, Partnersystem) entscheiden, ob dieser Login-Versuch zugelassen werden soll. Die Exit-Routine kann darüber hinaus alle Zugangsversuche protokollieren und manche Parameter (User id, Account, Password) verändert zurückgeben, indem sie den Returncode „Aufruf modifizieren“ verwendet. Dies kann zum Beispiel dazu benutzt werden, die Herausgabe von Dialogzugangsberechtigungen unnötig zu machen, indem die Exit-Routine spezielle FTP-Login-Kennungen, die keinen Dialogzugang ermöglichen, auf echte Dialog-Kennungen abbildet.
Unterereignis FTPBYE
Das Unterereignis FTPBYE wird beim Beenden einer FTP-Sitzung aufgerufen. Die Exit-Routine kann dann z.B. eine abschließende Protokollierung der FTP-Sitzung erstellen und gegebenenfalls zwischengespeicherte Daten löschen. Zusätzlich zu den immer mitgelieferten Daten werden bei diesem Aufruf User id, Account, Password, Partnersystem und ’ftp login’ als Aktionsklasse mitgeliefert.
Unterereignis FTPCMD
Das Unterereignis FTPCMD wird beim Empfang von bestimmten FTP-Kommandos aufgerufen. Dabei wird nicht nur der Name des FTP-(Protokoll-)Kommandos, sondern auch eine zugeordnete Aktionsklasse (siehe nachfolgende Tabelle) mitgegeben. Es wird empfohlen, die Erlaubnisentscheidung anhand der Aktionsklasse und nicht des Kommando-Namen zu treffen, um unnötige Änderungen bei einer evtl. Änderung der Menge der überprüften FTP-Kommandos in zukünftigen FTP-Versionen zu vermeiden.
Außerdem wird der Kommando-Parameter (Datei- oder Verzeichnisname) mitgeliefert.
Kommando | Aktionsklasse |
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 |
Bei allen anderen FTP-Kommandos wird der System-Exit nicht aufgerufen.
Wenn der Exit durch ein Kommando verursacht wird, das aus Sicht des FTP-Servers zu einem schreibenden Zugriff führt, wird in einem Parameter angegeben, ob dieser Zugriff eine Datei erweitern, ersetzen oder neu schreiben soll. Außerdem wird der Datei- bzw. Verzeichnisname, auf den das Kommando wirkt, mitgegeben. Dieser kann gegebenenfalls (z.B. durch Voransetzen eines Präfix) modifiziert wieder zurückgegeben werden. Der FTP-Server verwendet dann nachfolgend nur diesen veränderten Namen. Hierfür ist der Returncode „Aufruf modifizieren“ zu verwenden.
Unterereignis FTPCMDE
Das Unterereignis FTPCMDE wird nach Abarbeitung eines Kommandos mit den gleichen Parametern wie FTPCMD aufgerufen. Zusätzlich wird mitgeteilt, ob das Kommando fehlerfrei abgeschlossen wurde (Feld YAPXCMDR mit den Werten YAPXOK oder YAPXERR).
Registerversorgung
Beim Ansprung der Exit-Routine sind die Register 4 bis 11 undefiniert, die übrigen Register enthalten folgende Werte:
R0 R1 R2 R3 R12 R13 R14 R15 | = = = = = = = = | Exitnummer '023' A(YAPXPARL) = FTP-System-Exit-Parameterliste s.u. A(Task Control Block) A(Executive Vector Table) A(TPR Program Manager) A(Sicherungsbereich der rufenden Komponente) A(Indirekter Rücksprung) A(Exit-Routine) |
Die Register 12, 13 und 14 dürfen von der Exit-Routine nicht zerstört werden.
Rückkehrinformation
Die Exit-Routine gibt in Register 15 Rückkehrinformation an die rufende FTP-Komponente in folgendem Format zurück:
R15 BB | = = | X'BB0000RR' Rückkehrinformation des Basismechanismus | |
| 00 04 08 | kein Fehler Exit-Routine nicht aktiviert fehlerhafter Aufruf | ||
| RR | = | Rückkehrinformation der Exit-Routine an die rufende FTP-Komponente. | |
| Folgende Werte sind möglich: | |||
| 00 04 08 | Aufruf ablehnen Aufruf annehmen Aufruf modifizieren | ||
Mit dem Makro YAPSEPA kann eine DSECT für die FTP-System-Exit-Parameterliste erstellt werden.
Layout der Operandenliste
(Makro-Auflösung mit MF=D und Standardwerten für PREFIX und MACID)
[label] YAPSEPA MF=D [,PREFIX=Y | <prefix>]
-
[,MACID=APX | <mac-id>]
---
Beispiel
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
Alternativ gibt es auch einen entsprechenden 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 */