|
|
|
|
|
|
LU6.2 User Callback Services
This chapter introduces the LU6.2 User Callback Services (UCB) and contains detailed descriptions of all LU6.2 User Callback APPC messages alphabetized by message type. Each description lists the message type code name, the operating environment in which the message is available for use, and a detailed explanation of how to define the message area and supply required arguments to send messages using the BEA MessageQ API or scripts.
Specifically, this chapter addresses the following topics:
The simplest way to establish and maintain a connection between SNA and CICS applications is through the LU6.2 Port Server. The Port Server uses predefined messages to help you set up and manage the application connections between BEA MessageQ clients and remote partners.
If the standard LU6.2 port server programming interface does not meet all application needs, a specialized port server can be developed using the LU6.2 User Callback Services.
The LU6.2 User Callback allows you to engage in APPC conversations between any OpenVMS application program and one or more CICS transaction programs using BEA MessageQ pams_put_msg and pams_get_msg callable services. The remote CICS transaction program appears to the OpenVMS program as a source and recipient of BEA MessageQ messages.
Note: Unlike applications that use the LU6.2 Port Server, all applications using the LU6.2 User Callback Services must reside on an OpenVMS platform.
The LU6.2 User Callback uses a set of predefined messages to define and delete LUs, establish LU6.2 conversations, send and receive data, request and send confirmations, and process errors.
The APPC verb set consists of 21 BEA MessageQ messages. The verb flow logic is the same, regardless of whether you are programming in an OpenVMS or IBM environment.
Some of the messages are both sent by the pams_put_msg call and received by the pams_get_msg call.
Each message sent or received by the LU6.2 User Callback is prefixed by a header. Some user callback messages contain no fields other than the header fields. In this case, the type of message is sufficient to cause the desired action.
Conversations can be initiated either by an OpenVMS program, which is called inbound conversation allocation; or by a CICS transaction program, which is called outbound conversation allocation. Each user program can have a maximum of 256 conversations active at any time.
Note: To use the LU6.2 User Callback interface, the OpenVMS programmer should have general knowledge of APPC and the CICS programmer should have specific knowledge of CICS APPC. Because the OpenVMS programmer uses the familiar BEA MessageQ interface to perform the APPC functions, no knowledge of the DECnet/SNA OpenVMS APPC/LU6.2 Programming Interface is required.
The tool kit provided with the BEA MessageQ LU6.2 Services contains the object library (DMQLU62_LIB.OLB), PAMSLU62_MSG message structures, and the DMQLU62_TEST.C example program.
The following messages are issued by the LU6.2 User Callback:
Using the LU6.2 User Callback Interface
The LU6.2 User Callback interface is initialized by sending an LU62_INIT message. Remote LUs are defined by sending one or more LU62_DEFINE_LU messages. The User Callback returns the LU62_DEFINE_LU message if the define operation is successful. It returns an LU62_ERROR message if the define operation is not successful. A data field in the LU62_DEFINE_LU message indicates whether the LU is to be used for inbound or outbound conversations.
Multithreading Services
BEA MessageQ LU6.2 supports the development of multithread servers (for example, the LU6.2 port server). Multithreading is based on the use of context information in the special LU6.2 message header.
The LU62_REQUESTER and LU62_CONV_ID fields in the LU6.2 message header allow a process to handle multiple concurrent LU6.2 conversations. The LU62_CONV_ID uniquely identifies each active conversation. The LU62_REQUESTER identifies the originator of an LU62_DEFINE_LU, LU62_DEFINE_TP, LU62_ALLOCATE, and LU62_ACTIVATE. If a session terminates abnormally while a conversation is not active, the LU62_REQUESTER value is returned in the LU62_ERROR message.
Inbound Conversations
An inbound (to CICS) conversation is requested using the LU62_ALLOCATE message. The User Callback returns one of the following messages:
The LU62_ALLOCATE message returns a unique conversation ID for this conversation in the LU62_CONV_ID field. This value is returned by the User Callback for each conversation allocated. The OpenVMS programmer must keep track of the conversation ID (LU62_CONV_ID) for each active conversation.
After a successful LU62_ALLOCATE message, the remaining message types can be used to conduct the conversation.
Outbound Conversations
An outbound conversation is requested by CICS transaction programs. For a CICS transaction program to allocate a conversation with an OpenVMS transaction program, the OpenVMS transaction program must perform the following operations:
When a remote CICS transaction program allocates a conversation with one of the TPNs, the OpenVMS transaction program receives an LU62_CONNECTED message. The local LU name of the LU that received the connection is returned in the
LU62_CONNECTED_LU_NAME field.
The LU62_CONNECTED message also returns a unique conversation ID for this conversation in the LU62_CONV_ID field. This value is returned by the User Callback for each conversation allocated. The OpenVMS programmer must keep track of the LU62_CONV_ID for each active conversation.
Following receipt of an LU62_CONNECTED message, the remaining message types can be used to conduct the conversation.
Example of User Callback Message Flow
Table 6-1 shows a typical message exchange between a BEA MessageQ client and the LU6.2 User Callback. The "Messages Sent to User Callback:" column lists the messages that a BEA MessageQ client sends to the User Callback. The "Messages Received from User Callback:" column lists the messages that the User Callback sends back to the BEA MessageQ client in response to messages received from the client.
|
Table 6-1 BEA MessageQ Client-User Callback Message Exchange
|
|
|
Messages Sent to |
Messages Received |
|
LU62_INIT |
|
|
LU62_DEFINE_LU |
|
|
LU62_DEFINE_LU |
|
|
LU62_ALLOCATE |
|
|
LU62_ALLOCATE |
|
|
LU62_SEND_DATA . . |
|
|
LU62_SEND_DATA |
|
|
LU62_CONFIRM_RECV |
|
|
LU62_CONFIRMED |
|
|
LU62_RECV_DATA . . |
|
|
LU62_RECV_DATA |
|
|
LU62_CONFIRM_REQ |
|
|
LU62_DEALLOCATE |
|
|
LU62_DEALLOCATED |
|
|
-DONE- |
|
APPC User Callback Messages
The following sections describe APPC User Callback messages (verbs) individually. As an example, Figure 6-1 shows the session logic and corresponding OpenVMS (SNA), IBM (CICS), and BEA MessageQ messages (verbs) used in designing a distributed transaction.
Figure 6-1 BEA MessageQ LU6.2 Session-Typical Verb Sequence
When sent to the CICS (IBM) partner, the LU62_ACTIVATE message explicitly activates an SNA session on the LU indicated in the LU62_ACTIVATE_LOCAL_LU field.
Note: The behavior of the LU62_ACTIVATE message depends on the value of the LU62_DEFINE_INIT_TYPE field provided when the LU specified in the message was defined.
For LUs defined with LU62_DEFINE_INIT_TYPE = 1, the LU62_ACTIVATE message enables the LU for outbound (from CICS) session activation. The LU is reserved at the gateway, but an SNA session is not started until a transaction program from the remote system requests one.
For all other values of LU62_DEFINE_INIT_TYPE, the LU62_ACTIVATE message causes the creation of an SNA session on the specified LU. After a session is activated, it is available for use by either partner.
When received from the CICS (IBM) partner, the LU62_ACTIVATE message indicates that a previous request to activate a session has been completed by the interface.
C Message Structure
struct lu62_activate_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_activate_local_lu [8];
char lu62_activate_polarity;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_REQUESTER |
longword |
Identifies the originator of an LU62_ACTIVATE request. This field is returned to the user with the status of the request. A copy of the request is returned to the user if the request is successful. The LU62_ERROR message is returned to the user if the request is unsuccessful. This value is ignored by the User Callback Interface. This field is intended for use in building applications that handle multiple concurrent conversations. In the event of an abnormal session termination while a conversation is not active, this value is returned on the LU62_ERROR message that contains the PAMSLU62_SESSFAILED error code (described in LU6.2 User Callback Interface Logical Names and Error Codes.). |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_ACTIVATE_LOCAL_LU |
text 8 char |
The LU name identifying the session to be activated. The LU62_DEFINE_SESSION field must have been explicitly defined in the LU62_DEFINE_LU message that defined the LU name. |
|
LU62_ACTIVATE_POLARITY |
byte |
Indicates the contention status for the conversation. Valid values are: 0-OpenVMS application is the winner in a contention situation 1-OpenVMS application must bid for access in a contention situation Note: If a session is activated with the LU62_ACTIVATE message, subsequent LU62_ALLOCATE messages must specify the same value for polarity. In other words, the values of LU62_ACTIVATE_POLARITY and LU62_ALLOCATE_POLARITY must be the same. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLASS_APPC |
UCB_CLASS_APPC |
|
Type |
MSG_TYPE_LU62_ACTIVATE |
MSG_TYPE_LU62_ACTIVATE |
LU62_ALLOCATE
When sent to the CICS (IBM) partner, the LU62_ALLOCATE message requests an APPC conversation with the CICS transaction program. The conversation uses LUs defined in the 8-byte LU62_ALLOCATE_LOCAL_LU field and in the 8-byte LU62_TPN field, respectively.
The TPN must be in EBCDIC data format. To translate to this format, use LIB$ASC_TO_EBC.
The TPN must be accessible through the specified LU, which means that the local LU name must already be successfully defined using the LU62_DEFINE_LU message.
When received from the CICS (IBM) partner, the LU62_ALLOCATE message indicates that a previous request to allocate conversation completed successfully. The LU62_CONV_ID field contains the unique conversation ID used to manage this conversation. The LU62_REQUESTER field returns whatever value was placed there in the LU62_ALLOCATE message sent to the User Callback. This provides a way to manage multiple, concurrent conversations.
C Message Structure
struct lu62_alloc {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_allocate_local_lu [8];
char lu62_allocate_username [10];
char lu62_allocate_password [10];
char lu62_allocate_profile [10];
char lu62_allocate_sync_level;
char lu62_allocate_polarity;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_REQUESTER |
longword |
Identifies the originator of an LU62_ALLOCATE request. This field is returned to the user with the status of the request. A copy of the request is returned to the user if the request is successful. The LU62_ERROR message is returned to the user if the request is unsuccessful. This value is ignored by the User Callback interface. This field is intended for use in building applications that handle multiple concurrent conversations. In the event of an abnormal session termination while a conversation is not active, this value is returned on the LU62_ERROR message that contains the PAMSLU62_SESSFAILED error code. (Error codes are described in LU6.2 User Callback Interface Logical Names and Error Codes.) |
|
LU62_TPN |
text 8 |
Identifies the TPN with whom a user wants a conversation. This value must be in EBCDIC data format. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_ALLOCATE_LOCAL_LU |
text 8 |
The LU name identifying the session to be used for the requested conversation. |
|
LU62_ALLOCATE_USERNAME |
text 10 |
The ASCII value of the user ID to be presented to the remote application for authorization. |
|
LU62_ALLOCATE_PASSWORD |
text 10 |
The ASCII value of the password to be presented to the remote application for authorization. |
|
LU62_ALLOCATE_PROFILE |
text 10 |
The ASCII value of the profile to be presented to the remote application for authorization. |
|
LU62_ALLOCATE_SYNC_LEVEL |
byte |
Indicates the permitted sync-level on the conversation if DMQLU62$SELECT_SYNC is defined. Valid values are: 0-SYNC_LEVEL=NONE |
|
LU62_ALLOCATE_POLARITY |
byte |
Indicates the status for the conversation. Valid values are: 0-OpenVMS application is the winner in a contention situation Note: If a session is activated with the LU62_ACTIVATE message, then subsequent LU62_ALLOCATE messages must specify the same value for polarity. In other words, the value of LU62_ALLOCATE_POLARITY and LU62_ACTIVATE_POLARITY must be the same. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLAS_APPC |
UCB_CLAS_APPC |
|
Type |
MSG_TYPE_LU62_ALLOCATE |
MSG_TYPE_LU62_ALLOCATE |
LU62_CONFIRMED
The LU62_CONFIRMED message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has issued a CONFIRM in response to a CONFIRM request from the OpenVMS program. The LU62_CONFIRMED message has the header field only.
C Message Structure
struct lu62_confirmed_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ;
Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_CONFIRM_RECV
The LU62_CONFIRM_RECV message sends a PREPARE_TO_RECEIVE, TYPE=SYNC_LEVEL indicator on the conversation specified in the message.
This message is typically used to reverse the direction of the conversation. On successful issue of this message and receipt of an LU62_CONFIRMED message from the User Callback, an OpenVMS program can receive data from the CICS transaction program.
Note: The behavior of this message is affected by disabling
SYNC_LEVEL=CONFIRM with the logical
DMQLU62$DISABLE_CONFIRM. The logical must be set before program activation.
If SYNC_LEVEL=CONFIRM is disabled, then the LU62_CONFIRMED message indicates that the OpenVMS program is now in a receive state.
C Message Structure
struct lu62_confirm_recv_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ;
Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_CONFIRM_REQ
The LU62_CONFIRM_REQ message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has issued a CONFIRM. The LU62_CONFIRM_REQ message has the header field only.
C Message Structure
struct lu62_confirm_req_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_CONFIRM_SEND
The LU62_CONFIRM_SEND message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has issued a PREPARE_TO_RECEIVE, TYPE=SYNC_LEVEL, with the current SYNC_LEVEL set to CONFIRM.
The OpenVMS program can now issue a CONFIRM by sending an LU62_CONFIRM message on the specified conversation. Sending the CONFIRM places the conversation in the send state: the OpenVMS user program can then send data (using the LU62_SEND_DATA message) on this conversation.
C Message Structure
struct lu62_send_confirm_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ;
Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_CONNECTED
When received, the LU62_CONNECTED message indicates that a remote LU6.2 partner has allocated a conversation with one of the TPNs defined with a previously issued LU62_DEFINE_TP message. The LU62_REQUESTER field in the header of the LU62_CONNECT message is provided in the LU62_DEFINE_TP message for the TPN that was attached. The LU62_CONNECT_LOCAL_LU field contains the local LU name for the LU that has received the connection.
C Message Structure
struct lu62_connected_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_connected_lu_name [8];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONNECTED_LU_NAME |
text 8 |
The ASCII value of the name of the LU that received the connection. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
NA |
Client |
|
Source |
NA |
UCB |
|
Class |
NA |
APPC |
|
Type |
NA |
MSG_TYPE_LU62_CONNECTED |
LU62_DEALLOCATE
The LU62_DEALLOCATE message sends a DEALLOCATE to a remote partner in the conversation.
C Message Structure
struct lu62_deallocate_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
int16 lu62_abend_flag;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_ABEND_FLAG |
word |
If LU62_ABEND_FLAG= -1, this message sends a DEALLOCATE, TYPE=ABEND_PROG on the conversation specified in the LU62_CONV_ID field in the message. This causes the conversation to terminate abnormally. All other values for LU62_ABEND_FLAG cause this message to send a DEALLOCATE, TYPE=SYNC_LEVEL. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
Client |
NA |
|
Source |
UCB |
NA |
|
Class |
APPC |
NA |
|
Type |
MSG_TYPE_LU62_DEALLOCATED |
NA |
LU62_DEALLOCATED
The LU62_DEALLOCATED message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has deallocated normally. The LU62_DEALLOCATED message has the header field only.
C Message Structure
struct lu62_deallocated_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None.
See Also
LU62_DEALLOCATE
LU62_DEFINE_LU
When sent to the CICS (IBM) partner, the LU62_DEFINE_LU message defines a remote SNA resource. Resources must be defined using the LU62_DEFINE_LU message before they can be used to allocate conversations.
When received from the CICS (IBM) partner, the LU62_DEFINE_LU message indicates that a previous request to define the LU, specified in the 8-byte LU62_DEFINE_LOCAL_LU field, completed successfully.
C Message Structure
struct lu62_define_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_define_local_lu [8];
char lu62_define_lu_password [8];
char lu62_define_gateway [6];
char lu62_define_accname [8];
char lu62_define_circuit [5];
int16 lu62_define_session;
char lu62_define_applid [8];
char lu62_define_logmode [8];
char lu62_define_user_data [128];
int16 lu62_define_init_type;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_REQUESTER |
longword |
This field identifies the originator of an LU62_DEFINE_LU request. The field is returned to the user with the status of the request. A copy of the request is returned to the user if the request is successful. The LU62_ERROR message is returned to the user if the request is unsuccessful. This value is ignored by the User Callback Interface. This field is intended for use in building applications that handle multiple concurrent conversations. In the event of an abnormal session termination while a conversation is not active, this value is returned on the LU62_ERROR message that contains the PAMSLU62_SESSFAILED error code. (Error codes are described in LU6.2 User Callback Interface Logical Names and Error Codes.) |
|
LU62_CONV_ID |
longword |
This field identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_DEFINE_LOCAL_LU |
text 8 |
The ASCII value of the name specified by the user for the specified remote LU. |
|
LU62_DEFINE_LU_PASSWORD |
text 8 |
The ASCII value of the password for the remote LU. |
|
LU62_DEFINE_GATEWAY |
text 6 |
The ASCII value of the DECnet/SNA gateway through which a specified LU is to be accessed. |
|
LU62_DEFINE_ACCNAME |
text 8 |
The ASCII value of the specified gateway that defines the remote LU to be accessed. If this field is specified, the following fields can be optional: LU62_DEFINE_CIRCUIT The values specified in these fields are site-specific and must be obtained from the person responsible for DECnet/SNA gateway administration at the user site. |
|
LU62_DEFINE_CIRCUIT |
text 5 |
The ASCII value of the circuit on the specified gateway that provides the physical connection over which the remote LU is to be accessed. |
|
LU62_DEFINE_SESSION |
word |
The DECnet/SNA gateway session address number (1-255) when accessing the specified remote LU. This field is required for all LUs that are explicitly activated by an LU62_ACTIVATE message. |
|
LU62_DEFINE_APPLID |
text 8 |
The ASCII value of the VTAM application that owns the specified remote LU. |
|
LU62_DEFINE_LOGMODE |
text 8 |
The ASCII value of the VTAM LOGON MODE table entry that accesses the specified remote LU. |
|
LU62_DEFINE_USER_DATA |
text 128 |
Up to 128 bytes of variable data to be passed when accessing the remote LU. This data is not interpreted by the User Callback; it must be presented in the format expected by the remote application. |
|
LU62_DEFINE_INIT_TYPE |
word |
A short integer indicating whether the LU is used for inbound or outbound session activation. Valid values are: |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLAS_APPC |
UCB_CLAS_APPC |
|
Type |
MSG_TYPE_LU62_DEFINE_LU |
MSG_TYPE_LU62_DEFINE_LU |
LU62_DEFINE_TP
When sent to the CICS (IBM) partner, the LU62_DEFINE_TP message defines a TPN for use in accepting outbound conversation allocation requests from CICS transaction programs. The value entered in the LU62_REQUESTER field is returned in the LU62_CONNECTED message (in the same field) when a remote CICS transaction program is allocated using this TPN. This provides a way to distinguish between allocated TPNs when multiple TPNs are defined.
When received from the CICS (IBM) partner, the LU62_DEFINE_TP message indicates that a previous request to define the TPN has completed successfully.
C Message Structure
struct lu62_define_tp_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_define_tp_tpn [8];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_REQUESTER |
longword |
This field identifies the originator of an LU62_DEFINE_TP request. The field is returned to the user with the status of the request. If the request is successful, the user receives a copy of the request. If the request is unsuccessful, the LU62_ERROR message is returned to the user. This value is ignored by the User Callback interface. This field is intended for use in building applications that handle multiple concurrent conversations. If the event is terminated abnormally while a conversation is not active, this value is returned in the LU62_ERROR message that contains the PAMSLU62_SESSFAILED error code. (Error codes are described in LU6.2 User Callback Interface Logical Names and Error Codes.) |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_DEFINE_TP_TPN |
text 8 |
The TPN |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLAS_APPC |
UCB_CLAS_APPC |
|
Type |
MSG_TYPE_LU62_DEFINE_TP |
MSG_TYPE_LU62_DEFINE_TP |
LU62_DELETE_LU
When sent to the CICS (IBM) partner, the LU62_DELETE_LU message deletes the LU identified in the 8-byte LU62_DELETE_LOCAL_LU field. This message terminates any SNA session active on the specified LU and unbinds the SNA session, freeing up the associated gateway.
If the message is successful, the LU62_DELETE_LU message is returned. If the message is unsuccessful, the LU62_ERROR message is returned.
It is not necessary to send an LU62_DELETE_LU message unless you want to explicitly unbind the SNA session. A previously established session is available to the user program for reuse in establishing conversations with the specified LU following a successful LU62_DEALLOCATED message.
Note: An LU62_DELETE_LU message sent while a conversation is active on the LU specified for deletion causes the DECnet/SNA APPC/LU6.2 interface to enter a Wait state until the remote transaction program deallocates or unbinds the SNA session. This blocks the user process until the LU62_DELETE_LU operation is complete.
When received from the CICS (IBM) partner, the LU62_DELETE_LU message indicates that the specified LU has been successfully deleted.
C Message Structure
struct lu62_delete_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_delete_local_lu [8];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_DELETE_LOCAL_LU |
text 8 |
The ASCII value of the name specified by the user for the specified remote LU. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLAS_APPC |
UCB_CLAS_APPC |
|
Type |
MSG_TYPE_LU62_DELETE_LU |
MSG_TYPE_LU62_DELETE_LU |
LU62_ERROR
The LU62_ERROR message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has signaled an error or that the User CallbackUser Callback encountered a fatal error on the specified conversation and deallocated. The LU62_ERROR field contains the returned status value. The exact circumstances can be determined from the LU62_ERROR_CODE field values.
C Message Structure
struct lu62_error_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
int32 lu62_error_code;
int32 lu62_error_vector [16];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_ERROR_CODE |
longword |
Contains the primary error received from the User Callback on an LU62_ERROR message. The error codes are:
Each of these values indicates that the remote process has signaled an error. The receipt of these LU62_ERROR_CODE values changes the current state to RECEIVE. This message indicates that the buffer is too small to contain the received message. This value does not change the current state. All other errors are treated as fatal by the User Callback and result in the immediate deallocation of the conversation on which the error was received.
|
|
LU62_ERROR_VECTOR |
longword |
Contains the secondary error information, if any. This is a 16-element longword array. The LU62_ERROR_VECTOR array contains the error vector returned (if applicable). This can be processed by the user or displayed directly with the SYS$PUTMSG system service. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
NA |
Client |
|
Source |
NA |
UCB |
|
Class |
NA |
UCB_CLAS_APPC |
|
Type |
NA |
MSG_TYPE_LU62_ALLOCATE |
LU62_INIT
The LU62_INIT message initializes the LU6.2 User Callback. Logical names for tracing and buffer allocation are translated when the LU62_INIT message is processed. The LU62_INIT message has the header field only.
C Message Structure
struct lu62_init {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
}; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None.
LU62_OK_TO_SEND
The LU62_OK_TO_SEND message indicates that the remote partner on the conversation specified in the LU62_CONV_ID field has entered the receive state in response to a REQUEST_TO_SEND from the OpenVMS transaction program. The OpenVMS transaction is now in the send state and can send the data.
C Message Structure
struct lu62_ok_to_send_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_RECV_DATA
The LU62_RECV_DATA message contains a data block received on the conversation specified in the LU62_CONV_ID field.
C Message Structure
struct lu62_recv_data_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_data_message [31982];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
LU62_MSG_LEN |
word |
Contains the length of the data block that was received. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_DATA_MESSAGE |
text 1-31982 |
Contains the data block received. The length of the block is contained in the LU62_MSG_LEN field in the message header. The message size is limited to 31,982 bytes, which is 32,000 (the maximum size of User Callback buffers) minus 18 (the size of the header). |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
Client |
|
Source |
Client |
UCB |
|
Class |
MSG_CLAS_APPC |
UCB_CLAS_APPC |
|
Type |
MSG_TYPE_LU62_RECV_DATA |
MSG_TYPE_LU62_RECV_DATA |
LU62_REQ_CONFIRM
The LU62_REQ_CONFIRM message issues a CONFIRM on the conversation specified in the LU62_CONV_ID field contained in the message, provided that SYNC_LEVEL=CONFIRM processing is not disabled.
This message is discarded if SYNC_LEVEL=CONFIRM processing has been disabled using the DMQLU62$DISABLE_CONFIRM logical name.
C Message Structure
struct lu62_req_confirm_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None.
LU62_REQ_TO_SEND
When sent to the CICS (IBM) partner, the LU62_REQ_TO_SEND message issues a REQUEST_TO_SEND on the conversation specified in the LU62_CONV_ID field in the message.
When received from the CICS (IBM) partner, the LU62_REQUEST_TO_SEND message indicates that the remote partner on the conversation has issued a REQUEST_TO_SEND.
C Message Structure
struct lu62_req_confirm_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_SEND_CONFIRM
The LU62_SEND_CONFIRM message sends a CONFIRM on the conversation specified in the LU62_CONV_ID field.
C Message Structure
struct lu62_send_confirm_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
Arguments
None
LU62_SEND_DATA
The LU62_SEND_DATA message sends the data block contained in the message on the conversation specified in the LU62_CONV_ID field.
C Message Structure
struct lu62_send_data_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
char lu62_data_message [31982];
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
LU62_MSG_LEN |
word |
Contains the length of the data block that was sent. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_DATA_MESSAGE |
text 1-31982 |
Contains the data block to send. The message size is limited to 31,982 bytes, which is 32,000 bytes (UCB buffer maximum size) minus 18 bytes (the header). |
Arguments
None.
LU62_SEND_ERROR
The LU62_SEND_ERROR message sends a SEND_ERROR on the conversation specified in the message. This notifies the remote program that an error has occurred and places the conversation in a send state.
C Message Structure
struct lu62_send_error_struct {
struct {
int32 lu62_requester;
int32 lu62_conv_id;
char lu62_tpn [8];
int16 lu62_msg_len;
} lu62_header_struct;
int32 lu62_error_code;
} ; Message Data Fields
|
Header Fields |
||
|
Field |
Data Type |
Description |
|
LU62_CONV_ID |
longword |
Identifies the conversation involved in the request. |
|
Message Fields |
||
|
Field |
Data Type |
Description |
|
LU62_ERROR_CODE |
longword |
Contains the primary error received from the User Callback on an LU62_ERROR message. |
Arguments
|
Argument |
pams_put_msg Format |
pams_get_msg Format |
|
Target |
UCB |
NA |
|
Source |
Client |
NA |
|
Class |
MSG_CLAS_APPC |
NA |
|
Type |
MSG_TYPE_LU62_SEND_ERROR |
NA |
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|