Function
Add a new file object to the target CICS region control file.
Syntax

ADD FILE
.---,REPLACE(-NO-)----.
>>-ADD FILE(filename)--+---------------------+------------------>
'-,REPLACE(-+-YES-+-)-'
'-NO--'
>--+-------------------------------------------------------------------------------------+-->
'-,EXCLUDE(-+-YES--)--,EXCLUDEACTION(-+-IGNORE--)---------------------------------+-+-'
| +-TERMINATE--)--,EXCLUDERETCODE(returncode)-+ |
| '-ABEND--)--,EXCLUDEABCODE(abendcode)-------' |
'-NO--)-----------------------------------------------------------------'
>--+----------------------------------+------------------------->
'-,STARTUPOPTS(-+-COLD---------+-)-'
+-WARM---------+
+-EMER---------+
+-COLDWARM-----+
+-COLDWARMEMER-+
+-COLDEMER-----+
+-WARMEMER-----+
'-USECICS------'
>--+---------------------------+-------------------------------->
'-,PRIMARYDSN--(--dsname--)-'
>--+-----------------------------+------------------------------>
'-,ALTERNATEDSN--(--dsname--)-'
>--+--------------------------------------------------------+--->
'-,RLSOPTIONS(-+-IGNORE--)-----------------------------+-'
+-PROCESS--)----------------------------+
+-TERMINATE--)--,RLSRETCODE(returncode)-+
+-ABEND--)--,RLSABCODE(abendcode)-------+
'-TAKE--)-------------------------------'
>--+---------------------------------------------+-------------->
'-,TRANSIDS(transid-1[,transid-2…,transid-n])-'
>--+------------------------------------------+----------------><
'-,PROGRAMS(progid-1[,progid-2…,progid-n])-'
Description
You can use the ADD FILE command to add a file object record to
a CICS region control file. If a record for the specified file name
already exists in the region control file, the action taken by the file maintenance utility is
determined by the REPLACE parameter.
Parameters
- ALTERNATEDSN(datasetname)
- Specifies the fully-qualified data set name CICS BAC is to use
when a batch request utility job step invokes a SET FILE command that
specifies DSN(ALTERNATE) parameter.
- EXCLUDE({NO | YES})
- Specifies that CICS BAC is to exclude this file from all processing,
including batch request utility processing and CICS state monitoring.
- NO
- CICS BAC is not to exclude this file.
- YES
- CICS BAC is to exclude this file from all processing. If you
specify YES, also specify the action that CICS BAC is to take if it
encounters a batch request utility command for this file (see the
EXCLUDEACTION parameter).
- EXCLUDEABCODE(abendcode)
- Specifies the numeric abend code CICS BAC is to use if you specify
EXCLUDEACTION(ABEND). You can specify an abend code value in the range
1 through 4095.
- EXCLUDEACTION(IGNORE|TERMINATE|ABEND)
- Specifies the action CICS BAC is to take if you specify EXCLUDE(YES).
You can choose one of the following three options:
- IGNORE
- CICS BAC is to ignore the command as if it was not present and
continue processing with the next command.
- TERMINATE
- CICS BAC is not to process any further commands in the job step,
and the batch request utility job step is to terminate with the specified
return code (see the EXCLUDERETCODE parameter).
- ABEND
- CICS BAC is not to process any further commands in the job step,
and the batch request utility job step is to abend with the specified
abend code (see the EXCLUDEABCODE parameter).
- EXCLUDERETCODE(returncode)
- Specifies the numeric return code CICS BAC is to use if you specify
EXCLUDEACTION(TERMINATE). You can specify a return code value in the
range 1 through 4095.
- FILE(filename)
- Specifies the 8-character file name that you want to add to
a CICS region control file.
- PRIMARYDSN(datasetname)
- Specifies the fully-qualified data set name CICS BAC is to use
when a batch request utility job step invokes a SET FILE command that
specifies DSN(PRIMARY) parameter.
- PROGRAMS(progid-1[,progid-2…,progid-n])
- Specifies one or more programs to be added to the list of programs
in the file object record in the CICS region control file. Program
names must be valid CICS application program names up to a maximum
of 8 characters.
If you enter more than one program name, separate
the names with a comma or a blank. The maximum number of program names
you can add is 512.
These are programs to be processed by the
batch request utility when it processes a SET FILE command for this
file. If the command sets the file state to OPENSTATUS(OPEN) and ENABLESTATUS(ENABLED),
the specified programs are set to ENABLESTATUS(ENABLED) after the file state has been successfully set.
If the batch request utility command sets the file state to OPENSTATUS(CLOSED)
or ENABLESTATUS(DISABLED), the programs are set to ENABLESTATUS(DISABLED) before the file state is set.
For more information,
see the PROCESSPROGRAMS parameter on the SET FILE command on page SET FILE.
- REPLACE({NO|YES})
- Specifies the action the file maintenance utility is to take if a file object record
already exists for the file name you are trying to add.
- NO
- If there is already a file object in the CICS region control
file for this file name, reject the ADD FILE command.
- YES
- If there is already a file object in the CICS region control
file for this file name, replace it with the information in this ADD
FILE command.
- RLSABCODE(abendcode)
- Specifies the numeric abend code CICS BAC is to use if you specify
RLSOPTION(ABEND). You can specify an abend code value in the range
1 through 4095.
- RLSOPTIONS({IGNORE|PROCESS|TERMINATE|ABEND|TAKE})
- Specifies the default action to be taken if the CICS BAC request
server receives a command to open or close the file, and the file
is defined with RLSACCESS(YES). You can specify one of the following
options:
- IGNORE
- CICS BAC is to ignore open and close commands for this file. However,
programs and transaction IDs associated with the file object are to
be processed as if the command was processed.
- PROCESS
- CICS BAC is to process the command. If the command is to close
the file, CICS BAC is to quiesce the data set associated with the file
(if the file is not already quiesced) before closing the file. If
the command is to open the file, CICS BAC is to unquiesce the data set
associated with the file (if it is currently quiesced) before opening
the file.
- TERMINATE
- CICS BAC is to terminate the job step with the return code specified
on the RLSRETCODE parameter.
- ABEND
- CICS BAC is to abend the job step with the abend code specified
on the RLSABCODE parameter.
- TAKE
- CICS BAC is to take the action specified in the CICS region settings.
- RLSRETCODE(abendcode)
- Specifies the numeric return code CICS BAC is to use if you specify
RLSOPTION(TERMINATE). You can specify a return code value in the range
1 through 4095.
- STARTUPOPTS({COLD|WARM|EMER|COLDWARM|COLDWARMEMER| COLDEMER|WARMEMER|USECICS})
- Specifies the types of CICS startups during which CICS BAC should
set the state of this file to its last requested state, including
its open status, enable status, data set name, and access options.
If you specify any of the startup types, CICS BAC resets this file
to its last requested state at the end of that type of CICS region
initialization. The options are as follows:
- COLD
- CICS BAC is to restore the last requested state of the file
during a cold start of the CICS region.
- WARM
- CICS BAC is to restore the last requested state of the file
during a warm start of the CICS region.
- EMER
- CICS BAC is to restore the last requested state of the file
during an emergency restart of the CICS region.
- COLDWARM
- CICS BAC is to restore the last requested state of the file
during cold and warm starts of the CICS region.
- COLDWARMEMER
- CICS BAC is to restore the last requested state of the file
during cold, warm, and emergency starts of the CICS region.
- COLDEMER
- CICS BAC is to restore the last requested state of the file
during cold and emergency starts of the CICS region.
- WARMEMER
- CICS BAC is to restore the last requested state of the file
during warm and emergency starts of the CICS region.
- USECICS
- Depending on the type of startup, CICS BAC is to use the CICS
region default startup property (as defined by the region properties
record for the CICS region) to determine whether or not it should
reset a file to its last requested state.
- TRANSIDS(transid-1[,transid-2…,transid-n])
- Specifies one or more transactions to be added to the list of
transaction in the file object record in the CICS region control file.
Transaction IDs must be valid CICS transaction IDs up to a maximum
of 4 characters.
If you enter more than one transactionID, separate
the IDs with a comma or a blank. The maximum number of transaction
IDs you can add is 512.
These are transactions to be processed
by the batch request utility when it processes a SET FILE command
for this file. If the command sets the file state to OPENSTATUS(OPEN)
and ENABLESTATUS(ENABLED), the specified transactions are set to ENABLESTATUS(ENABLED) after the file state has been successfully set.
If the batch request utility command sets the file state to OPENSTATUS(CLOSED)
or ENABLESTATUS(DISABLED), the transactions are set to ENABLESTATUS(DISABLED) before the file state is set.
For more information,
see the PROCESSTRANSIDS parameter on the SET file command on page SET FILE).