storagepool add argument: Add a storage pool entry (SQL administration API)

Use the storagepool add argument with the admin() or task() function to add an entry to the storage pool (a collection of available raw devices, cooked files, or directories that OneDB can use to automatically add space to an existing storage space).

Syntax


1  EXECUTE FUNCTION
1 admin
1 task
2  (
2  " storagepool add " , "path_name"
2  , "begin_offset" , "total_size" , "chunk_size" , "priority"
2  ) ;
Element Description Key Considerations
path_name The path for the file, directory, or device that the server can use when additional storage space is required. You do not need to add a final slash (/) to a directory name.

You can use an environment variable in the path if the variable is in your environment when the oninit command runs.
begin_offset The offset in kilobytes into the device where OneDB can begin allocating space. If you specified a path to a directory, you must specify 0 as the offset.
total_size The total space available to OneDB in this entry. The server can allocate multiple chunks from this amount of space. Be sure to specify 0 for the total size of a directory. If you specify a value that is not zero for a directory, the SQL administration API command returns an error.

If you specify 0 for a file or device, the server will allocate one extendable chunk from the entry.
chunk_size The minimum size of a chunk that can be allocated from the device, file, or directory. The smallest chunk that you can create is 1000 K. Therefore, the minimum chunk size that you can specify is 1000 K.

See admin() and task() Argument Size Specifications.
priority The priority of the directory, file, or device when the server searches through the storage pool for space.
  • 1 = High priority
  • 2 = Medium priority
  • 3 = Low priority
 The server tries to allocate space from a high-priority entry before it allocates space from a lower priority entry.

Usage

The server uses entries in the storage pool if necessary to add a new chunk to a storage space.

When you add an entry to the storage pool, you might want some control over how that entry is used. For example, to reduce the number of chunks in an instance, you might want only large chunks of space to be allocated from a particular raw device, and might not want the chunks to be extendable. In this case, configure the chunk size for that storage pool entry to be large.

You can add the following types of entries to the storage pool:

  • A fixed-length raw device
  • A fixed-length cooked file
  • An extendable raw device (for extending the size of a chunk)
  • An extendable cooked file (for extending the size of a chunk)
  • A directory

A storage pool entry that is a directory is always categorized as extendable, because it does not have a total size. If new chunks are automatically created in the directory, the server marks those chunks as extendable. When you add a storage pool entry that is a directory, you might want a small chunk size, because the server can extend any chunk created in the directory and smaller chunk sizes can reduce the amount of wasted space in the instance.

If a storage pool entry is on a High-Availability Data Replication (HDR) primary server, the same path in the entry must be available on all secondary servers in the HDR cluster.

The default units for sizes and offsets are kilobytes. However, you can specify information in any of the ways shown in the following examples:

  • "100000"
  • "100000 K"
  • "100 MB"
  • "100 GB"
  • "100 TB"

Example: Adding a storage pool entry for a directory

The following command adds a directory named /region2/dbspaces with a beginning offset of 0, a total size of 0, an initial chunk size of 20 megabytes, and a high priority: 

DATABASE sysadmin;
EXECUTE FUNCTION task("storagepool add", "/region2/dbspaces", "0", "0", 
"20000", "1");

Example: Adding a storage pool entry for a fixed-length raw device

The following command adds a fixed-length raw device with the path name /dev/raw/device1 and a total of 500 megabytes of space to the storage pool. The command specifies a beginning offset of 50 megabytes, a total size of 10 gigabytes, a minimum of 100 megabytes to allocate to a chunk, and a low priority.

EXECUTE FUNCTION task("storagepool add", "/dev/rawdevice1", "50 MB",
 "10 GB", "100 MB", "3");

Example: Adding a storage pool entry for a fixed-length cooked file

The following command adds a fixed-length cooked file and 1 gigabyte of space to the storage pool. The command specifies a beginning offset of 0, a total size of 1000000 kilobytes, a minimum of 50000 kilobytes to allocate to a chunk, and a medium priority: 

EXECUTE FUNCTION task("storagepool add", "/ifmx_filesystem/storage/cooked7",
 "0", "1000000", "50000", "2");

When adding this entry, the server tries to increase the size of the cooked7 file to 1 gigabyte. If the server cannot increase the size because the file system is full, the server returns an error message and does not add the entry to the storage pool.

OneDB uses part of the cooked file initially, but can use more of the device as necessary as spaces fill.

Example: Adding a storage pool entry for an extendable cooked file

The following command adds a cooked file with the path name /ifmx/CHUNKFILES/cooked2. If the server uses this entry, the server creates one chunk with an initial size of 1 GB, and the server automatically marks the chunk as extendable. 

EXECUTE FUNCTION task("storagepool add", "/ifmx/CHUNKFILES/cooked2",
 "0", "0", "1 GB", "2");

Example: Adding a storage pool entry with an environment variable in the path

The following example includes an environment variable in the path. The variable was present in the server environment when the oninit command ran.

EXECUTE FUNCTION task("storagepool add", "$DBSDIR/chunk1",
 "0", "100000", "20000", "2");