Für die Behandlung der verschiedenen Exits übergeben die Aufrufer der Exit-Routine (FTP-Client oder FTP-Server) an den Einsprungspunkt YAPFEXIT die Adresse einer Parameterliste. Die Struktur YAPFX_pl_mdl dieser Parameterleiste wird in der Header-Datei YAPFX.H der Bibliothek SYSLIB.TCP-IP-AP.nnn ausgeliefert. Die Signatur von YAPFEXIT lautet wie folgt:
void YAPFEXIT (struct YAPFX_pl_mdl*)
Struktur YAPFX_pl_mdl
Die Struktur YAPFX_pl_mdl ist wie folgt definiert:
/* 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;
};
Beschreibung der Parameter
caller
zeigt an, ob die Routine vom FTP-Client oder vom FTP-Server aufgerufen wurde.
action
zeigt an, ob der Aufruf vor dem Senden (YAPFXsend) oder nach dem Empfangen (YAPFXrecv) von Daten erfolgt ist.
actionm
zeigt an, ob der Aufruf der erste oder der letzte ist, der zu dem aktuellen Datentransfer gehört (siehe auch Parameter connId). Bei sehr kleinen Dateien können auch beide Flags gleichzeitig gesetzt sein.
selector
Mit selector können Sie unter mehreren zur Verfügung stehenden Aktionen die gewünschte Aktion auswählen. Zu diesem Zweck kann der Umwandlungsroutine ein String mitgegeben werden, auf den selector verweist. Dabei können Sie frei entscheiden, welche Strings mit welchen Bedeutungen verwendet werden. Lediglich den Strings „*“ und „*NONE“ ist eine feste Bedeutung zugeordnet.
hostName
liefert den Namen des jeweiligen Client-Hosts (mit Null-Byte terminiert).
portNo
wird im Fall caller = YAPFXserver versorgt und spezifiziert die Portnummer, unter der der aufrufende Server seine Dienste anbietet. Auf diese Weise können mehrere gleichzeitig gestartete Server unterschieden werden.
connId
ermöglicht es bei mehreren aktiven Verbindungen, die einzelnen Verbindungen durch das Paar (portNo, connId) zu identifizieren. Erforderlich ist dies z.B., wenn verbindungsspezifische Status-Informationen über die Dauer eines Aufrufs hinaus gespeichert und wiedergewonnen werden müssen. Wird beispielsweise bei einem Aufruf als letztes Byte nur das erste Byte einer aus zwei Zeichen bestehenden Zeichenfolge mitgeliefert, so muss dieses Byte so lange zwischengespeichert werden, bis es beim nächsten Aufruf berücksichtigt werden kann.
Wie mit solchen zwischengespeicherten Informationen verfahren werden soll, wird über die Flags in actionm gesteuert:
Bei YAPFXfirst müssen Sie Statusinformationen löschen, die von früheren Aufrufen stammen.
Bei YAPFXlast müssen Sie alle zwischengespeicherten Daten zurückliefern.
inBuf
enthält die Adresse des Puffers, in dem die umzuwandelnden Daten stehen (Eingabepuffer).
inBufLen
spezifiziert die Länge (Anzahl der gültigen Bytes) des Eingabepuffers.
outBuf
enthält die Adresse des Ausgabepuffers.
outBuflen
spezifiziert die Länge des Ausgabepuffers.
outDataLen
Vor dem Rücksprung zum Aufrufer muss die Routine in outDataLen hinterlegen, wie viele Bytes im Ausgabepuffer gültig sind und somit übertragen werden müssen.
rc
In rc zeigt die Umwandlungsroutine an, ob die Umwandlung erfolgreich beendet wurde.
Benutzerdefinierte FTP-Exits unter POSIX schreiben
Da der POSIX-FTP aus dem Zusammenbinden der LLMs FTP und FTPEXIT entsteht, können Sie auch unter POSIX mit den FTP-Exits arbeiten. Der Lieferumfang von interNet Services enthält den Dummy-Modul FTPEXIT, der nur einen Rücksprung ausführt.
Eigene FTP-Exits schreiben Sie wie folgt:
- Erstellen Sie Ihre gewünschte Version des FTPEXIT.
- Binden Sie diese Version mit FTP aus der SYSLNK.TCP-IP-AP.nnn zusammen.
- Schreiben Sie das resultierende LLM unter dem Namen FTP in die Bibliothek SINLIB.TCP-IP-AP.nnn.
- Installieren Sie anschließend POSIX-FTP (siehe Abschnitt „Installation und Deinstallation von FTP- und TELNET-Client in POSIX“).
Ergebnisse und Returncodes der Exit-Routinen
Falls der Ausgabepuffer für die vollständige Umwandlung zu klein ist, muss die Exit-Routine den Returncode YAPFXbufTooShort zurückliefern. In diesem Fall wird die Exit-Routine mit den gleichen Daten, aber größerem Ausgabepuffer erneut aufgerufen. Dies kann u.U. mehrfach erfolgen, bis der Ausgabepuffer groß genug ist oder ein internes Limit des Aufrufers überschritten wird.
Bei allen anderen Fehlern muss die Exit-Routine den Returncode YAPFXother zurückzuliefern. Der Aufrufer wird dann die Übertragung abbrechen und eine entsprechende Fehlerbehandlung einleiten.