![]() |
![]() |
![]() |
![]() |
![]() |
Note: Oracle Tuxedo Message Queue supports PAMS APIs for Oracle Messageq (OMQ) compatibility. To migrate OMQ applications to OTMQ, please see Migrating from OMQ to OTMQ 12c.The beginning of each description contains the entry-point name and a brief description of the function performed. Table 2‑1 Table 8-1 describes the sections in the description of each callable service.
Table 2‑1 Callable Service Description Formats Oracle MessageQ API arguments use data types defined by the C programming language and some data types defined by Oracle MessageQ software. Data types such as short, -unsigned short, and char are data types defined by the C programming language. Oracle MessageQ data types such as q_address and the PSB and show_buffer structures are defined in the p_entry.h include file.Oracle MessageQ supports data type definitions for signed and -unsigned longwords. The int32 data type defined by Oracle MessageQ is a 32-bit signed integer. The int32 data type replaces the use of the integer data type long, the size of which is operating system dependent. The int32 data type definition guarantees a consistent definition across all platforms and was added to accommodate next generation 64-bit architectures such as the Compact Alpha AXP systems. The uint32 data type designates a 32-bit unsigned integer and replaces the use of unsigned long.
Note: The int32 and uint32 data type definitions are not available on Oracle MessageQ Version 2.0 platforms. Oracle MessageQ Version 2.0 software uses the standard signed longword and unsigned longword data types defined by the C programming language.
Table 2‑2 Arguments
• PSYM_ATTACH_BY_NAME-Attach by name
• PSYM_ATTACH_BY_NUMBER-Attach by number
• PSYM_ATTACH_TEMPORARY-Attach as a temporary queueWhen attach_mode is PSYM_ATTACH_BY_NAME, the application attaches to the queue identified by the specified queue or alias name. Oracle MessageQ finds the queue by implicitly performing a pams_locate_q call for the specified q_name. The procedure that Oracle MessageQ uses is determined by the name_space_list argument.
• PSYM_ATTACH_PQ-Primary queue (default)
• PSYM_ATTACH_SQ-Secondary queueSupplies the name or number of the permanent queue to attach to the application if the attach_mode argument specifies attachment by queue name or queue number. Queue names are alphanumeric strings with no embedded spaces and allow the following special characters: underscore (_), hyphen (-), and dollar sign ($).References to queue names are case sensitive and must match the queue name entered in the group initialization file. Some example queue names are: QUEUE_1, high-priority, and My$Queue.
• If the attach_mode argument is PSYM_ATTACH_BY_NAME, the q_name argument must contain a valid queue name as specified during Oracle MessageQ group configuration.
• If the attach_mode argument is PSYM_ATTACH_BY_NUMBER, the q_name argument is specified as an ASCII string of 1 to 3 numeric characters representing the queue number.
• If the attach_mode argument is PSYM_ATTACH_TEMPORARY, the q_name argument is not used and should be specified by passing a value of 0.Supplies a list of name tables to search when the attach_mode argument PSYM_ATTACH_BY_NAME is specified.If the name_space_list is specified, then the name_space_list_len argument must also be specified. If this argument is unspecified, then PSEL_TBL_GRP is the default.Possible values in a name_space_list argument are as follows:
Table 2‑3 name_space_list argument values The name_space_list argument identifies the scope of the name as follows:
• To identify a local queue reference or a queue, an application must include PSEL_TBL_GRP in name_space_list. (Do not specify PSEL_TBL_BUS in the list because it would identify a global queue reference.)
• To identify a global queue reference, include PSEL_TBL_BUS (or PSEL_TBL_BUS_MEDIUM or PSEL_TBL_BUS_LOW) in the name_space_list argument and specify its pathname, either explicitly or implicitly. If the q_name argument contains any slashes (/), or periods (.), Oracle MessageQ treats it as a pathname. Otherwise, Oracle MessageQ treats q_name as a name and adds the DEFAULT_NAMESPACE_PATH to the name to create the pathname to lookup. (The DEFAULT_NAMESPACE_PATH is set in the %PROFILE section of the group initialization file.)The name_space_list argument also controls the cache access as follows.
• To cause the lookup of a local queue reference or queue name to check the process cache before looking in the group cache, specify the name_space_list argument as PSEL_TBL_GRP and PSEL_TBL_PROC.
• To cause the lookup of a global queue reference to check the process cache and then the group cache before looking into the global name space, specify PSEL_TBL_BUS(or PSEL_TBL_BUS_LOW or PSEL_TBL_BUS_MEDIUM), PSEL_TBL_GRP and PSEL_TBL_PROC.
•
• instead of PSEL_TBL_BUS.
• To lookup only the slower but more up-to-date caches in the global name space before looking in the master database, specify PSEL_TBL_BUS_MEDIUM instead of PSEL_TBL_BUS.Supplies the number of entries in the name_space_list argument. If the name_space_list_len argument is zero, Oracle MessageQ uses PSEL_TBL_GRP as the default in the name_space_list argument.The number of PAMS time units (1/10 second intervals) to allow for the attach to complete. If a zero is specified, the group's ATTACH_TMO property is used. If the ATTACH_TMO property is also zero, 600 is used.Before an application can use the pams_attach_q function, the Oracle MessageQ message queuing bus must be configured. A Oracle MessageQ message queuing bus is a collection of one or more Oracle MessageQ message queuing groups. A message queuing group is a collection of message queues that reside on a system, share global memory sections and files, and are served by the same server processes. A Oracle MessageQ message queue is an area of memory or disk where messages are stored and retrieved. See the installation and configuration guide for the platform you are using to learn how to configure the Oracle MessageQ environment.To receive Oracle MessageQ messages, an application must attach to at least one message queue. The pams_attach_q function enables an application to attach in the following ways:
• An application can attach to a queue by specifying a number. To attach by number, the message queue must be configured in the group definition. Attaching by number enables an application to attach to a specific queue, send messages to the queue, and retrieve messages sent to that queue.
• An application can attach to a queue by specifying the queue name. To attach by name, the message queue must be configured in the group definition. Attaching by name enables an application to attach to a specific queue, send messages to the queue, and retrieve messages sent to that queue. In addition, attaching by name eliminates the need to change code or recompile if the queue address changes. Therefore, attaching by name protects applications from changes in the Oracle MessageQ environment configuration.
• An application can attach to a temporary queue. To attach to a temporary queue, the application does not have to give a specific queue name or number. Oracle MessageQ will assign a queue and return the number of the queue which has been assigned. Temporary queues allow an application to perform messaging without knowing configuration details of the group.
Table 2‑4 Return Codes this example illustrates how to attach to a queue by name. The name "example_q_1" must be defined in your group configuration information as a primary queue or as a local queue alias or a primary queue. The complete code example called x_attnam.c is contained in the examples directory.this example illustrates how to attach to a queue by number. A queue numbered 1 must be defined in your group configuration information file as a primary queue. The complete code example called x_attnum.c is contained in the examples directory.this example illustrates how to attach as a temporary queue. The complete code example called x_atttmp.c is contained in the examples directory.
Table 2‑5 Arguments
• If 0 is specified, this function unbinds the q_alias from its queue address. The calling application must be bound to q_alias to set it back to zero.Identifies a global queue reference or a local queue reference. The procedure that Oracle MessageQ uses to find this alias is controlled by the name_space_list argument, which is described below.If specified, identifies a one-entry list containing either PSEL_TBL_BUS or PSEL_TBL_GRP.To identify a local queue reference, an application must have a name space list of PSEL_TBL_GRP and pass its name in the q_alias argument. To identify a global queue reference, an application must have a name space list of PSEL_TBL_BUS and specify its pathname, either explicitly or implicitly:
• If the q_alias argument contains any slashes (/), or periods (.), Oracle MessageQ treats the q_alias as a pathname.
• Otherwise, Oracle MessageQ treats q_alias as a name and adds the group's DEFAULT_NAMESPACE_PATH to the name to create the pathname to lookup. (The DEFAULT_NAMESPACE_PATH is set in the %PROFILE section of the initialization file.)Specifies the number of entries in name_space_list argument. The number of entries is either 0 or 1. If the number of entries is 0 (indicating that the name_space_list is omitted), PSEL_TBL_GRP is assumed.Specifies the number of PAMS time units (1/10 second intervals) to allow for the bind to complete. If 0 is specified, the group's ATTACH_TMO property is used. If the ATTACH_TMO property is also 0, 600 is used.Before an application can call pams_bind_q, it must be attached to the specified queue address. Listing 2‑1 shows an attach before the bind call and is typical usage of the two functions together:Listing 2‑1 Example of Using pams_bind_q
Table 2‑6 Return Code Returned if a non-zero value for q_addr is passed and the specified q_alias is already assigned to a queue address. The timeout period specified has expired. In this situation, Oracle MessageQ internally unbinds the specified queue alias. Subsequent PAMS_bind_q calls to the same name will return the PAMS__UNBINDING error until the internal unbind succeeds. The timeout period specified has expired. In this situation, Oracle MessageQ internally unbinds the specified queue alias. Subsequent PAMS_bind_q calls to the same name will return the PAMS__UNBINDING error until the internal unbind succeeds. The pams_bind_q example illustrates how to bind a queue reference to a queue address at runtime. The complete code example called x_bind.c is contained in the examples directory.Cancels all pending pams_get_msga requests that match the value specified in the sel_filter argument. When a pending pams_get_msga request is canceled, the PAMS Status Block (PSB) delivery status is set to pams_CANCEL and the specified action routine is queued. The pams_cancel_get function waits until completion to allow for proper synchronization between the pams_cancel_get function and the request for pams_get_msga functions. Any outstanding pams_get_msga function requests are canceled by the pams_exit function or at image exit.
Table 2‑7 Arguments Supplies the criteria that enables the application to selectively cancel outstanding pams_get_msga requests. For a description of the sel_filter argument, see the pams_get_msg function. For a description of how to create a complex selection filter, see the pams_set_select function.
Table 2‑8 Return Codes Releases the selection array and index handle associated with a previously generated selection mask. An index_handle and associated selection mask are created using the pams_set_select function. When the selection mask is used in the OpenVMS environment with asynchronous read requests, this function also cancels any pending pams_get_msga requests that use the referenced index_handle.
Table 2‑9 Arguments Supplies the index handle of the selection mask to cancel. The index_handle is returned by the pams_set_select function.
Table 2‑10 Return Codes Deletes the Oracle MessageQ timer identified by the timer_id argument that is passed to this function. All expired timers with the selected identification code that are waiting in the message queue are purged and are not delivered.
Table 2‑11 Arguments Supplies the timer ID of the timer to cancel. The timer_id is returned by the pams_set_timer function.
Table 2‑12 Return Codes The timer_id argument was specified as null. Closes the MRS journal file associated with the jrn_handle argument. The two types of journal files are dead letter journal (DLJ) and post confirmation journal (PCJ). See Using Recoverable Messaging for a description of how to use the Oracle MessageQ message recovery system.
Table 2‑13 Arguments Supplies the journal handle of the message recovery journal file to close. The jrn_handle is returned by the pams_open_jrn function.
Table 2‑14 Return Codes When a recoverable message is received, the application must call the pams_confirm_msg function in order to delete it from the message recovery journal disk storage. If receipt of a recoverable message is not confirmed, the message continues to be stored by the recovery system and will be redelivered if the application detaches and then reattaches to the queue.Successfully delivered recoverable messages can be recorded in the post confirmation journal (PCJ). The pams_confirm_msg function uses the force_j argument to write messages to the PCJ file if the system is not currently configured to store them. Note that successfully delivered recoverable messages cannot be written to the PCJ file unless they are explicitly confirmed using the pams_confirm_msg function.
Table 2‑15 Arguments Supplies the message sequence number of the recoverable message being confirmed. The message sequence number is generated by the Oracle MessageQ message recovery system for each recoverable message. This value is passed to the receiver program in the PSB of the pams_get_msg function when it reads each recoverable message.
Table 2‑16 force_j The PSB status codes associated with recoverable message delivery are PAMS__CONFIRMREQ and PAMS__POSSDUPL. The PAMS__CONFIRMREQ PSB status code indicates that it is the first time the application received the recoverable message. The PAMS_POSSDUPL status code indicates that the message was retrieved from the recovery journal and may have been sent previously. This status code allows the application to take extra precautions to handle duplicate messages if necessary.The PSB also contains a sequence number that uniquely identifies the message. The pams_confirm_msg function requires this sequence number. If one of these status codes is present and the pams_confirm_msg function is not called, the message will continue to be stored by the message recovery system and will be delivered again if the application exits and then reattaches.
Table 2‑17 Return Code This example demonstrates using recoverable messaging. It attaches to queue_1, puts some recoverable messages to queue_2, exits, attaches to queue_2, gets the messages, prints them out, then exits.The queues named "queue_1" and "queue_2" are defined in your initialization file. On OpenVMS systems, you must set up a DQF for queue_2. The complete code example called x_recovr.c is contained in the examples directory.
Table 2‑18 Arguments 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 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 calling the pams_exit function.
• 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, Oracle MessageQ invalidates all selection masks that reference the queue or queues that you are detaching. You must cancel the invalidated selection masks using the pams_cancel_select function.Supplies the number of int32 values in the detach_opt_list array. The maximum number of int32 longwords is 32,767.
•
Table 2‑19 Return Codes Invalid detach_opt_list. Terminates all attachments between the application and the Oracle MessageQ message queuing bus. All pending messages in temporary queues and permanent queues which are not permanently active multi-reader queues are discarded. Only the messages pending in permanently active multi-reader queues are retained. To retain messages in permanently active queues, call pams_detach_q with option PSYM_NOFLUSH_Q before calling pams_exit.
•
Table 2‑20 Return Codes This example shows how to use the pams_exit function. The complete code example called x_exit.c is contained in the examples directory.Retrieves the next available message from a selected queue and moves it to the location specified in the msg_area argument. When no selection filter is specified, the function returns the next available message in first-in/first-out (FIFO) order based on message priority to the buffer specified in the msg_area argument. Priority ranges from 0 (lowest priority) to 99 (highest priority). For example, priority 1 messages are always placed before priority 0 messages. Messages are placed in first-in/first out order by message priority. If a selection filter is specified, then only messages that meet the selection criteria are retrieved. If no messages are available or meet the selection criteria, then the return status is pams__NOMOREMSG.Applications should check the PSB status field of each message to determine if the message was sent with a recoverable delivery mode. If an application receives a recoverable message, it must call the pams_confirm_msg function to delete it from the message recovery journal disk storage. If receipt of a recoverable message is not confirmed, the message continues to be stored by the recovery system and will be redelivered if the application detaches and then reattaches to the queue.The receiver program determines whether each message is a FML32 buffer or large message by reading the msg_area_len argument. See the Sending and Receiving Oracle MessageQ Messages topic for more information on working with FML32 buffers and large messages.
Table 2‑21 Arguments Supplies the priority level for selective message reception. Priority ranges from 0 (lowest priority) to 99 (highest priority). If the priority is set to 0, the pams__get_msqw function gets messages of any priority. If the priority is set to any value from 1 to 99, the pams__get_msqw function gets only messages of that priority.Receives the class code of the retrieved message. The class is specified in the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for class argument values. Symbolic class names should begin with MSG_CLAS_. For information on defining class symbols, see the p_typecl.h include file. On UNIX and Windows NT systems, the p_typecl.h include file cannot be edited. You must create an include file to define type and class symbols for use by your application.
Table 2‑22 Class symbols Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for type argument values. Symbolic type names begin with MSG_TYPE_. For specific information on defining type symbols, see the p_typecl.h include file.
• Supplies the size of the buffer (in bytes) for static message buffers of up to 32767 bytes. The msg_area buffer is used to store the retrieved message.
• For messages using double buffers, including FML32 buffers, this argument contains the symbol PSYM_MSG_BUFFER_PTR to indicate that the message is a pointer to the address of the message being retrieved. The msg_area buffer contains the message pointer. The size of the message is returned in the large_size argument. The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the message. If the retrieved buffer is larger than the space allocated, space is dynamically reallocated and the new buffer size is stored in large_area_len.
• For large messages (buffer-style messages larger than 32767 bytes), this argument contains the symbol PSYM_MSG_LARGE to indicate that the message buffer is greater than 32K. The size of the message is returned in the large_size argument. The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the large message.For static buffer-style messaging with messages of up to 32767 bytes, this argument receives the number of bytes retrieved from the message queue and stored in the area specified by the msg_area argument. This field also receives the PSYM_MSG_BUFFER_PTR symbol for double buffer and FML-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.
• Compound select using the pams_set_select function .The sel_filter argument is composed of two words as follows:PSEL_DEFAULT, reads the next pending message from the message queue. Messages are stored by priority and then in FIFO order. To specify this explicitly, both words in the sel_filter argument should be set to 0.
Table 2‑23 Selection by Message Queue
Table 2‑24 Selection by Message Attribute Using PSEL_PRI_ANY enables the reading of any pending messages of all priorities. Setting PSEL_PRI_P0 enables the application to retrieve pending messages of priority 0 only. Setting PSEL_PRI_P1 enables the strict retrieval of pending messages with a priority of 1.Some examples of possible sel_filter arguments and their actions are as follows:
Table 2‑25 sel_filter arguments Source q_address Only those messages that have a matching q_address are retrieved. Allows the application to formulate complex rules for the order in which the message queues are searched. The pams_set_select function allows the application to create custom selection masks that can be used in the low-order word of the sel_filter argument. The format for compound selection follows:Receives a PAMS Status Block containing the final completion status. The psb argument is used when sending or receiving recoverable messages. The PSB structure stores the status information from the message recovery system and may be checked after sending or receiving a message. The structure of the PSB is as follows:
Table 2‑26 PSB Structure The completion status of the function. For recoverable messages, this field contains PAMS__CONFIRMREQ or PAMS__POSSDUPL. For nonrecoverable messages, it may also contain a value of PAMS__SUCCESS. A unique number assigned to a message when it is sent and follows the message to the destination PSB. This number is input to pams_confirm_msg to release a recoverable message. This field is not used for the pams_get_msg function. This field is not used for the pams_get_msg function. Receives additional information which Oracle MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
Table 2‑27 show_buffer argument 10 = Version 1.020 = Version 2.050 = Version 5.0 The status code associated with the transfer of show_buffer information into the application's buffer. Valid symbols are as follows: A bit array showing the status of fields in the show_buffer. A set bit indicates a valid field, while a cleared bit indicates indeterminable data or the end of the allocated show_buffer memory. The symbols for the flags field are as follows: The q_address of the latest message target. The q_address of the original message target. The q_address of the latest message source. The q_address of the original message. PSYM_VAX_BYTE_ORDER or PSYM_LITTLE_ENDIAN PSYM_NETWORK_BYTE_ORDER or PSYM_BIG_ENDIAN PSYM_FML Supplies the length in bytes of the buffer defined in the show_buffer argument. The minimum length is 40 bytes. If the buffer is too small to contain all of the information, then the return code PAMS__BUFFEROVF will be in the show_buffer transfer status.Specifies the size of the message area to receive messages larger than 32K. Also specifies the length of the message buffer when using double buffers (as indicated by PSYM_MSG_BUFFER_POINTER). This argument also stores the length of double buffers and FML32 buffers after reallocation.
Table 2‑28 Return Code The size of the show_buffer specified is too small. The msg_area_len argument must be positive or zero. FML32 buffer received but msg_area_len argument not set to
Table 2‑29 PBS Delivery Status This example uses the pams_get_msg function to retrieve all the messages currently in the queue and sends them to a print function. The complete code example called x_get.c is contained in the examples directory.The pams_get_msga function is only available on OpenVMS systems.Requests asynchronous notification of a message arrival. The pams_get_msga function triggers an asynchronous system trap (AST) routine when a message arrives in that queue. Notification to the application occurs by triggering an AST, by setting an event flag, or both.When no selection filter is specified, the function returns the next available message in first-in/first-out (FIFO) order based on message priority to the user-supplied msg_area argument. Priority ranges from 0 (lowest priority) to 99 (highest priority). For example, priority 1 messages are always placed before priority 0 messages. Messages are placed in first-in/first out order by message priority. If a selection filter is specified, then only messages that meet the selection criteria are retrieved, and the AST or event flag is triggered only when a matching message arrives.If a queue has been sent a recoverable message, the receiver program can confirm receipt of the message using the pams_confirm_msg function. The pams_confirm_msg function enables the successfully delivered message to be deleted from the message recovery system. See the Using Recoverable Messaging topic for a description of the Oracle MessageQ recovery system.
Table 2‑30 Arguments For static buffer-style messaging, receives the address of a memory region where Oracle MessageQ writes the contents of the retrieved message. For FML-style messaging or when using double pointers, receives a pointer to the address of the message being retrieved. When using double buffer pointers with pams_get_msga, the new buffer size is returned in large_size. (This differs from pams_get_msg[w}, where the new buffer size is returned in large_area_len.)Figure 2‑5 Group ID Data StructureReceives the class code of the retrieved message. The class is specified in the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for class argument values. Symbolic class names should begin with MSG_CLAS_. For information on defining class symbols, see the p_typecl.h include file.
Table 2‑31 Class Symbols Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for type argument values. Symbolic type names begin with MSG_TYPE_. For specific information on defining type symbols, see the p_typecl.h include file.
• Supplies the size of the buffer (in bytes) for buffer-style messages of up to 32767 bytes. The msg_area buffer is used to store the retrieved message.
• For messages using double buffers, including FML32 buffers, this argument contains the symbol PSYM_MSG_BUFFER_PTR to indicate that the message is a pointer to the address of the message being retrieved. The msg_area buffer contains the message pointer. The size of the message is returned in the large_size argument. The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the message. If the retrieved buffer is larger than the space allocated, space is dynamically reallocated and the new buffer size is stored in large_size.
• For large messages (buffer-style messages larger than 32767 bytes), this argument contains the symbol PSYM_MSG_LARGE to indicate that the message buffer is greater than 32K. The size of the message is returned in the large_size argument The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the large message.For static buffer-style messaging with messages of up to 32767 bytes, this argument receives the number of bytes retrieved from the message queue and stored in the area specified by the msg_area argument. This field also receives the PSYM_MSG_BUFFER_PTR symbol for FML-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.
• Compound selection using the pams_set_select functionThe sel_filter argument is composed of two words as follows:Figure 2‑6 sel_filter argumentEnables applications to read messages from the queue based on the order in which they arrived. The default selection, PSEL_DEFAULT, reads the next pending message from the message queue. Messages are stored by priority and then in FIFO order. To specify this explicitly, both words in the sel_filter argument should be set to 0.
Table 2‑32 sel_filter argument
Table 2‑33 Message Atribute Argument Using PSEL_PRI_ANY enables the reading of any pending messages of all priorities. Setting PSEL_PRI_P0 enables the application to retrieve pending messages of priority 0 only. Setting PSEL_PRI_P1 enables the strict retrieval of pending messages with a priority of 1.Figure 2‑7 Selection by Message SourceSome examples of possible sel_filter arguments and their actions are as follows:
Table 2‑34 sel_filter Argument Source q_address Only those messages that have a matching q_address are retrieved. Allows the application to formulate complex rules for the order in which the message queues are searched. The pams_set_select function allows the application to create custom selection masks that can be used in the low-order word of the sel_filter argument. The format for compound selection follows.Figure 2‑8 Compound SelectionReceives a PAMS Status Block containing the final completion status. The psb argument is used when sending or receiving recoverable messages. The PSB structure stores the status information from the message recovery system and may be checked after sending or receiving a message. The structure of the PSB is as follows:
Table 2‑35 psb Structure The completion status of the function. For recoverable messages, this field contains PAMS__CONFIRMREQ or PAMS__POSSDUPL. For nonrecoverable messages, it may also contain a value of PAMS__SUCCESS. A unique number assigned to a message when it is sent and follows the message to the destination PSB. This number is input to pams_confirm_msg to release a recoverable message. This field is not used with the pams_get_msga function. This field is not used with the pams_get_msga function. Receives additional information which Oracle MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
Table 2‑36 show_buffer Argument The version of the show_buffer structure. Valid values are as follows: The status code associated with the transfer of show_buffer information into the application's buffer. Valid symbols are as follows:PAMS__SUCCESS-All available information has been transferred.PAMS__BUFFEROVF-Information was lost due to receiver buffer overflow. 0-No message returned. There is no information to transfer. A bit array showing the status of fields in the show_buffer. A set bit indicates a valid field, while a cleared bit indicates indeterminable data or the end of the allocated show_buffer memory. The symbols for the flags field are as follows: The q_address of the latest message target. The q_address of the original message target. The q_address of the latest message source. The q_address of the original message. PSYM_VAX_BYTE_ORDER or PSYM_LITTLE_ENDIAN PSYM_NETWORK_BYTE_ORDER or PSYM_BIG_ENDIAN PSYM_FML Supplies the length in bytes of the buffer defined in the show_buffer argument. The minimum length is 40 bytes. If the buffer is too small to contain all of the information, then the return code PAMS__BUFFEROVF will be in the show_buffer transfer status.Specifies the size of the message area to receive messages larger than 32K. Also specifies the length of the message buffer when using double buffers (as indicated by PSYM_MSG_BUFFER_POINTER).Returns the actual size of the large message, double buffer message, or FML32 message written to the message buffer. When using double buffer pointers with pams_get_msga, the new buffer size is returned in large_size. (This differs from pams_get_msg[w}, where the new buffer size is returned in large_area_len.)Supplies the address of an int32 value that is the entry point to an action routine. This action routine is executed when the pams_get_msga function completes.Supplies an int32 value that is passed to the action routine specified in the actrtn argument when it is invoked.Supplies the int32 value for the flag number to be set when the pams_get_msga function completes. When the pams_get_msga function executes, it clears this flag. If this argument value is not supplied, no flag is used.Because the pams_get_msga function executes asynchronously, it obtains several argument values only after the message arrives. These argument values are the message buffer, source, class, type of the message, and a PAMS Status Block (PSB) status code containing the delivery status, UMA status, and the sequence number of the message. These values are not set until the message arrival triggers the AST routine or sets the event flag.The pams_get_msga function specifies an AST parameter which is passed by value to the AST routine when the parameter is called. This parameter is used to provide a context for the information contained in the message and can be used to identify the specific processing required for the message. Following are some suggestions and rules for programming with ASTs:
•
Table 2‑37 Return Code The msg_area_len argument must be positive or zero.
Table 2‑38 PSB Delivery Status When no selection filter is specified, the function returns the next available message in first-in/first-out (FIFO) order based on message priority to the user-supplied msg_area argument. Priority ranges from 0 (lowest priority) to 99 (highest priority). If the priority is set to 0, the pams_get_msqw function gets messages of any priority. If the priority is set to any value from 1 to 99, the pams_get_msqw function gets only messages of that priority. Messages are placed in first-in/first-out order by message priority. If a selection filter is specified, then only messages that meet the selection criteria are retrieved. If no message arrives, or no available message meets the selection criteria before the timeout period expires, then the return status is PAMS_TIMEOUT.If a queue has been sent a recoverable message, the receiver program can confirm receipt of the message using the pams_confirm_msg function. The pams_confirm_msg function enables the successfully delivered message to be deleted from the message recovery system. See the Using Recoverable Messaging topic for a description of the Oracle MessageQ recovery system.
Table 2‑39 Argument Supplies the priority level for selective message reception. Priority ranges from 0 (lowest priority) to 99 (highest priority). If the priority is set to 0, the pams__get_msqw function gets messages of any priority. If the priority is set to any value from 1 to 99, the pams__get_msqw function gets only messages of that priority.Figure 2‑9 group ID and queue numberReceives the class code of the retrieved message. The class is specified in the arguments of the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for class argument values. Symbolic class names should begin with MSG_CLAS_. For information on defining class symbols, see the p_typecl.h include file. On UNIX and Windows NT systems, the p_typecl.h include file cannot be edited. You must create an include file to define type and class symbols for use by your -application.
Table 2‑40 Class symbols Receives the type code of the retrieved message. The type is specified in the arguments of the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for type argument values. Symbolic type names begin with MSG_TYPE_. For specific information on defining type symbols, see the p_typecl.h include file.
• Supplies the size of the buffer (in bytes) for buffer-style messages of up to 32767 bytes. The msg_area buffer is used to store the retrieved message.
• For messages using double buffers, including FML32 buffers, this argument contains the symbol PSYM_MSG_BUFFER_PTR to indicate that the message is a pointer to the address of the message being retrieved. The msg_area buffer contains the message pointer. The size of the message is returned in the large_size argument. The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the message. If the retrieved buffer is larger than the space allocated, space is dynamically reallocated and the new buffer size is stored in large_area_len.
• For large messages (buffer-style messages larger than 32767 bytes), this argument contains the symbol PSYM_MSG_LARGE to indicate that the message buffer is greater than 32K. The size of the message is returned in the large_size argument. The msg_area buffer is used to store the retrieved message. The large_area_len argument is used to supply the size of the message buffer to receive the large message.For static buffer-style messaging with messages of up to 32767 bytes, this argument receives the number of bytes retrieved from the message queue and stored in the area specified by the msg_area argument. This field also receives the PSYM_MSG_BUFFER_PTR symbol for double buffer and FML-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.Supplies the maximum amount of time the pams_get_msg function waits for a message to arrive before returning control to the application. The timeout value is entered in tenths (0.1) of a second. A value of 100 indicates a timeout of 10 seconds. If the timeout occurs before a message arrives, the status code of PAMS__TIMEOUT is -returned.
• Compound selection using the pams_set_select functionFigure 2‑10 sel_filter argumentEnables applications to read messages from the queue based on the order in which they arrived. The default selection, PSEL_DEFAULT, reads the next pending message from the message queue. Messages are stored by priority and then in FIFO order. To specify this explicitly, both words in the sel_filter argument should be set to 0.
Table 2‑41 Selection by Message Queue
Table 2‑42 Selection by Message Attribute Using PSEL_PRI_ANY enables the reading of any pending messages of all priorities. Setting PSEL_PRI_P0 enables the application to retrieve pending messages of priority 0 only. Setting PSEL_PRI_P1 enables the strict retrieval of pending messages with a priority of 1.Figure 2‑11 Selection by Message SourceSome examples of possible sel_filter arguments and their actions are as follows:
Table 2‑43 sel_filter arguments Source q_address Only those messages that have a matching q_address are retrieved. Allows the application to formulate complex rules for the order in which the message queues are searched. The pams_set_select function allows the application to create custom selection masks that can be used in the low-order word of the sel_filter argument. The format for compound selection follows:Figure 2‑12 Compound SelectionReceives a PAMS Status Block containing the final completion status. The psb argument is used when sending or receiving recoverable messages. The PSB structure stores the status information from the message recovery system and may be checked after sending or receiving a message. The structure of the PSB is as follows:
Table 2‑44 PSB Structure The completion status of the function. It contains the status from MRS. It can also contain a value of PAMS__SUCCESS when the message is not sent recoverably. A unique number assigned to a message when it is sent and follows the message to the destination PSB. This number is input to the pams_confirm_msg function to release a recoverable message. Receives additional information which Oracle MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
Table 2‑45 show_buffer argument Supplies the length in bytes of the buffer defined in the show_buffer argument. The minimum length is 40 bytes. If the buffer is too small to contain all of the information, the return code PAMS__BUFFEROVF will be in the show_buffer transfer status.Specifies the size of the message area to receive messages larger than 32K. Also specifies the length of the message buffer when using double buffers (as indicated by PSYM_MSG_BUFFER_POINTER). This argument also stores the length of double buffers and FML32 buffers after reallocation.
Table 2‑46 Return Codes The size specified for the show_buffer argument is too small. The msg_area_len argument must be positive or zero. FML32 buffer received but msg_area_len argument not set to PSYM_MSG_BUFFER_PTR. This example shows how to use the pams_get_msgw function. It sets an alarm to send messages to itself every 5 seconds; it uses pams_get_msgw to sit and wait for them. The queue named "queue_1" must be defined in your initialization file as a primary queue. The complete code example called x_getw.c is contained in the examples directory.
Table 2‑47 Arguments Supplies the queue name or queue alias whose queue address is requested. The procedure that Oracle MessageQ uses to find this name is controlled by the name_space_list argument, described below.Supplies the number of characters in the q_name argument. The maximum string length on UNIX, Windows NT, and OpenVMS systems is 255 characters. For all other Oracle MessageQ environments, the maximum string length is 31.Supplies the search mode of the pams_locate_q function. The mode indicates whether the application waits for the search completion or receives the response in an acknowledgment message. There are two predefined constants for this argument:PSYM_WF_RESP (default setting)-The application issues the pams_locate_q request and waits for the queue address to be returned.PSYM_AK_RESP-The application issues the pams_locate_q address and continues processing. When the search is completed, the queue address is returned to the application's primary queue in a LOCATE_Q_REP message. The response message can be redirected to an alternate queue address using the resp_q argument.Supplies an application-specified transaction ID to associate with the pams_locate_q function.Supplies an alternate queue to use for receiving the acknowledgment message of the q_address. If no response queue is specified, the acknowledgment message is sent to the sender program's primary queue. The resp_q argument has the following format:Figure 2‑13 resp_q argumentIf the name_space_list argument is specified, the name_space_list_len argument must also be specified. If this argument is unspecified, then PSEL_TBL_GRP is the default.Possible values in a name_space_list argument are as follows:
Table 2‑48 name_space_list argument The name_space_list argument identifies the scope of the name as follows:
• To identify a local queue reference or a queue, an application must include PSEL_TBL_GRP in name_space_list. (Do not specify PSEL_TBL_BUS in the list because it would identify a global queue reference.)
• To identify a global queue reference, include PSEL_TBL_BUS (or PSEL_TBL_BUS_MEDIUM or PSEL_TBL_BUS_LOW) in the name_space_list argument and specify its pathname, either explicitly or implicitly. If the q_name argument contains any slashes (/), or periods (.), Oracle MessageQ treats it as a pathname. Otherwise, Oracle MessageQ treats q_name as a name and adds the DEFAULT_NAMESPACE_PATH to the name to create the pathname to lookup. (The DEFAULT_NAMESPACE_PATH is set in the %PROFILE section of the group initialization file.)The name_space_list argument also controls the cache access as follows:
• To lookup a local queue reference or queue name, specify both PSEL_TBL_GRP and PSEL_TBL_PROC. This causes the process cache to be checked before looking into the group cache.
• To lookup a global queue reference, specify PSEL_TBL_BUS (or PSEL_TBL_BUS_LOW or PSEL_TBL_BUS_MEDIUM), PSEL_TBL_GRP and PSEL_TBL_PROC. This causes the process cache to be checked. Then, the group cache is checked before looking into the global name space.Note that to lookup all caches in the global name space before looking in the master database, specify PSEL_TBL_BUS_LOW instead of PSEL_TBL_BUS.To lookup only the slower but more up-to-date caches in the global name space before looking in the masterdatabase, specify PSEL_TBL_BUS_MEDIUM instead of PSEL_TBL_BUS.Supplies the number of entries in the name_space_list argument. If the name_space_list_len argument is zero, Oracle MessageQ uses PSEL_TBL_GRP as the default in the name_space_list argument.Specifies the number of PAMS time units (1/10 second intervals) to allow for the locate to complete. If timeout is zero, the group's ATTACH_TMO property is used. If the ATTACH_TMO is also zero, 600 is used.
Table 2‑49 Return Codes DMQ_BUS_ID environment variable not set. DMQ_GROUP_ID environment variable not set. This example shows how to use the pams_locate_q function by attaching to queue_1 and locating queue_3 where a message is being sent. The queues named "queue_1" and "queue_3" must be defined in your initialization file; queue_1 must be a primary queue. The complete code example called x_locate.c is contained in the examples directory.
Table 2‑50 Arguments
Note: jrn_filespec should use the following format: <group name><queue name>.< SAF/DQF/ACK/DLQ/PCJ>. The group name length is four, and the queue name length is 8.Supplies the length of the file specification entered to the jrn_filespec argument specified (filename array) in number of bytes.
Note: jrn_filespec uses the following format: <group name><queue name>.< SAF/DQF/ACK/DLQ/PCJ>. The group name length is four, and the queue name length is 8.
A journal queue is locked by only one application that opens or reads the journal queue at one time. When the application attempts to open the journal queue, it tries to attach a temporary queue as a secondary queue at first. If there are not enough temporary queues left in the queue pool, the journal queue is not opened. The number of temporary queues can be defined when creating queue space; the default value is 200.
Table 2‑51 Return Code Sends a message to a target queue using a set of standard Oracle MessageQ delivery modes. Applications specify buffer-style or FML-style messaging using the msg_size argument. For buffer-style messaging using message buffers up to 32K, this argument supplies the length of the message in bytes in the user's msg_area buffer. In addition, you can use the msg_size argument to specify one of the following symbols:
• PSYM_MSG_FML-indicates FML-style messaging. The msg_area argument must contain a pointer to an FML32 buffer.
• PSYM_MSG_LARGE-indicates buffer-style message with messages up to 4MB in length. The pointer to the buffer is contained in the msg_area argument and the size of the large message buffer is contained in the large_size argument.The delivery argument of the pams_put_msg function can be used to guarantee message delivery if a system, process, or network fails. Recoverable messages are stored on disk by the message recovery system until they can be delivered to the target queue of the receiver program. When sending a recoverable message, you must specify the uma argument if the message recovery cannot store the message. You must also supply the psb argument to receive the return status of the operation.The optional timeout argument lets you set a maximum amount of time for the send operation to complete before the function times out. The optional resp_q argument allows you to specify an alternate queue for receiving the response messages rather than directing responses to the primary queue of the sender program.To use a pointer to an FML32 buffer when sending a message, the sender program specifies the symbol PSYM_MSG_FML as the msg_size argument to the pams_put_msg function.
Table 2‑52 Arguments Figure 2‑14 targetSupplies the class code of message being sent. Oracle MessageQ supports the use of symbolic names for class argument values. Symbolic class names should begin with MSG_CLAS_. For information on defining class symbols, see the p_typecl.h include file. On UNIX and Windows NT systems, the p_typecl.h include file cannot be edited. You must create an include file to define type and class symbols for use by your application.
Table 2‑53 Class symbols Supplies the type code for the message being sent. Oracle MessageQ supports the use of symbolic names for type argument values. Symbolic type names begin with MSG_TYPE_. For information on defining type symbols, see the p_typecl.h include file.
•
• WF-Wait for completion
• AK-Asynchronous acknowledgment
• NN-No notificationAnd dip is one of the following delivery interest point constants:
• ACK-Read from target queue and explicitly acknowledged using the pams_confirm_msg function. ACK can also be an implicit acknowledgement sent after the second pams_get_msg call by the receiving application.
• CONF-Delivered from the DQF and explicitly confirmed using the pams_confirm_msg function (recoverable)
• DEQ-Read from the target queue
• DQF-Stored in the destination queue file (recoverable)
• MEM-Stored in the target queue
• SAF-Stored in the store and forward file (recoverable)
Note: If temporary queues are used, deleted, and reused quickly, it is possible in isolated cases for an implicit ACK response from a previous temporary queue to be placed on the new temporary queue.For buffer-style messaging using message buffers up to 32K, supplies the length of the message in bytes in the user'smsg_area buffer. In addition, you can specify one of the following symbols:
• PSYM_MSG_FML--indicates FML-style messaging. The msg_area argument must contain a pointer to an FML32 buffer.
• PSYM_MSG_LARGE-indicates buffer-style messaging with messages up to 4MB in length. The pointer to the buffer is contained in the msg_area argument and the size of the large message buffer is contained in the large_size argument.Supplies the maximum amount of time the pams_put_msg function waits for a message to arrive before returning control to the application. The timeout value is entered in tenths (0.1) of a second. A value of 100 indicates a timeout of 10 seconds. If the timeout occurs before a message arrives, the status code PAMS__TIMEOUT is returned. Specifying 0 as the timeout value sets the timeout to the default value of 30 seconds.Receives a value in the PAMS Status Block specifying the final completion status. The psb argument is used when sending or receiving recoverable messages. The PSB structure stores the status information from the message recovery system and may be checked after sending or receiving a message.
Table 2‑54 PSB Structure The completion status of the function. It contains the status from MRS. It can also contain a value of PAMS__SUCCESS when the message is not sent recoverably. A unique number assigned to the message when it is sent and follows the message to the destination PSB. This number is input to the pams_confirm_msg function to release a recoverable message. Supplies the action to be performed if the message cannot be stored at the specified -delivery interest point. The format of this argument is PDEL_UMA_XXX where XXX is one of the following symbols:
Table 2‑55 UMA Symbols Supplies a q_address to use as the alternate queue for receiving response messages from the receiver program. The sender program must be attached to the queue specified in the resp_q argument to receive the response messages. The resp_q argument has the following format:Figure 2‑15 resp_q argument
Table 2‑56 Return Codes Invalid (negative) msg_size specified in the argument list.
Table 2‑57 UMA Status Message not recoverable in destination queue file (DQF); undeliverable message action (UMA) was PDEL_UMA_DISC; message could not be discarded. Message not recoverable in DQF; UMA was PDEL_UMA_DISC; message - discarded. Message not recoverable in DQF; UMA was PDEL_UMA_DISC; recoverability failure could not be logged or message could not be discarded. Message not recoverable in DQF; UMA was PDEL_UMA_DISC; message discarded after logging recoverability -failure. Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; dead letter journal (DLJ) write operation failed. Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; message written to the DLJ. Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message could not be queued to the DLQ. Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message queued to the DLQ. Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message could not be returned to sender. Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message returned Message not recoverable in DQF; UMA was PDEL_UMA_SAF; store and forward (SAF) write operation failed. Message not recoverable in DQF; UMA was PDEL_UMA_SAF; message recoverable from SAF file. This example sends a number of messages to a queue. The complete code example called x_putslf.c is contained in the examples directory.Reads a message from a Oracle MessageQ journal file. Use the pams_open_jrn function to open the dead letter journal or postconfirmation journal for a message queuing group. Use the pams_close_jrn function to close the journal file after reading selected messages. Note that on UNIX and Windows NT systems, these functions are performed by running the Journal Replay utility.The receiver program determines whether each message is a FML buffer or a large message by reading the len_data argument. See the Sending and Receiving Oracle MessageQ Messages topic for more information on working with message handles and large messages.
Table 2‑58 Arguments Supplies the journal handle of the message recovery journal from which the application has selected to read journal entries. The journal handle is returned to the application by the pams_open_jrn function.Figure 2‑16 queue number and group IDReceives the class code of the retrieved message. The class is specified in the arguments of the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for class argument values. Symbolic class names should begin with MSG_CLAS_. For information on defining class symbols, see the p_typecl.h include file. Class symbols reserved by Oracle MessageQ are as follows:
Table 2‑59 Class symbols Receives the type code of the journaled message. The type is specified in the arguments of the pams_put_msg function. Oracle MessageQ supports the use of symbolic names for type argument values. Symbolic type names begin with MSG_TYPE_. For information on defining type symbols, see the p_typecl.h include file. The OpenVMS symbol values range from -1 through -5000. Use of the type argument facilitates selective message reception. However, if the receiving application does not need a specific value for its processing, then use a value of 0.Supplies the size of the buffer (in bytes) for buffer-style messages of up to 32K bytes. The msg_area buffer is used to store the retrieved message.
•
• For an FML-style message, this argument contains the symbol PSYM_MSG_BUFFER_PTR to indicate that the message is a pointer to an FML32 buffer.
• For large messages, this argument contains the symbol PSYM_MSG_LARGE to indicate that the message buffer is greater than 32K. The size of the message is returned in the large_size argument.Figure 2‑17 target
Table 2‑60 Return Codes Message in journal file is larger than GROUP_MAX_MESSAGE_SIZE. The pams_set_select function creates an index handle that is used as the sel_filter argument of Oracle MessageQ functions for reading the message. When a selection index handle is passed to pams_get_msg, pams_get_msga or pams_get_msgw, each message received is compared against comparison key_1 and then comparison key_2. If the message matches both keys (a logical AND operation), the message is added to a set of matched messages. The order in which selected messages are delivered is determined by the order key.
Table 2‑61 Arguments Supplies an array of selection records that contain the selection rules for each queue. The typedef structures define the C data structure for the selection array. The structure is defined in p_entry.h as follows:The selection_array_component data structure has the following components:
Table 2‑62 selection_array_component data structure The following tables define the content of each of the components of the selection_array_component data structure.The following table specifies the valid values that can be applied to the arguments in this part of the Select_Queue structure:
Table 2‑63 Select_Queue structure Specifies the queue number to be searched. The queue number can be any message queue for which the application has read access. The queue number can be obtained from the q_attached argument of the pams_attach_q function or q_address of the pams_locate_q function. A value of 0 for this argument specifies the application's primary queue. The following table specifies the arguments and valid values that can be applied to this part of the Selection_Array_Components structure:
Table 2‑64 Selection_Array_Components structure Correlation ID of the message. May be used for key_1_offset or key_2_offset but not both. If this symbol is specified, the Size field must be set to PSEL_CORRELATION_ID_SIZE (or 32 bytes). Message sequence number acquired from the PAMS Status Buffer. If this symbol is specified, the Size field must be set to PSEL_SEQUENCE_NUMBER_SIZE (or 8 bytes).
Table 2‑65 Order Key Byte offset of the message field. The offset variable contains a value that specifies where the information to be compared begins inside the message. Correlation ID of the message. If this symbol is specified, the Size field must be set to PSEL_CORRELATION_ID_SIZE (or 32 bytes). Message sequence number acquired from the PAMS Status Buffer. If this symbol is specified, the Size field must be set to PSEL_SEQUENCE_NUMBER_SIZE (or 8 bytes). Size of the comparison. The size variable specifies the data type of the key to be compared. int32 (32 bits). Order operator. The order variable specifies the sequence in which the select process is to be performed. The correlation ID is a 32-byte user-defined identifier associated with a message. If PSEL_CORRELATION_ID is supplied as the value for either the key_1_offset or key_2_offset field, the correlation ID value is used to match messages with the specified correlation ID. Since there is a single correlation ID per message, PSEL_CORRELATION_ID should only be specified for one of the comparison keys; specifying the correlation ID for both keys results in a PAMS__BADPARAM error.If PSEL_CORRELATION_ID is supplied as the value for the order_offset field, messages with the specified correlation ID are returned in the order specified by the order_order field.
• The high-order word contains PSEL_BY_MASK.The index_handle is passed as the sel_filter argument in pams_get_msg, pams_get_msga or pams_get_msgw, and pams_cancel_select functions. OpenVMS allows a maximum number of 500 index handles. Other Oracle MessageQ implementations offer 16K to 32K index handles.
Table 2‑66 Return Codes This example shows the selective reception of messages using pams_set_select to build a complex message selection filter. The queue named "queue_1" must be defined in your initialization file as a primary queue. The complete code example called x_select.c is contained in the examples directory.Creates a timer that sends a message to an application's primary queue when a time interval expires or a time of day arrives. The message is sent as a priority 1 message with a source of PAMS__TIMER_QUEUE, a class code of PAMS, and a type code of TIMER_EXPIRED. A timer_id is returned by this function as the first int32 value in the TIMER_EXPIRED message.To act upon the timer message, the application uses the pams_get_msgw function to read its primary queue, block until the timer expiration message arrives, and then act upon it. To cancel a Oracle MessageQ timer, use the pams_cancel_timer function with the identification code of the timer you want to cancel.
Table 2‑67 Arguments P-selects the time interval in PAMS timer format supplied to the p_timeout argument. PAMS timer format expresses time in units of one tenth of a second. Using the PAMS timer format provides an operating system independent way to represent a time interval.S-selects the system-dependent time format supplied to the s_timeout argument. Using a system-dependent time format limits the portability of applications to a specific operating system environment.Supplies the amount of time to delay (delta) from the current time before returning a timer expiration message. If the timer_format argument is set to P, a value greater than 0 must be entered for this argument. This argument uses the PAMS timer format which expresses time in units of one tenth of one second.On OpenVMS systems, use this argument to supply a pointer to an array of two int32 values used to set a 64-bit OpenVMS time format. The s_timeout argument can be specified as an absolute time or a delta time matching the OpenVMS time format rules. Note that if the caller exceeds the ASTLM or TQELM process quota, the process can enter the RWAST state.On UNIX and Windows NT systems, use this argument to supply a two element array of int32 values. The values represent an absolute time (a UTC time in seconds and microseconds) at which the timer will expire. To use the s_timeout argument, developers provide a pointer to a "struct timeval" as follows:
Table 2‑68 Return Codes Invalid timer number passed to PAMS_set_timer. This example shows how to use the Oracle MessageQ timer functions by setting a timer to go off every 5 seconds. When the timer expires, it sends messages to itself. While not handling the timer event, it sits and waits for other incoming messages. If it is interrupted, it cancels any outstanding timers. The queue named "queue_1" must be defined in your initialization file as a primary queue. The complete code example called x_timer.c is contained in the examples directory.
Table 2‑69 Arguments 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 the status of PAMS__TRUNCATED.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:For example, 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 your application from the message queuing bus in the same manner as the pams_exit function.
Table 2‑70 Return Codes
Table 2‑71 Arguments Supplies the number of queue entries in the in_q_list argument (the number of indexes in the array). The maximum allowed value is 32,000.Supplies an array of int32 values containing the queue numbers for which the pending message count is requested.
Table 2‑72 Return Code This example shows how to use putil_show_pending to display the number of pending messages currently in the queue. A queue named "queue_1" must be defined during group configuration. The complete code example called x_shopnd.c is contained in the examples directory.Table 2‑73 describes the functions performed by using message-based services and lists the servers they are available through.
Table 2‑73 Overview of Message-Based Services You can send a service request message using the pams_put_msg function. Request messages use the type argument to identify the purpose of the message. Each request message has a predefined data structure.When an application requests information using the pams_put_msg function, it provides the Oracle MessageQ server with the group ID and queue number to which the response should be directed. The sender program then reads this queue using the pams_get_msg, pams_get_msgw, or pams_get_msga function to obtain the response information.
Table 2‑74 A Oracle MessageQ server response The type code of the message received. For example, AVAIL_REG_REPLY.
• AVAIL_REG-Request message to register to receive queue information.
• AVAIL_REG_REPLY-Response message to confirm registration or deregistration.
• AVAIL-Notification message to indicate that the queue is available.
• UNAVAIL-Notification message to indicate that the queue is unavailable.
• AVAIL_DEREG-Notification message to deregister from obtaining queue information.Figure 2‑18 Figure 5-1 Avail Server Message FlowAn application program registers to receive availability messages by sending a message of type AVAIL_REG to the local Avail Server process. The Avail Server responds with a message of type AVAIL_REG_REPLY, acknowledging the notification request.After registration, the requestor immediately receives an AVAIL or UNAVAIL message indicating the current availability of the target queue. Queue availability messages provide ongoing notification when a specific queue becomes attached or detached and when a link is connected or lost. If the queue becomes active because a process becomes attached, the Avail Server sends a message of type AVAIL. If it becomes -inactive, the server sends a message of type UNAVAIL.Applications must cancel availability notification by sending a message of type AVAIL_DEREG. The application receives a AVAIL_REG_REPLY message indicating the status of the operation. It is important to note that if the distribution queue for an AVAIL registration becomes unavailable, the registration will be automatically deleted by Oracle MessageQ. A subsequent attempt to deregister AVAIL services for this distribution queue will result in an error message indicating that the registration does not exist.
• LIST_ALL_CONNECTIONS (Request)-Request message to provide a list of all cross-group connections.
• LIST_ALL_CONNECTIONS (Response)-Response message to provide a list of all cross-group connections. Groups with no link connection are not listed.
• LIST_ALL_ENTRIES (Request)-Request message to provide a list of all queue entries for a group.
• LIST_ALL_ENTRIES (Response)-Response message to provide a list of all queue entries for a group.
• LIST_ALL_GROUPS (Request)-Request message to provide a list of groups on the message queuing bus.
• LIST_ALL_GROUPS (Response)-Response message to provide a list of all groups, connected and unconnected, on the message queuing bus.Figure 2‑19 Figure 5-2 Requesting Cross-Group InformationTo obtain a list of all groups defined on the message queuing bus, send a LIST_ALL_GROUPS message to the Connect Server. To obtain a list of all cross-group connections for the message bus or a list of all cross-group entries, send a LIST_ALL_CONNECTIONS message to the Connect Server. To obtain a list of queues in a group, send a LIST_ALL_ENTRIES message.The reply to these requests is a variable-length message with the same type and class as the request. To read the information returned, the application uses the message size parameter returned by the pams_get_msg function and divides it by the byte size of the data object requested to determine the number of data entries returned. The byte size of these entries is described in the reference description of each message.
• ENABLE_NOTIFY-Request message to request notification of link changes.
• LINK_COMPLETE-Notification message to indicate that the cross-group link was created.
• LINK_LOST-Notification message to indicate that the cross-group link was lost.
• DISABLE_NOTIFY-Request message to request disabling of link change -notification.Figure 2‑20 Figure 5-3 Requesting Cross-Group Link StatusApplications send an ENABLE_NOTIFY message to the Connect Server to receive ongoing notification when new connections are made or lost. Registered applications receive a LINK_COMPLETE notification message when a new cross-group connection is created. Applications receive a LINK_LOST message when a cross-group connection is lost. To deregister from -receiving further notification messages, the application sends a DISABLE_NOTIFY message to the Connect Server.
Note: Note: To receive ongoing notification of queue attachments, we recommend the use of the Queue Server messages,such as ENABLE_Q_NOTIFY_REQ. The ENABLE_NOTIFY message should no longer be used to obtain queue attachment information.The LINKMGT_REQ request message enables the following control functions:The LINKMGT_RESP response message notifies the requesting application if the request was successful and supplies information about the cross-group connection. Link management functions are also available through the System Manager utility on Oracle MessageQ for OpenVMS systems. Figure 5-4 is a graphical representation of the functional relationship facilitated by LINKMGT_REQ and LINKMGT_RESP:Figure 2‑21 Figure 5-4 Using Link Management
Note: When using link management, automatic creation of cross-group connections must be disabled with the generate connect option D (disable) in the %XGROUP section of the Oracle MessageQ group initialization file to completely control all cross-group links. For more information, refer to the Enabling Network Connections in the Cross-Group Section topic in the Oracle MessageQ Installation and Configuration Guide for each platform.The Inquire function of the link management request message allows querying of a single group's link state. To use the Inquire function, specify the group number of the local or remote group for which you want to learn the link state. This function does not allow you to specify any selection parameters other than the group number. Because you can only inquire about the link state of one group at a time, you cannot specify the PSYM_LINKMGT_ALL_GROUPS symbol in the group_number field.Table 2‑75 displays the Inquire function request message format:
Table 2‑75 Inquire Function Request Message Format The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the inquiry request. Refer to Table 5-3 for a description of each status return and the corresponding user action.
• PSYM_LINKMGT_CONNECTED-the incoming/outgoing cross-group link for the selected group is connected.
• PSYM_LINKMGT_NOCN-the incoming/outgoing cross-group link for the selected group is not connected.
• PSYM_LINKMGT_DISABLE-the incoming/outgoing cross-group link for the selected group is disabled.If the link status for the group is PSYM_LINKMGT_CONNECTED, the response message contains the following information:
Table 2‑77 Response Message Information Transport that message is connected over: PSYM_LINKMGT_TCPIP. Connected platform ID (PSYM_PLATFORM_xxxx).
• If the group_number field is set to PSYM_LINKMGT_ALL_GROUPS, then the node name and transport address cannot be specified.
• If a specific group number is specified and PSYM_LINKMGT_ALL_TRANSPORTS is specified, then the node name and transport address cannot be specified.
Note: The symbol PSYM_LINKMGT_ALL_TRANSPORTS is new to the LINK_MGT message API for Oracle MessageQ Version 4.0. On OpenVMS systems, the Enable function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.Table 2‑78 displays the Enable function message format:
Table 2‑78 Enable function message format Group number to receive the action. Valid values are 1 to 32000. Or, use the PSYM_LINKMGT_ALL_GROUPS symbol to enable all known links for groups with the connect_type requested. Select the following transport type: PSYM_LINKMGT_TCPIP ASCII text of node name. The length is determined by node_name_len up to 255 characters. The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Enable request. See Table 2‑79 for a description of each status return and the corresponding user action.
Table 2‑80 Enable function Transport that message is connected over: PSYM_LINKMGT_TCPIP. Connected platform ID (PSYM_PLATFORM_xxxx). All addresses in the group address table that match the selection criteria of the message (for example, group ID, connect type, node name, and transport address) will be disabled. All other address entries for the groups selected will not be affected. If no entry matches the group_number field, then PSYM_LINKMGT_NOGROUP is returned.Table 2‑81 displays the Disable function message format:
Table 2‑81 Disable Function Message Format PSYM_LINKMGT_ALL_GROUPS symbol indicates all known links for this group. Select the following transport type: PSYM_LINKMGT_TCPIP The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Disable request. See Table 2‑82 for a description of each status return and the corresponding user action.
Transport that message is connected over:PSYM_LINKMGT_TCPIP. Connected platform ID (PSYM_PLATFORM_xxxx). If the group_number field is set to PSYM_LINKMGT_ALL_GROUPS, then node name and transport address cannot be specified. If a specific group number is specified, and PSYM_LINKMGT_ALL_TRANSPORTS is specified, then node name and transport address cannot be specified.On OpenVMS systems, the Connect function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.Table 2‑84 displays the Connect request function message format:
Table 2‑84 Connect Request Function Message Format PSYM_LINKMGT_ALL_GROUPS symbol indicates all known links for this group. ASCII text of node name. The length is determined by node_name_len up to 255 characters. The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Connect request. See Table 2‑85 for a description of each status return and the corresponding user action.
Connected platform ID (PSYM_PLATFORM_xxxx). The Disconnect function of the link management request message requests implicit disables of links and disconnects any links to the requested group. All addresses in the group address table that match the selection criteria of the message (for example, group ID, connect type, node name, and transport address) will be disconnected. All other address entries for the groups selected will not be affected. If no entry matches the group_number field, then PSYM_LINKMGT_NOGROUP is returned. On OpenVMS systems, the Disconnect function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.Table 2‑87 displays the Disconnect function message format.
Table 2‑87 Disconnect Function Message Format Group number to receive the action. Valid values are 1 to 32000. The PSYM_LINKMGT_ALL_GROUPS symbol means disconnect all known links for this group. ASCII text of node name. The length is determined by node_name_len up to 255 characters.The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Disconnect request. Refer to Table 2‑88 for a description of each status return and the corresponding user action.
Transport that message is connected over: PSYM_LINKMGT_TCPIP. Connected platform ID (PSYM_PLATFORM_xxxx). Length of the transport_addr string. Length of the node_name string. Table 2‑90 lists important design considerations for applications using link management.
Table 2‑90 Link Management Design Condsiderations When an application issues a LINKMGT_REQ request, the Connect Server disables the failover node table defined in the group initialization file. Disabling the failover node table ensures the application complete control over the attributes of the link request. When the application issues a LINKMGT_REQ request to disconnect a link, the Connect Server disables further connections to the group. Disabling connections ensures that no additional links to the group will occur until the application issues another LINKMGT_REQ request. When a connect request is made for a single group, the XGROUP_VERIFY table uses the information supplied in the message to determine whether to accept or reject the -request for a connection. Cross-group verification only works on incoming requests. The data structure for cross-group verification is overwritten by the information in the link management connect or disconnect message. OPER privilege or be granted the DMQ$OPERATOR rights identifier.The Queue Server process can provide applications with a list of all attached queues for a selected group. This information is available for local and remote groups and includes a listing of both permanent and temporary queues. To request this list, the application program sends a message of type LIST_ALL_Q_REQ to the Queue Server process.
• LIST_ALL_Q_REQ-Request message to request the status of all queues.
• LIST_ALL_Q_RESP-Response message to provide a list of all queues and their status.Figure 2‑22 Figure 5-5 Listing All QueuesThe application receives a response message from the Queue Server of type LIST_ALL_Q_RESP providing a list of all attached queues. Because a LIST_ALL_Q_RESP message may contain a long list of queue names, the application must allocate a sufficient buffer size to store the information returned.The Queue Server process can notify an application of all attached queues and subsequent queue attachments and detachments for its own group. An application registers for this service by sending a message of type ENABLE_Q_NOTIFY_REQ to the group's Queue Server process. The Queue Server responds with a message of type ENABLE_Q_NOTIFY_RESP, indicating the status of the registration request.
• ENABLE_Q_NOTIFY_REQ-Request message to request the current status of all queues with notification of future queue status changes.
• ENABLE_Q_NOTIFY_RESP-Response message to provide the current status of all queues and confirmation that queue status changes will be reported.
• Q_UPDATE-Notification message to provide information on newly attached and detached queues in the selected group.
• DISABLE_Q_NOTIFY_REQ-Request message to request that notification of queue status changes be discontinued.
• DISABLE_Q_NOTIFY_RESP-Response message to indicate that notification of queue status changes has been successfully disabled.Figure 2‑23 Listing Available QueuesThe registration request places the sender's response queue number in the list of applications to receive notification of new attachments and detachments. Notifications are sent using a message of type Q_UPDATE. The application can cancel the notification registration by sending a message of type DISABLE_Q_NOTIFY_REQ. The Queue Server responds with a reply of type DISABLE_Q_NOTIFY_RESP indicating the status of the registration cancellation request.
You can use the messages in Table 2‑79 to disable journaling when replacing a PCJ file and then reenable journaling:
• MRS_JRN_DISABLE-Request message to disable journaling to the PCJ file.
• MRS_JRN_DISABLE_REP-Response message to indicate the status of the request.
• MRS_JRN_ENABLE-Request message to enable journaling to the PCJ file.
• MRS_JRN_ENABLE_REP-Response message to indicate the status of the request.Figure 2‑24 Disabling JournalingUse the MRS_JRN_DISABLE message to disable journaling to the PCJ when you need to close the PCJ and open a new one. The MRS_JRN_DISABLE_REP message returns the status of the operation. Use the MRS_JRN_ENABLE message to enable journaling after you have opened a new PCJ file. The MRS_JRN_ENABLE_REP message returns the status of the operation.Oracle MessageQ message-based services are sent between a user application program that functions as a requestor and a Oracle MessageQ server process that fulfills the request. For messages to be properly understood between systems, message data must be sent and returned in the endian format understood by both the requestor and the server. Most Oracle MessageQ message-based services automatically perform this conversion if the endian format of the two systems is different. However, some message-based services do not perform this conversion, therefore, the user application must convert the message to the endian format of the server system to ensure that the message data is correctly interpreted. Each message-based service description notes whether the data structure is RISC aligned and whether the server performs the endian conversion automatically. Please note that the environment variables VIEWFILES and VIEWDIR should be setted properly before using message-based services. For instance, export VIEWDIR=$TUXDIR/udataobj and VIEWFILES=otmq_mbs.V.
•
•
•
•
Note: Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. The AVAIL notification message is sent to registered applications when a queue in the selected group becomes active. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.Applications must cancel availability notification by sending a message of type AVAIL_DEREG. The application receives a AVAIL_REG_REPLY message indicating the status of the operation. It is important to note that if the distribution queue for an AVAIL registration becomes unavailable, the registration will be automatically deleted by Oracle MessageQ. A subsequent attempt to deregister AVAIL services for this distribution queue will result in an error message indicating that the registration does not exist.
Table 2‑93 Message Data Fields
Table 2‑94 Arguments Supplied by AVAIL_REG Supplied by AVAIL_REG Supplied by AVAIL_REG
• The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. When notification messages are no longer needed, the application sends an AVAIL_DEREG message to the Avail Server to cancel registration. It is important to note that if the distribution queue for an AVAIL registration becomes unavailable, the registration will be automatically deleted by Oracle MessageQ. A subsequent attempt to deregister AVAIL services for this distribution queue will result in an error message indicating that the registration does not exist. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑95 Message Data Fields
Table 2‑96 Arguments
•
• The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message. If the application detaches from the distribution queue, the AVAIL registration is automatically deleted. The application must cancel notification, regardless of queue type, by sending a message of type AVAIL_DEREG. The application receives a AVAIL_REG_REPLY message indicating the status of the operation.
Table 2‑97 Message Data Fields
Table 2‑98 Arguments
•
• The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.Applications register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. The AVAIL_REG_REPLY message indicates whether the application has successfully registered or deregistered from receiving notification messages. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑99 Message Data Fields
Table 2‑100 Arguments Sender of AVAIL_REG/DEREG Sender of AVAIL_REG/DEREG
•
• The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. When an application no longer needs to receive notification messages, it deregisters by sending a DISABLE_NOTIFY message to the Connect Server. The DISABLE_NOTIFY message can stop notification of cross-group link changes. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑101 Message Data Fields
Table 2‑102 Arguments Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The DISABLE_Q_NOTIFY_REQ is sent to the Queue Server when the application no longer needs to receive notification messages. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑103 Message Data Fields
Table 2‑104 Arguments
• Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The DISABLE_Q_NOTIFY_REQ message is sent to the Queue Server when the application no longer needs to receive notification messages. The DISABLE_Q_NOTIFY_RESP message indicates whether the application is successfully deregistered from receiving notification messages. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑105 Message Data Fields
Table 2‑106 Arguments
• Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑107 Message Data Fields
Table 2‑108 Arguments Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. This message requests a list of all active queues and then subsequent notification when queues become attached or detached and active or inactive. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑109 Message Data Fields
Table 2‑110 Arguments
• Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The ENABLE_Q_NOTIFY_RESP message delivers a list of all active queues and then subsequently notifies the application of attachments, detachments, and changes to active and inactive status using the Q_UPDATE message. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑111 Message Data Fields
Table 2‑112 Arguments
• Applications can use link management messages to explicitly control cross-group connections. Use the LINKMGT_REQ message to request a connection to a remote group, to disconnect from a remote group, or to obtain information about a remote Oracle MessageQ group. See the Controlling Cross-Group Links topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑113 Message Data Fields Function of the message using PSYM_LINKMGT_CMD: Group number to receive action; valid values are between 1 and 32,000; PSYM_LINKMGT_ALL_GROUPS indicates all known links. 10-int32 array ASCII text of node name; length determined by node_name_len up to 255 characters.
Table 2‑114 Arguments Applications can use link management messages to explicitly control cross-group connections. Use the LINKMGT_REQmessage to request a connection to a remote group, to disconnect from a remote group, or to obtain information about a remote Oracle MessageQ group. The LINKMGT_RESP message notifies the requesting application if the connection or disconnection request was successful and supplies information about the cross-group connection. See the Controlling Cross-Group Links topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑115 Message Data Fields PSYM_LINKMGT_ALL_GROUPS indicates all known links. Platform type preceded by the prefix PSYM_PLATFORM. Valid values are: ASCII text of node name; length determined by node_name_len up to 255 characters.
Table 2‑116 Status Code
Table 2‑117 Arguments Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. Registered applications receive a LINK_COMPLETE message each time a cross-group connection occurs. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.
Note: The Connect Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑118 Message Data Fields
Table 2‑119 Arguments
• Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. Registered applications receive a LINK_LOST message each time a cross-group connection is lost. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.
Note: The Connect Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑120 Message Data Fields
Table 2‑121 Arguments
• An application can request a listing of all active and configured cross-group connections by sending a LIST_ALL_CONNECTIONS message to the Connect Server. The reply to this request is a variable-length message of the same type and class containing the cross-group connection information. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑122 Arguments An application can request a listing of all active and configured cross-group connections by sending a LIST_ALL_CONNECTIONS message to the Connect Server. The reply to this request is a variable length-message of the same type and class containing the cross-group connection information. To read the information returned, the application must total the number of bytes in the reply and divide by the cross-group entry length, which is 20 bytes, to determine the number of records returned. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message-Based Services section for an explanation of how to use this message.This message does not return any information on groups with no link connection. The state field for LIST_ALL_CONNECTIONS should always be 3 (linked).
Note: The Connect Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑123 Message Data Fields 4-char array 3-char array 6-char array 3-char
Note: Treat variable "state" as int type.
Table 2‑124 Arguments An application can request a listing of all attached and configured queues in a group by sending a LIST_ALL_ENTRIES message to the Connect Server. The reply to this request is a variable-length message of the same type and class containing the queue information. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑125 Arguments
• LIST_ALL_ENTRIES response message
• LIST_ALL_CONNECTIONS (Request)
• LIST_ALL_CONNECTIONS (Response)
• LIST_ALL_GROUPS (Request)
• LIST_ALL_GROUPS (Response)An application can request a listing of all attached and configured queues in a group by sending a LIST_ALL_ENTRIES message to the Connect Server. The reply to this request is a variable length message of the same type and class containing the queue information. To read the information returned, the application must total the number of bytes in the reply and divide by the queue entry length, which is 24 bytes, to determine the number of records returned. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message-Based Services section for an explanation of how to use this message.
Note: The Connect Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑126 Message Data Fields 20-char array
Note: Treat variable " attach_flag" as int type.
Table 2‑127 Arguments An application can request a listing of all groups on a message queuing bus by sending a LIST_ALL_GROUPS message to the Connect Server. The reply to this request is a variable-length message of the same type and class containing the group information. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message- Based Services section for an explanation of how to use this message.
Table 2‑128 Arguments
• LIST_ALL_GROUPS response message
• LIST_ALL_CONNECTIONS (Request)
• LIST_ALL_CONNECTIONS (Response)
• LIST_ALL_ENTRIES (Request)
• LIST_ALL_ENTRIES (Response)An application can request a listing of all groups, connected and unconnected, on a message queuing bus by sending a LIST_ALL_GROUPS message to the Connect Server. The reply to this request is a variable-length message of the same type and class containing the group information. To read the information returned, the application must total the number of bytes in the reply and divide by the group entry length, which is 18 bytes, to determine the number of records returned. See the Listing Cross-Group Connections, Entries, and Groups topic in the Using Message-Based Services section for an explanation of how to use this message.
Note: The Connect Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑129 Message Data Fields 4-char array 3-char array 6-char array 3-char (VMS)1-char (UNIX)
Table 2‑130 Arguments
• LIST_ALL_GROUPS request message
• LIST_ALL_CONNECTIONS (Request)
• LIST_ALL_CONNECTIONS (Response)
• LIST_ALL_ENTRIES (Request)
• LIST_ALL_ENTRIES (Response)The LIST_ALL_Q_REQ message is sent to the Queue Server to request a list of all attached permanent and temporary queues for a local or remote group. See the Listing Attached Queues in a Group topic in the Using Message-Based Services section for an explanation of how to use this message.
Note: Note: The Queue Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.
Table 2‑131 Message Data Fields
Table 2‑132 Arguments The LIST_ALL_Q_RESP message provides a list of all permanent queues and all attached temporary queues for a local or remote group. This information is requested by sending a LIST_ALL_Q_REQ message to the Queue Server. Because the response message may contain a long list of queue names, the application must allocate a sufficient buffer size to store the information returned. See Listing Attached Queues in a Group in Chapter 5, "Using Message-Based Services" for an explanation of how to use this message.
Table 2‑133 Message Data Fields Queue type (numerically encoded P, S, M).
Table 2‑134 Arguments The pams_locate_q function requests the queue address for a queue name. When this function is performed asynchronously, the results are returned in the LOCATE_Q_REP message. This message provides the location in the search list where the name is found, the status of the operation, a tag that can be set by the user, and the queue address associated with the name.
Table 2‑135 Message Data Fields Return code from pams_locate_q.
Table 2‑136 Arguments The MRS_ACK message acknowledges the delivery of a recoverable message at the delivery interest point when a nonblocking request is issued. It responds to a pams_put_msg request when delivery modes of PDEL_MODE_AK_DQF, PDEL_MODE_AK_SAF, or PDEL_MODE_AK_CONF are specified. Status codes for the send operation are extracted from the PAMS Status Block (PSB), an argument value which is returned to the pams_get_msg, pams_get_msga, and pams_get_msgw function when the recoverable message is read. The status codes for the psb and uma arguments are listed in the Status Codes section of this description.
Table 2‑137 Arguments
Table 2‑138 Status Code
Table 2‑139 UMA Status Message is not recoverable in DQF; UMA was PDEL_UMA_DISC; message discarded. Message is not recoverable in DQF; UMA was PDEL_UMA_DISC; message could not be discarded. Message is not recoverable in DQF; UMA was PDEL_UMA_DISC; message discarded after logging recoverability failure. Message is not recoverable in DQF; UMA was PDEL_UMA_DISC; recoverability failure could not be logged or message could not be discarded. Message is not recoverable in DQF; UMA was PDEL_UMA_DLJ; message written to dead letter journal (DLJ). Message is not recoverable in DQF; UMA was PDEL_UMA_DLJ; dead letter journal write failed. Message is not recoverable in DQF; UMA was PDEL_UMA_DLQ; message queued to dead letter queue. Message is not recoverable in DQF; UMA was PDEL_UMA_DLQ; message could not be queued to dead letter queue. Message is not recoverable in DQF; UMA was PDEL_UMA_RTS; message returned to sender. Message is not recoverable in DQF; UMA was PDEL_UMA_RTS; message could not be returned to sender. Message is not recoverable in DQF; UMA was PDEL_UMA_SAF; message recoverable from SAF file. Message is not recoverable in DQF; UMA was PDEL_UMA_SAF; SAF write failed.
Note: The MRS Server does not perform endian conversion when this message is sent between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑140 Message Data Fields
Table 2‑141 Arguments Applications can request to disable journaling for a running message queuing group by sending an MRS_JRN_DISABLE message to the MRS Server. The MRS_JRN_DISABLE_REP message returns the status of the request. This service is used before failing over auxiliary journals. See the Controlling Journaling to the PCJ File topic in the Using Message- Based Services section for an explanation of how to use this message. This service is available on OpenVMS systems only.
Note: The MRS Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑142 Message Data Fields
Table 2‑143 Arguments Enables journaling for a running message queuing group after it has been disabled using the MRS_JRN_DISABLE message. This service is used before failing over auxiliary journals. See the Controlling Journaling to the PCJ File topic in the Using Message-Based Services section for an explanation of how to use this message. This service is available on OpenVMS systems only.
Note: The MRS Server does not perform endian conversion when this message is sent between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑144 Message Data Fields
Table 2‑145 Arguments Applications can request to reenable journaling for a running message queuing group after it has been disabled by sending an MRS_JRN_ENABLE message to the MRS Server. The MRS_JRN_ENABLE_REP message returns the status of the request. This service is used with MRS before failing over auxiliary journals. See the Controlling Journaling to the PCJ File topic in the Using Message-Based Services section for an explanation of how to use this message. This service is available on OpenVMS systems only.
Note: The MRS Server does not perform endian conversion when this message is received between processes that run on systems that use different hardware data formats. The sender program must convert the message to the endian format of the target system to ensure that the message data is correctly interpreted. This message is RISC aligned.
Table 2‑146 Message Data Fields
Table 2‑147 Arguments Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The ENABLE_Q_NOTIFY_RESP message delivers a list of all active queues and then subsequently notifies the application of attachments, detachments, and changes to active and inactive status using the Q_UPDATE message. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑148 Message Data Fields
Table 2‑149 Arguments Requests SBS deregistration by exact match of MOT and distribution queue or by registration ID. This service replaces the SBS_DEREG service.
Table 2‑150 Message Data Fields
Table 2‑151 Arguments This service replaces the SBS_DEREG_ACK service.
Table 2‑152 Message Data Fields
Table 2‑153 Arguments This service replaces the SBS_REG and SBS_REG_EZ services.int32 user_tag; int32 mot;q_address distribution_q; int32 req_ack;int32 seq_gap_notify; int32 auto_dereg; int32 rule_count; int32 rule_conjunct;
Table 2‑154 Message Data Fields PSEL_ALL_RULES if all rules must be true for distribution to succeed;PSEL_ANY_RULE if any rule being true can trigger distribution. * Following items are repeated "rule_count" times * Valid values are: PSEL_TYPE PSEL_CLASInteger in the range 0, ..., MAX_MSG_SIZE, specifying an offset in the data
Table 2‑155 Arguments This message provides a response to an SBS_REGISTER_REQ subscriber registration. The response contains a status field, which is 1 on success. The message also contains the user tag, specified in the request message, the registration ID and the number of registered entries for the MOT address.This service replaces the SBS_REG_REPLY and SBS_REG_EZ_REPLY services.
Table 2‑156 Message Data Fields Returned status code. Valid codes are as follows: PSYM_SBS_SUCCESS = Success PSYM_SBS_BADPARAM = Bad parameter PSYM_SBS_RESRCFAIL = Failed to allocate resource
Table 2‑157 Arguments The request message is targeted to the SBS_SERVER with message class PAMS and message type SBS_STATUS_REQ. Upon receipt of the message, the SBS server validates the request. If the request is incorrect, the response message contains an error status. The SBS server responds with the reply message of type SBS_STATUS_RESP.
Table 2‑158 Message Data Fields
Table 2‑159 Arguments This message is returned following the successful processing of the SBS_STATUS_REQ request message. It is a variable format message and is made up of a variable number of fixed length parts. To parse the message, each variable length section has a count.
Table 2‑160 Message Data Fields PSYM_SBS_SUCCESS = Success PSYM_SBS_BADPARAM = Bad parameter PSYM_SBS_NOMATCH = No match * Remainder of message repeated "num_rec" times up to a maximum of 50 records per Local SBS Server data * Number bytes contained in "complete_rcvd" messages. * Registrant data: repeated "num_reg" times * * Remote SBS server data: Following fields repeated "num_groups" times *
Table 2‑161 Arguments TIMER_EXPIRED is a response message to the pams_set_timer function. This message is sent to the timer queue associated with sender program's primary queue. Each call to the pams_set_timer function generates one message of type TIMER_EXPIRED when the timer expires.
Table 2‑162 Message Data Fields Timer ID specified in the pams_set_timer call.
Table 2‑163 Arguments Applications register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. The UNAVAIL notification message is sent to the registered application when a queue in the selected group becomes inactive. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.
Table 2‑164 Message Data Fields
Table 2‑165 Arguments Supplied by AVAIL_REG Supplied by AVAIL_REG
•