You generate the appropriate IMS™ control blocks and resource definitions for a DBCTL subsystem by performing an IMS system definition. IMS system definition is a two-stage process with an optional preprocessor. Stage 1 checks your input specifications (appropriate JCL and macro statements, which are described below) and generates a series of MVS/ESA job steps for stage 2. Stage 2 builds IMS system libraries, execution procedures, and the DBCTL control program. The optional preprocessor is a convenient tool that checks for duplicate names and checks the length and format of the names used as input for stage 1.
This section covers:
IMS uses macro statements for system definition. These macro statements define the operating systems, operating system interfaces, storage pools, PSBs, and databases. From some of these macro statements, DBCTL constructs a set of control blocks with which to execute.
To define the environment in which DBCTL operates, you use DBCTL startup parameters and control information in a number of IMS system data sets. You then use the appropriate suffixes to specify the information to be used for a particular DBCTL run. (This is similar to selecting CICS® tables by specifying their suffixes in the SIT or in SIT overrides.)
The IMS system generation macros you need are listed in IMS system generation macros used by DBCTL. See the IMS System Definition Reference manual manual or IMS Installation Volume 2: System Definition and Tailoring for guidance on the syntax of these macros. Appendix B. Illustration of DBCTL startup parameter creation and selection shows how DBCTL startup parameters are created and selected during startup. If you are new to IMS system definition, you may find it helpful to refer to this illustration while reading the information on generating DBCTL.
The first macro in a DBCTL system generation is IMSCTRL. It is always required and there can be only one within each IMS system definition. IMSCTRL describes the MVS™ system under which IMS executes, the type of IMS system, the type of generation to be performed, and the components of the IMS environment, for example, IRLM and DBRC. Note that, because DBRC is mandatory for DBCTL, you do not need to specify the IMSCTRL parameter, DBRC=YES. (If you do specify this parameter, it is ignored.) You can use IMSCTRL to cause the IMS nucleus and/or the DDIR and PDIR to be regenerated.
MAXREGN is the number of regions (threads) that DBCTL will allocate at startup. This can be from 1 through 255. It can increase dynamically to a maximum of 255. Each BMP needs one region. Each connected CICS needs from MINTHRD to MAXTHRD regions. See also MINTHRD and MAXTHRD, which are used to specify the minimum and maximum numbers of threads for a particular CICS system, as described in Defining the IMS DRA startup parameter table. For information on how these parameters interact, see Specifying numbers of threads. (MAXREGN is not the only parameter you need in IMSCTRL, but we mention it here to contrast it with MINTHRD and MAXTHRD.)
You use the APPLCTN macro to name PSBs (one macro for each PSB) that are to be used by application programs to access databases through DBCTL.
If multiple CICS transactions or BMPs are to schedule a PSB concurrently, the APPLCTN macro for that PSB must specify SCHDTYP=PARALLEL. If you do not specify SCHDTYP=PARALLEL, only one transaction at a time will be able to schedule a PSB. You can change the SCHDTYP of a PSB using the online change process and the /MODIFY command, which you enter at the DBCTL console. See Changing DBCTL resources online for more information about the online change process and the /MODIFY command.
In DBCTL, PSBs used by CICS transactions can be defined either with the TP option or the BATCH option. In the example in Figure 6, we have used the BATCH option. Figure 6 also includes an example of defining a PSB for the CDBM operator transaction.
You use the BUFPOOLS macro to specify default main storage buffer pool sizes for DBCTL, including the size of the DMB and PSB pools. You can override these values at startup using the CSAPSB=, DLIPSB=, and DMB= parameters.
You use DATABASE macro statements to define the databases that DBCTL will access (one macro for each database). Each physical database must be referenced on a DATABASE macro statement. You can change this resource through the online change process using the /MODIFY command, which you enter at the DBCTL console. See Changing DBCTL resources online for more information on the /MODIFY command.
The FPCTRL macro statement defines the fast path options when DEDBs are used. You need to use this macro only if you want DEDB support.
The IMSCTF macro statement includes parameters to define the SVCs to be used by DBCTL, logging options, and the device type for DBCTL’s restart data set.
The SECURITY macro statement enables you to specify optional security features to be in effect during IMS execution, unless they are overridden during system initialization.
If you are implementing IMS security, the security maintenance utility is used to place descriptions of protected resources into suffixed members of a matrix data set called IMS.MATRIX.
The IMS.MODBLKS data set is used as input to the security maintenance utility, which means that:
For more information about security with DBCTL, see Security checking with DBCTL.
The IMSGEN macro statement must be the last system definition macro in the Stage 1 input. It specifies the assembler and linkage editor data sets and options, and the system definition output options and features. It specifies the suffix character for the IMS nucleus (DFSVNUCx in IMS.RESLIB) and for the DDIR (DFSDDIRx) and PDIR (DFSPDIRx) in IMS.MODBLKS. Note that you must specify the MACLIB parameter of the IMSGEN macro as MACLIB=ALL when using DBCTL for the first time.
CICS provides a transaction, CDBM, which enables DBCTL operator commands to be input from a CICS terminal (which must be a BMS supported device), as described in CDBM operator transaction. To use CDBM, you must have a DBCTL system running IMS.
CDBM uses the AOI commands that can be issued across the DRA interface between CICS and DBCTL. For more information, see Issue IMS AIB call format.
Choose either of these methods to implement CDBM:
PSBGEN LANG=ASSEM,PSBNAME=DFHDBMP,IOASIZE=1000
The IOASIZE parameter must be large enough to cope with the largest AOI command issued. Large AOI commands can result from using wild cards. For example, issuing CDBM /START DATABASE D* results in a start command being issued for all database names beginning with D. See the IMS Utilities Reference: Systems manual for information on defining IOASIZE.
CREATE PGM NAME(DFHDBMP) SET( BMPTYPE(Y) DOPT(N) +
FP(N) GPSB(Y) LANG(ASSEM) RESIDENT(N) +
SCHDTYPE(PARALLEL) TRANSTAT(N))
You can modify the IMS system data sets MODBLKS, MATRIX, and ACBLIB using online change. Each of them must be present in the following copies:
The IMS.MODSTAT data set, which is created during the IMS system generation and updated automatically, indicates which of the suffixed data sets is currently active. For guidance on using online change, see Changing DBCTL resources online and the IMS System Administration Guide or the IMS Administration Guide: System.
The minimum generation required to generate DBCTL is ON-LINE,DBCTL. (You will need to perform an online generation to change the SVC numbers.) You must include the dash (-) in the ON-LINE parameter. If you do not, you will get the following messages when you try to generate DBCTL:
** ASMA254I *** MNOTE *** 76+ 4,G002 FOLLOWING OPERAND(S) OMITTED OR INVALID:
** ASMA254I *** MNOTE *** 77+ 4, SYSTEM 
You use an ACB generation to create members of the IMS.ACBLIB. See the IMS Utilities Reference: Database manual manual for further guidance on doing this.
Figure 6 shows an example DBCTL generation that you can copy and modify to generate a DBCTL subsystem. Note that this example includes only the parameters needed to get a "basic" system up and running. It does not include optional parameters, such as those for DEDB support, and it assumes that you will want to tune other parameters (such as the number of threads) later, when you have had an opportunity to see how the subsystem runs.
//DBCGEN JOB 1,PGMERID,
// MSGCLASS=A,MSGLEVEL=(1,1),
// CLASS=A,NOTIFY=PGMERID
//ASM EXEC PGM=ASMA90,
// PARM='DECK,NOOBJECT',
// REGION=4096K
//SYSLIB DD DSN=IMS.OPTIONS,DISP=SHR
// DD DSN=IMS.SDFSMAC,DISP=SHR
// DD DSN=SYS1.MACLIB,DISP=SHR
//*
//SYSUT1 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT2 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT3 DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD DSN=IMS.STAGE2,DISP=SHR
//SYSIN DD *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* SAMPLE DBCTL SYSTEM DEFINITION STAGE 1 INPUT SPECIFICATIONS *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
IMSCTRL SYSTEM=(VS/2,(ON-LINE,DBCTL),3.1), X
MAXREGN=(20,52K,A,A), X
MCS=(2,7),DESC=7,MAXCLAS=1,IMSID=IMSA
*
IMSCTF SVCNO=(,203,202), X
LOG=(DUAL,MONITOR), X
RDS=(3380,4096), X
CPLOG=1000,CORE=(,50,1)
*
* DEFINE SYSTEM BUFFERS
*
BUFPOOLS PSBW=60000,DMB=10000,SASPSB=(20000,80000)
*
* DEFINE DL/I DATABASES
*
DATABASE RESIDENT,DBD=DI21PART
* DEFINE SAMPLE APPLICATIONS
*
APPLCTN PSB=DFHSAM04,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHSAM05,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHSAM14,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHSAM15,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHSAM24,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHSAM25,PGMTYPE=BATCH,SCHDTYP=PARALLEL
APPLCTN PSB=DFHDBMP,PGMTYPE=BATCH,SCHDTYP=PARALLEL
*
IMSGEN ASM=(H,SYSLIN), X
ASMPRT=ON, X
LKPRT=(XREF,LIST), X
LKSIZE=(880K,64K), X
LKRGN=4096K, X
SUFFIX=1, X
SURVEY=NO, X
SYSMSG=TIMESTAMP, X
MACLIB=ALL, X
OBJDSET=IMS.OBJDSET, X
USERLIB=IMS.LOADLIB, X
PROCLIB=(YES,), X
NODE=(IMS,IMS,IMS), X
JCL=(GENJOB, X
(1), X
PGMERID, X
A, X
(TIME=5,CLASS=K,NOTIFY=PGMERID)), X
SCL=(99)
END
For more detailed system definition examples and further guidance on selecting the appropriate system definitions, and for IMS system definition examples, see the IMS System Definition Reference manual manual or IMS Installation Volume 2: System Definition and Tailoring.
IMS logging uses two types of data set: online log data sets (OLDS) and write ahead data sets (WADS). These data sets are described below. For further guidance on using the OLDS and the WADS, see the IMS Operations Guide.
IMS writes log records to a DASD data set called the online log data set (OLDS). The OLDS is made up of multiple data sets written in wraparound form. Using more than one OLDS enables IMS to continue logging when the first OLDS is full. Also, if an I/O error occurs while writing to an OLDS, IMS can continue logging by isolating the OLDS where the problem occurred and switching to another one.
IMS can write committed log records to the write-ahead data set (WADS) so that these records are externalized to avoid the need to write partially filled and padded log blocks to the OLDS. The WADS is described in IMS write-ahead data set (WADS).
When the OLDS is full, it is archived to the system log data set (SLDS). How frequently the OLDS is archived depends on whether you specified automatic archiving using the ARC=parameter in the DBC JCL. You can specify ARC=1 through ARC=99. Automatic archiving takes place only when the number of OLDS you specified is full. The system reuses the OLDS after it has been archived. An SLDS can be on DASD or on tape. The contents are used as input to the database recovery process.
IMS archives the OLDS using the log archive utility (DFSUARC0). During archiving, IMS can write a subset of the log records it writes to the SLDS to the recovery log data set (RLDS). This subset consists only of the log records required to perform a database recovery.
During logging, IMS writes system checkpoint ID information (including OLDS positioning information) to the restart data set (RDS). IMS uses the RDS during the restart process to determine from which checkpoint to begin a restart. (See the IMS Operations Guide for further guidance about the RDS.)
The main purpose of the write-ahead data set (WADS) is to contain a copy of committed log records that are in the OLDS buffers, but have not yet been written to the OLDS because the OLDS buffer is not yet full. IMS uses the WADS to avoid the need to write partially filled and padded blocks to the OLDS. WADS space is continually reused after the appropriate log data has been written to the OLDS. If there is a system failure, IMS uses the log data in the WADS to complete the content of the OLDS in use, and then closes the OLDS as part of an emergency restart. This is also an option of the IMS log recovery utility (DFSULTR0). (The OLDS must be closed before database recovery can take place.) You can change the following specifications for the WADS at any restart:
Database Recovery Control (DBRC) assists you in controlling DBCTL logs and in managing recovery of databases. With DBCTL, you must use DBRC to control DBCTL logs, and you may optionally use it to control batch logs and database recovery. DBRC places the information it uses to control recovery in the RECON data sets, which are required with DBCTL. These data sets include information about the OLDS; for example, it indicates whether an OLDS is available for use or contains data that must be archived.
Define three RECON data sets when you install DBRC. Two of the RECON data sets are active; the third is a spare. For most purposes, you can think of the two active RECON data sets as a single RECON data set, or simply the RECON.
DBCTL requires DBRC to be at SHARECTL level; if it is not, DBCTL will not start. To initialize the RECON specify (or let it default to) INIT.RECON SHARECTL. Figure 8 shows some example JCL you can copy to initialize the RECON.
//INITREC JOB 1,PGMERID,CLASS=Q,MSGCLASS=A
//*
//RECON EXEC PGM=DSPURX00,REGION=1000K
//STEPLIB DD DSN=IMS.RESLIB,DISP=SHR
//DFSRESLB DD DSN=IMS.RESLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//RECON1 DD DSN=IMS.RECON1,DISP=SHR
//RECON2 DD DSN=IMS.RECON2,DISP=SHR
//SYSIN DD *
INIT.RECON SSID(IMSA)
/*
If you already have a RECON, specify (or let it default to) CHANGE.RECON SHARECTL. When the OLDS is full, DBRC starts a log archive job. Skeleton JCL statements are edited by DBRC before the job is submitted. The skeleton JCL is member ARCHJCL of the library specified in the JCLPDS DD statement in the DBRC JCL. You do not have to wait for the OLDS to fill in order to test the automatic log archive. Instead, you can cause the OLDS to switch using the DBCTL operator command /SWITCH OLDS. Alternatively, you can use the /DBRECOVERY without the NOFEOV keyword. For guidance on the syntax of the /SWITCH and /DBRECOVERY commands, see the IMS Operator’s Reference manual. (See also Operator communication with DBCTL -- overview for information on using DBCTL operator commands.)
For detailed guidance on automatic log archiving and DBRC skeleton JCL, see the IMS Utilities Reference: Database manual manual. For further guidance on using DBRC, see the IMS Operations Guide.
You define IMS logging parameters in member DFSVSMxx in the IMS.PROCLIB, identified by DD name PROCLIB in the DBC and DLISAS JCL. You specify the suffix xx for DFSVSMxx in the DBCTL startup parameter VSPEC. For an illustration of the parameters involved, see Appendix B. Illustration of DBCTL startup parameter creation and selection. The logging parameters in DFSVSMxx include:
A further logging parameter, used to specify single or dual copies of the WADS is in the DBCTL startup parameters. See Starting DBCTL, DLISAS, and DBRC for information about the DBCTL startup procedure.
You must preallocate the OLDS and WADS data sets and specify the block size when the data set is allocated. See the IMS Installation Guide for guidance on doing this.
Provide dynamic allocation members for all OLDS and WADS data sets. See IMS dynamic allocation macro (DFSMDA).
DBRC automatically submits a job to archive the OLDS when:
See the IMS Operations Guide and the IMS Utilities Reference: Database manual manual for guidance on implementing automatic archiving, and the IMS Operator’s Reference manual for the syntax of the /DBRECOVERY command. (You can also use the /DBRECOVERY command without the NOFEOV keyword to test your implementation.)
Use the IMS dynamic allocation macro (DFSMDA) in all production databases, because:
To use dynamic allocation, you need one member per database in the IMS.RESLIB library (or an authorized STEPLIB library), using the IMSDALOC procedure to assemble and link-edit the appropriate DFSMDA macros. See the IMS System Administration Guide or the IMS Administration Guide: System for general guidance on dynamic allocation and the IMS Utilities Reference: Database manual manual for guidance on using the DFSMDA macro.
You define the VSAM and OSAM database buffer pool specifications and IMS performance and trace options in the DFSVSMxx member of the IMS.PROCLIB data set, which is pointed to by the PROCLIB DD statement of the DBCTL startup procedure (DBC). The last two characters of the DFSVSMxx member are a suffix. You specify this suffix in the VSPEC parameter of the DBCTL startup procedure. See the IMS System Definition Reference manual manual or IMS Installation Volume 2: System Definition and Tailoring for guidance on the syntax of these parameters and the IMS Database Administration Guide or the IMS Administration Guide: Database Manager for guidance on specifying the database buffer pool parameters. For an illustration of the parameters involved in DBCTL startup, see Appendix B. Illustration of DBCTL startup parameter creation and selection.
You can change many IMS system definition values at DBCTL startup using parameters on the DBC procedure. You can specify these override parameters on the PARM of the EXEC statement. However, there is a 100-character limit to the length of the PARM field you can specify on a JCL EXEC statement, which means that you cannot override all possible DBC parameters in the JCL. A better approach is to use member DFSPBDBC, which allows you to specify DBCTL control region execution parameters that override those specified in the stage 1 macros.You can place several DFSPBDBC members in PROCLIB by replacing the member name DFSPBDBC with DFSPBxxx, where xxxmust be three alphanumeric characters. The RGSUF= keyword in the DBC procedure specifies the xxx suffix to be used during startup of the DBCTL control region. For more information about DFSPBDBC, see IMS Installation Volume 2: System Definition and Tailoring.
The DBCTL display commands (for example, /DISPLAY ACTIVE and /DISPLAY CCTL, described in Finding out current status of DBCTL activities). and the DRA startup table USERID parameter, all use what is known in IMS and DBCTL as the CCTL ID to identify the transaction management subsystem. In the case of CICS, the CCTL is CICS and the ID is the CICS APPLID.
However, many IMS messages use the jobname of the CICS system instead. An example of this sort of message is DFS554, which notifies you that a BMP region, or a thread from a CICS transaction, has terminated abnormally. If the DFS554 message was caused by an abnormal termination of a thread that originated from CICS, the message text contains the CICS job name or CICS startup procedure name. You will therefore need a naming convention that enables operators to immediately identify a corresponding CICS APPLID and CICS JOBNAME. For example, if you use the APPLID DBDCCICA, your job name could also contain the characters CICA.