DCMT VARY FILE

The DCMT VARY FILE command performs the following functions:
idmscu19
The DCMT VARY FILE command performs the following functions:
  • Changes the status of a specified file by closing the file or opening it for retrieval or update
  • Allocates or deallocates a specified z/OS or z/VM file
This article describes the following information:
Syntax
►►─── DCMT ─┬───────────────────┬─────────────────────────────────────────────► └─ broadcast-parms ─┘ ►─── Vary File ─┬─ segment-name.file-name ─┬─────────────────────────────────► └─ SYSTRK-file-name ───────┘ ►─┬─ OPen ──────────────────────────────────────────────────────────────┬─►◄ ├─ OPen Update ───────────────────────────────────────────────────────┤ ├─ Close ─────────────────────────────────────────────────────────────┤ ├─ ACtive ────────────────────────────────────────────────────────────┤ ├─ Inactive ──────────────────────────────────────────────────────────┤ ├─ ALlocate ──────────────────────────────────────────────────────────┤ ├─ DEallocate ─┬─────────┬────────────────────────────────────────────┤ │ └─ Force ─┘ | ├─┬─ DAtaspace No ─┬──────────────────────────────────────────────────┤ │ └─ DN ───────────┘ │ ├─┬─ DAtaspace Yes ─┬─────────────────────────────────────────────────┤ │ └─ DY ────────────┘ │ ├─ DSname new-dataset-name ───────────────────────────────────────────┤ ├─ DISp ─┬─ Old ─┬────────────────────────────────────────────────────┤ │ └─ Shr ─┘ │ ├─ PRefetch ─┬─ ON ──┬────────────────────────────────────────────────┤ │ └─ OFF ─┘ │ ├─ MEMORY CACHE ─┬─ NO ◄──────────────────────────────────────────────┤ │ └─ YES ──┬───────────────────────────────────┬───────┤ | └── STORAGE LIMIT NN ┬───────────┬──┘ │ │ └─ PERCENT ─┘ │ └─ SHAred CAche ─┬─ cache-name ─┬─────────────────────────────────────┘ └─ NO ◄────────┘
Parameters
  • broadcast-parms
    Indicates to execute the DCMT command on all or a list of data sharing group members.
    For more information about broadcasting and
    broadcast-parms
    syntax, see How to Broadcast System Tasks.
  • File
    Identifies a specific file.
    • segment-name
      The segment associated with the file.
    • file-name
      The name of the file.
    • SYSTRK-file-name
      The name of the SYSTRK file.
  • OPen
    Opens the file in read-only mode.
    If the file is open in read/write mode, DC/UCF closes the file and reopens it in read-only mode.
    Note:
    SYSTRK files are always opened in read-write mode.
  • OPen Update
    Opens the file in read/write mode.
    If the file is open in read-only mode, DC/UCF closes the file and reopens it in read/write mode.
  • Close
    Closes the file.
  • ACtive
    Enables access to the file and clears its status. If the file is not open, it is opened the next time it is accessed. Varying the file active allows suspended transactions that are waiting on the file to resume execution.
    If this is a SYSTRK file, its mirror status is changed to active or activating. Before an activating mirror becomes active, its contents are brought up-to-date.
  • Inactive
    Disables access to the file and sets its status to 9999 if this is a database file. The ability to vary database files inactive is provided to simulate I/O errors for the purpose of testing recovery procedures.
    If this is a SYSTRK file, its mirror status is changed to inactive. If this is the last active mirror, change tracking is inactivated.
  • ALlocate
    (z/OS and z/VM systems only) Allocates the file dynamically, using its currently assigned data set name and other options specified on its definition.
  • DEallocate
    (z/OS and z/VM systems only) Dynamically deallocates the named file making it unavailable to CA IDMS.
    • Force
      Directs DC/UCF to set the status of the file as deallocated and closed, even though it has not been closed.
  • DAtaspace No/Yes
    Closes the file, then switches to either a data space file (Yes) or to a non-data space file (No), and then re-opens it.
    Note:
    This VARY type is not supported for SYSTRK files.
  • DSname
    new-dataset-name
    Changes the data set name of a database file in the runtime DMCL to
    new-dataset-name
    . If the file has not been opened, then only the DSname is changed. If the file has previously been opened, then the DSname is changed, and the DDname is cleared to blanks.
    Data set names of SYSTRK files cannot be changed.
  • DISp Old/Shr
    Changes the disposition in the FCB (DMCL) for the file.
    Note:
    This VARY type is not supported for SYSTRK files.
  • PRefetch ON/OFF
    Enables or disables prefetch processing for the named file.
    Note:
    This VARY type is not supported for SYSTRK and VSAM files.
  • MEMORY CACHE
    Specifies whether or not to cache the file in memory. This option applies to all files in the area.
    • NO
        Specifies not to cache the file in memory.
      Note:
      This is the default for SYSTRK files and cannot be changed.
    • YES
        Specifies to limit the amount of 64-bit storage allocated for a given file to a percentage of a total file size, instead of allocating storage for the entire file.
      • STORAGE LIMIT NN PERCENT
        Specifies, in percentage, how much of the area's file to cache in memory.
        Limit:
        0 through 100
        • The value zero or 100 specifies to cache the entire file in memory
        • The values 1 to 99 specify to limit the amount of 64-bit storage allocated for a given file to a percentage of a total file size, instead of allocating storage for the entire file.
  • SHAred CAche
    Specifies the name or status of shared cache to which the file is assigned. The valid values are the following:
    • cache-name
      Specifies the name of a shared cache to which the file is assigned.
    • NO
      Specifies that the file is not to participate in a shared cache, even if another CV has the shared cache option enabled for this file. NO is the default.
      Note:
      This is the default for SYSTRK files and cannot be changed.
Usage
Changing the Status of a File
The OPEN, OPEN UPDATE, and CLOSE options allow a DBA to maintain the system at a file level. For example, you use the CLOSE option before you deallocate a file to fix problems associated with it. Within a multi-file area, the OPEN and OPEN UPDATE options let you keep specific files available, while others remain closed. If CA IDMS requires the closed file, it overrides your request as described below.
These functions cannot be performed against native VSAM files using the DCMT VARY FILE command. To accomplish these actions, use the corresponding options of the DCMT VARY AREA command.
DC/UCF Override
If you have not varied the area associated with a file offline, CA IDMS always overrides the file status requested in the DCMT VARY FILE command. For example, if CA IDMS needs to read and write to the file (OPEN UPDATE file status), it overrides your read-only (OPEN file status) request.
Dynamic File Allocation and Deallocation
With the ALLOCATE option, you can bring a new file online without recycling your DC/UCF system. Likewise, the DEALLOCATE option is useful when you need to bring a closed file offline; for example, due to a problem on the disk pack
Forcing Deallocation of Files
The DEALLOCATE FORCE option marks files closed and deallocated without actually closing or deallocating them. This allows you to reallocate the file with a different data set name. You may need to do this, for example, if there is physical damage to the channel. Then, you have to CANCEL the system, because normal shutdown cannot be executed.
Changing the Data Set Name of a File
The ability to change the data set name of a file through a DCMT VARY FILE command is provided for emergency situations only, such as, when a data set is physically damaged and cannot be recovered using its original name. Data set name changes made through a DCMT VARY FILE command are temporary and are not preserved after a normal shutdown. Furthermore, they introduce the potential for incorrect recovery during warmstart unless change tracking is active or appropriate changes are made to the execution JCL of the system to ensure that the correct data set is referenced.
To make permanent changes to the data set name of a file, change its definition in the dictionary and use a DCMT VARY DMCL command to make the change effective within a DC/UCF system.
To change a data set name through a DCMT VARY FILE command, the following conditions must be met:
  • The file must have encountered an I/O error, been varied inactive or its area must be varied offline using a DCMT VARY AREA or SEGMENT command.
  • The file must be deallocated, using the FORCE option if necessary.
  • If change tracking is in use, it must either be active or disabled.
Changing the Shared Cache for a File
In order to change or remove the shared cache assignment for a file, all
shared
areas associated with the file must have a status of OFFLINE or TRANSIENT RETRIEVAL
Changing the shared cache for a file affects only the system on which the command is issued. To change the shared cache for all systems that are accessing the file, the command must be issued on each of those systems. In a data sharing environment, the command can be broadcast to all members of the group.
If any area associated with the file is shared, the new shared cache takes effect only if all shared areas associated with the file have a status of OFFLINE or TRANSIENT RETRIEVAL in all group members. This is because the cache name for a file associated with a shared area (other than one in transient retrieval), is determined by the first sharing system to open the file. All systems that subsequently open the file will use the shared cache specified by the first system.
Optimizing 64-bit Memory Cache Storage
You can cache more files within a given amount of 64-bit storage by specifying a percentage of a file to be cached, instead of the whole file. When no file limit is specified, storage to hold every page in the file is allocated and every cached page is read. When a file limit is specified as a percentage of the file size, only the last N pages read are cached, where N is the number of pages that fit in the specified limit after allowing for overhead. When the cache is full, the oldest page in the cache is replaced by the newest page. For more information, see DMCL Statement.
Examples
DCMT VARY FILE file-id OPEN
V FILE DBCR.BRANCHA OPEN -------- Data File -------- Mode Stat Pg-Size Fl-Type M-Cache S-Cache DD-Name DBCR.BRANCHA Ret 0 4000 non-VSAM No No BRANCHA Pre-fetch: Not-Allowed (DMCL) Pages per Track 12 VOLSER: RIG006 DSname: (DMCL).. DBDC.SYSTEMXX.DBCRBRAA.X DISP=SHR ---------- Area ----------- Lock Lo-Page Hi-Page #Ret #Upd #Tret #Ntfy DBCR.BRNCHTEL Ofl 680001 685012 0 0 0 0 Stamp: 2005-09-02-09.17.48.206640 Pgrp: 15 Share NoICVI NoPerm
DCMT VARY FILE file-id OPEN UPDATE
VARY FILE DBCR.BRANCHA OPEN UPDATE -------- Data File -------- Mode Stat Pg-Size Fl-Type M-Cache S-Cache DD-Name DBCR.BRANCHA Upd 0 4000 non-VSAM No No BRANCHA Pre-fetch: Not-Allowed (DMCL) Pages per Track 12 VOLSER: RIG006 DSname: (DMCL).. DBDC.SYSTEMXX.DBCRBRAA.X DISP=SHR ---------- Area ----------- Lock Lo-Page Hi-Page #Ret #Upd #Tret #Ntfy DBCR.BRNCHTEL Ofl 680001 685012 0 0 0 0 Stamp: 2005-09-02-09.17.48.206640 Pgrp: 15 Share NoICVI NoPerm
DCMT VARY FILE file-id DEALLOCATE FORCE
V FILE DBCR.BRANCHA DEALLOCATE FORCE DBCR.BRANCHA File Forced Closed. Must Re-Allocate with DSNAME -------- Data File -------- Mode Stat Pg-Size Fl-Type M-Cache S-Cache DD-Name DBCR.BRANCHA Clos 0 4000 non-VSAM No No Null Pre-fetch: Not-Allowed (DMCL) Pages per Track 12 UNALLOCATED DSname: (DMCL).. DBDC.SYSTEMXX.DBCRBRAA.X DISP=SHR DSname: (DCMT).. NULL DISP=SHR ---------- Area ----------- Lock Lo-Page Hi-Page #Ret #Upd #Tret #Ntfy DBCR.BRNCHTEL Ofl 680001 685012 0 0 0 0 Stamp: 2005-09-02-09.17.48.206640 Pgrp: 15 Share NoICVI NoPerm