API には
- 結果の値を直接、受け取る
- 結果をユーザー・スペースに書き込む
の 2 種類の結果の戻し方がある。
ここでは最初に結果の値を直接、受け取る API として QUSROBJD ： オブジェクトの属性の検索を紹介しよう。
QUSROBJD は API の中でもかなり使用頻度が高い API であり、CLP 開発者が最初に使う API かも
知れないと思うほどポピュラーな API である。
QUSROBJD は DSPOBJD コマンドとほぼ同じ情報を提供する。
もちろん API であるので DSPOBJD より詳しい情報を高速で得ることができる。
今回のサンプルはライブラリー SPOOLWTR の 最終変更日 と 時刻 を QUSROBJD によって
取得するというものである。
オブジェクト記述の検索（QUSROBJD）API
必須パラメータ・グループ：
| 1. | レシーバー変数 | 出力 | Char(*) |
| 2. | レシーバー変数長 | 入力 | Binary(4) |
| 3. | 形式名 | 入力 | Binary(4) |
| 4. | オブジェクト修飾名 | 入力 | Char(10)の配列(*) |
| 5. | オブジェクト・タイプ | 入出力 | Char(*) |
任意選択パラメータ：
| 6. | エラー・コード | 入出力 | Char(*) |
【解説】
レシーバー変数 と レシーバー変数長 は形式名によって異なる。
形式名 は、
OBJD0100 形式 |
・・・・・・ | 基本情報(最高速) |
OBJD0200 形式 |
・・・・・・ | PDM によって表示される情報に良く似た情報 |
OBJD0300 形式 |
・・・・・・ | 保守情報 |
OBJD0400 形式 |
・・・・・・ | 全情報(最低速) |
レシーバー変数の構造
[参照メンバー] QSYSINC/H(QUSROBJD)
■ OBJD0100 形式
| オフセット | タイプ | フィールド | |
|---|---|---|---|
| 10進数 | 16進数 | ||
0 |
0 |
BINARY(4) |
返されるバイト数 |
4 |
4 |
BINARY(4) |
使用可能なバイト数 |
8 |
8 |
CHAR(10) |
オブジェクト名 |
18 |
12 |
CHAR(10) |
オブジェクト・ライブラリー名 |
28 |
1C |
CHAR(10) |
オブジェクト・タイプ |
38 |
26 |
CHAR(10) |
戻りライブラリー |
48 |
30 |
BINARY(4) |
補助記憶域プール |
52 |
34 |
CHAR(10) |
オブジェクト所有者 |
62 |
3E |
CHAR(2) |
オブドェクト・ドメイン |
64 |
40 |
CHAR(13) |
作成日時 |
77 |
40 |
CHAR(13) |
オブジェクト変更日時 |
■ OBJD0200 形式
| オフセット | タイプ | フィールド | |
|---|---|---|---|
| 10進数 | 16進数 | ||
0 |
0 |
OBJD0100 形式からのすべての情報 |
|
90 |
5A |
CHAR(10) |
オブジェクトの拡張属性 |
100 |
64 |
CHAR(50) |
テキスト記述 |
150 |
96 |
CHAR(10) |
ソース・ファイル名 |
160 |
A0 |
CHAR(10) |
ソース・ファイル・ライブラリー名 |
170 |
AA |
CHAR(10) |
ソース・ファイル・メンバー名 |
■ OBJD0300 形式
| オフセット | タイプ | フィールド | |
|---|---|---|---|
| 10進数 | 16進数 | ||
0 |
0 |
OBJD0200 形式からのすべての情報 |
|
180 |
B4 |
CHAR(13) |
ソース・ファイルの更新日時 |
193 |
C1 |
CHAR(13) |
オブジェクト保管日時 |
206 |
CE |
CHAR(13) |
オブジェクト復元日時 |
219 |
DB |
CHAR(10) |
作成者のユーザー・プロフィール |
229 |
E5 |
CHAR(8) |
オブジェクトが作成されたシステム |
237 |
ED |
CHAR(7) |
リセット日付 |
244 |
F4 |
BINARY(4) |
保管サイズ |
248 |
F8 |
BINARY(4) |
保管順序番号 |
252 |
FC |
CHAR(10) |
記憶域 |
262 |
106 |
CHAR(10) |
保管コマンド |
272 |
110 |
CHAR(71) |
保管ボリュームID |
343 |
157 |
CHAR(10) |
保管装置 |
353 |
161 |
CHAR(10) |
保管ファイル名 |
363 |
16B |
CHAR(10) |
保管ファイル・ライブラリー名 |
373 |
175 |
CHAR(17) |
保管ラベル |
390 |
186 |
CHAR(9) |
システム・レベル |
399 |
18F |
CHAR(16) |
コンパイラー |
415 |
19F |
CHAR(8) |
オブジェクト・レベル |
423 |
1A7 |
CHAR(1) |
ユーザーの変更 |
424 |
1A8 |
CHAR(16) |
ライセンス・プログラム |
440 |
1B8 |
CHAR(10) |
プログラム一時修正(PTF) |
450 |
1C2 |
CHAR(10) |
プログラム診断依頼書(APAR) |
■ OBJD0400 形式
| オフセット | タイプ | フィールド | |
|---|---|---|---|
| 10進数 | 16進数 | ||
0 |
0 |
OBJD0300 形式からのすべての情報 |
|
460 |
1CC |
CHAR(7) |
最終使用日付 |
467 |
1D3 |
CHAR(1) |
使用状況の更新 |
468 |
1D4 |
BINARY(4) |
使用日数カウント |
472 |
1D8 |
BINARY(4) |
オブジェクト・サイズ |
476 |
1DC |
BINARY(4) |
オブジェクト・サイズの乗数 |
480 |
1E0 |
CHAR(1) |
オブジェクト圧縮状況 |
481 |
1E1 |
CHAR(1) |
プログラムによる変更許可< |
482 |
1E2 |
CHAR(1) |
プログラムによる変更 |
483 |
1E3 |
CHAR(10) |
ユーザー定義属性 |
493 |
1ED |
CHAR(1) |
オブジェクト ASP オーバーフロー標識 |
494 |
1EE |
CHAR(13) |
SAVACT 保管日時 |
507 |
1FB |
CHAR(10) |
オブジェクト監査値 |
517 |
205 |
CHAR(10) |
1次グループ |
001.00 H DATEDIT(*YMD/)
002.00 F********** ライブラリーの更新日付時刻の検索 *************************
003.00 F* QUSROBJD のサンプル
004.00 F**********************************************************************
005.00 /COPY QSYSINC/QRPGLESRC,QUSROBJD
006.00 D OBJOBJLIB S 20A INZ('SPOOLWTR *LIBL ')
007.00 D CPFMSG C CONST('QCPFMSG *LIBL ')
008.00 D RCVLEN S 4B 0 INZ(%SIZE(QUSD0100))
009.00
010.00 D APIERR DS
011.00 D GETBYT 1 4B 0 INZ(160)
012.00 D AVLBYT 5 8B 0 INZ(0)
013.00 D MSGID 9 15
014.00 D MSGDTA 17 160
015.00
016.00 D SPCBIN DS
017.00 D MSGDTALEN 4B 0 INZ(100) 小数
018.00 D PGMSTKCNT 4B 0 INZ(1) 小数
019.00 D DATE 6A 小数
020.00 D TIME 6A 小数
021.00
022.00 C*----------------------------------------------------+
023.00 C CALL QUSROBJD
0024.00 C PARM QUSD0100
0025.00 C PARM RCVLEN
0026.00 C PARM 'OBJD0100' FOTMAT 8
0027.00 C PARM OBJOBJLIB
0028.00 C PARM '*LIB ' OBJTYPE 10
0029.00 C PARM APIERR
0030.00 C*----------------------------------------------------+
0031.00 C AVLBYT IFEQ *ZEROS
0032.00 C EVAL DATE = %SUBST(QUSCDT11:2:6)
0033.00 C 'DATE=20' CAT(P) DATE:0 DSP40 40
0034.00 C DSP40 DSPLY ANS 1
0035.00 C EVAL TIME = %SUBST(QUSCDT11:8:6)
0036.00 C 'TIME=' CAT(P) TIME:0 DSP40 40
0037.00 C DSP40 DSPLY ANS 1
0038.00 C ELSE
0039.00 C MOVEL CPFMSG MSGFILLIB
0040.00 C*----------------------------------------------------+
0041.00 C CALL 'QMHSNDPM' 99
0042.00 C PARM MSGID
0043.00 C PARM MSGFILLIB 20
0044.00 C PARM MSGDTA
0045.00 C PARM MSGDTALEN
0046.00 C PARM '*COMP ' MSGTYPE 10
0047.00 C PARM '*PGMBDY ' PGMQUE 10
048.00 C PARM PGMSTKCNT
049.00 C PARM MSGKEY 4
050.00 C PARM APIERR
051.00 C*----------------------------------------------------+
052.00 C END
053.00 C MOVE *ON *INLR
054.00 C RETURN 
【解説】
このサンプルRPGはサンプルとは言ってもエラー処理は相当、念入りにバッチや対話式で
行なわれた場合も含めて考慮されている。
RPG で API を利用するときのミソは
005.00 /COPY QSYSINC/QRPGLESRC,QUSROBJD
のようにして i5/OS で提供されているメンバー QSYSINC/QRPGLESRC(QUSROBJD) を参照して
利用することである。
このメンバーには戻り値の型が DS (データ・ストラクチャー) で定義されているので、
自分で定義しなくても便利である。
ただし API は OS のリリース・アップに従って予告なく拡張されるので
そのままでは上位の OS に移行したときに戻り値の長さが不足してエラーで
停止してしまう場合がある。
賢いAPI は戻り値の長さを見てその長さの分だけ戻すのもあるが、多くは実行時の
エラーとなってしまうので RPG を使用しているプログラムであっても上位互換は必ずしも
保証されず、再コンパイルが必要となる場合もあるので API を使っている高度な
プログラムの移行には注意が必要である。
さて、API : QUSROBJD は
0005.00 /COPY QSYSINC/QRPGLESRC,QUSROBJD
0006.00 D OBJOBJLIB S 20A INZ('SPOOLWTR *LIBL ')
0007.00 D CPFMSG C CONST('QCPFMSG *LIBL ')
0008.00 D RCVLEN S 4B 0 INZ(%SIZE(QUSD0100))
:
0022.00 C*----------------------------------------------------+
0023.00 C CALL QUSROBJD
0024.00 C PARM QUSD0100
0025.00 C PARM RCVLEN
0026.00 C PARM 'OBJD0100' FOTMAT 8
0027.00 C PARM OBJOBJLIB
0028.00 C PARM '*LIB ' OBJTYPE 10
0029.00 C PARM APIERR
0030.00 C*----------------------------------------------------+
として実行されていて、ライブラリー SPOOLWTR の変更日付と時刻を調べようとしている。
API の結果の値を受け取るレシーバー変数 &RCVVAR は 90 バイトで十分であるが
将来、API が拡張されることに準備して 256 バイトと余裕を持った長さで定義されており
レシーバー変数の長さ: RCVLEN も
0008.00 D RCVLEN S 4B 0 INZ(%SIZE(QUSD0100))
として 160 バイトで定義しておく必要がある。
0031.00 C AVLBYT IFEQ *ZEROS
:
0038.00 C ELSE
0039.00 C MOVEL CPFMSG MSGFILLIB
0040.00 C*----------------------------------------------------+
0041.00 C CALL 'QMHSNDPM' 99
0042.00 C PARM MSGID
0043.00 C PARM MSGFILLIB 20
0044.00 C PARM MSGDTA
0045.00 C PARM MSGDTALEN
0046.00 C PARM '*COMP ' MSGTYPE 10
0047.00 C PARM '*PGMBDY ' PGMQUE 10
0048.00 C PARM PGMSTKCNT
0049.00 C PARM MSGKEY 4
0050.00 C PARM APIERR
0051.00 C*----------------------------------------------------+
0052.00 C END
のように API : QUSROBJD の実行でエラーがあった場合は QCPFMSG の MSGID と MSGDTA を
0010.00 D APIERR DS 0011.00 D GETBYT 1 4B 0 INZ(160) 0012.00 D AVLBYT 5 8B 0 INZ(0) 0013.00 D MSGID 9 15 0014.00 D MSGDTA 17 160
のようにして取得してエラー・メッセージを表示することができる。
首尾よく &RCVMSG を受け取ることができたら
0032.00 C EVAL DATE = %SUBST(QUSCDT11:2:6) 0033.00 C 'DATE=20' CAT(P) DATE:0 DSP40 40 0034.00 C DSP40 DSPLY ANS 1 0035.00 C EVAL TIME = %SUBST(QUSCDT11:8:6) 0036.00 C 'TIME=' CAT(P) TIME:0 DSP40 40 0037.00 C DSP40 DSPLY ANS 1
のようにして変更日付と時刻を検索することができる。