gtpc2ma7C/C++ Language Support User's Guide

tppc_allocate-Allocate a Conversation

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:

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

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.