LU6.2 Port Server Application Programming Interface

 

Users can simplify the development of BEA MessageQ application programs that use the LU6.2 Port Server by hiding the details of BEA MessageQ LU6.2 Services for OpenVMS within a shell of procedure calls.

This chapter presents a sample application programming interface (API) for LU6.2 Services for OpenVMS. The sample API consists of the following four procedure calls:

• PORT_CONNECT-Establishes a connection to the specified inbound target.

• PORT_RECV-Receives a message through any existing connection or through a new connection resulting from a previous registration.

• PORT_REGISTER-Specifies the register to receive output directed at the specified outbound target.

• PORT_SEND-Sends a message through a previously established connection.

The source code for these procedures is found in the following file:

DMQLU62$SERVER_SRC:PORT_FUN.C 

Note: The procedure calls are portable to non-OpenVMS platforms with minimal code changes.

This chapter provides information, organized in the format of reference manual entries, about the following procedure calls:

• PORT_CONNECT

• PORT_RECV

• PORT_REGISTER

• PORT_SEND

PORT_CONNECT

This procedure establishes a connection to a specified inbound target.

Syntax

COND_VALUE=PORT_CONNECT(target_name, ... port_queue) 

Arguments

Argument	Data Type	Mechanism	Prototype	Access
target_name	char	reference	char *	passed
connection_index	word	reference	short *	returned
port_group	word	value	short	passed
port_queue	word	value	short	passed

Argument definitions

target_name

The name of the target to which to establish the connection.

connection_index

The unique identifier of the requested connection.

port_group

The BEA MessageQ group ID of the LU6.2 Port Server that connects to the specified target.

port_queue

The BEA MessageQ queue number of the LU6.2 Port Server that connects to the specified target.

DESCRIPTION

This procedure sends a CONNECT_REQUEST message for the specified target to the designated generic port server and waits for a response.

RETURNS

Argument	Data Type	Mechanism	Prototype	Access
cond_value	longword	value	long	returned

RETURN VALUES

Return Code	Description
SS$_NORMAL	A connection is successfully completed.
PAMSLU62_ALREADYCON	A connection has already been established to the named target.
PAMSLU62_BADSYSID	The port server target definition specifies an undefined value for SYS_ID.
PAMSLU62_BADTARGNAME	The named target has not been defined to the port server.
PAMSLU62_BUSY	All paths to the named target are currently in use.
PAMSLU62_WRONGTYPE	The named target is defined as OUTBOUND.
PAMS_xxxxxxxx	This indicates any PAMS status code returned by pams_put_msg or pams_get_msgw.

Example

The following is an example of the PORT_CONNECT procedure call.

#include stdio 
#include "port_fun.h" 
#include "p_entry.h" 

#define TRUE 1 
#define FALSE 0 


main() 
{ 
	int32 p_status; 
	int32 req; 
	long status; 
	q_address used; 
	short send_connection; 
	
	req = 0; 
	
	p_status = pams_attach_q(&req,&used); 
	if (!(p_status & 1)) return(p_status); 
	
	status = port_connect("MY_TARGET", 
		&send_connection, 
		3, 
		63); 

	if (!(status & 1)) 
	{ 
	p_status = pams_exit(); 
	return(p_status); 
	} 
. 
. 
. 
} 

PORT_RECV

This procedure receives a data message from a remote IBM application program through a previously established connection or through a new connection resulting from a previous PORT_REGISTER procedure call.

Syntax

COND_VALUE=PORT_RECV(message, buf_size, ... port_queue) 

Arguments

Argument	Data Type	Mechanism	Prototype	Access
message	char	reference	char *	returned
buf_size	word	value	short	passed
msg_size	word	reference	short *	returned
connection_index	word	reference	short *	returned
change_dir	word	reference	short *	returned
disconnect	word	reference	short *	returned
abort	word	reference	short *	returned
port_group	word	reference	short *	returned
port_queue	word	reference	short *	returned

Argument definitions

message

The user buffer to contain the message received from the IBM application program.

buf_size

The size of the user buffer to contain the received message. Messages too large to fit in the buffer are truncated to the buffer size.

msg_size

The size of the returned message, or the buffer size, if the message is larger than the buffer.

connection_index

The unique identifier of the connection on which the message was received.

change_dir

Indicates that the direction of the connection was reversed.

disconnect

When set to a non-zero value, indicates that the remote IBM client has terminated the conversation normally.

abort

When set to a non-zero value, indicates that the remote IBM client has terminated the conversation abnormally.

port_group

The BEA MessageQ group ID of the generic port server that sent the message.

port_queue

The BEA MessageQ queue number of the generic port server that sent the message.

Description

This procedure waits to receive a message from a remote IBM application program. The message can be received through an established connection or through a connection initiated by the remote IBM application program using a PORT_REGISTER procedure call. The connection on which the message arrives is identified by the connection_index argument. By setting the change_dir, disconnect, or abort flags, the direction of the message flow can be changed, buffers at the generic port server can be flushed, or the connection can be terminated (normally or abnormally).

Returns

Argument	Data Type	Mechanism	Prototype	Access
cond_value	longword	value	long	returned

Return values

Return Code	Description
SS$_NORMAL	Indicates successful completion.
PAMSLU62_BADINDEX	The connection_index provided is invalid.
PAMSLU62_ CONABORTDATA	The connection has been aborted by the port server due to a nontranslatable ASCII character in the body of the message.
PAMSLU62_CONABORTSTATE	The connection has been aborted by the port server due to a violation of the selected application protocol.
PAMSLU62_NOCONNECT	No connection has been established.
PAMS_xxxxxxxx	Any PAMS status code returned by pams_put_msg.

Example

The following is an example of the PORT_RECV procedure call.

#include stdio 
#include signal 
#include "port_fun.h" 
#include "p_entry.h" 
#include "p_return.h" 

#define TRUE 1 
#define FALSE 0 

main() 
{ 
	int32 p_status; 
	long  status; 
	char reply[1024]; 
	short get_disc = 0; 
	short buf_siz; 
	. 
	. 
	. 
	buf_size = sizeof(reply); 
	
	while (!get_disc) 
	{ 
	status = port_recv(reply, 
	buf_siz, 
	&msg_siz, 
	&recv_connection, 
	&get_cdi, 
	&get_disc, 
	&get_abort, 
	&source_group, 
	&source_process); 
	
	 if (!((status & 1)||(status == PAMS__TIMEOUT))) 
	{ 
	p_status = pams_exit(); 
	return(p_status); 
	} 
		. 
		. 
		. 
	} 

PORT_REGISTER

This procedure specifies the queue to receive the output directed to a specified target by a remote IBM application program.

Syntax

COND_VALUE=PORT_REGISTER(target_name, ... reg_queue) 

Arguments

Argument	Data Type	Mechanism	Prototype	Access
target_name	char	reference	char *	passed
port_group	word	value	short	passed
port_queue	word	value	short	passed
reg_group	word	value	short	passed
reg_queue	word	value	short	passed

Argument definitions

target_name

The name of the target with which to register.

port_group

The BEA MessageQ group ID of the generic port server that connects to the specified target.

port_queue

The BEA MessageQ queue number of the generic port server that connects to the specified target.

reg_group

The BEA MessageQ group ID of the process to register.

reg_queue

The BEA MessageQ queue number of the process to register.

Description

This procedure sends a REGISTER_TARGET message for the specified target to the designated generic port server and waits for a response.

Returns

Argument	Data Type	Mechanism	Prototype	Access
cond_value	longword	value	long	returned

Return values

Return Code	Description
SS$_NORMAL	The procedure is successfully completed.
PAMSLU62_ALREADYREG	The process has already registered with the named target.
PAMSLU62_BADSYSID	The port server target definition specifies an undefined value for SYS_ID.
PAMSLU62_BADTARGNAME	The named target has not been defined to the port server.
PAMS__xxxxxxxx	This indicates any PAMS status code returned by pams_put_msg(w).

Example

The following is an example of the PORT_REGISTER procedure call.

#include stdio 
#include "port_fun.h" 
#include "p_entry.h" 
#include "p_return.h" 

#define TRUE 1 
#define FALSE 0 

main() 
{ 
	int32 p_status; 
	long  status; 
	int32 req; 
	q_address used; 

	req = 0; 
	p_status = pams_attach_q(&req,&used); 
	if (!(p_status & 1)) return(p_status); 

	status = port_register("MY_TARGET", 
	 3, 
	 63, 
	 used.au.group, 
	 used.au.process); 

	if (!(status & 1)) 
{ 
p_status = pams_exit(); 
return(p_status); 
} 

. 
. 
. 
}        

PORT_SEND

This procedure sends a data message to a remote IBM application program through a previously established connection. The maximum size of a data message is 31982 bytes.

Syntax

COND_VALUE=PORT_SEND(message, connection_index, ... port_queue) 

Arguments

Argument	Data Type	Mechanism	Prototype	Access
message	char	reference	char *	passed
connection_index	word	value	short	passed
change_dir	word	value	short	passed
last	word	value	short	passed
disconnect	word	value	short	passed
abort	word	value	short	passed
port_group	word	value	short	passed
port_queue	word	value	short	passed

Argument definitions

message

The message text (up to 31982 bytes) to be sent to the IBM application program.

connection_index

The unique identifier of the connection returned by the previous PORT_CONNECT procedure call.

change_dir

Changes direction of message flow from Send to Receive when set to a nonzero value.

last

Indicates the last message in a series. When set to a non-zero value, this argument causes the port server to transmit any untransmitted traffic on the indicated connection. To deallocate the LU6.2 conversation, use the disconnect argument.

disconnect

Indicates the last message in a series. When set to a non-zero value, this argument causes the port server to transmit any untransmitted traffic on the indicated connection and deallocates the LU6.2 conversation normally.

abort

Indicates an error. When set to a non-zero value, this argument causes the port server to deallocate the LU6.2 conversation abnormally.

port_group

The BEA MessageQ group ID of the generic port server that connects to the specified target.

port_queue

The BEA MessageQ queue number of the generic port server that connects to the specified target.

Description

This procedure sends a message to the remote IBM application program through a previously established connection identified by the connection_index argument. By setting the change_dir, last, disconnect, or abort flags, the direction of message flow can be changed, buffers at the LU6.2 Port Server can be flushed, or the connection can be terminated (normally or abnormally).

Returns

Argument	Data Type	Mechanism	Prototype	Access
cond_value	longword	value	long	returned

Return values

Return Code	Description
SS$_NORMAL	The procedure is successfully completed.
PAMSLU62_BADINDEX	The connection_index provided is invalid.
PAMSLU62_CONABORTDATA	The connection has been aborted by the port server due to a nontranslatable ASCII character in the body of the message.
PAMSLU62_ CONABORTSTATE	The connection has been aborted by the port server due to a violation of the selected application protocol.
PAMSLU62_NOCONNECT	No connection has been established.
PAMS__xxxxxxxx	Indicates any PAMS status code returned by pams_put_msg.

Example

The following is an example of the PORT_SEND procedure call.

 #include stdio 
 #include signal 
 #include "port_fun.h" 
 #include "p_entry.h" 
 
 #define TRUE 1 
 #define FALSE 0 
 
 main() 
 { 
	int32 p_status; 
 	long status; 
	short send_connection;     
	. 
 	. 
 	. 
 
 	status = port_send(argv[2], 
	send_connection, 
	TRUE,           /* change direction     */ 
	FALSE,          /* do not FLUSH         */ 
	FALSE,          /* do not disconnect    */ 
 	FALSE,          /* do not abort         */ 
 	 3, 
	 63); 
 
	if (!(status & 1)) 
  { 
  p_status = pams_exit(); 
  return(p_status); 
  } 
 
     . 
     . 
     . 
 
 }