LU 6.2 API Application Programmer's Reference Guide (30294-90008)

Chapter 5 79
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. On MPE V, only 8
sessions may be active on the APPC subsystem at once. On MPE XL,
the APPC subsystem can support a maximum of 256 active sessions.
The available active sessions must be shared among all the TPs
running on the APPC subsystem, so your TP can allocate only as many
conversations as there are available sessions.
In addition to the session limit for the whole APPC subsystem, there is
also a session limit configured for each session type. For more
information on session limits and session type configuration, see the LU
6.2 API/V Node Manager’s Guide or the APPC Subsystem on MPE XL
Node Manager’s Guide.
The
ReturnControl parameter determines what your program will do
if no session is available when it calls MCAllocate. If you specify 0
(IMMEDIATE)in the
ReturnControl parameter, your program will not
wait for a session to be activated or freed; control will be returned to
your program immediately. If you specify 1
(WHEN_SESSION_ALLOCATED) in the
ReturnControl parameter,
your program will be suspended until a session is activated or until a
conversation is deallocated, freeing a session.
NOTE If you specify 1 (WHEN_SESSION_ALLOCATED) in the
ReturnControl parameter, your program can be suspended
indefinitely. If no session becomes available, or if there is an error with
the session type, your program will be suspended until the APPC
subsystem shuts down or discovers the error.
LU 6.2 API does not wait for a response from the host before it returns
a status info value. Therefore, allocation errors due to host problems do
not appear in the
Status parameter of the MCAllocate intrinsic. (See
Chapter 6 , “Buffer Management.”) To verify that a conversation has
been allocated successfully, call MCAllocate with a
SyncLevel of 0
(CONFIRM), and then call MCConfirm. See MCConfirm, later in this
chapter, for more information.
MCAllocate allows you to send initialization information to the remote
TP in the Program Initialization Parameters (PIPs). These parameters
can be used, for example, to indicate whether a TP is processing daily
information or an end-of-month report. They can also be used to inform
the remote TP of the type of data it will receive, the size of the records,
etc. PIPs can be used to transmit any special information the local TP
must send to the remote TP before it executes.