db2GetRowPartNum 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, db2RowPartNumStruct, is the input for this API. The information that is part of the input structure (partinfo) can be returned by the db2GetDistMap 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

db2ApiDf.h

API and data structure syntax

db2GetRowPartNum (
   sqluint32 db2VersionNumber,                      /* Database version number   */
   void * pParmStruct,                              /* In/out parameters         */
   struct sqlca * pSqlca);                          /* SQLCA                     */
where

SQL_STRUCTURE db2RowPartNumStruct
{
   unsigned short                      num_ptrs;    /* Number of pointers        */
   unsigned char                       **ptr_array; /* An array of pointers      */
                                                    /* to char string            */
   unsigned short                      *ptr_lens;   /* An array of character     */
                                                    /* string lengths            */
   unsigned short                      countrycode; /* Territory/Country         */
                                                    /* code                      */
   unsigned short                      codepage;    /* Code page                 */
   struct db2PartitioningInfo          *partinfo;   /* Partitioning              */
                                                    /* Information               */
   short                               *part_num;   /* Partition number          */
   SQL_PDB_NODE_TYPE                   *node_num;   /* Node number               */
   unsigned short                      chklvl;      /* Check level               */
   short                               dataFormat;  /* Data format               */
};

SQL_STRUCTURE db2PartitioningInfo
{
   sqluint32                           pmaplen;     /* Length of partitioning    */
                                                    /* map                       */
   SQL_PDB_NODE_TYPE                   *pmap;       /* Partitioning map          */
   unsigned short                      sqld;        /* # of used                 */
                                                    /* db2PartitioningKey        */
                                                    /* elements                  */
   struct db2PartitioningKey           sqlpartkey[SQL_MAX_NUM_PART_KEYS];    /*  */
                                                    /* KEYS                      */
};

SQL_STRUCTURE db2PartitioningKey
{
   unsigned short                      sqltype;     /* Date Type of Key          */
   unsigned short                      sqllen;      /* Data Length of Key        */
};

db2GetRowPartNum API parameters

num_ptrs

The number of pointers in ptr_array. The value must be the same as the one specified for the partinfo parameter; that is, partinfo->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.

countrycode

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.

partinfo

Information for pmaplen, pmap, sqld, sqlpartkey that can be retrieved using the db2GetDistMap API.

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.

Usage notes

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

Note: CHAR, VARCHAR, GRAPHIC, and VARGRAPHIC data types must be converted to the database code page before this API is called.

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 partinfo parameter (partinfo->pmaplen) is either 2 or 65536. Otherwise, SQLCODE -2032 is returned. The distribution key must be defined; that is, sqld field in partinfo parameter (partinfo->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.

The pmap in db2PartitioningInfo structure must point to an array of SQL_PDB_MAP_SIZE_32K entries.