UPDATE REGION

Function

Update an existing CICS region object in the CICS region control file.

Description

You can use the UPDATE REGION command to modify a CICS region object record in a region control file. If a record for the specified CICS region that you are trying to update does not exist in the region control file, the file maintenance utility rejects the command as an error with error message CBKxx7206E.

Note that you cannot specify an ADDIFNEW parameter for the CICS region object record as you can with other resource types. For information about the CICS region control file, see Defining and initializing a CICS BAC control file.

Parameters

ABENDFLAG({CONTINUE|TERMINATE|ABEND|WRITE})

Specifies the action to be taken by the CICS® BAC batch request utility if the CICS region is not available and the last time the CICS region was shut down it did not go through normal shutdown processing.

CONTINUE

The CICS BAC batch request utility is to continue processing as if the CICS region had shut down normally.

ABEND

The CICS BAC batch request utility job step is to terminate abnormally with the abend code you specify on the RESETABCODE parameter.

TERMINATE

The CICS BAC batch request utility job step is to terminate with the non-zero return code you specify on the RESETRETCODE parameter.

WRITE

The CICS BAC batch request utility is to issue a write-to-operator-with-reply (WTOR) message to the MVS system console and wait for a reply to determine what further action it should take.

BATCHLEAVECLOSED({YES|NO})

Specifies the action CICS BAC is to take during batch request utility processing if it receives a SET FILE command to set the file open status and enable status to OPEN and ENABLED and the specified file is currently set to CLOSED and ENABLED.

YES

Specifies that CICS BAC is to ignore the SET FILE OPENSTATUS and ENABLESTATUS parameters and leave the file status as CLOSED and ENABLED.

NO

Specifies that CICS BAC is honor the SET FILE OPENSTATUS and ENABLESTATUS parameters and change the file status to OPEN and ENABLED.

CEMTREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility RUNCEMT commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

COLDSTART({YES | NO})

Specifies whether a cold start of the CICS region should include CICS BAC resource processing.

YES

If CICS performs a cold start, at the end of CICS region initialization process CICS BAC is to set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

NO

If CICS performs a cold start, CICS BAC does not set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

See also the STARTUPOPTS parameter on the definitions of the CICS BAC FILE, PROGRAM, TDQUEUE, and TRANSID resource objects.

CONVERTOPEN({YES|NO})

Specifies the action that CICS BAC is to take for batch request utility SET FILE and SET TDQUEUE commands if a command specifies OPENSTATUS(OPEN) parameter but the ENABLESTATUS parameter is not also specified.

YES

Specifies that CICS BAC is to convert SET FILE and SET TDQUEUE OPENSTATUS(OPEN) commands to OPENSTATUS(OPEN),ENABLESTATUS(ENABLED) even if the if the command does not explicitly contain the ENABLESTATUS parameter.

NO

Do not convert commands that specify OPENSTATUS without ENABLESTATUS.

CREATERECORD({YES|NO})

Specifies whether CICS BAC is to create a resource object record in the CICS region control file for an undefined resource and for which the batch request utility processes a command. These are undefined resources controlled by the UNDEFINEDresource(YES) parameters.

YES

Specifies that CICS BAC is to create a resource object record in the CICS region control file for an undefined resource that it is allowed to process. Creating a record for an undefined resource enables CICS BAC to set the object to its last known state during CICS BAC region startup processing, and avoids an undefined object condition occurring again for the resource.

See the UNDEFINED and UNDEFINEDresource parameters for more information.

NO

Specifies that CICS BAC is not to create a resource object record in the CICS region control file for an undefined resource, even though you have specified that CICS BAC is allowed to process batch request utility commands for such resources.

DISALLOWED({CONTINUE|TERMINATE|ABEND})

Specifies the action CICS BAC is to take if it receives a disallowed command (that is you have specified NO on one of the commandREQUEST parameters, such as the FILEREQUEST(NO) parameter, for example). The disallowed actions are:

CONTINUE

CICS BAC is to ignore only the disallowed command and carry on processing the next command from the batch request utility.

TERMINATE

CICS BAC is to terminate the job step with the return code specified on the DISALLOWEDRETCODE parameter.

ABEND

CICS BAC is to terminate the job step abnormally with the abend code specified on the DISALLOWEDABCODE parameter.

Terminate with abend code. CICS BAC will abend the job step with the abend code entered in this text field.

DISALLOWEDABCODE(number)

Specifies the abend code CICS BAC is to use when it abends the batch request utility job step because it has received a disallowed command and you have specified DISALLOWED(ABEND).

number

Specifies an abend code in the range 1 through 4095.

DISALLOWEDRETCODE(number)

Specifies the job step return code CICS BAC is to use when it terminates the batch request utility job step because it has received a disallowed command and you have specified DISALLOWED(TERMINATE).

number

Specifies a return code in the range 1 through 4095.

EMERGENCYSTART({YES | NO})

Specifies whether an emergency start of the CICS region should include CICS BAC resource processing.

YES

If CICS performs an emergency start, at the end of CICS region initialization process CICS BAC is to set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

NO

If CICS performs an emergency start, CICS BAC does not set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

See also the STARTUPOPTS parameter on the definitions of the CICS BAC FILE, PROGRAM, TDQUEUE, and TRANSID resource objects.

FILEREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility SET FILE commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

LINKREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility LINK commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

DYNALLOG({SYSOUT|DSN|NO})

Specifies whether the CICS BAC audit log, DD name CBKLOG, should be dynamically allocated at CICS BAC startup if it is not present in the CICS region JCL, or in the batch request utility JCL if the request is being serviced directly because the CICS region is not available. If it dynamically allocates the audit log data set, CICS BAC uses CBKLOG as the DD name.

SYSOUT

Specifies that CICS BAC is to dynamically allocate the audit log to the SYSOUT class instead of a data set.

DSN

Specifies that CICS BAC is to dynamically allocate the audit log to the data set named on the LOGDSN parameter, with the attributes specified on the LOGDISP parameter.

NO

Specifies that CICS BAC is not to dynamically allocate the audit log. If a CBKLOG DD statement is not present in the CICS region JCL, no audit log messages are written, regardless of the value of the LOGERRORS, LOGSTATE, or LOGNATIVE parameters at the time the audit log record needs to be written. This also applies to the batch request utility JCL if the commands are being serviced directly to the CICS region control file because the CICS region is not available.

LOGDISP({SHR|OLD|MOD})

Specifies the disposition of the audit log data set named on the LOGDSN parameter. The dispositions you can specify are the standard MVS DISP parameter values for data sets (SHR, OLD, and MOD).

LOGDSN(datasetname)

Specifies the fully-qualified 44-character data set name that CICS BAC is to dynamically allocate as the audit log data set. Dynamic allocation is performed either:

• By CICS BAC if it is running in the CICS region, or
• By the batch request utility if is processing commands directly because the CICS region is not available.

The DD name used to dynamically allocate the audit log is CBKLOG. See The audit log data set for more information.

LOGERRORS({YES|NO})

Specifies whether you want CICS BAC to write audit log records for any error conditions or failed requests. If you specify YES, log records are written to the audit log if one is currently allocated.

LOGNATIVE({YES|NO})

Specifies whether you want CICS BAC batch request utility to write audit log records for any error conditions or failed requests when it is updating the CICS region control file directly because the CICS region is not available. If you specify YES, log records are written to the audit log if one is currently allocated to the batch request utility.

LOGSTATE({YES|NO})

Specifies whether you want CICS BAC to write audit log records for any changes to the state of resources by other than CICS BAC commands. If you specify YES, log records are written to the audit log if one is currently allocated.

MONITORFILES({YES|NO})

Specifies whether you want the CICS BAC state monitor to track file status changes for the region. Note that all state changes resulting from a CICS BAC command are recorded, regardless of the value of this parameter.

YES

Any change in the state of a file occurring while CICS BAC is active in the region is recorded in the relevant file object record in the CICS control file record, if the file is defined.

NO

Any change in the state of a file is not recorded unless the state change originated from a CICS BAC command from the batch request utility or from the CICS BAC request server callable API.

MONITORPROGRAMS({YES|NO})

Specifies whether you want the CICS BAC state monitor to track program status changes for the region. Note that all state changes resulting from a CICS BAC command are recorded, regardless of the value of this parameter.

YES

Any change in the state of a program occurring while CICS BAC is active in the region is recorded in the relevant program object record in the CICS control file record, if the program is defined.

NO

Any change in the state of a program is not recorded unless the state change originated from a CICS BAC command from the batch request utility or from the CICS BAC request server callable API.

MONITORTDQUEUES({YES|NO})

Specifies whether you want the CICS BAC state monitor to track TD queue status changes for the region. Note that all state changes resulting from a CICS BAC command are recorded, regardless of the value of this parameter.

YES

Any change in the state of a TD queue that occurs while CICS BAC is active in the region is recorded in the relevant TD queue object record in the CICS control file record, if the TD queue is defined.

NO

Any change in the state of a TD queue is not recorded unless the state change originated from a CICS BAC command from the batch request utility or from the CICS BAC request server callable API.

MONITORTRANSIDS({YES|NO})

Specifies whether you want the CICS BAC state monitor to track transaction ID status changes for the region. Note that all state changes resulting from a CICS BAC command are recorded, regardless of the value of this parameter.

YES

Any change in the state of a transaction ID that occurs while CICS BAC is active in the region is recorded in the relevant transaction ID object record in the CICS control file record, if the transaction ID is defined.

NO

Any change in the state of a transaction ID is not recorded unless the state change originated from a CICS BAC command from the batch request utility or from the CICS BAC request server callable API.

POSTCOMMANDEXIT(exitprogname)

Specifies the name of your exit program that is to be invoked immediately after the CICS BAC request server has processed a batch request utility command in the CICS region. Note that commands must be processed in the CICS region for this post-command exit to be invoked. Also, commands issued through the CICS BAC request server callable API can also drive the exit.

PRECOMMANDEXIT(exitprogname)

Specifies the name of your exit program that is to be invoked immediately before the CICS BAC request server processes a batch request utility command in the CICS region. Note that commands must be processed in the CICS region for this pre-command exit to be invoked. Also, commands issued through the CICS BAC request server callable API can also drive the exit.

PROGRAMREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility SET PROGRAM commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

REGION(applid)

Specifies the name of the CICS region object record that you are updating.

RESETABCODE(number)

Specifies the abend code to be used by the batch request utility if:

• The CICS region is not available and the last time the CICS region was shut down it did not go through normal shutdown processing and
• You specify ABENDFLAG(ABEND) in the CICS region properties record.

number

Specifies an abend code in the range 1 through 4095.

RESETFLAG({YES|NO})

Specifies whether the CICS region shutdown flag is to be reset to normal in addition to the action CICS BAC takes if you specify the ABENDFLAG parameter.

RESETRETCODE(number)

Specifies the return code to be used by the batch request utility if:

• The CICS region is not available and the last time the CICS region was shut down it did not go through normal shutdown processing and
• You specify ABENDFLAG(TERMINATE).

number

Specifies a return code in the range 1 through 4095.

RLSOPTIONS({PROCESS|IGNORE|TERMINATE|ABEND})

Specifies what action CICS BAC is to take when the CICS BAC request server receives a command to open or close a file defined to CICS with RLSACCESS(YES).

PROCESS

Specifies that CICS BAC is to process the command. If the command is to close the file, CICS BAC issues the appropriate commands to quiesce the data set associated with the file (if the file is not currently quiesced) before closing the file. If the command is to open the file, CICS BAC issues the appropriate commands to unquiesce the data set associated with the file (if it is currently quiesced) before opening the file.

IGNORE

Specifies that CICS BAC is to ignore the command. However, programs and transaction IDs associated with the file are processed as if the SET FILE command was processed.

TERMINATE

Specifies that CICS BAC is to terminate the job step with the return code specified on the RLSRETCODE parameter.

ABEND

Specifies that CICS BAC is to abnormally terminate the job step with the abend code specified on the RLSABCODE parameter

RLSRETCODE(number)

Specifies the numeric return code CICS BAC is to use if you specify RLSOPTIONS(TERMINATE). You can specify a return code value in the range 1 through 4095.

RLSABCODE(number)

Specifies the numeric abend code CICS BAC is to use if you specify RLSOPTIONS(ABEND). You can specify a return code value in the range 1 through 4095.

STARTREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility START commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

STARTUPLEAVECLOSED({YES|NO})

Specifies how you want CICS BAC to handle status changes for files during CICS region startup. To reduce region initialization time, CICS allows you to define a file with the CLOSED ENABLED attributes. This means that the file is not allocated and opened until the first time it is referenced by an application program. This avoids the overhead of opening files during CICS initialization, and reduces CICS region initialization time.

YES

CICS BAC is to allow a file to remain in the CLOSED ENABLED state during startup processing even if, during CICS region initialization, it finds that the last requested status for the file is OPEN ENABLED.

NO

CICS BAC is to override the CLOSED ENABLED attributes if the last requested state in the CICS BAC region control file is OPEN ENABLED and open the file.

SYSCREATE({YES|NO})

Specifies whether CICS BAC is to create a resource object record in the CICS region control file for an undefined resource and for which the CICS BAC state change monitor has detected a state change. This parameter applies to undefined resources controlled by the UNDEFINEDresource(YES) parameters.

YES

Specifies that CICS BAC is to create a resource object record in the CICS region control file for an undefined resource for which the state change monitor has detected a state change. Creating a record for an undefined resource enables CICS BAC to set correctly the state of an object during CICS BAC region startup processing, and avoids an undefined object condition occurring again for the resource.

See the UNDEFINED and UNDEFINEDresource parameters for more information.

NO

Specifies that CICS BAC is not to create a resource object record in the CICS region control file for an undefined resource.

TDQUEUEREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility SET TDQUEUE commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

TRACEENTRIES(0|number)

Specifies the number of trace table entries CICS BAC is to allocate for diagnostic tracing. A single entry occupies 128 bytes in CICS private storage above 16MB.

0

Zero turns off CICS BAC internal trace.

number

Number can be a value in the range 1 through 9999.

TRACEOPTIONS({ENTRY|ALL})

Specifies the level of CICS BAC internal tracing activity you want in the CICS region. CICS BAC has its own trace facility for diagnostic purposes and the following options specify what you want CICS BAC to trace:

ENTRY

Trace CICS BAC module entry and exit points only.

ALL

Trace all CICS BAC trace points.

TRANSIDREQUEST({YES|NO})

Specifies whether CICS BAC is to allow batch request utility SET TRANSID commands to be processed in this CICS region. If you specify NO, the action taken by CICS BAC is determined by the DISALLOWED parameter.

UNDEFINED({CONTINUE|TERMINATE|ABEND})

Specifies the action you want CICS BAC to take if an undefined object condition occurs and you have specified that batch request utility commands for such resources are not to be processed (see the UNDEFINEDresource parameters).

In some situations, a batch request utility job step can contain a command to change the state of a resource, even though the resource is not yet defined to CICS BAC in the CICS region control file, causing an undefined object condition. Similarly, if the CICS BAC state change monitor is active and tracking resource state changes in the CICS region, it could detect a state change request for an undefined resource.

If you have specified NO on an UNDEFINEDresource parameter, specify the action CICS BAC is to take as follows:

CONTINUE

Specifies that CICS BAC is to ignore the batch request utility command for the undefined resource and continue processing with the next command.

TERMINATE

Specifies that CICS BAC is to terminate the batch request utility job step with the return code you specify on the UNDEFINEDRETCODE parameter.

ABEND

Specifies that CICS BAC is to terminate abnormally the batch request utility job step with the abend code you specify on the UNDEFINEDABCODE parameter.

UNDEFINEDABCODE({YES|NO})

Specifies the abend code CICS BAC is to use when it abends the batch request utility job step because it has received a command for an undefined object and you have specified UNDEFINED(ABEND).

number

Specifies an abend code in the range 1 through 4095.

UNDEFINEDFILE({YES|NO})

UNDEFINEDPROGRAM({YES|NO})

UNDEFINEDTDQUEUE({YES|NO})

UNDEFINEDTRANSID({YES|NO})

Specifies the action you want CICS BAC to take if the batch request utility receives a command for a file, program, TD queue, or transaction ID resource that is not defined in the CICS region control file (see also the UNDEFINED parameter).

YES

Specifies that CICS BAC batch request utility can process commands for file, program, TD queue, or transaction ID resources if they are not defined in the CICS region control file.

NO

Specifies that CICS BAC batch request utility is not to process commands for resources if they are not defined in the CICS region control file. The action taken by the batch request utility in this case is determined by what you specify on the UNDEFINED parameter.

UNDEFINEDRETCODE({YES|NO})

Specifies the return code CICS BAC is to use when it terminates the batch request utility job step because it has received a command for an undefined object and you have specified UNDEFINED(TERMINATE).

number

Specifies a return code in the range 1 through 4095.

WARMSTART({YES | NO})

Specifies whether a warm start of the CICS region should include CICS BAC resource processing.

YES

If CICS performs a warm start, at the end of CICS region initialization process CICS BAC is to set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

NO

If CICS performs a warm start, CICS BAC does not set the state of resources defined in the region control file to their last requested state, unless specified otherwise by an individual resource object definition.

See also the STARTUPOPTS parameter on the definitions of the CICS BAC FILE, PROGRAM, TDQUEUE, and TRANSID resource objects.