CREATE LOCK

Read syntax diagramSkip visual syntax diagram CREate LOCk fn*ft*diridfnftbfsidSHAreEXClusiveUPDateSESsionLASting(NOType(TYPeSTACKFIFOLIFOFIFOLIFONOType)

Authorization

General User for SFS files and directories. A file pool administrator may enter this command for byte file system (BFS) files.

Purpose

Use the CREATE LOCK command to create an explicit lock on an SFS file or directory, or a BFS regular file. An explicit lock limits or prevents access to a directory or file. Use QUERY LOCK to display lock information.

Operands

fn ft
specifies the name of the file to be locked. You must have authority to read from or write to the file to lock it, depending on the type of lock you choose to create. Special characters (* or %) can be used to designate a set of files, providing you have appropriate authority for the directory specified by dirid. For file control directories, you need read or write authority on the directory. For directory control directories, you need DIRREAD or DIRWRITE authority on the directory.

For more information specifying the dirid, see Naming Shared File System (SFS) Directories. For more information on using special characters to do pattern matching, see Using Pattern Matching to Specify Sets of Files.

dirid
identifies the directory. If fn and ft are specified, this is the directory that contains the file to be locked. If fn and ft are not specified, this is the name of the directory to be locked. You can also use a file mode for the dirid if the directory is already accessed. For more information specifying the dirid, see Naming Shared File System (SFS) Directories.
bfsid
identifies the byte file system (BFS).

For a BFS file, fn and ft are system-generated values that together uniquely identify the file within the BFS.

SHAre
specifies others may read while you read it. You must have read authority to use the SHARE operand. This operand applies only to directories with the file control attribute and the files that reside within them.

BFSregular files may not be locked SHARE.

EXClusive
prevents other users from modifying or reading regardless of the authority that may have been granted. You must have write authority to the base file or directory to use this operand. This operand applies only to directories with the file control attribute and the files that reside within them.
UPDate
specifies others may read while you read or modify. You must have write authority to use this operand on a file control directory or a file within it. You must have directory control write (DIRWRITE) authority to use this operand on a file within a directory control directory.

If UPDATE is specified for a BFS object, it is treated as if EXCLUSIVE was specified.

SESsion
specifies the lock is automatically removed when your CMS session with the file pool ends. A CMS session ends when any of the following occur:
  • System reset
  • Re-IPL
  • File system server abend
  • Network or APPC/VM failure on the last data link with a file pool
  • Log off

A DELETE LOCK command will remove the lock during the CMS session. This is the default.

LASting
specifies the lock stays in effect until a DELETE LOCK command is issued. The lock remains across CMS sessions.

Options

TYPe
displays the names of the files for which you have created locks.
NOType
specifies file information is not displayed at the terminal. The default is NOTYPE.
STACK FIFO
STACK LIFO
places the output in the console stack rather than displaying it at the terminal. The default is FIFO. Error messages are displayed at the terminal and are not stacked.
FIFO
specifies the output is stacked in a first in, first out order. This option is equivalent to STACK FIFO.
LIFO
specifies the output is stacked in a last in, first out order. This option is equivalent to STACK LIFO.

Usage Notes

Applicable to both the shared file system (SFS) and byte file system (BFS)

  1. If another user has an UPDATE or EXCLUSIVE lock on a file or directory, you cannot create a lock on the same file or directory. Multiple SHARE locks are allowed. If you have a lock on a file or directory, you must delete the lock before creating another lock on it. For more information, see the DELETE LOCK.
  2. When you use a batch facility that—unlike CMSBATCH—runs the job under your user ID:
    • Even if you have an EXCLUSIVE lock on a file, your job running in the batch machine can use the file.
    • If your batch machine has a file open to update it, any job running from your own virtual machine cannot update the file.
  3. For more information on how the FILEWAIT setting affects the CREATE LOCK command, see the SET FILEWAIT.
  4. If the CREATE LOCK command is issued from an exec or assembler program for a file pool that is active on the specified work unit, the command will fail.
  5. You can invoke the CREATE LOCK command from the command line, from an exec, or as a function from a program. No error messages are issued if CREATE LOCK is invoked:
    • As a function from a program
    • From a CMS exec file that has the &CONTROL NOMSG option in effect
    • From an EXEC2 exec where CMDCALL is not in effect
    • From a REXX exec with ADDRESS COMMAND in effect
  6. Locking a file or directory, in any lock mode, does not prevent DFSMS/VM from migrating or recalling files.
  7. Locking a file or directory EXCLUSIVE or UPDATE prevents anyone other than the holder of the lock from deleting that file, or files, in that directory, while locking SHARE prevents anyone from deleting that file, or files, in that directory.
  8. For examples on using the CREATE LOCK command, see z/VM: CMS User's Guide.

Applicable to only the shared file system (SFS)

  1. Locks are not created in the directory for:
    • Subdirectories
    • Erased or revoked aliases
    • Aliases whose base files reside in directory control directories
    • External objects
    • Files you are not authorized to read or write

    If special characters are used to specify the file name or file type, or both, processing continues for the remaining file IDs that match the specified pattern.

  2. When you CREATE LOCK on a alias, it is the base file that determines whether the CREATE LOCK command will succeed.
  3. Only UPDATE locks can be created on files in directory control directories.
  4. You can lock a file in a directory control directory that is accessed R/O if no one has the directory accessed R/W or has the file locked.
  5. For file control directories and files within, existing locks can affect whether you can create a lock on a file or directory:
    • You can always lock a directory that contains locked files if you hold the locks, unless you are trying to lock the directory SHARE and you have one or more files locked UPDATE or EXCLUSIVE. If another user has files locked, you cannot lock the directory, unless the locks are all SHARE and you are trying to lock the directory SHARE or UPDATE.
    • You can always lock files in a locked directory if you hold the lock, unless you are trying to lock the files UPDATE or EXCLUSIVE and you have the directory locked SHARE. If another user has the directory locked, you can cannot lock files in that directory, unless the directory is locked SHARE or UPDATE and you are trying to lock the files SHARE.
  6. If you create an EXCLUSIVE lock on a file control directory and another user already has the directory accessed, their access to the directory remains in effect. Even if the user releases the directory, they will be able to reaccess it until they re-IPL or their connection to the file pool is broken.
  7. You can lock a directory control directory if no one, including you, has it accessed R/W, no one else has it or a file in it locked, and you do not have it accessed R/O.

Applicable to only the byte file system (BFS)

  1. Locks are created in the directory only for BFS regular files. Locks are not created for links, subdirectories, or special files.
  2. CREATE LOCK may be used to create an explicit lock on a byte file system file. However, the CMS short file name format of the file name must be used. You may not enter the CREATE LOCK command using the fully qualified byte file system (BFS) path name.
  3. A BFS top directory cannot be locked. If a CREATE LOCK is attempted on a BFS top directory, the command will fail.
  4. A BFS file space can be locked with the FILEPOOL DISABLE FILESPACE command.
  5. You must have file pool administration authority to lock a byte file system file.
  6. If a BFS object is in use by an OPENVM user, it affects whether you can create a lock. A file cannot be locked if it is in use by an OPENVM user because BFS files may not be locked SHARE.
  7. An EXCLUSIVE lock creates a busy file condition.

Messages and Return Codes

  • DMS002E File fn ft fm│dirname not found [RC=28]
  • DMS069E Filemode mode not accessed [RC=36]
  • DMS109S Virtual storage capacity exceeded [RC=104]
  • DMS1132E Invalid number of operands [RC=24]
  • DMS1163E The CREATE LOCK command failed for fn ft fm│dirname [RC=nn]
  • DMS1184E Directory dirname not found or you are not authorized for it [RC=28]
  • DMS1184E File fn ft or directory dirname not found or you are not authorized for it [RC=28]
  • DMS1184E File fn ft fm not found or you do not have write authority to it [RC=28]
  • DMS1184E Directory dirname not found or you do not have write authority to it [RC=28]
  • DMS1187E Too many subdirectory levels in dirname [RC=24]
  • DMS1188E Filemode mode is not associated with a directory [RC=74]
  • DMS1212E You have opened a file pool catalog for WRITE on work unit workunitid for file pool filepoolid.
  • DMS1214E You have already created a lock of type {EXCLUSIVE│SHARE│UPDATE} on file fn ft dirname│fm [RC=28]
  • DMS1214E You have already created a lock of type {EXCLUSIVE│SHARE│UPDATE} on directory dirname [RC=28]
  • DMS1215E A lock of type {EXCLUSIVE│SHARE│UPDATE} on file fn ft dirname│fm was already created by another user [RC=28]
  • DMS1215E A lock of type {EXCLUSIVE│SHARE│UPDATE} on directory dirname was already created by another user [RC=28]
  • DMS1223E There is no default file pool currently defined [RC=40]
  • DMS1291E There are no unused work units available [RC=88]
  • DMS2040E CREATE LOCK SHARE [or EXCLUSIVE] cannot be performed on [file filename filetype which is associated with] {a directory control directory|a BFS file.} [RC=24]
  • DMS2133E fn ft bfsid is not a BFS regular file. You cannot create a lock for it. [RC=24]

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

Reason Location
Errors in command syntax Command Syntax Error Messages
Errors in the Shared File System File Pool Server Messages