This chapter describes new and changed features of MessageQ for UNIX Version 4.0A, 4.0, 3.2B, 3.2A and 3.2.
This section describes important information that you need to know before you install MessageQ for UNIX, Version 4.0A.
MessageQ for UNIX Version 4.0A is an update of the Version 4.0 media kit and contains some corrections to MessageQ software and documentation as documented in these release notes.
The installation procedure for Version 4.0A is the same as the procedure for MessageQ for UNIX, Version 4.0. For complete information on how to install MessageQ software, refer to the Read Before Installing MessageQ for UNIX Version 4.0A.
MessageQ for UNIX Version 4.0A uses Version 4.0 configuration files. If you have not already upgraded your group initialization files to Version 4.0, MessageQ provides a program called dmqconvert.exe that converts a Version 3.2 group initialization file into a format that can be used with MessageQ for UNIX Version 4.0. The conversion utility does not add any new Version 4.0 features to the group initialization file. These must be added to the converted file using a text editor. Refer to the Installation and Configuration Guide for UNIX for complete information on how to configure MessageQ and how to convert existing configuration files.
If you have recompiled and relinked your applications to run Version 4.0 of MessageQ for UNIX, you need only relink your applications. You do not need to recompile applications for Version 4.0A. However, if you received Version 4.0A as your initial upgrade from Version 3.2 of MessageQ for UNIX, you may need to recompile and relink your applications due to changes in several PAMS API functions. For more information about how changes to the PAMS API may affect your application, refer to the following section entitled "Changes to the PAMS API" in these release notes.
Running a program linked with an earlier version of MessageQ in a Version 4.0A group may cause the program to function improperly. We recommend relinking your applications with the latest version of MessageQ software before you run your existing applications.
To determine the version of MessageQ that is linked with your application, enter the following command:
If you are running MessageQ for UNIX, Version 3.2A or later, MessageQ displays the following information:
If no output appears, you are running MessageQ Version 3.2 or earlier. Enter the following command to list the exact version number:
MessageQ will display a line similar to the following:
what <application_name> | grep pams_attach
Command output DmQ Version
-------------- -----------
pams_attachq.c 4.0a.7 97/10/14 sjz 4.0A
pams_attachq.c 4.0.5 96/04/02 sjz 4.0
pams_attachq.c 3.2a.76 96/04/22 sjz 3.2Awhat <application name>
MessageQ for UNIX, V40A Wed Oct 22 00:00:00 EDT 1997
This section describes the new and changed features for Version 4.0A release of MessageQ for UNIX:
New and Changed Features in MessageQ Version 4.0A
The Performance Test utility enables users to test the message throughput of their current configuration by sending messages in a selected MessageQ configuration and reporting messaging rates. This utility runs as a MessageQ application and is invoked using a simple command line interface. The utility can send or receive a series of messages up to the maximum message size of 4MB and supports all Delivery Modes and Undeliverable Message Actions. For complete information on how to run and use the Performance Test utility, refer to the "Corrections to Documentation" section of these release notes.
MessageQ now supports queues numbered to 3999. You can set the maximum queue number for your configuration using the GROUP_MAX_USER_QUEUE parameter in the %PROFILE section of the group initialization file. The default value for this field is 999. MessageQ Version 4.0A applications that are being designed to work with earlier versions of MessageQ must continue to adhere to the queue number limit of 999 imposed by earlier versions of the software.
In Version 3.2 and earlier the CLS supported same-client reconnect to permanent queues. This allowed a client to attach multiple times to the same queue without receiving the PAMS__DECLARED error status. This capability has been removed from the CLS for Version 4.0 because it was non-standard behavior.
The primary impact of this change will be on Visual Basic developers who run their application in design mode; attach to a permanent queue; and then stop the application without detaching. They will receive PAMS__DECLARED the next time they run the application.
We recommend that Visual Basic developers always perform a pams_exit() from the Form_Load event before calling any other MessageQ API functions. This action will terminate any previously open connection and allow the pams_attach_q to succeed.
MessageQ for UNIX Version 4.0A provides shared library support. Users can now take advantage of shared library and shared objects by linking their applications against the shared libraries and setting their LD_LIBRARY_PATH to include to include Using shared libraries reduces overall system memory consumption when running multiple MessageQ applications. It also reduces the need to recompile and relink applications when your MessageQ software is upgraded.
/usr/lib or the directory where the shared library software is installed.
Refer to the section entitled "Corrections to Known Problems" for a description of all software corrections contained in this release.
This section describes the new and changes features for Version 4.0 release of MessageQ for UNIX:
New and Changed Features in MessageQ Version 4.0
The following changes have been made to the MessageQ include files:
Changes to the MessageQ Include Files
To create greater consistency of environment configuration between platforms, the bus control process has been eliminated from MessageQ configuration on UNIX systems. For Version 4.0, users configure each group using the dmqinit.txt file and start each group using the MessageQ startup procedure called "dmqstartup." Users can duplicate the capability of the bus initialization file by creating a shell script that starts multiple groups on the same node.
MessageQ now includes a procedure for immediately shutting down message queuing groups from the command line. Enter "dmqshutdown" with the bus and group number to shut down a group.
The ability to distribute broadcast messages to any number of registered recipients is now available on all MessageQ message server implementations. The default configuration for each MessageQ Version 4.0 group enables the use of Selective Broadcast Services (SBS). Note that the SBS Server must be enabled in order for the message queuing group to provide AVAIL/UNAVAIL services.
Self-describing messaging (SDM) provides a new form of MessageQ messaging. Previously, MessageQ applications passed information using a message buffer whose format and structure were agreed upon by the sender and receiver program. SDM enables applications to construct messages containing both the message content and the information needed by the receiver program to understand what is in the message. The receiver program dynamically interprets the contents of the message by "decoding" some or all of the data contained in it. SDM also provides automatic data marshaling between platforms that use different data formats.
SDM consists of the following new API functions: Elimination of the Bus Control Process
Addition of Group Shutdown Utility
Message Broadcasting on all Platforms
Self-describing Messaging
For information on how to use SDM, refer to the BEA MessageQ Programmer's Guide.
MessageQ can now send and receive messages of up to 4MB using buffer-style and handle-style messages. Note that the time necessary to send a message is directly proportional to the size of the message. User applications must be designed to wait an appropriate length of time for a message to be delivered. The delivery period is a function of the delivery mode, uma, and message size.
In the case of cross-group messaging, user applications must also factor possible network latencies into the delivery interval. In the case of recoverable messages, users applications must also factor disk I/O into the message delivery interval.
In addition, system load can also be a factor in the delivery period for queued messages. In some instances, the total amount of time necessary to deliver a message may exceed the default timeout of 30 seconds for the pams_put_msg function. Refer to the BEA MessageQ Programmer's Guide for more information on how to use this feature.
MessageQ Version 4.0 adds a new API function called pams_bind_q. This API function has been added to enable applications to associate a queue address with local and global queue names.
Global naming enables MessageQ applications to refer to message queues in remote groups by name without having to define the name in each referring group's initialization file.
The following changes have been made to the group initialization file on UNIX:
MessageQ now enables users to change configuration data for groups and queues at runtime. Previously, a group had to be shut down and restarted to enable changes to group configuration. Now users can make required changes to the initialization file for the group and invoke the MessageQ Loader program to change the configuration of a running group. Refer to the MessageQ Installation and Configuration Guide for UNIX for information on which parameters can be changed at runtime and how to run the Loader utility.
The following PAMS API functions have been changed for Version 4.0: Ability to Change Configuration Data at Runtime
Changes to PAMS API Functions
Refer to the BEA MessageQ Programmer's Guide for complete reference description of these new and changed programming functions.
MessageQ Version 4.0 adds features for stopping groups and queues orderly and fast, starting queues, and starting and stopping cross-group connections and the Client Library Server using the Monitor utility. The following options are available through both the character-cell and Motif-based Monitor utility.
Refer to the MessageQ Installation and Configuration Guide for more information on how to use each of these features.
Message Recovery Services on MessageQ for UNIX systems offer significant performance improvements over Version 3.2. In addition, MessageQ for UNIX now enables users to selectively receive recoverable messages by specifying the in-memory queue depth of recoverable messages.
MessageQ for UNIX Version 4.0 will support the link management API functions that are currently supported on OpenVMS systems. These functions include:
Enhancements to Message Recovery
Support for Link Management API Messages
Refer to the BEA MessageQ Programmer's Guide for information on how to use each of these request and response messages.
All MessageQ manuals have been revised for Version 4.0. The following manuals are available online as HTML files:
Distribution of Documentation Online
To use the online documentation, you must install the optional subset called "Online Documentation." Once installed, invoke a World Wide Web browser, and use the "Open File" option to open the following files:
MessageQ now returns the error code PAMS__BADPARAM if the p_timeout argument of the pams_set_timer is specified as zero or a negative number. In addition, the pams_set_timer function returns an error code if the timer_id argument is set to zero.
In addition, the s_timeout argument now supports the use of the system time format as well as the PAMS time format. Refer to the BEA MessageQ Programmer's Guide for more information on how to use this API function.
The ability to set a group-wide memory threshold has been replaced with the ability to set a group-wide memory limit. Rather than logging warnings and continuing to grow, the group server will return a PAMS__EXCEEDQUOTA status for a message that would cause the limit to be exceeded.
To set the limit, use the GROUP_MAX_BYTES property in the %PROFILE section of the group initialization file. To set a limit that corresponds to the threshold you used with MessageQ Version 3.x, simply set GROUP_MAX_BYTES to the value in the Threshold column of the group's entry in the %XGROUP section. If you do not set a value for GROUP_MAX_BYTES, the default value of 8388608 will be used.
The ENABLE_NOTIFY message supports notification when cross-group messages are established and lost. It no longer supports notification of primary queue attachments and detachments. Therefore, the use of the attachment_flag is no longer a valid field in the message. Applications using the attachment_flag field will not compile under MessageQ for UNIX, Version 4.0. ApplicationS requiring notification of queue attachments and detachments should use the ENABLE_Q_NOTIFY_REQ.
MessageQ for UNIX Version 4.0 incorporates a change to the behavior of AVAIL Services deregistration to provide compability among all MessageQ servers implementations. Applications running under MessageQ for UNIX Version 4.0 must now explicitly cancel AVAIL Services registration using the AVAIL_DEREG message. AVAIL Services registrations will no longer be cancelled automatically by MessageQ when the requestor process exits. Instead, the only automatic cancellation of registration message occurs when the distribution queue becomes unavailable.
This section describes the following new features of MessageQ for UNIX software implemented in the version 3.2, 3.2A and V3.2B release:
/usr/kits/DMA400/books/bookshelf.html (Digital UNIX)
or
/usr/kits/DMQ400/books/bookshelf.html (all other UNIX systems) Changes to pams_set_timer Function
Change to Parameter Setting for Group-wide Memory
Change to ENABLE_NOTIFY Message
Change to AVAIL Services Deregistration
New and Changed Features in MessageQ
Versions 3.2, 3.2A and 3.2B
The on-disk structure of journals has changed to improve message recovery capabilities when disk crashes or power failures occur.
Message Recovery performance has been increased on all UNIX platforms. Performance increases vary by processor type, operating system and delivery mode. Significant improvements in message throughput have been measured during product testing.
The PAMS__DECNETDEAD return code is obsolete and has been removed from the p_return.h file. If your application references this return code, you must remove it, then recompile and relink your application.
This section describes changes to Message Recovery Services.
Improved Message Recovery Capabilities
Improved Message Recovery Performance
Changes to Return Codes for Version 3.2A
Changes to Message Recovery Services
Each SAF or DQF journal set is limited to 65,536 files per journal set. Each journal file is currently 0.5MB, this limits the size of any single journal set (SAF, DQF) to 32 GB. PCJ and DLJ journal sets are limited to 4,294,967,296 files per set at 0.5MB per file. This limits the size of these journals to 2251 terabytes each.
It is important to note that journal file names are unique within a bus but not between buses. Therefore, message queuing environments running more than one message queuing bus must ensure that journal files are not accidentally shared by applications running on different message buses.
LLLLQQQQSSSS.DQF
LLLLRRRRSSSS.SAF
LLLLSSSSSSSS.PCJ
LLLLSSSSSSSS.DLJwhere 'L' is the 4 digit local group number in hex
'Q' is the 4 digit queue number in hex
'R' is the 4 digit remote group number in hex
'S' is the file sequence number within a set of files
The -b and -g switches to this command override the settings of the environment variables DMQ_BUS_ID and DMQ_GROUP_ID.
The -m option allows users to specify one of the following modes of operation:
Valid journal types include :
dmqjplay -b bus -g group -m mode -t journal_type -j
journal_path [-l log_path]"r" - reads and sends messages from journal
"t" - reads, sends and deletes messages from journal
"d" - reads and deletes messages from journal
The journal path is the directory where the journals are located. Using the -l option redirects any errors to the specified log file.
The -b and -g switches to the command line options specify the bus and group of the journals to be dumped. These settings override any definition of the environment variables DMQ_BUS_ID and DMQ_GROUP_ID.
The -t option allows users to specify the type of journal to be dumped. Valid journal types include:
dmqjdump -b bus -g group -t journal_type -h header_type
-m message_format -j journal_path [-d] [-l log_path]
[-o output_file] [-n number]
Valid header types include :
Valid message formats include :
The journal path is the directory where the journals to be dumped can be found.
Specifying the -d option deletes messages from the journal as they are dumped. USE WITH EXTREME CAUTION.
The -l option redirects messages and any errors, dumping the journals to the specified log file.
The -o option redirects messages to the specified output file.
The -n option limits the number of messages dumped to the associated argument provided with the option.
MessageQ for UNIX, Version 3.2 runs on AT&T 3430 processors under NCR UNIX.
The MessageQ for UNIX installation procedure now includes an option for installing the MessageQ UNIX Client. The MessageQ UNIX Client allows applications running in a UNIX environment to send and receive messages to target applications in a networked environment using the MessageQ Client Library Server software running on a MessageQ server system.
The MessageQ UNIX Client provides applications with full support of MessageQ features without requiring the system resources needed by a MessageQ UNIX message server that supports full message routing. User applications designed as clients or servers can be deployed on systems running MessageQ Client software.
MessageQ for UNIX, Version 3.2 requires changes to the documented UNIX kernel configuration settings as follows:
Support for NCR UNIX Systems
Addition of MessageQ UNIX Client
Changes to UNIX Kernel Configuration Settings
For example, the formula for determining the MSGMNI setting for a bus and group with MRS and one link up is:
1 bcp + 1 gcp + 1 qe + 2jps + 3 lds = 8 processes
In addition to the 8 processes, this example assumes that 2 applications are running. Therefore, the MSGMNI setting is determined by totaling the processes and adding one for the bus and one for the group resulting in a setting of 12. The MSGMNI setting must be increased if links, processes and applications are added.
For information on how to set UNIX kernel parameters, refer to the MessageQ Installation and Configuration Guide for UNIX.
Version 3.2 of MessageQ for UNIX systems contains a new API function called pams_status_text. Application developers can use this API function to obtain a descriptive text string and a severity level for each API return value.
This function receives the status value and returns a text description in the following format:
The text description contains the text name of the return code (as it appears in the documentation and development include files) followed by a comma, a space, and then a status description. If the user buffer is large enough, the string is zero terminated. In addition to the text description, this function returns a code indicating the severity level for both success and error messages. Severity levels are designed to provide more information about the message being returned.
For example, the pams_detach_q has two of the possible success return codes; PAMS__SUCCESS and PAMS__DETACHED. The PAMS__SUCCESS return code is used to indicate that you successfully detached the specified queue(s). PAMS__DETACHED is an informational return code indicating that the call was successful and that you have detached your last queue (which effectively detaches you from the message bus in the same manner as a call to pams_exit).
Following are the valid severity codes for MessageQ messages and their meaning:
New API Function Returns Text Description of Return Status
PAMS__SUCCESS, normal successful completion
MessageQ for UNIX Version 3.2B includes a change to the behavior of cross-group connections. In previous versions of MessageQ, when a group tried to connect to a specific system and the hostname was not translatable by the network name service, the result was a fatal error.
In Version 3.2B, the group now logs the error and continues to try to create the cross-group connection. The advantage to this change is that manual intervention is no longer required in order to reissue the reconnection request. In addition, the continuous retry feature enables the connection to automatically become established when the network error condition is resolved.
Change to Behavior of Cross-Group Connections