Client Version 1.3.3
 —  Installation and Administration  —

Using the Entire Net-Work User Exit Interface

The Entire Net-Work user exit interface supports the implementation of user-written programs that perform the following types of functions:

Entire Net-Work user exits can be implemented on all open systems platforms where Entire Net-Work is supported. Compiled user exit code is placed in a library where it can be accessed by Entire Net-Work when required.

This document covers the following topics:


Writing User Exits

User exits must be written in C and must use C calling conventions. If you wish, you can use the files from the supplied user exit examples as a basis.

Note the following additional restrictions, when writing your own user exit:

  1. The destination buffer cannot be larger than the source buffer. Therefore, a message that is compressed or encrypted by a user exit must not exceed the size of the original message.

  2. Data that has been modified by a user exit must be restored to its original form before being processed again by another Entire Net-Work Client node. For example, if you use a user exit to encrypt a message sent from an Entire Net-Work Client, you must use a corresponding user exit to decrypt the message before it can be processed by another server.

Once your user exit has been written, it and any files it requires must be built and compiled into a user exit library (a DLL file) on Windows systems or a shared library on UNIX systems before Entire Net-Work Client can use it. Entire Net-Work Kernel and Entire Net-Work Client configurations reference user exit DLL file or shared library names in their definitions.

Top of page

Storing User Exit Library Files

Windows compiled user exit libraries (DLL files) or UNIX user exit shared libraries should be stored in the installation directory wherever the other executable and library files for Entire Net-Work Server or Entire Net-Work Client are installed (as appropriate for the user exit). By default, Entire Net-Work Server and Entire Net-Work Client user exit files should be stored in one of the following locations:

In addition, user exit libraries should be stored in the root directory; they should not be stored in the examples subdirectory of the Entire Net-Work Client installation.

Important:
It is a good idea to keep copies of your user exit libraries in a separate location from your Entire Net-Work installations.

Top of page

User Exit Processing and Functions in Windows Environments

Entire Net-Work provides a user exit entry point (UE_Y) for every Entire Net-Work Kernel definition and every Entire Net-Work Client configuration. This user exit entry point is called from the transport layer protocol. At various times during processing, Entire Net-Work calls the user exit, passing it a structure that contains a function code and various optional data elements. The user exit program performs the desired function and returns a success or error indicator to Entire Net-Work.

Note:
Modification of data traffic (compression or encryption) requires processor cycles on both sending and receiving nodes. The User Exit Facility may be unsuitable in situations where processor performance is critical. Its use on relay nodes is not recommended.

This section covers the following topics:

Calling the User Exit

The syntax of a user exit call in Windows environments is:

LONG UE_Y(pUEYCB_control)

where pUEYCB_control is a pointer to the user exit control block (UEYCB).

User Exit Control Block Structure

The following table describes the user exit control block (UEYCB). For a full description of UEYCB, review the example user exit file user_exit.h, as described in Windows User Exit Examples. Each user exit function must comply with this control block structure.

Element Type Description
Function byte The name of user exit function being processed by the call. Valid values include "UE_INIT", "UE_CON_OUT", "UE_CON_IN", "UE_SEND", "UE_RECV", "UE_DISCON", and "UE_TERM". For more information about each of these functions, read User Exit Functions.
LineDriver byte The name of the transport protocol used by the call. At this time, the only valid value is "UE_D_TCP", indicating that TCP/IP is used.
Source pvoid The pointer to the source buffer; that is, the buffer used to contain the data to be processed by the user exit.
Slen long The size of the source buffer, which equals the length of the source data.
Dest pvoid The pointer to the destination buffer; that is, the buffer used to return data that has been modified by the user exit. Entire Net-Work is responsible for allocation and management of this buffer. The user exit should not attempt to free it.
Context dword A unique identifier supplied by Entire Net-Work for each connection.
Length long The length of the modified data message in the destination buffer.
MaxLength long The maximum size of the destination buffer. The destination buffer cannot be larger than the size of the source buffer.
Domain[6+1] char Not used.
Host[8+1] char Not used.
Argument pvoid Not used.
LD_Data pvoid Not used.
Model pvoid Not used.

Note:
The user exit must not modify the contents of the Context element in the control block. It will be required for later use in send/receive calls. For an example of a user exit source code file, review the supplied example file user_exit.c, described in Windows User Exit Examples.

Windows User Exit Responses

The response from the user exit may include one of the return codes described in the table below. The specific meaning of these return codes varies, based on the user exit function you are trying to perform. To interpret these return codes, read about the user exit function you are using in User Exit Functions.

Response Description
UE_DATAOUT The user exit function processes a modified data message in an intermediate buffer. The control block's Length element contains the length of this message.
UE_FAILURE The user exit function fails and a message is written to the log file.
UE_RESTRICT The user exit connection is allowed to continue to function on a restricted basis (only the UE_DISCON function is enabled for the exit).
UE_SUCCESS The requested user exit function is successful.

Windows Tracing, Debugging. or Dumping User Exit Processing

You can include any trace, debug, or dump information pertaining to your user exit in the Entire Net-Work log file. To do this, use one of the following Software AG Transport Subsystem trace functions listed in the user exit file user_exit.h, as described in Windows User Exit Examples. Each user exit function must comply with this control block structure.

In addition to using any of these functions in your user exit, you should be sure to include the xts2.lib file in your user exit library. If you do not, the trace, debug, or dump processing will not occur. The xts2.lib file is supplied in the sample user exit supplied with Entire Net-Work. For more information, read Windows User Exit Examples

If you need additional assistance with tracing, debugging, or dumping your user exit processing, contact your Software AG technical support representative.

User Exit Windows Functions

This section describes the available user exit functions, in order of normal use.

UE_INIT Function

The UE_INIT function is called once during Entire Net-Work startup (before remote connections are enabled) to allow the user exit to allocate resources for this session of Entire Net-Work and to describe its capabilities to Entire Net-Work. Software AG strongly recommends that a reason message be written to the log file if an initialization attempt fails.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_INIT
LineDriver Zero
Source NULL
Slen Zero
Dest NULL
Context Zero
Length Zero
MaxLength Zero
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

The user exit should supply one of the following return codes to indicate processing results:

Response Description
UE_FAILURE Enable all future user exit calls.
UE_SUCCESS Disable all future user exit calls (including UE_TERM) and write a message to the log file.

UE_CON_OUT Function

The UE_CON_OUT function is called once for each outbound connection attempt. The user exit can accept the connection attempt, accept the connection but restrict user exit functions, or reject the connection and terminate the connection process.

Software AG strongly recommends that a reason message be written to the log file if a connection attempt is rejected. Because rejection of an outbound connection attempt is unlikely, this function is normally used to allocate statistical recording memory and other resources. It is also the point at which DES encryption hardware is allocated, if it is being used.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_CON_OUT
LineDriver Protocol type
Source NULL
Slen Zero
Dest NULL
Context Non-zero
Length Zero
MaxLength Zero
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

The user exit should supply one of the following return codes to indicate processing results:

Response Description
UE_FAILURE Terminate the connection process and a write a message to the log file.
UE_RESTRICT Continue the connection process on a restricted basis and enable the exit for UE_DISCON functions, but not for the UE_SEND or UE_RECV functions.
UE_SUCCESS Continue the connection process and enable this exit for UE_SEND, UE_RECV, and UE_DISCON functions for this node.

UE_CON_IN Function

The UE_CON_IN function is called during inbound connection processing. The user exit can accept the connection, accept the connection but restrict user exit functions, or reject the connection for security reasons.

Software AG strongly recommends that a reason message be written to the log file if a connection attempt is rejected. If the connection is accepted, the user exit should allocate the resources and memory required for the connection.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_CON_IN
LineDriver Protocol type
Source NULL
Slen Zero
Dest NULL
Context Non-zero
Length Zero
MaxLength Zero
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

The user exit should supply one of the following return codes to indicate processing results:

Response Description
UE_FAILURE Reject the connection and write a message to the log file.
UE_RESTRICT Accept the connection on a restricted basis and enable the user exit for UE_DISCON functions, but not for UE_SEND or UE_RECV functions.
UE_SUCCESS Accept the connection and enable the user exit for UE_SEND, UE_RECV, and UE_DISCON functions.

UE_SEND Function

The UE_SEND function is called before a data message is transmitted to a remote node. The user exit can send the message, modify the message before sending it, or reject the message and force disconnection of the node. Software AG strongly recommends that a reason message be written to the log file if the message is rejected.

UE_INIT and either UE_CON_IN or UE_CON_OUT must have been successful (returned response "UE_SUCCESS") for this node before the UE_SEND function can be run.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_SEND
LineDriver Protocol type.
Source Pointer to the source buffer containing the data message to be transmitted.
Slen Length of the source data.
Dest Pointer to the destination buffer.
Context Unique connection ID supplied by Entire Net-Work during the connection.
Length Zero (see the "UE_DATAOUT" return code)
MaxLength Maximum size of the user exit buffer.
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

The user exit should supply one of the following return codes to indicate processing results:

Response Description
UE_DATAOUT Send the modified data message in the destination buffer. The Length element contains the length of the message.
UE_FAILURE Reject the message, force a disconnection of the node, and write a message to the log file.
UE_SUCCESS Send the unmodified source data.

UE_RECV Function

The UE_RECV function is called when a data message that was modified before transmission arrives from a remote node. The user exit can accept the message for processing, modify the message, or discard the message and force disconnection of the node. Software AG strongly recommends that a reason message be written to the log file if the message is discarded.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_RECV
LineDriver Protocol type
Source Pointer to the buffer containing the data message received.
Slen Length of the data received.
Dest Pointer to the user exit buffer, which contains the data message when and if it is modified by the user exit.
Context Unique connection ID supplied by Entire Net-Work during the connection.
Length The original message length (see the UE_DATAOUT return code).
MaxLength The maximum size of the user exit buffer.
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

The user exit should supply one of the following return codes to indicate processing results:

Response Description
UE_DATAOUT Process the modified message contained in the user exit buffer. The Length element contains the length of the message.
UE_FAILURE Discard the message, force the disconnection of the node, and write a message to the log file.
UE_SUCCESS Continue processing the source data.

UE_DISCON Function

The UE_DISCON function is called once immediately after a node is disconnected for any reason. The user exit can release resources allocated during a connection call, log statistical information, and initiate actions to reestablish the connection (activate a watchdog security function).

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_DISCON
LineDriver Protocol type
Source NULL
Slen Zero
Dest NULL
Context Unique connection ID supplied by Entire Net-Work during the connection.
Length Zero
MaxLength Zero
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

Return codes for the UE_DISCON function are ignored.

UE_TERM Function

The UE_TERM function is called once during Entire Net-Work shutdown processing. It allows the user exit to release resources allocated during UE_INIT function processing and to log statistical data prior to shutdown.

Prior to user exit processing, the contents of the UEYCB elements should be:

pUEYCB Contents
Function UE_TERM
LineDriver Zero
Source NULL
Slen Zero
Dest NULL
Context Zero
Length Zero
MaxLength Zero
Domain not applicable
Host not applicable
Argument not applicable
LD Data not applicable
Model not applicable

Return codes for the UE_TERM function are ignored.

Windows User Exit Examples

The Entire Net-Work Client installation kit includes several example user exits in a series of subdirectories in the examples subdirectory:

Subdirectory Contains
acb_uexit An ADALNK user exit. This user exit is called before an Adabas call is processed (ADALNK interface) and it rejects all Adabas operator calls whose user is not SAG. In addition, it blocks N1/N2 and A1 commands for the user SAG. Response code 22 is set when any of these call restrictions in encountered.
acbx_uexit An ADALNKX user exit. This user exit is called before an Adabas call is processed (ADALNKX interface) and it rejects all Adabas operator calls whose user is not SAGPC. In addition, it blocks N1/N2 and A1 commands for the user SAGPC. A return value of ADA_UEXREJ is set when any of these call restrictions in encountered.
adaesi_uexit An External Security Interface (ESI) user exit you can use to modify the method used to encrypt and decrypt the ESI logon dialog information, read .
adasaf_uexit An External Security Interface (ESI) user exit you can use to access secured Adabas resources on a z/OS host node. For more information, read .
wcl_uexit An example user exit and a shared library stub. These are provided to assist you in creating and implementing your user exit program.

The remainder of this section describes the files and compilation method you can use to create and compile your own user exit, based on the files in the wcl_uexit subdirectory.

acb_uexit Example User Exit Files

The examples/acb_uexit subdirectory contains all of the necessary source code files to make a working example of an ADALNK user exit program, as described in the following table:

File Name Description
adabas.h Adabas call resource file. This file lists resources files that should be included when the user exit is compiled.
adabasx.h Adabas call control block file.
lnkuex.c ADALNK user exit source code file.
lnkuex.h ADALNK user exit control block layout file.
makefile C program to be run in Windows and used to create the user exit library from the files in the user exit source code library.
makefile.ux C program to be run in UNIX and used to create the user exit library from the files in the user exit source code library.
mk.bat A batch file that runs nmake on the makefile file.

You can use these files as a model for writing your own ADALNK user exit programs. The supplied ADALNK user exit program is called before an Adabas call is processed (ADALNK interface) and it rejects all Adabas operator calls whose user is not SAG. In addition, it blocks N1/N2 and A1 commands for the user SAG. Response code 22 is set when any of these call restrictions in encountered.

acbx_uexit Example User Exit Files

The examples/acbx_uexit subdirectory contains all of the necessary source code files to make a working example of an ADALNKX user exit program, as described in the following table:

File Name Description
adabas.h Adabas call resource file. This file lists resources files that should be included when the user exit is compiled.
adabasx.h Adabas call control block file.
lnkuexacbx.c ADALNKX user exit source code file.
lnkuexacbx.h ADALNKX user exit control block layout file.
makefile C program to be run in Windows and used to create the user exit library from the files in the user exit source code library.
makefile.ux C program to be run in UNIX and used to create the user exit library from the files in the user exit source code library.
mk.bat A batch file that runs nmake/make on the makefile file.

You can use these files as a model for writing your own ADALNKX user exit programs. The supplied ADALNKX user exit is called before an Adabas call is processed (ADALNKX interface) and it rejects all Adabas operator calls whose user is not SAGPC. In addition, it blocks N1/N2 and A1 commands for the user SAGPC. A return value of ADA_UEXREJ is set when any of these call restrictions in encountered.

wcl_uexit Example User Exit Files

The examples/wcl_uexit subdirectory contains all of the necessary source code files to make a working example of a user exit program, as described in the following table:

File Name Description
user_exit.c User exit source code file.
user_exit.rc User exit stub resource file. This file lists resource files that should be included when the user exit is compiled.
user_exit.def User exit module definition file.
user_exit.h User exit control block layout file.
makefile C program used to create the user exit library from the files in the user exit source code library.
xts2.lib If you need to make use of the Software AG transport subsystems's dump, trace and debug facilities in your code, include this file in your user exit library.

You can use these files as a model for writing your own user exit programs.

Compiling the Example User Exit Files

Start of instruction setTo compile a user exit into a user exit library in Windows environments:

Top of page

User Exit Processing and Functions in UNIX Environments

The UNIX user exit shared library must contain an entry point, "ph_uexit", that will be called by the protocol handler processes.

This section covers the following topics:

Calling the User Exit

The syntax of a user exit call in UNIX environments is:

int ph_uexit (int fct_id, char *source, int slen, char *dest, int dlen);

Note:
The shared library's entry point function must be "ph_uexit".

This syntax uses the following call parameters and return codes:

Parameter Description
int fct_id The number of the user exit function to be run. Current valid values for fct_id are:
  • 0: The user exit is called by the send process before sending a buffer.

  • 1: The user exit is called by the receive process after receiving a buffer.

.
char *source The pointer to the source buffer. The source buffer contains either original data to be sent or data just received.
int slen The number of bytes in the source buffer.
char *dest The pointer to a free (destination) buffer to be used by the requested user exit function to store the manipulated data from the source buffer.
int dlen The size of the destination buffer (which must equal the length of the original message).

UNIX User Exit Return Codes

The response from the user exit may include one of the return codes described in the table below.

Value Description
-1 An error occurred. The user exit call failed.
Anything greater than 0 (>0) The user exit call was successful. The return value is the length of the data in the destination buffer.

Processing

If user exit usage is enabled, the ph_uexit function is called by the protocol handler processes either just before starting to send a data buffer to a remote node or just after receiving a data buffer from a remote node. The protocol handler provides the data to be manipulated by the user exit in the buffer referenced by the source pointer, and expects the user exit's output to be in the buffer referenced by the destination pointer. The sizes of these buffers is passed to the user exit in the slen or dlen parameters, as appropriate. The user exit routines must ensure that there is no address violation when accessing these buffers.

On successful completion of the user exit call, the ph_uexit routine must return the length of data put into the destination buffer. If an error occurs, ph_uexit must return -1 to indicate the failure to the calling protocol handler processes.

When the ph_uexit routine is called during send processing, and a value greater than zero (0) is returned, the information from the destination buffer with the length returned by the ph_uexit is sent instead of the information in the source buffer. At the remote (destination) node, the user exit will be called for this buffer.

UNIX User Exit Examples

The Entire Net-Work Client installation kit includes several example user exits in a series of subdirectories in the examples subdirectory:

Subdirectory Contains
acb_uexit An ADALNK user exit. This user exit is called before an Adabas call is processed (ADALNK interface) and it rejects all Adabas operator calls whose user is not SAG. In addition, it blocks N1/N2 and A1 commands for the user SAG. Response code 22 is set when any of these call restrictions in encountered.
acbx_uexit An ADALNKX user exit. This user exit is called before an Adabas call is processed (ADALNKX interface) and it rejects all Adabas operator calls whose user is not SAGPC. In addition, it blocks N1/N2 and A1 commands for the user SAGPC. A return value of ADA_UEXREJ is set when any of these call restrictions in encountered.
adasaf_uexit An External Security Interface (ESI) user exit you can use to access secured Adabas resources on a z/OS host node. For more information, read .
wcl_uexit An example user exit and a shared library stub. These are provided to assist you in creating and implementing your user exit program.

The remainder of this section describes the files and compilation method you can use to create and compile your own user exit, based on the files in the wcl_uexit subdirectory.

acb_uexit Example User Exit Files

The examples/acb_uexit subdirectory contains all of the necessary source code files to make a working example of an ADALNK user exit program, as described in the following table:

File Name Description
adabas.h Adabas call resource file. This file lists resources files that should be included when the user exit is compiled.
adabasx.h Adabas call control block file.
lnkuex.c ADALNK user exit source code file.
lnkuex.h ADALNK user exit control block layout file.
makefile C program to be run in Windows and used to create the user exit library from the files in the user exit source code library.
makefile.ux C program to be run in UNIX and used to create the user exit library from the files in the user exit source code library.
mk.bat A batch file that runs nmake on the makefile file.

You can use these files as a model for writing your own ADALNK user exit programs. The supplied ADALNK user exit program is called before an Adabas call is processed (ADALNK interface) and it rejects all Adabas operator calls whose user is not SAG. In addition, it blocks N1/N2 and A1 commands for the user SAG. Response code 22 is set when any of these call restrictions in encountered.

acbx_uexit Example User Exit Files

The examples/acbx_uexit subdirectory contains all of the necessary source code files to make a working example of an ADALNKX user exit program, as described in the following table:

File Name Description
adabas.h Adabas call resource file. This file lists resources files that should be included when the user exit is compiled.
adabasx.h Adabas call control block file.
lnkuexacbx.c ADALNKX user exit source code file.
lnkuexacbx.h ADALNKX user exit control block layout file.
makefile C program to be run in Windows and used to create the user exit library from the files in the user exit source code library.
makefile.ux C program to be run in UNIX and used to create the user exit library from the files in the user exit source code library.

You can use these files as a model for writing your own ADALNKX user exit programs. The supplied ADALNKX user exit is called before an Adabas call is processed (ADALNKX interface) and it rejects all Adabas operator calls whose user is not SAGPC. In addition, it blocks N1/N2 and A1 commands for the user SAGPC. A return value of ADA_UEXREJ is set when any of these call restrictions in encountered.

wcl_uexit Example User Exit Files

The examples/wcl_uexit subdirectory contains all of the necessary source code files to make a working example of a user exit program, as described in the following table:

File Name Description
user_exit.c User exit source code file
user_exit.h User exit control block layout file
makefile.ux C program used to create the user exit library from the files in the user exit source code library.

You can use these files as a model for writing your own user exit programs.

Compiling the Example User Exit Files

Start of instruction setTo compile a user exit into a user exit library in UNIX environments:

Top of page