Use the TPPCC general macro with the ALLOCATE verb specified to allocate a
conversation between a TPF transaction program and a transaction program in a
remote LU. A resource ID is assigned to the conversation and returned
by this macro.
Format
- label
- A symbolic name can be assigned to the macro statement.
- ALLOCATE
- Directs the TPPCC macro to perform the ALLOCATE verb function.
- LUNAME
- Specifies the symbolic name of a field or a register pointing to a
field. This is a 16-byte field that contains the network name of the
remote LU or local secondary LU (SLU) thread with which this local transaction
program wants to start a conversation. The first 8 bytes contain the
left-justified network name, which is padded with blanks, or all blanks if the
LU name is unqualified. The second 8 bytes contain the left-justified
LU name, which is padded with blanks.
- TPN
- Specifies either the symbolic name of a field or a register pointing to a
field that contains the following:
- The 1-byte length of the remote transaction program name.
- A remote transaction program name, which can be from 4 to 64 characters
long.
- RCONTROL
- Specifies when control is returned to the issuer. The allowed
values are:
- WSA
- Specifies that control is returned when a session is allocated for this
conversation.
- IMM
- Specifies to allocate a session for the conversation if a session is
immediately available. A session is immediately available when it is
active, it is not allocated to another conversation, and the local LU is the
contention winner for the session.
- Note:
- TPF does not support the other options defined for this parameter by the LU
6.2 architecture.
- MODE
- Specifies the name used to designate the properties of the session to be
allocated. It can be specified as a symbolic name of a field or a
register, which points to a field that contains the 8-character mode name
(padded on the right with blanks if necessary).
- Note:
- If you do not specify MODE, it defaults to the single session mode
name. The single session mode name is defined with the SINGMODE
parameter on the SNAKEY macro. See TPF ACF/SNA
Network Generation for more information about the SNAKEY macro.
- TYPE
- Specifies the type of conversation. The allowed values are:
- BASIC
- Provides support for the BASIC_CONVERSATION option defined by the LU
6.2 architecture. This is the default.
- MAPPED
- Provides support for the MAPPED_CONVERSATION option defined by the LU
6.2 architecture.
- Note:
- TPF/APPC supports mapped conversations through the C language only.
See TPF C/C++ Language Support User's Guide for
information on the mapped conversation verbs.
- SHAREDB
- Provides support for the BASIC_CONVERSATION option defined by the LU
6.2 architecture, and specifies that this is a shared LU 6.2
conversation.
- SHAREDM
- Provides support for the MAPPED_CONVERSATION option defined by the LU
6.2 architecture, and specifies that this is a shared LU 6.2
conversation.
- Note:
- TPF/APPC supports mapped conversations through the C language only.
See TPF C/C++ Language Support User's Guide for
information on the mapped conversation verbs.
- PIP
- NO is the only allowable value. PIP (program initialization
parameter) data cannot be supplied by the TPF transaction program. If
PIP data is indicated in an ATTACH header received by TPF, the ATTACH
conversation request is rejected.
- SYNC
- Specifies the synchronization level allowed on this conversation.
The allowed values are:
- NONE
- Specifies that the programs cannot perform confirmation processing on this
conversation. This is the default value.
- CONFIRM
- Specifies that the programs can perform confirmation processing on this
conversation.
- Note:
- TPF does not support the LU 6.2 architecture's SYNCPT
option.
- SECURITY
- Specifies the security level allowed on this conversation. NONE is
the only allowed value. (For migration purposes, NONE can be
abbreviated as NO.) TPF does not support the options SAME and PGM
defined by the LU 6.2 architecture.
- RESID
- Specifies either the symbolic name of a field or a register that points to
a field. This is a 4-byte field in which the resource ID is
returned. This resource ID must be specified on all subsequent verbs
for this conversation.
- RCODE
- Specifies the symbolic name of a field or a register that points to a
field. This is a 6-byte field in which the return code is
placed. The return code consists of a 2-byte primary return code
followed by a 4-byte secondary return code. The actual values returned
are listed in Return Conditions.
Entry Requirements
See Entry Requirements for the entry requirements relating to the TPPCC macro in
general.
Return Conditions
- The results of the verb are indicated by the value returned in
RCODE. The valid return codes are listed in the following section,
"Return Codes".
- See Return Conditions for the return conditions relating to the TPPCC macro in
general.
- The following table contains a list of the primary and secondary return
codes that can be returned to the program that issued the ALLOCATE
verb. A complete list of return codes and their definitions can be
found in Table 11 and in Table 12.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_ALLOC_ERROR
| 0003
|
|
LU62RC_ALLOCERR_NORETRY
| ....
| 00000004
|
LU62RC_ALLOCERR_RETRY
| ....
| 00000005
|
LU62RC_INVALID_MODE_NAME
| ....
| 000000F3
|
LU62RC_ALLOC_UNSUCESFUL
| 0015
|
|
LU62RC_TPF_ABEND
| FFFF
|
|
Programming Considerations
- If you specify a register for a keyword value, the register must be
enclosed in parentheses and in the range R1-R7.
- The value returned in RESID must be used by all other TPF/APPC verbs
issued for this conversation.
- If the TYPE parameter is SHAREDB or SHAREDM, then this is a shared LU
6.2 conversation. Shared LU 6.2 conversations are one-way
pipes used to send data from the TPF system to a remote LU. Verbs can
be issued from any ECB for a shared conversation. For conversations
that are not shared, verbs can be issued only from the ECB that started the
conversation. Because a shared conversation is a one-way pipe used to
send data, only certain LU 6.2 verbs are allowed:
- SEND_DATA
- FLUSH
- GET_ATTRIBUTES
- DEALLOCATE (except when TYPE=CONFIRM is specified)
See TPF ACF/SNA Data Communications Reference for
more information about shared LU 6.2 conversations.
- The value returned in RESID is stored in field EBCCBID in the ECB.
This changes with every ALLOCATE request.
- If you are allocating a secondary LU (SLU) thread session, you must
specify a single session mode name. Parallel sessions are not supported
for SLU threads.
- The ATTACH is buffered until the buffer is full or a verb that implies the
FLUSH function is issued.
- If the session assigned to this conversation is a contention winner, the
session is assigned without seeking permission from the remote partner.
If the RCONTROL parameter is WSA and if the session assigned to this
conversation is a contention loser, permission is sought from the remote
partner before the allocation is permitted.
- A session is activated for this conversation if all of the following
conditions are true:
- The RCONTROL parameter is WSA
- A session is not already available for the conversation
- The session limit has not been reached for this LUNAME and
MODE.
- Note:
- PU 2.1 SLU thread sessions cannot be activated from the TPF
side. In this case, if you specify a local SLU thread, that SLU must
already be in session with the remote LU.
This verb uses TPF's EVENT and POST facility to suspend the ECB until
a session is established. If a session is not established within a
certain amount of time, the program sends a failure return code to the
transaction program. The amount of time that the system will wait is
determined by the value you specify for the TPALLOC parameter on the SNAKEY
macro. See TPF ACF/SNA Network Generation for
information about the SNAKEY macro.
ALLOCATE must know what 2 LUs are involved to activate the session.
One LU is specified with LUNAME; the other LU is determined as
follows:
- If you specify a remote LU that is in session with SLU threads, ALLOCATE
selects the thread to be used for the session.
- If you specify a local LU that is a SLU thread, a remote LU must have been
previously initialized for that SLU thread (with a CNOS INITIALIZE
request).
- If you specify a parallel sessions mode name, the LU specified on the CNOS
INITIALIZE request is used.
- The default TPF/APPC LU is used if the following conditions are
true:
- You specify single sessions
- You are not using SLU threads
- A CNOS INITIALIZE was not done.
- The LU specified on the CNOS INITIALIZE is used if the following
conditions are true:
- You specify single sessions
- A CNOS INITIALIZE was done.
- The ALLOCATE request is queued until a session becomes available for use
by this conversation if all of the following conditions are true:
- The RCONTROL parameter is WSA
- A session is not already available for this conversation
- The session limits have been reached for this LUNAME and MODE.
- If the conversation is allocated to a contention loser session, this verb
uses TPF's EVENT and POST facility to suspend the ECB until the program
receives a BID response.
If the program does not receive a BID response from the remote LU within a
certain amount of time, an UNBIND is scheduled for this session, and the
program sends a failure return code to the transaction program. The
amount of time that the system waits is determined by the value you specify
for the TPALLOC parameter on the SNAKEY macro. See TPF ACF/SNA Network Generation for information about the
SNAKEY macro.
- If the ECB that issues the ALLOCATE request does not already have a TCB ID
stored in field EBTCBID in the ECB, the ALLOCATE request represents a new TPF
transaction program instance, and a new TCB ID is stored in EBTCBID. If
EBTCBID does already have a value stored, the ALLOCATE request represents
another conversation for the same transaction program instance, and EBTCBID is
not changed.
- The mode name SNASVCMG cannot be used by a user TPF TP.
- Upon completion of the ALLOCATE, the local transaction program is in
send state, and the remote partner is in receive
state.
- See Programming Considerations for the programming considerations relating to the TPPCC
macro in general.
Examples
SYMB100 TPPCC ALLOCATE, X
LUNAME=EBX024, X
TPN=EBX000, X
RCONTROL=WSA, X
MODE=(R3) X
TYPE=BASIC, X
PIP=NO, X
SYNC=NONE, X
SECURITY=NONE, X
RESID=(R7), X
RCODE=EBW010