In order to run the loader (DMQ$EXE:DMQ$LOADER), the user must have either VMS OPER privileges or be granted the DMQ$MANAGER rights identifier.
The following actions require either OPER privileges or the DMQ$MANAGER rights identifier:
The other identifier is DMQ$OPERATOR. The following actions require either OPER privileges or the DMQ$OPERATOR rights identifier:
See Section 14.3 for more information on the DMQ$OPERATOR rights
identifier.
14.3 Defining Access Control on Queues
To control queue access, the system manager must have an account holding DMQ$OPERATOR rights identifier or the VMS OPER privilige. The system manager can limit which processes are allowed to read from a queue by setting the flag in the Check ACL column of the Queue Configuration Table in the DMQ$INIT file to Y. When the flag is set to Y, MessageQ checks a zero-length access control file called DMQ$ACCESS:DMQ$bbbbgggggqqqqq.DAT, where:
| bbbb | is the 4-digit bus ID |
| ggggg | is the 5-digit group ID |
| qqqqq | is the 5-digit queue number |
To read from a queue, a process requires read access to the queue's access control file. MessageQ checks access control by determining if the process can perform an OPEN/READ operation on the DMQ$ACCESS:DMQ$bbbbgggggqqqqq.DAT file.
To set up access control for a queue, you must create the access control file before processes can access its associated queue. Use the CREATE command at DCL level to create the file and use the SET ACL command to give the user account read access to the file. The logical DMQ$ACCESS is specific to each group and is defined in DMQ$USER:DMQ$BOOT.COM. The default value of DMQ$ACCESS is the MessageQ group-specific directory referred to by the logical DMQ$USER.
For example, use the following commands to give user identification code (UIC) [345,333] access to queue 4, on group 1, bus 15:
$ CREATE DMQ$ACCESS:DMQ$00150000100004.DAT $ Ctrl/Z $ SET ACL/ACL=(IDENTIFICATION=[345,333],ACCESS=READ) - _$ DMQ$ACCESS:DMQ$0015000010004.DAT $ SET PROT=(S,O,G,W) DMQ$ACCESS:DMQ$00150000100004.DAT
If Check ACL is set to Y on a primary or secondary message queue,
MessageQ validates whether a process is allowed to read from a
queue when the process first attaches to the queue. If the queue is a
multireader queue (MRQ), MessageQ validates access at the first
attempt to read from the queue.
14.3.2 Securing the Creation of Temporary Queues
If Check ACL is set to Y on the TEMPORARY_Q queue and the queue number
is 0, then only those processes that can read
DMQ$ACCESS:DMQ$bbbbggggg00000.DAT) are allowed to create
temporary queues. This protection works for processes that call the
pams_attach_q function. However, securing access to temporary
queues results in the disabling of the message interface to the COM
Server to create temporary secondary queues.
14.4 Setting the Global Section Protection Mask
You can configure a protection mask to restrict access to MessageQ global sections. When the protection mask is configured, an access control list (ACL) can be applied to control individual user access. All MessageQ global sections use one protection mask and, therefore, each requires an ACL to be set after the COM Server is booted.
MessageQ uses system global sections, which are owned by UIC
[1,4]. If the owner has not been granted access, the COM Server will be
unable to initialize the global sections.
14.4.1 Defining Protection Mask Logical Name
The logical name controlling the global section protection mask definition is called DMQ$SET_GBLSEC_PROT. Define the logical name using the following command:
$ DEFINE/TABLE=DMQ$LNM_TBL/EXEC DMQ$SET_GBLSEC_PROT sogw
where:
Table 14-1 shows typical combinations of protection settings.
| Setting | Description |
|---|---|
| YYYY | Default; unrestricted access to global sections |
| NYNN | Access only for MessageQ Server processes and ACLs |
| NNNN | Access only through ACLs |
When you set the ACL for the global sections, you must apply the ACL to all five global sections shown in Table 14-2 . Set an ACL for a global section (called, in this case, DMQ$MCS_C_bbbb_ ggggg) as follows:
$ SET ACL/OBJ=SYSTEM_GLOBAL_SECTION/ACL=(ID=__,AC=__) - _$ DMQ$MCS_C_bbbb_ggggg
Note:
You must set the ACL after the COM Server is running. For example, you can add the ACL command to DMQ$BOOT.COM after the line that executes DMQ$COM_START.COM.
Table 14-2 shows the names for the five global sections where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID.
| Section Name | Description |
|---|---|
| DMQ$MCS_C_ bbbb_ ggggg | Control section |
| DMQ$LLS_S_ bbbb_ ggggg | Small buffer pool section |
| DMQ$LLS_M_ bbbb_ ggggg | Medium buffer pool section |
| DMQ$LLS_L_ bbbb_ ggggg | Large buffer pool section |
| DMQ$GNT_C_ bbbb_ ggggg | Group Name Table (GNT) section |
| DMQ$GRP_C_ bbbb_ ggggg | Cross-group control section |
| DMQ$MRQ_C_ bbbb_ ggggg | Multireader queue (MRQ) control section |
The Link Drivers can limit incoming cross-group connections to the nodes found in the cross-group connection table. The incoming cross-group connections are controlled by the XGROUP_VERIFY parameter in the Profile section of the DMQ$INIT.TXT file (see Chapter 4 ).
When XGROUP_VERIFY is enabled, the cross-group connection table functions use an ACL to validate all connections against a known list of valid nodes and MessageQ group IDs. If a connection fails to match exactly, that connection is dropped and a security match failure event is logged.
Failover in a distributed system means the dynamic replacement of service after a system or component failure. This chapter presents an overview of failover and describes the following MessageQ failover features:
MessageQ for OpenVMS has two mechanisms for quickly switching
service from a failed component to a backup service point: group
failover and recoverable queue failover.
15.1.1 Group Failover
Group failover involves movement of the location of a group from one network node to another. This can be accomplished using the following two methods:
Immediately upon startup, a group establishes network links to all the groups listed in the cross-group connection table. If the first node for a group is not available, a connection is tried to the second node that is listed, and so on.
If no connection can be made to a group, it is marked as DOWN until a
connection is made. After the group is started, connections to
disconnected groups are retried periodically. This scheme allows
clients to transparently establish a connection to a backup node when
the primary node fails. (Messages sent to the group while it is
unavailable will take the undeliverable message action (UMA).)
15.1.2 Recoverable Queue Failover
The recoverable queue failover involves movement of the recoverable journaling stream associated with the specific queue. This can be accomplished using the following failover mechanisms:
| Failover Mechanism | Description |
|---|---|
| DQF Redirection | The entire DQF stream for a queue is moved to another queue. This queue may be served in the same group or in a different group. |
| DQF Queue Merge | The messages in a DQF journal stream can be merged into another DQF journal stream. |
| SAF Redirection | Same as DQF redirection but involves store and forward files of the sending group. |
| SAF Queue Merge | The messages in a SAF journal stream can be merged into another SAF journal stream. |
When a system running message queuing groups goes down, the system manager can bring the groups up on a backup node and then bring up the connected processes. When failover is needed, it is best if it is planned and designed early in the application design cycle. It can be difficult to back fit failover handling once an application is in production.
All the failover mechanisms require operational planning. In most cases, failover handling requires that an application code be written to support it.
The physical media (where recoverable journals reside) must be
accessible to both the primary node where the application is originally
running and the backup node where the application will failover to. In
a VMS cluster, this can be rather a simple task because the access to
disks can span network nodes. Outside of a VMS cluster, this is still
possible, by physically moving or copying the media.
15.2 Cold Failover
The Cold failover from one node to another requires no special application coding, but has the drawback of being the slowest of the failover schemes, since both MessageQ and the application must be completely restarted.
Due to the fact that the %XGROUP section of the DMQ$INIT.TXT file allows several nodes to be specified as connection points for a group, when an attempt fails to connect a group to a node, MessageQ attempts to connect to the next node in the list. Connections are retried on either a timed basis or when an explicit command is given to force connections.
Refer to Chapter 4 for more information on cross-group configuration.
If one node is down, the group may be moved to the next node in the connection list and started as shown in Figure 15-1 .
In the case where the two nodes do not share the same file system, the entire group environment needs to be physically moved before failover can begin. In a VMS cluster environment, all the nodes in the connection list can share files. In that case, failover from one node to another is accomplished by simply starting the group on the new node (as shown in Figure 15-2 ).
It is possible to automate this failover procedure with appropriate DCL command procedures.
Figure 15-1 Cold Failover For Non-Clustered Environment
Figure 15-2 Cold Failover For Clustered Environment
Hot failover can be configured to be automatic, or can be managed by a
"watchdog" process.
15.3.1 Automatic Synchronized Cluster Failover
In automatic synchronize cluster failover, a customer (for example, a
system manager) maintains a running copy of the group on each of the
backup nodes. Only one of the groups is the primary group. The primary
group holds a cluster lock which prevents the other secondary (backup)
groups from starting any MessageQ servers other than the COM Server and
Event Logger. When the primary group goes down for any reason it will
release the cluster lock and one of the secondary groups will obtain
the lock and become the primary group. Once a secondary group becomes
the primary it will startup all of its servers. A secondary group can
perform local messaging while waiting to become the primary group, but
it cannot perform any cross-group messaging.
15.3.1.1 Implementing Automatic Synchronized Failover
Automatic synchronized cluster failover is enabled by default via the logical DMQ$GROUP_SYNCHRONIZE which is predefined in the COM section of the DMQ$SET_SERVER_LOGICALS.COM file. When this logical is set to YES, or not defined at all, a cluster lock is used by MessageQ to determine which group is the primary group. Therefore, a group may be started on multiple nodes within a cluster. Only one of the groups (first one up) may hold the cluster lock. A group cannot become the primary group until it gains the cluster lock. The cluster lock name is DMQ$PRIMARY_GRP_bbbb_ggggg, where bbbb is the bus number and ggggg is the group number.
If a group cannot obtain the cluster lock it will log the following message in the EVL log.
COM_SERVER 9-JAN-1998 12:03:10.77 I This group is waiting to become the primary
When a group obtains the cluster lock it will log the following message in the EVL log.
COM_SERVER 13-JAN-1998 23:48:50.22 I This group is the primary
If a group is not the primary group it will only startup the COM server and Event Logger. This is important for a number of reasons:
In non-automatic hot failover, a customer (for example, a system manager) maintains a running copy of the group on another node, but it is set up in such a way that it has no cross group links and has no journal files opened. When a failover is needed, the cross group links from the failed group are terminated, and files are closed. (This may occur naturally in the event of a hardware failure on the machine). Then, MessageQ allows links from the shadow group to be set and files opened.
For both primary and backup nodes, the %XGROUP table must have the Gen Cnt field set to D (disabled). Example 15-1 shows a sample of the cross-group connection table.
Example 15-1 Sample Cross-Group Connection Table
-------------------------------------------------------------------------- %XGROUP ***** Cross-Group Connection Table ****** * * gen buf buf recon dly win transport *gname gnumber node cnt warn max type endpt * kb kb sec sec msg *--------- ------- ---------------- --- --- --- --- --- --- ----- ---- ONE 1 BIGVAX Y -1 75 0 -1 -1 DECNET TWO 2 GVAX01 D -1 -1 -1 -1 -1 DECNET TWO 2 GVAX02 D -1 -1 -1 -1 -1 DECNET TWO 2 GVAX03 D -1 -1 -1 -1 -1 DECNET * %EOS --------------------------------------------------------------------------
Figure 15-3 shows a normal condition when nodes share files on the cluster before a failover occurs.
Figure 15-3 Normal File Sharing for a Running Group
Any backup copy of a group must be started without ANY cross-group connections. This is important since two groups with the same group address cannot share the network simultaneously. The group links can be disabled using the DMQ$INIT.TXT file (XGROUP Table).
Failover is then accomplished by explicitly tearing down the links to one node (if they have not dropped as a result of the failure), and then forcing links to the next node in the failover list (as shown in Figure 15-4 ).
This procedure works for nonrecoverable messaging, but runs into difficulty if the backup group has message recovery services (MRS) enabled. The problem is that only one recovery service can own recovery journals (DQF, SAF, PCJ or DLJ file) at one time. The journals can not be shared between the original and backup group.
Figure 15-4 Hot Failover for a Running Group
The solution to this problem is to tell the recovery system of the
backup group to start up but remain idle. This is done by setting the
logical name DMQ$MRS_DISABLE_JOURNALING to YES in the MRS section of
the DCL command procedure,
DMQ$USER:DMQ$SET_SERVER_LOGICALS.COM.
The journal files may then be opened ONLY when a
MSG_TYPE_MRS_JRN_ENABLE message is sent to the MRS Server indicating
that it should open the journals. Failover of recoverable messaging
from the primary to the backup group is completed by sending the
MSG_TYPE_MRS_JRN_ENABLE message to the MRS_SERVER in the backup group.
15.3.2.2 Detecting a Failure While the Failing Group Is Still Running
Some applications may want to initiate failover from the primary group to the backup group when the primary group is still running. The heuristic for handling this type of failover is rather complex and is often application dependent.
To close all journal files, the MSG_TYPE_MRS_JRN_DISABLE message must be sent to the MRS Server. Therefore, the way to initiate the failover is to send a MSG_TYPE_MRS_JRN_DISABLE control message to the MRS Server of the group that is failing. This tells MRS to close all journal files. LINK_MANAGEMENT control messages are then used to disconnect the primary group from the network.
A MSG_TYPE_MRS_JRN_ENABLE message is sent to the MRS Server of the
backup group causing it to open the journals. Finally, the links to the
backup group are brought up and messaging can continue.
15.3.3 Programming Considerations
Some significant programming effort is needed to make hot failover work in a production environment. Usually, a watchdog program is coded to run on the primary and backup nodes. This program maintains information on the state of both primary and backup node and periodically decides whether the primary or backup node owns the processing.
A communication mechanism is needed between the watchdog programs. It may be as simple as a shared file that is polled periodically.
The heuristic for determining that a failover operation is required
will vary according to the application. One scheme that works in a VMS
cluster environment is to use the OpenVMS lock manager so that a lock
is granted when some critical process dies.
15.4 Failover of Recoverable Messaging to and from a Single Target
Two methods for handling failover of a single Destination Queue File
(DQF) are DQF REDIRECT (Failover) option and MERGE (QTRANSFER) option.
15.4.1 Redirecting Recoverable Data Streams
The DQF Redirect option works for redirecting an entire recoverable data stream from one queue to another queue (which may or may not be in the same group). The DQF journal must be closed before the failover can be attempted. If the link to the group is down, but the group is still running, you will need to explicitly force the recovery system to close the files. You can perform this failover dynamically using the RE option of DMQ$MGR_UTILITY journal control menu. Refer to Figure 15-5 .
The entire DQF data stream must be on the same disk drive to be redirected (renamed) to a new DQF data stream. VMS does not allow file renaming across devices.
Figure 15-5 DQF or SAF Redirecting for Failover
The MERGE option on the DQF screen allows you to merge a recoverable data stream with another data stream. The merging is controlled by the QTRANSFER Server that handles the moving of the contents of a DQF journal. This is accomplished by enveloping each message and sending the messages one by one to the MRS Server of the target group. The MRS Server then unpacks the envelope, writes (merges) the message to the DQF journal, and forwards it to the target queue
You can manage the merging option using the ME option on the DQF screen.
For the QTRANSFER process to work, the first DQF must be closed, either because the group serving the DQF is down, or because the DQF was explicitly closed using a control message. The QTRANSFER Server is then told to initiate the transfer by another control message. This is managed by a dialog between the QTRANSFER Server and the MRS Server.
Figure 15-6 shows major steps in the MERGE process.
Figure 15-6 Data Stream Merging for Failover
The SAF failover works identically to the DQF failover. However, it may be a much more complex operation because the senders may be distributed across many systems.
In general, redirecting a SAF data stream involves:
You can start the SAF failover using the Redirect (RE) option on the SAF screen.
Part IV includes the following appendixes:
| Appendix | Describes... |
|---|---|
| Appendix A | Sample MessageQ initialization file (DMQ$INIT.TXT). |
| Appendix B | Sample MessageQ message definition file (DMQ$TYPCLS.TXT). |
| Appendix C | Guidelines for tuning OpenVMS and MessageQ parameters. |
| Appendix D | MessageQ directories and logical names. |
| Appendix E | Warning and error messages logged by the COM server, SBS server, MRS server, and link drivers. |
| Appendix F | Files installed on your system. |
The following example Example A-1 is a sample of the MessageQ DMQ$INIT.TXT file that is used to customize the MessageQ software.
Example A-1 SampleMessageQDMQ$INIT.TXT File
************************************************************************* * * * MessageQ Initialization File * * * ************************************************************************* * ! VERSION SECTION ! ! The Version Section begins with %VERSION, and consists of a single line iden- ! tifying the initialization file version. V4.0 accepts init files with a ver- ! sion of 1.0, 2.0, or 3.0, 3.1, 3.2, or 4.0. ! %VERSION 4.0 * ! PROFILE SECTION ! ! The Profile Section begins with %PROFILE, and contains lines defining the ! group-wide configurable limits. The values given below are examples, and do ! not represent "real" values. %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 YES ! 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-950) XGROUP_TABLE_SIZE 25 ! Select max number of group entries (25-32000)
RCV_MSG_QUOTA_METHOD MAX ! Select type of rcv msg quota deductions (MIN | MAX) ATTACH_TMO 600 ! Select PAMS_ATTACH_Q timeout (100-36000) GROUP_MAX_MESSAGE_SIZE 128000 ! Maximum number of bytes per message DEFAULT_NAMESPACE_PATH /DMQNS/ ! Default namespace path for the Naming Agent * %EOS * * ! XGROUP SECTION ! ! The Xgroup Section begins with %XGROUP, and contains lines defining the ! cross-group connections that will be established by this group. Each line in ! the XGROUP section defines a single cross-group connection. All parameters ! for a given connection must appear on the same line. The general format of a ! cross-group connection is given below, followed by an explanation of each ! parameter. ! ! GNAME - Name by which the remote MessageQ Group is known to the local ! group. ! ! GNUMBER - MessageQ Group Number of the remote group. ! ! NODE - Name by which the remote node is known to the local node. ! ! INITIATE - "Y", "N", or "D" indicating whether connections to this node ! should be initiated (Y), not initiated (N), or disabled (D). ! A "Disabled" connection requires a link management command to ! enable connections to occur. ! ! THRESHOLD - Value for dynamic memory consumption at which congestion control ! will begin for this cross-group connection. (not used in v4.0) ! ! BUFFER - Maximum number of Kbytes that can be queued to this link. ! POOL This should exceed GROUP_MAX_MESSAGE_SIZE. ! ! RECONNECT - Interval, in seconds, between reconnect attempts when this cross- ! group link is not connected. ! ! DELAY - Delay, in seconds, that a sender must wait before using a new ! window when the receiver is congested. ! ! WINDOW - Maximum transmission window size for this cross-group link. ! ! TRANSPORT - Network protocol stack used. For MessageQ V4.0 this is one ! of DECNET, or TCPIP. The DECNET transport is only available on ! OpenVMS and Digital UNIX and on Windows NT and OS/2 platforms ! using PATHWORKS ! ! ENDPOINT - Protocol dependent - for the TCPIP transport, it is the internet ! port number of the remote link listener process. For the DECNET ! transport it is left blank. ! ! A sample xgroup table can be seen below:
%XGROUP ***** Cross-Group Connection Table ****** * * gen buf buf recon dly win transport *gname gnumber node cnt warn max type endpt * kb kb sec sec msg *--------- ------- ------------------- --- --- --- --- --- --- ----- ----- *ONE_TCPIP 1 sneezy.mycompany.com Y -1 75 -1 -1 -1 TCPIP 2001 *ONE_TCPIP 1 dopey.mycompany.com Y -1 75 -1 -1 -1 TCPIP 2001 *ONE_DECNET 1 sneezy Y -1 -1 -1 -1 -1 DECNET *ONE_DECNET 1 dopey Y -1 -1 -1 -1 -1 DECNET * *TWO_TCPIP 2 sleepy.myCompany.com Y -1 75 -1 -1 -1 TCPIP 2002 *TWO_TCPIP 1 sleepy.myCompany.com Y -1 75 -1 -1 -1 TCPIP 2002 *TWO_DECNET 2 sleepy Y -1 -1 -1 -1 -1 DECNET *TWO_FAILOVER 2 doc Y -1 -1 -1 -1 -1 DECNET * * %EOS * * * ! ROUTING SECTION ! ! The Routing Section begins with %ROUTE, and contains lines defining the ! MessageQ static routing data base. All parameters for a given queue must ! appear on the same line. The general format of a routing definition is given ! below, followed by an explanation of each parameter. ! ! ! TARGET_GROUP - Group for which traffic must be routed. ! ! ROUTE_THROUGH_GROUP - Group to which traffic for the target_group must be ! sent. ! ! Note that the sample routing entries are commented out in this example ! file !
%ROUTE * * Target Route-Thru * Group Group * ------ ---------- * 6 1 * 71 4 * %EOS * * * ! CLS SECTION ! ! you can start any number of client library server processes (one per line) ! by enumerating each process and its endpoint below. ! ! ENDPOINT defines the TCP/IP port number or DECnet object name ! that the server uses to accept incoming connections. ! for TCP/IP the value is limited to 1024-65535 inclu- ! sive. for DECnet the value is limited to 1-99999 in- ! clusive. ! ! TRANSPORT the name of the network protocol stack to be used for ! the server. valid values are DECnet and TCP/IP. ! ! MAX_CLIENTS the maximum number clients the server will allow at ! any given time, valid value are 1-512 inclusive, OpenVMS only. ! ! SECURITY_FILE the full path name of the security file. if no file ! is specified then a default file name is used. see ! documentation for details.
%CLS **** Client Lib 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 * *! GLOBAL MEMORY BUFFER POOL CONFIGURATION SECTION *! *! The buffer pool contains space for ALL messages on a DmQ VMS 4.0 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. *!
%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 * ! QUEUE CONFIGURATION SECTION ! ! The Queue Configuration Section begins with %QCT, and contains lines defining ! the permanent queues. Each line in the QCT section defines a single queue. ! All parameters for a given queue must appear on the same line. The general ! format of a queue definition is given below, followed by an explanation of ! each parameter. ! ! QNAME QNUMBER BYTE_QUOTA MSG_QUOTA QUOTA_ENBL UCB_SEND TYPE OWNER CONF_STYLE ! PERM_ACT SCOPE SECURITY ! ! QNAME - A name for this queue, 252 characters max ! ! QNUMBER - Number of this queue. Queue numbers must be less than the value ! established in the %PROFILE section for FIRST_TEMP_QUEUE and may ! appear only once in the QCT section. Queues 100 is reserved ! and must not appear in this table ! ! BYTE_QUOTA - The maximum number of uncollected bytes that may reside in this ! queue. if the value is -1 then the default value (the value for ! queue 0) is used. if there is no queue 0 then a default value ! of 64000 is used.
! ! MSG_QUOTA - The maximum number of uncollected messages that may reside in ! this queue. if the value -1 then the default value (the value ! for queue 0) is used. if there is no queue 0 then a default ! value of 100 is used. ! ! QUOTA_ENBL - Controls the enabling/disabling of queue quotas. ! "All" - all queue quotas on ! "None" - all queue quotas off ! "Byte" - only byte quota enabled, msg quota disabled ! "Msg" - only msg quota enabled, byte quota disabled ! "." - take the default which is "All" ! ! UCB_SEND - Send User Callback Indicator (A - J) Indicates which user ! callback routine is called from PAMS_PUT_MSG to this queue ! ! TYPE - Type of queue ! P - primary queue ! S - secondary queue ! M - multi-reader queue. ! ! OWNER - Number of controlling primary queue, if type = "S" ! ! CONF_STYLE - Controls the method by which msgs can be confirmed. ! "II" - Implicit, in-order confirmations ! "EI" - Explicit, in-order confirmations ! "EO" - Explicit, out-of-order confirmations ! "." - take default which is "EO" ! ! PERM_ACT - Permanently active queue: setting this value to "Y" allows proc- ! esses to insert messages into this queue even if it is not cur- ! rently attached by any client process.
! ! SCOPE - "L" for local scope, "G" for global scope ! globally scoped names are made available to the bus by the ! name service ! ! SECURITY - Attach security ! ! N - no attach security ! ! Y - acl security on attach. an ACL file must be present ! and openable for read/write in order to attach the queue ! %QCT ***** Queue Configuration Table ****** * * ---Pool Quota--- UCB Q Q Confrm 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 * * 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_SQ 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 * * *
%SBS ******* SBS Server Initialization Section ************
*
* NOTE: heartbeat interval is in units of 1 millisecond
HEARTBEAT 100
* ----Service----
* ID Prot/Xport
COMM_SERVICE 10 DG/DMQ ! default emulated broadcast path
GROUPS * ! all known server groups
REGISTER * ! all universsal MOTS
END_COMM_SERVICE
*
* The entry below is commented out but shows how dual rail direct ethernet
* broadcasting could be configured.
*
*COMM_SERVICE 2 DG/ETH ! datagram messaging over optimized Ethernet
* DEVICE_1 ESA0: ! VMS device name of the Ethernet board (rail A)
* DEVICE_2 EZA0: ! VMS device name of the Ethernet board (rail B)
* DRIVER_BUFFERS 16 ! # of VMS Ethernet driver buffers to preallocate
* *
* *
* * <<<<<<<<<<<<<<<<<< Warning >>>>>>>>>>>>>>>>>>>
* * The protocol and Ethernet addresses shown below are not registered
* * and are not guaranteed to not cause a conflict. Use them with
* * discretion.
* * |------ MCA ----| |Prot #| |UCB #|
* CNTRL_CHAN AB-AA-34-56-78-90 81F0 74
* DATA_CHAN AB-12-34-56-78-90 81F1 75
* *
* * NOTE: MAB = Message Assembly Buffer. Each MAB requires area for
* * a large message buffer, plus overhead of 150 bytes.
* *
* * Transmit SILO Receive SILO Maximum Poll Dead Poll
* * MOT (in MABs) (in MABs) Heartbeat Interval Interval
* REGISTER 5101 1 15 4 10 10
* REGISTER 5102 1 12 4 10 10
* REGISTER 5156 1 6 6 10 10
* *
*END_COMM_SERVICE
*
*
%EOS
*
*
! MRS SECTION
!
! this section is used to specify the journal paths for the recovery,
! post-confirmation and dead-letter journals.
%MRS ******* MRS/JRN Servers 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 msg 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 * %EOS
* ! GROUP NAME TABLE SECTION ! ! The Group Name Table Section begins with %GNT, and contains lines that define ! name-to-queue translations for names and queues that do not necessarily ! appear in the QCT. Each line in the GNT section defines a single name-to- ! queue translation. The general format of a GNT entry is given below, follow- ! ed by an explanation of each parameter. ! ! NAME GROUP.QUEUE SCOPE ! ! NAME - Case sensitive equivalence name ! ! GROUP.QUEUE - Group and Queue number to be returned to the calling process ! when this name is translated via the PAMS_LOCATE_Q service. ! Specifying zero for the 'GROUP' implies the local group num- ! ber. ! ! SCOPE - Scope of name ! ! L - Local; the name is loaded into the Group Name Table, but not ! the distributed naming service. It can be translate by the ! PAMS_LOCATE_Q service by other processes in this group. ! ! G - Global; the name is loaded into both the Group Name Table and ! the distributed naming service. It can be translated by the ! PAMS_LOCATE_Q service by other processes in this network. %GNT ********* Group Name Table Section ********************* * * Queue Name Group.Queue Scope *------------------------------ ---------- ----- *GLOBAL_QUEUE1 1.234 G
LCL_QUEUE1 134 L LCL_QUEUE2 135 L LCL_QUEUE3 136 L IVP_test_bindq1 0.0 L IVP_test_bindq2 0.0 L IVP_private_MOT1 4999 L IVP_universal_MOT1 5001 L * alias names for reserved queues SCREEN_PROCESS 0 L AVAIL_SERVER 99 L DECLARE_SERVER 100 L CONNECT_SERVER 100 L QUEUE_SERVER 100 L * %EOS
* %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 * * %END
Example B-1 is a sample of the MessageQ DMQ$TYPCLS.TXT file that is used to define all the message definitions used within the MessageQ system.
Example B-1 SampleMessageQDMQ$TYPCLS.TXT File
* Function: * * This include file defines all the message definitions * * used within the MessageQ system. * * * * NOTE: * * The following are reserved to MessageQ: * * * * Msg Classes: 28, 29, 62 & 30,000 thru 32,767 * * Msg Types: -1 thru -5,000 * *------------------------------------------------------------* ************************************************************** * * * MRS Class and Type codes (800-899) * * * ************************************************************** msg_clas_MRS 28 * define MRS class * * define MRS type codes * msg_type_mrs_dqf_transfer -700 msg_type_mrs_dqf_transfer_ack -701 msg_type_mrs_dqf_transfer_rep -702 msg_type_mrs_dqf_set -704 msg_type_mrs_dqf_set_rep -705 msg_type_mrs_saf_set -706 msg_type_mrs_saf_set_rep -707 msg_type_mrs_ack -801 msg_type_mrs_saf_transfer -805 msg_type_mrs_saf_transfer_ack -806 msg_type_mrs_saf_transfer_rep -807 msg_type_mrs_cnf -840 msg_type_mrs_cnf_ack -841 msg_type_mrs_cnf_nak -842 msg_type_mrs_debug_on -850 msg_type_mrs_debug_off -851 msg_type_mrs_jrn_disable -871 msg_type_mrs_jrn_disable_rep -872 msg_type_mrs_jrn_enable -873 msg_type_mrs_jrn_enable_rep -874 msg_type_mrs_set_pcj -880 msg_type_mrs_set_pcj_rep -881 msg_type_mrs_set_dlj -882 msg_type_mrs_set_dlj_rep -883
************************************************************** * * * PAMS Class and Type codes (900-999) * * * ************************************************************** msg_clas_PAMS 29 * define PAMS class * * define PAMS type codes * msg_type_timer_expired -900 msg_type_list_all_q_req -960 msg_type_list_all_q_resp -961 msg_type_enable_q_notify_req -962 msg_type_enable_q_notify_resp -963 msg_type_disable_q_notify_req -964 msg_type_disable_q_notify_resp -965 msg_type_q_update -966 msg_type_locate_q_rep -972 msg_type_linkmgt_req -975 msg_type_linkmgt_resp -976 msg_type_declare_sq -980 msg_type_undeclare_sq -981 msg_type_allocated_sq -982 msg_type_msg_status -983 msg_type_dmq_server_nak -989 msg_type_enable_notify -990 msg_type_disable_notify -991 msg_type_process_dcl -992 msg_type_process_exit -993 msg_type_list_dcls -994 msg_type_list_all_entrys -995 msg_type_list_all_entries -995 msg_type_list_all_connections -996 msg_type_list_all_groups -997 msg_type_link_lost -998 msg_type_link_complete -999
************************************************************** * * * SBS_SERVER - class: PAMS * * type: codes (1150-1179) * * * ************************************************************** msg_type_sbs_reg -1150 * registration message long form msg_type_sbs_reg_ez -1173 * registration record short form (new v2 format) msg_type_sbs_reg_reply -1152 * registration reply msg_type_sbs_reg_ez_reply -1153 * registration reply msg_type_sbs_dereg_by_id -1154 * deregister request (old v1 format) msg_type_mot_dereg -1154 * deregister request (old v1 format) msg_type_sbs_dereg -1174 * deregister request (new v2 format) msg_type_sbs_dereg_ack -1155 * deregister acknowledgement msg_type_sbs_purge -1157 * purge registration table msg_type_sbs_purge_ack -1158 * purge registration acknowledgement msg_type_sbs_dump_tables -1162 * process, reg, and group tables to log msg_type_sbs_bs_seqgap -1166 * declaration message missing ************************************************************** * * * AVAIL_SERVER - class: PAMS * * type: codes (1180-1189) * * * **************************************************************
msg_type_avail_reg -1180 * available registration
msg_type_avail_dereg -1181 * available deregistration
msg_type_avail_reg_reply -1182 * registration reply
msg_type_avail -1183 * process is now available
msg_type_unavail -1184 * process is now unavailable
**************************************************************
* *
* ETHERNET Class and Type codes (1000-1010) *
* *
**************************************************************
msg_clas_Ethernet 100 * define Ethernet class
* define Ethernet type codes
msg_type_E_connect -1000 * Initiate connection
msg_type_E_disconnect -1001 * shutdown circuit
msg_type_E_initialize -1002 * set Ethernet characteristics
msg_type_E_connect_complete -1003 * circuit established
msg_type_E_connect_rejected -1004 * partner rejected circuit
msg_type_E_partner_disc -1005 * partner disconnected circuit
msg_type_E_io_error -1006 * bad return status from QIO$
msg_type_E_protocol_error -1007 * unrecognized msg from partner
msg_type_E_listen_timeout -1008 * partner's heartbeat stopped
msg_type_E_messages_lost -1009 * detected msg loss
msg_type_E_runtime_error -1010 * detected runtime error in AST
*************************************************
* Generic UCB Types and Classes *
*************************************************
msg_clas_ucb 102 msg_type_ucb_connect -1200 * Initiate connection msg_type_ucb_disconnect -1201 * shutdown circuit msg_type_ucb_initialize -1202 * set UCB characteristics msg_type_ucb_connect_complete -1203 * circuit established msg_type_ucb_partner_disc -1204 * partner disconnected circuit msg_type_ucb_messages_lost -1205 * detected msg loss msg_type_ucb_io_error -1206 * bad return status from QIO$ msg_type_ucb_rcv_data -1207 * data message received by UCB ************************************************************** * * * DEFINE DEMO type codes for DEMO_IO_SERVER * * * ************************************************************** msg_type_demo_add -1200 * add record function * msg_type_demo_chg -1216 * chg record function * msg_type_demo_del -1232 * del record function * msg_type_demo_inq -1248 * inq record function * msg_type_demo_lst -1280 * list record function * msg_type_demo_lst_next -1281 * list next record function * msg_type_demo_client_up -1282 * client up * msg_type_demo_client_down -1283 * client down * ************************************************************** * * * DEFINE LU62 type codes for LU6.2 UCB * * * ************************************************************** msg_clas_appc 62 * define LU6.2 class
msg_type_lu62_init -6200 * init the interface msg_type_lu62_define_lu -6201 * define an LU msg_type_lu62_allocate -6202 * allocate a conversation msg_type_lu62_send_data -6203 * send a data block msg_type_lu62_req_confirm -6204 * ask the remote to CONFIRM msg_type_lu62_send_confirm -6205 * reply to a CONFIRM REQ msg_type_lu62_confirm_recv -6206 * Req CONFIRM, go to recv when obtained msg_type_lu62_deallocate -6207 * deallocate a conversation msg_type_lu62_send_error -6208 * Signal an error msg_type_lu62_delete_lu -6209 * Delete an LU msg_type_lu62_recv_data -6210 * data received from remote partner msg_type_lu62_confirm_req -6211 * remote wants a CONFIRM msg_type_lu62_confirm_send -6212 * remote has CONFIRMED, gone to recv msg_type_lu62_confirmed -6213 * remote has CONFIRMED msg_type_lu62_error -6214 * Error has been signalled msg_type_lu62_deallocated -6215 * Conversation has been deallocated ************************************************************** * * * The following message types are for 2.1 functionality * * * ************************************************************** msg_type_lu62_req_send -6220 * Issue REQUEST_TO_SEND msg_type_lu62_connected -6221 * Remote has allocated a conversation msg_type_lu62_define_tp -6222 * Define TPN for remote to use msg_type_lu62_activate -6223 * Wait for inbound connect msg_type_lu62_ok_send -6224 * Remote is in RECEIVE State msg_type_lu62_flush -6225 * Force transmission of data ************************************************************** * * * The following message types are for the Generic Port Server* * * **************************************************************
msg_type_register_target -6280 * register a VAX TP msg_type_connect_request -6281 * ask for a connection to IBM msg_type_connect_accept -6282 * Connection established msg_type_connect_reject -6283 * Connection request rejected msg_type_connection_terminated -6284 * Connection broken msg_type_change_direction -6285 * IBM issued RECEIVE msg_type_data_message -6286 * Application data / control msg_type_log_event -6287 * Event Log Message msg_type_lu62_add_lu -6288 * dynamic LU definition msg_type_lu62_add_target -6289 * dynamic Target definition msg_type_lu62_report_status -6290 * report LU status to event stream msg_type_lu62_shutdown -6299 * DIVE DIVE DIVE ************* End of PAMS_xxx_TYPE_CLASS **************
Table C-1 describes the impact of increasing or decreasing different OpenVMS and MessageQ parameters.
| Advantage | Disadvantage | Min/Max Value | Parameter Affected |
|---|---|---|---|
| Message Buffer Count | |||
| Increase | |||
| Allows higher number of pending messages. | MessageQ consumes more page file and global pages, and the page count increases for each process. | 8--50,000 for each buffer pool | GBLPAGFIL
GBLPAGES VIRTUALPAGECNT |
| Decrease | |||
| Frees up page file for other programs. | Increases the probability of lost messages or poor performance due to resource exhaustion. | . | . |
| Message Buffer Reserve Count | |||
| Increase | |||
| Allocates a higher number of message buffers for exclusive MessageQ internal use. Results in higher probability of unblocking and internal messages being delivered sucessfully. | Reduces the available number of message buffers for general use. | 0 to all buffers in pool | . |
| Decrease | |||
| Increases available number of buffers. | Increases probability of lost messages or poor performance due to resource exhaustion. | . | . |
| Message Buffer Size | |||
| Increase | |||
| Allows transfer of larger blocks of data in a single call. | Consumes extra memory when data fills only a small portion of the buffer. Increases the size of each MessageQ process due to the creation of the local MessageQ buffers; two to four buffers depending on the features utilized. | 1---31998 (small)
2---31999 (medium) 1500--- 65000 (large) S < M < L |
PGFLQUO
GBLPAGFIL GBLPAGES VIRTUALPAGECNT |
| Decrease | |||
| Higher utilization of available memory. | Increases program complexity to disassemble and reassemble the data buffers when larger data transfers are required. Some features of MessageQ might not work because of the inability to allocate a large enough buffer. | . | . |
| Receive Message Quota | |||
| Increase | |||
| Allows a higher number of pending messages to build up during a burst condition. | A queue might consume a disproportionate amount of resources on its pending queue, causing other parts of the system to have problems. | 0 bytes---2 GB | . |
| Decrease | |||
| Limits resource consumption of slow service rate queues or queues with no reader. | Queues might be unable to receive large messages. Messages might be lost or delayed because they cannot be queued. | . | . |
| MRS NUM_DQF_AREAS | |||
| Increase | |||
| Allows more unconfirmed messages to be stored before a UMA is taken. | Uses more disk space and MRS Server resources. | 100---1000000 | . |
| Decrease | |||
| Reduces disk and MRS Server resource consumption. Reduces time to locate a given message. | Reduces probability of storing a message. | . | . |
| MRS CACHE_PERCENTAGE | |||
| Increase | |||
| Allows the queue to have more outstanding messages, which results in more overlap of the MRS Server I/O when applications process recoverable messages. This quota is a percentage of the byte or message receive quota. | Could cause the MRS Server to consume most or all of the receive byte/message quota on queue attachment. | 1---100 | . |
| Decrease | |||
| Reduces consumption of MessageQ buffers on queue attachment. | Lowers the amount of I/O overlap for reading messages out of the DQF and delivering the messages to the appropriate queue. | . | . |
| MRS Maximum Queues | |||
| Increase | |||
| Allows the MRS Server to track more local and remote queues. | Causes the MRS Server to grow larger to contain these data structures. | 128---2147483647 | FILLM
PGFLQUO VIRTUALPAGECNT |
| Decrease | |||
| Reduces the size of the MRS Server. | The MRS Server might be unable to track all the queues requested. | . | . |
| MRS Maximum Messages | |||
| Increase | |||
| Allows the MRS Server to track more messages | Causes the MRS Server to grow larger to contain these data structures. | 128---2147483647 | PGFLQUO
VIRTUALPAGECNT |
| Decrease | |||
| Reduces the size of the MRS Server. | The MRS Server might be unable to track all the messages requested. | . | . |
| MRS NUM_SAF_AREAS | |||
| Increase | |||
| Allows the MRS Server to handle more remote queues. | Could increase the number of files and disk blocks used by the MRS Server. | 0---1000000 | . |
| Decrease | |||
| Limits the total number of remote queues that can have pending SAF messages. | Might be unable to track all queues requested. | ||
| MRS AREA_SIZE | |||
| Increase | |||
| Reduces disk fragmentation and number of files needed to store messages. | Less efficient use of disk space. | 128---16384 blocks for each file. | FILLM |
| Decrease | |||
| More efficient use of disk space. | Could cause an inordinate number of disk files to be created. Causes disk and directory fragmentation. | . | . |
| MRS Redelivery Timer | |||
| Increase | |||
| Less CPU overhead due to reduced retries. | Less responsive to changes in available resources. | 0--5000 | |
| Decrease | |||
| More responsive in systems with limited resources. | Could cause an inordinate amount of CPU attempting to retry message delivery. | . | . |
This appendix lists the MessageQ directories and logical names.
D.1 Directories
Table D-1 lists the MessageQ directories.
| Directory | Logical | Description |
|---|---|---|
| [DMQ$V nn] | . | MessageQ root area. |
| [.BOOKS] | . | Online Documentation files and release notes (HTML format). |
| [.CVT] | . | MessageQ Conversion Utility |
| [.DMQNS] | . | Default lightweight namespace area. |
| [.DOC] | DMQ$DOC | Documentation files and release notes. |
| [.EXAMPLES] | DMQ$EXAMPLES | Sample programs. |
| [.EXE] | DMQ$EXE | Executable files and command files. |
| [.LIB] | DMQ$LIB | Library holding area for standard object and text libraries. |
| [.MRS. bbbb_ ggggg] | DMQ$MRS | MRS Server data file area for DQFs and SAFs. |
| [.USER. bbbb_ ggggg] | DMQ$USER
DMQ$ACCESS |
Specific user customizing area. The extension is the 4-digit bus ID and 5-digit group ID. |
| [.LOG. bbbb_ ggggg] | DMQ$LOG | Specific group server log file area. |
| [.USER.TEMPLATE] | User customizing area template. Files should be moved before attempting to alter any files. |