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:

• Port Server Control Messages

• Port Server Connection Messages

• Example of Port Server Messages Used for Client Communications

Port Server Control Messages

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

• PAMSLU62_ALREADYCON

• PAMSLU62_BADSYSID

• PAMSLU62_BADTARGNAME

• PAMSLU62_BUSY

• PAMSLU62_WRONGTYPE

CONNECT_REQUEST

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:

• Indicate that this is the last message

• Request a direction change and become the receiver program

• Terminate the connection, normally or abnormally

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 PREPARE_TO_RECEIVE message.
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(); 
} 

... 

---