ACCESS

Authorization

General User

Purpose

Operands

0191

topdirectory

If you issue ACCESS without any operands, the 0191 disk or top directory is accessed as file mode A. If both the 0191 disk and top directory exist, the top directory will be the one to be accessed as file mode A.

dirid

identifies the SFS directory to be accessed. For this command you cannot use the fm format of dirid. For a more information on dirid, see Naming Shared File System (SFS) Directories.

fm

assigns a one-character file mode letter to all files on the minidisk

/ext

indicates the file mode of the parent minidisk or SFS directory. Files on the minidisk (vdev) or directory (dirid) being accessed are logically associated with files on the parent minidisk or directory. The minidisk or directory is considered a read-only extension. A parent minidisk or directory must be accessed in the search order before the extension. A blank must not precede or follow the slash.

vdev

makes available the minidisk at the specified virtual device number. The valid numbers are X'0001' through X'FFFF'.

fn

ft

fm

define a subset of the files on the specified minidisk. Only the specified files are included in the user file directory and only those files can be read. An asterisk coded in any of these fields indicates all file names, file types, or file mode numbers (except 0) are to be included. For more information, see Usage Notes 2 and 3, Using the ACCESS command with vdev. To specify a file mode, use a letter and a number, for example:

B1

The allowable file mode numbers are 0 to 6. For more information about file mode 0 files see, Usage Note 3, Using the ACCESS Command with vdev.

For more information about OS and DOS disk access restrictions, see Usage Note 8, Using the ACCESS Command with vdev.

Options

NOPROF

suppresses execution of a PROFILE EXEC file. This option is valid only if the ACCESS command is the first command entered after you IPL CMS. Only the minidisk or directory at file mode A and the system disk (file mode S) with its associated extensions are accessed. On any ACCESS commands issued after you have IPLed CMS, the PROFILE EXEC is not executed and the NOPROF option is ignored.

FORCERO

forces the SFS directory to be accessed in read-only status. You do not need authority to the files in the directory, just to the directory itself. For a file control directory, you need either READ or WRITE authority. For a directory control directory, you need DIRREAD authority.

FORCERW

forces the SFS directory to be accessed in read/write status. You can specify FORCERW even if you have only read authority to the directory. For directories with the (DIRCONTROL) attribute, directory control write (DIRWRITE) authority is required. This option is not valid for SFS directories accessed as extensions to another file mode.

ERASE

indicates you want to erase all the files on the specified minidisk. This option is only valid for read/write disks. If the minidisk is read-only, you will receive the following message: DMS003E Invalid option: ERASE. For more information, see Usage Note 6, Using the ACCESS Command with vdev.

SAVEONLY

accesses the minidisk if a saved copy of the file directory information is available in a saved segment. If it is not available, the minidisk is not accessed.

NOSAVE

accesses the minidisk and places the file directory information in your virtual machine. A saved copy of the file directory information in a saved segment is not used.

NODISK

lets you gain access to the CMS operating system with no minidisks accessed by CMS except the system disk (file mode S) and its extensions. This option is only valid if the ACCESS command is the first command you enter after you IPL CMS.

MODE0

accesses the minidisk and includes file mode 0 files. This option is meaningful only to minidisks linked read-only. The ACCESSM0 command must be set to ON before you can use the MODE0 option of the ACCESS command.

Usage Notes

Using the ACCESS Command with a Directory ID or a Device Number

1. When you IPL CMS, if you have a default file pool defined in your z/VM® directory, or if you define it when you IPL CMS, your top directory in that file pool is accessed as file mode A. If no file pool is defined and you have a defined disk number of 0191 in your z/VM directory, or you define it before you IPL CMS, your 0191 disk is accessed as A. If you do not have either a top directory in the default file pool or a 0191 disk defined, nothing is accessed as file mode A.

   Issuing ACCESS without any parameters or options accesses your top directory or 0191 disk in the same manner.

2. If you have defined disk numbers 190 and 19E in the z/VM directory, or if they are defined before you IPL CMS, these disks are accessed as file mode S and Y respectively. If you have a minidisk defined as virtual device number 192, it may be automatically accessed as D when you IPL CMS:
   • If 192 is an unformatted temporary minidisk or virtual disk in storage, CMS formats it and accesses it as file mode D.
   • If 192 is a CP-formatted temporary minidisk or virtual disk in storage, CMS reformats it for CMS and accesses it as file mode D.
   • If 192 is a CMS-formatted temporary minidisk, virtual disk in storage, or permanent minidisk accessed as a file mode other than D, CMS reaccesses it as file mode D.
   • If 192 is an unformatted or CP-formatted permanent minidisk, CMS does not automatically format, reformat, access, or reaccess it.

   When CMS accesses 190 as S, 19E as Y, or 192 as D, any minidisk or SFS directory already accessed as that file mode is released.

   Following an IPL of CMS, you must issue explicit ACCESS commands to access other minidisks or directories. Ordinarily, you have access only to files with a file mode number of 2 on the system disk, or file mode S.

   Note: You cannot specify a file mode of S with the ACCESS command. When ACCESS is the first command issued after an IPL of the CMS system, a disk or SFS directory is not automatically defined as file mode A. You must issue another ACCESS command to define a minidisk or directory as file mode A.
3. If you enter the ACCESS command and any associated operands or options at the VM READ after you IPL CMS, it must be entered in American English; you cannot use any other national language.
4. You can force a read/write minidisk or SFS directory into read-only status by accessing it as an extension of another minidisk, directory, or of itself; for example:

   access 0191 a/a

   forces your 0191 disk into read-only status.

   Note: Having a directory in read-only status does not restrict all writing to the directory or files. Use the CREATE LOCK command to protect SFS files and directories.
5. When a minidisk or SFS directory is made a read-only extension of another minidisk or directory, some commands that allow you to specify a file mode will search extensions of the specified minidisk or directory. For more information on the read-only extensions, see z/VM: CMS User's Guide.
6. When you access a minidisk, a list of the files on the minidisk is stored in your virtual machine. For shared minidisks, if another user updates a file on the minidisk, the minidisk's file directory is updated, but the list of files in your storage is not. You must reaccess the minidisk to get the current list of files.

   That is, when another user creates, erases, or updates files on the minidisk, the minidisk's file directory is updated to reflect the current status of the minidisk, but copies in other users' storage is not updated to reflect the changes. Users that have the minidisk accessed read-only, must re-access the minidisk to see any changes. Thus, if you have a minidisk accessed read-only while another user is writing to a file, you may need to periodically reenter the ACCESS command for the minidisk to obtain a fresh copy of the file. You will see the updates to the file up to the last save.

   When you access a file control directory, a list of files is also stored in your virtual machine. Unlike minidisks, however, the list of files is updated automatically for you. There is no need for you to reaccess the directory when users create, erase, or change files.

   When you access a directory control directory, a list of files is sometimes stored in your virtual storage. If you are using an XC virtual machine and the directory is in a data space, CMS puts the list of files in the data space. Regardless of where the list of files is maintained, however, directory control directories work like minidisks. That is, when another user creates, erases, or updates files in the directory, the data in the file pool is updated, but the version of the directory you have accessed is not. You must reaccess the directory to see any changes.

7. If you have many directories or minidisks accessed and you are experiencing poor response time, release the ones you are not using. For more information, see RELEASE.
8. If you are accessing minidisks and SFS directories that contain many files or you are accessing many minidisks or SFS directories, you may get a virtual storage exceeded error. This is because a list of files is stored in your virtual machine.

   You can increase the storage of your virtual machine and re-ipl. If the problem still occurs, you must free some virtual storage.

   1. Release some minidisks or SFS directories that are no longer needed.
   2. Reorganize the files. Break up a minidisk or SFS directory with a large number of files into multiple minidisks and directories.
   3. Reduce the number of files.
9. When a directory control directory is accessed (read-only) more than once without first releasing it, all nested accesses must be released before committed changes become available to the user (upon next access).
10. You cannot use the ACCESS command to access minidisks formatted in 800-byte blocks.
11. Because the CMS file system requires file status and control information to reside below 16 MB in virtual storage, there is a practical limitation on the size of CMS minidisks. As a minidisk increases in size, or more files reside on the disk, the amount of virtual storage associated with the disk for CMS file system status and control increases in storage below 16 MB. The current ECKD DASD limitation is 65520 cylinders for a 3390 disk on an IBM TotalStorage DASD subsystem, or about 45 GB of data. The maximum size for FBA SCSI disks supported for use by CMS or GCS is 381 GB. IBM suggests that customers defining disks for use by CMS should set a practical limit of about 22 GB. If larger disks are defined, they should be limited to contain very few files, or the CMS file system may not be able to obtain enough virtual storage below 16 MB to format or access those disks.

Using the ACCESS Command with a Directory ID

1. When you access an SFS directory without forcing the status to read-only or read/write, the status is determined by who owns it.
   • If you are the directory owner, it is accessed as read/write. For directory control directories, however, only one user can have the directory accessed in read/write status. If someone already has the directory accessed in read/write status, and you (the directory owner) attempt to get a read/write access, you will, instead, get a read-only access.
   • If you are not the directory owner, the directory is accessed as read-only.
   • If you attempt to access a directory for which you are not authorized, the directory is not accessed.
2. To force a directory you own to be accessed in read-only status, you can either:
   • Access the directory as an extension of another minidisk, directory, or of itself. For example:

     access vmsysu:yourid.test a/a

   • Specify the FORCERO option:

     access vmsysu:yourid.test a (forcero

   Any directory you do not own is, by default, accessed in read-only status, even if you have write authority to that directory.

3. When you access an SFS directory in read-only status, you can write to a file in that directory if all the following are true:
   • The directory has the file control attribute.
   • You have WRITE authority to the file.
   • The CMS command you are using to write to the file does not require the directory to be accessed read/write. (CSL routines do not require the directory to be accessed read/write, but many CMS commands do.)

   For more information on the CMS commands that do not require a directory to be accessed R/W, see z/VM: CMS User's Guide.

   You cannot write to a file in a directory control directory if you have that directory accessed in read-only status. The attempts will fail even if you own the directory or if you have directory control write (DIRWRITE) authority to it.

   To write to file in a directory control directory, access the directory in read/write status. You can also write to files by not accessing the directory and, instead, using CMS commands or Callable Services Library (CSL) routines that let you specify a directory name.

4. If you are not the directory owner, but have some authority to the directory, you may be able to force the directory into read/write status. For file control directories, you can force any directory into read/write status so long as you have write or read authority to that directory. For directory control directories, you must have directory control write (DIRWRITE) authority to force the directory into read/write status. Directory control directories also have the restriction that only one user at a time may have the directory accessed in read/write status. So, you may not always be able to force a directory control directory into read/write status, even if you are properly authorized.
   To force a directory into read/write status, use the FORCERW option:

   access vmsysu:dave.notes b (forcerw

   You cannot specify FORCERW if you are accessing the directory as an extension of some other file mode.

5. If you force a file control directory into read/write status you can use commands that require a read/write file mode. Of course, you must have proper authority for the files you use.
   Suppose, for example, you have write authority to the PROJECT NOTEBOOK file in the VMSYSU:MINDY.SERVICE directory. You want to use EXECIO to write to the file, which requires a read/write file mode. However, you have only read authority to the directory. You can access Mindy's directory in read/write status using the FORCERW option:

   access vmsysu:mindy.service b (forcerw

   Now you can write to the PROJECT NOTEBOOK file. Because the file exists and you have write authority, almost any command that writes to it will succeed. If, however, the command internally creates a temporary file, it will fail because you do not have write authority to the directory. You will see messages similar to these:

   DMS105S Error nn writing file fn ft fm on disk or directory
   DMS1258E You are not authorized to write to file fn ft fm

   Any command that tries to create a new file in the directory will fail for the same reason.

   Applications or execs may also fail for similar reasons. Many applications try to create new files or temporary files on read/write file modes. These applications will fail if you have only read authority to the directory.

6. If you have write authority to another user's directory and specify FORCERW, your applications or commands may conflict with those of other authorized users.

   Suppose, for example, you use FORCERW to access a directory owned by user DAVE. Dave has granted you write authority on his directory. Now suppose you run an application that creates a work file in Dave's directory. Meanwhile, Dave runs the same application using the same directory. Dave's application will see the work file you created, but replaces it anyway because it is only a work file. Your application continues execution and now reads the work file which, of course, contains the wrong data. Or, if the application erases the work file instead of replacing its contents, your authorization to the file will be lost when Dave runs the application. In either case, you get undesired results. So, be careful when using FORCERW -it is intended for special use.

7. If a file control directory is locked EXCLUSIVE, only the holder of the lock can access the directory. If a file control directory is locked SHARE or UPDATE, any authorized user can access the directory.
8. You can access a file control directory in read-only mode even if it has no files in it. You cannot access a directory control directory in read-only mode if it does not contain files or subdirectories.

Using the ACCESS Command with DIRCONTROL Directories

This section contains notes that apply only to SFS directories with the directory control attribute. Use the QUERY DIRATTR command to determine whether the directory attribute is FILECONTROL or DIRCONTROL.

1. To access a directory with the DIRCONTROL attribute, you must have directory control read (DIRREAD) or directory control write (DIRWRITE) authority, depending on the mode of access. Users who create (own) directory control directories automatically have DIRREAD and DIRWRITE authority for those directories. File pool administrators have implicit DIRREAD and DIRWRITE authority to every directory control directory in the file pool.

   A directory accessed with the DIRCONTROL attribute has unique functional characteristics. These characteristics are described in the CREATE DIRECTORY command.

   Some of these special characteristics involve the ACCESS command itself. The Table 1 shows the specific conditions and results for accessing a directory with the DIRCONTROL attribute.

   Table 1. Accessing a Directory with the Directory Control Attribute

   ACCESS		DIRECTORY CONTROL AUTHORITY
   Force R/O	Force R/W	Owner	Dirread	Dirwrite
   —	—	Directory Control Write (Note a)	Directory Control Read	Directory Control Read
   —	X	Directory Control Write (Note c)	Deny Access	Directory Control Write (Note b)
   X	—	Directory Control Read	Directory Control Read	Directory Control Read

   Notes on the Table:

   1. When the owner accesses a directory control directory without specifying FORCERO or FORCERW, the owner usually gets a read/write access. The owner will get a read-only access in the following cases:
      • The directory is already accessed in read/write mode by another user.
      • The owner or another user has an UPDATE lock on the directory.
      • Another user has an UPDATE lock on a file in the directory.
      Also, if the same user accesses the directory again, the user's prior accesses will be released except when the latest access results in one of these two conditions:

      • The directory is being accessed read-only at more than one file mode (each access is, therefore, for the same version of the directory).
      • The directory is already accessed read/write and the latest access is for read-only at a different file mode (this access results in an error).
   2. When a nonowner accesses a directory control directory using the FORCERW option and someone already had it accessed or open in read/write mode, or locked in UPDATE mode, the request is denied.
   3. When an owner accesses a directory control directory using FORCERW and the directory is already accessed or open in read/write mode, the request is denied.
2. Only one user at a time can have a directory control directory accessed in read/write mode. Attempts to access a directory control directory in read/write status (using the FORCERW option) will fail if the directory is already accessed in read/write mode by another user.

   An attempt to access a directory control directory in read/write mode will also fail if another user has locked a file in the directory. In this case, an attempt to access the directory in read-only mode will succeed.

3. When another user has a directory accessed in read/write mode, you cannot change files in that directory, even if you are authorized to do so.
4. It is possible for a user to write directly to a file in an SFS directory without accessing the directory. (This can be done with Callable Services Library routines in application programs.) If you try to access the directory in read/write mode while someone is directly writing to a file in the directory, your access will wait or be rejected according to the setting of the FILEWAIT option. For more information, see the SET FILEWAIT.
5. You cannot make changes to files or create subdirectories in a directory control directory you have accessed in read-only mode.
6. Once you have a directory control directory accessed in read-only status, you will not see any changes in that directory (including the contents of the files) that are made by other users. To see the changes, you must access the directory again. At that time, you will be able to see any committed changes.

   However, if you are the writer, you do not need to reaccess in order to see the changes. They are always available to you.

   Likewise, if a directory control directory is renamed or relocated while you have it accessed read-only, you must release the directory before you can access it under the new name.

   Exception: When a file has the INPLACE attribute, you see changes as they are written to the file pool. You do not need to wait until the changes are committed, and you do not need to reaccess the directory. For more information about the INPLACE files, see z/VM: CMS Application Development Guide.

Using the ACCESS Command with a Virtual Device Number

1. Associated with each CMS minidisk is a file directory, which contains an entry for every CMS file on the minidisk. Specifying ACCESS without the SAVEONLY or NOSAVE options accesses the minidisk using a saved copy of the file directory that contains entries for only those files you can access. If the saved segment containing the saved copy is not available or is not current, ACCESS creates a file directory in your virtual machine.

   If you use the CP LINK command to link to a new minidisk, issue an ACCESS command each time. Do this so you obtain the appropriate file directory.

2. The fn ft fm fields can only be specified for minidisks accessed as read-only extensions. Also, requesting a subset of files creates a file directory in your virtual machine. For example:

   access 195 b/a * assemble

   gives you read-only access to all the files with a file type of ASSEMBLE on the minidisk at virtual number 195, and the file directory information is stored in your virtual machine. The command:

   access 190 z/a * * z1

   gives you access to all files on the system disk (190) that have a file mode number of 1.

   When you access any minidisk in read-only status, files with a file mode number of 0 are not accessed.

3. You can also identify a set of files on a minidisk by referring to a file name or file type prefix. For example:

   access 192 c/a abc*

   accesses only those files in the minidisk at virtual number 192 whose file names begin with the characters ABC. The command:

   access 192 c/a * a* c2

   gives you access to all files whose file types begin with an A and have a file mode number of 2.
4. Accessing the same minidisk with different file modes affects the type of access. Once a minidisk is accessed using a saved file directory, subsequent ACCESS commands for the same minidisk place the file directory in your virtual machine. For example, the command sequence:

   access 19f g
   access 19f h
   access 19f i

   accesses the minidisk defined at virtual number 19F with a saved file directory for the file mode G minidisk while the minidisks with file mode H and I are accessed with the file directory in your virtual machine.
5. When you have linked to a formatted minidisk as read-only, and it does not contain any files, you cannot access the minidisk. A formatted minidisk linked as read/write can be accessed whether or not it contains files.
6. If you enter the ERASE option by mistake, you can recover from the error as long as you have not yet written any new files onto the minidisk. (That is, you have not yet caused CMS to rewrite the file directory.) Reissue the ACCESS command without the ERASE option.
7. You should never attempt to access a minidisk in read/write status if another user already has it in read/write status; the results are unpredictable.
8. When accessing OS and DOS disks:
   1. You cannot specify file name, file type, and file mode when you access OS or DOS disks, nor can you specify any options.
   2. To see OS and DOS disks, you must have a mode A, if you are going to use the LOAD command with the MAP option. The default option is MAP.
   3. If two or more minidisks have been accessed in CMS, and CP DEFINE commands are executed that swap virtual numbers, a subsequent RELEASE command may write the file directory on the wrong minidisk; for example:

   (CMS)  ACCESS 193 C
   (CMS)  ACCESS 198 E
   (CP)   DEFINE 193 293
   (CP)   DEFINE 198 193
   (CMS)  RELEASE C

   Note: The 193 disk is the MAINT 193 disk.

   This sequence of commands will write the file directory from 193 to 198 because the CP definitions are unknown to CMS.

9. Using the MODE0 Option
   • If MODE0 is specified for a disk accessed read/write, or for a disk accessed read-only that is linked read/write, file mode 0 files will be brought into storage regardless of whether the ACCESSM0 command has been previously set to ON.
   • If you specify MODE0 for a disk accessed read-only that is linked read-only, file mode 0 files will be included only when the MODE0 option has been enabled by previously setting the ACCESSM0 command to ON.
   • Specifying file mode number 0 for ACCESS has the same effect as specifying MODE0. For example:

     access 391 d/d * * d0

     is equivalent to:

     access 391 d/d * * d0 (MODE0

     The same rules that apply for file mode 0 files apply whether the option is specified or implied.
   • If MODE0 is specified and the file mode number (if specified) is not zero, an error will be issued.
   • If MODE0 is specified, nonsaved storage access is performed (that is, the file directory is brought into your virtual storage, and the saved copy of the file directory in a shared segment is not used). This is because saved storage access will not have file mode 0 files saved in the segment.

Responses

DMS723I mode (vdev | dirname) {R/O|R/W} [-OS|-DOS]

This message is displayed if the specified minidisk directory is a read-only CMS minidisk or read-only SFS directory. If the minidisk is in OS or DOS format, the message indicates the format, as well as whether it is a read/write or read-only minidisk.

DMS724I vdev1 | dirname1 replaces mode (vdev2 | dirname2

Before execution of the command, the minidisk represented by vdev2, or the directory represented by dirname2, was accessed as mode. The minidisk vdev1, or directory dirname1 is now assigned that file mode letter.

DMS725I vdev | dirname also = mode [-OS|-DOS] minidisk

The minidisk specified by vdev, or directory specified by dirname, is accessed as mode and an ACCESS command was issued to assign it another file mode letter.

DMS726I vdev | dirname mode released

The minidisk being accessed at virtual number vdev as a read/write minidisk, or the directory dirname, is already accessed at a different mode. It is released from that mode. This message is also displayed when directory control directories are reaccessed.

Messages and Return Codes

• DMS003E Invalid option option [RC=24]
• DMS017E Invalid device address vdev [RC=24]
• DMS048E Invalid filemode mode [RC=24]
• DMS059E vdev | dirname already accessed as read/write filemode fm [RC=36]
• DMS060E File [fn [ ft [fm]]] not found; filemode fm[vdev | dirid] will not be accessed [RC=28]
• DMS066E option1 and option2 are conflicting options [RC=24]
• DMS070E Invalid parameter parameter [RC=24]
• DMS109S Virtual storage capacity exceeded [RC=104]
• DMS112S Disk fm(vdev) device error [RC=100]
• DMS113S fm(vdev) not attached or invalid device address [RC=100]
• DMS114S Device vdev too large for CMS use [RC=100]
• DMS230W O/S disk-fileid and options specified are ignored [RC=4]
• DMS260E Disk not properly formatted for ACCESS [RC=88]
• DMS724I vdev replaces fm (vdev)
• DMS1000E The accessing of file mode 0 files must be enabled by prior use of the ACCESSM0 command RC=24]
• DMS1078E Cannot access saved file directory for this disk [RC=44]
• DMS1153E File pool unavailable [RC=99]
• DMS1184E Directory dirname not found or you are not authorized for it [RC=100]
• DMS1198E {File|Directory} [fn ft] fm|dirname is currently open; it must be closed before it can be accessed. [RC=70]
• DMS1216E Option option is not valid when used for a directory [RC=24]
• DMS1216E Parameter parameter is not valid when used for a file in a directory [RC=24]
• DMS1223E There is no default file pool currently defined [RC=40]
• DMS1233E Invalid use of FORCERO/FORCERW option [RC=24]
• DMS1240E You are not authorized to connect to file pool filepoolid RC=76|31]
• DMS2133E bfsid is a byte file system. It cannot be accessed [RC=24]
• DMS2522E DIRCONTROL directory dirid2 is already accessed using previous directory name dirid1 [RC=36]

Additional system messages may be issued by this command. The reasons for these messages and their location are: