The Entire Net-Work user exit interface allows you to:
encrypt or compress data before transmission;
decrypt or decompress data after reception;
decide to accept or reject a connection from a host that is not predefined to Entire Net-Work; and
select model link parameters when accepting a connection from a host that is not predefined to Entire Net-Work.
If a user exit is defined, it is called before sending data, after receiving data, before accepting a connect request from a host that has not been defined, and before disconnecting a link to free resources obtained by the exit.
This section covers the following topics:
On entry to the exit, the exit must save the registers in the area provided, which is pointed to by R13. Register contents are listed in the following table:
| Register | Contents |
|---|---|
| R1 | Points to a parameter list (described below). |
| R13 | Points to a 72-byte save area. |
| R14 | Contains the return address of the exit. |
| R15 | Contains the entry address of the exit. |
The following table contains the user exit parameter list format. Also see NETUEXPL DSECT.
| Function | Offset | Contents |
|---|---|---|
| Function 0 | Immediately before sending data: | |
| +0 | Function code = 0 | |
| +4 | User context word | |
| +8 | Link name | |
| +16 | Address of message to be sent | |
| +20 | Length of message to be sent | |
| +24 | Address of area to compress/encrypt message | |
| +28 | Length of area to compress/encrypt message | |
| Function 4 | Immediately after receiving data: | |
| +0 | Function code = 4 | |
| +4 | User context word | |
| +8 | Link name | |
| +16 | Address of message received | |
| +20 | Length of message received | |
| +24 | Address of area to decompress/decrypt message | |
| +28 | Length of area to decompress/decrypt message | |
| Function 8 | Immediately after accepting a connect request from a host that has not been defined to Entire Net-Work: | |
| +0 | Function code = 8 | |
| +4 | User context word | |
| +8 | Generated link name | |
| +16 | Model link name | |
| +20 | VTAM LU name of the remote host (8 bytes) | |
| +24 | TCP/IP Internet host address (4 bytes) | |
| +28 | TCP Port Number of remote host (2 bytes) | |
| +31 | Reserved | |
| +32 | Reserved | |
| Function 12 | Immediately before disconnecting a link: | |
| +0 | Function code = 12 | |
| +4 | User context word | |
| +8 | Link name |
A user exit that compresses/decompresses or encrypts/decrypts must modify the data in the supplied conversion buffer before the data is sent or after the data is received. The user exit must not alter the original message in any manner.
The user exit should be coded to be reentrant although it is never entered more than once during the same execution. With the exception of the area in which the modified message is to be placed, the user exit must provide any storage that it requires.
At offset 4 in the parameter list is a user context word. This word is initially zeroes. The user exit may obtain a work area and place the address of this work area in the user context word. On all subsequent entries to the exit, the user context word remains intact. The user context word on one link is specific to the link and is not related to the user context word on any other link.
When the user exit is ready to accept a connect request for a dynamically added link, the exit may modify the generated link name and the model link name. The link name should be unique within the network due to difficulties in controlling links with operator commands when two or more links have the same name. The model link name must be the name of one of the model links predefined in the Entire Net-Work configuration parameters.
On return from the exit, all registers except R15 must be restored. If the exit modified the length of the message, the message length of the compressed/decompressed message must be updated in the parameter list at offset 28 (X `1C'; field name=NEUXLCNV). Register 15 must contain one of the return codes described in the following table:
| Function | Offset | Contents |
|---|---|---|
| Function 0 | Immediately before sending data: | |
| +0 | Message was not modified (default) | |
| +4 | Message was modified | |
| +8 | Do not send message | |
| +12 | Do not send/discard message and disconnect link | |
| Function 4 | Immediately after receiving data: | |
| +0 | Message was not modified (default) | |
| +4 | Message was modified | |
| +8 | Discard message | |
| +12 | Do not send/discard message and disconnect link | |
| Function 8 | Immediately before accepting a connect request from a host that has not been defined to Entire Net-Work: | |
| +0 | Accept or reject according to ACCEPTUI setting (default) | |
| +4 | Accept connection regardless of ACCEPTUI setting | |
| +8 | Reject connection regardless of ACCEPTUI setting | |
| Function 12 | Immediately before disconnecting a link: | |
| N/A | Any return code is acceptable. |
The following restrictions apply to Entire Net-Work user exits:
If a user exit is specified on the sending side of a link, an equivalent user exit must be defined on the receiving side of the link. If a link exit is not defined on the receiving side of the link, results are unpredictable and Entire Net-Work may terminate abnormally .
A user exit on the receiving side of a link that is processing a compressed or encrypted message must do one of the following:
Decompress and/or decrypt the message and return with R15 set to 4; or
Return with R15 set to 8.
Returning with R15 set to any other value causes unpredictable results; Entire Net-Work may terminate abnormally.
The user exit must not alter the original message.