SET FILE

Function

To set the file options and process a file.

Syntax

Read syntax diagramSkip visual syntax diagramSET FILE
 
>>-SET FILE(filename)------------------------------------------->
 
>--+-------------------------------------------------------------------------------------------+-->
   '-,OPENSTATUS(-+-OPEN---+-)-+-----------------------------+-+-----------------------------+-'
                  '-CLOSED-'   '-,PROCESSTRANSIDS(-+-YES-+-)-' '-,PROCESSPROGRAMS(-+-YES-+-)-'
                                                   '-NO--'                         '-NO--'
 
>--+-----------------------------------------------------------------------------------------------+-->
   '-,ENABLESTATUS(-+-ENABLED--+-)-+-----------------------------+-+-----------------------------+-'
                    '-DISABLED-'   |                   .-YES-.   | |                   .-YES-.   |
                                   '-,PROCESSTRANSIDS(-+-NO--+-)-' '-,PROCESSPROGRAMS(-+-NO--+-)-'
 
>--+------------------------+--+---------------------------+---->
   |              .-NO--.   |  +---,DSN(-+-PRIMARY---+-)---+
   '-,IMMQUIESCE(-+-YES-+-)-'  |         '-ALTERNATE-'     |
                               '---,NEWDSN(datasetname)----'
 
>--+---------------+--+-------------------------+--------------->
   '-,CICS(applid)-'  '-,DISPOSITION(-+-SHR-+-)-'
                                      '-OLD-'
 
>--+----------------------------------------------+------------->
   +-+------------------+--+--------------------+-+
   | '-,READ(-+-YES-+-)-'  '-,BROWSE(-+-YES-+-)-' |
   |          '-NO--'                 '-NO--'     |
   '-,ALLREAD(-+-YES-+-)--------------------------'
               '-NO--'
 
>--+---------------------------------------------------------------------+-><
   +-+--------------------+--+-----------------+--+--------------------+-+
   | '-,UPDATE(-+-YES-+-)-'  '-,ADD(-+-YES-+-)-'  '-,DELETE(-+-YES-+-)-' |
   |            '-NO--'              '-NO--'                 '-NO--'     |
   '--,ALLUPDATE(-+-YES-+-)----------------------------------------------'
                  '-NO--'
 
Note:
Although all the options in the above syntax diagram are shown as optional, you must specify at least either the OPENSTATUS parameter or the ENABLESTATUS parameter. For example, the minimum command could be:
SET FILE(FILEA),OPENSTATUS(CLOSED)
or
SET FILE(FILEA),ENABLESTATUS(ENABLED)

Description

The SET FILE command enables you to open, close, enable, or disable a VSAM file in a CICS® region. You can also specify whether you want any transactions and programs that are in the control file record for the specified file to be processed, and you can vary the data set name that CICS is to use.

In this discussion of the SET FILE command, we assume that the files described in the various scenarios are dynamically allocated by CICS. It does not apply to those files that are defined by a DD statement in the CICS JCL, which are therefore allocated by MVS™ at job step initiation and remain allocated to CICS even when closed. We also stress that in addition to the points mentioned, that whether or not a file can be accessed through a batch job also depends on other factors not covered in this brief discussion. For example, the file disposition (OLD or SHR), the OPEN mode (INPUT or OUTPUT), and type of access (read or update) also affect the success or failure of the file control operation. When using CICS BAC commands, you should ensure that none of these other factors prevent a successful operation of the command you are using.

The discussion does not take into account the various file transition states, such as in the process of closing or being disabled (indicated by the CLOSING and DISABLING attributes). These have no effect on the issues being discussed.

In CICS, the open status of a VSAM file can either be OPEN or CLOSED, and this is indicated by the OPENSTATUS attribute in the file entry in the CICS file control table. If CICS closes a file, it is also de-allocated so that it can be processed by batch jobs. A file also has an enabled status, indicated by the ENABLESTATUS attribute, which can be either ENABLED, DISABLED, or UNENABLED. The enabled status determines whether or not a CICS application program request to a VSAM file can be attempted. If a file is disabled or unenabled, CICS fails the application program request without even attempting to send the request to VSAM. If the file is enabled, CICS issues the VSAM request on behalf of the application program.

The following are the most common combinations of these two states:

In the first case (OPEN, ENABLED), the file is open and available to CICS application programs and if a batch job tries to access the file, it generally fails.

In the second case (CLOSED, ENABLED), the file is closed and not allocated, but it is available to CICS programs. In this state, if your application program issues a file access request, CICS attempts to allocate then open the file. If CICS cannot allocate and open the file, it is most probably because it is allocated to a batch job, and the application program request fails. Also in this case, as long as the file is closed, it is available for access by batch jobs.

In the last three cases in the above list (OPEN, DISABLED; CLOSED, DISABLED; and CLOSED, UNENABLED), CICS fails all file control requests without even attempting them because the file is not enabled. The key difference in these three cases is that in one the file is open and in the other two it is closed. In the open case, it is allocated to CICS so that batch jobs that attempt to access the file will probably fail. In the closed cases , it is not allocated to CICS, and is available for access by batch jobs.

Note that when a file is closed to CICS, and therefore de-allocated, the file can even be deleted by a batch job.

For the most part, the DISABLED and UNENABLED states are the same. Both states prevent an application program from accessing the file. However, there is one important difference that you must take into consideration when changing the state of a file.

The only way that a file becomes unenabled is when you close the file without altering its enabled status. You can do this using the CICS BAC batch request utility, or by using the EXEC CICS SET FILE command or the CEMT SET FILE transaction. For example, if FILEA is currently open and enabled, and you issue the CEMT command SET FILE(FILEA) CLOSED, the resulting file attributes are set to CLOSED and UNENABLED. However, if the file is currently open and disabled, the same command results in the file state being set to CLOSED and DISABLED.

The difference between a disabled and an unenabled file is in how the file state is set when a closed file is subsequently opened. If a file is currently closed and disabled, and a request is made through the CICS BAC batch request utility, CICS system programming interface (SPI), or CICS CEMT command to open the file without altering its enable status attribute, the file is opened (assuming there is nothing to keep it from being opened), but its enable status remains DISABLED. On the other hand, if a file is unenabled, an open request that does not also specify an enabled status results in the file state being set to OPEN and ENABLED.

If you issue a request that alters the enable status of a file explicitly, the file ENABLESTATUS attribute is changed regardless of whether the current state is ENABLED, DISABLED, or UNENABLED.

When you define CICS BAC batch request utility SET FILE commands, it is very important to consider the final effects of various state changes. Not doing so can result in an unwanted state for a file. For example, if the state of FILEA is CLOSED, DISABLED, simply issuing a command to open the file will result in FILEA being OPEN, DISABLED - a state in which a CICS application program cannot access the file.

You should also be aware that in various situations CICS itself attempts to change the state of a file on behalf of an application program, and as specified by CICS file resource definitions. With this in mind, consider what could happen if a file is set by CICS BAC startup processing to the CLOSED, DISABLED state:

CICS BAC batch request utility SET FILE (and other SET commands) are implemented by CICS SPI commands, therefore the results of such commands are the same as if you issued an EXEC CICS SET FILE or CEMT SET FILE command. For example, if you use the batch request utility to close a currently OPEN, ENABLED file (without altering the ENABLESTATUS) it results in a file state of CLOSED, UNENABLED. Thus, you can use the CEMT transaction or the CICS SPI through the CECI transaction to determine in advance what the effects of various batch request utility commands will be.

RLS-mode files: CICS BAC includes support for VSAM files that are defined to CICS with VSAM record-level sharing (RLS) enabled (that is, RLSACCESS(YES) is specified). There is special processing associated with RLS-mode files for which you issue SET FILE commands. For a information about how CICS BAC processes SET FILE commands for RLS files, see CICS BAC support for record-level sharing (RLS).

Parameters

CICS(applid)
Specifies the applid of the CICS region to which this command is to be routed. If you omit this option, the batch request utility routes the command to the default CICS region specified by the most recent DEFAULT command.
DISPOSITION({SHR | OLD})
Sets the value of the file allocation disposition with CICS, which specifies how CICS allocates the file. The values you can specify are:
SHR
Specify this value if you want the data set to be allocated by CICS as DISP(SHR) the next time CICS opens the file.
OLD
Specify this value if you want CICS to allocate the file as DISP(OLD) the next time CICS opens the file.
DSN({PRIMARY | ALTERNATE})
Enables you to change the data set name associated with the CICS file definition. The values you can specify are:
PRIMARY
Specify this value if you want to change the data set name associated with the CICS file definition to the primary data set name defined in the CICS BAC control file object record.
ALTERNATE
Specify this value if you want to change the data set name associated with the CICS file definition to the alternate data set name in the CICS BAC control file object record.
Notes:
  1. The CICS BAC request server can process the DSN option only if the specified file is dynamically allocated by CICS. CICS BAC cannot process the DSN option for a file that is explicitly defined in the CICS region startup JCL and therefore allocated to CICS by MVS. If you attempt to alter the data set name for a file that is allocated by MVS, the SET FILE command fails and the batch request utility job step terminates immediately with return code 12.
  2. Also, the CICS BAC request server can process the DSN option only if the specified file is currently closed and disabled, or if the DSN parameter is specified as part of a command to CLOSE and DISABLE the file. If the file is not already closed, or CLOSE and DISABLE are not specified on the command, the command fails and the batch request utility job step is terminated.
  3. If the CICS region is unavailable or CICS BAC is not active in the CICS region, the batch request utility itself sets the data set name in the CICS region control file. In this case, it does so without regard to the last known state of the file, or whether or not the file was explicitly defined in the CICS region JCL.
  4. The DSN parameter is mutually exclusive with the NEWDSN parameter--you cannot specify both options. If you omit this and the NEWDSN option, the data set name remains as defined in the CICS region.
ENABLESTATUS({ENABLED | DISABLED})
Specifies whether the file is to be enabled or disabled to CICS.
FILE(filename)
Specifies the CICS file control 8-character file name.
IMMQUIESCE({NO | YES})
Specifies the type of quiesce command CICS BAC issues when it determines that it must issue a quiesce for a file that references an RLS data set. This is the equivalent of the IMMQUIESCED parameter on the EXEC CICS SET DSNAME(name) SPI command. See CICS BAC support for record-level sharing (RLS) for more information.
NEWDSN(data-value)
Specifies a new, fully qualified, 44-character data set name to be associated with the CICS file definition.
Notes:
  1. The CICS BAC request server can process the NEWDSN option only if the specified file is currently closed and disabled, or if the NEWDSN parameter is specified as part of a command to CLOSE and DISABLE the file. If the file is not already closed, or CLOSE and DISABLE are not specified on the command, the command fails and the batch request utility job step is terminated.
  2. If the CICS region is unavailable or CICS BAC is not active in the CICS region, the batch request utility itself sets the data set name in the CICS region control file. In this case, it does so without regard to the last known state of the file.
  3. The NEWDSN parameter is mutually exclusive with the DSN parameter--you cannot specify both options. If you omit this and the DSN option, the data set name remains as defined in the CICS region.
OPENSTATUS({OPEN | CLOSED})
Specifies whether the file is to be opened or closed in the CICS region.
PROCESSPROGRAMS({YES | NO})
Specifies whether any program specified in the CICS BAC control file object record for the file being processed is also to be processed, depending on the requested status of the file.
YES
Specifying YES means that the program status is set as follows:
  • If the command specifies OPENSTATUS(OPEN) and ENABLESTATUS(ENABLED), the associated programs are ENABLED. The programs are enabled after the file status is set.
  • If the command specifies OPENSTATUS(CLOSED) or ENABLESTATUS(DISABLED), the associated programs are DISABLED. The programs are disabled before the file status is set
NO
Specifies that the status of associated programs is not to be changed.
PROCESSTRANSIDS({YES | NO})
Specifies whether any transaction specified in the CICS BAC control file object records for the file being processed is also to be processed, depending on the requested status of the file, as follows:
YES
Specifying YES means that the transaction status is set as follows:
  • If the command specifies OPENSTATUS(OPEN) and ENABLESTATUS(ENABLED), the associated transactions are ENABLED.
  • If the command specifies OPENSTATUS(CLOSED) or ENABLESTATUS(DISABLED), the associated transactions are DISABLED.
NO
Specifies that the status of associated transaction IDs is not to be changed.
The following options all relate to the file operations as defined by the CICS file resource definition.
ALLREAD({YES | NO})
Sets the value of both the file READ and BROWSE attributes (see below).

You cannot specify ALLREAD with either READ or BROWSE.

ALLUPDATE({YES | NO})
Sets the value of the file ADD, DELETE, and UPDATE attributes (see below).

You cannot specify ALLUPDATE with any of the ADD, UPDATE, or DELETE options.

ADD({YES | NO})
Sets the value of the file ADD attribute, which specifies whether records can be added to the file.
BROWSE({YES | NO})
Sets the value of the file BROWSE attribute, which specifies whether records can be retrieved sequentially from the file.
DELETE({YES | NO})
Sets the value of the file DELETE attribute, which specifies whether records can be deleted from the file.
READ({YES | NO})
Sets the value of the file READ attribute, which specifies whether records on this file can be read.
UPDATE({YES | NO})
Sets the value of the file UPDATE attribute, which specifies whether records on this file can be updated.