|
|
This section covers the following topics:
The WLE Notification Service is layered on the BEA TUXEDO Event Broker and Queuing systems. This means that administering the WLE Notification Service requires that you also administer these BEA TUXEDO systems. You use the existing BEA TUXEDO utilities tmadmin
and qmadmin
and the WLE utility ntsadmin
to administer the BEA TUXEDO and WLE components.
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.
Before you can run event Notification Service applications, the following configuration requirements must be satisfied:
Introduction
Configuring the Notification Service
If data filtering or TUXEDO interoperability is used in subscriber applications, you must perform the following steps to use data filtering in subscriptions:
Configuring Data Filters
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 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 NT)
FLDTBLDIR32=D:\wledir\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:\wledir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
TMNTS
SRVGRP = NTS_GRP
SRVID = 3
ENVFILE = "D:\wledir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
CLOPT = "-A -- -s TMNTSQS"
TMNTSFWD_T
SRVGRP = NTS_GRP
SRVID = 4
ENVFILE = "D:\wledir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
TMNTSFWD_P
SRVGRP = NTS_GRP
SRVID = 5
ENVFILE = "D:\wledir\EVENTS_Samples\ADVANCED_Simple_CXX\envfile"
The object references host and port number requirements for the callback object are as follows.
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.
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.
For Java subscriber applications, you can use the setProperties
method to set the host and port. Listing 7-5 illustrates how to do this.
Listing 7-5
Setting Host and Port in Java Subscriber Applications
Properties prop = new Properties(System.getProperties());
prop.put( "org.omg.CORBA.ORBClass", "com.beasys.CORBA.iiop.ORB" );
prop.put("org.omg.CORBA.ORBSingletonClass",
"Com.beasys.CORBA.idl.ORBSingleton");
prop.put( "org.omg.CORBA.ORBPort", nnnn );
System.setProperties(prop)
ORB orb = ORB.init(args, prop);
Note: You can also set the port in the java command line. Here is an example of a java command line that sets the port number:
java -DTOBJADDR=//BEANIE:2359 \ -Dorg.omg.corba.ORBPort= portnumber -classpath...
When you use persistent subscriptions, you must configure and boot the TUXEDO queuing system. The queuing system requires a transaction log. Listing 7-6 shows how to use the tmadmin utility to create a transaction log.
Listing 7-6 Creating a Transaction Log (createtlog ) (Microsoft Windows NT)
>tmadmin
>crdl -b 100 -z D:\wledir\EVENTS_Samples\ADVANCED_Simple_CXX\TLOG
>crlog -m SITE1
>quit
>
When you use persistent events, you must configure and boot the TUXEDO queuing system. Two event queues must be created:
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:
1) Queuing order (for example, first in, first out).
2) How to handle out-of-order enqueuing.
3) Retry limit (how many retries before moving the event to the error queue).
4) Retry time interval.
5) How full the queue can get before administrative intervention is required.
6) How low the queue can get after getting full before administrative intervention is required.
7) Definition of the administrative intervention command.
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:
These steps are described in the following sections.
To tune your system for maximum performance, you should determine the optimal values for the following parameters:
Proceed as follows to determine space parameters for transient subscriptions:
IPC Queue Space for Transient Subscriptions
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
Proceed as follows to determine space parameters for persistent subscriptions:
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-7 shows an example of the commands:
Listing 7-7 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.
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 to the BEA TUXEDO /Q Guide.
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-8 shows an example the queue space that is configured for the Advanced Sample application.
Listing 7-8 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-8, take note of the following size settings:
For more information about creating queue space, see the BEA TUXEDO /Q Guide.
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-9 shows an example of creating the TMNTSFWD_P and TMNTSFWD_E queues that are created for Advanced Sample application.
Listing 7-9 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 the BEA TUXEDO /Q Guide.
The WLE software for Microsoft Windows NT 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 (Figure 7-1) of the Control Panel, perform these steps:
To define IPC settings for your WLE machine, proceed as follows:
You can view the performance of a running WLE server application on the NT Performance Monitor.
To start the Performance Monitor, click
Start->Programs->Administration Tools->Performance Monitor on the NT taskbar. The Performance Monitor screen is displayed (Figure 7-2).
For event poster and subscriber applications to communicate with a WLE object in the WLE 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 runtime. 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. Here 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.
To support these types of Subscriptions |
You 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 Server Listener (ISL) command in the UBBCONFIG
file with parameters that enable outbound IIOP to invoke callback objects that are not connected to an IIOP Server Handler (ISH). The -O
option (uppercase letter O) of the ISL command enables outbound IIOP. Additional parameters allow administrators to obtain the optimum configuration for their Notification Service application. For more information about the ISL command, see the Administration Guide When developing a Notification Service application, the SERVERS
section of the UBBCONFIG
file may include the following types of servers:
A BEA TUXEDO system provided server that processes event report message buffers from tppost (3), and acts as an Event Broker to filter and distribute them. (Required)
A WLE Notification Service server that processes requests for subscriptions and event postings. (Required)
A WLE Notification Service server that forwards transient events to subscribers of transient subscriptions. (Required for transient subscriptions)
A WLE Notification Service server that forwards persistent events to subscribers that have persistent subscriptions. Events that cannot be delivered to subscribers are sent the error queue. (Required for persistent subscriptions)
A TUXEDO server that manages event queues. (Required for persistent subscriptions)
A 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 WLE 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-10 is from the Notification Service Introductory Application. The Introductory Application supports transient subscriptions only; it does not support persistent subscriptions or data filtering.
Listing 7-10
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:\wledir\EVENTS~1\INTROD~2"
TUXCONFIG = "D:\wledir\EVENTS~1\INTROD~2\tuxconfig"
TUXDIR = "d:\wledir"
MAXWSCLIENTS = 10
ULOGPFX = "D:\wledir\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-11 is from the Notification Service Advanced Application. The Advanced Application supports transient and persistent subscriptions and data filtering.
Listing 7-11 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:\wledir\EVENTS~1\ADVANC~1"
TUXCONFIG = "D:\wledir\EVENTS~1\ADVANC~1\tuxconfig"
TUXDIR = "d:\wledir"
MAXWSCLIENTS = 10
ULOGPFX = "D:\wledir\EVENTS~1\ADVANC~1\ULOG"
#
# Since we are using persistent events, we need a transaction log.
#
TLOGDEVICE = "D:\wledir\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:\wledir\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 event broker. Pass in the environment file
# so that the user event broker can find the "Story" fml field
# definition. This allows the user event broker to perform
# data filtering.
#
TMUSREVT
SRVGRP = NTS_GRP
SRVID = 2
ENVFILE = "D:\wledir\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:\wledir\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:\wledir\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:\wledir\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"
#-------------
After you have deployed the Notification Service application, you may need to perform the following administrative tasks on an on-going basis:
If you configure more than one Event Broker, 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 Event Broker unless the event traffic warrants it.
When you configure more than one Event Broker, 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 BEA TUXEDO 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.
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 the ntsadmin Utility, see "ntsadmin" on page 7-28.
Although there is no way of programmatically detecting a dead subscription, the ntsadmin
utility is helpful in determining when and if a subscription is dead.
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 BEA TUXEDO Reference Section 1 - Commands, qmadmin
).
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 7-7). 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 BEA TUXEDO Reference, Section 1 - Commands, qmadmin
.
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.
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.
This section cover the following topics:
Monitoring Queue Utilization
Purging the Queues of Unwanted Events
Managing the Error Queue
Notification Service Administration Utility and Commands
This section describes the ntsadmin
utility.
ntsadmin Utility
ntsadmin
Synopsis
WLE Notification Service administration command interpreter.
Syntax
ntsadmin
Description
The Notification Service includes an administration command interpreter, ntsadmin , that provides commands to perform the following tasks for WLE Notification Service applications:
- List subscriptions
- Delete subscriptions
- Display summary information about structured events on the pending and error queues
- Delete structured events on the pending and error queues
- Move structured events from the error queue to the pending queue
Note: When you enter ntsadmin to start the program, if your application only has transient subscriptions, the commands for persistent subscriptions are disabled.
Note: The Notification Service must be running before you can use ntsadmin .
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 paginate command below).
Note: The subscription command has different output depending on the setting of the verbose command.
Security
This utility can only be used by the system administrator.
See Also
TMNTS, TMNTSFWD_T, TMNTSFWD_P , qmadmin
ntsadmin Commands
Commands may be entered either by their full name or by an abbreviation (if available, the abbreviation is listed below in parentheses following the full name), followed by appropriate arguments. Arguments that appear in square brackets [] are optional; arguments in curly braces {} indicate a selection from mutually exclusive options. Each command offers the following options:
The ntsadmin commands are as follows:
- subscriptions (sub) [{-i identifier |-n name |-t | -p}]
- Lists subscriptions in the subscription database.
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-12 shows examples of subscription output with verbose on and off.
Listing 7-12 Subscription Command Output with Verbose Mode On and Off
> verbose on
Verbose mode is now on> sub
ID: 1000000006
Name: marcello
QoS: Transient
Qspace: <N/A>
Expression: stock trade\.quote
Filter: stock_name %% 'BEAS' && price_per_share > 150ID: 1000000005
Name: marcello
QoS: Persistent
Qspace: TMNTSQS
Expression: stock trade\.sell
Filter:ID: 1000000004
Name: marcello
QoS: Persistent
Qspace: TMNTSQS
Expression: stock trade\.buy
Filter:> verbose off
Verbose mode is now off> sub
ID Name Expression
-- ---- ----------
1000000006 marcello [T] stock trade\.quote
1000000005 marcello [P] stock trade\.sell
1000000004 marcello [P] stock trade\.buy
- rmsubscriptions (rmsub) [{-i identifier |-n name |-t | -p]}[-y]
- Removes subscriptions from the subscription database. This command prompts for confirmation unless -y is used.
- This command displays the number of subscriptions removed.
- pendevents (pevt) [{-i identifier |-n name}]
- List information about events in the pending events queue.
- rmpendevents (rmpevt) [{-i identifier |-n name |-o}][-y]
- 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.
- This command displays the number of events removed.
- errevents (eevt) [{-i identifier |-n name}]
- Lists events in the events error queue.
- rmerrevents (rmeevt) [{-i identifier |-n name |-o}][-y]
- 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.
- This command displays the number of events removed.
- retryerrevents (reteevt) [{-i identifier |-n name}][-y]
- Retries the events in the events error queue. This will move the events from the error queue to the pending queue.
- This command prompts for confirmation unless -y is used.
- This command displays the number of events moved from the error queue to the pending queue.
- quit (q)
- Terminates the session.
- echo (e) [{off |on}]
- Echos 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.
- help (h) [{ command |all}]
- Prints help messages. If command is specified, the abbreviation, arguments and description for that command are printed. all causes a description of commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.
- paginate (page) [{off |on}]
- 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.
- verbose (v) [{on | off }]
- Produces output in verbose mode. If no option is given then the current setting will be toggled, and the setting is printed. The initial setting is off .
- ! shellcommand
- Use this command to escape to shell and execute shellcommand.
- !!
- Use this command to repeat the previous shell command.
- #[text]
- Use this command to designate the line as a comment.
- <CR>
- Use this command to repeat the previous command.
Using the ntsadmin Utility
This section shows examples using the ntsadmin utility.
Listing 7-13 shows an example of using ntsadmin to move events from the error queue back to the pending queue. The following steps are performed:
- Look up all subscriptions for marcello .
- Use the unique subscription id to display information about events on the error queue.
- Move the events from the error queue to the pending queue.
Listing 7-13 Moving Events From the Error Queue to the Pending 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.
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\.buy> verbose off
Verbose mode is now off> eevt -i 1000000003
ID Name Count
-- ---- -----
1000000003 marcello 1
> reteevt -i 1000000003 -y
1 event(s) retried
Listing 7-14 shows an example of using ntsadmin to remove subscriptions and purge events.
Listing 7-14 Removing a Subscription
> rmsub -n JimJones -y
2 subscription(s) removed
> rmeevt -n marcello -y
1 event(s) removed
> rmpevt -n JimJones -y
No events removed
Listing 7-15 shows how to check events pending for a specific subscription.
Listing 7-15 Checking for Pending Events
> pevt -n marcello
ID Name Count
-- ---- -----
1000000003 marcello 1
Notification Servers
This section provides descriptions of the following servers:
- TMTNS
- TMNTSFWD_T
- TMNTSFWD_P
The Notification Service also uses the following BEA TUXEDO system servers. For descriptions of these servers, refer to section 5 of the BEA TUXEDO Reference.
- TMSYSEVT (5)
- TMUSREVT (5)
- TMQFORWARD (5)
- TMQUEUE (5)
Synopsis
Processes requests for subscriptions and event postings
Syntax
TMNTS SRVGRP="identifier" SRVID="number"
[CLOPT="[-A] [servopts options]
[--[-S queuespace]"]Description
TMNTS is a WLE-provided server that processes all requests for subscriptions and event postings.
Parameter
- -S queuespace
- The 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.
Interoperability
TMNTS must be run on WLE Version 5.0 or later.
Notes
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.
Example
*SERVERS
TMNTS SRVGRP = NTS_GRP SRVID = 3
CLOPT = "-A -- -s TMNTSQS"See Also
TMSYSEVT (5), TMUSREVT (5), TMQUEUE (5), TMQFORWARD (5), TMNTSFWD_P , TMNTSFWD_T , UBBCONFIG (5)
Synopsis
Forwards events to transient subscribers
Syntax
TMNTSFWD_T SRVGRP="identifier" SRVID="number"
[CLOPT="[-A][--"]Description
TMNTS is a WLE-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.
Interoperability
TMNTS must run on WLE version 5.0 or later software.
Notes
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.
Example
*SERVERS
TMNTSFWD_T SRVGRP = SYS_GRP SRVID = 7
See Also
TMSYSEVT (5), TMUSREVT (5), TMNTS (5), TMNTSFWD_P , UBBCONFIG (5). Also, see "IPC Queue Space for Transient Subscriptions" on page 7-8.
Synopsis
Forwards events to persistent subscribers
Synopsis
TMNTSFWD_P SRVGRP="identifier" SRVID="number"
CLOPT="[-A] [--"]Description
TMNTS is an WLE-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.
Interoperability
TMNTS must run on WLE version 5.0 or later.
Notes
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.
This server must be booted in a transactional group.
The number of TMNTSFWD_P servers booted should be the same as the number of TMQFORWARD servers booted.
Example
*SERVERS
TMNTSFWD_P SRVGRP = NTS_GRP SRVID = 5
See Also
TMSYSEVT (5), TMUSREVT (5), TMNTS , TMNTSFWD_T , servopt, UBBCONFIG (5)
Copyright © 1999 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.