sqlbotcq API - Open a table space container query

Prepares for a table space container query operation, and returns the number of containers currently in the table space.

Authorization

One of the following authorities:
  • SYSADM
  • SYSCTRL
  • SYSMAINT
  • SYSMON
  • DBADM

Required connection

Database

API include file

sqlutil.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  sqlbotcq (
   struct sqlca * pSqlca,
   sqluint32 TablespaceId,
   sqluint32 * pNumContainers);

SQL_API_RC SQL_API_FN
  sqlgotcq (
   struct sqlca * pSqlca,
   sqluint32 TablespaceId,
   sqluint32 * pNumContainers);

sqlbotcq API parameters

pSqlca
Output. A pointer to the sqlca structure.
TablespaceId
Input. ID of the table space for which container data is desired. If the special identifier SQLB_ALL_TABLESPACES (in sqlutil.h) is specified, a complete list of containers for the entire database is produced.
pNumContainers
Output. The number of containers in the specified table space.

Usage notes

This API is normally followed by one or more calls to sqlbftcq, and then by one call to sqlbctcq.

An application can use the following APIs to fetch information about containers in use by table spaces:
  • sqlbtcq

    Fetches a complete list of container information. The API allocates the space required to hold the information for all the containers, and returns a pointer to this information. Use this API to scan the list of containers for specific information. Using this API is identical to calling the following three APIs - sqlbotcq, sqlbftcq, and sqlbctcq, except that this API automatically allocates the memory for the output information. A call to this API must be followed by a call to sqlefmem to free the memory.

  • sqlbotcq, sqlbftcq, and sqlbctcq

    These three APIs function like an SQL cursor, in that they use the OPEN/FETCH/CLOSE paradigm. The caller must provide the output area for the fetch. Unlike an SQL cursor, only one table space container query can be active at a time. Use this set of APIs to scan the list of table space containers for specific information. These APIs allows the user to control the memory requirements of an application (compared with sqlbtcq).

When sqlbotcq is called, a snapshot of the current container information is formed in the agent servicing the application. If the application issues a second table space container query call (sqlbtcq or sqlbotcq), this snapshot is replaced with refreshed information.

No locking is performed, so the information in the buffer may not reflect changes made by another application after the snapshot was generated. The information is not part of a transaction.

There is one snapshot buffer for table space queries and another for table space container queries. These buffers are independent of one another.