Administrative API Reference

sqlugrpn - Get Row Partitioning Number

Returns the partition number and the node number based on the partitioning key values. An application can use this information to determine at which node a specific row of a table is stored.

The partitioning data structure, SQLUPI, is the input for this API. The structure can be returned by sqlugtpi - Get Table Partitioning Information. Another input is the character representations of the corresponding partitioning key values. The output is a partition number generated by the partitioning strategy and the corresponding node number from the partitioning map. If the partitioning map information is not provided, only the partition number is returned. This can be useful when analyzing data distribution.

The database manager does not need to be running when this API is called.

Scope

This API can be invoked from any node in the db2nodes.cfg file.

Authorization

None

Version

sqlutil.h

C API Syntax 



/* File: sqlutil.h */
/* API: Get Row Partitioning Number */
/* ... */
SQL_API_RC SQL_API_FN
  sqlugrpn (
    unsigned short num_ptrs,
    unsigned char ** ptr_array,
    unsigned short * ptr_lens,
    unsigned short ctrycode,
    unsigned short codepage,
    struct sqlupi * part_info,
    short * part_num,
    SQL_PDB_NODE_TYPE * node_num,
    unsigned short chklvl,
    struct sqlca * sqlca,
    short dataformat,
    void * pReserved1,
    void * pReserved2);
/* ... */

Generic API Syntax 



/* File: sqlutil.h */
/* API: Get Row Partitioning Number */
/* ... */
SQL_API_RC SQL_API_FN
  sqlggrpn (
    unsigned short num_ptrs,
    unsigned char ** ptr_array,
    unsigned short * ptr_lens,
    unsigned short ctrycode,
    unsigned short codepage,
    struct sqlupi * part_info,
    short * part_num,
    SQL_PDB_NODE_TYPE * node_num,
    unsigned short chklvl,
    struct sqlca * sqlca,
    short dataformat,
    void * pReserved1,
    void * pReserved2);
/* ... */

API Parameters

num_ptrs
The number of pointers in ptr_array. The value must be the same as the one specified for part_info; that is, part_info->sqld.

ptr_array
An array of pointers that points to the character representations of the corresponding values of each part of the partitioning key specified in part_info. If a null value is required, the corresponding pointer is set to null.

ptr_lens
An array of unsigned integers that contains the lengths of the character representations of the corresponding values of each part of the partitioning key specified in part_info.

ctrycode
The country code of the target database. For a list of valid country code values, see one of the Quick Beginnings books.

This value can also be obtained from the database configuration file (see the GET DATABASE CONFIGURATION command in the Command Reference.

codepage
The code page of the target database. For a list of valid code page values, see one of the Quick Beginnings books.

This value can also be obtained from the database configuration file (see the GET DATABASE CONFIGURATION command in the Command Reference.

part_info
A pointer to the sqlupi structure. For more information about this structure, see SQLUPI.

part_num
A pointer to a 2-byte signed integer that is used to store the partition number.

node_num
A pointer to an SQL_PDB_NODE_TYPE field used to store the node number. If the pointer is null, no node number is returned.

chklvl
An unsigned integer that specifies the level of checking that is done on input parameters. If the value specified is zero, no checking is done. If any non-zero value is specified, all input parameters are checked.

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

dataformat
Specifies the representation of partitioning key values. Valid values are:

SQL_CHARSTRING_FORMAT
All partitioning key values are represented by character strings. This is the default value.

SQL_IMPLIEDDECIMAL_FORMAT
The location of an implied decimal point is determined by the column definition. For example, if the column definition is DECIMAL(8,2), the value 12345 is processed as 123.45.

SQL_PACKEDDECIMAL_FORMAT
All decimal column partitioning key values are in packed decimal format.

SQL_BINARYNUMERICS_FORMAT
All numeric partitioning key values are in big-endian binary format.

pReserved1
Reserved for future use.

pReserved2
Reserved for future use.

Usage Notes

Data types supported on the operating system are the same as those that can be defined as a partitioning key.

CHAR, VARCHAR, GRAPHIC, and VARGRAPHIC must be converted to the target code page before this API is called.

For numeric and datetime data types, the character representations must be at the code page of the respective system where the API is invoked.

If node_num is not NULL, the partitioning map must be supplied; that is, part_info->pmaplen is either 2 or 8 192. Otherwise, SQLCODE -6038 is returned.

The partitioning key must be defined; that is, part_info->sqld must be greater than zero. Otherwise, SQLCODE -2032 is returned.

If a null value is assigned to a non-nullable partitioning column, SQLCODE -6039 is returned.

All the leading blanks and trailing blanks of the input character string are stripped, except for the CHAR, VARCHAR, GRAPHIC, and VARGRAPHIC data types, where only trailing blanks are stripped.

See Also

sqlfxdb - Get Database Configuration

sqlugtpi - Get Table Partitioning Information

sqludrdt - Redistribute Nodegroup.

[ Top of Page | Previous Page | Next Page ]