doc: add documentation of locking for indexed files (#700)

* doc: add documentation of locking for indexed files

* doc: fix documents

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* Update doc/specification-locking-indexed-file_JP.md

Co-authored-by: Copilot <[email protected]>

* Update locking specification

* Update locking specification

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Momoka Shimada <[email protected]>

Author: 3 people

README.md

@@ -171,6 +171,7 @@ java [PROGRAM-ID]
 * [The API reference of the runtime library `libcobj.jar`](https://opensourcecobol.github.io/opensourcecobol4j/javadoc/libcobj/index.html)
 * [opensource COBOL 4J: Java変換解説](./doc/converted_Java_file_JP.md)
 * [configuration-params-JP](./doc/configuration-params-JP.md)
+* [The specification of locking for INDEXED files in opensource COBOL 4J](./doc/specification-locking-indexed-file.md)
 
 ## Development Progress
 

README_JP.md

@@ -160,6 +160,7 @@ java [PROGRAM-ID]
 * [ランタイムライブラリ`libcobj.jar`のAPIリファレンス](https://opensourcecobol.github.io/opensourcecobol4j/javadoc/libcobj/index.html)
 * [opensource COBOL 4J: Java変換解説](./doc/converted_Java_file_JP.md)
 * [configuration-params-JP](./doc/configuration-params-JP.md)
+* [INDEXEDファイルのロックの仕様](./doc/specification-locking-indexed-file_JP.md)
 
 ## 実装状況
 実装済み機能：

doc/specification-locking-indexed-file.md

@@ -0,0 +1,44 @@
+# INDEXED File Locking Specification
+
+## LOCK MODE in the SELECT Statement
+
+- The SELECT statement's LOCK MODE can only specify AUTOMATIC or MANUAL.
+- When omitted, the default value for LOCK MODE is MANUAL
+  - When `-lock-mode-automatic` is specified at compile time, the default value for omitted LOCK MODE becomes AUTOMATIC.
+
+## Record Locking Behavior
+
+- When a file is opened with OPEN I-O and a READ statement without WITH NO LOCK or WITH LOCK is executed:
+  - If the SELECT statement's LOCK MODE is MANUAL, the record is not locked
+  - If the SELECT statement's LOCK MODE is AUTOMATIC, the record is locked
+- When a file is opened with OPEN I-O and a READ statement with WITH LOCK is executed, the record is locked
+- When a file is opened with OPEN I-O and a READ statement with WITH NO LOCK is executed, the record is not locked
+- When processing fails due to record locking, the file status becomes 51
+
+## File Locking Behavior
+
+- When a file is opened with OPEN OUTPUT, a file lock is applied to the file
+- When processing fails due to file locking, the file status becomes 61
+
+## Migrating Legacy INDEXED Files to the New Version
+
+Legacy INDEXED files cannot be used directly with the new version of opensource COBOL 4J.
+To convert INDEXED files created with legacy versions to be compatible with the new version, please use the following command:
+
+```sh
+cobj-idx migrate <<INDEXED_FILE>>
+```
+
+This command converts the specified INDEXED file to be compatible with the new version.
+
+## Unlocking INDEXED Files
+
+The following command can release all file locks and record locks on an INDEXED file:
+
+```sh
+cobj-idx unlock <<INDEXED_FILE>>
+```
+
+## Behavior When Opening Legacy INDEXED Files
+
+When attempting to open legacy INDEXED files, the file status becomes 92.

doc/specification-locking-indexed-file_JP.md

@@ -0,0 +1,45 @@
+
+# INDEXEDファイルのロック仕様
+
+## SELECT句のLOCK MODE
+
+- SELECT句のLOCK MODEにはAUTOMATICかMANUALのみ指定可能である。
+- 省略した場合のLOCK MODEのデフォルト値はMANUAL
+  - コンパイル時に`-lock-mode-automatic`を指定した場合、LOCK MODEを省略した場合のデフォルト値はAUTOMATICになる。
+
+## レコードロックの動作
+
+- OPEN I-Oでファイルを開き、WITH NO LOCKもWITH LOCKも指定されないREAD文を実行したとき
+  - SELECT句のLOCK MODEがMANUALの場合、当該レコードをロックしない
+  - SELECT句のLOCK MODEがAUTOMATICの場合、当該レコードをロックする
+- OPEN I-Oでファイルを開き、WITH LOCK指定のあるREAD文を実行したとき、当該レコードをロックする
+- OPEN I-Oでファイルを開き、WITH NO LOCK指定のあるREAD文を実行したとき、当該レコードをロックしない
+- レコードロックにより処理が失敗した場合、ファイルステータスが51となる
+
+## ファイルロックの動作
+
+- OPEN OUTPUTで開いたときに、当該ファイルにファイルロックがかかる
+- ファイルロックにより処理が失敗した場合、ファイルステータスは61となる
+
+## 古いバージョンのINDEXEDファイルを新バージョンに対応させる。
+
+古いバージョンのINDEXEDファイルは、直接最新バージョンのopensource COBOL 4Jでは使用できません。
+古いバージョンで作成したINDEXEDファイルを新バージョンに対応したものに変換するには、以下のコマンドを実行してください。
+
+```sh
+cobj-idx migrate <<INDEXEDファイル>>
+```
+
+これにより、指定したINDEXEDファイルが新バージョンに対応したものに変換される。
+
+## INDEXEDファイルのロックを解除する
+
+下記のコマンドで、INDEXEDファイルにかかったファイルロックとすべてのレコードロックを解除できる。
+
+```sh
+cobj-idx unlock <<INDEXEDファイル>>
+```
+
+## 古いバージョンのINDEXEDファイルを開いたときの動作
+
+古いバージョンのINDEXEDファイルを開こうとした場合、ファイルステータスが92となる。