 |
» |
|
|
|
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. 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.) - SessionType
Required; character array;
input. This is an 8-character ASCII array, left justified and padded
with blanks. It contains the name of a session type that is configured
for the APPC subsystem. For more information on session types and
configuration of the APPC subsystem, see the LU 6.2 API/V
Node Manager's Guide or the APPC
Subsystem on MPE XL Node Manager's Guide. - RemoteTPName
Required; character array;
input; EBCDIC. This is an array of up to 64 EBCDIC characters. It
contains the name of the remote TP to be connected at the other
end of the conversation. The remote TP must be written to use mapped
conversations. Because LU 6.2 API performs no translation on this array,
the local TP must convert it from ASCII to 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.2 API
can determine which conversation the intrinsic calls belong to. - 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. - ReturnControl
6-bit signed integer by value; input. Specifies
when the local LU will return control to the local TP after allocating
or attempting to allocate a session. Possible values are as follows: - 0
= IMMEDIATE
If an active session is immediately available, it
will be allocated, and control will be returned to the calling program.
If no session is immediately available, no session will be allocated,
and control will be returned to the calling program. - 1 = WHEN_SESSION_ALLOCATED
The requested session will be allocated before control
is returned to the calling program. If no session is immediately
available, the request will be queued, and the calling program will
be suspended until a session is activated or freed, or until the
allocation request fails. Default: 0 (IMMEDIATE)
- SyncLevel
16-bit signed integer by value; input. This parameter determines
the synchronization level (whether or not confirmation will be used)
for this conversation. Possible values are as follows: - 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. If any confirmation is attempted with SyncLevel set to 2, a status info value of -31 is returned. - Default:
2 (NONE)
- Timer
16-bit signed integer by value; input. This is an
integer from 0 through 28800 that indicates the maximum number of
seconds LU 6.2 API will wait after executing an intrinsic before
returning control to the TP. (28800 seconds = 8 hours.) For example,
if the local TP sets its Timer to 600 (10 minutes) and issues MCRcvAndWait, and no data arrives within 10 minutes, LU 6.2
API will issue a status info of +80 to the local TP, which indicates
that the allotted time has expired. A Timer value of zero indicates that no timer is to be used,
which means that the program will wait indefinitely for an intrinsic
call to complete. The intrinsics that use the Timer are: MCConfirm MCDeallocate DeallocateType = CONFIRM) MCPrepToRcv (PrepToRcvType = CONFIRM) MCRcvAndWait MCWait See the intrinsic descriptions in this chapter for more information. Default: 0 - Security
16-bit signed integer by value; input. Reserved
for future use. - 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). The combined length of all the PIPs must not be greater than
1980 bytes.
| | | |  | NOTE: If NumPIPs is greater than 0, the PIPLengths parameter is required. If NumPIPs is zero, the PIPLengths parameter is ignored. | | | | |
Description | |
The MCAllocate intrinsic establishes a conversation between the
local TP that calls it and the remote TP specified in the RemoteTPName parameter. Once the MCAllocate intrinsic has executed successfully, the local
TP is in Send state and the remote TP is in Receive state. When the local TP initiates a conversation, the MCAllocate intrinsic must be the first LU 6.2 API intrinsic
called after TPStarted, unless the TPEnded intrinsic is called and the program terminated.
See MCGetAllocate, later in this chapter, for information about conversations
initiated by the remote TP. 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. Status Info Values | |
0 Successful Completion.
-1 Intrinsic called with parameter out of bounds.
-4 Out of range 'ReturnControl' parameter specified in intrinsic call.
-5 Out of range 'SyncLevel' parameter specified in intrinsic call.
-6 PIP data length is out of range.
-7 Out of range 'Timer' parameter specified in intrinsic call.
-15 Out of range 'TPID' parameter specified in intrinsic call.
-19 APPC subsystem is inactive.
-20 Not enough stack space for intrinsic to run.
-21 Insufficient memory space to allocate a conversation.
-22 Internal error: Unable to create Presentation Services port.
-23 Unable to allocate a conversation.
-24 Unable to obtain an LU-LU session.
-90 An internal error in Presentation Services has occurred.
-91 An internal error in the APPC subsystem has occurred.
-1002 An internal error at the mapped conversation level has occurred.
-1003 Required parameter missing.
-1005 Insufficient Heap Space. (MPE V)
-1006 Out of range 'RemoteTPLen' parameter specified in intrinsic call.
-1007 Out of range 'NumPIPs' parameter specified in intrinsic call.
-1009 Combined length of PIPs is out of range.
|
|
