For handling the various exits, the callers of the exit routine (TELNET client or TELNET server) pass the address of a parameter list to the entry point YAPTEXIT. The yaptx structure from this parameter list is supplied in SYSLIB.TCP-IP-AP.nnn under the name yaptx.h.
Structure of yaptx
The yaptx structure is defined as follows:
struct yaptx {
int caller; /* Aufrufer: S=Server, C=Client */
#define client 0x01 /* X'01' Client */
#define server 0x02 /* X'02' Server */
int action /* main action code */
#define telrecv 0x01 /* action = receive */
#define telsend 0x02 /* action = send */
#define telopen 0x03 /* action = open connection */
#define telclos 0x04 /* action = close connection */
char *selector; /* Selector */
int portno; /* Port-Nummer (Server-Port) */
char hname[128+1]; /* Hostname von Server / Client */
char reserved[3]; /* Reserved */
int connid; /* identifies uniquely client-server */
/* connection. Only for Server */
char *inbuf; /* Address of input buffer */
int inbuflen; /* Length of input buffer */
char *outbuf; /* Address of output buffer */
int outbuflen; /* Length of output buffer */
int outDatalen; /* Length of output data */
Description of parameters
The following parameters are transferred:
Caller of exit routine (caller)
Type of entry (action)
Printable character string for identifying the exit routine (selector)
Connection identifier (connid)
Host name (hname)
of the addressed TELNET server (for TELNET clients)
of the calling TELNET server (for TELNET servers)
Port number (portno)
of the addressed TELNET server (for TELNET clients)
of the addressed TELNET client (for TELNET servers)
For send/receive exits: inbuf, inbuflen, outbuf, outbufLen, outDataLen
outDataLen must be supplied by the exit itself.
caller
Specifies whether the exit routine was called by the TELNET client or TELNET server.
action
Specifies the type of entry (receive, send, open connection, close connection)
selector
Printable character string for selecting the required exit routine. The character string is terminated with \0.
portno
Port number of the server or client:
On TELNET clients, portno specifies the port number of the addressed TELNET server.
On TELNET servers, portno specifies the port number of the addressed TELNET client.
hname[128+1]
Host name of server or client:
On TELNET clients, hname specifies the host name of the addressed TELNET server.
On TELNET servers, hname specifies the host name of the addressed TELNET client.
inBuf
Contains the address of the buffer containing the data to be converted (input buffer). Only relevant for send/receive exits.
inBufLen
Specifies the length (number of valid bytes) of the input buffer. Only relevant for send/receive exits.
outBuf
Contains the address of the output buffer. Only relevant for send/receive exits.
outBuflen
Specifies the length of the output buffer. Only relevant for send/receive exits.
outDataLen
Before returning to the caller, the routine must specify in outDataLen the number of valid bytes in the output buffer that must therefore be sent. Only relevant for send/receive exits.
connid
Connection identifier. The Connection Identifier uniquely identifies the client/server connection in the case of a fixed TELNET server. If several servers are active, the pair (portno, connid) uniquely identifies the connection between client and server and thus the TELNET client (see also the connid parameter). This is important, for example, for code conversions if two bytes are mapped to one byte. The exit routine must buffer the first byte in this case for the conversion to be able to perform the conversion when the second byte is received. connid ensures the unique assignment of the buffer to the respective connection.
Results and return values of exit routines
Exit routines must always supply a return value. Every exit for which no user-defined exit routine exists, must return the value 0xff as a return value.
Results and return values for send and receive
Following orderly execution, outbuf contains the converted code and outDataLen the length of the converted code. Return value: 0.
If an exit determines that there is not enough memory for a code conversion, the return value -2 must be returned.
The only query with inbuf = 0 is whether or not a relevant exit was defined:
If a relevant exit is defined, the return value must be 0.
If no relevant exit is defined, the return value must be 0xff.
Results and return values for open and close
open
If the exit permits access to the server, the return value is 0, otherwise it must be -1.
close
close always returns the return value 0.