MSX Datapack wiki化計画

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

 4.1 概要

 MSXディスクシステムの持つ入出力機能はBDOSというかたちで、汎用のサブルーチン形式でROMにまとめられています。ファンクションコールとは、BDOSを呼び出すためにあらかじめ決められた手順のことで、ユーザープログラムはファンクションコールを実行することでファイルの入出力操作が簡単にできます。
 ファンクションコールの役割は、大きく分けると2つがあります。

  1. 基本的な機能をあらかじめ用意することによってプログラムの負担を少なくすること。
  2. すべてのプログラムが共通の手順を使用することによって、移植性や汎用性を高めること。

 ファンクションコールを自由自在に活用することによって、プログラム開発の期間は短縮され、できあがったプログラムは移植性の高いものになります。これは、OSを利用した時の最大のメリットの1つです。
 ファンクションコールを実行するには、CPUのCレジスタに決められたファンクション番号を入れ、次のアドレスをコールします。

0005HMSX-DOS上の外部コマンド
F37DHDisk BASIC上のマシン語プログラム
 例えば、ファンクション番号が1FHであり、コール手順としてAレジスタに00Hをセットすることになっているファンクションコールがあるとすると、このファンクションコールは次のようにして実行します。

ld      a,00h
ld      c,1fh
call    0005h       ; Disk BASICのときは0F37DH

 CALL文の後には、戻り値(処理の結果)を受け取ったり、退避していたレジスタを復活させたりする事後処理が続きます。
 Disk BASICのプログラムからは、CLEAR文で確保した領域にマシン語プログラムを置き、その開始アドレスをUSR関数で呼び出すことでファンクションコールを利用できます。

 4.2 書式

 ここでは、以下の書式によってファンクションコールの使用法を紹介します。

ファンクション
ファンクション番号とは、ファンクションコールの種類を判別するためのもので、それぞれのファンクションコールに対応する番号が決められています。ファンクションコールを実行するときには、このファンクション番号をCレジスタにセットします。

コール手順

ファンクションコールの前準備として、レジスタやメモリに必要な値をセットしなければならないことがあります。ここでは、これを「コール手順」の部分に示します。

戻り値

ファンクションコールの結果得られた値は、レジスタやメモリにセットされます。獲得した値が、どこにどのようにセットされるかを、「戻り値」の部分に示します。
ただし、ファンクションコールでは、戻り値がセットされるレジスタ以外にも、ファンクション内での作業に使用され、内容が破壊されるレジスタがあります。ファンクションコールでは原則としてレジスタのもとの内容は保障していません。そこで、ファンクションコールを使用するときには、その前に、破壊されては困るレジスタの内容を、適当な場所(スタックなど)に退避して下さい。

解説

ファンクションコールの解説です。

表3.6 ファンクションコール一覧

ファンクション番号機能CP/M※ページ
00システムリセット 419
01コンソール1文字入力 419
02コンソール1文字出力 420
03補助装置1文字入力 421
04補助装置1文字入力 421
05プリンタ1文字出力 422
06コンソール直接入出力(入力時エコーバック、コントロールコードチェック、入力待無)422
07コンソール直接入出力(入力時エコーバック、コントロールコードチェック無)423
08コンソール直接入出力(入力時エコーバック無)423
09コンソール文字列出力424
0Aコンソール1行入力424
0Bコンソール入力チェック425
0Cバージョン番号の取り出し425
0Dディスクリセット426
0Eディフォルトドライブの設定426
0Fファイルのオープン427
10ファイルのクローズ428
11ファイルの検索(ワイルドカードに一致する最初のファイル)428
12ファイルの検索(ワイルドカードに一致する後続のファイル)429
13ファイルの削除429
14シーケンシャル読み出し430
15シーケンシャル書き込み430
16ファイルの作成431
17ファイル名の変更432
18ログインベクトルの獲得432
19ディフォルトドライブの獲得433
1A転送アドレスの設定433
1Bディスク情報の獲得434
21ランダム読み出し434
22ランダム書き込み435
23ファイルサイズの獲得435
24ランダムレコードの設定436
26ランダムブロック書き込み436
27ランダムブロック読み出し437
28ゼロ書き込みを伴うランダム書き込み438
2A日付の獲得438
2B日付の設定439
2C時刻の獲得440
2D時刻の設定440
2Eベリファイフラグの設定441
2F論理セクタの読み出し441
30論理セクタの書き込み442

注意
  • 「○」は、CP/M 2.2のファンクションとの互換性があるものを示している。

 ファンクションコールのファンクション番号は00H〜30Hですが、この中には以下の無効なファンクション番号があります。

  • 1CH〜20H、25H、29H

 これらの無効なファンクションコールを実行したときには、AレジスタとBレジスタに00Hがセットされる以外は何も行いません。また、31H以降のファンクション番号でも結果は同じです。

 4.3 ファンクションコールの解説

システムリセット

ファンクション

00H

コール手順

なし

戻り値

なし

機能

MSX-DOS上のプログラムからコールしたときには、MSX-DOSがウォームスタートし、DOSのコマンドレベルに戻ります。Disk BASIC上のプログラムからコールしたときには、Disk BASICがウォームスタートし、BASICのコマンドレベルに戻ります。このとき、ロードされているBASICのプログラムは破壊されません。

コンソール入力

ファンクション

01H

コール手順

なし

戻り値
Aコンソールから入力した1文字
解説

入力がないとき(キーボードバッファが空のとき)には、入力を待ちます。入力された文字はコンソールにエコーバックされます。以下に示すコントロールキャラクタはファンクション内部で処理されるため、入力としては扱いません。

[CTRL]+[C] システムリセット
[CTRL]+[P] プリンタへのエコー開始
[CTRL]+[N] プリンタへのエコー停止

[CTRL]+[C]が入力されるとプログラムの実行を中断してMSX-DOSのコマンドレベルに戻ります。[CTRL]+[P]が入力されると、以降のコンソール出力はすべてプリンタにもエコーします。この状態は、[CTRL]+[N]を入力することによって解除されます。

コンソール出力

ファンクション

02H

コール手順
E出力する文字コード
戻り値

なし

解説

Eレジスタで指定した文字を画面に表示します。この際、コンソール入力をチェックし、[CTRL]+[C]、[CTRL]+[P]、[CTRL]+[N]、[CTRL]+[S]の処理を行います。[CTRL]+[S]が入力されると、次に任意のキーを押すまでファンクション内部で入力待ちを行うので、プログラムの一時停止ができます。

補助入力

ファンクション

03H

コール手順

なし

戻り値
A補助入力装置(AUXデバイス)から読み込んだ1文字
解説

補助入力装置がセットされていないときは、EOF文字(1AH)を返します。コンソール入力は、ファンクション02Hと同様にチェックします。

補助出力

ファンクション

04H

コール手順
E補助出力装置(AUXデバイス)に出力する文字コード
戻り値

なし

解説

補助出力装置がセットされていないときは何もしません。出力は捨てられます。コンソール入力は、ファンクション02Hと同様にチェックします。

プリンタ出力

ファンクション

05H

コール手順
Eプリンタに出力する文字コード
戻り値

なし

解説

文字コードをプリンタに出力します。コンソール入力は、ファンクション02Hと同様にチェックします。

直接コンソール入出力

ファンクション

06H

コール手順
EFFH 入力
FFH以外セットされた値を文字コードとみなしてコンソールに出力
戻り値

■EレジスタがFFHだったとき(入力)

Aコンソール入力があるときはその文字コード
コンソールがないときは00H

■EレジスタがFFH以外だったとき(出力)

なし

解説

入力のとき、エコーバック、コントロールキャラクタの処理は行いません。(入力文字として扱われる)。また、出力のとき、プリンタへのエコーバックは行いません。

直接コンソール入力

ファンクション

07H

コール手順

なし

戻り値
Aコンソールから入力した1文字
解説

エコーバック、コントロールキャラクタの処理は行いません。
このファンクションコールはCP/Mとの互換性はありません。

コンソール入力

ファンクション

08H

コール手順

なし

戻り値
Aコンソールから入力した1文字
解説

エコーバックは行いません。コントロールキャラクタはファンクション01Hと同様に処理します。
このファンクションコールはCP/Mとの互換性はありません。

文字列出力

ファンクション

09H

コール手順
DEコンソールに出力する文字列があるメモリの先頭アドレス
戻り値

なし

解説

文字列の最後には、終端文字(ターミネータ)として「$」(24H)を置きます。最初に現れる「$」の直前までの文字列をコンソールに出力するので、「$」文字を出力することはできません。
コントロールキャラクタはファンクション02Hと同様にチェックします。

文字列入力

ファンクション

0AH

コール手順
DE行バッファの先頭アドレス
行バッファ+0最大入力文字数(1〜255)(図3.22参照)
戻り値
行バッファ+1 実際に入力された文字数
行バッファ+2〜コンソールから入力された文字列
解説

リターンキーの直前までをコンソールからの入力とみなします。最大入力文字数以上を入力することはできません。このファンクションコールによる文字列入力時には、テンプレートによる編集ができます。
このファンクションコールは、コントロールキャラクタをチェックします。


図3.24 行バッファの構造

コンソールの入力状態のチェック

ファンクション

0BH

コール手順

なし

戻り値
A FFH コンソール入力がある
00H コンソール入力がない
解説

コンソール入力の状態を調べます。入力文字があるとときもその文字は取り出しません。ただし、コントロールキャラクタはファンクション02Hと同様にチェックします。入力文字は、ファンクション01Hか08Hで取り出すことができます。

バージョン情報の獲得

ファンクション

0CH

コール手順

なし

戻り値
HL 0022H
解説

このファンクションコールは、CP/Mのバージョン番号を獲得するためのものです。MSX-DOSでは、必ず0022Hが戻ります。

ディスクリセット

ファンクション

0DH

コール手順

なし

戻り値

なし

解説

変更されて、まだディスクに書き込まれていないセクタがあれば、それをディスクに書き込んだ後、デフォルトドライブをAドライブにセットし、DTAを0080Hにセットします。

デフォルトドライブの設定

ファンクション

0EH

コール手順
E デフォルトドライブ番号(A=0、B=1、・・・H=7)
戻り値

なし

解説

デフォルトドライブを変更します、FCBなどのドライブ番号に「0」が指定されたときに有効です。接続されていないドライブが指定されたときには、変更しません。

ファイルのオープン

ファンクション

0FH

コール手順
DE オープンされていないFCBの先頭アドレス
FCBのカレントブロック読み出すブロック番号
戻り値
オープン成功のとき
A 0
FCBの各フィールドが設定される
オープン失敗のとき
A 0FFH
解説

FCBがファイル入出力のファンクションコールで使用できるようになります。レコードサイズ、カレントレコード、ランダムレコードの各フィールドは使用するファンクションに応じてオープンの後、ユーザープログラムで設定しなければなりません。

ファイルのクローズ

ファンクション

10H

コール手順
DE オープンされたFCBの先頭アドレス
戻り値
A 00H クローズ成功
FFH クローズ失敗
解説

現在のFCBの内容をディスク上の該当するディレクトリエリアに書き込むことによって、ファイルの更新に関する整合性を保ちます。ただし、ファイルの内容を変更していないときには、書き込みは行いません。クローズしたFCBはオープンされていないFCBとして再利用できます。また、オープンされたFCBとしてさらに入出力を続けることもできます。

ファイルの検索(最初の一致)

ファンクション

11H

コール手順
DE オープンされていないFCBの先頭アドレス
戻り値
A 00H ファイルが見つかった
0FFH ファイルが見つからなかった
ファイルが見つかったときは、DTAで指定される領域にドライブ番号を、それに続く32バイトにそのファイルのディスク上のディレクトリエントリをセットする。
解説

ファイル名にはワイルドカード文字の「?」を使用することができます。例えば、ファイル名の名前部分に「????????」、拡張子部分に「MAC」を設定すると、「MAC」という拡張子を持つファイルのうち、最初にマッチしたファイルのディレクトリ情報を得ることができます。ファンクションコールレベルでは、ワイルドカード文字の「*」はサポートしていないので、適当な数の「?」に置き換えて下さい。一致するファイルすべてを検索したいときや、一致するファイルが1個だけかどうかを知りたいときには、ファンクション12Hを利用します。
DTA領域に設定されたデータはオープンされていないFCBとして使用できます。

ファイルの検索(後続の一致)

ファンクション

12H

コール手順

なし

戻り値
A 00H ファイルが見つかった
FFH ファイルが見つからなかった
ファイルが見つかったときは、DTAで指定される領域にドライブ番号を、それに続く32バイトにそのファイルのディスク上のディレクトリエントリをセットする。
解説

このファンクションコールは、ファンクション11Hのワイルドカード文字によるファイル名の指定と一致した複数のファイルを検索するときに使います。単独で使用することはできません。このファンクションコールを繰り返し使用して、ファンクション11Hによって一致した複数のファイルのディレクトリ情報を、1つずつ順番に獲得していくことができます。
DTA領域に設定されたデータはオープンされていないFCBとして使用できます。

ファイルの削除

ファンクション

13H

コール手順
DE オープンされていないFCBの先頭アドレス
戻り値
A 00H 削除が成功
FFH 削除が失敗
解説

このファンクションコールでは、ファイル名にワイルドカード文字を指定して、複数のファイルを一度に削除することができます。

シーケンシャルな読み出し

ファンクション

14H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのカレントレコード読み出すレコード番号
戻り値
A 00H 読み出しが成功
01H 読み出しが失敗
読み出しが成功したときは、DTA以降の128バイトに読み込んだレコードをセットします。
解説

FCBのカレントブロックとカレントレコードは、読み出し後に次のレコードを指すように自動的に更新されます。したがって、連続して読み出すときは、カレントブロックとカレントレコードを再設定する必要はありません。
このファンクションコールが失敗するのは、ファイルの終わりに達したときです。また、読み出すレコードサイズは128バイト固定です。

シーケンシャルな書き込み

ファンクション

15H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのカレントレコード書き込むレコード番号
DTA以降の128バイト 書き込むデータ
戻り値
A 00H 書き込みが成功
01H 書き込みが失敗
解説

FCBのカレントブロックとカレントレコードは、書き込み後に次のレコードを指すように自動的に更新されます。したがって、連続して書き込むときには、カレントブロックとカレントレコードを再設定する必要はありません。
このファンクションコールが失敗するのは、ディスクの残り容量がなくなったときです。

ファイルの作成

ファンクション

16H

コール手順
DE オープンされていないFCBの先頭アドレス
FCBのカレントブロック読み出すブロック番号
戻り値
A 00H ファイルの作成が成功
FFH ファイルの作成が失敗
解説

FCB中のレコードサイズ、カレントレコード、ランダムレコードの各フィールドは、このファンクションコールの実行後に必要に応じて設定しなければなりません。
このファンクションコールが失敗するのは、ファイル名が正しくセットされていないか、ディレクトリに空きがないときです。

ファイル名の変更

ファンクション

17H

コール手順
DE オープンされていないFCBの先頭アドレス
FCB+0 旧ファイル名
FCB+16 新ファイル名
戻り値
A 00H ファイル名の変更が成功
FFH ファイル名の変更が失敗
解説

新旧ファイル名に、ワイルドカード文字を使用できます。例えば、旧ファイル名に「????????REL」を、新ファイル名に「????????LIB」を指定すれば、「REL」という拡張子のファイルがすべて、「LIB」という拡張子のファイルに変更されます。
新ファイル名のドライブ番号は無視されます。

ログインベクトルの獲得

ファンクション

18H

コール手順

なし

戻り値
HL オンラインドライブ情報
解説

MSXには最大8台のディスクドライブが接続できます。「オンラインドライブ」とは、MSXに実際に接続されているドライブを示します。このファンクションコールを実行すると、各ドライブがオンラインであるかどうかを調べ、結果を表3.7のようにHLレジスタに入れて返します。それぞれのビットが1ならば対応するドライブはオンラインであり、0ならば接続されていないことを示します。MSX-DOSのときは、Hレジスタは常に「0」です。

表3.7 ログインベクトル

レジスタHL
ビット 7654321076543210
ドライブ常に、0H:G:F:E:D:C:B:A:
オンライン・オフライン各ビットが「1」ならばオンライン、「0」ならばオフライン

デフォルトドライブ番号の獲得

ファンクション

19H

コール手順

なし

戻り値
A デフォルトドライブ番号(A=0、B=1、・・・H=7)
解説

現在設定されているドライブ番号を獲得します。

転送先アドレス(DTA)の設定

ファンクション

1AH

コール手順
DE設定するDTAアドレス
戻り値

なし

解説

DTAアドレスは、システムリセット時に0080Hに初期化されますが、このファンクションコールによって、任意アドレスに設定し直すことができます。

ディスク情報の獲得

ファンクション

1BH

コール手順
E目的のディスクが入っているドライブ番号
戻り値
A 1クラスタあたりの論理セクタ数
FFH指定ドライブがオフライン
BC セクタのサイズ(バイト単位)
DE クラスタの総数
HL 未使用クラスタの総数
IX DPBの先頭アドレス
IY FATバッファの先頭アドレス
解説

指定ドライブのディスクの情報を獲得します。ドライブ番号に「0」を指定すると、デフォルトドライブの指定になります。それ以外は、Aドライブなら「1」、Bドライブなら「2」、・・・を指定します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

ランダムな読み出し

ファンクション

21H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのランダムレコード読み出すレコード番号
戻り値
A 00H 読み出しが成功
01H 読み出しが失敗
読み出しが成功したときは、DTA以降の128バイトに読み込んだレコードをセットします。
解説

レコードの大きさは128バイト固定です。

ランダムな書き込み

ファンクション

22H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのランダムレコード書き込むレコード番号
DTA以降の128バイト 書き込むデータ
戻り値
A 00H 書き込みが成功
01H 書き込みが失敗
解説

レコードの大きさは128バイト固定です。

ファイルサイズの獲得

ファンクション

23H

コール手順
DE オープンされたFCBの先頭アドレス
戻り値
A 00H ファイルサイズの獲得が成功
FFH ファイルサイズの獲得が失敗
獲得が成功すれば、FCBのランダムレコードフィールドに指定されたファイルの128バイト単位のサイズをセットします。
解説

ファイルのサイズは128バイト単位です。200バイトのファイルであれば「2」が、257バイトのファイルであれば「3」が設定されます。

ランダムレコードフィールドの設定

ファンクション

24H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのカレントブロック目的のブロック
FCBのカレントレコード目的のレコード
戻り値

ランダムレコードフィールドに、指定されたFCBのカレントブロックフィールドとカレントレコードフィールドから計算したカレントレコードポジションを設定します。

ランダムブロック書き込み

ファンクション

26H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのレコードサイズ 書き込むレコードサイズ
FCBのランダムレコード書き込みを開始するレコード
HL 書き込むレコード数
DTA以降のメモリ領域 書き込むデータ
戻り値
A 00H 書き込みが成功
01H 書き込みが失敗
解説

書き込みが終わると、ランダムレコードフィールドの値が自動的に更新されて、最後に書き込んだレコードの次のレコードを指します。1つのレコードの大きさはFCBのレコードサイズフィールドによって1バイトから65535バイトまで任意に設定できます。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

ランダムブロック読み出し

ファンクション

27H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのレコードサイズ 読み出すレコードサイズ
FCBのランダムレコード読み出しを開始するレコード
HL 読み出すレコード数
戻り値
A 00H 読み出しが成功
01H 読み出しが失敗
HL 実際に読み込んだレコードの個数
解説

データの読み込みが終わると、ランダムレコードフィールドの値が自動的に更新されます。このファンクションコール実行後、HLレジスタには実際に読み込んだレコードの総数が設定されます。つまり、指定した数のレコードを読み込み終わる前にファイルの終わりに達してしまったときには、それまでに読み込んだ実際のレコード数がHLレジスタに入ることになります。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

「0」の書き込みをともなうランダムな書き込み

ファンクション

28H

コール手順
DE オープンされたFCBの先頭アドレス
FCBのランダムレコード書き込むレコード番号
DTA以降の128バイト 書き込むレコード
戻り値
A 00H 書き込みが成功
01H 書き込みが失敗
解説

レコードの大きさは128バイト固定です。
このファンクションコールでは、ファイルサイズより大きなレコード番号が指定されたとき、ファイルの終わりの次のレコードから指定されたレコードの直前までのレコードを「0」で埋めた後、指定されたレコードに書き込みます。「0」で埋める点を除けば、ファンクション22H(ランダムな書き込み)と同じです。

日付の獲得

ファンクション

2AH

コール手順

なし

戻り値
HL (1980〜2079)
D (1〜12)
E (1〜31)
A 曜日 (0=日曜、1=月曜、・・・6=土曜)
機能

クロックICに設定されている日付のデータを獲得します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

日付の設定

ファンクション

2BH

コール手順
HL (1980〜2079)
D (1〜12)
E (1〜31)
戻り値
A 00H 日付の設定が成功
FFH 日付の設定が失敗
機能

クロックICに指定した日付を設定します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

時刻の獲得

ファンクション

2CH

コール手順

なし

戻り値
H
L
D
E 1/100秒
機能

クロックICに設定されている時刻のデータを獲得します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

時刻の設定

ファンクション

2DH

コール手順
H
L
D
戻り値
A 00H 時刻の設定が成功
FFH 時刻の設定が失敗
機能

クロックICに時刻のデータを設定します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

ベリファイフラグの設定

ファンクション

2EH

コール手順
E 00H ベリファイフラグをリセット
01H ベリファイフラグをセット
戻り値

なし

機能

ベリファイフラグをセットすると、以降のディスクに対する書き込みをベリファイ付きで行います。ベリファイとは、書き込んだあとでその内容をディスクから読み込み、書き込むべき内容と比較して等しいかどうかをチェックする機能です。
ベリファイ機能はオプションであり、ドライブによってはその機能がないものもあります。その場合、ベリファイフラグを設定しても意味はありません。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

論理セクタの読み出し

ファンクション

2FH

コール手順
DE 読み出す論理セクタの番号(複数のときはその先頭の論理セクタ番号)
H 読み出す論理セクタの個数
L 読み出すディスクのドライブ番号(A=0、B=1、・・・H=7)
戻り値

DTA以降の(論理セクタサイズ×論理セクタの個数)バイトに読み込んだ内容を設定

機能

指定ドライブの指定論理セクタから指定された個数の論理セクタを読み出し、その内容をDTA以降のメモリに設定します。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。

論理セクタの書き込み

ファンクション

30H

コール手順
DE 書き込む論理セクタの番号(複数のときはその先頭の論理セクタ番号)
H 書き込む論理セクタの個数
L 書き込むディスクのドライブ番号(A=0、B=1、・・・H=7)
DTA以降の(論理セクタサイズ×論理セクタの個数)バイトに書き込むデータを設定
戻り値

なし

機能

DTA以降に設定されたデータを指定ドライブの指定論理セクタへ、指定された論理セクタの個数だけ書き込みます。
このファンクションコールはMSX-DOS独自のもので、CP/Mとの互換性はありません。