PAMS Application Programming Interface

 

Because the BEA MessageQ application programming interface (API) is portable, the API is documented once for all supported platforms. This chapter describes all BEA MessageQ callable services in alphabetical order using a standard description -format.

BEA MessageQ API Description Format

The beginning of each description contains the entry-point name and a brief description of the function performed. Table 8-1 describes the sections in the description of each callable service.

Table 8-1 Callable Service Description Format

In the section entitled . . .	You will find . . .
Syntax	The syntax for using the callable service with the entry-point name and argument list. Square brackets ([ ]) indicate optional arguments to the service.
Arguments	The data type, passing mechanism, C language prototype, and access for each argument.
Argument Definitions	Detailed information on how to specify each argument.
Description	More detailed information on how to use the callable service.
Return Values	The return codes with the platforms on which they are supported.
See Also	A list of related callable services.
Example	A sample program illustrating the use of the callable service. These sample programs are available in the examples directory of the BEA MessageQ media kit.

BEA MessageQ API Data Types

BEA MessageQ API arguments use data types defined by the C programming language and some data types defined by BEA MessageQ software. Data types such as short, -unsigned short, and char are data types defined by the C programming language. BEA MessageQ data types such as q_address and the PSB and show_buffer structures are defined in the p_entry.h include file.

BEA MessageQ supports data type definitions for signed and -unsigned longwords. The int32 data type defined by BEA 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 Compaq's 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 BEA MessageQ Version 2.0 platforms. BEA MessageQ Version 2.0 software uses the standard signed longword and unsigned longword data types defined by the C programming language.

pams_attach_q

Connects an application program to the BEA 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

Table 8-2

Argument	Data Type	Mechanism	Prototype	Access
attach_mode	int32	reference	int32 *	passed
q_attached	q_address	reference	q_address *	returned
[q_type]	int32	reference	int32 *	passed
[q_name]	char	reference	char *	passed
[q_name_len]	int32	reference	int32 *	passed
[name_space_list]	int32 array	reference	int32 array *	passed
[name_space_list_len]	int32	reference	int32 *	passed
[timeout]	int32	reference	int32 *	passed
[nullarg_2]	char	reference	char *	passed
[nullarg_3]	char	reference	char *	passed

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

• PSYM_ATTACH_BY_NUMBER-Attach by number

• PSYM_ATTACH_TEMPORARY-Attach as a temporary queue

When attach_mode is PSYM_ATTACH_BY_NAME, the application attaches to the queue identified by the specified queue or alias name. BEA MessageQ finds the queue by implicitly performing a pams_locate_q call for the specified q_name. The procedure that BEA MessageQ uses is determined by the name_space_list argument.

q_attached

Receives the queue address from BEA 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)

• PSYM_ATTACH_SQ-Secondary queue

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 BEA 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.

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 BEA 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.)

• 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 (.), BEA MessageQ treats it as a pathname. Otherwise, BEA 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.

  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, BEA 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 BEA MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.

nullarg_3

Reserved for BEA 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 BEA MessageQ message queuing bus must be configured. A BEA MessageQ message queuing bus is a collection of one or more BEA 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 BEA 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 BEA MessageQ environment.

To receive BEA 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 BEA 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. BEA 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.

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

Table 8-3

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Wrong number of call arguments has been passed to this function.
PAMS__BADDECLARE	All	Queue has already been attached to this application.
PAMS__BADNAME	All	Invalid name string was specified.
PAMS__BADPARAM	All	Invalid argument in the argument list.
PAMS__BADPROCNUM	All	Queue number out of range.
PAMS__BADQTYPE	All	Invalid queue type.
PAMS__BADTMPPROC	OpenVMS	Invalid temporary queue number.
PAMS__DECLARED	All	The queue number is already attached to another application or process.
PAMS__DUPLQNAME	OpenVMS	Duplicate queue name.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOACCESS	All	No access to the resource. The address of the specified name is either 0 or it is in another group.
PAMS__NOACL	All	The queue access control file could not be found.
PAMS__NOOBJECT	All	No such queue name. For a global queue reference, this error can be caused by a bad default pathname in the group configuration file.
PAMS__NOQUOTA	OpenVMS	Insufficient receive message or byte quota to attach.
PAMS__NOTBOUND	All	The queue name is not bound to an address.
PAMS__NOTMRQ	OpenVMS	Attempting to attach to Multi-reader Queue and queue type is not an MRQ.
PAMS__NOTPRIMARYQ	All	Queue name or number is not a primary queue.
PAMS__NOTSECONDARYQ	All	Queue name or number is not a secondary queue.
PAMS__PAMSDOWN	All	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	The previous call to CLS has not been completed.
PAMS__PNUMNOEXIST	OpenVMS	Target queue name or number does not exist.
PAMS__RESRCFAIL	All	Failed to allocate resources.
PAMS__SUCCESS	All	Successful completion of an action.
PAMS__TIMEOUT	All	The timeout period specified has expired.

See Also

• pams_detach_q

• pams_exit

• pams_locate_q

Examples

• 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

Table 8-4

Argument	Data Type	Mechanism	Prototype	Access
q_addr	q_address	reference	q_address *	passed
q_alias	char	reference	char *	passed
q_alias_len	int32	reference	int32 *	passed
[name_space_list]	int32 array	reference	int32 array *	passed
[name_space_list_len]	int32	reference	int32 *	passed
[timeout]	int32	reference	int32 *	passed
[nullarg_1]	char	reference	char *	passed

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.

• 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.

q_alias

Identifies a global queue reference or a local queue reference. The procedure that BEA 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 (.), BEA MessageQ treats the q_alias as a pathname.

• Otherwise, BEA 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.)

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 BEA 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

Table 8-5

Return Code	Platform	Description
PAMS__BADARGLIST	All	Invalid number of call arguments.
PAMS__BADNAME	All	Name contains bad characters.
PAMS__BADPARAM	All	The name space list is invalid.
PAMS__BOUND	All	Returned if a non-zero value for q_addr is passed and the specified q_alias is already assigned to a queue address.
PAMS__DUPLQNAME	All	Duplicate queue name.
PAMS__FAIL	All	Operation failed.
PAMS__NOACCESS	All	No access to the resource. The address of the specified name is either 0 or it is in another group.
PAMS__NOOBJECT	All	For a global reference, this error can be caused by a bad default pathname in the group configuration file.
PAMS__NOTBOUND	All	The queue name is not bound to an address.
PAMS__NOTDCL	All	Not attached to BEA MessageQ.
PAMS__PAMSDOWN	All	The specified BEA MessageQ group is not running.
PAMS__SUCCESS	All	Indicates successful completion.
PAMS__TIMEOUT	All	The timeout period specified has expired. In this situation, BEA 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.
PAMS__UNBINDING	All	The bind cannot be done because BEA MessageQ is still in the process of has unbinding the old binding.

See Also

• pams_attach_q

• pams_locate_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

Table 8-6

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

Table 8-7

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Argument list is invalid.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.
SS$_EXQUOTA	OpenVMS	Process has exceeded its asynchronous system trap (AST) quota.

See Also

• pams_cancel_select

• pams_get_msga

• pams_set_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

Table 8-8

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

Table 8-9

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of call arguments.
PAMS__BADPARAM	UNIX Windows NT	The value of the selection index is null.
PAMS__BADSELIDX	All	Invalid or undefined selective receive index.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_get_msga

• pams_set_select

pams_cancel_timer

Deletes the BEA 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

Table 8-10

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

Table 8-11

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments.
PAMS__BADPARAM	All	The timer_id argument was specified as null.
PAMS__INVALIDNUM	All	The application has supplied an invalid value for the timer_id.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	The application has not attached to a queue.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__RESRCFAIL	All	Insufficient resources to complete the operation.
PAMS__SUCCESS	All	Indicates successful completion.

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 BEA MessageQ message recovery system.

Syntax

int32 pams_close_jrn ( jrn_handle ) 

Arguments

Table 8-12

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

Table 8-13

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments.
PAMS__INVJH	OpenVMS	The application has supplied an invalid journal handle.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.

See Also

• pams_confirm_msg

• pams_open_jrn

• pams_read_jrn

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.

BEA 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

Table 8-14

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 BEA 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:

Symbol	Description
PDEL_DEFAULT_JRN	Enables writing the message to the PCJ file if the journaling is configured in the group initialization file.
PDEL_FORCE_JRN	Enables writing to the PCJ only if journaling is configured. It is not possible to write messages to the PCJ on UNIX and Windows NT systems if a path was not defined for the PCJ in the group configuration information.
PDEL_NO_JRN	Disables journaling regardless of whether journaling is configured.

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

Table 8-15

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments.
PAMS__BADPARAM	All	Bad argument value.
PAMS__BADSEQ	All	Journal sequence number is not known to the Message Recovery Services (MRS).
PAMS__DQF_DEVICE_FAIL	OpenVMS	I/O error writing to the destination queue file for the target queue.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOMRS	All	MRS is not available.
PAMS__NOTDCL	All	Process is not attached to BEA MessageQ.
PAMS__NOTJRN	All	Message is not written to the PCJ file.
PAMS__NOTSUPPORTED	OpenVMS	Attached to the dead letter queue.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__RESRCFAIL	OpenVMS	BEA MessageQ resources exhausted.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_get_msg

• pams_get_msga

• pams_get_msgw

• pams_put_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_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 BEA MessageQ message queuing bus.

Syntax

int32 pams_detach_q ( q, detach_opt_list, detach_opt_len,
			 msgs_flushed ) 

Arguments

Table 8-16

Argument	Data Type	Mechanism	Prototype	Access
q	q_address	reference	q_address *	passed
detach_opt_list	int32 array	reference	int32 *	passed
detach_opt_len	int32	reference	int32 *	passed
msg_flushed	int32	reference	int32 *	returned

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.

• 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, BEA 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.

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

• Detaching from the message queuing bus by calling pams_exit

• Exiting your application

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

Table 8-17

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments.
PAMS__BADPARAM	All	Invalid detach_opt_list.
PAMS__DETACHED	All	Process has detached from BEA MessageQ.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	Not attached to BEA MessageQ.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__PNUMNOEXIST	All	Invalid queue address or queue not owned by process.
PAMS__SUCCESS	All	Queue successfully detached.

See Also

• pams_attach_q

• pams_exit

pams_exit

Terminates all attachments between the application and the BEA 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.

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

• Detaching from the message queuing bus by calling pams_exit

• Exiting your application

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

Table 8-18

Return Code	Platform	Description
PAMS__NETERROR	OpenVMS Client	Network error resulted in a communications link abort.
PAMS__NOTDCL	OpenVMS	Not attached to BEA MessageQ.
PAMS__PREVCALLBUSY	OpenVMSClient	Previous call to CLS has not been completed.
PAMS__PNUMNOEXIST	OpenVMS	Invalid queue address or queue not owned by process.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_attach_q

• pams_detach_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_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 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 BEA MessageQ Messages topic for more information on working with FML32 buffers 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

Table 8-19

Argument	Data Type	Mechanism	Prototype	Access
msg_area	char	reference	char *	returned
priority	char	reference	char *	passed
source	q_address	reference	q_address *	returned
class	short	reference	short *	returned
type	short	reference	short *	returned
msg_area_len	short	reference	short *	passed
len_data	short	reference	short*	returned
[sel_filter]	int32	reference	int32 *	passed
[psb]	struct psb	reference	struct psb *	returned
[show_buffer]	struct show_buffer	reference	struct show_buffer *	returned
[show_buffer_len]	int32	reference	int32 *	passed
[large_area_len]	int32	reference	int32 *	passed/ returned
[large_size]	int32	reference	int32 *	returned
[nullarg_3]	char	reference	char*	passed

Argument Definitions

msg_area

For static buffer-style messaging, receives the address of a memory region where BEA 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.

priority

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.

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. BEA 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 BEA 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_TUXEDO	31001
MSG_CLAS_TUXEDO_TPSUCCESS	31002
MSG_CLAS_TUXEDO_TPFAIL	31003
MSG_CLAS_XXX	30000 through 32767 (except 31001-31003)

type

Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. BEA 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.

BEA 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 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.

len_data

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.

sel_filter

Supplies the criterion to enable the application to selectively retrieve messages. The argument contains one of the following selection criteria:

• Default selection

• Selection by message queue

• Message attributes

• Message source

• Compound selection using the pams_set_select function

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:

Table 8-20

Select Mode	Select Variable	Mode Description
PSEL_PQ	0	Enables the application to read from the primary queue (PQ) only. The select variable must equal 0.
PSEL_AQ	Alternate queue number	Enables an application to read from an alternate queue (AQ) only. The queue type can be a secondary queue (SQ).
PSEL_PQ_AQ	Alternate queue number	Attempts to selectively retrieve from a primary queue and then from an alternate queue.
PSEL_AQ_PQ	Alternate queue number	Attempts to selectively retrieve from an alternate queue and then from a primary queue.
PSEL_TQ_PQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), and then from a primary queue.
PSEL_TQ_PQ_AQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), then from a primary queue, and finally from an alternate queue.
PSEL_UCB	0	Retrieves messages only from the user callback queues (UCB).

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:

Table 8-21

Select Mode	Select Variable	Mode Description
PSEL_PQ_TYPE	Type	Selects the first pending message from the primary queue that matches the type value in the select variable word.
PSEL_PQ_CLASS	Class	Selects the first pending message from the primary queue that matches the class value in the select variable word.
PSEL_PQ_PRI	PSEL_PRI_ANY PSEL_PRI_P0 PSEL_PRI_P1 integer value between 0 and 99	Selects the first pending message with a priority equal to an integer between 0 and 99 inclusive (or equal to the select variable value) from within the primary queue. Specifying the direct integer value is the preferred method of selected messages by priority. 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.

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:

sel_filter Argument	Action
Zero or not specified	No filtering of any messages. All messages can be retrieved.
Source q_address	Only those messages that have a matching q_address are retrieved.
Selection mask created with pams_set_select	Only messages that exactly match the specified selection mask are retrieved.

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:

Table 8-22

Low Byte	High Byte	Contents	Description
0	1	Type	PSB type
2	3	Call Dependent	Currently not used.
4	7	PSB Delivery Status	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.
8	15	Message Sequence Number	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.
16	19	PSB UMA Status	This field is not used for the pams_get_msg function.
20	23	Function Return Status	This field is not used for the pams_get_msg function.
24	31	Not Used	Not used.

show_buffer

Receives additional information which BEA MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:

Table 8-23

Longword	Contents	Description
0	Version	The version of the show_buffer structure. Valid values are as follows: 10 = Version 1.0 20 = Version 2.0 50 = Version 5.0
1	Transfer Status	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.
2	Transfer Size	The number of bytes transferred to the application buffer.
3	Flags	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: PSYM_SHOW_VERSION PSYM_SHOW_STATUS PSYM_SHOW_SIZE PSYM_SHOW_FLAGS PSYM_SHOW_TARGET PSYM_SHOW_ORIGINAL_TARGET PSYM_SHOW_SOURCE PSYM_SHOW_ORIGINAL_SOURCE PSYM_SHOW_DELIVERY PSYM_SHOW_PRIORITY PSYM_SHOW_ENDIAN PSYM_SHOW_CORRELATION_ID
4	Not Used	Fills out the Control Section to its maximum 24 bytes.
5	Not Used	Fills out the Control Section to its maximum 24 bytes.
6	Not Used	Fills out the Control Section to its maximum 24 bytes.
7	Not Used	Fills out the Control Section to its maximum 24 bytes.
8	Not Used	Fills out the Control Section to its maximum 24 bytes.
9	Not Used	Fills out the Control Section to its maximum 24 bytes.
10	Target	The q_address of the latest message target.
11	Original Target	The q_address of the original message target.
12	Source	The q_address of the latest message source.
13	Original Source	The q_address of the original message.
14	Delivery Mode	The delivery mode that was used to queue the message. This is not necessarily the delivery mode used to generate the message.
15	Priority	The priority used to queue the message.
16	Endian	The byte ordering or encoding schemes of 2- and 4-byte integers. The possible settings are as follows: PSYM_UNKNOWN PSYM_VAX_BYTE_ORDER or PSYM_LITTLE_ENDIAN PSYM_NETWORK_BYTE_ORDER or PSYM_BIG_ENDIAN PSYM_FML
17	Correlation ID	The 32 byte correlation ID associated with the message.

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

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.

large_size

Returns the actual size of the large message, double buffer message, or FML32 message written to the message buffer.

nullarg_3

Reserved for BEA MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.

Return Values

Table 8-24

Return Code	Platform	Description
PAMS__AREATOSMALL	All	Received message is larger than the user's message area.
PAMS__BADARGLIST	All	Wrong number of call arguments have been passed to this function.
PAMS__BADHANDLE	All	Invalid message handle.
PAMS__BADPARAM	All	Bad argument value.
PAMS__BADPRIORITY	All	Invalid priority value used for receive.
PAMS__BADSELIDX	All	Invalid or undefined selective receive index.
PAMS__BUFFEROVF	UNIX Windows NT	The size of the show_buffer specified is too small.
PAMS__EXHAUSTBLKS	OpenVMS	No more message blocks available.
PAMS__FMLERROR	All	Problem detected with internal format of FML message; this can be an error in processing or data corruption.
PAMS__INSQUEFAIL	All	Failed to properly queue a message buffer.
PAMS__MSGTOSMALL	All	The msg_area_len argument must be positive or zero.
PAMS__MSGUNDEL	All	Message returned is undeliverable.
PAMS__NEED_BUFFER_PTR	UNIX Windows NT	FML32 buffer received but msg_area_len argument not set to PSYM_MSG_BUFFER_PTR.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOACCESS	All	No access to resource.
PAMS__NOACL	All	Queue access control file could not be found.
PAMS__NOMEMORY	OpenVMS	Insuffucient memory resources to reallocate buffer pointer.
PAMS__NOMOREMSG	All	No messages available.
PAMS__NOMRQRESRC	All	Insufficient multireader queue resources to allow access.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__NOTSUPPORTED	UNIX Windows NT	The supplied delivery mode is not -supported.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__QUECORRUPT	OpenVMS	Message buffer queue corrupt.
PAMS__REMQUEFAIL	All	Failed to properly read from a message buffer.
PAMS__STALE	All	Resource is no longer valid and must be freed by the user.
PAMS__STOPPED	All	The requested queue has been stopped.
PAMS__SUCCESS	All	Indicates successful completion.

PBS Delivery Status

Table 8-25

PSB Delivery Status	Platform	Description
PAMS__CONFIRMREQ	All	Confirmation required for this message.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__POSSDUPL	All	Message is a possible duplicate.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_get_msga

• pams_get_msgw

• pams_put_msg

• pams_set_select

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

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 BEA MessageQ recovery system.

See the Sending and Receiving BEA MessageQ Messages topic for more information on working with FML32 buffers 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

Table 8-26

Argument	Data Type	Mechanism	Prototype	Access
msg_area	char	reference	char *	returned
priority	char	reference	char *	passed
source	q_address	reference	q_address *	returned
class	short	reference	short *	returned
type	short	reference	short *	returned
msg_area_len	short	reference	short *	passed
len_data	short	reference	short *	returned
[sel_filter]	int32	reference	int32 *	passed
[psb]	struct psb	reference	struct psb *	returned
[show_buffer]	struct show_buffer	reference	struct show_buffer *	returned
[show_buffer_len]	int32	reference	int32 *	passed
[large_area_len]	int32	reference	int32 *	passed/ returned
[large_size	int32	reference	int32 *	returned
[actrtn]	int32	value	int32 *	passed
[actparm]	int32	reference	int32 *	passed
[flag_id]	int32	reference	int32 *	passed
[nullarg_3]	char	reference	char *	passed

Argument Definitions

msg_area

For static buffer-style messaging, receives the address of a memory region where BEA 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.)

priority

Supplies the priority level for selective message reception. Priority ranges from 0 (lowest priority) to 99 (highest 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. BEA 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 BEA 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_TUXEDO	31001
MSG_CLAS_TUXEDO_TPSUCCESS	31002
MSG_CLAS_TUXEDO_TPFAIL	31003
MSG_CLAS_XXX	30000 through 32767 (except 31001-31003)

type

Receives the type code of the retrieved message. The type is specified in the pams_put_msg function. BEA 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.

BEA 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.

• 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.

len_data

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.

sel_filter

Supplies the criteria enabling the application to selectively retrieve messages. The argument contains one of the following selection criteria:

• Default selection

• Selection by message queue

• Message attributes

• Message source

• Compound selection using the pams_set_select function

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:

Table 8-27

Select Mode	Select Variable	Mode Description
PSEL_PQ	0	Enables the application to read from the primary queue (PQ) only. The select variable must equal 0.
PSEL_AQ	Alternate queue number	Enables an application to read from an alternate queue (AQ) only. The queue type can be a secondary queue (SQ).
PSEL_PQ_AQ	Alternate queue number	Attempts to selectively retrieve from a primary queue and then from an alternate queue.
PSEL_AQ_PQ	Alternate queue number	Attempts to selectively retrieve from an alternate queue and then from a primary queue.
PSEL_TQ_PQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), and then from a primary queue.
PSEL_TQ_PQ_AQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), then from a primary queue, and finally from an alternate queue.
PSEL_UCB	0	Retrieves messages only from the user callback queues (UCB).

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:

Table 8-28

Select Mode	Select Variable	Mode Description
PSEL_PQ_TYPE	Type	Selects the first pending message from the primary queue that matches the type value in the select variable word.
PSEL_PQ_CLASS	Class	Selects the first pending message from the primary queue that matches the class value in the select variable word.
PSEL_PQ_PRI	PSEL_PRI_ANY PSEL_PRI_P0 PSEL_PRI_P1 integer value between 0 and 99	Selects the first pending message with a priority equal to an integer between 0 and 99 inclusive (or equal to the select variable value) from within the primary queue. Specifying the direct integer value is the preferred method of selected messages by priority. 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.

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:

sel_filter Argument	Action
Zero or not specified	No filtering of any messages. All messages can be retrieved.
Source q_address	Only those messages that have a matching q_address are retrieved.
Selection mask created with pams_set_select	Only messages that exactly match the specified selection mask are retrieved.

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:

Table 8-29

Low Byte	High Byte	Contents	Description
0	1	Type	PSB type
2	3	Call Dependent	Currently not used.
4	7	PSB Delivery Status	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.
8	15	Message Sequence Number	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.
16	19	PSB UMA Status	This field is not used with the pams_get_msga function.
20	23	Function Return Status	This field is not used with the pams_get_msga function.
24	31	Not Used	Not used.

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 BEA MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:

Table 8-30

Longword	Contents	Description
0	Version	The version of the show_buffer structure. Valid values are as follows: 10 = Version 1.0 20 = Version 2.0 50 = Version 5.0
1	Transfer Status	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.
2	Transfer Size	The number of bytes transferred to the application buffer.
3	Flags	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: PSYM_SHOW_VERSION PSYM_SHOW_STATUS PSYM_SHOW_SIZE PSYM_SHOW_FLAGS PSYM_SHOW_TARGET PSYM_SHOW_ORIGINAL_TARGET PSYM_SHOW_SOURCE PSYM_SHOW_ORIGINAL_SOURCE PSYM_SHOW_DELIVERY PSYM_SHOW_PRIORITY PSYM_SHOW_ENDIAN PSYM_SHOW_CORRELATION_ID
4	Not Used	Fills out the Control Section to its maximum 40 bytes.
5	Not Used	Fills out the Control Section to its maximum 40 bytes.
6	Not Used	Fills out the Control Section to its maximum 40 bytes.
7	Not Used	Fills out the Control Section to its maximum 40 bytes.
8	Not Used	Fills out the Control Section to its maximum 40 bytes.
9	Not Used	Fills out the Control Section to its maximum 40 bytes.
10	Target	The q_address of the latest message target.
11	Original Target	The q_address of the original message target.
12	Source	The q_address of the latest message source.
13	Original Source	The q_address of the original message.
14	Delivery Mode	The delivery mode that was used to queue the message. This is not necessarily the delivery mode used to generate the message.
15	Priority	The priority used to queue the message.
16	Endian	The byte ordering or encoding schemes of 2- and 4-byte integers. The possible settings are as follows: PSYM_UNKNOWN PSYM_VAX_BYTE_ORDER or PSYM_LITTLE_ENDIAN PSYM_NETWORK_BYTE_ORDER or PSYM_BIG_ENDIAN PSYM_FML
17	Correlation ID	The 32 byte correlation ID associated with the message.

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 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).

large_size

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.)

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 BEA 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. An 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.

• Ensure that the addresses of any fields that are filled in asynchronously are valid throughout the period that the AST is posted. A common error in using ASTs is to post an AST request that fills in fields on the stack and becomes invalid as soon as the caller returns.

• Data may be passed between AST routines and mainline by the following mechanisms:

  • BEA MessageQ messages.

  • An event queue managed by interlocked queuing instructions.

  • Shared data fields between mainline and the AST routines such that access to the data is clear. The use of a context area for each AST request can accomplish this.

• 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

Table 8-31

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Wrong number of call arguments have been passed to this function.
PAMS__BADPARAM	OpenVMS	Bad argument value.
PAMS__BADPRIORITY	OpenVMS	Invalid priority value used for receive.
PAMS__BADSELIDX	OpenVMS	Invalid or undefined selective receive index.
PAMS__BADHANDLE	OpenVMS	Invalid message handle.
PAMS__MSGTOSMALL	OpenVMS	The msg_area_len argument must be positive or zero.
PAMS__NOACCESS	OpenVMS	No access to the queue.
PAMS__NOACL	OpenVMS	No access to resource. The ACL check failed.
PAMS__NOMEMORY	OpenVMS	Insuffucient memory resources to reallocate buffer pointer.
PAMS__NOTDCL	OpenVMS	The application has not been attached to BEA MessageQ.
PAMS__NOTSUPPORTED	OpenVMS	Feature not supported or available.
PAMS__RESRCFAIL	OpenVMS	Failed to allocate a resource.
PAMS__STALE	OpenVMS	Resource is no longer valid and must be freed by the user.
PAMS__STOPPED	OpenVMS	The requested queue has been stopped.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.

PSB Delivery Status

Table 8-32

PSB Delivery Status	Platform	Description
PAMS__CONFIRMREQ	OpenVMS	Confirmation required for this message.
PAMS__POSSDUPL	OpenVMS	Message is a possible duplicate.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.

See Also

• pams_cancel_get

• pams_get_msg

• pams_get_msgw

• pams_put_msg

• pams_set_select

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 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 BEA MessageQ recovery system.

See the Sending and Receiving BEA MessageQ Messages topic for more information on working with FML32 buffers 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

Table 8-33

Argument	Data Type	Mechanism	Prototype	Access
msg_area	char	reference	char *	returned
priority	char	reference	char *	passed
source	q_address	reference	q_address *	returned
class	short	reference	short *	returned
type	short	reference	short *	returned
msg_area_len	short	reference	short *	passed
len_data	short	reference	short *	returned
timeout	int32	reference	int32 *	passed
[sel_filter]	int32	reference	int32 *	passed
[psb]	struct psb	reference	struct psb *	returned
[show_buffer]	struct show_buffer	reference	struct show_buffer *	returned
[show_buffer_len]	int32	reference	int32 *	passed
[large_area_len]	int32	reference	int32 *	passed/ returned
[large_size]	int32	reference	int32 *	returned
[nullarg_3]	char	reference	char *	passed

Argument Definitions

msg_area

For buffer-style messaging, receives the address of a memory region where BEA MessageQ writes the contents of the retrieved message. For FML-style messaging or when using double ponters, receives a pointer to the address of the message being retrieved.

priority

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.

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. BEA 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 BEA 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_TUXEDO	31001
MSG_CLAS_TUXEDO_TPSUCCESS	31002
MSG_CLAS_TUXEDO_TPFAIL	31003
MSG_CLAS_XXX	30000 through 32767 (except 31001-31003)

type

Receives the type code of the retrieved message. The type is specified in the arguments of the pams_put_msg function. BEA 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.

BEA 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.

• 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.

len_data

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.

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

• Selection by message queue

• Message attributes

• Message source

• Compound selection using the pams_set_select function

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:

Table 8-34

Select Mode	Select Variable	Mode Description
PSEL_PQ	0	Enables the application to read from the primary queue (PQ) only. The select variable must equal 0.
PSEL_AQ	Alternate queue number	Enables an application to read from an alternate queue (AQ) only. The queue type can be a secondary queue (SQ).
PSEL_PQ_AQ	Alternate queue number	Attempts to selectively retrieve from a primary queue and then from an alternate queue.
PSEL_AQ_PQ	Alternate queue number	Attempts to selectively retrieve from an alternate queue and then from a primary queue.
PSEL_TQ_PQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), and then from a primary queue.
PSEL_TQ_PQ_AQ	Alternate queue number	Attempts to selectively retrieve messages from a timer queue (TQ), then from a primary queue, and finally from an alternate queue.
PSEL_UCB	0	Retrieves messages only from the user callback queues (UCB).

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:

Table 8-35

Select Mode	Select Variable	Mode Description
PSEL_PQ_TYPE	Type	Selects the first pending message from the primary queue that matches the type value in the select variable word.
PSEL_PQ_CLASS	Class	Selects the first pending message from the primary queue that matches the class value in the select variable word.
PSEL_PQ_PRI	PSEL_PRI_ANY PSEL_PRI_P0 PSEL_PRI_P1 integer value between 0 and 99	Selects the first pending message with a priority equal to an integer between 0 and 99 inclusive (or equal to the select variable value) from within the primary queue. Specifying the direct integer value is the preferred method of selected messages by priority. 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.

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:

sel_filter Argument	Action
Zero or not specified	No filtering of any messages. All messages can be -retrieved.
Source q_address	Only those messages that have a matching q_address are retrieved.
Selection mask created with pams_set_select	Only messages that exactly match the specified selection mask are retrieved.

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:

Table 8-36

Low Byte	High Byte	Contents	Description
0	1	Type	PSB type
2	3	Call Dependent	Currently not used.
4	7	PSB Delivery Status	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.
8	15	Message Sequence Number	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.
16	19	PSB UMA Status	The completion status of the undeliverable message action (UMA). The PSB UMA status indicates if the UMA was not executed or applicable.
20	23	Function Return Status	After a BEA MessageQ function completes execution, BEA MessageQ software writes the return value to this field.
24	31	Not Used	Not used.

show_buffer

Receives additional information which BEA MessageQ extracts from the message header. The structure of the show_buffer argument is as follows:

Table 8-37

Longword	Contents	Description
0	Version	The version of the show_buffer structure. Valid values are as follows: 10 = Version 1.0 20 = Version 2.0
1	Transfer Status	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.
2	Transfer Size	The number of bytes transferred to the application buffer.
3	Flags	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: PSYM_SHOW_VERSION PSYM_SHOW_STATUS PSYM_SHOW_SIZE PSYM_SHOW_FLAGS PSYM_SHOW_TARGET PSYM_SHOW_ORIGINAL_TARGET PSYM_SHOW_SOURCE PSYM_SHOW_ORIGINAL_SOURCE PSYM_SHOW_DELIVERY PSYM_SHOW_PRIORITY PSYM_SHOW_ENDIAN PSYM_SHOW_CORRELATION_ID
4	Not Used	Fills out the Control Section to its maximum 24 bytes.
5	Not Used	Fills out the Control Section to its maximum 24 bytes.
6	Not Used	Fills out the Control Section to its maximum 24 bytes.
7	Not Used	Fills out the Control Section to its maximum 24 bytes.
8	Not Used	Fills out the Control Section to its maximum 24 bytes.
9	Not Used	Fills out the Control Section to its maximum 24 bytes.
10	Target	The q_address of the latest message target.
11	Original Target	The q_address of the original message target.
12	Source	The q_address of the latest message source.
13	Original Source	The q_address of the original message.
14	Delivery Mode	The delivery mode that was used to queue the message.
15	Priority	The priority used to queue the message.
16	Endian	The byte ordering or encoding schemes of 2- and 4-byte integers. The possible settings are as follows: PSYM_UNKNOWN PSYM_VAX_BYTE_ORDER or PSYM_LITTLE_ENDIAN PSYM_NETWORK_BYTE_ORDER or PSYM_BIG_ENDIAN PSYM_FML
17	Correlation ID	The 32 byte correlation ID associated with the message.

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. 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.

large_size

Returns the actual size of the large message, double buffer message, or FML message written to the message buffer.

nullarg_3

Reserved for BEA MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.

Return Codes

Table 8-38

Return Code	Platform	Description
PAMS__AREATOSMALL	All	Received message is larger than the application message area.
PAMS__BADARGLIST	All	Wrong number of call arguments have been passed to this function.
PAMS__BADHANDLE	All	Invalid message handle.
PAMS__BADPARAM	All	Bad argument value.
PAMS__BADPRIORITY	All	Invalid priority value used for receive.
PAMS__BADSELIDX	All	Invalid or undefined selective receive index.
PAMS__BADTIME	OpenVMS	An invalid time was specified.
PAMS__BUFFEROVF	UNIX Windows NT	The size specified for the show_buffer argument is too small.
PAMS__EXHAUSTBLKS	OpenVMS	No more message blocks available.
PAMS__FMLERROR	All	Problem detected with internal format of FML message; this can be an error in processing or data corruption.
PAMS__INSQUEFAIL	All	Failed to properly queue a message buffer.
PAMS__MSGTOSMALL	All	The msg_area_len argument must be positive or zero.
PAMS__MSGUNDEL	All	Message returned is undeliverable.
PAMS__NEED_BUFFER_PTR	UNIX Windows NT	FML32 buffer received but msg_area_len argument not set to PSYM_MSG_BUFFER_PTR.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOACCESS	All	No access to resource. ACL check failed.
PAMS__NOACL	All	The queue access control file could not be found.
PAMS__NOMEMORY	OpenVMS	Insuffucient memory resources to reallocate buffer pointer.
PAMS__NOMRQRESRC	All	Insufficient multireader queue resources to allow access.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__NOTSUPPORTED	UNIX Windows NT	Specified delivery mode is not supported.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__QUECORRUPT	OpenVMS	Message buffer queue corrupt.
PAMS__REMQUEFAIL	All	Failed to properly read a message buffer.
PAMS__STALE	All	Resource is no longer valid and must be freed by the user.
PAMS__STOPPED	All	The requested queue has been stopped.
PAMS__SUCCESS	All	Successful completion.
PAMS__TIMEOUT	All	Timeout period has expired.
PAMS__CONFIRMREQ	All	Confirmation required for this -message.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__POSSDUPL	All	Message is a possible duplicate.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_get_msga

• pams_put_msg

• pams_set_select

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_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

Table 8-39

Argument	Data Type	Mechanism	Prototype	Access
q_name	char	reference	char *	passed
q_name_len	int32	reference	int32 *	passed
q_address	q_address	reference	q_address *	returned
[wait_mode]	int32	reference	int32 *	passed
[req_id]	int32	reference	int32 *	passed
[resp_q]	int32	reference	int32 *	passed
[name_space_list]	int32 array	reference	int32 array *	passed
[name_space_list_len]	int32	reference	int32 *	passed
[timeout]	int32	reference	int32 *	passed

Argument Definitions

q_name

Supplies the queue name or queue alias whose queue address is requested. The procedure that BEA 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 BEA MessageQ environments, the maximum string length is 31.

q_address

Receives the queue address assigned by BEA 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.

• 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.

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.)

• 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 (.), BEA MessageQ treats it as a pathname. Otherwise, BEA 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 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, BEA 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

Table 8-40

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Wrong number of call arguments.
PAMS__BADNAME	UNIX Windows NT	The queue name contains illegal characters.
PAMS__BADPARAM	All	Invalid argument in the argument list.
PAMS__BADRESPQ	All	Invalid response queue specified.
PAMS__BOUND	All	Queue name in use.
PAMS__BUSNOTSET	UNIX Windows NT	DMQ_BUS_ID environment variable not set.
PAMS__GROUPNOTSET	UNIX Windows NT	DMQ_GROUP_ID environment variable not set.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOACCESS	All	The address of the specified name is either 0 or is in another group.
PAMS__NOOBJECT	All	Could not locate queue name.
PAMS__PAMSDOWN	All	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__RESRCFAIL	All	Failed to allocate resources.
PAMS__SUCCESS	All	Successful completion of an action.
PAMS__TIMEOUT	All	The timeout period specified has expired.
PAMS__UNBINDING	All	Queue requested is in the process of unbinding from a pams_bind_q request.

See Also

• pams_attach_q

• pams_exit

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_open_jrn

Opens the selected message recovery journal. The BEA MessageQ dead letter journal (DLJ) stores messages designated as recoverable that could not be delivered by the recovery system. The BEA MessageQ postconfirmation journal (PCJ) stores recoverable messages that were successfully delivered. See the Using Recoverable Messaging topic for a description of BEA MessageQ message recovery services.

Syntax

int32 pams_open_jrn ( jrn_filespec, jrn_filename_len, jrn_handle )

Arguments

Table 8-41

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

Table 8-42

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of call arguments.
PAMS__NOMEMORY	OpenVMS	Insufficient virtual memory.
PAMS__NOSUCHPCJ	OpenVMS	Error occured when attempting to open the specified journal file.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.

See Also

• pams_close_jrn

• pams_confirm_msg

• pams_put_msg

• pams_read_jrn

pams_put_msg

Sends a message to a target queue using a set of standard BEA 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.

Syntax

int32 pams_put_msg ( msg_area, priority, target, class, type,
		delivery, msg_size, [timeout], [psb], [uma],
		[resp_q], [large_size], [correlation_id],
		[nullarg_3] )

Arguments

Table 8-43

Argument	Data Type	Mechanism	Prototype	Access
msg_area	char	reference	char *	passed
priority	char	reference	char *	passed
target	q_address	reference	q_address *	passed
class	short	reference	short *	passed
type	short	reference	short *	passed
delivery	char	reference	char *	passed
msg_size	short	reference	short *	passed
[timeout]	int32	reference	int32 *	passed
[psb]	struct psb	reference	struct psb *	returned
[uma]	char	reference	char *	passed
[resp_q]	q_address	reference	q_address *	passed
large_size	int32	reference	int32 *	passed
[correlation_id]	char	reference	char *	passed
[nullarg_3]	char	reference	char *	passed

Argument Definitions

msg_area

For buffer-style messaging, supplies the address of a memory region or a message pointer containing the message to be delivered to the target queue of the receiver program. For FML-style messaging, supplies the message pointer that points to an FML32 buffer containing the message.

priority

Supplies the priority level for selective message reception. Priority ranges from 0 (lowest priority) to 99 (highest 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. BEA 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 BEA 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_TUXEDO	31001
MSG_CLAS_TUXEDO_TPSUCCESS	31002
MSG_CLAS_TUXEDO_TPFAIL	31003
MSG_CLAS_XXX	30000 through 32767 (except 31001-31003)

type

Supplies the type code for the message being sent. BEA 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.

BEA 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:

• WF-Wait for completion

• AK-Asynchronous acknowledgment

• NN-No notification

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. 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.

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_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.

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:

Table 8-44

Low Byte	High Byte	Contents	Description
1	0	Type	PSB type.
3	2	Call Dependent	Currently not used.
7	4	PSB Delivery Status	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.
15	8	Message Sequence Number	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.
19	16	PSB UMA Status	The completion status of the undeliverable message action (UMA). The PSB UMA status indicates if the UMA was not executed or applicable.
23	20	Function Return Status	After a BEA MessageQ function completes execution, BEA MessageQ software writes the return value to this field.
31	24	Not Used	Not used.

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.

correlation_id

Supplies the correlation id, a user-defined identifier stored as a 32-byte value

nullarg_3

Reserved for BEA MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.

Return Values

Table 8-45

Return Code	Platform	Description
PAMS__BADARGLIST	All	Wrong number of call arguments have been passed to this function.
PAMS__BADDELIVERY	All	Invalid delivery mode.
PAMS__BADHANDLE	All	Invalid message handle.
PAMS__BADPARAM	UNIX Windows NT OpenVMS	Attempt to use cross-group connection when cross-group communication is disabled. On OpenVMS systems, invalid NULL call argument.
PAMS__BADPRIORITY	All	Invalid priority value on send operation.
PAMS__BADPROCNUM	UNIX Windows NT	Invalid target queue address specified.
PAMS__BADRESPQ	All	Response queue not owned by process.
PAMS__BADTIME	OpenVMS	Invalid time specified.
PAMS__BADUMA	All	Undeliverable message action (UMA) is invalid.
PAMS__EXCEEDQUOTA	All	Target process quota exceeded; message was not sent.
PAMS__EXHAUSTBLKS	OpenVMS	No more message blocks available.
PAMS__FMLERROR	All	Problem detected with internal format of FML message; this can be an error in processing or data corruption.
PAMS__LINK_UP	OpenVMS	MRS has reestablished link.
PAMS__MSGTOBIG	All	Message exceeded the size of the largest link list section (LLS).
PAMS__MSGTOSMALL	OpenVMS	Invalid (negative) msg_size specified in the argument list.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOMRS	OpenVMS	MRS is not available.
PAMS__NOTACTIVE	All	Target process is not currently active; message not sent.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__NOTFLD	All	The buffer supplied is not an FML32 buffer.
PAMS__NOTSUPPORTED	All	The combination of delivery mode and uma selected is not supported.
PAMS__PNUMNOEXIST	OpenVMS	Target queue number does not exist.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__REMQUEFAIL	All	Failed to properly dequeue a message buffer.
PAMS__STOPPED	All	The requested queue has been stopped.
PAMS__SUCCESS	All	Successful completion.
PAMS__TIMEOUT	All	Timeout period has expired.
PAMS__UNATTACHEDQ	All	Message successfully sent to unattached queue.
PAMS__WAKEFAIL	OpenVMS	Failed to wake up the target process.

Table 8-46

UMA Status	Platform	Description
PAMS__DISC_FAILED	All	Message not recoverable in destination queue file (DQF); undeliverable message action (UMA) was PDEL_UMA_DISC; message could not be discarded.
PAMS__DISC_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_DISC; message -discarded.
PAMS__DISCL_FAILED	All	Message not recoverable in DQF; UMA was PDEL_UMA_DISC; recoverability failure could not be logged or message could not be discarded.
PAMS__DISCL_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_DISC; message discarded after logging recoverability -failure.
PAMS__DLJ_FAILED	All	Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; dead letter journal (DLJ) write operation failed.
PAMS__DLJ_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; message written to the DLJ.
PAMS__DLQ_FAILED	All	Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message could not be queued to the DLQ.
PAMS__DLQ_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message queued to the DLQ.
PAMS__NO_UMA	All	Message is recoverable; UMA not -executed.
PAMS__RTS_FAILED	All	Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message could not be returned to sender.
PAMS__RTS_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message returned to sender.
PAMS__SAF_FAILED	All	Message not recoverable in DQF; UMA was PDEL_UMA_SAF; store and forward (SAF) write operation failed.
PAMS__SAF_SUCCESS	All	Message not recoverable in DQF; UMA was PDEL_UMA_SAF; message recoverable from SAF file.
PAMS__UMA_NA	All	UMA not applicable.

See Also

• pams_get_msg

• pams_get_msga

• pams_get_msgw

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 BEA 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 BEA 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

Table 8-47

Argument	Data Type	Mechanism	Prototype	Access
jrn_handle	int32	reference	int32 *	passed
msg_area	char	reference	char *	returned
priority	char	reference	char *	returned
source	q_address	reference	q_address *	returned
class	short	reference	short *	returned
type	short	reference	short *	returned
msg_area_len	short	reference	short *	returned
len_data	short	reference	short*	returned
target	q_address	reference	q_address *	returned
write_time	unsigned int32	reference	unsigned int32 *	returned
conf_val	int32	reference	int32 *	returned
msg_seq_num	unsigned int32	reference	unsigned int32 *	returned
mrs_status	int32	reference	int32 *	returned
[large_area_len]	int32	reference	int32 *	returned
[large_size]	int32	reference	int32 *	returned
[nullarg_3]	char	reference	char *	returned

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 BEA MessageQ writes.

priority

Supplies the priority level for selective message reception. Priority ranges from 0 (lowest priority) to 99 (highest 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. BEA 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 BEA 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_TUXEDO	31001
MSG_CLAS_TUXEDO_TPSUCCESS	31002
MSG_CLAS_TUXEDO_TPFAIL	31003
MSG_CLAS_XXX	30000 through 32767 (except 31001-31003)

type

Receives the type code of the journaled message. The type is specified in the arguments of the pams_put_msg function. BEA 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.

• 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.

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 BEA 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 BEA MessageQ internal use as a placeholder argument. This argument must be supplied as a null pointer.

Return Values

Table 8-48

Return Code	Platform	Description
PAMS__AREASTOSMALL	OpenVMS	Received message is larger than the user message area.
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments supplied.
PAMS__BADHANDLE	OpenVMS	Invalid message handle.
PAMS__INVJH	OpenVMS	Invalid journal handle.
PAMS__MSGTOBIG	OpenVMS	Message in journal file is larger than GROUP_MAX_MESSAGE_SIZE.
PAMS__NOMEMORY	OpenVMS	Insufficient virtual memory.
PAMS__NOMOREMSG	OpenVMS	No more messages in journal.
PAMS__SUCCESS	OpenVMS	Indicates successful completion.

See Also

• pams_close_jrn

• pams_open_jrn

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 BEA 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

Table 8-49

Argument	Data Type	Mechanism	Prototype	Access
selection_array	selection_array_ component	reference	selection_array_ component *	passed
num_masks	short	reference	short *	passed
index_handle	int32	reference	int32 *	returned

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;
    union {
       pams_correlation_id  correlation_id;
       pams_sequence_number sequence number
    } extended_key
} selection_array_component;

The selection_array_component data structure has the following components:

Component	Description
Queue and Priority	Allows the application to specify the queue number and priority.
Comparison Key 1	Defines the components of the first comparison key used to enable range checking of messages.
Comparison Key 2	Defines the components of the second comparison key used to enable range checking of messages.
Order Key	Contains the information required to provide selection of messages by FIFO, Minimum Value, or Maximum Value.

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:

Table 8-50

Field	Values	Description
Queue	Queue Number	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.
Priority		Specifies the priority, using either an integer between 0 and 99 inclusive or a variable. (Using the direct interger value is the preferred method of specifying priority.) This argument also accepts the following predefined constants which are set by the application.
	PSEL_PRI_ANY	Read priority 1 before reading priority 0 messages.
	PSEL_PRI_P0	Read priority 0 messages only.
	PSEL_PRI_P1	Read priority 1 messages only.

Comparison Keys

The following table specifies the arguments and valid values that can be applied to this part of the Selection_Array_Components structure:

Table 8-51

Field	Values	Description
Offset		Contains a value that specifies where the information to be compared begins inside the message. The following predefined constants apply:
	n	User message byte number (0 relative).
	PSEL_SOURCE	Source address of message.
	PSEL_CLASS	Class of the message.
	PSEL_TYPE	Type of the message.
	PSEL_CORRELATION_ID	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).
	PSEL_SEQUENCE_NUMBER	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		Specifies data type of the key to be compared.
	0	Disable use of key.
	1	Byte (8 bits).
	2	Word (16 bits).
	4	int32 (32 bits).
	PSEL_SEQUENCE_NUMBER_SIZE	8 bytes
	PSEL_CORRELATION_ID_SIZE	32 bytes
Value	n	Contains the value for message field comparison field that is formatted as an integer of 32 bits.
oper		Relational operator comparison.
	PSEL_OPER_EQ	Message field = value.
	PSEL_OPER_NEQ	Message field <> value.
	PSEL_OPER_GTR	Message field > value.
	PSEL_OPER_LT	Message field < value.
	PSEL_OPER_GTRE	Message field > or = value.
	PSEL_OPER_LTE	Message field < or = value.

Order Key

The Order Key part contains variables described in the following table:

Table 8-52

Field	Values	Description
Offset		Byte offset of the message field. The offset variable contains a value that specifies where the information to be compared begins inside the message.
	n	User message byte number (0 relative).
	PSEL_SOURCE	Source address of the message.
	PSEL_CLASS	Class of the message.
	PSEL_TYPE	Type of the message.
	PSEL_CORRELATION_ID	Correlation ID of the message. If this symbol is specified, the Size field must be set to PSEL_CORRELATION_ID_SIZE (or 32 bytes).
	PSEL_SEQUENCE_NUMBER	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		Size of the comparison. The size variable specifies the data type of the key to be compared.
	0	Disable use of key.
	1	Byte.
	2	Word.
	4	int32 (32 bits).
	PSEL_SEQUENCE_NUMBER_SIZE	8 bytes
	PSEL_CORRELATION_ID_SIZE	32 bytes
Order		Order operator. The order variable specifies the sequence in which the select process is to be performed.
	PSEL_ORDER_FIFO	First pending.
	PSEL_ORDER_MIN	Minimum value of all pending.
	PSEL_ORDER_MAX	Maximum value of all pending.

Correlation ID

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.

Sequence Number

The message sequence number is a unique value for each message. The sequence number is stored in the PAMS Status Buffer (PSB). Applications should acquire the message sequence number from the PSB and not modify it in any way.

Note: An application may specify only one of the two keys to select by correlation identifier or by sequnce number.

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 BEA MessageQ implementations offer 16K to 32K index handles.

Return Values

Table 8-53

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments supplied.
PAMS__BADPARAM	All	Bad argument passed in the function call.
PAMS__IDXTBLFULL	All	Selective receive index table is full.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_cancel_get

• pams_cancel_select

• pams_get_msg

• pams_get_msga

• pams_get_msgw

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.

Note: Prior to BEA MessageQ Version 5.0, the valid priority values were 0 and 1. In Version 5.0, the valid range is 0 to 99 (0 being the lowest priority and 99 the highest priority). Keep in mind that timer priorities are always 1 and take this into account when modifying existing programs to take advantage of the expanded priority range. Messages associated with timers have a priority of 1 and are not sent until all messages with priorities from 2 to 99 are read.

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 BEA 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

Table 8-54

Argument	Data Type	Mechanism	Prototype	Access
timer_id	int32	reference	int32 *	passed
timer_format	char	reference	char *	passed
p_timeout	int32	reference	int32 *	passed
s_timeout	unsigned quadword	reference	unsigned quadword *	passed

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.

• 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.

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 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:

struct timeval theTime;
nStatus = pams_set_timer(&timer_id, "S", NULL, (int32 *) &theTime);

Return Values

Table 8-55

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of arguments supplied.
PAMS__BADPARAM	All	Bad argument value.
PAMS__INVALIDNUM	All	Invalid timer number passed to pams_set_timer.
PAMS__INVFORMAT	All	Invalid timer format specified in the call. Should be P or S.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	Process has not been attached to BEA MessageQ.
PAMS__NOTSUPPORTED	UNIX Windows NT	The S timer_format is not supported by BEA MessageQ for UNIX and Windows NT systems.
PAMS__PAMSDOWN	UNIX Windows NT	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__RESRCFAIL	All	Insufficient resources to complete operation.
PAMS__SUCCESS	All	Indicates successful completion.

See Also

• pams_cancel_timer

Example

Set a Timer

This example shows how to use the BEA 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

Table 8-56

Argument	Data Type	Mechanism	Prototype	Access
code	int32	reference	int32 *	passed
severity	int32	reference	int32 *	returned
buffer	char	reference	char *	returned
buflen	int32	reference	int32 *	passed
retlen	int32	reference	int32 *	returned

Argument Definitions

code

Specifies the return value for which you would like the text description and severity level returned.

severity

Receives a code indicating the severity level of the message. Severity levels apply to both success and error messages. They are designed to provide more information about the message being returned. The valid codes returned to this argument are as follows:

0 = warning
1 = success
2 = error
3 = informational
4 = fatal error

buffer

Receives the text description for the return status supplied.

buflen

Specifies the length of the buffer to store the text description returned. A buffer length of 256 bytes is adequate to store the text description for all return status codes. If the user buffer supplied is large enough, the string is zero terminated. The buffer length must be entered as a positive integer. Supplying a negative integer value to this argument causes the function to return a status of PAMS__BADPARAM. If you specify this argument as zero, no text is returned to the buffer and the function returns 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 completion

In 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

Table 8-57

Return Code	Platform	Description
PAMS__BADARGLIST	OpenVMS	Invalid number of call parameters specified.
PAMS__BADPARAM	All	Invalid call parameter specified.
PAMS__FAILED	All	There is no translation for the specified return code.
PAMS__SUCCESS	All	Normal successful completion.
PAMS__TRUNCATED	All	The description was returned but was -truncated.

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

Table 8-58

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

Table 8-59

Return Code	Platform	Description
PAMS__BADARGLIST	UNIX Windows NT	Invalid argument supplied to this function.
PAMS__BADPARAM	OpenVMS	Invalid argument supplied to this function.
PAMS__NETERROR	Clients	Network error resulted in a communications link abort.
PAMS__NOTDCL	All	Process is not attached to BEA MessageQ.
PAMS__RESRCFAIL	All	Insufficient resources to complete operation.
PAMS__PAMSDOWN	All	The specified BEA MessageQ group is not running.
PAMS__PREVCALLBUSY	Clients	Previous call to CLS has not been completed.
PAMS__SUCCESS	All	Successful completion.

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.