DECmessageQ Release Notes for UNIX November 1996 The DECmessageQ Release Notes for UNIX systems describe software changes implemented for Versions 3.2A 3.2, and 3.1 as well as corrections, known problems, and restrictions. The release notes also contain corrections to documentation distributed with this software. Software Version: DECmessageQ for AIX, Version 3.2A DECmessageQ for Digital UNIX, Version 3.2A DECmessageQ for HP-UX, Version 3.2A DECmessageQ for NCR UNIX, Version 3.2A DECmessageQ for Solaris, Version 3.2A DECmessageQ for SunOS, Version 3.2A This release notes file contains: 1. New and Changed Features in DECmessageQ 2. Corrections to Known Problems 3. Known Problems and Limitations 4. Corrections to Documentation For more information about DECmessageQ products, please visit our World Wide Web site at: http://www.digital.com/info/decmessageq ========================================================================== New and Changed Features in DECmessageQ ========================================================================== This section includes information on: o Read Before installing Version 3.2A o New and changed features of Version 3.2A o New and changed features of Version 3.2 o New and changed features of Version 3.1 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Before You Install DECmessageQ Version 3.2A ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes important information that you need to know before you install DECmessageQ for UNIX, Version 3.2A. - How do I install DECmessageQ for UNIX, Version 3.2A? Installation instructions for Version 3.2A are the same for Versions 3.1, 3.2, and 3.2A. Refer to the DECmessageQ Installation and Configuration Guide for UNIX for instructions on how to install DECmessageQ for UNIX software. Refer to the Read Before Installing DECmessageQ for UNIX, Version 3.2A or the Software Product Description for a list of installation prerequisites for using this version of DECmessageQ. - Do I need to change my existing configuration files to run Version 3.2A? No. Version 3.1 and 3.2 configuration files can be used when running DECmessageQ for UNIX, Version 3.2A. - Do I need to recompile my existing applications to run them under Version 3.2A? No. - Do I need to relink my existing applications to run them under Version 3.2A? Yes. To take advantage of the changes made to the API functions in Version 3.2A, you must relink your applications with the latest version of the object library libdmq.a. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ New and Changed Features in DECmessageQ for Version 3.2A ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes the following new features of DECmessageQ for UNIX software implemented in the version 3.2A release: - Improved message recovery capabilities - Improved message recovery performance - Changes to return codes - Changes to cross-group configuration - Changes to message recovery services - Changes to dmqjplay utility - Changes to dmqjdump utility - Change to building applications on Digital UNIX systems Improved Message Recovery Capabilities The on disk structure of journals has changed to improve message recovery capabilities when disk crashes or power failures occur. Improved Message Recovery Performance 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. Changes to Return Codes for Version 3.2A 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. Changes to Cross-group Configuration DECmessageQ Version 3.2A allows configuration of multiple cross-group connections to systems that have several different network interfaces. The cross-group connections must use different names to connect to each of the network interfaces. To utilize this feature, the cross-group section of the group initialization file must be configured as follows: o DECmessageQ Version 3.2A allows a cross-group entry to use the name of its network interface as the node name rather than the host name of the machine, if they are different. The name of the network interface forms an alias name for the group. The message queuing group verifies this name and sends it to a target group when the group initiates a cross-group connection. Therefore, if a node crashes, the group and its alias can be assigned for use on another node. Conversely, if the target group has cross-group verification enabled, it can have only one cross-group entry for the group that originated the cross-group link. This cross-group entry must specify the originating group's alias and not its host name. o The cross-group section of the group initialization file can contain multiple entries that specify different network interfaces for the system on which the group is running. When a remote group connects using one of these interfaces, the local group will complete the connection in the reverse direction by advertising itself using the same interface. Changes to Message Recovery Services a) Message Recovery Services under Version 3.2A no longer requires two processes. In Version 3.2A, the auxillary journal process (dmqjaux) is integrated into the dmqjourn process. b) Journal file names are now 16 characters in length. Each name is specified with a 12-digit file name, a dot, and a 3 character extension as follows: LLLLQQQQSSSS.DQF LLLLRRRRSSSS.SAF LLLLSSSSSSSS.PCJ LLLLSSSSSSSS.DLJ where '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 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 group but not between groups. 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. c) The command line options for the dmqjplay utility have changed dmqjplay -b bus -g group -m mode -t journal_type -j journal_path [-l log_path] 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: "r" - reads and sends messages from journal "t" - reads, sends and deletes messages from journal "d" - reads and deletes messages from journal Valid journal types include : "d" - dead letter journal "p" - post confirmation journal The journal path is the directory where the journals are located. Using the -l option redirects any errors to the specified log file. d) the command line options for the dmqjdump utility have changed dmqjdump -b bus -g group -q queue -t journal_type -h header_type -m message_format -j journal_path [-d] [-l log_path] [-o output_file] [-n number] 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 defin- ition 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 : "dlj" - dead letter journal "dqf" - destination queue file "pcj" - post confirmation journal "saf" - store and forward Valid header types include : "summary" - which display the source target, type and class of each message dumped. "detail" - which displays all the internal header fields of each message dumped. Valid message formats include : "hex" - output is displayed in hex bytes with ascii translation "script" - output is displayed in DECmessageQ script format 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. Change to building applications on Digital UNIX systems When building DECmessageQ applications on Digital UNIX systems, users must link against the library libots.a in addition to the DECmessageQ library as shown below: # cc myapp.c -ldmq -lots -o myapp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ New and Changed Features in DECmessageQ for Version 3.2 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes the following new features of DECmessageQ for UNIX software implemented in the Version 3.2 release: - Support for NCR UNIX Systems - Addition of DECmessageQ UNIX Client - Enhanced messaging throughput - Changes to UNIX kernel configuration settings - New API function returns a description for each status value Support for NCR UNIX Systems DECmessageQ for UNIX, Version 3.2 runs on AT&T 3430 processors under NCR UNIX. Addition of DECmessageQ UNIX Client The DECmessageQ for UNIX installation procedure now includes an option for installing the DECmessageQ UNIX Client. The DECmessageQ UNIX Client allows applications running in a UNIX environment to send and receive messages to target applications in a networked environment using the DECmessageQ Client Library Server software running on a DECmessageQ server system. The DECmessageQ UNIX Client provides applications with full support of DECmessageQ features without requiring the system resources needed by a DECmessageQ UNIX message server that supports full message routing. User applications designed as clients or servers can be deployed on systems running DECmessageQ Client software. The UNIX Client includes the following components: - Configuration Utility(dmqclconf) is used to define the run-time configuration options for UNIX client applications. These options includes settings for the default server, the failover server, MRS options, logging options, and trace options. - MRS Utility(dmqclmrsu) may be used to display the contents of local store-and-forward (SAF) journal files. It also provides the ability to selectively re-transmit any message from the SAF journal. - Event Watcher Utility(dmqclwatch) provides a mechanism to view the messaging activity of UNIX client applications at runtime. This utility displays messages transmitted and/or received by the application. - DmQ Test Utility(dmqcltest) allows users to interactively perform DECmessageQ message operations. For example, attaching to a queue and sending a message to an application that is being tested. Users can set delivery modes and other parameters when sending messages using the Test Utility. - Local SAF journal file-the UNIX client provides a store-and-forward (SAF) capability that allows client applications to send messages when the network connection to the server group is not available. If MRS is enabled, recoverable messages are written to the SAF journal. All messages in the SAF journal are transmitted when the network connection to the CLS is re-established. - Client library trace and error log files-the UNIX client provides the ability to trace run-time activity and error messages to log files. If error logging is enabled (in dmq.ini), error messages will be written to a file called dmqerror.log in the application working directory. If client library tracing is enabled, detailed trace messages are written to a file called dmqcldll.log in the application working directory. - Message logging-provides the ability to write a copy of all messages sent or received to a file. This allows you to obtain a complete history of the messaging activity of your application. If message logging is enabled, messages are logged to a file called dmqtrace.log in the application working directory. Message logging can be configured to capture messages sent, received, or both. Message logging is very useful in testing and debugging applications. Enhanced Messaging Throughput Version 3.2 of DECmessageQ for UNIX includes changes designed to enhance message throughput. Customers may experience a 10% to 50% increase in messaging rates when running applications under DECmessageQ for UNIX Version 3.2. Changes to UNIX Kernel Configuration Settings DECmessageQ for UNIX, Version 3.2 requires changes to the documented UNIX kernel configurating settings as follows: o The setting required for the MSGMNI has increased. System managers must allow 1 IPC message queue for each DECmessageQ process and one for each of the following: - DECmessageQ application process - message queuing group - message queuing bus 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. o The MSGTQL parameter must be set to a value greater than or equal to the MSGMNI setting. o The SHMMIN parameter must be set to 1. For information on how to set UNIX kernel parameters, refer to the DECmessageQ Installation and Configuration Guide for UNIX. New API Function Returns Text Description of Return Status Version 3.2 of DECmessageQ 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: PAMS__SUCCESS, normal successful completion 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 DECmessageQ messages and their meaning: 0=warning 1=success 2=error 3=an informational form of success 4=fatal error For a description of this new API function in reference page format, refer to the section of the release notes called "Corrections to Documentation." ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ New and Changed Features in DECmessageQ for Version 3.1 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes the following features of DECmessageQ for UNIX software implemented in the Version 3.1 release: - Access control list (ACL) type queue security - Congestion control - Addition of per queue quotas - Ability to invalidate selection masks on detach - Addition of connection timeout for link drivers - Changes which require recompiling and relinking applications - Changes to the DECmessageQ for UNIX group initialization file format requiring conversion of existing group configuration information - Enhancements to message-based services support - Integration of the Client Library Server with the DECmessageQ for UNIX products - Changes to return codes - Changes to timer selection - Changes to temporary queue allocation Support for ACL Queue Security DECmessageQ for UNIX Version 3.1 supports a form of access control list (ACL) queue security. DECmessageQ protects queues from unauthorized reading by preventing a process from attaching to a queue if it does not have privilege to open a protected file on disk. To implement the queue security feature, DECmessageQ for UNIX creates a directory tree structure in the /var/tmp/dmq directory. The path to the ACL security file for a selected queue is a combination of the bus, group, and queue number as follows: /var/tmp/dmq/b_xxxx/g_yyyyy/acl/q_zzz where `xxxx' is the number of the bus in decimal with leading zeros, `yyyyy' is the number of the group in decimal with leading zeros, and `zzz' is the number of queue in decimal with leading zeros. For example, the security file for queue 50 in group 2 of bus 777 is: /var/tmp/dmq/b_0777/g_00002/acl/q_050 You configure a queue to use queue security by placing the letter `Y' in the last column of a queue entry in the %QCT section of the initialization file. For more information on how to configure a queue, refer to the section entitled "Defining Permanent Queues" in the DECmessageQ Installation and Configuration Guide for UNIX. If you specify ACL security for a queue and the security file does not exist, you will not be able to attach the queue and you will receive an error status of PAMS__NOACL. If the security file exists, you must have read/write access to the security file to attach the queue. If you cannot open the file for read/write access, the attach operation will fail and return an error status of PAMS__NOPRIV. The instructions for setting file protections varies based on your file system. For most UNIX systems, the commands chmod, chown, and chgrp are used to set file protections. For more information, refer to the documentation for the file system you are using. Congestion Control When the message queuing environment becomes congested, DECmessageQ allows you to control the flow of messages by setting environment variables that limit messaging rates on a per process basis. DECmessageQ uses a congestion control algorithm to reduce the number of messages being enqueued which allows the system to process the backlog of messages. When the congestion condition subsides, DECmessageQ gradually raises the rate of message flow back to the maximum flow rate set for the queue. The set of rules for enforcing congestion control are as follows. - While a congestion condition exists the enqueue and dequeue rate of all processes is monitored. - The maximum rate at which any process can enqueue messages during a congestion condition is equal to a maximum value which is adjusted at regular intervals. - If, during a period of congestion, a process enqueues more messages than it dequeues, its message flow rate is reduced by a percentage of its current flow during the next interval. - Once a period of congestion has subsided the flow rate of each process is adjusted upward until the flow rate exceeds the maximum congestion flow rate (DMQ_FLOW_MAXIMUM). At this point flow control is no longer enforced. The following table lists the congestion control environment variables have been added to DECmessageQ for UNIX Version 3.1: Environment Variable Description --------------------- ----------------------------------------------- DMQ_FLOW_MAXIMUM Maximum number of messages per second a process can enqueue during a period of congestion. If not specified, the default value is set to 1000 messages per second. DMQ_FLOW_MINIMUM Minimum number of messages per second a process can enqueue during a period of congestion. DECmessageQ will always allow you to enqueue at least this number messages per second. If not specified, the default value is set to 10 messages per second. DMQ_FLOW_INTERVAL Interval at which DECmessageQ checks message flow and makes adjustments to the current flow rate. The value is expressed in milliseconds If not specified, the default value is set to 250 milliseconds. DMQ_FLOW_INCREASE Number of messages per second to increase the flow rate at the current interval after a congestion period has subsided. If not specified, the default value is set to 10 messages DMQ_FLOW_DECREASE Percent reduction of the current flow rate to applied at each interval during periods of congestion. If not specified, a default value of 0.25 is used. This value must be specified as real number in the range [0.0 to 1.0). If the value is set to zero, then the maximum flow rate for the given process is equal to the flow maximum as defined by the environment variable DMQ_FLOW_MAXIMUM and is not adjusted downward at each flow interval To set up congestion control for an application, use the following syntax to set the appropriate environment variables before you start the application: The correct command using C shell syntax is: setenv DMQ_FLOW_MAXIMUM 500 The correct command using Bourne shell syntax is: DMQ_FLOW_MAXIMUM=500 export DMQ_FLOW_MAXIMUM Because the environment variables are set on a per process basis, it is possible to set different values for each application in the environment. Addition of Per Queue Quotas In DECmessageQ Version 3.0 queue quotas had to be enabled or disabled for an entire message queuing group. Version 3.1 allows queue quotas to be enabled on a per queue basis. You enable per queue quotas as follows: - On UNIX systems you can enable or disable message and byte quotas for a selected queue at startup by setting the Enable Quotas field for each entry in the %QCT section of the group initialization file. You can also use the Monitor utility to enable or disable message and byte quotas for a selected queue at runtime. For more information, refer to the DECmessageQ Installation and Configuration Guide for UNIX. Support for Selection Invalidation on Detach Version 3.1 of DECmessageQ for UNIX systems supports a new constant value for the detach_opt_list argument of the pams_detach_q service. The new option, called PSYM_CANCEL_SEL_MASK, allows you to implicitly cancel all selection masks that reference the queue or queues that you are detaching. If you do not specify this option, the pams_detach_q function automatically invalidates selection masks that reference the queue you are detaching. The invalidated selection masks can no longer be used and must be explicitly canceled using the pams_cancel_select function. Any attempt to use an invalid selection mask will result in a return status of PAMS__STALE to the pams_put_msg function. Reattaching a detached queue does not validate any previously invalidated selection masks referencing that queue. For example, if you have a selection mask that references a queue and you detach that queue without canceling the selection mask, the pams_detach_q function marks the selection mask invalid. Once a selection mask is marked invalid it can no longer be used and you should cancel the selection mask using pams_cancel_select. Connection Timeout for Link Drivers The DECmessageQ for UNIX link drivers now provide a series of connection timeout parameters that allow you to define how often to check the status of a connection when there is no traffic going across that connection. These timeout parameters are implemented as the following new environment variables: - DMQLD_PING_INTERVAL - the Link Sender processes generate ping messages to test the state of the connection. The ping interval is the number of seconds between tests. If no value is specified, the default is 30 seconds. - DMQLD_PING_TIMEOUT - in the event a Link Receiver does not respond to a ping from a Link Sender, this is the amount of time that the Link Sender should wait before aborting the connection. If no value is specified, the default 60 seconds. You should set these environment variables before starting your bus and group. Recompiling Applications for Version 3.1 If your applications use the pams_confirm_msg function or function prototypes, you must recompile your applications to run under DECmessageQ Version 3.1 on UNIX systems. If you recompile your applications you must also relink them. Relinking Applications on UNIX Systems The DECmessageQ Version 3.1 release for UNIX systems includes changes to internal DECmessageQ data structures. To run DECmessageQ applications on UNIX systems in the Version 3.1 runtime environment, you must relink your applications. Modifications to the Group Initialization File DECmessageQ for UNIX, Version 3.1 uses a new group initialization file format that is compatible with DECmessageQ for OpenVMS. A conversion utility, convert.sh, is provided on UNIX platforms to convert existing group initialization files to the new format. The following changes have been made to the group initialization file on DECmessageQ for UNIX platforms: Section Description of Change --------- ---------------------------------------- %BUFFER The %BUFFER section has been added for greater compatibility across all DECmessageQ platforms. Currently, the information in this section is not used by DECmessageQ for UNIX systems. %CLS The %CLS section is used to define the Client Library Servers to be started at group startup time. For more information on configuring Client Library Servers on UNIX systems, refer to the DECmessageQ Installation and Configuration Guide for UNIX. %MRS The MRS section has been added for greater compatibility across all DECmessageQ platforms. The MRS journal paths previously defined in the %PROFILE section are now defined in the %MRS section. %QCT The %QCT section has been modified to enable per queue byte and message quotas, and the specification of ACL queue security. For more information on the format of the new %QCT section, refer to the DECmessageQ Installation and Configuration Guide for UNIX. %SBS The %SBS section of the group initialization file has been added for greater compatibility across all DECmessageQ platforms. This section is not used, however, because Selective Broadcast Services are not currently available DECmessageQ for UNIX systems. For more information on how to convert your group initialization files, refer to the DECmessageQ Installation and Configuration Guide for UNIX. Enhanced Support for DECmessageQ Message-Based Services This section describes the enhanced support for DECmessageQ message- based services in Version 3.1 of DECmessageQ for UNIX systems. Changes to the AVAIL_REG and AVAIL_DEREG Messages a)The AVAIL_REG and AVAIL_DEREG messages are sent to the AVAIL_SERVER queue. In DECmessageQ Version 3.0 for UNIX systems, the primary queue of the AVAIL_SERVER process was assigned to queue 100. However, for Version 3.1 this number has changed to be compatible with other DECmessageQ products. The new value is defined as PAMS_AVAIL_SERVER in the p_proces.h include file and is also defined in the Group Name Table section of the group initialization file. The ability to send AVAIL_SERVER messages to queue 100 will continue to be supported for backward compatibility. b)In DECmessageQ Version 3.0 or earlier, if an application required notification on the availability of a remote queue, it had to register with the AVAIL_SERVER for the group in which the queue resided. In Version 3.1, applications can now receive notification on remote queues by registering with the AVAIL_SERVER in their local group. NOTE: UNIX applications running on DECmessageQ V3.1 systems will be able to register with their local AVAIL_SERVER to obtain notification of queue availability on systems running DECmessageQ for OpenVMS Version 3.1. c)Changes to link status which affect the availability of remote queues are now reported by the AVAIL_SERVER process. For example, you may be registered to receive AVAIL/UNAVAIL messages for a remote queue. Initially you receive an AVAIL message when the queue is available to receive messages. However, if the link to that message queuing group goes down, the AVAIL_SERVER will send you an UNAVAIL message for that queue because cross-group communication is not possible. d)Notification of queue availability and link status now work in a routing environment. e)In Version 3.1, the new C message structure for the AVAIL_REG message enables you to specify a timeout value when registering for AVAIL/UNAVAIL services. The timeout value is expressed in seconds and represents the period of time to wait for acknowledgment before failing a registration for a target queue in a remote group. If registration is not completed within the timeout interval, the sender program receives a reply message with a status value of PAMS__EXPIRED. f)The AVAIL_REG data structure has been modified to overcome some RISC alignment issues and to support registration with a timeout. If your application uses the Version 2.0 AVAIL_REG message you must change it as follows: 1.Replace the AVAIL_REG declaration in your program to use the following: typedef struct { short version; /* version = 31 */ short filler; q_address target_q; q_address distribution_q; int32 timeout; } AVAIL_REG; 2.Set the version number to 31. 3.Set the timeout value to 0 for an indefinite timeout period. Or, set the timeout period to the interval (in seconds) for which you want DECmessageQ to attempt to perform the registration. g)The AVAIL_DEREG data structure has been modified to overcome some RISC alignment issues and to support registration with a timeout. If your application uses the Version 2.0 AVAIL_DEREG message you must change it as follows: 1.Replace the AVAIL_DEREG declaration in your program to use the following: typedef struct { short version; /* version = 31 */ short filler; q_address target_q; q_address distribution_q; char req_ack; } AVAIL_DEREG; 2.Set the version number to 31. Note that if you continue to use the Version 2.0 AVAIL_REG and AVAIL_DEREG data structures with Version 3.1, you can no longer use the q_address data type. The q_address data type contains a 4-byte integer value at an offset of 2 bytes into the data structure. This definition causes RISC compilers to insert an extra two bytes between the version and target_q fields resulting in alignment problems when sending registrations to remote groups with differing alignments. Changes to LIST_ALL_CONNECTIONS Messages The following symbols have been added to the p_symbol.h include file for use in determining operating system types in a LIST_ALL_CONNECTIONS response message. These symbols replace the definitions listed in the documentation under the LIST_ALL_CONNECTIONS message. #define PSYM_OS_TYPE_AIX 'I' #define PSYM_OS_TYPE_VAXELN 'E' #define PSYM_OS_TYPE_MACINTOSH 'A' #define PSYM_OS_TYPE_HPUX 'H' #define PSYM_OS_TYPE_IRIX 'G' #define PSYM_OS_TYPE_MSDOS 'D' #define PSYM_OS_TYPE_NT 'N' #define PSYM_OS_TYPE_OS2 'O' #define PSYM_OS_TYPE_OSF1 '1' #define PSYM_OS_TYPE_RSX 'M' #define PSYM_OS_TYPE_SCO 'C' #define PSYM_OS_TYPE_SOLARIS 'L' #define PSYM_OS_TYPE_SUNOS 'S' #define PSYM_OS_TYPE_SYSV '5' #define PSYM_OS_TYPE_ULTRIX_VAX 'X' #define PSYM_OS_TYPE_ULTRIX_MIPS 'Y' #define PSYM_OS_TYPE_UNIX 'U' #define PSYM_OS_TYPE_VMS 'V' #define PSYM_OS_TYPE_UNKNOWN '*' NOTE Digital recommends that you use the symbols which equate to character constants rather than the constants themselves. The PSYM_OS_TYPE_UNIX symbol refers to Digital UNIX, which was formerly known as Digital OSF/1. Note that the symbols are designed to map to the operating system name wherever possible. A notable exception is: OS_TYPE_MOTOROLA_VR32 is now PSYM_OS_TYPE_SYSV Integration of the Client Library Server The DECmessageQ Client Library Server (CLS) is used to communicate between DECmessageQ Windows clients and DECmessageQ for UNIX server systems. For Version 3.1 the CLS has been fully integrated in the DECmessageQ for UNIX products. Installation of the CLS is part of product installation and the startup and rundown of the CLS are now managed by the Group Control Process (GCP) without user intervention. The CLS is configured as follows: - On UNIX systems, the CLS is configured using the %CLS section of the group initialization file. Instructions for configuring the CLS are contained in the DECmessageQ Installation and Configuration Guide for UNIX. Changes to Return Codes for Version 3.1 The following return codes have been added to the p_return.h include file: Return Code Description API Function ------------------ -------------- ---------------- PAMS__CONFLICT The parameters pams_put_msg supplied to the call are mutually exclusive and are, therefore, in conflict. PAMS__PREVCALLBUSY The previous All PAMS API call to the functions client library executed on a server has not DECmessageQ completed. Version 3.1 or This code is higher Client only returned implementation by the Windows may return this Client status value. Library. PAMS__STALE The handle to pams_put_msg the supplied selection filter is stale and is no longer valid. PAMS__TRUNCATED The pams_status_text description for the return value was returned. However, the description was truncated because the buffer supplied was too small to store the text returned. In DECmessageQ Version 3.0 or earlier, several return codes had the same status value as PAMS__FATAL. The following return codes now have their own unique values: PAMS__BADMSGBUF PAMS__DNSCLASSBAD PAMS__DNSDIRFAIL PAMS__DNSFMTBAD PAMS__NOACL PAMS__NOACCESS PAMS__NOPRIV PAMS__SAF_FORCED This change prevents compilation errors in switch statements such as the following: switch (nStatus) { case PAMS__NOACL : ... case PAMS__NOACCESS : ... case PAMS__FATAL : ... } The following return codes are obsolete and have been removed from the p_return.h file. If your applications reference these return codes, you must remove them from your application and then recompile and relink your application. #define PAMS__BADRECVDEC -28 #define PAMS__BADRECVSFG -30 #define PAMS__BADRECVSNA -32 #define PAMS__BADRECVLNK -34 #define PAMS__TMPCREMBX -38 #define PAMS__TMPCREMBXS -40 #define PAMS__DCLTMPNOANS -42 #define PAMS__DCLTMPRCVW -44 #define PAMS__DCLTMPTYPE -46 #define PAMS__BADRECVSYNCH -48 #define PAMS__TRANLOGNODE -86 #define PAMS__TRANLOGTASK -88 #define PAMS__INTERNAL1 -112 #define PAMS__INTERNAL2 -114 #define PAMS__INTERNAL3 -116 #define PAMS__INTERNAL4 -118 #define PAMS__SPARENUM1 -142 #define PAMS__SPARENUM2 -144 #define PAMS__SPARENUM3 -146 #define PAMS__SPARENUM4 -148 #define PAMS__SPARENUM5 -150 #define PAMS__SPARENUM6 -152 #define PAMS__SPARENUM7 -154 Changes to Timer Selection Timer selection has been enhanced for the DECmessageQ for UNIX products. You can now select timers: - Using the PSEL_TQ_PQ and PSEL_TQ_PQ_AQ selection modes - Using the class or type code of the message. Timer messages have a class of MSG_CLAS_PAMS and a type of MSG_TYPE_TIMER - Directly from the timer queue by specifying the PAMS_TIMER_QUEUE in the sel_var field of the sel_filter argument of the pams_get_msg when using the PSEL_AQ, PSEL_PQ_AQ, and PSEL_AQ_PQ selection modes Changes to Temporary Queue Allocation The algorithm for allocating temporary queues has changed for Version 3.1. Previously, the algorithm recycled temporary queues as soon as they were detached using a most recently used algorithm. For instance, if several processes attached temporary queues 200, 201, and 202 and then one process detached queue 200, the next temporary queue to be allocated was 200, not 203. The new algorithm uses the entire range of temporary queues before recycling temporary queue numbers. Once all temporary queues have been allocated once, the queue numbers are recycled using a least recently used algorithm. The new algorithm reduces the incidence of temporary queues receiving stale messages destined for another process that was previously attached using the same temporary queue number. Note that when all temporary queues are attached, this problem may occur regardless of the new algorithm because each temporary queue will be immediately recycled upon detach. Changes to Queue Names for Default Configuration The queue names in the default group configuration for Version 3.1 have been changed to uppercase for compatibility with DECmessageQ for OpenVMS. Previously, the queue names were lowercase. All programming examples included with DECmessageQ for UNIX Version 3.1 have been changed to reflect the queue names in uppercase. ========================================================================== 2. Corrections to Known Problems ========================================================================== This section describes corrections to DECmessageQ for UNIX software released as Version 3.2A, 3.2, 3.1, 3.0B, and 3.0A. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Corrections to DECmessageQ for UNIX Version 3.2A ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes corrections to DECmessageQ for UNIX, Version 3.2A. Corrections to Message Recovery Services a)Recoverable messages that are dequeued from a multi-reader queue but not confirmed before the dequeuing process exits are now requeued without all processes having to detach and then reattach to the queue. b)The time it takes for the journal process to restart a queue when it becomes attached has been reduced from approximately 40 seconds to less than 1/100th of a second. c)Recoverable messages are no longer pushed to an inactive queue. This reduces the number of PAMS__POSSDUPL messages a process may receive. Corrections to the Group Control Process a)The group control process now accepts dollar sign ("$") and hyphen ("-") characters in queue names in the %QCT section and in names in the %GNT section of the initialization file. b)The group control process now accepts queue numbers without a quali- fying group number in the %GNT section. for instance : %GNT TheQueue 7 L %EOS where 7 defines the number for the queue and the group is assumed to be zero which translates to the number of the currently running group. c)A memory corruption problem that sometimes occurred when executing the LIST_ALL_xxx functions which caused the group control process to exit abruptly with a bus error or segmentation fault has been corrected. Corrections to the Message API a)When registering for AVAIL/UNAVAIL services for a queue in a remote group, the AVAIL_REG_REPLY is no longer sent to the distribution queue. It is now sent to the original en- queuing source like all other AVAIL/UNAVAIL registrations. b)The LIST_ALL_CONNECTIONS and LIST_ALL_GROUPS response messages now contain the correct node name and operating system information. c)If the size of a LIST_ALL_xxx response message is greater than the GROUP_MAX_MESSAGE_SIZE for the group, the message is now properly broken up into multiple response messages. d)Individual entires with the LIST_ALL_GROUPS response message are now 18 bytes in length as documented in the DECmessageQ Programmer's Guide. Corrections to the PAMS API a)When receiving a message of class MSG_CLASS_PAMS and a type of MSG_TYPE_TIMER_EXIRED on RISC system the pams_get_msgw call no longer generates a fault when the caller supplies an unaligned buffer. b)Previously, when a DECmessageQ application fork()ed a child process but did not follow the fork() with an exec(), the child process caused the parent process to become detached detached from the queue. This problem has been corrected. c)The timer_id argument to the pams_set_timer function now properly recognizes 0 (zero) as invalid. d)When a value less than 0 (zero) is supplied to the p_timeout argument of the pams_set_timer function, the function now returns PAMS__BADPARAM as documented in the DECmessageQ Programmer's Guide. This function previously returned PAMS__INVALIDNUM. e)DECmessageQ now returns the correct error codes when a user sends a message to queue zero using the pams_put_msg function. Corrections to Link Drivers a)A problem has been corrected that sometimes caused the link drivers to be hung in a retry loop while continuously trying to re-establish a two-way connection after one side of the connection failed. b)A problem has been corrected that sometimes caused the link driver to send a kill signal to pid 0 resulting in the message queuing group going down. Corrections to the Monitor Utility a)When monitoring a large number of queues, the DECmessageQ Monitor utility (dmqmonm and dmqmonc) sometimes displayed garbage information in the "Queue Traffic Counts" and "Queue Traffic Rates" fields. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Corrections to DECmessageQ for UNIX Version 3.2 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Corrections to Message Recovery Services a) This release includes fixes to several run-time and crash-recovery journal corruption problems. b) Processes no longer block indefinately when enqueuing messages with a recoverable WF delivery mode. Corrections to Scripts a)The script processor is now properly invoked when you specify a script file using the DMQ_SCRIPT environment variable. b)Script echoing and logging for single byte values larger than 127 now function properly. Corrections to the Installation Verification Procedure a)The IVP program (dmqivpipc) now properly cleans up resources if processing is interrupted before completion. b)The IVP program now stops allocating resources once it determines that sufficient resources exist to support the proposed configuration. Corrections to the Group Control Process a)The length of LIST_ALL_xxx response messages is no longer always set to zero. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Corrections to DECmessageQ for UNIX Version 3.1 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes corrections made to DECmessageQ software prior to the current release. Corrections to the Bus Control Process a)In the bus initialization file, the bus control process can now correctly parse special characters (such as *,&,#,~,-) in the path names for the group initialization file and the group log file. b)The bus control process no longer incorrectly reports duplicate group numbers and duplicate group names for groups on different machines. Corrections to the Group Control Process a)The Group Control Process no longer excessively logs failures when sending notification of queue and link states to inactive targets. b)The Group Control Process now performs clean up for processes that fail to deregister for queue and link state services before exiting c)Memory loss while handling the LIST_ALL_xxx messages no longer occurs. d)The Group Control Process now properly handles RISC alignment for AVAIL_REG and AVAIL_DEREG messages. e)The Group Control Process no longer experiences a segmentation fault upon receipt of a LIST_ALL_GROUPS message. Corrections to Link Drivers a)Link driver processes now provide more informative error messages when detecting certain invalid configurations b)Link driver processes now automatically shutdown inbound connections when an outbound connection has been lost. c)Links now properly failover to alternate groups when a link is lost. d)Link drivers no longer hold sockets open across an exec call. e)Link drivers no longer enter an infinite loop when interrupted during shutdown. f)In previous version of DECmessageQ, the link receiver sometimes dropped links when message exchange between two groups became congested. This no longer occurs. Corrections to the Message API a)The LIST_ALL_GROUPS and LIST_ALL_CONNECTIONS messages now return the correct values for link states. b)The LIST_ALL_CONNECTIONS message now returns the correct node name for DECnet connections. Corrections to Message Recovery Services a)In DECmessageQ Version 3.0 or earlier, the journal process did not properly restart a queue when a process detached and then reattached to the same queue. b)In DECmessageQ Version 3.0 or earlier, when a process dequeued all recoverable messages from a queue and detached the queue before confirming those messages, the journal process failed to restart that queue. c)MRS now properly handles stale recoverable messages. d)The journal process now properly validates the group number for messages targeted at remote groups. e)MRS now properly handles duplicate confirmation of a recoverable message sent to a multi-reader queue. f)Journal processing for a group will now properly start up regardless of whether the group configuration file contains a path specification for the group log file. g)Recoverable messages presented to the user for the first time are no longer marked as possible duplicates. h)Recoverable messages presented to the user more than once are now correctly marked as possible duplicates. i)MRS no longer presents already confirmed messages or more than one message at a time to a target queue. Corrections to PAMS API Functions a)Child processes that call the pams_attach_q function after executing a fork no longer cause heap corruption. b)Successive calls to the pams_set_timer and pams_cancel_timer functions no longer result in memory loss. c)Memory loss problems caused by the pams_set_select function have been corrected. d)In previous versions of DECmessageQ, a process that attempted to attach to a secondary queue to which it was already attached would incur a segmentation fault. This problem most often occurred when a process attached to a primary queue and then explicitly attached to its secondary queue. DECmessageQ automatically attaches secondary queues defined in the group initialization file. e)In DECmessageQ Version 3.0, the use of a selection filter argument with the pams_get_msg or pams_get_msgw functions did not result in messages being read in the proper order when message order was specified as the primary key. This problem has been corrected and messages are now selected in proper order from the queue. f)In DECmessageQ Version 3.0, the prototype in the file p_entry.h for the routine pams_confirm_msg listed the message sequence number parameter as an int32 array. The value is now prototyped as an uint32 array as documented in the DECmessageQ Programmer's Guide. The definition is changed when you recompile your applications under DECmessageQ Version 3.1. g)In DECmessageQ Version 3.0 or earlier, the priority field in the show buffer data structure was not properly filled in when receiving a recoverable message using pams_get_msg and pams_get_msgw. h)In DECmessageQ Version 3.0 the pams_get_msg call filled in the entire show buffer data structure regardless of whether the user-supplied data was too small. This problem resulted in memory corruption. Corrections to the Script Facility a)The SET SEND ECHO, SET SEND LOG, SET RECEIVE ECHO, SET RECEIVE LOG now work as documented in the DECmessageQ Programmer's Guide. b)You can now turn off echo and logging using the NOECHO and NOLOG phrases in a SET RECEIVE or a SET SEND statement c)The SET SEND and SET RECEIVE statements now accept numeric queue addresses in the FROM and TO clauses. For example, you can use the following commands: SET SEND LOG TO 1.3 ! group 1, queue 3 SET RECEIVE ECHO FROM 4 ! queue 4 in the local group d)The ON and OFF clauses for the SET RECEIVE and SET SEND statements now work as documented. e)The Script Facility now properly echos nonprinting characters as periods. f)The number of lines to echo or log can now be set on a per source or per target basis. g)Numerous problems with the script processor which caused it to hang in infinite loops have been corrected. h)The Script Facility now properly parses quoted strings. Corrections to the Queuing Engine a)The queuing engine now properly reports licensing problems. b)In previous versions of DECmessageQ, the queuing engine sometimes encountered a race condition that caused it to hang on timed operations until another process attempted to use the queuing engine. This problem no longer occurs for timed operations such as pams_get_msgw or a pams_put_msg with delivery modes of PDEL_MODE_WF_xxx. ======================================================================== 3. Known Problems and Limitations ======================================================================== This section lists the known problems for Version 3.2A. Known Problems with Compilation on HP-UX Systems You must specify the preprocessor option -D_HPUX_SOURCE=1 when using the c89 compiler on HP-UX systems Known Problem Running the Monitor Utility on HP-UX 10.10 or later The libcurses.sl library of HP-UX Version 10.10 and later contains a bug that prevents the character cell version of the Monitor utility (dmqmonc) from starting up. This problem can be corrected using an earlier version of the libcurses library by changing the link /usr/lib/libcurses.sl to point to the file /usr/lib/libHcurses.sl. Known Problem Installing DECmessageQ on HP-UX 10.2 or later DECmessageQ users running HP-UX 10.2 may experience problems installing DECmessageQ software if they have run a utility to remove and re-install the transition links for compatibility with HP-UX version 11. If the transition links to the old locations of the system binaries and libraries are not in place, the DECmessageQ installation will fail. Known Problems with GIDs and UIDs for UNIX Client Processes For security reasons the default behavior of DECmessageQ for UNIX systems requires all client processes that attach to a selected message queuing group have the same GID and UID as the user who started the group. Processes with a different UID or GID than that of the process starting the group can attach to the group. However, all subsequent calls will fail when the queuing engine attempts to check the existence of processes with a different UID or GID. This problem can be eliminated by granting the queuing engine (dmqqe) set-user-id status and changing the ownership to root as shown below: # chown root /usr/kits/DM*vvv/bin/dmqqe # chmod u+s /usr/kits/DM*vvv/bin/dmqqe where: * is the platform you are on as follows: A = Digital UNIX U = ULTRIX/MIPS V = ULTRIX/VAX Q = all other UNIX platforms vvv is the current version of the product (i.e. 202, 30A, 310). Note that the Queuing Engine spawns no child processes, creates no files, writes only to the designated log file for a given group, has no interactive user interface, and uses the "suid" privilege only for determining whether client processes are still active. Assigning suid privilege to the Queuing Engine poses no threat to overall system security beyond allowing all GIDs and UIDs access to the DECmessageQ message queuing groups on the machine in question. Known Problems with Manual Reference Pages on AIX Systems Manual reference pages do not display properly on AIX systems Known Interoperability Problem with Recoverable Messaging on DECmessageQ for OpenVMS, Version 3.x There is a known problem sending recoverable messages with a UMA of SAF from an OpenVMS system to a UNIX system, if the UNIX systems goes down. In the event of a UNIX system failure, if the message queuing group on the UNIX system comes back up while the OpenVMS group is attempting redelivery of messages from the SAF, DECmessage for OpenVMS marks messages as stale, deletes them and eventually the SAF transfer hangs. To clear the condition, both message queuinng groups must be restarted, however, the MRS messages marked as stale are lost and cannot be redelivered. Known Restriction on the Use of the UNIX Crontab Feature DECmessageQ for UNIX places key files that allow processes to locate shared memory, semaphores, and other IPC resources in a directory called /var/tmp/dmq. On some UNIX systems, most notably Digital UNIX (formerly DEC OSF/1) and AIX, the operating system is configured with a crontab entry that periodically deletes files that have not been accessed for a preselected time interval. This delete operation can include the key DECmessageQ files placed in the /var/tmp/dmq directory. If these files are deleted, both DECmessageQ processes (such as the link drivers and the Monitor utility) and user application processes will no longer be able to attach to a DECmessageQ group. To prevent the deletion of these key files while DECmessageQ is running, the crontab entry must be modified to avoid deleting the files in /var/tmp/dmq or removed completely. A typical crontab entry which removes files after they have not been accessed for two days appears as follows: 20 4 * * * find /var/tmp -type f -atime +2 -exec rm -f {} \; Known Restriction on Message Length on NCR UNIX Systems DECmessageQ for NCR UNIX supports a maximum message length of 8192 bytes. Restrictions on Using the Script Facility It is important to note that DECmessageQ script processing on UNIX systems does not begin until the target process issues a pams_get_msg or pams_get_msgw procedure call. So, for example, if you send a script to a target application that contains command to start script processing and capture message input, script processing does not begin until the target application issues the get function and obtains the script messages. Known Limitations with the UNIX Client This section identifies any known problems or limitations in the UNIX Client software for version 3.2A. UNIX Client function parameter limits The UNIX client library sets specific limits on DECmessageQ function parameter values that allow very large values on DECmessageQ server systems. The limits for the function parameters reduces the network message size for messages transmitted between client applications and the remote Client LIbrary Server running on the DECmessageQ server group. The limits implemented for the functions are as follows: Function Maximum Value ------------------- ---------------------------------- pams_attach_q, q_name_len is 32 pams_locate_q pams_attach_q, name_space_list_len pams_locate_q is 100 pams_put_msg, msg_area_size is pams_get_msg 32,700 pams_detach_q detach_q options is 32 pams_set_select num_masks is 20 putil_show_pending pending count is 100 In all other respects, the DECmessageQ function calls implented by the UNIX Client library are identical to those provided by DECmessageQ V3.1 or higher on other platforms. ======================================================================== 4. Corrections to Documentation ======================================================================== This section lists corrections to documentation for Version 3.2. No additional documentation corrections have been added for Version 3.2A. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Programmer's Guide (AA-PYRVB-TK) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ This section describes additions and corrections to the DECmessageQ Programmer's Guide (AA-PYRVB-TK) that ships with DECmessageQ Version 3.1. Correction to Description of Default Confirmation Types (page 2-19 and page 7-24) The DECmessageQ documentation describes the queue characteristics that must be set for queues to receive recoverable messages. Note that Version 3.1 of DECmessageQ no longer offers a default confirmation type when configuring groups for recoverable messaging. All queues must be configured for implicit or explicit confirmation. For complete information on how to configure message queues, refer to the DECmessageQ Installation and Configuration Guide for UNIX Correction to Description of Valid UMAs for Recoverable Messages (page2-27) The last sentence of the first paragraph in the section entitled "Using the SAF UMA" contains a typographical error. The sentence should read: The SAF UMA can be used with recoverable delivery interest points of DQF and CONF; however, it does not work with the WF_SAF delivery mode. Correction to Description of Script Processing on UNIX (page 5-14) The documentation provides incorrect syntax for invoking the Script Utility on UNIX systems using the environment variable. The correct command using the C shell syntax is: setenv DMQ_SCRIPT mylog.pss The correct command using Bourne shell syntax is: DMQ_SCRIPT=mylog.pss export DMQ_SCRIPT Correction to Documentation of Example Programs (Chapter 7) The default group configuration on DECmessageQ for UNIX systems has changed the names of the default queues to uppercase. The example programs for Version 3.1 have been updated to correctly reference the queue names in uppercase. Therefore, although the documentation does not reflect this change, the programming examples will work properly with the updated default configuration. Additional Return Codes for pams_attach_q (page 7-8) The documentation for the pams_attach_q function should include the following new or changed return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__NOACCESS All No access to resource. PAMS__NOACL All Queue access control file could not be found. PAMS__PAMSDOWN All The specified DECmessageQ group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to pams_cancel_select Return Codes (page 7-17) The documentation for the pams_cancel_select function should include the following return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to pams_cancel_timer Return Codes (page 7-19) The documentation for the pams_cancel_timer function should include the following new or changed return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed PAMS__SELRCVACT OpenVMS Selective reception is currently active. Correction to pams_confirm_msg Return Codes (page 7-27) The documentation for the pams_confirm_msg function should include the following new or changed return codes: Return Code Platform Description PAMS__BADPARAM All Bad argument value. PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Changes to pams_detach_q Arguments (page 7-35) The msg_flushed argument of the pams_detach_q function receives the number of messages flushed from the queue. Message count statistics are now enabled on all systems by default; therefore, it is not no longer necessary to enable statistics on UNIX and Windows NT systems in order to properly return this value. The detach_opt_list argument of the pams_detach_q function now supports three constants as follows: detach_opt_list Supplies an array of int32 values used to control how the queue is detached. The predefined constants for this argument are: - PSYM_NOFLUSH_Q---Detaches the queue without flushing the pending messages stored in memory. The default action for primary and secondary queues is to flush pending messages in the queue before it is detached. Messages are never flushed from multireader queues. - PSYM_DETACH_ALL---Detaches all of the application's message queues from the message queuing bus. Using this constant performs the same action as issuing a pams_exit request. - PSYM_CANCEL_SEL_MASK---Cancels all selection masks that reference the queue or queues that you are detaching. If you do not select this option and you do not cancel selection masks, DECmessageQ invalidates all selection masks that reference the queue or queues you are detaching. You must cancel the invalidated selection masks using the pams_cancel_select function. NOTE: This option is available on DECmessageQ V3.1 or higher server implementations. Correction to pams_detach_q Return Codes (page 7-36) The documentation for the pams_detach_q function should include the following new or changed return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Change to Return Codes for pams_get_msg and pams_get_msgw (page 7-49 and 7-76) The documentation for the pams_get_msg and pams_get_msgw functions should include the following new or changed return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__NOACCESS All No access to resource. PAMS__NOACL All Queue access control file could not be found. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed PAMS__STALE All Resource is no longer valid and must be freed by the user. The pams_get_msg and pams_get_msgw reference documentation should also include PAMS__PAMSDOWN in the list of valid PSB Delivery Status Values. Correction to pams_locate_q Return Codes (page 7-85) The documentation for the pams_locate_q function should include the following return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to Timeout Argument for pams_put_msg (page 7-93) The documentation currently states that entering a 0 value for timeout argument of the pams_put_msg call specifies an indefinite timeout. That is only true for the timeout argument used with the pams_get_msgw service. Specifying 0 as the timeout value for the pams_put_msg service sets the timeout to the default value of 30 seconds. Change to Return Codes for pams_put_msg (page 7-97) The documentation for the pams_put_msg function should include the following new or changed return codes: Return Code Platform Description PAMS__EXCEEDQUOTA All Target process quota exceeded; message not sent. PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed PAMS__NOTACTIVE All Target process is not currently active; message not sent. PAMS__UNATTACHED All Message successfully sent to unattached queue. The pams_put_msg reference documentation should also include PAMS__PAMSDOWN in the list of valid PSB Delivery Status Values. Correction to pams_set_select Return Codes (page 7-116) The documentation for the pams_set_select function should include the following return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to pams_set_timer Return Codes (page 7-124) The documentation for the pams_set_timer function should include the following return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN UNIX The specified DECmessageQ Windows NT group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to putil_show_pending Return Codes (page 7-128) The documentation for the putil_show_pending function should include the following return codes: Return Code Platform Description PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PAMSDOWN All The specified DECmessageQ group is not running. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed Correction to AVAIL_REG and AVAIL_DEREG Version Description (pages 8-4 and 8-6) The version number field of the C Message Structure is incorrectly described. The format version number of this field is 20 for the structure documented. Addition of API Reference Page for pams_status_text This section contains the documentation of the pams_status_text call using the DECmessageQ API reference page format. pams_status_text Receives the severity level and text description of a user-supplied PAMS API return code and moves that information to a user-supplied storage area. If the return code is not known, an error is returned and the call parameters are not filled in. Syntax int32 pams_status_text ( code, severity, buffer, buflen, retlen) Arguments Argument Data Mechanism Prototype Access Type code int32 reference int32 * passed severity int32 reference int32 * returned buffer char reference char * returned buflen int32 reference int32 * passed retlen int32 reference int32 * returned Argument Definitions code Specifies the return value for which you would like the text description and severity level returned. severity Receives a code indicating the severity level of the message. Severity levels apply to both success and error messages. They are designed to provide more information about the message being returned. The valid codes returned to this argument are: 0 = warning 1 = success 2 = error 3 = informational 4 = fatal error buffer Receives the text description for the return status supplied. buflen Specifies the length of the buffer to store the text description returned. A buffer length of 256 bytes is adequate to store the text description for all return status codes. If the user buffer supplied is large enough, the string is zero terminated. The buffer length must be entered as a positive integer. Supplying a negative integer value to this argument causes the function to return a status of PAMS__BADPARAM. If you specify this argument as zero, no text is returned to the buffer and the function returns that status PAMS__TRUNCATED. retlen Receives the size of the user-supplied buffer space that was filled by the text description returned. Description Application developers use the pams_status_text function to obtain a text description and severity level for each API return value. The text description contains both the symbolic name (as it is defined in the include files and described in the documentation) followed by a comma, a space and then a description of the return value in the following format: PAMS__SUCCESS, normal successful completion In addition to the text description, this function returns a code indicating the severity level for both success and error messages. For example, the pams_detach_q has two 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 queuing bus in the same manner as the pams_exit function. Return Values Return Code Platform Description PAMS__FAILED All There is no translation for the specified return code. PAMS__NETERROR Clients Network error resulted in a communications link abort. PAMS__PREVCALLBUSY Clients Previous call to CLS has not been completed PAMS__SUCCESS All Normal successful completion. PAMS__TRUNCATED All The description was returned but was truncated.