Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

SHOW-FILE-LOCKS

&pagelevel(3)&pagelevel

Show locks on files

Component:

BS2000

Functional area:

File processing

Domain:

FILE

Privileges:

STD-PROCESSING
TSOS

Function

The SHOW-FILE-LOCKS command provides the file owner and any users who have access authorization with information about the locks currently in force on a file. This helps the user to diagnose processing problems which are due to the presence of a file lock.
The file locks shown are those which have the following causes:

  • The file is currently open.

  • The file has been explicitly reserved with the SECURE-RESOURCE-ALLOCATION command.

  • A lock has been imposed to enable the file to be printed. A lock on a file which is to be printed can be placed explicitly in a PRINT-DOCUMENT command (LOCK-FILE=*YES) or in a PRNT macro. A file lock can also be imposed by making YES the default value of LOCK-FILE in the SPOOL parameter file.
    Similarly, the WRITE-DISKETTE command or the PNCH macro can be used to impose a lock on a file to enable it to be written to a floppy disk.
    A file which is in the process of being output to printer or floppy disk is in any case locked until the output process has been completed.

  • The file has been reserved for a file transfer (see the TRANSFER-FILE command).

  • The file is a SYSLST file which is waiting to be printed following job completion.

  • The file is currently being processed by a Concurrent Copy job.

  • The file is the source file for a batch job which is still waiting in the queue.

  • A temporary connection failure in a computer network or a system error in the local system make it impossible to reset the file lock.

File locks which are in force on the basis of the file’s catalog entry are not shown (see the CREATE-FILE or MODIFY-FILE-ATTRIBUTES command). Locks of this type are shown by the SHOW-CE-LOCK command.

The command supports structured output in S variables (see "Output in S variables").

Privileged functions

Systems support (TSOS privilege) has the same access rights as the file owner (user group OWNER) and thus can request information about file locks on any files. 

Format

SHOW-FILE-LOCKS                                                                                                                                    

FILE-NAME = <filename 1..54>

Operands

FILE-NAME = <filename 1..54>
Name of the file for which lock information is required.

Return codes

(SC2)

SC1

Maincode

Meaning


0

CMD0001

Command successfully executed

2

0

DMS13EE

File is not locked


1

CMD0221

Syntax error in command


32

DMS13EA

Internal system error


64

CMD2203

Error in syntax file


64

DMS0301

Catalog not available


64

DMS13EB

RFA connections not supported


64

DMS13EC

Output in S variables not possible


64

DMS13ED

Output to SYSOUT not possible


64

DMS13EF

Metadata cannot be accessed


64

DMS13E1

File access denied


64

DMS13E2

No access permission for associated pubset


64

DMS13E3

User ID does not exist


128

DMS13E0

Resource bottleneck

Output format

A table is displayed for the specified file, showing the locks it is subject to on the system. The output starts with a line showing the command name (SHOW-FILE-LOCKS) and the date and time of output, followed by a second line showing the file’s path name. Then comes a table comprising up to 20 rows of values for up to 20 locks. The total number of locks present is indicated in a totals line at the end of the table.

The locks in force on a file can all be allocated to one of the following types:

  • locks held by a job

  • locks held by a system component

  • locks held by the FT subsystem

Layout for locks held by jobs

Jobs which have caused a lock are shown. Further information on these jobs can be found by specifying the associated TSN in a SHOW-JOB-STATUS command.

SHOW-FILE-LOCKS                       Date: yyyy-mm-dd, Time: hh:mm:ss
File name:  <filename 1..54>
----------------------------------------------------------------------
Locks identified by TSN:
 TSN    Job name   User ID    Job type Lock type   Host name  XCS name
 @@@@   @@@@@@@@   @@@@@@@@   @@@@@@   @@@@@@@     @@@@@@@@   @@@@@@@@
 @@@@   @@@@@@@@   @@@@@@@@   @@@@@@   @@@@@@@     @@@@@@@@   @@@@@@@@
  .       .          .          .        .           .          .
  .       .          .          .        .           .          .
  .       .          .          .        .           .          .
 @@@@   @@@@@@@@   @@@@@@@@   @@@@@@   @@@@@@@     @@@@@@@@   @@@@@@@@
----------------------------------------------------------------------
Total number of locks is:  ####
----------------------------------------------------------------------
SHOW-FILE-LOCKS                                         End of display
Layout for locks held by system components

The locks which are shown were caused by the EAM or Concurrent Copy system component. These locks cannot be associated with a job (TSN).

SHOW-FILE-LOCKS                       Date: yyyy-mm-dd, Time: hh:mm:ss
File name:  <filename 1..54>
----------------------------------------------------------------------
Locks hold by system program:
 Identifier                            Lock type   Host name  XCS name
 @@@@@@@@@@@                           @@@@@@@     @@@@@@@@   @@@@@@@@
 @@@@@@@@@@@                           @@@@@@@     @@@@@@@@   @@@@@@@@
   .                                     .           .          .
   .                                     .           .          .
   .                                     .           .          .
 @@@@@@@@@@@                           @@@@@@@     @@@@@@@@   @@@@@@@@
----------------------------------------------------------------------
Total number of locks is:  ####
----------------------------------------------------------------------
SHOW-FILE-LOCKS                                         End of display

Layout for locks held by the FT subsystem

The locks which are shown were imposed by the FT (File Transfer) subsystem. These locks cannot be associated with a job (TSN). Further information on the file transfer requests responsible can be found by specifying the associated file transfer ID in a SHOW-FILE-TRANSFER command.

SHOW-FILE-LOCKS                       Date: yyyy-mm-dd, Time: hh:mm:ss
File name:  <filename 1..54>
----------------------------------------------------------------------
Locks identified by File Transfer ID:
 Transfer ID                           Lock type   Host name  XCS name
 ###########                           @@@@@@@     @@@@@@@@   @@@@@@@@
 ###########                           @@@@@@@     @@@@@@@@   @@@@@@@@
   .                                     .           .          .
   .                                     .           .          .
   .                                     .           .          .
 ###########                           @@@@@@@     @@@@@@@@   @@@@@@@@
----------------------------------------------------------------------
Total number of locks is:  ####
----------------------------------------------------------------------
SHOW-FILE-LOCKS                                         End of display
Key to the output columns

Output column

Possible values

Meaning

TSN

<alphanum-name 1..4>

Task sequence number

Job name

<name 1..8>

Job name

*NONE

Job name not known

User ID

<name 1..8>

Job user ID

*UNKNOWN

Job user ID not known

Job type


Job type to which the lock can be allocated:

DIALOG

Interactive job

BATCH

Batch job

HOLD

Batch job suspended by /HOLD-TASK

ENTER

Type 1 batch job waiting in queue. The lock only
affects the source file.

SPOOL

Spoolout job

SYSTEM

System job

UNDEF

Unidentifiable job type 

Lock type














Type of file lock:

INPUT

Lock on opening the file for reading

OUTPUT

Lock on opening the file for writing

INPUT-Y

Lock on opening the file for reading with SHARED-UPDATE=*YES

INOUT-Y

Lock on opening the file for writing with SHARED-UPDATE=*YES

INPUT-W

Lock on opening the file for reading with SHARED-UPDATE=*WEAK

INOUT-W

Lock on opening the file for writing with SHARED-UPDATE=*WEAK

SECURE

Lock imposed by SECURE-RESOURCE-ALLOCATION command

RES-INPUT

Lock on file modification

MIGRATE

Lock in force while the file is being migrated by the HSMS subsystem

EXCLUSIVE

Lock on all access

BACKUP

Lock while Concurrent Copy backup is in progress

RESERVE

File reserved for specific application

Host name


System the job is running on:

<alphanum-name 1..8>

MSCF name of the host

*OWN

Local host

*UNKNOWN

Host name not known

XCS name


Indicates that the host is connected to a cross-coupled system

<alphanum-name 1..8>

Name of the cross-coupled system

*NONE

Not connected

*UNKNOWN

Name of cross-coupled system not known

Table 115: Output columns of the SHOW-FILE-LOCKS command


Output in S variables

The output scope varies depending on the type of lock: lock set by a job TSN (TSN lock), lock set by system component (SYS lock) or lock set for file transfer (FT lock).

Output information

Name of the S variable

T

Contents          

Condition

MSCF name of the processor on which the FT job specified by the transfer ID is running

var(*LIST).LOCK-ENTRY(*LIST).FT-LOCK.HOST

S

*OWN
*UNKNOWN
<c-string 1..8>

FT lock

Type of file lock
*BACKUP=file is saved by means of CCOPY
*EXCL=file is locked against access of any kind
*INOUT-WEAK=lock against opening for write access with SHARUPD=WEAK
*INOUT-YES=lock against opening for write access with SHARUPD=YES
*INPUT=lock against opening for read access
*INPUT-WEAK=lock against opening for read access with SHARUPD=WEAK
*INPUT-YES=lock against opening for read access with SHARUPD=YES
*MIGR=lock during migration by means of HSMS
*NONE=no lock
*OUTPUT=lock against opening for write access
*RESERVE=file is reserved for a particular application
*RES-INPUT=lock against updating
*SEC=lock by means of /SECURE-RESOURCE-ALLOCATION

var(*LIST).LOCK-ENTRY(*LIST).FT-LOCK.LOCK-TYPE

S

*BACKUP
*EXCL
*INOUT-WEAK
*INOUT-YES
*INPUT
*INPUT-WEAK
*INPUT-YES
*MIGR
*NONE
*OUTPUT
*RESERVE
*RES-INPUT
*SEC

FT lock

Type of file lock (cont.)





Identification of the FT job

var(*LIST).LOCK-ENTRY(*LIST).FT-LOCK.TRANSFER-ID

S

<c-string 1..11>

FT lock

Name of the cross-coupled system to which the host is connected

var(*LIST).LOCK-ENTRY(*LIST).FT-LOCK.XCS-NAME

S

*NONE
*UNKNOWN
<c-string 1..8>

FT lock

Type or cause of the lock

var(*LIST).LOCK-ENTRY(*LIST).LOCK-CLASS

S

*FT-LOCK
*SYS-LOCK
*TSN-LOCK

MSCF name of the processor on which the function unit specified by the program ID is running

var(*LIST).LOCK-ENTRY(*LIST).SYS-LOCK.HOST

S

*OWN
*UNKNOWN
<c-string 1..8> 

SYS lock

Type of file lock
*BACKUP=file is saved by means of C-COPY
*EXCL=file is locked against access of any kind
*INOUT-WEAK=lock against opening for write access with SHARUPD=WEAK
*INOUT-YES=lock against opening for write access with SHARUPD=YES
*INPUT=lock against opening for read access
*INPUT-WEAK=lock against opening for read access with SHARUPD=WEAK
*INPUT-YES=lock against opening for read access with SHARUPD=YES
*MIGR=lock during migration by means of HSMS
*NONE=no lock
*OUTPUT=lock against opening for write access
*RESERVE=file is reserved for a particular application
*RES-INPUT=lock against updating
*SEC=lock by means of /SECURE-RESOURCE-ALLOCATION

var(*LIST).LOCK-ENTRY(*LIST).SYS-LOCK.LOCK-TYPE

S

*BACKUP
*EXCL
*INOUT-WEAK
*INOUT-YES
*INPUT
*INPUT-WEAK
*INPUT-YES
*MIGR
*NONE
*OUTPUT
*RESERVE
*RES-INPUT
*SEC

SYS lock

Identification of the function unit

var(*LIST).LOCK-ENTRY(*LIST).SYS-LOCK.PROGRAM-ID

S

*C-COPY
*EAM

SYS lock

Name of the cross-coupled system to which the host is connected

var(*LIST).LOCK-ENTRY(*LIST).SYS-LOCK.XCS-NAME

S

*NONE
*UNKNOWN
<c-string 1..8>

SYS lock

MSCF name of the processor on which the job specified by the TSN is running

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.HOST

S

*OWN
*UNKNOWN
<c-string 1..8>

TSN lock

Job name assigned to the TSN

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.JOB-NAME

S

*NONE
*UNKNOWN
<c-string 1..8>

TSN lock

Job type of the lock enforcer
*BATCH=active batch job
*DIALOG=dialog job
*ENTER=pending batch job; only the file from which the batch job will read its commands is locked.
*HOLD=batch job suspended by /HOLD-TASK
*SPOOL=print job
*SYS=system job
*UNDEF=not defined 

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.JOB-TYPE

S

*BATCH
*DIALOG
*ENTER
*HOLD
*SPOOL
*SYS
*UNDEF

TSN lock

Type of file lock
*BACKUP=file is saved by means of C-COPY
*EXCL=file is locked against access of any kind
*INOUT-WEAK=lock against opening for write access with SHARUPD=WEAK
*INOUT-YES=lock against opening for write access with SHARUPD=YES
*INPUT=lock against opening for read access
*INPUT-WEAK=lock against opening for read access with SHARUPD=WEAK
*INPUT-YES=lock against opening for read access with SHARUPD=YES
*MIGR=lock during migration by means of HSMS
*NONE=no lock
*OUTPUT=lock against opening for write access
*RESERVE=file is reserved for a particular application
*RES-INPUT=lock ag. updating
*SEC=lock by means of SECURE-RESOURCE-ALLOCATION

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.LOCK-TYPE

S

*BACKUP
*EXCL
*INOUT-WEAK
*INOUT-YES
*INPUT
*INPUT-WEAK
*INPUT-YES
*MIGR
*NONE
*OUTPUT
*RESERVE
*RES-INPUT
*SEC

TSN lock

Task sequence number to which the lock is assigned

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.TSN

S

*REM
<c-string 1..4>

TSN lock

User ID of the owner of the TSN

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.USER-ID

S

*UNKNOWN
<c-string 1..8>

TSN lock

Name of the cross-coupled system to which the host is connected

var(*LIST).LOCK-ENTRY(*LIST).TSN-LOCK.XCS-NAME

S

*NONE
*UNKNOWN
<c-string 1..8>

TSN lock

Name of the locked file

var(*LIST).PATH-NAME

S

<c-string 1..54>


Examples

The file ABK.ISAM is locked against opening for writing because the file transfer has not yet been completed:

/show-file-transfer

%TRANS-ID   INI STATE PARTNER  DIR  BYTE-COUNT  FILE-NAME
%45709604   LOC HOLD  D016ZE07 TO   0           ABK.ISAM
%  FTR0004 FT-BS2000: INFORMATION COMPLETED

/show-file-locks abk.isam

%SHOW-FILE-LOCKS                               Date: 2014-03-14, Time: 13:10:00 
%File name:  :2OSG:$USER1.ABK.ISAM
%------------------------------------------------------------------------------ 
%Locks identified by File Transfer ID:
% Transfer ID                               Lock type   Host name   XCS name
% 45709604                                  RES_INPUT   *OWN        *NONE
%------------------------------------------------------------------------------ 
%Total number of locks is: 1
%------------------------------------------------------------------------------ 
%SHOW-FILE-LOCKS                                                 End of display

The file SYSSDF.USER.1 has been opened in write mode using the SDF-A utility and so is locked against opening:

/show-file-locks syssdf.user.1 

%SHOW-FILE-LOCKS                               Date: 2014-03-14, Time: 13:11:39 
%File name:  :2OSG:$USER1.SYSSDF.USER.1
%------------------------------------------------------------------------------ 
%Locks identified by TSN:
% TSN   Job name    User ID     Job type    Lock type   Host name   XCS name
% 3PBR  ALT         USER1       DIALOG      OUTPUT      *OWN        *NONE
%------------------------------------------------------------------------------ 
%Total number of locks is: 1
%------------------------------------------------------------------------------ 
%SHOW-FILE-LOCKS                                                 End of display

The file SYSRME.SPOOL.049.D is currently being printed. It is locked against modification until the print job has been completed:

/print-doc sysrme.spool.049.d,line-spacing=*by-ebcdic

%  SCP0810 SPOOLOUT FOR FILE ':2OSG:$USER1.SYSRME.SPOOL.049.D' ACCEPTED. TSN: 
'3PIU', SPOOLOUT-NAME: 'ALT', MONJV: '*NONE'
%  SCP1025 PRINT JOB ACCEPTED BY SERVER 'GH5090Y0' WITH TSN '40VG'

/show-file-locks sysrme.spool.049.d

%SHOW-FILE-LOCKS                               Date: 2014-03-14, Time: 13:14:23 
%File name:  :2OSG:$USER1.SYSRME.SPOOL.049.D
%------------------------------------------------------------------------------ 
%Locks identified by TSN:
% TSN   Job name    User ID     Job type    Lock type   Host name   XCS name
% 3PIU  *UNKNOWN    *NONE       SPOOL       RES_INPUT   *OWN        *NONE
%------------------------------------------------------------------------------ 
%Total number of locks is: 1
%------------------------------------------------------------------------------ 
%SHOW-FILE-LOCKS                                                 End of display
Powered by Atlassian Confluence and Scroll Viewport.