sqlugrpn API - Get the database partition server number for a row
Returns the database partition number and the database partition server number based on the distribution key values. An application can use this information to determine on which database partition server 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 the sqlugtpi API. Another input is the character representations of the corresponding distribution key values. The output is a database partition number generated by the distribution strategy and the corresponding database partition server number from the distribution map. If the distribution map information is not provided, only the database 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 must be invoked from a database partition server in the db2nodes.cfg file. This API should not be invoked from a client, since it could result in erroneous database partitioning information being returned due to differences in code page and endianess between the client and the server.
Authorization
None
API include file
sqlutil.h
API and data structure syntax
SQL_API_RC SQL_API_FN
sqlugrpn (
unsigned short num_ptrs,
unsigned char ** ptr_array,
unsigned short * ptr_lens,
unsigned short territory_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);
SQL_API_RC SQL_API_FN
sqlggrpn (
unsigned short num_ptrs,
unsigned char ** ptr_array,
unsigned short * ptr_lens,
unsigned short territory_code,
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);
sqlugrpn API parameters
- num_ptrs
- The number of pointers in ptr_array. The value must be the same as the one specified for the part_info parameter; 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 distribution key specified in part_info. If a null value is required, the corresponding pointer is set to null. For generated columns, this function does not generate values for the row. The user is responsible for providing a value that will lead to the correct partitioning of the row.
- 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.
- territory_ctrycode
- The country/region code of the target database. This value can also be obtained from the database configuration file using the GET DATABASE CONFIGURATION command.
- codepage
- The code page of the target database. This value can also be obtained from the database configuration file using the GET DATABASE CONFIGURATION command.
- part_info
- A pointer to the sqlupi structure.
- part_num
- A pointer to a 2-byte signed integer that is used to store the database 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.
- dataformat
- Specifies the representation of distribution key values. Valid
values are:
- SQL_CHARSTRING_FORMAT
- All distribution 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 distribution key values are in packed decimal format.
- SQL_BINARYNUMERICS_FORMAT
- All numeric distribution key values are in big-endian binary format.
- pReserved1
- Reserved for future use.
- pReserved2
- Reserved for future use.
Usage notes
For numeric and datetime data types, the character representations must be at the code page of the corresponding system where the API is invoked.
If node_num is not null, the distribution map must be supplied; that is, pmaplen field in part_info parameter (part_info->pmaplen) is either 2 or 8192. Otherwise, SQLCODE -6038 is returned. The distribution key must be defined; that is, sqld field in part_info parameter (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.