Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
MessageQ Doc Home   |   Programmer's Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

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.

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.

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.

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

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.

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.

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.

int32 pams_bind_q (q_addr, q_alias, q_alias_len, [name_space_list],
                  [name_space_list_len], [timeout], [nullarg_1]);

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.

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:

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);
                }

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.

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.

int32 pams_cancel_get ( sel_filter ) 

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.

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.

int32 pams_cancel_select ( index_handle ) 

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.

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.

int32 pams_cancel_timer ( timer_id ) 

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.

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.

int32 pams_close_jrn ( jrn_handle ) 

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.

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.

int32 pams_confirm_msg ( msg_seq_num, confirmation_status, 
		force_j )

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

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.

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.

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.

int32 pams_detach_q ( q, detach_opt_list, detach_opt_len,
			 msgs_flushed ) 

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