Administrative API Reference

sqludrdt - Redistribute Nodegroup

Redistributes data across the nodes in a nodegroup. The current data distribution, whether it is uniform or skewed, can be specified. The redistribution algorithm selects the partitions to be moved based on the current data distribution.

This API can only be called from the catalog node. Use the LIST DATABASE DIRECTORY command (see the Command Reference) to determine which node is the catalog node for each database.

Scope

This API affects all nodes in the nodegroup.

Authorization

One of the following:

Version

sqlutil.h

C API Syntax 



/* File: sqlutil.h */
/* API: Redistribute Nodegroup */
/* ... */
SQL_API_RC SQL_API_FN
  sqludrdt (
    char * pNodeGroupName,
    char * pTargetPMapFileName,
    char * pDataDistFileName,
    SQL_PDB_NODE_TYPE * pAddList,
    unsigned short AddCount,
    SQL_PDB_NODE_TYPE * pDropList,
    unsigned short DropCount,
    unsigned char DataRedistOption,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlutil.h */
/* API: Redistribute Nodegroup */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgdrdt (
    unsigned short NodeGroupNameLen,
    unsigned short TargetPMapFileNameLen,
    unsigned short DataDistFileNameLen,
    char * pNodeGroupName,
    char * pTargetPMapFileName,
    char * pDataDistFileName,
    SQL_PDB_NODE_TYPE * pAddList,
    unsigned short AddCount,
    SQL_PDB_NODE_TYPE * pDropList,
    unsigned short DropCount,
    unsigned char DataRedistOption,
    struct sqlca * pSqlca);
/* ... */

API Parameters

NodeGroupNameLen
The length of the name of the nodegroup.

TargetPMapFileNameLen
The length of the name of the target partitioning map file.

DataDistFileNameLen
The length of the name of the data distribution file.

pNodeGroupName
The name of the nodegroup to be redistributed.

pTargetPMapFileName
The name of the file that contains the target partitioning map. If a directory path is not specified as part of the file name, the current directory is used. This parameter is used when the DataRedistOption value is T. The file should be in character format and contain either 4 096 entries (for a multi-node nodegroup) or 1 entry (for a single-node nodegroup). Entries in the file indicate node numbers. Entries can be in free format.

pDataDistFileName
The name of the file that contains input distribution information. If a directory path is not specified as part of the file name, the current directory is used. This parameter is used when the DataRedistOption value is U. The file should be in character format and contain 4 096 positive integer entries. Each entry in the file should indicate the weight of the corresponding partition. The sum of the 4 096 values should be less than or equal to 4 294 967 295.

pAddList
The list of nodes to add to the nodegroup during the data redistribution. Entries in the list must be in the form: SQL_PDB_NODE_TYPE.

AddCount
The number of nodes to add to the nodegroup.

pDropList
The list of nodes to drop from the nodegroup during the data redistribution. Entries in the list must be in the form: SQL_PDB_NODE_TYPE.

DropCount
The number of nodes to drop from the nodegroup.

DataRedistOption
A single character that indicates the type of data redistribution to be done. Possible values are:

U
Specifies to redistribute the nodegroup to achieve a balanced distribution. If pDataDistFileName is null, the current data distribution is assumed to be uniform (that is, each hash partition represents the same amount of data). If pDataDistFileName is not null, the values in this file are assumed to represent the current data distribution. When the DataRedistOption is U, the pTargetPMapFileName should be null.

Nodes specified in the add list are added, and nodes specified in the drop list are dropped from the nodegroup.

T
Specifies to redistribute the nodegroup using pTargetPMapFileName. For this option, pDataDistFileName, pAddList, and pDropList should be null, and both AddCount and DropCount must be zero.

C
Specifies to continue a redistribution operation that failed. For this option, pTargetPMapFileName, pDataDistFileName, pAddList, and pDropList should be null, and both AddCount and DropCount must be zero.

R
Specifies to roll back a redistribution operation that failed. For this option, pTargetPMapFileName, pDataDistFileName, pAddList, and pDropList should be null, and both AddCount and DropCount must be zero.

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

REXX API Syntax

This API can be called from REXX through the SQLDB2 interface. See How the API Descriptions are Organized, or the Application Development Guide. For a description of the syntax, see the Command Reference.

Usage Notes

When a redistribution operation is done, a message file is written to:

The time stamp value is the time at which the API was called.

This utility performs intermittent COMMITs during processing.

Use the ALTER NODEGROUP statement to add nodes to a nodegroup. This statement permits one to define the containers for the table spaces associated with the nodegroup. See the SQL Reference for details.
Note:DB2 Parallel Edition for AIX Version 1 syntax, with ADD NODE and DROP NODE options, is supported for users with sysadm or sysctrl authority. For ADD NODE, containers are created like the containers on the lowest node number of the existing nodes within the nodegroup.

All packages having a dependency on a table that has undergone redistribution are invalidated. It is recommended to explicitly rebind such packages after the redistribute nodegroup operation has completed. Explicit rebinding eliminates the initial delay in the execution of the first SQL request for the invalid package. The redistribute message file contains a list of all the tables that have undergone redistribution.

It is also recommended to update statistics by issuing sqlustat - Runstats after the redistribute nodegroup operation has completed.

Nodegroups containing replicated summary tables or tables defined with DATA CAPTURE CHANGES cannot be redistributed.

Redistribution is not allowed if there are user temporary table spaces with existing declared temporary tables in the nodegroup.

See Also

sqlarbnd - Rebind.

[ Top of Page | Previous Page | Next Page ]