MSX Datapack wiki化計画

17章 ファンクションコール

※
※ このページは書きかけです。以下の可能性があります。
※ ・誤字、脱字等のチェックをおこなっていません。
※ ・テキスト、表などフォーマットがされていない。
※ ・画像が抜けている。
※

 この章ではMSX-DOS2のファンクションコールについて詳しく解説しています。ファイルハンドル、ファイル情報ブロック(FIB-File Information Block)、環境変数などといったシステムの特徴について概説している13章「ディスクファイルの構造」とともに読むことをおすすめします。

 MSXではMSX-DOSとDisk-BASICという異なる環境でディスクを使用するので、MSX-DOSのファンクションコールを実行するには2つの方法があります。MSX-DOSの環境で実行される外部プログラムは、“CALL 0005H”でファンクションを利用しなければなりません。Disk-BASICやDisk-BASICの環境で実行される他のMSXプログラム(通常ROMから実行される)では、“CALL 0F37DH”を通してファンクションを利用します。

 F37DHを通してシステムをコールするときには、特にエラーハンドリングやアボートルーチンを実行する場合に、いくつかの制限があります。また、(Disk-BASICの場合のように)マスターディスクROM中にない限り、ページ1にあるパラメータを渡すことはできません。なぜなら、このようなファンクションコールが実行されている間はマスターディスクROMがページ1に選択されているためです。

 特定のファンクションについては、個々のファンションの説明で相違点が明記してあります。

 17.1 ファンクションコールの方法

 MSX-DOSのファンクションコールはCレジスタにファンクションコードを、他のレジスタ(A、BC、DEおよびHL)に必要なパラメータを入れ、「CALL 5」命令を実行することによって行います。結果はそれぞれレジスタ中に返されます。

 すべてのレジスタ(AF、BC、DEおよびHL)はMSX-DOSのコールによって破棄されるか、あるいは結果を返します。裏レジスタセット(AF'、BC'、DE'およびHL')は常に保存され、インデックスレジスタ(IXとIY)は、これらが結果を返す場合を除いて保存されます。

 MSX-DOSはコールされると内部スタックに切り換えるため、必要な外部プログラムのスタックは8バイトだけです。

 CP/Mとの互換性のため、CP/Mのファンクションに対応するすべてMSX-DOSのファンクションは、A=LおよびB=Hでリターンします。多くの場合、Aはゼロで成功を示し、01Hあるいは0FFHで失敗を示すようなエラーフラグを返します。

 新しいMSX-DOSのファンクション(40H以上のファンクションコードのもの)はエラーコードをAに、他の結果を別のレジスタ中に入れてリターンします。0のエラーコードはエラーなしを示し、コードがゼロでない場合は、なんらかのエラーが発生したことを示し、正確な原因はその値を調べることでつきとめることができます。エラーコードおよびメッセージのリストは9章で説明します。またMSX-DOSでは「エラーコードの説明」ファンクション(P.323参照)が提供されていて、エラーコードについての説明文字列を与えます。

 17.2 ファンクション一覧

 以下にファンクションコールの全リストを示します。

 「ファンクション」には、ファンクションの番号と機能を示します。

 「CP/M互換」に「○」と記されているファンクションは、CP/M2.2のファンクションと互換性があることを意味します。

 「DOS1互換」に「○」と記されているファンクションは、MSX-DOS1と互換性があることを意味し、それ以外のファンションは、MSX-DOS2で新たに追加されたファンクションであることを意味します。

 「エラー処理」に「○」が付いたファンクションは、ユーザーのディスクエラー処理ルーチン(ファンクション64Hおよびファンクション70H参照)からコールできることを意味します。

 「ページ」には、ファンクションの解説をしているページを示します。

表 2.24 MSX-DOSファンクションコール一覧

ファンクションCP/M互換DOS1互換エラー処理ページ
00H プログラムの終了 269
01H コンソール入力 269
02H コンソール出力 270
03H 補助入力 270
04H 補助出力 271
05H プリンタ出力 271
06H 直接コンソールI/O 271
07H 直接コンソール入力 272
08H エコーなしコンソール入力 272
09H 文字列出力 273
0AH バッファ行入力 273
0BH コンソールステータス 274
0CH バージョン番号の獲得 274
0DH ディスクリセット 275
0EH ディスクの選択 275
0FH ファイルのオープン[FCB] 275
10H ファイルのクローズ[FCB] 277
11H 最初のエントリの検索[FCB] 277
12H 次のエントリの検索[FCB] 278
13H ファイルの削除[FCB] 279
14H シーケンシャル読み込み[FCB] 279
15H シーケンシャル書き込み[FCB] 280
16H ファイルの作成[FCB] 280
17H ファイル名の変更[FCB] 281
18H ログインベクタの獲得 281
19H カレントドライブの獲得 282
1AH ディスク転送アドレスのセット 282
1BH アロケーション情報の獲得 282
21H ランダム読み出し[FCB] 283
22H ランダム書き込み[FCB] 283
23H ファイルサイズの獲得[FCB] 284
24H ランダムレコードのセット[FCB] 284
26H ランダムブロック書き込み[FCB] 285
27H ランダムブロック読み出し[FCB] 286
28H ゼロフィルを行うランダム書き込み[FCB]286
2AH 日付の獲得 287
2BH 日付のセット 287
2CH 時刻の獲得 288
2DH 時刻のセット 288
2EH ベリファイフラグのセット・リセット289
2FH アブソリュートなセクタの読み出し 289
30H アブソリュートなセクタの書き込み 290
31H ディスクパラメータの獲得 290
40H 最初のエントリの検索 291
41H 次のエントリの検索 292
42H 新しいエントリの検索 293
43H ファイルハンドルのオープン 295
44H ファイルハンドルの作成 296
45H ファイルハンドルのクローズ 297
46H ファイルハンドルの確保 297
47H ファイルハンドルの複製 297
48H ファイルハンドルからの読み出し 298
49H ファイルハンドルへの書き込み 300
4AH ファイルハンドルポインタの移動 301
4BH デバイスのI/O制御 302
4CH ファイルハンドルの検査 304
4DH ファイルあるいはサブディレクトリの削除 304
4EH ファイルあるいはサブディレクトリ名の変更305
4FH ファイルあるいはサブディレクトリの移動 306
50H ファイル属性の獲得・セット 307
51H ファイルの日付および時刻の獲得・セット 308
52H ファイルハンドルの削除 309
53H ファイルハンドルの名前の変更 309
54H ファイルハンドルの移動 310
55H ファイルハンドルの属性の獲得・セット 310
56H ファイルハンドルの日付および時刻の獲得・セット311
57H ディスク転送アドレスの獲得 311
58H ベリファイフラグ設定の獲得 312
59H カレントディレクトリの獲得 312
5AH カレントディレクトリの変更 313
5BH パス名の解析 313
5CH ファイル名の解析 314
5DH 文字の検査 315
5EH パス文字列全体の獲得 316
5FH ディスクバッファのフラッシュ 317
60H 子プロセスの起動 318
61H 親プロセスへ戻る 318
62H エラーコードを返して終了 320
63H アボート終了ルーチンの定義 320
64H ディスクエラー処理ルーチンの定義 322
65H 直前のエラーコードの獲得 323
66H エラーコードの説明 323
67H ディスクのフォーマット 324
68H RAMディスクの作成あるいは破壊 326
69H セクタバッファの割り付け 326
6AH 論理ドライブの割り当て 327
6BH 環境変数の獲得 328
6CH 環境変数のセット 328
6DH 環境変数の検索 329
6EH ディスク検査ステータスの獲得・セット 329
6FH MSX-DOSのバージョン番号の獲得 330
70H リダイレクションのステータスの獲得・セット331

 17.3 ファンクションの説明

 以下にMSX-DOSのファンクションのそれぞれについて、古いもの、新しいものを含めて詳しく説明します。ファンクション番号の後の括弧内の名前は「CODES.MAC」中で定義されているファンクションコードのパブリック・ラベルです。プログラムではこれらの名前を可能な限り使用しなければなりません。

 40H未満のファンクションの多くはエラーコードではなくエラーフラグを返します。エラーフラグがセットされると、エラーの原因を示す実際のエラーコードは「直前のエラーコードの獲得」ファンクション(P.323参照)で得ることができます。40H以上のすべてのファンクションはAレジスタ中にエラーコードを返します。16章「エラー」ではファンクションから返される一般的なエラーについて記述しています。本章での個々のファンクションの説明では、そのファンクション固有の主なエラーの状態について記述します。

 ディスク上の情報を変更するファンクションコールの多くは自動的にディスクバッファをフラッシュしないため、ディスクはそのファンクションコール実行後すぐには、必ずしも正しく更新されないことに注意して下さい。このようなファンクションコールにはすべてのタイプの「作成」、「書き込み」、「削除」、「名前の変更」、「ファイル属性の変更」、「ファイルの日付と時刻の変更」ファンクションコールがふくまれます。ディスクバッファを常にフラッシュするファンクションは、「バッファのフラッシュ」、「クローズ」、および「確保」だけです。これらの処理の後では、ディスクは常に正しく更新されています。

プログラムの終了 [CP/M][DOS1]

機能番号
00H(_TERM0)
コール手順
なし
戻り値
なし
解説

 このファンクションは0のリターンコードでプログラムを終了させます。これはMSX-DOS1およびCP/Mとの互換性のために用意されており、プログラムを終了するには、「エラーコードを返して終了」ファンクションコール(P.320参照)を使用することを推奨します。この場合でも、必要ならエラーがなかったことを示す0のエラーコードを渡すことができます。プログラムが終了するときに起こることについての詳細はそのファンクションコールの説明、および12.2「MSX-DOSへのリターン」を参照して下さい。このファンクションコールは呼び出し側に戻ることはありません。

コンソール入力 [CP/M][DOS1][エラー処理]

機能番号
01H(_CONIN)
コール手順
なし
戻り値
L=A  キーボードからの文字
解説

 文字が標準入力(ファイルハンドル0−通常はキーボード)から読み込まれ、標準出力(ファイルハンドル1−通常はスクリーン)へエコーされます。文字がなければ、文字が入力されるまで待ちます。「コンソールステータス」ファンクション(P.274参照)で指定されている様々なコントロール文字は種々の制御のためにトラップされます。この種の文字が検知されると、処理の後、別の文字を待ちます。したがって、このファンクションではそのコントロール文字はユーザーに返されることがありません。

コンソール出力 [CP/M][DOS1][エラー処理]

機能番号
02H(_CONOUT)
コール手順
E 出力する文字
戻り値
なし
解説

 Eレジスタに渡された文字が標準出力(ファイルハンドル1−通常はスクリーン)に書き出されます。プリンタエコーが有効になっていると、文字はプリンタにも出力されます。種々のコントロールコードやエスケープシーケンスは画面制御コードとして解釈されます。これらの一覧は14章「画面制御コード」に記載されており、標準のVT-52コントロールコードのサブセットになっています。TABはカラム位置が8の倍数になるまでスペースに展開されて出力されます。

 コンソール入力ステータスのチェックが行われ、「コンソールステータス」ファンクション(P.274参照)で解説された特別なコントロール文字が現れた場合は、そこで解説したように処理されます。それ以外の文字はその後の「コンソール入力」ファンクションコールのために内部でセーブされます。

補助入力 [CP/M][DOS1][エラー処理]

機能番号
03H(_AUXIN)
コール手順
なし
戻り値
L=A 入力文字
解説

 文字が補助入力デバイス(ファイルハンドル3)から読み込まれ、文字がない場合には文字の入力を待ちます。補助入力デバイスはこのファンクションが使用される前にインストールされていなければなりません。デバイスがインストールされていないと、このファンクションは常にエンドオブファイル文字(^Z)を返します。

補助出力 [CP/M][DOS1][エラー処理]

機能番号
04H(_AUXOUT)
コール手順
E  出力する文字
戻り値
なし
解説

 Eレジスタに渡された文字が補助出力デバイス(ファイルハンドル3)に書き出されます。補助出力デバイスは、このファンクションが使用される前にインストールされていなければなりません。デバイスがインストールされていないと、このファンクションは文字を捨ててしまいます。

プリンタ出力 [CP/M][DOS1][エラー処理]

機能番号
05H(_LSTOUT)
コール手順
E 出力する文字
戻り値
なし
解説

 Eレジスタに渡されて文字がプリンタデバイス(ファイルハンドル4−通常はプリンタ)に書き出されます。コンソール出力からプリンタへエコーする場合も、おなじチャンネルが使用されます。このファンクションではTABは展開されませんが、スクリーン出力が[CTRL]+[P]プリンタにエコーされるときには展開されます。

直接コンソールI/O [CP/M][DOS1][エラー処理]

機能番号
06H(_DIRIO)
コール手順

E 00H〜FEH 出力する文字

 FFH       入力要求
戻り値

A=L 入力

    00H  文字がない
    そうでない場合には入力文字、出力については未定義。
解説

 E=FFHの場合には、標準入力(アイルハンドル0)空の文字入力が調べられ、文字がないと00Hが返されます。文字があると、標準入力(ファイルハンドル0)から読み込まれ、エコーされず、またコントロール文字についてのチェックもされずにAレジスタに返されます。

 E≠FFHの場合には、レジスタE中の文字がTABの展開やプリンタエコーされずに、標準出力(ファイルハンドル1)へ直接出力されます。またこのファンクションではコンソールステータスのチェックはおこなわれません。またこのファンクション自体はTABを拡張しませんが、VT-52コントロールコードはTABの拡張を含むため、スクリーン上での効果は同じです。

直接コンソール入力 [DOS1][エラー処理]

機能番号
07H(_DIRIN)
コール手順
なし
戻り値
L=A  入力文字
解説

 このファンクションは文字がない場合には文字の入力を持つことを除いて、ファンクション00Hの入力オプションと同一です。ファンクション06H同様、エコーやコントロール文字のチェックは行われません。このファンクションは、このファンクション番号を「I/Oバイトの取得」に使用しているCP/Mとの互換性はありません。

エコーなしコンソール入力 [DOS1][エラー処理]

機能番号
08H(_INNOE)
コール手順
なし
戻り値
L=A 入力文字
解説

 このファンクションは入力された文字が標準出力にエコーされない点を除いて「コンソール入力」ファンクション(P.269参照)と同様です。同様のコントロール文字のチェックが行われます。このファンクションは、このファンクション番号を「I/Oバイトの設定」使用しているCP/Mとの互換性はありません。

文字列出力 [CP/M][DOS1][エラー処理]

機能番号
09H(_STROUT)
コール手順
DE 文字列のアドレス
戻り値
なし
解説

 DEレジスタで指される文字列の文字が標準の「コンソール出力」ファンクション(P.270参照)を使用して出力されます。文字列は「$」(ASCII 24H)で終了します。

バッファ行入力 [CP/M][DOS1][エラー処理]

機能番号
0AH(_BUFIN)
コール手順
DE 入力バッファのアドレス
戻り値
なし
解説

 DEは入力に使用されるべきバッファを指していなければなりません。このバッファの最初のバイトはバッファが保持できる文字数(0〜255)を持っていなければなりません。入力行は標準入力デバイス(ファイルハンドル0−通常キーボード)から読み込まれ、バッファに格納されます。入力はCRが標準入力から読み込まれたときに終了します。入力された文字数(CR自体は含まれない)は(DE+1)に格納されます。バッファに余裕があれば、CRが最後の文字の後に格納されます。
 キーボードから入力する場合(通常の場合)、簡単な行エディタが利用でき、また、以前に入力された行の256バイトのリングバッファがあって、これを編集したり再入力したりすることができます。これらの編集機能についての詳細は2章「コマンド行の編集」を参照して下さい。入力バッファが一杯になると、バッファに入れられない文字がタイプされるたびに、コンソールのベルが鳴ります。入力された文字は標準出力に出力され、プリンタエコーが有効になっている場合は、プリンタにも出力されます。

コンソールステータス [CP/M][DOS1][エラー処理]

機能番号
0BH(_CONST)
コール手順
なし
戻り値
L=A 00H 入力文字がない
    FFH 入力文字がある
解説

 キーボードからの入力について、入力文字があるかどうかを示すフラグがAレジスタに返されます。入力文字があればそれが読み込まれ、特殊なコントロール文字かどうか検査されます。そのようなコントロール文字でない場合には、内部の1バイトバッファに格納され、このファンクションへの以降のコールでは、キーボードをチェックしないで即座に「入力文字がある」を返します。このファンクションで「入力文字がある」と示された場合、その文字はいずれかの「コンソール入力」で読むことができます。
 文字が「^C」であると、プログラムはユーザーの亜ボードルーチン(定義されている場合)を経由して「.CTRLC」エラーを返して終了します。文字が「^P」であると、プリンタエコーが有効になり、「^N」の場合に無効になります。文字が「^S」であると、ルーチンは別の文字が押されるのを待ち、それから「入力文字がない」という状態を消すことによって、「ウェイト」機能を実現します。処理を続行するためにタイプされた文字は無視されますが、「^C」の場合にはプログラムが停止します。これらと同様の入力のチェックは、01H(P.269参照)、02H(P.270参照)、08H(P.272参照)、09H(P.273参照)、および0AH(P.273参照)でも実行されます。

バージョン番号の獲得 [CP/M][DOS1][エラー処理]

機能番号
0CH(_CPMVER)
コール手順
なし
戻り値
L=A 22H
H=B 00H
解説

 このファンクションはエミュレートしているCP/Mのバージョン番号を返します。これは現在のシステムでは常にバージョン2.2です。

ディスクリセット [CP/M][DOS1]

機能番号
0DH(_DSKRST)
コール手順
なし
戻り値
なし
解説

 内部バッファ中の、まだ書き出しが行われていないすべてのデータをディスクに書き出します。CP/Mでの場合のように、ディスクの交換を可能にするためにこのファンクションをコールする必要はありません。ディスク転送アドレスはまたこのファンクションによってその初期値80Hに戻されます。また、デフォルトドライブはA:となります。

ディスクの選択 [CP/M][DOS1]

機能番号
0EH(_SELDSK)
コール手順
E  ドライブ番号(0=A:  1=B: など)
戻り値
L=A ドライブ数(1〜8)
解説

 このファンクションは指定のドライブをデフォルトのドライブとして選択します。カレントライブは、CP/Mとの互換性のため、0004H番地にも格納されます。使用できるドライブの数をAレジスタに返します。ただし、ドライブ数にRAMディスクは含みません。

ファイルのオープン[FCB] [CP/M][DOS1]

機能番号
0FH(_FOPEN)
コール手順
DE オープンされていないFCBへのポインタ
戻り値
L=A 0FFH ファイルが見つからない場合
    0    ファイルが見つかった場合
解説

 オープンされていないFCBにはドライブ(カレントドライブを示す場合には0)とファイル名と拡張子(ワイルドカードを使用してよい)が入っていなければなりません。指定したドライブのカレントディレクトリで適合するファイルが検索され、見つかった場合にはそれがオープンされます。サブディレクトリやシステムファイルのエントリは無視され、ファイル名にワイルドカードを使用した場合には最初の適合するエントリがオープンされます。
 デバイス名は(コロンなしで)FCB中に置くことができ、その場合にはデバイスをあたかもディスクファイルであるかのようにアクセスすることができます。標準のデバイス名は13.1「デバイスおよび文字I/O」で定義されています。
 エクステント番号(extent number)の下位バイトはこのファンクションでは変更されず、ファイルはそれが指定された大きさを十分保持している場合にのみオープンされます。通常、アプリケーションプログラムではこのファンクションをコールする前にエクステント番号の上位バイトは0にセットされ、CP/Mとの互換性を確保しています。
 FCB中のファイル名と拡張子はディレクトリエントリからオープンされたファイルの実際の名前に置き換えられます。これは通常は元のものと同一ですが、ワイルドカードを使ったファイル名やファイル名中に小文字を使用している場合には異なることもあります。
 レコードカウントは、1レコードあたり128バイトとしてファイルのサイズから計算した値を、指定のエクステント中のレコードサイズにセットします。ファイルサイズのフィールド、ボリュームID、および8つの予約バイトもセットアップされます。カレントレコードおよびランダムレコードのフィールドはこのファンクションでは変更されません。読み出しあるいは書き込みのファンクションを使用する前にそれらを初期化するのはアプリケーションプログラムの責任となります。
 ファイルが見つからない場合には、環境変数「APPEND」が調べられます。これがセットされていると、ファイルを検索するべき2番目のディレクトリを指定するドライブ・パス文字列として解釈されます。指定のディレクトリでファイルを検索し、見つかった場合には前述のようにオープンします。この場合、元のFCBのドライブバイトがデフォルト(0)であれば、正しくファイルがアクセスできるようにドライブバイトをファイルが見つかったドライブにセットします。

ファイルのクローズ[FCB] [CP/M][DOS1]

機能番号
10H(_FCLOSE)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  0FFH  失敗した場合
     0     成功した場合
解説

 FCBはOPENまたはCREATファンクションコールのどちらかを使ってあらかじめオープンされていなければなりません。ファイルが読み出されただけであった場合、このファンクションは何もしません。ファイルに書き込みが行われていた場合には、バッファされていたすべてのデータがディスクに書き出され、ディレクトリのエントリが適切に更新されます。
 ファイルはクローズ後もアクセスできるため、このファンクションは「確保」ファンクションと同等なものと考えることができます。

最初のエントリの検索[FCB] [CP/M][DOS1]

機能番号
11H (_SFIRST)
コール手順
DE  オープンされていないFCBへのポインタ
戻り値
L=A  0FFH  失敗した場合
     0     成功した場合
解説

 このファンクションはFCB中の指定のドライブ(FCBのドライブ番号が0の場合はカレントドライブ)のカレントディレクトリで、FCB中のファイル名と拡張子に適合するファイルを検索します。ファイル名はワイルドカードが使用でき(「?」文字を含んでいる)、その場合には最初に適合するものが検索されます。エクステントフィールドの下位バイトが使用され、このエクステント番号を含むのに十分な大きさがあるファイルのみ見つかります。通常、このファンクションをコールする前に、エクステントフィールドをプログラムによって0にセットします。システムファイルおよびサブディレクトリのエントリは検索されません。
 適合するものが見つかった場合(A=0)、ディレクトエントリはDTA(ディスク転送アドレス)にコピーされ、前にドライブ番号がつけられます。これは、OPENファンクションコールでFCBとして直接使用することができます。エクステント番号は検索するFCBの下位バイトの値にセットされ、レコードカウントは適切に初期化されます(OPENの場合と同様)。ディレクトリエントリの属性バイトはS1バイトの位置にストアされますが、その通常の位置(ファイル名拡張フィールドの直後)がエクステントバイトのために使用されるからです。
 適合するものが見つからなかった場合(A=0FFH)、DTAは変更されません。いかなる場合も、DEで指されるFCBはまったく変更されません。このファンクションはシステム内部で必要な情報を記憶しており、「次のエントリの検索」ファンクション(P.278参照)で検索を続行することができるため、「次のエントリの検索」ファンクションを実行する場合にFCBを保存しておく必要はありません。
 CP/Mではこのファンクションでドライブ番号が「?」にセットされていると、すべてのディレクトリエントリ(割り当てられているものも解放されているものも)が適合します。また、エクステントフィールドが「?」にセットされるとファイルのすべてのエクステントが適合します。このような機能のどちらも、通常CP/Mのファイルシステム特有の特殊な目的のCP/Mプログラム(例えば「STAT」)でのみ使用されます。どちらの機能も、MSX-DOS1およびMSX-DOS2には存在しません。

次のエントリの検索[FCB] [CP/M][DOS1]

機能番号
12H(_SNEXT)
コール手順
なし
戻り値
L=A  0FFH  ファイルが見つからない場合
     0     ファイルが見つかった場合
解説

 このファンクションはファイル名に適合する次のファイルの検索を続行します。返される結果はに使用される情報はMSX「最初のエントリの検索」と同一ですので、そちらの説明を参照して下さい。検索を続行するためMSX-DOSの内部で保持され、「最初のエントリの検索」で使用した元のFCBはなくてかまいません。このファンクションは「最初のエントリの検索」ファンクションを実行した後でのみ使用可能です。

ファイルの削除[FCB] [CP/M][DOS1]

機能番号
13H(_FDEL)
コール手順
DE  オープンされていないFCBへのポインタ
戻り値
L=A  0FFH  ファイルがひとつも削除されなかった場合
     0     ファイルの削除が成功した場合
解説

 FCBで指定したドライブのカレントディレクトリ中でFCB中のワイルドカードを使用したファイル名に適合するすべてのファイルが削除されます。サブディレクトリ、システムファイル、不可視、読み出し専用ファイルは削除されません。このファンクションはなんらかのファイルの削除に成功した場合には、A=0として終了します。A=FFHでの終了はファイルが一つも削除されなかったことを示します。

シーケンシャル読み込み[FCB] [CP/M][DOS1]

機能番号
14H(_RDSEQ)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  01H  エンドオブファイルでのエラーの場合
     0    読み出しが成功した場合
解説

 このファンクションはファイルから次に続く128バイトのレコードを読み出し、現在のディスク転送アドレス(DTA)に入れます。れこーどは現在のエクステント(上位および下位バイト)とカレントレコードによって指定されます。レコードの読み出しに成功sルウと、このファンクションはカレントレコードを1つ増やし、それが80Hに達したらそれを0に戻して、エクステント番号を増やします。レコードカウントフィールドも、必要ならば常に更新されます。
 MSX-DOSではCP/Mとは異なり、ファイルのサイズが128バイトの倍数である必要はないので、一部だけで埋められたレコードができることがあります。この場合、断片レコードはそれが外部プログラムのDTAアドレスにコピーされるときに残りが0で詰められます。

シーケンシャル書き込み[FCB] [CP/M][DOS1]

機能番号
15H(_WRSQEQ)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  01H  ディスクが一杯でエラーの場合
     0    書き込みが成功した場合
解説

 このファンクションは現在のディスク転送アドレスから128バイトをファイルに書き出します。レコードはカレントレコードおよびエクステントによって指定されます。その後レコード呼びエクステントを適切に増やします。レコードカウントバイトはファイルが拡張された場合、または書き込みが新しいエクステントに移動した場合、正しく更新されます。FCB中のファイルサイズもファイルが拡張されたときには更新されます。

ファイルの作成[FCB] [CP/M][DOS1]

機能番号
16H(_FMAKE)
コール手順
DE  オープンされていないFCBへのポインタ
戻り値
L=A  0FFH  失敗
     0     成功
解説

 このファンクションは指定のドライブのカレントディレクトリ中に新しいファイルを作成し、読み込みおよび書き込みのためにオープンします。ドライブ、ファイル名、およびエクステント番号の下位バイトはFCB中にセットアップされていなければなりません。その際に、ファイル名にワイルドカードを使用することはできません。また、不正なファイル名が生成sレ内容にチェックが行われます。
 要求された名前のファイルが既に存在する場合には、動作はエクステント番号バイトの値によって異なります。通常これは0で、その場合には古いファイルが削除されて新しいファイルが作成されます。エクステント番号が0でない場合には、新しいファイルは作成されず、既存のファイルがオープンされます。それぞれのエクステントが明示的に作成されなければならなかったCP/Mの初期バージョンとの互換性がこれによって保証されます。
 どの場合も、OPENファンクションコールが実行されたのとまた駆動用に、処理されたファイルは所定のエクステント番号にしたがってオープンされます。

ファイル名の変更[FCB] [CP/M][DOS1]

機能番号
17H(_FREN)
コール手順
DE  オープンされていないFCBへのポインタ
戻り値
L=A  0FFH  失敗
     0     成功
解説

 オープンされていないFCBは通常のドライブとファイル名、および(DE+17)から始まる2番目のファイル名を持ちます。最初のファイル名に適合する指定のドライブのカレントディレクトリ中のそれぞれのファイルは2番目のファイル名中にある「?」文字については対応する文字を元のままmにして、2番目のファイル目に変更されます。また、ファイル名の重複や不正なファイル名が作成されるのを防ぐため、チェックが行われます。サブディレクトリやシステムファイル、不可視の名前を変更することはできません。

ログインベクタの獲得 [CP/M][DOS1][エラー処理]

機能番号
18H(_LOGIN)
コール手順
なし
戻り値
HL  ログインベクタ
解説

 このファンクションは利用できるそれぞれのドライブについてHLに対応するビットをセットして返します(Lのビット0がドライブ「A:」に対応する)。8つまでのドライブ(「A:」から「H:」まで)が現在のシステムでサポートされ、Hレジスタはリターン時には通常0になります。

カレントドライブの獲得 [CP/M][DOS1][エラー処理]

機能番号
19H(_CURDRV)
コール手順
なし
戻り値
L=A  カレントドライブ(0=A:など)
解説

 このファンクションはカレントドライブの番号を返します。

ディスク転送アドレスのセット [CP/M][DOS1]

機能番号
1AH (_SETDTA)
コール手順
DE  要求するディスク転送アドレス
戻り値
なし
解説

 このファンクションはDEに渡されたアドレスをディスク転送アドレスとしてセットします。このアドレスはすべてのその後のFCBの読み出しおよび書き込みコールで使用され、「最初のエントリの検索[FCB]」(P.277参照)、「次のエントリの検索[FCB]」コール(P.278参照)ではディレクトリエントリをストアするために使用され、また「アブソリュートなセクタの読み出し・書き込み」コール(P.289、290参照)で使用されます。MSX-DOS2で新たに追加された「読み出し」および「書き込み」ファンクションでは使用されません。アドレスは「ディスクリセット」コール(P.275参照)によって80Hに戻されます。

アロケーション情報の獲得 [DOS1]

機能番号
1BH(_ALLOC)
コール手順
E  ドライブ番号(0=カレント、1=A:など)
戻り値
A   1クラスタあたりのセクタ数
BC  セクタサイズ(常に512)
DE  ディスク上のクラスタの総数
HL  ディスク上の未使用クラスタ数
IX  DPBへのポインタ
IY  最初のFATセクタへのポインタ
解説

 このファンクションは指定のドライブ中のディスクについての様々な情報を返します。このファンクション番号をアロケーションベクタのアドレスを返すために使用しているCP/Mとの互換性はありません。MSX-DOS1と異なり、FATの最初のセクタだけがIY中のアドレスからアクセスでき、そこのデータは次のMSX-DOSコールまでしか有効ではありません。

ランダム読み出し[FCB] [CP/M][DOS1]

機能番号
21H(_RDRND)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  01H  エンドオブファイルでエラーの場合
     0    読み出しが成功の場合
解説

 このファンクションはファイルから128バイトのレコードを読み出して、現在のディスク転送アドレス(DTA)に入れます。ファイルの位置はFCBの3バイトのランダムレコード番号(21H〜23H)で決まります。CP/Mと異なり、ランダムレコード番号の3バイトすべてが使用されます。ファイルの終わりにある断片レコードはユーザーのDTAにコピーされる前に0で詰められます。
 ランダムレコード番号は変更されないため、このファンクションへの連続的なコールでは、外部プログラムがランダムレコード番号を変更しない限り同じレコードを読みます。副作用として、カレントレコードおよびエクステントはランダムレコード番号と同じレコードを参照するようにセットアップされます。つまり、連続的な読み出し(あるいは書き込み)をランダムな読み出しの後で実行でき、その場合には同じレコードから始まるということです。レコードカウントバイトもそのエクステントに対して正しくセットアップされます。

ランダム書き込み[FCB] [CP/M][DOS1]

機能番号
22H(_WRRND)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  01H  ディスクが一杯でエラーの場合
     0    エラーが起きなかった場合
解説

 このファンクションは現在のディスク転送アドレス(DTA)から128バイトのレコードをファイルに書き出します。書き込みは3バイトのランダムレコード番号(21H〜23H)で指定されるレコードの位置に行われます。ランダムレコード番号は3バイトすべてが使用されます。レコードの位置が現在のエンドオブファイルを超えている場合、初期化されていないディスク領域がその間を埋めるために割り当てられます。
 ランダムレコード番号のフィールドは変更されませんが、カレントレコードおよびエクステントのフィールドは同じレコードを参照するようにセットアップされます。レコードカウントバイトは、ファイルが拡張された場合、あるいは書き込みが新しいエクステントにまで及んだ場合には、必要に応じて調整されます。

ファイルサイズの獲得[FCB] [CP/M][DOS1]

機能番号
23H(_FSIZE)
コール手順
DE  オープンされていないFCBへのポインタ
戻り値
L=A  0FFH  ファイルが見つからない場合
     0     ファイルが見つかった場合
解説

 このファンクションは「ファイルのオープン」(P.275参照)と全く同じように、FCB中のファイル名に最初に一致するものを検索します。見つかったファイルのサイズは128バイト単位に切り上げられ、レコード数が決定されます。FCBの3バイトのランダムレコード領域がレコード数にセットされるため、それは存在しない最初のレコードの番号となります。ランダムレコード番号の4番目のバイトは変更されません。

ランダムレコードのセット[FCB] [CP/M][DOS1]

機能番号
24H(_SETRND)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
なし
解説

 このファンクションはFCB中の3バイトのランダムレコードフィールドをカレントレコードおよびエクステント番号によって決定されるレコードに設定します。ランダムレコード番号の4バイト目は変更されません。また、レコードがファイル中に実際に存在するかどうかについてのチェックは行いません。

ランダムブロック書き込み[FCB] [DOS1]

機能番号
26H(_WRBLK)
コール手順
DE  オープンされたFCBへのポインタ
HL  書き込むレコード数
戻り値
A   01H  エラー
    0    成功
解説

 現在のディスク転送アドレス(DTA)からランダムレコード番号によって決まるファイル中の位置へデータを書き込みます。ファイルをオープンした後でしかもこのファンクションをコールする前に、ユーザーによって設定されるFCB中のレコードサイズ領域(0EHおよび0FH)によってレコードのサイズは決まります。レコードのサイズが64バイトよりも小さい場合、ランダムレコード番号の4バイトすべてが使用され、それ以外の場合には最初の3バイトだけが使用されます。
 書き込むレコード数はHLによって指定し、レコードサイズとこれとで書き込むデータの合計が決まります。これが64Kを超える場合にはエラーが返されるため、転送の最大サイズが制限されます。
 データを書き込んだ後、ランダムレコード領域はファイル中の次のレコード番号に修正(つまり、HLがそれに加算)されます。カレントレコードおよびエクステントの領域は使用されず、変更もされません。ファイルが拡張された場合にはファイルサイズ領域が更新されます。
 レコードサイズは1〜0FFFFHの任意の値です。小さいレコードサイズは大きいレコードサイズに効率では劣らないため、レコードサイズは1にセットすることもでき、その場合にはレコードカウントはバイトカウントになります。1回のファンクションコールでできる限り多くのバイト数の書き込みを行う方が速度的に望ましいでしょう。
 書き込むレコード数(HL)が0の場合、データh書き込まれず、ファイルのサイズがランダムレコード領域で指定した値に変更されます。これはファイルサイズの現在のサイズより大きくても小さくてもかまわず、必要に応じてディスクの領域が割り当てられたり開放されたりします。この方法で割り当てられた追加のディスク領域は、特定の値に初期化されることはありません。

ランダムブロック読み出し[FCB] [DOS1]

機能番号
27H(_RDBLK)
コール手順
DE  オープンされたFCBへのポインタ
HL  読み出すレコード数
戻り値
A   01H  エラー、通常エンドオブファイル
    0    成功
HL       実際に読んだレコード数
解説

 このファンクションは上記のブロックの書き込みファンクションと対をなすものであり、その使用法もほとんど同じです。この場合も大きなブロックを読むと、通常のCP/Mの処理よりもかなり早くなります。
 例えば、ファイルから20Kを読みたい場合、1Kごとに20回の別々のファンクションコールを行うより、1回のファンクションコールで20Kを読む方が良い方法といえます。ただし20Kの読み込みをレコードサイズ1、レコードカウント20Kとして行うか、レコードサイズ20K、レコードカウント1として行うか、あるいはその中間の組み合わせで行うかと言うことに関しては違いありません。
 実際に読んだレコードの数がHLに返されます。エンドオブファイルになった場合、(この場合、断片レコードになれば、ユーザーのDTAにコピーする前に0で詰められます)このかずは要求されたレコードの数よりも小さいことがあります。ランダムレコード領域は読まれていない最初のレコードに修正(つまり、HLに返される値がそれに加算)されます。

ゼロフィルを行うランダム書き込み[FCB][CP/M][DOS1]

機能番号
28H(_WRZER)
コール手順
DE  オープンされたFCBへのポインタ
戻り値
L=A  01H  エラー
     0    成功
解説

 このファンクションは「ランダムな書き込み」(P.283参照)と同じですが、ファイルを拡張しなければならい場合に、データが書き込まれる前に新たに割り当てられたすべてのディスククラスタが0で埋められます。

日付の獲得 [DOS1][エラー処理]

機能番号
2AH(_GDATE)
コール手順
なし
戻り値
HL  年    1980〜2079
D   月    1=1月〜12=12月
E   日    1〜31
A   曜日  0=日曜〜6=土曜
解説

 このファンクションは上記のような形式で内部のカレンダーの現在の値を返します。

日付のセット [DOS1][エラー処理]

機能番号
2BH(_SDATE)
コール手順
HL  年    1980〜2079
D   月    1=1月〜12=12月
E   日    1〜31
戻り値
A   00H   日付が有効
    FFH   日付が無効
解説

 与えられた日付は有効性をチェックされ、有効ならば新しい日付としてセットされます。有効性のチェックはそれぞれの月の日数や閏年に付いても完全に行われます。日付が無効の場合、現在の日付は変更されません。日付はリアルタイムクロックチップに保持されるため、マシンの電源を切っても更新されています。

時刻の獲得 [DOS1][エラー処理]

機能番号
2CH(_GTIME)
コール手順
なし
戻り値
H   時間     0〜23
L   分       0〜59
D   秒       0〜59
E   1/100秒  常に0
解説

 このファンクションは上記の形式でシステムクロックの現在の値を返します。
 クロックチップが1/100秒単位で計時できないため、Eレジスタには常に0が返されます。

時刻のセット [DOS1][エラー処理]

機能番号
2DH(_STIME)
コール手順
H   時間     0〜23
L   分       0〜59
D   秒       0〜59
E   1/100秒  無視される
戻り値
A   00H      時刻が有効
    FFH      時刻が無効
解説

 このファンクションは内部のシステムクロックを指定の時刻の値にセットします。時刻が無効であると、Aレジスタは0FFHとして返されてエラーを示し、現在の時刻は変更されません。時刻はリアルタイムクロックチップに保持されるため、マシンの電源を切っても更新されます。
 クロックチップが1/100秒単位で設定できないため、Eレジスタの値は無視されます。

ベリファイフラグのセット・リセット[DOS1][エラー処理]

機能番号
2EH(_VERIFY)
コール手順
E  0      ベリファイを無効に
   0以外  ベリファイを有効に
戻り値
なし
解説

 このファンクションはすべての書き込みの際の自答的なベリファイを有効あるいは無効にします。MSX-DOSが起動したときにはデフォルトであオフになっています。ベリファイを有効にするとシステムの信頼性は向上しますが、同時に書き臣のスピードが低下します。また、この機能はディスクドライバに依存するため、ドライバがサポートしていないとベリファイ動作は行われません。

アブソリュートなセクタの読み出し [DOS1][エラー処理]

機能番号
2FH(_RDABS)
コール手順
DE  セクタ番号
L   ドライブ番号        0=A:など
H   読み出すセクタ番号
戻り値
A   エラーコード        0=エラーなし
解説

 このファンクションはセクタをファイルとして解釈することなしに、ディスクからセクタを直接読み出します。セクタ番号をディスク上の物理的な位置に変換するため、ディスクは有効なDOSのディスクでなければなりません。セクタは現在のディスク転送アドレスに読み出されます。ディスクエラーは通常の方法で知らされます。

アブソリュートなセクタの書き込み [DOS1][エラー処理]

機能番号
30H(_WRABS)
コール手順
DE  セクタ番号
L   ドライブ番号        0=A:など
H   書き込むセクタ数
戻り値
A   エラーコード        0=エラーなし
解説

 このファンクションはセクタをファイルとして解釈することなしに、ディスクへセクタを直接書き込みます。セクタ番号をディスク上の物理的な位置に変換するため、ディスクは有効なDOSのディスクでなければなりません。セクタは現在のディスク転送アドレスから書き込まれます。ディスクエラーは通常の方法で知らされます。

ディスクパラメータの獲得 [エラー処理]

機能番号
31H(_DPARM)
コール手順
DE  ディスクパラメータ(32バイトのバッファ)へのポインタ
L   ドライブ番号
     0=カレントドライブ、1=A:など
戻り値
A   エラーコード
DE  保存される
解説

 このファンクションは、指定のドライブ中のディスクのフォーマットに関する一連のパラメータをユーザープログラム内に確保されたバッファへ返します。これはアブソリュートなセクタの読み出しおよび書き込みを行うプログラムが、アブソリュートなセクタ番号を解釈する場合に有用です。返されるパラメータには外部プログラムが使用するのに便利なパラメータを提供するために、幾分余分な情報が含まれています。返されるパラメータブロックのフォーマットを以下に示します。,オフセット ,意味

DE+1,2セクタサイズ(現在は常に512)
DE+3クラスごとのセクタ数
(2のn乗。ただしnは1以上の整数)
DE+4,5予約セクタ数(通常1)
DE+6FATの数(通常2)
DE+7,8ルートディレクトリのエントリ数
DE+9,10論理セクタの総数
DE+11メディアディスクリプタバイト
DE+12FATごとのセク多数
DE+13,14ルートディレクトリの最初のセクタ番号
DE+15,16最初のデータのセクタ番号
DE+17,18最大クラスタ番号
DE+19ダーティディスクフラグ
DE+20〜23ボリュームID(-1=ボリュームIDなし)
DE+24〜31システム予約(現在は常に0)
 ダーティディスクフラグは、ディスク中にUNDELコマンドで復活できるファイルがあることを示すフラグです。したがって、ファイルあるいはディレクトリにクラスタが割り当てられるとこのフラグはリセットされます。

最初のエントリの検索

機能番号
40H(FFIRST)
コール手順
DE    ドライブ・パス・ファイル ASCIIZ文字列またはFIBポインタ
HL    検索ファイル名 ASCIIZ文字列(DE=FIBポインタである場合のみ)
B     検索属性
IX    新しいFIBへのポインタ
戻り値
A     エラーコード
(IX)  一致するエントリが入る
解説

 文字列の「ドライブ・パス」部分、あるいはFIB(ファイル情報ブロック)は検索するディレクトリを指定します。ファイルを指定するFIBが渡されると、「.IATTR」エラーが返されます。文字列の「ファイル」部分、あるいはHLが指す検索ファイル名ASCIIZ文字列は、どういったファイル名を一致させるかを決定します。一致したものがない場合には「.NOFIL」エラーが返され、有った場合にはIXによって指されるFIBが一致するエントリの情報で満たされます。
 このファイル目にはワイルドカード文字(「?」および「*」)を含めてもよく、その場合には最初に一致するエントリが返されます。ファイル名がヌル(DEで指されるASCIIZ文字列がヌルであるか「\」で終わっているか、あるいはHLで指される検索ファイル名文字列がヌルの場合)であると、このファンクションはあたかもファイル名が「*.*」であるかのように振るまい、従ってすべての名前が一致します。
 Bレジスタ中の属性バイトは一致するエントリのタイプを指定します。これが0だと、不可視でもシステムファイルでもないファイルだけが見つけられます。Bレジスタにディレクトリ、不可視あるいはシステムビットがセットされていると、これらの属性を持つエントリが通常のファイルとともに一致するようになります。Bレジスタの読み出し専用およびアーカイブビットは無視されます。
 Bレジスタのボリューム名ビットがセットされると検索は排他的に行われ、ボリュームラベルのエントリだけが検索されます。この場合にはまた指定を除いて無視されます。つまり、ボリューム名は指定のファイル名に一致するかどうかに関わらず、もし存在すれば、ルートディレクトリ中で見つけられます。
 DEがFIBを指している場合、必要ならIXも同一のFIBを指すことができます。この場合、一致するものが見つかると、新しいFIBは古いものを重ね書きします。

次のエントリの検索

機能番号
41H(_FNEXT)
コール手順
IX    以前の最初のエントリを検索するファンクションから返されたFIBへのポインタ
戻り値
A     エラー
(IX)  次の一致するエントリが入る
解説

 このファンクションは「最初のエントリの検索」ファンクションコールの後でのみ使用しなければなりません。これは「最初のエントリの検索」ファンクションコールに与えた(ワイルドカードを使用したしような)ファイル名に一致する次のエントリをディレクトリで探します。それ以上一致刷るエントリが存在しない場合には「.NOFIL」エラーが返され、存在した場合には、FIBが新しい一致するエントリの情報で満たされます。

新しいエントリの検索

機能番号
42H(_FNEW)
コール手順
DE   ドライブ・パス・ファイルASCIIZ文字列またはFIBポインタ
HL   検索ファイル名ASCIIZ文字列(DE=FIBポインタの場合のみ)
B    b0〜b6=要求する属性、b7=新規作成フラグ
IX   「テンプレートファイル名」を保持している新しいFIBへのポインタ
戻り値
A    エラー
(IX) 新しいエントリが入る
解説

 このファンクションは前述の「最初のエントリの検索」ファンクション(P.291参照)と大変よく似ています。HLおよびDE中のパラメータは全く同じ方法で使用され、ディレクトリエントリを指定シャムス。ただし、選択したディレクトリで指定された名前に一致するエントリを検索する代わりに、新しいエントリがこの名前で作成されます。IXで指されるFIBにはあたかも「最初のエントリの検索」コールで見つかったかのように新しい年取りについての情報がセットされます。
 ファイル名中にワイルドカード文字(「?」あるいは「*」)があると、それらはIXで指される新しいFIBのファイル名の位置にある「テンプレートファイル名」空の適切な文字に置き換わります。その結果がそれでもワイルドカード文字が残ったり、あるいは不正であったりすると「.IFNM」エラーが返されます。これは、自動的に名前を変更するコピー処理を行う場合に有用です。
 「最初のエントリの検索」と同様、ファイル名がヌルであると、「*.*」であるのと全く同じに扱われます。このファンクションでの場合それは「テンプレートファイル名」が新しく作成されるファイル名として使用されることを意味します。
 ルートディレクトリに領域がないと「.DRFUL」エラーが返されます。また、サブディレクトリを拡張する必要があるにもかかわらず、ディスクがいっぱいである場合には「.DKFUL」エラーが返されます。
 Bレジスタ中に渡される属性バイトは新しいエントリに付与すべき属性です。ボリューム名ビットがセットされていると、ルートディレクトリ中にボリューム名が作成されます。ディレクトリビットがセットされていると、作成されるエントリはサブディレクトリとなり、そうでない場合にはファイルとなります。ファイルには、システム、不可視、および読み出しビットがセットでき、サブディレクトリには不可視ビットがセットできます。ファイルは常にアーカイブ属性ビットをセットして作成されます。
 ファイルは現在の日付と時刻で長さ0で作成されます。サブディレクトリの場合には1宇野クラスタが割り当てられ、「.」および「..」エントリが適切に初期化されます。
 指定した名前のエントリがディレクトリ中に既に存在した場合、動作は「新規作成フラグ」(Bレジスタのビット7)、およびエントリのタイプによって異なります。「新規作成フラグ」がセットされていると、常に「.FILEX」エラーが返されます。従ってこのフラグをセットすると、既存のファイルが削除されないことが保証されます。
 既にエントリが存在し、「新規作成フラグ」がセットされていないと、既存のエントリのタイプが調べられて、それが新しいファイルを作成するために削除できるかどうかを判断します。エントリが読み出し専用ファイル(「.FILRO」エラー)、システムファイル(「.SYSX」エラー)、あるいはサブディレクトリ(「.DIRX」エラー)である場合、また、このファイルに対して既にオープンしているファイルハンドル(「.FOPEN」エラー)が存在する場合、エラーが返されます。サブディレクトリを作成しようとしているときは、通常のファイルであっても削除されません(「.FILEX」エラー)。
 これらのエラー(「.FILEX」、「.FILRO」、「.SYSX」、「.DIRX」、「.FOPEN」)が発生すると、既存のエントリの情報がFIBに書き込まれます。このFIBはあたかも「最初のエントリの検索」ファンクションで返されたこのように使用することができます。

ファイルハンドルのオープン

機能番号
43H(_OPEN)
コール手順
DE    ドライブ・パス・ファイル ASCIIZ文字列またはFIBポインタ
A     オープンモード
      b0セット   書き込み禁止
      b1セット   読み出し禁止
      b2セット   継承
      b3〜b7     必ずクリア
戻り値
A     エラー
B     たらしいファイルハンドル
解説

 ドライブ・パス・ファイル文字列あるいはFIBは通常、サブディレクトリあるいはボリューム名でなく、ファイルを参照しなければなりません。これがボリューム名であると「.IATTR」エラーが返されます。これがサブディレクトリであると「.DIRX」エラーが返されます。
 ファイルが指定されたとすると、それは読み出しおよび書き込み、あるいはその両方(Aレジスタ中のオープンモードによる)ができるようにオープンされ、そのための新しいファイルハンドルがBレジスタに返されます。利用できる最小のファイルハンドル番号が使用され、ファイルハンドルの領域がない場合(「.NHAND」エラー)、メモリ不足の場合(「.NORAM」エラー)にはエラーとなります。
 Aレジスタの「読み出し禁止ビット」がセットされると、ファイルハンドルからの読みだしは拒否され、どちらの場合も「.ACCV」エラーとなります。ファイルが読み出し専用の場合も書き込み拒否されます(「.FILRO」エラー)。Aレジスタの「継承ビット」がセットされていると、「子プロセスの起動」ファンクションコール(P.318参照)によって生成された新しいプロセスにファイルハンドルが受け継がれます。
 デバイスのファイルハンドルが組み込みデバイス(例えば「CON」や「NUL」)のひとつに一致するファイル名を与えられてオープンされると、それは最初は常にASCIIモードでオープンされます。「デバイスのI/O制御」(P.302参照)を使用して、これをバイナリモードに変更することができますが、エンドオブファイルの状態が存在しないため、デバイスからバイナリモードで読む場合には慎重に行わなければなりません。

ファイルハンドルの作成

機能番号
44H(_CREATE)
コール手順
DE   ドライブ・パス・ファイル ASCIIZ文字列
A     オープンモード
      b0セット   書き込み禁止
      b1セット   読み出し禁止
      b2セット   継承
      b3〜b7     必ずクリア
B     b0〜b6     要求する属性、b7=新規作成フラグ
戻り値
A     エラー
B     新しいファイルハンドル
解説

 ファイルまたはサブディレクトリ(Bレジスタの属性の指定による)がドライブ・パス・ファイル文字列によって指定される名前およびそのディレクトリ中に作成されます。Bレジスタがボリューム名を指定していると「.IATTR」エラーが返されます。
 ファイルまたはサブディレクトリが作成できないとエラーが返されます。この場合のエラーの状態は「新しいエントリの検索」ファンクション(P.291参照)のものと同じで、主なエラーコードは「.FILEX」、「.DIRX」、「.SYSX」、「.FILRO」、「.FOPEN」、「.DRFUL」、あるいは「.DKFUL」です。「新しいエントリの検索」ファンクションと同様、「新規作成フラグ」(Bレジスタのビット7)がセットされていると、既存のファイルは削除されず、「.FILEX」エラーが常に返されます。
 属性バイトがサブディレクトリを指定している場合には、不可視ビットをセットして不可視のサブディレクトリを作成することもできます。ファイルの場合は不可視、システム、あるいは読み出し専用ビットをセットしてそれぞれの属性を持ったファイルを作成することができます。不正な属性ビットは無視されます。ファイルは常にアーカイブビットをセットして作成されます。
 ファイルは前述の「ファイルハンドルのオープン」ファンクション(P.295参照)の場合と同様、自動的にオープンされ、ファイルハンドルがBレジスタに返されます。「オープンモード」パラメータは、「ファイルハンドルのオープン」ファンクションの場合と同様に解釈されます。サブディレクトリはオープンされない(これをオープンするのは無意味)ため、Bレジスタに有効なファイルハンドルとはなり得ない0FFHが返されます。

ファイルハンドルのクローズ

機能番号
45H(_CLOSE)
コール手順
B   ファイルハンドル
戻り値
A   エラー
解説

 このファンクションは指定のファイルハンドルを解放して再利用できるようにします。ハンドルにファイルが書き込まれていると、そのディレクトリエントリが新しい日付と時刻で更新され、アーカイブ属性ビットがセットされ、そしてすべてのバッファ中のデータがディスクに書き出されます。このファイルハンドルを続けて使おうとするとエラーとなります。「ファイルハンドルの複製」(P.297参照)や「子プロセスの起動」ファンクション(P.318参照)で作成されたこのファイルハンドルのコピーが別に存在する場合には、これらのコピーは続けて使用することができます。

ファイルハンドルの確保

機能番号
46H(_ENSURE)
コール手順
B   ファイルハンドル
戻り値
A   エラー
解説

 ファイルハンドルにファイルが書き込まれていると、そのディレクトリエントリが新しい日付と時刻で更新され、アーカイブ属性ビットがセットされ、そしてすべてのバッファ中のデータがディスクに書き出されます。ファイルハンドルは解放されないため、それを使用して続けてファイルをアクセスすることができ、現在のファイルポインタの設定は変わりません。

ファイルハンドルの複製

機能番号
47H(_DUP)
コール手順
B   ファイルハンドル
戻り値
A   エラー
B   新しいファイルハンドル
解説

 このファンクションは指定のファイルハンドルのコピーを作成します。利用できる最小のファイルハンドル番号が常に使用され、利用できるものがないと最初のファイルハンドル番号が常に使用され、利用できるものがないと「.NHAND」エラーが返されます。新しいファイルハンドルはもとのものと同一のファイルを参照し、そのどちらを使用してもかまいません。一方のファイルハンドルポインタが移動されると他方もまた移動されます。どちらかのハンドルがクローズしても、他方は続けて使用できます。
 このファンクションで作成される複製ファイルハンドルは「別々にオープンされた」ものではないため「.FOPEN」エラーを生成するような別々のファイルハンドルとはみなされないことに注意してください。たとえば、「複製」ファイルハンドルは名前を変更したり(P.309参照)、その属性を変更したり(P310参照)できますが、その効果は両方のハンドルにおよびます。
 特に、「複製」ファイルハンドルの一つのコピーが削除される(P.310参照)と、ファイルは実際に削除されるので、他方のファイルハンドルはオープンしたままの状態ですが、安全に使用することができなくなることに注意してください。それが(クローズ、確保、あるいは削除以外で)使用されると「.HDEAD」エラーが返されます。

ファイルハンドルからの読み出し

機能番号
48H(_READ)
コール手順
B   ファイルハンドル
DE  バッファアドレス
HL  読み込むバイト数
戻り値
A   エラー
HL  実際に読み込んだバイト数
解説

 指定されたバイト数をファイルの現在のファイルポインタの位置からDEレジスタで指定されたバッファアドレスへ読み込み、ファイルポインタはsれに続くバイトに更新されます。ファイルハンドルが「読み出し禁止」アクセスビットをセットしてオープンされた場合には、「.ACCV」エラーが返されます。
 読み込みまれたバイト数は要求された数よりも少ない場合も有り、エラーが少ない場合にはレジスタHLに読み込まれた数が返されます。一般的には、要求要理も少ない数が読み込まれた場合、エラー状態としては扱ってはならず、「.EOF」エラーが返されるまでは、続きを読むためにさらに読み出しを行わなければなりません。「.EOF」エラーは部分的な読み出しでは返されることはなく、0バイトを読む読み出しの場合にだけ返されます。このようなファイルの読み出しはデバイスファイルハンドルが正しく動作することを保証します。
 ディスクファイルでは、読まれたバイト数はエンドオブファイルに達した場合にのみ要求した数よりも少なくなり、この場合、次の読み出し処理が0バイトを読んで、「.EOF」エラーを返します。デバイスファイルハンドル(例えば0から4の標準ファイルハンドル)から読み出すと、その動作はそれぞれのデバイスによって異なり、また、その読み出しのモードがASCIIかバイナリであるかによっても異なります(後述のファンクションを参照)。最も一般的に使用されるデバイスである「CON」デバイスを例にとって説明しますが、ほかのデバイスも同様に動作します。
 「CON」デバイスからバイナリモードで読み出すと、変換されたり、画面やプリンタにエコーされることなしに、キーボードから文字が読み出されます。要求された正確な文字数が常に読まれ、エンドオブファイルの状態は存在しません。エンドオブファイルの状態が存在しないため、バイナリモードでデバイスを読み出すときには慎重に行わなければなりません。
 「CON」デバイスからASCIIモード(デフォルトモードで、標準入力チャンネルに通常適用される)での読み出しファンクションコールは、入力を1行読むだけです。入力行は、通常の行編集機能をユーザーに利用できるようにして、キーボードから読み込まれ、入力された文字は画面にエコーされ、^Pが有効な場合にはプリンタにもエコーされます。特殊な制御文字「^P」、「^N」、「^S」、および「^C」が調べられ、「コンソールステータス」(P.274参照)の場合と全く同様に処理されます。
 ユーザーが⏎(リターン)キーを入力すると、行は読み出しバッファにコピーされ、CR-LFシーケンスが最後に付加され、適切なバイト数が読み出しファンクションから返されます。次のよう見出しは、別のバッファ省入力処理を開始します。読み出しで要求されたバイト数が行入力の長さよりも小さい場合には、要求と同じ文字数が返され、次の読み出しファンクションコールは行をすべて読んでしまうまで、その行の残りの部分を即座に返します。
 ユーザーが「^Z」文字で始まる行を入力すると、これはエンドオブファイルを示すものとして解釈されます。この行は捨てられ、読み出しファンクションコールは0バイトを読み、「.EOF」エラーを返します。これに続く読み出しは、通常に戻り、別の行入力を始めます。このように、エンドオブファイルの状態は永続的なものではありません。

ファイルハンドルへの書き込み

機能番号
49H(_WRITE)
コール手順
B   ファイルハンドル
DE  バッファアドレス
HL  書き込むバイト数
戻り値
A   エラー
HL  実際に書き込んだバイト数
解説

 このファンクションは「読み出し」ファンクション(P.298参照)と大変にています。指定のバイト数がファイル中の現在のファイルポインタの位置に書き込まれ、ファイルポインタは書き込まれた最終バイトの直後を指すように更新されます。ファイルが[書き込み禁止」アクセスビットをセットしてオープンされた場合には、「.ACCV」エラーが返され、ファイルが読み出し専用であると「.FILRO」エラーが返されます。
 書き込みが現在のエンドオブファイルを超えて行われると、ファイルは必要に応じて拡張されます。ファイルポインタが既にエンドオブファイルを超えていると、ディスク領域が間を埋めるために割り当てられ、初期化されません。ディスク領域が十分にないと、「.DKFUL」エラーが返され、データの一部を入れる余地があったとしても、データは全く書き込まれません。
 書き込まれたバイト数はエラーが返された場合には0、書き込みが成功した場合には要求した数と等しいため、通常は無視できます。多くの小さなブロックよりも少数の大きなブロックでファイルを書き込んだ方が効率的であるため、プログラムでは常にできる限り大きなブロックで書き込むようにした方が良いでしょう。
 このファンクションはファイルハンドルに「変更有り」ビットをセットし、それによって、ファイルハンドルが明示的にせよ暗黙にせよクローズされたり確保されたときに、ディレクトリエントリが新しい日付と時刻、および新しい割り当て情報で更新されます。また、アーカイブビットがセットされ、このファイルが最後にアーカイブされた後に変更されたということを示します。
 デバイスファイルハンドルへの書き込みは、エンドオブファイル状態や行入寮を考慮しなくてもよいため、読み出しのように複雑ではありません。「CON」デバイスへの読み込みの際に、ASCIIとバイナリモードとの間には、相違があり、コンソールステータスのチェックはASCIIモードでだけ実行されます。プリンタエコーが有功の場合も、ASCIIモードでだけ実行されます。

ファイルハンドルポインタの移動

機能番号
4AH(_SEEK)
コール手順
B      ファイルハンドル
A      方式コード
DE:HL  符号付きオフセット
戻り値
A      エラー
DE:HL  新しいファイルポインタ
解説

 指定したファイルファンドルに結合したファイルポインタを方式コードとオフセットに従って変更し、新しいポインタ値をDE:HLに返します。方式コードは符号付きオフセットがどこからの相対であるかを以下のように指定します。

 A=0  ファイルの先頭から相対
 A=1  現在の位置から相対
 A=2  エンドオブファイルから相対

 オフセット0を指定すると移動方式コード1は単に現在のポインタ値を返し、移動方式コード2はファイルの大きさを返すということに注意して下さい。エンドオブファイルのチェックは行われないので、ファイルポインタをエンドオブファイルを超えてセットすることは可能です。「ファイルハンドルの複製」(P.297参照)あるいは「子プロセスの起動」(P.318参照)で作成された、このファイルハンドルのコピーが有る場合には、それらのファイルポインタも変更されます。
 ファイルポインタはランダムアクセスが可能なディスクファイルでのみ実際に意味を持ちます。デバイスファイルでも、ファイルポインタはすべての読み出しあるいは書き込みの際適切に更新され、またこのファンクションで調べたり変更したりすることができます。しかし変更は効果がなく、それを調べることが役に立つ場合はまずありません。
 

デバイスのI/O制御

機能番号
4BH(_IOCTL)
コール手順
B   ファイルハンドル
A   サブファンクションコード
    00H   ファイルハンドルの状態獲得
    01H   ASCII・バイナリモードのセット
    02H   入力レディの検査
    03H   出力レディの検査
    04H   画面サイズの検出
DE  他のパラメータ
戻り値
A   エラー
DE  他の結果
解説

 このファンクションによって、ファイルハンドルの種々の状態を調べたり変更したりすることができます。特に、これを使用してファイルハンドルがディスクファイルを参照しているのかあるいはデバイスを参照しているのかを判断することができます。これは、ディスクファイルとデバイスI/Oで異なった動作をしたいプログラムで役に立ちます。
 このファンクションはBレジスタにファイルハンドル、Aレジスタに処理を指定するサブファンクションコードを渡して実行します。特定のサブファンクションで必要となる他のすべてのパラメータはDEレジスタに渡し、結果はDEレジスタに返ります。サブファンクションコードが不正だと、「.ISBFN」エラーが返されます。
 A=0だと処理は「ファイルハンドルステータスの獲得」となります。これは、ファイルハンドルに付いての種々の情報を与える1ワードのフラグを返します。この1ワードのフォーマットはデバイスファイルハンドルとディスクファイルハンドルでは異なり、ビット7がどちらかを指定します。このワードのフォーマットは次のとおりです。
・デバイスの場合

ビット意味
DE0 セット=コンソール入力デバイス
1 セット=コンソール出力デバイス
2〜4 システム予約
5 セット=ASCIIモード
クリア=バイナリモード
6 セット=エンドオブファイル
7 常にセット (=デバイス)
8〜15 システム予約

・ディスクファイルの場合

ビット意味
DE0〜5 ドライブ番号 (0=A:など)
6 セット=エンドオブファイル
7 常にクリア (=ディスクファイル)
8〜15 システム予約

 エンドオブファイルフラグがデバイスの場合とディスクファイルの場合で同じ位置にあることに注意してください。デバイスの場合には、デバイスからの直前の読み出しが「.EOF」エラーを生成したときにセットされ、次の読み出しによってクリアされます。ディスクファイルの場合にはファイルポインタとファイルサイズを比較することによって作り出されます。
 A=1のとき、処理は「ASCII・バイナリモードのセット」となります。この処理はデバイスファイルハンドルの場合にだけ実行できます。ASCII・バイナリフラグはレジスタEのビット5(「ファイルハンドルステータスの獲得」によってそれが返されるところ)に渡しておかなければなりません。これはASCIIモードではセット、バイナリモードではクリアとなります。DEレジスタの他のすべてのビットは無視されます。
 A=2または3のとき、処理はそれぞれ「入力レディの検査」または「出力レディの検査」となります。どちらの場合も、フラグがレジスタEに返され、ファイルハンドルがレディであるとFFH、そうでないと00Hとなります。「レディ」の意味はデバイスによって異なります。ディスクファイルハンドルは常に出力についてレディであり、ファイルポインタがエンドオブファイルに無い限り入力についてレディです。「CON」デバイスはキーボードの状態をチェックして、それが入力についてレディであるかどうかを判断します。
 A=4のとき、処理は「画面サイズの獲得」になります。これは行数をDレジスタに、列数をEレジスタに入れて、そのファイルハンドルの論理画面サイズを返します。画面サイズがないデバイス(ディスクファイルなど)では、DもEも0になります。したがって、どちらが0でも、それは「無限」と解釈します。例えば、このファンクションは1行に表示するファイルの数を判断するために「DIR /W」コマンドで使用され、Eレジスタの値が0の場合、デフォルトの80として扱います。

ファイルハンドルのテスト

機能番号
4CH(_HTEST)
コール手順
B      ファイルハンドル
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
戻り値
A      エラー
B      00H  同じファイルではない
       FFH  同じファイル
解説

 この特殊なファンクションには、ファイルハンドルとファイルを識別するドライブ・パス・ファイル文字列あるいはFIBブロックを渡します。このファンクションは2つのファイルが実際に同じファイルかどうかを判断し、その結果を示すフラグを返します。ファイルハンドルがディスクファイルでなくデバイスそのものである場合には、「同一ファイルでない」ことを示す「B=00H」が常に返ります。
 このファンクションによって、COPYコマンドがファイルをそのファイル自身の上にコピーしてしまうなどといったある種のエラーの状態を検知することができ、ユーザーにそうした情報をエラーメッセージとして表示することが可能です。これは、同様の検査が必要な他のプログラムでも使用できます。

ファイル・サブディレクトリの削除

機能番号
4DH(_DELETE)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
戻り値
A      エラー
解説

 このファンクションはドライブ・パス・ファイル文字列あるいはFIBで指定されるもの(ファイルあるいはサブディレクトリ)を削除します。ワイルドカード文字は許されず、このファンクションでは一つだけのファイルまたはサブディレクトリが削除できます。サブディレクトリは空である場合にのみ削除でき、空でないとエラー(「.DIRNE」となります。サブディレクトリ中の「.」と「..」のエントリは削除できず(「.DOT」エラー)、ルートディレクトリも削除できません。ファイルはオープンされているファイルハンドルがある場合(「.FOPEN」エラー)、あるいは読み出し専用である場合(「.FILRO」エラー)には、削除することができません。
 ファイルの場合、それに対して割り当てられていたすべてのディスク領域が解放されます。ディスクがMSX-DOS2のディスクであると、UNDELコマンドでファイルを復活するのに十分な情報がディスク上に残されます。この情報はそのディスクで次にディスク領域の割り当て(通常ファイルへの書き込み)が実行されるまで残されます。FIBが渡された場合には、このファンクションの実行後は、それを「次のエントリの検索」ファンクションに渡す場合以外には使用してはいけません。なぜならそれが参照しているファイルはもう存在しなくなっているからです。
 「CON」などのデバイス名が指定されるとエラーは返されませんが、そのデバイスは実際には削除されません。

ファイル名・サブディレクトリ名の変更

機能番号
4EH(_RENAME)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
HL     新しいファイル名 ASCIIZ文字列
戻り値
A      エラー
解説

 このファンクションはドライブ・パス・ファイル文字列あるいはFIBで指定されるファイルあるいはディレクトリを、HLで指される文字列中の新しい名前に変更します。新しいファイル名文字列にドライブ文字やディレクトリパスを含めると「.IFNM」エラーになります。「CON」などのデバイス名が指定されるとエラーは返されませんが、そのデバイスは実際には名前の変更はされません。
 ワイルドカード文字はドライブ・パス・ファイル文字列中では使用できません。したがってこのファンクションで名前を変更できるファイルあるいはサブディレクトリはひとつだけです。しかし、ワイルドカード文字はHL中に渡される新しいファイル名では使用でき、それが該当する位置では、既存のファイル名文字が変更されずに残ります。その際には、不正なファイル名が作成されるのを避けるため、チェックが行われます。例えば、「XYZ」というファイルは新しいファイル名文字列「????A」へは変更できません(新しいファイル名は「XYZA」となり、不正であるため)。この場合には「.IFNM」エラーが返されます。
 既に新しいファイル名と同じエントリが存在する場合には、エラー(「.DUPF」)が返されて重複したファイル名を作成するのが回避されます。サブディレクトリ中の「.」と「..」のエントリは名前を変更できず(「.IDOT」エラー)、ルートディレクトリ名の変更もできません(ルートには名前がない)。オープンされているファイルハンドルを持つファイル(「.FOPEN」エラー)はファイル名を変更できませんが、読み出し専用ファイルは名前を変更できます。
 DEがFIBを指していると、これは新しいファイル名に変更されないことに注意してください。したがって、このファンクションコールの実行後、FIBを使用する場合には、注意が必要です。

ファイルあるいはサブディレクトリの移動

機能番号
4FH(_MOVE)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
HL     新しいパス ASCIIZ文字列
戻り値
A      エラー
解説

 このファンクションはドライブ・パス・ファイル文字列あるいはFIBで指定されるファイルあるいはディレクトリを、HLで指される新しいパス文字列で指定されるディレクトリに移動します。新しい文字列中にはドライブ名があってはなりません。「CON」などのデバイス名が指定されるとエラーは返されませんが、そのデバイスは実際には移動されません。
 ワイルドカード文字はドライブ・パス・ファイル文字列中でも使用できないため、このファンクションで移動できるファイルもしくはサブディレクトリはひとつだけです。ただしサブディレクトリが移動された場合、その下にあるすべてのファイルおよびサブディレクトリは、それに従って移動されます。すでに移動先のディレクトリ中に指定の名前のエントリが存在すると、(「.DUPF」)が返されて重複したファイル名を作成されることを防ぎます。サブディレクトリ中の「.」と「..」のエントリは移動できず(「.DOT」エラー)、ディレクトリはファイルシステム中で孤立したループを生成してしまうことになるため、自分自身の下に移動できません(「.DIRE」エラー)。オープンされているファイルハンドルを持つファイル移動できません(「.FOPEN」エラー)。
 FIBがこのファンクションに渡されても、FIBの内部情報はファイルの新しい位置に対応するようには更新されません。そうしないとFIBを続く「次のエントリの検索」ファンクションコール(P.292参照)で使用できなくなります。しかし、FIBは移動されたファイルをもう参照していないということになりますので、「名前の変更」や「オープン」などの処理に、このファンクションに渡したFIBを使用してはいけません。

ファイル属性の獲得・セット

機能番号
50H(_ATTR)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
A      0  属性の獲得
       1  属性のセット
L      新しい属性バイト(A=1の場合のみ)
戻り値
A      エラー
L      現在の属性バイト
解説

 このファンクションはファイルやサブディレクトリの属性を変更するために使用されます。また現在の属性を知るために使用することができ亜mすが、これは「最初のエントリの検索」ファンクション(P.291参照)を使用するのがより一般的です。A=0であるとファイルやサブディレクトリの現在の属性バイトがLレジスタに返されます。
 A=1の場合、属性バイトはLレジスタで指定された新しい値にセットされ、この新しい値もLレジスタ中に返されます。ファイルについてはシステム、不可視、読み出し専用、およびアーカイブビットを変更することができ、サブディレクトリについては不可視属性を変更できます。そのほかの属性ビットを変更しようとすると「.IATTR」エラーが返されます。FIBが渡されると、その中の属性バイトは新しい設定で更新されません。
 このファンクションではワイルドカードは使用できず、属性をセットできるファイルおよびサブディレクトリはひとつだけです。ルートディレクトリには属性がないため、その属性を変更することはできません。ファイルハンドルがオープンされているファイルの属性を変更することはできません(「.FOPEN」エラー)。一方「.」および「..」ディレクトリエントリの属性は変更することができます。「CON」などのデバイス名が指定されてもエラーは返されませんが、デバイスの属性は実際には変更されません。

ファイルの日付および時刻の獲得・セット

機能番号
51H(_FTIME)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列またはFIBポインタ
A      0  日付と時刻の獲得
       1  日付と時刻のセット
IX     新しい時刻の値(A=1の場合のみ)
HL     新しい日付の値(A=1の場合のみ)
戻り値
A      エラー
DE     ファイルの時刻の現在値
HL     ファイルの日付の現在値
解説

 A=1の場合、このファンクションはドライブ・パス・ファイル文字列あるいはFIBで指定されるファイルまたはサブディレクトリの最終修正時刻および日付をセットします。このファンクションではワイルドカード文字が使用できないため、日付と時刻を修正することができるファイルはひとつだけです。「CON」などのデバイス名が指定されてもエラーは返されませんが、デバイスの日付と時刻は実際には変更されません。
 日付と時刻の形式はディレクトリエントリとFIB中に保存されているものと全く同一です(13章「ディスクファイルの構造」を参照)。日付や時刻に着いてのチェックは行われず、値はただセットされるだけです。FIBが渡されると、それにセットされた日付と時刻はこのファンクションでは更新されません。
 A=0の場合、現在の値がそのまま返されます。時刻の値をIXに渡しますが、結果はDEに返されると言うことに注意してください。オープンされているファイルハンドルがあるファイル(「.FOPEN」エラー)の日付と時刻反抗できません。(読み出しは可)。

ファイルハンドルの削除

機能番号
52H(_HDELETE)
コール手順
B      ファイルハンドル
戻り値
A      エラー
解説

 このファンクションは指定したファイルを削除し、そのファイルハンドルをクローズします。同一のファイルに対して別個にオープンされたファイルハンドルがある場合には、ファイルハンドルは削除できません(「.FOPEN」エラー)。ファイルハンドルの複製(「ファイルハンドルの複製」あるいは「子プロセスの起動」ファンクションで作成されるもの)が存在すると、これらの複製は使用できないようにマークされ、これらを使用しようとすると「.HDEAD」エラーとなります。
 このファンクションのエラーの状態は、「ファイルあるいはサブディレクトリの削除」ファンクション(P.304参照)と同じです。エラーの状態(「.FILRO」や「.FOPEN」など)が存在しても、ファイルハンドルは常にクローズされます。

ファイルハンドルの名前の変更

機能番号
53H(_HRENAME)
コール手順
B      ファイルハンドル
HL     新しいファイル名ASCIIZ文字列
戻り値
A      エラー
解説

 このファンクションは指定のファイルハンドルに結合したファイルの名前を、HLで指される文字列中の新しい名前に変更します。ファイルがASCIIZ文字列やFIBではなくファイルハンドルで指定されるということを別にして、このファンクションは「ファイル名あるいはサブディレクトリ名の変更」ファンクション(P.305参照)と同じで、同一のエラー状態を持ちます。
 ファイルハンドルはそのファイルに対してオープンされた別のファイルハンドルが存在する場合には名前を変更できません(「.FOPEN」エラー)が、このファイルハンドルのコピーが存在していても名前を変更でき、この場合コピーの名前も変更されます。ファイルハンドルの名前の変更はファイルポインタを変えませんが、それは暗黙の「確保」処理を実行します。

ファイルハンドルの移動

機能番号
54H(_HMOVE)
コール手順
B      ファイルハンドル
HL     新しいファイル名ASCIIZ文字列
戻り値
A      エラー
解説

 このファンクションは指定のファイルハンドルに結合したファイルの名前を、HLで指される新しいパス文字列で指定されるディレクトリへ移動します。ファイルがASCIIZ文字列やFIBではなくファイルハンドルで指定されるということを別にして、このファンクションは「ファイル名あるいはサブディレクトリ名の移動」ファンクション(P.306参照)と同じで、同一のエラー状態を持ちます。
 ファイルハンドルはそのファイルに対してオープンされた別のファイルハンドルが存在する場合には移動できません(「.FOPEN」エラー)が、このファイルハンドルのコピーが存在していても移動でき、この場合コピーも移動されます。ファイルハンドルの移動はファイルポインタを変えませんが、それは暗黙の「確保」処理を実行します。

ファイルハンドルの属性の獲得・セット

機能番号
55H(_HATTR)
コール手順
B      ファイルハンドル
A      0  属性の獲得
       1  属性のセット
L      新しい属性バイト(A=1の場合のみ)
戻り値
A      エラー
L      現在の属性バイト
解説

 このファンクションは指定のファイルハンドルに結合したファイルの属性バイトを獲得または変更します。ファイルがASCIIZ文字列やFIBではなく、ファイルハンドルで指定されるということを別にして、このファンクションは「ファイル属性の獲得・セット」ファンクション(P.307参照)と同じで、同一のエラー状態を持ちます。
 ファイルハンドルはそのファイルについてオープンされている別のファイルハンドルが存在する場合には、その属性を(獲得することはできますが)変更することはできません(「.FOPEN」エラー)。ファイルポインタは変更されませんが、暗黙の「確保」処理が実行されます。

ファイルハンドルの日付および時刻の獲得・セット

機能番号
56H(_HFTIME)
コール手順
B      ファイルハンドル
A      0  日付と時刻の獲得
       1  日付と時刻のセット
IX     新しい時刻の値(A=1の場合のみ)
HL     新しい日付の値(A=1の場合のみ)
戻り値
A      エラー
DE     ファイルの時刻の現在値
HL     ファイルの日付の現在値
解説

 このファンクションは指定のファイルハンドルに結合したファイルの日付と時刻を獲得または変更します。ファイルがASCIIZ文字列やFIBではなく、ファイルハンドルで指定されるということを別にして、このファンクションは「ファイル日付および時刻の獲得・セット」ファンクション(P.307参照)と同じで、同一のエラー状態を持ちます。
 ファイルハンドルはそのファイルについてオープンされている別のファイルハンドルが存在する場合には、その日付と時刻を(獲得することはできますが)変更することはできません(「.FOPEN」エラー)。ファイルポインタは変更されませんが、暗黙の「確保」処理が実行されます。

ディスク転送アドレスの獲得 [エラー処理]

機能番号
57H(_GETDTA)
コール手順
なし
戻り値
DE     現在のディスク転送アドレス
解説

 このファンクションは現在のディスク転送アドレスを返します。このアドレスは「旧来の」CP/MスタイルのFCBファンクションやアブソリュートなセクタの読み出し・書き込みファンクションのために使用されます。

ベリファイフラグ設定の獲得 [エラー処理]

機能番号
58H(_GETVFY)
コール手順
なし
戻り値
B      00H  ベリファイ無効
       FFH  ベリファイ有効
解説

 このファンクションは「ベリファイフラグのセット・リセット」ファンクション(P.289参照)でセットすることのできるベリファイフラグの現在の状態を返します。

カレントディレクトリの獲得

機能番号
59H(_GETCD)
コール手順
B      ドライブ番号  0=カレント、1=A:など
DE     64バイトバッファへのポインタ
戻り値
A      エラー
DE     カレントパスで満たされる
解説

 このファンクションは指定のドライブのカレントディレクトリを表すASCIIZ文字列を獲得して、DEで指されるバッファ中に格納します。文字列にはドライブ名や前後の「\」文字は含まれないので、ルートディレクトリはヌル文字列で表現されます。ドライブがアクセスされて、カレントディレクトリが実際に現在のディスク上に存在するということが確認されるため、もし存在しない場合にはカレントディレクトリはルートにセットし直され、ヌル文字列が返されます。

カレントディレクトリの変更

機能番号
5AH(_CHDIR)
コール手順
DE     ドライブ・パス・ファイル ASCII文字列
戻り値
A      エラー
解説

 ドライブ・パス・ファイル文字列はファイルではなくディレクトリを指定しなければなりません。そのドライブのカレントディレクトリが存在しない場合、現在の設定は変更されず、「.NODIR」エラーが返されます。

パス名の解析

機能番号
5BH(_PARSE)
コール手順
B      ボリューム名フラグ(ビット4)
DE     解析するASCIIZ文字列
戻り値
A      エラー
DE     終了文字へのポインタ
HL     最後の項目の先頭へのポインタ
B      解析フラグ
C      論理ドライブ番号(1=A:など)
解説

 このファンクションは純粋な文字列操作ファンクションで、ディスクをまったくアクセスせず、またユーザーの文字列にいかなる変更も加えません。これは外部プログラムがコマンド行を解析する手助けのために用意されています。
 ボリューム名フラグ(Bレジスタのビット4。これは属性バイトにおけるボリューム名と同じビット位置にある)がクリアされているとき文字列を、「ドライブ・パス・ファイル」文字列として、セットされているとき「ドライブ・ボリューム」文字列として解析します。
 DEに返されるポインタはパス名文字列中で有効でない最初の文字を指し、文字列の終わりのヌルのこともあります。パス名文字列の構文の詳細や有効な文字のリストについては5.1「この章の表記法」を参照してください。
 HLに返されるポインタは文字列の最後の項目(「ファイル名」部分)の最初の文字を指します。例えば、渡された文字列が「A:\XYZ\P.Q /F」ならば、DEは/Fの前の空白文字を指し、HLは「P」を指します。解析された文字列が「\」文字で終わっていたり、あるいはヌル(ドライブ名は別として)であると、これらの場合には「最後の項目」は存在しないため、HLはDEと同一の文字を指します。この特殊な場合には、このファンクションを使用するすべてのプログラムでなんらかの特別な処理がふつう必要となります。
 Cレジスタに返されるドライブ番号は文字列中で指定される論理ドライブです。文字列がドライブ文字で始まらないと、カレントドライブが暗黙で指定されたということなので、Cレジスタはカレントドライブ番号を保持しています。Cレジスタは0になることはありません。
 Bレジスタに返される解析フラグは文字列に関する様々な情報を示します。ボリューム名では、ビット1、4、5、6、および7は常にクリアされます。ファイル名では、ビット3〜7は文字列の最後の項目(「ファイル名」部分)に関連します。ビットの割り当てを次に示します。

ビット意味
0ドライブ名以外の文字が解析されたときにセット
1ディレクトリパスが指定されたときにセット
2ドライブ名が指定されたときにセット
3最後の項目で主ファイル名がセットされたときにセット
4最後の項目でファイル名拡張子が指定されたときにセット
5最後の項目にワイルドカードがあるときにセット
6最後の項目が「.」あるいは「..」の時にセット
7最後の項目が「..」のときにセット

ファイル名の解析

機能番号
5CH(_PFILE)
コール手順
DE     解析するASCIIZ文字列
HL     11バイトバッファへのポインタ
戻り値
A      エラー(常に0)
DE     終了文字へのポインタ
HL     保存、バッファが使用
B      解析フラグ
解説

 このファンクションは純粋な文字列操作ファンクションであり、まったくディスクにアクセスせず、文字列に修正を加えることはまったくありません。このファンクションは主に外部プログラムがコマンド行がフォーマットされた形式でファイル名を出力する手助けになるために用意されています。ASCIIZ文字列は単一のファイル名の項目として解析され、ファイル名はユーザーの11バイトのバッファに拡張された形式でセットされ、ファイル名および拡張子の余白には空白が詰められます。
 Bレジスタに返される解析フラグは上記の「パス名の解析」ファンクション(P.313参照)と同じですが、ビット0、1、および2は常にクリアされています。例え文字列中に有効なファイル名がなかったとしてもユーザーのバッファは常に満たされ、その場合にはバッファは空白で満たされます。「*」文字は適当な数の「?」に展開されます。ファイル名あるはファイル名拡張子が長すぎると余分な文字は無視されます。
 DEレジスタに返されるポインタはファイル名の一部ではなかった文字列中の最初の文字を指しますが、これは文字列の終わりにあるヌルである場合があります。この文字は有効なファイル名の文字であることはありません(有効なファイル名の文字の詳細については5.1「この章の表記法」を参照)

文字の検査 [エラー処理]

機能番号
5DH(_CHKCHR)
コール手順
D      文字フラグ
E      検査する文字
戻り値
A      0(エラーを返すことはない)
D      更新された文字フラグ
E      検査された(大文字にされた)文字
解説

 このファンクションは言語設定とは独立して文字を大文字にしたり、2バイトの文字やファイル名の操作をしたりするのに役立ちます。文字フラグのビット割り当てを次に示します。

ビット意味
0 大文字にしないときにセット
1 2バイト文字の第1バイトのときにセット
2 2バイト文字の第2バイトのときにセット
3 セット=ボリューム名(ファイル名ではない)
4 セット=有効なファイル・ボリューム名の文字
5〜7 システム予約(常にクリア)
 ビット0は大文字化を制御するために使用します。これがクリアされると、文字はそのマシンの言語設定にしたがって大文字にされます。このビットがセットされていると、返される文字は常に渡された文字と同一になります。
 2つの2バイト文字のフラグ(ビット1と2)は、文字列の最初の文字をチェックするときに両方ともクリアすることができ、返された設定は、続く文字のためにこのファンクションに直接渡すことができます。これらのフラグで、2バイト文字を含む可能性のある文字列を逆戻りする場合には注意が必要です。
 ビット4は文字がファイル名やボリューム名の終了文字であると、セットされてリターンします。ビット3は単純に、ファイル名の検査か、あるいはボリューム目の文字の検査かを決定するのに使用されます(文字セットが異なるため)。2バイト文字(どちらのバイトも)はボリュームあるいはファイル名の終了文字としてみなされることはありません。

完全なパス文字列の獲得

機能番号
5EH(_WPATH)
コール手順
DE     64バイトバッファへのポインタ
戻り値
A      エラー
DE     完全なパス文字列で満たされる
HL     最後の項目のはじめへのポインタ
解説

 このファンクションは内部バッファからASCIIZパス文字列をユーザーのバッファへ単純にコピーします。文字列は、前に実行された「最初のエントリの検索」(P.291参照)あるいは「新しいエントリの検索」(P.293参照)で見つけられたファイルやサブディレクトリのルートディレクトリからの完全なパスとファイル名を表します。返された文字列はドライブや最初の「\」文字を含みません。HLレジスタは「パスの解析」ファンクション(P.313参照)と同様、文字列上の最後の項目の最初の文字を指しています。
 「最初のエントリの検索」や「新しいエントリの検索」ファンクションコールでDEがASCIIZ文字列を指して実行された場合、続く「完全なパス名の獲得」ファンクションコール(P.316参照)は「検索」ファンクションコールで返されるFIBに関連するサブディレクトリやファイルを表す文字列を返します。これがサブディレクトリであると、FIBはレジスタDEで別の「最初のエントリの検索」ファンクションコールに渡すことができ、このサブディレクトリ中でファイルが検索されます。この場合、新たに検索されるファイルは既に内部で存在する完全なパス文字列に加えられ、続く「完全なパス文字列の獲得」ファンクションコールは検索されたファイルについて正しい完全なパス文字列を返します。
 多くのファンクションコール内部の完全なパス文字列が変更され、たいていの場合正しくないので、このファンクションを使用する場合には十分な注意が必要です。「完全なパスの獲得」ファンクションコールは、それが関係する「最初のエントリの検索」や「新しいエントリの検索」ファンクションの直後に行うべきです。

ディスクバッファのフラッシュ

機能番号
5FH(_FLUSH)
コール手順
B      ドライブ番号  (0=カレント、FFH=すべて)
D      00H           フラッシュのみ
       FFH           フラッシュして無効にする
戻り値
A      エラー
解説

 このファンクションは指定のドライブ、あるいはB=FFHの場合にはすべてのドライブについて、まだ書き出されていないすべてのディスクバッファをフラッシュします。DレジスタがFFHであると、そのドライブのすべてのバッファも無効になります。

子プロセスの起動

機能番号
60H(_FORK)
コール手順
なし
戻り値
A      エラー
B      親プロセスのプロセスID
解説

 このファンクションはシステムに対して子プロセスが起動されようとしていることを報告します。一般的には、これは実行されようとする新しいプログラムやサブコマンドです。例えば、COMMAND2.COMはすべてのコマンドや外部プログラムを実行する前に、「子プロセスの起動」ファンクションコールを実行します。
 新しいファイルハンドルのセットが作成され、「継承アクセスモードビット」をセットしてオープンされたすべての現在のファイルハンドル(「ファイルハンドルのオープン」ファンクション(P.295参照))は新しいファイルハンドルのセットにコピーされます。「継承ビット」をクリアしてオープンされたすべてのファイルハンドルはコピーされないため、子プロセスでは利用できません。標準ファイルハンドル(00H〜05H)は継承できるため、これらはコピーされます。
 新しいプロセスIDが子プロセスのために割り当てられ、親プロセスのプロセスIDが返され、後で「親プロセスに戻る」ファンクションコール(P.318参照)で親プロセスへ戻れるようにします。ファイルハンドルを複製するのにメモリが足りない場合には「.NORAM」エラーが返されます。
 子プロセスはオリジナルではなくて以前のファイルハンドルのコピーを持つため、コピーの一つがクローズされても元のものは オープンされたままです。したがって、たとえば子プロセスが標準出力のファイルハンドル(ファイルハンドル番号1)をクローズし、それを新しいファイルに再オープンすると、「親プロセスに戻る」ファンクションが実行されて親プロセスに戻ったとき、元の標準出力チャンネルはまだ有効です。

親プロセスに戻る

機能番号
61H(_JOIN)
コール手順
B      親プロセスIDまたは0
戻り値
A      エラー
B      子プロセスからの1次エラーコード
C      子プロセスからの2次エラーコード
解説

 このファンクションは指定の親プロセスに戻り、子プロセスが終了したエラーコードをBレジスタに入れ、子プロセスからの2次エラーコードをCレジスタに入れてリターンします。親と子プロセスの間の関係は厳密に1対1ですが、このファンクションは適切なプロセスIDを与えることによって、いくつかのレベルを飛び越えて戻ることができます。プロセスIDが不正であると「.IPROC」エラーが返されます。
 子プロセスのファイルハンドルのセットは自動的にクローズされ、親プロセスのファイルハンドルのセットが再びアクティブになります。子プロセスが割り当てていたすべてのユーザーRAMセグメントも解放されます。
 このファンクションに渡されたプロセスIDが0であると、部分的なシステムの再初期化が実行されます。すべてのファイルハンドルがクローズされ、標準入出力が再オープンされ、すべてのユーザーセグメントが解放されます。この後ではコマンドインタープリタは正しい状態ではないため、ユーザープログラムはコマンドインタープリタに戻ろうとするならばこれを行ってはなりません。
 このファンクションは実際にファイルハンドルをクローズする前に(つまりディスクにアクセスする前に)、メモリの解放とプロセスIDの調整を行うように、慎重な配慮がなされています。これによって、ディスクエラーが起こって中断されても、処理は成功しているということが保証されます。しかし「join 0」がディスクエラーを起こしてアボートすると、デフォルトファイルハンドルの再初期化は実行されません。この場合には別の「join 0」ファンクションコールを実行しなければならず、これはディスクをアクセスしようとしないため(すべてのファイルはクローズされているため)成功します。
 このファンクションコールが0F37DHを通して実行されると、BおよびCレジスタはエラーコードを返さないことに注意してください。これは、プログラムの終了や中断の処理はアプリケーションプログラムによって実行されなければならないからです。エラーコードはアボートルーチンに渡されており、そこにあるプログラムが必要ならばエラーコードを記憶していなければなりません。1次および2次エラーコードの意味については、「エラーコードを伴った終了」ファンクション(P.320)も参照してください。

エラーコードを伴った終了

機能番号
62H(_TERM)
コール手順
B      終了のエラーコード
戻り値
なし
解説

 このファンクションは指定されたエラーコードでプログラムを終了させますが、このコードはエラーなしを示す0であってもかまいません。このファンクションコールは、ユーザーのアボートルーチンが戻るように設定されていない限り、呼び出し側に戻ることはありません(P.320「アボート終了ルーチンの定義」を参照)。このファンクションの操作は0005Hを通ってMSX-DOSの環境からコールされたのか、あるいは0F37DHを通ってDisk-BASICの環境からコールされたのかによって異なります。
 0005Hを通ってコールされた場合、ユーザーのアボートルーチンが「アボート終了ルーチンの定義」ファンクションによって定義されていると、それは指定のエラーコード(および0の2次エラーコード)を伴ってコールされます。このルーチンがリターンするか、またはユーザーのアボートルーチンが定義されていない場合、制御はアドレス0000Hへのジャンプを経由して外部プログラムをロードしたルーチンへ戻されます。これはほとんど常にコマンドインタープリタですが、場合によっては別の外部プログラムであることもあります。エラーコードはシステムによって記憶され、実行される次の「親プロセスに戻る」ファンクション(P.318参照)がこのエラーコードを返します。コマンドインタープリタは20H〜FFHの間のすべてのコードについてエラーメッセージを表示しますが、それ以下のエラーについてはメッセ維持を表示しません。
 このファンクションが0F37DHを通してDisk-BASICの環境からコールされると、制御は位置「BREAKVECT」のアボートベクタへ渡されます。この環境では、別に定義されたゆーざーのアボートルーチンはなく、「join」はエラーコードを返さないため、エラーコードは「BREAKVECT」にあるコードによって記憶されなければなりません。

アボート終了ルーチンの定義

機能番号
63H(_DEFAB)
コール手順
DE     アボート終了ルーチンのアドレス
       0000Hで定義解除
戻り値
A      0   エラーを生成しない
解説

 このファンクションはMSX-DOSの環境で0005H番地を通してコールされたときに利用できます。Disk-BASICの環境で0F37DHを通してはコールできません。
 DEレジスタが0であると、前に定義したアボートルーチンが定義を解除され、そうでないと新しいものが定義されます。0000H番地に直接ジャンプするのではなく、外部プログラムがなんらかの理由で終了しようとしているときには必ずシステムによってアボートルーチンがコールされます。MSX-DOS2のために書かれたプログラムでは、0000H番地へのジャンプではなくて、「エラーコードを伴った終了」ファンクションコール(P.320参照)で終了しなければなりません。
 ユーザーのアボートルーチンはユーザーのスタックをアクティブにし、ファンクションコールが行われたときと同じようにIX、IYと裏レジスタセットをセットし、TPA全体をページングして起動されます。終了エラーコードはAレジスタ、2次エラーコードはBレジスタでルーチンに渡され、ルーチンが「RET」を実行すると、AおよびBレジスタでルーチンに返された値が「親プロセスに戻る」ファンクション(P.318参照)で返されるべきエラーコードとしてストアされ、通常コマンドインタープリタによって出力されます。あるいは、ルーチンはリターンせずに外部プログラム中のなんらかのウォームスタートコードにジャンプしてもかまいません。システムは完全に安定した状態にあって、どのようなファンクションコールも受け付けることができます。
 Aレジスタに入れてルーチンに渡される1次エラーコードは、プログラム自身が「エラーコードを伴った終了」ファンクション(P.320参照)に渡したコード(0でもよい)になります(これが終了の理由ならば)。
 [CTRL]+[C]あるいは[CTRL]+[STOP]が検出された場合(「.CTRLC」または「.STOP」エラー)、ディスクエラーがアボートされた場合(「.ABORT」エラー)、あるいはMSX-DOSのファンクションコール01H〜0BHを通してアクセスしている標準入力あるいは出力のチャンネルのひとつでエラーが起こった場合(「.INERR」または「.OUTERR」)にもルーチンはコールされます。「.ABORT」、「.INERR」、および「.OUTERR」エラーはなんらかの他のエラーの結果としてシステムによって生成されます。例えば、「.ABORT」エラーは「.NRDY」エラーによって起こる可能性があり、「.INERR」エラーは「.EOF」エラーで起こる可能性があります。これらの場合には、元のエラーコード(「.NRDY」や「.EOF」)は2次エラーコードとしてBレジスタでアボートルーチンに渡されます。そのほかのすべてのエラーは2次エラーコードを持たず、Bレジスタは0です。
 アボートルーチンが単純にリターンせず、「POP HL :RET」(または同等のコード)を実行すると、制御はエラーが起こったMSX-DOSコールまたはBIOSコールのすぐ次の命令に渡ります。これは「ディスクエラー処理ルーチンの定義」ファンクション(P.322参照)とともに使用すると有用で、ディスクエラーが起こったときに現在のMSX-DOSコールをアボートすることが可能になります。

ディスクエラー処理ルーチンの定義

機能番号
64H(_DEFER)
コール手順
DE     ディスクエラールーチンのアドレス
       0000Hで定義解除
戻り値
A      0    エラーを生成しない
解説

 このファンクションはディスクエラーが起こった場合にコールされるユーザーのルーチンのアドレスを指定します。TPA全体をページングしてルーチンは起動されますが、ページ3のシステムスタックがアクティブになり、MSX-DOSのファンクションコールが実行されたときのレジスタは保存されません。
 エラールーチンはMSX-DOSのコールを実行できますが、エラーの再帰を避けるように十分注意しなければなりません。17.2「ファンクション一覧」はユーザーのエラールーチンからどのファンクションコールが安全に実行できるかを示しています。標準入出力チャンネルがリダイレクトされている場合には、このルーチンはリダイレクション状態を一時的に無効にした状態でコールされます。これについての詳細は、「リダイレクション状態の獲得・セット」ファンクション(P.329)を参照してください。
 ルーチン自体のパラメータと結果の使用を下に示します。IX、IYおよび裏レジスタセットを含むすべてのレジスタは破壊できますが、ページングとスタックは保存しなければなりません。ルーチンはシステムに返らねばならず、外部プログラムを続行するために別の所にジャンプしてはなりません。これを行うには、A=1(「アボート」)を返すことで、ユーザーのアボートルーチンに制御を渡して、アボートルーチン内で必要な処理を行うようにします。

  パラメータ   A  = エラーの原因となったエラーコード
               B  = 物理ドライブ
               C  = b0 - 書き込みでセット
                    b1 - 無視の処理が望ましくないときセット
                    b2 - オートアボートを指示するときセット
                    b3 - セクタ番号が有効のときセット
               DE = セクタ番号(Cのb3がセットされているとき)
  結果         A  = 0 = システムエラールーチンのコール
                  = 1 = アボート
                  = 2 = 再試行
                  = 3 = 無視

直前のエラーコードの獲得 [エラー処理]

機能番号
65H(_ERROR)
コール手順
なし
戻り値
A      0
B      直前のファンクションからのエラーコード
解説

 このファンクションによって、ユーザープログラムは前のMSX-DOSファンクションコールが失敗した原因のエラーコードを見つけることができます。これはエラーコードを返さない古いCP/M互換のファンクションで使用するためのものです。例えば、「ファイルFCBの作成」ファンクションがA=0FFHを返すと、失敗の理由は数多くある可能性がありますが、このファンクションコールを使用すると、例えば「.DRFUL」や「.SYSX」など適切なものを返します。

エラーコードの説明 [エラー処理]

機能番号
66H(_EXPLAIN)
コール手順
B      説明すべきエラーコード
DE     64バイトの文字列バッファへのポインタ
戻り値
A      0
B      0あるいは変更なし
DE     エラーメッセージが入る
解説

 このファンクションを使用すると、ユーザープログラムでMSX-DOSのファンクションから返される特定のエラーコードについてのASCIIZ説明文字列を得ることができます。もしエラーが旧来のファンクションのものであれば、「直前のエラーコードを得る」ファンクションを最初に呼んで本当のエラーコードを得なければならず、それからこのファンクションをコールして説明文字列を得ることができます。
 16章「エラー」にすべての現在定義されているエラーコードとそれに対するメッセージのリストがあります。システムの外国向けのバージョンではもちろん異なったメッセージとなります。エラーコードが実施に内部の説明文字列を持っていると、この文字列が返されてBレジスタが0にセットされます。説明文字列がないと、「システムエラー194」あるいは「ユーザーエラー45」という形式の文字列が返され、Bレジスタは変更されてません。(システムエラーは40H〜FFHの範囲のもので、ユーザーエラーは00H〜3FHのもの)。

ディスクのフォーマット

機能番号
67H(_FORMAT)
コール手順
B      ドライブ番号(0=カレント、1=A:)
A      00H        選択文字列を返す
       01H〜09H   この選択をフォーマットする
       0AH〜FDH   不正
       FEH, FFH   ブートセクタの更新
HL     バッファへのポインタ(A=1〜9の場合)
DE     バッファのサイズ(A=1〜9の場合)
戻り値
A      エラー
B      選択文字列のスロット(エントリでA=0の場合のみ)
HL     選択文字列のアドレス(エントリでA=0の場合のみ)
解説

 このファンクションはディスクをフォーマットするために使用され、アプリケーションプログラムで必要な場合には使用することもできますが、事実上FORMATコマンドのためにだけ提供されています。Aレジスタに渡されたコードによって選択される3つの異なったオプションがあります。
 A=0の場合、BとHLレジスタはフォーマットの種類を選択するASCIIZ文字列のスロット番号とアドレスをそれぞれ返します。このディスクがフォーマットできない(例えばRAMディスク)と「.IFORM」エラーが返されます。文字列は「RDSLT」ルーチンを使用して読み込まれ、画面に表示されて、それから「?」プロンプトが表示されます。ユーザーはそこで「1」〜「9」の選択を指定し、この選択が「フォーマット」ファンクションに適切な警告プロンプトの後で渡され、実際のディスクフォーマットが実行されます。A=0でHLに0が返される場合があり、これはフォーマットが1種類しかなくプロンプトの必要が無いことを意味します。これらの処理はディスクドライバごとに異なるため、それぞれの選択がどのようなディスクフォーマットを参照するのかを知る方法はありません。
 A=01H〜09Hの場合、これはフォーマットの選択として解釈され、それ以上のプロンプトなしでディスクは指定のドライブでフォーマットされます。HLとDEレジスタはディスクドライバによって使用されるバッファ領域を指定しなければなりません。このバッファがどのくらいの大きさであるべきか知る必要は無いので、可能な限り大きくするのが最良の方法です。バッファがページ境界をまたぐと、このファンクションはディスクドライバに渡すために、1つのページ中の最大部分を選択します。ほとんどのディスクドライバはこのバッファを全く使用しません。
 A=FFHの場合、ディスクは実際にはフォーマットされませんが、ディスクに新しいブートセクタを書き込み、MSX-DOS2ディスクにします。これは以前のMSX-DOS1のディスクボリュームIDを持つように更新して、それによってMSX-DOS2で可能な完全なボリュームIDを持つように更新して、それによってMSX-DOS2で可能な完全なディスク検査とファイルの復活を可能にするためです。A=FEHはA=FFHとほぼ同様ですが、ディスクパラメータのみを正しく更新し、ボリュームIDでブートセクタを重ね書きすることはありません。ディスク上に不正なブートセクタを置くいくつかのMSX-DOS1のインプリメンテーションが存在するため、それらのディスクはこのファンクションで訂正されるまでMSX-DOS2では使用することができません。
 「ブートセクタの更新」は主にFIXDISKコマンドのために設けられていますが、それが有用な場合には他のプログラムで使用することができます。それを有用な場合には他のプログラムで使用することができます。それを使用する場合には、「フォーマットの選択の獲得」(A=0)が最初に実行されなければならず、これがエラー(通常「.IFORM」)を返すと、これがフォーマットできないドライブで、ディスクはこのファンクションで損傷されることがあるため、処理はアボートされなければなりません。

RAMディスクの作成あるいは消去

機能番号
68H(_RAMD)
コール手順
B      00H        RAMディスクを消去
       01H〜FEH   新しいRAMディスクの作成
       FFH        RAMディスクのサイズを返す
戻り値
A      エラー
B      RAMディスクのサイズ
解説

 Bレジスタ=0FFHの場合、このルーチンは、現在のRAMディスクに割り当てられている16KRAMセグメントの数を返します。値0は現在定義されているRAMディスクが存在しないことを示します。B=0の場合、現在のRAMディスクが消去され、それが保持していたすべてのデータは失われ、RAMディスクがなかった場合でもエラーが返されません。
 また、Bが01H〜FEHの範囲にある場合、このファンクションはBレジスタに指定された16Kセグメントの数を使用して新しいRAMディスクを作成しようとします。RAMディスクが既にある場合(「.RAMDX」)、あるいは未使用のセグメントがひとつもない場合(「.NORAM」)、エラーが返されます。指定のサイズのRAMディスクを作成するのに十分な未使用RAMセグメントがないと可能な最大のものが作成されます。この場合エラーは返されません。
 すべての場合において、RAMディスクのサイズがセグメント数としてBレジスタに返されます。RAMのいくらかはファイルアロケーションテーブルとルートディレクトリに使われるため、DIRやCHKDSKコマンドで示されるRAMディスクのサイズは使用されるRAMの総計よりもやや小さくなります。システムの他のドライブ数にかかわらず、RAMディスクは常にドライブ文字「H:」としてアクセスされます。

セクタバッファの割り付け

機能番号
69H(_BUFFER)
コール手順
B      0  バッファ数を返す
       あるいは要求するバッファ数
戻り値
A      エラー
B      バッファの現在の数
解説

 B=0の場合、このファンクションは現在割り当てられているセクタバッファの数を返します。B≠0のであると、このファンクションはこの数をセクタバッファ数として使用しようとします。(常に最低でも2は必要です)。それが要求されただけのバッファを割り当てられないと、可能な限り割り当てを行い、Bレジスタにその数を返しますが、エラーは返しません。セクタバッファの数は増やすことも減らすこともできます。
 セクタバッファは通常の64Kの外の16KRAMセグメントに割り当てられるため、バッファ数はTPAのサイズを減少させません。しかし、バッファが多ければより多くのFATとディレクトリセクタを常駐させておくことができるため、バッファ数は効率に影響します。バッファの最大数は20くらいになります。

論理ドライブの割り当て [エラー処理]

機能番号
6AH(_ASSIGN)
コール手順
B      論理ドライブ番号(1=A:など)
D      物理ドライブ番号(1=A:など)
戻り値
A      エラー
D      物理ドライブ番号(1=A:など)
解説

 このファンクションは論理ー物理ドライブの割り当て機能を制御します。これは主としてASSIGNコマンドのために提供されていますが、ユーザープログラムで使用して論理ドライブ番号を物理ドライブ番号に変換することもできます。
 BとDがどちらも0でないと、新しい割り当てがセットアップされます。Bレジスタが0でなく、Dレジスタが0であると、Bで指定した論理ドライブについての割り当てがキャンセルされます。Bレジスタが0でなく、DレジスタがFFHであると、Bレジスタで指定した論理ドライブについての現在の割り当てが、Dレジスタに返されます。
 ファンクションコールへの文字列中のドライブ名とパラメータとしてのドライブ名を含め、様々なファンクションコールで使用されるすべてのドライブは論理ドライブです。しかし、ディスクエラールーチンに渡されるドライブ番号は物理番号であるため、ASSIGNコマンドを使用していると対応する論理ドライブとは異なる場合があります。

環境変数の獲得 [エラー処理]

機能番号
6BH(_GENV)
コール手順
HL     ASCIIZ名前文字列へのポインタ
DE     名前文字列のバッファへのポインタ
B      バッファサイズ
戻り値
A      エラー
HL     保存され、バッファが満たされる
解説

 このファンクションはHLレジスタに渡された環境変数名の現在の値を獲得します。環境変数の大文字、小文字の違いは無視されます。名前の文字列が不正であると「.IENV」エラーが返されます。その名前の環境変数がないとバッファにヌル文字が返されます。その名前の変数があると、その値の文字列がバッファにコピーされます。バッファが小さくて入らないと値の文字列は最後のヌルをつけずに切り捨てられ、「.ELONG」エラーが返されます。値の文字列は255文字よりも長くできない(最後のヌルも含む)ため、255バイトのバッファは常に十分な大きさを持つことになります。

環境変数のセット [エラー処理]

機能番号
6CH(_SENV)
コール手順
HL     ASCIIZ名前文字列へのポインタ
DE     ASCIIZ値文字列へのポインタ
戻り値
A      エラー
解説

 このファンクションは新しい環境変数をセットします。環境変数の大文字、小文字の違いは無視されます。名前文字列が不正であると「.IENV」エラーが返され、有効ならば値文字列がチェックされ、それが255文字よりも長い場合には「.ELONG」エラーが返され、また、新しい変数を格納するために十分なメモリがない場合には「.NORAM」エラーが返されます。すべてが有効ならば同じ名前の古い変数が削除され、新しい変数リストの最初に追加されます。値文字がヌルだと環境変数は除去されます。

環境変数の検索 [エラー処理]

機能番号
6DH(_FENV)
コール手順
DE     環境変数番号
HL     ASCIIZ名前文字列へのポインタ
B      バッファサイズ
戻り値
A      エラー
HL     保存され、バッファが満たされる
解説

 このファンクションはどのような環境変数が現在セットされているかを知るために使用されます。DEレジスタの変数番号は、リスト中のどの変数を検索するか(最初の変数がDE=1に対応)を示します。変数番号<DE>が存在すると、この変数の名前文字列がHLによって指されるバッファ中にコピーされます。バッファが小さすぎる場合には、名前は最後のヌルなしで切り捨てられ、「.ELONG」エラーが返されます。255バイトのバッファは、常に十分な大きさを持ちます。変数番号<DE>が存在しないと、ヌル文字列が返されます(変数はヌル名文字列を持つことはないため)。

ディスク検査ステータスの獲得・セット [エラー処理]

機能番号
6EH(_DSKCHK)
コール手順
A      00H   ディスク検査ステータスの獲得
       01H   ディスク検査ステータスのセット
B      00H   有効(A=01Hの場合のみ)
       01H   無効(A=01Hの場合のみ)
戻り値
A      エラー
B      現在のディスク検査設定
解説

 A=0の場合、ディスク検査変数の現在の値がBレジスタに返されます。A=01Hの場合、変数はBレジスタの値にセットされます。00Hという値はディスク検査を有効にすることを意味し、0でない値はそれが無効であることを示します。デフォルトの状態は有効です。
 ディスク検査変数はファイルハンドル、FIBあるいはFCBがアクセスされるたびに、ディスクが変更されたかどうかを見るためにディスクのブートセクタをシステムが再チェックするかどうかを制御します。それが有効であると、処理の最中にディスクを交換することによって、間違ったディスクに誤ってアクセスすることができなくなりますが、有効でない場合にはディスクを破壊する場合もあります。ディスクインタフェースのタイプによって異なりますが、この機能を有効にする場合に若干余分なオーバーヘッドがある場合があります。しかし、ほとんどのタイプのディスク(ディスク交換を検知するためのハードウェアを持つもの)では処理時間に変わりはなく、これによって安全性が確保されます。

MSX-DOSのバージョン番号の獲得 [エラー処理]

機能番号
6FH(_DOSVER)
コール手順
なし
戻り値
A      エラー(常に0)
BC     MSX-DOSのカーネルバージョン
DE     MSXDOS2.SYSのバージョン番号
解説

 このファンクションによって、プログラムは実行されているMSX-DOSのバージョンを判断することができます。2つのバージョン番号が返され、BCレジスタにROM中のMSX-DOSのカーネルバージョンが、DEれじすたにMSXDOS2.SYSシステムファイルのバージョンが入ります。これらのバージョン番号のどちらも上位バイトに主バージョン番号、下位バイトに2桁のバージョン番号がBCD値で入っています。例えばバージョン2.34のシステムが存在したとすると、これは0234Hとして表現されます。
 MSX-DOS1との互換性のために、次の手順がこのファンクションを使用するためには必要です。まず、エラーが存在する(A<>0)と、これはMSX-DOSではありません。次にBレジスタに注目します。これが2以下であると、システムは2.00より以前のもので、CとDEレジスタは不定となります。Bレジスタが2以上の場合、BCとDEレジスタは上記のように使用することができます。通常この手順の後、チェックされなければならないバージョン番号は、DEレジスタ中のMSXDOS2.SYSのバージョンです。

リダイレクションの状態の獲得・セット [エラー処理]

機能番号
70H(_REDIR)
コール手順
A      00H   リダイレクション状態の獲得
       01H   リダイレクション状態のセット
B      新しい状態
       b0    標準入力
       b1    標準出力
戻り値
A      エラー
B      コマンド以前のリダイレクションの状態
       b0セット    入力がリダイレクトされている
       b1セット    出力がリダイレクトされている
解説

 このファンクションは主にディスクエラールーチンや、リダイレクションに関係なくコンソールに常に出力されなければならないその他の文字I/Oのために提供されています。CP/M文字ファンクション(ファンクション01H〜0BH)が使用されると、それらは通常コンソールを参照します。しかし、標準入力あるいは標準出力ファイルハンドル(ファイルハンドル0および1)がクローズされてディスクファイルに再オープンされていると、CP/M文字ファンクションもディスクファイルへ出力されます。しかし、ディスクエラー出力アンドのある種の出力はそれに関係なく常に画面に出力する必要があります。
 このファンクションによって、このようなリダイレクションをこのファンクションをA=1およびB=0としてコールすることによって一時的に無効にすることができます。このファンクションをコールすることで、以降のCP/MのコンソールI/Oがすべてコンソールに出力されることが保証され、また、直前の設定が返されるためこれを後でリストアすることができます。このようにリダイレクションの状態を変更すると、システムは幾分不安定な状態となり、多くのファンクションコールがこのファンクションを無効にしてリダイレクションをその実際の状態にリセットします。通常、「オープン」、「クローズ」、「複製」などといった、ファイルハンドルを操作するすべてのファンクションコールはリダイレクションの状態をリセットします。従ってこのファンクションの効果は完全に一時的なものです。