• Configuring the Notification Service. This section includes the following topics:The Oracle Tuxedo CORBA Notification Service is layered on the Oracle Tuxedo EventBroker and Queuing systems. This means that administering the CORBA Notification Service requires that you also administer these other Oracle Tuxedo systems. You use the Oracle Tuxedo utilities tmadmin, qmadmin, and ntsadmin to administer the Notification Service.
•
•
1.
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‑2 shows the FML field table definitions file needed to use data filtering.Listing 7‑2 Data Filtering FML Field Table FileListing 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‑4 shows, in bold text, how the location of the FML field table file is specified in the UBBCONFIG file for the Advanced samples.*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"
• 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.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.When you use persistent subscriptions, you must configure and boot the Oracle 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.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.
• The number of transient forwarding servers (TMNTSFWD_T) and persistent forwarding servers (TMNTSFWD_P).
4. 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.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.
Oracle 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\QUEFor more information about creating a device on disk, see Using the ATMI /Q Component.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:Setting this parameter to 500 allows room for a total of 500 events in the pending and error queues.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.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> 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' createdFor more information about creating queues, see Using the ATMI /Q Component.
1. Click Start—>Settings—>Control Panel. The Microsoft Windows Control Panel is displayed (Figure 7‑1).Figure 7‑1 Microsoft Windows Control Panel
2.
3.
4. 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.To start the Performance Monitor, click
Start—>Programs—>Administration Tools—>Performance Monitor on the taskbar. The Performance Monitor screen is displayed (Figure 7‑3).For event poster and subscriber applications to communicate with a CORBA object in the Oracle 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: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.
Your UBBCONFIG file must include the following servers, and processes 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 an Oracle Tuxedo Application.When developing a Notification Service application, the SERVERS section of the UBBCONFIG file may include the following types of servers:
• An Oracle Tuxedo system-provided server that processes event report message buffers from tppost(3), and acts as an EventBroker to filter and distribute them. (Required)
•
• An Oracle 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)
• 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 FileThe 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"
#---------------------------------------------------------------
*SERVICESWhen 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.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” on page -26.
Table 7‑2 ntsadmin Commands Summary 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.You use qmadmin or ntsadmin to monitor queue utilization (see qmadmin(1) in the Oracle 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” on page -6). 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 Oracle Tuxedo Command Reference.You can purge events from either the pending queue or the error queue by using the ntsadmin commands rmerrevents and rmpendevents.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.This section describes the ntsadmin utility.The Notification Service includes an administration command interpreter, ntsadmin, that provides commands to perform the following tasks for CORBA Notification Service applications:
Note: When you enter ntsadmin to start the program, if your application only has transient subscriptions, the commands for persistent subscriptions are disabled.
Note: You can exit the ntsadmin program by entering a q (for quit) at the command prompt. You can terminate the output from a command by pressing the Break key; the program then prompts for a new command.Output from ntsadmin is paginated according to the pagination command in use (see the paginate command).
Note: TMNTS, TMNTSFWD_T, TMNTSFWD_P, qmadmin
[ -i identifier ] If specified, identifies the subscription(s) with a subscription name that matches name only. To specify names which match the empty string (that is, subscriptions with no name), enclose an empty string between quotes (“”). The ntsadmin commands are as follows:
Note: The subscription command has different output depending on whether the verbose mode is on or off (the verbose command is described below). Listing 7‑11 shows examples of subscription output with verbose on and off.Removes subscriptions from the subscription database. This command prompts for confirmation unless –y is used.Removes events in the pending events queue. If –o is specified, all events that do not currently have a corresponding subscription in the subscription database will be removed.This command prompts for confirmation unless –y is used and displays the number of events removed.Removes events in the events error queue. If –o is specified, all events that do not currently have a corresponding subscription in the subscription database will be removed.This command prompts for confirmation unless –y is used and displays the number of events removed.This command prompts for confirmation unless –y is used and displays the number of events moved from the error queue to the pending queue.Echoes input command lines when set to on. If no input is given, then the current setting is toggled and the new setting is printed. The initial setting is off.Prints help messages. If command is specified, the abbreviation, arguments and description for that command are printed. all causes a description of the commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.Paginates output. If no input is given, the current setting is toggled and the new setting is printed. The initial setting is on, unless either standard input or standard output is a non-terminal device. Pagination may only be turned on when both standard input and standard output are terminal devices. The shell environment variable PAGER may be used to override the default command used for paging output. The default paging command is the pager indigenous to the native operating system environment; for example, the command pg is the default on UNIX operating systems.! shellcommandUse this command to escape to shell and execute shellcommand.This section provides examples of using the ntsadmin utility.Listing 7‑12 shows an example of using ntsadmin to move events from the error queue back to the pending queue. The following steps are performed:
1. Look up all subscriptions for marcello.
2. Use the unique subscription_id to display information about events on the error queue.D:\smith\reg>ntsadmin
ntsadmin - 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.
Oracle Tuxedo is a registered trademark.
INFO: /Q Qspace - TMNTSQS
INFO: /Q Device - D:\smith\reg\QUE (SITE1)
> subscriptions -n marcello
ID Name Expression
-- ---- ----------
1000000002 marcello [T] stock trade\.quote
1000000001 marcello [P] stock trade\.sell
1000000000 marcello [P] stock trade\.buyListing 7‑13 shows an example of using ntsadmin to remove subscriptions and purge events.Listing 7‑13 Removing a SubscriptionListing 7‑14 shows how to check events pending for a specific subscription.Listing 7‑14 Checking for Pending Events
• The Notification Service also uses the following Oracle Tuxedo system servers. For descriptions of these servers, refer to the File Formats, Data Descriptions, MIBs, and System Processes Reference.TMNTS is an Oracle Tuxedo-provided server that processes all requests for subscriptions and event postings.-S queuespaceThe name of the queue space to use. This queue space must contain two queues: TMNTSFWD_P and TMNTSFWD_E. This option is required for persistent subscriptions only.
Note: If you plan to use subscriptions with a QoS of Persistent, you must create a queue space, a queue for holding events, and an error queue before the system is operational. The queue space name must match the queuespace name specified using the CLOPT -S queuespace parameter for the TMNTS server. The event queue must be named TMNTSFWD_P. The error queue must be named TMNTSFWD_E.It is possible to boot more then one TMNTS server to increase reliability and availability.The TMNTS server must be part of a transactional group if events will be posted in the context of a transaction.TMNTS must run on Oracle WebLogic Enterprise version 5.0 or later or Oracle Tuxedo 8.0 or later.The TMNTS server relies on services provided by the TMUSREVT and TMSYSEVT servers. Therefore, these servers must be booted before the system is operational. If transient subscriptions are used, the TMNTSFWD_T server must also be booted before the system is operational. If persistent subscriptions are used, the TMNTSFWD_P, TMQUEUE, and TMQFORWARD servers must also be booted before the system is operational.TMNTSFWD_T is an Oracle Tuxedo-provided server that forwards events to subscribers who specified a QoS of Transient. There is no transaction context associated with event delivery.
Note: It is possible to boot more then one TMNTSFWD_T server to increase reliability and availability.TMNTS must run on Oracle WebLogic Enterprise version 5.0 or later or Oracle Tuxedo 8.0 or later.The TMNTSFWD_T server relies on services provided by the TMNTS, TMUSREVT, and TMSYSEVT servers. Therefore, these servers must be booted before the system is operational.TMSYSEVT(5), TMUSREVT(5), TMNTS(5), TMNTSFWD_P, UBBCONFIG(5). Also, see “IPC Queue Space for Transient Subscriptions” on page -7.TMNTSFWD_P is an Oracle Tuxedo-provided server that forwards events to subscribers who specified a QoS of persistent. There is no transaction context associated with event delivery.It is possible to boot more then one TMNTSFWD_P server to increase reliability and availability.TMNTS must run on Oracle WebLogic Enterprise version 5.0 or later or Oracle Tuxedo 8.0 or later.The TMNTSFWD_P server relies on services provided by the TMNTS, TMUSREVT, TMSYSEVT, TMQUEUE, and TMQFORWARD servers. Consequently, these servers must be booted before the system is operational.The number of TMNTSFWD_P servers booted should be the same as the number of TMQFORWARD servers booted.