CREATE DATABASE
The CREATE DATABASE statement defines a new database to IMS.
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.PHIDAM syntax
- 1 If the ACCESS keyword is not specified, PHIDAM OSAM is the default database access type. If a specific database access type is required, the user must specify the ACCESS keyword followed by the access type.
HDAM syntax
HIDAM syntax
PHDAM syntax
GSAM syntax
HISAM syntax
SHISAM syntax
DEDB syntax
HSAM syntax
SHSAM syntax
LOGICAL syntax
INDEX syntax
PSINDEX syntax
data capture changes syntax
exit_attributes syntax
- 1 BEFORE, NOBEFORE, DLET, NODLET, SSPCMD, NOSSPCMD, FLD, and NOFLD are for DEDB only.
Description
The following keyword parameters are defined for the CREATE DATABASE statement:- database_name
- ACCESS
- CCSID 'encoding'
- An optional 1- to 25-character field that specifies
the default encoding of all character data in this database.
The default code page is Cp1047, which specifies EBCDIC encoding.
This value cannot contain the following characters:- Single or double quotation marks
- Blanks
- Less than (< ) and greater than ( >) symbols
- Ampersands (&)
This value can be overridden in individual tables or columns.
- 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.
- 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. The default is DATXEXITNO.
If DATXEXITYES 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 DATXEXITNO is specified, the DFSDBUX1 user exit routine 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.
- 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. By default, an index database is not a secondary index.
- LIKE resource_name
- Specifies the name of a model resource to base the new resource on.
- 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.
By default, a secondary index database uses index pointer protection.
- PSNAME psname
- 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 mod
- 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.
- RMANCH anch
- 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. The default value of this parameter is one.
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 rbn
- 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 224-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 bytes
- 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 224-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 an identification string. You can use this as a comment descriptor for your database changes.
Usage notes
Defining a database with the
default options (with a CREATE DATABASE database_name statement and
no other parameters) creates a PHIDAM database with the OSAM dataset
access type. You can also explicitly specify that a PHIDAM database
uses either the VSAM or OSAM dataset access type by including either
keyword in the CREATE statement: CREATE DATABASE database_name ACCESS
PHIDAM OSAM or CREATE DATABASE database_name ACCESS
PHIDAM VSAM
Notes on data versioning
On a CREATE DATABASE statement, the database version number (DBVER) is always 0. CREATE defines a new database to IMS, and 0 is always the base version. All CREATE and ALTER statements under the same DDL stream (before an activate command) will work with version 0.All dummy PSBs that are automatically generated will by default refer to the current version which is version 0. You can optionally issue CREATE SENSEGVIEW to create PSBs manually, and specify “DBVER 0” on the PCBs to lock them at version 0. You cannot specify higher version numbers because only version 0 will exist in this stream. You can also optionally specify a “DBLEVEL CURR | BASE” setting. Be aware that if a PSB that references version 0 is activated, but database versioning is not enabled, IMS rejects application call from that PSB.
Example: Full Function Database
The following input can be used to specify DATA CAPTURE CHANGES keywords without a data capture exit. This indicates to IMS that the user only wants logging.
DBD NAME=DHVNTZ02,ACCESS=(PHIDAM,OSAM), X
EXIT=((*,KEY,DATA,NOPATH,(CASCADE,KEY,DATA,NOPATH), X
LOG))
CREATE DATABASE DHVNTZ02
DATA CAPTURE CHANGES(
LOG KEY DATA NOPATH CKEY CDATA CNOPATH
)The following input can be used to specifying DATA CAPTURE CHANGES keywords with multiple data capture exit.
DBD NAME=DHVNTZ02,ACCESS=(PHIDAM,OSAM), X
EXIT=((EXIT1A,(CASCADE,KEY,DATA,PATH), X
KEY,DATA,PATH,NOLOG), X
(EXIT1B,NOKEY,NOPATH,NOLOG,(CASCADE,NOKEY,DATA,NOPATH)),X
(EXIT1C,(CASCADE,NOKEY,NODATA,NOPATH), X
NOKEY,DATA,PATH,NOLOG), X
(EXIT1D,KEY,NODATA,PATH,NOLOG, X
(CASCADE,NOKEY,NODATA,PATH)))CREATE DATABASE DHVNTZ02
DATA CAPTURE CHANGES(
EXIT1A NOLOG KEY DATA PATH CKEY CDATA CPATH,
EXIT1B NOLOG NOKEY NOPATH CNOKEY CDATA CNOPATH,
EXIT1C NOLOG NOKEY DATA PATH CNOKEY CNODATA CNOPATH,
EXIT1D NOLOG KEY NODATA PATH CNOKEY CNODATA CPATH
)The following input to the DBD generation utility creates a basic full function database:
DBD NAME=COGDBD, C
ENCODING=Cp1047, C
ACCESS=(HDAM,OSAM), C
RMNAME=(DFSHDC40,3,3,25), C
PASSWD=NO, C
VERSION=’Latest version of COGDBD’The same database can be created with the following CREATE DATABASE statement:
CREATE DATABASE COGDBD
ACCESS HDAM OSAM
RMNAME(DFSHDC40 RMANCH 3 RMRBN 3 RMBYTES 25)
VERSION ‘Latest version of COGDBD’
CCSID 'Cp1047';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:
DBD NAME=HOSPDBD1, C
ENCODING=Cp1047, C
ACCESS=(DEDB), C
RMNAME=(RMOD3,1,,,XCI) C
PASSWD=NO An equivalent database can be created with the CREATE DATABASE statement:
CREATE DATABASE HOSPDBD1
ACCESS DEDB
RMNAME( RMOD3 RMANCH 1 XCIYES)
CCSID 'Cp1047';