# list-locks command

The list-locks BASIC program displays
the current status of all system, FlashBASIC, spooler, group, and
item locks.

All locks display automatically unless one or more of
the available options is provided with the command.

## Syntax

```
 list-locks {-options} {(options}
```

## Parameter(s)

| -options | help | Shows the help text. |
| --- | --- | --- |
| computer | D3 Windows only: Includes the computer name in the report. | |
| hostfsi | D3 Windows only: Shows the locks on given FSI host. | |
| hostvme | Shows the locks on a given OSFI host. | |
| time | Includes the date and time the item lock was set. The -hostvme option does not support -time. | |

| (options | ? | Shows the help text. |
| --- | --- | --- |
| a | Shows the txlog producer lock. | |
| b | Shows BASIC locks. | |
| c | Shows the txlog consumer lock. | |
| g | Shows VME group locks. | |
| i | Shows local FSI and VME item locks. | |
| m | Shows phantom locks. | |
| n | Returns the output in a non-paginated form. Does not pause at page breaks. | |
| p | Directs output results to the system printer. | |
| q | Shows spooler locks. | |
| s | Shows system locks. | |
| t | Shows txlog locks. | |

## Description

Using list-locks shows both the VME and FSI item locks.

 File locks are special item locks that affect the whole file. These locks prevent any
 updates or normal item locks to a file while in effect. File locks display in the item
 lock listing as having item-IDs of an asterisk and hashes of zero. These locks are set
 with the BASIC filelock statement.

 When displaying item locks (by using the i option), it is optionally
 possible to display the locks of a remote D3 machine by specifying the host name. If an
 asterisk is specified for the host name, then the list-locks command
 attempts to list the locks on all remote hosts.

 **Filtering -options**

 When using filters, only lock entries satisfying at least one value for each filter will
 be included in the report.

 The individual values for a given filter are joined by a logical or,
 while multiple filters are joined together by a logical and. That is,
 (<*file 1*> or <*file 2*> or
 <*file ...*>) AND (<*pib#1*> or
 <*pib#2*> or <*pib#...*>)

 You can use the following to filter *-options*:

- -file ... VME files: Use the name of the level at which the lock is set.For example, if a lock is set on an item in dict resizing then use -file resizing

- FSI files: Use the full path.For example, -file account,dict,data

- -pib ...

**Report headings**

 The report includes the following headings:

 System locks are the 4 internal system locks used during saves:

| ### | Lock position is unused |
| --- | --- |
| 1 | Overflow |
| 3 | Unique id (for example, system(19)) |
| 4 | Item lock table |
| 9 | User-exits u0191, u1191, u2191, and u3191 |

 Basic locks are the 992 BASIC program execution locks (used by BASIC programs):

| ### | Lock position is unused. |
| --- | --- |
| nnn | Port number using this lock position. |

 Spooler locks are the internal spooler locks:

| mq | Secondary queue lock |
| --- | --- |
| iq | Input queue lock |
| fq | Forms queue lock |
| peq | Permanent entry queue lock |
| msp | Master queue lock |

 Group locks:

| nnnnn | Frame-ID (in decimal). |
| --- | --- |
| (nnnnnn) | Frame-ID (in hexadecimal). |
| PIB# | The PIB number (port) that has the item locked. |
| Lvl | The level on which this group is locked. |
| Type | The type of group lock. This can be either read-only (Rdo) or update (Upd). |
| Filename | The file in which the group exists. |

 Item locks:

| nnnnn | Frame-ID (in decimal). |
| --- | --- |
| (nnnnnn) | Frame-ID (in hexadecimal). |
| PIB# | The PIB number (port) that has the item locked. |
| Lvl | The level on which this item is locked. |
| Hash | The locked item’s hash code. |
| Type | The utility that is running the program. |
| Item-ID | The Item-ID that is currently locked. |
| Filename | The name of the file where the item resides. |
| Token | The unique identifier for that item. |

 Transaction Log locks:

| fof | The lock that is set when altering the file-of-files number counter. |
| --- | --- |
| pro | The lock that is set when accessing the producer side of the transaction log queue. |
| con | The lock that is set when accessing the consumer side of the transaction log queue. |

 Phantom locks:

| rel | Release Queue lock |
| --- | --- |
| job | Phantom job lock |
| pib | PIB table lock |
| que | Queue lock |
| plk | General Phantom lock |

## Example(s)

**Example 1**

 This example shows lock entries displayed for the VME file bp, or the FSI files
 bigdata,gps,gps or bigdata,rfid,rfid that are owned by any of the PIBs 3 7 12.

```

 list-locks -file bp bigdata,gps,gps bigdata,rfid,rfid -pib 3 7 12
```

 **Example 2**

 This example shows item locks displayed on the OSFI server referenced by the dm,hosts,
 item myremoteserver that are owned by PIB 33.

```

 list-locks -hostvme myremoteserver -pib 33
```

 **Example 3**

 This example shows item locks displayed on the OSFI server referenced by the dm,hosts,
 item myremoteserver and on the FSI server with the network hostname
 of mybackupfsiserver.

```

 list-locks -hostfsi mybackupfsiserver -hostvme myremoteserver
```

 **Example 4**

In this example, only the current item locks are shown.

```

 list-locks (i

 Item Locks PIB# Lvl Hash item-ID Filename
 5834 (0016CA) 54 0 7E2C 21086 orders
 2746 (000ABA) 68 0 0D1F roy/month2 memos
 183325 (02CC1D) 29 1 5DD7 3242 entity
 183197 (02CB9D) 22 2 7D9F 20946 entity
 184453 (02D085) 66 0 279F 73291176 entity
 110819 (01B0E3) 42 0 084D tcl.list-locks d3.doc
 110908 (01B13C) 3 0 3E36 data.representation d3.doc
 133899 (020B0B) 82 0 6C2C monitor status
```

 **Example 5**

In this example, all locks are shown.

```

 list-locks
 System Locks
 0 1 2 3 4 5 6 7 8 9 A B C D E F
 00 ### ### ### ### ### ### ### ### ### ### ###

 Basic Locks
 0 1 2 3 4 5 6 7 8 9 A B C D E F
 00 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
 Spooler Locks
 mq iq fq peq msp
 00 ### ### ### ### ###

 Txlog Locks

 fof pro con
 00 ### ### ###

 Phantom Locks
 rel job pib que plk
 00 ### ### ### ### ###

 Group Locks PIB# Lvl Type Filename
 442384 (06C00F) 13 1 Upd xsym

 Item Locks PIB# Lvl Hash item-ID Filename
 123034 (01E09A) 23 1 54B898A5 wm email
 79174 (013546) 57 0 9472A038 hv tcl-stack

 FSI Filename PIB# Lvl Type item-ID Token
 DM,basicprogram,ba 3 0 VME newfile 79309092
 :
```

## See also

- [filelock statement](https://d3codex.com/pickbasic-flashbasic/filelock-statement/)
- [hosts file](https://d3codex.com/systemfiles/hosts-file/)
- [list-lockq command](https://d3codex.com/tcl/list-lockq-command/)
- [Locking scheme](https://d3codex.com/definitions/locking-scheme/)
- [Locks (Spooler)](https://d3codex.com/tcl/locks-spooler/)
- [unlock-file command](https://d3codex.com/tcl/unlock-file-command/)

---
Source: https://d3codex.com/tcl/list-locks-command/ - part of the D3Codex reference.