Administrative API Reference
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 $HOME/sqllib/redist directory on UNIX based systems, using
the following format for subdirectories and file name:
database-name.nodegroup-name.timestamp.
- The $HOME\sqllib\redist\ directory on OS/2 or the Windows
operating system, using the following format for subdirectories and file
name:
database-name\first-eight-characters-of-the-nodegroup-name\date\time.
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.
See Also
sqlarbnd - Rebind.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
[ DB2 List of Books |
Search the DB2 Books ]