Because the MessageQ application programming interface (API) is portable, the API is documented once for all supported platforms. This chapter describes all MessageQ callable services in alphabetical order using a standard description -format.
MessageQ API Description Format
The beginning of each description contains the entry-point name, a graphic showing the platforms on which the service is supported, and a brief description of the function performed. Table 8-1 describes the sections in the description of each callable service.
MessageQ API Data Types
MessageQ API arguments use data types defined by the C programming language and some data types defined by MessageQ software. Data types such as short, -unsigned short, and char are data types defined by the C programming language. MessageQ data types such as q_address and the PSB and show buffer structures are defined in the p_entry.h include file.
MessageQ Version 3.0 has added two new data type definitions for signed and -unsigned longwords. The int32 data type defined by 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 Digital's Alpha AXP systems. The uint32 data type designates a 32-bit unsigned integer and replaces the use of unsigned long.
Note: The int 32 and uint32 data type definitions are not available on MessageQ Version 2.0 platforms. MessageQ Version 2.0 software uses the standard signed longword and unsigned longword data types defined by the C programming language.
Connects an application program to the MessageQ message queuing bus by attaching it to a message queue. An application must successfully execute this function before it can send and receive messages. When an application uses this function to attach to a queue, it becomes the owner of the queue. Only one application program can attach to a primary queue and read messages from it. When an application attaches to a permanent primary queue defined with secondary queue attachments, the secondary queues are also attached by this function.
Syntax
int32 pams_attach_q ( attach_mode, q_attached, [q_type], [q_name],
[q_name_len], [name_space_list], [name_space_list_len], [timeout], [nullarg_2], [nullarg_3] )Arguments
Argument Definitions
attach_mode
Supplies the mode for attaching the application to a message queue. The three predefined constants for this argument are:
- PSYM_ATTACH_BY_NAME-Attach by name
When attach_mode is PSYM_ATTACH_BY_NAME, the application attaches to the queue identified by the specified queue or alias name. MessageQ finds the queue by implicitly performing a pams_locate_q call for the specified q_name. The procedure that MessageQ uses is determined by the name_space_list argument.
q_attached
Receives the queue address from MessageQ when an application has successfully attached to a message queue.
q_type
Supplies the queue type for the attachment. The two predefined constants for this argument are:
- PSYM_ATTACH_PQ-Primary queue (default)
q_name
Supplies 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.
The q_name argument has the following dependencies with the attach_mode argument:
- If the attach_mode argument is PSYM_ATTACH_BY_NAME, the q_name argument must contain a valid queue name as specified during MessageQ group configuration.
q_name_len
Supplies the number of characters in the q_name argument. The maximum string length on UNIX, Windows NT, and OpenVMS servers is 255 characters. For all other MessageQ environments, the maximum string length is 31.
name_space_list
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:
Location It Represents Symbolic Value Process cache
PSEL_TBL_PROC
Group/group cache
PSEL_TBL_GRP
Global name space
PSEL_TBL_BUS
( or PSEL_TBL_BUS_MEDIUM
or PSEL_TBL_BUS_LOW)
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.)
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 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 master database, specify PSEL_TBL_BUS_MEDIUM instead of PSEL_TBL_BUS.
For more information on dynamic binding of queue addresses, see the Using Naming topic.
name_space_list_len
Supplies the number of entries in the name_space_list argument. If the name_space_list_len argument is zero, MessageQ uses PSEL_TBL_GRP as the default in the name_space_list argument.
timeout
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.
nullarg_2
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Description
Before an application can use the pams_attach_q function, the MessageQ message queuing bus must be configured. A MessageQ message queuing bus is a collection of one or more 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 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 MessageQ environment.
To receive 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.
Applications can specify an attachment as primary or secondary. All applications must have a primary queue. In addition, applications can attach to one or more secondary queues. Primary queues can be configured in the group definition as the owners of secondary queues. When an application attaches to a primary queue that is the owner of secondary queues, the application is automatically attached to the secondary queues at the same time it is attached to the primary queue.
In addition, an application can attach to a multireader queue. A multireader queue can be read by many applications and is configured as part of the group definition.
Return Values
See Also
- pams_detach_q
- Attach by Name-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.
- Attach by Number-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.
- Attach as Temporary-this example illustrates how to attach as a temporary queue. The complete code example called x_atttmp.c is contained in the examples directory.
pams_bind_q
Dynamically associates a queue address to a queue reference at run-time. This enables a server application to dynamically sign up to service a queue alias at run-time. Thus, an end user can access a service without having to be aware that its normal host computer is down and that the service is being provided from another host computer.
Syntax
int32 pams_bind_q (q_addr, q_alias, q_alias_len, [name_space_list],
[name_space_list_len], [timeout], [nullarg_1]);Arguments
Argument Definitions
q_addr
The value specified to this argument controls whether the queue address is bound or unbound:
- If the queue address is specified, this function binds it to a q_alias.
q_alias
Identifies a global queue reference or a local queue reference. The procedure that MessageQ uses to find this alias is controlled by the name_space_list argument, which is described below.
q_alias_len
Specifies the number of characters in q_alias.
name_space_list
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 (.), MessageQ treats the q_alias as a pathname.
For more information on dynamic binding of queue addresses, see the Using Naming topic.
name_space_list_len
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.
timeout
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.
nullarg_1
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Description
Before an application can call pams_bind_q, it must be attached to the specified queue address. Listing 8-1 shows an attach before the bind call and is typical usage of the two functions together:
Listing 8-1 Example of Using pams_bind_q
int32 mode = PSYM_ATTACH_BY_NUMBER;
int32 q_type = PSYM_ATTACH_PQ;
int32 len=1;
int32 status;
q_address qid;
status = pams_attach_q(&mode,&qid,&q_type,"2",&len,0,0,0,0,0);if (status == PAMS__SUCCESS {
int32 ns=PSEL_TBL_BUS;
int32 ns_len=1;
len = strlen("Q2");status = pams_bind_q(&qid,"Q2",&len,&ns,&ns_len,0,0);
}
Return Values
See Also
- pams_attach_q
Example
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.
pams_cancel_get
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.
Syntax
int32 pams_cancel_get ( sel_filter )Arguments
Argument Data Type Mechanism Prototype Access sel_filter
int32
reference
int32 *
passed
Argument Definition
sel_filter
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.
Return Values
See Also
- pams_cancel_select
pams_cancel_select
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.
Syntax
int32 pams_cancel_select ( index_handle )Arguments
Argument Data Type Mechanism Prototype Access index_handle
int32
reference
int32 *
passed
Argument Definitions
index_handle
Supplies the index handle of the selection mask to cancel. The index_handle is returned by the pams_set_select function.
Return Values
See Also
- pams_get_msga
pams_cancel_timer
Deletes the 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.
Syntax
int32 pams_cancel_timer ( timer_id )Arguments
Argument Data Type Mechanism Prototype Access timer_id
int32
reference
int32 *
passed
Argument Definitions
timer_id
Supplies the timer ID of the timer to cancel. The timer_id is returned by the pams_set_timer function.
Return Values
See Also
- pams_set_timer
pams_close_jrn
Closes the MRS journal file associated with the jrn_handle argument. The two types of journal files are dead letter journal (DLJ) and postconfirmation journal (PCJ). See Using Recoverable Messaging for a description of how to use the MessageQ message recovery system.
Syntax
int32 pams_close_jrn ( jrn_handle )Arguments
Argument Data Type Mechanism Prototype Access jrn_handle
int32
reference
int32 *
passed
Argument Definitions
Jrn_handle
Supplies the journal handle of the message recovery journal file to close. The jrn_handle is returned by the pams_open_jrn function.
Return Values
See Also
- pams_confirm_msg
Example
Closing a Message Recovery Journal
This example shows how to use the MessageQ dead letter journal functionality. It sends messages to a nonexistent queue with an undeliverable message action (UMA) of writing the message into the dead letter journal (DLJ). Because the UMA is taken, the messages are written to the active DLJ file. The active DLJ file is then reset so the original DLJ file can be opened, the messages in it are read and sent to another queue, and closed. The queue named "queue_1" must be defined during group configuration as a primary queue. The complete code example called x_close_jrn.c is contained in the examples directory on OpenVMS systems.
pams_confirm_msg
Confirms receipt of a message that requires explicit confirmation. This can be a recoverable message sent to a queue that is configured for explicit confirmation or a message sent using the ACK delivery mode which must be explicitly confirmed upon receipt. Applications should examine the PSB status field of each message received to determine if the message requires explicit confirmation.
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.
MessageQ can confirm receipt of a recoverable message automatically when the next consecutive message in the recovery journal is delivered. This feature is called implicit confirmation.
All queues must be configured for implicit or explicit confirmation. For complete information on how to configure message queues, see the installation and configuration guide for your system.
Successfully delivered recoverable messages can be recorded in the postconfirmation 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.
Syntax
int32 pams_confirm_msg ( msg_seq_num, confirmation_status,
force_j )Arguments
Argument Data Type Mechanism Prototype Access msg_seq_num
uint32 array
reference
uint32 array *
passed
confirmation_status
int32
reference
int32 *
passed
force_j
char
reference
char *
passed
Argument Definitions
msg_seq_num
Supplies the message sequence number of the recoverable message being confirmed. The message sequence number is generated by the 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.
confirmation_status
Supplies the confirmation status value stored with the message in the postconfirmation journal (PCJ) file. The value is set by the calling application. See the Using Recoverable Messaging topic for more information on using the PCJ file.
force_j
Supplies the journaling action for this message. Following are the predefined constants for this argument:
Description
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.
Return Values
See Also
- pams_get_msg
Example
Confirm Receipt of Recoverable Messages
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.
pams_create_handle
Creates an empty message and returns a handle to it.
Syntax
int32 pams_create_handle ( handle, [ handle_type ] );Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
returned
handle_type
int32
reference
int32 *
passed
Argument Definitions
handle
Supplies the handle that you want created.
handle_type
Specifies the type of handle to create.
Return Values
Description
The handle_type argument takes the PSYM_MSG_HANDLE value to request the creation of a message handle. In this case, the returned pams_handle argument can be used everywhere a pams_handle data type is needed with a function.
PSYM_MSG_HANDLE is a default value, so providing a null pointer as handle_type creates a message handle.
See Also
- pams_delete_handle
pams_decode
The pams_decode functions are a series of functions that decode a tagged field out of the message. The first unseen field in the message with the desired element is returned. The actual name of the function and its description is listed as follows:
Syntax
The syntax for each of the pams_decode functions is as follows:
Listing 8-2 Syntax for pams_encode function
int32 pams_decode_int8 ( pams_handle handle, int32* tag, int8*
value);int32 pams_decode_uint8 ( pams_handle handle, int32* tag, uint8*
value);int32 pams_decode_int16 ( pams_handle handle, int32* tag, int16*
value);int32 pams_decode_uint16 ( pams_handle handle, int32* tag, uint16*
value);int32 pams_decode_int32 ( pams_handle handle, int32* tag, int32*
value);int32 pams_decode_uint32 ( pams_handle handle, int32* tag, uint32*
value);int32 pams_decode_int64 ( pams_handle handle, int32* tag, int64*
value);int32 pams_decode_uint64 ( pams_handle handle, int32* tag, uint64*
value);int32 pams_decode_float ( pams_handle handle, int32* tag, float*
value);int32 pams_decode_double ( pams_handle handle, int32* tag, double*
value);int32 pams_decode_string ( pams_handle handle, int32* tag, char*
value,
int32* bufferLength,
int32* valueLength);int32 pams_decode_array ( pams_handle handle, int32* tag, void*
value,
int32* bufferLength,
int32* numEltsValue);int32 pams_decode_qid ( pams_handle handle, int32* tag,
q_address* value);,
Arguments
The following table describes the arguments for the pams_decode functions above. Some of these arguments apply to certain functions only.
Argument Definitions
handle
Specifies the message handle.
tag
Specifies the tag of the field to decode.
value
Contains the pointer to a buffer to receive the value of the field to decode.
bufferLength
Contains the number of bytes in the value buffer.
valueLength
Specifies the number of bytes in the returned value, unless a NULL pointer is passed. If the valueLength argument is a NULL pointer to the call to pams_decode_string, the string is returned null-terminated. In this case, the specified bufferLength argument must include space for the trailing null.
numEltsValue
Specifies the number of elements contained in the array.
Return Values
Description
This function scans the message for an unseen instance of the specified tag, starting at the beginning of the message:
- If the scan finds a match, the matched element is marked as seen, its value (and length) are returned, and the return value is set to PAMS_ _SUCCESS.
Thus, if there are two occurrences of a particular tag in a message, the first decode call always returns the earlier occurrence of the tag, and the second call returns the later one. Conversely, if a receiving application knows a message's tag order is Atag, Btag, ENDtag, Atag, Btag, ENDtag, the application cannot skip the first pair by decoding first ENDtag, and then decoding Atag.
The value is returned in the local host representation (endian conversions are applied when necessary).
See Also
- pams_encode
pams_delete_handle
Releases all of the resources allocated for the message handle.
Syntax
int32 pams_delete_handle ( handle );Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
Argument Definition
handle
Specifies the message handle to delete.
Return Values
Return Code Platform Description PAMS_ _BADARGLIST
All
Invalid number of arguments.
PAMS_ _BADHANDLE
All
Invalid message handle.
PAMS_ _SUCCESS
All
Indicates successful completion.
Description
Applications must use this function after sending or receiving messages. The use of this function avoids memory leaks. Note that your application must call this function if you decide not to send a message you have created.
See Also
- pams_create_handle
pams_detach_q
Detaches a selected message queue or all of the application's message queues from the message queuing bus. When an application detaches from its primary queue, this function automatically detaches all secondary queue attachments defined for the primary queue. When the last message queue has been detached, the application is automatically detached from the MessageQ message queuing bus.
Syntax
int32 pams_detach_q ( q, detach_opt_list, detach_opt_len,
msgs_flushed )Arguments
Argument Definitions
q
Supplies the queue address of the queue to be detached. This function can be used to detach primary, secondary, and multireader queues.
detach_opt_list
Supplies an array of int32 values used to control how the queue is detached. The predefined constants for this argument are:
- PSYM_NOFLUSH_Q-Detaches the queue without flushing the pending messages stored in memory. The default action is to flush pending messages in the queue before it is detached. Messages are never flushed from multireader queues.
detach_opt_len
Supplies the number of int32 values in the detach_opt_list array. The maximum number of int32 longwords is 32,767.
msgs_flushed
Receives the number of messages that were flushed from the queue. Message count statistics are enabled on all systems by default; therefore, it is not necessary to enable statistics on UNIX and Windows NT systems in order to properly return this value.
Description
If you are using implicit confirmation with recoverable messaging, you must ensure that the last message is confirmed before:
- Detaching from the queue which received the message by calling pams_detach_q
If you do not ensure that the last message was confirmed before detaching or exiting, the message will be redelivered when the queue is reattached. The easiest method to ensure confirmation is to save the PSB delivery status of the last message received, check it for the required confirmation status, and then exit after the message has been confirmed.
Return Values
See Also
- pams_attach_q
pams_encode
The pams_encode functions are a series of functions that append a field in the SDM message based on a specific data type. The actual name of the function and its description is as follows:
Syntax
The syntax for each of the pams_encode functions is as follows:
Listing 8-3 Syntax for pams_encode_functions
int32 pams_encode_int8 ( pams_handle handle, int32* tag, int8*
value);int32 pams_encode_uint8 ( pams_handle handle, int32* tag, uint8*
value);int32 pams_encode_int16 ( pams_handle handle, int32* tag, int16*
value);int32 pams_encode_uint16 ( pams_handle handle, int32* tag,
uint16* value);int32 pams_encode_int32 ( pams_handle handle, int32* tag, int32*
value);int32 pams_encode_uint32 ( pams_handle handle, int32* tag, uint32*
value);int32 pams_encode_int64 ( pams_handle handle, int32* tag, int64*
value);int32 pams_encode_uint64 ( pams_handle handle, int32* tag,
uint64* value);int32 pams_encode_float ( pams_handle handle, int32* tag, float*
value);int32 pams_encode_double ( pams_handle handle, int32* tag,
double* value);int32 pams_encode_string ( pams_handle handle, int32* tag, char*
value, int32* length);int32 pams_encode_array ( pams_handle handle, int32* tag, void*
value, int32* numElts);int32 pams_encode_qid ( pams_handle handle, int32* tag,
q_address* value);Arguments
The following table describes the arguments for the pams_encode functions. Some of these arguments apply to certain functions only.
Argument Definitions
handle
Specifies the message handle.
tag
Specifies the tag of the field to encode.
value
Specifies the value of the field to encode.
length
Specifies the length of the string to encode, or -1 if the string is null terminated.
numElts
Specifies the number of elements in the array.
Return Values
Description
Several structures exist to encode fields for each data type supported by the SDM capability. The application developer uses the function that matches the data type of the field to encode. Since the tag embeds information about the value data type, the PAMS_ _BADTAG code is returned if the function used does not match the tag data type. For example, if the pams_encode_int32 function is used to encode a character string. The PAMS_ _BADTAG code is also returned if the tag construction does not follow the rules or if the tag is reserved.
You can insert a null tag (PSDM_NULL_TAG) in a SDM message to control application behavior. For example, you can insert a null tag to stop an enumeration. To insert a null tag, use any of the numeric pams_encode functions and specify a NULL value pointer. The following code fragment shows how to insert a null tag into a signed 32-bit integer element:
null_tag = PSDM_NULL_TAG;
status = pams_encode_int32(mh, &null_tag, NULL);
See Also
- pams_decode
pams_exit
Terminates all attachments between the application and the MessageQ message queuing bus. All pending messages in temporary queues and permanent queues which are not defined as permanently active are discarded. Only the messages pending in permanently active queues, including multireader queues, are retained.
Syntax
int32 pams_exit (void)Arguments
None.
Description
If you are using implicit confirmation with recoverable messaging, you must ensure that the last message is confirmed before:
- Detaching from the queue which received the message by calling pams_detach_q
If you do not ensure that the last message was confirmed before detaching or exiting, the message will be redelivered when the queue is reattached. The easiest method to ensure confirmation is to save the PSB delivery status of the last message received, check it for the required confirmation status, and then exit after the message has been confirmed.
Return Values
Return Code Platform Description PAMS_ _SUCCESS
All
Indicates successful completion.
See Also
- pams_attach_q
Example
Exit the Message Queuing Bus
This example shows how to use the pams_exit function. The complete code example called x_exit.c is contained in the examples directory.
pams_extract_buffer
Returns a message in the specified buffer. The message size is also returned.
Syntax
int32 pams_extract_buffer ( handle, msgBuffer, bufferLength, msgLength);
Argument Definitions
handle
Specifies the message handle of the message to extract.
msgBuffer
Contains the pointer to the buffer from which to extract the message.
bufferLength
Specifies the size in bytes of msgBuffer.
msgLength
Contains the pointer where to place the message's length. You can specify a NULL pointer in languages that allow these kinds of pointers.
Return Values
Description
This function copies the received message associated with the specified handle into the user provided buffer. If requested (by passing a non-NULL msgLength), the number of bytes of the message is returned as well.
If the message handle points to an SDM message for which encoding or decoding has already been performed, this function returns PAMS_ _BADHANDLE.
If your application does not know the maximum size message that can arrive, it can call the pams_msg_length function prior to calling pams_extract_buffer to determine how big a buffer is needed.
See Also
- pams_create_handle
pams_get_msg
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 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 message handle or large message by reading the msg_area_len argument. See the Sending and Receiving MessageQ Messages topic for more information on working with message handles and large messages.
Syntax
int32 pams_get_msg ( msg_area, priority, source, class, type,
msg_area_len, len_data, [sel_filter], [psb],
[show_buffer], [show_buffer_len], [large_area_len],
[large_size], [nullarg_3] )Arguments
Argument Definitions
msg_area
For buffer-style messaging, receives the address of a memory region where MessageQ writes the contents of the retrieved message. For handle -style messaging, receives the message handle of the message being retrieved.
priority
Supplies the priority level for selective message reception. There are two priority levels: 0 retrieves messages with standard priority or 1 retrieves messages with a high priority.
source
Receives a data structure containing the group ID and queue number of the sender program's primary queue in the following format:
class
Receives the class code of the retrieved message. The class is specified in the pams_put_msg function. 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.
Class symbols reserved by MessageQ are as follows:
Reserved Class Symbol Value MSG_CLAS_MRS
28
MSG_CLAS_PAMS
29
MSG_CLAS_ETHERNET
100
MSG_CLAS_UCB
102
MSG_CLAS_XXX
30000 through 32767
type
Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. 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.
MessageQ has reserved the symbol value range -1 through -5000. A zero value for this argument indicates that no processing by message type is expected.
msg_area_len
- 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.
len_data
For 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_HANDLE symbol for handle-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.
sel_filter
Supplies the criterion to enable the application to selectively retrieve messages. The argument contains one of the following selection criteria:
- Default selection
The sel_filter argument is composed of two words as follows:
Default Selection
Enables 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.
Selection by Message Queue
Allows the application to retrieve messages based upon a queue type or combination of queue types. This selection criteria is used to retrieve the first pending message that matches the criteria on the first queue it encounters. FIFO ordering is maintained within each queue. The predefined constants for this argument are as follows:
Selection by Message Attribute
Enables the application to select messages based on the message type, class, or priority. The predefined constants for this argument are as follows:
Selection by Message Source
Provides for the selection of pending messages from primary and secondary queues, by source group ID, queue number, or both. The format for selection by source -follows:
Some examples of possible sel_filter arguments and their actions are as follows:
Compound Selection
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:
psb
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:
show_buffer
Receives additional information which MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
show_buffer_len
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.
large_area_len
Supplies the size of the message buffer to receive messages larger than 32K..
large_size
Returns the actual size of the large message written to the message buffer.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Return Values
PBS Delivery Status
See Also
- pams_get_msga
Example
Read a Message
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.
pams_get_msga
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 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 MessageQ recovery system.
See the Sending and Receiving MessageQ Messages topic for more information on working with message handles and large messages.
Syntax
int32 pams_get_msga ( msg_area, priority, source, class, type,
msg_area_len, len_data, [sel_filter], [psb],
[show_buffer], [show_buffer_len],
[large_area_len], [large_size], [actrtn],
[actparm], [flag_id], [nullarg_3] )Arguments
Argument Definitions
msg_area
For buffer-style messaging, receives the address of a memory region where MessageQ writes the contents of the retrieved message. For handle-style messaging, receives the message handle of the message being retrieved.
priority
Supplies the priority level of the message retrieved. There are two priority levels: 0 for standard priority or 1 for high priority.
source
Receives a data structure containing the sender program's primary queue in the following format:
class
Receives the class code of the retrieved message. The class is specified in the pams_put_msg function. 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 MessageQ are as follows:
Reserved Class
Symbol Value
MSG_CLAS_MRS
28
MSG_CLAS_PAMS
29
MSG_CLAS_ETHERNET
100
MSG_CLAS_UCB
102
MSG_CLAS_XXX
30000 through 32767
type
Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. 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.
MessageQ has reserved the symbol value range -1 through -5000. A zero value for this argument indicates that no processing by message type is expected.
msg_area_len
- 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.
len_data
For 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_HANDLE symbol for handle-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.
sel_filter
Supplies the criteria enabling the application to selectively retrieve messages. The argument contains one of the following selection criteria:
- Default selection
The sel_filter argument is composed of two words as follows:
Default Selection
Enables 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.
Selection by Message Queue
Allows the application to retrieve messages based upon a queue type or combination of queue types. This selection criteria is used to retrieve the first pending message that matches the criteria on the first queue it encounters. FIFO ordering is maintained within each queue.
The predefined constants for this argument are as follows:
Selection by Message Attribute
Enables the application to select messages based on the message type, class, or priority. The predefined constants for this argument are as follows:
Selection by Message Source
Provides for the selection of pending messages from primary and secondary queues, by source group ID, queue number, or both. The format for selection by source follows:
Some examples of possible sel_filter arguments and their actions are as follows:
Compound Selection
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.
psb
Receives 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:
Note: This function utilizes the AST services of OpenVMS; therefore, the application must check the status information returned in the PSB.
show_buffer
Receives additional information which MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
show_buff_len
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.
large_area_len
Specifies the size of the message buffer to receive messages larger than 32K.
large_size
Returns the actual size of the large message written to the message buffer.
actrtn
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.
actparm
Supplies an int32 value that is passed to the action routine specified in the actrtn argument when it is invoked.
flag_id
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.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Description
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:
- Create a context area, separate from mainline, for each AST that is simultaneously posted. A handle, address, or index associated with the context area should be used as the AST parameter to ensure the appropriate context is associated with the data that is delivered by the pams_get_msga function.
- Data may be passed between AST routines and mainline by the following mechanisms:
- MessageQ messages.
- Access to complex data structures shared between mainline and AST routines should be serialized by placing the access inside an AST safe critical section. One way to do this is with the $SETAST system service.
Return Values
PSB Delivery Status
See Also
- pams_cancel_get
pams_get_msgw
Retrieves the next available message from a specified queue and moves it to the location specified in the msg_area argument. This function waits until a message arrives in the queue or a user-specified timeout period has elapsed.
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 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 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 MessageQ recovery system.
See the Sending and Receiving MessageQ Messages topic for more information on working with message handles and large messages.
Syntax
int32 pams_get_msgw ( msg_area, priority, source, class, type, msg_area_len, len_data, timeout, [sel_filter], [psb], [show_buffer], [show_buffer_len], [large_area_len], [large_size], [nullarg_3] )Argument
Argument Definitions
msg_area
For buffer-style messaging, receives the address of a memory region where MessageQ writes the contents of the retrieved message. For handle-style messaging, receives the message handle of the message being retrieved.
priority
Supplies the priority level of the message retrieved. There are two priority levels: 0 for standard priority or 1 for high priority.
source
Receives a structure identifying the group ID and queue number of the sender program's primary queue in the following format:
class
Receives the class code of the retrieved message. The class is specified in the arguments of the pams_put_msg function. 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.
Class symbols reserved by MessageQ are as follows:
Reserved Class
Symbol Value
MSG_CLAS_MRS
28
MSG_CLAS_PAMS
29
MSG_CLAS_ETHERNET
100
MSG_CLAS_UCB
102
MSG_CLAS_XXX
30000 through 32767
type
Receives the type code of the retrieved message. The type is specified in the arguments of the pams_put_msg function. 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.
MessageQ has reserved the symbol value range -1 through -5000. A zero value for this argument indicates that no processing by message type is expected.
msg_area_len
- 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.
len_data
For 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_HANDLE symbol for handle-style messages and PSYM_MSG_LARGE for buffer-style messages larger than 32767 bytes.
timeout
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.
If an unlimited timeout period is required, set this argument to 0. On UNIX and Windows NT systems, a value of zero for this argument causes this function to block indefinitely or until it receives a message. On OpenVMS systems, this function waits for approximately 5 days or until it receives a message.
sel_filter
Supplies the criteria for the application to selectively retrieve messages. The argument contains one of the following selection criteria:
- Default selection
The sel_filter argument is composed of two words as follows:
Default Selection
Enables 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.
Selection by Message Queue
Allows the application to retrieve messages based upon a queue type or combination of queue types. This selection criteria is used to retrieve the first pending message that matches the criteria on the first queue it encounters. FIFO ordering is maintained within each queue. The predefined constants for this argument are as follows:
Selection by Message Attribute
Enables the application to select messages based on the message type, class, or priority. The predefined constants for this argument are as follows:
Selection by Message Source
Provides for the selection of pending messages from primary and secondary queues, by source group ID, queue number, or both. The format for selection by source -follows:
Some examples of possible sel_filter arguments and their actions are as follows:
Compound Selection
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:
.
psb
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:
show_buffer
Receives additional information which MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:
show_buff_len
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.
large_area_len
Specifies the size of the message area to receive messages larger than 32K.
large_size
Returns the actual size of the large message written to the message buffer.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Return Codes
See Also
- pams_get_msga
Example
Block Until a Message Is Read
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.
pams_insert_buffer
Inserts the contents of the specified buffer into the message identified by the message handle.
Syntax
int32 pams_insert_buffer ( handle, msgBuffer, length );Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
msgBuffer
char
reference
char *
passed
length
uint32
reference
uint32 *
passed
Argument Definitions
handle
Specifies the message handle.
msgBuffer
Specifies the pointer to a user area to use as message content.
length
Specifies the size in bytes of the msgBuffer buffer or zero.
Return Values
Description
This function copies the user-provided buffer into the received message that is associated with the specified handle. If a buffer was already inserted in the message, it is overwritten by a subsequent call to the pams_insert_buffer function. If the length -argument points to a zero-valued integer, the buffer to insert is an SDM message.
See Also
- pams_create_handle
pams_locate_q
Locates the queue address for the specified queue name or queue alias. By default, this function waits for the queue address to be returned.
Syntax
int32 pams_locate_q ( q_name, q_name_len, q_address, [wait_mode],
[req_id], [resp_q], [name_space_list],
[name_space_list_len], [timeout] )Arguments
Argument Definitions
q_name
Supplies the queue name or queue alias whose queue address is requested. The procedure that MessageQ uses to find this name is controlled by the name_space_list argument, described below.
q_name_len
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 MessageQ environments, the maximum string length is 31.
q_address
Receives the queue address assigned by MessageQ when an application has successfully located the queue name.
wait_mode
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.
req_id
Supplies an application-specified transaction ID to associate with the pams_locate_q function.
resp_q
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:
Note that the group ID field is always equal to zero because the sender program cannot specify a response queue outside its group.name_space_list
If 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:
Location it represents Symbolic value Process cache
PSEL_TBL_PROC
Group/group cache
PSEL_TBL_GRP
Global name space
PSEL_TBL_BUS ( or PSEL_TBL_BUS_MEDIUM or PSEL_TBL_BUS_LOW)
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.)
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.
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 master database, specify PSEL_TBL_BUS_MEDIUM instead of PSEL_TBL_BUS.
For more information on dynamic binding of queue addresses, see the Using Naming topic.
name_space_list_len
Supplies the number of entries in the name_space_list argument. If the name_space_list_len argument is zero, MessageQ uses PSEL_TBL_GRP as the default in the name_space_list argument.
timeout
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.
Return Values
See Also
- pams_attach_q
Example
Locate a Queue Address
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.
pams_msg_length
Returns the number of bytes in the message. The message is identified by a message handle created with the pams_create_handle function.
Syntax
int32 pams_msg_length ( handle, msgLength );Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
msgLength
uint32
reference
uint32 *
returned
Argument Definitions
handle
Specifies the message handle of the message.
msgLength
Contains the message handle of the message.
Return Values
Return Code Platform Description PAMS_ _SUCCESS
All
Indicates successful completion.
PAMS_ _BADARGLIST
All
Invalid number of arguments.
PAMS_ _BADHANDLE
All
Invalid message handle.
See Also
- pams_create_handle
pams_next_msg_field
Returns the tag and length of the first unseen field in the message.
Syntax
int32 pams_next_msg_field (pams_handle handle, tag, valueLength)Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
tag
int32
reference
int32 *
returned
valueLength
int32
reference
int32 *
returned
Argument Definitions
handle
Specifies the message handle of the message to scan.
tag
Returns the tag of first unseen field in the message.
valueLength
Returns the length of the returned value or a NULL pointer, if the user is not interested in this information. The length returned is the size in bytes necessary to receive the value. For strings, it is the string length (null terminator not included). For arrays, it is the number of fields multiplied by the size of each field.
Return Values
Description
This function does not mark the matched field as seen. Therefore, successive calls to this function without calling the appropriate pams_decode functions returns the same tag.
When all fields have been decoded, the function returns PAMS_ _NOMORETAG.
See Also
- pams_decode
pams_open_jrn
Opens the selected message recovery journal. The MessageQ dead letter journal (DLJ) stores messages designated as recoverable that could not be delivered by the recovery system. The MessageQ postconfirmation journal (PCJ) stores recoverable messages that were successfully delivered. See the Using Recoverable Messaging topic for a description of MessageQ message recovery services.
Syntax
int32 pams_open_jrn ( jrn_filespec, jrn_filename_len, jrn_handle )Arguments
Argument Data Type Mechanism Prototype Access jrn_filespec
char
reference
char *
passed
jrn_filename_len
short
reference
short *
passed
jrn_handle
int32
reference
int32 *
returned
Argument Definitions
jrn_filespec
Supplies the file name of the message recovery journal from which the application will read stored messages.
jrn_filename_len
Supplies the length of the file specification entered to the jrn_filespec argument specified (filename array) in number of bytes.
jrn_handle
Receives the journal handle for the selected message recovery file if this function completes successfully.
Return Values
Return Code Platform Description PAMS_ _NOJRN
OpenVMS
Error occurred when attempting to open the journal file specified.
PAMS_ _SUCCESS
OpenVMS
Indicates successful completion.
See Also
- pams_close_jrn
Example
Opening a Message Recovery Journal
This example shows how to use the dead letter journal. It sends messages to a nonexistent queue with a UMA that directs messages that cannot be stored by the message recovery system to be stored in the dead letter journal. Since the uma will be taken, the messages are put in the active DLJ. The active DLJ is reset so that the original DLJ can be opened, the messages in it read and sent to another queue, and closed. The complete code example called x_open_jrn.c is contained in the examples directory on OpenVMS systems.
pams_put_msg
Sends a message to a target queue using a set of standard MessageQ delivery modes. Applications specify buffer-style or handle-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_HANDLE-indicates handle-style messaging. The msg_area argument must contain the message handle.
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 message handle when sending a message, the sender program specifies the symbol PSYM_MSG_HANDLE as the msg_size argument to the pams_put_msg function.
Syntax
int32 pams_put_msg ( msg_area, priority, target, class, type, delivery, msg_size, [timeout], [psb], [uma], [resp_q], [large_size], [nullarg_2], [nullarg_3] )Arguments
Argument Definitions
msg_area
For buffer-style messaging, supplies the address of a memory region or a message handle containing the message to be delivered to the target queue of the receiver program. For handle-style messaging, supplies the message handle that points to the message.
priority
Supplies the priority level of the message being sent. There are two priority levels: 0 for standard priority or 1 for high priority.
target
Supplies the queue number and group ID of the receiver program's queue address in the following format:
.
class
Supplies the class code of message being sent. 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.
Class symbols reserved by MessageQ are as follows:
Reserved Class Symbol Value MSG_CLAS_MRS
28
MSG_CLAS_PAMS
29
MSG_CLAS_ETHERNET
100
MSG_CLAS_UCB
102
MSG_CLAS_XXX
30000 through 32767
type
Supplies the type code for the message being sent. 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.
MessageQ has reserved the symbol value range -1 through -5000. A zero value for this argument indicates that no processing by message type is expected.
delivery
Supplies the delivery mode for the message using the following format:
- PDEL_MODE_sn_dip where sn is one of the following sender notification constants:
And dip is one of the following delivery interest point constants:
- ACK-Read from target queue and explicitly acknowledged using the pams_confirm_msg function
- DEQ-Read from the target queue
- DQF-Stored in the destination queue file (recoverable)
msg_size
For buffer-style messaging using message buffers up to 32K, supplies the length of the message in bytes in the user's msg_area buffer. In addition, you can specify one of the following symbols:
- PSYM_MSG_HANDLE--indicates handle-style messaging. The msg_area argument must contain the message handle.
timeout
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.
psb
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.
The structure of the PSB is as follows:
uma
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:
Symbol Description DISC
Discard message
DISCL
Discard after logging message
DLJ
Dead letter journal
DLQ
Dead letter queue
RTS
Return to sender
SAF
Store and Forward
resp_q
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:
The group ID is always specified as zero because the sender program cannot assign a response queue outside its group.large_size
Supplies the actual size of the large message written to the message buffer.
nullarg_2
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Return Values
See Also
- pams_get_msg
Example
Send a Message
This example sends a number of messages to a queue. The complete code example called x_putslf.c is contained in the examples directory.
pams_read_jrn
Reads a message from a 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 message handle or a large message by reading the len_data argument. See the Sending and Receiving MessageQ Messages topic for more information on working with message handles and large messages.
Syntax
int32 pams_read_jrn ( jrn_handle, msg_area, priority, source, class, type, msg_area_len, len_data, target, write_time, conf_val, msg_seq_num, mrs_status, [large_area_len], [large_size], [nullarg_3] )Arguments
Argument Definitions
jrn_handle
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.
msg_area
Receives the contents of the message retrieved from the selected message recovery journal. This argument contains either the address of a memory region or a message handle where MessageQ writes.
priority
Receives the priority level of the journaled message. There are two priority levels: 0 for the standard priority or 1 for a high priority.
source
Receives a structure containing the queue number and group ID of the sender program's primary queue in the following format:
class
Receives the class code of the retrieved message. The class is specified in the arguments of the pams_put_msg function. 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 MessageQ are as follows:
Reserved Class Symbol Value MSG_CLAS_MRS
28
MSG_CLAS_PAMS
29
MSG_CLAS_ETHERNET
100
MSG_CLAS_UCB
102
MSG_CLAS_XXX
30000 through 32767
type
Receives the type code of the journaled message. The type is specified in the arguments of the pams_put_msg function. 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.
msg_area_len
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.
len_data
- For buffer-style messaging with messages of up to 32K, this argument receives the number of bytes retrieved from the message queue and stored in the area specified by the msg_area argument.
target
Receives the queue number and group ID of the receiver's queue address in the following format:
write_time
Receives the address of the quadword (an array of two int32 values) specifying the date and time that the recoverable message was confirmed. This parameter uses standard OpenVMS system time.
conf_val
Receives the message confirmation value.
msg_seq_num
Receives the message sequence number generated by MessageQ in the PSB of the received message. This argument should be set to the values in the PSB.
mrs_status
Receives the Message Recovery Services (MRS) status of the message.
large_area_len
Specifies the size of the message buffer to receive messages larger than 32K.
large_size
Returns the actual size of the large message written to the message buffer.
nullarg_3
Reserved for MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.
Return Values
See Also
- pams_close_jrn
Example
Reading Messages from a Recovery Journal
This example illustrates how to use the pams_read_jrn function to read messages from the dead letter journal. The example begins by forcing a message to be written to the dead letter journal by sending a recoverable message to a queue that does not exist. Because the recovery system is unable to deliver the message, the UMA is taken. In this case, the UMA is to write the message to the DLJ. The remaining portion of the example shows how to open the journal file and read messages. To run this example, "queue_1" must be defined in your initialization file as a primary queue. The complete code example called x_read_jrn.c is contained in the examples directory on OpenVMS systems.
pams_remove_encoding
Removes a previously encoded field from the message buffer.
Syntax
int32 pams_remove_encoding (pams_handle handle, int32* tag, int32* flags);Argument
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
tag
int32
reference
int32 *
passed
flags
int32
reference
int32 *
passed
Argument Definitions
handle
Specifies the message handle.
tag
Specifies the tag of the field to remove. If the tag is PSDM_NULL_TAG, the first or last - depending on flags - encoded null tag is removed.
flags
Specifies the flags to control the function behavior. The flags argument can take the following values:
- PSDM_FIRST to remove the first encoded field matching tag.
Return Values
See Also
- pams_decode
pams_set_msg_position
Resets the message to the position of a specific tag.
Syntax
int32 pams_set_msg_position (pams_handle handle, int32* tag, int32*
flags);Arguments
Argument Data Type Mechanism Prototype Access handle
pams_handle
reference
pams_handle *
passed
tag
int32
reference
int32 *
passed
flags
int32
reference
int32 *
passed
Argument Definitions
handle
Specifies the message handle.
tag
Specifies the tag to reset encoding or decoding to.
flags
Specifies the flags argument, which is a mask allowing you to specify the behavior. It can OR the following modifiers:
- PSDM_PREVIOUS searches for the previous occurrence of the specified tag (default for encoding).
- PSDM_NEXT searches for the next occurrence of the specified tag (default for decoding).
- PSDM_FIRST searches for the first occurrence of the specified tag in the message.
- PSDM_LAST searches for the last occurrence of the specified tag in the message.
- PSDM_AT sets the position at the element specified (default).
- PSDM_BEFORE sets the position at the element preceding the specified element.
- PSDM_AFTER sets the position at the element following the specified element.
- PSDM_ANY tells to ignore the specified tag argument. The following combinations are possible :
- (PSDM_ANY | PSDM_PREVIOUS) sets position at the previous tag.
- (PSDM_ANY | PSDM_FIRST) sets position at the beginning of the message.
The modifiers PSDM_PREVIOUS, PSDM_NEXT, PSDM_FIRST, and PSDM_LAST are mutually exclusive.
The modifiers PSDM_AT, PSDM_BEFORE, and PSDM_AFTER are also mutually exclusive.
Return Values
Description
This function resets the starting point of the encoding or decoding to the field in the message with the specified tag:
- When used to perform further encoding, already encoded fields after the specified element are lost.
- pams_encode
pams_set_select
Allows application developers to define complex selection criteria for message reception. The selection array specifies the queues to search, the priority order of message reception, two comparison keys for range checking, and an order key to determine the order in which messages are selected from the queue.
The pams_set_select function creates an index handle that is used as the sel_filter argument of 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.
Syntax
int32 pams_set_select ( selection_array, num_masks, index_handle )Arguments
Argument Definitions
selection_array
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:
typedef struct _selection_array_component {
int32 queue;
int32 priority;
int32 key_1_offset;
int32 key_1_size;
int32 key_1_value;
int32 key_1_oper;
int32 key_2_offset;
int32 key_2_size;
int32 key_2_value;
int32 key_2_oper;
int32 order_offset;
int32 order_size;
int32 order_order;
} selection_array_component;The selection_array_component data structure has the following components:
The following tables define the content of each of the components of the selection_array_component data structure.
Queue and Priority
The following table specifies the valid values that can be applied to the arguments in this part of the Select_Queue structure:
Comparison Keys
The following table specifies the arguments and valid values that can be applied to this part of the Selection_Array_Components structure:
Order Key
The Order Key part contains variables described in the following table:
num_masks
Supplies the number of records in the selection array. This argument allows a minimum of 1 record to a maximum of 256 records in the selection array.
index_handle
Receives a variable containing the index handle for the selection mask as follows:
- The high-order word contains PSEL_BY_MASK.
- The low-order word contains the index to the selection array.
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 MessageQ implementations offer 16K to 32K index handles.
Return Values
See Also
- pams_cancel_get
Example
Selecting Messages Using a Complex Selection Filter
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.
pams_set_timer
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 MessageQ timer, use the pams_cancel_timer function with the identification code of the timer you want to cancel.
Syntax
int32 pams_set_timer ( timer_id, timer_format, p_timeout,
s_timeout )Arguments
Argument Definitions
timer_id
Supplies a unique timer identification value created by the application. Must be greater than zero.
timer_format
Supplies the time format being used. Following are the two predefined constants for this argument:
- 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.
p_timeout
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.
s_timeout
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, Windows NT, and OS/2 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:
struct timeval theTime;
nStatus = pams_set_timer(99, "S", NULL, (int32 *) &theTime);Return Values
See Also
- pams_cancel_timer
Example
Set a Timer
This example shows how to use the 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.
pams_status_text
Receives the severity level and text description of a user-supplied PAMS API return code and moves that information to a user-supplied storage area. If the error code is not known, an error is returned and the call parameters are not filled in.
Syntax
int32 pams_status_text ( code, severity, buffer, buflen, retlen)Arguments
Argument Definitions
code
Specifies the return value for which you would like the text description and severity level returned.
severity
Receives a code indicating the severity level of the message. Severity levels apply to both success and error messages. They are designed to provide more information about the message being returned. The valid codes returned to this argument are as follows:
0 = warning
1 = success
2 = error
3 = informational
4 = fatal errorbuffer
Receives the text description for the return status supplied.
buflen
Specifies the length of the buffer to store the text description returned. A buffer length of 256 bytes is adequate to store the text description for all return status codes. If the user buffer supplied is large enough, the string is zero terminated. The buffer length must be entered as a positive integer. Supplying a negative integer value to this argument causes the function to return a status of PAMS_ _BADPARAM. If you specify this argument as zero, no text is returned to the buffer and the function returns the status of PAMS_ _TRUNCATED.
retlen
Receives the size of the user-supplied buffer space that was filled by the text description returned.
Description
Application developers use the pams_status_text function to obtain a text description and severity level for each API return value. The text description contains both the symbolic name (as it is defined in the include files and described in the documentation) followed by a comma, a space, and then a description of the return value in the following format:
PAMS_ _SUCCESS, normal successful completionIn addition to the text description, this function returns a code indicating the severity level for both success and error messages.
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.
Return Values
putil_show_pending
Requests the number of pending messages for a list of selected queues. To use the putil_show_pending function, specify the number of message queues for which you want to obtain a pending message count and the list of queue addresses for which you want to obtain a pending message count. The value returned by this function contains the total number of messages in each memory queue. On OpenVMS systems, this function also returns the number of pending messages in the local recovery journals targeted for delivery to the selected queue.
Syntax
int32 putil_show_pending ( count, in_q_list, out_pend_list )Arguments
Argument Data Type Mechanism Prototype Access count
int32
reference
int32 *
passed
in_q_list
short array
reference
short array*
passed
out_pend_list
int32 array
reference
int32 array *
returned
Argument Definitions
count
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.
in_q_list
Supplies an array of int32 values containing the queue numbers for which the pending message count is requested.
out_pend_list
Receives the pending message count for each selected queue.
Return Values
Example
Display Number of Pending Messages
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.