A sample CICS startup job

You can use the sample CICS startup job to help you determine and adjust values needed for CICS startup parameters.

The EXEC statement contains the REGION parameter to define the size of CICS region. In this example, the value is set to 240, requesting MVS to allocate to the job all 16 MB of private storage below the 16 MB line and an extended region size of 240 MB.

CICS startup job stream

/*
//*  1    The JOB statement
//CICSRUN  JOB accounting info,name,CLASS=A,
//            MSGCLASS=A,MSGLEVEL=(1,1),NOTIFY=userid
//*
//*  2    The JOBPARM statement
/*JOBPARM SYSAFF=sysid
/*
//***********************************************************
//*******************  EXECUTE CICS  ************************
//***********************************************************
//*
//*  3    The EXEC CICS=DFHSIP statement
//CICS    EXEC PGM=DFHSIP,REGION=240M,
//*  4    System initialization parameters specified on PARM parameter
//             PARM=('SIT=6$',
//             'DSALIM=6M,EDSALIM=120M',
//             'RENTPGM=PROTECT,STGPROT=YES',
//             'START=AUTO,SI')
//*
//*  5    System initialization parameters specified on the SYSIN data set
//SYSIN    DD *
GRPLIST=(DFHLIST,userlist1,userlist2),
LPA=YES,
APPLID=CICSHTH1,
DFLTUSER=CICSUSER,   The default user ID
MXT=30,              Maximum number of user tasks is 30
INITPARM=(DFHDBCON='01'),
                     Pass DFSPZP01 suffix to DBCTL connect program
INITPARM=(DFHD2INI=('MYDB'),
                     Connect to DB2 subsystem MYDB
ISC=YES,             Include intersystem communication program
IRCSTRT=YES,         Start interregion communication
.END
/*
//*  6    The STEPLIB library
//STEPLIB  DD  DSN=CICSTS55.CPSM.SEYUAUTH,DISP=SHR
//         DD  DSN=CICSTS55.CICS.SDFHAUTH,DISP=SHR
//         DD  DSN=CEE.SCEERUN2,DISP=SHR
//         DD  DSN=CEE.SCEERUN,DISP=SHR
//*
//*  7    The CICS library (DFHRPL) concatenation
//DFHRPL   DD DSN=CICSTS55.CICS.SDFHLOAD,DISP=SHR
//*        Your application library
//         DD  DSN=your.prog.library,DISP=SHR
//*        Your CICS control tables library
//         DD  DSN=your.table.library,DISP=SHR
//*        The Language Environment runtime data sets
//         DD  DSN=CEE.SCEECICS,DISP=SHR
//         DD  DSN=CEE.SCEERUN2,DISP=SHR
//         DD  DSN=CEE.SCEERUN,DISP=SHR
//*        The Debug Tool runtime library
//         DD  DSN=EQA.SEQAMOD,DISP=SHR
//*  7a    The DB2 load library
//         DD  DSN=SYS2.DB2.SDSNLOAD,DISP=SHR
//*  8    Auxiliary temporary storage data sets
//DFHTEMP  DD DSN=CICSTS55.CICS.CNTL.CICSHTH1.DFHTEMP,DISP=SHR
//*
//*  9    Intrapartition data sets
//DFHINTRA DD DSN=CICSTS55.CICS.CNTL.CICSHTH1.DFHINTRA,DISP=SHR
//*
//*  10    Auxiliary trace data sets
//DFHAUXT  DD DSN=CICSTS55.CICS.CICSHTH1.DFHAUXT,DISP=SHR
//DFHBUXT  DD DSN=CICSTS55.CICS.CICSHTH1.DFHBUXT,DISP=SHR
//*

//*  11    Extrapartition data sets
//DFHCXRF  DD SYSOUT=*
//LOGUSR   DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136)
//MSGUSR   DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=140)
//COUT     DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=137)
//CEEMSG   DD SYSOUT=A
//CEEOUT   DD SYSOUT=A
//*
//*  12    The CICS local catalog data set
//DFHLCD   DD DSN=CICSTS55.CICS.CICSHTH1.DFHLCD,DISP=SHR
//*  13    The CICS global catalog data set
//DFHGCD   DD DSN=CICSTS55.CICS.CICSHTH1.DFHGCD,DISP=SHR,
//            AMP=('BUFND=33,BUFNI=32,BUFSP=1114112')
//*
//*  14    The transient data destination data set (CXRF)
//DFHCXRF  DD SYSOUT=A
//*
//*  15    The CICS transaction dump data sets
//DFHDMPA  DD DSN=CICSTS55.CICS.CICSHTH1.DFHDMPA,DISP=SHR
//DFHDMPB  DD DSN=CICSTS55.CICS.CICSHTH1.DFHDMPB,DISP=SHR
//*
//*  16    MVS system dump data sets
//SYSABEND DD SYSOUT=*
//*
//*  16a    Default stdout file for C-language system services used by CICS
//SYSPRINT DD SYSOUT=*
//*  17    The CICS system definition data set
//DFHCSD   DD DSN=CICSTS55.CICS.DFHCSD,DISP=SHR
//*
//*  18    The CICS BTS local request queue data set
//DFHLRQ   DD DSN=CICSTS55.CICS.DFHLRQ,DISP=SHR
//*

//*  19    The CMAC data file
//DFHCMACD DD DSN=CICSTS55.CICS.DFHCMACD,DISP=SHR
//*
//*  20    The CDBM group command file
//DFHDBFK  DD DSN=CICSTS55.CICS.DFHDBFK,DISP=SHR
//*
//*  21    FILEA & other permanently allocated data sets
//* (The FILEA DD statement below overrides the CSD definition in
//*  group DFHMROFD)
//FILEA    DD DISP=SHR,
// DSN=CICSTS55.CICS.CICSHTH1.FILEA
//*
//APPLICA  DD  DSN=CICSTS55.CICS.CICSHTH1.APPLICA,DISP=SHR
//APPLICB  DD  DSN=CICSTS55.CICS.CICSHTH1.APPLICB,DISP=SHR
//*
//*
//*  22 
//PRINTER  DD  SYSOUT=A,DCB=BLKSIZE=125,OUTLIM=0
//* User transactions input from sequential terminal
//CARDIN DD *
CESF GOODNIGHT\
/*

The JOB statement specifies the accounting information that you want to use for this run of CICS. For example:
```
//CICSRUN  JOB 24116475,userid,MSGCLASS=A,MSGLEVEL=(1,1),
//         CLASS=A,NOTIFY=userid
```
The JES JOBPARM statement is included to identify the MVS™ image on which this CICS (the active CICS region) is to run.
DFHSIP is the program that starts CICS initialization. CICS does not support more than one EXEC PGM=DFHSIP job step in the same MVS job.
To determine how much of the allocated private storage CICS gives to dynamic storage areas and leaves for demands on operating system storage, set values for the DSALIM and EDSALIM system initialization parameters. After obtaining the amount of space required for the DSAs from the total defined by the REGION parameter, the remaining storage is available to meet demands for operating system storage.

In this sample job stream, these system initialization parameters are specified in the PARM parameter.

For more details about the REGION parameter and CICS storage, see Setting address space storage limits for a CICS region.

If you are running CICS with RACF® support, see the Securing for information about parameters related to RACF.
You can use the PARM parameter of the EXEC statement to specify system initialization parameters as shown.
The information passed by the PARM parameter is limited to 100 characters. This limit includes all commas, but excludes the apostrophes delimiting the PARM strings, and excludes the opening and closing parentheses delimiting the PARM parameter. Internal parentheses enclosing system initialization operands are included. If 100 characters are not sufficient for the system initialization parameters that you want to provide at startup, indicate continuation by ending the PARM field with the SYSIN or CONSOLE control keywords, or SI or CN for short. If you specify SYSIN, system initialization parameters are read from the SYSIN data set; if you specify CONSOLE, CICS prompts you to enter parameters through the console. However, if all of your runtime system initialization parameters are in the PARM parameter, you can end the PARM field without any control keywords, or by the END control keyword.

In this example, CICS uses the values in the DFHSIT6$ system initialization table, modified by the system initialization parameters supplied in the PARM field and the SYSIN data set. For this example, the following system initialization parameters are provided in the PARM parameter:

RENTPGM

Storage for the read-only DSAs, RDSA and ERDSA, is obtained from key-0, non-fetch protected storage by using the default PROTECT option on the RENTPGM system initialization parameter. Specify RENTPGM=NOPROTECT for development CICS regions and RENTPGM=PROTECT for production CICS regions. For more information about the RENTPGM parameter, see RENTPGM system initialization parameter.

STGPROT

Storage protection is obtained for this run of CICS by specifying YES for the STGPROT system initialization parameter, or allowing it to default to YES. See STGPROT system initialization parameter for details about the STGPROT parameter.

START

START=AUTO is normally the type of start that you select for a production CICS system, so that CICS can determine the type of start to be performed.

SI

The PARM statement ends with SI (short for SYSIN), to tell CICS to continue reading overrides from the SYSIN data set.
You can include the SYSIN data set inline as part of the job stream. System initialization parameters entered in the SYSIN data set replace any that were entered in the PARM parameter for the same keyword. If you include the same parameter more than once, the last value read is the value used for initialization except for INITPARM. If you specify the INITPARM keyword and its parameters more than once, each one is accepted by CICS, for example:
```
* The following INITPARM parameters are for DBCTL and a user program
INITPARM=(DFHDBCON='XX,DBCON2',userprog='a,b,c')
* The following INITPARM parameter is for DB2
INITPARM=(DFHD2INI= 'DBA2')   
```
Unless you explicitly code the system initialization control keyword CONSOLE, CICS stops reading system initialization parameters when it reaches the end of SYSIN or the END control keyword.

In the sample job, CONSOLE is not coded in either PARM or SYSIN. The END control keyword is the last entry in SYSIN, so CICS does not prompt through the console for further system initialization parameters. After reading the SYSIN data set, CICS loads the specified SIT, applies any system initialization parameters supplied in the PARM field and the SYSIN data set, and begins the initialization process.

The SYSIN data set in this example includes several system initialization parameters:

GRPLIST

The group list defined in DFHSIT6$ is DFHLIST, the list that is generated when you initialize the CSD using the DFHCSDUP INITIALIZE command. DFHLIST contains only the standard resource definitions required by CICS. One of the group lists specified on the GRPLIST system initialization parameter must contain those resource definitions required by CICS. You can either include the resource definitions in one of your own group lists or specify the DFHLIST explicitly. Your own group lists (userlist1 and userlist2 in the example) must contain all the resource definitions generated by your installation for your CICS applications. In addition, your group lists must contain any definitions required for IBM licensed programs that you are using, such as COBOL or Db2®.

LPA

The SIT specifies that modules are not to be used from the link pack area; LPA=YES in SYSIN specifies that modules are to be used from the LPA in this run.

APPLID

The APPLID for this CICS region is CICSHTH1. If you want this CICS region to use z/OS Communications Server for terminal access or ISC communication, define this APPLID to z/OS Communications Server.
CICSID is the generic APPLID of this CICS region, and CICSHTH1 is the specific APPLID of the active CICS region.

The specific APPLID can be useful for naming those data sets that are unique; for example, dump data sets.

CICSSVC

245 is the CICS type 3 SVC number installed in the LPA, and defined to MVS in an SVCPARM statement. For more information, see CICSSVC system initialization parameter.
For guidance information about installing the CICS SVC in the LPA, and defining it to MVS, see Installing the CICS SVCs.

DFLTUSER

CICSUSER is the default user ID specified to RACF. During startup, CICS tries to sign on the default user ID. If it cannot be signed on (for example, if not defined), CICS issues a message and stops CICS initialization. After the valid default user ID is signed on, its security attributes are used for all CICS terminal users who do not sign on with the CESN transaction. If the default user ID is defined to RACF with a CICS segment, the operator attributes in that segment are also used for users who do not sign on.

MXT

The maximum number of user tasks is limited to 30 for this run. For information about the tasks that are included in the MXT parameter, see MXT system initialization parameter.

INITPARM

Passes parameters to programs. In this example, the DBCTL suffix (01) of DFSPZPxx is passed to DFHDBCON, and CICS is told to connect to the Db2 subsystem MYDB. You cannot use the ID of a data sharing group of Db2 subsystems on the INITPARM system initialization parameter; you must specify the ID of a single Db2 subsystem. If you want to use the INITPARM system initialization parameter to specify a Db2 subsystem, leave blank both the DB2GROUPID and the DB2ID in the installed DB2CONN definition. An ID specified in either of these attributes of the DB2CONN definition overrides an ID specified on the INITPARM system initialization parameter.

ISC

Include the intersystem communication program, DFHISP, in order to use interregion communication (IRC).

IRCSTRT

This CICS is running with MRO, and interregion communication is started during initialization.
STEPLIB is the DDNAME of the library containing the modules loaded by the operating system. DFHSIP, which is loaded from STEPLIB, must receive control in an authorized state, so each partitioned data set (library) concatenated in STEPLIB must be individually APF-authorized. In this sample job stream, the CICS authorized library is CICSTS55.CICS.SDFHAUTH. CICSTS55.CPSM.SEYUAUTH is also included in the concatenation so that CICS will load the CICSPlex® SM message file at initialization even if the region is not running as a Managed Address Space.
Placing user-written modules into an APF-authorized library might violate your security and integrity rules. The CICSTS55.CICS.SDFHAUTH library must not be included in the MVS link list, so that you can protect the libraries and ensure that only approved users can run the DFHSIP module. When you define your STEPLIB DD statement, remember that all other libraries concatenated with the CICSTS55.CICS.SDFHAUTH library must also be APF-authorized; for example, IMS.RESLIB. APF-authorization is required because, if any of the libraries in a STEPLIB concatenation are not authorized, MVS regards all of them as unauthorized. If there is a non-authorized library in the STEPLIB concatenation, CICS fails to start, and issues message DFHKE0101 to indicate that the DFHSIP module is not in an APF-authorized library. For information about authorizing access to CICS data sets, see RACF data set profiles.

The pregenerated DFHSIP module, which has been link-edited with the authorized attribute (SETCODE AC(1)), is supplied in CICSTS55.CICS.SDFHAUTH.

You must put the Language Environment® runtime libraries, CEE.SCEERUN and CEE.SCEERUN2, in the STEPLIB concatenation, or the MVS link list, to run COBOL, PL/I, C and C++, and Java programs that run in a JVM, under Language Environment. Like SDFHAUTH, SCEERUN and SCEERUN2 must be an APF-authorized library.

The CICS Db2 attachment facility must load the Db2 program request handler, DSNAPRH. You can either place the Db2 library DSNxxx.SDSNLOAD library in the MVS link list or add it to the STEPLIB concatenation of the CICS job.
DFHRPL is the DD name of the library that contains modules loaded by CICS. Protect individually the partitioned data sets constituting this library to prevent unapproved or accidental modification of their contents. The DFHRPL concatenation must include the library containing your CICS application programs, shown in this example as your.prog.library, and your CICS control tables, shown in this example as your.table.library.
In this sample job stream, the supplied library is CICSTS55.CICS.SDFHLOAD, which must be included in the CICS DFHRPL library concatenation. The CICSTS55.CICS.SDFHLOAD library contains only programs that run in problem state and must not be authorized.

Language Environment runtime library requirements

Use the services of Language Environment, which provides a common runtime environment for IBM implementations of assembler and those high-level languages (HLLs) supported by CICS, namely COBOL, PL/I, C, and C++.

To use the Language Environment runtime libraries to support all your program languages, add the Language Environment runtime libraries SCEERUN2 and SCEERUN to the DFHRPL DD concatenation. If you are running COBOL programs, also add Language Environment runtime library SCEECICS to DFHRPL. The SCEECICS library must be concatenated before the SCEERUN library. Remove any libraries that contain runtime routines from earlier versions of COBOL, PL/I, and C/C++ from the DFHRPL DD concatenation.

Debug Tool library

If you are using Debug Tool to debug CICS applications, include the Debug Tool library SEQAMOD in DFHRPL. For information about using Debug Tool with CICS, see Using Debug Tool with CICS applications.

7a Db2 requirements

Generally, you do not have to include any Db2 libraries in the DFHRPL DD statement. If you do require Db2 libraries in the DFHRPL concatenation for an application, they must be placed after the CICS libraries; for example, add SDSNLOAD in the DFHRPL to support those applications that issue dynamic calls to the Db2 message handling module, DSNTIAR, or the later DSNTIA1, both of which are shipped in SDSNLOAD. DSNTIA1 is loaded by applications programs that include the Db2 application stub DSNTIAC, which issues an EXEC CICS LOAD command for program DSNTIAC.
Define this data set if you want to save data to use later. The temporary storage queues used, identified by symbolic names, exist until explicitly deleted. Even after the originating task is deleted, temporary data can be accessed by other tasks, through references to the symbolic name under which it is stored.
For details of how to define these data sets, and for information about space calculations, see Setting up temporary storage data sets.

If you are using temporary storage data sharing, ensure that you start the temporary storage server before it is required by the CICS regions.

For more information about the temporary storage server and temporary storage data sharing, see Setting up and running a temporary storage server
The transient data intrapartition data set is used for queuing messages and data in the CICS region. For information about how to define these data sets, and about space calculations, see Defining the intrapartition data set.
Define one or both of these sequential data sets, if you want to use auxiliary trace. If you define automatic switching for your auxiliary trace data sets, define both data sets. If you define only one data set, its DD name must be DFHAUXT.
For details of how to define these data sets, see Setting up auxiliary trace data sets.

The auxiliary trace data sets in this job stream are unique to the active CICS region, and as such are identified in our example by using the specific APPLID of the active CICS region (CICSHTH1) as a second-level qualifier.
If you allocate and catalog the auxiliary trace data sets on disk as shown in Figure 1, you can define them to CICS in the startup job stream using the following DD statements:
```
//DFHAUXT  DD  DSN=CICSTS55.CICS.applid.DFHAUXT,DCB=BUFNO=n,DISP=SHR
//DFHBUXT  DD  DSN=CICSTS55.CICS.applid.DFHBUXT,DCB=BUFNO=n,DISP=SHR
```
If you specify BUFNO greater than 1, you can reduce I/O involved in writing auxiliary trace records. A value in the range 4 - 10 can greatly reduce I/O when running with auxiliary trace on.
LOGA and CSSL are examples of extrapartition transient data queues.
- LOGA defines a user data set used by the CICS sample programs.
- CSSL defines the data set used by a number of CICS services.
- CCSO is used as an output queue only when you are running C/370 application programs.
- CESO is used as an error queue only when you are running application programs under Language Environment.
  Sample definitions of the queues used by CICS are supplied in group DFHDCTG. DFHDCTG is unlocked, so you can alter the definitions before installation.
The CICS local catalog is used by the CICS domains to save some of their information between CICS runs, and to preserve this information across a cold start. The local catalog is not shared by any other CICS system. For details of how to create and initialize a CICS local catalog, see Setting up the catalog data sets.
There is only one global catalog.
For details of how to create and initialize a CICS global catalog, see Setting up the catalog data sets.

This sample job illustrates the use of the AMP parameter on the DD statement. Specifying this parameter, with its buffer sub-parameters, can help to improve restart and shutdown time. This example uses DEFINE CLUSTER statements that are shown in Figure 1 and the associated notes given under 4 in Defining the global catalog. The values given are the minimum values suitable for these parameters and must not be reduced.
This transient data destination is used by CICS as the target for messages sent to any transient data destination before CICS has completed intrapartition transient data initialization.
CICS records transaction dumps on a sequential data set or a pair of sequential data sets, tape, or disk. The data sets must be defined with the DD names DFHDMPA and DFHDMPB, but if you define only one data set, its DD name must be DFHDMPA. CICS always attempts to open at least one transaction dump data set during initialization.
For details about how to define CICS transaction dump data sets and how they are used, see Defining dump data sets.

The transaction dump data sets in this job stream are unique to the active CICS region, and as such are identified by using the specific APPLID of the active CICS region (DBDCCIC1) as a second-level qualifier.
Use a SYSABEND DD statement to direct MVS to produce a dump.
Produces a dump of user and system areas; this dump contains all the areas dumped in a SYSUDUMP plus the local system queue area (LSQA), including subpools 229 and 230, and the I/O system (IOS) control blocks for the failing task. The dump is formatted, so that it can be printed directly. MVS produces the requested dump if either of the following is true:
- CICS ends abnormally.
- CICS starts to end abnormally, but system recovery procedures enable CICS to end normally.
The dump contents are as described only when you use the IBM-supplied defaults for the dumps. The contents of these dumps can be set during MVS system initialization and can be changed for an individual dump in the ABEND macro instruction, in a CHNGDUMP command, and by a SLIP command. For details, see the z/OS MVS Initialization and Tuning Guide.

Dumps are optional; use a dump DD statement only when you want to produce a dump.

For information about how defining MVS system dump data sets, and about printing dumps from them, see the z/OS MVS JCL Reference. For information about how to interpret dumps, see z/OS MVS Diagnosis: Tools and Service Aids.

16a Default stdout file for C-language system services used by CICS

The SYSPRINT statement is opened as the stdout file by C-language system service routines that are used by CICS, such as system SSL and JVM servers. If it is omitted, multiple sysout files might be dynamically allocated by the operating system instead.
The system definition file (CSD) is required by CICS to hold some resource definitions.
You might want to provide job control DD statements for the CSD. If you do, the CSD data set is allocated at the time of CICS job step initiation, and remains allocated for the duration of the CICS job step.

You might prefer to use dynamic allocation of the CSD. For dynamic allocation, do not specify a DD statement for the CSD. Specify the data set name (DSNAME) and the data set disposition (DISP) either in a SET FILE command or in the System Initialization (as parameters CSDDSN and CSDDISP). CICS uses the DSNAME and DISP to allocate the file as part of OPEN processing.

For information about creating and initializing the CSD, see Setting up shared data sets, CSD and SYSIN.
DFHLRQ is a file-control-managed VSAM key-sequenced data set (KSDS), used by CICS business transaction services (BTS). The supplied FILE resource definition for DFHLRQ is in CSD group DFHCBTS, which is automatically included in DFHLIST group list when you initialize or upgrade your CSD. The FILE definition specifies that it is to be opened on first reference, which occurs at the end of CICS initialization when it is opened by BTS. CICS issues warning messages DFHFC0951 and DFHSH0109 if the data set is not found. Although CICS continues running without this data set, define the DFHLRQ data set, even if you are not using BTS. For information about DFHLRQ, see Overview of BTS.
DFHCMACD is a VSAM key-sequenced data set (KSDS) that is used by the CMAC transaction to provide online descriptions of CICS messages and codes. Before its first use, it must be defined and loaded as a KSDS data set. Defining the CMAC messages data set describes DFHCMACD in greater detail.
DFHDBFK is a VSAM key-sequenced data set (KSDS) that is used by the CDBM transaction to store Group commands. Before its first use, it must be defined as a KSDS data set. The DFHDBFK DD statement is required only if you intend to use the command storage functions of the CDBM transaction. Defining the CDBM GROUP command data set describes DFHDBFK in greater detail.
You might want to provide job control DD statements for those user files that are defined in the CSD (if you are using RDO) or in a file control table (for BDAM files only). If you do, the data sets are allocated at the time of CICS job step initiation, and remain allocated for the duration of the CICS job step. FILEA, the distributed library containing the data for the sample application programs, is included in this startup job stream as an example of direct allocation by job control statement.
Alternatively, you might prefer to take advantage of the CICS dynamic allocation of files. For dynamic allocation, do not specify a DD statement for the CSD. CICS then uses the full data set name as specified in the DSNAME parameter of the FILE resource definition (up to 44 characters), together with the DISP parameter, to allocate the file as part of OPEN processing. This form of dynamic allocation applies equally to files that are defined to be opened explicitly, and those that are to be opened on first reference by an application. For more information about file opening, see Defining user files. For information about the attributes that you can define on FILE resources, see FILE resources.

The card reader/line printer (CRLP) simulated terminals shown in the sample job stream are defined in the sample TCT (not used in this startup job). See the copy member DFH$TCTS, in CICSTS55.CICS.SDFHSAMP, for the source statements that you need for such devices.
For sequential devices, the last entry in the input stream can be CESF GOODNIGHT\ to provide a logical close, and quiesce the device. However, if you close a device in this way, the receive-only status is recorded in the warm keypoint at CICS shutdown. So the terminal is still in RECEIVE status in a subsequent warm start, and CICS does not then read the input file.
Note the end-of-data character (the “\” symbol) at the end of each line of the sample.