BEA MessageQ
Installation and Configuration Guide for OpenVMS

When you open the DMQ$BOOT.COM file, edit the following lines:

 
$       tcpip_ld       = "DEC"       ! Use the DEC/UCX  TCP/IP LinkDriver 
$!***   tcpip_ld       = "PSC"       ! Use the TCPware TCP/IP LinkDriver 
$!***   tcpip_ld       = ""          ! Select TCP/IP LD at SYSTEM level 
 
 

The default setting for DMQ$TCPIP_LD is "DEC". Change the commenting in the file to change the setting. Use the value "" to suppress the creation of the logical name in the MessageQ logical name table. This allows the logical to be created at the system level, thereby, controlling multiple groups simultaneously.

For example, you select link drivers at the system level as follows:

 
$ DEFINE/SYSTEM/EXEC DMQ$TCPIP_LD "DEC"   ! DEC TCP/IP 
 

or

 
$ DEFINE/SYSTEM/EXEC DMQ$TCPIP_LD "PSC"   ! TCPWARE 
 

Groups can share the same configuration, log, and MRS directories. Sharing configuration files is convenient when many groups have the same configuration. This is common in VMScluster environments, where there are groups running on each cluster member.

Note that the names of the log and MRS files of each group contain the bus ID and group ID of each message queuing group. These tags in the file names allow you to distinguish the files even if they are in the same directory as another group's files.

Example 4-4 shows how to start a group with group ID 5, bus ID 4 with the same configuration, log and script files as a group with group ID 6, bus ID 4.

Example 4-4 Sharing Configuration Files

$ @DUA1:[DMQ$V40.EXE]DMQ$SET_LNM_TABLE 4 6
%DMQ-S-SETLNM, Set to MessageQ
 LNM table DMQ$LNM_0004_00006
$ sho logical DMQ$USER
  "DMQ$USER" = "DMQ$DISK:[DMQ$V40.USER.0004_00006]" (DMQ$LNM_0004_00006)
$ sho logical DMQ$LOG
  "DMQ$LOG" = "DMQ$DISK:[DMQ$V40.LOG.0004_00006]" (DMQ$LNM_0004_00006)
$ @DMQ$EXE:DMQ$STARTUP 4 5 "" Y "" DMQ$DISK:[DMQ$V40.USER.0004_00006] -
                                  DMQ$DISK:[DMQ$V40.LOG.0004_00006] 

When message queuing groups share the same DMQ$USER area, they execute the same DMQ$BOOT.COM command procedure that defines all the logical names. If you make no changes to DMQ$BOOT.COM file, the logical name DMQ$MRS is the same for those groups, and the MRS files of the groups will be on the same disk.

Note:

Locating MRS files of multiple groups on a common disk can have significant performance impact. Refer to Chapter 6 for more information.

If you attempt a cross-group connection to a non-active group using the DECnet transport, MessageQ attempts to start a default DECnet object. If the DECnet default account has been eliminated from the system on which the group is running, DECnet intrusion alarms are generated every time a MessageQ group attempts to connect to a non-active group.

You can eliminate DECnet intrusion alarms by creating a dummy DECnet object to handle the connection attempt. The dummy DECnet object is configured to accept and then immediately drop the connection.

The following steps describe how to create a dummy DECnet object:

• Use the OpenVMS AUTHORIZE utility to create an account for the dummy DECnet object. This account should be set up for network-only access, with TMPMBX and NETMBX privileges.
  When MessageQ binds to the named object, it is going to use its own security information (for example, that of the current process). Use the user, password, and file name of this process when the COM Server is not available.
• The next step in creating the dummy object is to add an entry to the NCP database.
  The MessageQ DECnet Version 3 object is of the form "DMQ_bbbbggggg" and the DECnet Version 2 object is in the form of "DMQbbbbggggg" , where bbbb is the bus number, zero-filled to the left, and ggggg is the group number, also zero-filled to the left. The DECnet Version 3 object indentifies the bus and group number in hexidecimal format. The DECnet Version 2.0 object is represented in decimal format.
  For example, for bus 50 group 35, the DECnet Version 2 object name is "DMQ005000035".
• To load the dummy object into the permanent database, use the following NCP command:

   
  NCP> DEFINE OBJECT DMQ005000035 NUMBER 0 - 
  _  USER     user_id - 
  _  PASSWORD password FILE REJECT.COM 
   
  

• While MessageQ is not running, load the object into the volatile database using the following NCP command:

   
  NCP> SET OBJECT DMQ005000035 ALL 
   
  

  
  Now, you must restart MessageQ so that it can bind itself to the predefined DECnet object when it comes up. When the target group is not running, inbound DECnet connection requests are handled in a valid account by the REJECT.COM command procedure. You must create REJECT.COM and supply the following content:

   
  $ OPEN X SYS$NET 
  $ CLOSE X 
  $ EXIT 
   
  

  
  When this command procedure executes, the inbound connection is established and the link is dropped immediately. This procedure allows the remote system to know you are not accepting new MessageQ connects immediately, but rather you are waiting for the outgoing timer on the remote end to expire. You can change the contents of the REJECT.COM command procedure to contain only the "$ EXIT" statement, however, connection timeouts will take longer.

  4.7 Configuring DMQ$GMT_OFFSET for Network Communications

  If you are using networking software, set the value of the MessageQ logical name DMQ$GMT_OFFSET.

  DMQ$GMT_OFFSET is defined as the difference in hours between the time zone of the local system and Greenwich mean time (GMT). This value is used by the cross-group protocol and can seriously affect throughput if set improperly.

  Table 4-2 lists the GMT offsets for most time zones around the world.

  Table 4-2 GMT Offset

  Geographic Area	Offset	Daylight Offset
  Western Europe	0	- 1
  Central Europe	- 1	- 2
  Eastern Europe	- 2	- 3
  Eastern U.S.	+5	+4
  Central U.S.	+6	+5
  Mountain U.S.	+7	+6
  Pacific U.S.	+8	+7
  Alaska U.S.	+9	+8
  Hawaii U.S.	+10	+9
  Japan	- 9	.
  Hong Kong	- 8	.
  Singapore	- 8	.

  For example, to configure a system set to the eastern standard time (EST), enter the following command:

  $ DEFINE/SYSTEM DMQ$GMT_OFFSET "+5" 
  

  ---

  Chapter 5
  Configuring Message Queues and Global Memory

  5.1 Overview

  MessageQ stores messages in global sections and stores pointers to the messages in queues. Developers are primarily concerned with queue configuration. 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

  5.2 Configuring Message Queues

  You can configure your message queues using the queue configuration table section of the DMQ$INIT.TXT file. Example 5-1 is a sample of the queue configuration table section. You can access this table using the CUSTOMIZE option on the MessageQ main menu. For more information on the main menu options, refer to Chapter 10 .

  Use this table to configure your message queues following the configuration guidelines discussed in the section Section 5.2.2 .

  Example 5-1 Queue Configuration Table Section

  ---

   
   
  %QCT         ***** Queue Configuration Table ****** 
  * 
  *                          ---Pool Quota---  UCB  Q    Q  Confirm Perm Name  Check 
  *    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 
  *                                            
  *  The following are for the MessageQ demo in [DMQ$Vnn.demo.vms] 
  * 
  demo_io_server_1      101   35000  100   .    .    .   .    .       N     L    N 
  demo_io_server_2      102   35000  100   .    .    .   .    .       N     L    N 
  demo_io_server_3      103   35000  100   .    .    .   .    .       N     L    N 
  demo_io_server_4      104   35000  100   .    .    .   .    .       N     L    N 
  demo_io_server_mrq    105   35000  100   .    .    M   .    .       Y     L    N 
  demo_archive          106   35000  100   .    .    .   .    .       N     L    N 
  demo_io_broadcast_1  5101       0    0   .    .    .   .    .       .     L    N 
  demo_io_broadcast_2  5102       0    0   .    .    .   .    .       .     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 
   
   
  

  ---

  5.2.1 Queue Configuration Table Parameters

  Table 5-1 explains the parameters (fields) in the queue configuration table.

  Table 5-1 Queue Configuration Table Fields

  Field Name	Description
  Queue Name	The MessageQ internal name of the message queue. The queue name is 1 to 31 characters long and is converted to uppercase. The queue name is inserted into a queue name include file in the form "pams_queue_name". The name is also stored in the group's name table available for run-time translation by the queue location services.
  Num	The MessageQ internal queue number that ranges from 0 to 999 and 4000 to 6000 inclusive. The valid numbers in the low range are determined by setting the FIRST_TEMP_QUEUE field below which only permanent queues can be predefined.
  Pool Quota	Contains three parameters: Pool Bytes, Pool Msg, and Ctrl:
  	Pool 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.
  	Pool 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.
  	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"
  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 or period [.]), secondary (S), or multi-reader (M). Configure any queue with a send UCB as a primary queue.
  Q Own	Identifies queue owner, is used for preallocated, permanent secondary queues, and defines the primary queue that this queue is to be associated with.
  Confirm Style	II Implicit, in-order confirmations EI Explicit, in-order confirmations EO Explicit, out-of-order confirmations " . " A period [.] specifies the default which is "EO". Note: Refer to Chapter 6 for more information on this parameter.
  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 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
  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 MessageQ Naming Agent.
  Check ACL	Indicates whether the queue has controlled read access. When Check 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 Chapter 14 for more information.

  5.2.2 Queue Configuration Table Guidelines

  When assembling the queue configuration table, follow these guidelines:

  • Specify queues by queue name and queue number.
  • Permanent queue numbers range from 1 to 949. The upper limit is one less than the FIRST_TEMP_QUEUE value field in the profile section in DMQ$INIT.TXT.
  • Temporary queues range from 200 to 999. The minimum temporary queue value is controlled by the FIRST_TEMP_QUEUE value field in the profile section in DMQ$INIT.TXT. The default is 200.

    ---

    Note:

    Be aware of the following queue naming restrictions:

    • Queues use all alphanumeric characters plus "--" and "_".
    • Queue names are are limited to a length of 256 characters.
    • Queue names are case sensitive. This means that "Queue_1" and ""QUEUE_1"" are seen by MessageQ as completely separate queues.

    ---

  • Any queue configuration table entry must contain, at least, the reserved queues. The reserved entries define queue 0, queues 90 to 100, and queues 150 to 199.

    ---

    Note:

    The queues that are predefined in the software kit as unreserved queues are intended only as examples and can be changed.

    ---

  • Use the Pool Bytes Quota column to specify the number of message bytess pending to a particular queue before the queue requests for that target are rejected.
  • Use the Pool Msgs Quota 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 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 8 ).
  • 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. 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, MessageQ equates the queue name TEMPORARY_Q to queue number 0.
  • MessageQ recoverable messages are removed from the recovery system after they are confirmed by MessageQ or by the receiver application using the pams_confirm_msg service. 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 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.

  5.3 Configuring Global Memory

  The 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 MessageQ Uses Global Memory
  • Using the Buffer Pool Configuration Table

  5.3.1 How MessageQ Uses Global Memory

  MessageQ creates seven global sections for each message queuing group that is running on a node: four sections are for message control Table 5-2 and three sections describe the buffer pool configuration listed in Table 5-3 .

  Table 5-2 Message Control Sections

  Section	Use it to ...
  DMQ$MCS_C_ bbbb_ ggggg	Store general control information
  DMQ$GRP_C_ bbbb_ ggggg	Store cross-group link control information
  DMQ$MRQ_C_ bbbb_ ggggg	Store multi-reader queue (MRQ) control information

  where:

  bbbb	Corresponds to the bus ID
  ggggg	Corresponds to the group ID of the message queuing group

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

  Table 5-3 Buffer Pool Global Sections

  Global Section	Size of Stored Messages
  DMQ$LLS_S_ bbbb_ ggggg	Small
  DMQ$LLS_M_ bbbb_ ggggg	Medium
  DMQ$LLS_L_ bbbb_ ggggg	Large

  5.3.2 Using the Buffer Pool Configuration Table

  To change MessageQ memory allocation, configure the buffer pool in the buffer pool configuration table of the DMQ$INIT.TXT file (see Chapter 3 and Chapter 10 ).

  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. 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.

  Example 5-2 shows the buffer pool configuration table section of DMQ$INIT.TXT.

  Example 5-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 5-4 explains the parameters (fields) in the buffer pool configuration table.

  Table 5-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 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 MessageQ internal use. This allocation allows 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.

  ---

  Chapter 6
  Configuring Message Recovery

  6.1 Overview

  MessageQ Message Recovery Services (MRS) provide a mechanism for guaranteed message delivery by storing messages on disk and automatically attempting redelivery until the message is received by the target system. On MessageQ for OpenVMS systems, message recovery is provided by two servers:

  • The MRS Server
  • The Journal (JRN) Server.

  The following topics are covered in this chapter:

  • How Message Recovery Services Works
  • Starting MRS and JRN Servers
  • Configuring MRS and JRN Servers
  • Using Auxiliary Journal Files
  • Sizing MRS File Space
  • MRS Internal Operation Tracing at Startup

  6.2 How Message Recovery Services Works

  In MessageQ , the COM Server process starts up subsidiary servers depending upon the contents of the Profile section (see Section 3.2.6.1 ). The server which handles recoverable messaging is the MRS Server. It is started by setting ENABLE_MRS to YES. The server which handles auxiliary journal files is the Journal (JRN) Server. It is started by setting ENABLE_JRN to YES.

  ---

  Previous | Next | Contents