gtpc2maq | C/C++ Language Support User's Guide |
This function establishes a conversation with the partner program specified
by the TP_name and partner_LU_name
characteristics. This function establishes only mapped
conversations.
Format
#include <tpfmap.h>
void cmallc(unsigned char *conversation_ID,
signed int *return_code);
- conversation_ID
- This is a pointer to an 8-byte character array that contains the
conversation ID. This conversation ID must be the ID assigned on the
previous cminit (INITIALIZE) for this conversation.
- return_code
- This is a pointer to a 4-byte field where the return code is to be
placed.
Return Codes
The following is a list of return codes that can be returned to the program
that called the cmallc function. A complete list of the
return codes and their definitions can be found in Table 45.
- CM_OK
- CM_ALLOCATE_FAILURE_NO_RETRY
- CM_ALLOCATE_FAILURE_RETRY
- CM_PARAMETER_ERROR -- The mode_name, TP_name,
or partner_LU_name characteristic is invalid.
- CM_PRODUCT_SPECIFIC_ERROR
- CM_PROGRAM_PARAMETER_CHECK -- The specified conversation_ID
is invalid.
- CM_PROGRAM_STATE_CHECK -- The conversation is not in
initialize state.
- CM_UNSUCCESSFUL -- No session is immediately available, and the
return_control characteristic is set to CM_IMMEDIATE.
Programming Considerations
- You can execute this function on any I-stream.
- The conversation must be in initialize state.
- The value supplied in conversation_ID must be the conversation ID
returned by the cminit function.
- The first 4 bytes of the value supplied in conversation_ID is
stored in field EBCCBID in the ECB. This value changes with every
ALLOCATE request.
- The following characteristics can affect this function:
- mode_name
- mode_name_length
- partner_LU_name
- partner_LU_name_length
- return_control
- sync_level
- TP_name
- TP_name_length.
- If you are allocating a secondary LU (SLU) thread session, you must
specify a single session mode name for the partner_LU_name
characteristic. Parallel sessions are not supported for SLU
threads.
- If the return_control characteristic is set to
CM_IMMEDIATE, the cmallc function does not wait if there
is no contention winner session immediately available. If the
characteristic is set to CM_WHEN_SESSION_ALLOCATED, the ECB is
suspended until a session becomes available.
- A session is activated for this conversation if all of the following
conditions are true:
- The return_control characteristic is set to
CM_WHEN_SESSION_ALLOCATED
- A session is not already available for the conversation
- The session limits have not been reached for the remote LU and
the mode name.
- Note:
- PU 2.1 secondary LU (SLU) thread sessions cannot be activated from the
TPF side. In this case, if the partner_LU_name
characteristic specifies a local secondary LU (SLU) thread, that SLU must
already be in session with the remote LU.
ALLOCATE must know what 2 LUs are involved to activate the session.
One LU is specified with the partner_LU_name characteristic;
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 return_control characteristic is set to
CM_WHEN_SESSION_ALLOCATED
- A session is not already available for the conversation
- The session limits have been reached for the remote LU and the mode
name.
- If there is no session currently active and the return_control
characteristic is set to CM_WHEN_SESSION_ALLOCATED, 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.
- 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 cmallc 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 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 transaction
program.
- If the return_code is CM_OK, the conversation on the local
transaction program side enters send state, and the conversation on
the remote transaction program side enters receive state.
- If the local LU discovers an error with the allocation request, the
program is notified immediately. However, if the remote LU rejects the
allocation request, the program is notified by a later function's return
code.
- The ATTACH is buffered until the buffer is full or a verb that implies the
cmflus function is issued.
Examples
The following example allocates a conversation.
#include <tpfmap.h>
unsigned char convid[8];
signed int rcode;
.
.
.
cmallc(convid,&rcode,);
.
.
.
Related Information