QUERY_TP

QUERY_TP returns information about transaction programs currently being used by a local LU.

The information is returned as a list. To obtain information about a specific transaction program, or to obtain the list information in several chunks, the tp_name field should be set. If the list_options field is set to AP_FIRST_IN_LIST then this field will be ignored. Note that the lu_name or lu_alias field must always be set. The lu_name field, if nonzero, will be used in preference to the lu_alias field. 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 for names of the same length. This verb returns information that is determined once the TP starts to be used by a local LU. The QUERY_TP_DEFINITION verb returns definition information only.

VCB Structure

typedef struct query_tp
{
   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   lu_name[8];          /* LU name                       */
   unsigned char   lu_alias[8];         /* LU alias                      */
   unsigned char   tp_name[64];         /* TP name                       */
} QUERY_TP;

typedef struct tp_data
{
   unsigned short  overlay_size;        /* size of this entry            */
   unsigned char   tp_name[64];         /* TP name                       */
   unsigned char   description[RD_LEN];
                                        /* resource description          */
   unsigned short  instance_limit;      /* max instance count            */
   unsigned short  instance_count;      /* current instance count        */
   unsigned short  locally_started_count;
                                        /* locally started instance      */
                                        /* count                         */
   unsigned short  remotely_started_count;
                                        /* remotely started instance     */
                                        /* count                         */
   unsigned char   reserva[20];         /* reserved                      */
} TP_DATA;

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

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: The combination of lu_name (or lu_alias if the lu_name is set to all zeros) and tp_name specified (see the following parameters, lu_name and 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.

lu_name

LU name. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the index.

lu_alias

Locally defined LU alias. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_name and the lu_alias are set to all zeros, the LU that is associated with the control point (the default LU) is used.

tp_name

Transaction program name. 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_data.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
tp_data.tp_name: Transaction program name. This is a 64-byte string, padded to the right with spaces.
tp_data.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_data.instance_limit: Maximum number of concurrently active instances of the specified transaction program.
tp_data.instance_count: Number of instances of the specified transaction program that are currently active.
tp_data.locally_started_count: Number of instances of the specified transaction program which have been started locally (by the transaction program issuing a TP_STARTED verb).
tp_data.remotely_started_count: Number of instances of the specified transaction program that have been started remotely (by a received Attach request).
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_LU_NAME
AP_INVALID_LU_ALIAS
AP_INVALID_LIST_OPTION

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 of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR