gtpc2ma7 | C/C++ Language Support User's Guide |
This function allocates a conversation between a TPF transaction program
and a transaction program in a remote LU.
The function assigns a resource ID (RESID) to the conversation. You
must specify this resource ID on all subsequent functions for this
conversation.
Format
#include <tppc.h>
void tppc_allocate(unsigned int *resid,
struct tppc_return_codes *rcode,
struct tppc_name *luname,
struct tppc_progname *tpn,
unsigned char *mode,
enum t_allocate_sync sync,
enum t_allocate_rcontrol rcontrol,
enum t_allocate_type type,
enum t_allocate_pip pip,
enum t_allocate_security security);
- resid
- This is a pointer to a 4-byte field where the resource ID is
returned. You must specify this resource ID on all subsequent functions
for this conversation.
- rcode
- This is a pointer to the structure tppc_return_codes, defined
in tppc.h, where the return code is to be placed.
- luname
- This is a pointer to the structure tppc_name, defined in
tppc.h. This structure 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 name is unqualified. The second 8 bytes contain the
left-justified LU name, which is padded with blanks.
- tpn
- This is a pointer to the structure tppc_progname, defined in
tppc.h, which contains the following:
- 1-byte length of the remote transaction program name
- A remote transaction program name, which can be from 1-64
characters long.
- mode
- This is a pointer to an 8-byte field that contains the mode name, which
designates the properties of the session to be allocated.
- sync
- This specifies the synchronization level allowed on this
conversation. This argument must belong to the enumeration type
t_allocate_sync, defined in tppc.h. The
allowed values are:
- ALLOCATE_SYNC_NONE
- This value specifies that the programs cannot perform confirmation
processing on this conversation.
- ALLOCATE_SYNC_CONFIRM
- This value specifies that the programs can perform confirmation processing
on this conversation.
- Note:
- The TPF system does not support the SYNCPT option of the LU 6.2
architecture.
- rcontrol
- This argument specifies when control is returned to the caller.
This argument must belong to the enumeration type
t_allocate_rcontrol, defined in tppc.h.
The allowed values are:
- ALLOCATE_RCONTROL_WSA
- This value specifies that control is returned when a session is allocated
for this conversation.
- ALLOCATE_RCONTROL_IMM
- This value 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:
- The TPF system does not support the other options defined for this parameter
by the LU 6.2 architecture.
- type
- This argument must belong to the enumeration type
t_allocate_type, defined in tppc.h. The
allowed values are:
- ALLOCATE_TYPE_BASIC
- This value provides support for the BASIC_CONVERSATION option defined by
the LU 6.2 architecture.
- ALLOCATE_TYPE_MAPPED
- This value provides support for the MAPPED_CONVERSATION option defined by
the LU 6.2 architecture. This is provided for use with your own
mapped support. See TPF/APPC Mapped Conversation Functions for information about TPF's mapped conversation
support.
- ALLOCATE_TYPE_SHAREDB
- This value provides support for the BASIC_CONVERSATION option defined by
the LU 6.2 architecture, and specifies this is a shared LU 6.2
conversation.
- ALLOCATE_TYPE_SHAREDM
- This value provides support for the MAPPED_CONVERSATION option defined by
the LU 6.2 architecture, and specifies this is a shared LU 6.2
conversation.
- pip
- This argument must belong to the enumeration type
t_allocate_pip, defined in tppc.h. Use the
value ALLOCATE_PIP_NO. PIP (program initialization parameters)
data cannot be supplied by the TPF transaction program. If PIP data is
indicated in an ATTACH header received by the TPF system, the ATTACH
conversation request is rejected.
- security
- This specifies the security level allowed on this conversation.
This argument must belong to the enumeration type
t_allocate_security, defined in tppc.h.
Use the value ALLOCATE_SECURITY_NO.
- Note:
- The TPF system does not support the SAME and PGM options supported by the LU
6.2 architecture.
Return Codes
The following table contains a list of the primary and secondary return
codes that can be returned to the program that called the
tppc_allocate function. A complete list of the return codes
and their definitions can be found in Table 37 and Table 38.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_PARAMETER_CHECK
| 0001
|
|
LU62RC_PK_BAD_OPTION
| ....
| 00C62074
|
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
- The value returned in resid must be used by all other TPF/APPC
functions called for this conversation.
- If the vlaue of the type parameter is
ALLOCATE_TYPE_SHAREDB or ALLOCATE_TYPE_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:
- tppc_send_data
- tppc_flush
- tppc_get_attributes
- tppc_deallocate (except when DEALLOCATE_TYPE_CONFIRM is specified
on the type parameter).
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 value 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
tppc_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 value for rcontrol is ALLOCATE_RCONTROL_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 ALLOCATE_RCONTROL_WSA
- A session is not already available for the conversation
- The session limits have 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 the TPF system's EVENT and POST facility to suspend the
ECB until a session is established.
If a session is not established in a certain amount of time, 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.
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 ALLOCATE_RCONTROL_WSA
- A session is not already available for the 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 the TPF system'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 in 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 tppc_allocate does not already have a
TCBID stored in field EBTCBID in the ECB, the ALLOCATE request represents a
new TPF transaction program instance, and a new TCBID is stored in
EBTCBID. If EBTCBID already has 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 transaction
program.
- When the ALLOCATE is completed, the conversation on the local transaction
program side is in send state, and the conversation on the remote
transaction program side in receive state.
- See Programming Considerations for Basic Conversation Functions for additional programming considerations relating to the
TPF/APPC basic conversation functions.
Examples
The following example establishes a conversation between a program in the
local TPF LU and a remote LU on an LU-LU session that is already
established.
#include <tppc.h>
unsigned int resource_id;
struct tppc_return_codes return_code;
struct tppc_name their_lu_name;
struct tppc_progname their_tp_name;
unsigned char modename[8] = "TPFLU62";
·
·
·
tppc_allocate(&resouce_id,&return_code,&their_lu_name, \
&their_tp_name,modename,ALLOCATE_SYNC_NONE,ALLOCATE_RCONTROL_WSA, \
ALLOCATE_TYPE_BASIC,ALLOCATE_PIP_NO,ALLOCATE_SECURITY_NO);
·
·
·
Related Information
Return Codes for Basic Conversation Functions.