Your Browser is not longer supported

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

{{viewport.spaceProperty.prod}}

Exit routines

&pagelevel(4)&pagelevel

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.