Writing notifications user exit programs

Specifying Notifications user exits in Management Console.

Notifications user exit programs must contain the following entry point (or external functions) name:

• ALRMXIT

Before active replication begins during the subscription's initialization, each Notifications user exit program is called with the CALLTYPE field of the USRALARM predefined structure set to “Initialize” (value 2). This allows each entry point to provide code to obtain resources it will require, before any replication activities have started. Such initialization processing could include obtaining virtual storage resources, opening a file, obtaining one-time information from Db2® tables, and so on.

After active replication is complete during the subscription's termination, each Notifications user exit program is called with the CALLTYPE field of the USRALARM predefined structure set to “Terminate” (value 3). This allows each entry point to provide code to release resources it required, after all replication activities have ceased. Such termination processing could release obtained virtual storage, close an opened file, and so on.

For CALLTYPE values of “Initialize” and “Terminate” (values 2 and 3), no specific message was issued or passed to the user exit program in the USRALARM and Message predefined data structures.

While active replication is ongoing, each Notifications user exit program is called with the CALLTYPE field of the USRALARM predefined structure set to “Process” (value 1). This indicates that the Notifications user exit program is being called for its processing purpose, and that a message will be issued and is being passed to the user exit program in the USRALARM and Message predefined data structures.

It can be seen from the paragraphs above that each exit is called at least twice. For instance, if a Notifications user exit is specified, it is called twice even if there were no messages generated in the alarmed category between the times that the subscription was started and stopped. You must provide code in a Notifications user exit for detecting and processing the “Initialize” and “Terminate” values of the CALLTYPE field of the USRALARM predefined structure, otherwise the result will be unpredictable, and the Notifications user exit program could abnormally terminate.

When a Notifications user exit completes its processing, in addition to any action taken during processing, the user exit program that you write must pass back a return code to InfoSphere® CDC. This return code is the value returned by a program/function call. In the COBOL language, the return code is stored in the RETURN-CODE special register before the GOBACK statement for the program is executed. In C language, the return code is provided as the value of a return statement. In Assembly Language, the return code is provided as the value of the RC keyword in the RETURN macro instruction. InfoSphere CDC recognizes the following return codes and responds as indicated in the following table:

Notifications user exit programs cannot issue any SQL statements. Any attempt to do so will result in the abnormal termination of the user exit program.

The USERDATA field in the USRDATA predefined structure (see USRALARM Structure) is meant to be used by the user exits as a common resource field. It is defined in COBOL as a POINTER, in C as a void *, and in Assembly Language as an A-con. Initially, when the subscription starts, this field has all bits reset, which is equivalent to the POINTER value NULL/NULLS in COBOL or the pointer value NULL in C. The content of this field is never accessed or altered by InfoSphere CDC after the subscription has started. The content of this field is passed to all the Notifications user exits within a subscription. Each user exit receives the contents of this field as they were when the previously called user exit returned control to InfoSphere CDC. The first user exit to receive control within the subscription can initialize the USERDATA field. For example, the first user exit to receive control can store a pointer to acquired storage in this field, and the acquired storage can be used to convey data and communicate status to subsequent calls of any of the provided Notifications user exits in the subscription. It is the responsibility of the user exits to release any resources they acquire before a subscription ends.

Because all Notifications user exits are driven by the single task that implements the Product Administration Log process for a subscription within InfoSphere CDC, the Notifications user exits will be driven consecutively, and no two Notifications user exits will ever receive control concurrently within the same subscription. This effectively enforces a serialization on the content of the USERDATA field, and any user exit can examine and modify the content of the USERDATA field (or whatever data structure to which it points) without concern for serializing the accesses.

Any activity within a notifications user exit that involves “blocking” services or suspending execution (for example, issuing an Assembly Language WAIT macro instruction), will suspend the entire Product Administration Log process, and delay the InfoSphere CDC address space, including all the subscriptions. Try to design the Notifications user exits to minimize or eliminate the use of such services.

Notifications user exits must be coded, compiled and link-edited as reentrant programs. This is generally as simple as specifying the RENT option for the compiler and the linkage editor. If an exit is written in Assembly Language, specific design and coding accommodations are required to produce reentrant code. If InfoSphere CDC loads a Notifications user exit and detects that it is not marked as reentrant by the linkage editor, then initialization of the associated subscription will fail and the subscription will terminate. If a Notifications user exit is marked reentrant by the linkage editor but is actually not executing according to the requirements of reentrancy, then unexpected errors can result, including the failure of the Notifications user exit, or corruption of the data being passed to the Notifications user exit.

During development and testing, and sometimes during production execution, user-written notifications user exits may experience error conditions that result in an abnormal termination. For example, a Notifications user exit may attempt to store data into a virtual storage area using a storage reference pointer, but inadvertently, the storage reference pointer contains the NULL pointer value. This will result in an ABEND S0C4 (General Protection Fault). Normally, InfoSphere CDC intercepts all abnormal terminations that arise from within Notifications user exits. InfoSphere CDC then issues an explanatory message to the Event Log and CHCPRINT spooled output data set, and terminates the subscription that called the failing Notifications user exit. Based on the Language Environment® options provided to the InfoSphere CDC address space, LE may produce a diagnostic printout of the intercepted error, or permit a dump of the address space at the time of the error to occur. It is also possible to specify Language Environment options that inhibit InfoSphere CDC from intercepting such catastrophic errors. In this case, the catastrophic error is elevated to InfoSphere CDC itself, and the entire InfoSphere CDC address space may fail. It is your responsibility to locate and fix any errors in their Notifications user exits. Judiciously specified Language Environment options, coupled with diagnostic tests and messages issued from within the Notifications user exit can be helpful in achieving this goal. The Language Environment options that disable the interception of abnormal terminations within the Language Environment enclave should not be used unless for a specific issue and in a controlled environment.