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

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.

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.

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

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.

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

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.

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

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.

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

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.

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;

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.

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

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.

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

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.

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

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.

int32 pams_create_handle ( handle, [ handle_type ] );

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.

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.

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

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

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.

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.

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

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

int32 pams_delete_handle ( handle );

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.

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.

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

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

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


		

	

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.

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

• pams_decode

pams_extract_buffer

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

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

Table 9-10

Argument	Data Type	Mechanism