ALTER DATABASE

Invocation

• PHIDAM syntax
• HDAM syntax
• HIDAM syntax
• PHDAM syntax
• GSAM syntax
• HISAM syntax
• SHISAM syntax
• DEDB syntax
• HSAM syntax
• SHSAM syntax
• LOGICAL syntax
• INDEX syntax
• PSINDEX syntax

PHIDAM syntax

A

B

HDAM syntax

A

B

HIDAM syntax

A

B

PHDAM syntax

A

B

GSAM syntax

HISAM syntax

A

B

SHISAM syntax

A

B

DEDB syntax

A

B

HSAM syntax

SHSAM syntax

LOGICAL syntax

INDEX syntax

PSINDEX syntax

Description

database_name

Name of the database to be altered. The name can be from 1- to 8-alphanumeric characters.

CCSID 'encoding'

An optional 1- to 25-character field that specifies the default encoding of all character data in this database. The CCSID is stored as metadata in the Catalog. The OpenDatabase/JDBC drivers use this metadata for preparing result sets with the proper encoding type.

This value cannot contain the following characters:

• Single and double quotation marks
• Blanks
• Less than (< ) and greater than ( >) symbols
• Ampersands (&)

This value can be overridden in individual segments or fields.

DATA CAPTURE

When DATA CAPTURE is specified on the CREATE DATABASE statement, these options apply to all tables within the physical database. If you specify this parameter in the CREATE or ALTER TABLE statement, it overrides the specification for this statement.

The following physical databases support DATA CAPTURE:

• HISAM
• SHISAM
• HDAM
• PHDAM
• HIDAM
• PHIDAM
• DEDB

NONE

Indicates no data capture options.

CHANGES

You can specify any number of exit routines, each with its own set of change options. If you do not provide an exit routine, they can only specify 1 set of change options for logging. This method is equivalent to specifying an asterisk (*) in place of an exit routine name on the EXIT= parameter in a DBD macro statement. Each set is separated by a comma. NOCASCADE is mutually exclusive with any combination of the C* (for example, CKEY) options.

The following options are valid for DATA CAPTURE CHANGES:

NOBEFORE | BEFORE

Before data is included in X'99' log records for REPL calls. NOBEFORE is the default. This attribute is valid only for DEDB.

CDATA | CNODATA

Passes segment data to the exit routine for a cascade delete. CDATA also identifies the segment being deleted when the physical concatenated key is unable to do so. This attribute is mutually exclusive with NOCASCADE.

CKEY | CNOKEY

Passes the physical concatenated key to the exit. This key identifies the segment being deleted by a cascade delete. This attribute is mutually exclusive with NOCASCADE.

CNOPATH | CPATH

Indicates the exit routine does not require segment data in the physical root's hierarchical path. Use CNODATA to eliminate the substantial amount of path data needed for a cascade delete. This attribute is mutually exclusive with NOCASCADE.

DATA | NODATA

DATA specifies that the physical table data is passed to the exit routine for updating. When DATA is specified and an EDITPROC exit routine is also used on a table, the data passed is expanded data. DATA is the default.

NODLET |DLET

X'99' log records are written for DLET calls. NODLET is the default. This attribute is valid only for DEDB.

exitname

Specifies the name of the exit routine that processes the data. The name must match the name of a Data Capture exit routine as defined by the user to IMS. A maximum of 8 alphanumeric characters is allowed.

KEY | NOKEY

KEY specifies the exit routine is passed the physical concatenated key. This key identifies the physical table updated by the application. KEY is the default.

NOCASCADE

Indicates the exit routine is not called when DL/I deletes this segment. Cascade delete is not necessary when a segment without dependents is deleted.

NOFLD | FLD

The FLD option requests that updates made by a DEDB FLD call be captured. This option is valid only for a DEDB, and this information is logged only in the X'9904' log records if the option log is specified. This information is not passed to the data capture exit. This attribute is valid only for DEDB.

NOINPOS | INPOS

The INPOS option requests that twin data be passed when an ISRT is done for an unkeyed or non-unique keyed segment when an insert rule of HERE is used and the F or L command code is not used. The twin data IMS is positioned on at the time before the ISRT will be captured.

NOLOG | LOG

The LOG option requests that the data capture control blocks and data be written to the IMS system log.

For more information, see Asynchronous data propagation.

NOPATH | PATH

NOPATH indicates the exit routine does not require data from tables in the physical root's hierarchical path. NOPATH is an efficient way to avoid the processing time needed to retrieve path data. NOPATH is the default.

PATH can be specified when the data from each segment in the physical root's hierarchical path must be passed to the exit routine for an updated segment. Use PATH to allow an application to separately access several segments for insertion, replacement, or deletion.

You can use the PATH option when information from tables in the path is needed to compose the DB2® for z/OS primary key. The DB2 for z/OS primary key would then be used in a propagation request for a dependent table update. Typically, you need this kind of table information when the parent contains the key information and the dependent contains additional data that would not fit in the parent table.

You can also use PATH when additional processing is necessary. It could be that you are not accessing several tables with one call; for example, you did not invoke the D command code. In this case, additional processing is necessary if the application is to access each table with a separate call.

NOSSPCMD | SSPCMD

The SSPCMD option requests that DEDB subset pointer command codes are captured. This option is valid for DEDBs only.

DATXEXITNO | DATXEXITYES

Allows the Data Conversion user exit routine (DFSDBUX1) to be used by an application while it is processing this database.

If YES is specified, the user exit DFSDBUX1 is called at the beginning and at the end of each database call. If DFSDBUX1 is not loaded, IMODULE is called to load it.

If NO is specified, the user DFSDBUX1 can be called, provided DFSDBUX1 is located in the SDFSRESL. If DFSDBUX1 does not need to be called again for the database definition, X'FF' is returned in the SRCHFLAG field in the JCB, and DFSDLA00 dynamically marks the database definition as not requiring the exit. In this case, the user exit is not called again for that database definition for the duration of the IMS session, unless the DMB is purged from the DMB pool.

DBVER

A numeric value in the range 0 - 2147483647 that identifies a specific version of the DBD. Specifying a numeric value drives IMS to generate a new version of the DBD that can be used by different application programs.

• If the specified version number is not an increment of the current active version in the IMS catalog, the ALTER fails.
• If the specified version number already exists in the IMS catalog and not the current version, the ALTER fails.
• If the specified version number is the current active version, IMS will generate a new instance of that DBD version.

You can also specify the following instead of a numeric version number:

DBVER AUTO

AUTO drives IMS to auto increment the version number based on the current active version number that is saved in the IMS catalog.

DBVER CURRENT

CURRENT drives IMS to ALTER the current active DBD. DBVER CURRENT is the default.

DOSCOMPNO | DOSCOMPYES

Indicates if this is a DLI/DOS index database. Must be specified if the database is an index, and it was created using DLI/DOS. DLI/DOS index databases contain a segment code as part of the prefix. Specifying that a database is a DLI/DOS index database causes IMS to expect this code to be present in the defined database, and to process in a way that preserves this code. This includes providing a segment code for new segments being inserted. DLI/DOS databases must use VSAM and cannot be PHDAM, PHIDAM, or PSINDEX databases.

FPINDEXNO | FPINDEXYES

Specifies whether an index database is a secondary index for a primary Fast Path DEDB database.

PASSWDNO | PASSWDYES

Specifying PASSWDYES causes DL/I to use the database name as the VSAM password when opening any data set for this database. This parameter is only valid for databases that use VSAM as the access method. You cannot use the database name as the password for the LOGICAL or DEDB database types. When the user defines the VSAM data sets for this database using the DEFINE statement of z/OS® Access Method Services, the control level (CONTROLPW) or master level (MASTERPW) password must be the same as the DBDNAME for this DBD. All data sets associated with this DBD must use the same password.

For the IMS DB/DC system, all VSAM OPENs bypass password checking and thus avoid operator password prompting. For the IMS DB system, VSAM password checking is performed. In the batch environment, operator password prompting occurs if automatic password protection is not specified, and the data set is password protected at the control level (CONTROLPW) with passwords not equal to the database name.

PROTYES | PROTNO

Specifies if a secondary index database uses index pointer protection. This optional parameter ensures the integrity of all fields in index pointer segments that are used by IMS. Use of this parameter prevents an application program from doing a replace operation on any field within an index pointer segment except for fields within the user data portion of index pointer segments. Delete operations are still enabled for index pointer segments. If a delete is issued for an index pointer segment, the index target segment pointer in the index pointer segment is deleted. However, the index source segment that caused the index pointer segment to be created originally is not deleted.

If index pointer protection is not used, an application program can replace all fields within an index pointer segment except the constant, search, and subsequence fields. Inserts to an index database are invalid under all conditions.

PSNAME name

Specifies the module that selects the HALDB partition for PSINDEX, PHDAM, or PHIDAM databases. The parameter is a HALDB partition selection exit routine module name. This parameter is only valid when the access type for the database is PSINDEX, PHDAM, or PHIDAM.

Exception: A user-provided HALDB partition selection routine is not needed if root key ranges define HALDB partition membership.

RMNAME name

Specifies a module name that is used to manage the data that is stored in a DEDB or in the primary data set group of an HDAM or PHDAM database. This parameter is only valid when the database access type is HDAM, PHDAM, or DEDB. A randomizing module controls root segment placement in or retrieval from the DEDB, HDAM, or PHDAM database. One or more modules, called randomizing modules, can be utilized within the IMS system. A particular database has only one randomizing module associated with it. A generalized module, which uses user-supplied parameters to perform randomizing for a particular database, can be written to service several databases. The purpose of a randomizing module is to convert a value supplied by an application program for root segment placement in, or retrieval from, a DEDB, HDAM, or PHDAM database into a relative block number and anchor point number. You can randomize within an area by selecting a two-stage randomizer. When you select a two-stage randomizer, the number of root anchor points in an area can be changed without having to stop all areas in the DEDB with the /DBRECOVERY command.

For PHDAM databases, the randomizer module names and values become the default for each partition. You can set a different randomizer name and values for each partition during HALDB partition definition. HALDB partition selection is done prior to invoking the randomizing module. The randomizing module selects locations only within a partition.

The module name is the 1- to 8-character alphanumeric name of a user-supplied randomizing module that is used to store and access segments in this DEDB, PHDAM, or HDAM database. Select a two-stage randomizer by specifying the randomizer name in the module name parameter and 2 in the anchor point parameter.

RMANCH number

The purpose of the anch value is different depending on whether you are defining a Fast Path DEDB database or a full-function HDAM or PHDAM database.

This parameter must be an unsigned decimal integer.

For a DEDB database, the value of anch specifies the type of randomizer. A value of 1 indicates a single-stage randomizer. A value of 2 indicates a two-stage randomizer. Any other value is invalid.

For HDAM and PHDAM databases, the value of anch specifies the number of root anchor points desired in each control interval or block in the root addressable area of the HDAM or PHDAM database. Typical values are from 1 to 5 and the value cannot exceed 255.

When accessing a HDAM or PHDAM database, if a user randomizing routine produces an anchor point number greater than the number specified for this parameter, the highest-numbered anchor point in the control interval or block is used. When a randomizing routine produces an IMS anchor point number of zero, IMS uses anchor point one in the control interval or block.

RMRBN number

Specifies the maximum relative block number value that you want to allow a randomizing module to produce for this database. This parameter is for HDAM or PHDAM databases only. This value determines the number of control intervals or blocks in the root addressable area of an HDAM or PHDAM database. This parameter must be an unsigned decimal integer whose value does not exceed 2²⁴-1. If this parameter is omitted, no upper limit check is performed on the relative block number created by the randomizing module. If this parameter is specified, but the specified randomizing module produces an relative block number greater than this parameter, the highest control interval or block in the root addressable area is used by IMS. If a user randomizing module produces a block number of zero, the control interval or block one is used by IMS.

In an HDAM or PHDAM data set, the first bit map is in the first block of the first extent of the data set. In an HDAM or PHDAM database, the first control interval or block of the first extent of the data set specified for each data set group is used for a bit map. In a VSAM data set, the second control interval is used for the bit map and the first control interval is reserved. IMS adds one to the block calculated by the randomizer.

RMBYTES number

Specifies the maximum number of bytes of database record that can be stored into the root addressable area in a series of inserts unbroken by a call to another database record. This parameter is for HDAM and PHDAM databases only. If this parameter is omitted, no limit is placed on the maximum number of bytes of a database record that can be inserted into this database's root segment addressable area. The bytes parameter must be an unsigned decimal integer whose value does not exceed 2²⁴-1. When the maximum relative block number parameter is omitted, this parameter is ignored. In this case, there is no limit on the number of bytes of a database record that can be inserted into the root addressable area.

If this parameter is specified for an HDAM or PHDAM database and the length of the database record is larger, the remainder of the record is inserted into the overflow area following the current end-of-file (EOF). This operation requires that enough space be available after the current EOF to contain the remainder of all database records that exceed the value of this parameter. If sufficient space is not available in the overflow area following the current EOF, the database records are inserted randomly in the database.

XCINO | XCIYES

Specifies whether this DEDB uses the Extended Call Interface when making calls to the randomizer. This option allows the randomizer to be called in three different ways. On initialization of IMS or during a /START DB command, IMS will first load the randomizer and then make an INIT call to the randomizer to invoke its initialization routines. During a /DBR DB command, IMS will make a TERM call to the randomizer to invoke the termination routines before unloading the randomizer. The normal randomizing call to the randomizer is made when the application issues a GU or ISRT call on a root segment. The XCI option is only valid for DEDBs.

VERSION 'version_identifier'

Specifies a version identification string. You can use this identifier to differentiate the versions of the resource in subsequent queries to the IMS catalog.

Usage notes

Because the ALTER DATABASE statement modifies a database to IMS, the statement will fail with a -9000 message if the database specified on the ALTER DATABASE statement does not exist.

Database versioning notes

An ALTER DATABASE in its own DDL stream changes an existing DBD. Database versioning is optional. To implement changes against the current version, supply the current version number on the DBVER keyword. You can also specify “DBVER CURRENT” and IMS will identify the currently active version number for them.

To generate a new version, supply the next version number on the DBVER keyword. The version number supplied must be an increment of the currently active database version.

To automatically assign a version number on the DBD, specify “DBVER AUTO”. DDL will temporarily assign the INIT token as the version number. This assignment handles the case where multiple workstations are implementing different DBD changes.

You can optionally specify CREATE PROGRAMVIEW to generate new PSBs. As part of this stream, specify “DBVER AUTO” on the PCBs to have them locked to the same version number being generated. When the changes in the DDL stream are activated in the IMS system, IMS assigns the version number to the DBDs and PSBs.

If the DBVER keyword is omitted from the ALTER DATABASE statement, IMS implements changes against the currently active database version as indicated by the IMS catalog.

Example: full function database

The following input to the DBD generation utility creates a basic full function database:

The original DBD source to define a new database.

DBD   NAME=COGDBD,                                               C
         ENCODING=Cp1047,                                        C
         ACCESS=(HDAM,VSAM),                                     C
         RMNAME=(DFSHDC40,3,3,25),                               C
         PASSWD=NO,                                              C
         VERSION=’Latest version of COGDBD’

The following example is the DDL equivalent to the DBD source.

CREATE DATABASE COGDBD
  ACCESS HDAM VSAM 
  RMNAME(DFSHDC40 RMANCH 3 RMRBN 3 RMBYTES 25)
  VERSION ‘Latest version of COGDBD’
  CCSID 'Cp1047';

The DBD source to provide a different randomizer, PASSWD, and VERSION.

DBD   NAME=COGDBD,                                               C
         ENCODING=Cp1047,                                        C
         ACCESS=(HDAM,VSAM),                                     C
         RMNAME=(DFSHDC20,3,3,25),                               C
         PASSWD=YES,                                              C
         VERSION=’Latest version of COGDBD’

The following example is the DDL equivalent to the DBD source.

ALTER DATABASE COGDBD
  RMNAME(DFSHDC20 RMANCH 3 RMRBN 3 RMBYTES 25)
  PASSWDYES
  VERSION ‘Latest version of COGDBD’

Example: Fast Path Data Entry Database (DEDB)

Similarly to the previous example, the following input can be submitted to the DBD generation utility to create a DEDB:

Original DBD source to define the database:

DBD       NAME=HOSPDBD1,                                             C
             ENCODING=Cp1047,                                        C
             ACCESS=(DEDB),                                          C
             RMNAME=(RMOD3,1,,,XCI)                                  C
             PASSWD=NO                                                

The following example is the DDL equivalent to the DBD source.

CREATE DATABASE HOSPDBD1
  ACCESS DEDB
  RMNAME( RMOD3 RMANCH 1 XCIYES)
  CCSID 'Cp1047'; 

COMMENT ON DATABASE HOSPDBD1 IS 'This describes database HOSPDBD1.'

The DBD source change to provide a different randomizer, XCI, encoding, and new comment.

DBD       NAME=HOSPDBD1,                                             C
             ENCODING=Cp943C,                                        C
             ACCESS=(DEDB),                                          C
             RMNAME=(FPERNDM0,1,,,)                                  C
             PASSWD=NO                                                

The following example is the DDL equivalent to the DBD source.

ALTER DATABASE HOSPDBD1
  RMNAME(FPERNDM0 RMANCH 1 XCINO)
  CCSID 'Cp943C'; 
COMMENT ON DATABASE HOSPDBD1 IS 'Implemented change to database HOSPDBD1.'