ALTER TABLESPACE

The ALTER TABLESPACE statement changes attributes of a data set group within a database or an area for a DEDB. Altering a tablespace is an alter against the database resource.

Invocation

This statement can be submitted from a Java™ application program with an establish connection to IMS through the IMS Universal JDBC drivers. It is an executable statement that cannot be dynamically prepared.

ALTER TABLESPACE syntax
HSAM or SHSAM syntax
GSAM syntax
HISAM or INDEX syntax
SHISAM syntax
HDAM or HIDAM syntax
DEDB syntax

ALTER TABLESPACE syntax

HSAM or SHSAM syntax

GSAM syntax

HISAM or INDEX syntax

SHISAM syntax

HDAM or HIDAM syntax

DEDB syntax

Description

The following keyword parameters are defined for the ALTER TABLESPACE statement:

ddname

The 1- to 8-character ddname for the Fast Path database area or data set group that you want to change. The name can include alphanumeric characters and special characters (#, @, and $).

For a database area, this name can be an area name or a ddname for a data set that contains only one database area, but it must be an area name if the data set contains multiple database areas. If the database is registered with DBRC, use the area name.

HSAM | SHSAM | GSAM: The ddname of input data set. The input data set is used when an application program retrieves data from the database.
HISAM | SHISAM | INDEX: The ddname of primary data set in data set group.
HIDAM | HDAM: The ddname of data set in data set group.
DEDB: The area name or a ddname for single area data sets but can only be an area name for multiple area data sets. If the database is registered in DBRC, this parameter should specify the area name.

INdatabase_name

The name of the database that this database area or data set group belongs to.

database_name: The database this data set group belongs to.
Specifies the DBD name of a database whose data sets are to be dynamically allocated. This name is used as a member name in IMS.SDFSRESL to identify this database parameter list. Care should be taken to ensure that this name does not conflict with existing members in IMS.SDFSRESL. This includes, but is not limited to, IMS modules and user-supplied exit routines.

BLOCK PRIMARY

BLOCK SECONDARY

Is used to specify the blocking factors to be used for data sets in a data set group for HSAM, SHSAM, GSAM, HISAM, SHISAM, and INDEX databases, or is used to specify the block size or control interval size without overhead for the data set in a data set group for HDAM and HIDAM databases.

For HISAM, SHISAM, and INDEX databases that use VSAM as the access method, use the SIZE PRIMARY parameter to specify control interval size in place of the BLOCK PRIMARY or BLOCK SECONDARY parameter. If the SIZE keyword is used for a HISAM, SHISAM, or INDEX database, the BLOCK keyword is invalid.

In cases where the RECORD, BLOCK PRIMARY, and BLOCK SECONDARY operands are used, the resulting control interval size must be a multiple of 512 when the resulting size is less than 8192 bytes. If the product of the record length specified times the blocking factor specified plus VSAM overhead is not a multiple of 512 and is less than 8192 bytes, the resulting control interval size is obtained by rounding the value up to the next higher multiple of 512. Control interval sizes from 8192 to 30720 bytes (maximum allowed size) must be in multiples of 2048 bytes. When the product of the RECORD and BLOCK operands plus VSAM overhead is from 8192 to 30720 bytes but is not a multiple of 2048, the resulting control interval size is obtained by rounding the value up to the next higher multiple of 2048.

The VSAM overhead is 7 bytes if the blocking factor is 1; otherwise, it is 10 bytes. The maximum block size for OSAM data sets is 32 KB.

For HDAM and HIDAM databases, the BLOCK PRIMARY parameter is used to enable you to override the computation of control interval or block size of IMS. However, in addition to the value specified in the BLOCK PRIMARY parameter, IMS adds space for root anchor points, a free space anchor point, and access method overhead. The block or control interval size that results can be determined by referring to the equations in the description of the SIZE PRIMARY parameter or by examining the output of IMS. If the SIZE parameter is not specified and the access method is VSAM, IMS calculates the best VSAM LRECL value by equally distributing any unused space in the CI to each logical record in the CI. If the SIZE PRIMARY parameter is specified, this is not done.

The following table explains the use of the BLOCK and RECORD operands.

Table 1. BLOCK and RECORD operands
Database type	Use of BLOCK and RECORD operands
HSAM/SHSAM	BLOCK BLOCK PRIMARY applies to input data set and should always be 1. BLOCK SECONDARY applies to output data set and should always be 1. RECORD `recordlength1` is the input record length. `recordlength2` is the output record length. HSAM/SHSAM is always unblocked; LRECL and BLKSIZE are equal.
GSAM	BLOCK BLOCK PRIMARY applies to input/output data set. BLOCK SECONDARY is an invalid subparameter. RECORD `recordlength1` is the size of an LRECL length or maximum size for a variable length record. `recordlength2` is the minimum size for a variable length record. SIZE SIZE PRIMARY is the BLKSIZE for input/output data set. SIZE SECONDARY is an invalid subparameter.
HISAM/SHISAM	BLOCK BLOCK PRIMARY is the primary data set blocking factor. BLOCK SECONDARY is the overflow data set blocking factor. RECORD `recordlength1` is the data set logical record length. `recordlength2` is the overflow data set logical record length.
HIDAM, HDAM	BLOCK size0 is size without overhead of OSAM or VSAM data set group RECORD Is ignored.
DEDB	BLOCK and RECORD operands are invalid.
INDEX	BLOCK BLOCK PRIMARY is the primary data set blocking factor. BLOCK SECONDARY is the overflow data set blocking factor. RECORD `recordlength1` is the primary data set logical record length. `recordlength2` is the overflow data set logical record length.

Note: When both recordlength1 and recordlength2 are specified in a TABLESPACE statement, recordlength2 must be equal to or greater than recordlength1, except for GSAM.

FORMAT

Specifies the format of the records in the data set. The valid record formats are:

FIXED: Fixed length.
FIXEDBLOCK: Fixed length and blocked
VARIABLE: Variable length.
VARIABLEBLOCK: Variable length and blocked.
UNDEFINED: Undefined length.

This keyword is required and only valid for a GSAM database.

FREEBLOCK

Specifies the free block frequency factor. Every nth control interval or block in this data set group is left as free space during database load or reorganization. The valid range is 0-100 except 1. The default is 0.

A smaller value increases the frequency of free space in the database. A value of 2, for example, would mean that after each piece of data there would be a free space block. This causes system performance degradation when running reorganization or load utilities because of the extra processing required for the free space blocks.

FREEBLOCK is equivalent to the IMS keyword FRSPC=(fbff,)).

This keyword is optional and only valid for HDAM or HIDAM.

FREESPACE

Specifies the free space percentage factor, which is the minimum percentage of each control interval or block that is to be left as free space in this data set group. The valid range is 0-99. The default is 0.

This keyword is optional and only valid for HDAM or HIDAM.

FREESPACE is equivalent to the IMS keyword FRSPC=(,fspf)).

OUTPUT (ddname)

Specifies the 1- to 8-character alphanumeric ddname of the output data set that is required for an HSAM or SHSAM database and optional for a GSAM database. This output data set is used by IMS when loading the database. This keyword is invalid for other database access types.

OUTPUT is equivalent to the IMS keyword DD2=.

OVERFLOW (ddname)

Specifies the 1- to 8-character alphanumeric ddname of the overflow data set in this data set group. This parameter must be specified for:

An INDEX database that contains index pointer segments with non-unique keys.
All data set groups of a HISAM database except when only one segment type is defined in the HISAM database.

The following conditions apply:

Invalid for a simple HISAM (SHISAM) database.
Not required for an HISAM database that contains only one segment type.
Not required for an index DBD because all index segments are inserted in the key sequenced data set of the index.
Invalid for an INDEX database defined with an osaccess type of SHISAM.
Only valid for HISAM and INDEX database access types.

RECORD(recordlength1,recordlength2)

Specifies the data management logical record lengths to be used for this data set group. This keyword is optional and only valid for HSAM, SHSAM, GSAM, HISAM, SHISAM, INDEX.

SCAN cylinders

Specifies the number of direct-access device cylinders to be scanned when searching for available storage space during segment insertion operations. This parameter is optional and only valid for HIDAM or HDAM databases. If specified, the value must be a decimal integer that does not exceed 255. Typical values are 0 - 5. The default is 3. If 0 is specified, only the current cylinder is scanned for space.

Scanning is performed in both directions from the current cylinder position. If a scan limit value causes scanning to include an area outside of the current extent, IMS adjusts the scan limits so that scanning does not exceed current extent boundaries. If space cannot be found for segment insertion within the cylinder bounds defined by this parameter, space is used at the current end of the data set group for the database.

SEARCHA 0 | 1 | 2

Specifies the type of HD space search algorithm that IMS uses to insert a segment into an HD database.

0: Specifies that IMS chooses which HD space search algorithm to use. 0 is the default.
1: Specifies that IMS uses the HD space search algorithm that does not search for space in the second-most desirable block or CI.
2: Specifies that IMS uses the HD space search algorithm that includes a search for space in the second-most desirable block or CI.

This keyword is optional and only valid for HDAM or HIDAM database.

SIZE PRIMARY size1

For HISAM, SHISAM, INDEX, this keyword specifies control interval or block size of primary data set in a data set group.

For HDAM, HIDAM, this keyword specifies the control interval or block size of the data set in the data set group. For GSAM, this keyword specifies the block size for input/output data set.

For DEDB, this keyword is required and specifies the control interval.

This keyword is invalid for all other database types.

SIZE PRIMARY is equivalent to the IMS keyword SIZE=(size1,)).

SIZE SECONDARY size2

For HISAM, SHISAM, INDEX, this keyword specifies control interval or block size of overflow data set.

This keyword is valid only for HISAM, SHISAM, and INDEX.

SIZE SECONDARY is equivalent to the IMS keyword SIZE=(,size2))

ROOT(number1,number2)

Specifies the total space that is allocated to the root addressable part of the area and to the area reserved for independent overflow.

number1: Specifies the total space that is allocated to the root addressable part of the area. It is expressed in UOWs. The rest of the VSAM data set is reserved for sequential dependent data.
The valid range is 2-32767; it cannot be larger than the amount of space in the VSAM data set.
number2: Specifies the space that is reserved for independent overflow in terms of UOWs. It must be at least 1 and must be less than the value specified for number1. Although independent overflow does not contain UOWs, the UOW size is used as the unit for space allocation.

The reorganization UOW is automatically allocated by the DEDB Initialization utility. VSAM space definition should include this additional UOW. That is, the total space required is the root addressable area, the independent overflow, and one additional UOW for reorganization. The reorganization UOW is not used by the High-Speed DEDB Direct Reorganization utility, but might be used by other functions of IMS.

The ROOT keyword is required and only valid for DEDB.

UOW(number1,number2)

Required and only valid for DEDB. number1 specifies the number of control intervals in a unit of work. The valid range is 2-32767. number2 specifies the number of control intervals in the overflow section. Any value greater than or equal to 1 but at least one less than number1.