QUERY_TP_DEFINITION

QUERY_TP_DEFINITION returns both information previously passed in on a DEFINE_TP verb and information about Personal Communications or Communications Server defined transaction programs.

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific transaction program, or to obtain the list information in several chunks, the tp_name field should be set.

Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by the tp_name, using EBCDIC lexicographical ordering. If AP_LIST_FROM_NEXT is selected the returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

This verb returns definition information only. The QUERY_TP verb returns information that is determined once the transaction program starts to be used by a local LU.

VCB Structure

typedef struct query_tp_definition
{
   unsigned short  opcode;             /* Verb operation code           */
   unsigned char   attributes;         /* verb attributes               */
   unsigned char   format;             /* format                        */
   unsigned short  primary_rc;         /* Primary return code           */
   unsigned long   secondary_rc;       /* Secondary return code         */
   unsigned char   *buf_ptr;           /* pointer to buffer             */
   unsigned long   buf_size;           /* buffer size                   */
   unsigned long   total_buf_size;     /* total buffer size required    */
   unsigned short  num_entries;        /* number of entries             */
   unsigned short  total_num_entries;  /* total number of entries       */
   unsigned char   list_options;       /* listing options               */
   unsigned char   reserv3;            /* reserved                      */
   unsigned char   tp_name[64];        /* TP name                       */
} QUERY_TP_DEFINITION;
typedef struct tp_def_summary
{
   unsigned short  overlay_size;       /* size of this entry            */
   unsigned char   tp_name[64];        /* TP name                       */
   unsigned char   description[RD_LEN];
                                       /* resource description          */
} TP_DEF_SUMMARY;
typedef struct tp_def_detail
{
   unsigned short  overlay_size;       /* size of this entry            */
   unsigned char   tp_name[64];        /* TP name                       */
   TP_CHARS        tp_chars;           /* TP characteristics            */
} TP_DEF_DETAIL;
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 (AP_YES)            */
  unsigned char load_type;             /* type of load-DETACHED/CONSOLE */
  unsigned char dynamic_load;          /* dynamic loading of TP enabled */
  unsigned char reserved[5];           /* max size is 120 bytes         */
} TP_SPEC_DATA;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_TP_DEFINITION
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.
buf_ptr
Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information:
AP_SUMMARY
Returns summary information only.
AP_DETAIL
Returns detailed information.

The tp_name specified (see the following parameter, tp_name) represents an index value that is used to specify the starting point of the actual information to be returned:

AP_FIRST_IN_LIST
The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE
The returned list starts from the entry specified by the index value.
tp_name
Name of the defined transaction program. This is a 64-byte string, padded to the right with spaces. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries
Number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
tp_def_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
tp_def_summary.tp_name
Defined transaction program name. This is a 64-byte string, padded to the right with spaces.
tp_def_summary.description
Resource description (as specified on DEFINE_TP). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
tp_def_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
tp_def_detail.tp_name
Defined transaction program name. This is a 64-byte string, padded to the right with spaces.
tp_def_detail.tp_chars.description
Resource description (as specified on DEFINE_TP). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
tp_def_detail.tp_chars.conv_type
Specifies the types of conversation supported by the transaction program:

AP_BASIC
AP_MAPPED
AP_EITHER

tp_def_detail.tp_chars.security_rqd
Specifies whether conversation security information is required to start the transaction program (AP_NO or AP_YES).
tp_def_detail.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_def_detail.tp_chars.dynamic_load
Specifies whether the transaction program can be dynamically loaded (AP_YES or AP_NO).
tp_def_detail.tp_chars.enabled
Specifies whether the transaction program can be attached successfully (AP_YES or AP_NO). The default is AP_NO.
tp_def_detail.tp_chars.pip_allowed
Specifies whether the transaction program can receive program initialization (PIP) parameters (AP_YES or AP_NO).
tp_def_detail.tp_chars.duplex_support
Indicates whether the transaction program is full or half duplex.
AP_FULL_DUPLEX
Specifies the transaction program is full duplex.
AP_HALF_DUPLEX
Specifies the transaction program is half duplex.
AP_EITHER_DUPLEX
Specifies the transaction program can be either half or full duplex
tp_def_detail.tp_chars.tp_instance_limit
Limit on the number of concurrently active transaction program instances.
tp_def_detail.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_def_detail.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_def_detail.tp_chars.tp_data_len
Length of the implementation-dependent transaction program data.
tp_def_detail.tp_chars.tp_data
Implementation-dependent transaction program data that is passed unchanged on the DYNAMIC_LOAD_INDICATION.
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 how the transaction program will be loaded.
tp_spec_data.dynamic_load
Specifies whether the TP can be dynamically loaded (AP_YES or AP_NO).
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_INVALID_TP_NAME

AP_INVALID_LIST_OPTION

If the verb does not execute because the node has not yet been started, the Program returns the following parameters:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR