|
|
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:
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:
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
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
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_ |
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
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
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_ |
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);
}
.
.
.
}
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|