Obsolete Functions and Services

 

This appendix contains reference information for obsolete functions and services. These functions and services should not be used in new development. Information is provided referencing features which replace obsolete functions and services.

Obsolete Message-Based Services for Message Broadcasting

This section contains reference information for the following obsolete services for message broadcasting:

• SBS_BS_SEQGAP

• SBS_DEREG

• SBS_DEREG_ACK

• SBS_DEREG_BY_ID

• SBS_REG

• SBS_REG_EZ

• SBS_REG_EZ_REPLY

• SBS_REG_REPLY

SBS_BS_SEQGAP

Note: This service is obsolete. Use SBS_SEQUENCE_GAP instead.

Applications can register to receive notification of sequence gaps in broadcast messages when sending the SBS_REG message to the SBS Server. The registered application receives an SBS_BS_SEQGAP message when there is a gap in sequence of broadcast messages. Sequence gaps can occur when the sender program is broadcasting at a higher rate than the receiver program can handle.

C Message Structure

typedef struct _SBS_BS_SEQGAP {
    int32 num_msgs_missing;
    uint16 sender_group;
    uint16 mot;
    uint16 channel;
    } SBS_BS_SEQGAP;

Message Data Fields

Field	Data Type	Script Format	Description
num_msgs_ missing	int32	DL	Count of lost messages in sequence gap.
sender_group	unsigned word	DW	Group address of sending SBS Server.
mot	unsigned word	DW	Multipoint Outbound Target (MOT) address in which broadcast stream gap occurred.
channel	unsigned word	DW	Source address of MOT; either SBS Server or Ethernet channel.

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	SBS_SERVER	PAMS_SBS_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_BS_SEQGAP	MSG_TYPE_SBS_BS_SEQGAP

See Also

• SBS_REG

• SBS_DEREG

SBS_DEREG

Note: This service is obsolete. Use SBS_DEREGISTER_REQ instead.

Applications can register to receive broadcast messages by sending an SBS_REG message or an SBS_REG_EZ message to the SBS Server. When an application no longer needs to receive messages from a broadcast stream, it sends an SBS_DEREG message to the SBS Server. This message causes the SBS Server to deregister all entries for the broadcast stream and receiving queue combination.

C Message Structure

typedef struct _SBS_DEREG {
    int16 version;
    uint16 mot;
    q_address distribution_q;
    char req_ack;
    } SBS_DEREG;

Message Data Fields

Field	Data Type	Script Format	Description
version	word	DW	Message format version. Must be 20.
mot_q	unsigned word	DW	MOT queue address.
distribution_q	q_address	DL	Distribution queue address.
req_ack	Boolean	DB	Value of 1 if acknowledgment requested.

Arguments

Argument	Script Format	pams_get_msg Format
Target	SBS_SERVER	PAMS_SBS_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_DEREG	MSG_TYPE_SBS_DEREG

See Also

• SBS_BS_SEQGAP

• SBS_DEREG_ACK

• SBS_DEREG_BY_ID

• SBS_REG

• SBS_REG_EZ

SBS_DEREG_ACK

Note: This service is obsolete. Use SBS_DEREGISTER_RESP instead.

Applications can register to receive broadcast messages by sending an SBS_REG message or an SBS_REG_EZ message to the SBS Server. When an application no longer needs to receive messages from a broadcast stream, it sends an SBS_DEREG message to the SBS Server. This message causes the SBS Server to deregister all entries for the broadcast stream and receiving queue combination. The SBS_DEREG_ACK message acknowledges deregistration for the broadcast stream and receiver queue selected.

C Message Structure

typedef struct _SBS_DEREG_ACK {
    int16 status;
    int16 number_reg;
    } SBS_DEREG_ACK;

Message Data Fields

Field	Data Type	Script Format	Description
status	word	DW	The return status of 1 = success, -n = failure.
number_reg	word	DW	Number of registrants left on this Multipoint Outbound Target (MOT) after deregistration.

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	SBS_SERVER	PAMS_SBS_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_DEREG_ACK	MSG_TYPE_SBS_DEREG_ACK

See Also

• SBS_DEREG

• SBS_DEREG_BY_ID

• SBS_REG

• SBS_REG_EZ

SBS_DEREG_BY_ID

Note: This service is obsolete. Use SBS_DEREGISTER_REQ instead.

Applications can register to receive broadcast messages by sending an SBS_REG message or an SBS_REG_EZ message to the SBS Server. When an application has multiple registrations for a broadcast stream and no longer needs to receive one type of message, the application can send an SBS_DEREG_BY_ID message to the SBS Server by providing the ID returned by MessageQ during the initial broadcast registration. The queue will continue to receive broadcast messages requested through separate registrations.

C Message Structure

typedef struct _SBS_DEREG_BY_ID {
    short version;
    unsigned short reg_id;
    char req_ack;
    } SBS_DEREG_BY_ID;

Message Data Fields

Field	Data Type	Script Format	Description
version	word	DW	Message format version. Must be 20.
reg_id	unsigned word	DW	Registration ID.
req_ack	Boolean	DB	Value of 1 if ACK requested.

Arguments

Argument	Script Format	pams_get_msg Format
Target	SBS_SERVER	PAMS_SBS_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_DEREG_BY_ID	MSG_TYPE_SBS_DEREG_BY_ID

See Also

• SBS_DEREG

• SBS_DEREG_ACK

• SBS_REG

• SBS_REG_EZ

SBS_REG

Note: This service is obsolete. Use SBS_REGISTER_REQ instead.

Applications can register to receive selected messages from a broadcast stream by sending an SBS_REG message to the SBS Server. This message requests a target queue to receive all messages that meet the selection criteria entered as part of the registration process. Selection rules define a relational operation to be applied against a message header or message data field. Each broadcast message that matches the rule is distributed to the target queue.

C Message Structure

typedef struct _SBS_REG {
    int16 version;
    uint16 mot;
    q_address distribution_q;
    int16 offset;
    char data_operator;
    int16 length;
    uint32 operand;
    char req_ack;
    char req_seqgap;
    char req_autodereg;
    } SBS_REG;

Message Data Fields

Field	Data Type	Script Format	Description
version	word	DW	Message format version number. Must be 20.
mot_addr	unsigned word	DW	The Multipoint Outbound Target (MOT) broadcast stream to which the program tries to register.
distribution_q	q_address	DL	The MessageQ address that receives any messages that are selected from the broadcast stream.
offset	word	DW	Specifies a field in the message header or in the message data component.
operator	byte	DB	Controls the type of comparison to be performed on the field designated by the data offset and the operand.
length	word	DW	Specifies the size of comparison to be performed. The choices are 0, 1, 2, and 4.
operand	uint32	DL	The value to be used in the comparison of the field specified by the data offset.
req_ack	Boolean	DB	Specifies if an acknowledgment message is requested. See SBS_REG_REPLY.
req_seqgap	Boolean	DB	Specifies if a notification of broadcast stream message sequence number gap is requested.
req_autodereg	Boolean	DB	Specifies if a registration request is to be automatically purged from the SBS Server table.

Arguments

Argument	Script Format	pams_get_msg Format
Target	SBS_SERVER	PAMS_SBS_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_REG	MSG_TYPE_SBS_REG

See Also

• SBS_REG_REPLY

• SBS_REG_EZ

• SBS_DEREG

SBS_REG_EZ

Note: This service is obsolete. Use SBS_REGISTER_REQ instead.

Applications can register to receive all messages from a broadcast stream by sending an SBS_REG_EZ message to the SBS Server. This message requests a target queue to receive all messages sent to the selected broadcast stream.

C Message Structure

typedef struct _SBS_REG_EZ {
    int16 version;
    int16 mot;
    q_address distribution_q;
    } SBS_REG_EZ;

Message Data Fields

Field	Data Type	Script Format	Description
version	word	DW	Message format version number. Must be 20.
mot_addr	word	DW	The Multipoint Outbound Target (MOT) broadcast stream to which the process tries to subscribe.
distribution_q	q_address	DL	The MessageQ address that receives any messages selected from the broadcast stream.

Arguments

Argument	Script Format	pams_get_msg Format
Target	SBS_SERVER	PAMS_SBS_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_REG_EZ	MSG_TYPE_SBS_REG_EZ

See Also

• SBS_REG_EZ_REPLY

• SBS_REG

• SBS_DEREG

SBS_REG_EZ_REPLY

Note: This service is obsolete. Use SBS_REGISTER_RESP instead.

Applications can register to receive all messages from a broadcast stream by sending an SBS_REG_EZ message to the SBS Server. This message requests that all messages sent to a broadcast stream be distributed to a particular target queue. The SBS_REG_EZ_REPLY message indicates the status of the request and returns a registration ID if the application is successfully registered.

C Message Structure

typedef struct _SBS_REG_EZ_REPLY {
    int16 status;
    uint16 reg_id;
    int16 number_reg;
    } SBS_REG_EZ_REPLY;

Message Data Fields

Field	Data Type	Script Format	Description
status	word	DW	The return status of 1indicates success; -n indicates failure.
reg_id	unsigned word	DW	Returned registration ID.
number_reg	word	DW	Number of registrants left on this Multipoint Outbound Target (MOT).

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	SBS_SERVER	PAMS_SBS_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_REG_EZ_REPLY	MSG_TYPE_SBS_REG_EZ_REPLY

See Also

• SBS_REG_EZ

• SBS_DEREG

SBS_REG_REPLY

Note: This service is obsolete. Use SBS_REGISTER_RESP instead.

Applications can register to receive selected messages from a broadcast stream by sending an SBS_REG message to the SBS Server. This message requests a target queue to receive all messages sent to a particular broadcast stream that meet selection criteria. The SBS_REG_REPLY message indicates the status of the request and returns a registration ID.

C Message Structure

typedef struct _SBS_REG_REPLY {
    int16 status;
    uint16 reg_id;
    int16 number_reg;
    } SBS_REG_REPLY;

Message Data Fields

Field	Data Type	Script Format	Description
status	word	DW	The return status of 1 = success, -n = failure.
reg_id	unsigned word	DW	Returned registration ID.
number_reg	word	DW	Number of registrants left on this Multipoint Outbound Target (MOT).

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	SBS_SERVER	PAMS_SBS_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	SBS_REG_REPLY	MSG_TYPE_SBS_REG_REPLY

See Also

• SBS_REG

Obsolete PAMS API Functions

This section contains reference information for the following obsolete PAMS API functions:

• pams_create_handle

• pams_decode

• pams_delete_handle

• pams_encode

• pams_extract_buffer

• pams_insert_buffer

• pams_msg_length

• pams_next_msg_field

• pams_remove_encoding

• pams_set_msg_position

pams_create_handle

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Creates an empty message and returns a handle to it.

Syntax

int32 pams_create_handle ( handle, [ handle_type ] );

Arguments

Table 9-1

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	returned
handle_type	int32	reference	int32 *	passed

Argument Definitions

handle

Supplies the handle that you want created.

handle_type

Specifies the type of handle to create.

Return Values

Table 9-2

Return Code	Platform	Description
PAMS__BADARGLIST	All	Invalid number of arguments.
PAMS__BADPARAM	All	Invalid handle_type argument value.
PAMS__RESRCFAIL	All	Insufficient resources to complete the operation.
PAMS__SUCCESS	All	Indicates successful completion.

Description

The handle_type argument takes the PSYM_MSG_HANDLE value to request the creation of a message handle. In this case, the returned pams_handle argument can be used everywhere a pams_handle data type is needed with a function.

PSYM_MSG_HANDLE is a default value, so providing a null pointer as handle_type creates a message handle.

See Also

• pams_delete_handle

• pams_extract_buffer

• pams_insert_buffer

• pams_msg_length

pams_decode

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

The pams_decode functions are a series of functions that decode a tagged field out of the message. The first unseen field in the message with the desired element is returned. The actual name of the function and its description is listed as follows:

Table 9-3

Function	Description
pams_decode_int8	Decodes an 8-bit signed integer (char) element of information out of the message.
pams_decode_uint8	Decodes an 8-bit unsigned integer (unsigned char) element of information out of the message.
pams_decode_int16	Decodes a 16-bit signed integer element of information out of the message.
pams_decode_uint16	Decodes a 16-bit unsigned integer element of information out of the message.
pams_decode_int32	Decodes a 32-bit signed integer element of information out of the message.
pams_decode_uint32	Decodes a 32-bit unsigned integer element of information out of the message.
pams_decode_int64	Decodes a 64-bit signed integer element of information out of the message.
pams_decode_uint64	Decodes a 64-bit unsigned integer element of information out of the message.
pams_decode_float	Decodes a single floating-point element of information out of the message.
pams_decode_double	Decodes a double floating-point element of information out of the message.
pams_decode_string	Decodes a string element of information out of the message.
pams_decode_array	Decodes an array of elements of information of the same type out of the message.
pams_decode_qid	Decodes the q_address (MessageQ queue address) out of the message.

Syntax

The syntax for each of the pams_decode functions is as follows:

Listing 9-1 Syntax for pams_encode function

---

int32 pams_decode_int8 ( pams_handle handle, int32* tag, int8*
			value);

int32 pams_decode_uint8 ( pams_handle handle, int32* tag, uint8*
			value);

int32 pams_decode_int16 ( pams_handle handle, int32* tag, int16*
			value);

int32 pams_decode_uint16 ( pams_handle handle, int32* tag, uint16*
			value);

int32 pams_decode_int32 ( pams_handle handle, int32* tag, int32*
			value);

int32 pams_decode_uint32 ( pams_handle handle, int32* tag, uint32*
			value);

int32 pams_decode_int64 ( pams_handle handle, int32* tag, int64*
			value);

int32 pams_decode_uint64 ( pams_handle handle, int32* tag, uint64*
			value);

int32 pams_decode_float ( pams_handle handle, int32* tag, float*
			value);

int32 pams_decode_double ( pams_handle handle, int32* tag, double*
			value);

int32 pams_decode_string ( pams_handle handle, int32* tag, char*
			value,
                     int32* bufferLength,
                        int32* valueLength);

int32 pams_decode_array ( pams_handle handle, int32* tag, void*
			value,
                     int32* bufferLength,
                        int32* numEltsValue); 

int32 pams_decode_qid ( pams_handle handle, int32* tag,
			q_address* value);, 

---

Arguments

The following table describes the arguments for the pams_decode functions above. Some of these arguments apply to certain functions only.

Table 9-4

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
tag	int32	reference	int32 *	passed
value	varying pointer	reference	int32 *	returned
bufferLength	int32	reference	int32 *	passed
valueLength	int32	reference	int32 *	returned
numEltsValue	int32	reference	int32 *	returned

Argument Definitions

handle

Specifies the message handle.

tag

Specifies the tag of the field to decode.

value

Contains the pointer to a buffer to receive the value of the field to decode.

bufferLength

Contains the number of bytes in the value buffer.

valueLength

Specifies the number of bytes in the returned value, unless a NULL pointer is passed. If the valueLength argument is a NULL pointer to the call to pams_decode_string, the string is returned null-terminated. In this case, the specified bufferLength argument must include space for the trailing null.

numEltsValue

Specifies the number of elements contained in the array.

Return Values

Table 9-5

Return Code	Platform	Description
PAMS__AREATOSMALL	All	The buffer length is too small to fit the value string.
PAMS__BADHANDLE	All	Invalid message handle or handle to an untyped message.
PAMS__BADTAG	All	The tag data type does not match the routine used for the value data type.
PAMS__SUCCESS	All	Indicates successful completion.
PAMS__TAGNOTFOUND	All	Tag not found in the message.

Description

This function scans the message for an unseen instance of the specified tag, starting at the beginning of the message:

• If the scan finds a match, the matched element is marked as seen, its value (and length) are returned, and the return value is set to PAMS__SUCCESS.

• If the scan continues without success to the end of the message, the return value is set to PAMS__NOSUCHTAG.

Thus, if there are two occurrences of a particular tag in a message, the first decode call always returns the earlier occurrence of the tag, and the second call returns the later one. Conversely, if a receiving application knows a message's tag order is Atag, Btag, ENDtag, Atag, Btag, ENDtag, the application cannot skip the first pair by decoding first ENDtag, and then decoding Atag.

The value is returned in the local host representation (endian conversions are applied when necessary).

See Also

• pams_encode

• pams_remove_encoding

pams_delete_handle

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Releases all of the resources allocated for the message handle.

Syntax

int32 pams_delete_handle ( handle );

Arguments

Table 9-6

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed

Argument Definition

handle

Specifies the message handle to delete.

Return Values

Table 9-7

Return Code	Platform	Description
PAMS__BADARGLIST	All	Invalid number of arguments.
PAMS__BADHANDLE	All	Invalid message handle.
PAMS__SUCCESS	All	Indicates successful completion.

Description

Applications must use this function after sending or receiving messages. The use of this function avoids memory leaks. Note that your application must call this function if you decide not to send a message you have created.

See Also

• pams_create_handle

• pams_extract_buffer

• pams_insert_buffer

• pams_msg_length

pams_encode

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

The pams_encode functions are a series of functions that append a field in the SDM message based on a specific data type. The actual name of the function and its description is as follows:

Function	Description
pams_encode_int8	Encodes an 8-bit signed integer (char) element of information in the message.
pams_encode_uint8	Encodes an 8-bit unsigned integer (unsigned char) element of information in the message.
pams_encode_int16	Encodes a 16-bit signed integer element of information in the message.
pams_encode_uint16	Encodes a 16-bit unsigned integer element of information in the message.
pams_encode_int32	Encodes a 32-bit signed integer element of information in the message.
pams_encode_uint32	Encodes a 32-bit unsigned integer element of information in the message.
pams_encode_int64	Encodes a 64-bit signed integer element of information in the message.
pams_encode_uint64	Encodes a 64-bit unsigned integer element of information in the message.
pams_encode_float	Encodes a single floating-point element of information in the message.
pams_encode_double	Encodes a double floating-point element of information in the message.
pams_encode_string	Encodes a string element of information in the message.
pams_encode_array	Encodes an array of elements of information of the same type in the message.
pams_encode_qid	Encodes the q_address (MessageQ queue address) in the message.

Syntax

The syntax for each of the pams_encode functions is as follows:

Listing 9-2 Syntax for pams_encode_functions

---

int32 pams_encode_int8 ( pams_handle handle, int32* tag, int8*
			 value);

int32 pams_encode_uint8 ( pams_handle handle, int32* tag, uint8*
			 value);

int32 pams_encode_int16 ( pams_handle handle, int32* tag, int16*
			 value);

int32 pams_encode_uint16 ( pams_handle handle, int32* tag,
			 uint16* value);

int32 pams_encode_int32 ( pams_handle handle, int32* tag, int32*
			 value);

int32 pams_encode_uint32 ( pams_handle handle, int32* tag, uint32*
			 value);

int32 pams_encode_int64 ( pams_handle handle, int32* tag, int64*
			 value);

int32 pams_encode_uint64 ( pams_handle handle, int32* tag,
			 uint64* value);

int32 pams_encode_float ( pams_handle handle, int32* tag, float*
			 value);

int32 pams_encode_double ( pams_handle handle, int32* tag,
			 double* value);

int32 pams_encode_string ( pams_handle handle, int32* tag, char*
			 value, int32* length);

int32 pams_encode_array ( pams_handle handle, int32* tag, void*
			 value, int32* numElts);

int32 pams_encode_qid ( pams_handle handle, int32* tag,
			 q_address* value);

Arguments

The following table describes the arguments for the pams_encode functions. Some of these arguments apply to certain functions only.

Table 9-8   




	
	

		

			
Argument


		
		

			
Data Type


		
		

			
Mechanism


		
		

			
Prototype


		
		

			
Access


		

	
	

		

			
handle


		
		

			
pams_handle


		
		

			
reference


		
		

			
pams_handle *


		
		

			
passed


		

	
	

		

			
tag


		
		

			
int32


		
		

			
reference


		
		

			
int32 *


		
		

			
passed


		

	
	

		

			
value


		
		

			
varying


		
		

			
reference


		
		

			
int32 *


		
		

			
passed


		

	
	

		

			
length


		
		

			
int32


		
		

			
reference


		
		

			
int32 *


		
		

			
passed


		

	
	

		

			
numElts


		
		

			
int32


		
		

			
reference


		
		

			
int32 *


		
		

			
passed


		

	

Argument Definitions

handle

Specifies the message handle.

tag

Specifies the tag of the field to encode.

value

Specifies the value of the field to encode.

length

Specifies the length of the string to encode, or -1 if the string is null terminated.

numElts

Specifies the number of elements in the array.

Return Values

Table 9-9

Return Code	Platform	Description
PAMS__BADHANDLE	All	Invalid message handle or handle to an untyped message.
PAMS__BADTAG	All	Invalid tag.
PAMS__RESRCFAIL	All	Insufficient resources to expand the message.
PAMS__SUCCESS	All	Indicates successful completion.

Description

Several structures exist to encode fields for each data type supported by the SDM capability. The application developer uses the function that matches the data type of the field to encode. Since the tag embeds information about the value data type, the PAMS__BADTAG code is returned if the function used does not match the tag data type. For example, if the pams_encode_int32 function is used to encode a character string. The PAMS__BADTAG code is also returned if the tag construction does not follow the rules or if the tag is reserved.

You can insert a null tag (PSDM_NULL_TAG) in a SDM message to control application behavior. For example, you can insert a null tag to stop an enumeration. To insert a null tag, use any of the numeric pams_encode functions and specify a NULL value pointer. The following code fragment shows how to insert a null tag into a signed 32-bit integer element:

null_tag = PSDM_NULL_TAG;
status = pams_encode_int32(mh, &null_tag, NULL);

See Also

• pams_decode

pams_extract_buffer

Returns a message in the specified buffer. The message size is also returned.

Syntax

int32 pams_extract_buffer ( handle, msgBuffer, bufferLength, msgLength);

Table 9-10

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
msgBuffer	char	reference	char *	returned
bufferLength	uint32	reference	uint32 *	passed
msgLength	uint32	reference	uint32 *	returned

Argument Definitions

handle

Specifies the message handle of the message to extract.

msgBuffer

Contains the pointer to the buffer from which to extract the message.

bufferLength

Specifies the size in bytes of msgBuffer.

msgLength

Contains the pointer where to place the message's length. You can specify a NULL pointer in languages that allow these kinds of pointers.

Return Values

Table 9-11

Return Code	Platform	Description
PAMS__AREATOSMALL	All	Message is larger than the user's buffer.
PAMS__BADARGLIST	All	Invalid number of arguments.
PAMS__BADPARAM	All	Invalid bufferLength argument.
PAMS__BADHANDLE	All	Invalid message handle or handle to an SDM message already processed with the API.
PAMS__FATAL	All	SDM message is corrupted.
PAMS__SUCCESS	All	Indicates successful completion.

Description

This function copies the received message associated with the specified handle into the user provided buffer. If requested (by passing a non-NULL msgLength), the number of bytes of the message is returned as well.

If the message handle points to an SDM message for which encoding or decoding has already been performed, this function returns PAMS__BADHANDLE.

If your application does not know the maximum size message that can arrive, it can call the pams_msg_length function prior to calling pams_extract_buffer to determine how big a buffer is needed.

See Also

• pams_create_handle

• pams_delete_handle

• pams_insert_buffer

• pams_msg_length

pams_insert_buffer

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Inserts the contents of the specified buffer into the message identified by the message handle.

Syntax

int32 pams_insert_buffer ( handle, msgBuffer, length );

Arguments

Table 9-12

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
msgBuffer	char	reference	char *	passed
length	uint32	reference	uint32 *	passed

Argument Definitions

handle

Specifies the message handle.

msgBuffer

Specifies the pointer to a user area to use as message content.

length

Specifies the size in bytes of the msgBuffer buffer or zero.

Return Values

Table 9-13

Return Code	Platform	Description
PAMS__BADARGLIST	All	Invalid number of arguments.
PAMS__BADHANDLE	All	Invalid message handle or handle to an SDM message and *length > 0 or not handle to an SDM message and *length == 0.
PAMS__BADPARAM	All	Invalid msgBuffer or length argument.
PAMS__FATAL	All	SDM message is corrupted.
PAMS__RESRCFAIL	All	Insufficient resources to complete the operation.
PAMS__SUCCESS	All	Indicates successful completion.

Description

This function copies the user-provided buffer into the received message that is associated with the specified handle. If a buffer was already inserted in the message, it is overwritten by a subsequent call to the pams_insert_buffer function. If the length -argument points to a zero-valued integer, the buffer to insert is an SDM message.

See Also

• pams_create_handle

• pams_delete_handle

• pams_extract_buffer

• pams_msg_length

pams_msg_length

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Returns the number of bytes in the message. The message is identified by a message handle created with the pams_create_handle function.

Syntax

int32 pams_msg_length ( handle, msgLength );

Arguments

Table 9-14

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
msgLength	uint32	reference	uint32 *	returned

Argument Definitions

handle

Specifies the message handle of the message.

msgLength

Contains the message handle of the message.

Return Values

Table 9-15

Return Code	Platform	Description
PAMS__SUCCESS	All	Indicates successful completion.
PAMS__BADARGLIST	All	Invalid number of arguments.
PAMS__BADHANDLE	All	Invalid message handle.

See Also

• pams_create_handle

• pams_delete_handle

• pams_extract_buffer

• pams_insert_buffer

pams_next_msg_field

Returns the tag and length of the first unseen field in the message.

Syntax

int32 pams_next_msg_field (pams_handle handle, tag, valueLength)

Arguments

Table 9-16

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
tag	int32	reference	int32 *	returned
valueLength	int32	reference	int32 *	returned

Argument Definitions

handle

Specifies the message handle of the message to scan.

tag

Returns the tag of first unseen field in the message.

valueLength

Returns the length of the returned value or a NULL pointer, if the user is not interested in this information. The length returned is the size in bytes necessary to receive the value. For strings, it is the string length (null terminator not included). For arrays, it is the number of fields multiplied by the size of each field.

Return Values

Table 9-17

Return Code	Platform	Description
PAMS__BADHANDLE	All	Invalid message handle.
PAMS__NOMORETAG	All	No more tags in the message (all fields were decoded).
PAMS__SUCCESS	All	Indicates successful completion.

Description

This function does not mark the matched field as seen. Therefore, successive calls to this function without calling the appropriate pams_decode functions returns the same tag.

When all fields have been decoded, the function returns PAMS__NOMORETAG.

See Also

• pams_decode

• pams_set_msg_position

pams_remove_encoding

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Removes a previously encoded field from the message buffer.

Syntax

int32 pams_remove_encoding (pams_handle handle, int32* tag, int32* flags);

Argument

Table 9-18

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
tag	int32	reference	int32 *	passed
flags	int32	reference	int32 *	passed

Argument Definitions

handle

Specifies the message handle.

tag

Specifies the tag of the field to remove. If the tag is PSDM_NULL_TAG, the first or last - depending on flags - encoded null tag is removed.

flags

Specifies the flags to control the function behavior. The flags argument can take the following values:

• PSDM_FIRST to remove the first encoded field matching tag.

• PSDM_LAST to remove the last encoded field matching tag.

• PSDM_ANY to ignore the tag argument; PSDM_ANY must be used in combination with PSDM_FIRST or PSDM_LAST, to force the very first or very last field in the message to be removed, whatever its tag is.

Return Values

Table 9-19

Return Code	Platform	Description
PAMS__BADPARAM	All	Invalid flag.
PAMS__BADHANDLE	All	Invalid message handle or handle to a large message.
PAMS__BADTAG	All	Invalid tag.
PAMS__SUCCESS	All	Indicates successful completion.
PAMS__TAGNOTFOUND	All	Tag not found in the message.

See Also

• pams_decode

• pams_encode

pams_set_msg_position

Note: This function is obsolete. Handles and the SDM format used in MessageQ Version 4.0 have been replaced by the FML32 format for self describing messaging. Use pams_put_msg with the PSYM_MSG_FML symbol and pams_get_msg(w) with the PSYM_MSG_BUFFER_PTR symbol to send and receive FML messages.

Resets the message to the position of a specific tag.

Syntax

int32 pams_set_msg_position (pams_handle handle, int32* tag, int32*
			 flags);

Arguments

Table 9-20

Argument	Data Type	Mechanism	Prototype	Access
handle	pams_handle	reference	pams_handle *	passed
tag	int32	reference	int32 *	passed
flags	int32	reference	int32 *	passed

Argument Definitions

handle

Specifies the message handle.

tag

Specifies the tag to reset encoding or decoding to.

Specifies the flags argument, which is a mask allowing you to specify the behavior. It can OR the following modifiers:

• PSDM_PREVIOUS searches for the previous occurrence of the specified tag (default for encoding).

• PSDM_NEXT searches for the next occurrence of the specified tag (default for decoding).

• PSDM_FIRST searches for the first occurrence of the specified tag in the message.

• PSDM_LAST searches for the last occurrence of the specified tag in the message.

• PSDM_AT sets the position at the element specified (default).

• PSDM_BEFORE sets the position at the element preceding the specified element.

• PSDM_AFTER sets the position at the element following the specified element.

• PSDM_ANY tells to ignore the specified tag argument. The following combinations are possible :

• (PSDM_ANY | PSDM_PREVIOUS) sets position at the previous tag.

• (PSDM_ANY | PSDM_NEXT) sets position at the next tag; when used in conjunction with pams_next_msg_field, it allows skipping the undesired elements.

• (PSDM_ANY | PSDM_FIRST) sets position at the beginning of the message.

• (PSDM_ANY | PSDM_LAST) sets position at the end of the message; this allows appending elements to a received message.
  The modifiers PSDM_PREVIOUS, PSDM_NEXT, PSDM_FIRST, and PSDM_LAST are mutually exclusive.

  The modifiers PSDM_AT, PSDM_BEFORE, and PSDM_AFTER are also mutually exclusive.

Return Values

Table 9-21

Return Code	Platform	Description
PAMS__BADHANDLE	All	Invalid message handle or handle to a large message.
PAMS__BADPARAM	All	The specified flags argument is invalid.
PAMS__SUCCESS	All	Indicates successful completion.

Description

This function resets the starting point of the encoding or decoding to the field in the message with the specified tag:

• When used to perform further encoding, already encoded fields after the specified element are lost.

• When used to perform further decoding, all seen fields after the specified element are marked unseen and the rest are marked seen.

See Also

• pams_encode

• pams_decode

• pams_next_msg_field