Client	Version 1.3.3	HOME   UP   PREV   NEXT

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

• Compression and decompression of message data to optimize line transmission.

• Tailored statistical information gathering.

• Encryption and decryption of message data using an independent hardware or software formula.

• Control over the connection process, both inbound and outbound, based on local security requirements.

• Detection of node disconnections so that site-specific actions can be performed; for example, activation of a watchdog security function.

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

• Storing User Exit Library Files

• User Exit Processing and Functions in Windows Environments

• User Exit Processing and Functions in UNIX Environments

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.

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 Windows environments for Entire Net-Work Server: Program Files\Software AG\Entire Net-Work Server\vnn, where nn is the release number

  In Windows environments for Entire Net-Work Client: Program Files\Software AG\Entire Net-Work Client

• In UNIX environments: $SAG\ppp\vnn, where nn is the release number of Entire Net-Work Client or Entire Net-Work Server and ppp is either "wcl" (for Entire Net-Work Client) or "wcp" (for Entire Net-Work Server).

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.

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

• User Exit Control Block Structure

• Windows User Exit Responses

• Windows Tracing, Debugging. or Dumping User Exit Processing

• User Exit Windows Functions

• Windows User Exit Examples

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.

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.

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.

• XtsDump

• XtsDump_ex

• XtsTrace

• XtsDebug

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
• UE_CON_OUT Function
• UE_CON_IN Function
• UE_SEND Function
• UE_RECV Function
• UE_DISCON Function
• UE_TERM Function

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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:

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:

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
• acbx_uexit Example User Exit Files
• wcl_uexit Example User Exit Files
• Compiling the Example User Exit Files

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:

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:

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:

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

Compiling the Example User Exit Files

To compile a user exit into a user exit library in Windows environments:

• Navigate to the appropriate installation directory and enter the following command:

  nmake -f makefile

  The appropriate user exit library (*.dll file) is generated.

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

• UNIX User Exit Return Codes

• Processing

• UNIX User Exit Examples

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:

UNIX User Exit Return Codes

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

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:

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
• acbx_uexit Example User Exit Files
• wcl_uexit Example User Exit Files
• Compiling the Example User Exit Files

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:

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:

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:

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

Compiling the Example User Exit Files

To compile a user exit into a user exit library in UNIX environments:

• Navigate to the appropriate installation directory and enter the following command:

  make -f makefile.ux

  The appropriate user exit library (*.dll file) is generated.

www.softwareag.com

Copyright © 2014 Software AG, Darmstadt, Germany.

HOME   UP   PREV   NEXT