|
|
|
|
|
|
Defining the Message Queuing Environment
To use BEA MessageQ, begin by configuring a message queuing group on your local system. For BEA MessageQ to exchange messages between networked systems, you must configure cross-group connections.
This chapter describes the initial configuration steps you must take to make BEA MessageQ operational at a minimum level. As you use BEA MessageQ and add new applications, you must upgrade the BEA MessageQ message queuing environment to satisfy new requirements. This chapter describes additional configuration and system management that are described in more detail in following sections.
This chapter discusses the following topics:
Preparing to Define the BEA MessageQ Environment
Before defining your BEA MessageQ environment, you must create a system management account with the required privileges. Once the account has been created, you will need to perform some basic configuration tasks that will allow you to create, start, and stop message queuing groups.
BEA MessageQ Manager Account Privileges
Use the Authorize Utility (AUTHORIZE) to create a BEA MessageQ system management account with the following privileges:
|
ALTPRI |
CMKRNL |
DETACH |
EXQUOTA |
|
GROUP |
GRPNAM |
NETMBX |
OPER |
|
PSWAPM |
SYSGBL |
SYSLCK |
SYSNAM |
|
SYSPRV |
TMPMBX |
WORLD |
After you install BEA MessageQ software using SYS$UPDATE:VMSINSTAL, you must perform several initial configuration steps. The executables and command procedures necessary to perform these can be found in:
disk:[DMQ$Vnn.EXE]
where disk: is the disk drive on which BEA MessageQ was installed and Vnn is the version (for example, V50). After the initial configuration steps have been performed, the logical name DMQ$EXE: will point to this directory. Until then you need to specify the directory name.
The initial configuration steps are shown in Table 2-1.
|
Step |
Function |
Action |
|---|---|---|
|
1 |
Run DMQ$CREATE_GROUP |
Creates the directory and initial configuration tables for a new BEA MessageQ group. This step is not required if you performed conversion to BEA MessageQ version 5.0 from an earlier version. |
|
2 |
Run DMQ$STARTUP.COM (without starting up servers) |
Creates the required BEA MessageQ logical name table allowing group configuration. |
|
3 |
Edit DMQ$INIT.TXT file |
Enters the configuration information (such as queue definitions, which servers to startup and inter-group message communications). |
|
4 |
Run DMQ$STARTUP.COM |
Starts the BEA MessageQ group. |
|
5 |
Run DMQ$SHUTDOWN.COM |
Shuts down a running BEA MessageQ group. |
To maintain group configurations, you may need to perform the following tasks:
Creating a Message Queuing Group
The following topics are covered in this section:
Note: If you have upgraded an earlier version of BEA MessageQ to version 5.0 using the conversion utility (see the BEA MessageQ Installation Guide for OpenVMS), your messaging groups have already been created.
The BEA MessageQ Message Queuing Network
A BEA MessageQ message queuing network consists of one or more systems running BEA MessageQ. Each instance of BEA MessageQ running on a system is known as a BEA MessageQ group. Each group consists of queues, servers, and shared resources.
All queues within a group reside on the same system, share inter-process communications mechanisms (such as global memory, files and locks) and are handled by the same set of server processes. The servers, in turn, communicate to queues within their group, as well as to servers in other groups on the bus.
Before a group can start operation, the group's resources need to be configured. In BEA MessageQ for OpenVMS, each group has the following resources:
A message queuing group can consist of many message queues. A message queuing bus can have many message queuing groups. A networked system of computers may contain several message queuing buses which provide separate messaging domains.
The assignment of BEA MessageQ bus and group IDs should be done as part of the application system design. A well-planned design for bus and group IDs for the message queuing environment is similar to planning the topology of a network. If planned well, the network can handle changes as applications are added and changed. If planned poorly, it can be difficult to accomplish even minor changes and those changes can cause interruptions to network users.
In some situations, you may need to run more than one BEA MessageQ message queuing bus. A common situation for running multiple buses is when a test and production environment exist in the same network. BEA MessageQ allows multiple, concurrent BEA MessageQ buses to exist while ensuring that messages from different buses do not get mixed.
To create a bus, you create groups using the DMQ$CREATE_GROUP.COM command procedure and specify a new bus ID. The new bus will start running as soon as the groups within that message queuing bus are started. If more than one bus is required, the assignment of bus IDs should be designed using valid bus IDs in the range from 0001 to 9998.
Note: Bus IDs 0 and 9999 are reserved. We recommend that application developers and system designers control the assignment of bus and group IDs to applications.
An orderly assignment of group IDs may correlate group IDs to some functional, application, or organizational strategy. This strategy should allow the addition of future functional, application, or organizational areas.
Every group connected to a message queuing bus must have a unique group ID. BEA MessageQ allows up to 32000 group IDs per message queuing bus. A process for the registration and assignment of group IDs should ensure that each group ID is unique and does not conflict with other groups.
Creating Message Queuing Groups
Use the DMQ$CREATE_GROUP.COM command procedure to create message queuing groups. Execute DMQ$CREATE_GROUP once for each group to be created. This command procedure is located in the [DMQ$V50.EXE] directory.
DMQ$CREATE_GROUP has the following format:
$ DMQ$CREATE_GROUP bus_id group_id " " " " " " user_area log_area
where:
|
bus_id |
Required; It Defines the message queuing bus domain and is an integer between 1 and 9998 |
|
group_id |
Required; It defines a particular group within the message queuing bus and is an integer between 1 and 32000 |
|
" " |
Not used. |
|
" " |
Not used. |
|
" " |
Not used. |
|
user_area |
Optional: Allows you to share other groups' configuration files and is an OpenVMS directory or logical name containing a directory (See Sharing Group Configuration Files.) |
|
log_area |
Optional: It provides a directory location of log files and is an OpenVMS directory or logical name containing a directory |
If you specify only the bus ID and group ID, DMQ$CREATE_GROUP creates the following default directories, where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID:
Listing 2-1 shows how a group (bus 15 and group 1) is created.
Listing 2-1 Invoking DMQ$CREATE_GROUP
$ @DUA1:[DMQ$V50.EXE]DMQ$CREATE_GROUP 15 1
%CREATE-I-CREATED, DUA1:[DMQ$V50.USER.0015_00001] created
%CREATE-I-CREATED, DUA1:[DMQ$V50.LOG.0015_00001] created
%CREATE-I-CREATED, DUA1:[DMQ$V50.MRS.0015_00001] created
%DMQ-I-COPYFILE, Copying DMQ$BOOT.COM
%DMQ-I-COPYFILE, Copying DMQ$INIT.TXT
%DMQ-I-COPYFILE, Copying DMQ$SET_SERVER_LOGICALS.COM
%DMQ-I-COPYFILE, Copying DMQ$SET_SERVER_QUOTAS.COM
%DMQ-I-COPYFILE, Copying DMQ$TYPCLS.TXT
%DMQ-I-COPYFILE, Copying DMQCLSEC.TXT
%DMQ-I-COPYFILE, Copying FML32.H
%DMQ-I-COPYFILE, Copying HIDDEN_DATA_TYPES.PAS.
.
.
%DMQ-I-COPYFILE, Copying PAITYPBLI.TXT
%DMQ-I-COPYFILE, Copying PAITYPPAS.TXT
%DMQ-I-COPYFILE, Copying PAMS_ADA_ENTRY_POINT_.ADA
.
.
.
%DMQ-I-COPYFILE, Copying PAMS_ADA_TYPE_CLASS_.ADA
%DMQ-I-COPYFILE, Copying P_ENTRY.H
.
.
.
%DMQ-I-COPYFILE, Copying P_TYPECL.H
%DMQ-I-COPYFILE, Copying SYCUSTOMIZE.COM
%DMQ-I-COPYFILE, Copying TMENV.H
%DMQ-I-COPYFILE, Copying DMQ.TLB
%DMQ-I-COPYFILE, Copying DMQ.MLB
Connecting to the BEA MessageQ Logical Name Table
BEA MessageQ creates and utilizes a group logical name table for each BEA MessageQ group. The logical names contained in each table are used by BEA MessageQ to uniquely define the group.
The group logical name table is created when you run DMQ$STARTUP.COM. Once created, this logical name table will exist until either the system is rebooted or the DMQ$DEASSIGN.COM procedure is run.
Note: To create the BEA MessageQ group logical name table, execute DMQ$STARTUP without starting BEA MessageQ Servers. For a complete description of syntax for DMQ$STARTUP, see Using DMQ$STARTUP to Invoke BEA MessageQ. For an example of starting DMQ$STARTUP without starting servers, see Invoking DMQ$STARTUP without Starting the Servers.
BEA MessageQ places all the logical names that a group requires in this group logical name table. The table is named DMQ$LNM_bbbb_ ggggg, where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID.
After the group logical name table is created, other processes (user or application) must run DMQ$SET_LNM_TABLE.COM to access the group table. A process must run this procedure in order to do the following:
Note: We recommend that the DMQ$SET_LNM_TABLE command procedure be added to the user's LOGIN.COM file.
DMQ$SET_LNM_TABLE has the following format:
$ DMQ$SET_LNM_TABLE bus_id group_id [CREATE/UNSET/NOEXEC]
where:
|
bus_id |
Required; Specifies the bus ID (an integer between 1-9998). |
|
group_id |
Required; Specifies the group ID (an integer between 1-32000) |
|
CREATE/UNSET/NOEXEC |
Optional; specifies alternate processing (a character string of CREATE, UNSET, or NOEXEC). |
|
If CREATE is used, the LNM table is created if it does not already exist. |
|
|
If UNSET is used, the routine does the following:
|
|
|
If NOEXEC is used, the routine will enter DMQ$LNM_TBL in the LNM$FILE_DEV logical name list and the LNM$PROCESS_DIRECTORY table in supervisory mode rather than executive mode. |
For example, if BEA MessageQ is installed on disk DUA1:, access the group with bus ID 15 and group ID 1 as follows:
$ @DUA1:[DMQ$V50.EXE]DMQ$SET_LNM_TABLE 15 1
%DMQ-S-SETLNM, Set to MessageQ LNM table DMQ$LNM_0015_00001
Editing DMQ$INIT to Configure a Group
To create and maintain a BEA MessageQ group configuration, you need to perform the initial configuration, add new queues, maintain queue characteristics, maintain cross-group connections, maintain group tables, and modify group performance characteristics. Group configuration information is stored in the DMQ$INIT.TXT file which is located in the DMQ$USER directory.
The DMQ$INIT.TXT file contains information about:
Edit the DMQ$INIT.TXT file to add and change group configuration information. This file should be maintained by the system manager or other individual responsible for maintaining and managing the BEA MessageQ environment. The file can be edited by any of the standard system provided editors or through the DMQ$MENU utility procedure (refer to BEA MessageQ Main Menu and Utilities, for more information on DMQ$MENU).
The DMQ$INIT.TXT file contains the following sections that you must customize for each group. Each section begins with a percent sign (%) and the name or an abbreviation for the name of the section. The following characters are treated as comment characters in the DMQ$INIT.TXT file: exclamation point (!), pound sign (#), semicolon (;) and asterisk (*). Table 2-2 describes each section of DMQ$INIT.TXT and tells you where to find more information about how to configure each section of the file.
|
Section Header |
Name |
Description |
|---|---|---|
|
%PROFILE |
Profile |
Must precede all other sections and specifies global or COM Server-specific parameters (See Setting Servers and Configuring Groups in the Profile Section.) |
|
%XGROUP |
Cross-group Communications |
Provides the link driver with the information it needs to connect to other message queuing groups. The Cross-group section should contain a entry for the node on which the local group is running. (See Chapter 3, "Configuring Cross-group Connections".) |
|
%ROUTE |
Message Routing |
Enables cross-group communications paths among nodes with no direct network links (See Chapter 3, "Configuring Cross-group Connections".) |
|
%CLS |
Client Library Server |
Enables the support of multiple BEA MessageQ Client connections to a single OpenVMS process using either DECnet and TCP/IP transports (See Chapter 8, "Configuring the BEA MessageQ Client Library Server".) |
|
%BUFFER |
Buffer Pool Configuration Table |
Controls the size of the buffer pool where messages are stored (See Configuring Message Queues and Global Memory.) |
|
%QCT |
Queue Configuration Table |
Contains the specifications for all permanent queues. The default QCT section requires tailoring to meet your application needs. (See Configuring Message Queues and Global Memory.) |
|
%SBS |
Selective Broadcast Services (SBS) |
Controls the operation of the local SBS Server (See Setting Up Selective Broadcasting.) |
|
%MRS |
Message Recovery System (MRS) |
Controls the operation of the local MRS Server (See Configuring Message Recovery.) |
|
%GNT |
Group Name Table |
Contains alias and bind queue names and their addresses (See Configuring Message Recovery.) |
|
%NAM |
Naming Agent |
Contains the group numbers in which the Naming Agent will run. (See Creating Global Names.) |
Setting Servers and Configuring Groups in the Profile Section
A BEA MessageQ group includes a number of server processes. Each server process is dedicated to a specific function or set of functions. The main overseer of each BEA MessageQ message queuing group is the communications (COM) server. During startup, the COM Server process starts up subsidiary servers depending upon the contents of the Profile section. You can start the following servers by indicating YES for each server entry in DMQ$INIT.TXT file:
To request these BEA MessageQ Servers to start up, set the appropriate ENABLE_xxx parameters to YES in the profile section of DMQ$INIT.TXT. Listing 2-2 shows a sample Profile section. It specifies information that is global to the entire group or information that is needed by the COM server.
Listing 2-2 Sample Profile Parameters
%PROFILE ***** Profile Parameters *****
*
ACCEPT_KILL_CMD NO ! Control MONITOR terminate requests
ENABLE_XGROUP NO ! Enable MessageQ cross-group access
XGROUP_VERIFY NO ! Limit incoming cross-group connections
ENABLE_MRS YES ! Enable MessageQ Message Recovery Services
ENABLE_JRN NO ! Enable MessageQ Message Journaling Services
ENABLE_SBS YES ! Enable MessageQ Selective Broadcast Services
ENABLE_QXFER NO ! Enable MessageQ MRS Queue Transfer Services
FIRST_TEMP_QUEUE 200 ! Select start of temp queue pool (200-3950)
XGROUP_TABLE_SIZE 25 ! Select max number of group entries (25-32000)
RCV_MSG_QUOTA_METHOD MAX ! Select rcv msg quota deduction (MIN | MAX)
ATTACH_TMO 600 ! Select PAMS_ATTACH_Q timeout (100-36000)
GROUP_MAX_USER_QUEUE 999 ! Maximum temp queue number (999-3999)
GROUP_MAX_MESSAGE_SIZE 128000 ! Maximum number of bytes per message
*DEFAULT_NAMESPACE_PATH /DMQNS/ ! Default namespace path for the Naming Agent
*
%EOS
Profile Section Parameters
Table 2-3 shows the parameters in the Profile section.
|
Parameter |
Range |
Default |
Description |
|---|---|---|---|
|
ACCEPT_KILL_CMD |
YES/NO |
NO |
Controls COM Server termination requests from the DMQ$MONITOR utility. A setting of NO means that any message requests to shut down COM Server are ignored. |
|
ENABLE_XGROUP |
YES/NO |
NO |
Enables BEA MessageQ DECnet or TCP/IP network access. A setting of YES causes the appropriate link drivers to start up to perform cross-group communications. |
|
XGROUP_VERIFY |
YES/NO |
NO |
Validates incoming DECnet or TCP/IP connections. A setting of YES causes all connections to be validated against the cross-group connection table, much like an access control list (ACL). |
|
ENABLE_MRS |
YES/NO |
YES |
Controls the enabling or disabling of BEA MessageQ Message Recovery Services. A setting of YES enables the MRS Server to be started which is necessary for doing guaranteed message delivery via Store and Forward (SAF) and/or Destination Queue Files (DQF). |
|
ENABLE_JRN |
YES/NO |
NO |
Controls the enabling or disabling of BEA MessageQ Message Journaling Services. A setting of YES enables the JRN Server to be started which is necessary for Post Confirmation Journaling (PCJ) and/or Dead-Letter Journaling (DLJ). |
|
ENABLE_SBS |
YES/NO |
YES |
Controls the enabling or disabling of BEA MessageQ Selective Broadcast Services and/or AVAIL Services. |
|
ENABLE_QXFER |
YES/NO |
NO |
Controls the enabling or disabling of BEA MessageQ MRS Queue Transfer Services. |
|
FIRST_TEMP_QUEUE |
200-3950 |
200 |
Selects start of the temporary queue pool. This defines the size of the permanent and temporary queue pools for a group. |
|
XGROUP_TABLE_SIZE |
25-32000 |
25 |
Selects maximum number of group entries. This defines the maximum number of concurrently active groups tracked by the COM Server. This does not affect the maximum group number. |
|
RCV_MSG_QUOTA_METHOD |
MIN/MAX |
MAX |
Selects type of receive byte quota deductions. The two methods are: MIN, which deducts only the number of bytes used from the receive byte quota. MAX, which deducts the size of the buffer used to hold the message (LARGE, MEDIUM, or SMALL) as defined in the %BUFFER section. |
|
ATTACH_TMO |
100-36000 |
600 |
Selects the maximum elapsed time that an attach or locate queue operation can take before a status of PAMS__TIMEOUT is returned to the caller. This number is in units of tenths of a second. |
|
GROUP_MAX_USER_QUEUE |
999-3999 |
999 |
Sets the highest user queue number |
|
GROUP_MAX_MESSAGE_SIZE |
2048-4194304 |
128000 |
Sets the maximum number of bytes per message. |
|
DEFAULT_NAMESPACE_PATH |
- |
/DMQNS/ |
Sets the default namespace path for the Naming Agent. The VMS root for this path is defined in DMQ$BOOT.COM with the DMQNS_DEVICE logical name. This parameter is commented out by in the DMQ$INIT.TXT template. See Default Namespace Path Definition for more information. |
Default Namespace Path Definition
The DMQNS_DEFAULTPATH logical name is now supported, and is defined in DMQ$BOOT.COM. Using the DMQNS_DEFAULTPATH logical name allows you to remove the DEFAULT_NAMESPACE_PATH definition from the DMQ$INIT.TXT file, yet still define the path information needed by the Naming Agent Server. See Creating Global Names, for more information on defining a name space.
Setting Network Connections in the Cross-group Section
To establish connections to other BEA MessageQ groups, you must modify the cross-group connection table of the DMQ$INIT.TXT file. This table provides the COM Server with the information required to connect to other BEA MessageQ groups through DECnet or TCP/IP connections.
One entry for each BEA MessageQ group should be in the Xgroup section if the group in question is sending messages to another.
Listing 2-3 is a sample of the cross-group connection (%XGROUP) table. Refer to Chapter 3, "Configuring Cross-group Connections" for more information on how to establish cross-group connections. A group must have an entry in the cross-group table for itself.
Listing 2-3 Cross-group Connection Table
%XGROUP ***** Cross-Group Connection Table ******
*
* gen buf buf recon dly win transport
*gname gnumber node cnt warn pool sec sec msg type endpt
*--------- ------ ------------------- --- --- --- --- --- --- ----- -----
*GR1_TCP 1 ipaddr1.company.com Y -1 175 -1 -1 -1 TCPIP 2001
*GR1_TCP 1 ipaddr2.company.com Y -1 175 -1 -1 -1 TCPIP 2001
*GR1_DECNET 1 daddr1 Y -1 -1 -1 -1 -1 DECNET
*GR1_DECNET 1 daddr4 Y -1 -1 -1 -1 -1 DECNET
*
*GR2_TCP 2 ipaddr3.company.com Y -1 175 -1 -1 -1 TCPIP 2002
*GR1_TCP 1 ipaddr3.company.com Y -1 175 -1 -1 -1 TCPIP 2002
*GR2_DECNET 2 daddr4 Y -1 -1 -1 -1 -1 DECNET
*GR2_FAILOVER 2 daddr5 Y -1 -1 -1 -1 -1 DECNET
*
%EOS
Configuring Client Library Server in the CLS section
Use the Client Library Server configuration table to specify a PC-based client server endpoint (address), transport type, and maximum number of clients allowed for each server.
Listing 2-4 is a sample of the Client Library Server configuration table. Refer to Chapter 8, "Configuring the BEA MessageQ Client Library Server" for more information on how to configure the CLS section.
Listing 2-4 Client Library Server Configuration Table
%CLS **** Client Library Server Configuration Table ****
*
* Maximum # Security
* Endpoint Transport of Clients File Path
* -------- --------- ---------- ---------------
5000 TCPIP 16 dmq$user:cl_5000.sf
5001 TCPIP 16
6000 DECNET 32
*
%EOS
*
Configuring Local Buffer Pools in the Buffer section
BEA MessageQ uses sections of global memory to process messages. The section of global memory used for any given message is determined by the size of the message. There are global sections for small, medium, and large messages. The buffer pool configuration table is where the sizes of messages, the number of messages and threshold parameters for each global sections are defined.
Listing 2-5 is a sample of the buffer pool configuration table. Refer to Chapter 4, "Configuring Message Queues and Global Memory" for more information on how to change BEA MessageQ memory allocation.
Listing 2-5 Buffer Pool Configuration Table
%BUFFER ***** Buffer Pool Configuration Table *******
* Reserve
*Msg-Block-Type Byte-Size Number Warning-level Count
*-------------- --------- ------ ------------- ---------
SMALL 256 50 10 2
MEDIUM 5000 10 2 1
LARGE 64000 3 1 0
%EOS
*
Defining Queues in the Queue Configuration Section
The fundamental entity within a message queuing system is the queue. Each message queue has a number of definable attributes. As your BEA MessageQ environment matures, new queues will be added to groups and existing queue attributes will be changed.
The message queue characteristics that you can define are the queue name, queue number, performance attributes, queue type, owner of the queue, and the life span of the queue. Queue configuration information is stored in the Queue Configuration Table of the DMQ$INIT.TXT file.
Listing 2-6 is a sample of a small portion of the queue configuration table. Refer to Chapter 4, "Configuring Message Queues and Global Memory" for detailed information on how to define and configure queues.
Listing 2-6 Queue Configuration Table
%QCT ***** Queue Configuration Table ******
*
* ---Pool Quota--- UCB Q Q Confrm Perm Name Chk
* Queue Name Num Bytes Msgs Ctrl Send Type Own Style Act Scope ACL
*------------------- ---- ------- ---- ---- ---- ---- ---- ----- ---- ----- ----
* Sample Queues
QUEUE_1 1 64000 100 All . . . II Y L N
QUEUE_2 2 64000 100 Msg . . . EI Y L N
QUEUE_3 3 64000 100 Byte . . . EO Y L N
QUEUE_4 4 64000 100 None . . . . Y L N
QUEUE_5 5 64000 100 . . . . . Y L N
QUEUE_6 6 64000 100 . . . . . Y L N
QUEUE_7 7 64000 100 . . . . . Y L N
QUEUE_8 8 64000 100 . . . . . Y L N
QUEUE_9 9 64000 100 . . . . . Y L N
QUEUE_10 10 64000 100 . . . . . Y L N
*
%EOS
Setting Broadcast System Parameters in the SBS Section
The Selective Broadcast Server provides the function of broadcasting messages to interested parties. To set broadcast system parameters, edit the Selected Broadcast Services (SBS) Server section of the DMQ$INIT.TXT file.
Listing 2-7 is a sample of the SBS Server section. Refer to Chapter 6, "Setting Up Selective Broadcasting" for more detailed information on configuring message broadcasting.
Listing 2-7 SBS Server Initialization Section
%SBS ******* SBS Server Initialization Section ************
*
* NOTE: Heartbeat interval is in units of 1 millisecond
*
HEARTBEAT 2000
*
* ---- Service ----
* ID Prot/Xport
COMM_SERVICE 10 DG/DMQ ! default emulated broadcast path
GROUPS * ! all known server groups
REGISTER * ! all universal MOTs
END_COMM_SERVICE
*
%EOS
Setting Message Recovery System Parameters in the MRS Section
The Message Recovery System has several configurable attributes. To set recovery system parameters, edit the Message Recovery Service (MRS) Server section of the DMQ$INIT.TXT file. This section allows you to configure the mechanism for reliable message recovery and delivery.
The MRS file system is split up into a variable number of fixed-sized areas. MRS manages the creation, assignment, and deletion of files without user intervention. The total disk space taken up by incoming (DQF) and outgoing (SAF) journal files can be controlled by setting three parameters:
Listing 2-8 is a sample of the MRS Server initialization section. Refer to Chapter 5, "Configuring Message Recovery" for more information on how to configure the message recovery system.
Listing 2-8 MRS Server Initialization Section
%MRS ******* MRS/JRN Server Initialization Section ************
*
AREA_SIZE 512 ! disk blks per file (min:128, max:16384, def:512)
NUM_DQF_AREAS 1000 ! min:100, max:1000000, default:1000
NUM_SAF_AREAS 1000 ! min:0, max:1000000, default:1000
NUM_PCJ_AREAS 1000 ! min:0, max:1000000, default:1000
NUM_DLJ_AREAS 1000 ! min:0, max:1000000, default:1000
NUM_MESSAGES 512 ! min:128, max:2147483647, default:512
NUM_QUEUES 128 ! min:128, max:2147483647, default:128
CACHE_PERCENTAGE 90 ! % rcv quota for MRS msgs (min:1, max:100, def:90)
USE_HIGH_WATER_MARK YES ! checkpt MRS sizing params to disk (YES/NO)
LOAD_MRS_CTRS YES ! init recoverable msg ctrs on startup (YES/NO)
RCVR_ONLY_CONFIRM YES ! limit msg confirms to receiving process (YES/NO)
XGRP_JRN_CTRL NO ! allow JRN cntrl msgs from other groups (YES/NO)
REDELIVERY_TIMER 10 ! integer seconds (min:0, max:5000, default:10)
*
PCJ_FILENAME DMQ$MRS:MRS_%bg.PCJ ! char[64] - %bg is a macro that
DLJ_FILENAME DMQ$MRS:MRS_%bg.DLJ ! char[64] - expands to bus_group
Assigning the Groups in which the Naming Agent Will Run
Listing 2-9 is a sample of the section of the group initialization file used to configure the groups in which the Naming Agent will run. Refer to Creating Global Names, for more complete information on how to configure BEA MessageQ to support its global naming feature.
Listing 2-9 Naming Agent Initialization Section
%NAM **************** Naming Agent Section ********************
* This section consists of a maximum of 2 entries consisting of
* a keyword, "NA_GROUP", followed by the group number of a group
* where a naming agent is running
*NA_GROUP 1
NA_GROUP 2
%EOS
Starting and Stopping BEA MessageQ Groups
The following topics are covered in this section:
Using DMQ$STARTUP to Invoke BEA MessageQ
To set up the BEA MessageQ environment and begin using the BEA MessageQ software you need to run the DMQ$STARTUP command procedure. You can execute DMQ$STARTUP interactively or during system startup by adding a call to the SYS$STARTUP_VMS command.
The DMQ$STARTUP command procedure automatically sets the named logical name table for the current process by invoking the DMQ$SET_LNM_TABLE command procedure. After the BEA MessageQ application is started, you can access its main menu and use the BEA MessageQ main menu to compile, link, and run the utilities.
DMQ$STARTUP has the following format:
$ @DMQ$STARTUP bus_id group_id timeout start_servers "" user_area log_area
where:
|
bus_id |
Required. It specifies the bus ID of the bus you want to start and is an integer between 1 and 9998. |
|
group_id |
Required. It specifies the group ID of the group you want to start and is an integer between 1 and 32,000. |
|
timeout |
Optional. It specifies the server startup timeout in seconds. |
|
start_servers |
Optional. It specifies whether you want to start the BEAMessageQ serviers for this group and is either Y or N. The default is Y to start the servers. If you do not want to start the servers, specify N for this parameter. |
|
"" |
Not used. |
|
user_area |
Optional. It specifies the directory name for storing user files; is a directory specification or logical name containing the directory specification. The logical name DMQ$USER points to this location which contains the group-specific DMQ$BOOT.COM and DMQ$INIT.TXT files. |
|
log_area |
Optional. It specifies the directory name for storing log files and is a directory specification or logical name containing the directory specification. The logical name DMQ$LOG points to this location. |
To use the BEA MessageQ default directories, specify only the bus and group ID parameters. Specify the parameters for user area or log area when starting a group that uses configuration files that are different from the default.
Invoking DMQ$STARTUP without Starting the Servers
Sometimes, you may want to configure a BEA MessageQ message queuing group without starting it; for example, during initial group configuration. To define the BEA MessageQ environment, run the DMQ$STARTUP.COM procedure and specify the start start_servers parameter as N to prevent the servers from starting.
Listing 2-10 shows how to invoke DMQ$STARTUP without starting the servers. It defines the environment for bus 99, group 50, but does not start the servers. After you run DMQ$STARTUP, you can customize the messaging group using the DMQ$INIT.TXT file.
Listing 2-10 Invoking DMQ$STARTUP without Starting Servers
$ @DUA1:[DMQ$V50.EXE]DMQ$STARTUP 99 50 "" N
DMQ$STARTUP.COM - 12-NOV-1999 14:40:46.88
Bus: 0099
Group: 00050
Disk: DISK$DUA1:
Timeout:
Start Servers: No
DMQ Version: DMQ$V50
User Area: DMQ$DISK:[DMQ$V50.USER.0099_00050]
Log Area: DMQ$DISK:[DMQ$V50.LOG.0099_00050]
%DMQ-S-SETLNM, Set to MessageQ LNM table DMQ$LNM_0099_00050
...Installing DMQ$MSGSHR
...Installing DMQ$EXECRTL
...Installing DMQ$ENTRYRTL
...Installing DMQ$VPS_EXEC
...Installing DMQ$SET_LNM
Note: BEA MessageQ places all the logical names that a group requires in the group-specific logical name table, DMQ$LNM_bbbb_ggggg, where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID.
Starting Groups Under an Older Version of BEA MessageQ
BEA MessageQ for OpenVMS is designed to allow all versions to coexist on the same system and the same disk. Each version has its own startup command procedure called DMQ$STARTUP.COM. For example, to start a version 4.0 group (bus 20, group 36), execute the following:
$ @DUA0:[DMQ$V40.EXE]DMQ$STARTUP 20 36
Note: When running multiple versions of BEA MessageQ in the same message queuing environment, do not define two groups with the same bus and group IDs if they are to run on the same system simultaneously.
Starting Application Programs in a Message Queuing Group
Application programs using BEA MessageQ for OpenVMS are usually written as a number of detached cooperating server processes within a single message queuing group. Each server process handles specific functions and communicates with clients and other servers via BEA MessageQ messages.
Application Startup Process
The application startup procedure starts the message queuing group along with the BEA MessageQ Servers. It then detaches application server processes with the DCL command RUN/DETACH.
Two Methods for Connecting
Because BEA MessageQ does not use GROUP or SYSTEM logical name tables, applications that are started by the RUN/DETACH command need a mechanism to attach the detached process to the named logical name table associated with a given bus ID and group ID.
There are two ways for a detached process to connect to a BEA MessageQ bus and group:
Detaching a Process with DCL Context
The detached process is given a DCL command stream that sets the BEA MessageQ logical name table and runs the application program image. BEA MessageQ uses this mechanism when it detaches its servers. Use the DMQ$PROCESS_START command procedure as a starting point in running the detach process with DCL context.
DMQ$PROCESS_START builds a temporary command procedure that is passed to LOGINOUT.EXE by the /INPUT qualifier. The temporary command procedure is a single-line invocation of DMQ$DETACH_PROCESS with the required parameters filled in.
Use the following command to run the DMQ$PROCESS_START command procedure:
$ @DMQ$EXE:DMQ$PROCESS_START executable_name process_name priority page_file
where:
|
executable_name |
Required; Specifies the name of the executable that you want to start. |
|
process_name |
Required; Specifies the name of the process that you want to start. |
|
priority |
Optional; Allows you to specify a process priority. |
|
page_file |
Optional; Allows you to specify the size of the page file. |
Detaching a Process without DCL Context
You can detach an application process without a DCL context by making a unique association between a message queuing group and a UIC code. This allows the detached process to access the group logical name table to pick up its configuration and startup information. Use DMQ$COPY_LNM_TABLE to copy the logical names from the BEA MessageQ LNM table to either a group or system LNM table.
After the logical names have been copied, use the DCL command RUN/UIC to detach a user application process directly. This approach is recommended for detaching processes in environments where a UIC can associated easily and uniquely with each message queuing group.
Listing 2-11 shows a detached process attached to bus 15, group 1.
Listing 2-11 Accessing the Group Logical Name Table
$!In this DCL fragment, the program SYS$LOGIN:MYPROG.EXE is started
$!as a detached process connected to bus:15 group:1
$!DMQ$COPY_LNM_TABLE is used to copy the MessageQ logical name
$!table into the group table associated with the current UIC.
$
$ myarea = f$trnlnm("SYS$LOGIN")
$ proc_name := MYPROG
$ log_file := 'myarea'MYPROG.LOG
$ err_file := 'myarea'MYPROG.ERR
$ bus_id := 00015
$ grp_id := 00001
$
$ !Connect to MessageQ
Logical Name Table
$ @DMQ$EXE:DMQ$SET_LNM_TABLE \Qbus_id' \Qgrp_id'
$
$ !Copy the MessageQ
Logical Name Table into the current group table
$ @DMQ$EXE:DMQ_COPY_LNM_TABLE GROUP
$
$ run /detached SYS$LOGIN:MYPROG.EXE -
/priv = (noall,netmbx,tmpmbx) -
/output = 'log_file' -
/error = 'err_file' -
/name = 'proc_name'
The DMQ$COPY_LNM_TABLE command procedure copies logical names from the named logical name table that is currently connected to the GROUP or SYSTEM logical name table.
The DMQ$COPY_LNM_TABLE command procedure has the following format:
$ DMQ$COPY_LNM_TABLE system_type octal_group_UIC
where:
|
system_type |
Required; specifies the system type (GROUP or SYSTEM) of the group you want to start |
|
octal_group_UIC |
Optional; specifies the octal group UIC number |
Shutting Down a Running BEA MessageQ Group
Use the DMQ$SHUTDOWN.COM procedure to shut down a running group. You can run the command procedure directly or you can run it through option 2 of the DMQ$MENU.COM utility procedure.
The DMQ$SHUTDOWN command procedure forces the COM Server process to exit either gracefully or instantly (known as stop_fast). Once the COM server exits the rest of the group server processes will also shutdown. The procedure can optionally deinstall the run-time libraries (RTLs).
DMQ$SHUTDOWN has the following format:
$ @DMQ$EXE:DMQ$SHUTDOWN bus_id group_id rtl_deinstall stop_fast
where:
|
bus_id |
Required; specifies the bus ID of the RTL's bus. |
|
group_id |
Required; specifies the group ID of the RTL's group. |
|
rtl_deinstall |
If set to YES, deinstalls all the installed BEA MessageQ images and RTLs for that group. If set to NO (the default), does not deinstall RTLs. |
|
stop_fast |
Default is YES, which uses the FORCEX utility to stop the COM server and bring down all other BEA MessageQ processes. Specifying NO will result in a graceful shutdown. During a graceful shutdown BEA MessageQ waits until all queues have been drained before shutting down. |
The following example shows the COM Server shutdown command for bus 15 and group 1.
$ @DMQ$EXE:DMQ$SHUTDOWN 15 1
Note: We recommend that you use DMQ$SHUTDOWN before you install new patches to the BEA MessageQ kit or when using the SYS$SHUTDOWN procedure. Repeat DMQ$SHUTDOWN to shut down each running COM Server on the system to which you need to apply the software patch.
Use the main menu to restart the BEA MessageQ Servers.
Additional Configuration Tasks
The following topics are covered in this section:
BEA MessageQ offers a variety of options for capturing and viewing system events. Event logging captures important information regarding the success and failure of BEA MessageQ operations. You can use the information in BEA MessageQ event logs to troubleshoot system problems. BEA MessageQ allows you to configure a variety of event logging options, including the ability to:
If you are having problems with a BEA MessageQ Server, look at the log files for that server. Refer to Managing a BEA MessageQ Environment, for more information on how to locate and view server log files. If you are having difficulty starting the BEA MessageQ group, look at the COM Server log file. This may include informative messages if the COM Server is having difficulty during startup.
Adding Queue Names to Network-wide Namespace
BEA MessageQ includes a capability for creating and maintaining a global name space and for providing runtime look up of name-to-queue address translations. These services are provided by the BEA MessageQ Naming Agent.
In addition to using the BEA MessageQ global naming capability, you can continue to use Distributed Namespace names using the NA option of the DMQ$MGR_UTILITY utility. Refer to Creating Global Names, for information on configuring and using the BEA MessageQ global naming feature. Refer to Using BEA MessageQ System Management Utilities, for information on using the BEA MessageQ Manager utility.
Changing Parameters in the Running Group
BEA MessageQ allows you to change some group characteristics at run-time. To do so, you must edit the DMQ$INIT.TXT file for the group and then run the DMQ$LOADER program to modify queues, links, names, and other modifiable group characteristics. The ability to modify some group characteristics is dependent upon the state of the object being modified.
Group initialization file parameters that are removed from the DMQ$INIT.TXT file will not be removed from the running group. To remove characteristics, you must stop the group and then restart it after modifying the group initialization file to delete the unwanted characteristics.
BEA MessageQ allows a limited number of multireader queues to be added to a running group without restarting the group. The limit is twice the initial number of MRQ entries or 20, whichever is greater. In addition, links to a remote group can be added to a group initialization file and activated by running the DMQ$LOADER program.
You can run the DMQ$LOADER from the BEA MessageQ main menu by selecting Option 10. DMQ$LOADER also runs during the servers startup (@DMQ$STARTUP). Table 2-4 describes the parameters in the group initialization file that can be modified at runtime.
|
Init File Section |
Parameter |
Run-time Restriction? |
|---|---|---|
|
%PROFILE |
ACCEPT_KILL_COMMAND |
No |
|
ATTACH_TMO |
No |
|
|
DEFAULT_NAMESPACE_PATH |
No |
|
|
%CLS |
MAX_CLIENTS |
Yes. CLS must be stopped. This parameter applies only to OpenVMS systems. |
|
SECURITY_FILE |
Yes. CLS must be stopped. |
|
|
%XGROUP |
RECONNECT |
Yes. The link must be disabled. |
|
RECONN_TIMER |
Yes. The link must be disabled. |
|
|
WINDOW_DELAY |
Yes. The link must be disabled. |
|
|
WINDOW_SIZE |
No |
|
|
%QCT |
BYTE_QUOTA |
No |
|
MESSAGE_QUOTA |
No |
|
|
MESSAGE_QUOTA_ENABLE |
No |
|
|
BYTE_QUOTA_ENABLED |
No |
|
|
TYPE |
Yes. The queue must be empty and have no processes attached. When changing a primary queue to a secondary queue, the primary queue cannot have any secondary queues defined. |
|
|
OWNER |
Yes. The queue must be empty and have no processes attached. To set this parameter to a value other than zero, the queue must be defined as a secondary queue, and the owning queue must be defined and be a primary queue. |
|
|
MRS_CONFIRM_STYLE |
No |
|
|
PERM_ACTIVE |
Yes. The queue must be empty and have no processes attached. |
|
|
SECURITY_ENABLED |
Yes. No change may be made to the security field unless the queue is empty and it has no attached processes. |
Use the following command to run the DMQ$DELETE_GROUP command procedure:
$ @DMQ$EXE:DMQ$DELETE_GROUP bus_id group_id logging_flag
where:
|
bus_id |
Required. Specifies the bus ID for the group to be deleted. |
|
group_id |
Required. Specifies the group ID for the group to be deleted. |
|
logging_flag |
Optional. Set to Y to enable logging or N to disable logging for the deletion The default value is Y. |
To delete a message queuing group, take the following steps:
|
Step |
Action |
|
1. Bring down the group's servers |
Run DMQ$SHUTDOWN.COM and specify the bus ID, group ID, and Y to remove installed images. |
|
2. Delete the group |
Run DMQ$DELETE_GROUP.COM specifying the bus and group ID of the group to delete. If the group shares directories with another group, do NOT run DMQ$DELETE_GROUP.COM. Instead, delete the files specific to that group (see Sharing Group Configuration Files). These files are:
|
Defining Message Type and Class Codes
BEA MessageQ software customization includes defining the symbolic usage of type and class codes within BEA MessageQ application programs and the BEA MessageQ script facility. The DMQ$TYPCLS.TXT file contains symbolic definitions of type and class codes. Refer to Chapter 7, "Creating Global Names" for more information on how to edit this file to create or change application-specific type and class codes.
BEA MessageQ Hints and Tips
This section provides some helpful hints for configuring your BEA MessageQ environment, including:
The default editor used by BEA MessageQ command procedures is DECTPU. To change the default editor, change the global symbol DMQ$$EDITOR. For example, enter the following command to change the default editor to invoke your own customized DECTPU section file:
$ DMQ$$EDITOR:==EDIT/TPU/SECTION=SYS$LOGIN:MY_SEC.TPU$SECTION
Defining BEA MessageQ Symbols
You can define symbols that execute the command procedures commonly used by BEA MessageQ application developers. We recommend that you define these symbols in the SYS$MANAGER:SYLOGIN command procedure.
Define the following symbol for setting the logical name table:
$ DMQ_SET :== @DUA1:[DMQ$V50.EXE]DMQ$SET_LNM_TABLE
Define the following symbol for invoking the BEA MessageQ main menu:
$ DMQ :== @DMQ$EXE:DMQ$MENU
Startup Synchronization
The DMQ$STARTUP.COM command procedure will not exit until all requested servers have started and initialized. DMQ$STARTUP uses DMQ$WAIT_FOR_SERVICE.EXE, which accepts one of the following keywords: COM, MRS, SBS, EVL, JRN, DECNET, TCPIP, QTRANSFER, CLS, NA, or ALL. If the service was specified for startup in DMQ$INIT.TXT, then DMQ$WAIT_FOR_SERVICE will block until the service has indicated to BEA MessageQ that it is ready, or until it times out (two minutes).
Redirecting Configuration and Log Files
The user area and log area parameters allow you to redirect the location of the group's configuration and log files. Usually, you do this if you want the group to share configuration files with another group or for performance reasons. See Chapter 3, "Configuring Cross-group Connections" for more information on cross-group communications.
If these parameters are not specified, DMQ$STARTUP uses the files in the following directories where the variable bbbb is the 4-digit bus ID and the variable ggggg is the 5-digit group ID.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|