You can start the following servers by indicating "YES" for each server entry in DMQ$INIT.TXT file:
To request these MessageQ Servers to start up, set the appropriate ENABLE_xxx parameters to YES in the profile section of DMQ$INIT.TXT. Example 3-2 is a sample of the Profile section. It specifies information that is global to the entire group or information that is needed by the COM server.
Example 3-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 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 * --------------------------------------------------------------------------------
Table 3-2 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 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 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 | YES | Controls the enabling or disabling of 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 MessageQ Selective Broadcast Services and/or AVAIL Services. |
| ENABLE_QXFER | YES/NO | NO | Controls the enabling or disabling of MessageQ MRS Queue Transfer Services. |
| FIRST_TEMP_QUEUE | 200--950 | 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:
|
| 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_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. |
To establish connections to other 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 MessageQ groups through DECnet or TCP/IP connections.
One entry for each MessageQ group should be in the Xgroup section if the group in question is sending messages to another.
Example 3-3 is a sample of the cross-group connection (%XGROUP) table. Refer to Chapter 4 for more information on how to establish cross-group connections. A group must have an entry in the cross-group table for itself.
Example 3-3 Cross-Group Connection Table
------------------------------------------------------------------------------- %XGROUP ***** Cross-Group Connection Table ****** * * gen buf buf recon win dly transport *gname gnumber node cnt warn max type endpt * sec sec *--------- ------- ---------------- --- --- --- --- --- --- ----- ---- ONE_TCPIP 1 sneezy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2001 ONE_TCPIP 1 dopey.abc.com Y -1 -1 -1 -1 -1 TCPIP 2001 ONE_DECNET 1 sneezy Y 75000 -1 -1 -1 -1 DECNET ONE_DECNET 1 dopey Y 75000 -1 -1 -1 -1 DECNET * TWO_TCPIP 2 sleepy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2002 TWO_TCPIP 1 sleepy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2002 TWO_DECNET 2 sleepy Y 75000 -1 -1 -1 -1 DECNET TWO_FAILOVER 2 doc Y 75000 -1 -1 -1 -1 DECNET * * %EOS --------------------------------------------------------------------------------
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.
Example 3-4 is a sample of the Client Library Server configuration table. Refer to Chapter 9 for more information on how to configure the CLS section.
Example 3-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
*
--------------------------------------------------------
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.
Example 3-5 is a sample of the buffer pool configuration table. Refer to Chapter 5 for more information on how to change MessageQ memory allocation.
Example 3-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 * ------------------------------------------------------------------------
The fundamental entity within a message queuing system is the queue. Each message queue has a number of definable attributes. As your 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.
Example 3-6 is a sample of a small portion of the queue configuration table. Refer to Chapter 5 for detailed information on how to define and configure queues.
Example 3-6 Queue Configuration Table
------------------------------------------------------------------------ %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 * %EOS ------------------------------------------------------------------------
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.
Example 3-7 is a sample of the SBS Server section. Refer to Chapter 7 for more detailed information on configuring message broadcasting.
Example 3-7 SBS Server Initialization Section
----------------------------------------------------- %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 universal MOTs END_COMM_SERVICE * %EOS -----------------------------------------------------
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:
Example 3-8 is a sample of the MRS Server initialization section. Refer to Chapter 6 for more information on how to configure the message recovery system.
Example 3-8 MRS Server Initialization Section
------------------------------------------------------------------------------- %MRS ******* MRS 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 --------------------------------------------------------------------------------
Example 3-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 Chapter 8 for more complete information on how to configure MessageQ to support its global naming feature.
Example 3-9 Naming Agent Initialization Section
------------------------------------------------------------------------------- %NAM **************** Naming Agent Section ******************** NA_GROUP 1 NA_GROUP 2 %EOS --------------------------------------------------------------------------------
The following topics are covered in this section:
To set up the MessageQ environment and begin using the 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 MessageQ application is started, you can access its main menu and use the MessageQ main menu to compile, link, and run the utilities.
DMQ$STARTUP has the following format:
$ @DMQ$STARTUP bus_id group_id " " start_servers_flag - $ - optional_parameters
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 |
| " " | Required; a null parameter |
| Start_servers | Optional; It specifies whether you want to start the group's communications servers 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. |
| 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 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 MessageQ message queuing group without starting it; for example, during initial group configuration. To define the MessageQ environment, run the DMQ$STARTUP.COM procedure and specify the start server parameter (the third parameter) as "N" to prevent the servers from starting.
The following example shows how to invoke DMQ$STARTUP without starting the servers. It defines the environment for bus 15, group 1, but does not start the servers. After you run DMQ$STARTUP, you can customize the messaging group using the DMQ$INIT.TXT file.
$ @DUA1:[DMQ$V40.EXE]DMQ$STARTUP 15 1 "" N
DMQ$STARTUP.COM - 9-OCT-1996 14:40:46.88
Bus: 0015
Group: 00001
Disk: DUA1:
Start Servers: No
DMQ Version: DMQ$V40
User Area: DMQ$DISK:[DMQ$V40.USER.0015_00001]
Log Area: DMQ$DISK:[DMQ$V40.LOG.0015_00001]
%DMQ-S-TBLCREATE, Created MessageQ
LNM table DMQ$LNM_0015_00001
%DMQ-S-SETLNM, Set to MessageQ
LNM table DMQ$LNM_0015_00001
Note:
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.
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 2.1 group, execute the following:
$ @DUA0:[DMQ$V21.EXE]DMQ$STARTUP 1 1
To start a Version 3.0 group, execute the following:
$ @DUA1:[DMQ$V30.EXE]DMQ$STARTUP 1 1
Note:
When running multiple versions of 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.
Application programs using 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
MessageQ messages.
3.3.3.1 Application Startup Process
The application startup procedure starts the message queuing group
along with the MessageQ Servers. It then detaches application
server processes with the DCL command RUN/DETACH.
3.3.3.2 Two Methods for Connecting
Because 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 MessageQ bus and group:
The detached process is given a DCL command stream that sets the MessageQ logical name table and runs the application program image. 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. |
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 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.
Example 3-10 shows a detached process attached to bus 15,
group 1.
Example 3-10 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 `bus_id' `grp_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 |
Use the DMQ$SHUTDOWN.COM procedure to shutdown 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 MessageQ images and RTLs for that group. If set to NO (the default), deinstalls group-specific RTL ONLY. |
| stop_fast | Default is YES, which uses the FORCEX utility to stop the COM server and bring down all other MessageQ processes. Specifying NO will result in a graceful shutdown. During a graceful shutdown 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 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.