LU 6.2 API Application Programmer’s Reference Manual HP 3000 MPE/iX Computer Systems Edition 3 Manufacturing Part Number: 30294-90008 E0692 U.S.A.
Notice The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Contents 1. The SNA Network and LU 6.2 API Systems Network Architecture (SNA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Peer-to-Peer Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Units (LUs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LU Type 6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Receive State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Confirm State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 Confirm Send State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 Confirm Deallocate State . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Status Info Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 MCFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Status Info Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 MCSendError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Parameters for Future Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Mask Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Parameter Mask in TPs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 8
Figures Figure 1-1 . Node Types in an SNA Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Figure 1-2 . Type 2.1 Nodes in an SNA Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Figure 1-3 . Logical Mapping of LUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Figure 2-1 . One-Way Phone Conversation Without Confirm . . . . . . . . . . . . . . . . . . . . . . 28 Figure 2-2 .
Figures Figure B-2 . Structure of Example COBOL II Program. . . . . . . . . . . . . . . . . . . . . . . . . . .161 Figure B-3 . Structure of Example Pascal Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables Intrinsics Used in Example Conversations 37 LU 66.2 API Intrinsics 46 Control Operator Intrinsics 47 Conversation States 49 Reset State Intrinsics 50 Send State Intrinsics 51 Receive State Intrinsics 53 Confirm State Intrinsics 54 Confirm Send State Intrinsics 55 Confirm Deallocate State Intrinsics 56 Confirm Deallocate State Intrinsics 57 Data Types for COBOL II and Transact 65 Data Types for Pascal and C 65 LU 6.2 API TP Instrinsics 68 LU 6.
Tables 12
Preface This manual serves two purposes: It is a training manual for programmers who wish to create LU 6.2 API applications, and it also serves as a reference manual. NOTE The information in this manual can be used to create LU 6.2 API applications on MPE V systems or MPE XL systems. Any differences between LU 6.2 API on MPE V and LU 6.2 API on MPE XL are noted in the manual.
Audience The audience for this manual is the HP 3000 applications programmer who will participate in writing an LU 6.2 API application. The programmer is assumed to have little or no knowledge of data communications or the IBM environment. For more information in these areas, see the list of related publications at the end of this preface.
Organization This manual is divided into the following sections and appendices: Chapter 1, The SNA Network and LU 6.2 API, gives an overview of the SNA environment and Advanced Program-to-Program Communication. It explains the LU 6.2 architecture and Hewlett-Packard’s implementation of LU 6.2 API. Chapter 2, Conversations, describes what a conversation is and the different kinds of conversations that application programs can have. It explains the tasks necessary to establish a conversation.
Related HP Publications • COBOL II 3000 Reference Manual (32233-90001) • COBOL II 3000/XL Reference Manual (31500-60001) • Pascal 3000 Reference Manual (32106-90001) • HP Pascal Reference Manual (31502-60005) • HP C/XL Reference Manual (31506-60001) • Transact Reference Manual (32247-60003) • MPE XL Languages Migration Guides: Pascal/XL, FORTRAN 77/XL, COBOL II/XL (31502-60004) • MPE V Command Reference Manual (32033-90006) • MPE XL Commands Reference Manual (32650-60002) • MPE/V Intrinsics Reference Manual
Related IBM Publications • Systems Network Architecture Transaction Programmer’s Reference Manual for LU Type 6.
1 The SNA Network and LU 6.2 API Systems Network Architecture (SNA) IBM has established a set of protocols that govern communication between various types of machines and applications. This set of protocols is called Systems Network Architecture (SNA). SNA is an architecture designed to be independent of specific software or hardware. In SNA, machines and applications are defined only in terms of the functions they perform.
The SNA Network and LU 6.2 API Systems Network Architecture (SNA) Figure 1-1 Node Types in an SNA Network Peer-to-Peer Communication As computers have become smaller and less expensive, companies have replaced cluster controllers with computers like the HP 3000 that adhere to Node Type 2 protocols. Using an HP 3000 as a cluster controller allows a remote location to have local processing power as well as a connection to the mainframe computer.
The SNA Network and LU 6.2 API Systems Network Architecture (SNA) Figure 1-2 Type 2.1 Nodes in an SNA Network NOTE The APPC subsystem on MPE XL allows the HP 3000 to function as a Type 2.0 or Type 2.1 node. On MPE V, however, the HP 3000 functions only as a Type 2.0 node. For more information on Node Type 2.1, see the APPC Subsystem on MPE XL Node Manager’s Guide. Logical Units (LUs) A Logical Unit (LU) is the set of data communication functions required by an end user in an SNA network.
The SNA Network and LU 6.2 API Systems Network Architecture (SNA) Figure 1-3 Logical Mapping of LUs LU Type 6.2 Logical Unit types are usually used for device emulation. LU.T2 devices or applications emulate IBM 3270 terminals, and LU.T1 and LU.T3 devices or applications emulate printers. Logical Unit Type 6.2 differs from other LU types in that it does not emulate a device. LU 6.2 applications exchange raw data in a format called the generalized data stream. LU 6.
The SNA Network and LU 6.2 API Systems Network Architecture (SNA) APPC Communication between LU 6.2 applications is called Advanced Program-to-Program Communication (APPC). APPC and LU 6.2 allow programs or applications running on different processors to communicate and exchange data. When data can be processed at both ends of a communication line, fewer data transfers are necessary to perform certain transactions.
The SNA Network and LU 6.2 API Systems Network Architecture (SNA) An Example Transaction With APPC The following example is the same transaction described above, but the local computer has APPC capabilities, and an APPC application on the local system automates communication with the central mainframe. Now the clerk must perform the following tasks: 1. Log on to the local processor. 2. Run the appropriate application. 3.
The SNA Network and LU 6.2 API Hewlett-Packard’s LU 6.2 API Hewlett-Packard’s LU 6.2 API APPC allows two programs to communicate, and LU 6.2 defines the actions or verbs that each program may execute in an APPC application. The Application Program Interface (API) consists of a set of intrinsics. These intrinsics are predefined subroutines that implement the LU 6.2 architected verbs. They can be called from within application programs. Hewlett-Packard’s LU 6.
The SNA Network and LU 6.2 API Hewlett-Packard’s LU 6.
2 Conversations An LU 6.2 application is called a transaction program (TP). Transaction programs are written in pairs to communicate with each other across a network. Every TP on the HP 3000 will have at least one partner TP on a remote system that is designed to communicate with it. The communication between two TPs is called a conversation. Conversations take place across sessions.
Conversations One-Way Conversation Without Confirm One-Way Conversation Without Confirm In a one-way conversation, only one TP sends data. This section describes the simplest type of conversation: a one-way conversation without confirm. Figure 2-1 is an illustration of a one-way phone conversation without confirm. Notice that data (in this case, the message) is only transmitted in one direction.
Conversations One-Way Conversation With Confirm One-Way Conversation With Confirm In a one-way conversation with confirm, the side that sends the data requests confirmation from the receiving side that the conversation is synchronized. Figure 2-2 illustrates a one-way conversation in which the local TP asks the remote TP for confirmation that it received all the data the local TP sent.
Conversations Two-Way Conversation Without Confirm Two-Way Conversation Without Confirm In a two-way conversation, both sides send and receive data. Because the two sides must take turns talking, they use the following protocol: 1. Only one person can talk at a time. 2. The person that initiated the conversation talks first after communication is established. 3. The person talking must relinquish control before the other person can speak. 4.
Conversations Two-Way Conversation With Confirm Two-Way Conversation With Confirm In a two-way conversation with confirm, the sending side issues a confirmation request and must wait for confirmation from the receiving side before transmitting any more information. Figure 2-4 is an illustration of a two-way conversation with confirm.
Conversations Establishing Conversations Establishing Conversations TP conversations can be locally initiated (initiated by the TP on the HP 3000), or remotely initiated (initiated by the TP on the remote system). This section describes the tasks that the local application programmer, the node manager, and the remote application programmer must perform in order to establish a locally or remotely initiated conversation.
Conversations Establishing Conversations 1. Configure an appropriate session type. For information on configuring session types, see the APPC Subsystem on MPE XL Node Manager’s Guide or the LU 6.2 API/V Node Manager’s Guide. 2. Tell the application programmer the name of the session type. The programmer must code the name of the session type into the local TP. 3. Activate a session of the appropriate session type, or configure one for automatic activation at subsystem startup.
Conversations Establishing Conversations 5. Ask the node manager for the name of the job file that runs the local TP, and tell the programmer on the remote system what the job file name is. The remote system must send the name of the job file in the allocate request. Node Manager Tasks To prepare for a remotely initiated conversation on MPE V, the node manager must do the following: 1. Configure an appropriate session type. See the LU 6.
Conversations Establishing Conversations a. If the local TP is configured to conduct multiple remotely initiated conversations, and if it is already active and in conversation, the APPC subsystem must queue the allocate request until the local TP finishes the current conversation and calls the MCGetAllocate intrinsic again. If the local TP is not currently running, the APPC subsystem must stream the job that runs the local TP. b.
Conversations Establishing Conversations 6. Tell the node manager the executable file name of the TP. The executable file may reside in any group and account. The node manager will create a job to run the TP. 7. Tell the node manager whether the TP calls the MCGetAllocate intrinsic multiple times or only once. The node manager must configure the TP to accept either single or queued allocate requests. 8. Decide whether you want to start the TP yourself or have the APPC subsystem start the TP.
3 Using Intrinsics Chapter 2 , “Conversations,” introduced the types of conversations in which transaction programs can participate. This chapter explains how LU 6.2 API intrinsics are used to create the conversations described in Chapter 2 , “Conversations.” Table 3-1 lists the intrinsics that will be discussed in this chapter. The list is a subset of the LU 6.2 API intrinsics. Chapter 5 , “Intrinsic Descriptions,” contains a complete description of all of the intrinsics.
Using Intrinsics One-Way Conversation Without Confirm One-Way Conversation Without Confirm In this section, the one-way conversation introduced in Chapter 2 , “Conversations,” is described in terms of the intrinsics you would use to create it. Figure 3-1, the one-way phone conversation without confirm, is reproduced below. In the following sections, the intrinsics used to create this conversation will be discussed and added to the illustration.
Using Intrinsics One-Way Conversation Without Confirm MCAllocate MCAllocate allocates network resources and establishes a conversation with the remote TP. After the MCAllocate intrinsic has executed, the local TP is ready to send data, and the remote TP is ready to receive it. The MCAllocate intrinsic replaces “person dials number,” as shown in Figure 3-2.
Using Intrinsics One-Way Conversation Without Confirm MCSendData The MCSendData intrinsic is the vehicle used by the local TP to send information to the remote TP. The MCSendData intrinsic replaces “person gives message,” as shown in Figure 3-3.
Using Intrinsics One-Way Conversation Without Confirm MCDeallocate The local TP calls MCDeallocate to end the conversation and deallocate the resources used by the conversation. The MCDeallocate intrinsic replaces “person hangs up,” as shown in Figure 3-4.
Using Intrinsics One-Way Conversation With Confirm One-Way Conversation With Confirm The synchronization level of a conversation (whether it will use confirm or not) is established when the conversation is initiated, in a parameter of the MCAllocate intrinsic. Figure 3-5 illustrates a one-way conversation with confirm, using the MCConfirm intrinsic. MCConfirm The MCConfirm intrinsic sends a confirmation request to the remote TP and waits for a response.
Using Intrinsics Two-Way Conversation Without Confirm Two-Way Conversation Without Confirm In order to carry on a two-way conversation, a TP must be able to inform its partner that it is finished sending data and is ready to receive. It also must wait for data sent by its partner and receive the data when it arrives. The two-way conversation illustrated in Figure 3-6 uses the MCPrepToRcv and MCRcvAndWait intrinsics as well as the intrinsics already introduced.
Using Intrinsics Two-Way Conversation Without Confirm Figure 3-6 Using MCPrepToRcv and MCRcvAndWait 44 Chapter 3
Using Intrinsics Two-Way Conversation With Confirm Two-Way Conversation With Confirm Figure 3-7 illustrates a two-way conversation with confirm. Notice that, in this example, the MCDeallocate intrinsic is used to request confirmation, wait for a confirmation response, and then deallocate the conversation. This type of deallocation is specified by setting the DeallocateType parameter of the MCDeallocate intrinsic to CONFIRM.
Using Intrinsics LU 6.2 API Intrinsics LU 6.2 API Intrinsics LU 6.2 API intrinsics are used to set up the resources for distributed transactions, allocate and conduct conversations between transaction programs, and release LU 6.2 resources after transactions have completed. Table 3-2 lists all the LU 6.2 API intrinsics and gives a brief description of each. Table 3-2 LU 66.2 API Intrinsics Intrinsic Definition TPStarted Initializes access to the LU 6.
Using Intrinsics Control Operator Intrinsics Control Operator Intrinsics In addition to the intrinsics used by transaction programmers, LU 6.2 API/XL provides a set of control operator intrinsics that allow node managers and system managers to control APPC sessions and manage the APPC subsystem. The control operator intrinsics are described in detail in the APPC Subsystem on MPE XL Node Manager’s Guide. Table 3-3 lists the control operator intrinsics and gives a brief description of each.
Using Intrinsics Control Operator Intrinsics 48 Chapter 3
4 Conversation States Conversation states indicate the status of each side of a conversation. Application programmers on different processors use conversation states to discuss how their TPs will communicate. Certain intrinsics (or verbs, depending on the implementation) can be called from each state, and control information is exchanged through parameters of the intrinsics. Control information sent by the remote TP may determine the state of the local side of the conversation.
Conversation States Reset State Reset State A TP calls the TPStarted intrinsic to gain access to LU 6.2 API. Once TPStarted has executed successfully, the TP is in Reset state. Reset state is the only state associated with the entire TP. The remainder of the states are associated with individual conversations. From Reset state, a TP can call either MCAllocate or MCGetAllocate to allocate a conversation with a remote TP.
Conversation States Send State Send State In Send state, a TP controls the conversation. A TP in Send state stays in Send state unless it requests to enter another state or the remote TP detects an error and forces the local TP to enter another state. Table 4-3 lists all the intrinsics that can be called from Send state. It also indicates what state the local TP is in after each intrinsic executes successfully.
Conversation States Receive State Receive State In Receive state, a local TP can receive data and control information from a remote TP. A local TP can enter Receive state from Send state by calling either MCPrepToRcv or MCRcvAndWait. Both of these intrinsics cause the local side of the conversation to change from Send state to Receive state and the remote side to change from Receive state to Send state.
Conversation States Receive State Table 4-4 Receive State Intrinsics Intrinsic State Entered Upon Successful Execution MCDeallocate DeallocateType= 2 (ABEND) Reset MCErrMsg Receive MCGetAttr Receive MCPostOnRcpt Receive MCRcvAndWait or MCRcvNoWait WhatReceived= { 1 (DATA_COMPLETE) } { 2 (DATA_INCOMPLETE) } { 4 (SEND) } { 5 (CONFIRM) } { 6 (CONFIRM_SEND) } { 7 (CONFIRM_DEALLOCATE) } Receive Receive Send Confirm Confirm Send Confirm Deallocate MCReqToSend Receive MCSendError Send MCTest R
Conversation States Confirm State Confirm State A local TP enters Confirm state from Receive state whenever it receives a confirmation request from the remote TP. Table 4-5 lists the intrinsics that can be called from Confirm state. The MCDeallocate intrinsic can be called from Confirm state only with the DeallocateType parameter set to 2 (ABEND). See the description of MCDeallocate in Chapter 5 , “Intrinsic Descriptions,” for more information.
Conversation States Confirm Send State Confirm Send State A TP enters Confirm Send state from Receive state when the remote TP issues the equivalent of the MCPrepToRcv intrinsic with a confirmation request, asking the local TP to respond to the confirmation request and enter Send state. Table 4-6 lists the intrinsics that can be called from Confirm Send state. The MCDeallocate intrinsic can be called from Confirm Send state only with the DeallocateType parameter set to 2 (ABEND).
Conversation States Confirm Deallocate State Confirm Deallocate State A TP enters Confirm Deallocate state from Receive state when it calls MCRcvAndWait or MCRcvNoWait and the WhatReceived parameter returns 7 (CONFIRM_DEALLOCATE). This indicates that the remote TP has issued the equivalent of the MCDeallocate intrinsic with a confirmation request. Table 4-7 lists the intrinsics that can be called from Confirm Deallocate state.
Conversation States Deallocate State Deallocate State The local TP enters Deallocate state when it encounters an error condition or when the remote TP deallocates the conversation. Table 4-8 lists the intrinsics that can be called from Deallocate state. The MCDeallocate intrinsic can be called from Deallocate state only with the DeallocateType parameter set to 5 (LOCAL). See the description of MCDeallocate in Chapter 5 , “Intrinsic Descriptions,” for more information.
Conversation States One-Way Conversation Without Confirm One-Way Conversation Without Confirm Figure 4-1 shows the state transitions for a one-way conversation without confirm.
Conversation States One-Way Conversation With Confirm One-Way Conversation With Confirm Figure 4-2 shows the state transitions for a one-way conversation with confirm.
Conversation States Two-Way Conversation Without Confirm Two-Way Conversation Without Confirm Figure 4-3 shows the state transitions for a two-way conversation without confirm.
Conversation States Two-Way Conversation With Confirm Two-Way Conversation With Confirm Figure 4-4 shows the state transitions for a two-way conversation with confirm.
Conversation States Two-Way Conversation With Confirm 62 Chapter 4
5 Intrinsic Descriptions This chapter describes all the LU 6.2 API intrinsics. It is divided into the following sections: The Syntax Conventions section explains how formatting and typefaces are used to describe the intrinsics and their parameters. The Parameter Data Types section defines the mnemonics listed above the intrinsic parameters. These mnemonics indicate the data types of the parameters. The Status Parameter section explains the fields of the Status parameter, used by all LU 6.2 API intrinsics.
Intrinsic Descriptions Syntax Conventions Syntax Conventions The syntax description for each intrinsic is given in the following form: Syntax I32 I16V I16 INTRINSIC NAME (parameter1, [parameter2], parameter3) Optional parameters, like parameter2, are enclosed in square brackets. Required parameters, like parameter1 and parameter3, are not enclosed in brackets. NOTE Any optional parameters that are not used in an intrinsic call must have place holders. In most languages, a comma serves as a place holder.
Intrinsic Descriptions Parameter Data Types Parameter Data Types Above each intrinsic parameter is a mnemonic that indicates the data type of the parameter. Data types are defined generically; they are not language-specific. Table 5-1 maps each mnemonic to its generic definition, to its definition in COBOL II, and to its definition in Transact.
Intrinsic Descriptions Status Parameter Status Parameter When a TP calls an intrinsic, information about the execution of the intrinsic is returned to the TP in the Status parameter. The Status parameter is 32 bits long and is divided into two 16-bit fields: the status info field and subsystem field, as shown in Figure 5-1. Figure 5-1 Status Parameter Fields The status info field is a 16-bit integer that indicates whether an error has occurred or a message has been generated.
Intrinsic Descriptions Status Parameter Programs should be able to reference the Status parameter as a full 32-bit integer and as two 16-bit fields. After executing an intrinsic, always compare the 32-bit value in the Status parameter to zero (successful completion). If Status is not zero, compare the 16-bit value in the status info field with the numbers of any messages that can be generated by the intrinsic.
Intrinsic Descriptions TP Intrinsics TP Intrinsics In Hewlett-Packard’s implementation of the LU 6.2 architecture, the TPStarted intrinsic initializes access to LU 6.2 API and sets up the resources necessary to establish conversations. The TPEnded intrinsic terminates access to LU 6.2 API and releases all the resources used by the TP. The TP intrinsics and their descriptions are given in Table 5-3. Table 5-3 LU 6.2 API TP Instrinsics TPStarted Initializes access to LU 6.2 API and allocates resources.
Intrinsic Descriptions TPStarted TPStarted Initializes access to LU 6.2 API and allocates resources. Syntax CA I16 I32 TPStarted(LocalTPName, TPID, Status, I16 I16V CA CA [TraceOn], [TraceSize], [TraceFile], [DefaultFile]); Parameters LocalTPName Required; character array; input. This parameter is an 8-character array, left justified and padded with blanks. It identifies the name of the transaction program being executed.
Intrinsic Descriptions TPStarted from 1 through 32767 that specifies the maximum number of logical records in the user trace file. When the maximum number of records is reached, the first record is overwritten. Default: TraceFile 1024 logical records. character array; input. This character array contains an actual file designator of the trace file to be used. The TraceFile parameter is used only when tracing is turned on with the TraceOn parameter.
Intrinsic Descriptions TPStarted NOTE For remotely initiated TPs on MPE XL, the LocalTPName parameter of the TPStarted intrinsic must match the LocalTPName parameter of the MCGetAllocate intrinsic. The TraceOn parameter can have four possible values. When you are writing and debugging programs, it is useful to turn API intrinsic tracing on by setting the TraceOn parameter to 1. API intrinsic tracing is documented in Chapter 7 , “Debugging.” It will help you diagnose errors in your TP.
Intrinsic Descriptions TPEnded TPEnded Terminates access to LU 6.2 API and releases resources. Syntax I16V I32 TPEnded(TPID, Status); Parameters TPID Required; 16-bit signed integer by value; input. This number is assigned to the specific instance of the TP during the execution of the TPStarted intrinsic. (More than one instance of the same TP may be executing at once, and the TPID uniquely identifies a single instance of a TP.) Status Required; 32-bit signed integer; output.
Intrinsic Descriptions TPEnded Status Info Values 0 -1 -15 -19 -20 -90 -1002 -1003 -1040 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'TPID' parameter specified in intrinsic call. APPC subsystem is inactive. Not enough stack space for intrinsic to run. An internal error in Presentation Services has occurred. An internal error at the mapped conversation level has occurred. Required parameter missing. Conversation(s) not deallocated before calling TPEnded.
Intrinsic Descriptions Conversation Intrinsics Conversation Intrinsics This section describes the intrinsics used to manage a conversation between TPs on different processors. Table 5-4 lists the LU 6.2 API conversation intrinsics and their descriptions. Table 5-4 LU 6.2 API Conversation Intrinsics Intrinsic Definition MCAllocate Establishes a mapped conversation between TPs. MCConfirm Sends a confirmation request to the remote TP and waits for a reply.
Intrinsic Descriptions MCAllocate MCAllocate Establishes a conversation initiated by a local TP. Syntax I16V CA CA I16V MCAllocate (TPID, SessionType, RemoteTPName, RemoteTPLen, I16 I32 I16V I16V ResourceID, Status, [ReturnControl], [SyncLevel], I16V I16V I16V I16A [Timer], [Security], [NumPIPs], [PIPLengths], CA CA CA [PIP1,] [PIP2,] . . . [PIP16]); Parameters TPID Required; 16-bit signed integer by value; input.
Intrinsic Descriptions MCAllocate EBCDIC. The MPE CTRANSLATE intrinsic, or the NLTRANSLATE intrinsic on MPE XL, may be used. RemoteTPLen Required; 16-bit signed integer by value; input. This parameter contains the length, in characters, of the RemoteTPName. It must be an integer from 1 through 64. ResourceID Required; 16-bit signed integer; output. This number identifies the conversation being allocated. It must be used in all subsequent intrinsic calls, so that LU 6.
Intrinsic Descriptions MCAllocate 0 = CONFIRM Denotes that the MCConfirm and MCConfirmed intrinsics can be called. It also means that the confirm request option of any intrinsic may be used. 2 = NONE Denotes that no confirmation will be used. If a SyncLevel of 2 is specified, the MCConfirm and MCConfirmed intrinsics cannot be called during this conversation, nor can the confirm request option of any intrinsic be used during this conversation.
Intrinsic Descriptions MCAllocate NumPIPs 16-bit signed integer by value; input. This is the number (from 0 through 16) of Program Initialization Parameters (PIPs) to be sent to the remote TP. A NumPIPs value of 0 indicates that no PIP data will be sent. Default: 0 PIPLengths 16-bit signed integer array; input. This is an array of up to 16 integers that indicate the lengths, in bytes, of the Program Initialization Parameters (PIP1...PIP16).
Intrinsic Descriptions MCAllocate When the MCAllocate intrinsic executes successfully, a ResourceID is assigned to the allocated conversation. Just as the TPID uniquely identifies one among many possible instances of the same TP, the ResourceID uniquely identifies one among many possible conversations conducted by one instance of a TP. Every time MCAllocate is called, a new conversation is established, and a unique ResourceID is assigned to it. Every conversation requires one APPC session.
Intrinsic Descriptions MCAllocate Status Info Values 0 -1 -4 -5 -6 -7 -15 -19 -20 -21 -22 -23 -24 -90 -91 -1002 -1003 -1005 -1006 -1007 -1009 Successful Completion. Intrinsic called with parameter out of bounds. Out of range 'ReturnControl' parameter specified in intrinsic call. Out of range 'SyncLevel' parameter specified in intrinsic call. PIP data length is out of range. Out of range 'Timer' parameter specified in intrinsic call. Out of range 'TPID' parameter specified in intrinsic call.
Intrinsic Descriptions MCConfirm MCConfirm Sends a confirmation request to the remote program and waits for a reply. A status info value of 0 indicates that the remote TP has returned a positive confirmation response (the equivalent of an MCConfirmed). Syntax I16V I16 I32 MCConfirm (ResourceID, RequestToSendReceived, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated.
Intrinsic Descriptions MCConfirm MCAllocate or MCGetAllocate intrinsic was called with the SyncLevel parameter set to 0). It is used to request confirmation from the remote TP and wait for a reply. A TP must be in Send state to call MCConfirm. How confirmation is used in a conversation is up to the TP programmers. It can be used, for example, to verify that a conversation has been allocated properly and that the remote TP is ready to receive data.
Intrinsic Descriptions MCConfirm Following is a complete list of status info values that may be returned to the MCConfirm intrinsic. Status Info Values 0 -1 -2 -20 -31 -40 -50 -51 -52 -60 +80 -90 -91 -1002 -1003 -1020 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Not enough stack space for intrinsic to run. Confirm not allowed. Intrinsic called in invalid state. Allocation Error. Resource Failure: No retry possible.
Intrinsic Descriptions MCConfirmed MCConfirmed Sends a positive confirmation response to the remote TP. Syntax I16V I32 MCConfirmed(ResourceID, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution.
Intrinsic Descriptions MCConfirmed Table 5-6 Intrinsics With Confirmation Requests Intrinsic Requesting Confirmation State of Local TP After Remote Calls Intrinsic MCConfirm Confirm state MCPrepToRcv Confirm Send state (PrepToRcvType = CONFIRM or PrepToRcvType = CONVERSATION_SYNC_LEVEL, if conversation was allocated with SyncLevel of CONFIRM) MCDeallocate Confirm Deallocate state (DeallocateType = CONFIRM or DeallocateType = CONVERSATION_SYNC_LEVEL, if conversation was allocated with SyncLevel of
Intrinsic Descriptions MCDeallocate MCDeallocate Deallocates the specified conversation. Syntax I16V I16V I32 MCDeallocate(ResourceID, [DeallocateType], Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. DeallocateType 16-bit signed integer by value; input. The type of deallocation to be performed.
Intrinsic Descriptions MCDeallocate 2 = ABEND Allows the conversation to deallocate in any state except Deallocate state. All buffers are flushed. If the conversation is in Receive state, loss of data can occur. 5 = LOCAL Deallocates the conversation from Deallocate state. 6 = CONFIRM Causes an internal execution of the MCConfirm intrinsic. The remote TP must respond with positive confirmation before the conversation can be deallocated.
Intrinsic Descriptions MCDeallocate Figure 5-2 Remote TP Deallocating a Conversation Status Info Values 0 -1 -2 -8 -20 -31 -40 -50 -51 -52 -60 +80 -90 -91 -1002 -1003 -1020 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Out of range 'DeallocateType' specified in intrinsic call. Not enough stack space for intrinsic to run. Confirm not allowed. Intrinsic called in invalid state. Allocation Error.
Intrinsic Descriptions MCErrMsg MCErrMsg Provides the message corresponding to a status info value that was returned in a previous intrinsic call. Syntax I32V CA I16 I32 MCErrMsg(OldStatus, MessageBuffer, MessageLength, Status); Parameters OldStatus Required; 32-bit signed integer by value; input. The status info value for which a corresponding message is desired. This is a value that was returned in the Status parameter of a previous intrinsic call.
Intrinsic Descriptions MCErrMsg Status Info Values 0 -1 -16 -17 -17 -20 -28 -90 -91 -1002 -1003 Successful Completion. Intrinsic called with parameter out of bounds. Unable to open catalog file. GENMESSAGE failed. (MPE V) CATREAD failed. (MPE XL) Not enough stack space for intrinsic to run. Invalid 'OldStatus' passed to error message intrinsic. An internal error in Presentation Services has occurred. An internal error in the APPC subsystem has occurred.
Intrinsic Descriptions MCFlush MCFlush Flushes the local LU’s send buffer, sending everything in it to the remote LU’s receive buffer. Syntax I16V I32 MCFlush(ResourceID, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution.
Intrinsic Descriptions MCFlush Status Info Values 0 -1 -2 -20 -40 -90 -91 -1002 -1003 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Not enough stack space for intrinsic to run. Intrinsic called in invalid state. An internal error in Presentation Services has occurred. An internal error in the APPC subsystem has occurred. An internal error at the mapped conversation level has occurred. Required parameter missing.
Intrinsic Descriptions MCGetAllocate MCGetAllocate Establishes a conversation initiated by a remote TP. Syntax I16V CA CA I16 MCGetAllocate(TPID, SessionType, LocalTPName, ResourceID, I32 I16 I16V I16V Status, [SyncLevel], [Timer], [Security], I16V I16A CA CA CA [NumPIPs], [PIPLengths], [PIP1,] [PIP2,] . . . [PIP16]); Parameters TPID Required; 16-bit signed integer by value; input. This number is assigned to the specific instance of the TP during the execution of the TPStarted intrinsic.
Intrinsic Descriptions MCGetAllocate the local TP must convert it from EBCDIC to ASCII. The MPE CTRANSLATE intrinsic, or the intrinsic on MPE XL, may be used. On MPE XL, LocalTPName is an input ASCII parameter. It must match the value in the LocalTPName parameter of the TPStarted intrinsic. The LocalTPName parameter contains the TP name sent by the remote TP. This TP name must be configured in the APPC configuration branch of NMMGR.
Intrinsic Descriptions MCGetAllocate Denotes that no confirmation will be used. If a SyncLevel of 2 is specified, the MCConfirm and MCConfirmed intrinsics cannot be called during this conversation, nor can the confirm request option of any intrinsic be used during this conversation. If any confirmation is attempted with SyncLevel set to 2, a status info value of -31 is returned. Timer 16-bit signed integer by value; input.
Intrinsic Descriptions MCGetAllocate NOTE If the remote TP sends more PIPs than the value specified in the NumPIPs parameter, the PIPLengths parameter and all PIPs are ignored. A status info value of -1010 is returned. PIPLengths 16-bit signed integer array; input/output. This is an array of up to 16 integers that indicate the lengths, in bytes, of the Program Initialization Parameters (PIP1...PIP16). The combined length of all the PIPs must not be greater than 1980 bytes.
Intrinsic Descriptions MCGetAllocate HP 3000 then runs the local TP, which calls MCGetAllocate to allocate the local side of the conversation. Once the MCGetAllocate intrinsic has executed successfully, the local TP is in Receive state and the remote TP is in Send state. When the MCGetAllocate intrinsic executes successfully, a ResourceID is assigned to the allocated conversation.
Intrinsic Descriptions MCGetAllocate job file through configuration. When the HP 3000 receives the TP name from the remote TP, it does one of two things: 1. If the local TP is already active, and if it is configured to receive multiple allocate requests from remote TPs, LU 6.2 API waits for any current conversation with the local TP process to be deallocated, and then it allocates a conversation with the local TP process. 2.
Intrinsic Descriptions MCGetAllocate Figure 5-3 Remotely Initiated TP on the HP 3000 Figure 5-4 shows how, on MPE XL, allocate requests from the remote TP can be queued to wait until the local TP calls the MCGetAllocate intrinsic. The TP in Figure 5-4 loops through the same conversation, beginning with MCGetAllocate and ending with MCDeallocate, until it receives the last allocate request.
Intrinsic Descriptions MCGetAllocate Figure 5-4 Queued Allocate Requests from Remote TPs Status Info Values 0 -1 -5 -6 -7 -15 -19 -20 -21 -22 -23 -24 -25 +29 Successful Completion. Intrinsic called with parameter out of bounds. Out of range 'SyncLevel' parameter specified in intrinsic call. PIP data length is out of range. Out of range 'Timer' parameter specified in intrinsic call. Invalid 'TPID' parameter specified in intrinsic call. APPC subsystem is inactive.
Intrinsic Descriptions MCGetAttr MCGetAttr Returns information pertaining to the specified conversation. Syntax I16V I32 CA MCGetAttr(ResourceID, Status, [OwnFullyQualifiedLUName], CA CA [PartnerLUName], [PartnerFullyQualifiedLUName], CA I16 [ModeName], [SyncLevel]); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information.
Intrinsic Descriptions MCGetAttr PartnerLUName character array; output. This is an 8-character ASCII array, left justified and padded with blanks. It returns the name of the remote LU used by the remote TP. PartnerLUName is the name by which the local LU knows the remote LU. PartnerLUName is returned only on a conversation using a dependent LU to communicate with a Type 5 node (like an IBM mainframe). PartnerFullyQualifiedLUName character array; output.
Intrinsic Descriptions MCGetAttr 0 = CONFIRM Denotes that the MCConfirm and MCConfirmed intrinsics can be called. It also means that the confirm request option of any intrinsic may be used. 2 = NONE Denotes that no confirmation will be used. If the SyncLevel is 2, the MCConfirm and MCConfirmed intrinsics cannot be called during this conversation, nor can the confirm request option of any intrinsic be used during this conversation.
Intrinsic Descriptions MCPostOnRcpt MCPostOnRcpt Allows the LU to check the contents of the receive buffer for the specified conversation. Syntax I16V I16V CA I32 MCPostOnRcpt(ResourceID, Length, Data, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Length Required; 16-bit signed integer by value; input.
Intrinsic Descriptions MCPostOnRcpt intrinsic is called that ends posting and releases the resources. The following intrinsics end posting: MCDeallocate MCRcvAndWait MCRcvNoWait MCSendError When the MCTest or MCWait intrinsic indicates that something is waiting in the receive buffer, call MCRcvAndWait or MCRcvNoWait with the same Data parameter you used in the last call to MCPostOnRcpt. The MCPostOnRcpt intrinsic can be called only from Receive state.
Intrinsic Descriptions MCPrepToRcv MCPrepToRcv Changes the conversation state of the local TP from Send to Receive, and changes the conversation state of the remote TP from Receive to Send. Syntax I16V I32 I16V I16V MCPrepToRcv(ResourceID, Status, [PrepToRcvType], [Locks]); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information.
Intrinsic Descriptions MCPrepToRcv 1 = FLUSH Causes the local LU to empty its send buffer and the local TP to enter Receive state. 6 = CONFIRM Causes the local LU to flush its send buffer and immediately send a confirmation request to the remote TP. The remote TP is then placed in Confirm Send state and must respond with positive confirmation before it can enter Send state.
Intrinsic Descriptions MCPrepToRcv Control will not be returned to the local TP until information, such as data, is received from the remote TP following a positive confirmation response. Default: 0 (SHORT) Description The MCPrepToRcv intrinsic flushes the local TP’s send buffer, changes the conversation state of the local TP from Send to Receive, and changes the state of the remote TP from Receive to Send. No data can be received through this intrinsic.
Intrinsic Descriptions MCRcvAndWait MCRcvAndWait Waits for information to arrive on the specified conversation and then receives the information. Syntax I16V I16 I16 MCRcvAndWait(ResourceID, Length, RequestToSendReceived, CA I16 I32 Data, WhatReceived, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information.
Intrinsic Descriptions MCRcvAndWait RequestToSendReceived Required; 16-bit signed integer; output. Indicates whether the remote TP has issued a RequestToSend. Possible values are as follows: 1 = YES Indicates a RequestToSend has been received from the remote TP. The remote TP has issued the equivalent of the MCReqToSend intrinsic, requesting that the local TP enter Receive state and place the remote TP in Send state. 0 = NO No RequestToSend has been received.
Intrinsic Descriptions MCRcvAndWait in the Length parameter. When the final portion of a data record is received, the WhatReceived parameter returns 1 (DATA_COMPLETE). 4 = SEND Indicates that the remote TP has issued the equivalent of MCPrepToRcv or MCRcvAndWait and has entered Receive state. The local TP is now in Send state and can issue only those intrinsics that are callable from Send state.
Intrinsic Descriptions MCRcvAndWait NOTE A TP cannot receive both data and control information in the same call to MCRcvAndWait. If both data and control information have been received in the receive buffer, a TP must make separate calls to MCRcvAndWait for each one. The only control information that can be received in the same MCRcvAndWait call with data is the RequestToSendReceived notification. If posting has been set on the specified conversation, MCRcvAndWait ends posting.
Intrinsic Descriptions MCRcvAndWait Timer expires. See MCAllocate or MCGetAllocate for information on the Timer). Figure 5-5 Conversation with Calls to MCRcvAndWait Status Info Values 0 -1 -2 -11 -13 -20 -40 -50 -51 -52 -56 -60 +80 -90 -91 +100 -1002 -1003 -1020 -1050 -1105 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Out of range 'Length' parameter specified in intrinsic call.
Intrinsic Descriptions MCRcvNoWait MCRcvNoWait Receives any information available for the specified conversation but does not wait for information to arrive before returning control to the calling TP. Syntax I16V I16 I16 MCRcvNoWait(ResourceID, Length, RequestToSendReceived, CA I16 I32 Data, WhatReceived, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated.
Intrinsic Descriptions MCRcvNoWait RequestToSendReceived Required; 16-bit signed integer; output. Indicates whether the remote TP has issued a RequestToSend. Possible values are as follows: 1 = YES Indicates a RequestToSend has been received from the remote TP. The remote TP has issued the equivalent of the MCReqToSend intrinsic, requesting that the local TP enter Receive state and place the remote TP in Send state. 0 = NO No RequestToSend has been received. Data Required; character array; output; EBCDIC.
Intrinsic Descriptions MCRcvNoWait in the Length parameter. When the final portion of a data record is received, the WhatReceived parameter returns 1 (DATA_COMPLETE). 4 = SEND Indicates that the remote TP has issued the equivalent of MCPrepToRcv or MCRcvAndWait and has entered Receive state. The local TP is now in Send state and can issue only those intrinsics that are callable from Send state.
Intrinsic Descriptions MCRcvNoWait 1. MCRcvNoWait can be called only from Receive state. Unlike MCRcvAndWait, it cannot be used to change the conversation state of the local TP from Send state to Receive state. 2. Unlike MCRcvAndWait, which waits for information from the remote before returning control to the calling TP, MCRcvNoWait does not wait for information to arrive.
Intrinsic Descriptions MCReqToSend MCReqToSend Notifies the remote TP that the local TP wants to enter Send state. Syntax I16V I32 MCReqToSend(ResourceID, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution.
Intrinsic Descriptions MCSendData MCSendData Sends one data record to the remote TP. Syntax I16V CA I16V I16 MCSendData(ResourceID, Data, Length, RequestToSendReceived, I32 Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Data Required; character array; input; EBCDIC.
Intrinsic Descriptions MCSendData 0 = NO No RequestToSend has been received. Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution. See the “Status Parameter” section, earlier in this chapter, for more information. Description The MCSendData intrinsic sends data to the remote TP. When it is called, the data in the Data parameter is moved to the send buffer.
Intrinsic Descriptions MCSendError MCSendError Informs the remote TP that the local TP has detected an error in an application. Places the remote TP in Receive state and the local TP in Send state. Syntax I16V I16 I32 MCSendError(ResourceID, RequestToSendReceived, Status); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information.
Intrinsic Descriptions MCSendError in Receive state (if it is not already in Receive state) and the local TP in Send state (if it is not already in Send state). The most common use of MCSendError is to respond negatively to a confirmation request. A call to MCSendError ends posting. For more information on posting, see the description of MCPostOnRcpt, earlier in this chapter. The MCSendError intrinsic operates differently depending on the current state of the TP that calls it.
Intrinsic Descriptions MCTest MCTest Tests the specified for the receipt of information. Syntax I16V I16V I32 I16 MCTest(ResourceID, [Test], Status, [PostedType]); Parameters ResourceID Required; 16-bit signed integer by value; input. This is the unique resource ID number assigned to this conversation when it was allocated. See MCAllocate or MCGetAllocate, in this chapter, for more information. Test 16-bit signed integer by value; input.
Intrinsic Descriptions MCTest Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution. See the “Status Parameter” section, earlier in this chapter, for more information. PostedType 16-bit signed integer; output. This parameter indicates the kind of information received. It is valid only when Test = 0 (POSTED) and Status = 0 (something is waiting in the receive buffer).
Intrinsic Descriptions MCTest Status Info Values 0 -1 -2 -20 -35 +36 -37 +38 -40 -50 -51 -52 -56 -60 -90 -91 +100 -1002 -1003 -1020 -1105 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Not enough stack space for intrinsic to run. Out of range 'Test' parameter specified in intrinsic call. Request To Send Not Received. Posting Not Active. Not Posted. Intrinsic called in invalid state. Allocation Error.
Intrinsic Descriptions MCWait MCWait Waits for information to arrive for any of a list of conversations. Syntax IA16 I16V I16 MCWait(ResourceList, NumResources, ResourcePosted, I32 I16 Status, [PostedType]); Parameters ResourceList Required; 16-bit integer array; input. This array is a list of ResourceIDs for current conversations. It specifies the conversations that MCWait will monitor for incoming information.
Intrinsic Descriptions MCWait Status Required; 32-bit signed integer; output. Indicates the result of intrinsic execution. See the “Status Parameter” section, earlier in this chapter, for more information. PostedType 16-bit signed integer; output. This parameter indicates the kind of information received. It is valid only when Status = 0 (something is waiting in the receive buffer for one of the posted conversations).
Intrinsic Descriptions MCWait information arrives in the receive buffer of one of the conversations it is monitoring before it returns control to the conversation. Status Info Values 0 -1 -2 -20 -34 -37 -40 -50 -51 -52 -56 -60 +80 -90 -91 +100 -1002 -1003 -1020 -1105 Successful Completion. Intrinsic called with parameter out of bounds. Invalid 'ResourceID' parameter specified in intrinsic call. Not enough stack space for intrinsic to run. Out of range 'NumResources' parameter specified in intrinsic call.
6 Buffer Management LU 6.2 API optimizes the use of the data communications line by buffering the data that is sent and received. This chapter explains how LU 6.2 API handles control information and how it uses the send and receive buffers to manage the data traffic between transaction programs. Control Information For every conversation allocated, LU 6.2 API establishes and maintains a set of flags or indicators that keep track of certain control information necessary to manage the conversation.
Buffer Management Send Buffer Send Buffer For each conversation allocated, LU 6.2 API establishes a send buffer. On MPE V, the send buffer is always 2044 bytes. On MPE XL, the send buffer is the same size as the maximum RU size for the session. The maximum RU size is a configured value from 256 through 2048 associated with the session type. For more information on configuring RU sizes, see the APPC Subsystem on MPE XL Node Manager’s Guide.
Buffer Management Send Buffer LU 6.2 API checks to see if 16 more bytes will fit in the send buffer. Only 12 more bytes will fit, so LU 6.2 API transmits the 127 records in the send buffer and then stores the 128th record in the send buffer. Example 2: An Allocation Error In example 2, a local TP receives an allocation error from the remote TP. After executing the MCAllocate intrinsic, LU 6.2 API does not wait for a response from the remote TP before it starts executing calls to MCSendData.
Buffer Management Receive Buffer Receive Buffer Unless the data records exchanged by TPs are very large, they are transmitted and received in groups of more than one at a time. However, a TP can logically send and receive only one record at a time. So each group of records that a TP receives is stored in its receive buffer, and the TP takes the records out of the receive buffer one at a time. LU 6.2 API allocates a receive buffer for every active conversation.
Buffer Management Receive Buffer Figure 6-3 Receiving Data and Changing State Example 4: Receiving Large Data Records In example 4, the remote TP has a large send buffer, and the data records that it sends to the local TP are 5000 bytes long. The local receive buffer will hold 4092 bytes.
Buffer Management Receive Buffer Figure 6-4 Receiving Large Data Records 134 Chapter 6
7 Debugging This chapter shows you how to isolate problems in your TPs. It contains the following sections: • Debugging Steps. This section tells you the steps to follow to minimize the time you spend debugging. • The User Trace. This section explains how to enable user tracing, how to identify and format the trace files, and how to read a user trace.
Debugging Debugging Steps Debugging Steps To minimize the time spent isolating TP problems, follow the procedure below. 1. Format and analyze the user trace. The user trace is the most useful point of departure when debugging. If you have not enabled user tracing, you will have to recreate the problem with user tracing enabled. See the description of the TPStarted intrinsic, in Chapter 5 , “Intrinsic Descriptions,” for more information on enabling user tracing.
Debugging The User Trace The User Trace User tracing records intrinsic calls and data for a single transaction program, including all conversations in which the transaction program is engaged. Tracing can be turned on using the TraceOn parameter of the TPStarted intrinsic. Once the trace has been turned on, it remains on until TPEnded is called. Entries are written to the trace file at the completion of each intrinsic call.
Debugging The User Trace Collecting the User Trace The user trace file is created in the group and account from which the TP is run. The default name is PSTRACnn, where nn is a number from 00 through 49 that increments each time a new file is opened. After 25 user trace files are created, the system purges one trace file each time a new one is opened. Trace files are created and numbered as follows: 1. Trace files PSTRAC00 through PSTRAC24 are created. 2. PSTRAC25 is created and file PSTRAC00 is purged. 3.
Debugging The User Trace :listf pstrac@.testpgms.
Debugging The User Trace If the file numbers have wrapped, the file with the highest number is not the youngest. In the following example, notice that the numbering jumps from PSTRAC02 to PSTRAC28. There is a gap of 26 file numbers after PSTRAC02. The youngest file will always be at the lower end of the gap. In this example, the youngest file is PSTRAC02. The files PSTRAC03 through PSTRAC27 have been purged, and the numbering has wrapped. :listf pstrac@.testpgms.
Debugging The User Trace Formatting the User Trace The trace file must be formatted before you can read it. On MPE V, use the utility APPCDUMP.APPC.SYS to format the user trace. APPCDUMP requires that you specify an input file and an output file. The syntax for running APPCDUMP is as follows: :FILE TRACEIN = trace file name :FILE TRACEOUT = { $STDLIST } (terminal) { *LP } (printer) { file designator } :RUN APPCDUMP.APPC.SYS On MPE XL, use the NMS utility NMDUMP.PUB.SYS to format the user trace.
Debugging The User Trace Figure 7-1 User Trace of a Two-Way Conversation NMDUMP output of data file: PSTRAC26.USERTPS.API Time of output: MON, SEP 16, 1991, 2:27 PM Subsystems being formatted: 16 ****************************************************************************** TPSTARTED RetCode: 0 TPID TPName TraceSize TraceFile = = = = 14 LOCALTP 1024 PSTRAC26.USERTPS.
Debugging The User Trace Field Descriptions Figure 7-1 is an example of a trace of a two-way conversation. This section explains the meaning of each field in the user trace. Intrinsic name The name of each LU 6.2 API intrinsic the local TP calls appears on the left side of the display. RetCode (Return Code) This is the status info value returned in the Status parameter of the intrinsic. The status info is the most useful piece of diagnostic information in the user trace.
Debugging The User Trace TraceFile Name of trace file for user tracing TPID Transaction program identifier TPID Transaction program identifier TPEnded: MCAllocate: SessionType Configured session type used by the conversation SyncLevel Synchronization level for the conversation (CONFIRM or NONE) ReturnControl When control is returned to your program if no session is available (IMMEDIATE or WHEN_SESSION_ALLOCATED) Timer How long your program will wait on an intrinsic call for data or confirmation
Debugging The User Trace MCConfirm: RTS Request to send received MCDeallocate: DeallocateType Type of deallocation for the conversation (CONVERSATION_SYNC_LEVEL, FLUSH, ABEND, LOCAL, or CONFIRM) MCPostOnRcpt: Length Length of data to be received before local TP is notified Offset Stack offset of data to be posted (This value is in decimal on MPE V and hexadecimal on MPE XL.
Debugging The User Trace Data Data sent. On the left, the data is displayed in hexadecimal. On the right, it is displayed in EBCDIC. RTS Request to send received PostedType Type of information posted (DATA or NOT_DATA) Test Condition being tested (POSTED or REQUEST_TO_SEND_RECEIVED) PostedType Type of information posted (DATA or NOT_DATA) MCSendError: MCTest: MCWait: ResourcePosted Resource ID of the conversation being posted.
A Status Info This appendix contains all of the status info values that are returned to LU 6.2 API intrinsics through the Status parameter. The status info values are listed here in order by absolute value. No status info value has both a positive and a negative meaning. A positive value indicates that an intrinsic executed successfully and further information is available. A negative value indicates that an intrinsic did not execute successfully. 0 MESSAGE: Intrinsic called with parameter out of bounds.
Status Info -4 MESSAGE: Out of range 'ReturnControl' parameter specified in intrinsic call. CAUSE: (MPE V only) The ReturnControl parameter has been set to a value other than 0. ACTION: Because this parameter is not currently implemented, the value must always be 0. The parameter can be explicitly set to 0 in the intrinsic call, or it can be omitted from the intrinsic call and allowed to default to 0. CAUSE: (MPE XL only) The ReturnControl parameter has been set to a value other than 0 or 1.
Status Info ACTION: Verify that the Length parameter is a value from 0 through 4092 bytes (or from 0 through 32763 bytes for the MCRcvAndWait intrinsic on MPE XL). CAUSE: The value of the Length parameter is greater than the length of the Data array specified in the intrinsic call. ACTION: Verify that the value of the Length parameter is less than or equal to the length of the Data array. CAUSE: The Length parameter may be corrupted. ACTION: Verify that addresses are not being corrupted.
Status Info CAUSE: The MPE CATREAD intrinsic did not execute properly. ACTION: Notify your HP representative. -19 MESSAGE: APPC subsystem is inactive. CAUSE: The APPC subsystem has not been started or is no longer active. ACTION: Request that the node manager start the APPC subsystem. -20 MESSAGE: Not enough stack space for intrinsic to run. CAUSE: The minimum amount of stack space required to call and execute an intrinsic is not available.
Status Info Verify that the specified SessionType has been configured in the NMCONFIG file for the APPC subsystem. For information on APPC subsystem configuration, see the LU 6.2 API/V Node Manager’s Guide or the APPC Subsystem on MPE XL Node Manager’s Guide. CAUSE: No conversations are available because the maximum number of conversations has been allocated. ACTION: Run programs at a time when resources are not in heavy demand. -24 MESSAGE: Unable to obtain an LU-LU session.
Status Info ACTION: Verify that the OldStatus value is a valid status info value and that it has not been corrupted. +29 MESSAGE: Could not find a conversation for this transaction program - timer popped. (MPE XL only) CAUSE: The configured Time-out value for the remotely initiated transaction program expired before an allocate request arrived from a remote TP. ACTION: If this message indicates a problem, verify that the remote TP is sending the correct TP name in the allocate request.
Status Info ACTION: Before calling MCTest or MCWait, verify that the MCPostOnRcpt intrinsic has executed successfully for the specified conversation. +38 MESSAGE: Not Posted. CAUSE: No data or conversation status information has been received for the specified conversation. ACTION: Informational message. No action necessary. -40 MESSAGE: Intrinsic called in invalid state. CAUSE: The program called an intrinsic from a state in which the intrinsic is not allowed.
Status Info CAUSE: An unavailable remote TP. The remote LU rejected the allocation request because the remote TP could not be started. ACTION: Determine why the remote TP could not be started. Do not try to restart the TP until the problem has been resolved. -51 MESSAGE: Resource Failure: No retry possible. CAUSE: A conversation failure has occurred and the APPC subsystem is unable to reactivate the conversation. Possible reasons include the following: LU 6.
Status Info -65 MESSAGE: Received an invalid attach from the remote LU. CAUSE: The APPC subsystem rejected the remote TP’s request to start a conversation, because it was invalid. The APPC subsystem could not receive the PIP data successfully. ACTION: Have remote programmer verify the parameters used to allocate the conversation. PIP data length must be specified correctly by the remote TP. +80 MESSAGE: Timer has expired.
Status Info -1003 MESSAGE: Required parameter missing. CAUSE: A required parameter was not included in the call to an LU 6.2 API intrinsic. ACTION: Verify that all the required parameters are included in the intrinsic call. -1005 MESSAGE: Insufficient Heap Space. (MPE V) CAUSE: The size of the DL to DB area was insufficient for the MCAllocate intrinsic to start a conversation. ACTION: Increase the maximum stack size using the Stack parameter of the MPE RUN parameter of the MPE PREP command.
Status Info ACTION: Reduce the lengths of the PIPs until their combined length is less than or equal to 1980 bytes. -1010 MESSAGE: Too many PIP subfields. CAUSE: The remote TP has sent more PIPs than the number specified in the NumPIPs parameter of the MCGetAllocate intrinsic. ACTION: Consult with the remote programmer to make sure the number of PIPs sent matches the value in the NumPIPs parameter. -1020 MESSAGE: Deallocate Abend.
Status Info -1036 MESSAGE: Out of range 'TraceOn' parameter specified in intrinsic call. CAUSE: The value of the TraceOn parameter is not within its valid range. ACTION: Verify that the TraceOn parameter is a value from 0 through 3. -1040 MESSAGE: Conversation(s) not deallocated before calling TPENDED. CAUSE: One or more conversations were not deallocated before the TPEnded intrinsic was called.
B Sample Programs This appendix contains an example LU 6.2 application. The application in this example enables a clerk in a retail store to check the credit of a buyer before allowing the buyer to charge a purchase to a credit card. The retail store has an HP 3000 running LU 6.2 API. The credit information is stored in a VSAM database on an IBM processor running CICS.
Sample Programs Figure B-1 is a sample credit card verification report generated from the database on the IBM processor. This is the data set used by the example application in this appendix. Figure B-1 is a sample credit card verification report generated from the database on the IBM processor. When the CICS TP receives a social security number and name from the TP on the HP 3000, it sends the data record associated with the social security number and name.
Sample Programs COBOL II Program COBOL II Program Figure B-2 is a chart of the program structure for the COBOL II TP that runs on the HP 3000.
Sample Programs COBOL II Program 001000$CONTROL CROSSREF,SYMDEBUG 001100*----------------------------------------------------* 001200 IDENTIFICATION DIVISION. 001300*----------------------------------------------------* 001400 PROGRAM-ID. 001500 AUTHOR. 001600 INSTALLATION. 001700 DATE-WRITTEN. 001800 DATE-COMPILED. 001900* 002000 REMARKS. 002100* 002200*----------------------------------------------------* 002300 ENVIRONMENT DIVISION.
Sample Programs COBOL II Program 006200 006300 006400 006500 006600 006700* 006800 01 006900* 007000 01 007100 007200 007300 007400 007500 007600 007700 007800* 007900 01 008000 008100 008200 008300 008400 008500 008600 008700 008800* 05 05 05 05 05 DEALLOCATE-RTRNCD ENDED-RTRNCD SENDDATA-RTRNCD TPSTART-RTRNCD RCVANDWAIT-RTRNCD 008900 01 009000 009100* 009200 01 009300 009400 009500* 009600 01 009700 009800 009900* 010000 01 010100 010200* 010300 01 010400* 010500 01 010600 010700 010800 010900 011000 01
Sample Programs COBOL II Program 011400 011500 011600 011700 011800 011900* 012000 01 012100 012200 012300* 05 05 05 CREDIT-INFO-MASTER 10 CO-CODE-MASTER 10 BALANCE-MASTER FILLER RISK-CODE-MASTER OCCURS 5 TIMES. PIC X. PIC 9(4)V9(2). PIC X(14). PIC X(1). ERROR-RECORD REDEFINES MASTER-DATA. 05 ERROR-CODE PIC 9(4). 05 FILLER PIC X(76). 012400 01 TRANS-DATA. 012500 05 SOCSEC-TRANS. 012600 10 SOCSEC1-TRANS PIC X(3). 012700 10 SOCSEC2-TRANS PIC X(2). 012800 10 SOCSEC3-TRANS PIC X(4). 012900 05 NAME-TRANS.
Sample Programs COBOL II Program 015300*----------------------------------------------------* 015400 101000-BEGIN-HOUSEKEEPING SECTION. 015500*----------------------------------------------------* 015600* This section calls TPStarted to initialize resources 015700* for the local TP, and then it calls MCAllocate to 015800* allocate a conversation with the remote TP. 015900* 016000 MOVE NO-SW TO QUIT-SW.
Sample Programs COBOL II Program 020500 IF QUIT-SW IS EQUAL TO YES-SW 020600 GO TO 102099-EXIT. 020700* 020800 PERFORM 202000-RECEIVE-DATA. 020900* 021000 102099-EXIT. 021100 EXIT. 021200* 021300*----------------------------------------------------* 021400 103000-END-HOUSEKEEPING SECTION. 021500*----------------------------------------------------* 021600* This section deallocates the conversation and calls 021700* TPEnded to free the resources used by the local TP.
Sample Programs COBOL II Program 025700 MOVE YES-SW TO QUIT-SW 025800 MOVE INTRINSIC-STATUS-INFO TO SENDDATA-RTRNCD 025900 DISPLAY SENDDATA-ERR-MSG,SENDDATA-RTRNCD. 026000* 026100 201099-EXIT. 026200 EXIT. 026300* 026400*----------------------------------------------------* 026500 202000-RECEIVE-DATA SECTION.
Sample Programs COBOL II Program 030900 031000 031100 031200* DISPLAY WHAT-RECEIVED-MSG,DISPLAY-WHAT-RECEIVED MOVE YES-SW TO QUIT-SW GO TO 202099-EXIT. 031300 CALL INTRINSIC "CTRANSLATE" USING TRANSLATE-TO-ASCII, 031400 MASTER-DATA, 031500 MASTER-DATA, 031600 RECEIVE-LENGTH. 031700 IF CCODE << ZERO 031800 DISPLAY CTRANSLATE-ERR-MSG, 031900 "CCL - MASTER-DATA NOT TRANSLATED" 032000 MOVE YES-SW TO QUIT-SW 032100 GO TO 202099-EXIT.
Sample Programs COBOL II Program 034800*----------------------------------------------------* 034900 302000-DISPLAY-ERROR-MESSAGE SECTION. 035000*----------------------------------------------------* 035100* This section evaluates the errorcode returned by the 035200* remote TP and writes an error message to the user’s 035300* terminal. The remote TP can return any of 3 error codes: 035400* 001 - The SS# is not in the database.
Sample Programs COBOL II Program 039300*----------------------------------------------------* 039400 501000-FULL-SCREEN SECTION. 039500*----------------------------------------------------* 039600* This section prompts the user for data and 039700* receives the data from the terminal. 039800* 039900 MOVE SPACE TO TRANS-DATA. 040000 MOVE SPACES TO MASTER-DATA. 040100* 040200 DISPLAY CONSOLE-HEADING. 040300* 040400 DISPLAY "SOCSEC # :". 040500 PERFORM 601000-ACCEPT-SOCSEC 040600 UNTIL SOCSEC-TRANS IS NUMERIC.
Sample Programs Pascal Program Pascal Program Figure B-3 is a chart of the program structure for the Pascal TP that runs on the HP 3000.
Sample Programs Pascal Program $uslinit$ $standard_level 'HP3000'; tables on; code_offsets on; xref on$ $global 'SPL'$ $PAGE$ program credit(input,output); { Date written: August, 1987.} { Date compiled: August, 1987.
Sample Programs Pascal Program 1: BalanceMaster2 CoCodeMaster3 BalanceMaster3 CoCodeMaster4 BalanceMaster4 CoCodeMaster5 BalanceMaster5 Filler RiskCodeMaster (ErrorCode ErrorFiller : : : : : : : : : : : balancetype; char; balancetype; char; balancetype; char; balancetype; packed array [1..14] of char; char); pac4type; packed array [1..76] of char); end; short_text text TPNameType = packed array [1..8] of char; = packed array [1..20] of char; = packed array [1..
Sample Programs Pascal Program {************************************************************ ErrorHandler This procedure returns the error message associated with a status info value.
Sample Programs Pascal Program {************************************************************ BeginHouseKeeping This procedure calls TPStarted to initialize resources for the local TP, and then it calls MCAllocate to allocate a conversation with the remote TP.
Sample Programs Pascal Program {************************************************************ SendData This procedure translates the data received from the user's screen into EBCDIC and sends it to the remote TP.
Sample Programs Pascal Program {************************************************************ DisplayAcceptance This procedure evaluates the Risk Code received from the remote TP to determine whether to approve or deny credit, and then it writes a message to the user's terminal. ************************************************************} procedure DisplayAcceptance (RiskCode : shortint; var Quit_SW : boolean); begin if ord(RiskCode) << ord(ACCEPT_CODE) then writeln ('Credit Denied.
Sample Programs Pascal Program end; end; $PAGE$ {************************************************************ ReceiveData This procedure calls MCRcvAndWait twice: once to receive a data record from the remote TP and once to receive the instruction to change to Send state. If this procedure receives a complete data record, it calls CTranslate to translate it to ASCII.
Sample Programs Pascal Program ReceiveLength); if CCode = 1 then begin Quit_SW := YES_SW; writeln (CTranslateErrMsg, 'CCL - MasterData not translated.'); end; if not Quit_SW then begin if ReceiveLength = FULL_RECORD then DisplayAcceptance (MasterData.RiskCodeMaster, Quit_SW) else DisplayErrorMessage (bin(MasterData.
Sample Programs Pascal Program {************************************************************ EndHousekeeping This procedure deallocates the conversation and calls TPEnded to free the resources used by the local TP. ************************************************************} procedure EndHousekeeping (ResourceID, TPID : shortint); var IntrinsicStatus : hpe_status; begin MCDeallocate (ResourceID, DeallocateType, IntrinsicStatus); if IntrinsicStatus.
Sample Programs CICS Program (PL/I) CICS Program (PL/I) CICS provides a high-level command interface to the LU 6.2 verbs. Table B-1 gives the mappings between the LU 6.2 verbs and the equivalent CICS commands issued by the CICS TP. Table B-1 Mapping of CICS Commands to LU 6.2 Verbs LU 6.
Sample Programs CICS Program (PL/I) S027: PROCEDURE OPTIONS (MAIN); DCL 1 RECEIVE_AREA, 2 KEY CHAR(9) INIT((9)' '), 2 NAME CHAR(21) INIT((21)' '); DCL 1 SEND_AREA, 2 KEY CHAR(9) INIT((9)' '), 2 NAME CHAR(21) INIT((21)' '), 2 DATA CHAR(50) INIT((50)' '); /*** error codes ***/ DCL NOT_FOUND CHAR(4) INIT('0001'); DCL INVALID_NAME CHAR(4) INIT('0002'); DCL MISC_ERROR CHAR(4) INIT('0003'); DCL DCL DCL DCL DCL DCL DCL ADDR CSTG HIGH LOW SUBSTR STG VERIFY DCL DCL DCL DCL DCL DCL CONV_GONE BIT(1) CONFIRM_REQ BIT
Sample Programs CICS Program (PL/I) /* If the partner TP deallocated, exit the receive loop. */ IF DFHEIBLK.EIBFREE = HIGH(1) THEN DO; CONV_GONE = '1'B; LEAVE RCV_LOOP; END; /* If the partner TP called MCConfirm, exit the receive loop. */ IF DFHEIBLK.EIBCONF = HIGH(1) THEN DO; CONFIRM_REQ = '1'B; LEAVE RCV_LOOP; END; /* If End-Of-Chain & DATA_COMPLETE & partner TP called MCPrepToRcv */ IF ( (DFHEIBLK.EIBEOC = HIGH(1)) & (DFHEIBLK.EIBCOMPL = HIGH(1)) & (DFHEIBLK.
Sample Programs CICS Program (PL/I) ELSE DO; EXEC CICS DEQ RESOURCE(RSC) LENGTH(6); L_ERR: EXEC CICS SEND FROM(MISC_ERROR) INVITE WAIT; END; END; END RCV_LOOP; /* If the partner TP called MCConfirm, */ /* respond with MCConfirmed (EXEC CICS ISSUE CONFIRMATION). */ L_BYE: IF ((SYNC = 1) & (CONFIRM_REQ = '1'B)) THEN DO; EXEC CICS ISSUE CONFIRMATION; CONFIRM_REQ = '0'B; END; /* If the remote TP deallocated, deallocate the local conversation. */ IF DFHEIBLK.
State Transition Tables C This appendix contains the state transition tables for all the conversation states. Each table contains the following information: • The intrinsics that can be called from the state. • The state of the local side of the conversation after the intrinsic has executed and a status info value has been returned. • The state of the remote side of the conversation after the intrinsic has executed. *** means that the state cannot be determined from the local side of the conversation.
State Transition Tables Table C-2 shows the Confirm Deallocate State transition table.
State Transition Tables Table C-4 shows the Deallocate State transition table. Table C-4 Deallocate State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCDeallocate (LOCAL) 0 Successful Completion Reset Reset MCErrMsg Any value Deallocate Reset MCGetAttr Any value Deallocate Reset Table C-5 show the Receive State transition table.
State Transition Tables Table C-5 Receive State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCRcvAndWait or MCRcvNoWait 0 Successful Completion WhatReceived= DATA_COMPLETE Receive Send WhatReceived= DATA_INCOMPLETE Receive Send WhatReceived= SEND Send Receive WhatReceived= CONFIRM Confirm Send WhatReceived= CONFIRM_SEND Confirm Send Receive WhatReceived= CONFIRM_DEALLOCATE Confirm Deallocate Deallocate -50 Allocat
State Transition Tables Table C-5 Receive State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCTest (POSTED) 0 Successful Completion Receive Send -37 Posting Not Active Receive Send -38 Not Posted Receive Send -51 Resource Failure No Retry Deallocate *** -52 Resource Failure Retry Deallocate *** -56 Prog Error No Truncation Receive Send -60 Prog Error Data Purged Receive Send +100 Deallocate Normal Deallocate
State Transition Tables Table C-6 shows the Reset State transition table. Table C-6 Reset State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCDeallocate 0 Successful Completion Send Receive Any other value Reset *** 0 Successful Completion Receive Send Any other value Reset *** MCGetAllocate Table C-7 shows the Send State transition table.
State Transition Tables Table C-7 Send State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCDeallocate (CONFIRM) 0 Successful Completion Reset Confirm Deallocate -50 Allocation Error Deallocate *** -51 Resource Failure No Retry Deallocate *** -52 Resource Failure Retry Deallocate *** -60 Prog Error Data Purged Receive Send +80 Timer has expired Send Receive -1020 Deallocate Abend Deallocate *** MCDeallocate (ABE
State Transition Tables Table C-7 Send State Intrinsics You Can Call Status Info MCRcvAndWait 0 Successful Completion MCSendData Local State After Intrinsic Execution Remote State After Intrinsic Execution WhatReceived= DATA_COMPLETE Receive Send WhatReceived= DATA_INCOMPLETE Receive Send WhatReceived= SEND Send Receive WhatReceived= CONFIRM Confirm Send WhatReceived= CONFIRM_SEND Confirm Send Receive WhatReceived= CONFIRM_DEALLOCATE Confirm Deallocate Deallocate -50 Allocation E
State Transition Tables Table C-7 Send State Intrinsics You Can Call Status Info Local State After Intrinsic Execution Remote State After Intrinsic Execution MCSendError 0 Successful Completion Send Receive -50 Allocation Error Deallocate *** -51 Resource Failure No Retry Deallocate *** -52 Resource Failure Retry Deallocate *** -60 Prog Error Data Purged Receive Send -1020 Deallocate Abend Deallocate *** Any value Send Receive MCTest Appendix C 193
State Transition Tables 194 Appendix C
D LU 6.2 Verb Table The following Table D-1, is Hewlett-Packard’s LU 6.2 API intrinsics to IBM’s architected LU 6.2 verbs. Table D-1 LU 6.2 Verb Table HP 3000 Intrinsic LU 6.
LU 6.
E Transact Parameter Masks LU 6.2 API intrinsics contain optional parameters that may or may not be passed on any given call. Whenever intrinsics that take optional parameters are used, a communication mechanism must exist between the calling program and the intrinsic to indicate which parameters are being passed and which have been omitted. In many languages, this communication mechanism is handled by the compiler.
Transact Parameter Masks The Parameter Mask The Parameter Mask The parameter mask, or bit mask, is a string of bits, each corresponding to an intrinsic parameter. The leftmost bit corresponds to the first parameter in the intrinsic call. If a bit is set to 1, the corresponding parameter is passed, and if the bit is set to 0 the parameter is omitted. For intrinsics with up to 16 parameters, a 16-bit mask is used. For intrinsics with 17 through 32 parameters, a 32-bit mask is used.
Transact Parameter Masks The Parameter Mask Table E-1 Intrinsics Requiring a 16-Bit Mask Intrinsic Number of Hidden Parameters Bit Map Template 1 = required x = optional 0 = hidden Mask Constant TPStarted 7 111xxxx0000000 n/a TPEnded 5 1100000 96 MCConfirm 5 11100000 224 MCConfirmed 5 1100000 96 MCDeallocate 5 1x100000 n/a MCErrMsg 4 11110000 240 MCFlush 5 1100000 96 MCPostOnRcpt 5 111100000 480 MCPrepToRcv 5 11xx00000 n/a MCRcvAndWait 6 111111000000 4032 MCRcvN
Transact Parameter Masks The Parameter Mask Using the Parameter Mask in TPs To use the parameter mask in the TP you must do the following: 1. Declare both the 16-bit and 32-bit parameter masks at the beginning of the program. 2. Assign the appropriate number to the parameter mask in a LET statement before each LU 6.2 API intrinsic call. The number in the parameter mask must be the decimal representation of the bit mask described in “Parameter Mask Templates.” 3.
Transact Parameter Masks The Parameter Mask Example E-2 TPStarted Declarations and Intrinsic Call DEFINE(ITEM) LOCAL-TP-NAME X(8): TP-ID I(4): TRACE-ON I(4): TRACE-SIZE I(4): TRACE-FILE X(35): DEFAULT-FILE X(28); @COMPUTERTEXTW = LIST LOCAL-TP-NAME: TP-ID: TRACE-ON: TRACE-SIZE: TRACE-FILE: DEFAULT-FILE; LET (MASK16) = 15872; << "11111000000000" >> PROC TPSTARTED ( %(LOCAL-TP-NAME), (TP-ID), (STATUS), (TRACE-ON), #(TRACE-SIZE), << %(TRACE-FILE), << %(DEFAULT-FILE), , , , , , , , #(MASK16) ); << optional
Transact Parameter Masks The Parameter Mask Example E-4 MCAllocate Declarations and Intrinsic Call DEFINE(ITEM) TP-ID I(4): SESSION-TYPE X(8): REMOTE-TP-NAME X(64): REMOTE-TP-LEN I(4): RESOURCE-ID I(4): RETURN-CONTROL I(4): SYNC-LEVEL I(4): TIMER I(4): SECURITY I(4): NUM-PIPS I(4): PIP-LENGTHS[16] I(4): PIP1 X(1980): PIP2 X(1980): << The lengths given in the PIP PIP3 X(1980): << declarations may vary from PIP4 X(1980): << 0 to 1980 bytes.
Transact Parameter Masks The Parameter Mask %(PIP3), %(PIP4) >>, %(PIP5), %(PIP6), %(PIP7), %(PIP8), %(PIP9), %(PIP10), %(PIP11), %(PIP12), %(PIP13), %(PIP14), %(PIP15), %(PIP16), , , , #(MASK32) ); << << << << << << << << << << << << << Example E-5 << << << << << << << << << << << << << << optional >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> option
Transact Parameter Masks The Parameter Mask Example E-7 MCDeallocate Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4): DEALLOCATE-TYPE I(4); LIST RESOURCE-ID: DEALLOCATE-TYPE; LET (MASK16) = 160; << "10100000" >> @COMPUTERTEXTW = PROC MCDEALLOCATE ( #(RESOURCE-ID), << #(DEALLOCATE-TYPE), optional, not used >> (STATUS), , , , , , << 5 hidden parameters >> #(MASK16) ); ---------------------------------------------------------------------------- Example E-8 MCErrMsg Declarations and Intrinsi
Transact Parameter Masks The Parameter Mask Example E-10 MCGetAllocate Declarations and Intrinsic Call DEFINE(ITEM) TP-ID I(4): SESSION-TYPE X(8): TP-NAME X(64): RESOURCE-ID I(4): SYNC-LEVEL I(4): TIMER I(4): SECURITY I(4): NUM-PIPS I(4): PIP-LENGTHS[16] I(4): PIP1 X(1980): PIP2 X(1980): << PIP3 X(1980): << PIP4 X(1980): << PIP5 X(1980): PIP6 X(1980): << PIP7 X(1980): << PIP8 X(1980): << PIP9 X(1980): PIP10 X(1980): PIP11 X(1980): PIP12 X(1980): PIP13 X(1980): PIP14 X(1980): PIP15 X(1980): PIP16 X(1980);
Transact Parameter Masks The Parameter Mask << << << << << << << << %(PIP9), %(PIP10), %(PIP11), %(PIP12), %(PIP13), %(PIP14), %(PIP15), %(PIP16), , , , #(MASK32) ); optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> optional, not used >> << 3 hidden parameters >> ---------------------------------------------------------------------------- Example E-11 MCGetAttr Declarations and Intrinsic Call DEFINE
Transact Parameter Masks The Parameter Mask Example E-12 MCPostOnRcpt Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4): LENGTH I(4): DATA X(4092); LIST RESOURCE-ID: LENGTH: DATA; LET (MASK16) = 480; << "111100000" >> PROC MCPOSTONRCPT ( #(RESOURCE-ID), #(LENGTH), %(DATA), (STATUS), , , , , , #(MASK16) ); << 5 hidden parameters >> ---------------------------------------------------------------------------- Example E-13 MCPrepToRcv Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID
Transact Parameter Masks The Parameter Mask Example E-14 MCRcvAndWait Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4): LENGTH I(4): REQUEST-TO-SEND-RECEIVED I(4): DATA X(4092): WHAT-RECEIVED I(4); LIST RESOURCE-ID: LENGTH: REQUEST-TO-SEND-RECEIVED: DATA: WHAT-RECEIVED; LET (MASK16) = 4032; << "111111000000" >> PROC MCRCVANDWAIT ( #(RESOURCE-ID), (LENGTH), (REQUEST-TO-SEND-RECEIVED), %(DATA), (WHAT-RECEIVED), (STATUS), , , , , , , << 6 hidden parameters >> #(MASK16) ); ----------------------
Transact Parameter Masks The Parameter Mask Example E-16 MCReqToSend Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4); LIST RESOURCE-ID; LET (MASK16) = 96; << "1100000" >> PROC MCREQTOSEND ( #(RESOURCE-ID), (STATUS), , , , , , #(MASK16) ); << 5 hidden parameters >> ---------------------------------------------------------------------------- Example E-17 MCSendData Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4): DATA X(4092): LENGTH I(4): REQUEST-TO-SEND-RECEIVED I(4); LIS
Transact Parameter Masks The Parameter Mask Example E-19 MCTest Declarations and Intrinsic Call DEFINE(ITEM) RESOURCE-ID I(4): TEST I(4): POSTED-TYPE I(4); LIST RESOURCE-ID: TEST: POSTED-TYPE; LET (MASK16) = 480; << "111100000" >> PROC MCTEST ( #(RESOURCE-ID), #(TEST), (STATUS), (POSTED-TYPE), , , , , , #(MASK16) ); << optional >> << optional >> << 5 hidden parameters >> ---------------------------------------------------------------------------- Example E-20 MCWait Declarations and Intrinsic Call D
F Migrating Transaction Programs This appendix describes any source code changes you might have to make in order to migrate a TP from LU 6.2 API/V to LU 6.2 API/XL (or from an early version of LU 6.2 API/XL to the version that supports Node Type 2.1). You must change your TPs to migrate them to LU 6.2 API/XL if any of the following is true: 1. Your TPs issue APPCCONTROL commands programmatically. 2. Your TPs call the MCGetAllocate intrinsic. 3. Your TPs are written in Transact on MPE V.
Migrating Transaction Programs TPs that Issue APPCCONTROL Commands TPs that Issue APPCCONTROL Commands If your TPs start or stop the APPC subsystem or change the number of active sessions programmatically, you must change them to run on the Node Type 2.1 version of LU 6.2 API/XL. On the Node Type 2.1 version, TPs cannot call the MPE COMMAND intrinsic to issue APPCCONTROL commands programmatically, because APPCCONTROL commands are not interpreted by the MPE command interpreter.
Migrating Transaction Programs Remotely Initiated TPs Remotely Initiated TPs On all versions of LU 6.2 API prior to the Node Type 2.1 version, whenever a remote TP sends an allocate request to initiate a conversation with a local TP, LU 6.2 API streams a job that runs the local TP. This method of starting up remotely initiated TPs can be very slow, because a job must be streamed every time an allocate request is received from a remote TP. The Node Type 2.1 version of LU 6.
Migrating Transaction Programs TPs In Transact MPE XL Node Manager’s Guide for information on TP configuration. The remote TP must send this configured TP name in the allocate request. In older versions of LU 6.2 API, the remote TP sends the name of the job file that runs the local TP. In order to avoid changing the remote TP, make the configured TP name (and the LocalTPName parameter) match the job file name. 4.
Glossary A Advanced Program-to-Program Communication (APPC): Programmatic communication based on IBM's LU 6.2 architecture. APPC provides partner programs with a common set of rules for communication. Application Program Interface (API): A set of subprograms, callable from inside applications, that carry out data communications tasks.
conversation with confirm: A conversation established in such a way that confirmation requests and responses can be sent and received. conversation without confirm: A conversation established in such a way that confirmation requests and responses cannot be sent or received. Customer Information Control System (CICS): An IBM application subsystem that provides file handling and data communications services for application programs.
Logical Unit (LU): The SNA entity through which application data is transmitted within an SNA network. Logical Units are the ports through which end users have access to the network (see end user). LU type: A Logical Unit type, defined by SNA to perform a particular type of communication. LU-LU session: See session. LU 6.2: An SNA LU type which defines the communication that can take place between two application programs on separate processors. LU 6.
Physical Unit: An SNA term that refers to the software and hardware that controls the resources of a node. PU: See Physical Unit. PU 2.0: See Node Type 2.0. T transaction program (TP): An application program that processes distributed transactions. PU 2.1: See Node Type 2.1. two-way conversation: A conversation in which data is sent and received by both TPs. R U Receive state: The conversation state from which a TP can receive information from the remote TP. UDC: User-Defined Command.
Index A Advanced Program-to-Program Communication (APPC), 23 allocate a conversation remotely, 93 allocate requests queued, 35, 36 allocation errors, 79, 82 receiving, 131 AOOC sybststem, 21 APPC subsystem session limit, 27 APPC subsystem configuration LUs, 101 mode name, 102 remotely initiated TPs, 34, 35, 36, 98 session types, 75, 79, 93, 97 APPCDUMP.APPC.
Index length of data record to be sent, 119 Length parameter MCPostOnRcpt intrinsic, 104 MCRevAndWait intrinsic, 109 MCRevNoWait intrinsic, 114 MCSendData intrinsic, 119 locally initiated conversations, 32 LocalTPName parameter MCGetAllocate intrinsic, 93, 94 TPStarted intrinsic, 69 Locks parameter MCPrepToRcv intrinsic, 107 logical record length, 104 Logical Unit (LU), 21, 22 LU 6.
Index receiving change to Send state, 111, 116, 132 receiving complete data record, 110, 111, 115 receiving confirmation request, 111, 116 receiving control information, 111, 116 receiving incomplete data record, 116, 133 receiving records larger than receive buffer, 112, 117, 133 record length, 104 remotely initiated conversation, 36, 93 on MPE V, 33, 34 on MPE XL, 34 remotely initiated conversations, 32 remotely initiated TP configuration, 34, 35, 36 manual or automatic startup, 36 RemoteTPLen parameter
Index TraceOn parameter TPStarted intrinsic, 69, 137 TraceSize parameter TPStarted intrinsic, 70 tracing enabling, 69, 71, 136, 137 transaction program (TP), 27 translation ASCII to EBCDIC, 76, 78, 119 EBCDIC to ASCII, 94, 96, 110, 115 transmitting data, 120 treading user trace, 141 Type 5 node, 22 typical IBM network, 19 U underlined parameters in intrinsic descriptions, 64 user trace file default name, 70 name of, 70 reading it, 141 size, 70 user tracing enabling, 69, 71, 136, 137 V verbs, 25 basic conve
