|
|
Port Server Messages
BEA MessageQ clients establish and manage LU6.2 connections through the LU6.2 Port Server using predefined messages. There are two types of predefined messages used by the LU6.2 Port Server: port server control messages and port server connection messages (BEA MessageQ messages).
These messages are sent via the BEA MessageQ API function pams_put_msg. Message class and type definitions, which are used as arguments to pams_put_msg, are provided in the BEA MessageQ Class and Type file (DMQ$TYPCLS.TXT) at installation. Refer to Appendix B in the BEA MessageQ Installation and Configuration Guide for OpenVMS for a sample of DMQ$TYPCLS.TXT.
This chapter discusses the following topics:
This section describes messages that control the LU6.2 Port Server.
Message |
Description |
ADD_LU |
Dynamically adds an LU definition while the LU6.2 Port Server is running |
ADD_TARGET |
Dynamically adds a target definition while the LU6.2 Port Server is running |
SHUTDOWN |
Instructs the LU6.2 Port Server to exit |
To send these control messages, use the pams_put_msg with the target of the port server and the message type of message.
ADD_LU
The ADD_LU message dynamically adds an LU definition while the LU6.2 port server is running. The ADD_LU message is formatted as a valid configuration file entry for LUs and TYPE 1 targets. See Configuring the LU6.2 Port Server, for more information about configuration files.
Listing 4-1 shows the C message structure for the ADD_LU service.
Listing 4-1 C Message Structure for ADD_LU
typedef struct _add_lu {
char sysid[9];
char gateway[7];
char lu_access[9];
char lu_sess[4];
char lu_type[3];
int16 lu_session_dir;
} add_lu;
int16 msg_size;
...
class = MSG_CLAS_APPC;
type = MSG_TYPE_LU62_ADD_LU;
msg_size = sizeof(struct add_lu);
dmq_status = pams_put_msg(
&add_lu,
&priority,
&server_queue,
&class,
&type,
&delivery,
&msg_size,
&timeout,
&put_psb,
&uma,
(q_address *) 0,
(int32 *) 0,
(char *) 0,
(char *) 0 );
ADD_TARGET
The ADD_TARGET message dynamically adds a TYPE 1 inbound target definition while the LU6.2 port server is running. The ADD_TARGET message is formatted as a valid configuration file entry for LUs and targets. See Configuring the LU6.2 Port Server, for more information about configuration files.
Listing 4-2 shows the C message structure for the ADD_TARGET service.
Listing 4-2 C Message Structure for ADD_TARGET
typedef struct _add_tgt {
char targ_name[9];
char targ_tpn[9];
char targ_sysid[9]
int16 comm_type;
int16 dealloc;
} add_tgt;
...
class = MSG_CLAS_APPC;
type = MSG_TYPE_LU62_ADD_TGT;
msg_size = sizeof(struct add_tgt);
dmq_status = pams_put_msg(
&add_tgt,
&priority,
&server_queue,
&class,
&type,
&delivery,
&msg_size,
&timeout,
&put_psb,
&uma,
(q_address *) 0,
(int32 *) 0,
(char *) 0,
(char *) 0 );
SHUTDOWN
The SHUTDOWN message instructs the LU6.2 port server to exit. The SHUTDOWN message has no content; the BEA MessageQ message type is sufficient to convey the information.
Listing 4-3 shows the C message structure for the SHUTDOWN service.
Listing 4-3 C Message Structure for SHUTDOWN
char msg_buf[1024];
int16 msg_size;
...
class = MSG_CLAS_APPC;
type = MSG_TYPE_LU62_SHUTDOWN;
msg_size = 0;
dmq_status = pams_put_msg(
&msg_buf,
&priority,
&server_queue,
&class,
&type,
&delivery,
&msg_size,
&timeout,
&put_psb,
&uma,
(q_address *) 0,
(int32 *) 0,
(char *) 0,
(char *) 0 );
Port Server Connection Messages
This section describes messages either received from or sent to BEA MessageQ clients by the LU6.2 Port Server. These seven predefined messages allow BEA MessageQ clients to use the LU6.2 Port Server to establish and manage LU6.2 connections to remote partners using the port server as the standard API.
Table 4-1 lists the seven predefined port server messages.
Table 4-1 Summary of LU6.2 Port Server Messages
|
|
This message |
Is used to . . . |
CHANGE_DIRECTION |
Indicate change of direction of connection. It may mean that the remote IBM client has become the receiver program, and that the BEA MessageQ client is now the sender program, or vice versa. |
CONNECT_ACCEPT |
Indicate that the requested connection has been established |
CONNECT_REJECT |
Indicate that the requested connection could not be established |
CONNECT_REQUEST |
Request a connection for a BEA MessageQ client to a remote LU6.2 partner |
CONNECTION_TERMINATED |
When sent to a BEA MessageQ client, indicate that the remote IBM client has terminated the connection. When sent by a BEA MessageQ client, request termination of the connection. |
DATA_MESSAGE |
When sent to a BEA MessageQ client, carry a data message received from the remote partner. When sent by a Message client, carry a data message to be transmitted to the remote partner. |
REGISTER_TARGET |
Map to a BEA MessageQ client a target name (including group ID and queue number) for registration purposes |
Figure 4-1 shows a typical program structure that uses BEA MessageQ messages (verbs) to establish and manage data connections.
Figure 4-1 Typical Program Structure
Note: If the message field value is shorter than the required field length, it is necessary to enter null terminators (hex 0s).
The following sections describe each port server message and its format.
CHANGE_DIRECTION
The CHANGE_DIRECTION message indicates a change in the direction of the connection.
When the CHANGE_DIRECTION message is sent to the BEA MessageQ client, it indicates that the remote IBM client has become the receiver program, and that the BEA MessageQ client is now the sender program.
When the CHANGE_DIRECTION message is sent by the BEA MessageQ client, it indicates that the remote IBM client has become the sender program, and that the BEA MessageQ client is now the receiver.
Listing 4-4 shows the C message structure for the CHANGE_DIRECTION service.
Listing 4-4 C Message Structure for CHANGE_DIRECTION
typedef struct _change_direction {
int32 connection_index;
} change_direction;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
CONNECTION_INDEX |
word |
Context value that uniquely identifies the connection that has changed direction |
CONNECT_ACCEPT
The CONNECT_ACCEPT message is sent to the BEA MessageQ client to indicate that the requested connection has been established. This message contains a word (16-bit) context variable used by the LU6.2 port server to identify the connection. The context variable value must be stored by the BEA MessageQ client and provided in any subsequent message sent over the connection.
Listing 4-5 shows the C message structure for the CONNECT_ACCEPT service.
Listing 4-5 C Message Structure for CONNECT_ACCEPT
typedef struct _connect_accept {
int16 connection_index;
char target_name [8];
} connect_accept;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
CONNECTION_INDEX |
word |
Context value that uniquely identifies the connection |
TARGET_NAME |
text 8 char |
Name of the target connected |
CONNECT_REJECT
The CONNECT_REJECT message is sent to the BEA MessageQ client to indicate that the requested connection could not be established. The reason for the rejection is indicated in the body of the message.
Listing 4-6 shows the C message structure for the CONNECT_REJECT service.
Listing 4-6 C Message Structure for CONNECT_REJECT
typedef struct _connect_reject {
char target_name [8];
int32 reject_reason;
} connect_reject;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
TARGET_NAME |
text 8 char |
Name of the target rejected |
REJECT_REASON |
int32 |
Reason for the connect reject |
CONNECT REJECT REASON CODES
The CONNECT_REQUEST message is sent by the BEA MessageQ client to request a connection to a remote LU6.2 partner. This message contains the target name of the remote partner and, optionally, can contain security information to be presented to the VTAM application program when the conversation is allocated by the LU6.2 Port Server.
Listing 4-7 shows the C message structure for the CONNECT_REQUEST service.
Listing 4-7 C Message Structure for CONNECT_REQUEST
typedef struct _connect_request {
char target_name [8];
char username [10];
char password [10];
char profile [10];
} connect_request;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
TARGET_NAME |
text 8 char |
Name of the target for connection |
USER_NAME |
text 10 char |
User name for security authentication |
PASSWORD |
text 10 char |
Password for security authentication |
PROFILE |
text 10 char |
Security profile for security authentication |
CONNECTION_TERMINATED
When sent to a BEA MessageQ client, the CONNECTION_TERMINATED message indicates that the remote IBM client has terminated the connection. This message contains a field indicating the termination status (normal or abnormal).
When sent by a BEA MessageQ client, the CONNECTION_TERMINATED message requests termination of the connection. This message can be used to terminate the connection normally when the BEA MessageQ client is the sender program and no data messages are being sent. This message can also be used to terminate the connection abnormally, regardless of the current state (send or receive).
Listing 4-8 shows the C message structure for the CONNECTION_TERMINATED service.
Listing 4-8 C Message Structure for CONNECTION_TERMINATED
typedef struct _connection_terminated {
int16 connection_index;
int16 terminate_type;
int32 terminate_reason;
} connection_terminated;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
CONNECTION_INDEX |
word |
Context value that uniquely identifies the connection to which this message is to be applied |
TERMINATE_TYPE |
word |
Specifies the type of termination. Valid values are: 1-Disconnect (normal) 2-Disconnect (error) |
TERMINATE_REASON |
int32 |
Reason for termination This field is filled in by the LU6.2 port server when a connection is abnormally terminated by the IBM system. The field is ignored on messages sent to the LU6.2 port server. |
DATA_MESSAGE
When sent to a BEA MessageQ client, the DATA_MESSAGE message contains the text of a data message received from the remote partner. The LU6.2 Port Server translates the data message from EBCDIC to ASCII before sending it, provided that translation is requested in the target definition.
When sent by a BEA MessageQ client, the DATA_MESSAGE message contains the text of a data message to be transmitted to the remote partner. The LU6.2 Port Server translates the data message from ASCII to EBCDIC before transmitting it, provided that translation is requested in the target definition. Control fields in DATA_MESSAGE allow the BEA MessageQ client application program to:
Listing 4-9 shows the C message structure for the DATA_MESSAGE service.
Listing 4-9 C Message Structure for DATA_MESSAGE
typedef struct _data_message {
int16 last_message;
int16 change_direction;
int16 disconnect;
int16 connection_index;
char data [31982];
} data_message;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
LAST_MESSAGE |
word |
Indicates that the current message is the last in the current set. Valid values are: 0-False 1-True When set, the LU6.2 port server issues an explicit FLUSH. |
CHANGE_DIRECTION |
word |
Indicates that the BEA MessageQ client wants to be the receiver program. Valid values are: 0-False 1-True When set, the LU6.2 Port Server issues a |
DISCONNECT |
word |
Indicates that the BEA MessageQ client wants to terminate the connection. Valid values are: 0-False 1-Disconnect (normal) 2-Disconnect (error) |
CONNECTION_INDEX |
word |
Context value that uniquely identifies the connection to which this message is to be applied. |
DATA |
text |
0 to 31982 bytes of data to be sent to the remote LU6.2 partner program. |
REGISTER_TARGET
When sent by a BEA MessageQ client, the REGISTER_TARGET message maps a target name. This message contains the target name for the registration request and the BEA MessageQ queue address (group ID and queue number) of the application program to be registered.
Listing 4-10 shows the C message structure for the REGISTER_TARGET service.
Listing 4-10 C Message Structure for REGISTER_TARGET
typedef struct _register_target {
char target_name [8];
int16 target_group;
int16 target_process;
} register_target;
MESSAGE DATA FIELDS
Field |
Data Type |
Description |
TARGET_NAME |
text 8 char |
Name of the target to register |
TARGET_GROUP |
word |
BEA MessageQ group ID of the application program to register |
TARGET_PROCESS |
word |
BEA MessageQ queue number of the application program to register |
Example of Port Server Messages Used for Client Communications
Listing 4-11 shows port server messages used in a program to support LU6.2 client communications.
Listing 4-11 LU6.2 Port Server Program
typedef struct _connect_request {
char target_name [8];
char username [10];
char password [10];
char profile [10];
} connect_request;
...
strncpy(connect_request.target_name, "MY_TARGET", 8);
strncpy(connect_request.username, "MY_USERNAME", 10);
strncpy(connect_request.password, "TOPSECRET", 10);
strncpy(connect_request.profile, "THEPROFILE", 10);
class = MSG_CLAS_APPC;
type = MSG_TYPE_CONNECT_REQUEST;
msg_ptr = &connect_request;
do{
status = put_msg(msg_ptr, class,type);
if(status)
return(status);
status = get_msg(msg_ptr, class, type);
}while(status == CONTINUE);
status
put_msg(msg_ptr, class, type)
char *msg_ptr;
int16 class;
int16 type;
{
...
dmq_status = pams_put_msg(
msg_ptr,
&priority,
&server_queue,
&class,
&type,
&delivery,
&msg_size,
&timeout,
&put_psb,
&uma,
(q_address *) 0,
(int32 *) 0,
(char *) 0,
(char *) 0 );
return(dmq_status);
}
status
put_msg(msg_ptr, class, type)
char *msg_ptr;
int16 class;
int16 type;
{
...
dmq_status = pams_get_msg(
msg_ptr,
&priority,
&source,
&class,
&type,
&msg_area_len,
&size,
(int32 *) sel_filter,
(struct PSB *) 0,
(struct show_buffer *) 0,
(int32 *) 0,
(int32 *) 0,
(int32 *) 0,
(char *) 0 );
if(dmq_status)
return(dmq_status);
switch(type) {
case MSG_TYPE_CONNECT_ACCEPT:
send_data();
break;
case MSG_TYPE_CONNECT_REJECT:
error_routine();
break;
case MSG_TYPE_CHANGE_DIRECTION:
change_state();
break;
case MSG_TYPE_DATA_MESSAGE:
process_data_msg();
break;
case MSG_TYPE_CONNECTION_TERMINATED:
handle_termination();
break;
default
break;
}
return();
}
...
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|