Configuring Message Queues and Global Memory

 

BEA MessageQ stores messages in global sections and stores pointers to the messages in queues. Developers are primarily concerned with queue configuration. BEA MessageQ system managers configure the global sections where the messages are stored.

This chapter describes how to configure message queues and global sections. See the BEA MessageQ Introduction to Message Queuing for a description of message queues.

The following topics are covered in this chapter:

• Configuring Message Queues

• Configuring Global Memory

Configuring Message Queues

You can configure your message queues using the queue configuration table section of the DMQ$INIT.TXT file. Listing 4-1 is a sample of the queue configuration table section. You can access this table using the CUSTOMIZE option on the BEA MessageQ main menu. For more information on the main menu options, refer to BEA MessageQ Main Menu and Utilities.

Use this table to configure your message queues following the configuration guidelines discussed in the section Queue Configuration Table Rules.

Listing 4-1 Queue Configuration Table Section

---

%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 
* 
*  SBS Server uses the following UCB numbers for Optimized Delivery 
* 
SBS_ETH_CONTROL        74       0    0   .    E    .   .    .       .     L    N 
SBS_ETH_CHAN1          75       0    0   .    E    .   .    .       .     L    N 
SBS_ETH_CHAN2          76       0    0   .    E    .   .    .       .     L    N 
*
*  Queues 90-100 & 150-199 are reserved for MessageQ utilities 
TEMPORARY_Q             0   64000  100   .    .    .   .    .       .     L    N 
SPARE1                 90  100000  100   .    .    .   .    .       Y     L    N 
ALL_UCBS               91       0    0   .    .    .   .    .       .     L    N 
TIMER_QUEUE            92       0    0   .    .    .   .    .       .     L    N 
NULL                   93       0    0   .    .    .   .    .       .     L    N 
NA_SERVER              94 1000000 1000 None   .    .   .    .       N     L    N 
QTRANSFER_SERVER       95 1000000 1000 None   .    .   .    .       N     L    N 
DEAD_LETTER_QUEUE      96   64000  100   .    .    .   .    .       Y     L    N 
MRS_SERVER             98 1000000 1000 None   .    .   .    .       N     L    N 
SBS_SERVER             99 1000000 1000 None   .    .   .    .       N     L    N 
COM_SERVER            100 1000000 1000 None   .    .   .    .       N     L    N 
DCL_BY_Q_NAME         151       0    0   .    .    .   .    .       .     L    N 
TCPIP_LD              152 1000000 1000 None   .    .   .    .       N     L    N 
DECNET_LD             153 1000000 1000 None   .    .   .    .       N     L    N 
RESERVED_LD           154 1000000 1000 None   .    .   .    .       N     L    N 
JRN_SERVER            156 1000000 1000 None   .    .   .    .       N     L    N 
DMQ_FULLTEST_PQ       191  250000  100   .    .    .   .    .       N     L    N 
DMQ_FULLTEST_PQ       192  250000  100   .    .    S 191    .       N     L    N 
EXAMPLE_Q_1           193   64000  100   .    .    .   .    .       N     L    N 
EXAMPLE_Q_2           194   64000  100   .    .    .   .    .       N     L    N 
IVP_unowned_sq        195  250000  100   .    .    S   .    .       N     L    N 
* 
%EOS 

---

Queue Configuration Table Parameters

The following table explains the parameters (fields) in the queue configuration table.

Table 4-1 Queue Configuration Table Fields

Field Name	Description
Queue Name	The BEA MessageQ internal name of the message queue. The queue name is 1 to 255 characters long and is stored as uppercase. The name is stored in the group's name table available for run-time translation by the queue location services. If the CUSTOMIZE procedure is run and you request that language specific files be created, the queue names are added to p_proces.h and are prefixed with PAMS_.
Num	The BEA MessageQ internal queue number that ranges from 0 to 3949 and 4000 to 6000, inclusive. The queue number must be below the value defined by FIRST_TEMP_QUEUE in the %PROFILE section. Multipoint outbound target (MOT) queue values are not allowed in the Queue Configuration Table.
Pool Quota	Contains three parameters: Bytes, Msgs, and Ctrl Bytes-The maximum number of data bytes sent to a message queue. The range is from 0 to 2 31-1 (2147483647). A period (.) specifies the default which is 64000. Msgs-The maximum number of messages that can be pending to a queue. The range is from 0 to 2 31-1 (2147483647). A period (.) specifies the default which is 100. Ctrl-Controls the enabling and disabling of queue quotas. Valid settings are (case insensitive): A or All-All queue quotas enabled N or None- All queue quotas disabled B or Byte-Only Byte quota enabled; Msgs quota disabled M or Msgs-Only Msgs quota enabled; Byte quota disabled " . "- A period (.) specifies the default which is All The quotas for the queue may need to be changed to accomodate large messages (up to 4MB) as described in Chapter 11, "Sizing and Tuning the BEA MessageQ Environment" under Queue Quota.
UCB Send	Specifies special message processing by using user-writable subroutines. Send user callback points (send UCB) are designated by the uppercase letters A through J. A period (.) means that there are no send UCBs for this queue.
Q Type	Designates the queue type. It can be a primary (P), secondary (S), or multi-reader (M). A period (.) specifies the default which is primary (P ). Configure any queue with a send UCB as a primary queue.
Q Own	Identifies queue owner. Used for preallocated, permanent secondary queues, and defines the primary queue with which this queue is to be associated.
Confirm Style	Controls the method by which messages can be confirmed. Valid settings are (case insensitive): II-Implicit, in-order confirmations EI-Explicit, in-order confirmations EO-Explicit, out-of-order confirmations " . "-A period (.) specifies the default, which is EO. For more information on this parameter, refer to Configuring Message Recovery.
Perm Act	Indicates whether a permanent queue can accept messages when no process has currently attached to the queue. The queue is activated when a process attaches to BEA MessageQ . This applies to only primary and secondary queues. Multi-reader queues are always active, and temporary queues are only active when a process has attached to the temporary queue. Valid settings are: Y for always active N for active on attach period (.) for the default setting (Y for always active)
Name Scope	Indicates the scope in which the DMQ$LOADER utility advertises the association between names and addresses. Name scope must contain the letter L or G. L indicates that the name is available for lookup only within the message queuing group. G indicates that the name is available to the entire message queuing bus. When the DMQ$LOADER utility encounters a name scope of G, it advertises the address setting through the BEA MessageQ Naming Agent.
Chk ACL	Indicates whether the queue has controlled read access. When Chk ACL is enabled, any attempt to read from the queue results in an access check against a corresponding file that has limited read access. Valid settings are Y for enable and N for disable. See BEA MessageQ Security, for more information.

Queue Configuration Table Rules

When assembling the queue configuration table, follow these rules:

• Specify queues by queue name and queue number.

• Permanent queue numbers range from 1 to 3949. The upper limit is one less than the FIRST_TEMP_QUEUE value field in the profile section in DMQ$INIT.TXT.

• Temporary queues can range from 200 to 3999. The minimum temporary queue is controlled by the FIRST_TEMP_QUEUE field in the profile section in DMQ$INIT.TXT, and the value can range from 200 to 3949. The default is 200.

• Adhere to the following queue naming rules:

  • Queues use all alphanumeric characters plus hyphens (-), underscores ( _ ), and dollar signs ($). Queue names with dollar signs are only allowed on OpenVMS systems.

  • Queue names are are limited to a length of 256 characters.

  • Queue names are case sensitive; therefore, Queue_1 and QUEUE_1 are considered two different queues.

• Use the Pool Quota Bytes column to specify the number of message bytes pending to a particular queue before the queue requests for that target are rejected.

• Use the Pool Quota Msgs column to specify the number of messages that can be pending to a queue before the queue requests for that target are rejected.

• Use the Pool Quota Ctrl column to specify the enabling/disabling of queue quotas.

• You can specify queue entries in any order. Multiple queue entries can share the same queue number with only the first entry taking effect. These multiple definitions of queues are useful for setting up aliases in the include files and in the group name table (see Chapter 7, "Creating Global Names").

• Secondary queues do not have to be assigned an owner in DMQ$INIT.TXT. Instead, any user that passes access control checks can be attached for read access to the queue. However, only one user is allowed to be attached to a secondary queue at any particular time.

• This feature allows read access to a recoverable queue to be passed from process to process, without requiring those processes to exit from the bus and reattach as a particular primary queue.

• If a secondary queue is assigned an owner in DMQ$INIT.TXT, then it is attached when the owner primary queue is attached, if it passes access control checks.

• Specify all temporary queues with a single table entry with the queue name TEMPORARY_Q. BEA MessageQ assigns a queue number to a temporary queue when a process requests one. To define the default receive quota and access control for temporary queues, BEA MessageQ equates the queue name TEMPORARY_Q to queue number 0.

• BEA MessageQ recoverable messages are removed from the recovery system after they are confirmed by BEA MessageQ or by the receiver application using the pams_confirm_msg service. BEA MessageQ offer two types of message confirmation; explicit and implicit. It also allows in-order and out-of-order message confirmation. Confirmation characteristics of the queue are set using the CONFIRM_STYLE queue attribute in the QCT section. Refer to the BEA MessageQ Programmer's Guide for a complete explanation of message confirmation.

• The queue configuration table also accepts SBS broadcast stream entries (4000 to 6000). These entries do not correspond to queues but are useful for creating symbols in include files and the group name table. Refer to the BEA MessageQ Programmer's Guide for more information.

• If you use dynamic naming, add alias entries to the group name table (GNT) in the DMQ$INIT.TXT file. This allows for easier division of features into separate servers at a later time.

Configuring Global Memory

The BEA MessageQ global memory provides storage for queue names and addresses and allocates memory space for message queuing groups and message buffers.

The following topics are covered in this section:

• How BEA MessageQ Uses Global Memory

• Using the Buffer Pool Configuration Table

How BEA MessageQ Uses Global Memory

BEA MessageQ creates seven global sections for each message queuing group that is running on a node. The four sections for message control are listed in Table 4-2 and the three sections describing the buffer pool configuration are listed in Table 4-3. In the following tables, bbbb corresponds to the bus ID and ggggg corresponds to the group ID of the message queuing group.

Table 4-2 Message Control Section

Section	Use it to store ...
DMQ$MCS_C_bbbb_ggggg	General control information
DMQ$GRP_C_bbbb_ggggg	Cross-group link control information
DMQ$MRQ_C_bbbb_ggggg	Multireader queue (MRQ) control information
DMQ$GNT_C_bbbb_ggggg	Group Name Table (GNT) information

Messages are stored in one of the buffer pool global sections listed in Table 4-3.

Table 4-3 Buffer Pool Global Sections

Global Section	Stored Message Size
DMQ$LLS_S_bbbb_ggggg	Small
DMQ$LLS_M_bbbb_ggggg	Medium
DMQ$LLS_L_bbbb_ggggg	Large

Using the Buffer Pool Configuration Table

To change BEA MessageQ memory allocation, configure the buffer pool in the buffer pool configuration table of the DMQ$INIT.TXT file (see Defining the Message Queuing Environment, and BEA MessageQ Main Menu and Utilities, for more information on working with the DMQ$INIT.TXT file).

This table controls the size of the buffer pool where messages are stored. A buffer pool consists of fixed-size memory buffers that hold one message each. The buffer pool is created during COM Server startup.

The buffer pool contains space for all messages on a system. It must be sized to contain all messages active in memory at any given time. When this pool is fully allocated, attempts to send a message cause PAMS__REMQUEFAIL to be returned to the sending application. This return code can also indicate that insufficient global memory buffers were found to contain a particular message request. If GROUP_MAX_MESSAGE_SIZE is larger than a LARGE buffer, then multiple buffers are chained together to contain such a message. The maximum LARGE buffer size is 65K. However, the default LARGE buffer size is 64K.

Listing 4-2 shows the buffer pool configuration table section of DMQ$INIT.TXT.

Listing 4-2 Buffer Pool Configuration Table Section

---

---------------------------------------------------------------- 
%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 
* 
---------------------------------------------------------------- 

---

Table 4-4 describes the fields (parameters) in the buffer pool configuration table.

Table 4-4 Buffer Pool Configuration Table Fields

Field Name	Description
Msg-Block-Type	Indicates whether the buffer pool being specified is for small, medium, or large messages.
Byte-Size	Indicates the size of the largest message that can be stored in the specified buffer pool. The minimum byte size required to boot is 1500. The minimum byte size to support all BEA MessageQ services is 8192. The maximum value is 64000.
Number	Indicates the maximum number of messages desired of this size. The maximum number is 50000.
Warning-level	Indicates the threshold number of buffers remaining before a warning message is sent to the console. The minimum number is zero, and the maximum number must be less than the number of messages.
Reserve Count	Allocates the last n messages in the buffer pool for BEA MessageQ internal use. This allocation allows BEA MessageQ internal messaging to occur when the buffer pool is full. The reserve count space, set at 5% to 10% of the buffer pool capacity, would be a good starting point when allocating the space. By reserving messages, the unblocking messages used by PDEL_MODE_WF_xxx and PAMS_CONFIRM_MSG messages have a higher tolerance to the buffer pool capacity overflow.