All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used:

• - to help implement/run third party Java ORB libraries, and
• - for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

Introduction

The BEA Tuxedo CORBA Notification Service is layered on the BEA Tuxedo EventBroker and Queuing systems. This means that administering the CORBA Notification Service requires that you also administer these other BEA Tuxedo systems. You use the BEA Tuxedo utilities tmadmin, qmadmin, and ntsadmin to administer the Notification Service.

Notification Service administration is comprised of two related tasks: configuration and management. Although these areas are discussed separately, they are in fact, interrelated. Thus, to fully understand configuration, you must also understand management and vice versa.

Configuring the Notification Service

Before you can run event Notification Service applications, the following configuration requirements must be satisfied:

• If data filtering or BEA Tuxedo ATMI interoperability is to be used, create BEA Tuxedo ATMI FML field definition files that describe the fields on which to filter or to interoperate.
• If persistent subscriptions are to be used:
• If using a a joint client/server, set the host and port number for the callback object references.
• Create a transaction log.
• Create queues to hold events.
• Create a system configuration file (UBBCONFIG) and a TUXCONFIG file.

Configuring Data Filters

If data filtering or BEA Tuxedo ATMI interoperability is used in subscriber applications, you must perform the following steps to use data filtering in subscriptions:

Create the BEA Tuxedo ATMI FML field table definition file that describes the fields on which to filter (see Listing 7-2).
In the UBBCONFIG file, specify where the FML field table definition file is located so that when the application is started, the location of field definition files is passed to the Notification Service servers (see Listing 7-3).

In Listing 7-1, the code that is shown in bold text shows how the data filtering is implemented in an event poster application. Only subscriptions that contain the name/value pair billing and patient_account will receive the event.

Listing 7-1 Sample Data Filtering Using the BEA Simple Events API (C++)

CosNotification::StructuredEvent notif;

notif.header.fixed_header.event_type.domain_name =
       CORBA::string_dup("HEALTHCARE");

notif.header.fixed_header.event_type.type_name =
       CORBA::string_dup("HMO");

// Specify an additional filter, based upon name and value 
// for this event.

notif.filterable_data.length(2);
notif.filterable_data[0].name = CORBA::string_dup("billing");
notif.filterable_data[0].value <<= CORBA::Long(1999);
notif.filterable_data[1].name =
          CORBA::string_dup("patient_account");
notif.filterable_data[1].value <<= CORBA::Long(2345);

// Push the structured event onto the channel.
testChannel->push_structured_event(notif);

Listing 7-2 shows the FML field table definitions file needed to use data filtering.

Listing 7-2 Data Filtering FML Field Table File

*base 2000

#Field Name      Field #  Field Type    Flags     Comments
#-----------     -------  ----------    ------    --------
billing          1        long          -         -
patient_account  2        long          -         -

Listing 7-3 shows the content of environment variable file (envfile). The envfile contains the location of the FML field definitions file.

Note: You can name the environment variable file whatever you want, but the name used must match the name specified for the ENVFILE configuration option n, the SERVERS section of the UBBCONFIG file.

Listing 7-3 Envfile Specification for Data Filtering (envfile) (Microsoft Windows)

FLDTBLDIR32=D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_cxx\common
FIELDTBLS32=news_flds

Listing 7-4 shows, in bold text, how the location of the FML field table file is specified in the UBBCONFIG file for the Advanced samples.

Listing 7-4 Specifying the FML Field Definitions File in the UBBCONFIG File

*SERVERS
TMSYSEVT
  SRVGRP  = NTS_GRP
  SRVID   = 1
TMUSREVT
  SRVGRP  = NTS_GRP>>$@
  SRVID   = 2
  ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
TMNTS
  SRVGRP = NTS_GRP
  SRVID = 3 
   ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
  CLOPT = "-A -- -s TMNTSQS"
TMNTSFWD_T
  SRVGRP = NTS_GRP
  SRVID = 4 
  ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
TMNTSFWD_P
  SRVGRP = NTS_GRP
  SRVID = 5 
  ENVFILE = "D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"

Setting the Host and Port

The object references host and port number requirements for the callback object are as follows:

• For transient callback objects, any port is sufficient and can be obtained dynamically by the ORB.
• For persistent callback objects, the ORB must be configured to accept requests for the callback object on the same port on which the object reference for the callback object was created.

You specify the port number from the user range of port numbers, rather than from the dynamic range. Assigning port numbers from the user range prevents joint client/server applications from using conflicting ports.

The method you use to set the host and port depends on the programming language you are using.

• Setting Host and Port on C++ Subscriber Applications

For C++ subscriber applications, to specify a particular port for the joint client/server application to use, include the following on the command line that starts the process for the joint client/server application:

-ORBport nnnn -IRBid BEA_IIOP

where nnnn is the number of the port to be used by the ORB when creating invocations and listening for invocations on the callback object in the joint client/server application.

Use this command when you want the object reference for the callback object in a joint client/server application to be persistent and when you want to stop and restart the joint client/server application. If this command is not used, the ORB uses a random port. If a random port is used when the joint client/server application is stopped and then restarted, invocations to persistent callback objects in the joint client/server application will fail.

The port number is part of the input to the argv argument of the CORBA::orb_init member function. When the argv argument is passed, the ORB reads that information, establishing the port for any object references created in that process.

Creating a Transaction Log

When you use persistent subscriptions, you must configure and boot the BEA Tuxedo queuing system. The queuing system requires a transaction log. Listing 7-5 shows how to use the tmadmin utility to create a transaction log.

Listing 7-5 Creating a Transaction Log (createtlog) (Microsoft Windows)

>tmadmin

>crdl -b 100 -z D:\tuxdir\EVENTS_Samples\ADVANCED_Simple_CXX\TLOG
>crlog -m SITE1
>quit
>

Creating Event Queues

When you use persistent events, you must configure and boot the BEA Tuxedo queuing system. Two event queues must be created:

• TMNTSFWD_P

This is the event forwarding queue for persistent subscriptions. Events go to this queue first and then are forwarded to matching persistent subscriptions. If an event cannot be delivered on the first attempt, it is held in this queue and repeated attempts are made to deliver it. If the settable retry limit is reached before the event can be successfully delivered, the event is moved to the error queue.

This queue requires the following configuration parameters:

• Queuing order (for example, first in, first out).
• How to handle out-of-order enqueuing.
• Retry limit (how many retries before moving the event to the error queue).
• Retry time interval.
• How full the queue can get before administrative intervention is required.
• How low the queue can get after getting full before administrative intervention is required.
• Definition of the administrative intervention command.
• TMNTSFWD_E

This is the error queue. This queue receives events from the TMNTSFWD_P queue that cannot be delivered to subscriptions. This queue requires the same configuration parameters as the TMNTSFWD_P forwarding queue, however, the retry limit and retry time interval parameters are irrelevant because this is the error queue and errors are only removed by administrative intervention.

To configure these queues, perform the following steps:

Create a device on disk for the queue space.
Configure a queue space.
Create the queues.

These steps are described in the following sections.

Determining Space Parameters for Transient and Persistent Subscriptions

To tune your system for maximum performance, you should determine the optimal values for the following parameters:

• The number of transient forwarding servers (TMNTSFWD_T) and persistent forwarding servers (TMNTSFWD_P).
• IPC queue space (this is used for transient subscriptions).
• Size of /Q queues (this is used for persistent subscriptions).

IPC Queue Space for Transient Subscriptions

Proceed as follows to determine space parameters for transient subscriptions:

Determine how many events may be in the pipeline for transient subscriptions; that is, how many events may be in the process of being delivered at any given time. This equals the number of events multiplied by the number of subscribers receiving them.
Determine the size of your events. For purposes of this discussion, we will assume that they are relatively small—about 300 bytes or less.
Determine how many transient forwarding servers you would like to start, most likely one or two—one per processor on your machine is a good number to start with.
Determine how much IPC queue space you will need to hold your transient events. The amount of space you need is 1000 bytes multiplied by the number of events you allow in the pipeline. Divide this number by the number IPC queues your transient forwarders have. If you use MSSQ sets, then your transient forwarders share one IPC queue; if you do not, then each forwarder has its own IPC queue.

For example, if you estimate that there will be 10 events delivered to 50 subscribers in the pipeline, and you start 2 transient forwarders and they do not share an IPC queue (that is, you do not use MSSQ sets), the amount of IPC queue space you need is:

10 events * 50 subscribers * 1000 bytes / 2 forwarders = 250,000 bytes

Configure the IPC queue size to that number by changing the entries in the system registry. How you do this is platform-specific.
• For Microsoft Windows systems, see Setting IPC Parameters on Microsoft Windows.
• For UNIX systems, refer to the system reference manual supplied with the system.

/Q Queue Size Parameter Persistent Subscriptions

Proceed as follows to determine space parameters for persistent subscriptions:

Determine how many events may be in the pipeline for persistent subscriptions; that is, how many events may be in the process of being delivered at any given time. This equals the number of events multiplied by the number of subscribers receiving them.
Determine the size of your events. For purposes of this discussion, we will assume that they are relatively small—about 300 bytes or less.
Determine the size your /Q queues need to be to hold your persistent events (both for your pending queue and error queue). Proceed as follows to do this:
Determine the size of a disk page. This is platform-specific. For example, on Microsoft Windows, a disk page is 500 bytes. On UNIX machines, a disk page could range from 500 to 4000 bytes in size.
Determine how many disk pages you will need to store one event rounding up. For example, if you need 1000 bytes per event and disk pages are 500 bytes, you will need 2 disk pages per event.
Determine how many disk pages you will need for your events. For example, if you want to allow 500 pending events and 200 error events, and an event takes up 2 disk pages, you will need 1400 disk pages.
Determine how many disk pages you will need for your qspace. This is the number of disk pages you need for your events plus some pages for qspace overhead. For example, if you need 1400 disk pages for events, then your qspace needs approximately 1450 disk pages (50 pages of qspace overhead).
Determine how many pages you will need for your qspace device. This is the number of pages you need for the qspace plus some pages for device overhead. For example, if you need 1450 disk pages for your qspace, then your device needs approximately 1500 pages (50 pages of device overhead).
When you use qmadmin to create the qspace for your persistent events, the first phase is to create a device. Use the size computed above in step 3e above (approximately 1500 pages). Next, specify the size of the qspace. Use the size computed in step 3d (approximately 1450 pages). Next, specify how many events can be in the pending queue and how many events can be in the error queue. The following sections explain how to create and configure qspaces.

Creating a Device on Disk for the Queue Space

You use the qmadmin command utility to create a device on disk for the queue space.

Before you create a queue space, you must create an entry for it in the universal device list (UDL). Listing 7-6 shows an example of the commands.

Listing 7-6 Creating a Device on Disk for Queue Space (UNIX)

prompt>qmadmin d:\smith\reg\QUE
qmadmin - Copyright (c) 1996-1999 BEA Systems, Inc.
Portions * Copyright 1986-1997 RSA Data Security, Inc.
All Rights Reserved.
Distributed under license by BEA Systems, Inc.
BEA Tuxedo is a registered trademark.
QMCONFIG=d:\smith\reg\QUE

> crdl d:\smith\reg\QUE 0 1100
Created device d:\smith\reg\QUE, offset 0, size 1100
 on d:\smith\reg\QUE

For more information about creating a device on disk, see Using the ATMI /Q Component.

Configuring a Queue Space

You use the qmdamin qspacecreate command to configure queue spaces. A queue space makes use of IPC resources; therefore, when you define a queue space you are allocating a shared memory segment and a semaphore. The easiest way to use the qspacecreate command is to let it prompt you. Listing 7-7 shows an example queue space that is configured for the Advanced sample application.

Listing 7-7 Creating Queue Space

> qspacecreate
Queue space name: TMNTSQS
IPC Key for queue space: 52359
Size of queue space in disk pages: 1050
Number of queues in queue space: 2
Number of concurrent transactions in queue space: 10
Number of concurrent processes in queue space: 10
Number of messages in queue space: 500
Error queue name: TMNTSFWD_E
Initialize extents (y, n [default=n]): y
Blocking factor [default=16]:

In the queue space created in Listing 7-7, take note of the following size settings:

Number of messages in queue space:500

Setting this parameter to 500 allows room for a total of 500 events in the pending and error queues.

Size of queue space in disk pages:1050

On Microsoft Windows, each disk page is 500 bytes and each event needs 1000 bytes. In addition, you must allow 2 disk pages per event. Since you estimate that there will be 500 events in the pending and error queues, then you must allow 1000 disk pages to store them (500 * 2). Also, you must allow 50 disk pages for qspace overhead, so the qspace size is set to 1050 disk pages. Finally, the device needs 50 disk pages of overhead too, so the device size is 1100 disk pages, which you set using the crdl command (see Listing 7-6).

For more information about creating queue space, see Using the ATMI /Q Component.

Creating the Queues

You must use the qmadmin qcreate command to create each queue that you intend to use. Before you can create a queue, you first have to open the queue space with the qmadmin qopen command. If you do not provide a queue space name, qopen will prompt for it.

Listing 7-8 shows an example of creating the TMNTSFWD_P and TMNTSFWD_E queues that are created for the Advanced sample application.

Listing 7-8 Creating Queues

> qopen
Queue space name: TMNTSQS

> qcreate
Queue name: TMNTSFWD_P
Queue order (priority, time, fifo, lifo): fifo
Out-of-ordering enqueuing (top, msgid, [default=none]): none
Retries [default=0]: 5
Retry delay in seconds [default=0]: 3
High limit for queue capacity warning (b for bytes used, B for
 blocks used, % for percent used, m for messages [default=100%]):
 80%
Reset (low) limit for queue capacity warning [default=0%]: 0%
Queue capacity command:
No default queue capacity command
Queue 'TMNTSFWD_P' created

> qcreate
Queue name: TMNTSFWD_E
Queue order (priority, time, fifo, lifo): fifo
Out-of-ordering enqueuing (top, msgid, [default=none]): none
Retries [default=0]: 2
Retry delay in seconds [default=0]: 30
High limit for queue capacity warning (b for bytes used, B for
 blocks used, % for percent used, m for messages [default=100%]):  
 80%
Reset (low) limit for queue capacity warning [default=0%]: 0%
Queue capacity command:
No default queue capacity command
Q_CAT:1438: INFO: Create queue - error queue TMNTSFWD_E created
Queue 'TMNTSFWD_E' created

> q

For more information about creating queues, see Using the ATMI /Q Component.

Setting IPC Parameters on Microsoft Windows

The BEA Tuxedo software for Microsoft Windows systems provides you with BEA Tuxedo IPC Helper (TUXIPC), an interprocess communication subsystem, that is installed with the product. On most machines, IPC Helper runs as installed; however, you can use the IPC Resources page of the control panel applet to tune the TUXIPC subsystem and maximize performance.

To display the IPC Resources page of the IPC Control Panel, perform these steps:

Click Start—>Settings—>Control Panel. The Microsoft Windows Control Panel is displayed (Figure 7-1).

Figure 7-1 Microsoft Windows Control Panel




 

 
Click the BEA Administration icon. The BEA Administration Control Panel is displayed (Figure 7-2).
Click on the IPC Resources tab. The IPC Resources Control Panel portion of the BEA Administration Control Panel is displayed (Figure 7-2).

Figure 7-2 BEA Tuxedo Software for Microsoft Windows IPC Resources Control Panel




 

To define IPC settings for your BEA Tuxedo machine, proceed as follows:

In the Current Resource Default box, click the Use Default IPC Settings check box to clear it.
Click the insert box.
Enter the name of your machine and press Enter.
Click the fields next to the IPC resources you want to set, enter the desired values, and click Apply. Clicking Apply saves the changes in the Registry Table. You must then stop and then restart the tuxipc.exe service for the changes to take effect.
Click OK to close the Control Panel.

You can view the performance of a running BEA Tuxedo server application on the Performance Monitor.

To start the Performance Monitor, click
Start—>Programs—>Administration Tools—>Performance Monitor on the taskbar. The Performance Monitor screen is displayed (Figure 7-3).

Figure 7-3 BEA Tuxedo Software for Microsoft Windows Performance Monitor

Creating the UBBCONFIG File and the TUXCONFIG File

For event poster and subscriber applications to communicate with a CORBA object in the BEA Tuxedo domain, in this case the Notification Service, a UBBCONFIG file is required for the Notification Service. The UBBCONFIG file must be written as part of the development of the Notification Service application; otherwise, you will not be able to build and run the application.

After you write the UBBCONFIG file, you use the tmloadcf command to produce the TUXCONFIG file, which is used at run time. Therefore, the TUXCONFIG file must exist before the Notification Service application is started. The TUXCONFIG file is simply a binary version of the UBBCONFIG file. The following is an example of how to use the tmloadcf command:

tmloadcf -y ubb

Before writing the UBBCONFIG, you should list the configuration requirements of your Notification Service application. To list requirements, determine the required servers and processes to support the subscription. Table 7-1 shows the configuration requirements for the different types of subscriptions.

If you are using event subscriber applications that use IIOP, you need to configure the IIOP Listener (ISL) command in the UBBCONFIG file with parameters that enable outbound IIOP to invoke callback objects that are not connected to an IIOP Handler (ISH). The -O option (uppercase letter O) of the ISL command enables outbound IIOP. Additional parameters allow system administrators to obtain the optimum configuration for their Notification Service application. For more information about the ISL command, see Setting Up a BEA Tuxedo Application.

When developing a Notification Service application, the SERVERS section of the UBBCONFIG file may include the following types of servers:

• TMUSREVT

A BEA Tuxedo system-provided server that processes event report message buffers from tppost(3), and acts as an EventBroker to filter and distribute them. (Required)

• TMNTS

A BEA Tuxedo Notification Service server that processes requests for subscriptions and event postings. (Required)

• TMNTSFWD_T

A BEA Tuxedo Notification Service server that forwards transient events to subscribers of transient subscriptions. (Required for transient subscriptions)

• TMNTSFWD_P

A BEA Tuxedo Notification Service server that forwards persistent events to subscribers that have persistent subscriptions. Events that cannot be delivered to subscribers are sent to the error queue. (Required for persistent subscriptions)

• TMQUEUE

A BEA Tuxedo server that manages event queues. (Required for persistent subscriptions)

• TMQFORWARD

A BEA Tuxedo server that forwards events to the Notification Service TMNTSFWD_P server so that they can be forwarded to persistent subscribers. (Required for persistent subscriptions)

• ISL

The BEA Tuxedo IIOP Server Listener/Handler process. (Required if the event poster or subscriber is remote, that is outside the local domain)

The UBBCONFIG file shown in Listing 7-9 is from the Notification Service Introductory sample application. The Introductory sample application supports transient subscriptions only; it does not support persistent subscriptions or data filtering.

Listing 7-9 The Introductory Sample UBBCONFIG File

# This UBBCONFIG file supports transient subscriptions only; it does
# not persistent subscriptions or data filtering.
*RESOURCES
    IPCKEY 52359
    DOMAINID events_intro_simple_cxx
    MASTER SITE1
    MODEL SHM
#---------------------------------------------------------------
*MACHINES
    "BEANIE"
        LMID = SITE1
    APPDIR = "D:\tuxdir\EVENTS~1\INTROD~2"
    TUXCONFIG = "D:\tuxdir\EVENTS~1\INTROD~2\tuxconfig"
    TUXDIR = "d:\tuxdir"
    MAXWSCLIENTS = 10
    ULOGPFX = "D:\tuxdir\EVENTS~1\INTROD~2\ULOG"
#----------------------------------------------------------------
# Since we are using transient events, the group need not be 
# transactional.
*GROUPS
    SYS_GRP
    LMID = SITE1
    GRPNO = 1 
#---------------------------------------------------------------
*SERVERS
    DEFAULT:
    CLOPT = "-A"
    TMSYSEVT
    SRVGRP = SYS_GRP
    SRVID = 1 
TMUSREVT
    SRVGRP = SYS_GRP
    SRVID = 2 
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 3 
    CLOPT = "-A -- -N -M"
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 4 
    CLOPT = "-A -- -N"
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 5 
    CLOPT = "-A -- -F"
# Start the notification service server.
#
TMNTS
    SRVGRP = SYS_GRP
    SRVID = 6 
# Start the Notification Service transient event forwarder.
#
TMNTSFWD_T
    SRVGRP = SYS_GRP
    SRVID = 7 
# Start the ISL with -O since we are using callbacks to clients.
ISL
    SRVGRP = SYS_GRP
    SRVID = 8 
    CLOPT = "-A -- -O -n //BEANIE:2359"
#---------------------------------------------------------------
*SERVICES

The code example shown in Listing 7-10 is from the Notification Service Advanced sample application. The Advanced sample application supports transient and persistent subscriptions and data filtering.

Listing 7-10 The Advanced Sample UBBCONFIG File

# This UBBCONFIG file supports transient and persistent 
# subscriptions and data filtering.
*RESOURCES
    IPCKEY 52363
    DOMAINID events_advanced_simple_cxx
    MASTER SITE1
    MODEL SHM
#---------------------------------------------------------------
*MACHINES
    "BEANIE"
        LMID = SITE1
    APPDIR = "D:\tuxdir\EVENTS~1\ADVANC~1"
    TUXCONFIG = "D:\tuxdir\EVENTS~1\ADVANC~1\tuxconfig"
    TUXDIR = "d:\tuxdir"
    MAXWSCLIENTS = 10
    ULOGPFX = "D:\tuxdir\EVENTS~1\ADVANC~1\ULOG"
#
#  Since we are using persistent events, we need a transaction log.
#
    TLOGDEVICE = "D:\tuxdir\EVENTS~1\ADVANC~1\TLOG"
    TLOGSIZE = 10
#---------------------------------------------------------------
*GROUPS
    SYS_GRP
    LMID = SITE1
    GRPNO = 1 
#  Create a null transactional group for the notification service
#  servers.
#
NTS_GRP
    LMID = SITE1
    GRPNO = 2 
    TMSNAME = TMS
    TMSCOUNT = 2 
#  Since we are using persistent events, we need a persistent queue
#  create a queue transactional group for the queue servers.
#
QUE_GRP
    LMID = SITE1
    GRPNO = 3 
    TMSNAME = TMS_QM
    TMSCOUNT = 2 
#
#  Make the queue group manage the QUE space we create.
#  The name of the queue space specified here as TMNTSQS must match #  the name of the queue space you created.
#
   OPENINFO = "TUXEDO/QM:D:\tuxdir\EVENTS~1\ADVANC~1\QUE;TMNTSQS"
#---------------------------------------------------------------
*SERVERS
    DEFAULT:
    CLOPT = "-A"
#
#  Start the queue server.
#  The name of the queue space specified in the -s option of 
#  CLOPT must match the name of the queue space you created. 
#
TMQUEUE
    SRVGRP = QUE_GRP
    SRVID = 1 
    CLOPT = "-s TMNTSQS:TMQUEUE --  "
#
#  Start the queue forwarder, have it forward events to the
#  notification service persistent forwarder.
#
TMQFORWARD
    SRVGRP = QUE_GRP
    SRVID = 2 
    CLOPT = "-- -i 2 -q TMNTSFWD_P"
    TMSYSEVT
    SRVGRP = NTS_GRP
    SRVID = 1 
#
#  Start the user EventBroker. Pass in the environment file
#  so that the user EventBroker can find the "Story" fml field
#  definition. This allows the user EventBroker to perform
#  data filtering.
#
TMUSREVT
    SRVGRP = NTS_GRP
    SRVID = 2 
    ENVFILE = "D:\tuxdir\EVENTS~1\ADVANC~1\envfile"
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 1 
    CLOPT = "-A -- -N -M"
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 2 
    CLOPT = "-A -- -N"
TMFFNAME
    SRVGRP = SYS_GRP
    SRVID = 3 
    CLOPT = "-A -- -F"
#
#  Start the notification service server. Pass in the environment
#  file so that the notification server can perform data filtering.
#  The -s option must be specified since we are using
#  persistent events. Note that the -s option specifies the name
#  of the queue space as TMNTSQS. This name must match the name
#  of the queue space you created.
#
TMNTS
    SRVGRP = NTS_GRP
    SRVID = 3 
    ENVFILE = "D:\tuxdir\EVENTS~1\ADVANC~1\envfile"
    CLOPT = "-A -- -s TMNTSQS"
#
#  Start the notification service transient event forwarder.
#  Pass in the environment file so that the server can perform
#  data filtering.
#
TMNTSFWD_T
    SRVGRP = NTS_GRP
    SRVID = 4 
    ENVFILE = "D:\tuxdir\EVENTS~1\ADVANC~1\envfile"
#
#  Start the notification service persistent event forwarder.
#  Pass in the environment file so that the server can perform
#  data filtering.
#
TMNTSFWD_P
    SRVGRP = NTS_GRP
    SRVID = 5 
    ENVFILE = "D:\tuxdir\EVENTS~1\ADVANC~1\envfile"
#
#  Start the ISL with -O since we're using callbacks to clients.
#
ISL
    SRVGRP = SYS_GRP
    SRVID = 4 
    CLOPT = "-A -- -O -n //BEANIE:2363"
#---------------------------------------------------------------
*SERVICES

Managing the Notification Service

After you have deployed the Notification Service application, you may need to perform the following administrative tasks on an on-going basis:

Synchronize databases.
Purge the system of dead subscriptions.
Monitor queue utilization.
Purge the queues of unwanted events.
Move or remove events from the error queue.

Synchronizing Databases

If you configure more than one EventBroker, then your Notification Service subscription databases will have to be synchronized. Because the synchronization process requires time—time that can impact event delivery—and increases network traffic, you should not configure more than one EventBroker unless the event traffic warrants it.

When you configure more than one EventBroker, you can configure time required to synchronize the databases using the -P option on the TMUSREVT server. For more information on how to set this option, see TMUSREVT(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

Note: The time required to synchronize the databases affects the elapsed time from when a subscriber subscribes and when it receives events. It also affects the elapsed time from when a subscriber unsubscribes and when it stops receiving events.

Purging the System of Dead Subscriptions

A subscription dies in one of two ways: (1) the subscriber creates a persistent subscription, shuts down without unsubscribing, and then does not restart and reconnect to the Notification Service, or, (2) the subscriber creates a subscription that never matches any event. While it is allowable for a subscriber to create a persistent subscription and then shut down without unsubscribing, it is an error if the subscriber does not periodically reconnect for the purpose of picking up accumulated events. Because the Notification Service periodically attempts to deliver events that match persistent subscriptions, such events accumulate while the subscriber is disconnected, consume queue space, and waste system resources.

Subscriptions that will never match any events should not be created because they serve no useful purpose. Also, subscriptions consume system resources because each posted event must be compared against each subscription.

Using the ntsadmin commands listed in Table 7-2, you can view all subscriptions and see how many events are currently in the pending queue and in the error queue for each subscription. You can also remove subscriptions using a ntsadmin command or move events from the error queue to the pending queue. For a description of the ntsadmin utility, see ntsadmin.

Although there is no way of automatically detecting a dead subscription, the ntsadmin utility is helpful in determining when and if a subscription is dead.

Monitoring Queue Utilization

Queues are created with a fixed amount of space allocated to them. This space is consumed as events accumulate in the queues. If the queues become full, subsequent attempts to enqueue events will fail.

You use qmadmin or ntsadmin to monitor queue utilization (see qmadmin(1) in the BEA Tuxedo Command Reference).

When the queue space was created to hold the pending events, the maximum number of events that could be held by the queue space was specified. For example, in the Advanced sample application, the maximum number of events for the TMNTSQS queue space was set to 200 (see Creating Event Queues). With knowledge of queue space capacity, you can use the ntsadmin pendevents command to determine the number of events pending in the event queue. If the event queue is full or nearly full, you may want to increase the setting for maximum number of events or increase the number of event queues.

Note: Use the threshold command option (cmd) on the qmadmin qcreate command to generate a warning when a queue is nearing capacity. For information on this command, see qmadmin(1) in the BEA Tuxedo Command Reference.

Purging the Queues of Unwanted Events

You can purge events from either the pending queue or the error queue by using the ntsadmin commands rmerrevents and rmpendevents.

Warning: After an event has been removed from the queue there is no way to recover it. The event is gone and the subscribing application will never receive the event.

Managing the Error Queue

After a preset number of attempts to deliver an event, the event is moved to the error queue. Once on the error queue, the administrator must take some action to either purge the event from the system, or move the event from the error queue back to the pending queue. Purging of events is discussed in the previous section.

When you move an event from the error queue back to the pending queue, you are requesting that the system resume delivery attempts of the event. Because failed attempts to deliver events consume system resources, you should not do this unless you have some reason to believe that the condition that prevented delivery before has been corrected. The ntsadmin retryerrevents command is provided specifically to move events back to the pending queue.

Notification Service Administration Utility and Commands

This topic includes the following sections:

• ntsadmin Utility
• ntsadmin Commands
• Using the ntsadmin Utility

ntsadmin Utility

This section describes the ntsadmin utility.