Starting a control region (STRCICS) - IBM - AS/400

You should use the STRCICS CL command to start a control region and, optionally, to convert any resource definition files.

Note: If you are migrating to a new release of CICS/400, you should convert all your existing resource definition files using the INZCICS CL command as part of the IVP procedure.

CL command defaults
The defaults given in the CL command description are those that are supplied with the OS/400 system. You should check that your installation has not made any changes to these command default parameters.

STRCICS

1 All parameters preceding this point can be specified positionally

Function
The Start CICS (STRCICS) CL command starts a CICS control region and specifies how to recover CICS temporary storage and transient data files.

This command causes a *WARM start (which is the default) of the specified control region. The library list (*LIBL is the default value) is used to locate the CICS group that contains the CICS system initialization table (SIT) that specifies the values needed to begin control region initialization. For details on setting up a SIT. The CICS control region must have completed its startup process before any associated shells (batch or user) can be started. Refer to the STRCICSUSR CL command to start a CICS user shell.

Required parameters

CTLRGN
The name of the CICS control region to be started, also known as the CICS system ID.

control-region: The name of the control region may be up to four characters in length. The first character must be alphabetic, or one of the special characters $, @, or #. The remaining characters can be alphanumeric or$, @, or #.

You should not give the control region the name CICS.

Optional parameters

STRTYPE
indicates how to recover the CICS temporary storage and transient data files when the CICS control region is started. STRTYPE is needed only if you need to do a *COLD or *EMER start. The possible STRTYPE values are:

• *WARM:
• *COLD:
• *EMER:

The results of setting these values are described in “Setting the STRTYPE parameter”.

SITLIB
The name of the OS/400 library containing the group (SITGRP) that contains the CICS system initialization table to be used to initialize the CICS control region. This parameter is used if you need to bring in a different SIT for special processing.

The possible SITLIB values are:

*LIBL: The library list is used to locate the first CICS group that contains the CICS system initialization table.
*CURLIB: The current library for the job is used to locate the group that contains the system initialization table.

library-name:Specifies the name of the library used to locate the group that contains the system initialization table.

SITGRP
The name of the CICS group that contains the CICS system initialization table to be used to initialize the CICS control region.

*FIRST No group is specified. The first group found is used.

group-name: The maximum length is ten characters. The first character must be alphabetic, or one of the special characters, $, @, or #. The remaining characters can be alphanumeric or$, @, or #.

CONVERT
indicates what happens to previous-release resource definition tables that are encountered during control region initialization.

The possible CONVERT values are:

*PROMPT: Tables from previous releases of CICS require the operator to respond as to whether they get converted to the current release.
*CVT: Tables from previous releases of CICS/400 are automatically converted by INZCICS to the current release.

All groups contained in the library are converted.

*NOCVT: Tables from previous releases of CICS are not automatically converted to the current release.
When the system initialization table is from a previous release of CICS/400, then the control region is not started. Any other tables from previous releases allow the CICS control region to be started, but the data in the tables is ignored.

Examples
The STRCICS command starts a CICS control region called “TEST”. The CICS control region is started with all CICS temporary storage and transient data files being cleared. It uses the CICS system initialization table located in the OS/400 library MYLIB and the CICS group MYGRP. If any resource definition files from the previous release are found, you will be asked whether or not you want these files to be converted. If you ask for the files to be converted, all files in the library will be converted.

STRCICS CTLRGN( TEST ) STRTYPE( *COLD ) SITLIB(MYLIB) SITGRP( MYGRP ) CONVERT( *PROMPT )

Setting the STRTYPE parameter

Terminology

The term recovery is applied to both recoverable and nonrecoverable queues with the following meanings:

To recover a nonrecoverable queue means to leave it as it was at the preceding control region termination.

To recover a recoverable queue unaffected by in-doubt units of work means to make it as it was at the preceding control region termination, but with all the uncommitted changes of in-flight units of work removed.

To recover a temporary storage recoverable queue affected by in-doubt units of work means to restore it to the condition at control region termination. It can be read by any transaction but cannot be written until the in-doubt units of work are resolved.

To recover a transient data recoverable queue affected by in-doubt units of work results in the actions shown

Recovery actions for TD queues affected by in-doubt units of work

(A temporary storage queue can be affected by at most one in-doubt unit of work. A transient data queue can be affected by up to two in-doubt units of work, one as reader, and one as writer.)

STRTYPE values affect the recovery of the CICS temporary storage (TS) and transient data (TD) files. The way these files are recovered also depends on the TSCTL and TDCTL data recovery options in the CICS system initialization table. The recovery of these files also depends on whether there are in-doubt units of work (explained below) affecting them.

Operation with no in-doubt units of work
STRTYPE set to *WARM: When *NO is specified on the TSCTL data recovery option, the CICS temporary storage queues are cleared. When *NO is specified on the TDCTL data recovery option the transient data queues are cleared.

When *YES is specified on the TSCTL data recovery option, all recoverable and nonrecoverable temporary storage queues are recovered. When *YES is specified on the TDCTL data recovery option, all recoverable and nonrecoverable transient data queues are recovered.

STRTYPE set to *COLD: The CICS temporary storage and transient data queues are cleared.

STRTYPE set to *EMER: When *NO is specified on the TSCTL data recovery option, the CICS temporary storage queues are cleared. When *NO is specified on the TDCTL data recovery option, the transient data queues are cleared.

When *YES is specified on the TSCTL data recovery option, recoverable temporary storage queues are recovered (except those that are older than the specified age limit in the TSCTL Age limit element). When *YES is specified on the TDCTL data recovery option, all recoverable transient data queues are recovered.

Operation with in-doubt units of work
The use of two-phase commit protocols for data integrity in distributed processing makes it possible for a CICS or OS/400 failure to leave uncommitted changes to resources. (Without two-phase commit, these resources are returned to the state they were in before any changes were made, irrespective of how related changes in other processors are treated.)

With two-phase commit, if a system failure occurs in the middle of coordinating changes with a remote system, the remote system waits until the failing system recovers, and advises it whether changes in the failing processor are to be committed or backed out. If a unit of work originating in a CICS system is still waiting to hear from the remote system at the time the CICS control region is initialized, the unit of work is said to be in-doubt. In this case, any CICS resources in which it has uncommitted changes must be preserved until the unit of work isresolved.

This means that the CICS control region is not initialized, because this would destroy the integrity of the in-doubt units of work. This happens when the STRCICS command is used to start a CICS control region for which:

• There are in-doubt units of work waiting to be resolved,
• And, the STRTYPE parameter is *WARM or *EMER,
• And, an in-doubt unit of work has uncommitted changes to a recoverable TD/TS queue, and the data recovery option of TDCTL (or TSCTL depending on the queue) is *NO.

A message to say that this has happened will be sent to the job log. You are recommended to make the recovery option *YES, or to use OS/400 facilities to remove the in-doubt units of work. If there are no in-doubt units of work, the control region will be initialized as required by the STRTYPE and TDCTL parameters.

TS queue with age-limit: The situation is different when a TS queue has the age-limit option of TSCTL set. If the STRCICS command is used to start a CICS control region for which:

• There are in-doubt units of work waiting to be resolved,
• And, the STRTYPE parameter is *WARM or *EMER,
• And, an in-doubt unit of work has uncommitted changes to a recoverable TS queue,
• And the aging option of TSCTL requires such a queue to be deleted,

the queue will not be deleted, since this would destroy the integrity of the in-doubt units of work. If there are no in-doubt units of work, the TS queues will be discarded in accordance with the aging option of the TSCTL parameter.

The complete summary of recovery procedures for TD and TS queues (whether in-doubt units of work are involved or not) is summarized in the following sections.

CICS/400 recovery with a cold start
With a cold start, all recoverable and nonrecoverable queues are cleared. The settings of TSCTL and TDCTL have no effect. If there are in-doubt units of work waiting to be resolved, the control region is not initialized and a message is written to the job log. You should use a warm start or OS/400 facilities to remove the in-doubt units of work.

CICS/400 recovery with a warm start

CICS/400 recovery with STRTYPE=*WARM. In each row, the last entry is the action taken, as a result of the conditions in the preceding columns.

CICS/400 recovery with STRTYPE=*EMER. In each row, the last entry is the action taken, as a result of the conditions in the preceding columns.