 |
» |
|
|
|
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. (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;
output. 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. - LocalTPName
Required; character array;
output in EBCDIC on MPE V; input in ASCII on MPE XL.
;
| | | |  | NOTE: If you are migrating a TP to LU 6.2 API/XL from LU 6.2
API/V or from a version of LU 6.2 API/XL prior to the Node Type
2.1 version, you must change the LocalTPName parameter from an output parameter to an input parameter. | | | | |
On MPE V, LocalTPName is an output parameter, received in EBCDIC from the
remote TP. It contains the name of the job file sent by the remote
TP. The job file name must be 8 characters long; if it is shorter than
8 characters long, it must be padded with blanks. The job file must be
located in the APPC.SYS group and account. When the HP 3000 receives
the job file name, it streams the job, which runs the local TP. Because LU 6.2 API performs no translation on the LocalTPName array, 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. The configuration file associates each TP name with a job file,
which may be located in any group and account. When LU 6.2 API receives
the TP name from the remote TP, it does one of two things: 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 until any conversation with the local
TP process has been deallocated, and then it allocates a conversation
with the local TP process. If the local TP is not active, or if it is configured
to receive only one allocate request per execution instance, LU
6.2 API initiates a new local TP process by streaming the job file
associated with the TP name. Then, it allocates a conversation with
the local TP process.
A remotely initiated TP on MPE XL is configured to conduct
either single or multiple conversations with the remote TP. A TP
that conducts a single conversation must call MCGetAllocate only once; another instance of the TP will be
started each time a remote TP requests a conversation. A TP that
conducts multiple conversations can call MCGetAllocate many times; only one instance of it may be running at
once. See the APPC Subsystem on MPE XL Node Manager's
Guide for more information on TP configuration. - 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. - SyncLevel
16-bit signed integer; output. 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. - 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 following intrinsics use the Timer: MCConfirm
MCDeallocate (DeallocateType = CONFIRM)
MCPrepToRcv (PrepToRcvType = CONFIRM)
MCRcvAndWait
MCWait |
Default: 0 - Security
16-bit signed integer by value; input. Reserved
for future use. - NumPIPs
16-bit signed integer by value; input/output. Indicates the
number of Program Initialization Parameters (PIPs) to be used for
this conversation. Input: The NumPIPs value that the local TP passes to the intrinsic specifies
the maximum number of PIPs the local TP can receive from the remote
TP on this conversation. Output: The NumPIPs value that the intrinsic returns to the local TP indicates
the number of PIPs that the remote TP actually sent to the local
TP. | | | | | 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. Input: The values the local TP passes in PIPLengths indicate the maximum number of characters each PIP
can receive. Output: The values the intrinsic returns in PIPLengths indicate the actual lengths of the PIPs sent by the
remote to the local TP. | | | | | NOTE: If NumPIPs is greater than 0, the PIPLengths parameter is required. If NumPIPs is zero, the PIPLengths parameter is ignored. | | | | |
Description | |
MCGetAllocate is called to receive a conversation allocation
request from the remote TP and initialize all the resources the
local TP needs to conduct a conversation. When the remote TP issues
the equivalent of the MCAllocate intrinsic, it sends a TP name to the HP 3000, indicating
the local TP with which it wants a conversation. The 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. 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 conversation requires one session on the APPC subsystem.
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. For more information on session
limits, see the APPC Subsystem on MPE V Node Manager's Guide or
the APPC Subsystem on MPE XL Node Manager's
Guide. MCGetAllocate allows you to receive initialization information
from 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 local 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 receive from the remote
TP before it executes. Remotely Initiated Conversations on MPE VOn MPE V, MCGetAllocate can be called only once during the execution of
a TP. That is, each execution instance of a TP can have only one
conversation initiated by the remote TP. On MPE V, when a conversation is initiated by the remote TP,
the MCGetAllocate intrinsic must be the first LU 6.2 API intrinsic
called after the TPStarted intrinsic, unless the TPEnded intrinsic is called and the program terminated. On MPE V, the TP name sent by the remote TP is the name of
a job file located in the APPC.SYS group and account. This TP name
must match the name of the job file exactly. The job file contains
the MPE RUN command that starts up the local TP. The executable TP
file can reside in any group and account. When LU 6.2 API
receives the TP name from the remote TP, it streams the job, which
in turn runs the local TP. The value returned in the LocalTPName parameter is the TP name sent by the remote TP. Remotely Initiated Conversations on MPE XLOn MPE XL, the TP name sent by the remote TP is configured
in the APPC subsystem branch of NMMGR. The TP name is associated
with a job file through configuration. When the HP 3000
receives the TP name from the remote TP, it does one of two things: 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. If the local TP is not active, or if it is configured
to receive only one allocate request per execution instance, LU 6.2 API
initiates a new local TP process by streaming the job file associated
with the TP name. Then, it allocates a conversation with the local
TP process.
A remotely initiated TP on MPE XL is configured to conduct
either single or multiple conversations with the remote TP. A TP
that conducts a single conversation must call MCGetAllocate only once; another instance of the TP will be
started each time a remote TP requests a conversation. A TP that
conducts multiple conversations can call MCGetAllocate many times; only one instance of it may be running at
once. See the APPC Subsystem on MPE XL Node Manager's
Guide for more information on TP configuration. On MPE XL, a timer for the MCGetAllocate intrinsic may be configured. The timer prevents
the local TP from being suspended indefinitely if no allocate request
arrives from the remote TP. The timer is a value from 0 (no timer)
to 480 minutes (8 hours), configured through NMMGR/XL. If your program
calls MCGetAllocate, and no allocate request arrives from the remote
TP before the timer expires, control is returned to your program.
See the APPC Subsystem on MPE XL Node Manager's
Guide for more information. The LocalTPName passed in the MCGetAllocate intrinsic must be configured in the APPC subsystem
branch of NMMGR. It must match the TP name sent by the remote TP,
and it must match the LocalTPName passed in the TPStarted intrinsic. | | | | | NOTE: If you are migrating a TP to LU 6.2 API/XL from LU 6.2
API/V or from a version of LU 6.2 API/XL prior to the Node Type
2.1 version, you must change the LocalTPName parameter from an output parameter to an input parameter. | | | | |
Figure 5-3 “Remotely Initiated TP on the HP 3000” shows how a local TP is started
when a conversation allocation request is received from a remote
TP. Figure 5-3 Remotely Initiated TP on the HP 3000 Figure 5-4 “Queued Allocate Requests from Remote
TPs” 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 “Queued Allocate Requests from Remote
TPs” loops
through the same conversation, beginning with MCGetAllocate and ending with MCDeallocate, until it receives the last allocate request. The TP could be written to handle a predetermined number of
allocate requests, or it could loop through the conversation until
the last MCGetAllocate call timed out because the queue was empty. When MCGetAllocate times out, +29 is returned in the Status parameter. (The MCGetAllocate time-out value must be configured through NMMGR/XL.
See the APPC Subsystem on MPE XL Node Manager's Guide.) Figure 5-4 Queued Allocate Requests from Remote
TPs Status Info Values | |
0 Successful Completion.
-1 Intrinsic called with parameter out of bounds.
-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 Invalid '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.
-25 Could not find a conversation for this transaction program.
+29 Could not find a conversation for this transaction program -
timer popped. (MPE XL)
-51 Resource failure: No retry possible.
-65 Received an invalid attach from the remote LU.
-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)
-1007 Out of range 'NumPIPs' parameter specified in intrinsic call.
-1008 Invalid 'LocalTPName' parameter specified in intrinsic call.
(MPE XL)
-1009 Combined length of PIPs is out of range.
-1010 Too many PIP subfields.
|
|
