Administrative API Reference

sqlbotsq - Open Tablespace Query

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

Authorization

One of the following:

• sysadm
• sysctrl
• sysmaint
• dbadm
• load

Required Connection

Database

Version

sqlutil.h

C API Syntax

/* File: sqlutil.h */ /* API: Open Tablespace Query */ /* ... */ SQL_API_RC SQL_API_FN sqlbotsq ( struct sqlca * pSqlca, sqluint32 TablespaceQueryOptions, sqluint32 * pNumTablespaces); /* ... */

Generic API Syntax

/* File: sqlutil.h */ /* API: Open Tablespace Query */ /* ... */ SQL_API_RC SQL_API_FN sqlgotsq ( struct sqlca * pSqlca, sqluint32 TablespaceQueryOptions, sqluint32 * pNumTablespaces); /* ... */

API Parameters

pSqlca

Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

TablespaceQueryOptions

Input. Indicates which table spaces to process. Valid values (defined in sqlutil) are:

SQLB_OPEN_TBS_ALL

Process all the table spaces in the database.

SQLB_OPEN_TBS_RESTORE

Process only the table spaces that the user's agent is restoring.

pNumTablespaces

Output. The number of table spaces in the connected database.

Sample Programs

C

\sqllib\samples\c\tabspace.sqc

COBOL

\sqllib\samples\cobol\tabspace.sqb

Usage Notes

This API is normally followed by one or more calls to sqlbftpq - Fetch Tablespace Query, and then by one call to sqlbctsq - Close Tablespace Query.

An application can use the following APIs to fetch information about the currently defined table spaces:

• sqlbstpq - Single Tablespace Query

  Fetches information about a given table space. Only one table space entry is returned (into a space provided by the caller). Use this API when the table space identifier is known, and information about only that table space is desired.

• sqlbmtsq - Tablespace Query

  Fetches information about all table spaces. The API allocates the space required to hold the information for all table spaces, and returns a pointer to this information. Use this API to scan the list of table spaces when searching for specific information. Using this API is identical to calling the three APIs below, 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 - Free Memory to free the memory.

• sqlbotsq - Open Tablespace Query
• sqlbftpq - Fetch Tablespace Query
• sqlbctsq - Close Tablespace Query

  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 query may be active at a time. Use this set of APIs to scan the list of table spaces when searching for specific information. This set of APIs allows the user to control the memory requirements of an application (compared with sqlbmtsq - Tablespace Query).

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

No locking is performed, so the information in the buffer may not reflect more recent changes made by another application. 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.

See Also

sqlbctsq - Close Tablespace Query

sqlbftpq - Fetch Tablespace Query

sqlbstpq - Single Tablespace Query

sqlbmtsq - Tablespace Query.