DEFINE_TP

The DEFINE_TP verb defines transaction program (TP) information for use by the Node Operator Facility TP Attach Manager when it processes incoming attaches from partner LUs. This verb can also be used to modify one or more fields on a previously defined transaction program (but cannot be used to modify Personal Communications or Communications Server defined transaction programs).

VCB Structure

typedef struct define_tp
{
        unsigned short  opcode;            /* verb operation code           */
        unsigned char   attributes;        /* verb attributes               */
        unsigned char   reserv2;           /* reserved                      */
        unsigned char   format;            /* format                        */
        unsigned short  primary_rc;        /* primary return code           */
        unsigned long   secondary_rc;      /* secondary return code         */
        unsigned char   tp_name[64];       /* TP name                       */
        TP_CHARS        tp_chars;          /* TP characteristics            */
} DEFINE_TP;

typedef struct tp_chars
{
        unsigned char   description[RD_LEN]
                                           /* resource description          */
        unsigned char   conv_type;         /* conversation type             */
        unsigned char   security_rqd;      /* security support              */
        unsigned char   sync_level;        /* synchronization level support */
        unsigned char   dynamic_load;      /* dynamic load                  */
        unsigned char   enabled;           /* is the TP enabled?            */
        unsigned char   pip_allowed;       /* program initialization        */
                                           /* parameters supported          */
        unsigned char   duplex_support;    /* duplex supported              */
        unsigned char   reserv3[9];        /* reserved                      */
        unsigned short  tp_instance_limit; /* limit on currently active TP  */
                                           /* instances                     */
        unsigned short  incoming_alloc_timeout;
                                           /* incoming allocation timeout   */
        unsigned short  rcv_alloc_timeout; /* receive allocation timeout    */
        unsigned short  tp_data_len;       /* TP data length                */
        TP_SPEC_DATA    tp_data;           /* TP data                       */
} TP_CHARS;

typedef struct tp_spec_data
{
        unsigned char   pathname[256];     /* path and TP name              */
        unsigned char   parameters[64];    /* parameters for TP             */
        unsigned char   queued;            /* queued TP                     */
        unsigned char   load_type;         /* type of load-DETACHED/CONSOLE */
        unsigned char   dynamic_load       /* dynamic loading of TP enabled */
        unsigned char   reserved[5];       /* reserved                      */
} TP_SPEC_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_TP

attributes

The attributes of the verb. This field is a bit field. The first bit contains the visibility of the resource to be defined and corresponds to one of the following:

AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

tp_name

Name of the transaction program (TP) being defined. This is a 64-byte EBCDIC string padded to the right with EBCDIC spaces. Note that Personal Communications or Communications Server does not check the character set of this field.

tp_chars.description

Resource description (returned on QUERY_TP_DEFINITION and QUERY_TP). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.

tp_chars.conv_type

Specifies the types of conversation supported by this transaction program.

AP_BASIC
AP_MAPPED
AP_EITHER

tp_chars.security_rqd

Specifies whether conversation security information is required to start the transaction program (AP_NO or AP_YES).

tp_chars.sync_level

Specifies the synchronization levels supported by the transaction program.

AP_NONE: The transaction program supports a synchronization level of None.
AP_CONFIRM_SYNC_LEVEL: The transaction program supports a synchronization level of Confirm.
AP_EITHER: The transaction program supports a synchronization level of None or Confirm.
AP_SYNCPT_REQUIRED: The transaction program supports a synchronization level of Sync-point.
AP_SYNCPT_NEGOTIABLE: The transaction program supports a synchronization level of None, Confirm or Sync-point.

tp_chars.dynamic_load

Specifies whether the transaction program can be dynamically loaded (AP_YES or AP_NO).

tp_chars.enabled

Specifies whether the transaction program can be attached successfully (AP_YES or AP_NO). The default is AP_NO.

tp_chars.pip_allowed

Specifies whether the transaction program can receive program initialization (PIP) parameters (AP_YES or AP_NO).

tp_chars.duplex_support

Indicates whether the transaction program is full or half duplex.

AP_FULL_DUPLEX: Specifies that the transaction program is full duplex.
AP_HALF_DUPLEX: Specifies that the transaction program is half duplex.
AP_EITHER_DUPLEX: Specifies that the transaction program can be either half or full duplex.

tp_chars.tp_instance_limit

Limit on the number of concurrently active transaction program instances. A value of zero means no limit.

tp_chars.incoming_alloc_timeout

Specifies the number of seconds that an incoming attach will be queued waiting for a RECEIVE_ALLOCATE. Zero implies no timeout, and so it will be held indefinitely.

tp_chars.rcv_alloc_timeout

Specifies the number of seconds that a RECEIVE_ALLOCATE verb will be queued while waiting for an Attach. Zero implies no timeout, and so it will be held indefinitely.

tp_chars.tp_data_len

Length of the implementation-dependent transaction program data.

tp_spec_data

Information used by the Attach Manager when launching the transaction program. Refer to the information about Attach Manager in Client/Server Communications Programming for further details of how this is used.

tp_spec_data.pathname

Specifies the path and transaction program name.

tp_spec_data.parameters

Specifies the parameters for the transaction program.

tp_spec_data.queued

Specifies whether the transaction program will be queued.

tp_spec_data.load_type

Specifies whether type of load is either AP_AM_CONSOLE, AP_AM_DETACHED or AP_AM_WINDOW.

tp_spec_data.dynamic_load

Specifies how the transaction program will be loaded.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:

primary_rc: AP_OK

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_SYSTEM_TP_CANT_BE_CHANGED
AP_INVALID_CONV_TYPE
AP_INVALID_SYNC_LEVEL
AP_INVALID_DYNAMIC_LOAD
AP_INVALID_ENABLED
AP_INVALID_PIP_ALLOWED
AP_INVALID_DUPLEX_SUPPORT

If the verb does not execute because of a state error, the Program returns the following parameters:

primary_rc: AP_STATE_CHECK
secondary_rc: AP_CANT_MODIFY_VISIBILITY

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because the node is stopping, the Program returns the following parameter:

primary_rc: AP_NODE_STOPPING

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR

Effects Of Redefinition: The redefinition of each field takes effect immediately (for example, when the next instance of the transaction program is started). However, changes to the fields incoming_alloc_timeout and rcv_alloc_timeout will not effect any attaches or RECEIVE_ALLOCATES that are already queued.