Windows アプリケーション・パッケージ

by user

on 28 марта 2017

Category: Documents

>> Downloads: 215

1575

views

Report

Comments

Description

Download Windows アプリケーション・パッケージ

Transcript

Windows アプリケーション・パッケージ

IBM i
バージョン 7.3
IBM i 接続
IBM i Access Client
ソリューション - Windows
アプリケーション・パッケージ:
プログラミング
IBM
IBM i
バージョン 7.3
IBM i 接続
IBM i Access Client
ソリューション - Windows
アプリケーション・パッケージ:
プログラミング
IBM
ご注意!
本書および本書で紹介する製品をご使用になる前に、 575 ページの『特記事項』に記載されている情報をお読みください。
本書にはライセンス内部コードについての参照が含まれている場合があります。ライセンス内部コードは機械コード
であり、IBM 機械コードのご使用条件に基づいて使用権を許諾するものです。
お客様の環境によっては、資料中の円記号がバックスラッシュと表示されたり、バックスラッシュが円記号と表示さ
れたりする場合があります。
原典：
IBM i
Version 7.3
Connecting to IBM i
IBM i Access Client Solutions Windows Application Package: Programming
発行：
日本アイ・ビー・エム株式会社
担当：
トランスレーション・サービス・センター
© Copyright IBM Corporation 2013.
目次
Windows アプリケーション・パッケージ
: プログラミング . . . . . . . . . . . 1
Windows アプリケーション・パッケージのPDF ファ
イル: プログラミング . . . . . . . . . . . 1
C/C++ API . . . . . . . . . . . . . . . 2
C/C++ API の概要 . . . . . . . . . . . 2
API グループ、ヘッダー・ファイル、インポー
ト・ライブラリー、および DLL . . . . . . 2
Programmer's Toolkit . . . . . . . . . . 4
Programmer's Toolkit のインストール . . . 4
Programmer's Toolkit の立ち上げ . . . . . 5
接続 API 用の IBM i 名の形式 . . . . . . 5
OEM、ANSI、およびユニコードの考慮事項 . . 6
単一の API タイプの使用 . . . . . . . 7
API タイプの混合使用 . . . . . . . . 8
汎用 Windows アプリケーション・パッケー
ジアプリケーションの作成 . . . . . . 8
戻りコードおよびエラー・メッセージ . . . . 9
オペレーティング・システム・エラーに対応
する戻りコード . . . . . . . . . . 9
戻りコード . . . . . . . . . . . 10
構成要素固有の戻りコード . . . . . . 17
管理 API . . . . . . . . . . . . . . 27
管理 API のリスト . . . . . . . . . . 28
cwbAD_GetClientVersion . . . . . . . 28
cwbAD_GetProductFixLevel . . . . . . 29
cwbAD_IsComponentInstalled . . . . . . 29
例: 管理 API . . . . . . . . . . . . 33
通信およびセキュリティー API . . . . . . . 38
システム・オブジェクトの属性 . . . . . . 39
システム・オブジェクトの属性のリスト . . 39
通信およびセキュリティー: 作成および削除の
API . . . . . . . . . . . . . . . 43
cwbCO_CreateSystem . . . . . . . . 43
cwbCO_CreateSystemLike . . . . . . . 44
cwbCO_DeleteSystem . . . . . . . . 45
通信およびセキュリティー: 接続および切断の
API . . . . . . . . . . . . . . . 46
cwbCO_Connect . . . . . . . . . . 46
cwbCO_Disconnect . . . . . . . . . 48
cwbCO_GetConnectTimeout . . . . . . 49
cwbCO_GetPersistenceMode . . . . . . 50
cwbCO_IsConnected . . . . . . . . . 51
cwbCO_SetConnectTimeout. . . . . . . 52
cwbCO_SetPersistenceMode . . . . . . 53
cwbCO_Verify. . . . . . . . . . . 54
通信およびセキュリティー: セキュリティー妥
当性検査とデータの API . . . . . . . . 55
cwbCO_ChangePassword . . . . . . . 55
cwbCO_GetDefaultUserMode . . . . . . 58
© Copyright IBM Corp. 2013
cwbCO_GetFailedSignons . . . . . . . 58
cwbCO_GetPasswordExpireDate . . . . . 59
cwbCO_GetPrevSignonDate. . . . . . . 60
cwbCO_GetPromptMode . . . . . . . 61
cwbCO_GetSignonDate . . . . . . . . 62
cwbCO_GetUserIDEx . . . . . . . . 63
cwbCO_GetValidateMode . . . . . . . 64
cwbCO_GetWindowHandle . . . . . . . 65
cwbCO_HasSignedOn . . . . . . . . 66
cwbCO_SetDefaultUserMode . . . . . . 67
cwbCO_SetPassword . . . . . . . . . 68
cwbCO_SetPromptMode . . . . . . . . 69
cwbCO_SetUserIDEx. . . . . . . . . 71
cwbCO_SetWindowHandle . . . . . . . 72
cwbCO_SetValidateMode . . . . . . . 73
cwbCO_Signon . . . . . . . . . . 74
cwbCO_VerifyUserIDPassword . . . . . 76
通信およびセキュリティー: 属性取得および属
性設定の API . . . . . . . . . . . . 77
cwbCO_CanModifyDefaultUserMode . . . . 77
cwbCO_CanModifyIPAddress . . . . . . 78
cwbCO_CanModifyIPAddressLookupMode . . 79
cwbCO_CanModifyPersistenceMode . . . . 80
cwbCO_CanModifyPortLookupMode . . . . 81
cwbCO_CanModifyUseSecureSockets. . . . 82
cwbCO_GetDescription . . . . . . . . 82
cwbCO_GetHostCCSID . . . . . . . . 83
cwbCO_GetHostVersionEx . . . . . . . 84
cwbCO_GetIPAddress . . . . . . . . 85
cwbCO_GetIPAddressLookupMode . . . . 86
cwbCO_GetPortLookupMode . . . . . . 87
cwbCO_GetSystemName . . . . . . . 88
cwbCO_IsSecureSockets . . . . . . . . 89
cwbCO_SetIPAddress . . . . . . . . 90
cwbCO_SetIPAddressLookupMode . . . . 91
cwbCO_SetPortLookupMode . . . . . . 92
cwbCO_UseSecureSockets . . . . . . . 94
cwbCO_Service の定義 . . . . . . . . . 95
cwbCO_Signon と
cwbCO_VerifyUserIDPassword の相違点 . . . 95
cwbCO_Signon と
cwbCO_VerifyUserIDPassword の類似点 . . . 96
通信: 作成および削除の API. . . . . . . 96
cwbCO_CreateSysListHandle . . . . . . 96
cwbCO_CreateSysListHandleEnv . . . . . 97
cwbCO_DeleteSysListHandle . . . . . . 98
cwbCO_GetNextSysName . . . . . . . 99
cwbCO_GetSysListSize. . . . . . . . 100
通信: システム情報 API . . . . . . . . 101
cwbCO_GetActiveConversations . . . . . 101
cwbCO_GetConnectedSysName . . . . . 101
iii
cwbCO_GetDefaultSysName . . . . . .
cwbCO_IsSystemConfigured . . . . . .
cwbCO_IsSystemConfiguredEnv . . . . .
cwbCO_IsSystemConnected . . . . . .
通信: 構成済み環境情報 . . . . . . . .
cwbCO_GetActiveEnvironment . . . . .
cwbCO_GetEnvironmentName . . . . .
cwbCO_GetNumberOfEnvironments . . . .
通信: 環境および接続情報 . . . . . . .
cwbCO_CanConnectNewSystem . . . . .
cwbCO_CanModifyEnvironmentList . . . .
cwbCO_CanModifySystemList . . . . .
cwbCO_CanModifySystemListEnv . . . .
cwbCO_CanSetActiveEnvironment . . . .
例: 通信 API の使用 . . . . . . . . .
IBM i データ待ち行列 API . . . . . . . .
データ待ち行列. . . . . . . . . . .
データ待ち行列メッセージの配列. . . . .
データ待ち行列の操作 . . . . . . . .
データ待ち行列の一般的な使用方法 . . . .
データ待ち行列: 作成、削除、およびオープ
ンの API . . . . . . . . . . . . .
cwbDQ_CreateEx . . . . . . . . .
cwbDQ_DeleteEx . . . . . . . . .
cwbDQ_OpenEx . . . . . . . . . .
データ待ち行列: データ待ち行列 API へのア
クセス. . . . . . . . . . . . . .
cwbDQ_AsyncRead . . . . . . . . .
cwbDQ_Cancel . . . . . . . . . .
cwbDQ_CheckData . . . . . . . . .
cwbDQ_Clear . . . . . . . . . .
cwbDQ_Close . . . . . . . . . .
cwbDQ_GetLibName . . . . . . . .
cwbDQ_GetQueueAttr . . . . . . . .
cwbDQ_GetQueueName . . . . . . .
cwbDQ_GetSysName . . . . . . . .
cwbDQ_Peek . . . . . . . . . . .
cwbDQ_Read. . . . . . . . . . .
cwbDQ_Write . . . . . . . . . .
データ待ち行列: 属性 API . . . . . . .
cwbDQ_CreateAttr . . . . . . . . .
cwbDQ_DeleteAttr . . . . . . . . .
cwbDQ_GetAuthority . . . . . . . .
cwbDQ_GetDesc. . . . . . . . . .
cwbDQ_GetForceToStorage . . . . . .
cwbDQ_GetKeySize . . . . . . . .
cwbDQ_GetMaxRecLen . . . . . . .
cwbDQ_GetOrder . . . . . . . . .
cwbDQ_GetSenderID . . . . . . . .
cwbDQ_SetAuthority . . . . . . . .
cwbDQ_SetDesc . . . . . . . . . .
cwbDQ_SetForceToStorage . . . . . .
cwbDQ_SetKeySize . . . . . . . . .
cwbDQ_SetMaxRecLen . . . . . . .
cwbDQ_SetOrder . . . . . . . . .
cwbDQ_SetSenderID . . . . . . . .
iv
102
103
104
105
105
105
106
107
108
108
109
109
110
110
111
122
123
123
123
124
125
125
127
129
131
131
132
133
134
135
136
137
137
138
139
140
141
143
143
143
144
145
145
146
147
147
148
149
150
151
151
152
153
154
IBM i: Windows アプリケーション・パッケージ: プログラミング
データ待ち行列: 読み取りおよび書き込み
API . . . . . . . . . . . . . .
cwbDQ_CreateData . . . . . . . .
cwbDQ_DeleteData . . . . . . . .
cwbDQ_GetConvert . . . . . . . .
cwbDQ_GetData . . . . . . . . .
cwbDQ_GetDataAddr . . . . . . .
cwbDQ_GetDataLen . . . . . . .
cwbDQ_GetKey . . . . . . . . .
cwbDQ_GetKeyLen . . . . . . . .
cwbDQ_GetRetDataLen . . . . . .
cwbDQ_GetRetKey . . . . . . . .
cwbDQ_GetRetKeyLen. . . . . . .
cwbDQ_GetSearchOrder . . . . . .
cwbDQ_GetSenderInfo . . . . . . .
cwbDQ_SetConvert . . . . . . . .
cwbDQ_SetData . . . . . . . . .
cwbDQ_SetDataAddr . . . . . . .
cwbDQ_SetKey . . . . . . . . .
cwbDQ_SetSearchOrder . . . . . .
例: データ待ち行列 API の使用法 . . .
データ形式変更および各国語サポート (NLS)
API . . . . . . . . . . . . . . .
データ形式変更 API . . . . . . . .
データ形式変更 API リスト . . . .
例: データ形式変更 API の使用法 . .
各国語サポート (NLS) API . . . . . .
コード化文字セット . . . . . . .
汎用 NLS API のリスト. . . . . .
変換 NLS API のリスト. . . . . .
ダイアログ・ボックス NLS API リスト
例: NLS API . . . . . . . . .
システム・オブジェクト API . . . . . .
システム・オブジェクトの属性 . . . .
高機能印刷 . . . . . . . . . .
ページの位置合わせ . . . . . . .
直接印刷可能 . . . . . . . . .
権限 . . . . . . . . . . . .
検査権限 . . . . . . . . . . .
書き出しプログラムの自動終了 . . .
バック・マージン・オフセット (横方向)
バック・マージン・オフセット (下方向)
背面オーバーレイ・ライブラリー名 . .
背面オーバーレイの名前. . . . . .
背面オーバーレイ・オフセット (横方向)
背面オーバーレイ・オフセット (下方向)
1 インチ当たり文字数 . . . . . .
コード・ページ. . . . . . . . .
コード化フォント名 . . . . . . .
コード化フォント・ライブラリー名 . .
コピー. . . . . . . . . . . .
作成されていない残りのコピー . . .
現行ページ . . . . . . . . . .
データ形式 . . . . . . . . . .
データ待ち行列ライブラリー名 . . .
データ待ち行列名 . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
154
154
155
155
156
157
158
158
159
160
160
161
162
163
164
164
165
166
167
168
.
.
.
.
.
.
.
.
169
169
170
188
188
189
190
197
210
217
219
219
220
220
220
220
220
221
221
221
221
221
222
222
222
222
222
223
223
223
223
223
223
224
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
ファイルがオープンされた日付 . . . .
ユーザー指定の DBCS データ . . . . .
DBCS 拡張文字 . . . . . . . . .
DBCS 文字回転 . . . . . . . . .
1 インチ当たりの DBCS 文字数 . . . .
DBCS SO/SI スペース . . . . . . .
書き出し据え置き . . . . . . . . .
ページ回転の角度 . . . . . . . . .
送信後にファイルを削除. . . . . . .
宛先オプション. . . . . . . . . .
宛先タイプ . . . . . . . . . . .
装置クラス . . . . . . . . . . .
装置型式 . . . . . . . . . . . .
装置タイプ . . . . . . . . . . .
ファイルの表示. . . . . . . . . .
区切りページの用紙入れ. . . . . . .
終了ページ . . . . . . . . . . .
ファイル区切り. . . . . . . . . .
レコードの折り返し . . . . . . . .
フォント識別コード . . . . . . . .
用紙送り . . . . . . . . . . . .
用紙タイプ . . . . . . . . . . .
用紙タイプ・メッセージ・オプション . .
フロント・マージン・オフセット (横方向)
フロント・マージン・オフセット (下方向)
前面オーバーレイ・ライブラリー名 . . .
前面オーバーレイ名 . . . . . . . .
前面オーバーレイ・オフセット (横方向)
前面オーバーレイ・オフセット (下方向)
グラフィック文字セット. . . . . . .
ハードウェア位置合わせ. . . . . . .
スプール・ファイルの保留 . . . . . .
書き出しプログラムの初期設定 . . . .
IP アドレス . . . . . . . . . . .
ジョブ名 . . . . . . . . . . . .
ジョブ番号 . . . . . . . . . . .
ジョブ区切り . . . . . . . . . .
ジョブ・ユーザー . . . . . . . . .
印刷された最終ページ . . . . . . .
ページの長さ . . . . . . . . . .
ライブラリー名. . . . . . . . . .
1 インチ当たりの行数 . . . . . . .
メーカー、機種型式 . . . . . . . .
スプール出力レコードの最大数 . . . .
測定方法 . . . . . . . . . . . .
メッセージ・ヘルプ . . . . . . . .
メッセージ ID . . . . . . . . . .
メッセージ待ち行列ライブラリー名 . . .
メッセージ待ち行列 . . . . . . . .
メッセージ応答. . . . . . . . . .
メッセージ・テキスト . . . . . . .
メッセージ・タイプ . . . . . . . .
メッセージ重大度 . . . . . . . . .
読み取り/書き込みバイト数 . . . . . .
ファイル数 . . . . . . . . . . .
224
224
224
224
225
225
225
225
225
226
226
226
226
226
227
227
227
227
227
228
228
228
228
228
229
229
229
229
229
230
230
230
230
230
231
231
231
231
231
232
232
232
232
232
232
233
233
233
233
233
234
234
234
234
235
待ち行列に対して開始された書き出しプロ
グラムの数 . . . . . . . . . . .
オブジェクト拡張属性 . . . . . . .
オープン時のコマンド . . . . . . .
オペレーター制御 . . . . . . . . .
待ち行列上のファイルの順序 . . . . .
出力優先順位 . . . . . . . . . .
出力待ち行列ライブラリー名 . . . . .
出力待ち行列名. . . . . . . . . .
出力待ち行列の状況 . . . . . . . .
オーバーフロー行番号 . . . . . . .
面当たりページ数 . . . . . . . . .
ペル密度 . . . . . . . . . . . .
ポイント・サイズ . . . . . . . . .
印刷精度 . . . . . . . . . . . .
両面印刷 . . . . . . . . . . . .
印刷品質 . . . . . . . . . . . .
印刷順序 . . . . . . . . . . . .
印刷テキスト . . . . . . . . . .
プリンター . . . . . . . . . . .
プリンター・タイプ . . . . . . . .
プリンター・ファイル・ライブラリー名
プリンター・ファイル名. . . . . . .
プリンター待ち行列 . . . . . . . .
レコードの長さ. . . . . . . . . .
リモート・システム . . . . . . . .
印刷不能文字の置き換え. . . . . . .
置換文字 . . . . . . . . . . . .
資源ライブラリー名 . . . . . . . .
資源名. . . . . . . . . . . . .
資源オブジェクト・タイプ . . . . . .
印刷の再始動 . . . . . . . . . .
スプール・ファイルの保管 . . . . . .
シーク・オフセット . . . . . . . .
起点のシーク . . . . . . . . . .
送信優先順位 . . . . . . . . . .
区切りページ . . . . . . . . . .
ソース・ドロワー . . . . . . . . .
スプール SCS . . . . . . . . . .
データのスプール . . . . . . . . .
スプール・ファイル名 . . . . . . .
スプール・ファイル番号. . . . . . .
スプール・ファイルの状況 . . . . . .
スプール出力のスケジュール . . . . .
開始ページ . . . . . . . . . . .
テキスト記述 . . . . . . . . . .
ファイルがオープンされた時刻 . . . .
合計ページ . . . . . . . . . . .
SCS から ASCII への変換 . . . . . .
計測単位 . . . . . . . . . . . .
ユーザー・コメント . . . . . . . .
ユーザー・データ . . . . . . . . .
ユーザー定義データ . . . . . . . .
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト名 . . . . .
ユーザー定義オブジェクト・タイプ . . .
235
235
235
235
236
236
236
236
236
237
237
237
237
237
238
238
238
238
238
239
239
239
239
239
240
240
240
240
240
240
241
241
241
241
241
242
242
242
242
243
243
243
243
243
244
244
244
244
244
245
245
245
245
245
246
目次
v
ユーザー定義オプション. . . . . . .
ユーザー・ドライバー・プログラム . . .
ユーザー・ドライバー・プログラム・ライ
ブラリー . . . . . . . . . . . .
ユーザー・ドライバー・プログラム名 . .
ユーザー ID . . . . . . . . . . .
ユーザー ID アドレス . . . . . . .
ユーザー変換プログラム・ライブラリー
ユーザー変換プログラム名 . . . . . .
VM/MVS クラス . . . . . . . . .
書き出しプログラムの自動終了時点 . . .
書き出しプログラムの終了時点 . . . .
ファイルの保留時点 . . . . . . . .
ページ幅 . . . . . . . . . . . .
ワークステーション・カスタマイズ・オブ
ジェクト名 . . . . . . . . . . .
ワークステーション・カスタマイズ・オブ
ジェクト・ライブラリー. . . . . . .
書き出しプログラム・ジョブ名 . . . .
書き出しプログラム・ジョブ番号. . . .
書き出しプログラム・ジョブ状況. . . .
書き出しプログラム・ジョブ・ユーザー名
書き出しプログラム開始ページ . . . .
ネットワーク印刷サーバー・オブジェクト
の属性. . . . . . . . . . . . .
リスト API . . . . . . . . . . . .
cwbOBJ_CloseList . . . . . . . . .
cwbOBJ_CreateListHandle. . . . . . .
cwbOBJ_DeleteListHandle. . . . . . .
cwbOBJ_GetListSize . . . . . . . .
cwbOBJ_OpenList . . . . . . . . .
cwbOBJ_ResetListAttrsToRetrieve . . . .
cwbOBJ_ResetListFilter . . . . . . .
cwbOBJ_SetListAttrsToRetrieve . . . . .
cwbOBJ_SetListFilter . . . . . . . .
cwbOBJ_SetListFilterWithSplF . . . . .
オブジェクト API . . . . . . . . . .
cwbOBJ_CopyObjHandle . . . . . . .
cwbOBJ_DeleteObjHandle . . . . . . .
cwbOBJ_GetObjAttr . . . . . . . .
cwbOBJ_GetObjAttrs . . . . . . . .
cwbOBJ_GetObjHandle . . . . . . .
cwbOBJ_GetObjHandleFromID . . . . .
cwbOBJ_GetObjID . . . . . . . . .
cwbOBJ_RefreshObj . . . . . . . .
cwbOBJ_SetObjAttrs . . . . . . . .
パラメーター・オブジェクト API . . . .
cwbOBJ_CopyParmObjHandle . . . . .
cwbOBJ_CreateParmObjHandle . . . . .
cwbOBJ_DeleteParmObjHandle . . . . .
cwbOBJ_GetParameter . . . . . . . .
cwbOBJ_SetParameter . . . . . . . .
書き出しプログラム・ジョブ API . . . .
cwbOBJ_EndWriter . . . . . . . . .
cwbOBJ_StartWriter . . . . . . . .
出力待ち行列 API . . . . . . . . . .
vi
246
246
246
246
247
247
247
247
247
247
248
248
248
248
248
249
249
249
249
249
250
252
252
253
254
255
256
257
257
258
259
263
264
264
265
266
270
272
273
274
275
276
279
279
280
280
281
282
283
284
285
286
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbOBJ_HoldOutputQueue . . . . . .
cwbOBJ_PurgeOutputQueue . . . . . .
cwbOBJ_ReleaseOutputQueue . . . . .
AFP 資源 API . . . . . . . . . . .
cwbOBJ_CloseResource . . . . . . .
cwbOBJ_CreateResourceHandle . . . . .
cwbOBJ_DisplayResource . . . . . . .
cwbOBJ_OpenResource . . . . . . .
cwbOBJ_OpenResourceForSplF . . . . .
cwbOBJ_ReadResource. . . . . . . .
cwbOBJ_SeekResource . . . . . . . .
新規スプール・ファイル用 API . . . . .
cwbOBJ_CloseNewSplF . . . . . . .
cwbOBJ_CloseNewSplFAndGetHandle . . .
cwbOBJ_CreateNewSplF . . . . . . .
cwbOBJ_GetSplFHandleFromNewSplF . . .
cwbOBJ_WriteNewSplF . . . . . . .
スプール・ファイルの読み取り API . . . .
cwbOBJ_CloseSplF . . . . . . . . .
cwbOBJ_OpenSplF . . . . . . . . .
cwbOBJ_ReadSplF . . . . . . . . .
cwbOBJ_SeekSplF . . . . . . . . .
スプール・ファイルの操作 API . . . . .
cwbOBJ_CallExitPgmForSplF. . . . . .
cwbOBJ_CreateSplFHandle . . . . . .
cwbOBJ_CreateSplFHandleEx . . . . .
cwbOBJ_DeleteSplF . . . . . . . .
cwbOBJ_DisplaySplF . . . . . . . .
cwbOBJ_HoldSplF . . . . . . . . .
cwbOBJ_IsViewerAvailable . . . . . .
cwbOBJ_MoveSplF . . . . . . . . .
cwbOBJ_ReleaseSplF . . . . . . . .
cwbOBJ_SendNetSplF . . . . . . . .
cwbOBJ_SendTCPSplF. . . . . . . .
スプール・ファイル・メッセージを処理する
API . . . . . . . . . . . . . . .
cwbOBJ_AnswerSplFMsg . . . . . . .
cwbOBJ_GetSplFMsgAttr . . . . . . .
スプール・ファイル・データを分析する API
cwbOBJ_AnalyzeSplFData. . . . . . .
API のサーバー・プログラム . . . . . .
cwbOBJ_DropConnections. . . . . . .
cwbOBJ_GetNPServerAttr . . . . . . .
cwbOBJ_SetConnectionsToKeep . . . . .
例: システム・オブジェクト API の使用法
リモート・コマンド/分散プログラム呼び出し
API . . . . . . . . . . . . . . . .
リモート・コマンド/分散プログラム呼び出し
API の一般的な使用法 . . . . . . . .
リモート・コマンド/分散プログラム呼び出し:
リモート・コマンド API リストへのアクセス
cwbRC_GetClientCCSID . . . . . . .
cwbRC_GetHostCCSID . . . . . . .
cwbRC_StartSysEx . . . . . . . . .
cwbRC_StopSys . . . . . . . . . .
286
287
288
289
289
290
291
293
294
295
297
298
298
299
300
302
303
304
304
305
306
307
308
309
310
311
313
313
315
316
316
318
318
320
322
322
323
325
325
326
326
326
328
329
331
332
334
334
334
335
336
リモート・コマンド/分散プログラム呼び出し:
API リストの実行 . . . . . . . . . .
cwbRC_RunCmd . . . . . . . . .
リモート・コマンド/分散プログラム呼び出し:
プログラム API リストへのアクセス . . .
cwbRC_AddParm . . . . . . . . .
cwbRC_CallPgm. . . . . . . . . .
cwbRC_CreatePgm . . . . . . . . .
cwbRC_DeletePgm . . . . . . . . .
cwbRC_GetLibName . . . . . . . .
cwbRC_GetParm. . . . . . . . . .
cwbRC_GetParmCount . . . . . . . .
cwbRC_GetPgmName . . . . . . . .
cwbRC_SetLibName . . . . . . . .
cwbRC_SetParm . . . . . . . . . .
cwbRC_SetPgmName . . . . . . . .
例: リモート・コマンド/分散プログラム呼び
出し API の使用法 . . . . . . . . .
保守容易性 API . . . . . . . . . . .
ヒストリー・ログとトレース・ファイル . .
エラー・ハンドル . . . . . . . . . .
保守容易性 API の一般的な使用法 . . . .
保守容易性 API のリスト: ヒストリー・ログ
への書き込み . . . . . . . . . . .
cwbSV_CreateMessageTextHandle . . . .
cwbSV_DeleteMessageTextHandle . . . .
cwbSV_LogMessageText . . . . . . .
cwbSV_SetMessageClass . . . . . . .
cwbSV_SetMessageComponent . . . . .
cwbSV_SetMessageProduct . . . . . .
保守容易性 API のリスト: トレース・データ
の書き込み . . . . . . . . . . . .
cwbSV_CreateTraceDataHandle . . . . .
cwbSV_DeleteTraceDataHandle . . . . .
cwbSV_LogTraceData . . . . . . . .
cwbSV_SetTraceComponent . . . . . .
cwbSV_SetTraceProduct . . . . . . .
保守容易性 API のリスト: トレース・ポイン
トの書き込み . . . . . . . . . . .
cwbSV_CreateTraceAPIHandle . . . . .
cwbSV_CreateTraceSPIHandle . . . . .
cwbSV_DeleteTraceAPIHandle . . . . .
cwbSV_DeleteTraceSPIHandle . . . . .
cwbSV_LogAPIEntry . . . . . . . .
cwbSV_LogAPIExit. . . . . . . . .
cwbSV_LogSPIEntry . . . . . . . .
cwbSV_LogSPIExit . . . . . . . . .
cwbSV_SetAPIComponent. . . . . . .
cwbSV_SetAPIProduct . . . . . . . .
cwbSV_SetSPIComponent . . . . . . .
cwbSV_SetSPIProduct . . . . . . . .
保守容易性 API のリスト: サービス・ファイ
ルの読み取り . . . . . . . . . . .
cwbSV_ClearServiceFile . . . . . . .
cwbSV_CloseServiceFile . . . . . . .
cwbSV_CreateServiceRecHandle . . . . .
337
337
338
338
340
341
342
343
344
345
346
347
348
349
350
353
353
355
355
355
355
356
357
358
358
359
360
360
361
361
362
363
364
364
365
366
366
367
368
369
370
371
372
372
373
374
374
375
376
cwbSV_DeleteServiceRecHandle . . . . .
cwbSV_GetComponent . . . . . . . .
cwbSV_GetDateStamp . . . . . . . .
cwbSV_GetMaxRecordSize . . . . . .
cwbSV_GetMessageText . . . . . . .
cwbSV_GetProduct . . . . . . . . .
cwbSV_GetRecordCount . . . . . . .
cwbSV_GetServiceFileName . . . . . .
cwbSV_GetServiceType . . . . . . .
cwbSV_GetTimeStamp . . . . . . . .
cwbSV_GetTraceData . . . . . . . .
cwbSV_GetTraceAPIData . . . . . . .
cwbSV_GetTraceAPIID . . . . . . .
cwbSV_GetTraceAPIType . . . . . . .
cwbSV_GetTraceSPIData . . . . . . .
cwbSV_GetTraceSPIID. . . . . . . .
cwbSV_GetTraceSPIType . . . . . . .
cwbSV_OpenServiceFile . . . . . . .
cwbSV_ReadNewestRecord . . . . . .
cwbSV_ReadNextRecord . . . . . . .
cwbSV_ReadOldestRecord. . . . . . .
cwbSV_ReadPrevRecord . . . . . . .
保守容易性 API のリスト: メッセージ・テキ
ストの検索 . . . . . . . . . . . .
cwbSV_CreateErrHandle . . . . . . .
cwbSV_DeleteErrHandle . . . . . . .
cwbSV_GetErrClass. . . . . . . . .
cwbSV_GetErrClassIndexed . . . . . .
cwbSV_GetErrCount . . . . . . . .
cwbSV_GetErrFileName . . . . . . .
cwbSV_GetErrFileNameIndexed . . . . .
cwbSV_GetErrLibName . . . . . . .
cwbSV_GetErrLibNameIndexed . . . . .
cwbSV_GetErrSubstText . . . . . . .
cwbSV_GetErrSubstTextIndexed . . . . .
cwbSV_GetErrText . . . . . . . . .
cwbSV_GetErrTextIndexed . . . . . .
例: 保守容易性 API の使用法 . . . . . .
システム・オブジェクト・アクセス (SOA) API
SOA オブジェクト . . . . . . . . .
システム・オブジェクト・ビュー. . . . .
システム・オブジェクト・アクセス API の一
般的な使用法 . . . . . . . . . . .
システム・オブジェクトのカスタマイズ・
リストの表示 . . . . . . . . . .
システム・オブジェクトのプロパティー・
ビューの表示 . . . . . . . . . .
システム・オブジェクトのデータのアクセ
スと更新 . . . . . . . . . . . .
システム・オブジェクト・アクセスのプログ
ラミングに関する考慮事項 . . . . . . .
システム・オブジェクト・アクセスのエラ
ー . . . . . . . . . . . . . .
システム・オブジェクト・アクセスのアプ
リケーション・プロファイル . . . . .
目次
376
377
378
379
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
393
394
395
396
396
397
397
398
399
400
401
402
403
405
406
408
409
410
411
412
412
413
413
415
418
421
421
421
vii
アプリケーション・プログラムのための
IBM i 通信セッションの管理 . . . . .
システム・オブジェクト・アクセス API のリ
スト . . . . . . . . . . . . . .
CWBSO_CloseList . . . . . . . . .
CWBSO_CopyObjHandle . . . . . . .
CWBSO_CreateErrorHandle . . . . . .
CWBSO_CreateListHandle . . . . . .
CWBSO_CreateListHandleEx . . . . . .
CWBSO_CreateObjHandle. . . . . . .
CWBSO_CreateParmObjHandle . . . . .
CWBSO_DeleteErrorHandle . . . . . .
CWBSO_DeleteListHandle . . . . . .
CWBSO_DeleteObjHandle. . . . . . .
CWBSO_DeleteParmObjHandle . . . . .
CWBSO_DisallowListActions. . . . . .
CWBSO_DisallowListFilter . . . . . .
CWBSO_DisplayErrMsg . . . . . . .
CWBSO_DisplayList . . . . . . . .
CWBSO_DisplayObjAttr . . . . . . .
CWBSO_GetErrMsgText . . . . . . .
CWBSO_GetListSize . . . . . . . .
CWBSO_GetObjAttr . . . . . . . .
CWBSO_GetObjHandle . . . . . . .
CWBSO_OpenList . . . . . . . . .
CWBSO_ReadListProfile . . . . . . .
CWBSO_RefreshObj . . . . . . . .
CWBSO_ResetParmObj . . . . . . .
CWBSO_SetListFilter . . . . . . . .
CWBSO_SetListProfile . . . . . . . .
CWBSO_SetListSortFields. . . . . . .
CWBSO_SetListTitle . . . . . . . .
CWBSO_SetObjAttr . . . . . . . .
CWBSO_SetParameter . . . . . . . .
CWBSO_WaitForObj . . . . . . . .
CWBSO_WriteListProfile . . . . . . .
SOA 属性の特殊値 . . . . . . . .
データベース・プログラミング . . . . . . .
.NET provider . . . . . . . . . . . .
OLE DB Provider . . . . . . . . . . .
IBM i Access ODBC . . . . . . . . . .
IBM i Access ODBC ドライバーに固有の詳
細 . . . . . . . . . . . . . . .
ODBC 3.x API に関する注意事項 . . .
接続ストリング・キーワード . . . . .
バージョンおよびリリースの変更に伴う
ODBC ドライバーの振る舞いの変更 . . .
viii
422
422
423
424
425
426
428
429
430
431
431
432
433
433
434
435
436
437
439
440
441
442
444
445
446
447
448
449
450
451
452
453
454
455
456
471
472
473
473
ODBC API の制約事項およびサポートさ
れない関数 . . . . . . . . . . .
サインオン・ダイアログの振る舞い . . .
ODBC データ・タイプおよびそれらと
DB2 for i データベース・タイプとの対応 .
XML データ・タイプの処理 . . . . .
ラージ・オブジェクト (LOB) の考慮事項
接続とステートメントの属性 . . . . .
接続プール . . . . . . . . . . .
SQLPrepare および SQLNativeSQL エスケ
ープ・シーケンスおよびスカラー関数 . .
分散トランザクションのサポート. . . .
カーソルの動作に関する注意事項. . . .
拡張動的使用不可エラー. . . . . . .
ODBC 64 ビット Windows および Linux
に関する考慮事項 . . . . . . . . .
64 ビット IBM i Access ODBC ドライバ
ーの制約事項 . . . . . . . . . .
SQLTables の説明 . . . . . . . . .
長時間実行照会の処理 . . . . . . .
分離レベルの考慮事項 . . . . . . .
ODBC のパフォーマンス . . . . . . .
ODBC のパフォーマンス調整 . . . . .
一般的なエンド・ユーザー用ツールでのパ
フォーマンスの考慮事項. . . . . . .
SQL パフォーマンス . . . . . . . .
複数行ステートメントに対する ODBC サ
ポート. . . . . . . . . . . . .
カタログ関数 . . . . . . . . . .
出口プログラム. . . . . . . . . .
SQL および外部プロシージャー . . . .
ODBC プログラム例 . . . . . . . . .
例: Visual C++ - プロシージャーの呼び出
しによるデータへのアクセスと戻し . . .
例: Visual Basic - プロシージャーの呼び
出しによるデータへのアクセスと戻し . .
例: ILE RPG - ODBC プロシージャーの
ホスト・コード. . . . . . . . . .
IBM i Access データベースの API . . . . .
ActiveX プログラミング . . . . . . . . . .
503
503
504
506
508
510
516
517
517
518
519
519
522
522
523
523
524
524
528
530
538
539
540
557
566
566
568
570
571
572
特記事項. . . . . . . . . . . . . . 575
475
475
482
プログラミング・インターフェース情報
商標 . . . . . . . . . . . .
使用条件 . . . . . . . . . . .
502
IBM i: Windows アプリケーション・パッケージ: プログラミング
.
.
.
.
.
.
.
.
.
. 577
. 577
. 577
Windows アプリケーション・パッケージ : プログラミング
IBM® i Access Client ソリューション - Windows アプリケーション・パッケージはオプションのパッケ
ージで、IBM i Access Client ソリューションの一部です。これには、現在 IBM i Access for Windows バ
ージョン 7.1 の一部であるミドルウェア、データベース・プロバイダー、およびプログラミング API が含
まれています。
アプリケーション開発者は、このトピックを調べて Windows アプリケーション・パッケージで利用でき
る技術的なプログラミング情報、ツール、および手法を参照し、使用してください。
ここには、IBM i の資源にアクセスするアプリケーションを作成する際に役立つ、プログラミング概念、
機能、例などといった情報が含まれています。このトピックを使用することにより、ユーザーのビジネス・
ニーズに合わせたクライアント/サーバー・アプリケーションの開発や、調整を行います。このサーバーで
提供される豊富な機能に接続し、それらを管理し、利用することができるように、さまざまなプログラミン
グ手法が説明されています。以下の各トピックを選択することにより、それぞれの情報にアクセスすること
ができます。
注: 各フィーチャーを Windows PC から起動するには、「スタート」 > 「すべてのプログラム」 >
「IBM i Access Client ソリューション」と選択し、構成要素を選択してください。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
Windows アプリケーション・パッケージのPDF ファイル: プログラミン
グ
この情報の PDF ファイルを表示または印刷できます。
本書の PDF 版を表示またはダウンロードするには、「 IBM i Access Client ソリューション - Windows
アプリケーション・パッケージ: プログラミング」を選択します。
PDF ファイルの保存
表示用または印刷用の PDF ファイルをワークステーションに保存するには、次のようにします。
1. ご使用のブラウザーで PDF のリンクを右クリックする。
2. PDF をローカルに保存するオプションをクリックする。
3. PDF を保存したいディレクトリーに進む。
4. 「保存」をクリックする。
Adobe Reader のダウンロード
これらの PDF を表示または印刷するには、Adobe Reader がご使用のシステムにインストールされている
必要があります。Adobe Reader は、Adobe の Web サイト (get.adobe.com/reader/)
ロードすることができます。
© Copyright IBM Corp. 2013
から無償でダウン
1
C/C++ API
C/C++ アプリケーション・プログラミング・インターフェース (API) を使用して、IBM i 資源にアクセス
します。
この API は、主として C/C++ プログラマーを対象としたものです。これは、C 形式の API をサポート
するその他の言語からも呼び出されます。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
C/C++ API の概要
C/C++ API の概要情報については、以下のトピックを参照してください。
API グループ、ヘッダー・ファイル、インポート・ライブラリー、および DLL
すべての C/C++ API グループについては、Programmer's Toolkit のインターフェース定義ファイルにア
クセスして、参照してください。
各 C/C++ API グループについて、以下の情報が後出の表に示されています。
v API ドキュメンテーション資料へのリンク
v 必要なインターフェース定義 (ヘッダー) ファイル (該当する場合)
v 関連するインポート・ライブラリー・ファイル (該当する場合)
v 関連するダイナミック・リンク・ライブラリー (DLL) ファイル
ToolKit のヘッダー・ファイルにアクセスする方法
1. プログラム・ディレクトリーで Programmer's Toolkit アイコンを見つけて起動します。 Programmer's
Toolkit がプログラム・ディレクトリーにない場合は、Toolkit をインストールします。
2. 左側のナビゲーション・パネルで、該当する API グループを選択します。
3. 左側のナビゲーション・パネルで、「C/C++ API」サブトピックを選択します。
4. 右側の表示パネルで、ヘッダー・ファイル (.h) を見付けて、それを選択します。
注: Toolkit の API グループ・トピックには、インターフェースの記述および定義に加えて、他の情報源に
対するリンクが含まれています。
インポート・ライブラリーについて
Programmer's Toolkit に同梱されているインポート・ライブラリーは、 Microsoft Visual C++ コンパイラー
を使用して作成されています。そのため、共通オブジェクト・ファイル形式 (COFF) になっています。
Borland の C コンパイラーなど、一部のコンパイラーは COFF をサポートしていません。そのようなコン
パイラーから C/C++ API にアクセスするには、IMPLIB ツールを使用して、オブジェクト・モデル形式
(OMF) のインポート・ライブラリーを作成する必要があります。例えば、以下のとおりです。
implib cwbdq.lib %windir%¥system32¥cwbdq.dll
表 1. C/C++ API グループ、ヘッダー・ファイル、ライブラリー・ファイル、および DLL ファイル
API グループ
ヘッダー・ファイル
インポート・ライブ
ラリー
DLL
管理
cwbad.h
cwbapi.lib
2
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbad.dll
表 1. C/C++ API グループ、ヘッダー・ファイル、ライブラリー・ファイル、および DLL ファイル (続き)
API グループ
ヘッダー・ファイル
インポート・ライブ
ラリー
DLL
通信およびセキュリティー cwbcosys.h
cwbco.h
cwb.h
cwbapi.lib
cwbco.dll
データ待ち行列
cwbdq.h
cwbapi.lib
cwbdq.dll
データ形式変更
cwbdt.h
cwbapi.lib
cwbdt.dll
各国語サポート
cwbnl.h
cwbapi.lib
cwbnl.dll
cwbnlcnv.h
cwbapi.lib
cwbcore.dll
cwbnldlg.h
cwbapi.lib
cwbnldlg.dll
IBM i オブジェクト
cwbobj.h
cwbapi.lib
cwbobj.dll
ODBC
sql.h
sqlext.h
sqltypes.h
sqlucode.h
odbc32.lib
odbc32.dll
cwbapi.lib
cwbdb.dll
(汎用 NLS)
各国語サポート
(変換 NLS)
各国語サポート
(ダイアログ・ボックス
NLS)
データベース API (最適化 cwbdb.h
SQL)
注: これらの API は、現
在では拡張は行われていま
せん。
OLE DB Provider
ad400.h
da400.h
cwbzzodb.dll
詳しくは、Microsoft Web サイトの『OLE
DB』セクション (英語)
ください。
リモート・コマンド / 分
散プログラム呼び出し
cwbrc.h
cwbapi.lib
cwbrc.dll
保守容易性
cwbsv.h
cwbapi.lib
cwbsv.dll
cwbapi.lib
cwbsoapi.dll
システム・オブジェクト・ cwbsoapi.h
アクセス
を参照して
関連資料:
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
7 ページの『単一の API タイプの使用』
特定のタイプの API のみをアプリケーションで使用するように制限するには、単一のプリプロセッサー定
義のみを定義する必要があります。
プログラミング
3
Programmer's Toolkit
アプリケーションを開発するための、ヘッダー・ファイルおよびあらゆる情報を検索します。
Programmer's Toolkit は、Windows アプリケーション・パッケージ製品のインストール可能な構成要素で
あり、アプリケーションの開発に不可欠な、主要な情報ソースとなります。 ActiveX オートメーション・
オブジェクト、ADO/OLE DB、.NET、および Java™ によるプログラミングが含まれています。
Programmer's Toolkit には、ヘッダー・ファイル、サンプル・プログラム、およびすべてのドキュメンテー
ション資料へのリンクが含まれています。
注:
v Toolkit や Windows アプリケーション・パッケージ製品のいずれの部分も、作成したアプリケーション
と一緒に再配布することはできません。
v コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』
の条件に同意します。
Programmer's Toolkit は、次の 2 つの部分から構成されています。
v Programmer's Toolkit の構成要素には、以下のものが含まれます。
– Toolkit のオンライン・ヘルプ情報、および、製品のその他のオンライン・ヘルプ
– C/C++ ヘッダー・ファイル
– C インポート・ライブラリー
– ActiveX オートメーション・タイプ・ライブラリー
v Programmer's Toolkit の Web サイト。アプリケーションの開発に役立つ、サンプル・アプリケーション
やツールを入手できます。このサイトは定期的に更新されます。定期的に新しい情報を確認してくださ
い。
Programmer's Toolkit のインストール:
Programmer's Toolkit は、Windows アプリケーション・パッケージのフィーチャーの 1 つとしてインスト
ールされます。
本製品の Programmer's Toolkit およびその他のフィーチャーを追加または除去するには、ご使用の PC の
コントロール・パネルにある「プログラムの追加と削除」を使用します。
1. 「スタート」 > 「コントロールパネル」 > 「プログラムの追加と削除」 > 「IBM i Access Client
ソリューション」 > 「変更」の順に選択します。
2. 画面の指示に従って、「変更」ボタンを選択します。
3. フィーチャー名 (Programmer's Toolkit) をクリックし、次の中から該当するものを選択します。
v このフィーチャーをローカルのハード・ディスクにインストールします。(This feature will be
installed on local hard drive.)(フィーチャーを単一でインストールする場合)
v このフィーチャーとすべてのサブフィーチャーをローカルのハード・ディスクにインストールしま
す。(This feature, and all subfeatures, will be installed on local hard drive.)(フィーチャ
ーを複数インストールする場合)
v このフィーチャーを使用しません。(This feature will not be available.)(フィーチャーを除去す
る場合)
4. 「インストール」をクリックしてインストール済みのフィーチャーを変更し、インストール・ウィザー
ドが完了するまで作業を続行します。
関連資料:
4
IBM i: Windows アプリケーション・パッケージ: プログラミング
572 ページの『ActiveX プログラミング』
ActiveX オートメーションは、Microsoftによって定義されたプログラミング・テクノロジーであり、IBM i
Access Client ソリューション製品でサポートされています。
Programmer's Toolkit の立ち上げ:
Programmer's Toolkit は、IBM i Access Client ソリューション製品のフィーチャーの 1 つとして立ち上げ
られます。
1. ご使用のパーソナル・コンピューターに、Programmer's Toolkit フィーチャーをインストールします。
2. 「スタート」 > 「プログラム」 > 「IBM i Access Client ソリューション」 > 「Programmer's
Toolkit」の順に選択します。
注: パーソナル・コンピューターに Programmer's Toolkit がインストールされると、Toolkit のアイコン
が表示されます。
関連資料:
572 ページの『ActiveX プログラミング』
ActiveX オートメーションは、Microsoftによって定義されたプログラミング・テクノロジーであり、IBM i
Access Client ソリューション製品でサポートされています。
接続 API 用の IBM i 名の形式
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
有効な形式は次のとおりです。
v TCP/IP ネットワーク名 (system.network.com)
v ネットワーク ID なしのシステム名 (SYSTEM)
v IP アドレス (1.2.3.4)
関連資料:
27 ページの『管理 API』
これらの API には、PC にインストールされているコードに関する情報にアクセスするための機能が備わ
っています。
38 ページの『通信およびセキュリティー API』
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
122 ページの『IBM i データ待ち行列 API』
製品のデータ待ち行列アプリケーション・プログラミング・インターフェース (API) を使用すると、IBM i
のデータ待ち行列に簡単にアクセスできます。データ待ち行列を使用することによって、通信 API を使う
必要のないクライアント/サーバー・アプリケーションを作成することができるようになります。
169 ページの『データ形式変更 API』
製品のデータ形式変換アプリケーション・プログラミング・インターフェース (API) を使用すると、クラ
イアント/サーバー・アプリケーションで IBM i 数値データの形式変更 (システム形式と PC 形式との相互
変更) を行えるようになります。 IBM i 数値データの送受信をシステムとの間で行う場合に、形式変更が
必要になることがあります。データ形式変更 API は、数多くの数値形式の変換をサポートします。
188 ページの『各国語サポート (NLS) API』
各国語サポート API によって、各国の言語バージョンに関連した製品の設定値の取得および保存 (照会お
よび変更) を、アプリケーションで行えるようになります。
プログラミング
5
219 ページの『システム・オブジェクト API』
システム・オブジェクトのアプリケーション・プログラミング・インターフェース (API) を使用して、シ
ステム上にある印刷関連のオブジェクトを処理できます。これらの API は、IBM i スプール・ファイル、
書き出しプログラム・ジョブ、出力待ち行列、プリンターなどを使った作業を可能にします。
331 ページの『リモート・コマンド/分散プログラム呼び出し API』
PC アプリケーション・プログラマーは、リモート・コマンド/分散プログラム呼び出し API を使用するこ
とで、IBM i の機能にアクセスできます。ユーザー・プログラムとシステム・コマンドを、エミュレーシ
ョン・セッションなしに呼び出します。コマンドとプログラムは単一の IBM i プログラムによって扱われ
るため、コマンドとプログラムの両方に対して、1 つのシステム・ジョブのみが開始されます。
411 ページの『システム・オブジェクト・アクセス (SOA) API』
システム・オブジェクト・アクセスを使用することで、グラフィカル・ユーザー・インターフェースを介し
て、システム・オブジェクトの表示および操作を行うことができます。
OEM、ANSI、およびユニコードの考慮事項
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
C/C++ API の汎用版は、デフォルトの OEM 版と同じ形式を取ります。この情報では、それぞれの関数ご
とに 1 つの名前のみが示されていますが、異なる 3 つのシステム・エントリー・ポイントがあります。例
えば、以下のとおりです。
cwbNL_GetLang();
compiles to:
cwbNL_GetLang();
//CWB_OEM or undefined
or:
cwbNL_GetLangA();
//CWB_ANSI defined
or:
cwbNL_GetLangW();
//CWB_UNICODE defined
表 2. API タイプ、名前の形式、およびプリプロセッサー定義
API タイプ
API 名の形式 (使用されている場合)
プリプロセッサー定義
OEM
cwbXX_xxx
なし (明示的に、CWB_OEM を指定
可能)
ANSI
cwbXX_xxxA
CWB_ANSI
ユニコード
cwbXX_xxxW
CWB_UNICODE
注:
v データ転送 API (cwbDT_xxx) は、「A」および「W」のサフィックスの規則には従いません。 API の
汎用バージョンは「String」を関数名の一部として使用しています。 ANSI/OEM バージョンは「ASCII」
を関数名の一部として使用しています。ユニコード・バージョンは「Wide」を関数名の一部として使用
しています。数値ストリングを取り扱う cwbDT_xxx API の OEM および ANSI 文字セットの間に違い
はありません。したがって、関連する API の ANSI および OEM バージョンはいずれも同じです。例
えば、以下のとおりです。
cwbDT_HexToString();
compiles to:
6
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbDT_HexToASCII();
//CWB_UNICODE not defined
or:
cwbDT_HexToWide();
//CWB_UNICODE defined
詳細については、データ形式変更ヘッダー・ファイル cwbdt.h の関連リンクを選択して、参照してくだ
さい。
v ストリングを渡すためのバッファーと長さ (例えば、cwbCO_GetUserIDExW) を持つユニコード API の
場合、その長さはバイト数として扱われます。文字数としては扱われません。
関連資料:
27 ページの『管理 API』
これらの API には、PC にインストールされているコードに関する情報にアクセスするための機能が備わ
っています。
38 ページの『通信およびセキュリティー API』
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
122 ページの『IBM i データ待ち行列 API』
製品のデータ待ち行列アプリケーション・プログラミング・インターフェース (API) を使用すると、IBM i
のデータ待ち行列に簡単にアクセスできます。データ待ち行列を使用することによって、通信 API を使う
必要のないクライアント/サーバー・アプリケーションを作成することができるようになります。
169 ページの『データ形式変更 API』
製品のデータ形式変換アプリケーション・プログラミング・インターフェース (API) を使用すると、クラ
イアント/サーバー・アプリケーションで IBM i 数値データの形式変更 (システム形式と PC 形式との相互
変更) を行えるようになります。 IBM i 数値データの送受信をシステムとの間で行う場合に、形式変更が
必要になることがあります。データ形式変更 API は、数多くの数値形式の変換をサポートします。
188 ページの『各国語サポート (NLS) API』
各国語サポート API によって、各国の言語バージョンに関連した製品の設定値の取得および保存 (照会お
よび変更) を、アプリケーションで行えるようになります。
219 ページの『システム・オブジェクト API』
システム・オブジェクトのアプリケーション・プログラミング・インターフェース (API) を使用して、シ
ステム上にある印刷関連のオブジェクトを処理できます。これらの API は、IBM i スプール・ファイル、
書き出しプログラム・ジョブ、出力待ち行列、プリンターなどを使った作業を可能にします。
331 ページの『リモート・コマンド/分散プログラム呼び出し API』
PC アプリケーション・プログラマーは、リモート・コマンド/分散プログラム呼び出し API を使用するこ
とで、IBM i の機能にアクセスできます。ユーザー・プログラムとシステム・コマンドを、エミュレーシ
ョン・セッションなしに呼び出します。コマンドとプログラムは単一の IBM i プログラムによって扱われ
るため、コマンドとプログラムの両方に対して、1 つのシステム・ジョブのみが開始されます。
2 ページの『API グループ、ヘッダー・ファイル、インポート・ライブラリー、および DLL』
すべての C/C++ API グループについては、Programmer's Toolkit のインターフェース定義ファイルにア
クセスして、参照してください。
単一の API タイプの使用:
特定のタイプの API のみをアプリケーションで使用するように制限するには、単一のプリプロセッサー定
義のみを定義する必要があります。
プリプロセッサー定義には以下のものがあります。
プログラミング
7
v CWB_OEM_ONLY
v CWB_ANSI_ONLY
v CWB_UNICODE_ONLY
例えば、純粋な ANSI アプリケーションを作成する場合は、CWB_ANSI_ONLY および CWB_ANSI の両
方を指定します。プリプロセッサー定義および API 名の詳細については、個々の Programmer's Toolkit の
ヘッダー・ファイルを参照してください。詳しくは、『API グループ、ヘッダー・ファイル、インポー
ト・ライブラリー、および DLL』のトピック集の関連リンク (以下参照) を参照してください。
関連資料:
2 ページの『API グループ、ヘッダー・ファイル、インポート・ライブラリー、および DLL』
すべての C/C++ API グループについては、Programmer's Toolkit のインターフェース定義ファイルにア
クセスして、参照してください。
API タイプの混合使用:
API 名を明示的に使用することによって、ANSI、OEM、およびユニコードの API を混合して使用するこ
とができます。
例えば、CWB_ANSI プリプロセッサー定義を指定することによって、ANSI アプリケーションを作成する
ことができます。この場合にも、接尾部「W」を使用することで、ユニコード・バージョンの API を呼び
出すことが可能です。
汎用 Windows アプリケーション・パッケージアプリケーションの作成:
Windows アプリケーション・パッケージ汎用アプリケーションでは、同じソース・コードを
OEM、ANSI、およびユニコード用にコンパイルすることができるため、移植性が大幅に向上します。
汎用アプリケーションを作成するには、異なるプリプロセッサー定義を指定し、 API の汎用版 (サフィッ
クス「A」または「W」がないもの) を使用します。汎用アプリケーションを作成する場合のガイドライン
の要約を以下に示します。
v ストリングの操作用に通常の <string.h> を組み込む代わりに、 <TCHAR.H> を組み込みます。
v 文字およびストリングに汎用データ・タイプを使用します。ソース・コードで、'char' の代わりに
'TCHAR' を使用します。
v リテラル文字およびストリング用に _TEXT マクロを使用します。例えば、TCHAR A[]=_TEXT("A
Generic String") とします。
v 汎用ストリング処理関数を使用します。例えば、_tcscpy の代わりに strcpy を使用します。
v 'sizeof' 演算子を使用する場合は特に注意してください。ユニコード文字が常に 2 バイトを占有すること
を忘れないでください。汎用 TCHAR 配列 A の文字数を決定する場合、単純な sizeof(A) の代わり
に、 sizeof(A)/sizeof(TCHAR) を使用してください。
v コンパイルには、適切なプリプロセッサー定義を使用してください。ユニコード用のソースを Visual
C++ でコンパイルする場合は、プリプロセッサー定義 UNICODE および _UNICODE を使用してください。
MAK ファイルに _UNICODE を定義する代わりに、ソース・コードの先頭で、次のように定義することも
できます。
#ifdef UNICODE
#define _UNICODE
#endif
これらのガイドラインの詳細については、以下の資料を参照してください。
8
IBM i: Windows アプリケーション・パッケージ: プログラミング
1. Richter, J. Advanced Windows: The Developer's Guide to the Win32 API for Windows NT 3.5 and
Windows 95, Microsoft Press, Redmond, WA, 1995.
2. Kano, Nadine Developing International Software for Windows 95 and Windows NT: a handbook for
software design, Microsoft Press, Redmond, WA, 1995.
3. Microsoft サポートの知識ベースの記事 (関連リンクを参照。)
4. MSDN ライブラリー (関連リンクを参照。)
関連情報:
Microsoft サポート
MSDN ライブラリー
戻りコードおよびエラー・メッセージ
C/C++ アプリケーション・プログラミング・インターフェース (API) では、多くの関数で整数の戻りコー
ドの戻りがサポートされています。戻りコードは、関数がどのように完了したのかを示しています。
IBM i のエラー・メッセージ
メッセージの一部は、システムにも記録されます。これらのメッセージは、PWS または IWS で始まりま
す。特定の PWSxxxx または IWSxxxx メッセージを表示させるには、該当するコマンドを、コマンド行プ
ロンプトで入力します (xxxx はメッセージ番号)。
DSPMSGD RANGE(IWSxxxx) MSGF(QIWS/QIWSMSG)
DSPMSGD RANGE(PWSxxxx) MSGF(QIWS/QIWSMSG)
オペレーティング・システム・エラーに対応する戻りコード:
戻りコードとシステム・エラー・メッセージとの関係を示します。
0
1
2
3
4
5
6
8
15
18
21
31
32
33
38
CWB_OK
正常終了。
CWB_INVALID_FUNCTION
サポートされない関数。
CWB_FILE_NOT_FOUND
ファイルが見付からない。
CWB_PATH_NOT_FOUND
パスが見付からない。
CWB_TOO_MANY_OPEN_FILES
システムはファイルをオープンできない。
CWB_ACCESS_DENIED
アクセスが拒否された。
CWB_INVALID_HANDLE
リスト・ハンドルが無効。
CWB_NOT_ENOUGH_MEMORY
メモリーが不足、一時バッファーの割り振りが失敗した可能性がある。
CWB_INVALID_DRIVE
システムは指定のドライブを見付けることができない。
CWB_NO_MORE_FILES
これ以上ファイルは見付からない。
CWB_DRIVE_NOT_READY
装置が作動可能でない。
CWB_GENERAL_FAILURE
一般エラー発生。
CWB_SHARING_VIOLATION
他のプロセスが使用しているためこのプロセスはファイルにアクセスできない。
CWB_LOCK_VIOLATION
他のプロセスがファイルの一部をロックしたためこのプロセスはファイルにアクセスできない。
CWB_END_OF_FILE
ファイルの終わりに達しました。
プログラミング
9
50
53
54
55
59
65
80
85
87
88
110
111
112
115
124
142
252
253
CWB_NOT_SUPPORTED
ネットワーク要求はサポートされない。
CWB_BAD_NETWORK_PATH
ネットワーク・パスが見付からない。
CWB_NETWORK_BUSY
ネットワークが使用中。
CWB_DEVICE_NOT_EXIST
指定のネットワーク資源または装置がもう使用可能でない。
CWB_UNEXPECTED_NETWORK_ERROR
予期しないネットワーク・エラーが発生。
CWB_NETWORK_ACCESS_DENIED
ネットワーク・アクセスが拒否された。
CWB_FILE_EXISTS
ファイルが存在する。
CWB_ALREADY_ASSIGNED
そのローカル装置名は既に使用されている。
CWB_INVALID_PARAMETER
パラメーターが無効。
CWB_NETWORK_WRITE_FAULT
書き込み障害がネットワークで発生。
CWB_OPEN_FAILED
システムは指定の装置またはファイルをオープンできない。
CWB_BUFFER_OVERFLOW
出力バッファーのスペースが不足。*bufferSize を使用して適正なサイズを決める必要がある。
CWB_DISK_FULL
ディスクに十分なスペースがない。
CWB_PROTECTION_VIOLATION
アクセスが拒否された。
CWB_INVALID_LEVEL
システム呼び出しのレベルが正しくない。
CWB_BUSY_DRIVE
この時点では、システムは JOIN または SUBST を実行できない。
CWB_INVALID_FSD_NAME
装置名が誤り。
CWB_INVALID_PATH
指定のネットワーク・パスが正しいものではない。
戻りコード:
IBM i Access には、グローバルおよび固有の戻りコードがあります。
グローバル戻りコード:
以下のグローバル戻りコードがあります。
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
10
CWB_USER_CANCELLED_COMMAND
ユーザーがコマンドを取り消した。
CWB_CONFIG_ERROR
構成エラーが発生。
CWB_LICENSE_ERROR
ライセンス・エラーが発生。
CWB_PROD_OR_COMP_NOT_SET
プロダクトまたは構成要素の登録と使用に関する障害による内部エラー。
CWB_SECURITY_ERROR
セキュリティー・エラー発生。
CWB_GLOBAL_CFG_FAILED
グローバル構成を試みたが失敗した。
CWB_PROD_RETRIEVE_FAILED
プロダクトの検索が失敗した。
CWB_COMP_RETRIEVE_FAILED
コンピューターの検索が失敗した。
CWB_COMP_CFG_FAILED
コンピューターの構成が失敗した。
CWB_COMP_FIX_LEVEL_UPDATE_FAILED
コンピューターの修正レベル更新が失敗した。
CWB_INVALID_API_HANDLE
IBM i: Windows アプリケーション・パッケージ: プログラミング
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
8998
8999
要求ハンドルが無効。
CWB_INVALID_API_PARAMETER
指定のパラメーターが無効。
CWB_HOST_NOT_FOUND
サーバーが非活動中であるかまたは存在しない。
CWB_NOT_COMPATIBLE
IBM i Access のプログラムまたは関数が正しいレベルでない。
CWB_INVALID_POINTER
ポインターが NULL。
CWB_SERVER_PROGRAM_NOT_FOUND
サーバー・アプリケーションが見付からない。
CWB_API_ERROR
一般 API 障害。
CWB_CA_NOT_STARTED
IBM i Access プログラムが開始していない。
CWB_FILE_IO_ERROR
レコードが読み取れない。
CWB_COMMUNICATIONS_ERROR
通信エラー発生。
CWB_RUNTIME_CONSTRUCTOR_FAILED
C ランタイム・コンストラクターが失敗した。
CWB_DIAGNOSTIC
予期しないエラー。メッセージ番号とメッセージ中のデータを記録して IBM サポートに
連絡してください。
CWB_COMM_VERSION_ERROR
データ待ち行列は、このバージョンの通信では稼働しない。
CWB_NO_VIEWER
IBM i Access 関数のビューアー・サポートがインストールされていない。
CWB_MODULE_NOT_LOADABLE
フィルター DLL がロードできない。
CWB_ALREADY_SETUP
オブジェクトが既にセットアップされている。
CWB_CANNOT_START_PROCESS
プロセスの開始が失敗。他のエラー・コードも参照。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
1 つ以上の入力 UNICODE 文字が、使用中のコード・ページにない。
CWB_UNSUPPORTED_FUNCTION
サポートされない機能。
CWB_INTERNAL_ERROR
内部エラーが発生しました。
関連資料:
38 ページの『通信およびセキュリティー API』
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
固有の戻りコード:
固有の戻りコードがあります。
セキュリティーの戻りコード:
以下のセキュリティーの戻りコードがあります。
8001
8002
8003
8004
8006
8007
8011
8013
8014
8015
8016
CWB_UNKNOWN_USERID
CWB_WRONG_PASSWORD
CWB_PASSWORD_EXPIRED
CWB_INVALID_PASSWORD
CWB_INCORRECT_DATA_FORMAT
CWB_GENERAL_SECURITY_ERROR
CWB_USER_PROFILE_DISABLED
CWB_USER_CANCELLED
CWB_INVALID_SYSNAME
CWB_INVALID_USERID
CWB_LIMITED_CAPABILITIES_USERID
プログラミング
11
8019
8022
8026
8027
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8070
8071
8072
8257
8258
8259
8260
8261
8262
8263
8264
8266
8267
8268
8270
8271
8272
CWB_INVALID_TP_ON_HOST
CWB_NOT_LOGGED_ON
CWB_EXIT_PGM_ERROR
CWB_EXIT_PGM_DENIED_REQUEST
CWB_TIMESTAMPS_NOT_SET
CWB_KERB_CLIENT_CREDENTIALS_NOT_FOUND
CWB_KERB_SERVICE_TICKET_NOT_FOUND
CWB_KERB_SERVER_CANNOT_BE_CONTACTED
CWB_KERB_UNSUPPORTED_BY_HOST
CWB_KERB_NOT_AVAILABLE
CWB_KERB_SERVER_NOT_CONFIGURED
CWB_KERB_CREDENTIALS_NOT_VALID
CWB_KERB_MAPPED_USERID_FAILURE
CWB_KERB_MAPPED_USERID_SUCCESS
CWB_PROFILE_TOKEN_INVALID
CWB_PROFILE_TOKEN_MAXIMUM
CWB_PROFILE_TOKEN_NOT_REGENERABLE
CWB_PW_TOO_LONG
CWB_PW_TOO_SHORT
CWB_PW_REPEAT_CHARACTER
CWB_PW_ADJACENT_DIGITS
CWB_PW_CONSECUTIVE_CHARS
CWB_PW_PREVIOUSLY_USED
CWB_PW_DISALLOWED_CHAR
CWB_PW_NEED_NUMERIC
CWB_PW_MATCHES_OLD
CWB_PW_NOT_ALLOWED
CWB_PW_CONTAINS_USERID
CWB_PW_LAST_INVALID_PWD
CWB_PW_STAR_NONE
CWB_PW_QPWDVLDPGM
通信の戻りコード:
以下の通信の戻りコードがあります。
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
CWB_INV_AFTER_SIGNON
CWB_INV_WHEN_CONNECTED
CWB_INV_BEFORE_VALIDATE
CWB_SECURE_SOCKETS_NOTAVAIL
CWB_RESERVED1
CWB_RECEIVE_ERROR
CWB_SERVICE_NAME_ERROR
CWB_GETPORT_ERROR
CWB_SUCCESS_WARNING
CWB_NOT_CONNECTED
CWB_DEFAULT_HOST_CCSID_USED
CWB_USER_TIMEOUT
CWB_SSL_JAVA_ERROR
CWB_USER_TIMEOUT_SENDRCV
CWB_FIPS_UNAVAILABLE
構成の戻りコード:
以下の構成の戻りコードがあります。
8500
8501
8502
8503
8504
8505
8506
8507
8508
8580
8599
12
CWB_RESTRICTED_BY_POLICY
CWB_POLICY_MODIFY_MANDATED_ENV
CWB_POLICY_MODIFY_CURRENT_ENV
CWB_POLICY_MODIFY_ENV_LIST
CWB_SYSTEM_NOT_FOUND
CWB_ENVIRONMENT_NOT_FOUND
CWB_ENVIRONMENT_EXISTS
CWB_SYSTEM_EXISTS
CWB_NO_SYSTEMS_CONFIGURED
CWB_CONFIGERR_RESERVED_START
CWB_CONFIGERR_RESERVED_END
IBM i: Windows アプリケーション・パッケージ: プログラミング
オートメーション・オブジェクトの戻りコード:
以下のオートメーション・オブジェクトの戻りコードがあります。
8600
8601
8602
8603
8604
8605
8606
8607
8608
8609
8610
8611
CWB_INVALID_METHOD_PARM
CWB_INVALID_PROPERTY_PARM
CWB_INVALID_PROPERTY_VALUE
CWB_OBJECT_NOT_INITIALIZED
CWB_OBJECT_ALREADY_INITIALIZED
CWB_INVALID_DQ_ORDER
CWB_DATA_TRANSFER_REQUIRED
CWB_UNSUPPORTED_XFER_REQUEST
CWB_ASYNC_REQUEST_ACTIVE
CWB_REQUEST_TIMED_OUT
CWB_CANNOT_SET_PROP_NOW
CWB_OBJ_STATE_NO_LONGER_VALID
WINSOCK 戻りコード:
以下の WINSOCK 戻りコードがあります。
10024
10035
10038
10047
10050
10051
10052
10053
10054
10055
10057
10058
10060
10061
10064
10065
10091
10092
11001
CWB_TOO_MANY_OPEN_SOCKETS
CWB_RESOURCE_TEMPORARILY_UNAVAILABLE
CWB_SOCKET_OPERATION_ON_NON_SOCKET
CWB_PROTOCOL_NOT_INSTALLED
CWB_NETWORK_IS_DOWN
CWB_NETWORK_IS_UNREACHABLE
CWB_NETWORK_DROPPED_CONNECTION_ON_RESET
CWB_SOFTWARE_CAUSED_CONNECTION_ABORT
CWB_CONNECTION_RESET_BY_PEER
CWB_NO_BUFFER_SPACE_AVAILABLE
CWB_SOCKET_IS_NOT_CONNECTED
CWB_CANNOT_SEND_AFTER_SOCKET_SHUTDOWN
CWB_CONNECTION_TIMED_OUT
CWB_CONNECTION_REFUSED
CWB_HOST_IS_DOWN
CWB_NO_ROUTE_TO_HOST
CWB_NETWORK_SUBSYSTEM_IS_UNAVAILABLE
CWB_WINSOCK_VERSION_NOT_SUPPORTED
CWB_HOST_DEFINITELY_NOT_FOUND
TCP/IP アドレスのルックアップでシステム名が見付からない。
CWB_HOST_NOT_FOUND_BUT_WE_ARE_NOT_SURE
TCP/IP アドレスのルックアップでシステム名が見付からない。
CWB_VALID_NAME_BUT_NO_DATA_RECORD
ローカルの SERVICES ファイルでサービス名が見付からない。
11002
11004
SSL 戻りコード:
以下の SSL 戻りコードがあります。
キー・データベースのエラー・コード
20001
20002
20003
20004
-
20005
20006
20007
20008
20009
20010
20011
20012
20013
-
不明エラーが発生。
asn.1 エンコード/デコード・エラーが発生。
asn.1 エンコーダー/デコーダーの初期化時にエラーが発生。
索引が範囲外であるかオプション・フィールドが存在しないために
asn.1 エンコード/デコード・エラーが発生。
データベース・エラーが発生。
データベース・ファイルのオープン時にエラーが発生。
データベース・ファイルの再オープン時にエラーが発生。
データベースの作成に失敗。
データベースが既に存在する。
データベース・ファイルの削除時にエラーが発生。
データベースがオープンされていない。
データベース・ファイルの読み取り時にエラーが発生。
データベース・ファイルへのデータの書き込み時にエラーが発生。
プログラミング
13
20014
20015
20016
20017
20018
20019
20020
20021
20022
20023
20024
20025
20026
20027
20028
20029
20030
20031
20032
20033
20034
20035
20036
20037
20038
20039
20040
20041
20042
20043
20044
20045
20046
20047
20048
20049
20050
20051
20052
20053
20054
20055
20056
20057
20058
20059
20060
20061
20062
20063
20064
20065
20066
20067
20068
20069
20070
20071
20072
20073
20074
20075
20076
20077
20078
20079
20080
14
-
データベース妥当性検査エラーが発生。
無効なデータベース・バージョンを検出。
無効なデータベース・パスワードを検出。
無効なデータベース・ファイル・タイプを検出。
データベースが破壊された。
無効なパスワードを検出、またはデータベースが無効である。
データベース・キー項目整合性エラーが発生。
データベースに重複するキーが既にある。
データベースに重複するキーが既にある (レコード ID)。
データベースに重複するキーが既にある (ラベル)。
データベースに重複するキーが既にある (署名)。
データベースに重複するキーが既にある (未署名の証明書)。
データベースに重複するキーが既にある (発行者およびシリアル番号)。
データベースに重複するキーが既にある (サブジェクト公開鍵情報)。
データベースに重複するキーが既にある (未署名の CRL)。
ラベルがデータベースで使用されている。
パスワード暗号化エラーが発生。
LDAP 関連エラーが発生。
暗号エラーが発生。
暗号機能エラーが発生。
無効な暗号アルゴリズムを検出。
データの署名時にエラーが発生。
データの検査時にエラーが発生。
データのダイジェストの計算時にエラーが発生。
無効な暗号パラメーターを検出。
サポートされない暗号アルゴリズムを検出。
指定された入力サイズがサポートされている係数サイズより大きい。
サポートされない係数サイズを検出。
データベース妥当性検査エラーが発生。
キー項目妥当性検査に失敗。
重複する拡張フィールドが存在する。
キーのバージョンが間違っている。
必須の拡張フィールドが存在しない。
有効期間に本日の日付が含まれていない、または有効期間がその発行者の有効期間に含まれていない。
有効期間に本日の日付が含まれていない、または有効期間がその発行者の有効期間に含まれていない。
秘密鍵使用拡張の有効期間の妥当性検査時にエラーが発生。
キーの発行者が見つからない。
必須の証明書拡張がない。
キー署名の妥当性検査が失敗した。
キー署名の妥当性検査が失敗した。
キーのルート・キーが信頼されない。
キーが失効している。
権限キー ID 拡張の妥当性検査時にエラーが発生。
秘密鍵使用拡張の妥当性検査時にエラーが発生。
サブジェクト代替名拡張の妥当性検査時にエラーが発生。
発行者代替名拡張の妥当性検査時にエラーが発生。
キー使用拡張の妥当性検査時にエラーが発生。
不明な重大拡張を検出。
鍵ペア項目の妥当性検査時にエラーが発生。
CRL の妥当性検査時にエラーが発生。
mutex エラーが発生。
無効なパラメーターを検出。
ヌルのパラメーターまたはメモリー割り振りエラーを検出。
サイズが大きすぎる、または小さすぎる。
古いパスワードは無効。
新しいパスワードは無効。
パスワードが期限切れである。
スレッド関連のエラーが発生。
スレッドの作成時にエラーが発生。
スレッドが終了を待機している間にエラーが発生。
入出力エラーが発生。
CMS のロード時にエラーが発生。
暗号化ハードウェア関連のエラーが発生。
ライブラリー初期化ルーチンが正しく呼び出されなかった。
内部データベース・ハンドル・テーブルが破壊された。
メモリー割り振りエラーが発生。
認識されないオプションを検出。
IBM i: Windows アプリケーション・パッケージ: プログラミング
20081
20082
20083
20084
20085
20086
20087
20088
20089
20090
20091
20092
20093
20094
20095
20096
20097
20098
20099
20100
20101
20102
20103
20104
20105
20106
20107
20108
20109
20110
20111
20112
20113
20114
20115
20116
20117
20118
20119
20120
-
20121
20122
20123
20124
20125
20126
20127
20128
20129
20130
20131
20132
20133
20134
20135
20136
20137
20138
20139
20140
20141
20142
-
時間情報の取得時にエラーが発生。
mutex 作成エラーが発生。
メッセージ・カタログのオープン時にエラーが発生。
エラー・メッセージ・カタログのオープン時にエラーが発生。
ヌルのファイル名を検出。
ファイルのオープン時にエラーが発生したので、ファイルの存在と許可をチェックする。
読み取るファイルのオープン時にエラーが発生。
書き込むファイルのオープン時にエラーが発生。
このようなファイルはない。
許可設定が原因でファイルをオープンできない。
ファイルへのデータの書き込み時にエラーが発生。
ファイルの削除時にエラーが発生。
無効な Base64 エンコード・データを検出。
無効な Base64 メッセージ・タイプを検出。
Base64 エンコード規則でデータをエンコードしているときにエラーが発生。
Base64 エンコード・データのデコード時にエラーが発生。
識別名タグの取得時にエラーが発生。
必須の共通名フィールドが空。
必須の国名フィールドが空。
無効なデータベース・ハンドルを検出。
キー・データベースが存在しない。
要求鍵ペア・データベースが存在しない。
パスワード・ファイルが存在しない。
新規パスワードが古いパスワードと等しい。
キー・データベース内にキーが見つからない。
要求キーが見つからない。
トラステッド CA が見つからない。
証明書に対する要求キーが見つからない。
キー・データベース内に秘密鍵がない。
キー・データベース内にデフォルト・キーがない。
キー・レコードに秘密鍵がない。
キー・レコードに証明書がない。
CRL 項目がない。
無効なキー・データベース・ファイル名を検出。
認識されない秘密鍵タイプを検出。
無効な識別名入力を検出。
指定されたキー・ラベルを持つキー項目が見つからない。
キー・ラベル・リストが破壊された。
入力データが有効な PKCS12 データではない。
パスワードが無効である、または PKCS12 データが破壊されたか PKCS12 の
後続のバージョンで作成されている。
認識されないキー・エクスポート・タイプを検出。
サポートされないパスワード・ベースの暗号化アルゴリズムを検出。
鍵リング・ファイルから CMS キー・データベースへの変換時にエラーが発生。
CMS キー・データベースから鍵リング・ファイルへの変換時にエラーが発生。
証明書要求に対して証明書を作成しているときにエラーが発生。
完全な発行者チェーンを作成できない。
無効な WEBDB データを検出。
鍵リング・ファイルに書き込むデータがない。
入力した日数が許容されている有効期間を超えている。
パスワードが短すぎる。最低文字数に満たない。
パスワードには少なくとも数字が 1 つ含まれていなければならない。
パスワード内の文字がすべて英字または数字のいずれかである。
認識されないまたはサポートされない署名アルゴリズムが指定された。
無効なキー・データベース・タイプが指定された。
現在、2 次キー・データベースは別の基本キー・データベースに対する 2 次キー・データベースである。
キー・データベースに、関連付けられた 2 次キー・データベースがない。
ラベルを持つ暗号トークンが見つからない。
暗号トークン・パスワードが指定されていないが、これは必須である。
暗号トークン・パスワードが指定されたが、これは必須ではない。
暗号モジュールをロードできない。暗号トークンのサポートを受けられない。
暗号トークンの機能がサポートされていない。
暗号トークン機能が失敗した。
SSL エラー・コード
プログラミング
15
25001
25002
25003
25004
25005
25006
25007
25008
25009
25010
25011
25012
25101
25102
25103
25104
25105
25106
-
25107 25108
25109
25201
25202
-
25203
25204
25205
25206
25301
25401
25402
25403
25404
25405
25406
25407
25408
-
25409
25410
25411
25412
25413
25414
-
25415
25416
25417
25418
25419
25420
-
25421
25422
25425
25426
25427
25428
25429
25430
25431
25432
25433
-
16
ハンドルが無効。
ダイナミック・リンク・ライブラリーが使用できない。
内部エラーが発生。
メイン・メモリーに操作を実行するだけのスペースがない。
ハンドルが操作に対して有効な状態ではない。
キー・ラベルが見つからない。
証明書が使用できない。
証明書妥当性検査エラー。
暗号化処理エラー。
証明書内の ASN フィールドの妥当性検査エラー。
LDAP サーバー接続エラー。
不明な内部エラー。問題をサービスに報告する。
暗号の処理でエラーが発生。
キー・ファイルの読み取りで入出力エラーが発生。
キー・ファイルの内部形式が無効。キー・ファイルを再作成する。
キー・ファイルに同じキーを持つ項目が 2 つある。iKeyman を使用して重複するキーを除去する。
キー・ファイルに同じラベルを持つ項目が 2 つある。iKeyman を使用して重複するラベルを除去する。
キー・ファイルのパスワードが整合性チェックとして使用されている。
キー・ファイルが破壊されているか、パスワード ID が誤っている。
キー・ファイル内のデフォルト・キーに対する証明書の有効期限が切れている。
iKeyman を使用して有効期限切れの証明書を除去する。
ダイナミック・リンク・ライブラリーの 1 つをロードしているときにエラーが発生。
環境がクローズした後で接続を確立しようとしている。
キー・ファイルを初期化できなかった。
キー・ファイルを開くことができない。パスの指定が誤っているか、
ファイル権限でファイルを開くことが許可されていなかった。
一時的な鍵ペアを生成できない。
ユーザー名オブジェクトが指定されたが、見つからない。
LDAP 照会に使用するパスワードが正しくない。
LDAP サーバーのフェイルオーバー・リストに対する索引が正しくない。
クローズ時にエラーが発生。
システム日付が無効な値に設定された。
SSLV2 も SSLV3 も使用可能ではない。
必要な証明書をパートナーから受け取らなかった。
受け取った証明書の形式が正しくない。
受け取った証明書のタイプはサポートされていない。
データの読み取りまたは書き込み時に入出力エラーが発生。
キー・ファイルで指定されたラベルが見つからない。
指定されたキー・ファイルのパスワードが誤っている。キー・ファイルを使用できなかった。
キー・ファイルが壊れている可能性もある。
制限された暗号化環境で、キー・サイズが長すぎてサポートされない。
誤った形式の SSL メッセージをパートナーから受け取った。
メッセージ確認コード (MAC) が正常に検査されなかった。
この操作はサポートされない。
受け取った証明書に誤った署名が入っていた。
サーバー証明書が信頼されない。通常、これは、サーバー証明書の認証局をダウンロードしなかった場合に
発生する。デジタル証明書マネージャーを使用して認証局を取得し、PC の IBM 鍵管理ユーティリティーを
使用してローカル・キー・データベースにその認証局を置く。詳細については、CWBCO1050 を参照。
リモート・システム情報が無効。
アクセスが拒否された。
自己署名証明書が無効。
読み取りが失敗した。
書き込みが失敗した。
プロトコルが完了する前にパートナーがソケットを閉じた。つまり、パートナーは
SSL クライアント認証用に構成されているのに、クライアント証明書がパートナーに
送信されなかった可能性がある。
指定された V2 暗号が無効。
指定された V3 暗号が無効。
ハンドルを作成できない。
初期化に失敗した。
証明書を妥当性検査しているときに、指定された LDAP ディレクトリーにアクセスできない。
指定されたキーに秘密鍵が入っていなかった。
指定された PKCS11 共用ライブラリーをロードする試みが失敗した。
PKCS #11 ドライバーが、呼び出し元で指定されたトークンを見つけられなかった。
PKCS #11 トークンがスロット内にない。
PKCS #11 トークンにアクセスするパスワード/ピンが無効。
受け取った SSL ヘッダーが正しい SSLV2 形式のヘッダーではなかった。
IBM i: Windows アプリケーション・パッケージ: プログラミング
25434
25435
25436
25437
25438
25501
25502
25601
25602
25701
25702
25703
25704
25705
25706
25707
25708
-
ハードウェア・ベースの暗号サービス・プロバイダー (CSP) にアクセスできない。
属性の設定が矛盾する。
アプリケーションが実行されているプラットフォームで要求された機能がサポートされていない。
IPv6 接続を検出。
リセット・セッション・タイプのコールバック機能から誤った値が戻された。
バッファー・サイズが負または 0 である。
非ブロッキング I/O で使用した。
reset_cipher では SSLV3 を必要とし、接続は SSLV2 を使用する。
関数呼び出しで無効な ID が指定された。
関数呼び出しの ID が無効。
属性が負の長さで、無効。
指定された列挙タイプに対し列挙値が無効。
SID キャッシュ・ルーチンを置き換えるためのパラメーター・リストが無効。
数値属性を設定するときに、指定された値が設定対象の具体的な属性に対して無効である。
追加の証明書妥当性検査で矛盾するパラメーターが設定された。
暗号仕様に、実行のシステムでサポートされていない AES 暗号仕様が含まれていた。
ピア ID の長さが誤っている。16 バイト以下でなければならない。
構成要素固有の戻りコード:
API タイプの戻りコードを示します。
管理 API の戻りコード:
以下の、管理の戻りコードがあります。
6001
CWBAD_INVALID_COMPONENT_ID
構成要素 ID が無効。
関連資料:
27 ページの『管理 API』
これらの API には、PC にインストールされているコードに関する情報にアクセスするための機能が備わ
っています。
通信 API の戻りコード:
以下の通信の API 戻りコードがあります。
6001
6002
6003
6004
6005
6007
6008
CWBCO_END_OF_LIST
システム・リストの終わりに達した。システム名が、戻されませんでした。
CWBCO_DEFAULT_SYSTEM_NOT_DEFINED
デフォルト・システムの設定が未定義。
CWBCO_DEFAULT_SYSTEM_NOT_CONFIGURED
デフォルト・システムは定義されているが、接続が構成されていない。
CWBCO_SYSTEM_NOT_CONNECTED
現行プロセスでは、指定のシステムは現在接続されていない。
CWBCO_SYSTEM_NOT_CONFIGURED
指定のシステムは、現在構成されていない。
CWBCO_INTERNAL_ERROR
内部エラー
CWBCO_NO_SUCH_ENVIRONMENT
指定の環境は存在しません。
関連資料:
38 ページの『通信およびセキュリティー API』
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
データベース API の戻りコード:
以下のデータベース API の戻りコードがあります。
プログラミング
17
注: データベース API に関する重要な情報については、データベース API に関するトピックを参照して
ください。
6001
CWBDB_CANNOT_CONTACT_SERVER
データ・アクセス・サーバーの開始を阻むエラーが発生。
6002
CWBDB_ATTRIBUTES_FAILURE
データ・アクセス・サーバーの属性設定中にエラー発生。
6003
CWBDB_SERVER_ALREADY_STARTED
有効なサーバーの稼働中にデータ・アクセス・サーバーを開始しようとした。
再始動の前にそれを停止してください。
6004
CWBDB_INVALID_DRDA_PKG_SIZE
サブミットされた DRDA 圧縮サイズが無効。
6005
CWBDB_REQUEST_MEMORY_ALLOCATION_FAILURE
要求ハンドルによるメモリー割り振りが失敗。
6006
CWBDB_REQUEST_INVALID_CONVERSION
要求ハンドルがデータ変換に失敗。
6007
CWBDB_SERVER_NOT_ACTIVE
データ・アクセス・サーバーが開始していない。
サーバーを開始してから、継続してください。
6008
CWBDB_PARAMETER_ERROR
パラメーター設定が失敗。再度試してみてください。エラーが直らないようであれば、
使用可能メモリーが不足している可能性があります。
6009
CWBDB_CLONE_CREATION_ERROR
複製要求を作成できない。
6010
CWBDB_INVALID_DATA_FORMAT_FOR_CONNECTION
この接続に対するデータ形式オブジェクトが無効。
6011
CWBDB_DATA_FORMAT_IN_USE
データ形式オブジェクトが既に別の要求により使用中。
6012
CWBDB_INVALID_DATA_FORMAT_FOR_DATA
データ形式オブジェクトがデータの形式に一致しない。
6013
CWBDB_STRING_ARG_TOO_LONG
与えられたストリングは、パラメーターとして長すぎる。
6014
CWBDB_INVALID_INTERNAL_ARG
(ユーザーが与えたものでない) 内部的に生成された引数が無効。
6015
CWBDB_INVALID_NUMERIC_ARG
数値引数の値が無効。
6016
CWBDB_INVALID_ARG
引数の値が無効。
6017
CWBDB_STMT_NOT_SELECT
与えられたステートメントが SELECT ステートメントでない。
この呼び出しでは、SELECT ステートメントが必要。
6018
CWBDB_STREAM_FETCH_NOT_COMPLETE
この接続は、ストリーム・フェッチ方式。ストリーム・フェッチが終わるまで
要求の操作はできない。
6019
CWBDB_STREAM_FETCH_NOT_ACTIVE
この接続は、ストリーム・フェッチ方式でない。要求の
操作のためには、ストリーム・フェッチ方式でなければならない。
6020
CWBDB_MISSING_DATA_PROCESSOR
要求オブジェクト中のデータ処理装置を指すポインターが NULL。
6021
CWBDB_ILLEGAL_CLONE_REQUEST_TYPE
属性要求の複製を作成できない。
6022
CWBDB_UNSOLICITED_DATA
サーバーからデータを受け取ったが、要求したものでない。
6023
CWBDB_MISSING_DATA
サーバーにデータを要求したが、一部未受領。
6024
CWBDB_PARM_INVALID_BITSTREAM
パラメーター中のビット・ストリームが無効。
6025
CWBDB_CONSISTENCY_TOKEN_ERROR
システムからのデータの解釈に使用したデータ形式が、戻されたデータと一致しない。
6026
CWBDB_INVALID_FUNCTION
このタイプの要求ではこの関数は無効。
6027
CWBDB_FORMAT_INVALID_ARG
API に渡されたパラメーター値が無効。
6028
CWBDB_INVALID_COLUMN_POSITION
API に渡された列位置が無効。
6029
CWBDB_INVALID_COLUMN_TYPE
API に渡された列タイプが無効。
18
IBM i: Windows アプリケーション・パッケージ: プログラミング
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
CWBDB_ROW_VECTOR_NOT_EMPTY
使用した形式が無効または間違っている。
CWBDB_ROW_VECTOR_EMPTY
使用した形式が無効または間違っている。
CWBDB_MEMORY_ALLOCATION_FAILURE
メモリー割り振り中にエラー発生。
CWBDB_INVALID_CONVERSION
無効なタイプ変換を試みた。
CWBDB_DATASTREAM_TOO_SHORT
ホストから受け取ったデータ・ストリームが短すぎる。
CWBDB_SQL_WARNING
データベース・サーバーが SQL 操作から警告を受け取った。
CWBDB_SQL_ERROR
データベース・サーバーが SQL 操作からエラーを受け取った。
CWBDB_SQL_PARAMETER_WARNING
データベース・サーバーが SQL 操作に使用されているパラメーターに関する
警告を受け取った。
CWBDB_SQL_PARAMETER_ERROR
データベース・サーバーが SQL 操作に使用されているパラメーターに関する
警告を受け取った。
CWBDB_LIST_SERVER_WARNING
データベース・サーバーがカタログ操作から警告を戻した。
CWBDB_LIST_SERVER_ERROR
データベース・サーバーがカタログ操作からエラーを戻した。
CWBDB_LIST_PARAMETER_WARNING
データベース・サーバーがカタログ操作に使用したパラメーター
に関する警告を戻した。
CWBDB_LIST_PARAMETER_ERROR
データベース・サーバーがカタログ操作に使用したパラメーター
に関するエラーを戻した。
CWBDB_NDB_FILE_SERVER_WARNING
データベース・サーバーがファイル処理操作から
警告を戻した。
CWBDB_NDB_FILE_SERVER_ERROR
データベース・サーバーがファイル処理操作からエラーを戻した。
CWBDB_FILE_PARAMETER_WARNING
データベース・サーバーがファイル処理操作に使用したパラメーター
に関する警告を戻した。
CWBDB_FILE_PARAMETER_ERROR
データベース・サーバーがファイル処理操作に使用したパラメーター
に関するエラーを戻した。
CWBDB_GENERAL_SERVER_WARNING
データベース・サーバーが一般警告を戻した。
CWBDB_GENERAL_SERVER_ERROR
データベース・サーバーが一般エラーを戻した。
CWBDB_EXIT_PROGRAM_WARNING
データベース・サーバーが出口プログラムから警告を戻した。
CWBDB_EXIT_PROGRAM_ERROR
データベース・サーバーが出口プログラムからエラーを戻した。
CWBDB_DATA_BUFFER_TOO_SMALL
ターゲットのデータ・バッファーが移動元のバッファーよりも小さい。
CWBDB_NL_CONVERSION_ERROR
PiNlConverter からエラーを受け取った。
CWBDB_COMMUNICATIONS_ERROR
処理中に通信エラーを受け取った。
CWBDB_INVALID_ARG_API
引数の値が無効 - API レベル。
CWBDB_MISSING_DATA_HANDLER
データ・ハンドラーがデータ・ハンドラー・リストにない。
CWBDB_REQUEST_DATASTREAM_NOT_VALID
カタログ要求中に無効なデータ・ストリームがある。
CWBDB_SERVER_UNABLE
サーバーは要求の関数を実行できない。
以下の戻りコードは、cwbDB_StartServerDetailed API によって戻されます。
6058
CWBDB_WORK_QUEUE_START_ERROR
プログラミング
19
クライアント作業待ち行列の問題のため、サーバーを開始できない。
CWBDB_WORK_QUEUE_CREATE_ERROR
クライアント作業待ち行列の問題のため、サーバーを開始できない。
6060
CWBDB_INITIALIZATION_ERROR
クライアント初期設定の問題のため、サーバーを開始できない。
6061
CWBDB_SERVER_ATTRIBS_ERROR
サーバー属性の問題のため、サーバーを開始できない。
6062
CWBDB_CLIENT_LEVEL_ERROR
クライアント・レベル設定の問題のため、サーバーを開始できない。
6063
CWBDB_CLIENT_LFC_ERROR
クライアント言語機能コード設定の問題のため、サーバーを開始できない。
6064
CWBDB_CLIENT_CCSID_ERROR
クライアント CCSID の問題のため、サーバーを開始できない。
6065
CWBDB_TRANSLATION_INDICATOR_ERROR
変換標識設定エラーのため、サーバーを開始できない。
6066
CWBDB_RETURN_SERVER_ATTRIBS_ERROR
サーバー属性の戻しの問題のため、サーバーを開始できない。
6067
CWBDB_SERVER_ATTRIBS_REQUEST
サーバー属性要求オブジェクトの欠落のため、
サーバーを開始できない。
6068
CWBDB_RETURN_ATTRIBS_ERROR
属性の戻り値の問題のため、サーバーを開始できない。
6069
CWBDB_SERVER_ATTRIBS_MISSING
戻されたサーバーの属性不足で、サーバーを開始できない。
(データの欠落)
6070
CWBDB_SERVER_LFC_CONVERSION_ERROR
サーバー属性のサーバー言語フィーチャー・コード・フィールドの
データ変換エラーのため、サーバーを開始できない。
6071
CWBDB_SERVER_LEVEL_CONVERSION_ERROR
サーバー属性のサーバー機能レベル・フィールドの
データ変換エラーのため、サーバーを開始できない。
6072
CWBDB_SERVER_LANGUAGE_TABLE_ERROR
サーバー属性のサーバー言語テーブル ID フィールドの
データ変換エラーのため、サーバーを開始できない。
6073
CWBDB_SERVER_LANGUAGE_LIBRARY_ERROR
サーバー属性のサーバー言語ライブラリー ID フィールドの
データ変換エラーのため、サーバーを開始できない。
6074
CWBDB_SERVER_LANGUAGE_ID_ERROR
サーバー属性のサーバー言語 ID フィールドの
データ変換エラーのため、サーバーを開始できない。
6075
CWBDB_COMM_DEQUEUE_ERROR
通信エラーのためサーバーを開始できない。
6076
CWBDB_COMM_ENQUEUE_ERROR
通信エラーのためサーバーを開始できない。
6077
CWBDB_UNSUPPORTED_COLUMN_TYPE
データにサポートされない列タイプが見付かった。
6078
CWBDB_SERVER_IN_USE
所定の接続ハンドルでのデータベース・サーバーへの接続が、
同じシステム・オブジェクト・ハンドルで作成された別の
接続ハンドルで既に使用されている。
6079
CWBDB_SERVER_REL_DB_CONVERSION_ERROR
サーバー属性のサーバー言語 ID フィールドの
データ変換エラーのため、サーバーを開始できない。
この戻りコードには、メッセージやヘルプ・テキストはありません。
6080
CWBDB_SERVER_FUNCTION_NOT_AVAILABLE
この機能はこのバージョンのホスト・サーバーでは利用できない。
6081
CWBDB_FUNCTION_NOT_VALID_AFTER_CONNECT
ホスト・サーバーへの接続後、この機能は無効。
6082
CWBDB_INVALID_INITIAL_REL_DB_NAME
初期リレーショナル DB 名 (IASP) が無効。
6099
CWBDB_LAST_STREAM_CHUNK
ストリーム・フェッチが完了。
注: 通知メッセージであり、エラーではありません。この戻りコードには、メッセージや
ヘルプ・テキストはありません。
6059
関連資料:
20
IBM i: Windows アプリケーション・パッケージ: プログラミング
571 ページの『IBM i Access データベースの API』
IBM i Access の専有 C/C++ データベース API で提供されていた機能のうち、現在は拡張が行われていな
い機能には、他のテクノロジーを使用します。
データ待ち行列 API の戻りコード:
データ待ち行列 API の戻りコードを示します。
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_INVALID_READ_HANDLE
データ待ち行列読み取りハンドルが無効。
CWBDQ_INVALID_QUEUE_LENGTH
データ待ち行列の最大レコード長が無効。
CWBDQ_INVALID_KEY_LENGTH
キーの長さが無効。
CWBDQ_INVALID_ORDER
待ち行列の順序が無効。
CWBDQ_INVALID_AUTHORITY
待ち行列の権限が無効。
CWBDQ_INVALID_QUEUE_TITLE
待ち行列の表題 (記述) が長すぎるか変換できない。
CWBDQ_BAD_QUEUE_NAME
待ち行列名が長すぎるか変換できない。
CWBDQ_BAD_LIBRARY_NAME
ライブラリー名が長すぎるか変換できない。
CWBDQ_BAD_SYSTEM_NAME
システム名が長すぎるか変換できない。
CWBDQ_BAD_KEY_LENGTH
このデータ待ち行列のキーの長さが正しくないか、キーの長さが
LIFO または FIFO データ待ち行列に対して 0 よりも大きい。
CWBDQ_BAD_DATA_LENGTH
このデータ待ち行列のデータの長さが適切でない。データの長さが、ゼロか許容最大値よりも大きい。
CWBDQ_INVALID_TIME
待ち時間が正しくない。
CWBDQ_INVALID_SEARCH
サーチ順序が正しくない。
CWBDQ_DATA_TRUNCATED
戻りデータが切り捨てられた。
CWBDQ_TIMED_OUT
待ち時間が満了したがデータが戻されなかった。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_USER_EXIT_ERROR
出口プログラムのエラーまたは出口プログラムの数が無効。
CWBDQ_LIBRARY_NOT_FOUND
システムにライブラリーがない。
CWBDQ_QUEUE_NOT_FOUND
システムに待ち行列がない。
CWBDQ_NO_AUTHORITY
ライブラリーかデータ待ち行列に対して権限がない。
CWBDQ_DAMAGED_QUEUE
データ待ち行列が使用不可状態。
CWBDQ_QUEUE_EXISTS
データ待ち行列が既に存在する。
CWBDQ_INVALID_MESSAGE_LENGTH
メッセージ長が無効 - 待ち行列の最大レコード長よりも大きい。
CWBDQ_QUEUE_DESTROYED
レコード読み取りのため待機中または読み取り中に待ち行列が壊された。
CWBDQ_NO_DATA
データを 1 つも受け取らなかった。
CWBDQ_CANNOT_CONVERT
プログラミング
21
このデータ待ち行列のデータが変換できない。このデータ待ち行列は
使用できるが、ASCII と EBCDIC との間でデータを変換できない。
このデータ・オブジェクトの変換フラグは無視される。
6029
CWBDQ_QUEUE_SYNTAX
データ待ち行列名の構文が正しくない。待ち行列名は、
システム・オブジェクト構文の後に続く。最初の文字は英字で、
後に続く文字は英数字でなければなりません。
6030
CWBDQ_LIBRARY_SYNTAX
ライブラリー名の構文が正しくない。ライブラリー名は、
システム・オブジェクト構文の後に続く。最初の文字は英字で、
後に続く文字は英数字でなければなりません。
6031
CWBDQ_ADDRESS_NOT_SET
アドレスが設定されていない。データ・オブジェクトが cwbDQ_SetDataAddr()
で設定されていないので、アドレスが検索できない。cwbDQ_GetData()
を使用し、cwbDQ_GetDataAddr() は使用しない。
6032
CWBDQ_HOST_ERROR
戻りコードが定義されていないホスト・エラーが発生。
メッセージ・テキストについてはエラー・ハンドルを参照。
6033
CWBDQ_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
6099
CWBDQ_UNEXPECTED_ERROR
予期しないエラー。
関連資料:
122 ページの『IBM i データ待ち行列 API』
製品のデータ待ち行列アプリケーション・プログラミング・インターフェース (API) を使用すると、IBM i
のデータ待ち行列に簡単にアクセスできます。データ待ち行列を使用することによって、通信 API を使う
必要のないクライアント/サーバー・アプリケーションを作成することができるようになります。
各国語サポート API の戻りコード:
以下の NLS API の戻りコードがあります。
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
CWBNL_ERR_CNV_UNSUPPORTED
あるコード・ページから別のコード・ページへの文字データの変換が試みられたが、
この変換はサポートされていない。
CWBNL_ERR_CNV_TBL_INVALID
変換テーブルの形式が認知されないものである。
CWBNL_ERR_CNV_TBL_MISSING
変換テーブルを使用しようとしたが、テーブルが見付からない。
CWBNL_ERR_CNV_ERR_GET
サーバーからコード・ページ変換テーブル検索中にエラーが発生。
CWBNL_ERR_CNV_ERR_COMM
サーバーからコード・ページ変換テーブル検索中に通信エラーが発生。
CWBNL_ERR_CNV_ERR_SERVER
サーバーからコード・ページ変換テーブル検索中サーバー・エラーが発生。
CWBNL_ERR_CNV_ERR_STATUS
文字データをあるコード・ページから別のコード・ページに変換中、
変換不可能な文字が見付かった。
CWBNL_ERROR_CONVERSION_INCOMPLETE_MULTIBYTE_INPUT_CHARACTER
文字データを変換中に不完全なマルチバイト文字が見付かった。
CWBNL_ERR_CNV_INVALID_SISO_STATUS
SISO パラメーターが正しくない。
CWBNL_ERR_CNV_INVALID_PAD_LENGTH
埋め込み長さパラメーターが正しくない。
以下の戻りコードは、言語 API 用です。
6201
6202
6203
22
CWBNL_ERR_STR_TBL_INVALID
メッセージ・ファイルの形式が認知されない。破壊されている。
CWBNL_ERR_STR_TBL_MISSING
メッセージ・ファイルが見付からない。
CWBNL_ERR_STR_NOT_FOUND
IBM i: Windows アプリケーション・パッケージ: プログラミング
6204
6205
6206
メッセージ・ファイルにメッセージがない。
CWBNL_ERR_NLV_NO_CONFIG
言語構成がない。
CWBNL_ERR_NLV_NO_SUBDIR
言語サブディレクトリーがない。
CWBNL_DEFAULT_HOST_CCSID_USED
デフォルトのサーバー CCSID (500) を使用。
以下の戻りコードは、ロケール API 用です。
6301
6302
6303
6304
CWBNL_ERR_LOC_TBL_INVALID
CWBNL_ERR_LOC_TBL_MISSING
CWBNL_ERR_LOC_NO_CONFIG
CWBNL_ERR_LOC_NO_LOCPATH
システム・オブジェクト API の戻りコード:
システム・オブジェクト API の戻りコードを示します。
6000
6001
6002
6003
6004
6005
6006
6007
6007
6008
6008
6009
6010
6011
6012
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
オブジェクト・タイプが正しくない。
CWBOBJ_RC_INVALID_KEY
キーが正しくない。
CWBOBJ_RC_INVALID_INDEX
リストへの索引が正しくない。
CWBOBJ_RC_LIST_OPEN
リストは既にオープンされている。
CWBOBJ_RC_LIST_NOT_OPEN
リストがオープンされていない。
CWBOBJ_RC_SEEKOUTOFRANGE
シークのオフセットが範囲外。
CWBOBJ_RC_SPLFNOTOPEN
スプール・ファイルがオープンされていない。
CWBOBJ_RC_RSCNOTOPEN
資源がオープンされていない。
CWBOBJ_RC_SPLFENDOFFILE
ファイルの終わりに達した。
CWBOBJ_RC_ENDOFFILE
ファイルの終わりに達した。
CWBOBJ_RC_SPLFNOMESSAGE
スプール・ファイルがメッセージを待っていない。
CWBOBJ_RC_KEY_NOT_FOUND
パラメーター・リストに指定のキーがない。
CWBOBJ_RC_NO_EXIT_PGM
出口プログラムが登録されていない。
CWBOBJ_RC_NOHOSTSUPPORT
ホストは、関数をサポートしない。
関連資料:
219 ページの『システム・オブジェクト API』
システム・オブジェクトのアプリケーション・プログラミング・インターフェース (API) を使用して、シ
ステム上にある印刷関連のオブジェクトを処理できます。これらの API は、IBM i スプール・ファイル、
書き出しプログラム・ジョブ、出力待ち行列、プリンターなどを使った作業を可能にします。
リモート・コマンド/分散プログラム呼び出し API 戻りコード:
リモート・コマンド/分散プログラム呼び出し API の戻りコードを示します。
6000
6001
6002
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_SYSTEM_NAME
プログラミング
23
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6099
システム名が長すぎるか変換できない。
CWBRC_COMMAND_STRING
コマンド・ストリングが長すぎるか、変換できない。
CWBRC_PROGRAM_NAME
プログラム名が長すぎるか、変換できない。
CWBRC_LIBRARY_NAME
ライブラリー名が長すぎるか変換できない。
CWBRC_INVALID_TYPE
指定のパラメーター・タイプが無効。
CWBRC_INVALID_PARM_LENGTH
パラメーターの長さが無効。
CWBRC_INVALID_PARM
指定のパラメーターが無効。
CWBRC_TOO_MANY_PARMS
プログラムに追加しようとしたパラメーターが多すぎる。
CWBRC_INDEX_RANGE_ERROR
索引がこのプログラムの範囲外。
CWBRC_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBRC_USER_EXIT_ERROR
ユーザー出口プログラムのエラー。
CWBRC_COMMAND_FAILED
コマンドは失敗しました。
CWBRC_PROGRAM_NOT_FOUND
プログラムが見付からないかアクセスできない。
CWBRC_PROGRAM_ERROR
プログラム呼び出し時に、エラーが発生。
CWBRC_COMMAND_TOO_LONG
コマンド・ストリングが長すぎます。
CWBRC_UNEXPECTED_ERROR
予期しないエラー。
関連資料:
331 ページの『リモート・コマンド/分散プログラム呼び出し API』
PC アプリケーション・プログラマーは、リモート・コマンド/分散プログラム呼び出し API を使用するこ
とで、IBM i の機能にアクセスできます。ユーザー・プログラムとシステム・コマンドを、エミュレーシ
ョン・セッションなしに呼び出します。コマンドとプログラムは単一の IBM i プログラムによって扱われ
るため、コマンドとプログラムの両方に対して、1 つのシステム・ジョブのみが開始されます。
セキュリティー API の戻りコード:
以下のセキュリティーの API 戻りコードがあります。
6000
6002
6003
6004
6007
6009
6011
6013
6015
6016
24
CWBSY_UNKNOWN_USERID
ユーザー ID が存在しない。
CWBSY_WRONG_PASSWORD
指定のユーザー ID のパスワードが正しくない。
CWBSY_PASSWORD_EXPIRED
パスワードの有効期限切れ。
CWBSY_INVALID_PASSWORD
パスワードの中の 1 つまたは複数の文字が無効であるか、パスワードが長すぎる。
CWBSY_GENERAL_SECURITY_ERROR
一般セキュリティー・エラーが起こりました。ユーザー・プロファイルにパスワードがないか、
パスワード検証プログラムがパスワードにエラーを検出しました。
CWBSY_INVALID_PROFILE
サーバーのユーザー・プロファイルが無効。
CWBSY_USER_PROFILE_DISABLED
IBM i ユーザー・プロファイル (ユーザー ID) が
使用不可に設定されている。
CWBSY_USER_CANCELLED
ユーザーがユーザー ID / パスワードのプロンプトを取り消した。
CWBSY_INVALID_USERID
ユーザー ID 中の 1 つまたは複数の文字が無効であるか、
ユーザー ID が長すぎる。
CWBSY_UNKNOWN_SYSTEM
IBM i: Windows アプリケーション・パッケージ: プログラミング
指定のシステムが不明。
CWBSY_TP_NOT_VALID
PC が IBM i セキュリティー・サーバーを検証できなかった。
システム上の IBM 提供のセキュリティー・サーバー・プログラムの
改ざんの可能性がある。
6022
CWBSY_NOT_LOGGED_ON
現在、指定のシステムにログオンしているユーザーはない。
6025
CWBSY_SYSTEM_NOT_CONFIGURED
セキュリティー・オブジェクトに指定のシステムは構成されていない。
6026
CWBSY_NOT_VERIFIED
オブジェクトに定義されているユーザー ID とパスワードは、まだ検証されていない。
cwbSY_VerifyUserIDPwd API を使用して検証しなければならない。
6255
CWBSY_INTERNAL_ERROR
内部エラー。IBM サービスに連絡してください。
6019
以下の戻りコードは、パスワード変更 API 用です。
6257
6258
6259
6260
6261
6262
6263
6264
6266
6267
6268
6269
6270
CWBSY_PWD_TOO_LONG
新規パスワードの文字数が多すぎる。最大許容文字数は、
iSeries システム値 QPWDMAXLEN で定義されている。
CWBSY_PWD_TOO_SHORT
新規パスワードの文字数が少なすぎる。最小許容文字数は、
iSeries システム値 QPWDMINLEN で定義されている。
QPWDMINLEN.
CWBSY_PWD_REPEAT_CHARACTER
新規パスワードに 2 回以上使用されている文字がある。iSeries の構成
(システム値 QPWDLMTREP) は、パスワードに文字の繰り返し使用を
許可しない。
CWBSY_PWD_ADJACENT_DIGITS
新規パスワードに 2 つの隣り合わせの数字がある。iSeries の構成
(システム値 QPWDLMTAJC) は、パスワードに隣り合わせの数字の使用を
許可しない。
CWBSY_PWD_CONSECUTIVE_CHARS
新規パスワードに連続して繰り返し使われている文字がある。iSeries の構成
(システム値 QPWDLMTREP) は、パスワードに文字の連続繰り返し使用を
許可しない。
CWBSY_PWD_PREVIOUSLY_USED
新規パスワードは、以前に使われたパスワードと同じ。iSeries の構成
(システム値 QPWDRQDDIF) は、以前に使われたすべてのパスワードと
異なるものを要求する。
CWBSY_PWD_DISALLOWED_CHAR
新規パスワードにシステムで使用禁止の文字が使用されている。IBM i の構成
(システム値 QPWDLMTCHR) は、新規パスワード内で使用される文字に制限を
設けています。
CWBSY_PWD_NEED_NUMERIC
新規パスワードは、数字を含まなければならない。iSeries 構成 (システム値
QPWDRQDDGT) は、新規パスワードに 1 つまたは複数の数字を含むことを必要
としている。
CWBSY_PWD_MATCHES_OLD
新規パスワードは旧パスワードと 1 つまたは複数の文字で一致する。
AS/400 構成 (システム値 QPWDPOSDIF) では、前のパスワードと
同じ位置に同じ文字を使用できない。
CWBSY_PWD_NOT_ALLOWED
パスワードが拒否された。
CWBSY_PWD_MATCHES_USERID
パスワードがユーザー ID と同じ。
CWBSY_PWD_PRE_V3
旧パスワードは、異なる暗号化技法を使用した V3 以前のシステムで作られている。
AS/400 で、手動でパスワードを作り直す必要がある。
CWBSY_LAST_INVALID_PASSWORD
次の無効入力は、ユーザー・プロファイルを使用禁止にする。
関連資料:
38 ページの『通信およびセキュリティー API』
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
プログラミング
25
保守容易性 API の戻りコード:
以下の保守容易性 API の戻りコードがあります。
6000
6001
6002
6003
6004
6005
6006
CWBSV_INVALID_FILE_TYPE
渡されたファイル・タイプが使用できない。
CWBSV_INVALID_RECORD_TYPE
渡されたレコード・タイプが使用できない。
CWBSV_INVALID_EVENT_TYPE
使用できないイベント・タイプが見付かった。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルに関連するエラー・メッセージがない。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていない。
CWBSV_INVALID_MSG_CLASS
使用できないメッセージ・クラスが渡された。
CWBSV_LOG_NOT_STARTED
要求されたログを開始できない。
関連資料:
353 ページの『保守容易性 API』
保守容易性アプリケーション・プログラミング・インターフェース (API) を使用すると、プログラム内の
メッセージおよびイベントを保守ファイルに記録することができます。
システム・オブジェクト・アクセス API 戻りコード:
以下の SOA API 戻りコードがあります。
0
18
CWBSO_NO_ERROR
エラーはなし。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがない。
CWBSO_BAD_LISTTYPE
リストのタイプに指定した値が無効。
CWBSO_BAD_HANDLE
指定したハンドルが無効。
CWBSO_BAD_LIST_HANDLE
指定したリスト・ハンドルが無効。
CWBSO_BAD_OBJ_HANDLE
指定したオブジェクト・ハンドルが無効。
CWBSO_BAD_PARMOBJ_HANDLE
指定したパラメーター・オブジェクト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定したエラー・ハンドルが無効。
CWBSO_BAD_LIST_POSITION
リストに指定した位置は存在しない。
CWBSO_BAD_ACTION_ID
指定されたアクション ID がこのリストのタイプに対して無効。
CWBSO_NOT_ALLOWED_NOW
要求のアクションはこの時点で許可されない。
CWBSO_BAD_INCLUDE_ID
指定のフィルター ID はこのリストに対して無効。
CWBSO_DISP_MSG_FAILED
メッセージの表示の要求が失敗。
CWBSO_GET_MSG_FAILED
エラー・メッセージのテキストを検索できなかった。
CWBSO_BAD_SORT_ID
指定のソート ID がこのリストのタイプに対して無効。
CWBSO_INTERNAL_ERROR
内部処理エラーが発生。
CWBSO_NO_ERROR_MESSAGE
指定のエラー・ハンドルにエラー・メッセージがない。
CWBSO_BAD_ATTRIBUTE_ID
26
IBM i: Windows アプリケーション・パッケージ: プログラミング
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
19
20
21
22
23
24
25
26
27
28
29
属性キーがこのオブジェクトに対して無効。
CWBSO_BAD_TITLE
指定の表題が無効。
CWBSO_BAD_FILTER_VALUE
指定したフィルター値が無効。
CWBSO_BAD_PROFILE_NAME
指定したプロファイル名が無効。
CWBSO_DISPLAY_FAILED
ウィンドウが作成できない。
CWBSO_SORT_NOT_ALLOWED
このリストのタイプに対するソートは許可されていない。
CWBSO_CANNOT_CHANGE_ATTR
属性は現時点では変更できない。
CWBSO_CANNOT_READ_PROFILE
指定のプロファイル・ファイルから読み取りができない。
CWBSO_CANNOT_WRITE_PROFILE
指定のプロファイル・ファイルに書き込みができない。
CWBSO_BAD_SYSTEM_NAME
指定されたシステム名が有効なシステム名ではない。
CWBSO_SYSTEM_NAME_DEFAULTED
リストの "CWBSO_CreateListHandle" 呼び出しでシステム名が指定されなかった。
CWBSO_BAD_FILTER_ID
指定のフィルター ID がこのリストのタイプに対して無効です。
関連資料:
411 ページの『システム・オブジェクト・アクセス (SOA) API』
システム・オブジェクト・アクセスを使用することで、グラフィカル・ユーザー・インターフェースを介し
て、システム・オブジェクトの表示および操作を行うことができます。
421 ページの『システム・オブジェクト・アクセスのエラー』
システム・オブジェクト・アクセス API は、戻りコードを使用してエラー条件を報告します。
管理 API
これらの API には、PC にインストールされているコードに関する情報にアクセスするための機能が備わ
っています。
管理 API を使用して、以下のことが判別できます。
v 製品のバージョンとサービス・レベル
v 個々のフィーチャーのインストール状況
v System i® ナビゲーターのプラグインのインストール状況
管理 API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbad.h
cwbapi.lib
cwbad.dll
Programmer's Toolkit:
Programmer's Toolkit には、管理 API の資料、cwbad.h ヘッダー・ファイルへのアクセス、およびプログラ
ム例へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit をオープンし
て、「クライアント情報」 > 「C/C++ API」と選択します。
管理 API のトピック
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
プログラミング
27
関連資料:
17 ページの『管理 API の戻りコード』
以下の、管理の戻りコードがあります。
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
管理 API のリスト
以下は、製品管理で使用する API です。
cwbAD_GetClientVersion:
cwbAD_GetClientVersion コマンドを使用します。
目的
現在 PC にインストールされている製品のバージョンを調べます。
構文
unsigned int CWB_ENTRY cwbAD_GetClientVersion(
unsigned long
*version
unsigned long
*release
unsigned long
*modificationLevel);
パラメーター
unsigned long *version - output
製品のバージョン・レベルが戻されるバッファーを指すポインター。
unsigned long *release - output
製品のリリース・レベルが戻されるバッファーを指すポインター。
unsigned long *modificationLevel - output
製品のモディフィケーション・レベルが戻されるバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
1 つまたは複数のポインター・パラメーターが NULL です。
使用法
戻りコードが CWB_OK ではない場合は、バージョン、リリース、およびモディフィケーション・レベル
の値は無意味です。
28
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbAD_GetProductFixLevel:
cwbAD_GetProductFixLevel コマンドを使用します。
目的
現在の製品の修正レベルを戻します。
構文
unsigned int CWB_ENTRY cwbAD_GetProductFixLevel(
char
*szBuffer
unsigned long
*ulBufLen);
パラメーター
char *szBuffer - output
プロダクトの修正レベル・ストリングが書き込まれるバッファー。
unsigned long * ulBufLen - input/output
szBuffer のサイズ。NULL 終了文字のスペースを含みます。出力時には、NULL 終了文字のスペース
と共に、修正レベル・ストリングの長さを含みます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
バッファー・オーバーフロー。必要な長さを ulBufLen に戻します。
CWB_INVALID_POINTER
無効なポインター。
使用法
製品の修正レベルを戻します。修正が適用されていない場合は、空ストリングが戻されます。
cwbAD_IsComponentInstalled:
製品コンポーネントは、フィーチャーと呼ばれます。この API は、製品のインストール済みフィーチャー
を識別するために使用します。
目的
特定の製品フィーチャーがインストールされているかどうかを示します。
構文
unsigned long CWB_ENTRY cwbAD_IsComponentInstalled(
unsigned long
ulComponentID,
cwb_Boolean
*bIndicator);
プログラミング
29
パラメーター
unsigned long ulComponentID - input
以下のいずれかの構成要素 ID に設定されている必要があります。
CWBAD_COMP_SSL
Secure Sockets Layer (セキュア・ソケット・レイヤー)。
CWBAD_COMP_SSL_128_BIT
128 ビットの Secure Sockets Layer (セキュア・ソケット・レイヤー)。
注: この定数は、 CWBAD_COMP_SSL と同じになるように定義します。
CWB_COMP_BASESUPPORT
プロダクトに必須のプログラム
CWBAD_COMP_OPTIONAL_COMPS
プロダクトのオプション・フィーチャー
CWBAD_COMP_DIRECTORYUPDATE
ディレクトリー更新
CWBAD_COMP_IRC
着信リモート・コマンド
CWBAD_COMP_OUG
ユーザーズ・ガイド
CWBAD_COMP_OPNAV
System i ナビゲーター
CWBAD_COMP_DATA_ACCESS
データ・アクセス
CWBAD_COMP_DATA_TRANSFER
データ転送
CWBAD_COMP_DT_BASESUPPORT
データ転送の基本サポート
CWBAD_COMP_DT_EXCEL_ADDIN
データ転送の Excel アドイン
CWBAD_COMP_DT_WK4SUPPORT
データ転送の WK4 ファイル・サポート
CWBAD_COMP_ODBC
ODBC
CWBAD_COMP_OLEDB
OLE DB Provider
CWBAD_COMP_MP
.NET Data Provider
CWBAD_COMP_AFP_VIEWER
AFP ワークベンチ・ビューアー
CWBAD_COMP_JAVA_TOOLBOX
Java Toolbox
30
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBAD_COMP_PC5250
PC5250 ディスプレイおよびプリンター・エミュレーター
PC5250 ディスプレイおよびプリンター・エミュレーター・サブコンポーネント
v CWBAD_COMP_PC5250_BASE_KOREAN
v CWBAD_COMP_PC5250_PDFPDT_KOREAN
v CWBAD_COMP_PC5250_BASE_SIMPCHIN
v CWBAD_COMP_PC5250_PDFPDT_SIMPCHIN
v CWBAD_COMP_PC5250_BASE_TRADCHIN
v CWBAD_COMP_PC5250_PDFPDT_TRADCHIN
v CWBAD_COMP_PC5250_BASE_STANDARD
v CWBAD_COMP_PC5250_PDFPDT_STANDARD
v CWBAD_COMP_PC5250_FONT_ARABIC
v CWBAD_COMP_PC5250_FONT_BALTIC
v CWBAD_COMP_PC5250_FONT_LATIN2
v CWBAD_COMP_PC5250_FONT_CYRILLIC
v CWBAD_COMP_PC5250_FONT_GREEK
v CWBAD_COMP_PC5250_FONT_HEBREW
v CWBAD_COMP_PC5250_FONT_LAO
v CWBAD_COMP_PC5250_FONT_THAI
v CWBAD_COMP_PC5250_FONT_TURKISH
v CWBAD_COMP_PC5250_FONT_VIET
v CWBAD_COMP_PC5250_FONT_HINDI
CWBAD_COMP_PRINTERDRIVERS
プリンター・ドライバー
CWBAD_COMP_AFP_DRIVER
AFP プリンター・ドライバー
CWBAD_COMP_SCS_DRIVER
SCS プリンター・ドライバー
CWBAD_COMP_OP_CONSOLE
オペレーション・コンソール
CWBAD_COMP_TOOLKIT
Programmer's Toolkit
CWBAD_COMP_TOOLKIT_BASE
ヘッダー、ライブラリー、および資料
CWBAD_COMP_EZSETUP
簡単セットアップ
CWBAD_COMP_TOOLKIT_JAVA_TOOLS
Programmer's Toolkit Tools for Java
CWBAD_COMP_SCREEN_CUSTOMIZER_ENABLER
Screen Customizer Enabler
プログラミング
31
CWBAD_COMP_OPNAV_BASESUPPORT
System i ナビゲーターの基本サポート
CWBAD_COMP_OPNAV_BASE_OPS
System i ナビゲーターの基本操作
CWBAD_COMP_OPNAV_JOB_MGMT
System i ナビゲーターのジョブ管理
CWBAD_COMP_OPNAV_SYS_CFG
System i ナビゲーターのシステム構成
CWBAD_COMP_OPNAV_NETWORK
System i ナビゲーターのネットワーク
CWBAD_COMP_OPNAV_SECURITY
System i ナビゲーターのセキュリティー
CWBAD_COMP_OPNAV_USERS_GROUPS
System i ナビゲーターのユーザーとグループ
CWBAD_COMP_OPNAV_DATABASE
System i ナビゲーターのデータベース
CWBAD_COMP_OPNAV_BACKUP
System i ナビゲーターのバックアップ
CWBAD_COMP_OPNAV_APP_DEV
System i ナビゲーターのアプリケーション開発
CWBAD_COMP_OPNAV_APP_ADMIN
System i ナビゲーターのアプリケーション管理
CWBAD_COMP_OPNAV_FILE_SYSTEMS
System i ナビゲーターのファイル・システム
CWBAD_COMP_OPNAV_MGMT_CENTRAL
System i ナビゲーターのマネージメント・セントラル
CWBAD_COMP_OPNAV_MGMT_COMMANDS
System i ナビゲーターのマネージメント・セントラル - コマンド
CWBAD_COMP_OPNAV_MGMT_PACK_PROD
System i ナビゲーターのマネージメント・セントラル - パッケージおよび製品
CWBAD_COMP_OPNAV_MGMT_MONITORS
System i ナビゲーターのマネージメント・セントラル - モニター
CWBAD_COMP_OPNAV_LOGICAL_SYS
System i ナビゲーターの論理システム
CWBAD_COMP_OPNAV_ADV_FUNC_PRES
System i ナビゲーターの拡張機能表示
cwb_Boolean *bIndicator - output
構成要素がインストールされている場合は、CWB_TRUE が入っている。構成要素がインストールされ
ていない場合は、CWB_FALSE が戻される。エラーが生じた場合は、なにも設定されない。
32
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
無効なポインター。
CWB_INVALID_COMPONENT_ID
このリリースでは、構成要素 ID が無効。
例: 管理 API
アプリケーションにおける管理 API の使用例です。
この例では、API を使用して、以下の情報の取得と表示を行います。
v 現行の製品バージョン/リリース/モディフィケーション・レベル
v 現行のサービス・パック (修正) レベル
v 現在 PC にインストールされているフィーチャー
その後で、ユーザーは、System i ナビゲーターのプラグインの名前を入力することができ、また、そのプ
ラグインがインストールされているかどうかが通知されます。
使用上の注意
cwbad.h * を組み込む。
cwbapi.lib とリンクする。
例
#include <windows.h>
#include <stdio.h>
#include "cwbad.h"
/*
* This is the highest numbered component ID known (it is
* the ID of the last component defined in cwbad.h).
*/
#define LAST_COMPID_WE_KNOW_ABOUT
(CWBAD_COMP_SSL)
/*
* Array of component names, taken from comments for component IDs
* in cwbad.h, so human-readable component descriptions are displayed .
* In the compDescr array, the component ID for a component must match
* the index in the array of that component’s description.
*
* For a blank or unknown component name, a string is provided to display
* an indication that the component ID is unknown, and what that ID is.
*/
static char* compDescr[ LAST_COMPID_WE_KNOW_ABOUT + 1 ] = {
"",
// #0 is not used
"Required programs",
"Optional Features",
"Directory Update",
"Incoming Remote Command",
プログラミング
33
"", // not used,
"Online User’s Guide",
"System i Navigator",
"Data Access",
"Data Transfer",
"Data Transfer Base Support",
"Data Transfer Excel Add-in",
"Data Transfer WK4 file support",
"ODBC",
"OLE DB Provider",
"AFP Workbench Viewer",
"IBM i Java Toolbox",
"5250 Display and Printer Emulator",
"Printer Drivers",
"AFP printer driver",
"SCS printer driver",
"IBM i Operations Console",
"IBM i Access Programmer’s Toolkit",
"Headers, Libraries, and Documentation",
"", // not used,
"", // not used,
"Java Toolkit",
"Screen customizer",
".NET Data Provider",
"",
//-------------#29
"", "", "", "", "",
//
#30-34
"", "", "", "", "",
//
#35-39
"", "", "", "", "",
//
#40-44
"", "", "", "", "",
//
#45-49
"", "", "", "", "",
//
not
#50-54
"", "", "", "", "",
//
#55-59
"", "", "", "", "",
//
#60-64
"", "", "", "", "",
//
#65-69
"", "", "", "", "",
//
used
#70-74
"", "", "", "", "",
//
#75-79
"", "", "", "", "",
//
#80-84
"", "", "", "", "",
//
#85-89
"", "", "", "", "",
//
#90-94
"", "", "", "", "",
//------------ #95-99
"System i Navigator Base Support",
"System i Navigator Basic Operations",
"System i Navigator Job Management",
"System i Navigator System Configuration",
"System i Navigator Networks",
"System i Navigator Security",
"System i Navigator Users and Groups",
"System i Navigator Database",
"",
// not used
#108
"System i Navigator Backup",
"System i Navigator Application Development",
"System i Navigator Application Administrat",
"System i Navigator File Systems",
"System i Navigator Management Central",
"System i Navigator Management Central - Commands",
"System i Navigator Management Central - Packages and Products",
"System i Navigator Management Central - Monitors",
"System i Navigator Logical Systems",
"System i Navigator Advanced Function Presentation",
"",
//-------------#119
"", "", "", "", "",
// not
#120-124
"", "", "", "", "",
//
#125-129
"", "", "", "", "",
//
#130-134
"", "", "", "", "",
// used
#135-139
"", "", "", "", "",
//
#140-144
"", "", "", "", "",
//------------ #145-149
"PC5250: BASE_KOREAN",
"PC5250: PDFPDT_KOREAN",
34
IBM i: Windows アプリケーション・パッケージ: プログラミング
"PC5250: BASE_SIMPCHIN",
"PC5250: PDFPDT_SIMPCHIN",
"PC5250: BASE_TRADCHIN",
"PC5250: PDFPDT_TRADCHIN",
"PC5250: BASE_STANDARD",
"PC5250: PDFPDT_STANDARD",
"PC5250: FONT_ARABIC",
"PC5250: FONT_BALTIC",
"PC5250: FONT_LATIN2",
"PC5250: FONT_CYRILLIC",
"PC5250: FONT_GREEK",
"PC5250: FONT_HEBREW",
"PC5250: FONT_LAO",
"PC5250: FONT_THAI",
"PC5250: FONT_TURKISH",
"PC5250: FONT_VIET",
"PC5250: FONT_HINDI",
"",
//-----------"", "", "", "", "",
//
"", "", "", "", "",
// not
"", "", "", "", "",
//
"", "", "", "", "",
// used
"", "", "", "", "",
//
"", "", "", "", "",
//-----------"Secure Sockets Layer (SSL)" } ;
static char unknownComp[] = "unknown, ID=
";
static char* pInsertID
= &( unknownComp[12] );
//
#169
#170-174
#175-179
#180-184
#185-189
#190-194
#195-199
// last one defined
insert ID here!
/**************************************************************************
* Show the IBM i Access for Windows Version/Release/Modification level
**************************************************************************/
void showCA_VRM()
{
ULONG caVer, caRel, caMod;
UINT rc;
char fixlevelBuf[ MAX_PATH ];
ULONG fixlevelBufLen = sizeof( fixlevelBuf );
printf( "IBM i Access level installed:\n\n" );
rc = cwbAD_GetClientVersion( &caVer, &caRel, &caMod);
if ( rc != CWB_OK )
{
printf( "
Error %u occurred when calling cwbAD_GetClientVersion()¥n¥n",
rc );
}
else
{
printf( "
Version %lu, Release %lu, Modification %lu¥n¥n",
caVer, caRel, caMod );
printf( "IBM i Access service pack level installed:\n\n" );
rc = cwbAD_GetProductFixLevel( fixlevelBuf, &fixlevelBufLen );
if ( rc != CWB_OK )
{
printf( "
Error %u occurred when calling "
"cwbAD_GetProduceFixLevel()¥n¥n", rc );
}
else if ( fixlevelBuf[0] == ’¥0’ ) // empty, no service packs applied
{
printf( "
None¥n¥n" );
}
else
{
プログラミング
35
printf( "
%s¥n¥n", fixlevelBuf );
}
}
}
/**************************************************************************
* Call IBM i Access for Windows API to determine if the component is installed,
* and pass back:
*
NULL if the component is not installed or an error occurs,
*
OR
*
A string indicating the component name is unknown if the
*
component ID is higher than we know about OR the component
*
description is blank,
*
OR
*
The human-readable component description if known.
**************************************************************************/
char* isCompInstalled( ULONG compID )
{
cwb_Boolean bIsInstalled;
char*
pCompName;
UINT rc = cwbAD_IsComponentInstalled( compID, &bIsInstalled );
/*
* Case 1:
*
*/
if ( ( rc !=
{
pCompName
}
Error OR component not installed, return NULL to
indicate not installed.
CWB_OK ) || ( bIsInstalled == CWB_FALSE ) )
= NULL;
/*
* Case 2: Component IS installed, but its name is not known,
*
return component name unknown string.
*/
else if ( ( compID > LAST_COMPID_WE_KNOW_ABOUT ) ||
( compDescr[ compID ][ 0 ] == ’¥0’ ) )
{
pCompName = unknownComp;
sprintf( pInsertID, "%lu", compID );
}
/*
* Case 3: Component IS installed, and a name is known, return it
*/
else
{
pCompName = compDescr[ compID ];
}
return pCompName;
}
/**************************************************************************
* List the IBM i Access Client Solutions features that currently are installed.
**************************************************************************/
void showCA_CompInstalled()
{
ULONG compID;
char* compName;
printf( "IBM i Access features installed:\n\n" );
36
IBM i: Windows アプリケーション・パッケージ: プログラミング
/*
* Try all known features, plus a bunch more in case some
* have been added (via service pack).
*/
for ( compID = 0;
compID < (LAST_COMPID_WE_KNOW_ABOUT + 50);
compID++ )
{
compName = isCompInstalled( compID );
if ( compName != NULL )
{
printf( "
%s¥n", compName );
}
}
printf( "¥n" );
}
/**************************************************************************
* MAIN PROGRAM BODY
**************************************************************************/
void main(void)
{
UINT
rc;
char
pluginName[ MAX_PATH ];
cwb_Boolean bPluginInstalled;
printf( "=======================================¥n");
printf( "IBM i Access What’s Installed Reporter\n" );
printf( "=======================================¥n¥n");
showCA_VRM();
showCA_CompInstalled();
/*
* Allow user to ask by name what plug-ins are installed.
*/
while ( TRUE ) /* REMINDER: requires a break to exit the loop! */
{
printf( "Enter plug-in to check for, or DONE to quit:¥n" );
gets( pluginName );
if ( stricmp( pluginName, "DONE" ) == 0 )
{
break;
/* exit from the while loop, DONE at user’s request */
}
rc = cwbAD_IsOpNavPluginInstalled( pluginName, &bPluginInstalled );
if ( rc == CWB_OK )
{
if ( bPluginInstalled == CWB_TRUE )
{
printf( "The plug-in ’%s’ is installed.¥n¥n", pluginName );
}
else
{
printf( "The plug-in ’%s’ is NOT installed.¥n¥n", pluginName );
}
}
else
{
printf(
"Error %u occurred when calling cwbAD_IsOpNavPluginInstalled.¥n¥n",
rc );
}
プログラミング
37
}
// end while (TRUE)
printf( "¥nEnd of program.¥n¥n" );
}
通信およびセキュリティー API
『通信およびセキュリティー』トピックでは、アプリケーション・プログラミング・インターフェース
(API) の使用方法について説明します。
これらの API は、以下のことに使用することができます。
v IBM i システム・オブジェクトを取得、使用、および削除する。システム・オブジェクトは、製品のさ
まざまな API で必要とされます。システム・オブジェクトは、IBM i のセキュリティー・オブジェクト
(ユーザー ID、パスワード、サインオン日時など) に対する接続や検証に関する情報を保有しています。
v 製品の機能を使用する際には、システム・リストで構成されている、環境や接続に関する情報を入手し
ます。システム・リストとは、現在、構成されているすべての環境のリストであり、これらの環境内で
のシステムのリストです。システム・リストは「ユーザーごとに」保管および管理され、他のユーザー
が使用することはできません。
注: ユーザーが新規システムを明示的に構成して、それをシステム・リストに追加する必要はありませ
ん。新規システムは、ユーザーが新規システムに接続したときに、自動的にシステム・リストに追加さ
れます。
通信およびセキュリティー API に必要なファイル
ヘッダー・ファイル
システム・オブジェクト API
システム・リスト API
cwbcosys.h
cwbco.h
インポート・ライブ
ラリー
ダイナミック・リン
ク・ライブラリー
cwbapi.lib
cwbco.dll
Programmer's Toolkit:
Programmer's Toolkit では、通信およびセキュリティーに関する資料、cwbco.h ヘッダー・ファイルおよび
cwbcosys.h ヘッダー・ファイルへのアクセス、およびプログラム例へのリンクが提供されます。この情報
にアクセスするには、Programmer's Toolkit をオープンして、「通信およびセキュリティー」 > 「C/C++
API」と選択します。
通信およびセキュリティーに関するトピック
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
17 ページの『通信 API の戻りコード』
以下の通信の API 戻りコードがあります。
24 ページの『セキュリティー API の戻りコード』
以下のセキュリティーの API 戻りコードがあります。
10 ページの『グローバル戻りコード』
以下のグローバル戻りコードがあります。
38
IBM i: Windows アプリケーション・パッケージ: プログラミング
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
システム・オブジェクトの属性
IBM i プラットフォームにおけるシステム・オブジェクトの属性は、システム・オブジェクトが表すシス
テムへのサインオンおよび通信の動作に影響します。
cwbCO_Signon または cwbCO_Connect のいずれかを使用してサインオンが正常終了した後では、ほとんど
の属性は変更不可になります。正常なサインオンの後で変更可能な属性は、ウィンドウ・ハンドルと接続タ
イムアウトの 2 つだけです。正常なサインオンの後で、その他の属性値を変更する API を呼び出すと、
戻りコード CWB_INV_AFTER_SIGNON で失敗します。
一部の値および値を変更する機能を、ポリシーによって制御することができます。ポリシーとは、システム
管理者がセットアップしてデフォルトの属性値を指示し、属性の変更を禁止できるようにする制御情報で
す。『システム・オブジェクトの属性のリスト』のトピックに指定されているデフォルト値 (以下にリンク
する) は、以下の条件の下で使用されます。
v ポリシーが異なる別の値を指定または示唆しない場合。
v そのような属性の値が、システム・リストに指定されたシステムで明示的に構成されていない場合。
属性のデフォルト値がポリシーによって設定できる場合には、このことが示されます。属性の値の変更がポ
リシーによって禁止できる場合は、以下のようになります。
v 属性が変更可能かどうかをチェックするための API が用意される。
v そのポリシーのために設定が失敗した場合は、属性の設定方式によって特定の戻りコードが提供され
る。
関連資料:
74 ページの『cwbCO_Signon』
cwbCO_Signon コマンドを使用します。
46 ページの『cwbCO_Connect』
cwbCO_Connect コマンドを使用します。
システム・オブジェクトの属性のリスト:
以下のリストには、IBM i におけるシステム・オブジェクト属性の記述、要件、および考慮事項が掲載さ
れています。
それぞれの属性には、以下のものが示されています。
v 属性を取得して、設定するために使用可能な API
v システム・オブジェクトが作成されるときのデフォルト値
注: 属性の設定値は、設定対象になっているシステム・オブジェクトに対してのみ適用されます。たとえシ
ステム名が同じであっても、その他のいかなるシステム・オブジェクトにも適用されません。
IBM i 名:
システム・オブジェクトのこのインスタンスによって定義されている、通信相手のシステム。これ
は、cwbCO_CreateSystem または cwbCO_CreateSystemLike が呼び出された時点でのみ、設定する
ことができます。特定のユーザー ID のセキュリティー情報を検証する際に、システム名が固有の
プログラミング
39
識別コードとして使用されることに注意してください。 2 つの異なるシステム・オブジェクト
に、同じ物理装置を表す異なるシステム名が含まれる場合、2 つのシステム・オブジェクトに対す
るユーザー ID およびパスワードの検証が、個別に必要となります。例えば、システム名 "SYS1"
および "SYS1.ACME.COM" が同じ IBM i 装置を表す場合に、これが適用されます。この結果、
プロンプトが二重になり、接続時に別々のデフォルトのユーザー ID を使用することになります。
cwbCO_GetSystemName を使用して取得。
デフォルト:
システム・オブジェクトが作成されるときに明示的に設定されるため、デフォルト値はあ
りません。
説明
IBM i の構成済み接続の記述。
System i ナビゲーターを使用して設定します。
cwbCO_GetDescription を使用して検索します。
記述は各システム・オブジェクトとともに保管され、そのシステム・オブジェクトのために変更さ
れることはありません。 System i ナビゲーターを使用して記述を変更しても、変更前に存在して
いたそのシステムのシステム・オブジェクトは変更されません。新規のシステム・オブジェクトの
みに新規の記述が含まれます。
デフォルト:
ブランク。これはポリシーで指定変更可能です。
ユーザー ID:
システムで使用される IBM i ユーザー ID。
cwbCO_GetUserIDEx を使用して取得。
cwbCO_SetUserIDEx を使用して設定。
デフォルト:
システム・オブジェクトで指定されているシステムに最初に接続したときに、以下のプロ
ンプトが出されます。
v デフォルトのユーザー ID の指定。
v デフォルトのユーザー ID を Windows のユーザー ID と同一にすることの指定。
v デフォルト値を使用しないこと。
後で接続しようとした場合、使用されるデフォルトのユーザー ID は、最初に接続しよう
としたときに出されたプロンプトで、どのオプションを選択したかによって決まります。
パスワード
システムへのサインオン時に使用する IBM i パスワード。
cwbCO_SetPassword を使用して設定。
デフォルト:
システム・オブジェクトで設定されたユーザー ID が、システム・オブジェクトで指定さ
れたシステムにサインオンしたことがない場合には、ブランク (パスワード設定なし)。以
前に、システム・オブジェクトで指定されたシステムへのサインオンまたは接続が正常に
行われている場合は、次回のサインオンまたは接続で、そのパスワードを使用できます。
cwbCO_SetPassword() API を介してパスワードが入力される場合、システムは製品の揮発
性パスワード・キャッシュにパスワードを入れなくなりました。以前、このパスワードは
揮発性 (つまり、セッション) パスワード・キャッシュに入っていました。
40
IBM i: Windows アプリケーション・パッケージ: プログラミング
デフォルトのユーザー・モード
デフォルトのユーザー ID をどこから取得するか、それを使用するかどうかも含めた、デフォルト
のユーザー ID に関連した動作を制御します。設定されていない場合 (値が
CWBCO_DEFAULT_USER_MODE_NOT_SET) は、サインオンしようとした時点での希望する動作
を選択するようにプロンプトが出されます。
cwbCO_GetDefaultUserMode を使用して取得。
cwbCO_SetDefaultUserMode を使用して設定。
cwbCO_CanModifyDefaultUserMode を使用して、変更の制限のチェック。
デフォルト:
CWBCO_DEFAULT_USER_MODE_NOT_SET
注: デフォルト値はポリシーで指定変更可能です。
プロンプト・モード
ユーザー ID およびパスワードを求めるプロンプトを制御します。指定できる値と関連する動作に
ついては、cwbCO_SetPromptMode の宣言の注釈を参照してください。
cwbCO_GetPromptMode を使用して取得。
cwbCO_SetPromptMode を使用して設定。
デフォルト:
CWBCO_PROMPT_IF_NECESSARY
ウィンドウ・ハンドル
呼び出し側アプリケーションのウィンドウ・ハンドル。これが設定されている場合には、発行する
IBM i のサインオン関連のプロンプトは、いずれもウィンドウ・ハンドルを使用し、関連するウィ
ンドウに対してモーダルになります。このことは、そのハンドルがシステム・オブジェクトに関連
している場合、メインのアプリケーション・ウィンドウの下にプロンプトが隠れることは決してな
いということを意味します。ウィンドウ・ハンドルがなにも設定されていない場合は、プロンプト
が存在してもメインのアプリケーション・ウィンドウの下に隠れてしまう場合があります。
cwbCO_GetWindowHandle を使用して取得。
cwbCO_SetWindowHandle を使用して設定。
デフォルト:
NULL (設定しない)
検証モード
ユーザー ID とパスワードを検証する際に、この検証を実際に実行するために IBM i通信を行うか
どうかを指定します。指定できる値と関連する動作については、cwbCO_SetValidateMode および
cwbCO_GetValidateMode の宣言の注釈を参照してください。
cwbCO_GetValidateMode を使用して取得。
cwbCO_SetValidateMode を使用して設定。
デフォルト:
CWBCO_VALIDATE_IF_NECESSARY
セキュア・ソケットの使用法
システムを認証し、送受信されるデータを暗号化するために、ソケットを使用するかどうかを指定
します。セキュア・ソケットが使用できないようなケース (例えば、セキュア・ソケットのソフト
ウェア・サポートが PC にインストールされていない場合) があります。その場合は、セキュア・
プログラミング
41
ソケットを使用するアプリケーションまたはユーザー要求が、cwbCO_UseSecureSockets API が呼
び出された時点か、または接続時のいずれかで失敗することがあります。そのような失敗が起こら
ない場合は、セキュア・ソケットが使用され、cwbCO_IsSecureSockets は CWB_TRUE を戻しま
す。
cwbCO_IsSecureSockets を使用して取得。
cwbCO_UseSecureSockets を使用して設定。
cwbCO_CanModifyUseSecureSockets を使用して、変更の制限のチェック。
デフォルト:
IBM i で構成されたものが何であれ、このシステムのシステム・リストが使用されます。
このシステムに IBM i 構成が存在しない場合、または IBM i Access のデフォルト値を使
用するように構成で指定されている場合、セキュア・ソケットは使用されません
(CWB_FALSE)。
注: デフォルト値はポリシーで指定変更可能です。
ポート・ルックアップ・モード
IBM i ホスト・サービス用のリモート・ポートの検索方法を指定します。ローカル (PC 上) で検
索するか、IBM i ホストで検索するか、あるいは単に指定されたサービスのデフォルト (「標準」)
のポートを使用するかを指定します。ローカルのルックアップが選択された場合、PC の
SERVICES ファイルにあるルックアップの標準 TCP/IP 方式が使用されます。サーバー・ルックア
ップが指定されている場合は、IBM i マッパーへの接続が行われ、IBM i サービス・テーブルから
のルックアップによって、ポート番号が検索されます。ローカルもしくはサーバーのルックアップ
方式のいずれかが失敗した場合には、サービスへの接続は失敗します。詳細および指定できる値に
ついては、cwbCO_SetPortLookupMode の API 宣言を参照してください。
cwbCO_GetPortLookupMode を使用して取得。
cwbCO_SetPortLookupMode を使用して設定。
cwbCO_CanModifyPortLookupMode を使用して、変更の制限のチェック。
デフォルト:
IBM i リストでこのシステム用に構成されたものが、すべて使用されます。このシステム
に IBM i 構成が存在しない場合、デフォルト値は CWBCO_PORT_LOOKUP_SERVER に
なります。
注: デフォルト値はポリシーで指定変更可能です。
パーシスタンス・モード
cwbCO_Connect への呼び出しが正常に終了した後に、このシステム・オブジェクトで指定されたシ
ステムを (まだリストにない場合に) IBM i リストに追加するかどうかを指定します。詳細および
指定できる値については、cwbCO_SetPersistenceMode を参照してください。
cwbCO_GetPersistenceMode を使用して取得。
cwbCO_SetPersistenceMode を使用して設定。
cwbCO_CanModifyPersistenceMode を使用して、変更の制限のチェック。
デフォルト:
CWBCO_MAY_MAKE_PERSISTENT
注: デフォルト値はポリシーで指定変更可能です。
42
IBM i: Windows アプリケーション・パッケージ: プログラミング
接続タイムアウト
接続試行が完了するまでの待機時間を指定します。この設定値は、TCP/IP 通信スタックが試行を
放棄するまで待機する時間に影響しません。 TCP/IP 通信スタックは、IBM i Access の接続タイ
ムアウトの有効期限が切れる前にタイムアウトになる可能性があります。詳細および指定できる値
については、cwbCO_SetConnectTimeout を参照してください。この値はシステム・オブジェクトに
合わせていつでも変更することができます。
cwbCO_GetConnectTimeout を使用して取得
cwbCO_SetConnectTimeout を使用して設定
デフォルト:
CWBCO_CONNECT_TIMEOUT_DEFAULT
注: デフォルト値はポリシーで指定変更可能です。
通信およびセキュリティー: 作成および削除の API
これらの API は、IBM i オブジェクトの作成および削除に使用されます。
cwbCO_CreateSystem:
cwbCO_CreateSystem コマンドを使用します。
目的
新規のシステム・オブジェクトを作成し、そのシステム・オブジェクトに後続の呼び出しで使用できるハン
ドルを戻します。システム・オブジェクトは、設定し、検索することができる多くの属性を持っています。
詳しくは、 39 ページの『システム・オブジェクトの属性』を参照してください。
構文
UINT CWB_ENTRY cwbCO_CreateSystem(
LPCSTR
cwbCO_SysHandle
systemName,
*system);
パラメーター
LPCSTR systemName - input
ヌル終了する IBM i 名を含んでいるバッファーを指すポインター。ホスト名、または IBM i の IP
アドレス (小数点付き 10 進数) 自体を指定することができます。長さがゼロであってはならず、また
ブランクを含んでいてはなりません。指定された名前が有効な IBM i ホスト名または IP アドレス・
ストリング (「nnn.nnn.nnn.nnn」の形式) ではない場合、接続やセキュリティー検証の試みはすべて失
敗します。
cwbCO_SysHandle *system - output
システム・オブジェクト・ハンドルがこのパラメーターへ戻されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインター・パラメーターのいずれかが NULL です。
プログラミング
43
CWB_INVALID_SYSNAME
システム名が無効です。
CWB_RESTRICTED_BY_POLICY
ユーザーが、システム・リストにまだ定義されていないシステムのシステム・オブジェクトを作成
することを禁止するポリシーが存在します。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
使用法
システム・オブジェクトの使用が終了した後に、cwbCO_DeleteSystem を呼び出し、システム・オブジェク
トが使用していた資源を解放する必要があります。既存のものと同じようなシステム・オブジェクトを作成
したい場合は、cwbCO_CreateSystemLike を使用します。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbCO_CreateSystemLike:
cwbCO_CreateSystemLike コマンドを使用します。
目的
所定のシステム・オブジェクトと似ているシステム・オブジェクトを作成します。新規システム・オブジェ
クトに特定のシステム名を与えることも、NULL を指定して所定のシステム・オブジェクトの名前を使用
することも、いずれも可能です。所定のシステム・オブジェクトのすべての属性は、以下の例外を除いて、
新規システム・オブジェクトへコピーされます。
v ユーザー ID
v パスワード
v システム名 (別のシステム名が指定されていた場合)
v IP アドレス (システム名が異なる場合)
システム・オブジェクトの属性のリストについては、 39 ページの『システム・オブジェクトの属性のリ
スト』を参照してください。
構文
UINT CWB_ENTRY cwbCO_CreateSystemLike(
cwbCO_SysHandle
LPCSTR
cwbCO_SysHandle
systemToCopy,
systemName
*system);
パラメーター
cwbCO_SysHandle systemToCopy - input
以前の、cwbCO_CreateSystem もしくは cwbCO_CreateSystemLike への呼び出しによって戻されたハン
ドル。これは IBM i の ID です。これが「コピー」されるオブジェクトです。
44
IBM i: Windows アプリケーション・パッケージ: プログラミング
LPCSTR systemName - input
新規システム・オブジェクトで使用する IBM i 名 (ヌル終了のもの) を含んでいるバッファーを指す
ポインター。 NULL または空のストリングが渡された場合は、所定のシステム・オブジェクトからの
名前が新規システム・オブジェクトにコピーされます。システム名を指定する場合は、ホスト名または
IBM i の IP アドレス (小数点付き 10 進数) のいずれを指定することもできます。指定された名前が
有効な IBM i ホスト名または IP アドレス・ストリング (「nnn.nnn.nnn.nnn」の形式) ではない場合、
接続やセキュリティー検証の試みはすべて失敗します。
cwbCO_SysHandle *newSystem - output
新規システム・オブジェクトのシステム・オブジェクト・ハンドルがこのパラメーターに戻されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
API に与えられたポインターが無効です。
CWB_INVALID_SYSNAME
システム名が無効です。
CWB_RESTRICTED_BY_POLICY
ユーザーが、システム・リストにまだ定義されていないシステムのシステム・オブジェクトを作成
することを禁止するポリシーが存在します。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
使用法
新規システム・オブジェクトの使用が終了した後で、cwbCO_DeleteSystem を呼び出し、システム・オブジ
ェクトが使用していた資源を解放する必要があります。
ユーザー ID とパスワードの検証が、新しいものについてはまだ行われていないため、新規システム・オ
ブジェクトの状態は所定のシステム・オブジェクトの状態と同じではない可能性があります。また、新規シ
ステム・オブジェクトはそれに関連した接続は持っていないのに対して、所定のシステム・オブジェクトで
は持っている可能性があります。このため、所定のシステム・オブジェクトの属性を、その状態のために変
更できない場合であっても、新規システム・オブジェクトの属性はその状態が異なっている可能性があるた
めに、変更できることがあります。
cwbCO_DeleteSystem:
cwbCO_DeleteSystem コマンドを使用します。
目的
そのハンドルで指定されたシステム・オブジェクトを削除し、システム・オブジェクトが使用していたすべ
ての資源を解放します。
プログラミング
45
構文
UINT CWB_ENTRY cwbCO_DeleteSystem(
cwbCO_SysHandle
system);
パラメーター
cwbCO_SysHandle system - input
以前の、cwbCO_CreateSystem もしくは cwbCO_CreateSystemLike への呼び出しによって戻されたハン
ドル。これは IBM i の ID です。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
使用法
システム・オブジェクト資源が解放される前に、指定されたシステム・オブジェクトを使用して行われた接
続が 1 つでもある場合には、必要であれば強制的に、接続を終了させます。活動状態にある接続があるか
どうかを判別するには、cwbCO_IsConnected を呼び出します。既存の接続の切断がいずれも正常終了した
かどうかを知りたい場合は、この API を呼び出す前に cwbCO_Disconnect を明示的に呼び出します。
通信およびセキュリティー: 接続および切断の API
IBM i の接続および切断や、その他の関連する動作をサポートする API です。
cwbCO_Connect:
cwbCO_Connect コマンドを使用します。
目的
指定された IBM i ホスト・サービスに接続します。
構文
UINT CWB_ENTRY cwbCO_Connect(
cwbCO_SysHandle
cwbCO_Service
cwbSV_ErrHandle
system,
service,
errorHandle );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは、接続
に使用される IBM i の ID です。
cwbCO_Service service - input
IBM i の接続用サービス。有効な値は、CWBCO_SERVICE_ANY および CWBCO_SERVICE_ALL の
値を除く、 95 ページの『cwbCO_Service の定義』でリストされている値。この API には、複数のサ
ービスを一度に切断できる cwbCO_Disconnect とは異なり、 1 つのサービスしか指定できません。
46
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_SERVICE_NAME_ERROR
サービス識別コードが有効な値ではないか、値を組み合わせたものとなっていました (この API
では、単一の値しか許されていません)。
CWB_CONNECTION_TIMED_OUT
システムを検出するのに時間がかかりすぎて、タイムアウトになりました。
CWB_CONNECTION_REFUSED
システムが、接続の受け入れを拒否しました。
CWB_NETWORK_IS_DOWN
ネットワーク・エラーが発生しました。あるいは TCP/IP が、PC 上で正しく構成されていませ
ん。
CWB_NETWORK_IS_UNREACHABLE
現在システムが接続されているネットワーク・セグメントは、PC が接続されているセグメントか
ら到達できません。
CWB_USER_TIMEOUT
システム・オブジェクトに関連した接続タイムアウト値の有効期限が、接続が確立される前に切れ
たため、待機を終了しました。
CWB_FIPS_UNAVAILABLE
この接続は SSL 用に構成され、FIPS 準拠モードが使用可能ですが、FIPS サポートが利用不可の
ため、SSL は使用できません。リカバリー情報については、以下のパスを使用してメッセージ
CWBCO1060 を参照してください。
「スタート」 > 「プログラム」 > 「IBM i Access Client ソリューション」 > 「ユーザー
ズ・ガイド」 > 「メッセージ」 > 「IBM i Access Client ソリューションメッセージ」 >
「CWBCO1060」
注: セキュリティー検証を行って失敗した結果として、その他の共通の戻りコードが戻されることがありま
す。 cwbCO_Signon の注釈の共通戻りコードを参照してください。
使用法
IBM i サインオンがまだ行われていない場合、cwbCO_Connect の呼び出し時に、まずサインオンが行われ
ます。サインオンを別のときに実行させたい場合は、先に cwbCO_Signon を呼び出してから、後で
cwbCO_Connect を呼び出します。サインオンとその動作については、cwbCO_Signon の注釈を参照してく
ださい。サインオンの試行が失敗した場合は、指定されたサービスへの接続は確立されません。
プログラミング
47
指定のシステム・オブジェクトで指定されたシステムがシステム・リストに存在せず、かつ、システム・オ
ブジェクト・パーシスタンス・モードが適切に設定されている場合、 cwbCO_Connect または
cwbCO_Signon の呼び出しが最初に正常に行われた際に、システム・オブジェクトで指定されたシステムが
システム・リストに追加されます。パーシスタンス・モードの詳細については、cwbCO_SetPersistenceMode
の注釈を参照してください。
指定されたサービスへの接続が既に存在している場合は、接続は新たには設定されず、CWB_OK が戻され
ます。この API の呼び出しが正常に行われるごとに、指定されたサービスへの接続の使用回数が増やされ
ます。
cwbCO_Disconnect が同じサービスのために呼び出されるごとに、使用回数は減らされます。使用回数がゼ
ロに達すると、接続が実際に終了します。
したがって、cwbCO_Connect API へのすべての呼び出しについて、接続が適切な時間に終了することがで
きるようにするために、後で cwbCO_Disconnect API への対の呼び出しがあるということは、きわめて重
要なことです。別の方法としては、CWBCO_SERVICE_ALL を指定して cwbCO_Disconnect API を呼び出
し (指定されたシステム・オブジェクトを通じて行われた全サービスに対して既存の接続をすべて切断す
る)、使用回数を全部 0 にリセットするというものがあります。
戻りコードが CWB_USER_TIMEOUT の場合、 cwbCO_SetConnectTimeout を呼び出してこのシステム・オ
ブジェクトの接続タイムアウト値を大きくし、接続を再度試行することができます。 TCP/IP 通信スタック
によって放棄されるまで、IBM i Access に放棄させたくない場合は、接続タイムアウト値を
CWBCO_CONNECT_TIMEOUT_NONE に設定して、接続を再度試行します。
関連資料:
39 ページの『システム・オブジェクトの属性』
IBM i プラットフォームにおけるシステム・オブジェクトの属性は、システム・オブジェクトが表すシス
テムへのサインオンおよび通信の動作に影響します。
cwbCO_Disconnect:
cwbCO_Disconnect コマンドを使用します。
目的
指定された IBM i ホスト・サービスからの切断を行います。
構文
UINT CWB_ENTRY cwbCO_Disconnect(
cwbCO_SysHandle
cwbCO_Service
cwbSV_ErrHandle
system,
service,
errorHandle );
パラメーター
cwbCO_SysHandle system - input
以前の、cwbCO_CreateSystem もしくは cwbCO_CreateSystemLike への呼び出しによって戻されたハン
ドル。これは、切断に使用される IBM i の ID です。
cwbCO_Service service - input
IBM i の切断用サービス。有効な値は、CWBCO_SERVICE_ANY の値を除き、このファイルの冒頭に
リストされています。CWBCO_SERVICE_ALL が指定されている場合は、すべての接続されたサービ
スへの接続は終了し、接続使用回数はすべてリセットされてゼロに戻ります。
48
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_SERVICE_NAME_ERROR
サービス識別コードが無効です。
CWB_NOT_CONNECTED
単一サービスが接続されませんでした。
使用法
cwbCO_Connect を使用して確立された接続がもはや必要なくなった際に、この関数を呼び出してくださ
い。
指定されたサービスが切断できない場合、戻りコードはこのエラーを戻します。複数のエラーが生じた場
合、最初の戻りコードだけが API 戻りコードとして戻されます。
個別サービスの切断に関する使用上の注意:
この関数によって、このシステム・オブジェクトで指定したサービスの使用回数が減らされ、接続
は実際に終了する場合も、終了しない場合もあります。詳しくは、cwbCO_Connect API の使用上
の注意を参照してください。
現在、接続されていないサービスを切断すると CWB_NOT_CONNECTED になります。
個別サービスは、安全に切断されます。
CWBCO_SERVICE_ALL に関する使用上の注意:
戻りコード CWB_NOT_CONNECTED は、接続されたサービスの数に関係なく、
CWBCO_SERVICE_ALL が指定されている場合には戻されません。
活動状態のサービスすべてに対する切断を要求すると、IBM i 切断メッセージが生成されます。
cwbCO_GetConnectTimeout:
cwbCO_GetConnectTimeout コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、現在設定されている秒単位の接続タイムアウト
値を取得します。
プログラミング
49
構文
UINT CWB_ENTRY cwbCO_GetConnectTimeout(
cwbCO_SysHandle
PULONG
system,
timeout );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
PULONG timeout - output
秒単位のタイムアウト値を戻します。この値は CWBCO_CONNECT_TIMEOUT_MIN から
CWBCO_CONNECT_TIMEOUT_MAX の範囲になります。あるいは、接続タイムアウト値が必要でな
い場合には、CWBCO_CONNECT_TIMEOUT_NONE になります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
タイムアウト・ポインターが NULL です。
使用法
なし
cwbCO_GetPersistenceMode:
cwbCO_GetPersistenceMode コマンドを使用します。
目的
指定されたシステム・オブジェクトについて、それが表すシステムがサインオンに成功した後で、システ
ム・リストにその属性とともにそのシステムが追加されるかどうか (まだリストにない場合) についての情
報を取得します。
構文
UINT CWB_ENTRY cwbCO_GetPersistenceMode(
cwbCO_SysHandle
system,
cwbCO_PersistenceMode *mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
50
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbCO_PersistenceMode * mode - output
パーシスタンス・モードを戻します。指定できる値とその意味については、cwbCO_SetPersistenceMode
の注釈を参照してください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_IsConnected:
cwbCO_IsConnected コマンドを使用します。
目的
現行のシステム・オブジェクトのうち、特定のものを使用している IBM i 接続があるかどうかを検出し、
ある場合にはその数も検出します。
構文
UINT CWB_ENTRY cwbCO_IsConnected(
cwbCO_SysHandle
cwbCO_Service
PULONG
system,
service,
numberOfConnections );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_Service service - input
接続をチェックするサービス。 95 ページの『cwbCO_Service の定義』にリストされている
cwbCO_Service のいずれの値も有効です。何らかのサービスが接続されているかどうかを検出するに
は、CWBCO_SERVICE_ANY を指定します。このシステム・オブジェクトを使用して接続されている
サービスの数を検出するには、CWBCO_SERVICE_ALL を指定します。
PULONG numberOfConnections - output
指定されたサービス (1 つまたは複数) について活動中の接続の数を戻すのに使用されます。指定され
たサービスが CWBCO_SERVICE_ALL ではない場合は、システム・オブジェクトごとに、1 つのサー
ビスにつき活動中の接続は、多くても 1 つしか認められないため、戻される値は 0 または 1 のいず
れかです。 CWBCO_SERVICE_ALL が指定されている場合は、サービスごとに 1 つの接続が活動中
である可能性があるため、この値は 0 から可能なサービスの数までになります。
プログラミング
51
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。指定されたすべてのサービスが接続、あるいは CWBCO_SERVICE_ANY が指定されて
いる場合は 1 つまたは複数のサービスが接続されています。
CWB_NOT_CONNECTED
単一のサービスが指定されていた場合は、そのサービスは接続されません。
CWBCO_SERVICE_ANY の値が指定されていた場合は、活動中の接続はなにもありません。
CWBCO_SERVICE_ALL の値が指定されていた場合は、接続されていないサービスが少なくとも 1
つは存在します。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_SERVICE_NAME_ERROR
サービス識別コードが無効です。
CWB_INVALID_POINTER
numberOfConnections パラメーターが NULL です。
使用法
CWBCO_SERVICE_ALL が指定されており CWB_NOT_CONNECTED が戻された場合には、活動接続がい
くつか存在する可能性があり、依然として、活動接続の回数が戻されます。指定されたシステム・オブジェ
クトを通じて接続がいくつ存在するかを検出する場合は、この API を呼び出し、CWBCO_SERVICE_ALL
を指定します。戻りコードが、CWB_OK または CWB_NOT_CONNECTED のいずれかの場合でも、存在
する接続の数は numberOfConnections に保管されます。
cwbCO_SetConnectTimeout:
cwbCO_SetConnectTimeout コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、接続の試行を放棄してエラーを戻すまでに待機
する時間 (秒単位) を指定します。
構文
UINT CWB_ENTRY cwbCO_SetConnectTimeout(
cwbCO_SysHandle
ULONG
system,
timeout );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
ULONG timeout - input
接続タイムアウト値を秒単位で指定します。この値は CWBCO_CONNECT_TIMEOUT_MIN から
CWBCO_CONNECT_TIMEOUT_MAX の範囲の値でなければなりません。あるいは、タイムアウトが
必要でない場合には、CWBCO_CONNECT_TIMEOUT_NONE を使用します。値が最小値より小さい場
52
IBM i: Windows アプリケーション・パッケージ: プログラミング
合は CWBCO_CONNECT_TIMEOUT_MIN を、値が最大値より大きい場合は
CWBCO_CONNECT_TIMEOUT_MAX を使用します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
使用法
ポリシーによりタイムアウト値が示されておらず、かつ、この API を使用して明示的に設定されていない
場合には、使用される接続タイムアウト値は CWBCO_CONNECT_TIMEOUT_DEFAULT になります。
cwbCO_SetPersistenceMode:
cwbCO_SetPersistenceMode コマンドを使用します。
目的
この関数は、サインオンが正常終了したならば、システム・オブジェクトが表すシステム (システム・オブ
ジェクトで指名) を、その属性とともに、システム・リストに追加できるかどうか (まだリストにない場合)
を設定します。
構文
UINT CWB_ENTRY cwbCO_SetPersistenceMode(
cwbCO_SysHandle
cwbCO_PersistenceMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_PersistenceMode mode - input
パーシスタンス・モードを指定します。指定できる値は以下のとおりです。
CWBCO_MAY_MAKE_PERSISTENT
指定されたシステム・オブジェクトで指名されているシステムがまだシステム・リストにない
場合は、サインオンが正常終了したならばそのシステムをリストに追加します。これによっ
て、システム・オブジェクトで定義されているシステムを、現在および将来にわたって、この
パーソナル・コンピューター上で実行されるこのアプリケーションおよびその他のアプリケー
ションが (システムがこのリストから削除されるまで) 選択できるようになります。
CWBCO_MAY_NOT_MAKE_PERSISTENT
指定されたシステム・オブジェクトで (その属性とともに) 指名されたシステムを、システ
ム・リストに追加することはできません。
プログラミング
53
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。
システム・オブジェクトで指定されたシステムが既にシステム・リストにある場合は、この設定は無効で
す。
cwbCO_Verify:
cwbCO_Verify コマンドを使用します。
目的
特定の IBM i ホスト・サービスに接続できるかどうかを検証します。
構文
UINT CWB_ENTRY cwbCO_Verify(
cwbCO_SysHandle
cwbCO_Service
cwbSV_ErrHandle
system,
service,
errorHandle );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは、接続可
能性が検証された IBM i ID です。
cwbCO_Service service - input
接続可能性がされた IBM i サービスです。有効な値は、CWBCO_SERVICE_ANY の値を除き、 95 ペ
ージの『cwbCO_Service の定義』にリストされています。すべてのサービスの接続可能性を検証する場
合は、CWBCO_SERVICE_ALL を指定します。
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
54
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_SERVICE_NAME_ERROR
サービス識別コードが無効です。
CWB_USER_TIMEOUT
システム・オブジェクトに関連した接続タイムアウト値が、接続の検証が完了する前に有効期限が
切れました。そのため、待機を停止します。
CWB_COMMUNICATIONS_ERROR
サービスへの接続を検証しようとしてエラーが起こりました。
使用法
この API ではユーザー ID とパスワードが設定されている必要はありません。また、サインオンを引き起
こすこともないため、この情報についてプロンプトを出すこともありません。いずれにせよ、システム・オ
ブジェクトの状態を変更することはありません。
指定されたサービスへの接続が既に存在している場合は、新たな接続が設定されることはなく、接続可能性
がそのサービスについて検証されたと見なされます。
CWBCO_SERVICE_ALL が検証のために指定された場合は、すべてのサービスが接続できる場合のみ、戻
りコードが CWB_OK になります。何らかの検査を行おうとして失敗した場合、他のサービスの検証が引
き続き試行されていても、戻りコードは最初に失敗したものからの戻りコードになります。
この API は使用可能な接続を確立しないため、検証が完了した場合には自動的に切断されます。したがっ
て、接続を終了させるために cwbCO_Disconnect を呼び出さないでください。
通信およびセキュリティー: セキュリティー妥当性検査とデータの API
セキュリティー妥当性検査およびデータを提供する IBM i API です。
cwbCO_ChangePassword:
cwbCO_ChangePassword コマンドを使用します。
目的
指定した IBM i ユーザーのパスワードを、指定した古い値から、指定した新しい値に変更します。この
API は、所定のシステム・オブジェクトで現在設定されているユーザー ID とパスワードは使用せず、ま
たこれらの値の変更も行いません。
プログラミング
55
構文
UINT CWB_ENTRY cwbCO_ChangePassword(
cwbCO_SysHandle
LPCSTR
LPCSTR
LPCSTR
cwbSV_ErrHandle
system,
userID,
oldPassword,
newPassword,
errorHandle);
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPCSTR userID - input
ユーザー ID が含まれている ASCIIZ ストリングを指すポインター。最大長は、NULL 終了文字を含
めて、CWBCO_MAX_USER_ID + 1 文字です。
LPCSTR oldPassword - input
旧パスワードを含むバッファーを指すポインター。最大長は、ヌル終了文字を含めて、
CWBCO_MAX_PASSWORD + 1 バイトです。
LPCSTR newPassword - input
新規パスワードを含むバッファーを指すポインター。最大長は、ヌル終了文字を含めて、
CWBCO_MAX_PASSWORD + 1 バイトです。
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
ポインター・パラメーターが NULL。
CWB_GENERAL_SECURITY_ERROR
一般セキュリティー・エラーが起こりました。ユーザー・プロファイルにパスワードがないか、パ
スワード検証プログラムがパスワードにエラーを検出しました。
CWB_INVALID_PASSWORD
新規パスワード中の 1 つまたは複数の文字が無効であるか、パスワードが長すぎます。
CWB_INVALID_USERID
ユーザー ID 中の 1 つまたは複数の文字が無効であるか、ユーザー ID が長すぎます。
CWB_UNKNOWN_USERID
与えられたユーザー ID がこのシステムでは認知されていません。
56
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_WRONG_PASSWORD
パスワードが正しくありません。
CWB_USER_PROFILE_DISABLED
このユーザー ID は使用不可になっています。
CWB_PW_TOO_LONG
新規パスワードが許容最大長を超えています。
CWB_PW_TOO_SHORT
新規パスワードが許容最小長に至っていません。
CWB_PW_REPEAT_CHARACTER
新規パスワードに 2 回以上使用された文字が含まれています。
CWB_PW_ADJACENT_DIGITS
新規パスワードでは数字同士が隣接しています。
CWB_PW_CONSECUTIVE_CHARS
新規パスワードでは、ある文字が連続して繰り返し使用されています。
CWB_PW_PREVIOUSLY_USED
新規パスワードは以前使用されています。
CWB_PW_DISALLOWED_CHAR
新規パスワードには、システムで使用禁止の文字が使用されています。
CWB_PW_NEED_NUMERIC
新規パスワードは、少なくとも 1 つの数字が含まれていなければなりません。
CWB_PW_MATCHES_OLD
新規パスワードは、1 つまたは複数の文字位置で旧パスワードと一致しています。
CWB_PW_NOT_ALLOWED
新規パスワードは、使用禁止パスワードの辞書の中に存在します。
CWB_PW_CONTAINS_USERID
新規パスワードには、パスワードの一部としてユーザー ID が含まれています。
CWB_PW_LAST_INVALID_PWD
無効なパスワードをもう一度使用すると、そのユーザー・プロファイルは使用不可になります。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
有効なパスワードの長さは、IBM i のパスワード・レベルの現在の設定によって決まります。パスワー
ド・レベル 0 および 1 では、最高 10 文字までの長さのパスワードを許可します。パスワード・レベル 2
および 3 では、最高 128 文字までの長さのパスワードを許可します。
プログラミング
57
cwbCO_GetDefaultUserMode:
cwbCO_GetDefaultUserMode コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、現在設定されているデフォルトのユーザー・モ
ードを取得します。
構文
UINT CWB_ENTRY cwbCO_GetDefaultUserMode(
cwbCO_SysHandle
cwbCO_DefaultUserMode
system,
*mode );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_DefaultUserMode * mode - output
このシステム・オブジェクトについてのデフォルトのユーザー・モードを戻します。指定できる値とそ
の意味のリストについては、cwbCO_SetDefaultUserMode の注釈を参照してください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_GetFailedSignons:
cwbCO_GetFailedSignons コマンドを使用します。
目的
セキュリティー検証の試行が、前回成功して以来、これまでに成功しなかった回数を検索します。
構文
UINT CWB_ENTRY cwbCO_GetFailedSignons(
cwbCO_SysHandle
PUSHORT
58
system,
numberFailedAttempts);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
PUSHORT numberFailedAttempts - output
失敗したログオン試行の回数が含まれる短精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
numberFailedAttempts ポインターが NULL です。
CWB_INV_BEFORE_VALIDATE
指定されたシステム・オブジェクトで設定されているユーザー ID とパスワードがまだ検証されて
いないため、この情報は利用できません。
使用法
この API を使用する前に、cwbCO_VerifyUserIDPassword、cwbCO_Signon、または cwbCO_Connect の呼び
出しに成功している必要があります。戻された値が最近のものであることを確認したい場合は、
cwbCO_VerifyUserIDPassword を明示的に呼び出すか、もしくは cwbCO_Signon または cwbCO_Connect を
呼び出す前に、Validate Mode を CWBCO_VALIDATE_ALWAYS に設定する必要があります。
cwbCO_GetPasswordExpireDate:
cwbCO_GetPasswordExpireDate コマンドを使用します。
目的
システム・オブジェクトで指定されたシステムに関して、IBM i ユーザー ID のパスワードが期限切れに
なった日時を検索します。
構文
UINT CWB_ENTRY cwbCO_GetPasswordExpireDate(
cwbCO_SysHandle
cwb_DateTime
system,
*expirationDateTime);
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_DateTime * expirationDateTime - output
現行のユーザー ID について、以下の形式により、パスワードの有効期限が切れる日時が入っている構
造を指すポインター。
プログラミング
59
バイト
内容
1 - 2
年 (例: 1998 = 0x07CF)
3
月 (1 月 = 0x01)
4
日 (1 日 = 0x01、31 日 = 0x1F)
5
時 (午前 0 時 = 0x00、23 時 = 0x17)
6
分 (0 分 = 0x00、59 分 = 0x3B)
7
秒 (0 秒 = 0x00、59 秒 = 0x3B)
8
0.01 秒 (0.00 秒 = 0x00、0.99 秒 = 0x63)
注: 1 日の最大時刻は、23 時 59 分 59.99 秒です。(午前 0 時は、次の日の 0 時 0 分 0.0 秒です。)
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
cwb_DateTime 構造を指すポインターが NULL です。
CWB_INV_BEFORE_VALIDATE
指定されたシステム・オブジェクトで設定されているユーザー ID とパスワードがまだ検証されて
いないため、パスワードの有効期限情報が利用できないか、あるいは検証が行われ、ユーザー・プ
ロファイルのパスワード有効期限の間隔が *NOMAX に設定されています。
使用法
この API を使用する前に、cwbCO_VerifyUserIDPassword、cwbCO_Signon、または cwbCO_Connect の呼び
出しに成功している必要があります。戻された値が最近のものであることを確認したい場合は、
cwbCO_VerifyUserIDPassword を明示的に呼び出すか、もしくは cwbCO_Signon または cwbCO_Connect を
呼び出す前に、Validate Mode を CWBCO_VALIDATE_ALWAYS に設定する必要があります。
ユーザー・プロファイルのパスワードの有効期限間隔が *NOMAX に設定されている場合、パスワードの
有効期限が切れる日は存在しません。この事例を検出するには、まず上記の方法でユーザー ID とパスワ
ードを検証し、検証に成功した後 cwbCO_GetPasswordExpireDate を呼び出します。
CWBCO_INV_BEFORE_VALIDATE の戻りコードは、パスワードの有効期限間隔が *NOMAX に設定され
ていることを意味します。
cwbCO_GetPrevSignonDate:
cwbCO_GetPrevSignonDate コマンドを使用します。
目的
前回の、正常終了したセキュリティー検証の日時を検索します。
60
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
UINT CWB_ENTRY cwbCO_GetPrevSignonDate(
cwbCO_SysHandle
cwb_DateTime
system,
*signonDateTime);
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_DateTime * signonDateTime - output
以下の形式で、前回に行われたサインオンの日時が入っている構造を指すポインター。
バイト
内容
1 - 2
年 (例: 1998 = 0x07CF)
3
月 (1 月 = 0x01)
4
日 (1 日 = 0x01、31 日 = 0x1F)
5
時 (午前 0 時 = 0x00、23 時 = 0x17)
6
分 (0 分 = 0x00、59 分 = 0x3B)
7
秒 (0 秒 = 0x00、59 秒 = 0x3B)
8
0.01 秒 (0.00 秒 = 0x00、0.99 秒 = 0x63)
注: 1 日の最大時刻は、23 時 59 分 59.99 秒です。(午前 0 時は、次の日の 0 時 0 分 0.0 秒です。)
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
cwb_DateTime 構造を指すポインターが NULL です。
CWB_INV_BEFORE_VALIDATE
指定されたシステム・オブジェクトで設定されているユーザー ID とパスワードがまだ検証されて
いないため、この情報は利用できません。
使用法
この API を使用する前に、cwbCO_VerifyUserIDPassword、cwbCO_Signon、または cwbCO_Connect の呼び
出しに成功している必要があります。戻された値が最近のものであることを確認したい場合は、
cwbCO_VerifyUserIDPassword を明示的に呼び出すか、もしくは cwbCO_Signon または cwbCO_Connect を
呼び出す前に、Validate Mode を CWBCO_VALIDATE_ALWAYS に設定する必要があります。
cwbCO_GetPromptMode:
cwbCO_GetPromptMode コマンドを使用します。
プログラミング
61
目的
この関数は、指定されたシステム・オブジェクトについて、現在、設定されているプロンプト・モードを取
得します。
構文
UINT CWB_ENTRY cwbCO_GetPromptMode(
cwbCO_SysHandle
cwbCO_PromptMode
system,
*mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_PromptMode * mode - output
プロンプト・モードを戻します。指定できる値とその意味については、cwbCO_SetPromptMode の注釈
を参照してください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_GetSignonDate:
cwbCO_GetSignonDate コマンドを使用します。
目的
現行の、正常終了したセキュリティー検証の日時を検索します。
構文
UINT CWB_ENTRY cwbCO_GetSignonDate(
cwbCO_SysHandle
cwb_DateTime
system,
*signonDateTime);
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
62
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwb_DateTime * signonDateTime - output
以下の形式で、現行のサインオンが行われた日時が入っている構造を指すポインター。
バイト
内容
1 - 2
年 (例: 1998 = 0x07CF)
3
月 (1 月 = 0x01)
4
日 (1 日 = 0x01、31 日 = 0x1F)
5
時 (午前 0 時 = 0x00、23 時 = 0x17)
6
分 (0 分 = 0x00、59 分 = 0x3B)
7
秒 (0 秒 = 0x00、59 秒 = 0x3B)
8
0.01 秒 (0.00 秒 = 0x00、0.99 秒 = 0x63)
注: 1 日の最大時刻は、23 時 59 分 59.99 秒です。(午前 0 時は、次の日の 0 時 0 分 0.0 秒です。)
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
cwb_DateTime 構造を指すポインターが NULL です。
CWB_INV_BEFORE_VALIDATE
指定されたシステム・オブジェクトで設定されているユーザー ID とパスワードがまだ検証されて
いないため、この情報は利用できません。
使用法
この API を使用する前に、cwbCO_VerifyUserIDPassword、cwbCO_Signon、または cwbCO_Connect の呼び
出しに成功している必要があります。戻された値が最近のものであることを確認したい場合は、
cwbCO_VerifyUserIDPassword を明示的に呼び出すか、もしくは cwbCO_Signon または cwbCO_Connect を
呼び出す前に、Validate Mode を CWBCO_VALIDATE_ALWAYS に設定する必要があります。
cwbCO_GetUserIDEx:
cwbCO_GetUserIDEx コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトに関連したユーザー ID を取得します。このユーザー ID
は、IBM i 接続に使用されます。
構文
UINT CWB_ENTRY cwbCO_GetUserIDEx(
cwbCO_SysHandle
LPSTR
PULONG
system,
userID,
length );
プログラミング
63
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPSTR userID - output
NULL で終わるユーザー ID が含まれているバッファーを指すポインター。ユーザー ID の長さは、
最大で CWBCO_MAX_USER_ID 文字になります。
PULONG length - input/output
ユーザー ID バッファーの長さを指すポインター。バッファーが、終了の NULL のスペースを含め
て、ユーザー ID を含めるには小さすぎる場合は、必要とするバッファーのサイズがこのパラメーター
に入れられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
渡されたポインター・パラメーターのいずれかが NULL です。
CWB_BUFFER_OVERFLOW
ユーザー ID バッファーが、ユーザー ID 全体を保持するには十分な大きさではありません。
使用法
IBM i のユーザー ID は、すでに検証されている場合もありますし、未検証の場合もあります。検証済み
であることを確認するためには、この API を呼び出す前に、 cwbCO_Signon または cwbCO_Connect を呼
び出します。
ユーザー ID が設定されておらず、システム・オブジェクトへのサインオンが行われていない場合に戻さ
れるユーザー ID は、IBM i のデフォルトのユーザー ID が構成済みであっても、空ストリングになりま
す。
cwbCO_GetValidateMode:
cwbCO_GetValidateMode コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、現在、設定されている検証モードを取得しま
す。
構文
UINT CWB_ENTRY cwbCO_GetValidateMode(
cwbCO_SysHandle
cwbCO_ValidateMode
64
system,
*mode );
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_ValidateMode * mode - output
検証モードを戻します。指定できる値とその意味については、cwbCO_SetValidateMode の注釈を参照し
てください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_GetWindowHandle:
cwbCO_GetWindowHandle コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、現在、関連付けられているウィンドウ・ハンド
ルがあれば、それを取得します。
構文
UINT CWB_ENTRY cwbCO_GetWindowHandle(
cwbCO_SysHandle
HWND
system,
*windowHandle );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
HWND * pWindowHandle - output
システム・オブジェクトに関連したウィンドウ・ハンドルを戻します。あるいは、それに関連したウィ
ンドウ・ハンドルが無い場合は、NULL を戻します。
戻りコード
以下は、共通の戻り値です。
プログラミング
65
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
windowHandle ポインターが NULL です。
使用法
なし
cwbCO_HasSignedOn:
cwbCO_HasSignedOn コマンドを使用します。
目的
指定されたシステム・オブジェクトが、「サインオン」されたかどうか (ユーザー ID とパスワードが、指
定されたシステム・オブジェクトの存続期間内のある時点で検証されたかどうか) の指示を戻します。
構文
UINT CWB_ENTRY cwbCO_HasSignedOn(
cwbCO_SysHandle
cwb_Boolean
system,
*signedOn );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean * signedOn - output
「サインオンの有無」の指示が保管されている cwb_Boolean を指すポインター。指定されたシステ
ム・オブジェクトがサインオンされている場合は、これは CWB_TRUE に設定され、そうでない場合
は CWB_FALSE に設定されます。 (エラーの場合は、同じく CWB_FALSE に設定されます。)
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
signedOn ポインターが NULL です。
使用法
戻された CWB_TRUE の指示は、ユーザー ID とパスワードがある一定時間枠内に検証されたことを意味
するものではなく、システム・オブジェクトの作成以降にサインオンが行われたということを意味している
に過ぎません。このようなサインオンによって、IBM i 接続やセキュリティー検証フローが発生すること
66
IBM i: Windows アプリケーション・パッケージ: プログラミング
はなく、これらが組み込まれることもありません。このことは、次のことを意味しています。すなわち、た
とえ CWB_TRUE が戻された場合でも、正常なサインオンを必要とするシステム・オブジェクトに対して
次回に呼び出しを行うと、接続を行い、ユーザー ID とパスワードを再度、検証しようとする可能性があ
り、さらにその検証、したがってサインオンは、失敗する可能性があるということです。 signedOn 標識
は、最新のユーザー ID とパスワードの検証結果を反映しています。ユーザー ID とパスワードの検証 (サ
インオン) が、ある時点では成功していたとしても、その時点以降に検証が失敗すれば、signedOn は
CWB_FALSE に設定されます。
cwbCO_SetDefaultUserMode:
cwbCO_SetDefaultUserMode コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、構成済みのデフォルトのユーザー ID に関し
て動作を設定します。
構文
UINT CWB_ENTRY cwbCO_SetDefaultUserMode(
cwbCO_SysHandle
cwbCO_DefaultUserMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_DefaultUserMode mode - input
デフォルトのユーザー ID について行うことを指定します。指定できる値は以下のとおりです。
CWBCO_DEFAULT_USER_MODE_NOT_SET
現在、デフォルトのユーザー・モードは使用されていません。このモードが活動中で、かつプ
ロンプト・モード設定でプロンプトを禁止していない場合は、それ以降は残りのデフォルトの
ユーザー・モードのいずれを使用するのか、サインオン時または接続時にプロンプトが出され
ます。これらの他のモード値のうちのいずれか 1 つが選択されるまでは、サインオンまたは接
続を成功させることはできません。デフォルトのユーザー・モードの設定をこの値に戻すと、
次回 System Access がデフォルトのユーザー ID を必要とするときに、プロンプトが出されま
す。
CWBCO_DEFAULT_USER_USE
明示的に (cwbCO_SetUserIDEx を使用して) 設定されたユーザー ID がない場合にサインオン
を行うには、IBM i 用に構成されているデフォルトのユーザー ID を、システム・オブジェク
トで指定されたとおりに使用します。
CWBCO_DEFAULT_USER_IGNORE
デフォルトのユーザー ID を絶対に使用しないことを指定します。サインオンが生じたのに、
このシステム・オブジェクト・インスタンス用にユーザー ID が明示的に設定されていない場
合は、プロンプト・モードで許可されていれば (cwbCO_SetPromptMode の注釈参照)、ユーザ
ー ID を入力するようにプロンプトが出されます。なお、プロンプトにはこのユーザー ID の
初期値は入っていません。
プログラミング
67
CWBCO_DEFAULT_USER_USEWINLOGON
このシステム・オブジェクトについて、明示的にユーザー ID が (cwbCO_SetUserIDEx を使用
して) 設定されていない場合は、 Windows へログオンしたときに使用したユーザー ID がデ
フォルトとして使用されます。
CWBCO_DEFAULT_USER_USE_KERBEROS
このシステム・オブジェクトについて、明示的にユーザー ID が (cwbCO_SetUserIDEx を使用
して) 設定されていない場合には、 Windows ドメインにログオンした際に作成された
Kerberos プリンシパルがデフォルト値として使用されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
CWB_KERB_NOT_AVAILABLE
このバージョンの Windows では、Kerberos セキュリティー・パッケージは利用できません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。ユーザー ID が
cwbCO_SetUserIDEx API で明示的に設定された場合には、この API で設定されたデフォルトのユーザ
ー・モードは無視されます。
Kerberos をサポートしない Windows プラットフォームで CWBCO_DEFAULT_USER_USE_KERBEROS を
設定しようとした場合には、エラー・コード CWB_KERB_NOT_AVAILABLE が戻されます。
cwbCO_SetPassword:
cwbCO_SetPassword コマンドを使用します。
目的
この関数は、パスワードを設定して、指定されたシステム・オブジェクトに関連付けます。 cwbCO_Signon
呼び出しまたは cwbCO_Connect 呼び出しを使用して IBM i に接続する場合や、cwbCO_SetUserIDEx 呼び
出しを使用してユーザー ID を設定する場合に、このパスワードが使用されます。
68
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
UINT CWB_ENTRY cwbCO_SetPassword(
cwbCO_SysHandle
LPCSTR
system,
password );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPCSTR password - input
NULL で終わるパスワードが含まれているバッファーを指すポインター。最大長は、NULL 終了文字
を含めて、CWBCO_MAX_PASSWORD + 1 バイトです。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
パスワード・ポインターが NULL です。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。この API で設定されたパス
ワードは、対応するユーザー ID が cwbCO_SetUserIDEx を使用して設定されていない場合には、使用され
ません。
有効なパスワードの長さは、IBM i のパスワード・レベルの現在の設定によって決まります。パスワー
ド・レベル 0 および 1 では、最高 10 文字までの長さのパスワードを許可します。パスワード・レベル 2
および 3 では、最高 128 文字までの長さのパスワードを許可します。
cwbCO_SetPromptMode:
cwbCO_SetPromptMode コマンドを使用します。
プログラミング
69
目的
この関数は、指定されたシステム・オブジェクトについて、プロンプト・モードを設定します。これは、サ
インオンを行うときにユーザー ID とパスワードまたはその他の情報のプロンプトをユーザーに出すかど
うか、さらにいつ出すかについて指定するものです。
構文
UINT CWB_ENTRY cwbCO_SetPromptMode(
cwbCO_SysHandle
cwbCO_PromptMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_PromptMode - input
プロンプト・モードを指定します。指定できる値は以下のとおりです。
CWBCO_PROMPT_IF_NECESSARY
ユーザー ID またはパスワードのいずれかが明示的に設定されていないか、またはこのシステ
ムの永続的構成、パスワード・キャッシュ (使用可能な場合) などといった方法を使っても検
索できない場合に、プロンプトが出されます。
デフォルトのユーザー・モードが設定されており、デフォルトのユーザー ID を求める IBM i
プロンプトがまだ出されていない場合、cwbCO_Connect または cwbCO_Signon の実行時に
IBM i がこのプロンプトを出します。
CWBCO_PROMPT_ALWAYS
指定したシステム・オブジェクトにサインオンが行われるたびに (たとえ、同じシステムに対
する同じユーザー ID を使用した IBM i サインオンが、異なるシステム・オブジェクトを使
用して正常に行われた場合であっても)、必ずプロンプトが出されます。サインオンは 1 つの
システム・オブジェクトについて一度しか行わないため、このことは、システム・オブジェク
トごとに、厳密に 1 回のプロンプトが行われることを意味しています。明示的な追加のサイン
オン呼び出しを行っても、(プロンプトも含めて) なにも実行されません。下記の使用法に記載
されている、このモードを使用する際の 2 つの例外を参照してください。
CWBCO_PROMPT_NEVER
ユーザー ID およびパスワード、あるいはデフォルトのユーザー ID に関するプロンプトが出
されなくなります。このモードを使用すると、ユーザー ID またはパスワードのいずれかが設
定されておらず、 (IBM i パスワード・キャッシュから) プログラマチックに検索できない場
合には、実行にサインオンが必要な API (例えば、cwbCO_Signon または cwbCO_Connect) に
対する呼び出しは、いずれも失敗することになります。このモードは、以下のいずれかの場合
に使用します。
v 無人の PC、または何らかの理由によりエンド・ユーザーとの対話をサポートできない PC
で、製品が実行されている場合。
v ユーザー ID とパスワードについて、アプリケーション自体でプロンプトを出しているか、
その他の方法でアプリケーションが取り出しており、さらに cwbCO_SetUserIDEx および
cwbCO_SetPassword を使用して明示的に設定している場合。
70
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。プロンプト・モードを
CWBCO_PROMPT_ALWAYS に設定しても、以下の 2 つのケースではプロンプトが出されません。
v ユーザー ID とパスワードが、cwbCO_setUserIDEx および cwbCO_SetPassword API を使用して明示的
に設定されている。
v Windows ログオン情報 (CWBCO_DEFAULT_USER_USEWINLOGON) の使用が、
cwbCO_SetDefaultUserMode API を使用して設定されている。
cwbCO_SetUserIDEx:
cwbCO_SetUserIDEx コマンドを使用します。
目的
この関数は、ユーザー ID を設定して、指定されたシステム・オブジェクトに関連付けます。
cwbCO_Signon 呼び出しまたは cwbCO_Connect 呼び出しのいずれかを使用する IBM i 接続で、このユー
ザー ID が使用されます。
構文
UINT CWB_ENTRY cwbCO_SetUserIDEx(
cwbCO_SysHandle
LPCSTR
system,
userID );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
プログラミング
71
LPCSTR userID - input
NULL で終わるユーザー ID が入っているバッファーを指すポインター。ユーザー ID は、終了の
NULL 文字を含まずに、CWBCO_MAX_USER_ID 文字よりも長くなってはなりません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
ユーザー ID ポインターが NULL です。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。この API を使用してユーザ
ー ID を明示的に設定すると、cwbCO_SetDefaultUserMode API を使用して設定されたデフォルトのユーザ
ー・モードは、いずれも無視されます。
cwbCO_SetWindowHandle:
cwbCO_SetWindowHandle コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、システム・オブジェクトに関連する何らかのプ
ロンプト (例えば、ユーザー ID とパスワードについてのプロンプト) が出される場合に、使用するウィン
ドウ・ハンドルを設定します。そのように設定された場合 (NULL ではないウィンドウ・ハンドルに対し
て)、このプロンプトはメインのアプリケーション・ウィンドウに対して「モーダル」で表示されるため、
そのウィンドウの下に隠れてしまうことはありません。
構文
UINT CWB_ENTRY cwbCO_SetWindowHandle(
cwbCO_SysHandle
HWND
system,
windowHandle );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
72
IBM i: Windows アプリケーション・パッケージ: プログラミング
HWND windowHandle - input
システム・オブジェクトに関連付けるウィンドウ・ハンドルを指定します。 NULL の場合は、ウィン
ドウ・ハンドルはシステム・オブジェクトに関連付けられません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
使用法
この API は、指定されたシステム・オブジェクトのウィンドウ・ハンドルを変更するために、たとえサイ
ンオンが正常に行われた後であっても、いつでも使用することができます。
cwbCO_SetValidateMode:
cwbCO_SetValidateMode コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、検証モードを設定します。このモードは、ユー
ザー ID とパスワードを検証する際に、動作に影響を与えます。
構文
UINT CWB_ENTRY cwbCO_SetValidateMode(
cwbCO_SysHandle
cwbCO_ValidateMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_ValidateMode mode - input
検証モードを指定します。指定できる値は以下のとおりです。
CWBCO_VALIDATE_IF_NECESSARY
この PC から過去 24 時間以内に行われた IBM i ユーザー ID の検証が成功している場合、
その最新の検証結果を使用し、この時点での検証には接続しません。別のシナリオで再検証を
行う場合もあります。必要に応じて、再検証が行われます。
CWBCO_VALIDATE_ALWAYS
この検証が要求される (必要とされる) ごとに、ユーザー ID とパスワードを検証するための
IBM i 通信が行われます。このモードを設定すると、強制的に検証が行われます (システム・
オブジェクトがまだサインオンされていない場合)。システム・オブジェクトがサインオンされ
てしまうと、この設定は無視されます。
プログラミング
73
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。
cwbCO_Signon:
cwbCO_Signon コマンドを使用します。
目的
ユーザー ID とパスワードを使用して、IBM i 指定のオブジェクトで表されるシステムに、ユーザーをサ
インオンさせます。
注: cwbCO_Signon API に誤ったパスワードを渡した場合は、指定されたユーザーの無効サインオン試行カ
ウンターが増やされます。無効なパスワードをホストにあまり多く送信すると、そのユーザー・プロファイ
ルは使用できなくなります。
構文
UINT CWB_ENTRY cwbCO_Signon(
cwbCO_SysHandle
cwbSV_ErrHandle
system,
errorHandle );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
74
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_UNKNOWN_USERID
与えられたユーザー ID がこのシステムでは認知されていません。
CWB_WRONG_PASSWORD
パスワードが正しくありません。
CWB_PASSWORD_EXPIRED
パスワードの有効期限切れ。
CWB_USER_PROFILE_DISABLED
このユーザー ID は使用不可になっています。
CWB_INVALID_PASSWORD
パスワード中の 1 つまたは複数の文字が無効であるか、パスワードが長すぎます。
CWB_INVALID_USERID
ユーザー ID 中の 1 つまたは複数の文字が無効であるか、ユーザー ID が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
CWB_USER_CANCELLED
ユーザーがサインオン処理を取り消しました。
その他の共通の戻りコードが、サインオン・サーバーへ接続しようとして失敗した結果として戻されること
がよくあります。そのような戻りコードのリストについては、cwbCO_Connect の注釈を参照してくださ
い。
使用法
ユーザー検証時に IBM i がユーザーのパスワードを求めるプロンプトと、実際に IBM i への問い合わせ
を行うプロンプトを出すかどうかは、いずれも現行のシステム・オブジェクトの設定 (ユーザー ID、パス
ワード、プロンプト・モード、デフォルトのユーザー・モード、検証モードなど) に左右されます。詳細に
ついては、これらの属性の取得と設定についての API の宣言を参照してください。指定のシステム・オブ
ジェクトの IBM i 名がシステム・リストに存在しない場合、システム・オブジェクトのパーシスタンス・
モードが適切に設定されていれば、cwbCO_Connect または cwbCO_Signon の最初の呼び出しが正常に行わ
れた際に、このシステム・オブジェクトの IBM i 名がシステム・リストに追加されます。
パーシスタンス・モードの詳細については、cwbCO_SetPersistenceMode の注釈を参照してください。呼び
出しが正常に行われて、IBM i のパスワード・キャッシングが使用可能になっている場合、パスワードが
結果のユーザー ID 用パスワードとして、PC の IBM i パスワード・キャッシュに保管されます。
以下の項も参照してください。
v
95 ページの『cwbCO_Signon と cwbCO_VerifyUserIDPassword の相違点』
プログラミング
75
v
96 ページの『cwbCO_Signon と cwbCO_VerifyUserIDPassword の類似点』
関連資料:
39 ページの『システム・オブジェクトの属性』
IBM i プラットフォームにおけるシステム・オブジェクトの属性は、システム・オブジェクトが表すシス
テムへのサインオンおよび通信の動作に影響します。
cwbCO_VerifyUserIDPassword:
cwbCO_VerifyUserIDPassword コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトで表されるシステムの IBM i ユーザー ID およびパスワード
の正確さを検証します。ユーザー ID とパスワードが正しい場合は、この関数は、サインオンの試行とパ
スワードの有効期限に関するデータも検索します。
注: cwbCO_VerifyUserIDPassword API に誤ったパスワードを渡した場合は、指定されたユーザーの無効サ
インオン試行カウンターが増やされます。無効なパスワードをホストにあまり多く送信すると、そのユーザ
ー・プロファイルは使用できなくなります。
構文
UINT CWB_ENTRY cwbCO_VerifyUserIDPassword(
cwbCO_SysHandle
LPCSTR
LPCSTR
cwbSV_ErrHandle
system,
userID,
password,
errorHandle );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPCSTR userID - input
NULL で終わるユーザー ID が含まれているバッファーを指すポインター。これは、終了の NULL を
含めずに、長さが CWBCO_MAX_USER_ID 文字を超えてはなりません。
LPCSTR password - input
NULL で終わるパスワードが含まれているバッファーを指すポインター。最大長は、NULL 終了文字
を含めて、CWBCO_MAX_PASSWORD + 1 バイトです。
cwbSV_ErrHandle errorHandle - input/output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合、または errorHandle が無効な
場合は、メッセージは検索されません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
76
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
API に与えられたポインターが無効。
CWB_UNKNOWN_USERID
与えられたユーザー ID がこのシステムでは認知されていません。
CWB_WRONG_PASSWORD
パスワードが正しくありません。
CWB_PASSWORD_EXPIRED
パスワードの有効期限切れ。
CWB_USER_PROFILE_DISABLED
このユーザー ID は使用不可になっています。
CWB_INVALID_PASSWORD
パスワード中の 1 つまたは複数の文字が無効であるか、パスワードが長すぎます。
CWB_INVALID_USERID
ユーザー ID 中の 1 つまたは複数の文字が無効であるか、ユーザー ID が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
有効なパスワードの長さは、IBM i のパスワード・レベルの現在の設定によって決まります。パスワー
ド・レベル 0 および 1 では、最高 10 文字までの長さのパスワードを許可します。パスワード・レベル 2
および 3 では、最高 128 文字までの長さのパスワードを許可します。
95 ページの『cwbCO_Signon と cwbCO_VerifyUserIDPassword の相違点』および 96 ページの
『cwbCO_Signon と cwbCO_VerifyUserIDPassword の類似点』を参照してください。
通信およびセキュリティー: 属性取得および属性設定の API
この製品の API を使用して、他のシステム・オブジェクトの属性を取得および設定したり、属性がポリシ
ーで制限されているかどうかを判別したりします。
cwbCO_CanModifyDefaultUserMode:
cwbCO_CanModifyDefaultUserMode コマンドを使用します。
目的
指定されたシステム・オブジェクトのデフォルトのユーザー・モードが変更可能であるかどうかを示しま
す。
構文
UINT CWB_ENTRY cwbCO_CanModifyDefaultUserMode(
cwbCO_SysHandle
cwb_Boolean
system,
*canModify );
プログラミング
77
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean *canModify - output
このモードが変更可能であれば CWB_TRUE に設定し、そうでない場合は CWB_FALSE に設定しま
す。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。この API から戻された結果が正しいのは、呼び出し時点の
みです。
ポリシー設定が変更されるか、このシステム・オブジェクトを使用したサインオンや接続が行われた場合に
は、この API の結果は誤ったものになる可能性があります。特にマルチスレッドのアプリケーションの場
合、この点を考慮に入れて、対処する必要があります。
cwbCO_CanModifyIPAddress:
cwbCO_CanModifyIPAddress コマンドを使用します。
目的
接続に使用される IP アドレスがこのシステム・オブジェクト用に変更可能であるかどうかを示します。
構文
UINT CWB_ENTRY cwbCO_CanModifyIPAddress(
cwbCO_SysHandle
cwb_Boolean
system,
*canModify );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
78
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwb_Boolean *canModify - output
IP アドレスが変更可能であれば CWB_TRUE に設定し、そうでない場合は CWB_FALSE に設定しま
す。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。 IP アドレス・ルックアップ・モードが
CWBCO_IPADDR_LOOKUP_NEVER ではなく、ポリシー設定で IP アドレス・ルックアップ・モードの変
更が禁止されている場合は、この値は変更できません。そのケースでは、canModify は CWB_FALSE に設
定されます。この API から戻された結果が正しいのは、呼び出し時点のみです。ポリシー設定が変更され
るか、このシステム・オブジェクトを使用したサインオンや接続が行われた場合には、この API の結果は
誤ったものになる可能性があります。特にマルチスレッドのアプリケーションの場合、この点を考慮に入れ
て、対処する必要があります。
cwbCO_CanModifyIPAddressLookupMode:
cwbCO_CanModifyIPAddressLookupMode コマンドを使用します。
目的
IP アドレス・ルックアップ・モードがこのシステム・オブジェクト用に変更可能であるかどうかを示しま
す。
構文
UINT CWB_ENTRY cwbCO_CanModifyIPAddressLookupMode(
cwbCO_SysHandle
system,
cwb_Boolean
*canModify );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean *canModify - output
このモードが変更可能であれば CWB_TRUE に設定し、そうでない場合は CWB_FALSE に設定しま
す。
プログラミング
79
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。この API から戻された結果が正しいのは、呼び出し時点の
みです。
ポリシー設定が変更されるか、このシステム・オブジェクトを使用したサインオンや接続が行われた場合に
は、この API の結果は誤ったものになる可能性があります。特にマルチスレッドのアプリケーションの場
合、この点を考慮に入れて、対処する必要があります。
cwbCO_CanModifyPersistenceMode:
cwbCO_CanModifyPersistenceMode コマンドを使用します。
目的
指定されたシステム・オブジェクトのパーシスタンス・モードが変更可能であるかどうかを示します。
構文
UINT CWB_ENTRY cwbCO_CanModifyPersistenceMode(
cwbCO_SysHandle
cwb_Boolean
system,
*canModify );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean *canModify - output
このモードが変更可能であれば CWB_TRUE に設定し、そうでない場合は CWB_FALSE に設定しま
す。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
80
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。この API から戻された結果が正しいのは、呼び出し時点の
みです。ポリシー設定が変更されるか、このシステム・オブジェクトを使用したサインオンや接続が行われ
た場合には、この API の結果は誤ったものになる可能性があります。特にマルチスレッドのアプリケーシ
ョンの場合、この点を考慮に入れて、対処する必要があります。
cwbCO_CanModifyPortLookupMode:
cwbCO_CanModifyPortLookupMode コマンドを使用します。
目的
指定されたシステム・オブジェクトのポート・ルックアップ・モードが変更可能であるかどうかを示しま
す。
構文
UINT CWB_ENTRY cwbCO_CanModifyPortLookupMode(
cwbCO_SysHandle
cwb_Boolean
system,
*canModify );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean *canModify - output
このモードが変更可能であれば CWB_TRUE に設定し、そうでない場合は CWB_FALSE に設定しま
す。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。この API から戻された結果が正しいのは、呼び出し時点の
プログラミング
81
みです。ポリシー設定が変更されるか、このシステム・オブジェクトを使用したサインオンや接続が行われ
た場合には、この API の結果は誤ったものになる可能性があります。特にマルチスレッドのアプリケーシ
ョンの場合、この点を考慮に入れて、対処する必要があります。
cwbCO_CanModifyUseSecureSockets:
cwbCO_CanModifyUseSecureSockets コマンドを使用します。
目的
セキュア・ソケット使用の設定値がこのシステム・オブジェクト用に変更可能であるかどうかを示します。
構文
UINT CWB_ENTRY cwbCO_CanModifyUseSecureSockets(
cwbCO_SysHandle
cwb_Boolean
system,
*canModify );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean *canModify - output
セキュア・ソケット使用設定値が変更可能であれば CWB_TRUE に設定し、そうでない場合は
CWB_FALSE に設定します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
canModify ポインターが NULL です。
使用法
ポリシー設定で変更を禁止している場合、あるいは指定されたシステム・オブジェクトを使用しているサイ
ンオンまたは接続が既に成功している場合には、この値は変更できません。これらのケースでは、
canModify は CWB_FALSE に設定されます。この API から戻された結果が正しいのは、呼び出し時点の
みです。ポリシー設定が変更されるか、このシステム・オブジェクトを使用したサインオンや接続が行われ
た場合には、この API の結果は誤ったものになる可能性があります。特にマルチスレッドのアプリケーシ
ョンの場合、この点を考慮に入れて、対処する必要があります。
cwbCO_GetDescription:
cwbCO_GetDescription コマンドを使用します。
82
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
この関数は、指定されたシステム・オブジェクトに関連したテキスト記述を取得します。
構文
UINT CWB_ENTRY cwbCO_GetDescription(
cwbCO_SysHandle
LPSTR
PULONG
system,
description,
length );
パラメーター
cwbCO_SysHandle system - input
以前に、cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPSTR description - output
NULL で終わる記述が含まれているバッファーを指すポインター。記述の長さは、終了文字の NULL
を含まずに、最大 CWBCO_MAX_SYS_DESCRIPTION 文字までです。
PULONG length - input/output
記述バッファーの長さを指すポインター。バッファーが、終了文字の NULL のスペースを含めて、記
述を含めるためには小さすぎる場合は、必要とするバッファーのサイズがこのパラメーターに入れられ
ます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
渡されたポインター・パラメーターのいずれかが NULL です。
CWB_BUFFER_OVERFLOW
記述バッファーが、記述全体を保持するには十分な大きさではありません。
cwbCO_GetHostCCSID:
cwbCO_GetHostCCSID コマンドを使用します。
目的
システム・オブジェクト内のユーザー ID によって表される、IBM i に関連付けられた CCSID のうち、
システムへのサインオンが行われたときに使用中だったものを戻します。
構文
UINT CWB_ENTRY cwbCO_GetHostCCSID(
cwbCO_SysHandle
PULONG
system,
pCCSID );
プログラミング
83
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
PULONG pCCSID - output
成功すれば、ホスト CCSID はここへコピーされます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
CCSID ポインターが NULL です。
CWB_DEFAULT_HOST_CCSID_USED
この API は、システム・オブジェクトに設定されているユーザー ID に適切なホスト CCSID を
判別できないため、ホスト CCSID 500 が戻されます。
CWB_USER_TIMEOUT
CWB_SSL_JAVA_ERROR
CWB_USER_TIMEOUT_SENDRCV
使用法
この API は、関連する CCSID 値を検索するのに、ホスト・システムへの活動接続を行わず、またそれが
必要でもありません。しかしながら、この検索は、指定されたシステム・オブジェクトで設定されているも
のと同じユーザー ID を使用することによって、前回成功したホスト・システムへの接続に依存していま
す。これは、IBM i のデフォルト CCSID ではなく、特定のユーザー・プロファイルの CCSID が戻され
るためです。ユーザー ID を必要とせずにホスト CCSID を検索するには、cwbNL_GetHostCCSID を呼び
出します。
cwbCO_GetHostVersionEx:
cwbCO_GetHostVersionEx コマンドを使用します。
目的
ホストのバージョンとリリース・レベルを取得します。
構文
UINT CWB_ENTRY cwbCO_GetHostVersionEx(
cwbCO_SysHandle
PULONG
PULONG
84
system,
version,
release);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
PULONG version - output
システムのバージョン・レベルが戻されるバッファーを指すポインター。
PULONG release - output
システムのリリース・レベルが戻されるバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_CONNECTED
現在活動中である環境の使用中に、このシステムは一度も接続されていません。
CWB_INVALID_POINTER
渡されたポインターの 1 つが NULL です。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
使用法
IBM i 接続が行われると必ず、ホストのバージョンが検索され、保管されます。現在活動中の環境に IBM
i 接続が存在しない場合、この情報は使用できず、エラー・コード CWB_NOT_CONNECTED が戻されま
す。 IBM i への接続が正常に完了したことが分かっている場合は、戻されたバージョンとリリース・レベ
ルはおそらく現行のものになります。この値が使用可能であり、最近検索されたものであることを確認した
い場合は、このシステム・オブジェクトの cwbCO_Signon または cwbCO_Connect を最初に呼び出し、そ
の後、cwbCO_GetHostVersionEx を呼び出します。
cwbCO_GetIPAddress:
cwbCO_GetIPAddress コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトによって表される、IBM i の IP アドレスを取得します。こ
の IP アドレスは、IBM i 接続で使用されていた (あるいは、cwbCO_SetIPAddress を使用するなどの方法
で設定された) ものであり、指定のシステム・オブジェクトを使用する場合に、今後の接続用に使用されま
す。
構文
UINT CWB_ENTRY cwbCO_GetIPAddress(
cwbCO_SysHandle
LPSTR
PULONG
system,
IPAddress,
length );
プログラミング
85
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPSTR IPAddress - output
ドット表記法 ("nnn.nnn.nnn.nnn" の形式、ここでそれぞれの "nnn" は 0 から 255 までの範囲) で表し
た NULL で終わる IP アドレスが含まれているバッファーを指すポインター。
PULONG length - input/output
IPAddress バッファーの長さを指すポインター。バッファーが、終了の NULL のスペースを含めて、
出力を入れるには小さすぎる場合は、必要とするバッファーのサイズがこのパラメーターに入れられ、
CWB_BUFFER_OVERFLOW が戻されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
入力ポインターの 1 つが NULL です。
CWB_BUFFER_OVERFLOW
IPAddress バッファーが、IPAddress のストリング全体を含めるには十分な大きさではありません。
使用法
なし
cwbCO_GetIPAddressLookupMode:
cwbCO_GetIPAddressLookupMode コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトによって表される IBM i IP アドレスが動的にルックアップ
される場合、そのルックアップがいつ行われるかを示す指示を取得します。
構文
UINT CWB_ENTRY cwbCO_GetIPAddressLookupMode(
cwbCO_SysHandle
cwbCO_IPAddressLookupMode
system,
*mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
86
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbCO_IPAddressLookupMode * mode - output
現在、使用中の IP アドレス・ルックアップ・モードを戻します。指定できる値とその意味について
は、 91 ページの『cwbCO_SetIPAddressLookupMode』の注釈を参照してください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_GetPortLookupMode:
cwbCO_GetPortLookupMode コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトに関して、IBM i のサービス接続を確立するためにホスト・
サービス・ポートが必要になったときに、これらのポートをルックアップするモードや方式を取得します。
構文
UINT CWB_ENTRY cwbCO_GetPortLookupMode(
cwbCO_SysHandle
cwbCO_PortLookupMode
system,
*mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_PortLookupMode * mode - output
ホスト・サービス・ポートのルックアップ・モードを戻します。指定できる値とその意味については、
cwbCO_SetPortLookupMode の注釈を参照してください。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
プログラミング
87
CWB_INVALID_POINTER
モード・ポインターが NULL です。
使用法
なし
cwbCO_GetSystemName:
cwbCO_GetSystemName コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトに関連付けられた IBM i 名を取得します。
構文
UINT CWB_ENTRY cwbCO_GetSystemName(
cwbCO_SysHandle
LPSTR
PULONG
system,
sysName,
length );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPSTR sysName - output
NULL で終わるシステム名が含まれるバッファーを指すポインター。名前の長さは、終了の NULL を
含まずに、最大で、CWBCO_MAX_SYS_NAME 文字になります。
PULONG length - input/output
sysName バッファーの長さを指すポインター。バッファーが、終了の NULL のスペースを含めて、シ
ステム名を含めるには小さすぎる場合は、必要とするバッファーのサイズがこのパラメーターに入れら
れ、 CWB_BUFFER_OVERFLOW が戻されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
渡されたポインター・パラメーターのいずれかが NULL です。
CWB_BUFFER_OVERFLOW
sysName バッファーが、システム名全体を保持するには十分な大きさではありません。
使用法
なし
88
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbCO_IsSecureSockets:
cwbCO_IsSecureSockets コマンドを使用します。
目的
この関数は、(指定されたシステム・オブジェクトについて) セキュア・ソケットが使用されているかどう
か (接続されている場合)、あるいはセキュア・ソケットを使用して接続しようとしているかどうか (現在は
接続されていない場合) についての情報を取得します。
構文
UINT CWB_ENTRY cwbCO_IsSecureSockets(
cwbCO_SysHandle
cwb_Boolean
system,
*inUse );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwb_Boolean * inUse - output
IBM i Access が通信にセキュア・ソケットを使用しているかどうか (または使用しようとしているか
どうか) の情報を戻します。
CWB_TRUE
接続が活動中である場合、現在使用中、あるいは使用する予定です。
CWB_FALSE
使用中ではなく、今後も使用する予定はありません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
inUse ポインターが NULL です。
使用法
このフラグは、今後の通信に関して試行する内容を示しています。 CWB_TRUE が戻される場合、IBM i
の通信に対する試みのうち、セキュア・ソケットを使用して実行できないものは、すべて失敗します。
SSL が使用されている場合、製品は Federal Information Processing Standards (FIPS) 準拠を (一定の制限付
きで) 強制しますが、この API では、FIPS 準拠がオンかオフかについては戻されません。 FIPS 準拠がオ
ンかオフかを確認する唯一の方法は、プロパティーの FIPS 準拠のチェック・ボックスを確認することで
す。 FIPS とその使用法について詳しくは、本製品と共にインストールされる「ユーザーズ・ガイド」を参
照してください。
プログラミング
89
cwbCO_SetIPAddress:
cwbCO_SetIPAddress コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトに、IBM i 接続で使用される IP アドレスを設定します。ま
た、この関数は、システム・オブジェクトの IP アドレス・ルックアップ・モードを
CWBCO_IPADDR_LOOKUP_NEVER に変更します。この変更は、既存の、あるいは後で作成される他のシ
ステム・オブジェクトのいずれにも影響することはありません。
構文
UINT CWB_ENTRY cwbCO_SetIPAddress(
cwbCO_SysHandle
LPCSTR
system,
IPAddress );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
LPCSTR IPAddress - input
IP アドレスを文字ストリングとして、ドット表記法 ("nnn.nnn.nnn.nnn") で指定します。ここで、それ
ぞれの "nnn" は、0 から 255 までの 10 進数です。 IPAddress は、終了の NULL 文字を含まずに、
CWBCO_MAX_IP_ADDRESS 文字よりも長くなってはなりません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
IPAddress パラメーターが有効な IP アドレスを含んでいません。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。
指定されたシステム・オブジェクトを使用して何らかの接続が行われる場合にはいつでも、特定の IP アド
レスを強制的に使用させるために、この API を使用します。 IP アドレス・ルックアップ・モードが IP
90
IBM i: Windows アプリケーション・パッケージ: プログラミング
アドレスをルックアップしないように設定されているため、接続やサインオンが行われる前に、 IP アドレ
ス・ルックアップ・モードが cwbCO_SetIPAddressLookupMode 呼び出しによって変更されない限り、指定
されたアドレスが常に使用されます。
cwbCO_SetIPAddressLookupMode:
cwbCO_SetIPAddressLookupMode コマンドを使用します。
目的
この関数は、指定のシステム・オブジェクトについて、このオブジェクトが表すシステムに接続を行う際
に、IBM i の IP アドレスの動的ルックアップが行われる時点を指定します。 cwbCO_CreateSystem また
は cwbCO_CreateSystemLike の呼び出し時に指定されるシステム名が、実際の IP アドレスである場合、製
品でアドレスをルックアップする必要はないため、この設定は無視されます。
構文
UINT CWB_ENTRY cwbCO_SetIPAddressLookupMode(
cwbCO_SysHandle
cwbCO_IPAddressLookupMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_IPAddressLookupMode mode - input
動的アドレス・ルックアップをいつ実行するかを指定します。指定できる値は以下のとおりです。
CWBCO_IPADDR_LOOKUP_ALWAYS
接続が行われるたびに、IBM i の IP アドレスを動的にルックアップします。
CWBCO_IPADDR_LOOKUP_1HOUR
このシステムでの前回のルックアップから 1 時間以上経過している場合には、IP アドレスを
動的にルックアップします。
CWBCO_IPADDR_LOOKUP_1DAY
このシステムでの前回のルックアップから 1 日以上経過している場合には、IP アドレスを動
的にルックアップします。
CWBCO_IPADDR_LOOKUP_1WEEK
このシステムでの前回のルックアップから 1 週間以上経過している場合には、IP アドレスを
動的にルックアップします。
CWBCO_IPADDR_LOOKUP_NEVER
このシステムの IBM i IP アドレスの動的ルックアップを行いません。この PC で最近使用し
た IP アドレスが、常にシステムで使用されます。
CWBCO_IPADDR_LOOKUP_AFTER_STARTUP
このシステムでの前回のルックアップ以降、Windows が再始動された場合には、IP アドレス
を動的にルックアップします。
戻りコード
以下は、共通の戻り値です。
プログラミング
91
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。
CWB_IPADDR_LOOKUP_ALWAYS 以外の値に設定すると、IBM i の接続時間を短縮できる場合がありま
す。動的ルックアップによって、ネットワーク・トラフィックが増大し、完了までに時間がかかることがあ
るためです。動的ルックアップを行わない場合、IBM i の IP アドレスが変更されて、接続が失敗した
り、間違ったシステムに接続されたりするというリスクが発生します。
cwbCO_SetPortLookupMode:
cwbCO_SetPortLookupMode コマンドを使用します。
目的
この関数は、指定されたシステム・オブジェクトについて、ホスト・サーバーのポート・ルックアップがど
のように行われるかを設定します。
構文
UINT CWB_ENTRY cwbCO_SetPortLookupMode(
cwbCO_SysHandle
cwbCO_PortLookupMode
system,
mode );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。これは IBM i
の ID です。
cwbCO_PortLookupMode mode - input
ポート・ルックアップ方式を指定します。指定できる値は以下のとおりです。
CWBCO_PORT_LOOKUP_SERVER
まだ確立されていないサービスへの接続を行う場合は、その都度 IBM i ホスト・サーバー・
マッパーに連絡が取られて、ホスト・サーバー・ポートのルックアップが行われます。サーバ
ー・マッパーは、希望の IBM i サービスに接続するために後で使用されるポート番号を戻し
ます。
92
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBCO_PORT_LOOKUP_LOCAL
ホスト・サーバー・ポートのルックアップは、PC 自体の SERVICES ファイルをルックアップ
することによって行われます。
CWBCO_PORT_LOOKUP_STANDARD
標準ポートを使用して、希望するサーバーに接続します。標準ポートは、所定のホスト・サー
バーにデフォルトで設定されており、そのサービスの IBM i サービス・テーブルに変更が一
切加えられていない場合に使用されるポートです。
後の 2 つのモードは、IBM i マッパー接続とそれに関連した遅れ、ネットワーク・トラフィック、お
よびシステムの負荷を取り除きます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_PARAMETER
モード・パラメーターの値が無効。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
使用法
この API は、指定されたシステム・オブジェクトについて、サインオンが正常に行われた後では使用する
ことができません。このシステム・オブジェクトについて、 cwbCO_Signon または cwbCO_Connect のい
ずれかの呼び出しが正常に行われた場合には、サインオンが行われています。
サービス用のポート番号をきわめて正確なものにするためには、CWBCO_PORT_LOOKUP_SERVER を使
用します。ただし、この場合、サービスへの新たな接続が行われるたびに、システムのサーバー・マッパー
への余分な接続が必要になります。
CWBCO_PORT_LOOKUP_STANDARD を使用すると最良のパフォーマンスが得られます。ただし、システ
ム管理者がシステムのサービス・テーブルで、いずれかの IBM i ホスト・サービスのポートを変更した場
合、このモードは機能しません。
システム・オブジェクトによって表されるシステムで IBM i Access ホスト・サービスのポートが変更され
ている場合、最良のパフォーマンスを得るためには CWBCO_PORT_LOOKUP_LOCAL を使用します。こ
れを機能させるためには、それぞれのホスト・サービス・ポートごとの記入項目を、SERVICES という名
の PC のファイルに追加する必要があります。そのような各記入項目では、まず最初に、ホスト・サービ
スの標準名 (例えば、引用符なしの "as-rmtcmd") を含み、その後にスペースおよびそのサービスのポート
番号が続いている必要があります。 SERVICES ファイルは、Windows インストール・ディレクトリーの
下の system32\drivers\etc というサブディレクトリーにあります。
プログラミング
93
cwbCO_UseSecureSockets:
cwbCO_UseSecureSockets コマンドを使用します。
目的
システム・オブジェクトで表されるシステムに対するすべての IBM i 通信で、セキュア・ソケットを使用
するか使用しないかを指定します。
構文
UINT CWB_ENTRY cwbCO_UseSecureSockets(
cwbCO_SysHandle
cwb_Boolean
system,
useSecureSockets );
パラメーター
cwbCO_SysHandle system - input
以前に cwbCO_CreateSystem または cwbCO_CreateSystemLike から戻されたハンドル。 IBM i システ
ムを識別します。
cwb_Boolean useSecureSockets - input
指定のシステム・オブジェクト・ハンドルが表しているシステムと通信を行う際に、セキュア・ソケッ
トの使用が必要かどうかを指定します。次のうち、適切な値を使用します。
CWB_TRUE
通信にセキュア・ソケットの使用が必要。
CWB_FALSE
通信にセキュア・ソケットは使用しない。
CWB_USER_TIMEOUT
システム・オブジェクトに関連した接続タイムアウト値が、接続の検証が完了する前に有効期
限が切れました。そのため、待機を停止します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_SECURE_SOCKETS_NOTAVAIL
セキュア・ソケットが使用不可。セキュア・ソケットが、PC にインストールされていないか、こ
のユーザーでは禁止されているか、あるいは IBM i システムでは使用できません。
CWB_RESTRICTED_BY_POLICY
この値の変更を禁止するポリシーが存在します。
CWB_INV_AFTER_SIGNON
指定されたシステム・オブジェクトを使用して、サインオンが正常に行われたため、この設定値は
変更されることはありません。
94
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
指定されたサービスへの接続が所定のシステム・オブジェクト用に既に存在している場合でも、新規の接続
は試行されます。所定のシステム・オブジェクトの属性 (セキュア・ソケットを使用するかどうかなど)
が、この接続の試行に使用されます。その結果、渡されたシステム・オブジェクトを指定した接続の検証は
失敗する可能性がありますが、属性の設定が異なるシステム・オブジェクトを指定した同じシステムでは成
功する場合があります。これが最も明確に現れるのは、セキュア・ソケットの使用が関係してくる場合で
す。これは、非セキュア・ソケット・バージョンのサービスはシステムで稼働する可能性があるものの、セ
キュア・ソケット・バージョンのサービスは稼働しない可能性がある、またはその逆の場合が考えられるた
めです。
この API が呼び出された時、製品において、IBM i 接続時に使用可能なセキュア・ソケットを検出できな
い場合があります。 CWB_SECURE_SOCKETS_NOTAVAIL が戻されない場合であっても、後でセキュ
ア・ソケットが使用不可であることが判明する場合もあります。
SSL が使用されている場合、製品は Federal Information Processing Standards (FIPS) 準拠を (一定の制限付
きで) 強制しますが、この API では、FIPS 準拠がオンかオフかについては戻されません。 FIPS 準拠がオ
ンかオフかを確認する唯一の方法は、製品プロパティーの FIPS 準拠のチェック・ボックスを確認すること
です。 FIPS とその使用法について詳しくは、本製品と共にインストールされる、製品の「ユーザーズ・ガ
イド」を参照してください。
cwbCO_Service の定義
cwbCO_Service を定義する値を、以下に示します。
v CWBCO_SERVICE_CENTRAL
v CWBCO_SERVICE_NETFILE
v CWBCO_SERVICE_NETPRINT
v CWBCO_SERVICE_DATABASE
v CWBCO_SERVICE_ODBC
v CWBCO_SERVICE_DATAQUEUES
v CWBCO_SERVICE_REMOTECMD
v CWBCO_SERVICE_SECURITY
v CWBCO_SERVICE_DDM
v CWBCO_SERVICE_WEB_ADMIN
v CWBCO_SERVICE_TELNET
v CWBCO_SERVICE_MGMT_CENTRAL
v CWBCO_SERVICE_ANY
v CWBCO_SERVICE_ALL
cwbCO_Signon と cwbCO_VerifyUserIDPassword の相違点
以下に挙げるのは、cwbCO_Signon コマンドと cwbCO_VerifyUserIDPassword コマンドとの主要な相違点で
す。
v cwbCO_VerifyUserIDPassword は、ユーザー ID とパスワードが渡されることが必要であり (これらのた
めのシステム・オブジェクト値は使用されません)、この情報についてのプロンプトを出すことはありま
せん。 cwbCO_Signon は、他のシステム・オブジェクトの設定次第ではプロンプトを出すことがありま
す。その場合には、その検証を行おうとしたときにユーザーから与えられたユーザー ID とパスワード
の値はすべて使用します。
プログラミング
95
v cwbCO_VerifyUserIDPassword は、ユーザー ID とパスワードを求めてプロンプトを出すことはないた
め、指定されたシステム・オブジェクトの設定値がこの呼び出しの結果、変更されることはありませ
ん。しかし、cwbCO_Signon への呼び出しでは、この情報に対するプロンプトが出される可能性があり、
その結果として、システム・オブジェクトのユーザー ID とパスワードは変更されることがあります。
v cwbCO_VerifyUserIDPassword を使用すると、IBM i 接続の確立、ユーザー ID とパスワードの検証、お
よびサインオンの試行に関連する現行値 (前回のサインオンが正常に行われた日時など) の検索が、常に
実行されるようになります。しかし、cwbCO_Signon はユーザー ID とパスワードを検証するために接
続しない可能性があり、その代わりに先行の検証における最近の結果を使用することがあります。これ
は、所定のシステム・オブジェクトの検証モード属性のほか、先行の検証結果がどの程度新しいかによ
って影響を受けます。
v cwbCO_Signon が正常終了した場合にのみ、パスワードが IBM i パスワード・キャッシュに入れられま
す。cwbCO_VerifyUserIDPassword の呼び出しの結果として、キャッシュに入れられることはありませ
ん。
v cwbCO_VerifyUserIDPassword は、システム・オブジェクトの状態を「サインオン」に設定することはあ
りません。それに対して、cwbCO_Signon は成功すれば状態を「サインオン」に変更します。システム・
オブジェクトが「サインオン」状態にある場合、その属性の大部分はもはや変更されないため、このこ
とは重要です。
cwbCO_Signon と cwbCO_VerifyUserIDPassword の類似点
以下の情報は、cwbCO_Signon コマンドと cwbCO_VerifyUserIDPassword コマンドとの類似点に関するもの
です。
この両方の API は、ユーザー ID とパスワードの検証を行うために接続を使用する場合、サインオンの試
行に関連した現行データの検索も行います。このデータは、以下の API を使用して検索することができま
す。
v cwbCO_GetSignonDate
v cwbCO_GetPrevSignonDate
v cwbCO_GetPasswordExpireDate
v cwbCO_GetFailedSignons
通信: 作成および削除の API
これらの製品 API を使用して、現在活動中の環境もしくは別の環境で、構成済みシステムのリストを作成
します。リストの項目数の検索と、各項目の順序どおりの検索を行います。
cwbCO_CreateSysListHandle:
cwbCO_CreateSysListHandle コマンドを使用します。
目的
活動中の環境の構成済みシステム名リストへのハンドルを作成します。
構文
unsigned int CWB_ENTRY cwbCO_CreateSysListHandle(
cwbCO_SysListHandle *listHandle,
cwbSV_ErrHandle
errorHandle);
96
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbCO_SysListHandle *listHandle - output
出力の際に返されるリスト・ハンドルを指すポインター。このハンドルは、他の呼び出しでリストを使
用する時に必要になります。
cwbSV_ErrorHandle errorHandle - input
API 呼び出しが失敗した場合、このハンドルに関連したメッセージ・オブジェクトに、エラーを説明す
るメッセージ・テキストが書き込まれます。このパラメーターがゼロの場合は、メッセージの利用はで
きません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_POINTER
リスト・ハンドルを指すポインターが NULL です。
使用法
cwbCO_DeleteSysListHandle を呼び出して、この API で割り振られた資源を解放する必要があります。
cwbCO_CreateSysListHandleEnv:
cwbCO_CreateSysListHandleEnv コマンドを使用します。
目的
この関数は、指定された環境の、構成済みシステム名のリストへのハンドルを作成します。
構文
unsigned int CWB_ENTRY cwbCO_CreateSysListHandleEnv(
cwbCO_SysListHandle *listHandle,
cwbSV_ErrHandle
errorHandle,
LPCSTR
pEnvironment );
パラメーター
cwbCO_SysListHandle *listHandle - output
出力の際に返されるリスト・ハンドルを指すポインター。このハンドルは、他の呼び出しでリストを使
用する際に必要になります。
cwbSV_ErrorHandle errorHandle - input
API 呼び出しが失敗した場合、このハンドルに関連したメッセージ・オブジェクトに、エラーを説明す
るメッセージ・テキストが書き込まれます。このパラメーターがゼロの場合は、メッセージの利用はで
きません。
プログラミング
97
LPCSTR pEnvironment
必要な環境名が入っているストリングを指すポインター。 pEnvironment が NULL ポインター、すな
わち NULL ストリング ("¥0") を指すポインターである場合、現在活動中の環境のシステム・リストが
戻ります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_INVALID_POINTER
リスト・ハンドルを指すポインターが NULL です。
CWBCO_NO_SUCH_ENVIRONMENT
指定の環境は存在しません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
cwbCO_DeleteSysListHandle を呼び出して、この API で割り振られた資源を解放する必要があります。
cwbCO_DeleteSysListHandle:
cwbCO_DeleteSysListHandle コマンドを使用します。
目的
構成済みシステム名のリストへのハンドルを削除します。この関数は、システム名のリストの使用を終了し
た際に、呼び出す必要があります。
構文
unsigned int CWB_ENTRY cwbCO_DeleteSysListHandle(
cwbCO_SysListHandle listHandle);
パラメーター
cwbCO_SysListHandle - listHandle
削除するシステム名へのハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
98
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
使用法
cwbCO_CreateSysListHandle または cwbCO_CreateSysListHandleEnv の API で作成されたリストを削除する
ために、この API を使用します。
cwbCO_GetNextSysName:
cwbCO_GetNextSysName コマンドを使用します。
目的
システムのリストから、次の順番のシステムの名前を取得します。
構文
unsigned int CWB_ENTRY cwbCO_GetNextSysName(
cwbCO_SysListHandle listHandle,
char
*systemName,
unsigned long
bufferSize,
unsigned long
*needed);
パラメーター
cwbCO_SysListHandle handleList - input
システムのリストへのハンドル。
char *systemName - output
システム名が含まれているバッファーを指すポインター。このバッファーは、終了の NULL 文字を含
めて、少なくとも、CWBCO_MAX_SYS_NAME + 1 文字を保持することのできる大きさになっている
必要があります。
unsigned long bufferSize - input
systemName が指定するバッファーのサイズ。
unsigned long *needed - output
システム名全体を保持するために必要なバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
システム名を指すポインター、または必要なバッファー・サイズを指すポインターが NULL で
す。ヒストリー・ログのメッセージをチェックして、どれが NULL かを判別してください。
CWB_BUFFER_OVERFLOW
出力バッファーにシステム名全体を保持することのできる十分なスペースがありません。*needed
プログラミング
99
を使用して、正しいサイズを判別してください。呼び出し側が、このエラーから回復して継続する
処理を行う予定であるため、ヒストリー・ログにエラー・メッセージは記録されません。
CWBCO_END_OF_LIST
システムのリストの最後まで到達しました。システム名が、戻されませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
渡されたシステム・リストが API cwbCO_CreateSystemListHandle を使用して作成された場合、この API
呼び出しの間にユーザーがその環境を除去するか、別の環境へ切り換えることをしない限り、戻されるシス
テムは現在活動中である環境で構成されたものです。システム・リストを作成するために
cwbCO_CreateSysListHandleEnv が呼び出された場合、その環境をユーザーがそれ以降除去したのではない
限り、戻されるシステムはその API に渡される環境で構成されます。
cwbCO_GetSysListSize:
cwbCO_GetSysListSize コマンドを使用します。
目的
リストにあるシステム名の数を取得します。
構文
unsigned int CWB_ENTRY cwbCO_GetSysListSize(
cwbCO_SysListHandle listHandle,
unsigned long
*listSize);
パラメーター
cwbCO_SysListHandle listHandle - input
システムのリストのハンドル。
unsigned long *listSize - output
このパラメーターは、出力時に、リスト内のシステムの数に設定されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_API_HANDLE
システム・ハンドルが無効。
CWB_INVALID_POINTER
リスト・サイズを指すポインターが NULL です。
100
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
なし
通信: システム情報 API
これらの製品 API を使用して、現行のプロセスで構成または接続された個々のシステムに関する情報を入
手します。環境名がパラメーターとして渡されるのではない限り、これらの API は、現在、活動中の環境
でのみ機能します。
cwbCO_GetActiveConversations:
cwbCO_GetActiveConversations コマンドを使用します。
目的
システムの活動中の会話の数を取得します。
構文
int CWB_ENTRY cwbCO_GetActiveConversations(
LPCSTR systemName);
パラメーター
LPCSTR systemName - input
システム名が含まれているバッファーを指すポインター。
戻りコード
活動中の会話がある場合には、その数が戻されます。systemName ポインターが NULL であるか、空スト
リングを指しているか、システムが現在接続されていないか、あるいは変換できない 1 つまたは複数のユ
ニコード文字が含まれている場合は、0 が戻されます。
使用法
この API は、現行のプロセス内に限り、指定されたシステムで活動中の会話の数を戻します。 PC で実行
されている他のプロセス内で、その他の会話が活動中である可能性があります。
cwbCO_GetConnectedSysName:
cwbCO_GetConnectedSysName コマンドを使用します。
目的
索引に対応する、接続されたシステムの名前を取得します。
構文
unsigned int CWB_ENTRY cwbCO_GetConnectedSysName(
char
*systemName,
unsigned long
*bufferSize,
unsigned long
index);
プログラミング
101
パラメーター
char *systemName - output
システム名が含まれているバッファーを指すポインター。このバッファーは、終了の NULL 文字を含
めて、少なくとも、CWBCO_MAX_SYS_NAME + 1 文字を保持することのできる大きさになっている
必要があります。
unsigned long * bufferSize - input/output
入力
*systemName が指すバッファーのサイズ。
出力
必要なバッファー・サイズ。
unsigned long index
名前を検索する、接続されたシステムを示します。最初に接続されたシステムの索引は 0、2 番目の索
引は 1、以下同様です。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
システム名を指すポインター、または必要なバッファー・サイズを指すポインターが NULL で
す。ヒストリー・ログのメッセージをチェックして、どれが NULL かを判別してください。
CWB_BUFFER_OVERFLOW
出力バッファーにシステム名全体を保持することのできる十分なスペースがありません。
*bufferSize を使用して、正しいサイズを判別してください。呼び出し側が、このエラーから回復し
て継続する処理を行う予定であるため、ヒストリー・ログにエラー・メッセージは記録されませ
ん。
CWBCO_END_OF_LIST
接続されたシステムのリストの最後まで到達しました。システム名が、戻されませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
システム名を検索することができる接続は、現行プロセス内のものに限られます。
cwbCO_GetDefaultSysName:
cwbCO_GetDefaultSysName コマンドを使用します。
目的
活動中の環境のデフォルト・システムの名前を取得します。
102
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbCO_GetDefaultSysName(
char
unsigned long
unsigned long
cwbSV_ErrHandle
*defaultSystemName,
bufferSize,
*needed,
errorHandle);
パラメーター
char *defaultSystemName - output
NULL で終わるシステム名が含まれるバッファーを指すポインター。このバッファーは、終了の
NULL 文字を含めて、少なくとも、CWBCO_MAX_SYS_NAME + 1 文字を保持することのできる大き
さになっている必要があります。
unsigned long bufferSize - input
入力バッファーのサイズ。
unsigned long *needed - output
終了の NULL を含めて、システム名全体を保持するために必要なバイト数。
cwbSV_ErrorHandle errorhandle - input
API 呼び出しが失敗した場合、このハンドルに関連したメッセージ・オブジェクトに、エラーを説明す
るメッセージ・テキストが書き込まれます。このパラメーターがゼロの場合は、メッセージの利用はで
きません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
システム名を指すポインター、または必要なバッファー・サイズを指すポインターが NULL で
す。ヒストリー・ログのメッセージをチェックして、どれが NULL かを判別してください。
CWB_BUFFER_OVERFLOW
出力バッファーにシステム名全体を保持することのできる十分なスペースがありません。*needed
を使用して、正しいサイズを判別してください。呼び出し側が、このエラーから回復して継続する
処理を行う予定であるため、ヒストリー・ログにエラー・メッセージは記録されません。
CWBCO_DEFAULT_SYSTEM_NOT_DEFINED
活動中の環境で、デフォルト・システムの設定が定義されていません。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
なし
cwbCO_IsSystemConfigured:
cwbCO_IsSystemConfigured コマンドを使用します。
プログラミング
103
目的
入力システムが、現在使用中の環境の中で構成されているかどうかをチェックします。
構文
cwb_Boolean CWB_ENTRY cwbCO_IsSystemConfigured(
LPCSTR
systemName);
パラメーター
LPCSTR systemName - input
システム名が含まれているバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_TRUE:
システムは、構成されています。
CWB_FALSE:
システムが構成されていないか、systemName が NULL であるか、または変換できない 1 つまた
は複数のユニコード文字がシステム名に含まれています。
使用法
なし (None)
cwbCO_IsSystemConfiguredEnv:
cwbCO_IsSystemConfiguredEnv コマンドを使用します。
目的
入力システムが、指定された環境で構成されているかどうかをチェックします。
構文
cwb_Boolean CWB_ENTRY cwbCO_IsSystemConfiguredEnv(
LPCSTR
systemName,
LPCSTR
pEnvironment);
パラメーター
LPCSTR systemName - input
システム名が含まれているバッファーを指すポインター。
LPCSTR pEnvironment - input
環境名が含まれているバッファーを指すポインター。 pEnvironment が NULL であるか、または空ス
トリングを指している場合、現在使用中の環境がチェックされます。
戻りコード
以下は、共通の戻り値です。
104
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_TRUE:
システムは、構成されています。
CWB_FALSE:
システムが構成されていないか、systemName が NULL であるか、または変換できない 1 つまた
は複数のユニコード文字がシステム名に含まれています。
使用法
なし (None)
cwbCO_IsSystemConnected:
cwbCO_IsSystemConnected コマンドを使用します。
目的
入力システムが現在接続されているかどうかをチェックします。
構文
cwb_Boolean CWB_ENTRY cwbCO_IsSystemConnected(
LPCSTR systemName);
パラメーター
LPCSTR systemName - input
システム名が含まれているバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_TRUE:
システムは、接続されています。
CWB_FALSE:
システムが接続されていないか、systemName が NULL であるか、または変換できない 1 つまた
は複数のユニコード文字がシステム名に含まれています。
使用法
この API は、現在のプロセス内のみの接続状況を示しています。別のプロセス内ではシステムは接続され
ている可能性がありますが、このことはこの API の出力には影響しません。
通信: 構成済み環境情報
これらの製品 API を使用して、構成されている環境名を取得します。
cwbCO_GetActiveEnvironment:
cwbCO_GetActiveEnvironment コマンドを使用します。
目的
現在活動中である環境の名前を取得します。
プログラミング
105
構文
unsigned int CWB_ENTRY cwbCO_GetActiveEnvironment(
char
*environmentName,
unsigned long
*bufferSize);
パラメーター
char *environmentName - output
渡されるバッファーがその名前を保持することのできる十分な大きさがある場合は、活動中の環境の名
前がコピーされるバッファーを指すポインターです。バッファーは、終了の NULL 文字を含めて、少
なくとも、CWBCO_MAX_ENV_NAME + 1 文字を保持することのできる大きさが必要です。
unsigned long * bufferSize - input/output
入力
*environmentName が指しているバッファーのサイズ。
出力
必要なバッファー・サイズ。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
1 つまたは複数のポインター・パラメーターが NULL です。
CWB_BUFFER_OVERFLOW
出力バッファーに環境名全体を保持することのできる十分なスペースがありません。*bufferSize を
使用して、正しいサイズを判別してください。呼び出し側が、このエラーから回復して継続する処
理を行う予定であるため、ヒストリー・ログにエラー・メッセージは記録されません。
CWBCO_NO_SUCH_ENVIRONMENT
環境が構成されていないため、活動中の環境がありません。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
なし
cwbCO_GetEnvironmentName:
cwbCO_GetEnvironmentName コマンドを使用します。
目的
索引に対応する環境名を取得します。
106
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbCO_GetEnvironmentName(
char
*environmentName,
unsigned long
*bufferSize,
unsigned long
index);
パラメーター
char *environmentName - output
環境名が含まれるバッファーを指すポインター。このバッファーは、終了の NULL 文字を含めて少な
くとも、CWBCO_MAX_ENV_NAME + 1 文字を保持することのできる大きさが必要です。
unsigned long * bufferSize - input/output
入力
*environmentName が指しているバッファーのサイズ。
出力
用意されたバッファーが小さすぎた場合、必要なバッファーのサイズ。
unsigned long index - input
0 は、1 番目の環境に対応します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
1 つまたは複数のポインター・パラメーターが NULL です。
CWB_BUFFER_OVERFLOW
出力バッファーに環境名全体を保持することのできる十分なスペースがありません。*bufferSize を
使用して、正しいサイズを判別してください。呼び出し側が、このエラーから回復して継続する処
理を行う予定であるため、ヒストリー・ログにエラー・メッセージは記録されません。
CWBCO_END_OF_LIST
環境リストの最後に到達しました。環境名は、戻されませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
なし
cwbCO_GetNumberOfEnvironments:
cwbCO_GetNumberOfEnvironments コマンドを使用します。
目的
存在する IBM i Access 環境の数を取得します。活動中の環境と活動中ではない環境の両方が含まれます。
プログラミング
107
構文
unsigned int CWB_ENTRY cwbCO_GetNumberOfEnvironments(
unsigned long
*numberOfEnv);
パラメーター
unsigned long *numberOfEnv - output
出力時に、環境の数に設定されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
numberOfEnv ポインター・パラメーターが NULL です。
使用法
なし
通信: 環境および接続情報
これらの製品 API を使用して、呼び出し側のアプリケーションで環境と接続情報を変更できるかどうかを
判別します。
cwbCO_CanConnectNewSystem:
cwbCO_CanConnectNewSystem コマンドを使用します。
目的
活動中の環境内のシステム・リストで、構成されていないシステムにユーザーが接続できるかどうかを示し
ています。
構文
cwb_Boolean CWB_ENTRY cwbCO_CanConnectNewSystem();
パラメーター
なし (None)
戻りコード
以下は、共通の戻り値です。
CWB_TRUE
まだ構成されていないシステムに接続可能。
CWB_FALSE
まだ構成されていないシステムに接続は不可能。
108
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
この API が CWB_FALSE を戻す場合、現在構成されていないシステム名による cwbCO_CreateSystem へ
の呼び出しは失敗します。その他の製品 API において、システム名をパラメーターとして取るものについ
ても、同様に失敗します。
cwbCO_CanModifyEnvironmentList:
cwbCO_CanModifyEnvironmentList コマンドを使用します。
目的
ユーザーが環境を作成 / 除去 / 名前変更できるかどうかを示します。
構文
cwb_Boolean CWB_ENTRY cwbCO_CanModifyEnvironmentList();
パラメーター
なし (None)
戻りコード
以下は、共通の戻り値です。
CWB_TRUE
環境を作成 / 除去 / 名前変更 / 削除することができます。
CWB_FALSE
環境を作成 / 除去 / 名前変更 / 削除することはできません。
使用法
この API は、環境が操作可能であるかどうかを示しています。環境内のシステムが、操作可能であるかど
うかを調べるには、cwbCO_CanModifySystemList および cwbCO_CanModifySystemListEnv の API を使用
します。
cwbCO_CanModifySystemList:
cwbCO_CanModifySystemList コマンドを使用します。
目的
ユーザーが活動中の環境内のシステムを作成 / 除去 / 削除できるかどうかを示します。ポリシーを介して
管理者が「指定した」システムは、除去することはできない点に注意してください。
構文
cwb_Boolean CWB_ENTRY cwbCO_CanModifySystemList();
パラメーター
なし (None)
プログラミング
109
戻りコード
以下は、共通の戻り値です。
CWB_TRUE
システム・リストを変更可能。
CWB_FALSE
システム・リストは変更不可。
使用法
この API は、活動中の環境内のシステムが操作可能かどうかを示しています。環境が操作可能かどうかを
調べる場合は、cwbCO_CanModifyEnvironmentList を参照してください。
cwbCO_CanModifySystemListEnv:
cwbCO_CanModifySystemListEnv コマンドを使用します。
目的
ユーザーが入力環境内のシステムを作成 / 除去 / 削除できるかどうかを示します。ポリシーを介して管理
者が「指定した」システムは、除去することはできない点に注意してください。
構文
cwb_Boolean CWB_ENTRY cwbCO_CanModifySystemListEnv(
char
*environmentName);
パラメーター
char *environmentName - input
必要な環境名が入っているストリングを指すポインターです。このポインターが NULL であるか、ま
たは空ストリングを指している場合、現在活動中の環境がチェックされます。
戻りコード
以下は、共通の戻り値です。
CWB_TRUE
システム・リストを変更可能。
CWB_FALSE
システム・リストは変更不可。あるいは、存在しない環境名が渡されたというようなエラーが起こ
りました。
使用法
この API は、環境内のシステムが操作可能かどうかを示しています。環境が操作可能かどうかを調べる場
合は、cwbCO_CanModifyEnvironmentList を参照してください。
cwbCO_CanSetActiveEnvironment:
cwbCO_CanSetActiveEnvironment コマンドを使用します。
110
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
ユーザーが環境を活動中の環境に設定できるかどうかを示します。
構文
cwb_Boolean CWB_ENTRY cwbCO_CanSetActiveEnvironment();
パラメーター
なし (None)
戻りコード
以下は、共通の戻り値です。
CWB_TRUE
活動中の環境を設定できる。
CWB_FALSE
活動中の環境を設定できない。
使用法
なし (None)
例: 通信 API の使用
通信 API を使用して、デフォルト (管理) システムの名前、および活動環境の中で構成されたすべてのシ
ステムの名前を検索して表示する場合の、プログラム例です。
/*******************************************************************
*
* Module:
* GETSYS.C
*
* Purpose:
* This module is used to demonstrate how an application might use the
* Communication API’s. In this example, these APIs are used to get
* and display the list of all configured systems. The user can then
* select one, and that system’s connection properties (the attributes
* of the created system object) are displayed. All Client Access
* services are then checked for connectabliity, and the results displayed.
*
* Usage notes:
*
* Include CWBCO.H, CWBCOSYS.H, and CWBSV.H
* Link with CWBAPI.LIB
*
* IBM grants you a nonexclusive license to use this as an example
* from which you can generate similar function tailored to your own
* specific needs. This sample is provided in the form of source
* material which you may change and use.
* If you change the source, it is recommended that you first copy the
* source to a different directory. This will ensure that your changes
* are preserved when the tool kit contents are changed by IBM.
*
*
DISCLAIMER
*
---------*
* This sample code is provided by IBM for illustrative purposes only.
* These examples have not been thoroughly tested under all conditions.
* IBM, therefore, cannot guarantee or imply reliability,
プログラミング
111
* serviceability, or function of these programs. All programs
* contained herein are provided to you "AS IS" without any warranties
* of any kind. ALL WARRANTIES, INCLUDING BUT NOT LIMITED TO THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE, ARE EXPRESSLY DISCLAIMED.
*
* Your license to this sample code provides you no right or licenses to
* any IBM patents. IBM has no obligation to defend or indemnify against
* any claim of infringement, including but not limited to: patents,
* copyright, trade secret, or intellectual property rights of any kind.
*
*
*
*
*
*
COPYRIGHT
*
--------*
5770-XE1 (C) Copyright IBM CORP. 1996, 2009
*
All rights reserved.
*
US Government Users Restricted Rights *
Use, duplication or disclosure restricted
*
by GSA ADP Schedule Contract with IBM Corp.
*
Licensed Material - Property of IBM
*
*
*******************************************************************/
#include <windows.h>
#include <stdio.h>
#include "cwbsv.h"
#include "cwbco.h"
#include "cwbcosys.h"
#define SUCCESS
#define FAILURE
/* Service APIs for retrieving any FAILURE messages */
/* Comm APIs for enumerating systems configured
*/
/* Comm APIs for creating and using system objects */
(0)
(1)
/*
* Arrays of attribute description strings, for human-readable
* display of these values.
*/
char* valModeStr[2] = { "CWBCO_VALIDATE_IF_NECESSARY" ,
"CWBCO_VALIDATE_ALWAYS" } ;
char* promptModeStr[3] = { "CWBCO_PROMPT_IF_NECESSARY" ,
"CWBCO_PROMPT_ALWAYS" ,
"CWBCO_PROMPT_NEVER" } ;
char* dfltUserModeStr[5] = { "CWBCO_DEFAULT_USER_MODE_NOT_SET" ,
"CWBCO_DEFAULT_USER_USE" ,
"CWBCO_DEFAULT_USER_IGNORE" ,
"CWBCO_DEFAULT_USER_USEWINLOGON",
"CWBCO_DEFAULT_USER_USE_KERBEROS" } ;
char* IPALModeStr[6] = { "CWBCO_IPADDR_LOOKUP_ALWAYS" ,
"CWBCO_IPADDR_LOOKUP_1HOUR" ,
"CWBCO_IPADDR_LOOKUP_1DAY" ,
"CWBCO_IPADDR_LOOKUP_1WEEK" ,
"CWBCO_IPADDR_LOOKUP_NEVER" ,
"CWBCO_IPADDR_LOOKUP_AFTER_STARTUP" } ;
char* portLookupModeStr[3] = { "CWBCO_PORT_LOOKUP_SERVER" ,
"CWBCO_PORT_LOOKUP_LOCAL" ,
"CWBCO_PORT_LOOKUP_STANDARD" } ;
char* cwbBoolStr[2] = { "False", "True" } ;
112
IBM i: Windows アプリケーション・パッケージ: プログラミング
/* NOTE! The corresponding service CONSTANT integers start
*
at 1, NOT at 0; that is why the dummy "FAILURE" value
*
was added at position 0.
*/
char* serviceStr[15] = { "CWBCO_SERVICE_THISISABADSERVICE!",
"CWBCO_SERVICE_CENTRAL" ,
"CWBCO_SERVICE_NETFILE" ,
"CWBCO_SERVICE_NETPRINT" ,
"CWBCO_SERVICE_DATABASE" ,
"CWBCO_SERVICE_ODBC" ,
"CWBCO_SERVICE_DATAQUEUES" ,
"CWBCO_SERVICE_REMOTECMD" ,
"CWBCO_SERVICE_SECURITY" ,
"CWBCO_SERVICE_DDM" ,
"", /* not used */
"", /* not used */
"CWBCO_SERVICE_WEB_ADMIN" ,
"CWBCO_SERVICE_TELNET" ,
"CWBCO_SERVICE_MGMT_CENTRAL" } ;
/*
* Node in a singly-linked list to hold a pointer
* to a system name. Note that the creator of an
* instance of this node must allocate the space to
* hold the system name himself, only a pointer is
* supplied here.
*/
typedef struct sysListNodeStruct SYSLISTNODE, *PSYSLISTNODE;
struct sysListNodeStruct
{
char*
sysName;
cwbCO_SysHandle
hSys;
PSYSLISTNODE
next;
} ;
/****************************************************************************
* Add a system name to the list of configured systems we will keep around.
****************************************************************************/
UINT addSystemToList(
char* sysName,
SYSLISTNODE** ppSysList )
{
SYSLISTNODE* pNewSys;
char*
pNewSysName;
pNewSys = (SYSLISTNODE*) malloc (sizeof( SYSLISTNODE ));
if ( pNewSys == NULL )
{
return FAILURE;
}
pNewSysName = (char*) malloc (strlen( sysName ) + 1 );
if ( pNewSysName == NULL )
{
free (pNewSys);
return FAILURE;
}
strcpy( pNewSysName, sysName );
pNewSys->sysName = pNewSysName;
pNewSys->hSys = 0;
/* delay creating sys object until needed */
プログラミング
113
pNewSys->next = *ppSysList;
*ppSysList = pNewSys;
return SUCCESS;
}
/****************************************************************************
* Clear the list of system names and clean up used storage.
****************************************************************************/
void clearList( SYSLISTNODE* pSysList )
{
PSYSLISTNODE pCur, pNext;
pCur = pSysList;
while ( pCur != NULL )
{
pNext = pCur->next;
free (pCur->sysName);
free (pCur);
pCur = pNext;
}
}
/****************************************************************************
* Retrieve and display Client Access FAILURE messages.
****************************************************************************/
void reportCAErrors( cwbSV_ErrHandle hErrs )
{
ULONG msgCount;
UINT apiRC;
UINT i;
char msgText[ 200 ];
/* 200 is big enuf to hold most msgs */
ULONG bufLen = sizeof( msgText ); /* holds size of msgText buffer
*/
ULONG lenNeeded;
/* to hold length of buf needed
*/
apiRC = cwbSV_GetErrCount( hErrs, &msgCount );
if ( CWB_OK != apiRC )
{
printf( "Failed to get message count, cwbSV_GetErrCount rc=%u¥n", apiRC );
if ( ( CWB_INVALID_POINTER == apiRC ) ||
( CWB_INVALID_HANDLE == apiRC ) )
{
printf( " --> likely a programming FAILURE!¥n");
}
return;
}
bufLen = sizeof( msgText );
for ( i=1; i<=msgCount; i++ )
{
apiRC = cwbSV_GetErrTextIndexed(hErrs, i, msgText, bufLen, &lenNeeded);
if ( ( CWB_OK == apiRC ) ||
( CWB_BUFFER_OVERFLOW == apiRC ) ) /* if truncated, that’s ok */
{
printf( "CA FAILURE #%u: %s¥n", i, msgText );
}
else
{
printf( "CA FAILURE #%u unuvailable, cwbSV_GetErrTextIndexed rc=%u¥n",
i, apiRC );
}
}
}
114
IBM i: Windows アプリケーション・パッケージ: プログラミング
/****************************************************************************
* Build the list of systems as it is currently configured in Client
* Access.
****************************************************************************/
UINT buildSysList(
SYSLISTNODE** ppSysList )
{
cwbSV_ErrHandle
hErrs;
cwbCO_SysListHandle hList;
char
sysName[ CWBCO_MAX_SYS_NAME + 1 ];
ULONG
bufSize = sizeof( sysName );
ULONG
needed;
UINT
apiRC;
UINT
myRC = SUCCESS;
UINT
rc = SUCCESS;
/* Create a FAILURE handle so that, in case of FAILURE, we can
* retrieve and display the messages (if any) associated with
* the failure.
*/
apiRC = cwbSV_CreateErrHandle( &hErrs );
if ( CWB_OK != apiRC )
{
/* Failed to create a FAILURE handle, use NULL instead.
* This means we’ll not be able to get at FAILURE messages.
*/
hErrs = 0;
}
apiRC = cwbCO_CreateSysListHandle( &hList, hErrs );
if ( CWB_OK != apiRC )
{
printf( "Failure to get a handle to the system list.¥n" );
reportCAErrors( hErrs );
myRC = FAILURE;
}
/* Get each successive system name and add the system to our
* internal list for later use.
*/
while ( ( CWB_OK == apiRC ) && ( myRC == SUCCESS ) )
{
apiRC = cwbCO_GetNextSysName( hList, sysName, bufSize, &needed );
/* Note that since the sysName buffer is as large as it will
*
ever need to be, we don’t check specifically for the return
*
code CWB_BUFFER_OVERFLOW. We could instead choose to use a
*
smaller buffer, and if CWB_BUFFER_OVERFLOW were returned,
*
allocate one large enough and call cwbCO_GetNextSysName
*
again.
*/
if ( CWB_OK == apiRC )
{
myRC = addSystemToList( sysName, ppSysList );
if ( myRC != SUCCESS )
{
printf( "Failure to add the next system name to the list.¥n");
}
}
else if ( CWBCO_END_OF_LIST != apiRC )
{
printf( "Failed to get the next system name.¥n" );
myRC = FAILURE;
}
} /* end while (to build a list of system names) */
プログラミング
115
/*
* Free the FAILURE handle if one was created
*/
if ( hErrs != 0 )
/* (non-NULL if it was successfully created) */
{
apiRC = cwbSV_DeleteErrHandle( hErrs );
if ( CWB_INVALID_HANDLE == apiRC )
{
printf("Failure: FAILURE handle invalid, could not delete!¥n");
myRC = FAILURE;
}
}
return myRC;
}
/****************************************************************************
* Get a system object given an index into our list of systems.
****************************************************************************/
UINT getSystemObject(
UINT sysNum,
SYSLISTNODE* pSysList,
cwbCO_SysHandle* phSys )
{
SYSLISTNODE* pCur;
UINT myRC=0, apiRC;
pCur = pSysList;
for ( ; sysNum > 1; sysNum-- )
{
/* We have come to the end of the list without finding
* the system requested, break out of loop and set FAILURE rc.
*/
if ( NULL == pCur )
{
myRC = FAILURE;
break;
}
pCur = pCur->next;
}
/* If we’re at a real system node, continue
*/
if ( NULL != pCur )
{
/* We’re at the node/sysname of the user’s choice. If no
* Client Access "system object" has yet been created for this
* system, create one. Pass back the one for the selected system.
*/
if ( 0 == pCur->hSys )
{
apiRC = cwbCO_CreateSystem( pCur->sysName, &(pCur->hSys) );
if ( CWB_OK != apiRC )
{
printf(
"Failed to create system object, cwbCO_CreateSystem rc = %u¥n",
apiRC );
myRC = FAILURE;
}
}
*phSys = pCur->hSys;
}
return myRC;
116
IBM i: Windows アプリケーション・パッケージ: プログラミング
}
/****************************************************************************
* Allow the user to select a system from the list we have.
****************************************************************************/
UINT selectSystem(
UINT* pNumSelected,
SYSLISTNODE* pSysList,
BOOL refreshList )
{
UINT
myRC = SUCCESS;
SYSLISTNODE*
pCur;
UINT
sysNum, numSystems;
char
choiceStr[ 20 ];
/* If the user wants the list refreshed, clear any existing list
* so we can rebuilt it from scratch.
*/
if ( refreshList )
{
clearList( pSysList );
pSysList = NULL;
}
/* If the list of system names is NULL (no list exists), build
* the list of systems using Client Access APIs.
*/
if ( NULL == pSysList )
{
myRC = buildSysList( &pSysList );
if ( SUCCESS != myRC )
{
*pNumSelected = 0;
printf( "Failed to build sys list, cannot select a system.¥n");
}
}
if ( SUCCESS == myRC )
{
printf( "-------------------------------------------- ¥n" );
printf( "The list of systems configured is as follows:¥n" );
printf( "-------------------------------------------- ¥n" );
for ( sysNum = 1, pCur = pSysList;
pCur != NULL;
sysNum++, pCur = pCur->next )
{
printf( "
%u) %s¥n", sysNum, pCur->sysName );
}
numSystems = sysNum - 1;
printf( "Enter the number of the system of your choice:¥n");
gets( choiceStr );
*pNumSelected = atoi( choiceStr );
if ( *pNumSelected > numSystems )
{
printf( "Invalid selection, there are only %u systems configured.\n",numSystems);
*pNumSelected = 0;
myRC = FAILURE;
}
}
return myRC;
}
プログラミング
117
/****************************************************************************
* Display a single attribute and its value, or a failing return code
* if one occurred when trying to look it up.
****************************************************************************/
void dspAttr(
char* label,
char* attrVal,
UINT lookupRC,
cwb_Boolean* pCanBeModified,
UINT canBeModifiedRC )
{
if ( CWB_OK == lookupRC )
{
printf( "%25s : %-30s
", label, attrVal );
if ( CWB_OK == canBeModifiedRC )
{
if ( pCanBeModified != NULL )
{
printf( "%s¥n", cwbBoolStr[ *pCanBeModified ] );
}
else
{
printf( "(N/A)¥n" );
}
}
else
{
printf( "(Error, rc=%u)¥n", canBeModifiedRC );
}
}
else
{
printf( "%30s : (Error, rc=%u)¥n", label, lookupRC );
}
}
/****************************************************************************
*
* Load the host/version string into the buffer specified. The
* buffer passed in must be at least 7 bytes long! A pointer to
* the buffer itself is passed back so that the output from this
* function can be used directly as a parameter.
*
****************************************************************************/
char* hostVerModeDescr(
ULONG ver,
ULONG rel,
char* verRelBuf )
{
char* nextChar = verRelBuf;
if ( verRelBuf != NULL )
{
*nextChar++ = ’v’;
if ( ver < 10 )
{
*nextChar++ = ’0’ + (char)ver;
}
else
{
*nextChar++ = ’?’;
*nextChar++ = ’?’;
}
118
IBM i: Windows アプリケーション・パッケージ: プログラミング
*nextChar++ = ’r’;
if ( rel < 10 )
{
*nextChar++ = ’0’ + (char)rel;
}
else
{
*nextChar++ = ’?’;
*nextChar++ = ’?’;
}
*nextChar = ’¥0’;
}
return verRelBuf;
}
/****************************************************************************
* Display all attributes of the system whose index in the passed list
* is passed in.
****************************************************************************/
void dspSysAttrs(
SYSLISTNODE* pSysList,
UINT sysNum )
{
cwbCO_SysHandle hSys;
UINT rc;
char sysName[ CWBCO_MAX_SYS_NAME + 1 ];
char IPAddr[ CWBCO_MAX_IP_ADDRESS + 1 ];
ULONG bufLen, IPAddrLen;
ULONG IPAddrBufLen;
UINT apiRC, apiRC2;
cwbCO_ValidateMode
valMode;
cwbCO_DefaultUserMode
dfltUserMode;
cwbCO_PromptMode
promptMode;
cwbCO_PortLookupMode
portLookupMode;
cwbCO_IPAddressLookupMode IPALMode;
ULONG ver, rel;
char verRelBuf[ 10 ];
ULONG verRelBufLen;
cwb_Boolean isSecSoc;
cwb_Boolean canModify;
IPAddrBufLen = sizeof( IPAddr );
verRelBufLen = sizeof( verRelBuf );
rc = getSystemObject( sysNum, pSysList, &hSys );
if ( rc == FAILURE )
{
printf( "Failed to get system object for selected system.¥n");
return;
}
printf("¥n¥n");
printf("-----------------------------------------------------------¥n");
printf("
S y s t e m A t t r i b u t e s
¥n");
printf("-----------------------------------------------------------¥n");
printf("¥n");
printf( "%25s : %-30s
%s¥n", "Attribute", "Value", "Modifiable" );
printf( "%25s : %-30s
%s¥n", "---------", "-----", "----------" );
printf("¥n");
apiRC = cwbCO_GetSystemName( hSys, sysName, &bufLen );
dspAttr( "System Name", sysName, apiRC, NULL, 0 );
プログラミング
119
apiRC = cwbCO_GetIPAddress( hSys, IPAddr, &IPAddrLen );
dspAttr( "IP Address", IPAddr, apiRC, NULL, 0 );
apiRC = cwbCO_GetHostVersionEx( hSys, &ver, &rel );
dspAttr( "Host Version/Release",
hostVerModeDescr( ver, rel, verRelBuf ), apiRC, NULL, 0 );
apiRC = cwbCO_IsSecureSockets( hSys, &isSecSoc );
apiRC2 = cwbCO_CanModifyUseSecureSockets( hSys, &canModify );
dspAttr( "Secure Sockets In Use", cwbBoolStr[ isSecSoc ],
apiRC, &canModify, apiRC2 );
apiRC = cwbCO_GetValidateMode( hSys, &valMode );
canModify = CWB_TRUE;
dspAttr( "Validate Mode", valModeStr[ valMode ], apiRC,
&canModify, 0 );
apiRC = cwbCO_GetDefaultUserMode( hSys, &dfltUserMode );
apiRC2 = cwbCO_CanModifyDefaultUserMode( hSys, &canModify );
dspAttr( "Default User Mode", dfltUserModeStr[ dfltUserMode ], apiRC,
&canModify, apiRC2 );
apiRC = cwbCO_GetPromptMode( hSys, &promptMode );
canModify = CWB_TRUE;
dspAttr( "Prompt Mode", promptModeStr[ promptMode ], apiRC,
&canModify, 0 );
apiRC = cwbCO_GetPortLookupMode( hSys, &portLookupMode );
apiRC2 = cwbCO_CanModifyPortLookupMode( hSys, &canModify );
dspAttr( "Port Lookup Mode", portLookupModeStr[ portLookupMode ], apiRC,
&canModify, apiRC2 );
apiRC = cwbCO_GetIPAddressLookupMode( hSys, &IPALMode );
apiRC2 = cwbCO_CanModifyIPAddressLookupMode( hSys, &canModify );
dspAttr( "IP Address Lookup Mode", IPALModeStr[ IPALMode ], apiRC,
&canModify, apiRC2 );
printf("¥n¥n");
}
/****************************************************************************
* Display connectability to all Client Access services that are
* possible to connect to.
****************************************************************************/
void dspConnectability(
PSYSLISTNODE pSysList,
UINT sysNum )
{
UINT rc;
UINT apiRC;
cwbCO_Service service;
cwbCO_SysHandle hSys;
rc = getSystemObject( sysNum, pSysList, &hSys );
if ( rc == FAILURE )
{
printf( "Failed to get system object for selected system.¥n");
}
else
{
printf("¥n¥n");
printf("-----------------------------------------------------------¥n");
printf("
S y s t e m S e r v i c e s
S t a t u s
¥n");
printf("-----------------------------------------------------------¥n");
120
IBM i: Windows アプリケーション・パッケージ: プログラミング
for ( service=(cwbCO_Service)1;
service <= CWBCO_SERVICE_MGMT_CENTRAL;
service++ )
{
apiRC = cwbCO_Verify( hSys, service, 0 );
// 0=no err handle
printf(" Service ’%s’: ", serviceStr[ service ] );
if ( apiRC == CWB_OK )
{
printf("CONNECTABLE¥n");
}
else
{
printf("CONNECT TEST FAILED, rc = %u¥n", apiRC );
}
}
}
printf("¥n");
}
/****************************************************************************
* MAIN PROGRAM BODY
****************************************************************************/
void main(void)
{
PSYSLISTNODE pSysList = NULL;
UINT numSelected;
UINT rc;
char choiceStr[10];
UINT choice;
rc = buildSysList( &pSysList );
if ( SUCCESS != rc )
{
printf( "Failure to build the system list, exiting.¥n¥n");
exit( FAILURE );
}
do
{
printf( "Select one of the following options:¥n" );
printf( "
(1) Display current system attributes¥n");
printf( "
(2) Display service connectability for a system¥n");
printf( "
(3) Refresh the list of systems¥n" );
printf( "
(9) Quit¥n" );
gets( choiceStr );
choice = atoi( choiceStr );
switch ( choice )
{
// ---- Display current system attributes --------------case 1 :
{
rc = selectSystem( &numSelected, pSysList, FALSE );
if ( SUCCESS == rc )
{
dspSysAttrs( pSysList, numSelected );
}
break;
}
// ---- Display service connectability for a system ----case 2 :
{
rc = selectSystem( &numSelected, pSysList, FALSE );
プログラミング
121
if ( SUCCESS == rc )
{
dspConnectability( pSysList, numSelected );
}
break;
}
// ---- Refresh the list of systems --------------------case 3 :
{
clearList( pSysList );
pSysList = NULL;
rc = buildSysList( &pSysList );
break;
}
// ---- Quit -------------------------------------------case 9 :
{
printf("Ending the program!¥n");
break;
}
default :
{
printf("Invalid choice.
Please make a different selection.¥n");
}
}
} while ( choice != 9 );
/* Cleanup the list, we’re done */
clearList( pSysList );
pSysList = NULL;
printf( "¥nEnd of program.¥n¥n" );
}
IBM i データ待ち行列 API
製品のデータ待ち行列アプリケーション・プログラミング・インターフェース (API) を使用すると、IBM i
のデータ待ち行列に簡単にアクセスできます。データ待ち行列を使用することによって、通信 API を使う
必要のないクライアント/サーバー・アプリケーションを作成することができるようになります。
IBM i データ待ち行列 API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbdq.h
cwbapi.lib
cwbdq.dll
Programmer's Toolkit:
Programmer's Toolkit には、データ待ち行列資料、cwbdq.h ヘッダー・ファイルへのアクセス、およびプロ
グラム例へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit をオープン
して、「データ待ち行列」 > 「C/C++ API」と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
122
IBM i: Windows アプリケーション・パッケージ: プログラミング
21 ページの『データ待ち行列 API の戻りコード』
データ待ち行列 API の戻りコードを示します。
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
データ待ち行列
データ待ち行列は、IBM i のオブジェクトです。
データ待ち行列を使用する利点
PC 開発者および IBM i アプリケーション開発者にとって、データ待ち行列には数多くの利点がありま
す。
v データ待ち行列を使用すると、IBM i 通信を高速かつ効率的に行うことができます。
v データ待ち行列は、システム・オーバーヘッドが少なくて済み、ごくわずかのセットアップですみま
す。
v 1 つのバッチ・ジョブが単一のデータ待ち行列を使用して、複数の対話式ジョブをサービスすることが
できるので、データ待ち行列は効率的です。
v データ待ち行列メッセージの内容は不定様式であり (フィールドは不要)、他のシステム・オブジェクト
にはない柔軟性を備えています。
v データ待ち行列へのアクセスは、IBM i API ならびに CL コマンドを介して行われます。これによっ
て、クライアント/サーバー・アプリケーションの開発を容易に行うことができます。
データ待ち行列メッセージの配列
IBM i データ待ち行列に入れるメッセージの配列方法を指定するには、次の 3 つの方法があります。
LIFO
後入れ先出し法です。データ待ち行列に最後に入れられた (最新) メッセージを待ち行列から最初
に取り出します。
FIFO
先入れ先出し法です。データ待ち行列に最初に入れられた (最古) メッセージを待ち行列から最初
に取り出します。
KEYED
データ待ち行列に入れられたメッセージごとに、キーが関連付けられます。メッセージは、関連付
けられているキーを要求することによってのみ、待ち行列から取り出すことができます。
データ待ち行列の操作
IBM i CL コマンド、または呼び出し可能なプログラミング・インターフェースを使用して、データ待ち行
列の操作を行うことができます。アプリケーションを作成したプログラミング言語に関係なく、すべての
IBM i アプリケーションが、データ待ち行列にアクセスできます。
次に挙げる IBM i インターフェースを使用して、データ待ち行列の操作を行えます。
IBM i コマンド
CRTDTAQ
データ待ち行列を作成し、指定のライブラリーに保管します。
プログラミング
123
DLTDTAQ
指定のデータ待ち行列をシステムから削除します。
IBM i アプリケーション・プログラミング・インターフェース
QSNDDTAQ
指定のデータ待ち行列にメッセージ (レコード) を送ります。
QRCVDTAQ
指定のデータ待ち行列のメッセージ (レコード) を読み込みます。
QCLRDTAQ
指定のデータ待ち行列からすべてのメッセージを消去します。
QMHQRDQD
データ待ち行列の記述を検索します。
QMHRDQM
項目を削除することなく、データ待ち行列の記入項目を検索します。
データ待ち行列の一般的な使用方法
データ待ち行列は、強力なプログラム間インターフェースです。IBM i プログラミングの経験が豊富なプ
ログラマーであれば、待ち行列の使い方には慣れているはずです。データ待ち行列とは、単に、情報を別の
プログラムに渡すために使用される手段に過ぎません。
このインターフェースには通信プログラミングが不要であるため、同期処理にも非同期 (切断) 処理にも使
用することができます。
ホスト・アプリケーションと PC アプリケーションは、サポートされている言語であれば、どの言語を使
用しても開発できます。例えば、ホスト・アプリケーションでは RPG を使用し、PC アプリケーションで
は C++ を使用するといったことが可能です。このような場合の待ち行列の役割は、一方のプログラムから
入力を取り込み、それを他方のプログラムに渡すことです。
データ待ち行列の使用例を次に示します。
v PC ユーザーが、終日電話注文を取り、注文を 1 つ 1 つプログラムにキー入力し、プログラムがそれぞ
れの注文を IBM i データ待ち行列に入れると想定します。
v パートナー・プログラム (PC プログラムまたは IBM i プログラムのいずれか) は、データ待ち行列を
モニターし、待ち行列から情報を引き出します。このパートナー・プログラムは、同時に稼働させるこ
ともできれば、ユーザー使用のピーク時を過ぎてから開始することもできます。
v パートナー・プログラムは、開始 PC プログラムに入力を戻すこともあれば、戻さないこともありま
す。また、別の PC または IBM i のプログラムの待ち行列に何らかの情報を入れることもあります。
v 最終的には、受注が完了し、顧客に請求書が送られ、在庫レコードが更新され、PC ユーザーに、顧客に
電話をして出荷予定日を知らせるための指示情報が、PC アプリケーションの「待ち行列」に入れられま
す。
オブジェクト
データ待ち行列機能を使用するアプリケーションでは、4 つのオブジェクトを利用します。これらのオブジ
ェクトは、それぞれに、ハンドルを介してそのアプリケーションに識別されます。オブジェクトには、以下
のものがあります。
待ち行列オブジェクト
このオブジェクトは、IBM i データ待ち行列を表します。
124
IBM i: Windows アプリケーション・パッケージ: プログラミング
属性
このオブジェクトは、IBM i データ待ち行列を記述します。
データこれらのオブジェクトは、IBM i データ待ち行列との間でレコードの書き込みや読み取りを行うの
に使用されます。
読み取りオブジェクト
このオブジェクトは、非同期読み取り API の場合にのみ使用されます。読み取りオブジェクト
は、IBM i データ待ち行列からレコードを読み取る要求を、固有に識別します。このハンドルは、
データが戻されたかどうかを検査するのに、以降の呼び出しで使用されます。詳細については、
cwbDQ_AsyncRead API を参照してください。
関連資料:
131 ページの『cwbDQ_AsyncRead』
cwbDQ_AsyncRead コマンドを使用します。
データ待ち行列: 作成、削除、およびオープンの API
これらの IBM i API は、cwbCO_SysHandle システム・オブジェクト・ハンドルと一緒に使用します。
cwbDQ_CreateEx:
cwbDQ_CreateEx コマンドを使用します。
目的
IBM i データ待ち行列オブジェクトを作成します。オブジェクトが作成されたら、cwbDQ_OpenEx API を
使用してそのオブジェクトをオープンすることができます。オブジェクトは、属性ハンドルに指定した属性
を持ちます。
構文
unsigned int CWB_ENTRY cwbDQ_CreateEx(
cwbCO_SysHandle
const char
const char
cwbDQ_Attr
cwbSV_ErrHandle
sysHandle,
*queue,
*library,
queueAttributes,
errorHandle);
パラメーター
cwbCO_SysHandle sysHandle - input
システム・オブジェクトを指すハンドル。
const char * queue - input
ASCIIZ ストリングに入っているデータ待ち行列名を指すポインター。
const char * library - input
ASCIIZ ストリングに入っているライブラリー名を指すポインター。このポインターが NULL の場合
は、現行ライブラリーが使用されます (ライブラリーを "*CURLIB" に設定)。
cwbDQ_Attr queueAttributes - input
データ待ち行列の属性へのハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
プログラミング
125
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_COMMUNICATIONS_ERROR
通信エラーが発生しました。
CWB_SERVER_PROGRAM_NOT_FOUND
IBM i アプリケーションが見つかりません。
CWB_HOST_NOT_FOUND
システムが非活動中であるか、または存在しません。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWB_SECURITY_ERROR
セキュリティー・エラーが発生しました。
CWB_LICENSE_ERROR
ライセンス・エラーが発生しました。
CWB_CONFIG_ERROR
構成エラーが発生しました。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
CWBDQ_BAD_QUEUE_NAME
待ち行列名が正しくありません。
CWBDQ_BAD_LIBRARY_NAME
ライブラリー名が正しくありません。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_USER_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBDQ_USER_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBDQ_LIBRARY_NOT_FOUND
システムにライブラリーがありません。
CWBDQ_NO_AUTHORITY
ライブラリーへの権限がありません。
CWBDQ_QUEUE_EXISTS
待ち行列が既に存在します。
126
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBDQ_QUEUE_SYNTAX
待ち行列構文が正しくありません。
CWBDQ_LIBRARY_SYNTAX
ライブラリー構文が正しくありません。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
CWB_INVALID_HANDLE
システム・ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_CreateSystem
v cwbDQ_CreateAttr
v cwbDQ_SetMaxRecLen
cwbDQ_DeleteEx:
cwbDQ_DeleteEx コマンドを使用します。
目的
IBM i データ待ち行列からすべてのデータを除去し、そのデータ待ち行列オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbDQ_DeleteEx(
cwbCO_SysHandle
const char
const char
cwbSV_ErrHandle
sysHandle
*queue,
*library,
errorHandle);
パラメーター
cwbCO_SysHandle - input
システム・オブジェクトを指すハンドル。
const char * queue - input
ASCIIZ ストリングに入っているデータ待ち行列名を指すポインター。
const char * library - input
ASCIIZ ストリングに入っているライブラリー名を指すポインター。このポインターが NULL の場合
は、現行ライブラリーが使用されます (ライブラリーを "*CURLIB" に設定)。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
プログラミング
127
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_COMMUNICATIONS_ERROR
通信エラーが発生しました。
CWB_SERVER_PROGRAM_NOT_FOUND
IBM i アプリケーションが見つかりません。
CWB_HOST_NOT_FOUND
システムが非活動中であるか、または存在しません。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWB_SECURITY_ERROR
セキュリティー・エラーが発生しました。
CWB_LICENSE_ERROR
ライセンス・エラーが発生しました。
CWB_CONFIG_ERROR
構成エラーが発生しました。
CWBDQ_BAD_QUEUE_NAME
待ち行列名が長すぎます。
CWBDQ_BAD_LIBRARY_NAME
ライブラリー名が長すぎます。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_USER_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBDQ_LIBRARY_NOT_FOUND
システムにライブラリーがありません。
CWBDQ_QUEUE_NOT_FOUND
システムに待ち行列がありません。
CWBDQ_NO_AUTHORITY
待ち行列への権限がありません。
CWBDQ_QUEUE_SYNTAX
待ち行列構文が正しくありません。
CWBDQ_LIBRARY_SYNTAX
ライブラリー構文が正しくありません。
128
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
CWB_INVALID_HANDLE
システム・ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ cwbCO_CreateSystem を発行する必要があります。
cwbDQ_OpenEx:
cwbDQ_OpenEx コマンドを使用します。
目的
指定のデータ待ち行列への接続を開始します。これによって、IBM i との会話が開始されます。正常に接
続されなかった場合は、非ゼロ・ハンドルが戻されます。
構文
unsigned int CWB_ENTRY cwbDQ_OpenEx(
cwbCO_SysHandle
const char
const char
cwbDQ_QueueHandle
cwbSV_ErrHandle
sysHandle
*queue,
*library,
*queueHandle,
errorHandle);
パラメーター
cwbCO_SysHandle sysHandle - input
システム・オブジェクトを指すハンドル。
const char * queue - input
ASCIIZ ストリングに入っているデータ待ち行列名を指すポインター。
const char * library - input
ASCIIZ ストリングに入っているライブラリー名を指すポインター。このポインターが NULL の場合
は、ライブラリー・リストが使用されます (ライブラリーを「*LIBL」に設定)。
cwbDQ_QueueHandle * queueHandle - output
ハンドルが戻される先の cwbDQ_QueueHandle を指すポインター。以降の呼び出しではすべて、このハ
ンドルを使用してください。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
プログラミング
129
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_COMMUNICATIONS_ERROR
通信エラーが発生しました。
CWB_SERVER_PROGRAM_NOT_FOUND
IBM i アプリケーションが見つかりません。
CWB_HOST_NOT_FOUND
システムが非活動中であるか、または存在しません。
CWB_COMM_VERSION_ERROR
データ待ち行列は、このバージョンの通信では稼働しません。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWB_SECURITY_ERROR
セキュリティー・エラーが発生しました。
CWB_LICENSE_ERROR
ライセンス・エラーが発生しました。
CWB_CONFIG_ERROR
構成エラーが発生しました。
CWBDQ_BAD_QUEUE_NAME
待ち行列名が長すぎます。
CWBDQ_BAD_LIBRARY_NAME
ライブラリー名が長すぎます。
CWBDQ_BAD_SYSTEM_NAME
システム名が長すぎます。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_USER_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBDQ_LIBRARY_NOT_FOUND
システムにライブラリーがありません。
CWBDQ_QUEUE_NOT_FOUND
システムに待ち行列がありません。
CWBDQ_NO_AUTHORITY
待ち行列またはライブラリーへの権限がありません。
CWBDQ_DAMAGED_QUE
待ち行列が、使えない状態になっています。
CWBDQ_CANNOT_CONVERT
データを、この待ち行列に合うように変換できません。
130
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
CWB_INVALID_HANDLE
システム・ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ cwbCO_CreateSystem を発行する必要があります。
データ待ち行列: データ待ち行列 API へのアクセス
cwbDQ_Open API を使用して、特定の IBM i データ待ち行列との接続を確立したら、これらの他の API
を呼び出して、その接続を利用します。その接続が不要になったら、cwbDQ_Close API を使用します。
cwbDQ_AsyncRead:
cwbDQ_AsyncRead コマンドを使用します。
目的
指定のハンドルで識別される IBM i データ待ち行列オブジェクトから、レコードを読み取ります。この
AsyncRead は、即時に制御権を呼び出し側に戻します。この呼び出しは、CheckData API と一緒に使用し
ます。レコードは、データ待ち行列から読み取られると、そのデータ待ち行列から除去されます。指定の待
ち時間を過ぎてもデータ待ち行列が空の場合、読み取りは打ち切られ、CheckData API によって
CWBDQ_TIMED_OUT の値が戻されます。0 から 99,999 (秒単位) か永久 (-1) の待ち時間を指定すること
が可能です。ゼロの待ち時間を指定すると、データ待ち行列にデータがない場合、 CheckData API は、最
初の呼び出し時に CWBDQ_TIMED_OUT の値を戻します。
構文
unsigned int CWB_ENTRY cwbDQ_AsyncRead(
cwbDQ_QueueHandle
cwbDQ_Data
signed long
cwbDQ_ReadHandle
cwbSV_ErrHandle
queueHandle,
data,
waitTime,
*readHandle,
errorHandle);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
cwbDQ_Data data - input
IBM i データ待ち行列から読み取られるデータ・オブジェクト。
signed long waitTime - input
データ待ち行列が空の場合、データを待つ、秒単位の時間の長さ。待機時間が -1 の場合は、永久に待
機することを示します。
プログラミング
131
cwbDQ_ReadHandle * readHandle - output
cwbDQ_ReadHandle が書き込まれる場所を指すポインター。このハンドルは、後続の
cwbDQ_CheckData API の呼び出しで使用されます。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_TIME
無効な待機時間。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_INVALID_SEARCH
無効な検索順序。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
v cwbDQ_CreateData
関連概念:
124 ページの『データ待ち行列の一般的な使用方法』
データ待ち行列は、強力なプログラム間インターフェースです。IBM i プログラミングの経験が豊富なプ
ログラマーであれば、待ち行列の使い方には慣れているはずです。データ待ち行列とは、単に、情報を別の
プログラムに渡すために使用される手段に過ぎません。
cwbDQ_Cancel:
cwbDQ_Cancel コマンドを使用します。
目的
前に出された AsyncRead を取り消します。これによって、IBM i データ待ち行列の読み取りが終了しま
す。
構文
unsigned int CWB_ENTRY cwbDQ_Cancel(
cwbDQ_ReadHandle
cwbSV_ErrHandle
132
readHandle,
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbDQ_ReadHandle readHandle - input
AsyncRead API が戻したハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_READ_HANDLE
無効な読み取りハンドル。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
v cwbDQ_CreateData
v cwbDQ_AsyncRead
cwbDQ_CheckData:
cwbDQ_CheckData コマンドを使用します。
目的
前に出された AsyncRead API からデータが戻されたかどうかを検査します。この API は、1 回の
AsyncRead 呼び出しに対して何度も出すことができます。実際にデータが戻されていれば、この API は 0
を戻します。
構文
unsigned int CWB_ENTRY cwbDQ_CheckData(
cwbDQ_ReadHandle
cwbSV_ErrHandle
readHandle,
errorHandle);
パラメーター
cwbDQ_ReadHandle readHandle - input
AsyncRead API が戻したハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
プログラミング
133
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_READ_HANDLE
無効な読み取りハンドル。
CWBDQ_DATA_TRUNCATED
データが切り捨てられました。
CWBDQ_TIMED_OUT
待機時間の有効期限が切れ、データは戻されませんでした。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_QUEUE_DESTROYED
待ち行列が破棄されました。
CWBDQ_NO_DATA
データがありません。
CWBDQ_CANNOT_CONVERT
データを変換できません。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
v cwbDQ_CreateData
v cwbDQ_AsyncRead
AsyncRead に時間限界が指定されている場合、この API は、データが戻されるまで (戻りコードは
CWB_OK)、あるいは、時間限界が過ぎるまで (戻りコードは CWBDQ_TIMED_OUT)、
CWBDQ_NO_DATA を戻します。
cwbDQ_Clear:
cwbDQ_Clear コマンドを使用します。
目的
指定のハンドルで識別される、IBM i データ待ち行列オブジェクトから、すべてのメッセージを取り除き
ます。待ち行列にキーが関連付けられている場合は、キーおよびキーの長さを指定して、特定のキーに合っ
たメッセージを取り除くこともできます。待ち行列からすべてのメッセージを消去したい場合には、キーの
値を NULL に設定し、キーの長さの値をゼロに設定します。
構文
unsigned int CWB_ENTRY cwbDQ_Clear(
cwbDQ_QueueHandle
134
queueHandle,
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned char
unsigned short
cwbSV_ErrHandle
*key,
keyLength,
errorHandle);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
unsigned char * key - input
キーを指すポインター。このキーには、組み込み NULL が含まれることがあります。したがって、こ
のキーは ASCIIZ ストリングではありません。
unsigned short keyLength - input
キーの長さ (バイト数)。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_BAD_KEY_LENGTH
キーの長さは正しくありません。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
使用法
この関数を使うには、前もって次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
cwbDQ_Close:
cwbDQ_Close コマンドを使用します。
目的
指定のハンドルで識別される IBM i データ待ち行列オブジェクトとの接続を終了します。これによって、
IBM i との会話が終了します。
構文
unsigned int CWB_ENTRY cwbDQ_Close(
cwbDQ_QueueHandle
queueHandle);
プログラミング
135
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数や cwbDQ_OpenEx 関数への先行の呼び出しで戻されたハンドル。これは IBM i デ
ータ待ち行列オブジェクトを識別します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
cwbDQ_GetLibName:
cwbDQ_GetLibName コマンドを使用します。
目的
cwbDQ_Open API で使用されるライブラリー名を検索します。
構文
unsigned int CWB_ENTRY cwbDQ_GetLibName(
cwbDQ_QueueHandle
queueHandle,
char
*libName);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
char * libName - output
ライブラリー名が書き込まれる先のバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open を発行する必要があります。
136
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbDQ_GetQueueAttr:
cwbDQ_GetQueueAttr コマンドを使用します。
目的
指定のハンドルで識別される、IBM i データ待ち行列オブジェクトの属性を検索します。データ待ち行列
属性へのハンドルが戻されます。そこで、属性を個々に検索することが可能になります。
構文
unsigned int CWB_ENTRY cwbDQ_GetQueueAttr(
cwbDQ_QueueHandle
cwbDQ_Attr
cwbSV_ErrHandle
queueHandle,
queueAttributes,
errorHandle);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
cwbDQ_Attr queueAttributes - input/output
属性オブジェクト。これは、cwbDQ_CreateAttr 呼び出しからの出力です。属性は、この関数によって
書き入れられるため、このオブジェクトから属性を検索した後で、cwbDQ_DeleteAttr 関数を呼び出し
てこのオブジェクトを削除する必要があります。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
使用法
この関数を使用する場合は、あらかじめ次の API を発行する必要があります。
v cwbDQ_Open または cwbDQ_OpenEx
v cwbDQ_CreateAttr
cwbDQ_GetQueueName:
cwbDQ_GetQueueName コマンドを使用します。
プログラミング
137
目的
cwbDQ_Open API で使用される待ち行列名を検索します。
構文
unsigned int CWB_ENTRY cwbDQ_GetQueueName(
cwbDQ_QueueHandle
queueHandle,
char
*queueName);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
char * queueName - output
待ち行列名が書き込まれる先のバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open を発行する必要があります。
cwbDQ_GetSysName:
cwbDQ_GetSysName コマンドを使用します。
目的
cwbDQ_Open API で使用されるシステム名を検索します。
構文
unsigned int CWB_ENTRY cwbDQ_GetSysName(
cwbDQ_QueueHandle
queueHandle,
char
*systemName);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
char *systemName - output
システム名が書き込まれる先のバッファーを指すポインター。
138
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open か cwbDQ_OpenEx を発行する必要があります。
cwbDQ_Peek:
cwbDQ_Peek コマンドを使用します。
目的
指定のハンドルで識別される IBM i データ待ち行列オブジェクトから、レコードを読み取ります。レコー
ドは、データ待ち行列から読み取られた後も、そのデータ待ち行列内に入れられたままとなります。データ
待ち行列が空の場合は、待機時間に 0 から 99,999 または永久 (-1) を指定して、レコードを待機すること
もできます。待機時間をゼロにすると、データ待ち行列の中にデータがない場合は、直ちに制御権が戻りま
す。
構文
unsigned int CWB_ENTRY cwbDQ_Peek(
cwbDQ_QueueHandle
cwbDQ_Data
signed long
cwbSV_ErrHandle
queueHandle,
data,
waitTime,
errorHandle);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open API への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
cwbDQ_Data data - input
IBM i データ待ち行列から読み取られるデータ・オブジェクト。
signed long waitTime - input
データ待ち行列が空の場合、データを待つ、秒単位の時間の長さ。待機時間が -1 の場合は、永久に待
機することを示します。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
プログラミング
139
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_TIME
無効な待機時間。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_INVALID_SEARCH
無効な検索順序。
CWBDQ_DATA_TRUNCATED
データが切り捨てられました。
CWBDQ_TIMED_OUT
待機時間の有効期限が切れ、データは戻されませんでした。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_QUEUE_DESTROYED
待ち行列が破棄されました。
CWBDQ_CANNOT_CONVERT
データを変換できません。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open または cwbDQ_OpenEx と cwbDQ_CreateData を発
行する必要があります。
cwbDQ_Read:
cwbDQ_Read コマンドを使用します。
目的
指定のハンドルで識別される IBM i データ待ち行列オブジェクトから、レコードを読み取ります。レコー
ドは、データ待ち行列から読み取られると、そのデータ待ち行列から除去されます。データ待ち行列が空の
場合は、待機時間に 0 から 99,999 または永久 (-1) を指定して、レコードを待機することもできます。待
機時間をゼロにすると、データ待ち行列の中にデータがない場合は、直ちに制御権が戻ります。
構文
unsigned int CWB_ENTRY cwbDQ_Read(
cwbDQ_QueueHandle
cwbDQ_Data
long
cwbSV_ErrHandle
140
queueHandle,
data,
waitTime,
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数への先行の呼び出しで戻されたハンドル。これは IBM i データ待ち行列オブジェク
トを識別します。
cwbDQ_Data data - input
IBM i データ待ち行列から読み取られるデータ・オブジェクト。
long waitTime - input
データ待ち行列が空の場合、データを待つ、秒単位の時間の長さ。待機時間が -1 の場合は、永久に待
機することを示します。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_TIME
無効な待機時間。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_INVALID_SEARCH
無効な検索順序。
CWBDQ_DATA_TRUNCATED
データが切り捨てられました。
CWBDQ_TIMED_OUT
待機時間の有効期限が切れ、データは戻されませんでした。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_QUEUE_DESTROYED
待ち行列が破棄されました。
CWBDQ_CANNOT_CONVERT
データを変換できません。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open と cwbDQ_CreateData を発行する必要があります。
cwbDQ_Write:
cwbDQ_Write コマンドを使用します。
プログラミング
141
目的
指定のハンドルで識別される、IBM i データ待ち行列オブジェクトに、レコードを書き込みます。
構文
unsigned int CWB_ENTRY cwbDQ_Write(
cwbDQ_QueueHandle
cwbDQ_Data
cwb_Boolean
cwbSV_ErrHandle
queueHandle,
data,
commit,
errorHandle);
パラメーター
cwbDQ_QueueHandle queueHandle - input
cwbDQ_Open 関数または cwbDQ_OpenEx 関数への先行の呼び出しで戻されたハンドル。これは IBM
i データ待ち行列オブジェクトを識別します。
cwbDQ_Data data - input
IBM i データ待ち行列に書き込まれる、データ・オブジェクト。
cwb_Boolean commit - input
このフラグは使用されなくなったため無視されます。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_BAD_DATA_LENGTH
データの長さが正しくありません。
CWBDQ_INVALID_MESSAGE_LENGTH
無効なメッセージ長。
CWBDQ_INVALID_QUEUE_HANDLE
待ち行列ハンドルが無効。
CWBDQ_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBDQ_CANNOT_CONVERT
データを変換できません。
使用法
この関数を使用する場合は、あらかじめ cwbDQ_Open か cwbDQ_OpenEx、および cwbDQ_CreateData を
発行する必要があります。
142
IBM i: Windows アプリケーション・パッケージ: プログラミング
データ待ち行列: 属性 API
これらの API を使用して、IBM i データ待ち行列の属性の宣言を行います。データ待ち行列の作成時やデ
ータ待ち行列属性の入手時には、属性オブジェクトを使用します。
cwbDQ_CreateAttr:
cwbDQ_CreateAttr コマンドを使用します。
目的
データ待ち行列属性オブジェクトを作成します。cwbDQ_Create API または cwbDQ_CreateEx API の入力
として使用する前に、この API によって戻されたハンドルを使用して、データ待ち行列に指定したい特定
の属性を設定することができます。このハンドルは、cwbDQ_GetQueueAttr API の入力として使用した後、
データ待ち行列の特定の属性を調べる場合にも使用することができます。
構文
cwbDQ_Attr CWB_ENTRY cwbDQ_CreateAttr(void);
パラメーター
なし (None)
戻りコード
以下は、共通の戻り値です。
cwbDQ_Attr - cwbDQ_Attr オブジェクトのハンドル。
このハンドルは、属性の入手と設定に使用します。作成後、属性オブジェクトは、次のデフォルト
値を持ちます。
v 最大レコード長 - 1000
v 順序 - FIFO (先入れ先出し法)
v 権限 - LIBCRTAUT
v 記憶装置へ強制 - FALSE
v 送信側 ID - FALSE (偽)
v キーの長さ - 0
使用法
なし (None)
cwbDQ_DeleteAttr:
cwbDQ_DeleteAttr コマンドを使用します。
目的
データ待ち行列属性を削除します。
構文
unsigned int CWB_ENTRY cwbDQ_DeleteAttr(
cwbDQ_Attr
queueAttributes);
プログラミング
143
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetAuthority:
cwbDQ_GetAuthority コマンドを使用します。
目的
他のユーザーがデータ待ち行列に対して持つ権限の属性を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetAuthority(
cwbDQ_Attr
unsigned short
queueAttributes,
*authority);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short * authority - output
権限の書き込み先である無符号短精度整数を指すポインター。この値は、次の定義済みの値のいずれか
です。
v CWBDQ_ALL
v CWBDQ_EXCLUDE
v CWBDQ_CHANGE
v CWBDQ_USE
v CWBDQ_LIBCRTAUT
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
144
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetDesc:
cwbDQ_GetDesc コマンドを使用します。
目的
データ待ち行列の記述についての属性を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetDesc(
cwbDQ_Attr
char
queueAttributes,
*description);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
char * description - output
記述が書き込まれる先の、51 文字バッファーを指すポインター。記述は、ASCIIZ ストリングです。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetForceToStorage:
cwbDQ_GetForceToStorage コマンドを使用します。
目的
レコードが待ち行列に入れられた時点で、それらのレコードを強制的に補助記憶装置に移すかどうかに関す
る属性を設定します。
プログラミング
145
構文
unsigned int CWB_ENTRY cwbDQ_GetForceToStorage(
cwbDQ_Attr
queueAttributes,
cwb_Boolean
*forceToStorage);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
cwb_Boolean * forceToStorage - output
強制記憶標識の書き込み先であるブールを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetKeySize:
cwbDQ_GetKeySize コマンドを使用します。
目的
バイト単位でのキー・サイズについての属性を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetKeySize(
cwbDQ_Attr
unsigned short
queueAttributes,
*keySize);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short * keySize - output
キー・サイズが書き込まれる先の無符号短精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
146
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetMaxRecLen:
cwbDQ_GetMaxRecLen コマンドを使用します。
目的
データ待ち行列の最大レコード長を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetMaxRecLen(
cwbDQ_Attr
unsigned long
queueAttributes,
*maxRecordLength);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned long * maxRecordLength - output
最大レコード長が書き込まれる先の無符号長精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetOrder:
cwbDQ_GetOrder コマンドを使用します。
プログラミング
147
目的
待ち行列順序についての属性を取得します。順序が CWBDQ_SEQ_LIFO の場合、最後に書き込まれたレコ
ードが最初に読み取られます (後入れ先出し法)。順序が CWBDQ_SEQ_FIFO の場合、最初に書き込まれた
レコードが最初に読み取られます (先入れ先出し法)。順序が CWBDQ_SEQ_KEYED である場合、データ
待ち行列からレコードを読み取る順序は、データ・オブジェクトの検索順序属性の値、ならびに、
cwbDQ_SetKey API に指定されたキー値に応じて異なります。複数のレコードに検索順序の条件を満たす
キーが含まれている場合は、これらのレコードの間で、FIFO (先入れ先出し法) 方式が使用されます。
構文
unsigned int CWB_ENTRY cwbDQ_GetOrder(
cwbDQ_Attr
unsigned short
queueAttributes,
*order);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short * order - output
順序が書き込まれる先の無符号短精度整数を指すポインター。指定できる値は以下のとおりです。
v CWBDQ_SEQ_LIFO
v CWBDQ_SEQ_FIFO
v CWBDQ_SEQ_KEYED
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_GetSenderID:
cwbDQ_GetSenderID コマンドを使用します。
目的
送信側に関する情報を待ち行列上のそれぞれのレコードと一緒に保持するかどうかに関する属性を取得しま
す。
148
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbDQ_GetSenderID(
cwbDQ_Attr
cwb_Boolean
queueAttributes,
*senderID);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
cwb_Boolean * senderID - output
送信側 ID 標識が書き込まれる先のブールを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_SetAuthority:
cwbDQ_SetAuthority コマンドを使用します。
目的
他のユーザーが持つデータ待ち行列への権限についての属性を設定します。
構文
unsigned int CWB_ENTRY cwbDQ_SetAuthority(
cwbDQ_Attr
unsigned short
queueAttributes,
authority);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short authority - input
システム上の他のユーザーが保持する、データ待ち行列にアクセスする権限。権限には、次のいずれか
の定義済みタイプを使用してください。
v CWBDQ_ALL
v CWBDQ_EXCLUDE
v CWBDQ_CHANGE
プログラミング
149
v CWBDQ_USE
v CWBDQ_LIBCRTAUT
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
CWBDQ_INVALID_AUTHORITY
待ち行列の権限が無効。
使用法
なし (None)
cwbDQ_SetDesc:
cwbDQ_SetDesc コマンドを使用します。
目的
データ待ち行列の記述についての属性を設定します。
構文
unsigned int CWB_ENTRY cwbDQ_SetDesc(
cwbDQ_Attr
char
queueAttributes,
*description);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
char * description - input
データ待ち行列についての記述が入っている ASCIIZ ストリングを指すポインター。記述の最大長
は、50 文字です。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
CWBDQ_INVALID_QUEUE_TITLE
待ち行列の記述が長すぎます。
150
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
なし (None)
cwbDQ_SetForceToStorage:
cwbDQ_SetForceToStorage コマンドを使用します。
目的
レコードが待ち行列に入れられた時に、それらのレコードを強制的に補助記憶装置に移すかどうかに関する
属性を設定します。
構文
unsigned int CWB_ENTRY cwbDQ_SetForceToStorage(
cwbDQ_Attr
queueAttributes,
cwb_Boolean
forceToStorage);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
cwb_Boolean forceToStorage - input
レコードが待ち行列に入れられたときに、それぞれのレコードを強制的に補助記憶装置に移すかどうか
を示すブール標識。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_SetKeySize:
cwbDQ_SetKeySize コマンドを使用します。
目的
バイトでのキー・サイズについての属性を設定します。
構文
unsigned int CWB_ENTRY cwbDQ_SetKeySize(
cwbDQ_Attr
unsigned short
queueAttributes,
keySize);
プログラミング
151
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short keySize - input
バイトでのキーのサイズ。この値は、順序が LIFO または FIFO の場合はゼロであり、キー順データ
待ち行列の場合は 1 から 256 の間の値でなければなりません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_KEY_LENGTH
キーの長さが無効。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
cwbDQ_SetMaxRecLen:
cwbDQ_SetMaxRecLen コマンドを使用します。
目的
データ待ち行列について最大レコード長を設定します。
構文
unsigned int CWB_ENTRY cwbDQ_SetMaxRecLen(
cwbDQ_Attr
unsigned long
queueAttributes,
maxRecordLength);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned long maxLength - input
データ待ち行列レコードについての最大長。この値は、1 と 31744 の間の値でなければなりません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
152
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBDQ_INVALID_QUEUE_LENGTH
無効な待ち行列レコード長。
使用法
なし (None)
cwbDQ_SetOrder:
cwbDQ_SetOrder コマンドを使用します。
目的
待ち行列の順序についての属性を設定します。順序が CWBDQ_SEQ_LIFO の場合、最後に書き込まれたレ
コードが最初に読み取られます (後入れ先出し法)。順序が CWBDQ_SEQ_FIFO の場合、最初に書き込まれ
たレコードが最初に読み取られます (先入れ先出し法)。順序が CWBDQ_SEQ_KEYED である場合、デー
タ待ち行列からレコードを読み取る順序は、データ・オブジェクトの検索順序属性の値、ならびに、
cwbDQ_SetKey API に指定されたキー値に応じて異なります。複数のレコードに検索順序の条件を満たす
キーが含まれている場合は、これらのレコードの間で、FIFO (先入れ先出し法) 方式が使用されます。
構文
unsigned int CWB_ENTRY cwbDQ_SetOrder(
cwbDQ_Attr
unsigned short
queueAttributes,
order);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
unsigned short order - input
新規の入力が待ち行列に入れられる順序。順序には、次のいずれかの定義済みタイプを使用してくださ
い。
v CWBDQ_SEQ_LIFO
v CWBDQ_SEQ_FIFO
v CWBDQ_SEQ_KEYED
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
CWBDQ_INVALID_ORDER
待ち行列の順序が無効。
使用法
なし (None)
プログラミング
153
cwbDQ_SetSenderID:
cwbDQ_SetSenderID コマンドを使用します。
目的
送信側に関する情報を待ち行列上のそれぞれのレコードと一緒に保持するかどうかに関する属性を設定しま
す。
構文
unsigned int CWB_ENTRY cwbDQ_SetSenderID(
cwbDQ_Attr
cwb_Boolean
queueAttributes,
senderID);
パラメーター
cwbDQ_Attr queueAttributes - input
cwbDQ_CreateAttr への先行の呼び出しで戻されたデータ待ち行列属性のハンドル。
cwb_Boolean senderID - input
送信側に関する情報を待ち行列に入れられているレコードと一緒に保持するかどうかに関するブール標
識。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_ATTRIBUTE_HANDLE
属性ハンドルが無効。
使用法
なし (None)
データ待ち行列: 読み取りおよび書き込み API
これらの製品 API を使用して、データ待ち行列との間で書き込みおよび読み取りを行います。
cwbDQ_CreateData:
cwbDQ_CreateData コマンドを使用します。
目的
データ・オブジェクトを作成します。作成したデータ・オブジェクトは、データ待ち行列からのデータの読
み取りとデータ待ち行列へのデータの書き込みの両方に使用します。
構文
cwbDQ_Data CWB_ENTRY cwbDQ_CreateData(void);
154
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
なし (None)
戻りコード
以下は、共通の戻り値です。
cwbDQ_Data - データ・オブジェクトのハンドル
作成後、データ・オブジェクトは、次のデフォルト値を持ちます。
v データ - NULL および長さ 0
v
キー - NULL および長さ 0
v 送信側 ID 情報 - NULL
v 検索順序 - NONE (なし)
v 変換 - FALSE (偽)
使用法
なし (None)
cwbDQ_DeleteData:
cwbDQ_DeleteData コマンドを使用します。
目的
データ・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbDQ_DeleteData(
cwbDQ_Data
data);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetConvert:
cwbDQ_GetConvert コマンドを使用します。
プログラミング
155
目的
データ・ハンドル用の変換フラグの値を取得します。この変換フラグにより、ホストへ送信したデータおよ
びホストから受信したデータが、変換された (例えば、ASCII から EBCDIC に変換された) CCSID である
かどうかが判別されます。
構文
unsigned int CWB_ENTRY cwbDQ_GetConvert(
cwbDQ_Data
cwb_Boolean
data,
*convert);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
cwb_Boolean * convert - output
変換フラグが書き込まれる先のブール値を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetData:
cwbDQ_GetData コマンドを使用します。
目的
データ・オブジェクトのデータ属性を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetData(
cwbDQ_Data
unsigned char
data,
*dataBuffer);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
156
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned char * data - output
データを指すポインター。データには、組み込み NULL が含まれている場合があります。したがっ
て、このデータは、ASCIIZ ストリングではありません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetDataAddr:
cwbDQ_GetDataAddr コマンドを使用します。
目的
データ・バッファーの位置のアドレスを取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetDataAddr(
cwbDQ_Data
unsigned char
data,
**dataBuffer);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * * data - output
バッファー・アドレスが書き込まれる場所を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_ADDRESS_NOT_SET
アドレスが cwbDQ_SetDataAddr で設定されていません。
プログラミング
157
使用法
この関数は、データが保管されている場所のアドレスを検索するのに使用します。データ・アドレスは、
cwbDQ_SetDataAddr API を使用して設定する必要があります。そうでない場合は、戻りコード
CWBDQ_ADDRESS_NOT_SET が戻されます。
cwbDQ_GetDataLen:
cwbDQ_GetDataLen コマンドを使用します。
目的
データ・オブジェクトのデータ長属性を取得します。この属性は、データ・オブジェクトの全長です。読み
取られたデータの長さを取得するには、cwbDQ_GetRetDataLen API を使用します。
構文
unsigned int CWB_ENTRY cwbDQ_GetDataLen(
cwbDQ_Data
unsigned long
data,
*dataLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned long * dataLength - output
データの長さが書き込まれる先の無符号長精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetKey:
cwbDQ_GetKey コマンドを使用します。
目的
データ・オブジェクトのキー属性で、前に cwbDQ_SetKey API によって設定されたキー属性を取得しま
す。このキーが、キー順データ待ち行列へのデータの書き込みに使用するキーです。検索順序に使う以外
に、このキーは、キー順データ待ち行列からデータを読み取る場合にも使用します。検索されたレコードと
関連したキーは、cwbDQ_GetRetKey API を呼び出すと取得することができます。
158
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbDQ_GetKey(
cwbDQ_Data
unsigned char
data,
*key);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * key - output
キーを指すポインター。このキーには、組み込み NULL が含まれることがあります。したがって、こ
のキーは、ASCIIZ ストリングではありません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetKeyLen:
cwbDQ_GetKeyLen コマンドを使用します。
目的
データ・オブジェクトのキーの長さ属性を取得します。
構文
unsigned int CWB_ENTRY cwbDQ_GetKeyLen(
cwbDQ_Data
unsigned short
data,
*keyLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned short * keyLength - output
キーの長さが書き込まれる先の無符号短精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
プログラミング
159
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetRetDataLen:
cwbDQ_GetRetDataLen コマンドを使用します。
目的
戻されたデータの長さを取得します。戻されたデータ長は、cwbDQ_Read または cwbDQ_Peek API が呼び
出されるまではゼロですが、呼び出された後は、実際に戻されたデータの長さになります。
構文
unsigned int CWB_ENTRY cwbDQ_GetRetDataLen(
cwbDQ_Data
unsigned long
data,
*retDataLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned long * retDataLength - output
戻されたデータの長さが書き込まれる先の、無符号長精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetRetKey:
cwbDQ_GetRetKey コマンドを使用します。
160
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
データ・オブジェクトの戻されたキーを取得します。これは、キー順データ待ち行列から検索されるメッセ
ージに関連したキーです。検索順序が CWBDQ_EQUAL 以外の値である場合、このキーは、メッセージの
検索に使用されたキーとは異なることがあります。
構文
unsigned int CWB_ENTRY cwbDQ_GetRetKey(
cwbDQ_Data
unsigned char
data,
*key);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * retKey - output
戻されたキーを指すポインター。このキーには、組み込み NULL が含まれることがあります。したが
って、このキーは ASCIIZ ストリングではありません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetRetKeyLen:
cwbDQ_GetRetKeyLen コマンドを使用します。
目的
データ・オブジェクトの戻されたキーの長さ属性を取得します。これは、cwbDQ_GetKey API によって戻
されるキーの長さです。
構文
unsigned int CWB_ENTRY cwbDQ_GetRetKeyLen(
cwbDQ_Data
unsigned short
data,
*retKeyLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
プログラミング
161
unsigned short * retKeyLength - output
キーの長さが書き込まれる先の無符号短精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetSearchOrder:
cwbDQ_GetSearchOrder コマンドを使用します。
目的
オープン属性の検索順序を取得します。検索順序は、検索するレコードのキーと cwbDQ_SetKey API 上に
指定されたキー値との関係の識別に使用するためにキー順データ待ち行列の読み取り時や検査時に使用され
ます。データ待ち行列順序属性が CWBDQ_SEQ_KEYED 以外の場合、このプロパティーは無視されます。
構文
unsigned int CWB_ENTRY cwbDQ_GetSearchOrder(
cwbDQ_Data
unsigned short
data,
*searchOrder);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned short * searchOrder - output
順序が書き込まれる先の無符号短精度整数を指すポインター。指定できる値は以下のとおりです。
v CWBDQ_NONE
v CWBDQ_EQUAL
v CWBDQ_NOT_EQUAL
v CWBDQ_GT_OR_EQUAL
v CWBDQ_GREATER
v CWBDQ_LT_OR_EQUAL
v CWBDQ_LESS
戻りコード
以下は、共通の戻り値です。
162
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_GetSenderInfo:
cwbDQ_GetSenderInfo コマンドを使用します。
目的
オープン属性の送信側情報属性を取得します。データ待ち行列の送信側 ID 属性が作成時に設定された場
合にのみ、この情報を使用することができます。
構文
unsigned int CWB_ENTRY cwbDQ_GetSenderInfo(
cwbDQ_Data
unsigned char
data,
*senderInfo);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * senderInfo - output
送信側情報が書き込まれる先の、36 文字バッファーを指すポインター。このバッファーには、次のも
のが入っています。
v ジョブ名 (10 バイト)
v ユーザー名 (10 バイト)
v ジョブ ID (6 バイト)
v ユーザー・プロファイル (10 バイト)
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
プログラミング
163
使用法
なし (None)
cwbDQ_SetConvert:
cwbDQ_SetConvert コマンドを使用します。
目的
変換フラグを設定します。フラグが設定されている場合、書き込まれるすべてのデータは、PC CCSID (例
えば ASCII) からホスト CCSID (例えば EBCDIC) に変換され、読み取られるすべてのデータは、ホスト
CCSID (例えば EBCDIC) から PC CCSID (例えば ASCII) に変換されます。デフォルトの設定は、データ
変換なしです。
構文
unsigned int CWB_ENTRY cwbDQ_SetConvert(
cwbDQ_Data
cwb_Boolean
data,
convert);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
cwb_Boolean convert - input
待ち行列へ書き込むデータと待ち行列から読み取るデータを、CCSID 変換するかしないかを指示する
フラグです。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
使用法
なし (None)
cwbDQ_SetData:
cwbDQ_SetData コマンドを使用します。
目的
データ・オブジェクトのデータとデータ長属性を設定します。デフォルトでは、長さはゼロでデータを持ち
ません。この関数は、データのコピーを作成します。
164
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbDQ_SetData(
cwbDQ_Data
unsigned char
unsigned long
data,
*dataBuffer,
dataLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * dataBuffer - input
データを指すポインター。データには、組み込み NULL が含まれている場合があります。したがっ
て、このデータは、ASCIIZ ストリングではありません。
unsigned long dataLength - input
バイトでのデータの長さ。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_BAD_DATA_LENGTH
データの長さが正しくありません。
使用法
この関数は、少量のデータを書き込みたい場合、またはアプリケーションの中でデータ用のメモリー管理を
行いたくない場合に使用します。データがコピーされるため、ユーザーのアプリケーションのパフォーマン
スに影響を及ぼす場合があります。
cwbDQ_SetDataAddr:
cwbDQ_SetDataAddr コマンドを使用します。
目的
データ・オブジェクトのデータとデータ長属性を設定します。デフォルトでは、長さはゼロでデータを持ち
ません。この関数は、データをコピーしません。
構文
unsigned int CWB_ENTRY cwbDQ_SetDataAddr(
cwbDQ_Data
unsigned char
unsigned long
data,
*dataBuffer,
dataLength);
プログラミング
165
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned char * dataBuffer - input
データを指すポインター。データには、組み込み NULL が含まれている場合があります。したがっ
て、このデータは、ASCIIZ ストリングではありません。
unsigned long dataLength - input
バイトでのデータの長さ。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_BAD_DATA_LENGTH
データの長さが正しくありません。
使用法
大量のデータを扱う場合、またはユーザーのアプリケーションの中でメモリーを管理したい場合には、この
関数の方が便利です。データはコピーされないため、パフォーマンスは向上します。
cwbDQ_SetKey:
cwbDQ_SetKey コマンドを使用します。
目的
データ属性のキーとキーの長さ属性を設定します。このキーが、キー順データ待ち行列へのデータの書き込
みに使用するキーです。検索順序のほかに、このキーは、キー順データ待ち行列からデータを読み取る場合
にも使用します。デフォルトでは、長さはゼロでキーを持ちません。このデフォルト値は、非キー順
(LIFO または FIFO) データ待ち行列についての正しい値です。
構文
unsigned int CWB_ENTRY cwbDQ_SetKey(
cwbDQ_Data
unsigned char
unsigned short
data,
*key,
keyLength);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
166
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned char * key - input
キーを指すポインター。このキーには、組み込み NULL が含まれることがあります。したがって、こ
のキーは、ASCIIZ ストリングではありません。
unsigned short keyLength - input
キーの長さ (バイト数)。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_BAD_KEY_LENGTH
キーの長さは正しくありません。
使用法
なし (None)
cwbDQ_SetSearchOrder:
cwbDQ_SetSearchOrder コマンドを使用します。
目的
オープン属性の検索順序を設定します。デフォルトは、検索順序なしです。 cwbDQ_SetKey API が呼び出
されると、検索順序はキー順に変更されます。別の検索順序に設定するのに、この API を使用します。検
索順序は、検索するレコードのキーと cwbDQ_SetKey API 上に指定されたキー値との関係の識別に使用す
るためにキー順データ待ち行列の読み取り時や検査時に使用されます。データ待ち行列順序属性が
CWBDQ_SEQ_KEYED 以外の場合、このプロパティーは無視されます。
構文
unsigned int CWB_ENTRY cwbDQ_SetSearchOrder(
cwbDQ_Data
unsigned short
data,
searchOrder);
パラメーター
cwbDQ_Data data - input
cwbDQ_CreateData への先行の呼び出しで戻されたデータ・オブジェクトのハンドル。
unsigned short searchOrder - input
キー順待ち行列から読み取る場合に使用する順序。指定できる値は以下のとおりです。
v CWBDQ_NONE
v CWBDQ_EQUAL
v CWBDQ_NOT_EQUAL
v CWBDQ_GT_OR_EQUAL
v CWBDQ_GREATER
プログラミング
167
v CWBDQ_LT_OR_EQUAL
v CWBDQ_LESS
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBDQ_INVALID_DATA_HANDLE
データ・ハンドルが無効。
CWBDQ_INVALID_SEARCH
無効な検索順序。
使用法
なし (None)
例: データ待ち行列 API の使用法
IBM i データ待ち行列 API の使用法について、以下の例で説明します。
// Sample Data Queues application
#ifdef UNICODE
#define _UNICODE
#define CWB_UNICODE
#endif
#include <windows.h>
// Include the necessary DQ Classes
#include <stdlib.h>
#include <iostream>
#include "cwbdq.h"
using namespace std;
/**********************************************************************/
void main()
{
cwbDQ_Attr queueAttributes;
cwbDQ_QueueHandle queueHandle;
cwbDQ_Data queueData;
// Create an attribute object
if ( (queueAttributes = cwbDQ_CreateAttr()) == 0 )
return;
// Set the maximum record length to 100
if ( cwbDQ_SetMaxRecLen(queueAttributes,
100) != 0 )
return;
// Set the order to First-In-First-Out
if (cwbDQ_SetOrder(queueAttributes, CWBDQ_SEQ_FIFO) != 0 )
return;
// obtain a handle to the system
cwbCO_SysHandle system = NULL;
if(cwbCO_CreateSystem( TEXT("SYSNAMEXXX"),&system) != 0)
return;
168
IBM i: Windows アプリケーション・パッケージ: プログラミング
// Create the data queue DTAQ in library QGPL on system SYS1
if ( cwbDQ_CreateEx(system,
TEXT("DTAQX"),
TEXT("QGPL"),
queueAttributes,
NULL) != 0 )
return;
// Delete the attributes
if ( cwbDQ_DeleteAttr( queueAttributes ) != 0 )
return;
// Open the data queue
if ( cwbDQ_OpenEx(system,
TEXT("DTAQ"),
TEXT("QGPL"),
&queueHandle,
NULL) != 0 )
return;
// Create a data object
if ( (queueData = cwbDQ_CreateData()) == 0 )
return;
// Set the data length and the data
if ( cwbDQ_SetData(queueData, (unsigned char*)"Test Data!", 10) != 0 )
return;
// Write the data to the data queue
if ( cwbDQ_Write(queueHandle, queueData, CWB_TRUE, NULL) != 0 )
return;
// Delete the data object
if ( cwbDQ_DeleteData(queueData) != 0 )
return;
// Close the data queue
if ( cwbDQ_Close(queueHandle) != 0 )
return;
}
データ形式変更および各国語サポート (NLS) API
データ形式変更および各国語サポート (NLS) API を使用して、ご使用のアプリケーションで製品データの
形式変更を行えるようにします。
データ形式変更 API
製品のデータ形式変換アプリケーション・プログラミング・インターフェース (API) を使用すると、クラ
イアント/サーバー・アプリケーションで IBM i 数値データの形式変更 (システム形式と PC 形式との相互
変更) を行えるようになります。 IBM i 数値データの送受信をシステムとの間で行う場合に、形式変更が
必要になることがあります。データ形式変更 API は、数多くの数値形式の変換をサポートします。
データ形式変更 API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbdt.h
cwbapi.lib
cwbdt.dll
プログラミング
169
Programmer's Toolkit:
Programmer's Toolkit には、データ形式変更の資料、cwbdt.h ヘッダー・ファイルへのアクセス、およびプ
ログラム例へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit をオープ
ンして、「データ操作」 > 「C/C++ API」と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
データ形式変更 API リスト:
以下のデータ形式変更 API は、アルファベット順にリストされています。
注: ストリングを受け入れるデータ形式変更 API は、ユニコード・バージョンで提供されます。これらの
API の場合、「ASCII」は「Wide」で置換されます (例えば、cwbDT_ASCII11ToBin4 のユニコード・バー
ジョンは cwbDT_Wide11ToBin4 になります)。以下の表は、これらの API を示しています。ユニコード・
バージョンは、それらに対応している ASCII バージョンとは異なる構文、パラメーター、および戻り値を
使用します。
cwbDT_ASCII11ToBin4:
cwbDT_ASCII11ToBin4 コマンドを使用します。
目的
11 桁の ASCII 数字を、有効桁の最高位バイトを最初に保管して、4 バイト整数に (正確に) 変換します。
(ソース・ストリングはゼロで終わっていなくてもかまいません。)この関数を使用すると、ASCII 数値デー
タを IBM i 整数形式に変換することができます。
ユニコード・バージョン
cwbDT_Wide11ToBin4
構文
unsigned int CWB_ENTRY cwbDT_ASCII11ToBin4(
char *target,
char *source);
パラメーター
char * target - output
ターゲット (4 バイト整数) を指すポインター。
char * source - input
ソース (11 バイトの ASCII) を指すポインター。
170
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
CWB_BUFFER_OVERFLOW
オーバーフロー・エラー。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
ターゲット・データは、有効桁の最高位バイトが最初に保管されます。これはシステムが使用する IBM i
形式であり、Intel x86 プロセッサーが使用する形式とは逆になっています。 ASCII ソース・データで有効
な形式は以下のとおりです。
v [blankspaces][sign][blankspaces][digits] または
v [sign][blankspaces][digits][blankspaces]
例:
" +
123"
"123 "
"
+123 "
"
123"
"
-123"
"+123
"
cwbDT_ASCII6ToBin2:
cwbDT_ASCII6ToBin2 コマンドを使用します。
目的
6 桁の ASCII 数字を、有効桁の最高位バイトを最初に保管して、2 バイト整数に (正確に) 変換します。
(ソース・ストリングはゼロで終わっていなくてもかまいません。)この関数を使用すると、ASCII 数値デー
タを IBM i 整数形式に変換することができます。
ユニコード・バージョン
cwbDT_Wide6ToBin2
構文
unsigned int CWB_ENTRY cwbDT_ASCII6ToBin2(
char *target,
char *source);
パラメーター
char * target - output
ターゲット (2 バイト整数) を指すポインター。
プログラミング
171
char * source - input
ソース (6 バイト ASCII) を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
CWB_BUFFER_OVERFLOW
オーバーフロー・エラー。
最初の非変換文字に 1 を加えたオフセット。
other
使用法
ターゲット・データは、有効桁の最高位バイトが最初に保管されます。これはシステムが使用する IBM i
形式であり、Intel x86 プロセッサーが使用する形式とは逆になっています。 ASCII ソース・データで有効
な形式は以下のとおりです。
v [blankspaces][sign][blankspaces][digits] または
v [sign][blankspaces][digits][blankspaces]
例:
" + 123"
"- 123 "
" +123 "
" 123"
" -123"
"+123 "
cwbDT_ASCIIPackedToPacked:
cwbDT_ASCIIPackedToPacked コマンドを使用します。
目的
ASCII パック形式のデータをパック 10 進数に変換します。この関数は、ASCII ファイルのデータを、
IBM i 形式に変換するために使用します。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_ASCIIPackedToPacked(
char
*target,
char
*source,
unsigned long length);
172
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。この関数
は、パック 10 進数データの各ハーフバイトが 0 から 9 までの範囲内にあるかどうかを検査します。最後
のハーフバイトは例外で、ここには符号標識 (0x3 または 0xb) が入ります。
cwbDT_ASCIIToHex:
cwbDT_ASCIIToHex コマンドを使用します。
目的
データを ASCII (16 進表示) から 2 進数に変換します。ソース中の 2 バイトごとに、1 バイトがターゲ
ットに保管されます。
ユニコード・バージョン
cwbDT_WideToHex
構文
unsigned int CWB_ENTRY cwbDT_ASCIIToHex(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース (ASCII 16 進数) データを指すポインター。
プログラミング
173
unsigned long length - input
変換するソース・データのバイト数 /2。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
最初の非変換文字に 1 を加えたオフセット。
other
使用法
ソース・データの '長さ' バイトに対して、'長さ'/2 バイトのターゲット・データが保管されます。呼び出し
側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。
cwbDT_ASCIIToPacked:
cwbDT_ASCIIToPacked コマンドを使用します。
目的
ASCII 数値データをパック 10 進数形式に変換します。この関数を使用すると、ASCII テキスト・データ
を、IBM i プラットフォームで使用できるように変換することができます。
ユニコード・バージョン
cwbDT_WideToPacked
構文
unsigned int CWB_ENTRY cwbDT_ASCIIToPacked(
char
*target,
char
*source,
unsigned long length,
unsigned long decimalPosition);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。ゼロで終わる必要があります。
unsigned long length - input
変換するターゲット・データのバイト数。
unsigned long decimalPosition - input
小数点の位置。
戻りコード
以下は、共通の戻り値です。
174
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
CWB_BUFFER_OVERFLOW
オーバーフロー・エラー。
CWB_NOT_ENOUGH_MEMORY
一時メモリーの割り振りができません。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。符号用の
ハーフバイトには、負数を表す場合は 16 進の 0xd がセットされ、正数を表す場合は 0xc がセットされま
す。0 <= 小数点位置 < (長さ * 2)。 ASCII 数値データで有効な形式は以下のとおりです。
v [blankspaces][sign][blankspaces][digits] または
v [sign][blankspaces][digits][blankspaces] または
v [sign][digits][.digits][blankspaces] または
v [blankspaces][sign][digits][.digits][blankspaces]
例:
" + 123¥0"
"- 123 ¥0"
"
+123 ¥0"
"
123¥0"
"
-12.3¥0"
"+1.23
¥0"
cwbDT_ASCIIToZoned:
cwbDT_ASCIIToZoned コマンドを使用します。
目的
ASCII 数値データを EBCDIC ゾーン 10 進形式に変換します。この関数を使用すると、ASCII テキスト・
データを、IBM i プラットフォームで使用できるように変換することができます。
ユニコード・バージョン
cwbDT_WideToZoned
構文
unsigned int CWB_ENTRY cwbDT_ASCIIToZoned(
char
*target,
char
*source,
unsigned long length,
unsigned long decimalPosition);
プログラミング
175
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。ゼロで終わる必要があります。
unsigned long length - input
変換するターゲット・データのバイト数。
unsigned long decimalPosition - input
小数点の位置。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
CWB_BUFFER_OVERFLOW
オーバーフロー・エラー。
CWB_NOT_ENOUGH_MEMORY
一時メモリーの割り振りができません。
最初の非変換文字に 1 を加えたオフセット。
other
使用法
呼び出し側は、ターゲット情報を保持するための十分のスペースを確保しておく必要があります。符号用の
ハーフバイトには、負数を表す場合は 16 進の 0xd がセットされ、正数を表す場合は 0xc がセットされま
す。0 <= 小数点位置 <= 長さです。ASCII 数値データで有効な形式は以下のとおりです。
v [blankspaces][sign][blankspaces][digits] または
v [sign][blankspaces][digits][blankspaces] または
v [sign][digits][.digits][blankspaces] または
v [blankspaces][sign][digits][.digits][blankspaces]
例:
" + 123¥0"
"- 123 ¥0"
"
+123 ¥0"
"
123¥0"
"
-12.3¥0"
"+1.23
¥0"
cwbDT_ASCIIZonedToZoned:
cwbDT_ASCIIZonedToZoned コマンドを使用します。
176
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
データを、ASCII ゾーン 10 進形式から EBCDIC ゾーン 10 進数に変換します。この関数を使用すると、
ASCII ファイルのデータを変換して、IBM i プラットフォームで使用可能にすることができます。
ユニコード・バージョン
なし。
構文
unsigned int CWB_ENTRY cwbDT_ASCIIZonedToZoned(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
ASCII ゾーン 10 進形式中の各バイトの左半分 (0x3) は、最後のバイト (符号) を除き EBCDIC ゾーン・
データの左のハーフバイト中の 0xf に変換されます。ASCII ゾーン 10 進データ中の各バイトの左半分
は、最後のバイトを除き 0x3 でなければなりません。この関数はそれを検査します。最後のバイトの高位
の半分は 0x3 または 0xb でなければなりません。ASCII ゾーン 10 進データ中の各バイトの右半分は 0
から 9 の範囲内でなければなりません。
cwbDT_Bin2ToASCII6:
cwbDT_Bin2ToASCII6 コマンドを使用します。
目的
有効桁の最高位バイトを最初に保管した 2 バイト整数を、(正確に) 6 桁の ASCII 数字に変換します。
(ターゲットはゼロで終わりません。) この関数を使用すると、IBM i の数値データを ASCII に変換するこ
とができます。
プログラミング
177
ユニコード・バージョン
cwbDT_Bin2ToWide6
構文
unsigned int CWB_ENTRY cwbDT_Bin2ToASCII6(
char *target,
char *source);
パラメーター
char * target - output
ターゲット (6 バイト) の領域を指すポインター。
char * source - input
ソース (2 バイト整数) を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
使用法
ソース・データには、有効桁の最高位バイトが最初に保管されるものと想定します。これはシステムが使用
する IBM i 形式であり、Intel x86 プロセッサーが使用する形式とは逆になっています。
cwbDT_Bin2ToBin2:
cwbDT_Bin2ToBin2 コマンドを使用します。
目的
2 バイト整数のバイトの順序を入れ替えます。この関数を使用すると、2 バイトの整数と IBM i 形式とを
相互に変換することができます。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_Bin2ToBin2(
char *target,
char *source);
パラメーター
char * target - output
ターゲット (2 バイト整数) を指すポインター。
178
IBM i: Windows アプリケーション・パッケージ: プログラミング
char * source - input
ソース (2 バイト整数) を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
使用法
ソース・データとターゲット・データはオーバーラップしてはなりません。以下に、この変換の結果の例を
示します。
v ソース・データ: 0x1234
v ターゲット・データ: 0x3412
cwbDT_Bin4ToASCII11:
cwbDT_Bin4ToASCII11 コマンドを使用します。
目的
有効桁の最高位バイトを最初に保管した 4 バイト整数を、(正確に) 11 桁の ASCII 数字に変換します。
(ターゲットはゼロで終わりません。) この関数を使用すると、IBM i の数値データを ASCII に変換するこ
とができます。
ユニコード・バージョン
cwbDT_Bin4ToWide11
構文
unsigned int CWB_ENTRY cwbDT_Bin4ToASCII11(
char *target,
char *source );
パラメーター
char * target - output
ターゲット (11 バイト) 域を指すポインター。
char * source - input
ソース (4 バイト整数) を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
179
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
使用法
ソース・データには、有効桁の最高位バイトが最初に保管されるものと想定します。これはシステムが使用
する IBM i 形式であり、Intel x86 プロセッサーが使用する形式とは逆になっています。
cwbDT_Bin4ToBin4:
cwbDT_Bin4ToBin4 コマンドを使用します。
目的
4 バイト整数のバイトの順序を入れ替えます。この関数を使用すると、4 バイトの整数と IBM i 形式とを
相互に変換することができます。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_Bin4ToBin4(
char *target,
char *source);
パラメーター
char * target - output
ターゲット (4 バイト整数) を指すポインター。
char * source - input
ソース (4 バイト整数) を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
使用法
ソース・データとターゲット・データはオーバーラップしてはなりません。以下に、この変換の結果の例を
示します。
v ソース・データ: 0x12345678
v ターゲット・データ: 0x78563412
cwbDT_EBCDICToEBCDIC:
cwbDT_EBCDICToEBCDIC コマンドを使用します。
180
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
EBCDIC データを EBCDIC に変換 (0x40 よりも小さい文字値の場合を除き、コピー) します。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_EBCDICToEBCDIC(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するターゲット・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。
cwbDT_HexToASCII:
cwbDT_HexToASCII コマンドを使用します。
目的
2 進データを ASCII 16 進表示に変換します。ソース・データのバイトごとに、2 桁の ASCII 文字がター
ゲットに保管されます。
ユニコード・バージョン
cwbDT_HexToWide
プログラミング
181
構文
unsigned int CWB_ENTRY cwbDT_HexToASCII(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット (ASCII 16 進) データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
使用法
ソース・データの '長さ' バイトに対して、ターゲット・データの '長さ'*2 バイトが保管されます。呼び出
し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。
cwbDT_PackedToASCII:
cwbDT_PackedToASCII コマンドを使用します。
目的
データをパック 10 進数形式から ASCII 数値データに変換します。この関数を使用すると、システムの
IBM i データを、ASCII テキスト形式で使用できるように変換することができます。
ユニコード・バージョン
cwbDT_PackedToWide
構文
unsigned int CWB_ENTRY cwbDT_PackedToASCII(
char
*target,
char
*source,
unsigned long length,
unsigned long decimalPosition);
パラメーター
char * target - output
ターゲット・データを指すポインター。
182
IBM i: Windows アプリケーション・パッケージ: プログラミング
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
unsigned long decimalPosition - input
小数点の位置。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。この関数
は、パック 10 進数データの各ハーフバイトが 0 から 9 までの範囲内にあるかどうかを検査します。最後
のハーフバイトは例外で、ここには符号標識が入ります。 0 <= 小数点位置 < (長さ * 2)。
cwbDT_PackedToASCIIPacked:
cwbDT_PackedToASCIIPacked コマンドを使用します。
目的
データをパック 10 進数形式から ASCII パック形式に変換します。この関数を使用すると、システムの
IBM i データを、ASCII 形式で使用できるように変換することができます。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_PackedToASCIIPacked(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
プログラミング
183
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
最初の非変換文字に 1 を加えたオフセット。
other
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。この関数
は、パック 10 進数データの各ハーフバイトが 0 から 9 までの範囲内にあるかどうかを検査します。最後
のハーフバイトは例外で、ここには符号標識 (0 から 9、0xd または 0xb のいずれも可) が入ります。
cwbDT_PackedToPacked:
cwbDT_PackedToPacked コマンドを使用します。
目的
パック 10 進データをパック 10 進数に変換します。この関数を使用すると、システムの IBM i データと
非変換ファイルとを相互に変換できるようになります。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_PackedToPacked(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
184
IBM i: Windows アプリケーション・パッケージ: プログラミング
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。この関数
は、パック 10 進数データの各ハーフバイトが 0 から 9 までの範囲内にあるかどうかを検査します。最後
のハーフバイトは例外で、ここには符号標識が入ります。
cwbDT_ZonedToASCII:
cwbDT_ZonedToASCII コマンドを使用します。
目的
EBCDIC ゾーン 10 進データを ASCII 数値形式に変換します。この関数を使用すると、システムの IBM i
データを、ASCII テキスト形式で使用できるように変換することができます。
ユニコード・バージョン
cwbDT_ZonedToWide
構文
unsigned int CWB_ENTRY cwbDT_ZonedToASCII(
char
*target,
char
*source,
unsigned long length,
unsigned long decimalPosition);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
unsigned long decimalPosition - input
小数点の位置。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
CWB_BUFFER_OVERFLOW
オーバーフロー・エラー。
other
最初の非変換文字に 1 を加えたオフセット。
プログラミング
185
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。ゾーン・
データの最後のバイトの高位の半分はその数値の符号を表します。高位のハーフバイトが 0xb または 0xd
の場合は負数を表します。それ以外の値の場合は正数を表します。ゾーン・データの各バイトの高位の半分
は、最後のバイトを除き 0xf でなければなりません。この関数はそれを検査します。ゾーン・データの各
バイトの低位の半分は 0 から 9 の範囲内でなければなりません。 0 <= 小数点位置 < 長さ。
cwbDT_ZonedToASCIIZoned:
cwbDT_ZonedToASCIIZoned コマンドを使用します。
目的
データを、EBCDIC ゾーン 10 進形式から ASCII ゾーン 10 進数に変換します。この関数を使用すると、
システムの IBM i データを、ASCII ファイルで使用できるように変換することができます。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_ZonedToASCIIZoned(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
最初の非変換文字に 1 を加えたオフセット。
other
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。EBCDIC
ゾーン 10 進データ中の左のハーフバイト (0xf) は、最後のバイト (符号) を除き ASCII ゾーン 10 進デ
ータの左のハーフバイト中の 0x3 に変換されます。EBCDIC ゾーン 10 進データの最後のバイトの高位の
半分はその数値の符号を表します。高位のハーフバイトが 0xb または 0xd の場合は負数を表し、それ以外
186
IBM i: Windows アプリケーション・パッケージ: プログラミング
の値の場合は正数を表します。EBCDIC ゾーン 10 進データの各バイトの高位の半分は、最後のバイトを
除き 0xf でなければなりません。この関数はそれを検査します。EBCDIC ゾーン 10 進データの各バイト
の低位の半分は 0 から 9 の範囲内でなければなりません。
cwbDT_ZonedToZoned:
cwbDT_ZonedToZoned コマンドを使用します。
目的
データを、ゾーン 10 進形式からゾーン 10 進数に変換します。この関数を使用すると、システムの IBM
i データを変換して、非変換ファイルで使用することができ、その反対の変換を行うことも可能になりま
す。
ユニコード・バージョン
なし
構文
unsigned int CWB_ENTRY cwbDT_ZonedToZoned(
char
*target,
char
*source,
unsigned long length);
パラメーター
char * target - output
ターゲット・データを指すポインター。
char * source - input
ソース・データを指すポインター。
unsigned long length - input
変換するソース・データのバイト数。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
呼び出し側から、NULL ポインターが渡されました。
other
最初の非変換文字に 1 を加えたオフセット。
使用法
呼び出し側は、ターゲット情報を保持するための十分なスペースを確保しておく必要があります。ゾーン・
データの最後のバイトの高位の半分はその数値の符号を表します。高位のハーフバイトが 0xb または 0xd
の場合は負数を表し、それ以外の値の場合は正数を表します。ゾーン・データの各バイトの高位の半分は、
最後のバイトを除き 0xf でなければなりません。この関数はそれを検査します。ゾーン・データの各バイ
トの低位の半分は 0 から 9 の範囲内でなければなりません。
プログラミング
187
例: データ形式変更 API の使用法:
データ形式変更 API の使用法をこの例で説明します。
/*******************************************************************/
/* Sample Data Transform Program using cwbDT_Bin4ToBin4 to reverse */
/* the order of bytes in a 4-byte integer.
*/
/*******************************************************************/
#include <iostream>
using namespace std;
#include "cwbdt.h"
void main()
{
unsigned int returnCode;
long source,
target;
cout << "Enter source number:¥n";
while (cin >> source) {
cout << "Source in Dec = " << dec << source;
cout << "¥nSource in Hex = " << hex << source << ’¥n’;
if (((returnCode = cwbDT_Bin4ToBin4((char *)&target,(char *)&source)) == CWB_OK)) {
cout << "Target in Dec = " << dec << target;
cout << "¥nTarget in Hex = " << hex << target << ’¥n’;
} else {
cout << "Conversion failed, Return code = " << returnCode << ’¥n’ ;
}; /* endif */
cout << "¥nEnter source number:¥n";
}; /* endwhile */
}
各国語サポート (NLS) API
各国語サポート API によって、各国の言語バージョンに関連した製品の設定値の取得および保存 (照会お
よび変更) を、アプリケーションで行えるようになります。
製品では、NLS を通じて各国語をサポートします。 NLS によって、ユーザーは、システム上で選択した
言語で作業することができます。また、このサポートによって、システムとの間で送受信されるデータを、
意図どおりの形式と順序で表示させることができます。数多くの異なる言語をサポートすることによって、
言語的ならびに文化的観点の双方から、システムを意図したとおりに動作させます。
すべての IBM i 関数が、システム上でユーザーが使用する言語に関係なく、共通のプログラム・コードの
セットを使用します。例えば、米国英語バージョンの IBM i プログラム・コードと、スペイン語バージョ
ンの IBM i プログラム・コードは、同じものです。ただし、異なる言語においては、異なるセットのテキ
スト・データが使用されます。ここでいうテキスト・データとは、メニュー、画面、リスト、プロンプト、
オプション、オンライン・ヘルプ情報、およびメッセージを一括して指す用語です。これは、次のことを意
味します。すなわち、米国英語システムでは、オンライン・ヘルプ情報に対する機能キーの説明に Help が
表示されますが、スペイン語システムでは Ayuda が表示されます。同じプログラム・コードを異なるテキ
スト・データ群と共に使用することによって、システムは、単一システム上で複数の言語をサポートする
ことができます。
これらの API を使用すると、次の操作を行うための機能をはじめとする便利な機能を、製品アプリケーシ
ョンに追加することができるようになります。
188
IBM i: Windows アプリケーション・パッケージ: プログラミング
v インストール済みの各国語のリストから選択する。
v ある 1 つのコード・ページから別のコード・ページに文字データを変換する。これによって、パーソナ
ル・コンピューターと IBM i オペレーティング・システムのように、異なるコード・ページを使用する
コンピューターで情報を共用することが可能になります。
v ダイアログ・ボックス内の変換可能なテキスト (表題およびコントロール名) を自動的に置換する。これ
によって、コントロールのサイズが、それらに関連しているテキストに応じて拡張されます。ダイアロ
グ・ボックス・フレームのサイズも自動的に調整されます。
注: プログラムを設計するに当たっては、その開始時点から各国語サポートに関する考慮事項を組み込んで
おくことが必要です。プログラムを設計、あるいはコード化し終わってからでは、NLS または DBCS サポ
ートを追加することは非常に困難です。
NLS API に必要なファイル
NLS API タイプ
ヘッダー・ファイル
インポート・ライブラリ
ー
ダイナミック・リンク・
ライブラリー
その他
cwbnl.h
cwbapi.lib
cwbnl.dll
変換
cwbnlcnv.h
cwbcore.dll
ダイアログ・ボックス
cwbnldlg.h
cwbnldlg.dll
Programmer's Toolkit:
Programmer's Toolkit には、NLS 資料、NLS API ヘッダー・ファイルへのアクセス、およびプログラム例
へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit をオープンして、
「データ操作」 > 「C/C++ API」と選択します。
関連資料:
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
コード化文字セット:
製品では、文字エンコード・スキームを使用します。
グラフィック文字とは、文字、数字や句読点の記号のような、印刷可能な記号または画面表示可能な記号の
ことです。グラフィック文字の集合はグラフィック文字セットと呼ばれ、多くの場合、省略して文字セッ
トと呼ばれます。
各言語には、正しく印刷したり画面表示したりするための独自のグラフィック文字セットが必要です。文字
は、コード・ページに従ってエンコードされます。コード・ページとは、グラフィック文字および制御文
字を、コード・ポイントと呼ばれる特定の値に割り当てるテーブルのことです。
コード・ページは、そのエンコード・スキームに従って多くのタイプに分類されます。IBM i Access
Family には、ホスト・コード・ページと PC コード・ページの、2 つの重要なエンコード・スキームがあ
ります。ユニコードもまた、重要なエンコード・スキームになりつつあります。ユニコードは、ホストおよ
びパーソナル・コンピューターの両方において一般的になりつつある、16 ビットの世界的文字エンコー
ド・スキームです。
プログラミング
189
v ホスト・コード・ページは、IBM 標準の拡張 2 進化 10 進コード (EBCDIC) に沿ってエンコードさ
れ、通常 S/390® および IBM i プラットフォームで使用されます。
v PC コード・ページは ANSI X3.4、ASCII に基づいてエンコードされ、通常 IBM パーソナル・コンピ
ューターで使用されます。
汎用 NLS API のリスト:
汎用 NLS API を使用します。
この製品は、多くの言語に翻訳されています。 1 つまたは複数の言語をパーソナル・コンピューターにイ
ンストールすることができます。以下の汎用 NLS API を使用すると、アプリケーションで次の作業ができ
るようになります。
v インストール済み言語のリストを取得する。
v 現行の言語設定値を取得する。
v 言語設定値を保管する。
cwbNL_FindFirstLang:
cwbNL_FindFirstLang コマンドを使用します。
目的
使用可能な最初の言語を戻します。
構文
unsigned int CWB_ENTRY cwbNL_FindFirstLang(
char
char
unsigned short
unsigned short
unsigned long
cwbSV_ErrHandle
*mriBasePath,
*resultPtr,
resultLen,
*requiredLen,
*searchHandle,
errorHandle);
パラメーター
char * mriBasePath - input
mriBasePath を指すポインター (例えば C:¥Program Files¥IBM¥ClientAccess)。 NULL の場合は、プロ
ダクトの mriBasePath が使用されます。
char * resultPtr - output
結果を入れるバッファーを指すポインター。
unsigned short resultLen - input
結果を入れるバッファーの長さ。推奨サイズは CWBNL_MAX_LANG_SIZE です。
unsigned short * requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
unsigned long * searchHandle - output
後続の cwbNL_FindNextLang への呼び出しで渡される検索ハンドル。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
190
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_FILE_NOT_FOUND
ファイルが見付かりませんでした。
CWB_PATH_NOT_FOUND
パスが見付かりませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
使用法
結果を入れるバッファーに言語が入ります。
cwbNL_FindNextLang:
cwbNL_FindNextLang コマンドを使用します。
目的
使用可能な次の言語を戻します。
構文
unsigned int CWB_ENTRY cwbNL_FindNextLang(
char
*resultPtr,
unsigned short
resultLen,
unsigned short *requiredLen,
unsigned long
*searchHandle,
cwbSV_ErrHandle errorHandle);
パラメーター
char * resultPtr - output
結果を入れるバッファーを指すポインター。
unsigned short resultLen - input
結果を入れるバッファーの長さ。推奨サイズは CWBNL_MAX_LANG_SIZE です。
プログラミング
191
unsigned short * requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
unsigned long * searchHandle - output
後続の cwbNL_FindNextLang への呼び出しで渡される検索ハンドル。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NO_MORE_FILES
これ以上ファイルは見付かりません。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
使用法
結果を入れるバッファーに言語が入ります。
cwbNL_GetLang:
cwbNL_GetLang コマンドを使用します。
目的
現行の言語設定値を取得します。
構文
unsigned int CWB_ENTRY cwbNL_GetLang(
char
*mriBasePath,
char
*resultPtr,
unsigned short resultLen,
unsigned short *requiredLen,
cwbSV_ErrHandle errorHandle);
192
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
char * mriBasePath - input
mriBasePath を指すポインター (例えば C:¥Program Files¥IBM¥ClientAccess)。 NULL の場合は、プロ
ダクトの mriBasePath が使用されます。
char * resultPtr - output
結果を入れるバッファーを指すポインター。
unsigned short resultLen - input
結果を入れるバッファーの長さ。推奨サイズは CWBNL_MAX_LANG_SIZE です。
unsigned short * requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎて結果を入れることができません。
使用法
結果を入れるバッファーには、言語サブディレクトリーの名前が入ります。この言語サブディレクトリーに
は言語特有のファイルが入っています。この言語サブディレクトリー名も、cwbNL_GetLangName に渡すこ
とができます。
cwbNL_GetLangName:
cwbNL_GetLangName コマンドを使用します。
目的
言語設定値の記述名を戻します。
構文
unsigned int CWB_ENTRY cwbNL_GetLangName(
char
*lang,
プログラミング
193
char
*resultPtr,
unsigned short resultLen,
unsigned short *requiredLen,
cwbSV_ErrHandle errorHandle);
パラメーター
char * lang - input
言語を表す ASCIIZ ストリングのアドレス。
char * resultPtr - output
結果を入れるバッファーを指すポインター。
unsigned short resultLen - input
結果を入れるバッファーの長さ。推奨サイズは CWBNL_MAX_NAME_SIZE です。
unsigned short * requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
使用法
言語は、次のいずれかの API から戻される値でなければなりません。
v cwbNL_GetLang
v cwbNL_FindFirstLang
v cwbNL_FindNextLang
cwbNL_GetLangPath:
cwbNL_GetLangPath コマンドを使用します。
194
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
言語ファイルについて、完全なパスを戻します。
構文
unsigned int CWB_ENTRY cwbNL_GetLangPath(
char
*mriBasePath,
char
*resultPtr,
unsigned short
resultLen,
unsigned short *requiredLen,
cwbSV_ErrHandle errorHandle);
パラメーター
char * mriBasePath - input
mriBasePath を指すポインター (例えば C:¥Program Files¥IBM¥ClientAccess)。 NULL の場合は、プロ
ダクトの mriBasePath が使用されます。
char * resultPtr - output
結果を入れるバッファーを指すポインター。
unsigned short resultLen - input
結果を入れるバッファーの長さ。推奨サイズは CWBNL_MAX_PATH_SIZE です。
unsigned short * requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_PATH_NOT_FOUND
パスが見付かりませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
プログラミング
195
使用法
結果を入れるバッファーには言語サブディレクトリーの完全なパスが入ります。言語ファイルはこのパスか
らロードしてください。
cwbNL_SaveLang:
cwbNL_SaveLang コマンドを使用します。
目的
言語設定値をプロダクト・レジストリーに保管します。
構文
unsigned int CWB_ENTRY cwbNL_SaveLang(
char
*lang,
cwbSV_ErrHandle errorHandle);
パラメーター
char * lang - input
言語を表す ASCIIZ ストリングのアドレス。
cwbSV_ErrHandle errorHandle - input
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle() API で作成されます。メッセージは、cwbSV_GetErrText() API を介して検索
することができます。パラメーターがゼロに設定されている場合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
言語は、次のいずれかの API から戻される値でなければなりません。
v cwbNL_GetLang
v cwbNL_FindFirstLang
v cwbNL_FindNextLang
以下の API は、この呼び出しによって影響を受けます。
v cwbNL_GetLang
v cwbNL_GetLangPath
196
IBM i: Windows アプリケーション・パッケージ: プログラミング
変換 NLS API のリスト:
このトピックでは、変換 NLS API について説明します。
以下の変換 NLS API を使用すると、アプリケーションで次のことが行えるようになります。
v ある 1 つのコード・ページから別のコード・ページに文字データを変換する。
v 現行のコード・ページ設定値を入手する。
v 最新の CCSID 設定値を判別する。
v コード・ページ値とコード化文字セット識別コード (CCSID) との間の変換を行う。
cwbNL_CCSIDToCodePage:
cwbNL_CCSIDToCodePage コマンドを使用します。
目的
CCSID をコード・ページにマップします。
構文
unsigned int CWB_ENTRY cwbNL_CCSIDToCodePage(
unsigned long
CCSID,
unsigned long *codePage,
cwbSV_ErrHandle errorHandle);
パラメーター
unsigned long CCSID - input
コード・ページに変換する CCSID。
unsigned long * codePage - output
結果のコード・ページ。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
プログラミング
197
使用法
なし (None)
cwbNL_CodePageToCCSID:
cwbNL_CodePageToCCSID コマンドを使用します。
目的
コード・ページを CCSID にマップします。
構文
unsigned int CWB_ENTRY cwbNL_CodePageToCCSID(
unsigned long codePage,
unsigned long *CCSID,
cwbSV_ErrHandle errorHandle);
パラメーター
unsigned long codePage - input
CCSID に変換するコード・ページ。
unsigned long * CCSID - output
結果の CCSID。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
なし (None)
cwbNL_Convert:
cwbNL_Convert コマンドを使用します。
198
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
前にオープンしたコンバーターを使用してストリングを変換します。
構文
unsigned int CWB_ENTRY cwbNL_Convert(
cwbNL_Converter theConverter,
unsigned long
sourceLength,
unsigned long
targetLength,
char
*sourceBuffer,
char
*targetBuffer,
unsigned long *numberOfErrors,
unsigned long *firstErrorIndex,
unsigned long *requiredLen,
cwbSV_ErrHandle errorHandle);
パラメーター
cwbNL_Converter theConverter - output
前にオープンされたコンバーターへのハンドル。
unsigned long sourceLength - input
ソース・バッファーの長さ。
unsigned long targetLength - input
ターゲット・バッファーの長さ。DBCS 文字を含む ASCII コード・ページを変換する場合は、その結
果のデータにはシフトアウト・バイトおよびシフトイン・バイトが含まれている可能性があることに留
意してください。したがって、targetBuffer は sourceBuffer よりも大きくしておく必要があります。
char *sourceBuffer - input
変換すべきデータが入っているバッファー。
char *targetBuffer - output
変換されたデータが入るバッファー。
unsigned long *numberOfErrors - output
正しく変換できなかった文字の数が入ります。
unsigned long *firstErrorIndex - output
正しく変換できなかったソース・バッファー中の最初の文字のオフセットが入ります。
unsigned long *requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
199
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
使用法
なし (None)
cwbNL_ConvertCodePages:
cwbNL_ConvertCodePages コマンドを使用します。
コメント
cwbNL_ConvertCodePages はサポートされなくなりました。cwbNL_ConvertCodePagesEx を参照してくださ
い。
cwbNL_ConvertCodePagesEx:
cwbNL_ConvertCodePagesEx コマンドを使用します。
目的
ストリングを 1 つのコード・ページから別のコード・ページに変換します。この API は、デフォルト変
換のために次の 3 つのコンバーター API を結合します。
v cwbNL_CreateConverterEx
v cwbNL_Convert
v cwbNL_DeleteConverter
構文
unsigned int CWB_ENTRY cwbNL_ConvertCodePagesEx(
unsigned long sourceCodePage,
unsigned long targetCodePage,
unsigned long sourceLength,
unsigned long targetLength,
char
*sourceBuffer,
char
*targetBuffer,
unsigned long *numberOfErrors,
unsigned long *positionOfFirstError,
unsigned long *requiredLen,
cwbSV_ErrHandle errorHandle);
パラメーター
unsigned long sourceCodePage - input
ソース・バッファー中のデータのコード・ページ。
200
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long targetCodePage - input
データの変換先のコード・ページ。
unsigned long sourceLength - input.
ソース・バッファーの長さ。
unsigned long targetLength - input.
ターゲット・バッファーの長さ。
char *sourceBuffer - input
変換すべきデータが入っているバッファー。
char *targetBuffer - output
変換されたデータが入るバッファー。
unsigned long *numberOfErrors - output
正しく変換できなかった文字の数が入ります。
unsigned long *positionOfFirstError - output
正しく変換できなかったソース・バッファー中の最初の文字のオフセットが入ります。
unsigned long *requiredLen - output
結果の実際の長さ。requiredLen > resultLen の場合、戻り値は CWB_BUFFER_OVERFLOW になりま
す。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWBNL_ERR_CNV_UNSUPPORTED
文字の変換をしようとしたときにエラーが発生しました。変換は行われませんでした。最もよく見
られる理由は、変換テーブルが欠落しているということです。変換テーブルは、製品と共にインス
トールされるか、または必要な場合にデフォルト・システムから取得されます。デフォルト・シス
テムとの通信に、何らかの障害が発生している可能性があります。
CWBNL_ERR_CNV_ERR_STATUS
この戻りコードは、要求した変換がサポートされている間とその変換が完了した時点で、一部の文
字が正しく変換されなかったことを示す場合に使用されます。ソース・バッファーの中に NULL
文字が入れられたか、あるいは、ターゲット・コード・ページの中にこれらの文字が入っていない
かのいずれかです。アプリケーションは、この戻りコードを無視するか、またはそれを警告として
処理することができます。
プログラミング
201
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
sourceCodePage および targetCodePage パラメーターで次の値を指定することができます。
値
CWBNL_CP_UNICODE_F200
CWBNL_CP_UNICODE
CWBNL_CP_AS400
CWBNL_CP_CLIENT_OEM
CWBNL_CP_CLIENT_ANSI
CWBNL_CP_CLIENT_UNICODE
CWBNL_CP_UTF8
CWBNL_CP_CLIENT
CWBNL_CP_UTF16BE
CWBNL_CP_UTF16LE
CWBNL_CP_UTF16
CWBNL_CP_UTF32BE
CWBNL_CP_UTF32LE
CWBNL_CP_UTF32
意味
UCS2 バージョン 1.1 UNICODE
UCS2 現行バージョン UNICODE
IBM i ホスト・コード・ページ
OEM クライアント・コード・ページ
ANSI クライアント・コード・ページ
UNICODE クライアント・コード・ページ
UCS 変換形式、8 ビット形式
汎用クライアント・コード・ページ。デフォルトは
CWBNL_CP_CLIENT_OEM。CWBNL_CP_CLIENT は、
CWB_ANSI が定義されるときに
CWBNL_CP_CLIENT_ANSI に設定され、CWB_UNICODE
が定義されるときに CWBNL_CP_CLIENT_UNICODE に設
定され、CWB_OEM が定義されるときに
CWBNL_CP_CLIENT_OEM に設定されます。
UTF-16 (ビッグ・エンディアン)
UTF-16 (リトル・エンディアン)
CWBNL_CP_UTF16BE または CWBNL_CP_UTF16LE (プラ
ットフォームによって異なる)
UTF-32 (ビッグ・エンディアン)
UTF-34 (リトル・エンディアン)
CWBNL_CP_UTF32BE または CWBNL_CP_UTF32LE (プラ
ットフォームによって異なる)
cwbNL_CreateConverter:
cwbNL_CreateConverter コマンドを使用します。
コメント
cwbNL_CreateConverter はサポートされなくなりました。cwbNL_CreateConverterEx を参照してください。
目的
後続の cwbNL_Convert() への呼び出しで使用される cwbNL_Converter を作成します。
構文
unsigned int CWB_ENTRY cwbNL_CreateConverter(
unsigned long
sourceCodePage,
unsigned long
targetCodePage,
cwbNL_Converter *theConverter,
cwbSV_ErrHandle errorHandle,
unsigned long
shiftInShiftOutStatus,
unsigned long
padLength,
char
*pad);
202
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
unsigned long sourceCodePage - input
ソース・データのコード・ページ。
unsigned long targetCodePage - input
データの変換先のコード・ページ。
cwbNL_Converter * theConverter - output
新しく作成されたコンバーター。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
unsigned long shiftInShiftOutStatus - input
シフトイン・バイトおよびシフトアウト・バイトが、入力データまたは出力データの一部かどうかを表
示します。0 - 偽。シフトインおよびシフトアウト・バイトはデータ・ストリングの一部ではない。1 真。シフトインおよびシフトアウト・バイトはデータ・ストリングの一部である。
unsigned long padLength - input
埋め込み文字の長さ。0 - この変換要求には埋め込み文字はない。1 - 1 バイトの埋め込み文字。これ
は、ターゲット・コード・ページが SBCS コード・ページや DBCS コード・ページのいずれかの場合
にのみ有効です。2 - 2 バイトの埋め込み文字。これは、コード・ページが 1 バイト・コード・ペー
ジでない場合にのみ有効です。
char * pad - input
埋め込みのための文字 (複数の場合もある)。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWBNL_ERR_CNV_UNSUPPORTED
文字の変換をしようとしたときにエラーが発生しました。変換は行われませんでした。最もよく見
られる理由は、変換テーブルが欠落しているということです。変換テーブルは、製品と共にインス
トールされるか、または必要な場合にデフォルト・システムから取得されます。デフォルト・シス
テムとの通信に、何らかの障害が発生している可能性があります。
CWBNL_ERR_CNV_ERR_STATUS
この戻りコードは、要求した変換がサポートされている間とその変換が完了した時点で、一部の文
字が正しく変換されなかったことを示す場合に使用されます。ソース・バッファーの中に NULL
文字が入れられたか、あるいは、ターゲット・コード・ページの中にこれらの文字が入っていない
かのいずれかです。アプリケーションは、この戻りコードを無視するか、またはそれを警告として
処理することができます。
プログラミング
203
CWBNL_ERR_CNV_INVALID_SISO_STATUS
SISO パラメーターが無効です。
CWBNL_ERR_CNV_INVALID_PAD_LENGTH
埋め込みの長さパラメーターが無効です。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
sourceCodePage および targetCodePage パラメーターで次の値を指定することができます。
値
CWBNL_CP_UNICODE_F200
CWBNL_CP_UNICODE
CWBNL_CP_AS400
CWBNL_CP_CLIENT_OEM
CWBNL_CP_CLIENT_ANSI
CWBNL_CP_CLIENT_UNICODE
CWBNL_CP_UTF8
CWBNL_CP_CLIENT
CWBNL_CP_UTF16BE
CWBNL_CP_UTF16LE
CWBNL_CP_UTF16
CWBNL_CP_UTF32BE
CWBNL_CP_UTF32LE
CWBNL_CP_UTF32
意味
UCS2 バージョン 1.1 UNICODE
UCS2 現行バージョン UNICODE
IBM i ホスト・コード・ページ
OEM クライアント・コード・ページ
ANSI クライアント・コード・ページ
UNICODE クライアント・コード・ページ
UCS 変換形式、8 ビット形式
汎用クライアント・コード・ページ。デフォルトは
CWBNL_CP_CLIENT_OEM。CWBNL_CP_CLIENT は、
CWB_ANSI が定義されるときに CWBNL_CP_CLIENT_ANSI に
設定され、CWB_UNICODE が定義されるときに
CWBNL_CP_CLIENT_UNICODE に設定され、CWB_OEM が定
義されるときに CWBNL_CP_CLIENT_OEM に設定されます。
UTF-16 (ビッグ・エンディアン)
UTF-16 (リトル・エンディアン)
CWBNL_CP_UTF16BE または CWBNL_CP_UTF16LE (プラット
フォームによって異なる)
UTF-32 (ビッグ・エンディアン)
UTF-34 (リトル・エンディアン)
CWBNL_CP_UTF32BE または CWBNL_CP_UTF32LE (プラット
フォームによって異なる)
同じコード・ページを使用して、次のように何度も cwbNL_ConvertCodePagesEx を呼び出す代わりに、
v cwbNL_ConvertCodePagesEx(850, 500, ...);
v cwbNL_ConvertCodePagesEx(850, 500, ...);
v cwbNL_ConvertCodePagesEx(850, 500, ...);
コンバーターを作成してそれを複数回使用するほうが、より効率的です。
v cwbNL_CreateConverter(850, 500, &conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_DeleteConverter(conv, ...);
cwbNL_CreateConverterEx:
cwbNL_CreateConverterEx コマンドを使用します。
204
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
後続の cwbNL_Convert() への呼び出しで使用される cwbNL_Converter を作成します。
構文
unsigned int CWB_ENTRY cwbNL_CreateConverterEx(
unsigned long
sourceCodePage,
unsigned long
targetCodePage,
cwbNL_Converter *theConverter,
cwbSV_ErrHandle errorHandle,
unsigned long
shiftInShiftOutStatus,
unsigned long
padLength,
char
*pad);
パラメーター
unsigned long sourceCodePage - input
ソース・データのコード・ページ。
unsigned long targetCodePage - input
データの変換先のコード・ページ。
cwbNL_Converter * theConverter - output
新しく作成されたコンバーター。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
unsigned long shiftInShiftOutStatus - input
シフトイン・バイトおよびシフトアウト・バイトが、入力データまたは出力データの一部かどうかを表
示します。0 - 偽。シフトインおよびシフトアウト・バイトはデータ・ストリングの一部ではない。1 真。シフトインおよびシフトアウト・バイトはデータ・ストリングの一部である。
unsigned long padLength - input
埋め込み文字の長さ。0 - この変換要求には埋め込み文字はない。1 - 1 バイトの埋め込み文字。これ
は、ターゲット・コード・ページが SBCS コード・ページや DBCS コード・ページのいずれかの場合
にのみ有効です。2 - 2 バイトの埋め込み文字。これは、コード・ページが 1 バイト・コード・ペー
ジでない場合にのみ有効です。
char * pad - input
埋め込みのための文字 (複数の場合もある)。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
プログラミング
205
CWBNL_ERR_CNV_UNSUPPORTED
文字の変換をしようとしたときにエラーが発生しました。変換は行われませんでした。最もよく見
られる理由は、変換テーブルが欠落しているということです。変換テーブルは、製品と共にインス
トールされるか、または必要な場合にデフォルト・システムから取得されます。デフォルト・シス
テムとの通信に、何らかの障害が発生している可能性があります。
CWBNL_ERR_CNV_ERR_STATUS
この戻りコードは、要求した変換がサポートされている間とその変換が完了した時点で、一部の文
字が正しく変換されなかったことを示す場合に使用されます。ソース・バッファーの中に NULL
文字が入れられたか、あるいは、ターゲット・コード・ページの中にこれらの文字が入っていない
かのいずれかです。アプリケーションは、この戻りコードを無視するか、またはそれを警告として
処理することができます。
CWBNL_ERR_CNV_INVALID_SISO_STATUS
SISO パラメーターが無効です。
CWBNL_ERR_CNV_INVALID_PAD_LENGTH
埋め込みの長さパラメーターが無効です。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
sourceCodePage および targetCodePage パラメーターで次の値を指定することができます。
値
CWBNL_CP_UNICODE_F200
CWBNL_CP_UNICODE
CWBNL_CP_AS400
CWBNL_CP_CLIENT_OEM
CWBNL_CP_CLIENT_ANSI
CWBNL_CP_CLIENT_UNICODE
CWBNL_CP_UTF8
CWBNL_CP_CLIENT
CWBNL_CP_UTF16BE
CWBNL_CP_UTF16LE
CWBNL_CP_UTF16
CWBNL_CP_UTF32BE
CWBNL_CP_UTF32LE
CWBNL_CP_UTF32
意味
UCS2 バージョン 1.1 UNICODE
UCS2 現行バージョン UNICODE
IBM i ホスト・コード・ページ
OEM クライアント・コード・ページ
ANSI クライアント・コード・ページ
UNICODE クライアント・コード・ページ
UCS 変換形式、8 ビット形式
汎用クライアント・コード・ページ。デフォルトは
CWBNL_CP_CLIENT_OEM。CWBNL_CP_CLIENT は、
CWB_ANSI が定義されるときに CWBNL_CP_CLIENT_ANSI に
設定され、CWB_UNICODE が定義されるときに
CWBNL_CP_CLIENT_UNICODE に設定され、CWB_OEM が定
義されるときに CWBNL_CP_CLIENT_OEM に設定されます。
UTF-16 (ビッグ・エンディアン)
UTF-16 (リトル・エンディアン)
CWBNL_CP_UTF16BE または CWBNL_CP_UTF16LE (プラット
フォームによって異なる)
UTF-32 (ビッグ・エンディアン)
UTF-34 (リトル・エンディアン)
CWBNL_CP_UTF32BE または CWBNL_CP_UTF32LE (プラット
フォームによって異なる)
同じコード・ページを使用して、次のように何度も cwbNL_ConvertCodePagesEx を呼び出す代わりに、
v cwbNL_ConvertCodePagesEx(850, 500, ...);
v cwbNL_ConvertCodePagesEx(850, 500, ...);
v cwbNL_ConvertCodePagesEx(850, 500, ...);
206
IBM i: Windows アプリケーション・パッケージ: プログラミング
コンバーターを作成してそれを複数回使用するほうが、より効率的です。
v cwbNL_CreateConverterEx(850, 500, &conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_Convert(conv, ...);
v cwbNL_DeleteConverter(conv, ...);
cwbNL_DeleteConverter:
cwbNL_DeleteConverter コマンドを使用します。
目的
cwbNL_Converter を削除します。
構文
unsigned int CWB_ENTRY cwbNL_DeleteConverter(
cwbNL_Converter theConverter,
cwbSV_ErrHandle errorHandle);
パラメーター
cwbNL_Converter theConverter - input
前に作成したコンバーター。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbNL_GetCodePage:
cwbNL_GetCodePage コマンドを使用します。
プログラミング
207
目的
クライアント・システムの現行コード・ページを取得します。
構文
unsigned int CWB_ENTRY cwbNL_GetCodePage(
unsigned long *codePage,
cwbSV_ErrHandle errorHandle);
パラメーター
unsigned long * codePage - output
クライアント・システムの現行コード・ページ、または OEM コード・ページ文字変換オーバーライ
ド値が「IBM i Access Familyのプロパティー」ダイアログの言語タブに指定されていれば、それを戻
します。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
なし (None)
cwbNL_GetANSICodePage:
cwbNL_GetANSICodePage コマンドを使用します。
目的
クライアント・システムの現行 ANSI コード・ページを取得します。
構文
unsigned int CWB_ENTRY cwbNL_GetANSICodePage(
unsigned long *codePage,
cwbSV_ErrHandle errorHandle);
208
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
unsigned long * codePage - output
クライアント・システムの現行 ANSI コード・ページ、または ANSI コード・ページ文字変換オーバ
ーライド値が「IBM i Access Familyのプロパティー」ダイアログの言語タブに指定されていれば、そ
れを戻します。
cwbSV_ErrHandle errorHandle - output
エラー・オブジェクトのハンドル。戻されたメッセージはすべてこのオブジェクトに書き込まれます。
このオブジェクトは、cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、
cwbSV_GetErrText API を介して検索することができます。パラメーターがゼロに設定されている場合
は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
なし (None)
cwbNL_GetHostCCSID:
cwbNL_GetHostCCSID コマンドを使用します。
目的
所定のホスト・システムまたは管理システムに関連する CCSID、または EBCDIC コード・ページ文字変
換オーバーライド値が製品の「プロパティー」ダイアログの「言語」タブに指定されていれば、それを戻し
ます。
構文
unsigned long CWB_ENTRY cwbNL_GetHostCCSID(
char * system,
unsigned long * CCSID );
パラメーター
char * system - input
ホスト・システムの名前。NULL の場合は、管理システムが使用されます。
unsigned * CCSID - output
結果を入れるバッファーの長さ。
プログラミング
209
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWBNL_DEFAULT_HOST_CCSID_USED
ホスト CCSID 500 が戻されます。
使用法
この API は、関連する CCSID 値を検索するのに、ホスト・システムへの活動接続を行わず、またそれが
必要でもありません。それはホスト・システムへの以前の正常な接続に依存します。ホスト・システムに対
して正常な接続が前に行われていない場合は、API は、内部マッピング・テーブルを使用して最も適切な
関連するホスト CCSID を判別します。
ダイアログ・ボックス NLS API リスト:
ダイアログ・ボックス NLS API は、ダイアログ・ボックス内の変換可能テキストを操作するために使用さ
れるインターフェースです。
以下のダイアログ・ボックス NLS API を使用すると、アプリケーションで次の作業が行えるようになりま
す。
v ダイアログ・ボックス内の変換可能テキストを置き換える
v テキストに従ってダイアログ・ボックス・コントロールを拡張する
使用上の注意
このモジュールは、次のような種類のダイアログ・ボックス・コントロールの場合にのみ動作します。
v 静的テキスト
v ボタン
v グループ・ボックス
v 編集ボックス
v チェック・ボックス
v ラジオ・ボタン
組み合わせボックスなどの複合コントロールの場合は、動作しません。
cwbNL_CalcControlGrowthXY:
cwbNL_CalcControlGrowthXY コマンドを使用します。
目的
ダイアログ・ボックス中の個々のコントロールの拡大係数を計算するためのルーチン。
210
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbNL_CalcControlGrowthXY(
HWND windowHandle,
HDC hDC,
float* growthFactorX,
float* growthFactorY);
パラメーター
HWND windowHandle - input
拡大係数を計算する対象のコントロールのウィンドウ・ハンドル。
HDC hDC - input
装置コンテキスト。コントロール内の変換済みストリングに必要な範囲を決めるのに
GetTextExtentPoint32 によって使用されます。
float* growthFactorX - output
コントロールのストリングを入れるために必要な幅に対する +/- 拡大。
float* growthFactorY - output
コントロールのストリングを入れるために必要な高さに対する +/- 拡大。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
使用法
この関数を呼び出す前に、変換済みテキストがコントロール内にロードされているものと想定します。テキ
ストを含まないコントロールは、1.00 の拡大係数を戻します。これは、サイズを変更する必要がないこと
を意味します。
cwbNL_CalcDialogGrowthXY:
cwbNL_CalcDialogGrowthXY コマンドを使用します。
目的
ダイアログ・ボックスの拡大係数を計算するためのルーチン。ダイアログ・ボックスのサイズをどれだけ調
整する必要があるかを判別するために、ダイアログ・ボックス内のすべてのコントロールが調査されます。
構文
unsigned int CWB_ENTRY cwbNL_CalcDialogGrowthXY(
HWND windowHandle,
float* growthFactorX,
float* growthFactorY);
パラメーター
HWND windowHandle - input
拡大係数を計算する対象のダイアログ・ボックスのウィンドウ・ハンドル。
プログラミング
211
float* growthFactorX - output
ダイアログ・ボックス内のすべてのコントロール用のストリングを入れるために必要な幅に対する +/拡大。
float* growthFactorY - output
ダイアログ・ボックス内のすべてのコントロール用のストリングを入れるために必要な高さに対する
+/- 拡大。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
使用法
この関数を呼び出す前に、変換済みテキストがコントロール内にロードされているものと想定します。
cwbNL_GrowControlXY:
cwbNL_GrowControlXY コマンドを使用します。
目的
ダイアログ・ボックス内の個々のコントロールを拡大するためのルーチン。
構文
unsigned int CWB_ENTRY cwbNL_GrowControlXY(
HWND
windowHandle,
HWND
parentWindowHandle,
float
growthFactorX,
float
growthFactorY,
cwb_Boolean growAllControls);
パラメーター
HWND windowHandle - input
サイズ変更されるコントロールのウィンドウ・ハンドル。
HWND parentWindowHandle - input
コントロールを含むダイアログ・ボックスのウィンドウ・ハンドル。
float growthFactorX - input
コントロールの幅の拡大に使用される乗算係数。1.00 = 同じサイズのまま。1.50 = 元のサイズの 1.5
倍。
float growthFactorY - input
コントロールの高さの拡大に使用される乗算係数。1.00 = 同じサイズのまま。1.50 = 元のサイズの
1.5 倍。
cwb_Boolean growAllControls - input
CWB_TRUE = すべてのコントロールは growthFactor によってサイズ変更される。CWB_FALSE = テ
キストを持つコントロールのみがサイズ変更される。
212
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
使用法
コントロールが実際の表示装置に合わない拡大係数を渡さないよう注意が必要です。
cwbNL_GrowDialogXY:
cwbNL_GrowDialogXY コマンドを使用します。
目的
ダイアログ・ボックスおよびそのコントロールを、入力される拡大係数に比例して拡大する内部ルーチン。
構文
unsigned int CWB_ENTRY cwbNL_GrowDialogXY(
HWND
windowHandle,
float
growthFactorX,
float
growthFactorY,
cwb_Boolean growAllControls);
パラメーター
HWND windowHandle - input
コントロールを所有するウィンドウのウィンドウ・ハンドル。
float growthFactorX - input
ダイアログ・ボックスを拡大する乗算係数。1.00 = 同じサイズのまま。1.50 = 元のサイズの 1.5 倍。
float growthFactorY - input
ダイアログ・ボックスを拡大する乗算係数。1.00 = 同じサイズのまま。1.50 = 元のサイズの 1.5 倍。
cwb_Boolean growAllControls - input
CWB_TRUE = すべてのコントロールは growthFactor によってサイズ変更される。CWB_FALSE = テ
キストをもつコントロールのみがサイズ変更される。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
使用法
この関数を呼び出す前に、変換済みテキストがコントロール内にロードされているものと想定します。ダイ
アログ・ボックス・フレームは、デスクトップ・ウィンドウ・サイズよりも大きく拡大することはできませ
ん。
cwbNL_LoadDialogStrings:
cwbNL_LoadDialogStrings コマンドを使用します。
プログラミング
213
目的
このルーチンは、ダイアログ・ボックス内の変換可能テキストの置き換えを制御します。これには、ダイア
ログ・ボックスの表題だけでなくダイアログ・コントロールのテキストも含まれます。
構文
unsigned int CWB_ENTRY cwbNL_LoadDialogStrings(
HINSTANCE
MRIHandle,
HWND
windowHandle,
int
nCaptionID,
USHORT
menuID,
HINSTANCE
menuLibHandle,
cwb_Boolean growAllControls);
パラメーター
HINSTANCE MRIHandle - input
ダイアログ用のストリングが入っているモジュールのハンドル。
HWND windowHandle - input
ダイアログ・ボックスのウィンドウ・ハンドル。
int nCaptionID - input
ダイアログ・ボックス用の表題ストリングの ID。
USHORT menuID - input
ダイアログ・ボックス用メニューの ID。
HINSTANCE menuLibHandle - input
ダイアログ・メニューが入っているモジュールのハンドル。
cwb_Boolean growAllControls - input
CWB_TRUE = すべてのコントロールは growthFactor によってサイズ変更される。CWB_FALSE = テ
キストをもつコントロールのみがサイズ変更される。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBNL_DLG_MENU_LOAD_ERROR
メニューをロードすることができません。
CWBNL_DLG_INVALID_HANDLE
MRIHandle が誤り。
使用法
このプロセスは、ダイアログ・ボックス内のすべてのダイアログ・コントロールを列挙し、そのテキストを
置換し、横方向に調整することで始まり、最後にそこで調整されたコントロールを基準にして、ダイアロ
グ・ボックス自体を右寄せします。これらの調整は、現行ウィンドウの範囲が、テキストまたはすべてのコ
ントロールに必要な拡張スペースを十分に確保していない場合にのみ行われます。すべてのテキスト置換が
完了したあと、メニュー ID が渡されている場合は、その ID がロードされ、ダイアログ・ボックスに付
加されます。それぞれのダイアログ・ボックス・プロシージャーごとに、このルーチンを INITDLG メッ
セージ処理中に行われる最初のものとして呼び出すことをお勧めします。
214
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbNL_LoadMenu:
cwbNL_LoadMenu コマンドを使用します。
目的
このルーチンは、モジュールからの所定のメニューのロードと、メニュー内の変換可能テキストの置き換え
を制御します。
構文
HWND CWB_ENTRY cwbNL_LoadMenu(
HWND
HINSTANCE
USHORT
HINSTANCE
windowHandle,
menuResourceHandle,
menuID,
MRIHandle);
パラメーター
HWND windowHandle - input
メニューが入っているダイアログ・ボックスのウィンドウ・ハンドル。
HINSTANCE menuResourceHandle - input
メニューが入っている資源 DLL のハンドル。
USHORT menuID - input
ダイアログ・ボックス用メニューの ID。
HINSTANCE MRIHandle - input
メニュー用ストリングが入っている資源 DLL のハンドル。
戻りコード
以下は、共通の戻り値です。
HINSTANCE
メニューのハンドル。
使用法
なし (None)
cwbNL_LoadMenuStrings:
cwbNL_LoadMenuStrings コマンドを使用します。
目的
このルーチンは、メニュー内の変換可能テキストの置き換えを制御します。
構文
unsigned int CWB_ENTRY cwbNL_LoadMenuStrings(
HWND
WindowHandle,
HINSTANCE menuHandle,
HINSTANCE MRIHandle);
プログラミング
215
パラメーター
HWND windowHandle - input
メニューが入っているダイアログ・ボックスのウィンドウ・ハンドル。
HMODULE menuHandle - input
ダイアログ用メニューのハンドル。
HMODULE MRIHandle - input
メニュー用ストリングが入っている資源 DLL のハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
使用法
なし (None)
cwbNL_SizeDialog:
cwbNL_SizeDialog コマンドを使用します。
目的
このルーチンは、ダイアログ・ボックスとその子コントロールのサイズを制御します。拡張量は、テキスト
の範囲の長さと各コントロールの長さに基づきます。ダイアログ・ボックスとそのコントロールの拡張と縮
小は比例します。growAllControls を FALSE に設定すると、テキストを使用するコントロールだけが拡張
または縮小されます。これにより、プログラマーに対して、変換不可フィールドを元のサイズのまま残して
おくことができるという柔軟性が与えられます。このことは、ドロップダウン・リスト、組み合わせボック
ス、またはスピン・ボタンを使用するダイアログに適していると考えられます。
構文
unsigned int CWB_ENTRY cwbNL_SizeDialog(
HWND
windowHandle,
cwb_Boolean growAllControls);
パラメーター
HWND windowHandle - input
コントロールを所有するウィンドウのウィンドウ・ハンドル。
cwb_Boolean growAllControls - input
CWB_TRUE = すべてのコントロールは growthFactor によってサイズ変更される。CWB_FALSE = テ
キストをもつコントロールのみがサイズ変更される。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
216
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
このルーチンは、変換済みテキストが既にダイアログ・ボックス・コントロールにロードされていることを
想定しています。テキストがコントロール内にロードされていない場合は、cwbNL_LoadDialog を使用して
ください。
例: NLS API:
NLS API の使用法をこの例で説明します。
/* National Language Support Code Snippet
/* Used to demonstrate how the APIs would be run.
#include
#include
#include
#include
#include
#include
*/
*/
<stdio.h>
<stdlib.h>
<string.h>
"CWBNL.H"
"CWBNLCNV.H"
"CWBSV.H"
cwbSV_ErrHandle errhandle;
/* Return the message text associated with the top-level
/* error identified by the error handle provided.
Since
/* all APIs that fail use the error handle, this was moved
/* into a separate routine.
void resolveErr(cwbSV_ErrHandle errhandle)
{
static unsigned char buf[ BUFSIZ ];
unsigned long retlen;
unsigned int rc;
*/
*/
*/
*/
if ((rc = cwbSV_GetErrText(errhandle, (char*)buf, (unsigned long) BUFSIZ, &retlen)) != CWB_OK)
printf("cwbSV_GetErrText() Service API failed with return code 0x%x.¥n", rc);
else
printf("%s¥n", (char *) buf);
}
void main(void){
/* define some variables
-------------------- */
int SVrc = 0;
int NLrc = 0;
char *myloadpath = "";
char *resultPtr;
char *mylang;
unsigned short resultlen;
unsigned short reqlen;
unsigned long searchhandle;
unsigned long codepage;
unsigned long trgtpage;
char *srcbuf = "Change this string";
char *trgtbuf;
unsigned long srclen;
unsigned long trgtlen;
unsigned long nmbrerrs;
unsigned long posoferr;
unsigned long rqdlen;
unsigned long ccsid;
/*
/*
/*
Create an error message object and return a handle to
it. This error handle can be passed to APIs that
support it. If an error occurs, the error handle can
*/
*/
*/
プログラミング
217
/* be used to retrieve the message text associated with
*/
/* the API error.
*/
SVrc = cwbSV_CreateErrHandle(&errhandle);
if (SVrc != CWB_OK) {
printf("cwbSV_CreateErrHandle failed with return code %d.¥n", SVrc);
}
/* Retreive the current language setting.
*/
resultlen = CWBNL_MAX_LANG_SIZE+1;
resultPtr = (char *) malloc(resultlen * sizeof(char));
NLrc = cwbNL_GetLang(myloadpath, resultPtr, resultlen, &reqlen, errhandle);
if (NLrc != CWB_OK) {
if (NLrc == CWB_BUFFER_OVERFLOW)
printf("GetLang buffer too small, recommended size %d.¥n", reqlen);
resolveErr(errhandle);
}
printf("GetLang API returned %s.¥n", resultPtr);
mylang = (char *) malloc(resultlen * sizeof(char));
strcpy(mylang, resultPtr);
/* Retrieve the descriptive name of a language setting.
*/
resultlen = CWBNL_MAX_NAME_SIZE+1;
resultPtr = (char *) realloc(resultPtr, resultlen * sizeof(char));
NLrc = cwbNL_GetLangName(mylang, resultPtr, resultlen, &reqlen, errhandle);
if (NLrc != CWB_OK) {
if (NLrc == CWB_BUFFER_OVERFLOW)
printf("GetLangName buffer too small, recommended size %d.¥n", reqlen);
resolveErr(errhandle);
}
printf("GetLangName API returned %s.¥n", resultPtr);
/* Return the complete path for language files.
*/
resultlen = CWBNL_MAX_PATH_SIZE+1;
resultPtr = (char *) realloc(resultPtr, resultlen * sizeof(char));
NLrc = cwbNL_GetLangPath(myloadpath, resultPtr, resultlen, &reqlen, errhandle);
if (NLrc != CWB_OK) {
if (NLrc == CWB_BUFFER_OVERFLOW)
printf("GetLangPath buffer too small, recommended size %d.¥n", reqlen);
resolveErr(errhandle);
}
printf("GetLangPath API returned %s.¥n", resultPtr);
/* Get the code page of the current process.
NLrc = cwbNL_GetCodePage(&codepage, errhandle);
if (NLrc != CWB_OK) {
resolveErr(errhandle);
}
printf("GetCodePage API returned %u.¥n", codepage);
*/
/* Convert strings from one code page to another. This
*/
/* API combines three converter APIs for the default
*/
/* conversion. The three converter APIs it combines are: */
/*
cwbNL_CreateConverterEx
*/
/*
cwbNL_Convert
*/
/*
cwbNL_DeleteConverter
*/
srclen = strlen(srcbuf) + 1;
trgtlen = srclen;
trgtpage = 437;
trgtbuf = (char *) malloc(trgtlen * sizeof(char));
printf("String to convert is %s.¥n",srcbuf);
NLrc = cwbNL_ConvertCodePagesEx(codepage, trgtpage, srclen,
trgtlen, srcbuf, trgtbuf, &nmbrerrs, &posoferr, &rqdlen,
errhandle);
if (NLrc != CWB_OK) {
resolveErr(errhandle);
printf("number of errors detected is %u.¥n", nmbrerrs);
printf("location of first error is %u.¥n", posoferr);
218
IBM i: Windows アプリケーション・パッケージ: プログラミング
}
printf("ConvertCodePagesEx API returned %s.¥n", trgtbuf);
/* Map a code page to the corresponding CCSID.
NLrc = cwbNL_CodePageToCCSID(codepage, &ccsid, errhandle);
if (NLrc != CWB_OK) {
resolveErr(errhandle);
}
printf("CodePageToCCSID returned %u.¥n", ccsid);
*/
cwbSV_DeleteErrHandle(errhandle);
}
システム・オブジェクト API
システム・オブジェクトのアプリケーション・プログラミング・インターフェース (API) を使用して、シ
ステム上にある印刷関連のオブジェクトを処理できます。これらの API は、IBM i スプール・ファイル、
書き出しプログラム・ジョブ、出力待ち行列、プリンターなどを使った作業を可能にします。
システム・オブジェクト API を使用すると、ご使用の環境に応じてカスタマイズしたワークステーショ
ン・アプリケーションを作成できます。例えば、単一ユーザー、あるいは、IBM i オペレーティング・シ
ステムのネットワークを介して結ばれているすべてのユーザーのスプール・ファイルを管理するアプリケー
ションを作成することができます。これには、スプール・ファイルの保留、解放、属性の変更、削除、送
信、検索およびスプール・ファイルに関するメッセージの応答が含まれます。
システム・オブジェクト API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbobj.h
cwbapi.lib
cwbobj.dll
Programmer's Toolkit:
Programmer's Toolkit には、システム・オブジェクト資料、cwbobj.h ヘッダー・ファイルへのアクセス、お
よびプログラム例へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit を
オープンして、「IBM i オペレーション (IBM i Operations)」 > 「C/C++ API」と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
23 ページの『システム・オブジェクト API の戻りコード』
システム・オブジェクト API の戻りコードを示します。
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
システム・オブジェクトの属性
ネットワーク印刷サーバーのオブジェクトには属性があります。ネットワーク印刷サーバーは、以下の属性
をサポートします。特定の組み合わせに対してサポートされている属性を判別するには、それぞれのオブジ
ェクト / アクションのデータ・ストリームに関する説明を参照してください。
プログラミング
219
高機能印刷:
この高機能印刷 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_AFP
ID
0x000A
タイプ char[11]
説明
このスプール・ファイルが、このファイルの外部にある AFP 資源を使用するかどうかを示しま
す。有効な値は *YES または *NO です。
ページの位置合わせ:
ページの位置合わせ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ALIGN
ID
0x000B
タイプ char[11]
説明
このスプール・ファイルを印刷する前に、用紙位置決めメッセージを送るかどうかを示します。有
効な値は *YES または *NO です。
直接印刷可能:
この直接印刷可能 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ALWDRTPRT
ID
0x000C
タイプ char[11]
説明
プリントに直接印刷するジョブに対して、印刷装置書き出しプログラムにプリンターを割り振りさ
せるかどうかを示します。有効な値は *YES または *NO です。
権限:
この権限 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_AUT
ID
0x000D
タイプ char[11]
説明
出力待ち行列に対する特定の権限を持たないユーザーに対して、与える権限を指定します。有効な
値は、*USE、*ALL、*CHANGE、*EXCLUDE、*LIBCRTAUT です。
検査権限:
この検査権限 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_AUTCHK
ID
0x000E
タイプ char[11]
説明
220
出力待ち行列に対するどんなタイプの権限によって、ユーザーが出力待ち行列の全ファイルを制御
できるようにするかを示します。有効な値は *OWNER または *DTAAUT です。
IBM i: Windows アプリケーション・パッケージ: プログラミング
書き出しプログラムの自動終了:
この書き出しプログラムの自動終了 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_AUTOEND
ID
0x0010
タイプ char[11]
説明
書き出しプログラムが自動的に終了するかどうかを示します。有効な値は *YES または *NO で
す。
バック・マージン・オフセット (横方向):
このバック・マージン・オフセット (横方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BACKMGN_ACR
ID
0x0011
タイプ float
説明
用紙の裏側について、ページの左端からどれだけ離れた位置で印刷が開始されるかを指定します。
特殊値 *FRONTMGN は -1 としてエンコードされます。
バック・マージン・オフセット (下方向):
このバック・マージン・オフセット (下方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BACKMGN_DWN
ID
0x0012
タイプ float
説明
用紙の裏側について、ページの上端からどれだけ離れた位置で印刷が開始されるかを指定します。
特殊値 *FRONTMGN は -1 としてエンコードされます。
背面オーバーレイ・ライブラリー名:
この背面オーバーレイ・ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BKOVRLLIB
ID
0x0013
タイプ char[11]
説明
背面オーバーレイが入っているライブラリー名。背面オーバーレイの名前フィールドに特殊値が入
っている場合は、このライブラリー・フィールドはブランクです。
背面オーバーレイの名前:
この背面オーバーレイの名前 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BKOVRLAY
ID
0x0014
タイプ char[11]
説明
背面オーバーレイの名前。有効な特殊値には *FRONTMGN が含まれます。
プログラミング
221
背面オーバーレイ・オフセット (横方向):
この背面オーバーレイ・オフセット (横方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BKOVL_ACR
ID
0x0016
タイプ float
説明
オーバーレイが印刷される起点から横方向へのオフセット。
背面オーバーレイ・オフセット (下方向):
この背面オーバーレイ・オフセット (下方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_BKOVL_DWN
ID
0x0015
タイプ float
説明
オーバーレイが印刷される起点から下方へのオフセット。
1 インチ当たり文字数:
この 1 インチ当たり文字数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CPI
ID
0x0017
タイプ float
説明
横方向 1 インチ当たりの文字数。
コード・ページ:
このコード・ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CODEPAGE
ID
0x0019
タイプ char[11]
説明
このスプール・ファイルについて、グラフィック文字のコード・ポイントへのマッピング。グラフ
ィック文字セット・フィールドに特殊値が入っていると、このフィールドにはゼロ (0) が入りま
す。
コード化フォント名:
このコード化フォント名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CODEDFNT
ID
0x001A
タイプ char[11]
説明
222
コード化フォントの名前。コード化フォントとは、文字セットとコード・ページで構成される AFP
資源のことです。特殊値には *FNTCHRSET が含まれます。
IBM i: Windows アプリケーション・パッケージ: プログラミング
コード化フォント・ライブラリー名:
このコード化フォント・ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CODEDFNTLIB
ID
0x0018
タイプ char[11]
説明
コード化フォントが入っているライブラリーの名前。コード化フォントの名前フィールドが特殊値
をもつ場合は、このフィールドにはブランクが入ります。
コピー:
このコピー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_COPIES
ID
0x001C
タイプ long
説明
このスプール・ファイル用に作成されるコピーの合計数。
作成されていない残りのコピー:
この作成されていない残りのコピー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_COPIESLEFT
ID
0x001D
タイプ long
説明
このスプール・ファイル用に作成されるコピーの残りの数。
現行ページ:
この現行ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CURPAGE
ID
0x001E
タイプ long
説明
書き出しプログラム・ジョブが書き出し中の現行ページ。
データ形式:
このデータ形式 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DATAFORMAT
ID
0x001F
タイプ char[11]
説明
データ形式。有効な値は *RCDDATA または *ALLDATA です。
データ待ち行列ライブラリー名:
このデータ待ち行列ライブラリー名 API は、この製品と共に使用します。
プログラミング
223
キー
CWBOBJ_KEY_DATAQUELIB
ID
0x0020
タイプ char[11]
説明
データ待ち行列が入っているライブラリーの名前。
データ待ち行列名:
このデータ待ち行列名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DATAQUE
ID
0x0021
タイプ char[11]
説明
出力待ち行列に関連するデータ待ち行列の名前。
ファイルがオープンされた日付:
このファイルがオープンされた日付 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DATE
ID
0x0022
タイプ char[8]
説明
スプール・ファイルがオープンされた日付。日付は、C YY MM DD の形式で文字ストリングにエ
ンコードされています。
ユーザー指定の DBCS データ:
このユーザー指定の DBCS データ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DBCSDATA
ID
0x0099
タイプ char[11]
説明
スプール・ファイルに 2 バイト文字セット (DBCS) データが入っているかどうかを示します。有
効な値は *NO または *YES です。
DBCS 拡張文字:
この DBCS 拡張文字 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DBCSEXTENSN
ID
0x009A
タイプ char[11]
説明
システムが DBCS 拡張文字を処理するかどうかを示します。有効な値は *NO または *YES で
す。
DBCS 文字回転:
この DBCS 文字回転 API は、この製品と共に使用します。
キー
224
CWBOBJ_KEY_DBCAROTATE
IBM i: Windows アプリケーション・パッケージ: プログラミング
ID
0x009B
タイプ char[11]
説明
印刷前に DBCS 文字を反時計方向に 90 度回転させるかどうかを示します。有効な値は *NO ま
たは *YES です。
1 インチ当たりの DBCS 文字数:
この 1 インチ当たりの DBCS 文字数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DBCSCPI
ID
0x009C
タイプ long
説明
1 インチ当たり印刷される 2 バイト文字の数。有効な値は、-1、-2、5、6、および 10 です。値
*CPI は -1 としてエンコードされます。値 *CONDENSED は -2 としてエンコードされます。
DBCS SO/SI スペース:
この DBCS SO/SI スペース API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DBCSSISO
ID
0x009D
タイプ char[11]
説明
印刷時にシフトアウト文字とシフトイン文字を表示するかどうかを決めます。有効な値は、
*NO、*YES、および *RIGHT です。
書き出し据え置き:
この書き出し据え置き API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DFR_WRITE
ID
0x0023
タイプ char[11]
説明
印刷データがプリンターに送信される前にシステム・バッファーに保持されるかどうかを示しま
す。有効な値は *YES または *NO です。
ページ回転の角度:
このページ回転の角度 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PAGRTT
ID
0x0024
タイプ long
説明
用紙がプリンターにロードされる向きに対する、ページ上のテキストの回転角度。有効な値
は、-1、-2、-3、0、90、180、および 270 です。値 *AUTO は -1 に、*DEVD は -2 に、*COR
は -3 にそれぞれエンコードされます。
送信後にファイルを削除:
送信後にファイルを削除 API は、この製品と共に使用します。
プログラミング
225
キー
CWBOBJ_KEY_DELETESPLF
ID
0x0097
タイプ char[11]
説明
スプール・ファイルを送信後削除します。有効な値は *NO または *YES です。
宛先オプション:
宛先オプション API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DESTOPTION
ID
0x0098
タイプ char[129]
説明
宛先オプション。ユーザーが受信システムにオプションを渡すことができるようにするテキスト・
ストリングです。
宛先タイプ:
宛先タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DESTINATION
ID
0x0025
タイプ char[11]
説明
宛先タイプ。有効な値は *OTHER、*AS400、および *PSF2 です。
装置クラス:
装置クラス API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DEVCLASS
ID
0x0026
タイプ char[11]
説明
装置クラス。
装置型式:
装置型式 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DEVMODEL
ID
0x0027
タイプ char[11]
説明
装置の型式番号。
装置タイプ:
装置タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DEVTYPE
ID
0x0028
226
IBM i: Windows アプリケーション・パッケージ: プログラミング
タイプ char[11]
説明
装置タイプ。
ファイルの表示:
ファイルの表示 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DISPLAYANY
ID
0x0029
タイプ char[11]
説明
この出力待ち行列を読み取る権限をもつユーザーが、この待ち行列のいずれの出力ファイルの出力
データも表示できるか、ユーザー自身のファイルのデータしか表示できないかを示します。有効な
値は、*YES、*NO、および *OWNER です。
区切りページの用紙入れ:
区切りページの用紙入れ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DRWRSEP
ID
0x002A
タイプ long
説明
ジョブおよびファイルの区切りページが取り出される用紙入れを識別します。有効な値は、
-1、-2、1、2、および 3 です。値 *FILE は -1、値 *DEVD は -2 としてエンコードされます。
終了ページ:
終了ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ENDPAGE
ID
0x002B
タイプ long
説明
スプール・ファイルの印刷を終了するときのページ番号。有効な値は 0 か、または終了ページ番
号です。値 *END は 0 としてエンコードされます。
ファイル区切り:
ファイル区切り API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FILESEP
ID
0x002C
タイプ long
説明
スプール・ファイルの各コピーの最初に置かれる、ファイル区切りページ数。有効な値は、-1 また
は区切りページの数です。値 *FILE は -1 としてエンコードされます。
レコードの折り返し:
このレコードの折り返し API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FOLDREC
プログラミング
227
ID
0x002D
タイプ char[11]
説明
印刷用紙幅を超えるレコードが次行に折り返されるかどうかを示します。有効な値は *YES または
*NO です。
フォント識別コード:
このフォント識別コード API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FONTID
ID
0x002E
タイプ char[11]
説明
使用される印刷フォント。有効な特殊値には *CPI と *DEVD が含まれます。
用紙送り:
用紙送り API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FORMFEED
ID
0x002F
タイプ char[11]
説明
プリンターでの用紙送りの方法を示します。有効な値は、*CONT、*CUT、*AUTOCUT、および
*DEVD です。
用紙タイプ:
用紙タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FORMTYPE
ID
0x0030
タイプ char[11]
説明
このスプール・ファイルを印刷するためにプリンターにロードされる用紙のタイプ。
用紙タイプ・メッセージ・オプション:
用紙タイプ・メッセージ・オプション API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FORMTYPEMSG
ID
0x0043
タイプ char[11]
説明
この現行用紙タイプが終了したときに、メッセージを書き出しプログラムのメッセージ待ち行列に
送信するメッセージ・オプション。有効な値は、*MSG、*NOMSG、*INFOMSG、および
*INQMSG です。
フロント・マージン・オフセット (横方向):
フロント・マージン・オフセット (横方向) API は、この製品と共に使用します。
キー
228
CWBOBJ_KEY_FTMGN_ACR
IBM i: Windows アプリケーション・パッケージ: プログラミング
ID
0x0031
タイプ float
説明
用紙の表側について、ページの左端からどの程度離れた位置で印刷を開始するかを指定します。特
殊値 *DEVD は -2 としてエンコードされます。
フロント・マージン・オフセット (下方向):
フロント・マージン・オフセット (下方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FTMGN_DWN
ID
0x0032
タイプ float
説明
用紙の表側について、ページの上端からどの程度離れた位置で印刷を開始するかを指定します。特
殊値 *DEVD は -2 としてエンコードされます。
前面オーバーレイ・ライブラリー名:
前面オーバーレイ・ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FTOVRLLIB
ID
0x0033
タイプ char[11]
説明
前面オーバーレイが入っているライブラリー名。前面オーバーレイ名前フィールドに特殊値が入っ
ている場合は、このフィールドはブランクです。
前面オーバーレイ名:
前面オーバーレイ名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FTOVRLAY
ID
0x0034
タイプ char[11]
説明
前面オーバーレイの名前。有効な特殊値には *NONE が含まれます。
前面オーバーレイ・オフセット (横方向):
前面オーバーレイ・オフセット (横方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FTOVL_ACR
ID
0x0036
タイプ float
説明
オーバーレイが印刷される起点から横方向へのオフセット。
前面オーバーレイ・オフセット (下方向):
前面オーバーレイ・オフセット (下方向) API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FTOVL_DWN
ID
0x0035
プログラミング
229
タイプ float
説明
オーバーレイが印刷される起点から下方へのオフセット。
グラフィック文字セット:
グラフィック文字セット API は、この製品と共に使用します。
キー
CWBOBJ_KEY_CHAR_ID
ID
0x0037
タイプ char[11]
説明
このファイルを印刷するときに使用されるグラフィック文字セット。有効な特殊値には、
*DEVD、*SYSVAL、および *JOBCCSID が含まれます。
ハードウェア位置合わせ:
ハードウェア位置合わせ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_JUSTIFY
ID
0x0038
タイプ long
説明
出力が右寄せされるその割合。有効な値は、0、50、および 100 です。
スプール・ファイルの保留:
スプール・ファイルの保留 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_HOLD
ID
0x0039
タイプ char[11]
説明
スプール・ファイルが保留されるかどうかを示します。有効な値は *YES または *NO です。
書き出しプログラムの初期設定:
書き出しプログラムの初期設定 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTRINIT
ID
0x00AC
タイプ char[11]
説明
プリンターを初期設定する時期をユーザーが指定することができます。有効な値は、*WTR、
*FIRST、*ALL です。
IP アドレス:
IP アドレス API は、この製品と共に使用します。
キー
CWBOBJ_KEY_INTERNETADDR
ID
0x0094
タイプ char[16]
説明
230
受信システムの IP アドレス。
IBM i: Windows アプリケーション・パッケージ: プログラミング
ジョブ名:
ジョブ名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_JOBNAME
ID
0x003B
タイプ char[11]
説明
スプール・ファイルを作成したジョブの名前。
ジョブ番号:
ジョブ番号 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_JOBNUMBER
ID
0x003C
タイプ char[7]
説明
スプール・ファイルを作成したジョブの番号。
ジョブ区切り:
ジョブ区切り API は、この製品と共に使用します。
キー
CWBOBJ_KEY_JOBSEPRATR
ID
0x003D
タイプ long
説明
この出力待ち行列にスプール・ファイルをもつ各ジョブの出力の最初に置かれるジョブ区切りの
数。有効な値は、-2 および 0 から 9 です。値 *MSG は -2 としてエンコードされます。ジョブ
区切りは、出力待ち行列が作成されるときに指定されます。
ジョブ・ユーザー:
ジョブ・ユーザー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USER
ID
0x003E
タイプ char[11]
説明
スプール・ファイルを作成したユーザーの名前。
印刷された最終ページ:
印刷された最終ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_LASTPAGE
ID
0x003F
タイプ long
説明
ジョブが処理を完了する前に印刷が終了した場合、ファイルの、最後に印刷されたページ番号。
プログラミング
231
ページの長さ:
ページの長さ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PAGELEN
ID
0x004E
タイプ float
説明
ページの長さ。測定単位は、測定方法属性に指定されます。
ライブラリー名:
ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_LIBRARY
ID
0x000F
タイプ char[11]
説明
ライブラリーの名前。
1 インチ当たりの行数:
1 インチ当たりの行数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_LPI
ID
0x0040
タイプ float
説明
スプール・ファイルの縦方向 1 インチ当たりの行数。
メーカー、機種型式:
メーカー、機種型式 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MFGTYPE
ID
0x0041
タイプ char[21]
説明
印刷データを SCS から ASCII へ変換するときに、メーカー、機種、および型式を指定します。
スプール出力レコードの最大数:
スプール出力レコードの最大数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MAXRECORDS
ID
0x0042
タイプ long
説明
このファイルがオープンされたときの、このファイルの最大許容レコード数。値 *NOMAX は 0
としてエンコードされます。
測定方法:
測定方法 API は、この製品と共に使用します。
232
IBM i: Windows アプリケーション・パッケージ: プログラミング
キー
CWBOBJ_KEY_MEASMETHOD
ID
0x004F
タイプ char[11]
説明
ページ長属性およびページ幅属性で使用される測定方法。有効な値は *ROWCOL または *UOM
です。
メッセージ・ヘルプ:
メッセージ・ヘルプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGHELP
ID
0x0081
タイプ char(*)
説明
2 次レベル・テキストとしても知られているメッセージ・ヘルプで、メッセージ検索要求がこのメ
ッセージ・ヘルプを戻すことができます。長さはシステムによって 3000 文字に制限されています
(英語バージョンでは、翻訳される場合を考慮してこれよりも 30 % 少なくなければなりません)。
メッセージ ID:
メッセージ ID API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MESSAGEID
ID
0x0093
タイプ char[8]
説明
メッセージ ID。
メッセージ待ち行列ライブラリー名:
メッセージ待ち行列ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGQUELIB
ID
0x0044
タイプ char[11]
説明
メッセージ待ち行列が入っているライブラリーの名前。
メッセージ待ち行列:
メッセージ待ち行列 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGQUE
ID
0x005E
タイプ char[11]
説明
書き出しプログラムが操作メッセージ用に使用する、メッセージ待ち行列の名前。
メッセージ応答:
メッセージ応答 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGREPLY
プログラミング
233
ID
0x0082
タイプ char[133]
説明
メッセージ応答。クライアントが出すテキスト・ストリングで、「照会」タイプのメッセージに応
答します。検索されるメッセージの場合は、属性値がサーバーによって戻され、これにはクライア
ントが使用できるデフォルト応答が含まれます。長さはシステムによって 132 文字に制限されて
います。可変長のため、NULL 文字で終わるようにしてください。
メッセージ・テキスト:
メッセージ・テキスト API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGTEXT
ID
0x0080
タイプ char[133]
説明
第 1 レベル・テキストとしても知られているメッセージ・テキストで、メッセージ検索要求がこ
のメッセージ・ヘルプを戻すことができます。長さはシステムによって 132 文字に制限されてい
ます。
メッセージ・タイプ:
メッセージ・タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGTYPE
ID
0x008E
タイプ char[3]
説明
メッセージ・タイプで、2 つの数字の EBCDIC エンコードされたものです。2 つのタイプのメッ
セージによって、検索されたメッセージに応答できるかどうかを示します。すなわち、通知メッセ
ージ '04' は応答を要求しないで情報を伝送し (代わりに訂正アクションが必要な場合がありま
す)、照会メッセージ '05' は情報を伝送して応答を要求します。
メッセージ重大度:
メッセージ重大度 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MSGSEV
ID
0x009F
タイプ long
説明
メッセージ重大度。値の範囲は 00 から 99 までです。値が高いほど、状況はより重大、もしくは
より重要です。
読み取り/書き込みバイト数:
読み取り/書き込みバイト数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NUMBYTES
ID
0x007D
タイプ long
234
IBM i: Windows アプリケーション・パッケージ: プログラミング
説明
読み取り操作において読み取るバイト数、または書き込み操作において書き込むバイト数。オブジ
ェクト・アクションがこの属性の解釈方法を決めます。
ファイル数:
ファイル数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NUMFILES
ID
0x0045
タイプ long
説明
出力待ち行列に存在するスプール・ファイルの数。
待ち行列に対して開始された書き出しプログラムの数:
待ち行列に対して開始された書き出しプログラムの数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NUMWRITERS
ID
0x0091
タイプ long
説明
出力待ち行列に対して開始された書き出しプログラム・ジョブの数。
オブジェクト拡張属性:
オブジェクト拡張属性 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OBJEXTATTR
ID
0x000B1
タイプ char[11]
説明
フォント資源のような、いくつかのオブジェクトによって使用される拡張属性。この値は、コマン
ドの WRKOBJ および DSPOBJD IBM i を通じて表示されます。 IBM i 画面上の表題は、「属性」の
みを示します。例えば、フォント資源のオブジェクト・タイプの場合、共通の値は、
CDEPAG、CDEFNT、および FNTCHRSET になります。
オープン時のコマンド:
オープン時のコマンド API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OPENCMDS
ID
0x00A0
タイプ char[11]
説明
スプール・ファイル・データに先立って、ユーザーが、SCS オープン時のコマンドをデータ・スト
リームに挿入するかどうかを指定します。有効な値は *YES または *NO です。
オペレーター制御:
オペレーター制御 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OPCNTRL
ID
0x0046
プログラミング
235
タイプ char[11]
説明
ジョブ制御権限をもつユーザーが、この待ち行列上のスプール・ファイルの管理または制御を許可
されているかどうかを示します。有効な値は *YES または *NO です。
待ち行列上のファイルの順序:
待ち行列上のファイルの順序 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ORDER
ID
0x0047
タイプ char[11]
説明
この出力待ち行列上のスプール・ファイルの順序。有効な値は *FIFO または *JOBNBR です。
出力優先順位:
出力優先順位 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OUTPTY
ID
0x0048
タイプ char[11]
説明
スプール・ファイルの優先順位。優先順位は 1 (最高) から 9 (最低) までです。有効な値は 0 か
ら 9 で、0 は *JOB を表します。
出力待ち行列ライブラリー名:
出力待ち行列ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OUTQUELIB
ID
0x0049
タイプ char[11]
説明
出力待ち行列が入っているライブラリーの名前。
出力待ち行列名:
出力待ち行列名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OUTQUE
ID
0x004A
タイプ char[11]
説明
出力待ち行列の名前。
出力待ち行列の状況:
出力待ち行列の状況 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OUTQUESTS
ID
0x004B
タイプ char[11]
説明
236
出力待ち行列の状況。有効な値は RELEASED または HELD です。
IBM i: Windows アプリケーション・パッケージ: プログラミング
オーバーフロー行番号:
オーバーフロー行番号 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_OVERFLOW
ID
0x004C
タイプ long
説明
印刷中のデータが、次のページへオーバーフローする前に印刷される最後の行。
面当たりページ数:
面当たりページ数 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_MULTIUP
ID
0x0052
タイプ long
説明
ファイルの印刷時に、各物理ページの各面に印刷する論理ページの数。有効な値は、1、2、および
4 です。
ペル密度:
ペル密度 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PELDENSITY
ID
0x00B2
タイプ char[2]
説明
フォント資源についてのみ、この値は、ペル数をエンコードしたものになります ("1" は、ペル・
サイズ 240 を表し、"2" はペル・サイズ 320 を表します)。追加した値は、システムによる定義が
行われると有効になります。
ポイント・サイズ:
ポイント・サイズ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_POINTSIZE
ID
0x0053
タイプ float
説明
このスプール・ファイルのテキストが印刷されるポイント・サイズ。特殊値 *NONE は 0 として
エンコードされます。
印刷精度:
印刷精度 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_FIDELITY
ID
0x0054
タイプ char[11]
説明
印刷時に実行されるエラー処理の種類。有効な値は *ABSOLUTE または *CONTENT です。
プログラミング
237
両面印刷:
両面印刷 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DUPLEX
ID
0x0055
タイプ char[11]
説明
情報が印刷される方法を示します。有効な値は、*FORMDF、*NO、*YES、および *TUMBLE で
す。
印刷品質:
印刷品質 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTQUALITY
ID
0x0056
タイプ char[11]
説明
このスプール・ファイルを印刷するときに使用される印刷品質。有効な値は、*STD、*DRAFT、
*NLQ、および *FASTDRAFT です。
印刷順序:
印刷順序 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTSEQUENCE
ID
0x0057
タイプ char[11]
説明
印刷順序。有効な値は *NEXT です。
印刷テキスト:
印刷テキスト API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTTEXT
ID
0x0058
タイプ char[31]
説明
印刷出力の各ページの下部および区切りページ上に印刷されるテキスト。有効な特殊値には
*BLANK と *JOB が含まれます。
プリンター:
プリンター API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRINTER
ID
0x0059
タイプ char[11]
説明
238
プリンターの名前。
IBM i: Windows アプリケーション・パッケージ: プログラミング
プリンター・タイプ:
プリンター・タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTDEVTYPE
ID
0x005A
タイプ char[11]
説明
プリンター・データ・ストリーム・タイプ。有効な値は、*SCS、*IPDS(*)、*USERASCII、および
*AFPDS です。
プリンター・ファイル・ライブラリー名:
プリンター・ファイル・ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTRFILELIB
ID
0x005B
タイプ char[11]
説明
プリンター・ファイルが入っているライブラリーの名前。
プリンター・ファイル名:
プリンター・ファイル名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PRTRFILE
ID
0x005C
タイプ char[11]
説明
プリンター・ファイルの名前。
プリンター待ち行列:
プリンター待ち行列 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RMTPRTQ
ID
0x005D
タイプ char[129]
説明
SNDTCPSPLF (LPR) によりスプール・ファイルを送信するときの宛先プリンター待ち行列の名
前。
レコードの長さ:
レコードの長さ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RECLENGTH
ID
0x005F
タイプ long
説明
レコードの長さ
プログラミング
239
リモート・システム:
リモート・システム API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RMTSYSTEM
ID
0x0060
タイプ char[256]
説明
リモート・システムの名前。有効な特殊値には *INTNETADR が含まれます。
印刷不能文字の置き換え:
印刷不能文字の置き換え API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RPLUNPRT
ID
0x0061
タイプ char[11]
説明
印刷できない文字が別の文字に置き換えられるかどうかを示します。有効な値は *YES または
*NO です。
置換文字:
置換文字 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RPLCHAR
ID
0x0062
タイプ char[2]
説明
印刷不能文字を置き換える文字。
資源ライブラリー名:
資源ライブラリー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RSCLIB
ID
0x00AE
タイプ char[11]
説明
外部 AFP (高機能印刷) 資源が入っているライブラリーの名前。
資源名:
資源名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RSCNAME
ID
0x00AF
タイプ char[11]
説明
外部 AFP 資源の名前。
資源オブジェクト・タイプ:
資源オブジェクト・タイプ API は、この製品と共に使用します。
240
IBM i: Windows アプリケーション・パッケージ: プログラミング
キー
CWBOBJ_KEY_RSCTYPE
ID
0x00B0
タイプ Long
説明
外部 AFP 資源オブジェクト・タイプの数値的、ビット・エンコード方式。値は、*FNTRSC、
*FORMDF、*OVL、*PAGSEG、*PAGDFN にそれぞれ対応して、0x0001、0x0002、0x0004、
0x0008、0x0010 になります。
印刷の再始動:
印刷の再始動 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_RESTART
ID
0x0063
タイプ long
説明
印刷の再始動。有効な値は、-1、-2、-3、または再始動する場所のページ番号です。値 *STRPAGE
は -1 として、*ENDPAGE は -2 として、*NEXT は -3 としてそれぞれエンコードされます。
スプール・ファイルの保管:
スプール・ファイルの保管 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SAVESPLF
ID
0x0064
タイプ char[11]
説明
スプール・ファイルが書き込まれた後、保管されるかどうかを示します。有効な値は *YES または
*NO です。
シーク・オフセット:
シーク・オフセット API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SEEKOFF
ID
0x007E
タイプ long
説明
シーク・オフセット。シーク起点に対応して正の値と負の値の両方が可能です。
起点のシーク:
起点のシーク API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SEEKORG
ID
0x007F
タイプ long
説明
有効な値には 1 (最初または上部)、2 (現行)、3 (終わりまたは下部) が含まれます。
送信優先順位:
送信優先順位 API は、この製品と共に使用します。
プログラミング
241
キー
CWBOBJ_KEY_SENDPTY
ID
0x0065
タイプ char[11]
説明
送信優先順位。有効な値は *NORMAL または *HIGH です。
区切りページ:
区切りページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SEPPAGE
ID
0x00A1
タイプ char[11]
説明
バナー・ページの印刷のオプションの使用許可をユーザーに与えます。有効な値は *YES または
*NO です。
ソース・ドロワー:
ソース・ドロワー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SRCDRWR
ID
0x0066
タイプ long
説明
カット用紙自動送りオプションが選択されたときに使用される用紙入れ。有効な値は、-1、-2、お
よび 1 - 255 です。値 *E1 は -1、値 *FORMDF は -2 としてそれぞれエンコードされます。
スプール SCS:
スプール SCS API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SPLSCS
ID
0x00AD
タイプ Long
説明
スプール・ファイルの作成中、どのようにして SCS データを使用するかを指示します。有効な値
は -1、0、1、またはページ番号です。値 *ENDPAGE は -1 としてエンコードされます。値 0 で
は、印刷はページ 1 から開始されます。値 1 では、ファイル全体が印刷されます。
データのスプール:
データのスプール API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SPOOL
ID
0x0067
タイプ char[11]
説明
242
プリンターの出力データがスプールされるかどうかを示します。有効な値は *YES または *NO で
す。
IBM i: Windows アプリケーション・パッケージ: プログラミング
スプール・ファイル名:
スプール・ファイル名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SPOOLFILE
ID
0x0068
タイプ char[11]
説明
スプール・ファイルの名前。
スプール・ファイル番号:
スプール・ファイル番号 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SPLFNUM
ID
0x0069
タイプ long
説明
スプール・ファイルの番号
スプール・ファイルの状況:
スプール・ファイルの状況 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SPLFSTATUS
ID
0x006A
タイプ char[11]
説明
スプール・ファイルの状況。有効な値は、
*CLOSED、*HELD、*MESSAGE、*OPEN、*PENDING、 *PRINTER、*READY、*SAVED、およ
び *WRITING です。
スプール出力のスケジュール:
スプール出力のスケジュール API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SCHEDULE
ID
0x006B
タイプ char[11]
説明
スプール・ファイルが書き出しプログラムで使用可能になったときに、スプール・ファイルについ
てだけ指定します。有効な値は、*IMMED、*FILEEND、および *JOBEND です。
開始ページ:
開始ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_STARTPAGE
ID
0x006C
タイプ long
説明
スプール・ファイルの印刷を開始するページの番号。有効な値は -1、0、1、またはページ番号で
す。値 *ENDPAGE は -1 としてエンコードされます。値 0 では、印刷はページ 1 から開始され
ます。値 1 では、ファイル全体が印刷されます。
プログラミング
243
テキスト記述:
テキスト記述 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_DESCRIPTION
ID
0x006D
タイプ [51]
説明
IBM i オブジェクトのインスタンスを記述するテキスト。
ファイルがオープンされた時刻:
ファイルがオープンされた時刻 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_TIMEOPEN
ID
0x006E
タイプ char[7]
説明
このスプール・ファイルがオープンされた時刻。時刻は HH MM SS 形式で、文字 0x0005 にエン
コードされます。
合計ページ:
合計ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PAGES
ID
0x006F
タイプ long
説明
スプール・ファイル中に含まれるページ数。
SCS から ASCII への変換:
SCS から ASCII への変換 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_SCS2ASCII
ID
0x0071
タイプ char[11]
説明
印刷データが SCS から ASCII に変換されるかどうかを示します。有効な値は *YES または *NO
です。
計測単位:
計測単位 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_UNITOFMEAS
ID
0x0072
タイプ char[11]
説明
244
距離を指定するために使用する測定単位。有効な値は *CM または *INCH です。
IBM i: Windows アプリケーション・パッケージ: プログラミング
ユーザー・コメント:
ユーザー・コメント API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USERCMT
ID
0x0073
タイプ char[101]
説明
スプール・ファイルを説明するユーザー指定の 100 文字の注釈。
ユーザー・データ:
ユーザー・データ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USERDATA
ID
0x0074
タイプ char[11]
説明
スプール・ファイルを説明するユーザー指定の 10 文字のデータ。有効な特殊値には *SOURCE
が含まれます。
ユーザー定義データ:
ユーザー定義データ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDFNDTA
ID
0x00A2
タイプ char[]
説明
スプール・ファイルを処理する、ユーザー・アプリケーションまたはユーザー指定プログラムによ
って利用されるユーザー定義データ。すべての文字が受け入れられます。最大値は 255 です。
ユーザー定義オブジェクト・ライブラリー:
ユーザー定義オブジェクト・ライブラリー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDFNOBJLIB
ID
0x00A4
タイプ char[11]
説明
スプール・ファイルを処理するユーザー・アプリケーションによって検索するためのユーザー定義
オブジェクト・ライブラリー。
ユーザー定義オブジェクト名:
ユーザー定義オブジェクト名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDFNOBJ
ID
0x00A5
タイプ char[11]
説明
スプール・ファイルを処理するユーザー・アプリケーションによって利用される、ユーザー定義オ
ブジェクト名。
プログラミング
245
ユーザー定義オブジェクト・タイプ:
ユーザー定義オブジェクト・タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDFNOBJTYP
ID
0x00A6
タイプ char[11]
説明
ユーザー定義オブジェクトに関係するユーザー定義オブジェクト・タイプ。
ユーザー定義オプション:
ユーザー定義オプション API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USEDFNOPTS
ID
0x00A3
タイプ char[*]
説明
スプール・ファイルを処理するユーザー・アプリケーションによって利用されるユーザー定義オプ
ション。最大 4 オプションまで指定することができ、それぞれの値の長さは、char(10) です。すべ
ての文字が受け入れられます。
ユーザー・ドライバー・プログラム:
ユーザー・ドライバー・プログラム API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDRVPGMDTA
ID
0x00A9
タイプ char[11]
説明
ユーザー・ドライバー・プログラムで使用されるユーザー・データ。すべての文字が受け入れられ
ます。最大サイズは 5000 文字です。
ユーザー・ドライバー・プログラム・ライブラリー:
ユーザー・ドライバー・プログラム・ライブラリー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDRVPGMLIB
ID
0x00AA
タイプ char[11]
説明
スプール・ファイルを処理するドライバー・プログラムを検索するための、ユーザー定義ライブラ
リー。
ユーザー・ドライバー・プログラム名:
ユーザー・ドライバー・プログラム名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRDRVPGM
ID
0x00AB
タイプ char[11]
説明
246
スプール・ファイルを処理するユーザー定義プログラム名。
IBM i: Windows アプリケーション・パッケージ: プログラミング
ユーザー ID:
ユーザー ID API は、この製品と共に使用します。
キー
CWBOBJ_KEY_TOUSERID
ID
0x0075
タイプ char[9]
説明
スプール・ファイルが送信される先のユーザー ID。
ユーザー ID アドレス:
ユーザー ID アドレス API は、この製品と共に使用します。
キー
CWBOBJ_KEY_TOADDRESS
ID
0x0076
タイプ char[9]
説明
スプール・ファイルが送信される先のユーザーのアドレス。
ユーザー変換プログラム・ライブラリー:
ユーザー変換プログラム・ライブラリー API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USRTFMPGMLIB
ID
0x00A7
タイプ char[11]
説明
変換プログラムを検索するユーザー定義ライブラリー。
ユーザー変換プログラム名:
ユーザー変換プログラム名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_USETFMPGM
ID
0x00A8
タイプ char[11]
説明
スプール・ファイル・データを、それがドライバー・プログラムによって処理される前に変換する
ユーザー定義変換プログラム名。
VM/MVS クラス:
VM/MVS クラス API は、この製品と共に使用します。
キー
CWBOBJ_KEY_VMMVSCLASS
ID
0x0077
タイプ char[2]
説明
VM/MVS クラス。有効な値は、A から Z および 0 から 9 です。
書き出しプログラムの自動終了時点:
書き出しプログラムの自動終了時点 API は、この製品と共に使用します。
プログラミング
247
キー
CWBOBJ_KEY_WTRAUTOEND
ID
0x0078
タイプ char[11]
説明
書き出しプログラムを自動的に終了する場合に、いつ終了させるかを指定します。有効な値は
*NORDYF または *FILEEND です。書き出しプログラムの自動終了の属性を *YES に設定してお
かなければなりません。
書き出しプログラムの終了時点:
書き出しプログラムの終了時点 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTREND
ID
0x0090
タイプ char[11]
説明
書き出しプログラムをいつ終了させるかを指定します。有効な値は、*CNTRLD、*IMMED、およ
び *PAGEEND です。これは「書き出しプログラムの自動終了時点」とは異なります。
ファイルの保留時点:
ファイルの保留時点 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_HOLDTYPE
ID
0x009E
タイプ char[11]
説明
スプール・ファイルをいつ保留するかを指定します。有効な値は *IMMED および *PAGEEND で
す。
ページ幅:
ページ幅 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_PAGEWIDTH
ID
0x0051
タイプ float
説明
ページの幅。測定単位は、測定方法属性に指定されます。
ワークステーション・カスタマイズ・オブジェクト名:
ワークステーション・カスタマイズ・オブジェクト名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WSCUSTMOBJ
ID
0x0095
タイプ char[11]
説明
ワークステーション・カスタマイズ・オブジェクトの名前。
ワークステーション・カスタマイズ・オブジェクト・ライブラリー:
ワークステーション・カスタマイズ・オブジェクト・ライブラリー API は、この製品と共に使用します。
248
IBM i: Windows アプリケーション・パッケージ: プログラミング
キー
CWBOBJ_KEY_WSCUSTMOBJL
ID
0x0096
タイプ char[11]
説明
ワークステーション・カスタマイズ・オブジェクトが入っているライブラリーの名前。
書き出しプログラム・ジョブ名:
書き出しプログラム・ジョブ名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WRITER
ID
0x0079
タイプ char[11]
説明
書き出しプログラム・ジョブの名前。
書き出しプログラム・ジョブ番号:
書き出しプログラム・ジョブ番号 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTRJOBNUM
ID
0x007A
タイプ char[7]
説明
書き出しプログラム・ジョブの番号。
書き出しプログラム・ジョブ状況:
書き出しプログラム・ジョブ状況 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTRJOBSTS
ID
0x007B
タイプ char[11]
説明
書き出しプログラム・ジョブの状況。有効な値は、STR、END、JOBQ、HLD、および MSGW で
す。
書き出しプログラム・ジョブ・ユーザー名:
書き出しプログラム・ジョブ・ユーザー名 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTRJOBUSER
ID
0x007C
タイプ char[11]
説明
書き出しプログラム・ジョブを開始したユーザーの名前。
書き出しプログラム開始ページ:
書き出しプログラム開始ページ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_WTRSTRPAGE
ID
0x008F
プログラミング
249
タイプ long
説明
書き出しプログラム・ジョブを開始したときに、最初のスプール・ファイルから印刷する最初のペ
ージのページ番号を指定します。これは、書き出しプログラムを開始したときにスプール・ファイ
ル名もまた指定されている場合にのみ有効です。
ネットワーク印刷サーバー・オブジェクトの属性:
この製品使用時の、ネットワーク印刷サーバーのオブジェクト属性のリストを、以下に示します。
NPS 属性のデフォルト値:
NPS 属性のデフォルト値 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRDEFAULT
ID
0x0083
タイプ dynamic
説明
属性のデフォルト値。
NPS 属性の高限界:
NPS 属性の高限界 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRMAX
ID
0x0084
タイプ dynamic
説明
属性値の高限界。
NPS 属性 ID:
NPS 属性 ID API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRID
ID
0x0085
タイプ long
説明
属性の ID。
NPS 属性の低限界:
NPS 属性の低限界 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRMIN
ID
0x0086
タイプ dynamic
説明
属性値の低限界。
NPS 属性の可能値:
NPS 属性の可能値 API は、この製品と共に使用します。
キー
250
CWBOBJ_KEY_ATTRPOSSIBL
IBM i: Windows アプリケーション・パッケージ: プログラミング
ID
0x0087
タイプ dynamic
説明
属性の可能値。複数の NPS 可能値インスタンスがコード・ポイントに存在する場合があります。
NPS 属性テキスト記述:
NPS 属性テキスト記述 API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRDESCRIPT
ID
0x0088
タイプ char(*)
説明
属性の名前を与えるテキスト記述。
NPS 属性タイプ:
NPS 属性タイプ API は、この製品と共に使用します。
キー
CWBOBJ_KEY_ATTRTYPE
ID
0x0089
タイプ long
説明
属性のタイプ。有効な値は、ネットワーク印刷サーバーが定義するタイプです。
NPS CCSID:
NPS CCSID API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NPSCCSID
ID
0x008A
タイプ long
説明
すべてのストリングがこれによってエンコードされているものとネットワーク印刷サーバーが予測
している CCSID。
NPS オブジェクト:
NPS オブジェクト API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NPSOBJECT
ID
0x008B
タイプ long
説明
オブジェクト ID。有効な値は、ネットワーク印刷サーバーが定義するオブジェクトです。
NPS オブジェクト・アクション:
NPS オブジェクト・アクション API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NPSACTION
ID
0x008C
タイプ long
プログラミング
251
説明
アクション ID。有効な値は、ネットワーク印刷サーバーが定義するアクションです。
NPS レベル:
NPS レベル API は、この製品と共に使用します。
キー
CWBOBJ_KEY_NPSLEVEL
ID
0x008D
タイプ char[7]
説明
ネットワーク印刷サーバーのバージョン・レベル、リリース・レベル、およびモディフィケーショ
ン・レベルです。この属性は VXRYMY としてエンコードされた文字ストリング (例えば、
「V3R1M0」など) です。この場合の X と Y は次のようになります。
X is in (0..9)
Y is in (0..9,A..Z)
リスト API
以下の API は、リスト・オブジェクトに関するものです。 API はアルファベット順にリストされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CloseList:
cwbOBJ_CloseList API は、この製品と共に使用します。
目的
オープンされているリストをクローズします。
構文
unsigned int CWB_ENTRY
cwbOBJ_CloseList(
cwbOBJ_ListHandle
cwbSV_ErrHandle
listHandle,
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
クローズされるリストのハンドル。このリストはオープンされていなければなりません。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
252
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
CWBOBJ_RC_LIST_NOT_OPEN
リストがオープンされていません。
使用法
リストをクローズすると、その項目を保持するためにリストが使用した記憶域が解放されます。
cwbOBJ_GetObjHandle() API で得られたいずれのオブジェクト・ハンドルも、資源を解放するため、リス
トをクローズする前に解放してください。これらのハンドルは、もはや有効ではありません。
cwbOBJ_CreateListHandle:
cwbOBJ_CreateListHandle API は、この製品と共に使用します。
目的
オブジェクトのリスト用のハンドルを割り振ります。このリスト・ハンドルが割り振られると、
cwbOBJ_SetListFilter() API によるリストのフィルター基準の設定、cwbOBJ_OpenList() API によるリスト
の作成などが可能になります。このリスト・ハンドルを割り振り解除し、これによって使用されていたすべ
ての資源を解放するには、cwbOBJ_DeleteListHandle() を呼び出してください。
構文
unsigned int CWB_ENTRY
cwbOBJ_CreateListHandle(
const char
*systemName,
cwbOBJ_ListType
type,
cwbOBJ_ListHandle *listHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
cwbOBJ_ListType type - input
割り振りを行うリストのタイプ (例えば、スプール・ファイル・リスト、出力待ち行列リストなど)。
cwbOBJ_ListHandle *listHandle - output
出力の際に返されるリスト・ハンドルを指すポインター。このハンドルは、他の呼び出しでリストを使
用する時に必要になります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
253
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
このリスト・ハンドルの使用が終わった後に、呼び出し側は cwbOBJ_DeleteListHandle を呼び出す必要があ
ります。オブジェクトのリストを検索するための一般的な呼び出し手順を以下に示します。
1. cwbOBJ_CreateListHandle()
2. cwbOBJ_SetListFilter() { 必要に応じて繰り返す }
3. cwbOBJ_OpenList()
4. cwbOBJ_GetListSize() リストのサイズを取得する
5. n=0 からリスト・サイズ -1 の位置 n にあるリスト項目に対する cwbOBJ_GetObjHandle を
cwbOBJ_DeleteObjHandle() によって何らかの処理を行う。
6. cwbOBJ_CloseList() - ここからステップ 2 へ戻ることができる
7. cwbOBJ_DeleteListHandle()
cwbOBJ_DeleteListHandle:
cwbOBJ_DeleteListHandle API は、この製品と共に使用します。
目的
cwbOBJ_CreateListHandle() API で以前割り振られていたリスト・ハンドルを割り振り解除します。これに
より、リストに関連する資源はすべて解放されます。
構文
unsigned int CWB_ENTRY
cwbOBJ_DeleteListHandle(
cwbOBJ_ListHandle listHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
削除されるリスト・ハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
254
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_INVALID_HANDLE
リスト・ハンドルが見付かりません。
使用法
このハンドルに関連するリストがオープンされている場合は、この呼び出しがリストをクローズします。こ
のリスト内にオープンされたオブジェクトのハンドルがあっても、それらはもはや有効ではありません。こ
の呼び出しが正常に戻ったあとでは、リスト・ハンドルはもはや有効ではありません。
cwbOBJ_GetListSize:
cwbOBJ_GetListSize API は、この製品と共に使用します。
目的
オープンされたリストのサイズを取得します。
構文
unsigned int CWB_ENTRY
cwbOBJ_GetListSize(
cwbOBJ_ListHandle
listHandle,
unsigned long
*size,
cwbOBJ_List_Status *listStatus,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
サイズを取得するリストのハンドル。このリストはオープンされていなければなりません。
unsigned long *size - output
出力の際に、リストの現行サイズに設定されます。
cwbOBJ_List_Status *listStatus - output
オプションであり、NULL でも構いません。同時にオープンされたリストでは常に、
CWBOBJ_LISTSTS_COMPLETED です。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
プログラミング
255
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_LIST_NOT_OPEN
リストがオープンされていません。
使用法
なし (None)
cwbOBJ_OpenList:
cwbOBJ_OpenList API は、この製品と共に使用します。
目的
リストをオープンします。これは実際にリストを作成します。このリストの使用を終了したときは、資源を
解放するために、呼び出し側は cwbOBJ_ClostList() API を呼び出さなければなりません。リストがオープ
ンされたあと、呼び出し側は、リスト・サイズの取得、あるいはリスト中の項目のオブジェクト・ハンドル
の取得などのような処理を行うためにリスト上の他の API を使用することができます。
構文
unsigned int CWB_ENTRY
cwbOBJ_OpenList(
cwbOBJ_ListHandle
cwbOBJ_List_OpenType
cwbSV_ErrHandle
listHandle,
openType,
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
オープンするリストのハンドル。
cwbOBJ_List_OpenType openHandle - input
リストをオープンする方法。CWBOBJ_LIST_OPEN_SYNCH に設定されなければなりません。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
256
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBOBJ_RC_LIST_OPEN
リストは既にオープンされています。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_NOHOSTSUPPORT
ホストでは、このタイプのリストはサポートしていません。
使用法
なし (None)
cwbOBJ_ResetListAttrsToRetrieve:
cwbOBJ_ResetListAttrsToRetrieve API は、この製品と共に使用します。
目的
情報を検索するリストの属性を、デフォルトのリストのものにリセットします。
構文
unsigned int CWB_ENTRY
cwbOBJ_ResetListAttrsToRetrieve(
cwbOBJ_ListHandle
listHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
リセットするリスト・ハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
使用法
cwbOBJ_SetListAttrsToRetrieve() を呼び出した後、この呼び出しを使用して、検索するリスト・ハンドルの
属性のリストをリセットしてください。
cwbOBJ_ResetListFilter:
cwbOBJ_ResetListFilter API は、この製品と共に使用します。
プログラミング
257
目的
リスト上のフィルターを、そのリストが最初に割り振られたときのフィルター (デフォルトのフィルター)
にリセットします。
構文
unsigned int CWB_ENTRY
cwbOBJ_ResetListFilter(
cwbOBJ_ListHandle
cwbSV_ErrHandle
listHandle,
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
そのフィルターがリセットされるリストのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
使用法
変更を反映するためには、リストをクローズしてから、再度オープンする必要があります。
cwbOBJ_SetListAttrsToRetrieve:
cwbOBJ_SetListAttrsToRetrieve API は、この製品と共に使用します。
目的
リストがオープンされる前に、リスト・ハンドルに適用できるオプションの機能。これを行う目的は、
cwbOBJ_OpenList() API が、アプリケーションで使用される各オブジェクトの属性のみを検索できるように
して効率を改善することです。
構文
unsigned int CWB_ENTRY
258
cwbOBJ_SetListAttrsToRetrieve(
cwbOBJ_ListHandle
listHandle,
unsigned long
numKeys,
const cwbOBJ_KeyID *keys,
cwbSV_ErrHandle
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbOBJ_ListHandle listHandle - input
属性キーのリストを適用するリスト・ハンドル。
unsigned long numKeys - input
キー・パラメーターが指すキーの数。0 でも構いません。この場合、リスト中のオブジェクトには属性
が必要でないことを意味します。
const cwbOBJ_KeyID *keys - input
リストがオープンされたときに、リスト中の各オブジェクトごとに検索される属性の ID である
numKeys キーの配列。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
使用法
この呼び出しは、リストされているオブジェクトのどの属性にアプリケーションが関心をもっているかにつ
いて、cwbOBJ_OpenList() API への手掛かりを与えるために使用されます。この情報を使用すると、
cwbOBJ_OpenList() API をより効率的にすることができます。キー・リスト中の属性キーが有効かどうか
は、リストされたオブジェクトのタイプによって決まります (cwbOBJ_CreateListHandle() に設定されま
す)。リストをキーの、デフォルトのリストにリセットするには、cwbOBJ_ResetListAttrsToRetrieve() を呼び
出してください。
cwbOBJ_SetListFilter:
cwbOBJ_SetListFilter API は、この製品と共に使用します。
目的
リストのフィルターを設定します。このフィルターは、cwbOBJ_OpenList() が次に呼び出されるときに適用
されます。
プログラミング
259
構文
unsigned int CWB_ENTRY
cwbOBJ_SetListFilter(
cwbOBJ_ListHandle listHandle,
cwbOBJ_KeyID
key,
const char
*value,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
このフィルターが適用されるリスト・ハンドル。
cwbOBJ_KeyID key - input
設定されるフィルター・フィールドの ID。
const void *value - input
このフィールドに設定すべき値。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
リスト・ハンドルが見付かりません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
キーの値によって、値が指すタイプが決まります。値の長さは、そのタイプによって決まります。次のフィ
ルターは、これらのリスト・タイプのスプール・ファイル・リストに対して設定することができます。
v
CWBOBJ_LIST_SPLF:
– CWBOBJ_KEY_USER
どのユーザーのスプール・ファイルをリストするかを指定。特定のユーザー ID または次の特殊値:
*ALL - 全ユーザー。 *CURRENT - 現行ユーザーのリスト・スプール・ファイルのみ。 *CURRENT
がデフォルト。
– CWBOBJ_KEY_OUTQUELIB
どのライブラリーで出力待ち行列を検索するかを指定。特定の名前または次のいずれかの特殊値: "" OUTQUEUE キーワードが *ALL の場合は、この組み合わせはシステム上のすべての出力待ち行列を
260
IBM i: Windows アプリケーション・パッケージ: プログラミング
検索する。 *CURLIB - 現行ライブラリー *LIBL - ライブラリー・リスト OUTQUE フィルターが
*ALL でない場合 *LIBL がデフォルト。OUTQUE フィルターが *ALL に設定されている場合、""
がデフォルト。
– CWBOBJ_KEY_OUTQUE
どの出力待ち行列でスプール・ファイルを検索するかを指定。特定の名前または特殊値 *ALL が可。
*ALL がデフォルト。
– CWBOBJ_KEY_FORMTYPE
持っている用紙タイプ属性によって、どのスプール・ファイルがリストされるかを指定。特定の名前
または次のいずれかの特殊値: *ALL - どの用紙タイプを持つスプール・ファイルもリストされる。
*STD - 用紙タイプが *STD のスプール・ファイルがリストされる。 *ALL がデフォルト。
– CWBOBJ_KEY_USERDATA
持っているユーザー・データによって、どのスプール・ファイルがリストされるかを指定。特定の値
または次のいずれかの特殊値: *ALL - どのユーザー・データ値を持つスプール・ファイルもリストさ
れる。*ALL がデフォルト。
出力待ち行列リスト
v CWBOBJ_LIST_OUTQ:
– CWBOBJ_KEY_OUTQUELIB
どのライブラリーで出力待ち行列を検索するかを指定。特定の名前、総称名、または次のいずれかの
特殊値: *ALL - すべてのライブラリー *ALLUSER - すべてのユーザー定義ライブラリーに加えて、
ユーザー・データが入っていて Q で始まる名前を持つライブラリー。 *CURLIB - 現行ライブラリ
ー。 *LIBL - ライブラリー・リスト。 *USRLIBL - ライブラリー・リストのユーザー部分。*LIBL
がデフォルト。
–
- CWBOBJ_KEY_OUTQUE
どの出力待ち行列をリストするかを指定。特定の名前、総称名、または *ALL。*ALL がデフォル
ト。
プリンター記述リスト
v CWBOBJ_LIST_PRTD:
– CWBOBJ_KEY_PRINTER
どのプリンターをリストするかを指定。特定の名前、総称名、または *ALL。*ALL がデフォルト。
プリンター・ファイル・リスト
v CWBOBJ_LIST_PRTF:
– CWBOBJ_KEY_PRTRFILELIB
プリンター・ファイルを検索するライブラリーを指定。特定の名前、総称名、または次のいずれかの
特殊値。
- *ALL - すべてのライブラリー
- *ALLUSER - すべてのユーザー定義のライブラリーに加えて、ユーザー・データが入っており Q
で始まる名前を持つライブラリー
プログラミング
261
- *CURLIB - 現行ライブラリー
- *LIBL - ライブラリー・リスト
- *USRLIBL - ライブラリー・リストのユーザー部分
- *ALL がデフォルト。
– CWBOBJ_KEY_PRTRFILE
どのプリンター・ファイルをリストするかを指定。特定の名前、総称名、または *ALL。*ALL がデ
フォルト。
書き出しプログラム・ジョブ・リスト
v CWBOBJ_LIST_WTR:
– CWBOBJ_KEY_WRITER
どの書き出しプログラム・ジョブをリストするかを指定。特定の名前、総称名、または *ALL。*ALL
がデフォルト。
– CWBOBJ_KEY_OUTQUELIB および CWBOBJ_KEY_OUTQUE
これらのフィルターは、特定の出力待ち行列に対して活動中の書き出しプログラムのリストを取得す
るために共に使用される。OUTQUE キーが指定されると WRITER キーは無視される (指定された出
力待ち行列のすべての書き出しプログラムがリストされる)。OUTQUE キーが指定されていて、
OUTQUELIB が指定されていない場合は、OUTQUEULIB はデフォルトで *LIBL、つまりシステム・
ライブラリー・リストになる。デフォルトは、これらのいずれにも指定されない。
ライブラリー・リスト
v CWBOBJ_LIST_LIB:
– CWBOBJ_KEY_LIBRARY
どのライブラリーをリストするかを指定。特定の名前、総称名、または次のいずれかの特殊値。
- *ALL - すべてのライブラリー
- *CURLIB - 現行ライブラリー
- *LIBL - ライブラリー・リスト
- *USRLIBL - ライブラリー・リストのユーザー部分
- *USRLIBL がデフォルト。
v CWBOBJ_LIST_RSC:
– 資源は、スプール・ファイル内のリスト (この場合は、そのスプール・ファイルで使用するすべての
外部 AFP 資源のリスト)、ライブラリー内のリスト、またはライブラリー・セット内のリストの場合
があります。スプール・ファイルの資源をリストする場合は、RSCTYPE 属性と RSCNAME 属性用
の SetListFilter API と一緒に cwbOBJ_SetListFilterWithSplF API を使用してください。
- CWBOBJ_KEY_RSCLIB
資源を検索するライブラリーを指定します。リストがスプール・ファイルによってフィルターに掛
けられる (たとえば、SetListFilterWithSplF を使用する) 場合、このフィルターは無視されます。特
定の名前、総称名、または次のいずれかの特殊値。
v *ALL - すべてのライブラリー
v *ALLUSR - すべてのユーザー定義のライブラリーに加えて、ユーザー・データが収められてお
り Q で始まる名前を持つライブラリー
262
IBM i: Windows アプリケーション・パッケージ: プログラミング
v *CURLIB - 現行ライブラリー
v *LIBL - ライブラリー・リスト
v *USRLIBL - ライブラリー・リストのユーザー部分
v *LIBL がデフォルト。
- CWBOBJ_KEY_RSCNAME
リストする資源の名前を指定します。特定の名前、総称名、または *ALL。
*ALL がデフォルト。
- CWBOBJ_KEY_RESCTYPE
リストする資源のタイプを指定します。論理和演算が行われた次のビットのどのような組み合わせ
を指定することもできます。
v CWBOBJ_AFPRSC_FONT
v CWBOBJ_AFPRSC_FORMDEF
v CWBOBJ_AFPRSC_OVERLAY
v CWBOBJ_AFPRSC_PAGESEG
v CWBOBJ_AFPRSC_PAGEDEF
cwbOBJ_SetListFilterWithSplF:
cwbOBJ_SetListFilterWithSplF API は、この製品と共に使用します。
目的
スプール・ファイルに対してリスト用のフィルターを設定します。資源のリスト表示に関して、この呼び出
しは、openList によって戻される資源をスプール・ファイルで使用されるものに限定します。
構文
unsigned int CWB_ENTRY
cwbOBJ_SetListFilterWithSplF(
cwbOBJ_ListHandle listHandle,
cwbOBJ_ObjHandle
splFHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
このフィルターが適用されるリスト・ハンドル。
cwbOBJ_ObjHandle splFHandle - input
フィルターを行うスプール・ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
プログラミング
263
CWB_OK
正常終了。
CWBOBJ_RC_INVALID_TYPE
リストの誤ったタイプ。
CWB_INVALID_HANDLE
リスト・ハンドルが見付からないか、またはスプール・ファイル・ハンドルが正しくない。
使用法
AFP 資源をリスト表示するとき、スプール・ファイルによるフィルター操作が使用されるため、リスト・
タイプは CWBOBJ_LIST_RSC である必要があります。スプール・ファイルに基づいて資源をフィルター
に掛ける場合も、1 つまたは複数のライブラリーに基づいて資源をフィルターに掛けることはできません。
両方が指定された場合は、資源ライブラリー・フィルターが無視されます。リスト・フィルターをリセット
すると、スプール・ファイル・フィルターもまた、何もない状態にリセットされます。
オブジェクト API
以下の API は、オブジェクトに関するものです。 API はアルファベット順にリストされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CopyObjHandle:
cwbOBJ_CopyObjHandle API は、この製品と共に使用します。
目的
オブジェクトに重複ハンドルを作成します。この API を使用して、同じ IBM i オブジェクトの別のハン
ドルを取得します。この新規ハンドルは、それを解放するための cwbOBJ_DeleteObjHandle() API が呼び出
されるまで有効です。
構文
unsigned int CWB_ENTRY
cwbOBJ_CopyObjHandle(
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbSV_ErrHandle
objectHandle,
*newObjectHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
コピーするオブジェクトのハンドル。
cwbOBJ_ObjHandle *newObjectHandle - output
この呼び出しが正常に完了すると、このハンドルには新規のオブジェクト・ハンドルが入ります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
264
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
使用法
あるリスト上のオブジェクトへのハンドルを持っていて、このリストがクローズされた後もそのオブジェク
トのハンドルを保持したい場合、この API を使用してハンドルを保持することができます。このハンドル
用の資源を解放するには、cwbOBJ_DeleteObjHandle() を呼び出す必要があります。
cwbOBJ_DeleteObjHandle:
cwbOBJ_DeleteObjHandle API は、この製品と共に使用します。
目的
オブジェクトへのハンドルを解放します。
構文
unsigned int CWB_ENTRY
cwbOBJ_DeleteObjHandle(
cwbOBJ_ObjHandle objectHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
解放するオブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
プログラミング
265
使用法
なし (None)
cwbOBJ_GetObjAttr:
cwbOBJ_GetObjAttr API は、この製品と共に使用します。
目的
オブジェクトの属性を取得します。
構文
unsigned int CWB_ENTRY cwbOBJ_GetObjAttr(
cwbOBJ_ObjHandle objectHandle,
cwbOBJ_KeyID
key,
void
*buffer,
unsigned long
bufLen,
unsigned long
*bytesNeeded,
cwbOBJ_DataType *keyType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
属性を取得するオブジェクトのハンドル。
cwbOBJ_KeyID key - input
検索する属性の識別キー。CWBOBJ_KEY_XXX 定数がキー ID を定義します。objectHandle が指すオ
ブジェクトのタイプによって、どのキーが有効かが決まります。
void *buffer - output
この呼び出しが正常に戻った場合は、属性値を保持するバッファー。*Buffer に置かれるデータ・タイ
プは何かをキー値が決定します。タイプが与えられた場合、このタイプも *keyType パラメーターへ戻
されます。
unsigned long bufLen - input
*Buffer が指すバッファーの長さ。
unsigned long *bytesNeeded - output
出力の際には、結果を保持するために必要なバイト数が入ります。
cwbOBJ_DataType *keyType - output
オプションであり、NULL でも構いません。出力の際には、この属性と、*buffer に何が保管されるか
を表すために使用されるデータ・タイプが含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
266
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_KEY
キーが有効ではありません。
CWB_API_ERROR
一般 API 障害。
使用法
次に挙げるオブジェクト・タイプでは、以下の属性を検索することができます。
v
CWBOBJ_LIST_SPLF:
CWBOBJ_KEY_AFP
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_BKMGN_ACR
CWBOBJ_KEY_BKMGN_DWN
CWBOBJ_KEY_BKOVRLLIB
CWBOBJ_KEY_BKOVRLAY
CWBOBJ_KEY_BKOVL_ACR
CWBOBJ_KEY_BKOVL_DWN
CWBOBJ_KEY_CPI
CWBOBJ_KEY_CODEDFNTLIB
CWBOBJ_KEY_CODEDFNT
CWBOBJ_KEY_COPIES
CWBOBJ_KEY_COPIESLEFT
CWBOBJ_KEY_CURPAGE
CWBOBJ_KEY_DATE
CWBOBJ_KEY_PAGRTT
CWBOBJ_KEY_ENDPAGE
CWBOBJ_KEY_FILESEP
CWBOBJ_KEY_FOLDREC
CWBOBJ_KEY_FONTID
CWBOBJ_KEY_FORMFEED
CWBOBJ_KEY_FORMTYPE
CWBOBJ_KEY_FTMGN_ACR
CWBOBJ_KEY_FTMGN_DWN
CWBOBJ_KEY_FTOVRLLIB
CWBOBJ_KEY_FTOVRLAY
CWBOBJ_KEY_FTOVL_ACR
CWBOBJ_KEY_FTOVL_DWN
CWBOBJ_KEY_CHAR_ID
CWBOBJ_KEY_JUSTIFY
CWBOBJ_KEY_HOLD
CWBOBJ_KEY_JOBNAME
CWBOBJ_KEY_JOBNUMBER
CWBOBJ_KEY_USER
CWBOBJ_KEY_LASTPAGE
CWBOBJ_KEY_LPI
CWBOBJ_KEY_MAXRECORDS
CWBOBJ_KEY_OUTPTY
-
使用された AFP 資源
ページの位置合わせ
バック・マージン (横方向)
バック・マージン (下方向)
背面オーバーレイ・ライブラリー名
背面オーバーレイ名
背面オーバーレイ・オフセット (横方向)
背面オーバーレイ・オフセット (下方向)
1 インチ当たりの文字数
コード化フォント・ライブラリー名
コード化フォント
合計コピー数
作成されていない残りのコピー
現行ページ
ファイルがオープンされた日付
ページの回転角度
終了ページ
ファイル区切り
レコードの折り返し
使用するフォント識別コード (デフォルト)
用紙送り
用紙タイプ
フロント・マージン (横方向)
フロント・マージン (下方向)
前面オーバーレイ・ライブラリー名
前面オーバーレイ
前面オーバーレイ・オフセット (横方向)
前面オーバーレイ・オフセット (下方向)
グラフィック文字セット
ハードウェアの位置合わせ
スプール・ファイルの保留
ファイルを作成したジョブの名前
ファイルを作成したジョブの番号
ファイルを作成したユーザーの名前
印刷された最終のページ
1 インチ当たりの行数
許容最大レコード数
出力優先順位
プログラミング
267
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_OVERFLOW
CWBOBJ_KEY_PAGELEN
CWBOBJ_KEY_MEASMETHOD
CWBOBJ_KEY_PAGEWIDTH
CWBOBJ_KEY_MULTIUP
CWBOBJ_KEY_POINTSIZE
CWBOBJ_KEY_FIDELITY
CWBOBJ_KEY_DUPLEX
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_PRTTEXT
CWBOBJ_KEY_PRTDEVTYPE
CWBOBJ_KEY_PRTRFILELIB
CWBOBJ_KEY_PRTRFILE
CWBOBJ_KEY_RECLENGTH
CWBOBJ_KEY_RPLUNPRT
CWBOBJ_KEY_RPLCHAR
CWBOBJ_KEY_RESTART
CWBOBJ_KEY_SAVESPLF
CWBOBJ_KEY_SRCDRWR
CWBOBJ_KEY_SPOOLFILE
CWBOBJ_KEY_SPLFNUM
CWBOBJ_KEY_SPLFSTATUS
CWBOBJ_KEY_STARTPAGE
CWBOBJ_KEY_TIME
CWBOBJ_KEY_PAGES
CWBOBJ_KEY_UNITOFMEAS
CWBOBJ_KEY_USERCMT
CWBOBJ_KEY_USERDATA
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJTYP
-
出力待ち行列ライブラリー名
出力待ち行列
オーバーフロー行番号
ページ長
測定方法
ページ幅
面当たりの論理ページ数
デフォルトのフォントのポイント・サイズ
印刷精度
両面印刷
印刷品質
各ページの下部に印刷されたテキスト
プリンター・タイプ (データ・ストリーム・タイプ)
プリンター・ファイル・ライブラリー
プリンター・ファイル
レコード長
印刷不能文字の置き換え
印刷不能文字の置き換え文字
印刷再始動位置
印刷後のファイルの保管
用紙入れ
スプール・ファイル名
スプール・ファイル番号
スプール・ファイル状況
印刷開始ページ
スプール・ファイルがオープンされた時刻
スプール・ファイル中のページ数
測定単位
ユーザーの注釈
ユーザー・データ
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト・タイプ
-
検査権限
データ待ち行列ライブラリー
データ待ち行列
テキスト記述
ユーザーは待ち行列のいずれのファイルも表示可能
ジョブ区切りの数
出力待ち行列のスプール・ファイルの合計
待ち行列が開始された書き出しプログラムの数
オペレーター制御
待ち行列上の配列 (順序)
出力待ち行列ライブラリー名
出力待ち行列
出力待ち行列状況
プリンター
バナー・ページの印刷
ユーザー定義データ
ユーザー定義オブジェクト
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト・タイプ
ユーザー定義オプション
ユーザー・ドライバー・プログラム
ユーザー・ドライバー・プログラム・ライブラリー
ユーザー・ドライバー・プログラム・データ
ユーザー・データ変換プログラム
ユーザー・データ変換プログラム・ライブラリー
書き出しプログラム・ジョブ名
書き出しプログラム・ジョブ番号
書き出しプログラム・ジョブ状況
書き出しプログラム・ジョブ・ユーザー
v CWBOBJ_LIST_OUTQ:
CWBOBJ_KEY_AUTHCHCK
CWBOBJ_KEY_DATAQUELIB
CWBOBJ_KEY_DATAQUE
CWBOBJ_KEY_DESCRIPTION
CWBOBJ_KEY_DISPLAYANY
CWBOBJ_KEY_JOBSEPRATR
CWBOBJ_KEY_NUMFILES
CWBOBJ_KEY_NUMWRITERS
CWBOBJ_KEY_OPCNTRL
CWBOBJ_KEY_ORDER
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_OUTQUESTS
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_SEPPAGE
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJTYP
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDRVPGM
CWBOBJ_KEY_USRDRVPGMLIB
CWBOBJ_KEY_USRDRVPGMDTA
CWBOBJ_KEY_USRTFMPGM
CWBOBJ_KEY_USRTFMPGMLIB
CWBOBJ_KEY_WRITER
CWBOBJ_KEY_WTRJOBNUM
CWBOBJ_KEY_WTRJOBSTS
CWBOBJ_KEY_WTRJOBUSER
268
IBM i: Windows アプリケーション・パッケージ: プログラミング
v CWBOBJ_LIST_PRTD:
CWBOBJ_KEY_AFP
CWBOBJ_KEY_CODEPAGE
CWBOBJ_KEY_DEVCLASS
CWBOBJ_KEY_DEVMODEL
CWBOBJ_KEY_DEVTYPE
CWBOBJ_KEY_DRWRSEP
CWBOBJ_KEY_FONTID
CWBOBJ_KEY_FORMFEED
CWBOBJ_KEY_CHAR_ID
CWBOBJ_KEY_MFGTYPE
CWBOBJ_KEY_MSGQUELIB
CWBOBJ_KEY_MSGQUE
CWBOBJ_KEY_POINTSIZE
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_DESCRIPTION
CWBOBJ_KEY_SCS2ASCII
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJTYP
CWBOBJ_KEY_USRTFMPGMLIB
-
使用された AFP 資源
コード・ページ
装置クラス
装置モデル
装置タイプ
区切り用紙入れ
フォント識別コード
用紙送り
グラフィック文字セット
メーカーの機種とモデル
メッセージ待ち行列ライブラリー
メッセージ待ち行列
デフォルトのフォントのポイント・サイズ
プリンター
印刷品質
テキスト記述
SCS から ASCII への変換
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト
ユーザー定義オブジェクト・タイプ
ユーザー・データ変換プログラム・ライブラリー
CWBOBJ_KEY_USRTFMPGM
CWBOBJ_KEY_USRDRVPGMDTA
CWBOBJ_KEY_USRDRVPGMLIB
CWBOBJ_KEY_USRDRVPGM
-
ユーザー・データ変換プログラム
ユーザー・ドライバー・プログラム・データ
ユーザー・ドライバー・プログラム・ライブラリー
ユーザー・ドライバー・プログラム
-
ページの位置合わせ
バック・マージン (横方向)
バック・マージン (下方向)
背面オーバーレイ・ライブラリー
背面オーバーレイ名
背面オーバーレイ・オフセット (下方向)
背面オーバーレイ・オフセット (横方向)
1 インチ当たりの文字数
コード化フォント・ライブラリー名
コード・ページ
コード化フォント
合計コピー数
DBCS 文字セット・データを含む
DBCS 拡張文字の処理
v CWBOBJ_LIST_PRTF:
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_BKMGN_ACR
CWBOBJ_KEY_BKMGN_DWN
CWBOBJ_KEY_BKOVRLLIB
CWBOBJ_KEY_BKOVRLAY
CWBOBJ_KEY_BKOVL_DWN
CWBOBJ_KEY_BKOVL_ACR
CWBOBJ_KEY_CPI
CWBOBJ_KEY_CODEDFNTLIB
CWBOBJ_KEY_CODEPAGE
CWBOBJ_KEY_CODEDFNT
CWBOBJ_KEY_COPIES
CWBOBJ_KEY_DBCSDATA
CWBOBJ_KEY_DBCSEXTENSN
CWBOBJ_KEY_DBCSROTATE
- DBCS 文字の回転
CWBOBJ_KEY_DBCSCPI
- DBCS CPI
CWBOBJ_KEY_DBCSSISO
- DBCS SI/SO 位置決め
CWBOBJ_KEY_DFR_WRITE
- 書き出し据え置き
CWBOBJ_KEY_PAGRTT
- ページの回転角度
CWBOBJ_KEY_ENDPAGE
- 印刷終了ページ
CWBOBJ_KEY_FILESEP
- ファイル区切りの数
CWBOBJ_KEY_FOLDREC
- レコードの折り返し
CWBOBJ_KEY_FONTID
- 使用するフォント識別コード (デフォルト)
CWBOBJ_KEY_FORMFEED
- 使用する用紙送り
CWBOBJ_KEY_FORMTYPE
- 使用する用紙タイプ
CWBOBJ_KEY_FTMGN_ACR
- フロント・マージン (横方向)
CWBOBJ_KEY_FTMGN_DWN
- フロント・マージン (下方向)
CWBOBJ_KEY_FTOVRLLIB
- 前面オーバーレイ・ライブラリー
CWBOBJ_KEY_FTOVRLAY
- 前面オーバーレイ名
CWBOBJ_KEY_FTOVL_ACR
- 前面オーバーレイ・オフセット (横方向)
CWBOBJ_KEY_FTOVL_DWN
- 前面オーバーレイ・オフセット (下方向)
CWBOBJ_KEY_CHAR_ID
- このファイルに対するグラフィック文字セット
CWBOBJ_KEY_JUSTIFY
- ハードウェアの位置合わせ
CWBOBJ_KEY_HOLD
- スプール・ファイルの保留
プログラミング
269
CWBOBJ_KEY_LPI
CWBOBJ_KEY_MAXRCDS
CWBOBJ_KEY_OUTPTY
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_OVERFLOW
CWBOBJ_KEY_LINES_PAGE
CWBOBJ_KEY_PAGELEN
CWBOBJ_KEY_MEASMETHOD
-
1 インチ当たりの行数
許容最大レコード数
出力優先順位
出力待ち行列ライブラリー名
出力待ち行列
オーバーフロー行番号
ページ当たり行数でのページ長
測定単位でのページ長
測定方法 (*ROWCOL または *UOM)
CWBOBJ_KEY_CHAR_LINE
CWBOBJ_KEY_PAGEWIDTH
CWBOBJ_KEY_MULTIUP
CWBOBJ_KEY_POINTSIZE
CWBOBJ_KEY_FIDELITY
CWBOBJ_KEY_DUPLEX
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_PRTTEXT
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_PRTDEVTYPE
CWBOBJ_KEY_PRTRFILELIB
CWBOBJ_KEY_PRTRFILE
CWBOBJ_KEY_RPLUNPRT
CWBOBJ_KEY_RPLCHAR
CWBOBJ_KEY_SAVE
CWBOBJ_KEY_SRCDRWR
CWBOBJ_KEY_SPOOL
CWBOBJ_KEY_SCHEDULE
CWBOBJ_KEY_STARTPAGE
CWBOBJ_KEY_DESCRIPTION
CWBOBJ_KEY_UNITOFMEAS
CWBOBJ_KEY_USERDATA
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJTYP
-
行当たり文字数でのページ幅
測定単位でのページ幅
面当たりの論理ページ数
デフォルトのフォントのポイント・サイズ
印刷精度
両面印刷
印刷品質
各ページの下部に印刷されたテキスト
プリンター名
プリンター・タイプ (データ・ストリーム・タイプ)
プリンター・ファイル・ライブラリー
プリンター・ファイル
印刷不能文字の置き換え
印刷不能文字の置き換え文字
印刷後のスプール・ファイルの保管
用紙入れ
データのスプール
スプール・ファイルのスケジュール
印刷開始ページ
テキスト記述
測定単位
ユーザー・データ
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト
ユーザー定義オブジェクト・タイプ
-
書き出しプログラム・ジョブ名
書き出しプログラム・ジョブ番号
書き出しプログラム・ジョブ状況
書き出しプログラム・ジョブ・ユーザー
v CWBOBJ_LIST_WTR:
CWBOBJ_KEY_WRITER
CWBOBJ_KEY_WTRJOBNUM
CWBOBJ_KEY_WTRJOBSTS
CWBOBJ_KEY_WTRJOBUSER
v CWBOBJ_LIST_LIB:
CWBOBJ_KEY_LIBRARY
- ライブラリー名
CWBOBJ_KEY_DESCRIPTION - ライブラリーの記述
v CWBOBJ_LIST_RSC:
CWBOBJ_KEY_RSCNAME
CWBOBJ_KEY_RSCLIB
CWBOBJ_KEY_RSCTYPE
CWBOBJ_KEY_OBJEXTATTR
CWBOBJ_KEY_DESCRIPTION
CWBOBJ_KEY_DATE
CWBOBJ_KEY_TIME
-
資源名
資源ライブラリー
資源オブジェクト・タイプ
オブジェクトの拡張属性
資源の記述
オブジェクトの最終変更日付
オブジェクトの最終変更時刻
cwbOBJ_GetObjAttrs:
cwbOBJ_GetObjAttrs API は、この製品と共に使用します。
目的
オブジェクトのいくつかの属性を取得します。
270
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbOBJ_GetObjAttrs(
cwbOBJ_ObjHandle
objectHandle,
unsigned long
numAttrs,
cwbOBJ_GetObjAttrParms *getAttrParms,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
属性を取得するオブジェクトのハンドル。
unsigned long numAttrs - input
検索する属性の数。
cwbOBJ_GetObjAttrParms *getAttrParms - input
検索する属性ごとに、属性キー (id)、その属性の値を保管するバッファー、およびそのバッファーのサ
イズを与える、numAttrs の要素からなる配列。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_KEY
キーが有効ではありません。
CWB_API_ERROR
一般 API 障害。
使用法
各種オブジェクト・タイプに対して有効な属性を調べるには、cwbOBJ_GetObjAttr の使用上の注意を参照し
てください。
プログラミング
271
cwbOBJ_GetObjHandle:
cwbOBJ_GetObjHandle API は、この製品と共に使用します。
目的
リスト・オブジェクトを取得します。この呼び出しは、オープンされたリスト中のオブジェクトのハンドル
を取得します。資源を解放するために呼び出し側が cwbOBJ_DeleteObjHandle を使用したときは、戻された
ハンドルもこれによって解放されなければなりません。戻されたハンドルは、リストがオープンされている
間だけ有効です。
構文
unsigned int CWB_ENTRY
cwbOBJ_GetObjHandle(
cwbOBJ_ListHandle listHandle,
unsigned long
ulPosition,
cwbOBJ_ObjHandle *objectHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ListHandle listHandle - input
オブジェクト・ハンドルを取得するその元のリストのハンドル。このリストはオープンされていなけれ
ばなりません。
unsigned long ulPosition - input
ハンドルを取得するオブジェクトのリスト内の位置。0 が基準になります。0 から「リストのオブジェ
クト数 - 1」までが有効な値です。cwbOBJ_GetListSize() を使用して、リストのサイズを取得すること
ができます。
cwbOBJ_ObjHandle *objectHandle - output
出力の際に、オブジェクトのハンドルが入ります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたリスト・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_LIST_NOT_OPEN
リストがオープンされていません。
272
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBOBJ_RC_INVALID_INDEX
ulPosition が範囲外です。
使用法
なし (None)
cwbOBJ_GetObjHandleFromID:
cwbOBJ_GetObjHandleFromID API は、この製品と共に使用します。
目的
オブジェクト・ハンドルを、その 2 進数 ID およびタイプから再生成します。このオブジェクト・ハンド
ルの使用を終了したときは、資源を解放するため cwbOBJ_DeleteObjHandle() を呼び出す必要があります。
構文
unsigned int CWB_ENTRY
cwbOBJ_GetObjHandleFromID(
void
*idBuffer,
unsigned long
bufLen,
cwbOBJ_ObjType
objectType,
cwbOBJ_ObjHandle *objectHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
void *idBuffer - input
このオブジェクトの ID を保持するバッファー。
unsigned long bufLen - input
*IDBuffer が指すデータの長さ。
cwbOBJ_ObjType type - input
この ID 用のオブジェクトのタイプ。これは、この ID を提供したオブジェクトのタイプと一致する必
要があります。
cwbOBJ_ObjHandle *objectHandle - output
この呼び出しが正常に戻った場合は、これがオブジェクトのハンドルとなります。このオブジェクト・
ハンドルの使用を終了したときは、cwbOBJ_DeleteObjHandle() API を使用してこのハンドルを解放し
てください。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
プログラミング
273
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_INVALID_TYPE
objectType が正しくありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
なし (None)
cwbOBJ_GetObjID:
cwbOBJ_GetObjID API は、この製品と共に使用します。
目的
オブジェクトの ID を取得します。これは、サーバー上でオブジェクトを固有に識別するデータです。取
得されるデータは読み取り不能の 2 進数です。このデータは、ハンドルをそのオブジェクトに取り戻すた
めに、cwbOBJ_GetObjHandleFromID() API で返すことができます。
構文
unsigned int CWB_ENTRY
cwbOBJ_GetObjID(
cwbOBJ_ObjHandle objectHandle,
void
*idBuffer,
unsigned long
bufLen,
unsigned long
*bytesNeeded,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
ID の取得元のオブジェクトのハンドル。
void *idBuffer - output
このオブジェクトの ID を保持するバッファー。
unsigned long bufLen - input
*IDBuffer が指すバッファーの長さ。
unsigned long *bytesNeeded - output
出力の際には、ID を保持するために必要なバイト数が入ります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
274
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
使用法
なし (None)
cwbOBJ_RefreshObj:
cwbOBJ_RefreshObj API は、この製品と共に使用します。
目的
最新の IBM i 情報でオブジェクトをリフレッシュします。これにより、オブジェクトの戻された属性を最
新のものにします。
構文
unsigned int CWB_ENTRY cwbOBJ_RefreshObj(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
objectHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
リフレッシュされるオブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
プログラミング
275
使用法
以下のオブジェクト・タイプをリフレッシュすることができます。
v CWBOBJ_LIST_SPLF (スプール・ファイル)
v CWBOBJ_LIST_PRTF (プリンター・ファイル)
v CWBOBJ_LIST_OUTQ (出力待ち行列)
v CWBOBJ_LIST_PRTD (プリンター)
v CWBOBJ_LIST_WTR (書き出しプログラム)
例: リストの中に少なくとも 1 つの項目があるスプール・ファイル・リストを listHandle が指すものと想
定します。
cwbOBJ_ObjHandle splFileHandle;
ulRC = cwbOBJ_GetObjHandle(listHandle,
0,
&splFileHandle,
NULL);
if (ulRC == CWB_OK)
{
ulRC = cwbOBJ_RefreshObj(splFileHandle);
.....
get attributes for object
.....
ulRC = cwbOBJ_DeleteObjHandle(splFileHandle);
}
cwbOBJ_SetObjAttrs:
cwbOBJ_SetObjAttrs API は、この製品と共に使用します。
目的
サーバー上のオブジェクトの属性を変更します。
構文
unsigned int CWB_ENTRY cwbOBJ_SetObjAttrs(
cwbOBJ_ObjHandle
cwbOBJ_ParmHandle
cwbSV_ErrHandle
objectHandle,
parmListHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle objectHandle - input
変更されるオブジェクトへのハンドル。
cwbOBJ_ParmHandle parmListHandle - input
そのオブジェクト用に変更される属性が入っている、パラメーター・オブジェクトへのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
276
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
以下のオブジェクトによって、これらの属性を変更できるようになります。
v CWBOBJ_LIST_SPLF (スプール・ファイル):
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_BKOVRLLIB
CWBOBJ_KEY_BKOVRLAY
CWBOBJ_KEY_BKOVL_ACR
CWBOBJ_KEY_BKOVL_DWN
CWBOBJ_KEY_COPIES
CWBOBJ_KEY_ENDPAGE
CWBOBJ_KEY_FILESEP
CWBOBJ_KEY_FORMFEED
CWBOBJ_KEY_FORMTYPE
CWBOBJ_KEY_FTOVRLLIB
CWBOBJ_KEY_FTOVRLAY
CWBOBJ_KEY_FTOVL_ACR
CWBOBJ_KEY_FTOVL_DWN
CWBOBJ_KEY_OUTPTY
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_MULTIUP
CWBOBJ_KEY_FIDELITY
CWBOBJ_KEY_DUPLEX
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_PRTSEQUENCE
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_RESTART
CWBOBJ_KEY_SAVESPLF
CWBOBJ_KEY_SCHEDULE
CWBOBJ_KEY_STARTPAGE
CWBOBJ_KEY_USERDATA
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJTYP
v
-
ページの位置合わせ
背面オーバーレイ・ライブラリー名
背面オーバーレイ
背面オーバーレイ・オフセット (横方向)
背面オーバーレイ・オフセット (下方向)
コピー枚数
終了ページ
ファイル区切り
用紙送り
用紙タイプ
前面オーバーレイ・ライブラリー名
前面オーバーレイ
前面オーバーレイ・オフセット (横方向)
前面オーバーレイ・オフセット (下方向)
出力優先順位
出力待ち行列ライブラリー名
出力待ち行列
片面当たりの論理ページ数
印刷精度
両面印刷
印刷品質
P 印刷順序
プリンター
印刷再始動位置
印刷後のスプール・ファイルの保管
スプール・ファイルのスケジュール
開始ページ
ユーザー・データ
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト
ユーザー定義オブジェクト・タイプ
CWBOBJ_LIST_PRTF (プリンター・ファイル):
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_BKMGN_ACR
CWBOBJ_KEY_BKMGN_DWN
CWBOBJ_KEY_BKOVRLLIB
CWBOBJ_KEY_BKOVRLAY
CWBOBJ_KEY_BKOVL_ACR
CWBOBJ_KEY_BKOVL_DWN
CWBOBJ_KEY_CPI
-
ページの位置合わせ
バック・マージン・オフセット (横方向)
バック・マージン・オフセット (下方向)
背面オーバーレイ・ライブラリー名
背面オーバーレイ
背面オーバーレイ・オフセット (横方向)
背面オーバーレイ・オフセット (下方向)
1 インチ当たりの文字数
プログラミング
277
CWBOBJ_KEY_CODEPAGE
CWBOBJ_KEY_CODEDFNTLIB
CWBOBJ_KEY_CODEDFNT
CWBOBJ_KEY_COPIES
CWBOBJ_KEY_DBCSDATA
CWBOBJ_KEY_DBCSEXTENSN
CWBOBJ_KEY_DBCSROTATE
CWBOBJ_KEY_DBCSCPI
CWBOBJ_KEY_DBCSSISO
CWBOBJ_KEY_DFR_WRITE
CWBOBJ_KEY_ENDPAGE
CWBOBJ_KEY_FILESEP
-
コード・ページ
コード化フォント・ライブラリー名
コード化フォント名
コピー枚数
DBCS データを含む
DBCS 拡張文字の処理
DBCS 文字回転
DBCS CPI
DBCS SO/SI のスペース
書き出し据え置き
終了ページ
ファイル区切り (*FILE は使用不可)
CWBOBJ_KEY_FOLDREC
CWBOBJ_KEY_FONTID
CWBOBJ_KEY_FORMFEED
CWBOBJ_KEY_FORMTYPE
CWBOBJ_KEY_FTMGN_ACR
CWBOBJ_KEY_FTMGN_DWN
CWBOBJ_KEY_FTOVRLLIB
CWBOBJ_KEY_FTOVRLAY
CWBOBJ_KEY_FTOVL_ACR
CWBOBJ_KEY_FTOVL_DWN
CWBOBJ_KEY_CHAR_ID
CWBOBJ_KEY_JUSTIFY
CWBOBJ_KEY_HOLD
CWBOBJ_KEY_LPI
CWBOBJ_KEY_MAXRECORDS
CWBOBJ_KEY_OUTPTY
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_OVERFLOW
CWBOBJ_KEY_PAGELEN
CWBOBJ_KEY_MEASMETHOD
CWBOBJ_KEY_PAGEWIDTH
CWBOBJ_KEY_MULTIUP
CWBOBJ_KEY_POINTSIZE
CWBOBJ_KEY_FIDELITY
CWBOBJ_KEY_DUPLEX
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_PRTTEXT
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_PRTDEVTYPE
CWBOBJ_KEY_RPLUNPRT
CWBOBJ_KEY_RPLCHAR
CWBOBJ_KEY_SAVESPLF
CWBOBJ_KEY_SRCDRWR
CWBOBJ_KEY_SPOOL
CWBOBJ_KEY_SCHEDULE
CWBOBJ_KEY_STARTPAGE
CWBOBJ_KEY_DESCRIPTION
CWBOBJ_KEY_UNITOFMEAS
CWBOBJ_KEY_USERDATA
CWBOBJ_KEY_USRDFNDTA
CWBOBJ_KEY_USRDFNOPTS
CWBOBJ_KEY_USRDFNOBJLIB
CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJTYP
-
レコードの折り返し
フォント識別コード
用紙送り
用紙タイプ
フロント・マージン・オフセット (横方向)
フロント・マージン・オフセット (下方向)
前面オーバーレイ・ライブラリー名
前面オーバーレイ
前面オーバーレイ・オフセット (横方向)
前面オーバーレイ・オフセット (下方向)
グラフィック文字セット ID
ハードウェアの位置合わせ
スプール・ファイルの保留
1 インチ当たりの行数
スプール出力レコードの最大数
出力優先順位
出力待ち行列ライブラリー名
出力待ち行列
オーバーフロー行番号
ページ長
測定方法
ページ幅
片面当たりの論理ページ数
デフォルトのフォントのポイント・サイズ
印刷精度
両面印刷
印刷品質
印刷テキスト
プリンター
プリンター・タイプ
印刷不能文字の置き換え
置き換え文字
印刷後のスプール・ファイルの保管
用紙入れ
データのスプール
スプール・ファイルのスケジュール
開始ページ
テキスト記述
測定単位
ユーザー・データ
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト
ユーザー定義オブジェクト・タイプ
v CWBOBJ_LIST_OUTQ (出力待ち行列):
v CWBOBJ_LIST_PRTD (プリンター):
v CWBOBJ_LIST_WTR (書き出しプログラム):
v CWBOBJ_LIST_LIB (ライブラリー):
– なし
278
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター・オブジェクト API
以下の API は、パラメーター・オブジェクトに関するものです。 API はアルファベット順にリストされ
ます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CopyParmObjHandle:
cwbOBJ_CopyParmObjHandle API は、この製品と共に使用します。
目的
重複パラメーター・リスト・オブジェクトを作成します。パラメーター・リスト・オブジェクト中のすべて
の属性キーと属性値は、新しいパラメーター・リスト・オブジェクトにコピーされます。
構文
unsigned int CWB_ENTRY
cwbOBJ_CopyParmObjHandle(
cwbOBJ_ParmHandle
parmListHandle,
cwbOBJ_ParmHandle *newParmListHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ParmHandle parmListHandle - input
コピーするパラメーター・リスト・オブジェクトのハンドル
cwbOBJ_ParmHandle *newParmListHandle - output
この呼び出しが正常に完了すると、このハンドルには新規のパラメーター・リスト・オブジェクト・ハ
ンドルが入ります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
使用法
この呼び出しで割り振られた資源を解放するため、cwbOBJ_DeleteParmObjectHandle API を呼び出す必要が
あります。
プログラミング
279
cwbOBJ_CreateParmObjHandle:
cwbOBJ_CreateParmObjHandle API は、この製品と共に使用します。
目的
パラメーター・リスト・オブジェクト・ハンドルを割り振ります。パラメーター・リスト・オブジェクト
は、他の API 上で渡すことのできるパラメーターのリストを保持するために使用できます。
構文
unsigned int CWB_ENTRY
cwbOBJ_CreateParmObjHandle(
cwbOBJ_ParmHandle *parmListHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ParmHandle *parmListHandle - output
パラメーター・オブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
使用法
この呼び出しで割り振られた資源を解放するため、cwbOBJ_DeleteParmObjectHandle API を呼び出す必要が
あります。
cwbOBJ_DeleteParmObjHandle:
目的
パラメーター・リスト・オブジェクト・ハンドルを割り振り解除し、このハンドルによって使用された資源
を解放します。
構文
unsigned int CWB_ENTRY
280
cwbOBJ_DeleteParmObjHandle(
cwbOBJ_ParmHandle parmListHandle,
cwbSV_ErrHandle
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbOBJ_ParmHandle parmListHandle - input
パラメーター・オブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、パラメーター・オブジェクト・ハンドルではありません。
使用法
この呼び出しが正常に戻った後は、parmListHandle は有効ではなくなります。
cwbOBJ_GetParameter:
cwbOBJ_GetParameter API は、この製品と共に使用します。
目的
パラメーター・リスト・オブジェクトのパラメーターの値を取得します。
構文
unsigned int CWB_ENTRY cwbOBJ_GetParameter(
cwbOBJ_ParmHandle parmListHandle,
cwbOBJ_KeyID
key,
void
*buffer,
unsigned long
bufLen,
unsigned long
*bytesNeeded,
cwbOBJ_DataType *keyType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ParmHandle parmListHandle - input
パラメーター・オブジェクトのハンドル。
cwbOBJ_KeyID key - input
設定するパラメーターの ID。
プログラミング
281
void *buffer - output
属性値を保持するバッファー (この呼び出しが正常に戻った場合)。*Buffer に置かれるデータ・タイプ
は何かをキー値が決定します。タイプが与えられた場合、このタイプも *keyType パラメーターへ戻さ
れます。
unsigned long bufLen - input
バッファーが指すバッファーの長さ。
unsigned long *bytesNeeded - output
出力の際には、結果を保持するために必要なバイト数が入ります。
cwbOBJ_DataType *keyType - output
オプションであり、NULL でも構いません。出力の際には、この属性と、*buffer に何が保管されるか
を表すために使用されるデータ・タイプが含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
CWBOBJ_RC_KEY_NOT_FOUND
キーがパラメーター・リストに指定されていません。
CWB_API_ERROR
一般 API 障害。
使用法
なし (None)
cwbOBJ_SetParameter:
cwbOBJ_SetParameter API は、この製品と共に使用します。
目的
パラメーターの値をパラメーター・リスト・オブジェクトに設定します。
282
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY
cwbOBJ_SetParameter(
cwbOBJ_ParmHandle parmListHandle,
cwbOBJ_KeyID
key,
const void
*value,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ParmHandle parmListHandle - input
パラメーター・オブジェクトのハンドル。
cwbOBJ_KeyID key - input
設定するパラメーターの ID。
void *value - input
パラメーターに設定するその値。値が指すタイプは、キーの値によって決まります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、パラメーター・オブジェクト・ハンドルではありません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
なし (None)
書き出しプログラム・ジョブ API
以下の API は、書き出しプログラム・ジョブに関するものです。 API はアルファベット順にリストされ
ます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
プログラミング
283
cwbOBJ_EndWriter:
cwbOBJ_EndWriter API は、この製品と共に使用します。
目的
IBM i 書き出しプログラム・ジョブを終了します。
構文
unsigned int CWB_ENTRY
cwbOBJ_EndWriter(
cwbOBJ_ObjHandle
writerHandle,
cwbOBJ_ParmHandle *parmListHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle writerHandle - input
停止される書き出しプログラム・ジョブのハンドル。このハンドルは、書き出しプログラムをリストし
てそのリストから書き出しプログラム・ハンドルを取得するか、あるいは書き出しプログラムを開始し
て、書き出しプログラム・ハンドルが戻されるよう要求するかのいずれかによって獲得することができ
ます。
cwbOBJ_ParmHandle *parmListHandle - input
オプションです。書き出しプログラムを終了させるためのパラメーターが入っている、有効なパラメー
ター・リスト・オブジェクト・ハンドルを指すポインター。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
この呼び出しが正常に戻った後、writerHandle を解放するため cwbOBJ_DeleteObjHandle() を呼び出してく
ださい。以下のパラメーター・キーを pParmListHandl オブジェクトに設定することができます。
v CWBOBJ_KEY_WTREND - 書き出しプログラムが終了する時間以下の特殊値のうちの 1 つ。
284
IBM i: Windows アプリケーション・パッケージ: プログラミング
– *CNTRLD - 現行ファイルの印刷後書き出しプログラムを終了させる
– *IMMED - 書き出しプログラムを即刻終了させる
– *PAGEEND - 現行ページの終わりで書き出しプログラムを終了させる
cwbOBJ_StartWriter:
cwbOBJ_StartWriter API は、この製品と共に使用します。
目的
IBM i 書き出しプログラム・ジョブを開始します。
構文
unsigned int CWB_ENTRY
cwbOBJ_StartWriter(
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbOBJ_ParmHandle
cwbOBJ_ObjHandle
cwbSV_ErrHandle
*printerHandle,
*outputQueueHandle,
*parmListHandle,
*writerHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle *printerHandle - input
必須です。どのプリンターに対してこの書き出しプログラムを開始させるかを識別する有効なプリンタ
ー・オブジェクト・ハンドルを指すポインター。
cwbOBJ_ObjHandle *outputQueueHandle - input
オプションです。どの出力待ち行列からこの書き出しプログラムを開始させるかを識別する有効な出力
待ち行列オブジェクト・ハンドルを指すポインター。parmListHandle もまた指定され、
CWBOBJ_KEY_OUTQUE パラメーター・キーが入っている場合は、当パラメーターは無視されます。
cwbOBJ_ParmHandle *parmListHandle - input
オプションです。書き出しプログラムを開始させるためのパラメーターが入っている有効なパラメータ
ー・リスト・オブジェクト・ハンドルを指すポインター。
cwbOBJ_ObjHandle *writerHandle - output
オプションです。この API から正常に戻ったときに埋められる書き出しプログラム・オブジェクト・
ハンドルを指すポインター。このパラメーターが指定された場合は、この書き出しプログラム・ハンド
ル用に割り振られた資源を解放するために、呼び出し側は cwbOBJ_DeleteObjHandle() を呼び出さなけ
ればなりません。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは cwbSV_CreateErrHandle() API で作成されます。メッセージは
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
285
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
この API を呼び出すと、実行される書き出しプログラム・ジョブが投入されますが、この API が正常に
戻っても書き出しプログラム・ジョブは開始できない場合があります (ジョブの投入は完了しましたが、ジ
ョブを開始できません)。これは IBM i STRPRTWTR コマンドの動作です。次のパラメーター・キーを
parmListHandle オブジェクト内に設定することができます。
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_ALWDRTPRT
CWBOBJ_KEY_AUTOEND
CWBOBJ_KEY_DRWRSEP
CWBOBJ_KEY_FILESEP
CWBOBJ_KEY_FORMTYPE
CWBOBJ_KEY_JOBNAME
CWBOBJ_KEY_JOBNUMBER
CWBOBJ_KEY_USER
CWBOBJ_KEY_FORMTYPEMSG
CWBOBJ_KEY_MSGQUELIB
CWBOBJ_KEY_MSGQUE
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_SPOOLFILE
CWBOBJ_KEY_SPLFNUM
CWBOBJ_KEY_WTRSTRPAGE
CWBOBJ_KEY_WTREND
CWBOBJ_KEY_WRITER
CWBOBJ_KEY_WTRINIT
-
ページの位置合わせ
直接印刷可能
書き出しプログラムの自動終了
区切り用紙入れ
ファイル区切りの数
使用する用紙タイプ
ファイルを作成したジョブの名前
ファイルを作成したジョブの番号
ファイルを作成したユーザーの名前
用紙タイプ・メッセージ・オプション
メッセージ待ち行列ライブラリー
メッセージ待ち行列
出力待ち行列ライブラリー名
出力待ち行列
スプール・ファイル名
スプール・ファイル番号
書き出しプログラムの開始ページ
書き出しプログラムが終了する時間
書き出しプログラム・ジョブ名
プリンターの初期設定
出力待ち行列 API
以下の API は、出力待ち行列に関するものです。 API はアルファベット順にリストされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_HoldOutputQueue:
cwbOBJ_HoldOutputQueue API は、この製品と共に使用します。
目的
IBM i 出力待ち行列を保留にします。
構文
unsigned int CWB_ENTRY
286
cwbOBJ_HoldOutputQueue(
cwbOBJ_ObjHandle queueHandle,
cwbSV_ErrHandle
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbOBJ_ObjHandle queueHandle - input
保留される出力待ち行列のハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効な待ち行列ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
なし (None)
cwbOBJ_PurgeOutputQueue:
cwbOBJ_PurgeOutputQueue API は、この製品と共に使用します。
目的
IBM i 出力待ち行列にあるスプール・ファイルを除去します。
構文
unsigned int CWB_ENTRY
cwbOBJ_PurgeOutputQueue(
cwbOBJ_ObjHandle
queueHandle,
cwbOBJ_ParmHandle *parmListHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle queueHandle - input
除去される出力待ち行列のハンドル。
cwbOBJ_ParmHandle * parmListHandle - input
オプションです。出力待ち行列を除去するためのパラメーターが入っている、有効なパラメーター・リ
スト・オブジェクト・ハンドルを指すポインター。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
プログラミング
287
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
parmListHandle に指定されたパラメーターが与えられると、そのパラメーターはどのスプール・ファイルが
除去されるかを指定します。parmListHandle が NULL の場合、現行ユーザーのスプール・ファイルはすべ
て除去されます。以下のパラメーター・キーを parmListHandle オブジェクトに設定できます。
v CWBOBJ_KEY_USER
どのユーザーのスプール・ファイルを除去するかを指定します。特定のユーザー ID、"*ALL" または
"*CURRENT"。"*CURRENT" がデフォルト。
v CWBOBJ_KEY_FORMTYPE
指定されている用紙タイプに基づいて、どのスプール・ファイルを除去するかを指定します。特定の用
紙タイプ、"*ALL" または "*STD"。"*ALL" がデフォルト。
v CWBOBJ_KEY_USERDATA
指定されているユーザー・データに基づいて、どのスプール・ファイルを除去するかを指定します。特
定の値、または "*ALL"。"*ALL" がデフォルト。
cwbOBJ_ReleaseOutputQueue:
cwbOBJ_ReleaseOutputQueue API は、この製品と共に使用します。
目的
IBM i 出力待ち行列を解放します。
構文
unsigned int CWB_ENTRY
288
cwbOBJ_ReleaseOutputQueue(
cwbOBJ_ObjHandle queueHandle,
cwbSV_ErrHandle
errorHandle);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbOBJ_ObjHandle queueHandle - input
解放される出力待ち行列のハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効な待ち行列ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
なし (None)
AFP 資源 API
AFP 資源 API は、この製品と共に使用します。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CloseResource:
cwbOBJ_CloseResource API は、この製品と共に使用します。
目的
読み取りのために以前オープンした AFP 資源オブジェクトをクローズします。
構文
unsigned int CWB_ENTRY
cwbOBJ_CloseResource(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
resourceHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle resourceHandle - input
クローズされる資源のハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
プログラミング
289
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが有効な資源ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_RSCNOTOPEN
資源がオープンされていません。
CWBOBJ_RC_SPLFNOTOPEN
スプール・ファイルがオープンされていません。
使用法
資源に対するハンドルが cwbOBJ_OpenResourceForSplF() API への呼び出しを経由して取得された場合、こ
の API は、ユーザーに対するハンドルを削除します (ユーザーが資源をオープンしたとき、そのユーザー
に対してハンドルが動的に割り振られ、この呼び出しはそのハンドルを割り振り解除します)。
cwbOBJ_CreateResourceHandle:
cwbOBJ_CreateResourceHandle API は、この製品と共に使用します。
目的
指定されたシステム上の特定の AFP 資源の資源ハンドルを作成します。
構文
unsigned int CWB_ENTRY
cwbOBJ_CreateResourceHandle(
const char
const char
const char
cwbOBJ_AFPResourceType
cwbOBJ_ObjHandle
cwbSV_ErrHandle
*systemName,
*resourceName,
*resourceLibrary,
resourceType,
*objectHandle,
errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
const char *resourceName - input
AFP 資源名を指すポインター。
290
IBM i: Windows アプリケーション・パッケージ: プログラミング
const char *resourceLibrary - input
資源が入っている IBM i ライブラリーの名前を指すポインター。
cwbOBJ_AFPResourceType resourceType - input
どのタイプの資源であるかを指定します。下記のうちのいずれかでなければなりません。
v CWBOBJ_AFPRSC_FONT
v CWBOBJ_AFPRSC_FORMDEF
v CWBOBJ_AFPRSC_OVERLAY
v CWBOBJ_AFPRSC_PAGESEG
v CWBOBJ_AFPRSC_PAGEDEF
cwbOBJ_ObjHandle *objectHandle - output
出力の際は、資源ハンドルがこれに含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべて、このオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
名前ライブラリーと資源のタイプを知っている場合は、資源へのハンドルを取得するために、この API を
使用してください。そのいずれも分からない場合、または、リストから選択したい場合は、代わりにリスト
API を使用して AFP 資源をリストしてください。この API は、ホスト上の AFP 資源を検査しません。
このハンドルが最初に資源についてのデータの検索に使用されるときに、資源ファイルが存在しないとホス
ト・エラーが起こります。
cwbOBJ_DisplayResource:
cwbOBJ_DisplayResource API は、この製品と共に使用します。
プログラミング
291
目的
指定された AFP 資源をユーザーに表示します。
構文
unsigned int CWB_ENTRY
cwbOBJ_DisplayResource(
cwbOBJ_ObjHandle
resourceHandle,
const char
*view,
const unsigned long flags,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle resourceHandle - input
AFP 資源オブジェクトのハンドル。このハンドルは、オーバーレイまたはページ・セグメントの資源
のタイプである必要があります。
const char *view - input
オプションであり、NULL でも構いません。指定された場合、AFP ビューアーを呼び出す際に使用す
るビューを指定する、ASCIIZ ストリングを指すポインターです。ビューアーとともに出荷される 2
つの事前定義されたビューがあります。それらは、LETTER (8.5" x 11") と SFLVIEW (132 桁) で
す。ユーザー自身のビューを追加することもできます。
const unsigned long flags - input
以下のビットのいずれかが設定されることがあります。CWBOBJ_DSPSPLF_WAIT は、この呼び出し
に対して、戻る前に、ビューアーのプロセスが資源を正常にオープンするまで待機するように伝えま
す。このビットが 0 の場合、この API は、ビューアーのプロセスを開始した後で戻ります。このビッ
トが 1 の場合、この API は、戻る前に、ビューアーが資源をオープンするまで待機します。他のすべ
てのビットは、0 に設定される必要があります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべて、このオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_NO_VIEWER
Client Access/400 のビューアー・サポートがインストールされていません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
292
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_API_ERROR
一般 API 障害。
CWBOBJ_RC_INVALID_TYPE
resourceHandle 用に与えられたハンドルは、オーバーレイまたはページ・セグメントの資源へのハ
ンドルではありません。
使用法
この API は、指定された AFP 資源で AFP ビューアーを呼び出すために使用してください。資源のタイ
プは、オーバーレイかページ・セグメントを指定する必要があります。戻りコード CWB_NO_VIEWER
は、ビューアー構成要素がワークステーションにインストールされていなかったことを意味します。
cwbOBJ_OpenResource:
cwbOBJ_OpenResource API は、この製品と共に使用します。
目的
読み取りのために AFP 資源オブジェクトをオープンします。
構文
unsigned int CWB_ENTRY
cwbOBJ_OpenResource(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
resourceHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle resourceHandle - input
読み取りのためオープンされる AFP 資源ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが有効な資源ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_NOHOSTSUPPORT
ホストは、資源を対象とする作業をサポートしません。
プログラミング
293
使用法
資源は、そこからの読み取りが終了した時点で、cwbOBJ_CloseResource() API を使用してクローズする必
要があります。
cwbOBJ_OpenResourceForSplF:
cwbOBJ_OpenResourceForSplF API は、この製品と共に使用します。
目的
読み取り用に既にオープンされたスプール・ファイルのために、読み取り用に AFP 資源オブジェクトをオ
ープンします。AFP スプール・ファイルを読み取り中に読み取る必要のある外部 AFP 資源に接触した場
合、この API は役立ちます。この API を使用すれば、最初に資源をリストすることなしに、その資源を
読み取りのためにオープンすることができます。
構文
unsigned int CWB_ENTRY
cwbOBJ_OpenResourceForSplF(
cwbOBJ_ObjHandle
splFHandle,
const char
*resourceName,
const char
*resourceLibrary,
unsigned long
resourceType,
const char
*reserved,
cwbOBJ_ObjHandle
*resourceHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
読み取り用に既にオープンされており、そのための資源がオープンされるスプール・ファイルのハンド
ル。資源およびスプール・ファイルを読み取るために、同じシステム会話 (およびネットワーク印刷サ
ーバー・プログラムの同じシステム・インスタンス) が使用されます。
const char *resourceName - input
ASCIIZ ストリングの AFP 資源名を指すポインター。
const char *resourceLibrary - input
オプションであり、NULL でも構いません。ASCIIZ ストリング内にある、AFP 資源の IBM i ライブ
ラリーを指すポインター。ライブラリーが指定されていない場合は、資源を検索するためにスプール・
ファイルのライブラリー・リストが使用されます。
unsigned long resourceType - input
以下のいずれかのビットがオンである無符号長精度整数。
v CWBOBJ_AFPRSC_FONT
v CWBOBJ_AFPRSC_FORMDEF
v CWBOBJ_AFPRSC_OVERLAY
v CWBOBJ_AFPRSC_PAGESEG
v CWBOBJ_AFPRSC_PAGEDEF
オープンする資源のタイプを指定します。
const char *reserved 予約されています。NULL である必要があります。
294
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbOBJ_OBJHandle *resourceHandle - output
資源の読み取り、シーク、および最後にクローズをするために使用できる、動的に割り振られた資源ハ
ンドルが入る、正常に戻ってきた場合の OBJHandle を指すポインター。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_FILE_NOT_FOUND
資源が見付かりませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_INVALID_HANDLE
ハンドルが有効な資源ハンドルではありません。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_SPLFNOTOPEN
スプール・ファイルがオープンされていません。
CWBOBJ_RC_NOHOSTSUPPORT
ホストは、資源を対象とする作業をサポートしません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
この呼び出しは、正常終了した場合は、一時的資源ハンドルを生成し、それを resourceHandle パラメータ
ーに戻します。呼び出し側がこのハンドルを指定して cwbOBJ_CloseResource() API を呼び出した場合、こ
のハンドルは自動的に削除されます。
資源は、そこからの読み取りが終了した時点で、cwbOBJ_CloseResource() API を使用してクローズする必
要があります。
cwbOBJ_ReadResource:
cwbOBJ_ReadResource API は、この製品と共に使用します。
プログラミング
295
目的
現行の読み取り位置からバイトを読み取ります。
構文
unsigned int CWB_ENTRY
cwbOBJ_ReadResource(
cwbOBJ_ObjHandle resourceHandle,
char
*bBuffer,
unsigned long
bytesToRead,
unsigned long
*bytesRead,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle resourceHandle - input
読み取られる AFP 資源オブジェクトのハンドル。
char *buffer - input
資源から読み取られるバイトを保持するバッファーを指すポインター。
unsigned long bytesToRead - input
読み取るバイトの最大数。読み取られる数はこれより少なくなります。
unsigned long *bytesRead - output
実際に読み取られたバイト数。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_RSCNOTOPEN
資源ファイルがまだオープンされていません。
CWBOBJ_RC_ENDOFFILE
ファイルの終わりが読み取られました。
使用法
この API を呼び出す前に、この資源ハンドルを使用して cwbOBJ_OpenResource() API を呼び出すか、ま
たは、cwbOBJ_OpenResourceForSplF() API への呼び出しを使用してハンドルを検索する必要があります。
296
IBM i: Windows アプリケーション・パッケージ: プログラミング
読み取り時にファイルの終わりに到達した場合、その戻りコードは CWBOBJ_RC_ENDOFFILE で、
bytesRead には読み取られた実際のバイト数が入ります。
cwbOBJ_SeekResource:
cwbOBJ_SeekResource API は、この製品と共に使用します。
目的
読み取りのためにオープンされている資源上の現行の読み取り位置を移動させます。
構文
unsigned int CWB_ENTRY
cwbOBJ_SeekResource(
cwbOBJ_ObjHandle
cwbOBJ_SeekOrigin
signed long
cwbSV_ErrHandle
resourceHandle,
seekOrigin,
seekOffset,
errorHandle);
パラメーター
cwbOBJ_ObjHandle resourceHandle - input
シークされる AFP 資源オブジェクトのハンドル。
cwbOBJ_SeekOrigin seekOrigin - input
シークの際の開始位置。有効な値は以下のとおりです。
v CWBOBJ_SEEK_BEGINNING - ファイルの始めからシーク
v
CWBOBJ_SEEK_CURRENT - 現行の読み取り位置からシーク
v CWBOBJ_SEEK_ENDING - ファイルの終わりからシーク
signed long seekOffset - input
現行の読み取りポインターを移動させるための、バイト表示によるシーク起点からのオフセット (負ま
たは正)。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
プログラミング
297
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_RSCNOTOPEN
資源がまだオープンされていません。
CWBOBJ_RC_SEEKOUTOFRANGE
シーク・オフセットが範囲外にあります。
使用法
この API を呼び出す前に、この資源ハンドルを使用して cwbOBJ_OpenResource() API を呼び出すか、ま
たは、cwbOBJ_OpenResourceForSplF() API への呼び出しを使用してハンドルを検索する必要があります。
新規スプール・ファイル用 API
以下の API は、新規スプール・ファイルの処理に関するものです。API はアルファベット順にリストされ
ます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CloseNewSplF:
cwbOBJ_CloseNewSplF API は、この製品と共に使用します。
目的
新しく作成されたスプール・ファイルをクローズします。
構文
unsigned int CWB_ENTRY cwbOBJ_CloseNewSplF(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
newSplFHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle newSplFHandle - input
新しいスプール・ファイルのハンドル。これは cwbOBJ_CreateNewSplF() API で返されるハンドルで
す。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
298
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
スプール・ファイルがクローズされると、それ以降スプール・ファイルに書き込むことはできません。
cwbOBJ_CloseNewSplFAndGetHandle:
cwbOBJ_CloseNewSplFAndGetHandle API は、この製品と共に使用します。
目的
新しく作成されたスプール・ファイルをクローズし、そのハンドルを戻します。
構文
unsigned int CWB_ENTRY cwbOBJ_CloseNewSplFAndGetHandle(
cwbOBJ_ObjHandle
newSplFHandle,
cwbOBJ_ObjHandle
*splFHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle newSplFHandle - input
新しいスプール・ファイルのハンドル。これは cwbOBJ_CreateNewSplF() API で返されるハンドルで
す。
cwbOBJ_ObjHandle *splFHandle - output
この呼び出しが正常に完了したときに、スプール・ファイル・ハンドルを保持するオブジェクト・ハン
ドルを指すポインター。このハンドルは、スプール・ファイル・ハンドルを入力として用いる他の API
で使用することができます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
プログラミング
299
使用法
splFHandle に戻されたハンドルは、資源を解放するために、cwbOBJ_DeleteObjHandle() API を使用して解
放してください。
cwbOBJ_CreateNewSplF:
cwbOBJ_CreateNewSplF API は、この製品と共に使用します。
目的
新規の IBM i スプール・ファイルを作成します。
構文
unsigned int CWB_ENTRY cwbOBJ_CreateNewSplF(
const char
cwbOBJ_ParmHandle
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbSV_ErrHandle
*systemName,
*parmListHandle,
*printerFileHandle,
*outputQueueHandle,
*newSplFHandle,
errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
cwbOBJ_ParmHandle *parmListHandle - input
オプションです。スプール・ファイル作成のためのパラメーターを入れる、有効なパラメーター・リス
ト・オブジェクト・ハンドルを指すポインター。このリスト中のパラメーター群は、プリンター・ファ
イルおよび *outputQueueHandle パラメーターの中にあるものを変更します。
cwbOBJ_ObjHandle *printerFileHandle - input
オプションです。このスプール・ファイルの作成時に使用されるプリンター・ファイルを参照する、有
効なプリンター・ファイル・オブジェクト・ハンドルを指すポインター。プリンター・ファイルは、ス
プール・ファイルを作成中の同じシステム上になければなりません。
cwbOBJ_ObjHandle *outputQueueHandle - input
オプションです。このスプール・ファイルが作成されるはずの出力待ち行列を参照する、有効な出力待
ち行列オブジェクト・ハンドルを指すポインター。出力待ち行列は、このスプール・ファイルを作成中
の同じシステム上になければなりません。出力待ち行列が *parmListHandle パラメーター
(CWBOBJ_KEY_OUTQUELIB と CWBOBJ_KEY_OUTQUE) で設定されている場合、この出力待ち行
列は、この出力待ち行列ハンドルによって指定される出力待ち行列を変更します。
cwbOBJ_ObjHandle *newSplFHandle - output
この呼び出しが正常に完了したときに、新しく作成されたスプール・ファイル・ハンドルで埋められる
オブジェクト・ハンドルを指すポインター。新規のスプール・ファイルにデータを書き込み、それをク
ローズするには、このハンドルが必要です。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
300
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが無効です。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
parmListHandle が NULL の場合、または属性を指定しない場合、その属性は使用されるプリンター・ファ
イルから取られます。出力待ち行列を *parmListHandle とともに指定すると、この出力待ち行列は
*outputQueueHandle パラメーターに指定されているものを変更します。出力待ち行列を指定しない
(*parmListHandle になくて、outputQueueHandle が NULL) 場合、使用される出力待ち行列はプリンター・
ファイルから取られます。プリンター・ファイルを指定しない (printerFileHandle が NULL) 場合、サーバ
ーはデフォルトのネットワーク印刷のプリンター・ファイル、*LIBL/QNPSPRTF を使用します。次のパラ
メーター・キーを pParmListHandl オブジェクトに設定することができます。
ページの位置合わせ
背面オーバーレイ・ライブラリー名
背面オーバーレイ
背面オーバーレイ・オフセット (横方向)
背面オーバーレイ・オフセット (下方向)
1 インチ当たりの文字数
コード・ページ
コピー枚数
DBCS データを含む
DBCS 拡張文字の処理
CWBOBJ_KEY_ALIGN
CWBOBJ_KEY_BKOVRLLIB
CWBOBJ_KEY_BKOVRLAY
CWBOBJ_KEY_BKOVL_ACR
CWBOBJ_KEY_BKOVL_DWN
CWBOBJ_KEY_CPI
(1)CWBOBJ_KEY_CODEPAGE
CWBOBJ_KEY_COPIES
CWBOBJ_KEY_DBCSDATA
CWBOBJ_KEY_DBCSEXTENSN
-
CWBOBJ_KEY_DBCSROTATE
CWBOBJ_KEY_DBCSCPI
CWBOBJ_KEY_DBCSSISO
CWBOBJ_KEY_DFR_WRITE
CWBOBJ_KEY_ENDPAGE
(2)CWBOBJ_KEY_FILESEP
CWBOBJ_KEY_FOLDREC
CWBOBJ_KEY_FONTID
CWBOBJ_KEY_FORMFEED
CWBOBJ_KEY_FORMTYPE
CWBOBJ_KEY_FTOVRLLIB
CWBOBJ_KEY_FTOVRLAY
CWBOBJ_KEY_FTOVL_ACR
CWBOBJ_KEY_FTOVL_DWN
(1)CWBOBJ_KEY_CHAR_ID
CWBOBJ_KEY_JUSTIFY
CWBOBJ_KEY_HOLD
CWBOBJ_KEY_LPI
- DBCS 文字回転
- DBCS CPI
- DBCS SO/SI のスペース
- 書き出し据え置き
- 終了ページ
- ファイル区切り
- レコードの折り返し
- フォント識別コード
- 用紙送り
- 用紙タイプ
- 前面オーバーレイ・ライブラリー名
- 前面オーバーレイ
- 前面オーバーレイ・オフセット (横方向)
- 前面オーバーレイ・オフセット (下方向)
- グラフィック文字セット ID
- ハードウェアの位置合わせ
- スプール・ファイルの保留
- 1 インチ当たりの行数
プログラミング
301
CWBOBJ_KEY_MAXRECORDS
CWBOBJ_KEY_OUTPTY
CWBOBJ_KEY_OUTQUELIB
CWBOBJ_KEY_OUTQUE
CWBOBJ_KEY_OVERFLOW
CWBOBJ_KEY_PAGELEN
CWBOBJ_KEY_MEASMETHOD
CWBOBJ_KEY_PAGEWIDTH
CWBOBJ_KEY_MULTIUP
-
スプール出力レコードの最大数
出力優先順位
出力待ち行列ライブラリー名
出力待ち行列
オーバーフロー行番号
ページ長
測定方法
ページ幅
片面当たりの論理ページ数
CWBOBJ_KEY_POINTSIZE
CWBOBJ_KEY_FIDELITY
CWBOBJ_KEY_DUPLEX
CWBOBJ_KEY_PRTQUALITY
CWBOBJ_KEY_PRTTEXT
CWBOBJ_KEY_PRINTER
CWBOBJ_KEY_PRTDEVTYPE
CWBOBJ_KEY_RPLUNPRT
CWBOBJ_KEY_RPLCHAR
CWBOBJ_KEY_SAVESPLF
-
デフォルトのフォントのポイント・サイズ
印刷精度
両面印刷
印刷品質
印刷テキスト
プリンター名
プリンター・タイプ
印刷不能文字の置き換え
置き換え文字
印刷後のスプール・ファイルの保管
CWBOBJ_KEY_SRCDRWR
CWBOBJ_KEY_SPOOL
CWBOBJ_KEY_SPOOLFILE
CWBOBJ_KEY_SCHEDULE
CWBOBJ_KEY_STARTPAGE
CWBOBJ_KEY_UNITOFMEAS
CWBOBJ_KEY_USERCMT
CWBOBJ_KEY_USERDATA
CWBOBJ_KEY_SPLSCS
CWBOBJ_KEY_USRDFNDTA
(3)CWBOBJ_KEY_USRDFNOPTSCWBOBJ_KEY_USRDFNOBJLIB CWBOBJ_KEY_USRDFNOBJ
CWBOBJ_KEY_USRDFNOBJTYP -
用紙入れ
データのスプール
スプール・ファイル名
スプール・ファイルのスケジュール
開始ページ
測定単位
ユーザーの注釈 (100 文字)
ユーザー・データ (10 文字)
スプール SCS データ
ユーザー定義データ
ユーザー定義オプション
ユーザー定義オブジェクト・ライブラリー
ユーザー定義オブジェクト
ユーザー定義オブジェクト・タイプ
注:
1. コード・ページとグラフィック文字セットは相互に依存しています。これらのうちの一方を指定する
と、他方も指定する必要があります。
2. この属性を使用して新規のスプール・ファイルを作成する場合は、特殊値 *FILE は使用できません。
3. 最大 4 つまでのユーザー定義オプションを指定することができます。
cwbOBJ_GetSplFHandleFromNewSplF:
cwbOBJ_GetSplFHandleFromNewSplF API は、この製品と共に使用します。
目的
新規のスプール・ファイル・ハンドルを使用して、スプール・ファイル・ハンドルを生成します。自動デー
タ・タイプ付けを使用して作成された新規スプール・ファイル上でこの API を使用する方法については、
以下の注意を参照してください。
構文
unsigned int CWB_ENTRY cwbOBJ_GetSplFHandleFromNewSplF(
cwbOBJ_ObjHandle
newSplFHandle,
cwbOBJ_ObjHandle
*splFHandle,
cwbSV_ErrHandle
errorHandle);
302
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbOBJ_ObjHandle newSplFHandle - input
新しいスプール・ファイルのハンドル。これは cwbOBJ_CreateNewSplF() API で返されるハンドルで
す。
cwbOBJ_ObjHandle *splFHandle - output
この呼び出しが正常に完了したときに、スプール・ファイル・ハンドルを保持するオブジェクト・ハン
ドルを指すポインター。このハンドルは、スプール・ファイル・ハンドルを入力として用いる他の API
で使用することができます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_SPLFNOTOPEN
まだホスト上にスプール・ファイルが作成されていません。
使用法
splFHandle に戻されたハンドルは、資源を解放するために、cwbOBJ_DeleteObjHandle() API を使用して解
放してください。
スプール・ファイルに自動データ・タイプ付け (CWBOBJ_KEY_PRTDEVTYPE の属性が *AUTO に設定
されているか、cwbOBJ_CreateNewSplF() API 上に設定されていない) を使用している場合、データのタイ
プ (*SCS、*AFPDS または *USERASCII) を判別するため、十分なデータがスプール・ファイルに書き込
まれるまでスプール・ファイルの作成が遅らされます。この API を呼び出す際に、新規スプール・ファイ
ルがこの状態にある場合、戻りコードは CWBOBJ_RC_SPLFNOTOPEN になります。
cwbOBJ_WriteNewSplF:
cwbOBJ_WriteNewSplF API は、この製品と共に使用します。
目的
データを新規作成のスプール・ファイルに書き込みます。
プログラミング
303
構文
unsigned int CWB_ENTRY cwbOBJ_WriteNewSplF(
cwbOBJ_ObjHandle newSplFHandle,
const char
*data,
unsigned long
dataLen,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle newSplFHandle - input
新しいスプール・ファイルのハンドル。これは cwbOBJ_CreateNewSplF() API で返されるハンドルで
す。
const char *data - input
スプール・ファイルに書き込まれるデータ・バッファーを指すポインター。
unsigned long ulDataLen - input
書き込まれるデータの長さ。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
なし (None)
スプール・ファイルの読み取り API
以下の API は、スプール・ファイルの読み取りに関するものです。 API はアルファベット順にリストさ
れます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_CloseSplF:
cwbOBJ_CloseSplF API は、この製品と共に使用します。
304
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
読み取り用にオープンされている IBM i スプール・ファイルをクローズします。
構文
unsigned int CWB_ENTRY
cwbOBJ_CloseSplF(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
splFHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
シークされるスプール・ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
なし (None)
cwbOBJ_OpenSplF:
cwbOBJ_OpenSplF API は、この製品と共に使用します。
目的
IBM i スプール・ファイルを読み取り用にオープンします。
構文
unsigned int CWB_ENTRY
cwbOBJ_OpenSplF(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
splFHandle,
errorHandle);
プログラミング
305
パラメーター
cwbOBJ_ObjHandle splFHandle - input
読み取りのためオープンされるスプール・ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
スプール・ファイルからの読み取りを終了した際には、cwbOBJ_CloseSplF() API を使用してスプール・フ
ァイルをクローズしてください。
cwbOBJ_ReadSplF:
cwbOBJ_ReadSplF API は、この製品と共に使用します。
目的
現行の読み取り位置からバイトを読み取ります。
構文
unsigned int CWB_ENTRY
cwbOBJ_ReadSplF(
cwbOBJ_ObjHandle splFHandle,
char
*bBuffer,
unsigned long
bytesToRead,
unsigned long
*bytesRead,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
読み取られるスプール・ファイルのハンドル。
char *buffer - input
スプール・ファイルから読み取られるバイトを保持するバッファーを指すポインター。
306
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long bytesToRead - input
読み取るバイトの最大数。読み取られる数はこれより少なくなります。
unsigned long *bytesRead - output
実際に読み取られたバイト数。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_SPLFNOTOPEN
スプール・ファイルがまだオープンされていません。
CWBOBJ_RC_SPLFENDOFFILE
ファイルの終わりが読み取られました。
使用法
この API を呼び出す前に、このスプール・ファイル・ハンドルを使用して cwbOBJ_OpenSplF() API を呼
び出す必要があります。読み取り時にファイルの終わりに到達した場合、その戻りコードは
CWBOBJ_SPLF_ENDOFFILE で、bytesRead には読み取られた実際のバイト数が入ります。
cwbOBJ_SeekSplF:
cwbOBJ_SeekSplF API は、この製品と共に使用します。
目的
読み取りのためにオープンされているスプール・ファイル上の現行の読み取り位置を移動させます。
構文
unsigned int CWB_ENTRY
cwbOBJ_SeekSplF(
cwbOBJ_ObjHandle
cwbOBJ_SeekOrigin
signed long
cwbSV_ErrHandle
splFHandle,
seekOrigin,
seekOffset,
errorHandle);
プログラミング
307
パラメーター
cwbOBJ_ObjHandle splFHandle - input
シークされるスプール・ファイルのハンドル。
cwbOBJ_SeekOrigin seekOrigin - input
シークの際の開始位置。有効な値は以下のとおりです。
v CWBOBJ_SEEK_BEGINNING - ファイルの始めからシーク
v CWBOBJ_SEEK_CURRENT - 現行の読み取り位置からシーク
v CWBOBJ_SEEK_ENDING - ファイルの終わりからシーク
signed long seekOffset - input
現行の読み取りポインターを移動させるための、バイト表示によるシーク起点からのオフセット (負ま
たは正)。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_SPLFNOTOPEN
スプール・ファイルがまだオープンされていません。
CWBOBJ_RC_SEEKOUTOFRANGE
シーク・オフセットが範囲外にあります。
使用法
この API を呼び出す前に、このスプール・ファイル・ハンドルを使用して cwbOBJ_OpenSplF() API を呼
び出す必要があります。
スプール・ファイルの操作 API
以下の API は、スプール・ファイルの操作に関するものです。 API はアルファベット順にリストされま
す。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
308
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbOBJ_CallExitPgmForSplF:
cwbOBJ_CallExitPgmForSplF API は、この製品と共に使用します。
目的
IBM i Access のネットワーク印刷サーバー・プログラム QNPSERVR に対して、このスプール・ファイル
の ID とアプリケーションが指定したデータとを、パラメーターとして渡して、出口プログラムの連鎖を
呼び出すように指示します。
構文
unsigned int CWB_ENTRY
cwbOBJ_CallExitPgmForSplF(
cwbOBJ_ObjHandle
splFHandle,
void
*data,
unsigned long
dataLen,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
出口プログラムにパラメーターとして渡されるスプール・ファイルのハンドル。
void *data - input
出口プログラムに渡されるデータのブロックを指すポインター。このデータの形式は出口プログラム特
有のものです。
unsigned long dataLen - input
pData が指すデータの長さ。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
CWBOBJ_RC_NO_EXIT_PGM
出口プログラムがネットワーク印刷サーバーに登録されていません。
プログラミング
309
使用法
これは、クライアント・プログラムが、スプール・ファイルの処理を実行するためにそのサーバー部分と通
信するための 1 つの手段です。QNPSERVR プログラムによって登録された IBM i 出口プログラムが、す
べて呼び出されます。そのため、出口プログラムが認識できるように、*data 内のデータ形式の構成を行う
のは、クライアント・プログラムと出口プログラムの役割になります。 QNPSERVR サーバー・プログラ
ムと出口プログラムの間のインターフェースに関する情報については、IBM i の印刷に関するプログラミ
ングの手引きを参照してください。
cwbOBJ_CreateSplFHandle:
cwbOBJ_CreateSplFHandle API は、この製品と共に使用します。
目的
指定されたシステム上の特定のスプール・ファイルについて、スプール・ファイル・ハンドルを作成しま
す。
構文
unsigned int CWB_ENTRY
cwbOBJ_CreateSplFHandle(
const char
const char
const char
const char
const char
const unsigned long
cwbOBJ_ObjHandle
cwbSV_ErrHandle
*systemName,
*jobName,
*jobNumber,
*jobUser,
*splFName,
splFNumber,
*objectHandle,
errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
const char *jobName - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブの名前を指すポインター。
const char *jobNumber - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブの番号を指すポインター。
const char *jobNumber - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブのユーザーを指すポインタ
ー。
const char *splFName - input
ASCIIZ ストリング内の、スプール・ファイルの名前を指すポインター。
const unsigned long splFNumber - input
スプール・ファイルの番号
cwbOBJ_ObjHandle *objectHandle - output
出力の際は、スプール・ファイル・ハンドルがこれに含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
310
IBM i: Windows アプリケーション・パッケージ: プログラミング
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
この API は、ホスト上のスプール・ファイルを検査しません。このハンドルが最初にスプール・ファイル
のデータ検索に使用されるときに、スプール・ファイルが存在しないとホスト・エラーが起こります。
cwbOBJ_CreateSplFHandleEx:
cwbOBJ_CreateSplFHandleEx API は、この製品と共に使用します。
目的
指定されたシステム上の特定のスプール・ファイルについて、スプール・ファイル・ハンドルを作成しま
す。
構文
unsigned int CWB_ENTRY
cwbOBJ_CreateSplFHandleEx(
const char
const char
const char
const char
const char
const unsigned long
const char
const char
const char
cwbOBJ_ObjHandle
cwbSV_ErrHandle
*systemName,
*jobName,
*jobNumber,
*jobUser,
*splFName,
splFNumber,
*createdSystem,
*createdDate,
*createdTime,
*objectHandle,
errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
プログラミング
311
const char *jobName - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブの名前を指すポインター。
const char *jobNumber - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブの番号を指すポインター。
const char *jobNumber - input
ASCIIZ ストリング内の、スプール・ファイルを作成した IBM i ジョブのユーザーを指すポインタ
ー。
const char *splFName - input
ASCIIZ ストリング内の、スプール・ファイルの名前を指すポインター。
const unsigned long splFNumber - input
スプール・ファイルの番号
const char *createdSystem - input
ASCIIZ ストリング内の、スプール・ファイルが作成されたシステムの名前を指すポインター。
const char *createdDate - input
ASCIIZ ストリング内の、スプール・ファイルが作成された日付を指すポインター。
const char *createdTime - input
ASCIIZ ストリング内の、スプール・ファイルが作成された時刻を指すポインター。
cwbOBJ_ObjHandle *objectHandle - output
出力の際は、スプール・ファイル・ハンドルがこれに含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
この API は、ホスト上のスプール・ファイルを検査しません。このハンドルが最初にスプール・ファイル
のデータ検索に使用されるときに、スプール・ファイルが存在しないとホスト・エラーが起こります。
312
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbOBJ_DeleteSplF:
cwbOBJ_DeleteSplF API は、この製品と共に使用します。
目的
IBM i スプール・ファイルを削除します。
構文
unsigned int CWB_ENTRY
cwbOBJ_DeleteSplF(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
splFHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
削除されるスプール・ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
使用法
この呼び出しが正常に戻った後、splFHandle を解放するため cwbOBJ_DeleteObjHandle() を呼び出してくだ
さい。
cwbOBJ_DisplaySplF:
cwbOBJ_DisplaySplF API は、この製品と共に使用します。
目的
指定されたスプール・ファイルをユーザーに表示します。
プログラミング
313
構文
unsigned int CWB_ENTRY
cwbOBJ_DisplaySplF(
cwbOBJ_ObjHandle
splFHandle,
const char
*view,
const unsigned long flags,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
パラメーター・オブジェクトのハンドル。
const char *view - input
オプションであり、NULL でも構いません。指定された場合、スプール・ファイル・ビューアーを呼び
出す際に使用するビューを指定する、ASCIIZ ストリングを指すポインターです。ビューアーとともに
出荷される 2 つの事前定義されたビューがあります。
1. LETTER (8.5" x 11")
2. SFLVIEW (132 桁)
ユーザー自身のビューを追加することもできます。
const unsigned long flags - input
以下のビットのいずれかが設定されることがあります。CWBOBJ_DSPSPLF_WAIT - この呼び出しに対
して、戻る前に、ビューアーのプロセスがスプール・ファイルを正常にオープンするまで待機するよう
に伝えます。このビットが 0 の場合、この API は、ビューアーのプロセスを開始した後で戻ります。
このビットが 1 の場合、この API は、戻る前に、ビューアーがスプール・ファイルをオープンするま
で待機します。他のすべてのビットは、0 に設定される必要があります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_NO_VIEWER
Client Access/400 のビューアー・サポートがインストールされていません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
314
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
この API は、指定されたスプール・ファイルに AFP ビューアーを呼び出すために使用してください。
AFP ビューアーは、AFP データ、SCS データ、および ASCII のプレーン・テキスト・データを表示する
ことができます。戻りコード CWB_NO_VIEWER は、ビューアー構成要素がワークステーションにインス
トールされていなかったことを意味します。
cwbOBJ_HoldSplF:
cwbOBJ_HoldSplF API は、この製品と共に使用します。
目的
スプール・ファイルを保留します。
構文
unsigned int CWB_ENTRY
cwbOBJ_HoldSplF(
cwbOBJ_ObjHandle
cwbOBJ_ParmHandle
cwbSV_ErrHandle
splFHandle,
*parmListHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
保留されるスプール・ファイルのハンドル。
cwbOBJ_ParmHandle *parmListHandle - input
オプションです。スプール・ファイルを保留するためのパラメーターを含む、有効なパラメーター・リ
スト・オブジェクト・ハンドルを指すポインター。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
プログラミング
315
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
使用法
以下のパラメーター・キーが parmListHandle オブジェクトに設定できます。
v CWBOBJ_KEY_HOLDTYPE
実行する保留のタイプを指定します。"*IMMED" または "*PAGEEND" で、"*IMMED" がデフォルト。
cwbOBJ_IsViewerAvailable:
cwbOBJ_IsViewerAvailable API は、この製品と共に使用します。
目的
スプール・ファイル・ビューアーが使用可能かどうかを検査します。
構文
unsigned int CWB_ENTRY
cwbOBJ_IsViewerAvailable(
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了 (ビューアーはインストールされています)。
CWB_NO_VIEWER
ビューアーがインストールされていません。
使用法
ワークステーションにビューアーが存在するかどうかをテストするには、この関数を使用してください。ビ
ューアーがインストールされている場合、この関数は CWB_OK を戻します。ビューアーが使用不可の場
合、この関数は CWB_NO_VIEWER を戻し、errorHandle パラメーター (与えられている場合) には適切な
エラー・メッセージが入ります。この関数を使用すると、アプリケーションは cwbOBJ_DisplaySplF() API
を呼び出すことなしに、ビューアー・サポートについて検査することができます。
cwbOBJ_MoveSplF:
cwbOBJ_MoveSplF API は、この製品と共に使用します。
316
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
IBM i スプール・ファイルを、別の出力待ち行列、または同じ出力待ち行列の別の位置に移動します。
構文
unsigned int CWB_ENTRY
cwbOBJ_MoveSplF(
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbOBJ_ObjHandle
cwbSV_ErrHandle
splFHandle,
*targetSplFHandle,
*outputQueueHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
移動されるスプール・ファイルのハンドル。
cwbOBJ_ObjHandle *targetSplFHandle - input
オプションです。同じシステム上の別のスプール・ファイルのハンドルであり、このスプール・ファイ
ルをそのあとに移動させるスプール・ファイルを指定します。これが指定されていると、
*outputQueueHandle は使用されません。
cwbOBJ_ObjHandle *outputQueueHandle - input
オプションです。どの出力待ち行列にスプール・ファイルを移動させるかを指定する、同じシステム上
の出力待ち行列のハンドル。スプール・ファイルは、この待ち行列の最初の位置に移動されます。この
パラメーターは、targetSplFHandle が指定されると無視されます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
使用法
targetSplFHandle と outputQueueHandle の両方が NULL の場合は、スプール・ファイルは、現行の出力待
ち行列の最初の位置に移動されます。
プログラミング
317
cwbOBJ_ReleaseSplF:
cwbOBJ_ReleaseSplF API は、この製品と共に使用します。
目的
スプール・ファイルを解放します。
構文
unsigned int CWB_ENTRY
cwbOBJ_ReleaseSplF(
cwbOBJ_ObjHandle
cwbSV_ErrHandle
splFHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
解放されるスプール・ファイルのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
使用法
なし (None)
cwbOBJ_SendNetSplF:
cwbOBJ_SendNetSplF API は、この製品と共に使用します。
目的
スプール・ファイルを、同じシステム上の別のユーザーまたはネットワーク上のリモート・システムに送信
します。
318
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY
cwbOBJ_SendNetSplF(
cwbOBJ_ObjHandle
cwbOBJ_ParmHandle
cwbSV_ErrHandle
splFHandle,
parmListHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
送信されるスプール・ファイルのハンドル。
cwbOBJ_ParmHandle parmListHandle - input
必須です。スプール・ファイルを送信するためのパラメーターが入っているパラメーター・リスト・オ
ブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
CWB_INVALID_PARAMETER
指定のパラメーターが無効です。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
使用法
ネット・スプール・ファイルの送信 (SNDNETSPLF) コマンドに相当するコマンドがスプール・ファイルに
対して出されます。以下のパラメーター・キーを parmListHandl オブジェクトに設定する必要がありま
す。
v CWBOBJ_KEY_TOUSERID
スプール・ファイルを送る先のユーザー ID を指定。
v CWBOBJ_KEY_TOADDRESS
スプール・ファイルが送られるリモート・システムを指定。"*NORMAL" がデフォルト。
以下のパラメーター・キーを parmListHandle オブジェクトに設定できます。
プログラミング
319
v CWBOBJ_KEY_DATAFORMAT
スプール・ファイルを伝送するデータ形式を指定。"*RCDDATA" または "*ALLDATA"。 "*RCDDATA"
がデフォルト。
v CWBOBJ_KEY_VMMVSCLASS
VM ホスト・システムまたは MVS™ ホスト・システムへ配布するための VM/MVS SYSOUT クラスを
指定。"A" から "Z" または "0" から "9"。"A" がデフォルト。
v CWBOBJ_KEY_SENDPTY
SNADS ネットワークを介しての経路指定中に、このスプール・ファイル用に使用される待ち行列優先順
位を指定。"*NORMAL" または "*HIGH"。"*NORMAL" がデフォルト。
cwbOBJ_SendTCPSplF:
cwbOBJ_SendTCPSplF API は、この製品と共に使用します。
目的
リモート・システムで印刷されるスプール・ファイルを送信します。これは TCP/IP LPR コマンドの IBM
i バージョンになります。
構文
unsigned int CWB_ENTRY
cwbOBJ_SendTCPSplF(
cwbOBJ_ObjHandle
cwbOBJ_ParmHandle
cwbSV_ErrHandle
splFHandle,
parmListHandle,
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
送信されるスプール・ファイルのハンドル。
cwbOBJ_ParmHandle parmListHandle - input
必須です。スプール・ファイルを送信するためのパラメーターが入っているパラメーター・リスト・オ
ブジェクトのハンドル。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
無効なハンドル。
320
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
CWBOBJ_KEY_SEPPAGE
区切りページを印刷するかどうかを指定します。
CWBOBJ_KEY_USRDTATFMLIB
ユーザー・データ変換ライブラリーの名前を指定します。
CWBOBJ_KEY_USRDTATFM
ユーザー・データ変換プログラムの名前を指定します。
使用法
IBM i の TCP/IP スプール・ファイル送信 (SNDTCPSPLF) コマンドに相当するコマンドが、スプール・フ
ァイルに対して出されます。以下のパラメーター・キーを parmListHandl オブジェクトに設定する必要が
あります。
v CWBOBJ_KEY_RMTSYSTEM
印刷要求が送られるリモート・システムを指定。リモート・システム名または "*INTNETADR"。
v CWBOBJ_KEY_RMTPRTQ
宛先印刷待ち行列の名前を指定。
以下のパラメーター・キーを parmListHandle オブジェクトに設定できます。
v CWBOBJ_KEY_DELETESPLF
スプール・ファイルが正常に送信された後にそのスプール・ファイルを削除するかどうかを指定しま
す。"*NO" または "*YES"。"*NO" がデフォルト。
v CWBOBJ_KEY_DESTOPTION
宛先によって決まるオプションを指定。これらのオプションは、スプール・ファイルとともにリモー
ト・システムへ送られる。
v CWBOBJ_KEY_DESTINATION
スプール・ファイルが送られているシステムのタイプを指定。別のタイプの IBM i に送る場合は、この
値を "*AS/400" にします。 "*OTHER" または "*PSF/2" の場合もありえます。 "*OTHER" がデフォル
ト。
v CWBOBJ_KEY_INTERNETADDR
受信システムの IP アドレスを指定。
v CWBOBJ_KEY_MFGTYPE
印刷データを SCS から ASCII へ変換する際に、メーカー、機種、および型式を指定。
v CWBOBJ_KEY_SCS2ASCII
プログラミング
321
印刷データを SCS から ASCII へ変換するかどうかを指定。"*NO" または "*YES"。"*NO" がデフォル
ト。
v CWBOBJ_KEY_WSCUSTMOBJ
ワークステーション・カスタマイズ・オブジェクトの名前を指定。
v CWBOBJ_KEY_WSCUSTMOBJL
ワークステーション・カスタマイズ・オブジェクト・ライブラリーの名前を指定。
スプール・ファイル・メッセージを処理する API
以下の API は、スプール・ファイル・メッセージの処理に関するものです。 API はアルファベット順に
リストされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_AnswerSplFMsg:
cwbOBJ_AnswerSplFMsg API は、この製品と共に使用します。
目的
スプール・ファイルが待機しているメッセージに応答します。
構文
unsigned int CWB_ENTRY
cwbOBJ_AnswerSplFMsg(
cwbOBJ_ObjHandle
splFHandle,
char
*msgAnswer,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
メッセージを応答するスプール・ファイルのハンドル。
const char *msgAnswer - input
メッセージ応答が入っている ASCIIZ ストリングを指すポインター。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、有効なスプール・ファイル・ハンドルではありません。
322
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_TYPE
ハンドルが、スプール・ファイル・ハンドルではありません。
CWBOBJ_RC_SPLFNOMESSAGE
スプール・ファイルがメッセージを待機していません。
使用法
なし (None)
cwbOBJ_GetSplFMsgAttr:
cwbOBJ_GetSplFMsgAttr API は、この製品と共に使用します。
目的
スプール・ファイルに関連するメッセージの属性を検索します。
構文
unsigned int CWB_ENTRY
cwbOBJ_GetSplFMsgAttr(
cwbOBJ_ObjHandle splFHandle,
cwbOBJ_KeyID
key,
void
*buffer,
unsigned long
bufLen,
unsigned long
*bytesNeeded,
cwbOBJ_DataType *keyType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbOBJ_ObjHandle splFHandle - input
スプール・ファイルのハンドル。
cwbOBJ_KeyID key - input
検索する属性の識別キー。CWBOBJ_KEY_XXX 定数がキー ID を定義します。
void *buffer - output
この呼び出しが正常に戻った場合は、属性値を保持するバッファー。*Buffer に置かれるデータ・タイ
プは何かをキー値が決定します。タイプが与えられた場合、このタイプも *keyType パラメーターへ戻
されます。
unsigned long bufLen - input
*Buffer が指すバッファーの長さ。
unsigned long *bytesNeeded - output
出力の際には、結果を保持するために必要なバイト数が入ります。
cwbOBJ_DataType *keyType - output
オプションであり、NULL でも構いません。出力の際には、この属性と、*buffer に何が保管されるか
を表すために使用されるデータ・タイプが含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
プログラミング
323
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_INVALID_HANDLE
ハンドルが、割り振られたオブジェクト・ハンドルではありません。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
CWBOBJ_RC_INVALID_KEY
キーが有効ではありません。
CWBOBJ_RC_SPLFNOMESSAGE
スプール・ファイルがメッセージを待機していません。
CWB_API_ERROR
一般 API 障害。
使用法
以下のキーが有効です。
CWBOBJ_KEY_MSGTEXT
CWBOBJ_KEY_MSGHELP
CWBOBJ_KEY_MSGREPLY
CWBOBJ_KEY_MSGTYPE
CWBOBJ_KEY_MSGID
CWBOBJ_KEY_MSGSEV
CWBOBJ_KEY_DATE
CWBOBJ_KEY_TIME
-
メッセージ・テキスト
メッセージ・ヘルプ・テキスト
メッセージ応答
メッセージ・タイプ
メッセージ ID
メッセージ重大度
メッセージ日付
メッセージ時刻
メッセージ様式化文字がメッセージ・テキスト内に示されますが、この文字は、次のように使用してくださ
い。
&N
強制的にテキストを 2 桁字下げして改行します。そのテキストが 1 行を超える場合は、テキスト
の終わりや別の様式制御文字に達するまで、4 桁字下げして改行する必要があります。
&P
強制的にテキストを 6 桁字下げして改行します。そのテキストが 1 行を超える場合は、テキスト
の終わりや別の様式制御文字に達するまで、4 桁字下げして改行する必要があります。
&B
強制的にテキストを 4 桁字下げして改行します。そのテキストが 1 行を超える場合は、テキスト
の終わりや別の様式制御文字に達するまで、6 桁字下げして改行する必要があります。
324
IBM i: Windows アプリケーション・パッケージ: プログラミング
スプール・ファイル・データを分析する API
以下の API は、スプール・ファイル・データの分析に関するものです。 API はアルファベット順にリス
トされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_AnalyzeSplFData:
cwbOBJ_AnalyzeSplFData API は、この製品と共に使用します。
目的
スプール・ファイルのデータを分析し、データ・タイプが何であるかについての最善の予測を与えます。
構文
unsigned int CWB_ENTRY cwbOBJ_AnalyzeSplFData(
const char
unsigned long
cwbOBJ_SplFDataType
cwbSV_ErrHandle
*data,
bufLen,
*dataType,
errorHandle);
パラメーター
const char *data - input
分析されるデータを指すポインター。
unsigned long bufLen - input
データが指すバッファーの長さ。
cwbOBJ_SplFDataType *dataType - output
出力の際は、データ・タイプがこれに含まれます。データ・タイプが決められない場合は、デフォルト
は CWBOBJ_DT_USERASCII になります。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
使用法
これは、データ・タイプが指定されていないか、もしくは *AUTO が指定されているスプール・ファイル
の作成時に使用されるものと同じルーチンが使用されます。それが決められない場合は、その結果は
*USERASCII がデフォルトになります。
プログラミング
325
API のサーバー・プログラム
以下の API は、サーバー・プログラムに関するものです。 API はアルファベット順にリストされます。
注: 以下の API でハンドルを処理する場合に、有効なハンドルとして 0 が戻されることはありません。
cwbOBJ_DropConnections:
cwbOBJ_DropConnections API は、この製品と共に使用します。
目的
このプロセスに使用するネットワーク印刷サーバーの、すべてのシステムとの未使用会話をすべて除去しま
す。
構文
unsigned int CWB_ENTRY
cwbOBJ_DropConnections(
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべて、このオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
使用法
CWBOBJ.DLL は、API 上で使用するためのネットワーク印刷サーバーで使用できる会話のプールを維持管
理します。通常、これらの会話は、10 から 20 分の未使用時間が経過した後にタイムアウトになった上で
除去されます。この API を使用すれば、アプリケーションは、タイムアウトを待たずに、即時に会話のプ
ールを終結処理できるようになります。また、この API をプロセスの終了時に使用して、すべての会話が
終了していることを保証することもできます。この API は、このプロセスに使用するすべてのサーバーと
の「使用中」でない接続をすべて除去します。使用中の接続には、スプール・ファイルが (作成または読み
取りのために) オープンされている接続も含まれます。
cwbOBJ_GetNPServerAttr:
cwbOBJ_GetNPServerAttr API は、この製品と共に使用します。
目的
指定されたシステム上の QNPSERVR プログラムの属性を取得します。
326
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbOBJ_GetNPServerAttr(
const char
*systemName,
cwbOBJ_KeyID
key,
void
*buffer,
unsigned long
bufLen,
unsigned long
*bytesNeeded,
cwbOBJ_DataType *keyType,
cwbSV_ErrHandle errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
cwbOBJ_KeyID key - input
検索する属性の識別キー。
void *buffer - output
属性値を保持するバッファー (この呼び出しが正常に戻った場合)。*Buffer に置かれるデータ・タイプ
は何かをキー値が決定します。タイプが与えられた場合、このタイプも *keyType パラメーターへ戻さ
れます。
unsigned long bufLen - input
*Buffer が指すバッファーの長さ。
unsigned long *bytesNeeded - output
出力の際には、結果を保持するために必要なバイト数が入ります。
cwbOBJ_DataType *keyType - output
オプションであり、NULL でも構いません。出力の際には、この属性と、*buffer に何が保管されるか
を表すために使用されるデータ・タイプが含まれます。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべてこのオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。
CWB_BUFFER_OVERFLOW
バッファーが小さすぎます。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
CWBOBJ_RC_HOST_ERROR
ホストでエラーが発生しました。テキストは errorHandle にあります。
プログラミング
327
CWBOBJ_RC_INVALID_KEY
キーが有効ではありません。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
以下の属性を QNPSERVR プログラムから検索することができます。
v CWBOBJ_KEY_NPSCCSID - サーバー CCSID
v CWBOBJ_KEY_NPSLEVEL - サーバー・コード・レベル
cwbOBJ_SetConnectionsToKeep:
cwbOBJ_SetConnectionsToKeep API は、この製品と共に使用します。
目的
特定システムに対して活動状態のままにしておく必要のある接続の数を設定します。通常、ある未使用時間
が経過した後に cwbobj.dll はタイムアウトになり、接続を除去します。この API を使用すれば、システム
に対して、ある一定数の接続を強制的にオープンしたままにさせることが可能になります。
構文
unsigned int CWB_ENTRY cwbOBJ_SetConnectionsToKeep(
const char *systemName
unsigned int connections
cwbSV_ErrHandle errorHandle);
パラメーター
const char *systemName - input
ASCIIZ ストリングに入っているシステム名を指すポインター。
unsigned int connections - input
オープンの状態を保留させる接続の数。
cwbSV_ErrHandle errorHandle - output
オプションです。0 でも構いません。戻されたメッセージはすべて、このオブジェクトに書き込まれま
す。このオブジェクトは、cwbSV_CreateErrHandle() API で作成されます。メッセージは、
cwbSV_GetErrText() API を介して検索することができます。パラメーターがゼロに設定されている場
合は、メッセージは検索できません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_PARAMETER
指定のパラメーターが無効。
328
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
1 つのシステムにつき、オープンの状態を保持させる接続のデフォルト数は 0 です。接続はプロセスごと
に行われるため、この API は、それを呼び出したプロセスに属している接続のみに有効です。オープン状
態を保持させる接続の数を設定しても、いかなる新規接続もオープンされません。
例: システム・オブジェクト API の使用法
次の例は、スプール・ファイルのリストの検索とそれらの表示を行うための通常の呼び出し手順を示してい
ます。
/********************************************************/
/* List all spooled files for the current user and
*/
/* display them to the user.
*/
/********************************************************/
#ifdef UNICODE
#define _UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include "CWBOBJ.H"
main(int argc, char *argv[ ], char *envp[ ])
{
cwbOBJ_ListHandle listHandle;
cwbOBJ_ObjHandle splFHandle;
unsigned int ulRC;
unsigned long ulListSize, ulObjPosition, ulBytesNeeded;
cwbOBJ_KeyID keysWanted[] = { CWBOBJ_KEY_SPOOLFILE,
CWBOBJ_KEY_USER };
unsigned long ulNumKeysWanted = sizeof(keysWanted)/sizeof(*keysWanted);
char szSplFName[11];
char szUser[11];
ulRC = cwbOBJ_CreateListHandle(_TEXT("ANYAS400"),
CWBOBJ_LIST_SPLF,
&listHandle,
0);
if (ulRC == CWB_OK)
{
/* Set up the filter for the list to be opened with
/* NOTE: this is just for example, the user defaults
/*
to *CURRENT, so this isn’t really needed.
*/
*/
*/
cwbOBJ_SetListFilter(listHandle, CWBOBJ_KEY_USER,
_TEXT("*CURRENT"), 0);
/* Optionally call to cwbOBJ_SetListAttrsToRetrieve to*/
/* make walking the list faster
*/
ulRC = cwbOBJ_SetListAttrsToRetrieve(listHandle,
ulNumKeysWanted,
keysWanted,
0);
/* open the list - this will build the list of spooled*/
/* files.
*/
ulRC = cwbOBJ_OpenList(listHandle,
CWBOBJ_LIST_OPEN_SYNCH,
0);
if (ulRC == CWB_OK)
{
/* Get the number of items that are in the list
*/
ulRC = cwbOBJ_GetListSize(listHandle,
&ulListSize,
プログラミング
329
(cwbOBJ_List_Status *)0,
0);
if (ulRC == CWB_OK)
{
/* walk through the list of items, displaying */
/* each item to the user
*/
ulObjPosition = 0;
while (ulObjPosition < ulListSize)
{
/*******************************************/
/* Get a handle to the next spooled file in*/
/* the list. This handle is valid while
*/
/* the list is open. If you want to
*/
/* maintain a handle to the spooled file
*/
/* after the list is closed, you could call*/
/* cwbOBJ_CopyObjHandle() after this call. */
/*******************************************/
ulRC = cwbOBJ_GetObjHandle(listHandle,
ulObjPosition,
&splFHandle,
0);
if (ulRC == CWB_OK)
{
/****************************************/
/* call cwbOBJ_GetObjAttr() to get info */
/* about this spooled file. May also
*/
/* call spooled file specific APIs
*/
/* with this handle, such as
*/
/* cwbOBJ_HoldSplF().
*/
/****************************************/
ulRC = cwbOBJ_GetObjAttr(splFHandle,
CWBOBJ_KEY_SPOOLFILE,
(void *)szSplFName,
sizeof(szSplFName),
&ulBytesNeeded,
NULL,
0);
if (ulRC == CWB_OK)
{
ulRC = cwbOBJ_GetObjAttr(splFHandle,
CWBOBJ_KEY_USER,
(void *)szUser,
sizeof(szUser),
&ulBytesNeeded,
NULL,
0);
if (ulRC == CWB_OK)
{
printf("%3u: %11s %s¥n",
ulObjPosition, szSplFName, szUser);
} else {
/* ERROR on GetObjAttr! */
}
} else {
/* ERROR on GetObjAttr! */
}
/* free this object handle
*/
cwbOBJ_DeleteObjHandle(splFHandle, 0);
} else {
/* ERROR on GetObjHandle! */
}
ulObjPosition++;
}
330
IBM i: Windows アプリケーション・パッケージ: プログラミング
} else {
/* ERROR on GetListSize! */
}
cwbOBJ_CloseList(listHandle, 0);
} else {
/* ERROR on OpenList! */
}
cwbOBJ_DeleteListHandle(listHandle, 0);
}
リモート・コマンド/分散プログラム呼び出し API
PC アプリケーション・プログラマーは、リモート・コマンド/分散プログラム呼び出し API を使用するこ
とで、IBM i の機能にアクセスできます。ユーザー・プログラムとシステム・コマンドを、エミュレーシ
ョン・セッションなしに呼び出します。コマンドとプログラムは単一の IBM i プログラムによって扱われ
るため、コマンドとプログラムの両方に対して、1 つのシステム・ジョブのみが開始されます。
リモート・コマンド API
リモート・コマンド・アプリケーション・プログラミング・インターフェース (API) を使用すると、PC ア
プリケーションで非対話式の IBM i コマンドを開始して、これらのコマンドから完了メッセージを受け取
ることができるようになります。 IBM i コマンドは、最高 10 個までの応答メッセージを送信することが
できます。
分散プログラム呼び出し API
分散プログラム呼び出し API を使用すると、PC アプリケーションで任意の IBM i プログラムやコマンド
を呼び出すことができるようになります。入力、出力、および入出力のパラメーターは、この関数を介して
扱われます。プログラムが正しく実行されると、出力パラメーターと入出力パラメーターに、呼び出された
IBM i プログラムが戻したデータが入ります。プログラムがシステムで正しく実行されなかった場合は、
そのプログラムは、最高 10 個までの応答メッセージを送信することができます。
リモート・コマンド/分散プログラム呼び出し API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbrc.h
cwbapi.lib
cwbrc.dll
Programmer's Toolkit:
Programmer's Toolkit には、リモート・コマンドおよび分散プログラム呼び出しの資料、cwbrc.h ヘッダ
ー・ファイルへのアクセス、およびプログラム例へのリンクが用意されています。この情報にアクセスする
には、Programmer's Toolkit をオープンして、「リモート・コマンド」または「分散プログラム」 >
「C/C++ API」と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
23 ページの『リモート・コマンド/分散プログラム呼び出し API 戻りコード』
リモート・コマンド/分散プログラム呼び出し API の戻りコードを示します。
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
プログラミング
331
6 ページの『OEM、ANSI、およびユニコードの考慮事項』
ストリング・パラメーターを受け入れる C/C++ API の大部分は、OEM、ANSI、Unicode の 3 つのうち、
いずれかの形式になっています。
リモート・コマンド/分散プログラム呼び出し API の一般的な使用法
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
これらの各オブジェクトは、ハンドルによってアプリケーションに識別されます。
システム・オブジェクト
これは IBM i の ID です。このシステム・オブジェクトを指すハンドルは、コマンドや API が実
行されるシステムを識別するために、StartSysEx 関数に与えられます。
コマンド要求オブジェクト
これは IBM i の要求を表します。このオブジェクト上で、コマンドを実行させ、プログラムを呼
び出すことができます。
注: 以前のこの製品では、コマンド要求オブジェクトは「システム・オブジェクト」と呼ばれてい
ました。
プログラム・オブジェクト
IBM i プログラムを表します。パラメーターを追加し、プログラム情報をシステムへ送って、プロ
グラムを実行することができます。
コマンド用の別個のオブジェクトはありません。コマンド・ストリングは、コマンド要求へ直接送られま
す。
リモート・コマンド/分散プログラム呼び出し API を使用するアプリケーションでは、最初に、
cwbCO_CreateSystem 関数を呼び出してシステム・オブジェクトを作成します。この関数は、そのシステ
ム・オブジェクトを指すハンドルを戻します。次に、このハンドルを cwbRC_StartSysEx 関数で使用して、
IBM i の会話を開始します。cwbRC_StartSysEx 関数は、コマンド要求を指すハンドルを戻します。このコ
マンド要求ハンドルを使用して、プログラムを呼び出したり、あるいは、コマンドを実行することができま
す。コマンド要求オブジェクトに関連した API には、次のものがあります。
v cwbRC_StartSysEx
v cwbRC_CallPgm
v cwbRC_RunCmd
v cwbRC_StopSys
コマンドは、IBM i プラットフォーム上で実行される文字ストリングです。これは、単純なオブジェクト
(文字ストリング) であるため、コマンドを実行するために追加のオブジェクトを作成する必要はありませ
ん。コマンド・ストリングは、単に、cwbRC_RunCmd API でのパラメーターです。
プログラムは、cwbRC_CreatePgm API によって作成される複合オブジェクトです。この API には、プロ
グラム名とライブラリー名をパラメーターとして指定する必要があります。この関数によって戻されるハン
ドルには、0 から 35 のパラメーターを関連付けることができます。パラメーターは、cwbRC_AddParm 関
数を使って追加されます。パラメーター・タイプには、入力、出力、または入出力があります。これらのパ
ラメーターは、IBM i プログラムが処理できる形式 (つまり、データの変形や変換は行われないもの) で指
定する必要があります。パラメーターがすべて追加されたら、プログラム・ハンドルがコマンド要求オブジ
ェクトの cwbRC_CallPgm API で使用されます。プログラム・オブジェクトに関連する API には、次のも
のがあります。
332
IBM i: Windows アプリケーション・パッケージ: プログラミング
v cwbRC_AddParm
v cwbRC_CreatePgm
v cwbRC_DeletePgm
v cwbRC_GetLibName
v cwbRC_GetParm
v cwbRC_GetParmCount
v cwbRC_GetPgmName
v cwbRC_SetLibName
v cwbRC_SetParm
v cwbRC_SetPgmName
関連資料:
43 ページの『cwbCO_CreateSystem』
cwbCO_CreateSystem コマンドを使用します。
335 ページの『cwbRC_StartSysEx』
cwbRC_StartSysEx API は、この製品と共に使用します。
340 ページの『cwbRC_CallPgm』
cwbRC_CallPgm API は、この製品と共に使用します。
337 ページの『cwbRC_RunCmd』
cwbRC_RunCmd API は、この製品と共に使用します。
336 ページの『cwbRC_StopSys』
cwbRC_StopSys API は、この製品と共に使用します。
341 ページの『cwbRC_CreatePgm』
cwbRC_CreatePgm API は、この製品と共に使用します。
338 ページの『cwbRC_AddParm』
cwbRC_AddParm API は、この製品と共に使用します。
345 ページの『cwbRC_GetParmCount』
cwbRC_GetParmCount API は、この製品と共に使用します。
344 ページの『cwbRC_GetParm』
cwbRC_GetParm API は、この製品と共に使用します。
346 ページの『cwbRC_GetPgmName』
cwbRC_GetPgmName API は、この製品と共に使用します。
343 ページの『cwbRC_GetLibName』
cwbRC_GetLibName API は、この製品と共に使用します。
348 ページの『cwbRC_SetParm』
cwbRC_SetParm API は、この製品と共に使用します。
349 ページの『cwbRC_SetPgmName』
cwbRC_SetPgmName API は、この製品と共に使用します。
347 ページの『cwbRC_SetLibName』
cwbRC_SetLibName API は、この製品と共に使用します。
342 ページの『cwbRC_DeletePgm』
cwbRC_DeletePgm API は、この製品と共に使用します。
プログラミング
333
リモート・コマンド/分散プログラム呼び出し: リモート・コマンド API リストへのアク
セス
IBM i リモート・コマンドのサーバー・プログラムにアクセスします。コマンドの実行およびプログラム
の呼び出しには、要求ハンドルが使用されます。 API はアルファベット順にリストされます。
cwbRC_GetClientCCSID:
cwbRC_GetClientCCSID API は、この製品と共に使用します。
目的
現行のプロセスと関連した、コード化文字セット識別コード (CCSID) を取得します。この CCSID をホス
トの CCSID と一緒に使用すると、何らかの IBM i プログラムから戻される EBCDIC データを、クライ
アント・アプリケーションで使用可能な ASCII データに変換できます。
構文
unsigned int CWB_ENTRY cwbRC_GetClientCCSID(
cwbRC_SysHandle
unsigned long
system,
*clientCCSID);
パラメーター
cwbRC_SysHandle system - input
以前の cwbRC_StartSysEx 関数への呼び出しによって戻されたハンドル。これは IBM i の ID です。
unsigned long * clientCCSID - output
クライアント CCSID が書き込まれる先の、無符号長精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
使用法
CWBNLCNV.H ファイル中の関連する API を参照してください。
cwbRC_GetHostCCSID:
cwbRC_GetHostCCSID API は、この製品と共に使用します。
目的
IBM i ジョブに関連付けられたコード化文字セット ID (CCSID) を取得します。この CCSID をクライア
ントの CCSID と一緒に使用すると、何らかの IBM i プログラムから戻される EBCDIC データを、クラ
イアント・アプリケーションで使用可能な ASCII データに変換できます。
334
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbRC_GetHostCCSID(
cwbRC_SysHandle
unsigned long
system,
*hostCCSID);
パラメーター
cwbRC_SysHandle system - input
以前の cwbRC_StartSysEx 関数への呼び出しによって戻されたハンドル。これは IBM i の ID です。
unsigned long * hostCCSID - output
ホスト CCSID が書き込まれる先の、無符号長精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
使用法
CWBNLCNV.H ファイル中の関連する API を参照してください。
cwbRC_StartSysEx:
cwbRC_StartSysEx API は、この製品と共に使用します。
目的
この関数は、指定されたシステムとの会話を開始させます。会話が正常に開始されると、ハンドルが戻され
ます。このハンドルは、これ以降のすべてのコマンドの発行またはプログラムの呼び出しに使用します。こ
の会話が不要になった時点で、会話を終了させるために、このハンドルを cwbRC_StopSys API で使用して
ください。cwbRC_StartSysEx API は、1 つのアプリケーション内で何度も呼び出すことができます。
StartSysEx 呼び出しで同じシステム・オブジェクト・ハンドルを使用した場合、開始される IBM i の会話
は 1 つだけです。複数の会話を活動状態にするには、別々のシステム・オブジェクト・ハンドルを指定し
て、StartSysEx を何度も呼び出す必要があります。
構文
unsigned int CWB_ENTRY cwbRC_StartSysEx(
const cwbCO_SysHandle systemObj,
cwbRC_SysHandle
*request);
パラメーター
const cwbCO_SysHandle systemObj - input
プログラムとコマンドの実行元にするシステムの既存のシステム・オブジェクトを指すハンドル。
プログラミング
335
cwbRC_SysHandle *request - output
コマンド要求のハンドルが戻される cwbRC_SysHandle を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_COMMUNICATIONS_ERROR
通信エラーが発生しました。
CWB_SERVER_PROGRAM_NOT_FOUND
IBM i アプリケーションが見つかりません。
CWB_HOST_NOT_FOUND
システムが非活動中であるか、または存在しません。
CWB_SECURITY_ERROR
セキュリティー・エラーが発生しました。
CWB_LICENSE_ERROR
ライセンス・エラーが発生しました。
CWB_CONFIG_ERROR
構成エラーが発生しました。
CWBRC_SYSTEM_NAME
システム名が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
なし
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_StopSys:
cwbRC_StopSys API は、この製品と共に使用します。
目的
この関数は、ハンドルで指定されたシステムとの会話を停止させます。これ以降このハンドルは、プログラ
ム呼び出しまたはコマンドの発行には使用できなくなります。
336
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbRC_StopSys(
cwbRC_SysHandle
system);
パラメーター
cwbRC_SysHandle system - input
以前の cwbRC_StartSysEx 関数への呼び出しによって戻されたハンドル。これは IBM i の ID です。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
リモート・コマンド/分散プログラム呼び出し: API リストの実行
これらの API は、IBM i コマンドの実行に使用します。 API はアルファベット順にリストされます。
cwbRC_RunCmd:
cwbRC_RunCmd API は、この製品と共に使用します。
目的
ハンドルによって識別されたシステム上でコマンドを出します。戻りコードはコマンドが成功か失敗かを示
します。戻されたメッセージ・ハンドルを使用して、追加のメッセージを戻すことができます。
構文
unsigned int CWB_ENTRY cwbRC_RunCmd(
cwbRC_SysHandle
const char
cwbSV_ErrHandle
system,
*commandString,
msgHandle);
パラメーター
cwbRC_SysHandle system - input
以前の cwbRC_StartSysEx 関数への呼び出しによって戻されたハンドル。これは IBM i の ID です。
const char *commandString - input
実行するコマンドを含んだストリングを指すポインター。これは ASCIIZ ストリングです。
cwbSV_ErrHandle msgHandle - output
戻された IBM i メッセージは、すべてこのオブジェクトに書き込まれます。このオブジェクトは、
プログラミング
337
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrTextIndexed API
を介して検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索さ
れません。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
CWBRC_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBRC_USR_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBRC_COMMAND_FAILED
コマンドは失敗しました。
CWBRC_COMMAND_TOO_LONG
コマンド・ストリングが長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
リモート・コマンド/分散プログラム呼び出し: プログラム API リストへのアクセス
これらの API を使用して、プログラムおよびそのパラメーターへアクセスします。
cwbRC_AddParm:
cwbRC_AddParm API は、この製品と共に使用します。
338
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
ハンドルで識別されるプログラムにパラメーターを追加します。プログラムに追加されるパラメーターごと
に、この関数を呼び出す必要があります。プログラムが呼び出されるときには、パラメーターは、この関数
を使用して追加した順序に並べられています。
構文
unsigned int CWB_ENTRY cwbRC_AddParm(
cwbRC_PgmHandle
unsigned short
unsigned long
const unsigned char
program,
type,
length,
*parameter);
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
unsigned short type - input
パラメーターのタイプ。定義済みパラメーター・タイプである、 CWBRC_INPUT、
CWBRC_OUTPUT、CWBRC_INOUT のいずれかを使用します。ローカル CCSID とホスト CCSID と
の間で自動的に変換を実行させたい場合は、ビット単位 OR を指定して適切な変換フラグをこのフィ
ールドに追加します。次のいずれかの定義済みパラメーター・タイプを使用してください。
v CWBRC_TEXT_CONVERT
v CWBRC_TEXT_CONVERT_INPUT
v CWBRC_TEXT_CONVERT_OUTPUT
後の 2 つのタイプは、変換が一方向だけに必要な場合に CWBRC_INOUT で使用するよう意図されて
います。
unsigned long length - input
パラメーターの長さ。CWBRC_OUTPUT パラメーターの場合、この長さは、戻されたパラメーターが
書き込まれるバッファーの長さである必要があります。
const unsigned char * parameter - input
次のものが入っているバッファーを指すポインター。タイプが CWBRC_INPUT または
CWBRC_INOUT の場合は値、タイプが CWBRC_OUTPUT または CWBRC_INOUT の場合は戻された
パラメーターが書き込まれる場所。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_INVALID_TYPE
無効なタイプが指定されました。
CWBRC_INVALID_PARM_LENGTH
パラメーターの長さが無効。
プログラミング
339
CWBRC_INVALID_PARM
無効なパラメーター。
使用法
パラメーター・データは 2 進数であると想定されます。変換フラグがいずれか設定されない限り、パラメ
ーター・データの変換は行われません。例えば、以下のとおりです。
cwbRC_AddParm( hPgm,
CWBRC_INOUT | CWBRC_TEXT_CONVERT_OUTPUT,
bufferSize,
buffer );
これによって、ホストに送信される現状のままバッファーが使用され、結果がそのバッファーに入れられる
前に、出力が (例えば、ASCII などに) 変換されます。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_CallPgm:
cwbRC_CallPgm API は、この製品と共に使用します。
目的
ハンドルで識別されるプログラムを呼び出します。戻りコードはプログラムが正常か失敗かを示します。戻
されたメッセージ・ハンドルを使用して、追加のメッセージを戻すことができます。
構文
unsigned int CWB_ENTRY cwbRC_CallPgm(
cwbRC_SysHandle
cwbRC_PgmHandle
cwbSV_ErrHandle
system,
program,
msgHandle);
パラメーター
cwbRC_SysHandle system - input
以前の cwbRC_StartSysEx 関数への呼び出しによって戻されたハンドル。これは IBM i の ID です。
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
cwbSV_ErrHandle msgHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrTextIndexed API
を介して検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索さ
れません。
戻りコード
以下は、共通の戻り値です。
340
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_COMMUNICATIONS_ERROR
通信エラーが発生しました。
CWBRC_INVALID_SYSTEM_HANDLE
システム・ハンドルが無効。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_REJECTED_USER_EXIT
ユーザー出口プログラムによりコマンドが拒否されました。
CWBRC_USER_EXIT_ERROR
ユーザー出口プログラムでエラーが発生しました。
CWBRC_PROGRAM_NOT_FOUND
プログラムが見付かりませんでした。
CWBRC_PROGRAM_ERROR
プログラムの呼び出し時のエラー。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_CreatePgm:
cwbRC_CreatePgm API は、この製品と共に使用します。
目的
この関数は、プログラム名およびライブラリー名が与えられた、プログラム・オブジェクトを作成します。
戻されるハンドルを使って、プログラムにパラメーターを追加し、そのプログラムを呼び出すことができま
す。
構文
unsigned int CWB_ENTRY cwbRC_CreatePgm(
const char
const char
cwbRC_PgmHandle
*programName,
*libraryName,
*program);
パラメーター
const char *programName - input
呼び出すプログラムの名前が含まれている、ASCIIZ ストリングを指すポインター。名前は、二重引用
符で囲む場合を除き大文字です。
プログラミング
341
const char *libraryName - input
プログラムが置かれているライブラリーの名前が含まれている ASCIIZ ストリングを指すポインタ
ー。名前は、二重引用符で囲む場合を除き大文字です。
cwbRC_PgmHandle * program - output
プログラムのハンドルが戻される cwbRC_PgmHandle を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_PROGRAM_NAME
プログラム名が長すぎます。
CWBRC_LIBRARY_NAME
ライブラリー名が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
システムで呼び出すプログラムごとに、IBM i プログラム・オブジェクトを個別に作成する必要がありま
す。このファイルに記述された関数を使用して、プログラムに送られるパラメーターの値を変更することは
できますが、送られるパラメーターの数を変更することはできません。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_DeletePgm:
cwbRC_DeletePgm API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別されるプログラム・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbRC_DeletePgm(
cwbRC_PgmHandle
342
program);
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
使用法
なし
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_GetLibName:
cwbRC_GetLibName API は、この製品と共に使用します。
目的
このプログラム・オブジェクトを作成する際に使用されたライブラリーの名前を取得します。
構文
unsigned int CWB_ENTRY cwbRC_GetLibName(
cwbRC_PgmHandle
char
program,
*libraryName);
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
char * libraryName - output
ライブラリーの名前が書き込まれる先の 10 文字のバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
プログラミング
343
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_GetParm:
cwbRC_GetParm API は、この製品と共に使用します。
目的
指標で識別されるパラメーターを検索します。この指標の範囲は、0 から「パラメーターの合計数 - 1」で
す。この数値は、cwbRC_GetParmCount API を呼び出して入手することができます。
構文
unsigned int CWB_ENTRY cwbRC_GetParm(
cwbRC_PgmHandle
unsigned short
unsigned short
unsigned long
unsigned char
program,
index,
*type,
*length,
**parameter);
パラメーター
cwbRC_PgmHandle handle - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
unsigned short index - input
検索される、このプログラム内の特定のパラメーターの番号。この指標はゼロを基準とします。
unsigned short * type - output
このパラメーターのタイプを指すポインター。この値には、次のいずれかの定義済みパラメーター・タ
イプを指定します。
v CWBRC_INPUT
v CWBRC_OUTPUT
v CWBRC_INOUT
unsigned long * length - input
パラメーターの長さを指すポインター。
344
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned char * * parameter - output
実パラメーターのアドレスが入るバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_INDEX_RANGE_ERROR
指標が範囲外です。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_GetParmCount:
cwbRC_GetParmCount API は、この製品と共に使用します。
目的
このプログラム・オブジェクトについて、パラメーターの数を取得します。
構文
unsigned int CWB_ENTRY cwbRC_GetParmCount(
cwbRC_PgmHandle
unsigned short
program,
*count);
パラメーター
cwbRC_PgmHandle handle - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
unsigned short * count - output
パラメーター・カウントが書き込まれる先の、無符号短精度整数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
345
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_GetPgmName:
cwbRC_GetPgmName API は、この製品と共に使用します。
目的
このプログラムを作成するときに使用されたプログラムの名前を取得します。
構文
unsigned int CWB_ENTRY cwbRC_GetPgmName(
cwbRC_PgmHandle
char
program,
*programName);
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
char * programName - output
プログラムの名前が書き込まれる先の 10 文字のバッファーを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ポインターが、不良または NULL ポインターです。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_API_ERROR
一般 API 障害。
346
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
なし (None)
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_SetLibName:
cwbRC_SetLibName API は、この製品と共に使用します。
目的
このプログラム・オブジェクトについて、ライブラリーの名前を設定します。
構文
unsigned int CWB_ENTRY cwbRC_SetLibName(
cwbRC_PgmHandle
const char
program,
*libraryName);
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
const char *libraryName - input
プログラムが置かれているライブラリーの名前が含まれている ASCIIZ ストリングを指すポインタ
ー。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_LIBRARY_NAME
ライブラリー名が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
プログラミング
347
使用法
この関数は、呼び出す必要のあるプログラムが入っているライブラリーの名前を変更するために使用しま
す。異なるパラメーターで異なるプログラムを呼び出す場合は、この関数を使用しないでください。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_SetParm:
cwbRC_SetParm API は、この製品と共に使用します。
目的
指標で識別されるパラメーター値を設定します。この指標の範囲は、0 から「パラメーターの合計数 - 1」
です。この数値は、cwbRC_GetParmCount API を呼び出して入手することができます。この関数はパラメ
ーターを変更するために使用される点に注意してください。パラメーターを作成する場合は
cwbRC_AddParm を使用してください。
構文
unsigned int CWB_ENTRY cwbRC_SetParm(
cwbRC_PgmHandle
unsigned short
unsigned short
unsigned long
const unsigned char
program,
index,
type,
length,
*parameter);
パラメーター
cwbRC_PgmHandle handle - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
unsigned short index - input
変更する必要のある、このプログラム内の特定のパラメーターの番号。この指標はゼロを基準としま
す。
unsigned short type - input
パラメーターのタイプ。次のいずれかの定義済みパラメーター・タイプを使用します。
v CWBRC_INPUT
v CWBRC_OUTPUT
v CWBRC_INOUT
ローカル CCSID とホスト CCSID との間で自動的に変換を行いたい場合は、ビット単位 OR を指定
して適切な変換フラグをこのフィールドに追加します。次のいずれかの定義済みパラメーター・タイプ
を使用します。
v CWBRC_TEXT_CONVERT
v CWBRC_TEXT_CONVERT_INPUT
v CWBRC_TEXT_CONVERT_OUTPUT
後の 2 つは、変換が一方向にのみ必要な場合に CWBRC_INOUT で使用するよう意図されています。
348
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long length - input
パラメーターの長さ。CWBRC_OUT パラメーターの場合、この長さは、戻されたパラメーターが書き
込まれるバッファーの長さである必要があります。
const unsigned char * parameter - input
タイプが CWBRC_INPUT または CWBRC_INOUT の場合は、該当の値が含まれているバッファーを
指し、タイプが CWBRC_OUTPUT または CWBRC_INOUT の場合は、戻されたパラメーターの書き
込み先である場所を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_INVALID_TYPE
無効なタイプが指定されました。
CWBRC_INVALID_PARM_LENGTH
パラメーターの長さが無効。
CWBRC_INVALID_PARM
無効なパラメーター。
使用法
パラメーター・データは 2 進数であると想定されます。変換フラグがいずれか設定されない限り、パラメ
ーター・データの変換は行われません。例えば、以下のとおりです。
cwbRC_SetParm( hPgm,
CWBRC_INOUT | CWBRC_TEXT_CONVERT_OUTPUT,
bufferSize,
buffer );
これによって、ホストに送信される現状のままバッファーが使用され、結果がそのバッファーに入れられる
前に、出力が (例えば、ASCII に) 変換されます。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
cwbRC_SetPgmName:
cwbRC_SetPgmName API は、この製品と共に使用します。
目的
このプログラム・オブジェクトにプログラムの名前を設定します。
プログラミング
349
構文
unsigned int CWB_ENTRY cwbRC_SetPgmName(
cwbRC_PgmHandle
const char
program,
*programName);
パラメーター
cwbRC_PgmHandle program - input
以前の cwbRC_CreatePgm API の呼び出しによって戻されたハンドル。プログラム・オブジェクトを識
別します。
const char *programName - input
呼び出すプログラムの名前が含まれている、ASCIIZ ストリングを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWBRC_INVALID_PROGRAM
プログラム・ハンドルが無効。
CWBRC_PROGRAM_NAME
プログラム名が長すぎます。
CWB_NOT_ENOUGH_MEMORY
メモリー不足です。一時バッファーの割り振りに失敗した可能性があります。
CWB_NON_REPRESENTABLE_UNICODE_CHAR
入力された 1 つまたは複数のユニコード文字が、使用されているコード・ページで表示されてい
ません。
CWB_API_ERROR
一般 API 障害。
使用法
呼び出したいプログラムの名前を変更する場合は、この関数を使用します。異なるパラメーターで異なるプ
ログラムを呼び出すためにプログラム・オブジェクトを変更する場合は、この関数を使用しないでくださ
い。
関連資料:
332 ページの『リモート・コマンド/分散プログラム呼び出し API の一般的な使用法』
リモート・コマンド/分散プログラム呼び出し機能を使用するアプリケーションは、オブジェクトを利用し
ます。
例: リモート・コマンド/分散プログラム呼び出し API の使用法
リモート・コマンド/分散プログラム呼び出し API の使用法を、この例で説明します。
#ifdef UNICODE
#define _UNICODE
#endif
#include <windows.h>
// Include the necessary RC/DPC Classes
350
IBM i: Windows アプリケーション・パッケージ: プログラミング
#include <stdlib.h>
#include <iostream>
using namespace std;
#include <TCHAR.H>
#include "cwbrc.h"
#include "cwbcosys.h"
/**********************************************************************/
void main()
{
cwbCO_SysHandle system;
cwbRC_SysHandle request;
cwbRC_PgmHandle program;
// Create the system object
if ( (cwbCO_CreateSystem("SystemName",&system)) != CWB_OK )
return;
// Start the system
if ( (cwbRC_StartSysEx(system,&request)) != CWB_OK )
return;
// Call the command to create a library
char* cmd1 = "CRTLIB LIB(RCTESTLIB) TEXT(’RC TEST LIBRARY’)";
if ( (cwbRC_RunCmd(request, cmd1, 0)) != CWB_OK )
return;
cout << "Created Library" << endl;
// Call the command to delete a library
char* cmd2 = "DLTLIB LIB(RCTESTLIB)";
if ( (cwbRC_RunCmd(request, cmd2, 0)) != CWB_OK )
return;
cout << "Deleted Library" << endl;
// Create a program object to create a user space
if ( cwbRC_CreatePgm(_TEXT("QUSCRTUS"),
_TEXT("QSYS"),
&program) != CWB_OK )
return;
// Add the parameters
// name is DPCTESTSPC/QGPL
unsigned char name[20] = {0xC4,0xD7,0xC3,0xE3,0xC5,0xE2,0xE3,0xE2,0xD7,0xC3,
0xD8,0xC7,0xD7,0xD3,0x40,0x40,0x40,0x40,0x40,0x40};
// extended attribute is not needed
unsigned char attr[10] = {0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40};
// initial size is 100 bytes
unsigned long size = 0x64000000;
// initial value is blank
unsigned char init = 0x40;
// public authority is CHANGE
unsigned char auth[10] = {0x5C,0xC3,0xC8,0xC1,0xD5,0xC7,0xC5,0x40,0x40,0x40};
// description is DPC TEMP SPACE
unsigned char desc[50] = {0xC4,0xD7,0xC3,0x40,0xE3,0xC5,0xD4,0xD7,0x40,0xE2,
0xD7,0xC1,0xC3,0xC5,0x40,0x40,0x40,0x40,0x40,0x40,
0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,
0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,
0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40};
if ( cwbRC_AddParm(program, CWBRC_INPUT, 20, name) != CWB_OK)
プログラミング
351
return;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 10, attr) != CWB_OK)
return;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 4, (unsigned char*)&size) != CWB_OK)
return;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 1, &init) != CWB_OK)
return;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 10, auth) != CWB_OK)
return;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 50, desc) != CWB_OK)
return;
// Call the program
if ( cwbRC_CallPgm(request, program, 0) != CWB_OK )
return;
cout << "Created User Space" << endl;
// Delete the program
if ( cwbRC_DeletePgm(program) != CWB_OK )
return;
// Create a program object to delete a user space
if ( cwbRC_CreatePgm(_TEXT("QUSDLTUS"),
_TEXT("QSYS"),
&program) != CWB_OK )
return;
// Add the parameters
// error code structure will not be used
unsigned long err = 0x00000000;
if ( cwbRC_AddParm(program, CWBRC_INPUT, 20, name) != CWB_OK)
return;
if ( cwbRC_AddParm(program, CWBRC_INOUT, 4, (unsigned char*)&err) != CWB_OK)
return;
// Call the program
if ( cwbRC_CallPgm(request, program, 0) != CWB_OK )
return;
// Delete the program
if ( cwbRC_DeletePgm(program) != CWB_OK )
return;
cout << "Deleted User Space" << endl;
// Stop the system
if ( cwbRC_StopSys(request) != CWB_OK )
return;
// Delete the system object
if ( cwbCO_DeleteSystem(system) != CWB_OK )
return;
}
352
IBM i: Windows アプリケーション・パッケージ: プログラミング
保守容易性 API
保守容易性アプリケーション・プログラミング・インターフェース (API) を使用すると、プログラム内の
メッセージおよびイベントを保守ファイルに記録することができます。
作成された保守ファイルからレコードを読み取るために使用できる API のセットも用意されています。こ
れらの API を使用して、カスタマイズされた保守ファイル・ブラウザーを作成することができます。
保守容易性 API 機能の一般的なカテゴリーは、以下のとおりです。
v メッセージ・テキストをヒストリー・ログに書き込むための API
v トレース記入項目をトレース・ファイルに書き込むための API
v 保守ファイルの読み取り
v エラー処理に関連するメッセージ・テキストを取り出すための API
保守容易性 API を使用する理由
保守容易性 API は、効率的な方法を使用して、メッセージ・ロギングおよびトレース・ポイントをユーザ
ーのコードに追加します。これらの関数は、ユーザーのプロダクトの一部として出荷されるプログラムに組
み込むほかに、開発中のプログラムのデバッグを行う助けとして使用することができます。ファイル構造
は、複数プログラム (固有のプロダクトおよび構成要素のストリングによって識別される) による、同じフ
ァイルへの同時ログをサポートします。これにより、クライアント・ワークステーション上のロギング・ア
クティビティーの全体像が得られます。
保守容易性 API に必要なファイル
ヘッダー・ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbsv.h
cwbapi.lib
cwbsv.dll
Programmer's Toolkit:
Programmer's Toolkit には、保守容易性の資料、cwbsv.h ヘッダー・ファイルへのアクセス、およびプログ
ラム例へのリンクが用意されています。この情報にアクセスするには、Programmer's Toolkit をオープンし
て、「エラー処理」 > 「C/C++ API」と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
26 ページの『保守容易性 API の戻りコード』
以下の保守容易性 API の戻りコードがあります。
ヒストリー・ログとトレース・ファイル
ヒストリー・ログとトレース・ファイルを使用して、製品プログラムに関する情報をログに記録することが
できます。
ヒストリー・ログ
ログ機能を使用することにより、製品のヒストリー・ログに、メッセージ・テキストを書き込むことができ
ます。メッセージ・テキストは、表示可能な ASCII 文字データである必要があります。
プログラミング
353
製品プログラムは、製品のヒストリー・ログにメッセージを記録します。メッセージは、プロダクトが提供
する DLL によっても記録されます。
ヒストリー・ログは、cwbSV_LogMessageText API を介してメッセージ・テキスト・ストリングが記録され
るファイルです。このログは、クライアント・ワークステーションで実行されたヒストリーを提供します。
トレース・ファイル
トレース機能によって、ユーザー・プログラムの実行中に起こる低レベルのイベントを記録することができ
ます。例えば、他の関数呼び出しから受け取った種々の戻りコードをトレースすることができます。ユーザ
ー・プログラムがデータを送受信する場合、データの特別に意味のあるフィールド (例えば、関数バイトや
データ長など) を記録して、うまくいかない場合のデバッグに役立てることができます。これを行うには、
詳細データ・トレース関数 (cwbSV_LogTraceData) を使用します。
トレース機能の別の形態であるエントリー・ポイント・トレース関数は、ユーザー・ルーチンへ入る活動、
およびユーザー・ルーチンから出る活動をトレースできるようにします。異なる 2 つのタイプのエントリ
ー・ポイントのトレース・ポイントが定義されます。
API トレース・ポイント
API (アプリケーション・プログラミング・インターフェース) トレース・ポイントは、他のプログ
ラムに対して外部化されたルーチンへ入る活動、またそこから出る活動をトレースするために使用
するものです。
SPI トレース・ポイント
SPI (システム・プログラミング・インターフェース) トレース・ポイントは、トレースしたいユー
ザー・プログラムの重要な内部ルーチンへの、またそこからの、入りと出をトレースするために使
用するものです。
API 上に用意されている、1 バイトの eventID というキー情報があります。これによって、どの API また
は SPI への出入りが行われているかを識別することができます。入力値のようなデータは、入るときにト
レースすることができます。これは、出力値がルーチンから出るときにトレースされるのと同様です。これ
らのトレース関数は、これらを利用するルーチンにおいて、ペアで (例えば、cwbSV_LogAPIEntry と
cwbSV_LogAPIExit のペアで) 使用するよう意図されています。これらのタイプのトレース・ポイントによ
り、コードを使用して制御のフローを記録できるようにします。
このトピックで述べる各プロシージャー型 API はエントリー/エグジット API トレース・ポイントを備え
ています。トレース機能が活動中の場合、これらのうちのいずれかのプロシージャーの API が呼び出され
ると、入り口および出口のトレース・ポイントはエントリー・ポイント・トレース・ファイルに記録されま
す。エントリー/エグジット SPI トレースには、内部呼び出しの順序が記録されます。詳細データのトレー
ス機能を使用すると、問題のデバッグにおいて役立つデータを記録することができます。
次のタイプのトレースがサポートされます。
詳細 (データ)
このタイプを使用すると、cwbSV_LogTraceData API を介し、コード内のある 1 つのポイントで情
報のバッファーをトレースすることが可能になります。このバッファーは、ASCII 値または 2 進
値、あるいはその両方の混合を使用することが可能ですが (例えば、C-struct)、データは 2 進数形
式で記録されます。
エントリー/エグジット (API)
特殊化された形式のトレースで、これを使用すると、cwbSV_LogAPIEntry と cwbSV_LogAPIExit
API を介し、外部化されたルーチンに対する出入りをトレースすることが可能になります。
354
IBM i: Windows アプリケーション・パッケージ: プログラミング
エントリー/エグジット (SPI):
特殊化された形式のトレースで、これを使用すると、cwbSV_LogSPIEntry と cwbSV_LogSPIExit
API を介し、外部化されたルーチンに対する出入りをトレースすることが可能になります。
エラー・ハンドル
プロダクト・エラー処理関数を使用すると、この関数をサポートする製品 API で使用するエラー・ハンド
ル (cwbSV_CreateErrHandle) を作成することができます。
API 呼び出し時にエラー (ゼロ以外の戻りコード) が起こった場合は、他のエラー処理関数を呼び出して、
以下の情報を検索することができます。
v 戻りコードに関連するエラー・メッセージの数 (cwbSV_GetErrCount)
v 各エラー・メッセージのメッセージ・テキスト (cwbSV_GetErrTextIndexed)
保守容易性 API の一般的な使用法
保守容易性 API の一般的な使用法には、ヒストリー・ログやエラー・ハンドルなどがあります。
ヒストリー・ログ
保守容易性 API は、クライアント・ワークステーションで実行されるアクティビティーに関するトレー
ス・メカニズムを提供しています。メッセージ・ロギング API を使用することで、製品のヒストリー・ロ
グにメッセージを記録することができます。ログ・メッセージには、アプリケーションが開始したことやそ
の他の重要なイベントを示す記録が含まれています。例えば、ログ・メッセージは、ファイルが正常にシス
テムへ転送されたこと、何らかの理由でデータベース照会が失敗したこと、または、ジョブが印刷のため投
入されたことなどを示すことができます。
保守容易性 API を使用する際に提供されるプロダクト・ストリングと構成要素ストリングによって、メッ
セージとイベントを保守ファイル内の他の項目と区別することができます。階層については、あるプロダク
ト ID を定義して、その下に 1 つまたは複数の構成要素 ID を定義することをお勧めします。
エラー・ハンドル
C/C++ API のエラー・ハンドル・パラメーターを使用して、障害戻りコードに関連するメッセージ・テキ
ストを検索します。これにより、アプリケーションでは、Access 戻りコードのセット用に独自のテキスト
を用意しなくても、メッセージ・テキストを表示することができます。
保守容易性 API のリスト: ヒストリー・ログへの書き込み
これらの API を使用して、メッセージ・テキストをヒストリー・ログに書き込みます。
cwbSV_CreateMessageTextHandle:
cwbSV_CreateMessageTextHandle API は、この製品と共に使用します。
目的
この関数はメッセージ・テキスト・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。こ
のメッセージ・ハンドルをユーザー・プログラムで使用すると、メッセージ・テキストを現在活動状態のヒ
ストリー・ログに書き込むことができます。メッセージ・テキストは、cwbSV_LogMessageText() 呼び出し
で渡されたバッファーに与えられます。
プログラミング
355
構文
unsigned int CWB_ENTRY cwbSV_CreateMessageTextHandle(
char
*productID,
char
*componentID,
cwbSV_MessageTextHandle *messageTextHandle);
パラメーター
char * productID - input
このメッセージ記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリン
グを指します。このパラメーターはオプションで、NULL の場合は productID は設定されません。注:
プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されます。これより長いス
トリングは切り捨てられます。
char * componentID - input
このメッセージ記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリング
を指します。このパラメーターはオプションで、NULL の場合は componentID は設定されません。注:
構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これより長いストリ
ングは切り捨てられます。
cwbSV_MessageTextHandle * messageTextHandle - input/output
ハンドルが戻される先の cwbSV_MessageTextHandle を指すポインター。このハンドルは、これ以降の
メッセージ・テキスト関数呼び出しで使用する必要があります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
メッセージ・ハンドルを使用してメッセージ・テキストを記録する前に、そのメッセージ・ハンドルに固有
のプロダクト ID と構成要素 ID を設定することをお勧めします。これらの ID によって、ユーザー・メ
ッセージはヒストリー・ログの他のメッセージと区別されます。
cwbSV_DeleteMessageTextHandle:
cwbSV_DeleteMessageTextHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別されるメッセージ・テキスト・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteMessageTextHandle(
cwbSV_MessageTextHandle messageTextHandle);
356
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbSV_MessageTextHandle messageTextHandle - input
以前の cwbSV_CreateMessageTextHandle() 関数の呼び出しによって戻されたハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
要求時に、使用できないハンドルが渡されました。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_LogMessageText:
cwbSV_LogMessageText API は、この製品と共に使用します。
目的
この関数は、与えられたメッセージ・テキストを現在活動状態のヒストリー・ログへ記録します。記入項目
に設定されたプロダクト ID と構成要素 ID は、テキストが記録された日時と共に書き込まれます。
構文
unsigned int CWB_ENTRY cwbSV_LogMessageText(
cwbSV_MessageTextHandle messageTextHandle,
char
*messageText,
unsigned long
messageTextLength);
パラメーター
cwbSV_MessageTextHandle messageTextHandle - input
以前の cwbSV_CreateMessageTextHandle() の呼び出しによって戻されたハンドル。
char * messageText - input
記録したいメッセージ・テキストが含まれているバッファーを指します。
unsigned long messageTextLength - input
このメッセージ記入項目について記録するメッセージ・テキスト・バッファーのバイト数を指定しま
す。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
要求時に、使用できないハンドルが渡されました。
プログラミング
357
使用法
なし (None)
cwbSV_SetMessageClass:
cwbSV_SetMessageClass API は、この製品と共に使用します。
目的
この関数を使用すれば、ヒストリー・ログに書き込まれるメッセージに関連付けるメッセージ・クラス (重
大度) の設定が可能になります。
構文
unsigned int CWB_ENTRY cwbSV_SetMessageClass(
cwbSV_MessageTextHandle
cwbSV_MessageClass
messageTextHandle,
messageClass);
パラメーター
cwbSV_MessageTextHandle messageTextHandle - input
以前の cwbSV_CreateMessageTextHandle() の呼び出しによって戻されたハンドル。
cwbSV_MessageClass messageClass - input
次のいずれかを指定します。
v CWBSV_CLASS_INFORMATIONAL
v CWBSV_CLASS_WARNING
v CWBSV_CLASS_ERROR
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
要求時に、使用できないハンドルが渡されました。
CWBSV_INVALID_MSG_CLASS
無効なメッセージ・クラスが渡されました。
使用法
この値は、対応するログ関数 cwbSV_LogMessageText() を呼び出す前に設定してください。
cwbSV_SetMessageComponent:
cwbSV_SetMessageComponent API は、この製品と共に使用します。
目的
この関数によって、与えられたメッセージ・ハンドルに、固有な構成要素 ID を設定できます。ユーザー
のメッセージ記入項目をヒストリー・ログ中の他のプロダクト記入項目と区別するためにも、プロダクト
ID の設定 (cwbSV_SetMessageProduct を参照) と共にこの呼び出しを使用してください。
358
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbSV_SetMessageComponent(
cwbSV_MessageTextHandle messageTextHandle,
char
*componentID);
パラメーター
cwbSV_MessageTextHandle messageTextHandle - input
以前の cwbSV_CreateMessageTextHandle() の呼び出しによって戻されたハンドル。
char * componentID - input
このメッセージ記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリング
を指します。注: 構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これ
より長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
要求時に、使用できないハンドルが渡されました。
使用法
この値は、対応するログ関数 cwbSV_LogMessageData() を呼び出す前に設定してください。階層には、あ
るプロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義することをお勧めします。
cwbSV_SetMessageProduct:
cwbSV_SetMessageProduct API は、この製品と共に使用します。
目的
この関数によって、与えられたメッセージ・ハンドルに、固有なプロダクト ID を設定できます。ユーザ
ーのメッセージ記入項目をヒストリー・ログ中の他のプロダクト記入項目と区別するためにも、構成要素
ID の設定 (cwbSV_SetMessageComponent を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetMessageProduct(
cwbSV_MessageTextHandle messageTextHandle,
char
*productID);
パラメーター
cwbSV_MessageTextHandle messageTextHandle - input
以前の cwbSV_CreateMessageTextHandle() の呼び出しによって戻されたハンドル。
char * productID - input
このメッセージ記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリン
グを指します。注: プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されま
す。これより長いストリングは切り捨てられます。
プログラミング
359
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
要求時に、使用できないハンドルが渡されました。
使用法
この値は、対応するログ関数 cwbSV_LogMessageData() を呼び出す前に設定してください。階層には、あ
るプロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義することをお勧めします。
保守容易性 API のリスト: トレース・データの書き込み
これらの API を使用して、トレース・データを詳細トレース・ファイルに書き込みます。
cwbSV_CreateTraceDataHandle:
cwbSV_CreateTraceDataHandle API は、この製品と共に使用します。
目的
この関数はトレース・データ・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。このト
レース・ハンドルをユーザー・プログラムで使用すると、トレース情報をトレース・ファイルに記録するこ
とができます。トレース情報は、cwbSV_LogTraceData() 呼び出しで渡されるバッファーに与えられます。
構文
unsigned int CWB_ENTRY cwbSV_CreateTraceDataHandle(
char
*productID,
char
*componentID,
cwbSV_TraceDataHandle *traceDataHandle);
パラメーター
char * productID - input
このメッセージ記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリン
グを指します。このパラメーターはオプションで、NULL の場合は productID は設定されません。注:
プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されます。これより長いス
トリングは切り捨てられます。
char * componentID - input
このメッセージ記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリング
を指します。このパラメーターはオプションで、NULL の場合は componentID は設定されません。注:
構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これより長いストリ
ングは切り捨てられます。
cwbSV_TraceDataHandle * traceDataHandle - input/output
ハンドルが戻される先の cwbSV_TraceDataHandle を指すポインター。このハンドルは、これ以降のト
レース・データ関数呼び出しで使用する必要があります。
360
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
トレース・データ・ハンドルを使用してトレース記入項目を記録する前に、そのトレース・データ・ハンド
ルに固有のプロダクト ID と構成要素 ID を設定することをお勧めします。これらの ID によって、ユー
ザーのトレース記入項目はトレース・ファイルの他の記入項目と区別されます。
cwbSV_DeleteTraceDataHandle:
cwbSV_DeleteTraceDataHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別されるトレース・データ・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteTraceDataHandle(
cwbSV_TraceDataHandle traceDataHandle);
パラメーター
cwbSV_TraceDataHandle traceDataHandle - input
以前の cwbSV_CreateTraceDataHandle() 関数の呼び出しによって戻されたハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_LogTraceData:
cwbSV_LogTraceData API は、この製品と共に使用します。
プログラミング
361
目的
この関数は、与えられたトレース・データを現在活動状態のトレース・ファイルへ記録します。記入項目に
設定されたプロダクト ID と構成要素 ID は、データが記録された日時と共に書き込まれます。
構文
unsigned int CWB_ENTRY cwbSV_LogTraceData(
cwbSV_TraceDataHandle traceDataHandle,
char
*traceData,
unsigned long
traceDataLength);
パラメーター
cwbSV_TraceDataHandle traceDataHandle - input
以前の cwbSV_CreateTraceDataHandle() の呼び出しによって戻されたハンドル。
char * traceData - input
記録したいトレース・データが含まれているバッファーを指します。トレース量の決定には長さパラメ
ーターが使用されるため、バッファーには 2 進データを入れることができます。
unsigned long traceDataLength - input
このトレース記入項目について記録するトレース・データ・バッファーのバイト数を指定します。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbSV_SetTraceComponent:
cwbSV_SetTraceComponent API は、この製品と共に使用します。
目的
この関数によって、与えられた保守記入項目に、固有な構成要素 ID を設定できます。ユーザーのトレー
ス記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するためにも、プロダクト ID の設
定 (cwbSV_SetTraceProduct を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetTraceComponent(
cwbSV_TraceDataHandle traceDataHandle,
char
*componentID);
362
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbSV_TraceDataHandle traceDataHandle - input
以前の cwbSV_CreateTraceDataHandle() の呼び出しによって戻されたハンドル。
char * componentID - input
このトレース記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリングを
指します。注: 構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これよ
り長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この値は、対応するログ関数 cwbSV_LogTraceData() を呼び出す前に設定してください。階層には、あるプ
ロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義することをお勧めします。
cwbSV_SetTraceProduct:
cwbSV_SetTraceProduct API は、この製品と共に使用します。
目的
この関数によって、与えられたトレース・ハンドルに、固有なプロダクト ID を設定できます。ユーザー
のトレース記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するためにも、構成要素 ID
の設定 (cwbSV_SetTraceComponent を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetTraceProduct(
cwbSV_TraceDataHandle traceDataHandle,
char
*productID);
パラメーター
cwbSV_TraceDataHandle traceDataHandle - input
以前の cwbSV_CreateTraceDataHandle() の呼び出しによって戻されたハンドル。
char * productID - input
このトレース記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリング
を指します。注: プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されま
す。これより長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
プログラミング
363
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この値は、対応するログ関数 cwbSV_LogTraceData() を呼び出す前に設定してください。階層には、あるプ
ロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義することをお勧めします。
保守容易性 API のリスト: トレース・ポイントの書き込み
これらの API を使用して、トレース・ポイントをエントリー/エグジット・トレース・ファイルに書き込み
ます。
cwbSV_CreateTraceAPIHandle:
cwbSV_CreateTraceAPIHandle API は、この製品と共に使用します。
目的
この関数は API トレース・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。この API
トレース・ハンドルをユーザー・プログラムで使用すると、ユーザーの API エントリー・ポイントにおけ
る出入りを記録することができます。
構文
unsigned int CWB_ENTRY cwbSV_CreateTraceAPIHandle(
char
*productID,
char
*componentID,
cwbSV_TraceAPIHandle *traceAPIHandle);
パラメーター
char * productID - input
このメッセージ記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリン
グを指します。このパラメーターはオプションで、NULL の場合は productID は設定されません。注:
プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されます。これより長いス
トリングは切り捨てられます。
char * componentID - input
このメッセージ記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリング
を指します。このパラメーターはオプションで、NULL の場合は componentID は設定されません。注:
構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これより長いストリ
ングは切り捨てられます。
cwbSV_TraceAPIHandle * traceAPIHandle - input/output
ハンドルが戻される先の cwbSV_TraceAPIHandle を指すポインター。このハンドルは、これ以降の
API トレース関数呼び出しで使用する必要があります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
364
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
トレース・データ・ハンドルを使用してトレース記入項目を記録する前に、そのトレース・データ・ハンド
ルに固有のプロダクト ID と構成要素 ID を設定することをお勧めします。これらの ID によって、ユー
ザーのトレース記入項目はトレース・ファイルの他の記入項目と区別されます。
cwbSV_CreateTraceSPIHandle:
cwbSV_CreateTraceSPIHandle API は、この製品と共に使用します。
目的
この関数は SPI トレース・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。この SPI
トレース・ハンドルをユーザー・プログラムの中で使用すると、ユーザーの SPI エントリー・ポイントの
出入りを記録することができます。
構文
unsigned int CWB_ENTRY cwbSV_CreateTraceSPIHandle(
char
*productID,
char
*componentID,
cwbSV_TraceSPIHandle *traceSPIHandle);
パラメーター
char * productID - input
このメッセージ記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリン
グを指します。このパラメーターはオプションで、NULL の場合は productID は設定されません。注:
プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されます。これより長いス
トリングは切り捨てられます。
char * componentID - input
このメッセージ記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリング
を指します。このパラメーターはオプションで、NULL の場合は componentID は設定されません。注:
構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これより長いストリ
ングは切り捨てられます。
cwbSV_TraceSPIHandle * traceSPIHandle - input/output
ハンドルが戻される先の cwbSV_TraceSPIHandle を指すポインター。このハンドルは、これ以降の SPI
トレース関数呼び出しで使用する必要があります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
プログラミング
365
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
トレース・データ・ハンドルを使用してトレース記入項目を記録する前に、そのトレース・データ・ハンド
ルに固有のプロダクト ID と構成要素 ID を設定することをお勧めします。これらの ID によって、ユー
ザーのトレース記入項目はトレース・ファイルの他の記入項目と区別されます。
cwbSV_DeleteTraceAPIHandle:
cwbSV_DeleteTraceAPIHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別される API トレース・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteTraceAPIHandle(
cwbSV_TraceAPIHandle traceAPIHandle);
パラメーター
cwbSV_TraceAPIHandle traceAPIHandle - input
以前の cwbSV_CreateTraceAPIHandle() 関数の呼び出しによって戻されたハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_DeleteTraceSPIHandle:
cwbSV_DeleteTraceSPIHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別される SPI トレース・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteTraceSPIHandle(
cwbSV_TraceSPIHandle traceSPIHandle);
366
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbSV_TraceSPIHandle traceSPIHandle - input
以前の cwbSV_CreateTraceSPIHandle() 関数の呼び出しによって戻されたハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_LogAPIEntry:
cwbSV_LogAPIEntry API は、この製品と共に使用します。
目的
この関数は、API エントリー・ポイントを現在活動状態のエントリー/エグジット・トレース・ファイルへ
記録します。記入項目に設定されたプロダクト ID と構成要素 ID は、データが記録された日時と共に書
き込まれます。要求時に渡されるすべてのオプションのデータと共に、apiID も記録されます。
構文
unsigned int CWB_ENTRY cwbSV_LogAPIEntry(
cwbSV_TraceAPIHandle traceAPIHandle,
unsigned char
apiID,
char
*apiData,
unsigned long
apiDataLength);
パラメーター
cwbSV_TraceAPIHandle traceAPIHandle - input
以前の cwbSV_CreateTraceAPIHandle() の呼び出しによって戻されたハンドル。
unsigned char apiID - input
この API トレース・ポイントを、ユーザー・プログラムで記録された他の API トレース・ポイント
と区別する固有の 1 バイト・コード。これらのコードの定義は、この API の呼び出し側に任されま
す。プロダクトの固有な構成要素ごとに、定義された範囲 (0x00 から 0xFF) を使用するというアプロ
ーチをお勧めします (例えば、構成要素ごとに 0x00 から開始する)。
char * apiData - input
このエントリー・ポイントとともに記録する追加のデータ (例えば、呼び出し側からの入力パラメータ
ー値) が入っているバッファーを指します。このパラメーターはオプションで、アドレスが NULL ま
たはデータ長がゼロの場合は無視されます。トレース量の決定には長さパラメーターが使用されるた
め、このバッファーには 2 進データを入れることができます。
unsigned long apiDataLength - input
このトレースの記入項目について記録する API データ・バッファーのバイト数を指定します。
プログラミング
367
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、対応する cwbSV_LogAPIExit() と共に使用する必要のあるものです。これらの呼び出し
は、ユーザーがコーディングした API ルーチンの始めと終わりに入れることをお勧めします。他の方法と
しては、他のユーザーがコーディングした外部ルーチン呼び出しの際に、これらのログ関数を使用するとい
う方法が考えられます。
cwbSV_LogAPIExit:
cwbSV_LogAPIExit API は、この製品と共に使用します。
目的
この関数は、API エグジット・ポイントを現在活動状態のエントリー/エグジット・トレース・ファイルへ
記録します。記入項目に設定されたプロダクト ID と構成要素 ID は、データが記録された日時と共に書
き込まれます。要求時に渡されるすべてのオプションのデータと共に、API ID も記録されます。
構文
unsigned int CWB_ENTRY cwbSV_LogAPIExit(
cwbSV_TraceAPIHandle traceAPIHandle,
unsigned char
apiID,
char
*apiData,
unsigned long
apiDataLength);
パラメーター
cwbSV_TraceAPIHandle traceAPIHandle - input
以前の cwbSV_CreateTraceAPIHandle() の呼び出しによって戻されたハンドル。
unsigned char apiID - input
この API トレース・ポイントを、ユーザー・プログラムで記録された他の API トレース・ポイント
と区別する固有の 1 バイト・コード。これらのコードの定義は、この API の呼び出し側に任されま
す。プロダクトの固有な構成要素ごとに、定義された範囲 (0x00 から 0xFF) を使用するというアプロ
ーチをお勧めします (例えば、構成要素ごとに 0x00 から開始する)。
char * apiData - input
このエグジット・ポイントとともに記録する追加のデータ (例えば、呼び出し側に返される出力パラメ
ーター値) が入っているバッファーを指します。このパラメーターはオプションで、アドレスが NULL
またはデータ長がゼロの場合は無視されます。トレース量の決定には長さパラメーターが使用されるた
め、このバッファーには 2 進データを入れることができます。
unsigned long apiDataLength - input
このトレースの記入項目について記録する API データ・バッファーのバイト数を指定します。
368
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、対応する cwbSV_LogAPIEntry() と共に使用する必要のあるものです。これらの呼び出し
は、ユーザーがコーディングした API ルーチンの始めと終わりに入れることをお勧めします。他の方法と
しては、他のユーザーがコーディングした外部ルーチン呼び出しの際に、これらのログ関数を使用するとい
う方法が考えられます。
cwbSV_LogSPIEntry:
cwbSV_LogSPIEntry API は、この製品と共に使用します。
目的
この関数は、SPI エントリー・ポイントを現在活動状態のエントリー/エグジット・トレース・ファイルへ
記録します。記入項目に設定されたプロダクト ID と構成要素 ID は、データが記録された日時と共に書
き込まれます。要求時に渡されるすべてのオプションのデータと共に、spiID も記録されます。
構文
unsigned int CWB_ENTRY cwbSV_LogSPIEntry(
cwbSV_TraceSPIHandle traceSPIHandle,
unsigned char
spiID,
char
*spiData,
unsigned long
spiDataLength);
パラメーター
cwbSV_TraceSPIHandle traceSPIHandle - input
以前の cwbSV_CreateTraceSPIHandle() の呼び出しによって戻されたハンドル。
unsigned char spiID - input
この SPI トレース・ポイントを、ユーザー・プログラムで記録された他の SPI トレース・ポイントと
区別する固有の 1 バイト・コード。これらのコードの定義は、この API の呼び出し側に任されます。
プロダクトの固有な構成要素ごとに、定義された範囲 (0x00 から 0xFF) を使用するというアプローチ
をお勧めします (例えば、構成要素ごとに 0x00 から開始する)。
char * spiData - input
このエントリー・ポイントとともに記録する追加のデータ (例えば、呼び出し側からの入力パラメータ
ー値) が入っているバッファーを指します。このパラメーターはオプションで、アドレスが NULL ま
たはデータ長がゼロの場合は無視されます。トレース量の決定には長さパラメーターが使用されるた
め、このバッファーには 2 進データを入れることができます。
unsigned long spiDataLength - input
このトレース記入項目について記録する SPI データ・バッファーのバイト数を指定します。
プログラミング
369
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、対応する cwbSV_LogSPIExit() とともに使用する必要のあるものです。これらの呼び出し
は、ユーザーがコーディングした API ルーチンの始めと終わりに入れることをお勧めします。他の方法と
しては、他のユーザーがコーディングした外部ルーチン呼び出しの際に、これらのログ関数を使用するとい
う方法が考えられます。
cwbSV_LogSPIExit:
cwbSV_LogSPIExit API は、この製品と共に使用します。
目的
この関数は、SPI エグジット・ポイントを現在活動状態のエントリー/エグジット・トレース・ファイルへ
記録します。記入項目に設定されたプロダクト ID と構成要素 ID は、データが記録された日時と共に書
き込まれます。要求時に渡されるすべてのオプションのデータと共に、spiID も記録されます。
構文
unsigned int CWB_ENTRY cwbSV_LogSPIExit(
cwbSV_TraceSPIHandle traceSPIHandle,
unsigned char
spiID,
char
*spiData,
unsigned long
spiDataLength);
パラメーター
cwbSV_TraceSPIHandle traceSPIHandle - input
以前の cwbSV_CreateTraceSPIHandle() の呼び出しによって戻されたハンドル。
unsigned char spiID - input
この SPI トレース・ポイントを、ユーザー・プログラムで記録された他の SPI トレース・ポイントと
区別する固有の 1 バイト・コード。これらのコードの定義は、この API の呼び出し側に任されます。
プロダクトの固有な構成要素ごとに、定義された範囲 (0x00 から 0xFF) を使用するというアプローチ
をお勧めします (例えば、構成要素ごとに 0x00 から開始する)。
char * spiData - input
このエグジット・ポイントとともに記録する追加のデータ (例えば、呼び出し側に返される出力パラメ
ーター値) が入っているバッファーを指します。このパラメーターはオプションで、アドレスが NULL
またはデータ長がゼロの場合は無視されます。トレース量の決定には長さパラメーターが使用されるた
め、このバッファーには 2 進データを入れることができます。
unsigned long spiDataLength - input
このトレース記入項目について記録する SPI データ・バッファーのバイト数を指定します。
370
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、対応する cwbSV_LogSPIEntry() と共に使用する必要のあるものです。これらの呼び出し
は、ユーザーがコーディングした API ルーチンの始めと終わりに入れることをお勧めします。他の方法と
しては、他のユーザーがコーディングした外部ルーチン呼び出しの際に、これらのログ関数を使用するとい
う方法が考えられます。
cwbSV_SetAPIComponent:
cwbSV_SetAPIComponent API は、この製品と共に使用します。
目的
この関数によって、与えられたトレース記入項目に、固有な構成要素 ID を設定できます。ユーザーのト
レース記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するためにも、プロダクト ID
の設定 (cwbSV_SetAPIProduct を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetAPIComponent(
cwbSV_TraceAPIHandle traceAPIHandle,
char
*componentID);
パラメーター
cwbSV_TraceAPIHandle traceAPIHandle - input
以前の cwbSV_CreateTraceAPIHandle() の呼び出しによって戻されたハンドル。
char * componentID - input
このトレース記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリングを
指します。注: 構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これよ
り長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
プログラミング
371
使用法
この値は、対応するログ関数 cwbSV_LogAPIEntry() および cwbSV_LogAPIExit() を呼び出す前に設定して
ください。プロダクト ID を定義して、その下に単一または複数の機能を定義する、という階層にするこ
とをお勧めします。
cwbSV_SetAPIProduct:
cwbSV_SetAPIProduct API は、この製品と共に使用します。
目的
この関数によって、与えられたトレース・ハンドルに、固有なプロダクト ID を設定できます。ユーザー
のトレース記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するため、この呼び出しを構
成要素 ID の設定 (cwbSV_SetAPIComponent を参照) と共に使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetAPIProduct(
cwbSV_TraceAPIHandle traceAPIHandle,
char
*productID);
パラメーター
cwbSV_TraceAPIHandle traceAPIHandle - input
以前の cwbSV_CreateTraceAPIHandle() の呼び出しによって戻されたハンドル。
char * productID - input
このトレース記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリング
を指します。注: プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されま
す。これより長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この値は、対応するログ関数 cwbSV_LogAPIEntry() および cwbSV_LogAPIExit() を呼び出す前に設定して
ください。階層には、あるプロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義すること
をお勧めします。
cwbSV_SetSPIComponent:
cwbSV_SetSPIComponent API は、この製品と共に使用します。
目的
この関数によって、与えられたトレース記入項目に、固有な構成要素 ID を設定できます。ユーザーのト
レース記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するためにも、プロダクト ID
372
IBM i: Windows アプリケーション・パッケージ: プログラミング
の設定 (cwbSV_SetSPIProduct を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetSPIComponent(
cwbSV_TraceSPIHandle traceSPIHandle,
char
*componentID);
パラメーター
cwbSV_TraceSPIHandle traceSPIHandle - input
以前の cwbSV_CreateTraceSPIHandle() の呼び出しによって戻されたハンドル。
char * componentID - input
このトレース記入項目で使用される構成要素 ID が含まれている、NULL 文字で終わるストリングを
指します。注: 構成要素 ID について、最大で CWBSV_MAX_COMP_ID 文字が記録されます。これよ
り長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この値は、対応するログ関数 cwbSV_LogAPIEntry() および cwbSV_LogAPIExit() を呼び出す前に設定して
ください。階層には、あるプロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義すること
をお勧めします。
cwbSV_SetSPIProduct:
cwbSV_SetSPIProduct API は、この製品と共に使用します。
目的
この関数によって、与えられたトレース・ハンドルに、固有なプロダクト ID を設定できます。ユーザー
のトレース記入項目をトレース・ファイル中の他のプロダクト記入項目と区別するためにも、構成要素 ID
の設定 (cwbSV_SetSPIComponent を参照) と共にこの呼び出しを使用してください。
構文
unsigned int CWB_ENTRY cwbSV_SetSPIProduct(
cwbSV_TraceSPIHandle traceSPIHandle,
char
*productID);
パラメーター
cwbSV_TraceSPIHandle traceSPIHandle - input
以前の cwbSV_CreateTraceSPIHandle() の呼び出しによって戻されたハンドル。
プログラミング
373
char * productID - input
このトレース記入項目で使用されるプロダクト ID が含まれている、NULL 文字で終わるストリング
を指します。注: プロダクト ID について、最大で CWBSV_MAX_PRODUCT_ID 文字が記録されま
す。これより長いストリングは切り捨てられます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この値は、対応するログ関数 cwbSV_LogAPIEntry() および cwbSV_LogAPIExit() を呼び出す前に設定して
ください。階層には、あるプロダクト ID を定義し、その下に 1 つまたは複数の構成要素を定義すること
をお勧めします。
保守容易性 API のリスト: サービス・ファイルの読み取り
これらの API を使用して、サービス・ファイル、サービス・ファイル・レコード、およびサービス・ファ
イルのヘッダー情報を読み取ります。さらに、ヒストリー・ログ・サービス・レコード、詳細トレース・
ファイル・サービス・レコード、およびエントリー/エグジット・トレース・ファイル・サービス・レコー
ドを読み取ることができます。
cwbSV_ClearServiceFile:
cwbSV_ClearServiceFile API は、この製品と共に使用します。
目的
与えられたハンドルで識別される保守ファイルを削除します。
構文
unsigned int CWB_ENTRY cwbSV_ClearServiceFile(
cwbSV_ServiceFileHandle serviceFile,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile() 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
374
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_FILE_IO_ERROR
ファイルはクローズできませんでした。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbSV_CloseServiceFile:
cwbSV_CloseServiceFile API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守ファイルをクローズします。
構文
unsigned int CWB_ENTRY cwbSV_CloseServiceFile(
cwbSV_ServiceFileHandle serviceFile,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile() 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_FILE_IO_ERROR
ファイルは消去できませんでした。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
プログラミング
375
cwbSV_CreateServiceRecHandle:
cwbSV_CreateServiceRecHandle API は、この製品と共に使用します。
目的
この関数は保守レコード・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。
構文
unsigned int CWB_ENTRY cwbSV_CreateServiceRecHandle(
cwbSV_ServiceRecHandle *serviceRecHandle);
パラメーター
cwbSV_ServiceRecHandle * serviceRecHandle - input/output
ハンドルが戻される先の cwbSV_ServiceRecordHandle を指すポインター。このハンドルは、これ以降
の保守レコード関数呼び出しで使用する必要があります。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ハンドル・アドレスとして NULL が渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
このハンドルをユーザー・プログラムで使用すると、オープンされた保守ファイルからレコードを読み取っ
てそのレコードから情報を取り出すことができます。
cwbSV_DeleteServiceRecHandle:
cwbSV_DeleteServiceRecHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別される保守レコード・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteServiceRecHandle(
cwbSV_ServiceRecHandle serviceRecHandle);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
376
IBM i: Windows アプリケーション・パッケージ: プログラミング
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_GetComponent:
cwbSV_GetComponent API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトの構成要素 ID を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetComponent(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*componentID,
unsigned long
componentIDLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * componentID - input/output
ハンドルによって識別されるレコードに保管された、構成要素 ID を受け取るバッファーを指すポイン
ター。
unsigned long componentIDLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。注: 推奨サイズは CWBSV_MAX_COMP_ID です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
プログラミング
377
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
このルーチンを呼び出す前に、読み取り関数呼び出しによって保守レコード・ハンドルを取得する必要があ
ります。これを実行しないと、NULL ストリングが戻されます。この関数は、すべての保守レコード・タ
イプで有効です。
cwbSV_GetDateStamp:
cwbSV_GetDateStamp API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコードの (地域化された形式の) 日付スタンプを戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetDateStamp(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*dateStamp,
unsigned long
dateStampLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * dateStamp - input/output
ハンドルによって識別されるレコードに保管された、日付スタンプを受け取るバッファーを指すポイン
ター。
unsigned long dateStampLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。注: 推奨サイズは CWBSV_MAX_DATE_VALUE です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
378
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
このルーチンを呼び出す前に、読み取り関数呼び出しによって保守レコード・ハンドルを取得する必要があ
ります。これを実行しないと、NULL ストリングが戻されます。この関数は、すべての保守レコード・タ
イプで有効です。
cwbSV_GetMaxRecordSize:
cwbSV_GetMaxRecordSize API は、この製品と共に使用します。
目的
与えられたファイル・ハンドルによって識別される保守ファイルの中の最大レコードのサイズ (バイト数)
を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetMaxRecordSize(
cwbSV_ServiceFileHandle serviceFile,
unsigned long
*maxRecordSize);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
unsigned long * recordCount - input/output
ファイルの中の最大レコード・サイズを受け取る変数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbSV_GetMessageText:
cwbSV_GetMessageText API は、この製品と共に使用します。
プログラミング
379
目的
与えられたハンドルによって識別される保守レコード・オブジェクトのメッセージ・テキスト部分を戻しま
す。
構文
unsigned int CWB_ENTRY cwbSV_GetMessageText(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*messageText,
unsigned long
messageTextLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * messageText - input/output
ハンドルによって識別されるレコードに保管された、メッセージ・テキストを受け取るバッファーを指
すポインター。
unsigned long messageTextLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられて
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_MESSAGE_REC ではありません。
使用法
レコード・タイプが CWBSV_MESSAGE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetProduct:
cwbSV_GetProduct API は、この製品と共に使用します。
380
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
与えられたハンドルによって識別される保守レコード・オブジェクトのプロダクト ID 値を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetProduct(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*productID,
unsigned long
productIDLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * productID - input/output
ハンドルによって識別されるレコードに保管された、プロダクト ID を受け取るバッファーを指すポイ
ンター。
unsigned long productIDLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。注: 推奨サイズは CWBSV_MAX_PRODUCT_ID です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
このルーチンを呼び出す前に、読み取り関数呼び出しによって保守レコード・ハンドルを取得する必要があ
ります。これを実行しないと、NULL ストリングが戻されます。この関数は、すべての保守レコード・タ
イプで有効です。
cwbSV_GetRecordCount:
cwbSV_GetRecordCount API は、この製品と共に使用します。
プログラミング
381
目的
与えられたファイル・ハンドルによって識別される保守ファイル中のレコード数の合計が戻されます。
構文
unsigned int CWB_ENTRY cwbSV_GetRecordCount(
cwbSV_ServiceFileHandle serviceFile,
unsigned long
*recordCount);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
unsigned long * recordCount - input/output
ファイルの中のレコード数の合計を受け取る変数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbSV_GetServiceFileName:
cwbSV_GetServiceFileName API は、この製品と共に使用します。
目的
特定のファイル・タイプについて保守レコードが記録されている場所の完全修飾パス名および完全修飾ファ
イル名を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetServiceFileName(
cwbSV_ServiceFileType serviceFileType,
char
*fileName,
unsigned long
fileNameLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceFileType serviceFileType - input
返したもらいたい保守ファイル名を示す値。 - CWBSV_HISTORY_LOG - CWBSV_PROBLEM_LOG CWBSV_DETAIL_TRACE_FILE - CWBSV_ENTRY_EXIT_TRACE_FILE
382
IBM i: Windows アプリケーション・パッケージ: プログラミング
char * fileName - input/output
要求した関連の保守ファイル名を受け取るバッファーを指すポインター。
unsigned long fileNameLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。注: 推奨サイズは CWBSV_MAX_FILE_PATH です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWBSV_INVALID_FILE_TYPE
渡されたファイル・タイプは使用できないタイプです。
使用法
戻されるファイル名ストリングは、cwbSV_OpenServiceFile() ルーチンへの入力として使用することができ
ます。
cwbSV_GetServiceType:
cwbSV_GetServiceType API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコードのタイプ (トレース、メッセージ、エントリー/エグ
ジットなど) を戻します。注: この関数を呼び出す前に、読み取り関数呼び出しによって保守レコードを取
得する必要があります。
構文
unsigned int CWB_ENTRY cwbSV_GetServiceType(
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_ServiceRecType
*serviceType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
プログラミング
383
cwbSV_ServiceRecType * serviceType - output
serviceType を戻す先である cwbSV_ServiceRecType を指すポインター。- CWBSV_MESSAGE_REC CWBSV_PROBLEM_REC - CWBSV_DATA_TRACE_REC - CWBSV_API_TRACE_REC CWBSV_SPI_TRACE_REC
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
無効なレコード・タイプが検出されました。
使用法
このルーチンを呼び出す前に、読み取り関数呼び出しによって保守レコード・ハンドルを取得する必要があ
ります。これを実行しないと、CWBSV_INVALID_RECORD_TYPE が戻されます。
cwbSV_GetTimeStamp:
cwbSV_GetTimeStamp API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコードの (地域化された形式の) タイム・スタンプを戻しま
す。
構文
unsigned int CWB_ENTRY cwbSV_GetTimeStamp(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*timeStamp,
unsigned long
timeStampLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * timeStamp - input/output
ハンドルによって識別されるレコードに保管された、タイム・スタンプを受け取るバッファーを指すポ
インター。
384
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long timeStampLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。注: 推奨サイズは CWBSV_MAX_TIME_VALUE です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
このルーチンを呼び出す前に、読み取り関数呼び出しによって保守レコード・ハンドルを取得する必要があ
ります。これを実行しないと、NULL ストリングが戻されます。この関数は、すべての保守レコード・タ
イプで有効です。
cwbSV_GetTraceData:
cwbSV_GetTraceData API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトのトレース・データ部分を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceData(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*traceData,
unsigned long
traceDataLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * traceData - input/output
ハンドルによって識別されるレコードに保管された、トレース・データを受け取るバッファーを指すポ
インター。注: 戻されるデータは 2 進数であるため、ASCIIZ ストリングとしては戻されません。
プログラミング
385
unsigned long traceDataLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられて
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_DATA_TRACE_REC ではありません。
使用法
レコード・タイプが CWBSV_TRACE_DATA_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceAPIData:
cwbSV_GetTraceAPIData API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコードの API トレース・データ部分を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceAPIData(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*apiData,
unsigned long
apiDataLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * apiData - input/output
ハンドルによって識別されるレコードに保管された API トレース・データを受け取るバッファーを指
すポインター。注: 戻されるデータは 2 進数であるため、ASCIIZ ストリングとしては戻されません。
386
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long apiDataLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられて
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_API_REC ではありません。
使用法
レコード・タイプが CWBSV_API_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceAPIID:
cwbSV_GetTraceAPIID API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトの API イベント ID を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceAPIID(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*apiID);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * apiID - input/output
API イベント ID を受け取る、1 バイトのフィールドを指すポインター。
プログラミング
387
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_API_REC ではありません。
使用法
レコード・タイプが CWBSV_API_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceAPIType:
cwbSV_GetTraceAPIType API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトの API イベント・タイプを戻しま
す。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceAPIType(
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_EventType
*eventType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
cwbSV_EventType * eventType - output
eventType を戻す先である cwbSV_EventType を指すポインター。- CWBSV_ENTRY_POINT CWBSV_EXIT_POINT
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
388
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_API_REC ではありません。
CWBSV_INVALID_EVENT_TYPE
使用できないイベント・タイプが見付かりました。
使用法
レコード・タイプが CWBSV_API_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceSPIData:
cwbSV_GetTraceSPIData API は、この製品と共に使用します。
目的
与えられたハンドルで識別される保守レコードの SPI トレース・データ部分を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceSPIData(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*spiData,
unsigned long
spiDataLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * spiData - input/output
ハンドルによって識別されるレコードに保管された、SPI トレース・データを受け取るバッファーを指
すポインター。注: 戻されるデータは 2 進数であるため、ASCIIZ ストリングとしては戻されません。
unsigned long spiDataLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられて
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
プログラミング
389
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_SPI_TRACE_REC ではありません。
使用法
レコード・タイプが CWBSV_SPI_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceSPIID:
cwbSV_GetTraceSPIID API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトの SPI イベント ID を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceSPIID(
cwbSV_ServiceRecHandle serviceRecHandle,
char
*spiID);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
char * spiID - input/output
SPI イベント ID を受け取る 1 バイトのフィールドを指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_SPI_TRACE_REC ではありません。
390
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
レコード・タイプが CWBSV_SPI_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_GetTraceSPIType:
cwbSV_GetTraceSPIType API は、この製品と共に使用します。
目的
与えられたハンドルによって識別される保守レコード・オブジェクトの SPI イベント・タイプを戻しま
す。
構文
unsigned int CWB_ENTRY cwbSV_GetTraceSPIType(
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_EventType
*eventType,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
cwbSV_EventType * eventType - output
eventType を戻す先である cwbSV_EventType を指すポインター。- CWBSV_ENTRY_POINT CWBSV_EXIT_POINT
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_INVALID_RECORD_TYPE
タイプが CWBSV_SPI_TRACE_REC ではありません。
CWBSV_INVALID_EVENT_TYPE
使用できないイベント・タイプが見付かりました。
プログラミング
391
使用法
レコード・タイプが CWBSV_SPI_TRACE_REC ではない場合、戻りコード
CWBSV_INVALID_RECORD_TYPE が戻されます。(注: cwbSV_GetServiceType() は現行のレコード・タイ
プを戻します。)
cwbSV_OpenServiceFile:
cwbSV_OpenServiceFile API は、この製品と共に使用します。
目的
読み取りアクセスのために指定された保守ファイル (ヒストリー・ログ、トレース・ファイルなど) をオー
プンし、そのハンドルを戻します。
構文
unsigned int CWB_ENTRY cwbSV_OpenServiceFile(
char
*serviceFileName,
cwbSV_ServiceFileHandle *serviceFileHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
char * serviceFileName - input
オープンする保守ファイルの完全修飾名 (例えば、c:¥path¥filename.ext) が含まれているバッファーを指
します。
cwbSV_ServiceFileHandle * serviceFileHandle - input/output
ハンドルが戻される先の cwbSV_ServiceFileHandle を指すポインター。このハンドルは、これ以降の保
守ファイル関数呼び出しで使用する必要があります。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ハンドル・アドレスとして NULL が渡されました。
CWB_FILE_IO_ERROR
ファイルはオープンできませんでした。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
なし (None)
392
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_ReadNewestRecord:
cwbSV_ReadNewestRecord API は、この製品と共に使用します。
目的
保守ファイル中の最新レコードを、与えられたレコード・ハンドルに読み取ります。以降の呼び出しで、こ
のレコードに保管されている情報を検索することができます (例えば、GetProduct()、 GetDateStamp() な
ど)。注: このレコードは、ファイルの中で最新の日付と時刻のスタンプを持つレコードです。
構文
unsigned int CWB_ENTRY cwbSV_ReadNewestRecord(
cwbSV_ServiceFileHandle serviceFileHandle,
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_END_OF_FILE
ファイルの終わりに達しました。
CWB_FILE_IO_ERROR
レコードが読み取れません。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この読み取りは、ファイル終わり標識が戻されるまで、一連の cwbSV_ReadPrevRecord() 呼び出しを出す前
の「準備タイプ」の読み取りとして使用することが考えられます。
cwbSV_ReadNextRecord:
cwbSV_ReadNextRecord API は、この製品と共に使用します。
プログラミング
393
目的
保守ファイル中の次のレコードを、与えられたレコード・ハンドルに読み取ります。以降の呼び出しで、こ
のレコードに保管されている情報を検索することができます (例えば、GetProduct()、 GetDateStamp() な
ど)。
構文
unsigned int CWB_ENTRY cwbSV_ReadNextRecord(
cwbSV_ServiceFileHandle serviceFileHandle,
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_END_OF_FILE
ファイルの終わりに達しました。
CWB_FILE_IO_ERROR
レコードが読み取れません。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この読み取りは通常、いったん準備読み取り ReadOldestRecord() を実行してから使用します。
cwbSV_ReadOldestRecord:
cwbSV_ReadOldestRecord API は、この製品と共に使用します。
目的
保守ファイル中の最も古いレコードを、与えられたレコード・ハンドルに読み取ります。以降の呼び出し
で、このレコードに保管されている情報を検索することができます (例えば、GetProduct()、
GetDateStamp() など)。注: このレコードは、ファイルの中で最も古い日付と時刻のスタンプを持つレコー
ドです。
394
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbSV_ReadOldestRecord(
cwbSV_ServiceFileHandle serviceFileHandle,
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
cwbSV_ServiceRecHandle serviceRecHandle - input
以前の cwbSV_CreateServiceRecHandle() 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_END_OF_FILE
ファイルの終わりに達しました。
CWB_FILE_IO_ERROR
レコードが読み取れません。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この読み取りは、ファイル終わり標識が戻されるまで、一連の cwbSV_ReadNextRecord() 呼び出しを出す前
の「準備タイプ」の読み取りとして使用することが考えられます。
cwbSV_ReadPrevRecord:
cwbSV_ReadPrevRecord API は、この製品と共に使用します。
目的
保守ファイル中の 1 行前のレコードを、与えられたレコード・ハンドルに読み取ります。以降の呼び出し
で、このレコードに保管されている情報を検索することができます (例えば、GetProduct()、
GetDateStamp() など)。
プログラミング
395
構文
unsigned int CWB_ENTRY cwbSV_ReadPrevRecord(
cwbSV_ServiceFileHandle serviceFileHandle,
cwbSV_ServiceRecHandle serviceRecHandle,
cwbSV_ErrHandle
errorHandle);
パラメーター
cwbSV_ServiceFileHandle serviceFileHandle - input
以前の cwbSV_OpenServiceFile 関数の呼び出しによって戻されたハンドル。
cwbSV_ErrHandle errorHandle - output
戻されたメッセージはすべてこのオブジェクトに書き込まれます。このオブジェクトは、
cwbSV_CreateErrHandle API を使用して作成されます。メッセージは、cwbSV_GetErrText API を介し
て検索することができます。パラメーターがゼロに設定されている場合は、メッセージは検索されませ
ん。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_END_OF_FILE
ファイルの終わりに達しました。
CWB_FILE_IO_ERROR
レコードが読み取れません。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この読み取りは通常、準備読み取り ReadNewestRecord() を実行してから使用します。
保守容易性 API のリスト: メッセージ・テキストの検索
これらの API を使用して、エラー・ハンドルに関連したメッセージ・テキストを検索します。
cwbSV_CreateErrHandle:
cwbSV_CreateErrHandle API は、この製品と共に使用します。
目的
この関数はエラー・メッセージ・オブジェクトを作成し、そのオブジェクトへのハンドルを戻します。この
エラー・ハンドルは、そのハンドルをサポートする API に渡すことができます。これらの API のいずれ
かでエラーが起こった場合、エラー・ハンドルを使用して、その API エラーに関連するエラー・メッセー
ジ・テキストを検索することができます。
構文
unsigned int CWB_ENTRY cwbSV_CreateErrHandle(
cwbSV_ErrHandle *errorHandle);
396
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbSV_ErrHandle *errorHandle - input/output
ハンドルが戻される先の cwbSV_ErrHandle を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
ハンドル・アドレスとして NULL が渡されました。
CWB_NOT_ENOUGH_MEMORY
メモリーが十分にないため、ハンドルを作成できません。
使用法
なし (None)
cwbSV_DeleteErrHandle:
cwbSV_DeleteErrHandle API は、この製品と共に使用します。
目的
この関数は、与えられたハンドルで識別されるエラー・メッセージ・オブジェクトを削除します。
構文
unsigned int CWB_ENTRY cwbSV_DeleteErrHandle(
cwbSV_ErrHandle errorHandle);
パラメーター
cwbSV_ErrHandle errorHandle - output
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
この呼び出しは、ハンドルが必要でなくなった際に行ってください。
cwbSV_GetErrClass:
cwbSV_GetErrClass API は、この製品と共に使用します。
プログラミング
397
目的
与えられたエラー・ハンドルによって識別される、最上位の (最新の) エラーに関連するメッセージ・クラ
スを戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetErrClass(
cwbSV_ErrHandle errorHandle,
unsigned long *errorClass);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
unsigned long * errorClass - output
ハンドルによって識別されるエラーに保管された、エラー・クラスを受け取る変数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルに関連するエラー・メッセージがありません。
使用法
なし (None)
cwbSV_GetErrClassIndexed:
cwbSV_GetErrClassIndexed API は、この製品と共に使用します。
目的
与えられたエラー指標に関連するメッセージ・クラスを戻します。指標値が 1 であれば、エラー・ハンド
ルに関連する最下位の (例えば、最も古い) メッセージを検索します。指標値が「cwbSV_GetErrCount() が
戻した errorCount」であれば、エラー・ハンドルに関連する最上位の (例えば、最新の) メッセージを検索
します。
構文
unsigned int CWB_ENTRY cwbSV_GetErrClassIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long
errorIndex,
unsigned long *errorClass);
398
IBM i: Windows アプリケーション・パッケージ: プログラミング
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
unsigned long errorIndex - input
複数のエラーがエラー・ハンドルに関連する場合、どのエラー・テキストを戻すかを示す指標値。
unsigned long * errorClass - output
指標によって識別されるエラーに保管されたエラー・クラスを受け取る変数を指すポインター。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルに関連するエラー・メッセージがありません。
使用法
有効な指標値は 1 から cwbSV_GetErrCount() の戻り値までです。1 よりも小さい指標値は、 1 が渡され
た場合と同様に動作します。 cwbSV_GetErrCount() よりも大きい指標値は、 errorCount が渡された場合と
同様に動作します。
cwbSV_GetErrCount:
cwbSV_GetErrCount API は、この製品と共に使用します。
目的
与えられたエラー・ハンドルに関連するメッセージ数を戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetErrCount(
cwbSV_ErrHandle errorHandle,
unsigned long
*errorCount);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
unsigned long * errorCount - input/output
このエラー・ハンドルに関連するメッセージ数を受け取る変数を指すポインター。ゼロが戻された場合
は、エラー・ハンドルに関連するエラーはありません。
プログラミング
399
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
使用法
なし (None)
cwbSV_GetErrFileName:
cwbSV_GetErrFileName API は、この製品と共に使用します。
目的
与えられたエラー・ハンドルに追加される最上位 (最新) メッセージのメッセージ・ファイル名を戻しま
す。このメッセージ属性は、IBM i メッセージにのみ関連します。このファイル名は、メッセージが収め
られている IBM i メッセージ・ファイルの名前になります。
構文
unsigned int CWB_ENTRY cwbSV_GetErrFileName(
cwbSV_ErrHandle
char
unsigned long
unsigned long
errorHandle,
*fileName,
fileNameLength,
*returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
char * fileName - input/output
ハンドルによって識別されるエラーに保管されたメッセージ・ファイル名を受け取るバッファーを指す
ポインター。戻される値は ASCIIZ ストリングです。
unsigned long fileNameLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられ、CWB_BUFFER_OVERFLOW と returnLength
が設定されます。注: 推奨サイズは、CWBSV_MAX_MSGFILE_NAME です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
400
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージのメッセージ・ファイル名を取得できます。そのメッセージのメッセージ・ファイル名属性が
なければ、戻りコード CWBSV_ATTRIBUTE_NOT_SET が戻されます。
cwbSV_GetErrFileNameIndexed:
cwbSV_GetErrFileNameIndexed API は、この製品と共に使用します。
目的
与えられた指標によって識別されるメッセージのメッセージ・ファイル名を戻します。このメッセージ属性
は、IBM i から戻されるメッセージにのみ関連します。このファイル名は、メッセージが収められている
IBM i メッセージ・ファイルの名前になります。
構文
unsigned int CWB_ENTRY cwbSV_GetErrFileNameIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long
index,
char
*fileName,
unsigned long
fileNameLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
unsigned long index - input
複数のエラーがエラー・ハンドルに関連する場合、戻すメッセージ・ファイル名を示す指標値。指標の
有効な範囲は、1 から「エラー・ハンドルに入っているメッセージ数」です。メッセージ数は、
cwbSV_GetErrCount() API を呼び出して入手することができます。
char * fileName - input/output
指標によって識別されるエラーに保管されたメッセージ・ファイル名を受け取るバッファーを指すポイ
ンター。戻される値は ASCIIZ ストリングです。
プログラミング
401
unsigned long fileNameLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられ、CWB_BUFFER_OVERFLOW と returnLength
が設定されます。注: 推奨サイズは、CWBSV_MAX_MSGFILE_NAME です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージのメッセージ・ファイル名を取得できます。そのメッセージのメッセージ・ファイル名属性が
なければ、戻りコード CWBSV_ATTRIBUTE_NOT_SET が戻されます。指標値 1 では、エラー・ハンドル
内の最下位 (つまり最も古い) メッセージを処理します。cwbSV_GetErrCount() API によって戻されたカウ
ントと同じ指標値では、エラー・ハンドル内の最上位 (つまり最新) メッセージを処理します。1 よりも小
さい指標値を指定すると、1 が渡された場合のように動作します。エラー・ハンドルに入っているメッセー
ジ数より大きい指標値を指定すると、cwbSV_GetErrCount() API から戻されたカウント値が渡された場合の
ように動作します。
cwbSV_GetErrLibName:
cwbSV_GetErrLibName API は、この製品と共に使用します。
目的
与えられたエラー・ハンドルに追加される最上位 (つまり、最新) メッセージのメッセージ・ファイル・ラ
イブラリー名を戻します。このメッセージ属性は、IBM i から戻されるメッセージにのみ関連します。こ
のライブラリー名は、このメッセージのメッセージ・ファイルが含まれる IBM i ライブラリーの名前で
す。
402
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY cwbSV_GetErrLibName(
cwbSV_ErrHandle errorHandle,
char
*libraryName,
unsigned long
libraryNameLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
char * libraryName - input/output
ハンドルによって識別されるエラーで保管されたメッセージ・ファイル・ライブラリー名を受け取るバ
ッファーを指すポインター。戻される値は ASCIIZ ストリングです。
unsigned long libraryNameLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられ、CWB_BUFFER_OVERFLOW と returnLength
が設定されます。注: 推奨サイズは、CWBSV_MAX_MSGFILE_LIBR です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージのメッセージ・ファイル・ライブラリー名を取得できます。そのメッセージのメッセージ・フ
ァイル・ライブラリー名属性がなければ、戻りコード CWBSV_ATTRIBUTE_NOT_SET が戻されます。
cwbSV_GetErrLibNameIndexed:
cwbSV_GetErrLibNameIndexed API は、この製品と共に使用します。
プログラミング
403
目的
与えられた指標によって識別されるメッセージのメッセージ・ファイル・ライブラリー名を戻します。この
メッセージ属性は、IBM i から戻されるメッセージにのみ関連します。このライブラリー名は、このメッ
セージのメッセージ・ファイルが含まれる IBM i ライブラリーの名前です。
構文
unsigned int CWB_ENTRY cwbSV_GetErrLibNameIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long
index,
char
*libraryName,
unsigned long
libraryNameLength,
unsigned long *returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
unsigned long index - input
複数のエラーがエラー・ハンドルに関連する場合、戻すメッセージ・ファイル・ライブラリー名を示す
指標値。指標の有効な範囲は、1 から「エラー・ハンドルに入っているメッセージ数」です。メッセー
ジ数は、cwbSV_GetErrCount() API を呼び出して入手することができます。
char * libraryName - input/output
指標によって識別されるエラーに保管されたメッセージ・ファイル・ライブラリー名を受け取るバッフ
ァーを指すポインター。戻される値は ASCIIZ ストリングです。
unsigned long libraryNameLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられ、CWB_BUFFER_OVERFLOW と returnLength
が設定されます。注: 推奨サイズは、CWBSV_MAX_MSGFILE_LIBR です。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
404
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージのメッセージ・ファイル・ライブラリー名を取得できます。そのメッセージのメッセージ・フ
ァイル・ライブラリー名属性がなければ、戻りコード CWBSV_ATTRIBUTE_NOT_SET が戻されます。指
標値 1 では、エラー・ハンドル内の最下位 (つまり最も古い) メッセージを処理します。
cwbSV_GetErrCount() API によって戻されたカウントと同じ指標値では、エラー・ハンドル内の最上位 (つ
まり最新) メッセージを処理します。1 よりも小さい指標値を指定すると、1 が渡された場合のように動作
します。エラー・ハンドルに入っているメッセージ数より大きい指標値を指定すると、
cwbSV_GetErrCount() API から戻されたカウント値が渡された場合のように動作します。
cwbSV_GetErrSubstText:
cwbSV_GetErrSubstText API は、この製品と共に使用します。
目的
与えられたエラー・ハンドルで識別される最上位 (最新) のメッセージのメッセージ置換データを戻しま
す。このメッセージ属性は、IBM i から戻されるメッセージにのみ関連します。置換データは、メッセー
ジに対して定義されている置換変数フィールドに挿入されます。
構文
unsigned int CWB_ENTRY cwbSV_GetErrSubstText(
cwbSV_ErrHandle errorHandle,
char
*substitutionData,
unsigned long
substitutionDataLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
char * substitutionData - input/output
ハンドルで識別されるメッセージの置換データを受け取るバッファーを指すポインター。注: 戻される
データは 2 進数であるため、ASCIIZ ストリングとしては戻されません。置換データに含まれる文字
ストリングは、すべて EBCDIC 値として戻されます。
unsigned long substitutionDataLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられ、
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。これは、正常に終了した時点で戻される出力デ
ータの実際のバイト数に設定されます。
戻りコード
以下は、共通の戻り値です。
プログラミング
405
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージの置換データを検索できます。メッセージの置換データがない場合は、戻りコード
CWBSV_ATTRIBUTE_NOT_SET が戻されます。戻りコードが CWB_OK である場合は、returnLength パラ
メーターを使用して、置換データ内に戻された実際のバイト数を判別してください。この API で戻された
置換データを、後続のホスト検索メッセージ API 呼び出し (QSYS/QMHRTVM) で使用して、置換データ
の形式を検索したり、置換データを追加した 2 次ヘルプ・テキストを戻したりすることができます。ホス
ト API は、cwbRC_CallPgm() API を使用して呼び出します。
cwbSV_GetErrSubstTextIndexed:
cwbSV_GetErrSubstTextIndexed API は、この製品と共に使用します。
目的
与えられた指標で識別されるメッセージのメッセージ置換データを戻します。このメッセージ属性は、IBM
i から戻されるメッセージにのみ関連します。置換データは、メッセージに対して定義されている置換変数
フィールドに挿入されるデータです。
構文
unsigned int CWB_ENTRY cwbSV_GetErrSubstTextIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long
index,
char
*substitutionData,
unsigned long
substitutionDataLength,
unsigned long *returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() API への呼び出しによって戻されたハンドル。
unsigned long index - input
複数のエラーがエラー・ハンドルに関連する場合に戻す置換データを示す指標値。指標の有効な範囲
406
IBM i: Windows アプリケーション・パッケージ: プログラミング
は、1 から「エラー・ハンドルに入っているメッセージ数」です。メッセージ数は、
cwbSV_GetErrCount() API を呼び出して入手することができます。
char * substitutionData - input/output
指標で識別されるエラーに保管された置換データを受け取るバッファーを指すポインター。注: 戻され
るデータは 2 進数であるため、ASCIIZ ストリングとしては戻されません。置換データに含まれる文
字ストリングは、すべて EBCDIC 値として戻されます。
unsigned long substitutionDataLength - input
渡される受信バッファーの長さ。バッファーが小さすぎると、値が切り捨てられ、
CWB_BUFFER_OVERFLOW と returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に出力データを保持する
ために必要なバイト数を保管するための戻りアドレス。これは、正常に終了した時点で戻される出力デ
ータの実際のバイト数に設定されます。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルにメッセージは入っていません。
CWBSV_ATTRIBUTE_NOT_SET
属性が現行メッセージ内に設定されていません。
使用法
cwbRC_CallPgm() API および cwbRC_RunCmd() API の使用時に、IBM i メッセージがエラー・ハンドル
に追加されることがあります。このような場合、この API を使用して、エラー・ハンドルに含まれる IBM
i メッセージの置換データを検索できます。メッセージの置換データがない場合は、戻りコード
CWBSV_ATTRIBUTE_NOT_SET が戻されます。指標値 1 では、エラー・ハンドル内の最下位 (つまり最
も古い) メッセージを処理します。cwbSV_GetErrCount() API によって戻されたカウントと同じ指標値で
は、エラー・ハンドル内の最上位 (つまり最新) メッセージを処理します。1 よりも小さい指標値を指定す
ると、1 が渡された場合のように動作します。エラー・ハンドルに入っているメッセージ数より大きい指標
値を指定すると、cwbSV_GetErrCount() API から戻されたカウント値が渡された場合のように動作します。
戻りコードが CWB_OK である場合は、returnLength パラメーターを使用して、置換データ内に戻された実
際のバイト数を判別してください。この API で戻された置換データを、後続のホスト検索メッセージ API
呼び出し (QSYS/QMHRTVM) で使用して、置換データの形式を検索したり、置換データを追加した 2 次
ヘルプ・テキストを戻したりすることができます。ホスト API は、cwbRC_CallPgm() API を使用して呼び
出します。
プログラミング
407
cwbSV_GetErrText:
cwbSV_GetErrText API は、この製品と共に使用します。
目的
与えられたエラー・ハンドルによって識別される、最上位の (例えば、最新の) エラーに関連するメッセー
ジ・テキストを戻します。
構文
unsigned int CWB_ENTRY cwbSV_GetErrText(
cwbSV_ErrHandle errorHandle,
char
*errorText,
unsigned long
errorTextLength,
unsigned long *returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
char * errorText - input/output
ハンドルによって識別されるエラーに保管された、エラー・メッセージ・テキストを受け取るバッファ
ーを指すポインター。
unsigned long errorTextLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルに関連するエラー・メッセージがありません。
使用法
なし (None)
408
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbSV_GetErrTextIndexed:
cwbSV_GetErrTextIndexed API は、この製品と共に使用します。
目的
与えられたエラー指標に関連するメッセージ・テキストを戻します。指標値が 1 であれば、エラー・ハン
ドルに関連する最下位の (例えば、最も古い) メッセージを検索します。指標値が「cwbSV_GetErrCount()
が戻した errorCount」であれば、エラー・ハンドルに関連する最上位の (例えば、最新の) メッセージを検
索します。
構文
unsigned int CWB_ENTRY cwbSV_GetErrTextIndexed(
cwbSV_ErrHandle errorHandle,
unsigned long
errorIndex,
char
*errorText,
unsigned long
errorTextLength,
unsigned long
*returnLength);
パラメーター
cwbSV_ErrHandle errorHandle - input
以前の cwbSV_CreateErrHandle() 関数の呼び出しによって戻されたハンドル。
unsigned long errorIndex - input
複数のエラーがエラー・ハンドルに関連する場合、どのエラー・テキストを戻すかを示す指標値。
char * errorText - input/output
指標によって識別されるエラーに保管された、エラー・メッセージ・テキストを受け取るバッファーを
指すポインター。
unsigned long errorTextLength - input
渡される受信バッファーの長さ。これには、NULL 終了文字を入れるためのスペースを含める必要があ
ります。バッファーが小さすぎると、値が切り捨てられて CWB_BUFFER_OVERFLOW と
returnLength が設定されます。
unsigned long * returnLength - input/output
オプションであり、NULL でも構いません。受信バッファーが小さすぎる場合に、出力ストリングを保
持するために必要なバイト数を保管するための戻りアドレス。
戻りコード
以下は、共通の戻り値です。
CWB_OK
正常終了。
CWB_BUFFER_OVERFLOW
出力バッファーが小さすぎるため、データは切り捨てられました。
CWB_INVALID_POINTER
NULL が出力パラメーターに渡されました。
CWB_INVALID_HANDLE
無効なハンドル。
プログラミング
409
CWBSV_NO_ERROR_MESSAGES
エラー・ハンドルに関連するエラー・メッセージがありません。
使用法
有効な指標値は 1 から cwbSV_GetErrCount() の戻り値までです。1 よりも小さい指標値は、 1 が渡され
た場合と同様に動作します。 cwbSV_GetErrCount() よりも大きい指標値は、 errorCount が渡された場合と
同様に動作します。
例: 保守容易性 API の使用法
保守容易性 API を使用して、製品のヒストリー・ログにメッセージ・ストリングを記録する方法を、以下
の例で説明します。このプログラムを実行する前に、製品診断ヒストリー・ログを開始してください。
#include <stdio.h>
#include <string.h>
#include "CWBSV.H"
unsigned int logMessageText(char *msgtxt)
/* Write a message to the active message log. */
{
cwbSV_MessageTextHandle messageTextHandle;
unsigned int
rc;
/* Create a handle to a message text object, so that we may write */
/* message text to the active message log.
*/
if ((rc = cwbSV_CreateMessageTextHandle("ProductID", "ComponentID",
&messageTextHandle)) != CWB_OK)
return(rc);
/* Log the supplied message text to the active message log.
*/
rc = cwbSV_LogMessageText(messageTextHandle, msgtxt, strlen(msgtxt));
/* Delete the message text object identified by the handle provided.*/
cwbSV_DeleteMessageTextHandle(messageTextHandle);
return(rc);
}
unsigned int readMessageText(char **bufptr, cwbSV_ErrHandle errorHandle)
/* Read a message from the active message log. */
{
cwbSV_ServiceFileHandle serviceFileHandle;
cwbSV_ServiceRecHandle serviceRecHandle;
static char buffer[BUFSIZ];
unsigned int
rc;
/* Retrieve the fully-qualified path and file name of the active */
/* message log.
*/
if ((rc = cwbSV_GetServiceFileName(CWBSV_HISTORY_LOG, buffer, BUFSIZ,
NULL)) != CWB_OK)
return(rc);
/* Open the active message log for READ access and return a handle */
/* to it.
*/
if ((rc = cwbSV_OpenServiceFile(buffer, &serviceFileHandle, errorHandle))
!= CWB_OK)
return(rc);
/* Create a service record object and return a handle to it.
*/
if ((rc = cwbSV_CreateServiceRecHandle(&serviceRecHandle)) != CWB_OK) {
cwbSV_CloseServiceFile(serviceFileHandle, 0);
return(rc);
}
410
IBM i: Windows アプリケーション・パッケージ: プログラミング
/* Read the newest record in the active message log into the
*/
/* record handle provided.
*/
if ((rc = cwbSV_ReadNewestRecord(serviceFileHandle, serviceRecHandle,
errorHandle)) != CWB_OK) {
cwbSV_DeleteServiceRecHandle(serviceRecHandle);
cwbSV_CloseServiceFile(serviceFileHandle, 0);
return(rc);
}
/* Retrieve the message text portion of the service record object */
/* identified by the handle provided.
*/
if ((rc = cwbSV_GetMessageText(serviceRecHandle, buffer, BUFSIZ, NULL))
== CWB_OK || rc == CWB_BUFFER_OVERFLOW) {
*bufptr = buffer;
rc = CWB_OK;
}
/* Delete the service record object identified by the
/* handle provided.
cwbSV_DeleteServiceRecHandle(serviceRecHandle);
*/
*/
/* Close the active message log identified by the handle provided.*/
cwbSV_CloseServiceFile(serviceFileHandle, errorHandle);
return(rc);
}
void main(int argc, char *argv[ ])
{
cwbSV_ErrHandle errorHandle;
char *msgtxt = NULL, errbuf[BUFSIZ];
unsigned int
rc;
/* Write a message to the active message log.
if (logMessageText("Sample message text") != CWB_OK)
return;
*/
/* Create an error message object and return a handle to it.
cwbSV_CreateErrHandle(&errorHandle);
*/
/* Read a message from the active message log.
*/
if (readMessageText(&msgtxt, errorHandle) != CWB_OK) {
if ((rc = cwbSV_GetErrText(errorHandle, errbuf, BUFSIZ, NULL)) ==
CWB_OK || rc == CWB_BUFFER_OVERFLOW)
fprintf(stdout, "%s¥n", errbuf);
}
else if (msgtxt)
fprintf(stdout, "Message text: ¥"%s¥"¥n", msgtxt);
/* Delete the error message object identified by the
/* handle provided.
cwbSV_DeleteErrHandle(errorHandle);
*/
*/
}
システム・オブジェクト・アクセス (SOA) API
システム・オブジェクト・アクセスを使用することで、グラフィカル・ユーザー・インターフェースを介し
て、システム・オブジェクトの表示および操作を行うことができます。
システム・オブジェクト・アクセスのアプリケーション・プログラミング・インターフェース (API) によ
って、オブジェクト属性に直接アクセスすることが可能になります。例えば、一連の SOA API を呼び出
して任意のスプール・ファイルのコピー数を取得し、必要に応じてその値を変更することができます。
プログラミング
411
システム・オブジェクト・アクセス API に必要なファイル
インターフェース定義ファイル
インポート・ライブラリー
ダイナミック・リンク・ライブラリー
cwbsoapi.h
cwbapi.lib
cwbsoapi.dll
Programmer's Toolkit:
Programmer's Toolkit には、システム・オブジェクト・アクセスの資料、cwbsoapi.h ヘッダー・ファイルへ
のアクセス、およびプログラム例へのリンクが用意されています。この情報にアクセスするには、
Programmer's Toolkit をオープンして、「IBM i オペレーション (IBM i Operations)」 > 「C/C++ API」
と選択します。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
26 ページの『システム・オブジェクト・アクセス API 戻りコード』
以下の SOA API 戻りコードがあります。
5 ページの『接続 API 用の IBM i 名の形式』
パラメーターとして IBM i 名を取得する API では、3 つの異なる形式の名前を使用できます。
SOA オブジェクト
システム・オブジェクト・アクセスを使用して、次の IBM i オブジェクトの表示および操作を行います。
表示および操作可能なオブジェクト
v ジョブ
v プリンター
v 印刷出力
v メッセージ
v スプール・ファイル
操作のみ可能なオブジェクト
v ユーザーとグループ
v TCP/IP インターフェース
v TCP/IP 経路
v イーサネット回線
v トークンリング回線
v ハードウェア資源
v ソフトウェア資源
v QSYS のライブラリー
システム・オブジェクト・ビュー
次の 2 つのタイプのシステム・オブジェクト・ビューが提供されています。
412
IBM i: Windows アプリケーション・パッケージ: プログラミング
リスト・ビュー
選択したシステム・オブジェクトに対して、カスタマイズ可能なグラフィック・リスト・ビューを
表示します。ユーザーは 1 つまたは複数のオブジェクトに対して、さまざまなアクションを行う
ことができます。
プロパティー・ビュー
特定のシステム・オブジェクトの属性について、詳細なグラフィック・ビューを表示します。ユー
ザーは、必要であればすべての属性を表示させることができ、変更可能な属性に変更を加えること
ができます。
システム・オブジェクト・アクセス API の一般的な使用法
ここでは、システム・オブジェクト・アクセス API の 3 つの使用例を示します。
各例は、2 回ずつ示してあります。API 呼び出しの一般的な順序を要約形式で示し、次に実際の C 言語サ
ンプル・プログラムを示しています。要約では、どの API が必須 (R) か、およびどれがオプション (O)
かを示しています。通常、各関数呼び出しにはエラーの検査および処理のための追加のコードが必要です。
紙面の都合上、ここでは、それらのコードについては省略しています。
システム・オブジェクトのカスタマイズ・リストの表示:
この例では、IBM i スプール・ファイル・オブジェクトのリストを作成します。希望するソートおよびフ
ィルター基準を設定した後、ある種のユーザー・アクションが使用不可になるようユーザー・インターフェ
ースがカスタマイズされた状態で、リストがユーザーに表示されます。
ユーザーがリストを見終わった後、フィルター基準はアプリケーション・プロファイルに保管され、プログ
ラムは終了します。
システム・オブジェクトのカスタマイズ・リストの表示 (要約)
(O)
cwbRC_StartSys
IBM i の会話を開始する。
(R)
CWBSO_CreateListHandle
システム・オブジェクトのリストを作成する。
(O)
CWBSO_SetListProfile
アプリケーションの名前を設定する。
(O)
CWBSO_ReadListProfile
アプリケーションの設定をロードする。
(O)
CWBSO_SetListFilter
リスト・フィルターの基準を設定する。
(O)
CWBSO_SetListSortFields
リスト・ソートの基準を設定する。
(O)
CWBSO_DisallowListFilter
ユーザーにフィルター基準の変更を許可しない。
(O)
CWBSO_DisallowListActions
選択されたリスト・アクションを許可しない。
(O)
CWBSO_SetListTitle
リストのタイトルを設定する。
(R)
CWBSO_CreateErrorHandle
エラー・オブジェクトを作成する。
(R)
CWBSO_DisplayList
カスタマイズ・リストを表示する。
(O)
CWBSO_DisplayErrMsg
エラーが発生した場合、エラー・メッセージを表示する。
(O)
CWBSO_WriteListProfile
リスト・フィルター基準を保管する。
(R)
CWBSO_DeleteErrorHandle
エラー・オブジェクトを削除する。
プログラミング
413
(R)
CWBSO_DeleteListHandle
リストを削除する。
(O)
cwbRC_StopSys
IBM i の会話を終了する。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
サンプル・プログラム: システム・オブジェクトのカスタマイズ・リストの表示:
このサンプル・プログラムを使用して、IBM i オブジェクトを表示します。
#ifdef UNICODE
#define _UNICODE
#endif
#include <windows.h>
#include "cwbsoapi.h"
#include "cwbrc.h"
#include "cwbun.h"
//
//
//
//
#define
// Application profile name
APP_PROFILE
"APPPROF"
Windows APIs and datatypes
System Object Access APIs
IBM i DPC APIs
IBM i Navigator APIs
int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
{
MSG
msg;
// Message structure
HWND
hWnd;
// Window handle
cwbRC_SysHandle
hSystem;
// System handle
CWBSO_LIST_HANDLE hList = CWBSO_NULL_HANDLE;
// List handle
CWBSO_ERR_HANDLE hError = CWBSO_NULL_HANDLE;
// Error handle
cwbCO_SysHandle
hSystemHandle;
// System object handle
unsigned int
rc;
// System Object Access return codes
unsigned short
unsigned short
sortIDs[] = { CWBSO_SFL_SORT_UserData,
CWBSO_SFL_SORT_Priority };
// Array of sort IDs
actionIDs[] = { CWBSO_ACTN_PROPERTIES };
// Array of action IDs
//******************************************************************
// Start a conversation with IBM i SYSNAME. Specify
// application name APPNAME.
//******************************************************************
cwbUN_GetSystemHandle((char *)"SYSNAME", (char *)"APPNAME", &hSystemHandle);
cwbRC_StartSysEx(hSystemHandle, &hSystem);
//*******************************************************************
// Create a list of spooled files. Set desired sort/filter criteria.
// Create a list of spooled files on system SYSNAME
CWBSO_CreateListHandleEx(hSystemHandle,
CWBSO_LIST_SFL,
&hList);
// Identify the name of the application profile
CWBSO_SetListProfile(hList, APP_PROFILE);
// Create an error handle
CWBSO_CreateErrorHandle(&hError);
// Load previous filter criteria
CWBSO_ReadListProfile(hList, hError);
// Only show spooled files on printer P3812 for user TLK
CWBSO_SetListFilter(hList, CWBSO_SFLF_DeviceFilter, "P3812");
414
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_SetListFilter(hList, CWBSO_SFLF_UserFilter, "TLK");
// Sort by ’user specified data’, then by ’output priority’
CWBSO_SetListSortFields(hList, sortIDs, sizeof(sortIDs) / sizeof(short));
//*******************************************************************
// Customize the UI by disabling selected UI functions. Set the list title.
//*******************************************************************
// Do not allow users to change list filter
CWBSO_DisallowListFilter(hList);
// Do not allow the ’properties’ action to be selected
CWBSO_DisallowListActions(hList, actionIDs, sizeof(actionIDs) / sizeof(short));
// Set the string that will appear in the list title bar
CWBSO_SetListTitle(hList, "Application Title");
//*******************************************************************
// Display the list.
//*******************************************************************
// Display the customized list of spooled files
rc = CWBSO_DisplayList(hList, hInstance, nCmdShow, &hWnd, hError);
// If an error occurred, display a message box
if (rc == CWBSO_ERROR_OCCURRED)
CWBSO_DisplayErrMsg(hError);
else
{
// Dispatch messages for the list window
while(GetMessage(&msg, NULL, 0, 0))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
// List window has been closed - save filter criteria in application profile
CWBSO_WriteListProfile(hList, hError);
}
//*******************************************************************
// Processing complete - clean up and exit.
//*******************************************************************
// Clean up handles
CWBSO_DeleteErrorHandle(hError);
CWBSO_DeleteListHandle(hList);
// End the conversation started by EHNDP_StartSys
cwbRC_StopSys(hSystem);
//********************************************************************
// Return from WinMain.
//********************************************************************
return rc;
}
システム・オブジェクトのプロパティー・ビューの表示:
IBM i スプール・ファイルのリスト用のリスト・オブジェクトが作成されます。希望するフィルター基準
を設定した後、リストがオープンされ、リスト中の最初のオブジェクトのハンドルが獲得されます。このオ
ブジェクトの属性を示すプロパティー・ビューがユーザーに表示されます。
プログラミング
415
オブジェクトのプロパティー・ビューの表示 (要約)
IBM i の会話を開始する。
(O)
cwbRC_StartSys
(R)
CWBSO_CreateListHandle
システム・オブジェクトのリストを作成する。
(O)
CWBSO_SetListFilter
リスト・フィルターの基準を設定する。
(R)
CWBSO_CreateErrorHandle
エラー・オブジェクトを作成する。
(R)
CWBSO_OpenList
リストをオープンする
(IBM i リストを作成する)。
(O)
CWBSO_DisplayErrMsg
エラーが発生した場合、エラー・メッセージを表示する。
(O)
CWBSO_GetListSize
リスト内のオブジェクトの数を取得する。
(R)
CWBSO_GetObjHandle
リストからオブジェクトを取得する。
(R)
CWBSO_DisplayObjAttr
オブジェクトのプロパティー・ビューを表示する。
(R)
CWBSO_DeleteObjHandle
オブジェクトを削除する。
(O)
CWBSO_CloseList
リストをクローズする。
(R)
CWBSO_DeleteErrorHandle
エラー・オブジェクトを削除する。
(R)
CWBSO_DeleteListHandle
リストを削除する。
(O)
cwbRC_StopSys
IBM i の会話を終了する。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
サンプル・プログラム: オブジェクトのプロパティー・ビューの表示:
このサンプル・プログラムを使用して、プロパティー・ビューを表示します。
#ifdef UNICODE
#define _UNICODE
#endif
#include <windows.h>
#include "cwbsoapi.h"
#include "cwbrc.h"
#include "cwbun.h"
//
//
//
//
Windows APIs and datatypes
System Object Access APIs
IBM i DPC APIs
IBM i Navigator APIs
int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
{
MSG
msg;
// Message structure
HWND
hWnd;
// Window handle
cwbRC_SysHandle
hSystem;
// System handle
CWBSO_LIST_HANDLE hList = CWBSO_NULL_HANDLE;
// List handle
CWBSO_ERR_HANDLE hError = CWBSO_NULL_HANDLE;
// Error handle
CWBSO_OBJ_HANDLE hObject = CWBSO_NULL_HANDLE; // Object handle
cwbCO_SysHandle
hSystemHandle;
// System object handle
unsigned long
listSize = 0;
// List size
unsigned short
listStatus = 0;
// List status
unsigned int
rc;
// System Object Access return codes
//*******************************************************************
// Start a conversation with IBM i SYSNAME. Specify
// application name APPNAME.
//******************************************************************
cwbUN_GetSystemHandle((char *)"SYSNAME", (char *)"APPNAME", &hSystemHandle);
416
IBM i: Windows アプリケーション・パッケージ: プログラミング
cwbRC_StartSysEx(hSystemHandle, &hSystem);
//*******************************************************************
// Create a list of spooled files. Set desired filter criteria.
//*******************************************************************
// Create a list of spooled files on system SYSNAME
CWBSO_CreateListHandleEx(hSystemHandle,
CWBSO_LIST_SFL,
&hList);
// Only include spooled files on printer P3812 for user TLK
CWBSO_SetListFilter(hList, CWBSO_SFLF_DeviceFilter, "P3812");
CWBSO_SetListFilter(hList, CWBSO_SFLF_UserFilter, "TLK");
//*******************************************************************
// Open the list.
//*******************************************************************
// Create an error handle
CWBSO_CreateErrorHandle(&hError);
//
rc
//
if
Open the list of spooled files
= CWBSO_OpenList(hList, hError);
If an error occurred, display a message box
(rc == CWBSO_ERROR_OCCURRED)
CWBSO_DisplayErrMsg(hError);
else
{
//*****************************************************************
// Display the properties of the first object in the list
//*****************************************************************
// Get the number of objects in the list
CWBSO_GetListSize(hList, &listSize, &listStatus, hError);
if (listSize > 0)
{
// Get the first object in the list
CWBSO_GetObjHandle(hList, 0, &hObject, hError);
// Display the properties window for this object
CWBSO_DisplayObjAttr(hObject, hInstance, nCmdShow, &hWnd, hError);
// Dispatch messages for the properties window
while(GetMessage(&msg, NULL, 0, 0))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
// Properties window has been closed - delete object handle
CWBSO_DeleteObjHandle(hObject);
}
}
//*******************************************************************
// Processing complete - clean up and exit.
//*******************************************************************
// Close the list
CWBSO_CloseList(hList, hError);
// Clean up handles
CWBSO_DeleteErrorHandle(hError);
CWBSO_DeleteListHandle(hList);
プログラミング
417
// End the conversation started by EHNDP_StartSys
cwbRC_StopSys(hSystem);
//********************************************************************
// Return from WinMain.
//********************************************************************
return rc;
}
システム・オブジェクトのデータのアクセスと更新:
IBM i スプール・ファイルのリスト・オブジェクトが作成されます。希望するフィルター基準を設定した
後、リストがオープンされます。パラメーター・オブジェクトが作成され、これを使用してリスト内の各ス
プール・ファイルの出力優先順位が変更されます。
希望する出力優先順位値の "9" をパラメーター・オブジェクトに保管した後、ループに入ります。リスト
内の各オブジェクトが順番に調べられ、10 ページ以上あるスプール・ファイルが見付かると、その出力優
先順位が変更されます。
この例では、装置 P3812 のスプール・ファイルのうち、10 ページ以上のものは、出力優先順位が 9 に変
更され、それより小さいファイルより前に印刷しないようにしています。
システム・オブジェクトのデータのアクセスおよび更新 (要約)
(R)
CWBSO_CreateListHandle
システム・オブジェクトのリストを作成する。
(O)
CWBSO_SetListFilter
リスト・フィルターの基準を設定する。
(R)
CWBSO_CreateErrorHandle
エラー・オブジェクトを作成する。
(R)
CWBSO_OpenList
リストをオープンする
(IBM i の会話を自動的に開始する)。
(O)
CWBSO_DisplayErrMsg
エラーが発生した場合、エラー・メッセージを表示する。
(R)
CWBSO_CreateParmObjHandle
パラメーター・オブジェクトを作成する。
(R)
CWBSO_SetParameter
1 つまたは複数のオブジェクト属性用に新規の値を設定する。
(R)
CWBSO_WaitForObj
最初のオブジェクトが使用可能になるまで待機する。
. . . すべてのオブジェクトをループする。
.
. (R) CWBSO_GetObjHandle
リストからオブジェクトを取得する。
.
. (R) CWBSO_GetObjAttr
特定の属性データを読み取る。
.
. (R) CWBSO_SetObjAttr
IBM i 属性を更新する。
.
. (R) CWBSO_DeleteObjHandle
オブジェクト・ハンドルを終結処理する。
.
. (R) CWBSO_WaitForObj
リストの次のオブジェクトを待機する。
.
..............
(R)
CWBSO_DeleteParmObjHandle
パラメーター・オブジェクトを削除する。
(O)
CWBSO_CloseList
リストをクローズする。
(R)
CWBSO_DeleteErrorHandle
エラー・オブジェクトを削除する。
418
IBM i: Windows アプリケーション・パッケージ: プログラミング
(R)
CWBSO_DeleteListHandle
リストを削除する
(IBM i の会話を自動的に終了する)。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
サンプル・プログラム: システム・オブジェクトのデータのアクセスと更新:
このサンプル・プログラムを使用して、システム・オブジェクトを更新します。
#include
#include
#include
<windows.h>
<stdlib.h>
"cwbsoapi.h"
// Windows APIs and datatypes
// For atoi
// System Object Access APIs
int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpszCmdLine, int nCmdShow)
{
CWBSO_LIST_HANDLE hList = CWBSO_NULL_HANDLE;
// List handle
CWBSO_ERR_HANDLE hError = CWBSO_NULL_HANDLE;
// Error handle
CWBSO_PARMOBJ_HANDLE hParmObject = CWBSO_NULL_HANDLE; // Parm object
CWBSO_OBJ_HANDLE hObject = CWBSO_NULL_HANDLE; // Object handle
unsigned int
rc, setRC;
// System Object Access return codes
unsigned long
bytesNeeded = 0;
// Bytes needed
unsigned short
errorIndex = 0;
// Error index (SetObjAttr)
char
szString[100]; // Buffer for formatting
int
totalPages = 0;
// Total pages
int
i = 0;
// Loop counter
int
nNbrChanged = 0;
// Count of changed objects
MessageBox(GetFocus(), "Start of Processing", "PRIORITY", MB_OK);
//********************************************************************
// Create a list of spooled files. Set desired filter criteria.
//********************************************************************
// Create a list of spooled files on system SYSNAME
CWBSO_CreateListHandle("SYSNAME",
"APPNAME",
CWBSO_LIST_SFL,
&hList);
// Only include spooled files for device P3812
CWBSO_SetListFilter(hList, CWBSO_SFLF_DeviceFilter, "P3812");
//*******************************************************************
// Open the list.
//*******************************************************************
// Create an error handle
CWBSO_CreateErrorHandle(&hError);
// Open the list of spooled files
rc = CWBSO_OpenList(hList, hError);
// If an error occurred, display a message box
if (rc == CWBSO_ERROR_OCCURRED)
CWBSO_DisplayErrMsg(hError);
else
{
//*****************************************************************
// Set up to change output priority for all objects in the list.
//*****************************************************************
// Create a parameter object to hold the attribute changes
プログラミング
419
CWBSO_CreateParmObjHandle(&hParmObject);
// Set the parameter to change the output priority to ’9’
CWBSO_SetParameter(hParmObject,
CWBSO_SFL_OutputPriority,
"9",
hError);
//******************************************************************
// Loop through the list, changing the output priority for any
// files that have more than 10 total pages. Loop will
// terminate when CWBSO_WaitForObj
// returns CWBSO_BAD_LIST_POSITION, indicating that there
// are no more objects in the list.
//******************************************************************
// Wait for first object in the list
rc = CWBSO_WaitForObj(hList, i, hError);
// Loop through entire list
while (rc == CWBSO_NO_ERROR)
{
// Get the list object at index i
CWBSO_GetObjHandle(hList, i, &hObject, hError);
// Get the total pages attribute for this spooled file
CWBSO_GetObjAttr(hObject,
CWBSO_SFL_TotalPages,
szString,
sizeof(szString),
&bytesNeeded,;
hError);
totalPages = atoi(szString);
// Update the output priority if necessary
if (totalPages > 10)
{
// Change the spool file’s output priority to ’9’
setRC = CWBSO_SetObjAttr(hObject, hParmObject, &errorIndex, hError);
if (setRC == CWBSO_NO_ERROR)
nNbrChanged++;
}
// Delete the object handle
CWBSO_DeleteObjHandle(hObject);
// Increment list item counter
i++;
// Wait for next list object
rc = CWBSO_WaitForObj(hList, i, hError);
} /* end while */
// Parameter object no longer needed
CWBSO_DeleteParmObjHandle(hParmObject);
} /* end if */
// Display the number of spooled files that had priority changed
wsprintf (szString, "Number of spool files changed: %d", nNbrChanged);
MessageBox(GetFocus(), szString, "PRIORITY", MB_OK);
//********************************************************************
420
IBM i: Windows アプリケーション・パッケージ: プログラミング
// Processing complete - clean up and exit.
//********************************************************************
// Close the list
CWBSO_CloseList(hList,hError);
// Clean up handles
CWBSO_DeleteErrorHandle(hError);
CWBSO_DeleteListHandle(hList);
//********************************************************************
// Return from WinMain.
//********************************************************************
return 0;
}
システム・オブジェクト・アクセスのプログラミングに関する考慮事項
SOA のプログラミングに関する重要な考慮事項については、以下のトピックを参照してください。
システム・オブジェクト・アクセスのエラー:
システム・オブジェクト・アクセス API は、戻りコードを使用してエラー条件を報告します。
関数呼び出しごとに、エラーがないかチェックが行われます。それに加え、特定の API では、「エラー・
オブジェクト」のハンドルをそれ自体のインターフェースの中に組み入れています。エラー・オブジェクト
は、要求の処理中に発生したエラーについての追加情報を提供するために使用します。 IBM i オペレーテ
ィング・システムとの対話中に、このようなエラーがしばしば発生しますが、その場合、エラー・オブジェ
クトにエラー・メッセージ・テキストが組み込まれます。
関数呼び出しが CWBSO_ERROR_OCCURRED を戻す場合、エラー・オブジェクトには、エラーを記述す
る情報が入れられます。エラー・メッセージ・テキストを検索するには、CWBSO_GetErrMsgText を使用し
ます。メッセージは、ユーザーの実行環境で指定された言語に翻訳されます。もう 1 つの方法として、
CWBSO_DisplayErrMsg を呼び出すことによって、エラー・メッセージをユーザーに直接表示することがで
きます。
内部処理エラーが発生した場合、エラー・オブジェクトは、製品のインストール・ディレクトリー内に収め
られているシステム・オブジェクト・アクセス・ログ・ファイル soa.log の中に項目を自動的に記録しま
す。このファイルは英語のみで、問題分析のために IBM の担当者が使用するためのものです。
関連資料:
26 ページの『システム・オブジェクト・アクセス API 戻りコード』
以下の SOA API 戻りコードがあります。
システム・オブジェクト・アクセスのアプリケーション・プロファイル:
アプリケーション・プロファイルの使用
デフォルトでは、ユーザー指定のリスト・フィルター基準はディスクに保管されません。システム・オブジ
ェクト・アクセスによって、以下の API が提供されます。
v レジストリーから指定のリスト・オブジェクトの中にフィルター・データをロードするための、アプリ
ケーション固有のレジストリー・キーの使用を要求する API
v 特定のリスト・オブジェクトのデータを、レジストリーに保管する API
プログラミング
421
IBM i 名ごとにデータが保存され、システム名内ではオブジェクト・タイプごとにデータが保存されま
す。プロファイル・データの読み取りまたは書き込みを行うためには、システム名が、リスト・オブジェク
トについての CWBSO_CreateListHandle 呼び出しで指定されている必要があります。
アプリケーション・プログラムのための IBM i 通信セッションの管理:
システム・オブジェクト・アクセス API は、1 つ以上のクライアント/サーバー会話を介してシステムと通
信します。
1 つの会話を確立するために数秒を要することが多いため、リストが初めてオープンされる際に、アプリケ
ーションに遅延が発生することがあります。このトピックでは、会話の開始を制御および管理して、アプリ
ケーション・プログラムに対するパフォーマンスの影響を最小にする方法について説明します。
システム・オブジェクト・アクセスのデフォルトの動作は、次のように要約されます。
v CWBSO_CreateListHandleEx API で識別される IBM i オブジェクトとの間に何も会話が確立していない
場合は、リストがオープンまたは表示される際に会話が自動的に開始されます。指定のシステムとの通
信をまだ確立していない場合は、ダイアログ・ボックスが表示され、適切なユーザー ID とパスワード
を入力するようユーザーに求めるプロンプトが表示されます。
v アプリケーション・プログラムの別のインスタンスが開始されると、上記の過程が繰り返されます。異
なるプロセスで (つまり、異なるインスタンス・ハンドルによって) 稼働しているアプリケーション・プ
ログラム間では、会話の共用は行われません。
v アプリケーション・プログラムが最後のシステム・オブジェクト・アクセス・リストを削除すると、IBM
i の会話は自動的に終了します (CWBSO_CloseList の場合は IBM i の会話を終了しないので、注意して
ください)。
システム・オブジェクト・アクセスの会話は、cwbRC_StartSysEx API を使用して開始することができま
す。この API は、IBM i オブジェクトをパラメーターとして受け入れ、システム・ハンドルを戻します。
このハンドルを保存して、後で cwbRC_StopSys API で使用してください (アプリケーションが終了し、
IBM i の会話を終了させるとき)。
cwbRC_StartSysEx API が呼び出されると、会話が確立するまでアプリケーションは停止します。そのた
め、呼び出しのすぐ前に、接続が行われようとしていることをユーザーに通知することをお勧めします。呼
び出しに対して応答が戻された時点で、会話は開始済みの状態になります。システム・オブジェクト・アク
セスのリスト処理では、新規の会話を開始する代わりに、この会話を使用します。
cwbRC_StartSysEx がこのように使用される場合、最後のリストが削除されても会話は終了されません。ア
プリケーションを終了する前に、cwbRC_StopSys を明示的に呼び出す必要があります。
システム・オブジェクト・アクセス API のリスト
以下のシステム・オブジェクト・アクセス API が、アルファベット順にリストされています。
SOA イネーブラー
システム・オブジェクト・アクセスには、イネーブラー (API) も含まれます。アプリケーションは、これ
らのイネーブラーを使用してシステム・オブジェクト内のデータにアクセスしたり、グラフィカル・リス
ト、ならびに、オブジェクト・データの属性ビューを要求することができます。オブジェクトのリストを操
作する API は、正しい順序で呼び出す必要があります。基本的なフローは以下のとおりです。
CreateErrorHandle - 他の API に渡すエラー・オブジェクトのハンドルを作成する。
CreateListHandle -- クライアント上のリスト・オブジェクトのインスタンスを作成する。
OpenList -- クライアント・リストに関連した IBM i リストを構築する。
422
IBM i: Windows アプリケーション・パッケージ: プログラミング
(さまざまな汎用のサブクラス API を使用して、リストとそのオブジェクトを操作する)
CloseList -- リストをクローズして IBM i 資源を解放する。
DeleteListHandle - クライアント上のリスト・オブジェクトを破棄する。
CWBSO_CreateListHandleAPI を呼び出してリストを作成した後に、他のリスト API を呼び出すようにする
必要があります。 CWBSO_CreateListHandle API は、リスト・ハンドルを呼び出し側に戻します。リス
ト・ハンドルは、他のすべてのリスト API への入力として渡されなければなりません。
リストが割り振られた後で、CWBSO_SetListFilterAPI を呼び出してそのリストのフィルター基準を変更す
ることができます。 CWBSO_SetListFilter はオプションで、これを呼び出さなかった場合は、デフォルト
のフィルター基準を使用してリストが作成されます。同様に、CWBSO_SetListSortFields API を呼び出し
て、リストのソートの基準に使用される属性を定義することができます。これが呼び出されないと、リスト
はソートされません。
オブジェクトのリストを作成するには、CWBSO_OpenList API を呼び出す必要があります。これによって
作成された要求が、システムに送信されます。リストは、そのシステム上に作成され、リスト内の一部また
はすべてのオブジェクト (レコード) は、バッファーに入れられ、クライアントのリスト内に収められま
す。リストにあるオブジェクトすべてがクライアントでキャッシュされるとは限りませんが、API は、す
べてがキャッシュされるかのように動作します。CWBSO_OpenList API が正常に呼び出された後、次の
API を呼び出すことができます。
CWBSO_GetObjHandle
リスト内の特定のオブジェクトのハンドルを検索します。このオブジェクト・ハンドルはその後、
特定のオブジェクトを操作するために使用することができます。
CWBSO_DeleteObjHandle
CWBSO_GetObjHandle によって戻されたハンドルを解放します。
CWBSO_DisplayList
リストのスプレッドシート・ビューを表示します。
CWBSO_GetListSize
リスト内のオブジェクト数を検索します。
CWBSO_CloseList
IBM i リストをクローズし、リスト内のクライアント・オブジェクトをすべて破棄します。リスト
がクローズされた後は、CWBSO_GetListObject によって戻されたオブジェクト・ハンドルはすべて
無効になります。リストがクローズされた後は、CWBSO_OpenList API を再度呼び出すまでそのリ
スト内の API を呼び出すことはできません。リスト・オブジェクトを破棄するには、
CWBSO_DeleteListHandle API を呼び出す必要があります。
CWBSO_CloseList:
CWBSO_CloseList API は、この製品と共に使用します。
目的
オブジェクトのリストをクローズし、IBM i に割り振られた資源を解放します。
構文
unsigned int CWB_ENTRY CWBSO_CloseList(
CWBSO_LIST_HANDLE listHandle,
CWBSO_ERR_HANDLE errorHandle);
プログラミング
423
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
CWBSO_ERR_HANDLE errorHandle - input
以前の CWBSO_CreateErrorHandle の呼び出しによって戻されたエラーのハンドル。この API で戻さ
れた値が CWBSO_ERROR_OCCURRED である場合、エラー・ハンドルを使って、エラー・メッセー
ジ・テキストの検索、またはユーザーへのエラーの表示を行うことができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。リストは現在オープンされている必要があります。リストは、CWBSO_OpenList を呼び出してオー
プンします。この API によって、IBM i の会話を終了させることはできません。会話を終了させるには、
CWBSO_DeleteListHandle を使用して、リストを削除する必要があります。
CWBSO_CopyObjHandle:
CWBSO_CopyObjHandle API は、この製品と共に使用します。
目的
オブジェクトの新しいインスタンスを作成し、新しいインスタンスへのハンドルを戻します。これは、新規
システム・オブジェクトを作成するものではなく、単にクライアント上にシステム・オブジェクトの追加イ
ンスタンスを作成するものです。 CWBSO_GetObjHandle によって戻されるオブジェクト・ハンドルは、そ
のオブジェクトが収められているリストがクローズされる時点で必ず破棄されます。この API によって、
リストがクローズされた後も持続するオブジェクトのインスタンスの作成が可能になります。この API に
よって作成されたオブジェクト・インスタンスは、リストのオブジェクトと同期が保たれます。言いかえれ
ば、オブジェクトの 1 つが変更される場合、その変更は別のオブジェクトでも見ることができます。
424
IBM i: Windows アプリケーション・パッケージ: プログラミング
構文
unsigned int CWB_ENTRY CWBSO_CopyObjHandle(
CWBSO_OBJ_HANDLE objectHandle,
CWBSO_OBJ_HANDLE far* lpNewObjectHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
CWBSO_OBJ_HANDLE far* lpNewObjectHandle - output
同じシステム・オブジェクトの新しいハンドルに設定されるハンドルを指す、long 型のポインター。
このハンドルは、オブジェクト・ハンドルを受け入れる他の API でも使用できますが、API によって
は特定のタイプのオブジェクトにしか機能しないものもあります。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_BAD_OBJ_HANDLE
指定されたオブジェクト・ハンドルが無効。
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。オブジェクトが不要になったら、呼び出し側プログラムで
は、次の操作を行う必要があります。
v CWBSO_DeleteObjHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_CreateErrorHandle:
CWBSO_CreateErrorHandle API は、この製品と共に使用します。
目的
エラー・ハンドルを作成します。エラー・ハンドルは、他の API から戻されたエラー・メッセージを入手
するために使用します。エラー・ハンドルを使用して、エラーをダイアログで表示したり、関連するエラ
ー・メッセージ・テキストを検索することができます。
構文
unsigned int CWB_ENTRY CWBSO_CreateErrorHandle(
CWBSO_ERR_HANDLE far* lpErrorHandle);
プログラミング
425
パラメーター
CWBSO_ERR_HANDLE far* lpErrorHandle - output
エラーのためのハンドルに設定されるハンドルを指す long 型のポインター。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
使用法
エラー・ハンドルが不要になった後、呼び出したプログラムでは、次の操作を行う必要があります。
v CWBSO_DeleteErrorHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_CreateListHandle:
CWBSO_CreateListHandle API は、この製品と共に使用します。
目的
新しいリストを作成し、そのリストのハンドルを戻します。
構文
unsigned int CWB_ENTRY CWBSO_CreateListHandle(
char far* lpszSystemName,
char far* lpszApplicationName,
CWBSO_LISTTYPE type,
CWBSO_LIST_HANDLE far* lpListHandle);
パラメーター
char far* lpszSystemName - input
リストが作成される IBM i の名前。この名前には、構成済みシステムの名前を指定する必要がありま
す。現時点でクライアントが対象のシステムに接続されていない場合には、リストのオープン時に
IBM i 接続が確立されます。システム名に NULL が指定されていると、現行の IBM i Access のデフ
ォルト・システムが使用されます。
char far* lpszApplicationName - input
リストと対話するアプリケーションを識別する文字ストリング。このストリングの最大長は、NULL 終
了文字を除いた 10 文字です。
CWBSO_LISTTYPE type - input
作成するリストのタイプ。下記のうちのいずれかを指定します。
CWBSO_LIST_JOB
ジョブのリスト。
CWBSO_LIST_SJOB
サーバー・ジョブのリスト。
426
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_LIST_SJOB
サーバー・ジョブのリスト。
CWBSO_LIST_MSG
メッセージのリスト。
CWBSO_LIST_PRT
プリンターのリスト。
CWBSO_LIST_SFL
スプール・ファイルのリスト。
CWBSO_LIST_IFC
インターフェースのリスト。
CWBSO_LIST_ELN
イーサネット回線のリスト。
CWBSO_LIST_TLN
トークンリング回線のリスト。
CWBSO_LIST_HWL
ハードウェア資源のリスト。
CWBSO_LIST_SW
ソフトウェア・プロダクトのリスト。
CWBSO_LIST_RTE
TCP/IP 経路のリスト。
CWBSO_LIST_PRF
ユーザー・プロファイルのリスト。
CWBSO_LIST_SMP
QSYS のライブラリーのリスト。
CWBSO_LIST_HANDLE far* lpListHandle - output
新しく作成されたリストのハンドルに設定されるハンドルを指す long 型のポインター。このハンドル
は、リスト・ハンドルを受け入れる他の API で使用できます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LISTTYPE
リストのタイプに指定した値が無効です。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_BAD_SYSTEM_NAME
指定されたシステム名が、有効な IBM i 名ではありません。
プログラミング
427
使用法
リストが必要ではなくなったとき、呼び出し側プログラムでは次の操作を行う必要があります。
v CWBSO_DeleteListHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_CreateListHandleEx:
CWBSO_CreateListHandleEx API は、この製品と共に使用します。
目的
新しいリストを作成し、そのリストのハンドルを戻します。
構文
unsigned int CWB_ENTRY CWBSO_CreateListHandleEx(
cwbCO_SysHandle systemObjectHandle,
CWBSO_LISTTYPE type,
CWBSO_LIST_HANDLE far* lpListHandle);
パラメーター
cwbCO_SysHandle systemObjectHandle - input
リストの作成場所であるシステムを表す、システム・オブジェクトのハンドル。この IBM i ハンドル
は、構成済みのシステムに対するものでなければなりません。
CWBSO_LISTTYPE
作成するリストのタイプ。下記のうちのいずれかを指定します。
CWBSO_LIST_JOB
ジョブのリスト。
CWBSO_LIST_SJOB
サーバー・ジョブのリスト。
CWBSO_LIST_SJOB
サーバー・ジョブのリスト。
CWBSO_LIST_MSG
メッセージのリスト。
CWBSO_LIST_PRT
プリンターのリスト。
CWBSO_LIST_SFL
スプール・ファイルのリスト。
CWBSO_LIST_IFC
インターフェースのリスト。
CWBSO_LIST_ELN
イーサネット回線のリスト。
CWBSO_LIST_TLN
トークンリング回線のリスト。
CWBSO_LIST_HWL
ハードウェア資源のリスト。
428
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_LIST_SW
ソフトウェア・プロダクトのリスト。
CWBSO_LIST_RTE
TCP/IP 経路のリスト。
CWBSO_LIST_PRF
ユーザー・プロファイルのリスト。
CWBSO_LIST_SMP
QSYS のライブラリーのリスト。
CWBSO_LIST_HANDLE far* lpListHandle - output
新しく作成されたリストのハンドルに設定されるハンドルを指す long 型のポインター。このハンドル
は、リスト・ハンドルを受け入れる他の API で使用できます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LISTTYPE
リストのタイプに指定した値が無効です。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_BAD_SYSTEM_NAME
指定されたシステム名が、有効な IBM i 名ではありません。
使用法
リストが必要ではなくなったとき、呼び出し側プログラムでは次の操作を行う必要があります。
v CWBSO_DeleteListHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_CreateObjHandle:
CWBSO_CreateObjHandle API は、この製品と共に使用します。
目的
新規のオブジェクト・ハンドルを作成し、そのオブジェクトのハンドルを戻します。この API は、リスト
形式に従っていないリモート・オブジェクトにアクセスする場合に使用します。
構文
unsigned int CWB_ENTRY CWBSO_CreateObjHandle(
char far* lpszSystemName,
char far* lpszApplicationName,
CWBSO_OBJTYPE type,
CWBSO_OBJ_HANDLE far* lpObjHandle);
パラメーター
char far* lpszSystemName - input
オブジェクトが作成されるシステムの名前。この名前には、構成済みシステムの名前を指定する必要が
プログラミング
429
あります。現時点でクライアントが接続されていない場合には、リストのオープン時に IBM i 接続が
確立されます。システム名に NULL が指定されていると、現行の IBM i のデフォルト・システムが
使用されます。
char far* lpszApplicationName - input
リストと対話するアプリケーションを識別する文字ストリング。このストリングの最大長は、NULL 終
了文字を除いた 10 文字です。
CWBSO_OBJTYPE type - input
作成するオブジェクトのタイプ。次のように指定します。
v CWBSO_OBJ_TCIPATTR - TCP/IP 属性
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_BAD_SYSTEM_NAME
指定されたシステム名が、有効な IBM i 名ではありません。
使用法
リストが必要ではなくなったとき、呼び出し側プログラムでは次の操作を行う必要があります。
v CWBSO_DeleteObjHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_CreateParmObjHandle:
CWBSO_CreateParmObjHandle API は、この製品と共に使用します。
目的
パラメーター・オブジェクトを作成し、そのオブジェクトのハンドルを戻します。パラメーター・オブジェ
クトには、一連のパラメーター ID および他の API への入力として渡すことができる値が入っています。
構文
unsigned int CWB_ENTRY CWBSO_CreateParmObjHandle(
CWBSO_PARMOBJ_HANDLE far* lpParmObjHandle);
パラメーター
CWBSO_PARMOBJ_HANDLE far* lpParmObjHandle - output
新しいパラメーター・オブジェクトのためのハンドルに設定されるハンドルを指す long 型のポインタ
ー。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
430
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
使用法
パラメーター・オブジェクトが必要でなくなった後、呼び出したプログラムでは次の操作を行う必要があり
ます。
v CWBSO_DeleteParmObjHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_DeleteErrorHandle:
CWBSO_DeleteErrorHandle API は、この製品と共に使用します。
目的
エラー・ハンドルを削除し、クライアントに割り振られた資源を解放します。
構文
unsigned int CWB_ENTRY CWBSO_DeleteErrorHandle(
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_ERR_HANDLE errorHandle - input
以前の CWBSO_CreateErrorHandle の呼び出しによって戻されるエラー・ハンドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
使用法
この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。
CWBSO_DeleteListHandle:
CWBSO_DeleteListHandle API は、この製品と共に使用します。
目的
オブジェクトのリストを削除し、クライアントに割り振られた資源を解放します。
構文
unsigned int CWB_ENTRY CWBSO_DeleteListHandle(
CWBSO_LIST_HANDLE listHandle);
プログラミング
431
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。
CWBSO_DeleteObjHandle:
CWBSO_DeleteObjHandle API は、この製品と共に使用します。
目的
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しから戻されたオブジェクト・ハ
ンドルを削除します。
構文
unsigned int CWB_ENTRY CWBSO_DeleteObjHandle(
CWBSO_OBJ_HANDLE objectHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_OBJ_HANDLE
指定されたオブジェクト・ハンドルが無効。
432
IBM i: Windows アプリケーション・パッケージ: プログラミング
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。
CWBSO_DeleteParmObjHandle:
CWBSO_DeleteParmObjHandle API は、この製品と共に使用します。
目的
パラメーター・オブジェクト・ハンドルを削除し、クライアントに割り振られた資源を解放します。
構文
unsigned int CWB_ENTRY CWBSO_DeleteParmObjHandle(
CWBSO_PARMOBJ_HANDLE parmObjHandle);
パラメーター
CWBSO_PARMOBJ_HANDLE parmObjHandle - input
以前の CWBSO_CreateParmObjHandle の呼び出しによって戻されたパラメーター・オブジェクトのハン
ドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_PARMOBJ_HANDLE
指定されたパラメーター・オブジェクト・ハンドルが無効です。
使用法
この API を呼び出す前に、CWBSO_CreateParmObjHandle を呼び出す必要があります。
CWBSO_CreateParmObjHandle で戻されたパラメーター・オブジェクト・ハンドルをこの API への入力と
して渡す必要があるためです。
CWBSO_DisallowListActions:
CWBSO_DisallowListActions API は、この製品と共に使用します。
目的
リスト内のオブジェクトに対するユーザーの実行が許可されないアクションを設定します。これは、
CWBSO_DisplayList を呼び出してリストを表示する時点で使用可能になるアクションに影響します。使用
禁止にされたアクションは、メニュー・バー、ツールバー、またはオブジェクトのポップアップ・メニュー
には表示されません。この API は 1 つのリストにつき 1 回のみ呼び出すことができ、リストを表示する
前に呼び出さなくてはなりません。
プログラミング
433
構文
unsigned int CWB_ENTRY CWBSO_DisallowListActions(
CWBSO_LIST_HANDLE listHandle,
unsigned short far* lpusActionIDs,
unsigned short usCount);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
unsigned short far* lpusActionIDs - input
アクション識別コードの値の配列を指す long 型のポインター。これらの値は、ユーザーによる実行が
認められていないアクションを示します。このパラメーターの有効な値は、リストのオブジェクトのタ
イプによって決まります。有効な値については、下記の該当するヘッダー・ファイルを参照してくださ
い。
v cwbsojob.h
v cwbsomsg.h
v cwbsoprt.h
v cwbsosfl.h
unsigned short usCount - input
指定されたアクション識別コードの値の数。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ACTION_ID
指定されたアクション ID がこのリストのタイプに対しては無効です。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_NOT_ALLOWED_NOW
要求されたアクションは、現在許可されていません。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。
CWBSO_DisallowListFilter:
CWBSO_DisallowListFilter API は、この製品と共に使用します。
434
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
リストのフィルター値をユーザーが変更できないようにリストを設定します。これによって、リストが表示
されるときに「オプション」のプルダウン・メニューから「組み込み」を選択できなくなります。リスト
は、CWBSO_DisplayList を呼び出して表示します。この API が意味を持つのは、CWBSO_DisplayList API
を使用して表示されるリストについてのみです。この API は 1 つのリストにつき 1 回のみ呼び出すこと
ができ、リストを表示する前に呼び出さなくてはなりません。
構文
unsigned int CWB_ENTRY CWBSO_DisallowListFilter(
CWBSO_LIST_HANDLE listHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。
CWBSO_DisplayErrMsg:
CWBSO_DisplayErrMsg API は、この製品と共に使用します。
目的
エラー・メッセージをダイアログ・ボックスに表示します。この API は、別の API の呼び出しからの戻
り値として CWBSO_ERROR_OCCURRED が返されたときにのみ呼び出してください。この場合、エラ
ー・ハンドルに関連したエラー・メッセージがあります。
構文
unsigned int CWB_ENTRY CWBSO_DisplayErrMsg(
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_ERR_HANDLE errorHandle - input
エラーのハンドル。
プログラミング
435
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_NO_ERROR_MESSAGE
指定されたエラー・ハンドルにエラー・メッセージが入っていません。
CWBSO_DISP_MSG_FAILED
メッセージの表示要求が失敗しました。
使用法
この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。
CWBSO_DisplayList:
CWBSO_DisplayList API は、この製品と共に使用します。
目的
リストをウィンドウに表示します。ユーザーは、このウィンドウから、リスト内のオブジェクトに対してア
クションを行うことができます。
構文
unsigned int CWB_ENTRY CWBSO_DisplayList(
CWBSO_LIST_HANDLE listHandle,
HINSTANCE hInstance,
int nCmdShow,
HWND far* lphWnd ,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
HINSTANCE hInstance - input
呼び出し側プログラムの WinMain プロシージャーに渡されたプログラム・インスタンス。
int nCmdShow - input
呼び出し側プログラムの WinMain プロシージャーに渡されたウィンドウ表示パラメーター。その代わ
りとして、Windows API ShowWindow() 用に定義された定数のいずれかを使用することができます。
HWND far* lphWnd - output
ウィンドウ・ハンドルを指す long 型のポインター。これは、リストが表示されるウィンドウのハンド
ルに設定されます。
436
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用して、エラー・メッセージ・テキストを検索したり、エラーをユーザーに表示したりすることができ
ます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_DISPLAY_FAILED
ウィンドウが作成できませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。この API を使用する場合、CWBSO_OpenList または CWBSO_CloseList を呼び出す必要はありませ
ん。CWBSO_DisplayList が、リストのオープンとクローズの両方を処理します。システム・オブジェク
ト・リストの使用中に送られる Windows メッセージを受け取るためには、プログラムにメッセージ・ルー
プが必要です。
この API は、ジョブ、メッセージ、プリンター、プリンター出力、およびスプール・ファイルの各リス
ト・タイプにのみ適用されます。
CWBSO_DisplayObjAttr:
CWBSO_DisplayObjAttr API は、この製品と共に使用します。
目的
オブジェクトについて属性ウィンドウを表示します。このウィンドウから、ユーザーはオブジェクトの属性
を表示したり、変更可能な属性を変更することが可能になります。
構文
unsigned int CWB_ENTRY CWBSO_DisplayObjAttr(
CWBSO_OBJ_HANDLE objectHandle,
プログラミング
437
HINSTANCE hInstance,
int nCmdShow,
HWND far* lphWnd ,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
HINSTANCE hInstance - input
呼び出し側プログラムの WinMain プロシージャーに渡されたプログラム・インスタンス。
int nCmdShow - input
呼び出し側プログラムの WinMain プロシージャーに渡されたウィンドウ表示パラメーター。その代わ
りとして、Windows API ShowWindow() 用に定義された定数のいずれかを使用することができます。
HWND far* lphWnd - output
ウィンドウ・ハンドルを指す long 型のポインター。これは、オブジェクト属性が表示されるウィンド
ウのハンドルに設定されます。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_OBJ_HANDLE
指定されたオブジェクト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_DISPLAY_FAILED
ウィンドウが作成できませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を
呼び出す必要があります。CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の
入力として渡す必要があります。システム・オブジェクトの属性ウィンドウの使用中に送られる Windows
メッセージを受け取るためには、プログラムにメッセージ・ループが必要です。
438
IBM i: Windows アプリケーション・パッケージ: プログラミング
この API は、ジョブ、メッセージ、プリンター、プリンター出力、およびスプール・ファイルの各リス
ト・タイプにのみ適用されます。
CWBSO_GetErrMsgText:
CWBSO_GetErrMsgText API は、この製品と共に使用します。
目的
エラー・ハンドルからメッセージ・テキストを検索します。この API は、別の API の呼び出しからの戻
り値として CWBSO_ERROR_OCCURRED が返されたときにのみ呼び出してください。この場合、エラ
ー・ハンドルに関連したエラー・メッセージがあります。
構文
unsigned int CWB_ENTRY CWBSO_GetErrMsgText(
CWBSO_ERR_HANDLE errorHandle ,
char far* lpszMsgBuffer ,
unsigned long ulBufferLength,
unsigned long far* lpulBytesNeeded);
パラメーター
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
char far* lpszMsgBuffer - output
メッセージ・テキストが入れられる出力バッファーを指す long 型のポインター。この API によって
戻されたメッセージ・テキストは、変換されたテキストです。戻りコードが CWBSO_NO_ERROR に
設定されない場合、出力バッファーは変更されません。
unsigned long ulBufferLength - input
出力バッファー引数のバイトでのサイズ。
unsigned long far* lpulBytesNeeded - output
出力バッファーにメッセージ・テキスト全体を入れるために必要なバイト数に設定される、符号なし長
精度整数を指す long 型のポインター。この値が、指定された出力バッファーのサイズと等しいかこれ
より小さいと、メッセージ・テキスト全体が出力バッファーに入れられます。この値が、指定された出
力バッファーのサイズより大きいと、出力バッファーには NULL ストリングが入ります。メッセー
ジ・テキストに必要なバイト数を超えて、出力バッファーが変更されることはありません。戻りコード
が CWBSO_NO_ERROR に設定されない場合、この値はゼロに設定されます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_NO_ERROR_MESSAGE
指定されたエラー・ハンドルにエラー・メッセージが入っていません。
プログラミング
439
CWBSO_GET_MSG_FAILED
エラー・メッセージのテキストを検索できませんでした。
使用法
この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。 IBM i エラーに関するメッセージ・テキストは、ユーザーの実行環境用に指定された言語で表示さ
れます。その他のメッセージ・テキストはすべて、ユーザーのパーソナル・コンピューターの Windows コ
ントロール・パネルで指定された言語で表示されます。
CWBSO_GetListSize:
CWBSO_GetListSize API は、この製品と共に使用します。
目的
リスト内のオブジェクトの数を検索します。
構文
unsigned int CWB_ENTRY CWBSO_GetListSize(
CWBSO_LIST_HANDLE listHandle,
unsigned long far* lpulSize,
unsigned short far* lpusStatus,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
unsigned long far* lpulSize - output
現在リスト内にある項目の数に設定される無符号長精度整数を指す long 型のポインター。リスト状況
がリストが完全に作成されていることを示している場合、この値はリストのオブジェクトの合計数を表
します。リスト状況がリストが完全に作成されていないことを示している場合、この値は、現在ホスト
から利用できるオブジェクトの数を表しており、これ以降にこの API を呼び出すと、これより多くの
項目が利用可能であると示される可能性があります。
unsigned short far* lpusStatus - output
リストが完全に作成されているかどうかを示すために設定される符号なしの短精度整数を指す long 型
ポインター。リストが完全に作成されていない場合、この値は 0 に設定され、リストが完全に作成さ
れている場合、値は 1 に設定されます。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
440
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。リストは現在オープンされている必要があります。リストは、CWBSO_OpenList を呼び出してオー
プンします。 CWBSO_CloseList を呼び出してリストをクローズする場合は、CWBSO_OpenList を再度呼
び出さなければ、この API を呼び出すことができません。
CWBSO_GetObjAttr:
CWBSO_GetObjAttr API は、この製品と共に使用します。
目的
オブジェクトから属性の値を検索します。
構文
unsigned int CWB_ENTRY CWBSO_GetObjAttr(
CWBSO_OBJ_HANDLE objectHandle,
unsigned short usAttributeID,
char far* lpszBuffer,
unsigned long ulBufferLength,
unsigned long far* lpulBytesNeeded,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
unsigned short usAttributeID - input
検索すべき属性の識別コード。このパラメーターの有効な値は、オブジェクトのタイプによって決まり
ます。有効な値については、下記の該当するヘッダー・ファイルを参照してください。
v cwbsojob.h
v cwbsomsg.h
v cwbsoprt.h
v cwbsosfl.h
プログラミング
441
char far* lpszBuffer - output
属性値が入れられる出力バッファーを指す long 型のポインター。この API によって戻された値は、
変換されたストリングではありません。例えば、スプール・ファイルの終了ページ属性の場合、「終了
ページ」ではなく、「*END」が戻されます。それぞれのオブジェクトのタイプごとに戻される可能性
のある特殊値については、 456 ページの『SOA 属性の特殊値』を参照してください。戻りコードが
CWBSO_NO_ERROR に設定されない場合、出力バッファーは変更されません。
unsigned long ulBufferLength - input
出力バッファー引数のバイトでのサイズ。
unsigned long far* lpulBytesNeeded - output
出力バッファーに属性値全体を入れるのに必要なだけのバイト数に設定される無符号長精度整数を指す
long 型のポインター。この値が、指定された出力バッファーのサイズと等しいかこれより小さいと、
属性値全体が出力バッファーに入れられます。この値が、指定された出力バッファーのサイズより大き
いと、出力バッファーには NULL ストリングが入ります。属性値に必要なバイト数を超えて、出力バ
ッファーが変更されることはありません。戻りコードが CWBSO_NO_ERROR に設定されない場合、
この値はゼロに設定されます。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_OBJ_HANDLE
指定されたオブジェクト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_BAD_ATTRIBUTE_ID
属性キーがこのオブジェクトに対して無効。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を
呼び出す必要があります。CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の
入力として渡す必要があります。
CWBSO_GetObjHandle:
CWBSO_GetObjHandle API は、この製品と共に使用します。
442
IBM i: Windows アプリケーション・パッケージ: プログラミング
目的
リスト内のオブジェクトのハンドルを取得します。この API によって戻されたオブジェクト・ハンドル
は、リストがクローズされるまで、またはオブジェクト・ハンドルが削除されるまで有効です。このオブジ
ェクト・ハンドルは、以下の API を呼び出す際に使用されます。
v CWBSO_CopyObjHandle
v CWBSO_DeleteObjHandle
v CWBSO_DisplayObjAttr
v CWBSO_GetObjAttr
v CWBSO_RefreshObj
v CWBSO_SetObjAttr
v CWBSO_WaitForObj
構文
unsigned int CWB_ENTRY CWBSO_GetObjHandle(
CWBSO_LIST_HANDLE listHandle,
unsigned long ulPosition,
CWBSO_OBJ_HANDLE far* lpObjectHandle,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
unsigned long ulPosition - input
ハンドルが必要な、リスト内のオブジェクトの位置。注: リスト内の最初のオブジェクトは、位置 0
と見なされます。
CWBSO_OBJ_HANDLE far* lpObjectHandle - output
IBM i オブジェクトのハンドルに設定されるハンドルを指す、long 型のポインター。このハンドル
は、オブジェクト・ハンドルを受け入れる他の API でも使用できますが、API によっては特定のタイ
プのオブジェクトにしか機能しないものもあります。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
プログラミング
443
CWBSO_BAD_LIST_POSITION
指定されたリスト内の位置が無効です。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。リストは現在オープンされている必要があります。リストは、CWBSO_OpenList を呼び出してオー
プンします。 CWBSO_CloseList を呼び出してリストをクローズする場合は、CWBSO_OpenList を再度呼
び出さなければ、この API を呼び出すことができません。この API を使用するとき、オブジェクトがリ
ストに組み込まれるまでそのオブジェクトにアクセスすることはできません。例えば、CWBSO_OpenList
を呼び出した直後に、位置 100 にあるオブジェクトをこの API を出して取得しようとしても、オブジェ
クトはすぐには利用可能とならない場合があります。そのような場合には、CWBSO_WaitForObj を使用
し、オブジェクトが利用可能になるまで待機します。この API によって戻されるオブジェクト・ハンドル
は、後続の CWBSO_DeleteObjHandle の呼び出しによって削除する必要があります。
CWBSO_OpenList:
CWBSO_OpenList API は、この製品と共に使用します。
目的
リストをオープンします。リスト作成の要求が、システムに送信されます。
構文
unsigned int CWB_ENTRY CWBSO_OpenList(
CWBSO_LIST_HANDLE listHandle,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
CWBSO_ERR_HANDLE errorHandle - input
以前の CWBSO_CreateErrorHandle の呼び出しによって戻されたエラーのハンドル。この API で戻さ
れた値が CWBSO_ERROR_OCCURRED である場合、エラー・ハンドルを使って、エラー・メッセー
ジ・テキストの検索、またはユーザーへのエラーの表示を行うことができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
444
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。リストが必要ではなくなったとき、呼び出し側プログラムでは次の操作を行う必要があります。
v CWBSO_CloseList を呼び出して、リストをクローズし、割り振られている資源を解放する。
v CWBSO_DeleteListHandle を呼び出して、クライアントに割り振られている資源を解放する。
CWBSO_ReadListProfile:
CWBSO_ReadListProfile API は、この製品と共に使用します。
目的
リストに関するフィルター情報を、Windows レジストリーから読み取ります。ユーザーは、
CWBSO_SetListProfile API を使用してアプリケーション名を設定しておかなければなりません。この API
は、CWBSO_OpenList または CWBSO_DisplayList API を使用して、リストをオープンする前に呼び出す
必要があります。
構文
unsigned int CWB_ENTRY CWBSO_ReadListProfile(
CWBSO_LIST_HANDLE listHandle,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
CWBSO_ERR_HANDLE errorHandle - input
以前の CWBSO_CreateErrorHandle の呼び出しによって作成されたエラー・オブジェクトのハンドル。
この API で戻された値が CWBSO_ERROR_OCCURRED である場合、エラー・ハンドルを使って、エ
ラー・メッセージ・テキストの検索、またはユーザーへのエラーの表示を行うことができます。
戻りコード
以下は、共通の戻り値です。
プログラミング
445
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_SYSTEM_NAME_DEFAULTED
そのリストに関する CWBSO_CreateListHandle 呼び出しでシステム名が指定されませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、CWBSO_SetListProfile を呼び出す必要があります。この API は、既
にオープンされているリストに対しては有効とはなりません。プロファイルのフィルター基準を有効にする
ためには、この API を呼び出した後でリストをオープンする必要があります。
CWBSO_RefreshObj:
CWBSO_RefreshObj API は、この製品と共に使用します。
目的
オブジェクトの IBM i 属性をリフレッシュします。オブジェクトについてオープンしているシステム・オ
ブジェクト・アクセス・ビューをすべてリフレッシュします。
構文
unsigned int CWB_ENTRY CWBSO_RefreshObj(
CWBSO_OBJ_HANDLE objectHandle,
HWND hWnd ,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
HWND hWnd - input
リフレッシュが完了した後にフォーカスを受け取るウィンドウのハンドル。このパラメーターは NULL
にすることができます。この API がアプリケーション・ウィンドウ・プロシージャーから呼び出され
ていた場合は、現行のウィンドウ・ハンドルを与える必要があります。これを実行しない場合、フォー
カスは、最後にオープンされたオープン状態のシステム・オブジェクト・アクセス・ウィンドウにシフ
トします。
446
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_OBJ_HANDLE
指定されたオブジェクト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を
呼び出す必要があります。CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の
入力として渡す必要があります。
CWBSO_ResetParmObj:
CWBSO_ResetParmObj API は、この製品と共に使用します。
目的
オブジェクトから属性値を取り除くために、パラメーター・オブジェクトをリセットします。
構文
unsigned int CWB_ENTRY CWBSO_ResetParmObj(
CWBSO_PARMOBJ_HANDLE parmObjHandle);
パラメーター
CWBSO_PARMOBJ_HANDLE parmObjHandle - input
以前の CWBSO_CreateParmObjHandle の呼び出しによって戻されたパラメーター・オブジェクトのハン
ドル。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
プログラミング
447
CWBSO_BAD_PARMOBJ_HANDLE
パラメーター・オブジェクト・ハンドルが無効です。
使用法
この API を呼び出す前に、CWBSO_CreateParmObjHandle を呼び出す必要があります。
CWBSO_CreateParmObjHandle で戻されたパラメーター・オブジェクト・ハンドルをこの API への入力と
して渡す必要があるためです。
CWBSO_SetListFilter:
CWBSO_SetListFilter API は、この製品と共に使用します。
目的
リストのフィルター値を設定します。リストのタイプによって、さまざまなフィルター値の設定が可能で
す。フィルター値では、CWBSO_OpenList によってリストが作成される時点で、そのリストに組み込むオ
ブジェクトを制御します。
構文
unsigned int CWB_ENTRY CWBSO_SetListFilter(
CWBSO_LIST_HANDLE listHandle,
unsigned short usFilterID,
char far* lpszValue);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
unsigned short usFilterID - input
フィルターのどの部分が設定されるかを指定するフィルター識別コード。このパラメーターの有効な値
は、リストのオブジェクトのタイプによって決まります。有効な値については、下記の該当するヘッダ
ー・ファイルを参照してください。
v cwbsojob.h
v cwbsomsg.h
v cwbsoprt.h
v cwbsosfl.h
char far* lpszValue - input
フィルター属性の値。複数の項目を指定する場合、それらをコンマで区切らなければなりません。シス
テム・オブジェクト名を指定するフィルター値項目は、大文字でなければなりません。修飾オブジェク
ト名は、ライブラリー / オブジェクトの形式にする必要があります。修飾ジョブ名は、ジョブ番号 /
ユーザー / ジョブ名の形式にする必要があります。特殊値 (アスタリスクで始まる) を指定するフィル
ター値項目は、大文字で指定する必要があります。それぞれのオブジェクトのタイプごとに指定できる
特殊値については、 456 ページの『SOA 属性の特殊値』を参照してください。
戻りコード
以下は、共通の戻り値です。
448
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_FILTER_ID
指定のフィルター ID がこのリストのタイプに対して無効です。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API は、既にオープンされているリストに対しては有効とはなりません。フィルター基準を
有効とするためには、この API を呼び出した後でリストをオープンする必要があります。複雑なフィルタ
ーを要求すると、リストのパフォーマンスを低下させることがあるため、注意が必要です。
CWBSO_SetListProfile:
CWBSO_SetListProfile API は、この製品と共に使用します。
目的
アプリケーション名を Windows レジストリーに追加することによって、プロファイル名を設定します。リ
ストを表示する前に、CWBSO_ReadListProfile を使用して、レジストリーからフィルター情報を読み取りま
す。また、リストを削除する前に、CWBSO_WriteListProfile を使用して、更新済みのフィルター情報をレ
ジストリーに書き込みます。この API を呼び出さないと、CWBSO_ReadListProfile と
CWBSO_WriteListProfile は有効となりません。
構文
unsigned int CWB_ENTRY CWBSO_SetListProfile(
CWBSO_LIST_HANDLE listHandle,
char far* lpszKey);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
char far* lpszKey - input
リストに関する Windows レジストリー内でのキーとして使用されるストリングを指す long 型のポイ
ンター。この名前は、アプリケーション名の場合もあります。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
プログラミング
449
CWBSO_BAD_PROFILE_NAME
指定されたプロファイル名が無効です。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。
CWBSO_SetListSortFields:
CWBSO_SetListSortFields API は、この製品と共に使用します。
目的
リストのソート基準を設定します。ソート基準では、CWBSO_OpenList の呼び出しによってリストが作成
される時点で、オブジェクトがそのリスト内に表示される順序を決定します。この API は、ジョブのリス
トおよびスプール・ファイルのリストについてのみ有効です。この API は、メッセージのリストおよびプ
リンターのリストには許可されていません。
構文
unsigned int CWB_ENTRY CWBSO_SetListSortFields(
CWBSO_LIST_HANDLE listHandle,
unsigned short far* lpusSortIDs,
unsigned short usCount);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
unsigned short far* lpusSortIDs - input
ソート列識別コードの配列を指す long 型のポインター。指定されたソート ID は、リストの現行のソ
ート基準を置換します。このパラメーターの有効な値は、リストのオブジェクトのタイプによって決ま
ります。有効な値については、下記の該当するヘッダー・ファイルを参照してください。
v cwbsojob.h
v cwbsosfl.h
注: 複数のソート ID が指定される場合、配列内でのソート ID の順序によって、ソートが行われる順
序が定義されます。
unsigned short usCount - input
指定されたソート列識別コードの数。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
450
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_BAD_SORT_ID
指定のソート ID はこのリストのタイプに対しては無効です。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_SORT_NOT_ALLOWED
このリストのタイプに対するソートは許可されていません。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API は、既にオープンされているリストに対しては有効とはなりません。ソート基準を有効
とするためには、この API を呼び出した後でリストをオープンする必要があります。複雑なソートを要求
すると、リストのパフォーマンスが低下することがあるため、注意が必要です。
CWBSO_SetListTitle:
CWBSO_SetListTitle API は、この製品と共に使用します。
目的
リストのタイトルを設定します。このタイトルは、CWBSO_DisplayList の呼び出しによってリストが表示
される時点で、ウィンドウのタイトル・バーに表示されます。
構文
unsigned int CWB_ENTRY CWBSO_SetListTitle(
CWBSO_LIST_HANDLE listHandle ,
char far* lpszTitle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
char far* lpszTitle - input
リストのタイトルに使用されるストリングを指す long 型のポインター。ストリングの長さは、79 以
下でなければなりません。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_TITLE
指定されたタイトルが無効です。
プログラミング
451
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。
CWBSO_SetObjAttr:
CWBSO_SetObjAttr API は、この製品と共に使用します。
目的
オブジェクトの 1 つまたは複数の属性の値を設定します。
構文
unsigned int CWB_ENTRY CWBSO_SetObjAttr(
CWBSO_OBJ_HANDLE objectHandle,
CWBSO_PARMOBJ_HANDLE parmObjHandle,
unsigned short far* lpusErrorIndex,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_OBJ_HANDLE objectHandle - input
以前の CWBSO_GetObjHandle または CWBSO_CopyObjHandle の呼び出しによって戻されたオブジェ
クトのハンドル。
CWBSO_PARMOBJ_HANDLE parmObjHandle - input
以前の CWBSO_CreateParmObjHandle の呼び出しによって戻されたパラメーター・オブジェクトのハン
ドル。パラメーター・オブジェクトには、そのオブジェクトについて変更すべき属性が入っています。
unsigned short far* lpusErrorIndex - output
エラーが発生した場合、この値が、エラーを引き起こしたパラメーター項目の指標に設定されます。最
初のパラメーター項目は 1 です。パラメーター項目のいずれもエラーではない場合、この値は 0 に設
定されます。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_OBJECT_HANDLE
指定されたオブジェクト・ハンドルが無効。
CWBSO_BAD_PARMOBJ_HANDLE
指定されたパラメーター・オブジェクト・ハンドルが無効です。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
452
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_CANNOT_CHANGE_ATTRIBUTE
属性は現時点では変更できません。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_GetObjHandle または CWBSO_CopyObjHandle を呼び出す必要があり
ます。CWBSO_GetObjHandle または CWBSO_CopyObjHandle で戻されたオブジェクト・ハンドルを、この
API への入力として渡す必要があるためです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を
呼び出す必要があります。CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の
入力として渡す必要があります。
CWBSO_SetParameter:
CWBSO_SetParameter API は、この製品と共に使用します。
目的
オブジェクトの 1 つの属性の値を設定します。CWBSO_SetObjAttr を呼び出す前に、この API を複数回
呼び出すことができます。これにより、1 つの特定のオブジェクトについて CWBSO_SetObjAttr の一度の
呼び出しで複数の属性を変更することができます。
構文
unsigned int CWB_ENTRY CWBSO_SetParameter(
CWBSO_PARMOBJ_HANDLE parmObjHandle,
unsigned short usAttributeID,
char far* lpszValue,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_PARMOBJ_HANDLE parmObjHandle - input
以前の CWBSO_CreateParmObjHandle の呼び出しによって戻されたパラメーター・オブジェクトのハン
ドル。
unsigned short usAttributeID - input
設定されるパラメーターの属性 ID。このパラメーターの有効な値は、オブジェクトのタイプによって
決まります。有効な値については、下記の該当するヘッダー・ファイルを参照してください。
v cwbsojob.h
v cwbsomsg.h
v cwbsoprt.h
v cwbsosfl.h
char far* lpszValue - input
属性値を指す long 型のポインター。ASCIIZ ストリングのみが受け入れられることに注意してくださ
い。2 進値は、適切なライブラリー関数を使用してストリングに変換する必要があります。それぞれの
オブジェクトのタイプごとに指定できる特殊値については、 456 ページの『SOA 属性の特殊値』を参
照してください。
プログラミング
453
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_PARMOBJ_HANDLE
指定されたパラメーター・オブジェクト・ハンドルが無効です。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateParmObjHandle を呼び出す必要があります。
CWBSO_CreateParmObjHandle で戻されたパラメーター・オブジェクト・ハンドルをこの API への入力と
して渡す必要があるためです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要が
あります。CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す
必要があります。この API を呼び出しても、IBM i オブジェクトの属性は更新されません。指定したオブ
ジェクトの IBM i 属性値 (複数の場合あり) を実際に更新するには、CWBSO_SetObjAttr を呼び出す必要
があります。
CWBSO_WaitForObj:
CWBSO_WaitForObj API は、この製品と共に使用します。
目的
非同期で作成されているリストでオブジェクトが使用可能になるまで待機します。
構文
unsigned int CWB_ENTRY CWBSO_WaitForObj(
CWBSO_LIST_HANDLE listHandle,
unsigned long ulPosition,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
454
IBM i: Windows アプリケーション・パッケージ: プログラミング
unsigned long ulPosition - input
リスト内の、使用したいオブジェクトの位置。注: リスト内の最初のオブジェクトは、位置 0 と見な
されます。
CWBSO_ERR_HANDLE errorHandle - input
エラー・オブジェクトのハンドル。エラー・テキストのあるエラーが発生した場合、このハンドルを使
用してエラー・メッセージおよびメッセージ・ヘルプを検索することができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_BAD_LIST_POSITION
指定されたリスト内の位置が存在しません。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、 CWBSO_CreateErrorHandle を呼び出す必要があります。
CWBSO_CreateErrorHandle によって戻されたエラー・ハンドルを、この API の入力として渡す必要があり
ます。
CWBSO_WriteListProfile:
CWBSO_WriteListProfile API は、この製品と共に使用します。
目的
Windows レジストリー内の指定されたキーに、リストに関するフィルター情報を書き込みます。キー名
は、CWBSO_SetListProfile API を使用して、前もって設定されていなければなりません。この API は、リ
ストを削除する前に呼び出す必要があります。そうすることで、CWBSO_DisplayList API 使用時にユーザ
ーが変更したフィルター基準が、すべて保管されます。システムごと、およびリストのタイプごとに、フィ
ルター情報がレジストリーに保管されます。例えば、アプリケーションで 2 つの異なるシステムからオブ
ジェクトにアクセスし、4 つのリスト・タイプをすべて表示した場合、レジストリーには、フィルター情報
を指定する 8 つの個別セクションがあることになります。
プログラミング
455
構文
unsigned int CWB_ENTRY CWBSO_WriteListProfile(
CWBSO_LIST_HANDLE listHandle,
CWBSO_ERR_HANDLE errorHandle);
パラメーター
CWBSO_LIST_HANDLE listHandle - input
以前の CWBSO_CreateListHandle または CWBSO_CreateListHandleEx の呼び出しによって戻されたリ
ストのハンドル。
CWBSO_ERR_HANDLE errorHandle - input
以前の CWBSO_CreateErrorHandle の呼び出しによって作成されたエラー・オブジェクトのハンドル。
この API で戻された値が CWBSO_ERROR_OCCURRED である場合、エラー・ハンドルを使って、エ
ラー・メッセージ・テキストの検索、またはユーザーへのエラーの表示を行うことができます。
戻りコード
以下は、共通の戻り値です。
CWBSO_NO_ERROR
エラーは起こりませんでした。
CWBSO_BAD_LIST_HANDLE
指定されたリスト・ハンドルが無効。
CWBSO_BAD_ERR_HANDLE
指定されたエラー・ハンドルが無効。
CWBSO_SYSTEM_NAME_DEFAULTED
そのリストに関する CWBSO_CreateListHandle 呼び出しでシステム名が指定されませんでした。
CWBSO_LOW_MEMORY
要求に対する十分なメモリーがありませんでした。
CWBSO_ERROR_OCCURRED
エラーが発生しました。詳細な情報を入手するには、エラー・ハンドルを使用してください。
使用法
この API を呼び出す前に、CWBSO_CreateListHandle を呼び出す必要があります。
CWBSO_CreateListHandle によって戻されたリスト・ハンドルをこの API の入力として渡す必要があるた
めです。この API を呼び出す前に、CWBSO_SetListProfile を呼び出す必要があります。
SOA 属性の特殊値:
以下のリストにあるトピックでは、オブジェクトのタイプごとに、CWBSO_GetObjAttr によって戻される
特殊値、および CWBSO_SetObjAttr で指定される特殊値について説明します。また、リスト・オブジェク
トのタイプごとに、CWBSO_SetListFilter で指定される特殊値についても説明します。
特別な考慮事項
v 通常、数値である属性については、IBM i API は負の数値を戻して、どの特殊値 (存在する場合) がオ
ブジェクト属性に含まれているかを示します。システム・オブジェクト・アクセスでは、自動的にこれ
らの負の数値をそれに対応する特殊値ストリングにマップします。例えば、スプール・ファイル属性の
456
IBM i: Windows アプリケーション・パッケージ: プログラミング
検索 (QUSRSPLA) API では、出力縮小が自動的に行われる場合のページ回転について「-1」を戻しま
す。CWBSO_GetObjAttr は、「*AUTO」を戻します。
v いくつかのリスト・フィルター基準は複数の値を受け入れます。例えば、複数のプリンター名について
プリンターのリストをフィルター処理することが可能です。そのような場合、指定する値はコンマで区
切らなければなりません。
属性の特殊値についての追加情報の参照
IBM i Information Center の『IBM iアプリケーション・プログラミング・インターフェース』のトピック
を参照してください。
ジョブ属性:
システム・オブジェクト・アクセスは、IBM i API であるジョブのリスト (QUSLJOB) およびジョブ情報
の検索 (QUSRJOBI) を使用して、ジョブの属性を検索します。
指定できる特殊値は、IBM i Information Center の『IBM i API: Work Management API』トピックで説明
されているものと同じです。以下の特殊値マッピングは、明示的には文書化されていません。
CWBSO_JOB_CpuTimeUsed
フィールドが実際の結果を保持するには十分な大きさではない場合、QUSRJOBI は -1 を戻しま
す。システム・オブジェクト・アクセスは「++++」を戻します。
CWBSO_JOB_MaxCpuTimeUsed,
CWBSO_JOB_MaxTemporaryStorage,
CWBSO_JOB_DefaultWaitTime
値が *NOMAX の場合、QUSRJOBI は -1 を戻します。システム・オブジェクト・アクセスは
「*NOMAX」を戻します。
CWBSO_SetListFilter は、ジョブのリスト (QUSLJOB) API でサポートされるすべての特殊値を受け入れま
す。
メッセージ属性:
システム・オブジェクト・アクセスは、非プログラム・メッセージのリスト (QMHLSTM) IBM i API を使
用して、メッセージの属性を検索します。
指定できる特殊値は、IBM i Information Center の『IBM i API: Message Handling API』トピックで説明さ
れているものと同じです。
重大度基準については、CWBSO_SetListFilter は、非プログラム・メッセージのリスト (QMHLSTM) API
でサポートされる特殊値を受け入れます。さらに、CWBSO_MSGF_UserName フィルター ID を指定する
ことによって、10 文字のユーザー名を与えることができます。「*CURRENT」を使用して、現行ユーザー
についてのメッセージのリストを入手することができます。
プリンター属性:
システム・オブジェクト・アクセスは文書化されていない IBM i API を使用して、プリンター・オブジェ
クトについての属性を検索します。
プログラミング
457
プリンターは「論理」オブジェクトであり、実際には装置記述、書き出しプログラム、および出力待ち行列
を組み合わせたものです。この属性および指定できる値は以下のとおりです。
CWBSO_PRT_AdvancedFunctionPrinting
プリンターが高機能印刷 (AFP) をサポートするかどうか。
*NO
プリンターは高機能印刷をサポートしません。
*YES
プリンターは高機能印刷をサポートします。
CWBSO_PRT_AllowDirectPrinting
プリンターに直接印刷するジョブに、プリンターを割り振ることを印刷装置書き出しプログラムが
許可するかどうか。
*NO
直接印刷は許可されません。
*YES
直接印刷は許可されます。
CWBSO_PRT_BetweenCopiesStatus
複数コピー・スプール・ファイルのコピーとコピーの間に書き出しプログラムが使用可能かどう
か。指定できる値は、Y (はい) または N (いいえ) です。
CWBSO_PRT_BetweenFilesStatus
書き出しプログラムがスプール・ファイル間で使用可能かどうか。指定できる値は、Y (はい) また
は N (いいえ) です。
CWBSO_PRT_ChangesTakeEffect
書き出しプログラムに対する保留中の変更が効力を持つ時点。指定できる値は以下のとおりです。
*NORDYF
現行の有資格ファイルのすべてが印刷されるとき。
*FILEEND
現行のスプール・ファイルの印刷が行われるとき。
ブランク
書き出しプログラムに対する保留中の変更はありません。
CWBSO_PRT_CopiesLeftToProduce
まだ印刷していないコピー数。印刷するファイルがない場合、このフィールドは 0 に設定されま
す。
CWBSO_PRT_CurrentPage
現在、書き出しプログラムによって処理中の、スプール・ファイルのページ番号。示されたページ
番号は、印刷されている実際のページ番号より前かまたは後である場合があります。これは、シス
テムによって行われるバッファー方式のためです。印刷されるスプール・ファイルがない場合、こ
のフィールドは 0 に設定されます。
CWBSO_PRT_Description
プリンターのテキスト記述。
CWBSO_PRT_DeviceName
プリンターの名前。
CWBSO_PRT_DeviceStatus
プリンターの状況。指定できる値は、構成状況の検索 (QDCRCFGS) API で戻される装置状況と同
じです。
CWBSO_PRT_EndAutomatically
書き出しプログラムが、自動的に終了する場合にいつ終了させるか。
458
IBM i: Windows アプリケーション・パッケージ: プログラミング
*NORDYF
書き出しプログラムが印刷すべきファイルを選択する出力待ち行列に、印刷準備状態のフ
ァイルがないとき。
*FILEEND
現行のスプール・ファイルの印刷終了時。
*NO
書き出しプログラムは終了せず、さらにスプール・ファイルを待機します。
CWBSO_PRT_EndPendingStatus
書き出しプログラム終了 (ENDWTR) コマンドが、この書き出しプログラムに対して出されたかどう
か。指定できる値は以下のとおりです。
N
ENDWTR コマンドは出されませんでした。
I
*IMMED: 出力バッファーが空になるとすぐに書き出しプログラムは終了します。
C
*CNTRLD: スプール・ファイルの現行コピーが印刷された後で書き出しプログラムは終了
します。
P
*PAGEEND: 書き出しプログラムはページの終わりで終了します。
CWBSO_PRT_FileName
現在、書き出しプログラムによって処理中の、スプール・ファイル名。印刷しているファイルがな
い場合、このフィールドはブランクです。
CWBSO_PRT_FileNumber
現在、書き出しプログラムによって処理中の、スプール・ファイルの番号。印刷されるスプール・
ファイルがない場合、このフィールドは 0 に設定されます。
CWBSO_PRT_FormsAlignment
用紙位置決めメッセージが送信される時点。指定できる値は以下のとおりです。
*WTR 書き出しプログラムがメッセージをいつ送信するかを決定します。
*FILE ページ位置決めの制御は、各ファイルによって指定されます。
CWBSO_PRT_FormType
スプール・ファイルの印刷に使用している用紙のタイプ。指定できる値は以下のとおりです。
*ALL
いかなる用紙タイプであってもすべてのスプール・ファイルを印刷するというオプション
で、書き出しプログラムが開始されます。
*FORMS
異なる用紙タイプを使用する前に、同じ用紙タイプ指定を持つすべてのスプール・ファイ
ルを印刷するというオプションで、書き出しプログラムが開始されます。
*STD
用紙タイプ指定が *STD である、すべてのスプール・ファイルを印刷するというオプショ
ンで、書き出しプログラムが開始されます。
用紙タイプ名
ユーザーが指定した用紙タイプを持つすべてのスプール・ファイルを印刷するというオプ
ションで、書き出しプログラムが開始されます。
CWBSO_PRT_FormTypeNotification
この用紙の終了時にメッセージ待ち行列へメッセージを送信するためのメッセージ・オプション。
指定できる値は以下のとおりです。
*MSG メッセージがメッセージ待ち行列へ送信されます。
プログラミング
459
*NOMSG
メッセージはメッセージ待ち行列へ送信されません。
*INFOMSG
通知メッセージがメッセージ待ち行列へ送信されます。
*INQMSG
照会メッセージがメッセージ待ち行列へ送信されます。
CWBSO_PRT_HeldStatus
書き出しプログラムが保留されるかどうか。指定できる値は、Y (はい) または N (いいえ) です。
CWBSO_PRT_HoldPendingStatus
書き出しプログラムの保留 (HLDWTR) コマンドがこの書き出しプログラムについて出されたかどう
か。指定できる値は以下のとおりです。
N
HLDWTR コマンドは出されませんでした。
I
*IMMED: 出力バッファーが空になるとすぐに書き出しプログラムは保留されます。
C
*CNTRLD: ファイルの現行コピーが印刷された後で書き出しプログラムは保留されます。
P
*PAGEEND: ページの終わりで書き出しプログラムは保留されます。
CWBSO_PRT_JobName
現在、書き出しプログラムによって処理中のスプール・ファイルを作成したジョブの名前。印刷し
ているスプール・ファイルがない場合、このフィールドはブランクです。
CWBSO_PRT_JobNumber
現在、書き出しプログラムによって処理中のスプール・ファイルを作成したジョブの番号。印刷し
ているスプール・ファイルがない場合、このフィールドはブランクです。
CWBSO_PRT_MessageKey
書き出しプログラムが応答を待っているメッセージへのキー。書き出しプログラムが照会メッセー
ジへの応答を待っていない場合、このフィールドはブランクになります。
CWBSO_PRT_MessageQueueLibrary
メッセージ待ち行列が入っているライブラリーの名前。
CWBSO_PRT_MessageQueueName
この書き出しプログラムが操作上のメッセージに使用するメッセージ待ち行列の名前。
CWBSO_PRT_MessageWaitingStatus
照会メッセージへの応答を書き出しプログラムが待っているかどうか。指定できる値は、Y (はい)
または N (いいえ) です。
CWBSO_PRT_NextFormType
次に印刷する用紙タイプの名前。指定できる値は以下のとおりです。
*ALL
いずれの用紙タイプであってもすべてのスプール・ファイルを印刷するというオプション
に、書き出しプログラムが変更されます。
*FORMS
異なる用紙タイプを使用する前に、同じ用紙タイプ指定を持つすべてのスプール・ファイ
ルを印刷するというオプションに、書き出しプログラムが変更されます。
*STD
460
用紙タイプ指定が *STD である、すべてのスプール・ファイルを印刷するというオプショ
ンに、書き出しプログラムが変更されます。
IBM i: Windows アプリケーション・パッケージ: プログラミング
用紙タイプ名
ユーザーが指定した用紙タイプを持つすべてのスプール・ファイルを印刷するというオプ
ションに、書き出しプログラムが変更されます。
ブランク
この書き出しプログラムに対して変更は行われませんでした。
CWBSO_PRT_NextFormTypeNotification
次の用紙タイプの終了時に、メッセージ待ち行列へメッセージを送信するためのメッセージ・オプ
ション。指定できる値は以下のとおりです。
*MSG メッセージがメッセージ待ち行列へ送信されます。
*NOMSG
メッセージはメッセージ待ち行列へ送信されません。
*INFOMSG
通知メッセージがメッセージ待ち行列へ送信されます。
*INQMSG
照会メッセージがメッセージ待ち行列へ送信されます。
ブランク
この書き出しプログラムに対して変更は行われませんでした。
CWBSO_PRT_NextOutputQueueLibrary
次の出力待ち行列が入っているライブラリーの名前。書き出しプログラムに対して変更が行われな
かった場合、このフィールドはブランクです。
CWBSO_PRT_NextOutputQueueName
次に処理する出力待ち行列の名前。書き出しプログラムに対して変更が行われなかった場合、この
フィールドはブランクです。
CWBSO_PRT_NextSeparatorDrawer
この値は、書き出しプログラムに対する変更がある場合に、分離ページを取り出す用紙入れを示し
ます。指定できる値は以下のとおりです。
*FILE 区切りページは、スプール・ファイルが印刷されるのと同じ用紙入れから印刷されます。
色付きまたは異なるタイプの用紙が入っている、スプール・ファイルとは異なる用紙入れ
をユーザーが指定すれば、区切りページがさらに識別しやすくなります。
*DEVD
区切りページは、プリンター記述で指定された区切りページ用紙入れから印刷されます。
空ストリング
書き出しプログラムに対する保留中の変更はありません。
1
1 番目の用紙入れ。
2
2 番目の用紙入れ。
3
3 番目の用紙入れ。
CWBSO_PRT_NextSeparators
書き出しプログラムに対する変更が行われるときに印刷される区切りページの次の数。指定できる
値は以下のとおりです。
*FILE 区切りページの数はファイルごとに指定されます。
プログラミング
461
空ストリング
書き出しプログラムに対する保留中の変更はありません。
区切りページの数
印刷される区切りページの数。
CWBSO_PRT_NumberOfSeparators
印刷される区切りページの数。指定できる値は以下のとおりです。
*FILE 区切りページの数はファイルごとに指定されます。
区切りページの数
印刷される区切りページの数。
CWBSO_PRT_OnJobQueueStatus
書き出しプログラムがジョブ待ち行列にあり、そのため現在実行中ではないかどうか。指定できる
値は、Y (はい) または N (いいえ) です。
CWBSO_PRT_OutputQueueLibrary
スプール・ファイルが印刷のために選択される、出力待ち行列が入っているライブラリーの名前。
CWBSO_PRT_OutputQueueName
スプール・ファイルが印刷のために選択される、出力待ち行列の名前。
CWBSO_PRT_OutputQueueStatus
スプール・ファイルが印刷のために選択される、出力待ち行列の状況。指定できる値は以下のとお
りです。
H
出力待ち行列は保留されています。
R
出力待ち行列は解放されています。
CWBSO_PRT_PrinterDeviceType
スプール・ファイルの印刷に使用されているプリンターのタイプ。有効な値は以下のとおりです。
*SCS
SNA (システム・ネットワーク体系) 文字ストリーム
*IPDS Intelligent Printer Data Stream
CWBSO_PRT_SeparatorDrawer
ジョブおよびファイルの区切りページが取り出される用紙入れを識別します。指定できる値は以下
のとおりです。
*FILE ファイルが印刷される場合と同じ用紙入れから、区切りページは印刷されます。色付きま
たは異なるタイプの用紙が入っている、ファイルとは異なる用紙入れをユーザーが指定す
れば、区切りページがさらに識別しやすくなります。
*DEVD
区切りページは、プリンター記述で指定された区切りページ用紙入れから印刷されます。
1
1 番目の用紙入れ。
2
2 番目の用紙入れ。
3
3 番目の用紙入れ。
CWBSO_PRT_StartedByUser
書き出しプログラムを開始したユーザーの名前。
CWBSO_PRT_Status
論理プリンターの全体的な状況。このフィールドは、プリンター状況 (構成状況の検索
QDCRCFGS API からのもの)、出力待ち行列状況 (プリンターと書き出しプログラム状況のリス
462
IBM i: Windows アプリケーション・パッケージ: プログラミング
ト、および XPF マクロからのもの)、および書き出しプログラム状況 (書き出しプログラム情報の
検索、QSPRWTRI API からのもの) から取り込まれます。指定できる値は以下のとおりです。
1
使用不可
2
電源オフまたはまだ使用不可
3
停止状態
4
メッセージ待ち状態
5
保留
6
停止 (保留中)
7
保留 (保留中)
8
プリンターを待機中
9
開始を待機中
10
印刷中
11
プリンター出力の待機中
12
接続保留中
13
電源オフ
14
使用不可
15
サービス中
999
認識不能
CWBSO_PRT_TotalCopies
印刷されるコピーの合計数。
CWBSO_PRT_TotalPages
スプール・ファイル内のページの合計数。指定できる値は以下のとおりです。
数値
スプール・ファイル内のページ数。
0
印刷中のスプール・ファイルはありません。
CWBSO_PRT_User
現在、書き出しプログラムによって処理中のスプール・ファイルを作成したユーザーの名前。印刷
しているファイルがない場合、このフィールドはブランクです。
CWBSO_PRT_UserSpecifiedData
現在、書き出しプログラムによって処理中のファイルを記述しているユーザー指定のデータ。印刷
しているファイルがない場合、このフィールドはブランクです。
CWBSO_PRT_WaitingForDataStatus
書き出しプログラムが、現在スプール・ファイルにあるすべてのデータを書き込み済みで、さらに
データを待っているかいないか。指定できる値は以下のとおりです。
N
書き出しプログラムは、それ以上データを待っていません。
Y
書き出しプログラムは現在スプール・ファイルにあるすべてのデータを書き込み済みで、
さらにデータを待っています。この条件が発生するのは、書き出しプログラムが、
SCHEDULE(*IMMED) を指定したオープン・スプール・ファイルを生成しているときで
す。
プログラミング
463
CWBSO_PRT_WaitingForDeviceStatus
プリンターに直接印刷を行っているジョブから装置を獲得するのを書き出しプログラムが待ってい
るかどうか。
N
書き出しプログラムは装置を待っていません。
Y
書き出しプログラムは装置を待っています。
CWBSO_PRT_WriterJobName
印刷装置書き出しプログラムのジョブ名。
CWBSO_PRT_WriterJobNumber
印刷装置書き出しプログラムのジョブ番号。
CWBSO_PRT_WriterJobUser
システム・ユーザーの名前。
CWBSO_PRT_WriterStarted
このプリンターに対して書き出しプログラムが開始しているかどうかを指示します。指定できる値
は以下のとおりです。
0
書き出しプログラムは開始されていません。
1
書き出しプログラムは開始されています。
CWBSO_PRT_WriterStatus
このプリンターについての書き出しプログラムの状況。指定できる値は以下のとおりです。
X'01'
開始済み
X'02'
終了済み
X'03'
ジョブ待ち行列中
X'04'
保留
X'05'
メッセージ待ち状態
CWBSO_PRT_WritingStatus
印刷装置書き出しプログラムが書き込み状況にあるかどうか。指定できる値は以下のとおりです。
Y
書き出しプログラムは書き込み状況にあります。
N
書き出しプログラムは書き込み状況にありません。
S
書き出しプログラムはファイル区切りを書き込み中です。
システム・オブジェクト・アクセスは、コンマで区切られたプリンター名のリストを受け入れます。最高
100 個のプリンター名の指定が可能です。 IBM i の全プリンターのリストを要求するには、特殊値の
「*ALL」を指定します。
プリンター出力属性:
システム・オブジェクト・アクセスは、API であるスプール・ファイルのリスト (QUSLSPL) およびスプ
ール・ファイル属性の検索 (QUSRSPLA) IBM i を使用して、プリンター出力の属性を検索します。
指定できる特殊値は、IBM i Information Center の『IBM i APIs: Spooled File APIs』トピックで説明され
ているものと同じです。以下の特殊値マッピングは、明示的には文書化されていません。
464
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_SFL_StartingPage
終了ページの値が使用される場合、QUSRSPLA は -1 を戻します。システム・オブジェクト・ア
クセスは「*ENDPAGE」を戻します。
CWBSO_SFL_EndingPage
最後のページが終了ページになる場合、QUSRSPLA は 0 または 2147483647 を戻します。システ
ム・オブジェクト・アクセスは「*END」を戻します。
CWBSO_SFL_MaximumRecords
最大がない場合、QUSRSPLA は 0 を戻します。システム・オブジェクト・アクセスは
「*NOMAX」を戻します。
CWBSO_SFL_PageRotation
回転が行われない場合、QUSRSPLA は 0 を戻します。システム・オブジェクト・アクセスは
「*NONE」を戻します。
1 つの文書化されていない API が、スプール・ファイルの 1 つまたは複数のプリンター名を検索するた
めに使用されます。その属性および指定できる値について以下で説明します。
CWBSO_SFL_DeviceNames
ファイルを印刷するプリンターの名前。プリンター出力が複数のプリンターに割り当てられている
場合、このフィールドには、プリンター・グループ内のすべてのプリンター名が入ります。指定で
きる値は以下のとおりです。
プリンター名
プリンター出力が割り当てられているプリンターの名前。
プリンター名のリスト
プリンター出力が割り当てられているグループ内のプリンターの名前。プリンター名はコ
ンマで区切られます。
空ストリング
プリンター出力がプリンターまたはプリンター・グループに割り当てられていません。
CWBSO_SetListFilter は、スプール・ファイルのリスト (QUSLSPL) API でサポートされるすべての特殊値
を受け入れます。
TCP/IP インターフェース属性:
システム・オブジェクト・アクセスは、IBM i API であるネットワーク・インターフェースのリスト
(QtocLstNetIfc) を使用して、TCP/IP インターフェースの属性を検索します。
システム・オブジェクト・アクセスを使用して TCP/IP インターフェースの属性を検索するには、以下の
API のいずれか 1 つを使用します。
v 変更 IPv4 インターフェース (QTOCC4IF) API
– この API はプログラム一時修正 (PTF) によって文書化されています。PTF の詳細については、以下
のページの検索機能に SI17284 を入力して参照してください。
- 製品 Service Pack (英語) (http://www.ibm.com/servers/eserver/iseries/access/casp.htm)
v リスト・ネットワーク・インターフェース (QtocLstNetIfc) API
プログラミング
465
イーサネット回線属性:
イーサネット回線に関する情報は、構成 API のトピックにあります。
IBM iInformation Center の『General Configuration APIs』を参照してください。
トークンリング回線属性:
トークンリング回線に関する情報は、構成 API のトピックにあります。
IBM iInformation Center の『General Configuration APIs』を参照してください。
ハードウェア資源属性:
ハードウェア資源に関する情報は、ハードウェア資源 API のトピックにあります。
IBM i Information Center の『Hardware Resource APIs』のトピックを参照してください。
ソフトウェア・プロダクト属性:
ソフトウェア・プロダクトに関する情報は、ソフトウェア・プロダクト API のトピックにあります。
IBM i Information Center の『Software Product APIs』のトピックを参照してください。
TCP/IP 経路属性:
システム・オブジェクト・アクセスは、IBM i API である TCP/IP 経路 (QTOCRTEU) を使用して、
TCP/IP 経路の属性を検索します。
指定できる特殊値は以下のとおりです。
CWBSO_RTE_TCPIPNetworkName
CWBSO_RTE_InternetAddress
CWBSO_RTE_BinaryInternetAddress
*RTVxxxLST の場合のみ - 入出力変数ヘッダーの直後に、戻された経路のリストが表示されま
す。インターフェース構造体は、戻された経路ごとに繰り返されます。
CWBSO_RTE_SubnetMask
CWBSO_RTE_BinarySubnetMask
*RTVxxxLST の場合のみ - 入出力変数ヘッダーの直後に、戻された経路のリストが表示されま
す。インターフェース構造体は、戻された経路ごとに繰り返されます。
CWBSO_RTE_NextHopAddress
CWBSO_RTE_BinaryNextHop
*RTVxxxLST の場合のみ - 入出力変数ヘッダーの直後に、戻された経路のリストが表示されま
す。インターフェース構造体は、戻された経路ごとに繰り返されます。
CWBSO_RTE_BindingInterface
CWBSO_RTE_BinaryBindingIP
*RTVxxxLST の場合のみ - 入出力変数ヘッダーの直後に、戻された経路のリストが表示されま
す。インターフェース構造体は、戻された経路ごとに繰り返されます。
CWBSO_RTE_MaximumTransmissionUnit
466
IBM i: Windows アプリケーション・パッケージ: プログラミング
CWBSO_RTE_TypeOfService
v 1=通常
v 2=最小遅延
v 3=最大スループット
v 4=最大信頼性
v 5=最小コスト
CWBSO_RTE_RoutePrecedence
CWBSO_RTE_RIPMetric
CWBSO_RTE_RIPRedistribution
v 1=はい
v 2=いいえ
CWBSO_RTE_PPPProfile
*xxxRTE には無効
CWBSO_RTE_PPPCallerUserid
*xxxRTE には無効
CWBSO_RTE_PPPCallerIP
*xxxRTE には無効
CWBSO_RTE_ApplicationDefined
ユーザーとグループ属性:
このリストを使用して、IBM i ユーザーおよびグループの有効な特殊値を識別します。
v CWBSO_USR_ProfileName
v CWBSO_USR_ProfileOrGroupIndicator
v CWBSO_USR_GroupHasMembers
v CWBSO_USR_TextDescription
v CWBSO_USR_PreviousSignonDate
v CWBSO_USR_PreviousSignonTime
v CWBSO_USR_SignonAttemptsNotValid
v CWBSO_USR_Status
v CWBSO_USR_PasswordChangeDate
v CWBSO_USR_NoPasswordIndicator
v CWBSO_USR_PasswordExpirationInterval
v CWBSO_USR_DatePasswordExpires
v CWBSO_USR_DaysUntilPasswordExpires
v CWBSO_USR_SetPasswordToExpire
v CWBSO_USR_DisplaySignonInformation
v CWBSO_USR_UserClassName
v CWBSO_USR_AllObjectAccess
v CWBSO_USR_SecurityAdministration
v CWBSO_USR_JobControl
プログラミング
467
v CWBSO_USR_SpoolControl
v CWBSO_USR_SaveAndRestore
v CWBSO_USR_SystemServiceAccess
v CWBSO_USR_AuditingControl
v CWBSO_USR_SystemConfiguration
v CWBSO_USR_GroupProfileName
v CWBSO_USR_Owner
v CWBSO_USR_GroupAuthority
v CWBSO_USR_LimitCapabilities
v CWBSO_USR_GroupAuthorityType
v CWBSO_USR_SupplementalGroups
v CWBSO_USR_AssistanceLevel
v CWBSO_USR_CurrentLibraryName
v CWBSO_USR_InitialMenuName
v CWBSO_USR_InitialMenuLibraryName
v CWBSO_USR_InitialProgramName
v CWBSO_USR_InitialProgramLibraryName
v CWBSO_USR_LimitDeviceSessions
v CWBSO_USR_KeyboardBuffering
v CWBSO_USR_MaximumAllowedStorage
v CWBSO_USR_StorageUsed
v CWBSO_USR_HighestSchedulingPriority
v CWBSO_USR_JobDescriptionName
v CWBSO_USR_JobDescriptionNameLibrary
v CWBSO_USR_AccountingCode
v CWBSO_USR_MessageQueueName
v CWBSO_USR_MessageQueueLibraryName
v CWBSO_USR_MessageQueueDeliveryMethod
v CWBSO_USR_MessageQueueSeverity
v CWBSO_USR_OutputQueue
v CWBSO_USR_OutputQueueLibrary
v CWBSO_USR_PrintDevice
v CWBSO_USR_SpecialEnvironment
v CWBSO_USR_AttentionKeyHandlingProgramName
v CWBSO_USR_AttentionKeyHandlingProgramLibrary
v CWBSO_USR_LanguageID
v CWBSO_USR_CountryID
v CWBSO_USR_CharacterCodeSetID
v CWBSO_USR_ShowParameterKeywords
v CWBSO_USR_ShowAllDetails
468
IBM i: Windows アプリケーション・パッケージ: プログラミング
v CWBSO_USR_DisplayHelpOnFullScreen
v CWBSO_USR_ShowStatusMessages
v CWBSO_USR_DoNotShowStatusMessages
v CWBSO_USR_ChangeDirectionOfRollkey
v CWBSO_USR_SendMessageToSpoolFileOwner
v CWBSO_USR_SortSequenceTableName
v CWBSO_USR_SortSequenceTableLibraryName
v CWBSO_USR_DigitalCertificateIndicator
v CWBSO_USR_CharacterIDControl
v CWBSO_USR_ObjectAuditValue
v CWBSO_USR_CommandUsage
v CWBSO_USR_ObjectCreation
v CWBSO_USR_ObjectDeletion
v CWBSO_USR_JobTasks
v CWBSO_USR_ObjectManagement
v CWBSO_USR_OfficeTasks
v CWBSO_USR_ProgramAdoption
v CWBSO_USR_SaveAndRestoreTasks
v CWBSO_USR_SecurityTasks
v CWBSO_USR_ServiceTasks
v CWBSO_USR_SpoolManagement
v CWBSO_USR_SystemManagement
v CWBSO_USR_OpticalTasks
v CWBSO_USR_UserIDNumber
v CWBSO_USR_GroupIDNumber
v CWBSO_USR_DoNotSetAnyJobAttributes
v CWBSO_USR_UseSystemValue
v CWBSO_USR_CodedCharacterSetID
v CWBSO_USR_DateFormat
v CWBSO_USR_DateSeparator
v CWBSO_USR_SortSequenceTable
v CWBSO_USR_TimeSeparator
v CWBSO_USR_DecimalFormat
v CWBSO_USR_HomeDirectoryDelimiter
v CWBSO_USR_HomeDirectory
v CWBSO_USR_Locale
v CWBSO_USR_IndirectUser
v CWBSO_USR_PrintCoverPage
v CWBSO_USR_MailNotification
v CWBSO_USR_UserID
プログラミング
469
v CWBSO_USR_LocalDataIndicator
v CWBSO_USR_UserAddress
v CWBSO_USR_SystemName
v CWBSO_USR_SystemGroup
v CWBSO_USR_UserDescription
v CWBSO_USR_FirstName
v CWBSO_USR_PreferredName
v CWBSO_USR_MiddleName
v CWBSO_USR_LastName
v CWBSO_USR_FullName
v CWBSO_USR_JobTitle
v CWBSO_USR_CompanyName
v CWBSO_USR_DepartmentName
v CWBSO_USR_NetworkUserID
v CWBSO_USR_PrimaryTelephoneNumber
v CWBSO_USR_SecondaryTelephoneNumber
v CWBSO_USR_FaxNumber
v CWBSO_USR_Location
v CWBSO_USR_BuildingNumber
v CWBSO_USR_OfficeNumber
v CWBSO_USR_MailingAddress
v CWBSO_USR_MailingAddress2
v CWBSO_USR_MailingAddress3
v CWBSO_USR_MailingAddress4
v CWBSO_USR_CCMailAddress
v CWBSO_USR_CCMailComment
v CWBSO_USR_MailServerFrameworkServiceLevel
v CWBSO_USR_PreferredAddressFieldName
v CWBSO_USR_PreferredAddressProductID
v CWBSO_USR_PreferredAddressTypeValue
v CWBSO_USR_PreferredAddressTypeName
v CWBSO_USR_PreferredAddress
v CWBSO_USR_ManagerCode
v CWBSO_USR_SMTPUserID
v CWBSO_USR_SMTPDomain
v CWBSO_USR_SMTPRoute
v CWBSO_USR_GroupMemberIndicator
注: Lotus Notes® が IBM i プラットフォームにインストールされている場合にのみ、次の属性が有効にな
ります。
470
IBM i: Windows アプリケーション・パッケージ: プログラミング
v CWBSO_USR_NotesServerName
v CWBSO_USR_NotesCertifierID
v CWBSO_USR_MailType
v CWBSO_USR_NotesMailFileName
v CWBSO_USR_CreateMailFiles
v CWBSO_USR_NotesForwardingAddress
v CWBSO_USR_SecurityType
v CWBSO_USR_LicenseType
v CWBSO_USR_MinimumNotesPasswordLength
v CWBSO_USR_UpdateExistingNotesUser
v CWBSO_USR_NotesMailServer
v CWBSO_USR_LocationWhereUserIDIsStored
v CWBSO_USR_ReplaceExistingNotesID
v CWBSO_USR_NotesComment
v CWBSO_USR_NotesUserLocation
v CWBSO_USR_UserPassword
v CWBSO_USR_NotesUserPassword
v CWBSO_USR_NotesCertifierPassword
v CWBSO_USR_ShortName
QSYS のライブラリー属性:
QSYS のライブラリーに関する情報は、オブジェクト API のトピックにあります。
IBM i Information Center の『オブジェクト API (Object APIs)』のトピックを参照してください。
データベース・プログラミング
データベース・ファイルにアクセスするためのプログラミング・インターフェースが複数あります。
共通インターフェースを使用して、IBM i データベースと非 IBM i データベースの両方にアクセスする、
単一のアプリケーションを作成することができます。構造化照会言語 (SQL) を使用して、DB2® for i のデ
ータベース・ファイルにアクセスできます。また、ストアード・プロシージャーやレコード・レベルのアク
セス・インターフェースを使用して、ファイル内の単一レコードにアクセスすることもできます。
以下のトピックでは、サポートされるインターフェースに関する情報を紹介します。また、IBM i
Information Center にある『DB2 for i SQL 解説書』の一連のトピックから、DB2 for i の SQL プログラ
ミングに関する資料にアクセスして、詳細を参照してください。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連情報:
DB2 for i SQL リファレンス
プログラミング
471
.NET provider
.NET Provider によって、.NET 管理対象プログラムから IBM i データベース・ファイルへのアクセスを、
SQL を使用して行うことができます。
.NET のサポートについては、次のいずれかの名称が使われることがあります。
v 管理対象のプロバイダー
v DB2 for IBM i .NET Provider
v IBM.Data.DB2.iSeries のデータ・プロバイダー
使用される名称にかかわらず、IBM i での .NET Data Access Framework 接続時に、このデータ・プロバ
イダーによって PC-to-IBM i SQL アプリケーションの開発とサポートが実現されます。このプロバイダー
は、ADO.NET アーキテクチャー・モデルで定義され、サポートされている接続、コマンド、DataAdapter、
および DataReader の各機能へのアクセスを提供する、クラスとデータ・タイプのセットから構成されま
す。
IBM.Data.DB2.iSeries Data Provider は、既存の OLE DB データベース・プロバイダーを補完するもので
す。このプロバイダーにより、Visual Basic および C# を使用して .NET クライアント/サーバー・アプリ
ケーションを開発することが可能になります。このプロバイダーと Programmer's Toolkit を併用すれば、
.NET Windows クライアント PC アプリケーションをより短時間かつ簡単に開発することができます。
管理対象のプロバイダーは、.NET Framework が PC に既にインストールされているという要件を含め、
管理対象コードの .NET Framework 仕様に準拠します。このフレームワークのインストール後に製品の各
フィーチャーのインストールまたは除去を行う場合は、「ユーザーズ・ガイド」を参照してください。
Microsoft の .NET Framework、ADO.NET、Windows Installer、GAC、CLR のアーキテクチャーおよび詳
細、ならびに管理対象コードの仕様については、MicrosoftWeb サイト
を参照してください。
技術的な詳細へのアクセス
v 「DB2 for IBM i .NET Provider Technical Reference」(この製品に同梱されています) には、管理対象
のプロバイダーのサポートに関する詳細な説明が記載されています。この情報にアクセスするには次の
パスを使用してください。「スタート」 > 「プログラム」 > IBM i Access Client ソリューション >
「Programmer's Toolkit」 > 「.NET Provider Technical Reference」
v .NET Provider に関するテクニカル情報は、Visual Studio 2005 および 2008 内で「IBM i Access」でフ
ィルターに掛けることでも入手可能です。
.NET framework
Microsoft の .NET Framework、ADO.NET、Windows Installer、GAC、CLR のアーキテクチャーおよび詳
細、ならびに管理対象コードの仕様については、MicrosoftWeb サイト
を参照してください。
Programmer's Toolkit をインストールするには、次の手順を実行します。
v Programmer's Toolkit は、この製品のインストール時にオプションでインストールすることもできます
し、製品のインストール後に「変更セットアップ」を実行してインストールすることもできます。
『Programmer's Toolkit』を参照してください。
その他の .NET 情報源
v IBM i Access .NET Provider の Web サイト (英語)
472
IBM i: Windows アプリケーション・パッケージ: プログラミング
v IBM Redbook Integrating DB2 Universal Database™ for iSeries with Microsoft ADO .NET. SG24-6440
OLE DB Provider
IBM i データベース・ファイルへのレコード・レベル・アクセスおよび SQL アクセスをサポートしま
す。このサポートを活用するためには、ActiveX データ・オブジェクト (ADO) および OLE DB インター
フェースを使用します。
OLE DB Provider を Programmer's Toolkit と組み合わせて使用することによって、Windows クライアント
PC で IBM i クライアント/サーバー・アプリケーション開発を短期間で簡単に行うことができます。OLE
DB Provider 構成要素により、IBM i のプログラマーは、IBM i の DB2 for i 論理および物理データベー
ス・ファイルに対する、レコード・レベルでのアクセス・インターフェースを利用することができます。ま
た、SQL、データ待ち行列、プログラム、およびコマンドのサポートも提供されます。
ADO 規格と OLE DB 規格によって、IBM i のデータとサービスへの一貫性のあるインターフェースがプ
ログラマーに提供されます。 3 つのプロバイダー (IBMDA400、IBMDASQL、および IBMDARLA) すべ
てにおいて、IBM i から PC への変換およびデータ・タイプ間の変換がすべて処理されます。
OLE DB Provider のインストール方法
この Provider をインストールする場合には、「ユーザーズ・ガイド」でフィーチャーのインスト
ールと削除に関するトピックを参照してください。
注: 製品をインストールする前にコンピューターに MDAC 2.5 以降がインストールされていない
場合には、OLE DB Provider はインストールされません。 MDAC は Microsoft Web サイト:
www.microsoft.com/data/doc.htm からダウンロードすることができます。
OLE DB Technical Reference へのアクセス
OLE DB Technical Reference (製品に同梱されています) では、OLE DB Provider サポートに関す
る詳細な資料が提供されています。この情報にアクセスするには、「スタート」 > 「プログラ
ム」 > 「IBM i Access」 > 「Programmer's Toolkit」 > 「OLE DB Provider Technical
Reference」を選択してください。
Programmer's Toolkit をインストールするには、次の手順を実行します。
この Toolkit をインストールする場合には、「ユーザーズ・ガイド」でフィーチャーのインストー
ルと削除に関するトピックを参照してください。
その他の OLE DB 情報源
v IBM i Access OLE DB サポート Web サイト
関連資料:
572 ページの『ActiveX プログラミング』
ActiveX オートメーションは、Microsoftによって定義されたプログラミング・テクノロジーであり、IBM i
Access Client ソリューション製品でサポートされています。
IBM i Access ODBC
ODBC は、データベース・アクセス言語として SQL を使用する共通データベース・インターフェースで
す。IBM i Access 製品では、このインターフェースにサポートを提供するために、ODBC ドライバーをサ
ポートしています。
プログラミング
473
ODBC とは
ODBC とはオープン・データベース接続のことです。 ODBC は以下のもので構成されます。
v 適切に定義された関数のセット (アプリケーション・プログラミング・インターフェース)
v SQL 構文用の標準 (推奨されているが課せられてはいない)
v エラー・コード
v データ・タイプ
アプリケーション・プログラミング・インターフェースには、データベース管理システムへの接続、SQL
ステートメントの実行、データのリトリーブを行う豊富な関数のセットが用意されています。 API には、
データベースの SQL カタログとドライバーの機能を問い合わせる関数も含まれています。
ODBC ドライバーは、標準エラー・コードを戻し、データ・タイプを共通 (ODBC) 標準に変換します。
ODBC を使用することによって、アプリケーション開発者は、統合データベースのエラー情報を入手し、
アプリケーションを移植可能にする際に生じる最も複雑な問題の一部を回避することができるようになりま
す。
ODBC でユーザーが行えること
ODBC を使用して以下を行うことができます。
v SQL 要求をデータベース管理システム (DBMS) へ送信する。
v 同じプログラムを、再コンパイルせずに使用して、いろいろなデータベース管理システム (DBMS) プロ
ダクトにアクセスする。
v データ通信プロトコルから独立したアプリケーションを作成する。
v アプリケーションに使いやすい形式でデータを処理する。
ODBC の API は柔軟性があるため、(SQL が事前定義されている) トランザクション・ベースの基幹業務
アプリケーション、および (Select ステートメントが実行時に作成される) QUERY ツールでも使用するこ
とができます。
構造化照会言語 (SQL)
SOL は、リレーショナル・データベース内のデータを定義し、操作するための標準化言語です。データの
リレーショナル・モデルに従って、データベースは表集合として認知され、表に入っている値として関係が
表されます。データの取り出しは、1 つ以上の基本表から導き出すことができる結果表を指定することによ
って行われます。ODBC API は動的 SQL を使用して、データベースと対話します。動的 SQL では、
ODBC アプリケーションが実行されるときに SQL ステートメントを構成し、実行することができます。
SQL について詳しくは、DB2 for IBM i「SQL 解説書」ブックを参照してください。IBM i Information
Center にある『DB2 for IBM i SQL 解説書』の一連のトピックから、上記ブックの HTML オンライン版
を表示するか、PDF 版を印刷してください。以下の関連リンクを参照してください。
IBM i Access ODBC トピック
注: このページからリンクされている情報は、32 ビット ODBC ドライバーのサポート、64 ビット ODBC
ドライバーのサポート、および IBM i Access ODBC ドライバーのサポートに該当します。
ODBC 標準に関する資料を探すには、Microsoft Web サイトで ODBC を検索してください。
474
IBM i: Windows アプリケーション・パッケージ: プログラミング
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連情報:
DB2 for i SQL リファレンス
Microsoft Web サイト
IBM i Access ODBC ドライバーに固有の詳細
IBM i Access ODBC API を使用したインプリメンテーション時の問題について確認します。
ODBC API のインプリメンテーションに関する情報については、以下のトピックを選択してください。
注: Microsoft の ADO インターフェースで IBM i Access ODBC ドライバーを使用する際に発生する可能
性のある問題について、説明および次善策を確認したい場合には、Software Knowledge Base で検索ストリ
ングを MSDASQL 付きの ADO ストアード・プロシージャー呼び出しとして検索してください。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
560 ページの『例: SQL ストアード・プロシージャーと ODBC による CL コマンドの実行』
ストアード・プロシージャー・サポートは、SQL の CALL ステートメントを使用して IBM i 制御言語
(CL) コマンドを実行する手段を提供します。
関連情報:
Software Knowledge Base
Microsoft の ADO インターフェースで IBM i Access ODBC ドライバー・サポートを使用する際に発生
する可能性のある幾つかの問題の説明および次善策については、MSDASQL 付きの ADO ストアード・プ
ロシージャー呼び出しを検索ストリングとして使用して、Software Knowledge Base を検索します。
ODBC 3.x API に関する注意事項:
次の表は、IBM i Access ODBC 3.x API をその関連タスクごとにリストし、それぞれの API に関する考
慮事項を示しています。
注:
v IBM i Access ODBC Driver は、ユニコード・ドライバーですが、ANSI アプリケーションも、引き続き
それと共に稼働します。ODBC Driver Manager は、IBM i Access ODBC Driver を呼び出す前に、ANSI
ODBC API 呼び出しをワイド・バージョンに変換します。ユニコード・アプリケーションを作成するに
は、これらの API のいくつかのワイド・バージョンを呼び出さなければなりません。ワイド ODBC イ
ンターフェースに対応するアプリケーションを作成する場合、各 API の長さが文字として定義されてい
るのか、バイト単位で定義されているのか、あるいは長さを適用できないのかどうかが分かっている必
要があります。この情報については、次の表の「タイプ」列を参照してください。
v これらの API の動作について詳しくは、 Microsoft Web サイトで ODBC を検索してください。
タイプ
API
説明
その他の考慮事項
データ・ソースへの接続
注: 接続 API がサインオン・ダイアログのプロンプトを出す方法については、 503 ページの『サインオン・ダイアログの振る舞い』を参照してくだ
さい。詳しくは、『接続プール』も参照してください。
プログラミング
475
タイプ
API
説明
N/A
SQLAllocHandle
環境および接続ハンドルを入手しま
す。 1 個の環境ハンドルが、複数の
接続に使用されます。ステートメン
トや記述子ハンドルを割り振ること
もできます。
その他の考慮事項
Char
SQLConnect
特定のユーザー ID とパスワードを
含む特定のデータ・ソース名に接続
します。
ユーザー ID およびパスワードが指定されない場合に、この API
がサインオン・ダイアログを行うためのプロンプトを出すかどう
かを制御するオプションがあります。このオプションは、DSN
の「一般 (General)」タブの「接続オプション」のダイアログか
ら設定できます。
Char
SQLDriverConnect
接続ストリングで特定のドライバー
へ接続するか、ユーザーのためのド
ライバー・マネージャーとドライバ
ー接続のダイアログを表示するよう
に要求します。
すべてのキーワードを使用。DSN のみ必須。その他の値は任意
選択。詳しくは、 482 ページの『接続ストリング・キーワード』
を参照してください。
Char
SQLBrowseConnect
連続レベルの接続属性と有効属性の
値を戻します。接続属性ごとに値が
指定されると、データ・ソースに接
続します。
接続を試みるためには、SYSTEM キーワード、および DSN ま
たは DRIVER のいずれかのキーワードを指定しなければなりま
せん。それ以外のキーワードは、すべてオプションです。セキュ
リティー上の理由により、PWD キーワードは出力ストリングで
は戻されないようになっている点に注意してください。インプリ
メンテーションの問題については、 482 ページの『接続ストリン
グ・キーワード』を参照してください。
Byte
SQLGetInfo
特定のドライバーとデータ・ソース
に関する情報を戻します。
ドライバーまたはデータ・ソースに関する情報の取得
属性およびキーワードに基づいて別々に戻される特殊な属性で
す。SQLGetInfo によって戻される情報は、使用されているキー
ワードおよび属性に応じて異なります。影響を受ける InfoType
オプションは以下のとおりです。
v SQL_CATALOG_NAME_SEPARATOR - デフォルトではピリオ
ドが戻されます。接続ストリング・キーワード NAM を 1 に
設定すると、コンマが戻されます。
|
|
|
|
|
v SQL_CURSOR_COMMIT_BEHAVIOR、
SQL_CURSOR_ROLLBACK_BEHAVIOR - デフォルトでは
SQL_CB_PRESERVE が戻されます。接続属性
CWB_ATTR_PRESERVE_CURSORS が設定された場合は、
SQL_CB_DELETE が戻されます。
v SQL_DATA_SOURCE_READ_ONLY – デフォルトでは N が
戻されます。接続ストリング・キーワード CONNTYPE を 0
に設定すると、Y が戻されます。
v SQL_IDENTIFIER_QUOTE_CHAR - デフォルトでは二重引用
符が戻されます。使用されているアプリケーションが MS
QUERY (MSQRY32) である場合には、単一のブランクが戻さ
れます。
v SQL_IDENTIFIER_CASE – デフォルトでは SQL_IC_UPPER
が戻されます。接続ストリング・キーワード DEBUG でオプ
ション 2 が設定されている場合には、SQL_IC_MIXED が戻さ
れます。
|
|
|
|
|
|
|
|
|
|
|
v SQL_MAX_QUALIFIER_NAME_LEN – デフォルトでは 18 が
戻されます。接続ストリング・キーワード DEBUG でオプシ
ョン 8 が設定されている場合には、0 が戻されます。
v SQL_DRIVER_VER - ドライバーのバージョンを VV.RR.SSST
という形式で戻します。ここで、
– VV は IBM i Access 製品のバージョンを表します。
– RR は、IBM i Access 製品のリリース ID を表します。
– SSS は、IBM i Access 製品に適用済みの Service Pack の
番号です。
– T は、ODBC ドライバーの問題に適用済みのテスト修正の
バージョンです。ない場合は 0 になります。
476
IBM i: Windows アプリケーション・パッケージ: プログラミング
タイプ
API
説明
その他の考慮事項
N/A
SQLGetTypeInfo
サポートするデータ・タイプに関す
る情報を戻します。
異なる IBM i バージョンに対して実行すると、異なる結果デー
タ・タイプが得られます。例えば、DECFLOAT データ・タイプ
は、V6R1 またはそれ以降のサーバーに対して実行したときの結
果セットにのみ戻されます。
"LONG VARCHAR" データ・タイプは、結果セットには戻され
ません。この問題は、このタイプの長さを指定することを前提と
しているアプリケーションが原因となっています。"LONG
VARCHAR FOR BIT DATA" および "LONG VARGRAPHIC" も
同様の理由のために戻されません。
TYPE_NAME 列で、データ・タイプに括弧で囲んだ値が必要な
ときは、データ・タイプ名に括弧が含まれます。ただし、括弧が
データ・タイプ・ストリングの最後に来るときは、その括弧は省
略されます。次のストリングの例で、"CHAR" データ・タイプの
後には括弧が続いていますが、"DATA" データ・タイプの後には
括弧が続いていません。例: "CHAR() FOR BIT DATA"。
接続ストリング・キーワード GRAPHIC の設定値は、ドライバ
ーがグラフィック (DBCS) データ・タイプをサポートされるタイ
プとして戻すかどうかに影響を与えます。詳しくは、 504 ページ
の『ODBC データ・タイプおよびそれらと DB2 for i データベ
ース・タイプとの対応』を参照してください。
ドライバー属性の設定および検索
注: 次の API に適用可能なドライバー固有の接続およびステートメントの属性について詳しくは、 510 ページの『接続とステートメントの属性』を
参照してください。
Byte
SQLSetConnectAttr
接続オプションを設定します。
Byte
SQLGetConnectAttr
接続オプションの値を戻します。
N/A
SQLSetEnvAttr
環境オプションを設定します。
N/A
SQLGetEnvAttr
環境オプションの値を戻します。
Byte
SQLSetStmtAttr
ステートメント・オプションを設定
します。
SQL_ATTR_PARAMSET_SIZE、
SQL_ATTR_ROW_ARRAY_SIZE、 SQL_DESC_ARRAY_SIZE、
および SQL_ROWSET_SIZE 属性は、32767 行までサポートしま
す。
FOR FETCH ONLY または FOR UPDATE 文節を含む SELECT
ステートメントは、SQL_ATTR_CONCURRENCY 属性の現在の
設定値をオーバーライドします。 SQL_ATTR_CONCURRENCY
の設定値が SQL ステートメント内の文節と競合している場合、
SQLExecute または SQLExecDirect の実行中にはエラーが戻され
ません。
以下はサポートされていません。
v SQL_ATTR_ASYNC_ENABLE
v SQL_ATTR_RETRIEVE_DATA
v
SQL_ATTR_SIMULATE_CURSOR
v SQL_ATTR_USE_BOOKMARKS
v SQL_ATTR_FETCH_BOOKMARK_PTR
v SQL_ATTR_KEYSET_SIZE
SQL_ATTR_MAX_ROWS の設定はサポートされますが、静的カ
ーソルのパフォーマンスにしか影響しません。結果セット全体
は、このオプションが設定されていても、他のカーソル・タイプ
を使用して作成されます。 SQL 照会で FETCH FIRST x ROWS
ONLY 文節を使用すると、サーバーの作業量が削減されるため、
パフォーマンスが向上することがあります。この API は、次の
2 つの結果セット・タイプのカーソル行数を含むようにも拡張さ
れています。
v ストアード・プロシージャーの配列結果セット
v 静的カーソルの結果セット
プログラミング
477
タイプ
API
説明
その他の考慮事項
Byte
SQLGetStmtAttr
ステートメント・オプションの値を
戻します。
以下はサポートされていません。
v SQL_ATTR_ASYNC_ENABLE
v SQL_ATTR_RETRIEVE_DATA
v
SQL_ATTR_SIMULATE_CURSOR
v SQL_ATTR_USE_BOOKMARKS
v SQL_ATTR_FETCH_BOOKMARK_PTR
記述子フィールドの設定および検索
Byte
SQLGetDescField
記述子から情報を戻します。
Char
SQLGetDescRec
記述子から複数の情報を戻します。
Byte
SQLSetDescField
記述子フィールドを設定します。
SQL_DESC_ARRAY_STATUS_PTR および
SQL_DESC_ROWS_PROCESSED_PTR 以外の IRD には、記述子
フィールドは設定できません。
名前付きパラメーターはサポートしていません。
Char
SQLSetDescRec
記述子の複数のオプションを設定し
ます。
N/A
SQLCopyDesc
ある記述子から別の記述子に情報を
コピーします。
Char
SQLPrepare
後の実行のために、SQL ステートメ
ントを作成します。
SQLCopyDesc は名前付きパラメーターをサポートしません。
SQL 要求の作成
パッケージは、その接続用の SQL ステートメントが初めて準備
されるときに作成されます。このために、最初の準備には通常よ
りも完了するまで少し長く時間がかかります。既存パッケージに
何か問題がある場合、DSN セットアップ GUI で指定されたパッ
ケージの設定によっては最初の準備でエラーが戻される場合があ
ります。 DSN セットアップ GUI の「パッケージ」タブに、デ
フォルトのパッケージ設定があります。これらの設定は、パッケ
ージ設定が当該アプリケーションに合わせてまだカスタマイズさ
れていない場合に使用されます。これらは、グローバルな設定で
はない点に注意してください。
デフォルトでは、ドライバーは SQL ステートメント・テキスト
を、ユーザーのジョブに関連付けられている EBCDIC CCSID で
ホストに送信します。ドライバーが SQL ステートメント・テキ
ストを Unicode でホストに送信できるように、UNICODESQL キ
ーワードを 1 または 2 に設定します。 Unicode の SQL ステー
トメントを送信する場合は、EBCDIC SQL ステートメントを含
む既存のパッケージとの衝突を避けるため、ドライバーは別のパ
ッケージ名を生成することに注意してください。接続ストリン
グ・キーワード UNICODESQL を設定すると、アプリケーショ
ンでは、SQL ステートメント内のリテラルとしてユニコード・
データを指定できるようになります。
準備および実行することが推奨されていない幾つかの SQL ステ
ートメントについては、『SQL ステートメントの考慮事項』を
参照してください。
ドライバーがサポートするエスケープ・シーケンスおよびスカラ
ー関数については、 517 ページの『SQLPrepare および
SQLNativeSQL エスケープ・シーケンスおよびスカラー関数』を
参照してください。
478
IBM i: Windows アプリケーション・パッケージ: プログラミング
タイプ
API
説明
その他の考慮事項
Byte
SQLBindParameter
SQL ステートメントの中のパラメー
ター用に記憶域を割り当てます。
実際のホスト・パラメーター (列) データ・タイプに指定されて
いる C タイプから直接、データ変換されます。
指定されている SQL データ・タイプおよび列サイズは無視され
ます。
文字データを含む変換では、クライアント・コード・ページから
列 CCSID に直接変換が行われます。
|
|
|
|
|
IBM i はプロシージャー (IBM i 7.1 以上) および機能 (IBM i
7.2 以上) のデフォルト・パラメーターをサポートしますが、
SQL_DEFAULT_PARAM は INSERT および UPDATE ステート
メントでデフォルトの列値を使用した場合にのみサポートされま
す。
|
|
|
|
|
|
|
|
|
|
INSERT または UPDATE ステートメント上の標識値に対してド
ライバー固有の値 CWB_UNASSIGNED を指定すると、あたかも
パラメーター・マーカーがないかのようにデータベースがこのス
テートメントを扱うようにすることができます。この場合、ステ
ートメントが UPDATE であると列が更新されず、ステートメン
トが INSERT であるとデフォルト値が使用されます。これによ
り、アプリケーションは汎用 INSERT または UPDATE ステー
トメントをコーディングできるようになりますが、そのステート
メントの呼び出しによって影響を受ける列を選択的に選ぶことが
できます。
Char
SQLGetCursorName
ステートメント・ハンドルに関連し
たカーソル名を戻します。
ドライバーは、二重引用符で囲まれていないすべてのカーソル名
を大文字にします。
Char
SQLSetCursorName
カーソル名を指定します。
カーソル名は、引用符で囲まれていない場合には、大文字に変換
されます。引用符で囲まれたカーソル名は変換されません。例え
ば、myCursorName は MYCURSORNAME となりますが、
"myCursorName" は長さ 14 の myCursorName として扱われ
ます (引用符も長さに含まれるためです)。
ドライバーは、""、a から z、A から Z、0 から 9、または _
の文字のみをカーソル名の中でサポートします。無効な名前が入
力されても SQLSetCursorName はエラーを戻しませんが、後で無
効な名前を使用しようとした際に、エラーが戻されます。
カーソル名は、最大 128 文字 (前後に二重引用符がある場合はそ
れらも含めて) までとし、UNICODE から ANSI に変換可能な文
字で指定する必要があります。
アプリケーションで ODBC により DRDA® 接続を使用したい場
合は、以下の制約事項があります。
v DRDA 接続時にカーソル名は変更できません。
v カーソル名は、ドライバーによって変更され、カーソルがオー
プンした後、SQLGetCursorName により検査する必要がありま
す (SQLExecute または SQLExecDirect の後)。
要求の投入
N/A
SQLExecute
作成済みステートメントを実行しま
す。
SQLExecute は、PREFETCH、CONNTYPE、CMT、および
LAZYCLOSE などのいくつかの接続ストリング・キーワードの設
定値の影響を受けます。これらのキーワードの説明については、
482 ページの『接続ストリング・キーワード』を参照してくださ
い。
Char
SQLExecDirect
ステートメントを実行します。
SQLPrepare および SQLExecute を参照してください。
Char
SQLNativeSQL
ドライバーにより変換された SQL
ステートメントのテキストを戻しま
す。
Char
SQLDescribeParam
ステートメントの中の特定のパラメ
ーターについての記述を戻します。
N/A
SQLNumParams
ステートメントの中のパラメーター
の数を戻します。
プログラミング
479
タイプ
API
説明
N/A
SQLParamData
実行時にデータが送られるパラメー
ターに割り当てられた記憶域の値を
戻します (長いデータ値の場合に有
用)。
その他の考慮事項
Byte
SQLPutData
パラメーター値の一部または全部を
送信します (長いデータ値の場合に
有用)。
N/A
SQLRowCount
挿入、更新、または削除要求の影響
を受けた行数を戻します。
N/A
SQLNumResultCols
結果セットの中の列の番号を戻しま
す。
Char
SQLDescribeCol
結果セットの中の列を記述します。
Byte
SQLColAttribute
結果セットの中の列の属性を記述し
ます。
Byte
SQLBindCol
結果列用に記憶域を割り当て、デー
タ・タイプを指定します。
N/A
SQLExtendedFetch
結果セットの中の行を戻します。こ
れは、2.x ODBC API としてサポー
トされています。しかし、新規アプ
リケーションは、これではなく
SQLFetchScroll API を使用する必要
があります。
結果および関連情報の検索
この API は、静的カーソルを使用する結果セットまたは配列結
果セットのカーソル行カウントも含めるように拡張されました。
行セット・サイズに、SQL_ATTR_ROW_ARRAY_SIZE ではな
く、ステートメント属性 SQL_ROWSET_SIZE の値を使用しま
す。
SQLExtendedFetch は、行サイズが 1 の場合に、 SQLSetPos お
よび SQLGetData との組み合わせでのみ使用できます。
SQL_FETCH_BOOKMARK はサポートされていません。
カタログ API の結果セット (SQLTables や SQLColumns など)
は順方向専用および読み取り専用です。カタログ API によって
生成された結果セットと一緒に SQLExtendedFetch を使用した場
合、スクロールは行えません。
N/A
SQLFetch
結果セットの中の行を戻します。
N/A
SQLFetchScroll
結果セットの中の行を戻します。ス
クロール可能カーソルで使用できま
す。
ドライバーがブックマークをサポートしていないため、
SQL_FETCH_BOOKMARK の取り出し方向はサポートされませ
ん。
Byte
SQLGetData
結果セットの 1 行、1 列の一部また
は全部を戻します (長いデータ値の
場合に有用)。
SQLGetData は、単一行取り出しでのみ使用することができま
す。行配列サイズが 1 よりも大きい場合、SQLGetData によって
エラーが報告されます。
N/A
SQLSetPos
取り出したデータのブロックの中に
カーソルを置きます。
SQL_UPDATE、SQL_DELETE、および SQL_ADD は、
Operations パラメーターのオプションとしてはサポートされませ
ん。
SQL_LOCK_EXCLUSIVE および SQL_LOCK_UNLOCK は、
LockType パラメーターのオプションとしてはサポートされませ
ん。
N/A
SQLBulkOperations
更新、削除、およびブックマークに
よる取り出しなど、大量の挿入およ
び大量のブックマーク操作を実行し
ます。
N/A
SQLMoreResults
結果セットがさらにあるかどうかを
判別します。まだある場合は、次の
結果セットが処理できるように初期
設定を行います。
Byte
SQLGetDiagField
診断情報を戻します。
Char
SQLGetDiagRec
追加のエラーまたは状況情報を戻し
ます。
このドライバーは SQLBulkOperations をサポートしていません。
データ・ソース・システム・テーブル情報の取得
Char
480
SQLColumnPrivileges
1 つまたは複数のテーブルについて
の列のリストと関連する特権を戻し
ます。
IBM i: Windows アプリケーション・パッケージ: プログラミング
タイプ
API
説明
Char
SQLColumns
1 つまたは複数のテーブルの列に関
する情報のリストを戻します。
その他の考慮事項
Char
SQLForeignKeys
外部キーが、指定されたテーブル用
に存在する場合は、その外部キーを
含む列名のリストを戻します。
Char
SQLProcedureColumns
指定のプロシージャーに、入出力パ
ラメーターのリストを戻します。
Char
SQLProcedures
特定のデータ・ソースに保管された
プロシージャー名のリストを戻しま
す。
Char
SQLSpecialColumns
指定されたテーブルにある 1 つの行
を固有に識別する、最適な列のセッ
トに関する情報を検索します。ま
た、トランザクションでその行の任
意の値が更新されるたびに自動的に
更新される列についての情報も検索
します。
SQL_BEST_ROWID オプションを指定して呼ばれた場合は、その
テーブルのすべての索引付きの列を戻します。
Char
SQLStatistics
単一テーブルと、そのテーブルと関
連した索引のリストに関する統計を
検索します。
派生キー索引に関する情報の検索に SQLStatistics が使用される
と、COLUMN_NAME 結果セット列はその派生キー索引を表す式
を戻します。
索引の作成時に WHERE 文節を使用した場合、
FILTER_CONDITION 結果セット列に Where 式が戻されます。
Char
SQLTables
データ・ソースのスキーマ、テーブ
ル、またはテーブル・タイプのリス
トを戻します。
Char
SQLTablePrivileges
テーブルのリストおよびそれぞれの
テーブルと関連する特権を戻しま
す。
Char
SQLPrimaryKeys
テーブル用の基本キーを構成する列
の名前のリストを戻します。
N/A
SQLFreeStmt
ステートメント処理を終了し、関連
するカーソルをクローズし、保留結
果を廃棄します。
N/A
SQLCloseCursor
ステートメント・ハンドルでオープ
ンされているカーソルをクローズし
ます。
N/A
SQLCancel
SQL ステートメントを取り消しま
す。
すべての照会を取り消せるわけではありません。これは、実行に
時間のかかっている照会の場合にのみお勧めします。詳細につい
ては、 523 ページの『長時間実行照会の処理』を参照してくだ
さい。
N/A
SQLEndTran
トランザクションをコミット、また
はロールバックします。
コミットメント制御については、『コミットメント制御の考慮事
項』を参照してください。
N/A
SQLDisconnect
接続をクローズします。
N/A
SQLFreeHandle
ハンドルに関連した資源をリリース
します。
522 ページの『SQLTables の説明』を参照してください。
ステートメントの終結処理
接続の終了
関連資料:
503 ページの『ODBC API の制約事項およびサポートされない関数』
IBM i Access の ODBC ドライバーにおける関数のインプリメント方法の中には、「Microsoft ODBC
Software Development Kit Programmer's Reference」に記述されている仕様と一致しないものがあります。
関連情報:
Microsoft Web サイト
プログラミング
481
SQL ステートメントの考慮事項:
IBM i Access 関数で ODBC を使用する際に避けるべき SQL ステートメントを確認します。
準備および実行することが推奨されていない SQL ステートメントが幾つかあります。以下はその例です。
v SET TRANSACTION
v SET SCHEMA
v SET PATH
v COMMIT
v ROLLBACK
v CONNECT TO
v DISCONNECT ALL
これらのステートメントでは、同じ振る舞いを、ODBC を介して別の方法で実現できます。例えば、
ODBC 接続の自動コミットをオフにする場合は、COMMIT ステートメントまたは ROLLBACK ステート
メントを実行する代わりに、 SQLEndTran オプションを使用することができます。
SET SESSION AUTHORIZATION SQL ステートメントは、ODBC 接続プールと組み合わせて使用した場
合に、予測不能の振る舞いを生じる接続の制御下にあるユーザーを変更します。 ODBC を介して SET
SESSION AUTHORIZATION ステートメントを使用する場合には、実行される SET SESSION
AUTHORIZATION 用以外のすべてのオープン・ステートメント・ハンドルを解放することをお勧めしま
す。 SET SESSION AUTHORIZATION の実行が終了したら、そのステートメント・ハンドルを解放して
ください。
接続ストリング・キーワード:
IBM i Access の ODBC ドライバー・サポートでは、ODBC 接続の振る舞いを変更するために、複数の接
続ストリング・キーワードを使用します。
ODBC データ・ソースがセットアップされる際に、同じキーワードおよびそれらの値が保管されます。
ODBC アプリケーションが接続を行う際には、接続ストリングで指定されたキーワードにより、ODBC デ
ータ・ソースで指定した値がオーバーライドされます。
IBM i Access の ODBC ドライバー・サポートが認識する接続ストリング・キーワードについて詳しく
は、以下の表にある該当項目を参照してください。「キーワード」列にある接続ストリング・キーワード
は、SQLBrowseConnect および SQLDriverConnect に渡される接続ストリング上で使用できるものです。
「キーワード」列にある ODBC.INI キーワードは、ODBC.INI ファイル内でデータ・ソース名 (DSN) レ
ベルで設定できるものです。 Windows 上では、ODBC.INI 情報はレジストリーに保管されます。 Linux
上では、ODBC.INI 情報は /etc の下にある odbc.ini ファイル (システム DSN の場合) または
$HOME/.odbc.ini ファイル (ユーザー DSN の場合) に保管されます。
表 3. 一般プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: DSN
482
説明
接続に使用する ODBC データ・ソースの名前を指定します。
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 3. 一般プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
説明
接続ストリング: DRIVER
使用する ODBC ドライバーの名前を指定します。
注: DSN プロパティーが指定されている場合には、これは使用しないでく
ださい。
使用できる値:
v IBM i Access ODBC Driver
v iSeries Access ODBC Driver注
1
v Client Access ODBC Driver (32 ビット)注
接続ストリング: PWD
1
接続用の IBM i ユーザー ID のパスワードを指定します。
ODBC.INI: Password
接続ストリング: SIGNON注
ODBC.INI: Signon注
2
2
現行のユーザー ID およびパスワード情報で接続を行うことができない場合
にどのデフォルトのユーザー ID を使用するのかを指定します。
使用できる値:
v 0 = Windows ユーザー名を使用
v 1 = デフォルトのユーザー ID を使用
v 2 = なし
v 3 = IBM iナビゲーターのデフォルトを使用
v 4 = Kerberos プリンシパルを使用
デフォルト: 3
接続ストリング: SSL
ODBC.INI: SSL注
注 2
2
サーバーと通信するために Secure Sockets Layer (SSL) 接続を使用するかど
うかを指定します。
使用できる値:
v 0 = パスワードのみを暗号化する
v 1 = すべてのクライアント/サーバー通信を暗号化する
デフォルト: 0
接続ストリング: SYSTEM
接続する IBM i のシステム名を指定します。詳しくは、ODBC 接続 API
のための IBM i 名の形式を参照してください。
ODBC.INI: System
接続ストリング: UID
IBM i 接続のユーザー ID を指定します。
ODBC.INI: UserID
プログラミング
483
表 4. サーバー・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
説明
接続ストリング: CMT
デフォルトのトランザクション分離レベルを指定します。
ODBC.INI: CommitMode
使用できる値:
v 0 = 即時コミット (*NONE)
v 1 = コミット読み取り (*CS)
v 2 = 非コミット読み取り (*CHG)
v 3 = 反復可能読み取り (*ALL)
v 4 = シリアライズ可能 (*RR)
デフォルト: 2
接続ストリング: CONNTYPE
接続におけるデータベース・アクセスのレベルを指定します。
ODBC.INI: ConnectionType
使用できる値:
v 0 = 読み取り / 書き込み (すべての SQL ステートメントを使用可能)
v 1 = 読み取り / 呼び出し (SELECT および CALL ステートメントを使
用可能)
v 2 = 読み取り専用 (SELECT ステートメントのみ)
デフォルト: 0
接続ストリング: DATABASE
接続する IBM i リレーショナル・データベース (RDB) 名を指定します。
ODBC.INI: Database
このオプションの特殊値には、空ストリングまたは *SYSBAS の指定が含
まれます。空ストリングは、データベースに関してユーザー・プロファイ
ルのデフォルトの設定値を使用することを表します。 *SYSBAS を指定す
ると、ユーザーは SYSBAS データベース (RDB 名) に接続されます。
デフォルト: 空ストリング
接続ストリング: DBQ
ODBC.INI: DefaultLibraries
サーバー・ジョブのライブラリー・リストに追加する IBM i ライブラリー
を指定します。ライブラリーはコンマまたはスペースで区切って指定しま
す。サーバー・ジョブの現行ライブラリー・リストでは、プレースホルダ
ーとして *USRLIBL を使用することができます。このライブラリー・リス
トは、未修飾のストアード・プロシージャー呼び出しの解決、およびカタ
ログ API 呼び出しからのライブラリーの検出に使用されます。 *USRLIBL
を指定しない場合、サーバー・ジョブの現行ライブラリー・リストは、指
定されたライブラリーによって置き換えられます。
サポートされるライブラリーの数は 75 です。この制限を超えたライブラ
リーは無視されます。
注: このプロパティーでリストされた最初のライブラリーは、デフォルトの
スキーマ (またはライブラリー) でもあり、SQL ステートメント内の未修
飾名を解決するために使用されます。デフォルト以外のスキーマを指定す
るには、ライブラリーの前にコンマを入力する必要があります。
デフォルト: QGPL
接続ストリング: MAXDECPREC
戻す 10 進数データの最大精度を指定します。
ODBC.INI: MaximumDecimalPrecision
使用できる値: 31 または 63
デフォルト: 31
484
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 4. サーバー・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: MAXDECSCALE
説明
10 進データを必要とする演算で使用する最大スケールを指定します。この
値は MAXDECPREC の値より小さくなければなりません。
ODBC.INI: MaximumDecimalScale
使用できる値: 0 - 63
デフォルト: 31
接続ストリング: MINDIVSCALE
10 進データを必要とする演算で使用する最小スケールを指定します。
ODBC.INI: MinimumDivideScale
使用できる値: 0 - 9
デフォルト: 0
接続ストリング: NAM
テーブルの参照時に使用する命名規則を指定します。詳しくは、DB2 for i
SQL リファレンス所収の命名規則を参照してください。
ODBC.INI: Naming
使用できる値:
v 0 = *SQL
v 1 = *SYS
デフォルト: 0
表 5. データ・タイプ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: DFT
説明
SQL ステートメント内の日付リテラルで使用される日付形式を指定しま
す。
ODBC.INI: DateFormat
使用できる値:
v 0 = yy/dd (*JUL)
v 1 = mm/dd/yy (*MDY)
v 2 = dd/mm/yy (*DMY)
v 3 = yy/mm/dd (*YMD)
v 4 = mm/dd/yyyy (*USA)
v 5 = yyyy-mm-dd (*ISO)
v 6 = dd.mm.yyyy (*EUR)
v 7 = yyyy-mm-dd (*JIS)
デフォルト: 5
プログラミング
485
表 5. データ・タイプ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: DSP
ODBC.INI: DateSeparator
説明
SQL ステートメント内の日付リテラルで使用される日付区切り文字を指
定します。
注: このプロパティーは、DateFormat プロパティーが 0 (*JUL)、1
(*MDY)、2 (*DMY)、または 3 (*YMD) に設定されていない場合には効
果がありません。
使用できる値:
v 0 = "/" (スラッシュ)
v 1 = "-" (ダッシュ)
v 2 = "." (ピリオド)
v 3 = "," (コンマ)
v 4 = " " (ブランク)
デフォルト: 1
接続ストリング: DEC
SQL ステートメント内の数値リテラルで使用される小数点を指定しま
す。
ODBC.INI: Decimal
使用できる値:
v 0 = "." (ピリオド)
v 1 = "," (コンマ)
デフォルト: 0
接続ストリング:
DECFLOATERROROPTION
10 進浮動小数点データ・タイプのエラーを検出した場合に、警告として
報告するか、またはデータ・マッピング・エラーとして報告するかを指
定します。これを指定しない場合、サーバー属性値は変更されません。
ODBC.INI: DecfloatErrorOption
使用できる値:
v 0 = 10 進浮動小数点エラーを、データ・マッピング・エラーとして報
告します。
v 1 = 10 進浮動小数点エラーを、警告として報告します。
デフォルト: 0
486
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 5. データ・タイプ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング:
DECFLOATROUNDMODE
説明
結果に対する丸めが許可されている場合、丸めモードを指定します。
使用できる値:
ODBC.INI: DecFloatRoundMode
v 0 = ROUND_HALF_EVEN - 最も近い数字に丸めます。 2 つの数字
の中間にある場合は、最も近い偶数に丸めます。
v 1 = ROUND_HALF_UP - 最も近い数字に丸めます。 2 つの数字の中
間にある場合は、切り上げます。
v 2 = ROUND_DOWN - 最も近い数字のうち、小さい方の数字に丸めま
す。これは、切り捨てと同じです。
v 3 = ROUND_CEILING - 正の無限大に近づくように丸めます。
v 4 = ROUND_FLOOR - 負の無限大に近づくように丸めます。
v 5 = ROUND_HALF_DOWN - 最も近い数字に丸めます。 2 つの数字
の中間にある場合は、切り捨てます。
v 6 = ROUND_UP - 最も近い数字のうち、大きい方の数字に丸めま
す。
デフォルト: 0
接続ストリング:
MAPDECIMALFLOATDESCRIBE
DECFLOAT 演算の結果のフォーマットを指定します。
使用できる値:
ODBC.INI: MapDecimalFloatDescribe
v 1 = SQL_ VARCHAR
v 3 = SQL_ DOUBLE
デフォルト: 1
接続ストリング: TFT
SQL ステートメント内の時刻リテラルで使用される時刻形式を指定しま
す。
ODBC.INI: TimeFormat
使用できる値:
v 0 = hh:mm:ss (*HMS)
v 1 = hh:mm AM/PM (*USA)
v 2 = hh.mm.ss (*ISO)
v 3 = hh.mm.ss (*EUR)
v 4 = hh:mm:ss (*JIS)
デフォルト: 0
プログラミング
487
表 5. データ・タイプ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: TSP
ODBC.INI: TimeSeparator
説明
SQL ステートメント内の時刻リテラルで使用される時刻区切り文字を指
定します。
注: このプロパティーは、TimeFormat プロパティーが 0 (*HMS) に設定
されていない場合には効果がありません。
使用できる値:
v 0 = ":" (コロン)
v 1 = "." (ピリオド)
v 2 = "," (コンマ)
v 3 = " " (ブランク)
デフォルト: 0
接続ストリング: TSFT
ODBC.INI: TimestampFormat
ドライバーによって TIMESTAMP 値が SQL_C_CHAR に変換されたと
きに、その TIMESTAMP 値の形式を指定します。詳しくは、DB2 for i
SQL リファレンス所収の日付/時刻の値のストリング表記を参照してくだ
さい。
使用できる値:
v 0 = yyyy-mm-dd hh:mm:ss.[n...] (*ISO)
v 1 = yyyy-mm-dd.hh.mm.ss.[n...](*IBM)
デフォルト: 0
接続ストリング: XMLCURIMPPARSE
ODBC.INI: XMLCurrentImplicitParse
接続に使用する XMLPARSE オプションを指定します。この属性は、デ
ータが検証なしに暗黙的に構文解析されるときに、シリアライズされた
XML データ内の空白が DB2 によってどのように処理されるかを示しま
す。
使用できる値:
v 0 = 空白の除去
v 1 = 空白の保持
デフォルト: 0
488
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 5. データ・タイプ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: XMLDECLARATION
説明
結果セットで戻される XML 列と一緒に戻される XML 宣言を指定しま
す。
ODBC.INI: XMLDeclarationFormat
これはビット・フラグ値です。任意の使用可能値を加算して合計値を計
算することができます。
使用できる値:
v 0 = 宣言もバイト・オーダー・マーク (BOM) も出力バッファーに追
加されない。
v 1 = ターゲット・エンコードが UTF-16 である場合、該当するエンデ
ィアンネス内のバイト・オーダー・マーク (BOM) が、出力バッファ
ーの前に付加される。
v 2 = XML バージョンのみを含む、最小の XML 宣言が生成される。
v 4 = ターゲット・エンコードを識別するエンコード属性が、生成され
る任意の XML 宣言に追加される。そのため、この設定は、この属性
の値を計算するときに 2 の設定も含まれている場合のみ有効です。
デフォルト: 7
表 6. パッケージ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: DFTPKGLIB
ODBC.INI: DefaultPkgLibrary
説明
SQL パッケージ用のライブラリーを指定します。
注: このプロパティーは、XDYNAMIC プロパティーが 1 に設定されていな
い場合には効果がありません。
デフォルト: QGPL
プログラミング
489
表 6. パッケージ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: PKG
ODBC.INI: DefaultPackage
説明
拡張動的 (パッケージ) サポートがどのように振る舞うのかを指定します。
注: このプロパティーは、XDYNAMIC プロパティーが 1 に設定されていな
い場合には効果がありません。
使用できる値: A/DEFAULT(IBM),x,0,y,z,0
x オプションの値:
v 1 = 使用 (パッケージを使用するが、パッケージにそれ以上 SQL ステー
トメントを追加しない)
v 2 = 使用 / 追加 (パッケージを使用し、新規 SQL ステートメントをパッ
ケージに追加する)
y オプションの値:
v 0 = SQL パッケージ・エラーが起こったときにエラー (SQL_ERROR) を
アプリケーションに返す
v 1 = SQL パッケージ・エラーが起こったときに警告
(SQL_SUCCESS_WITH_INFO) をアプリケーションに返す
v 2 = SQL パッケージ・エラーが起こったときに成功 (SQL_SUCCESS) を
アプリケーションに返す
z オプションの値:
v 0 = SQL パッケージをメモリー内のキャッシュに入れない
v 1 = SQL パッケージをメモリー内のキャッシュに入れる (サーバーへの通
信量が減る可能性があります)
デフォルト: A/DEFAULT(IBM),2,0,1,0,512
接続ストリング: XDYNAMIC
拡張動的 (パッケージ) サポートを使用するかどうかを指定します。
ODBC.INI: ExtendedDynamic
拡張動的サポートを使用すると、動的 SQL ステートメントをサーバーでキ
ャッシングするためのメカニズムが提供されます。特定の SQL ステートメ
ントを最初に実行するときには、そのステートメントがサーバー上の SQL
パッケージに保管されます。その後同じ SQL ステートメントを実行すると
きには、サーバーは SQL パッケージに保管された情報を使用することによ
り、かなりの部分の処理をスキップすることができます。詳細については、
527 ページの『拡張動的 SQL の使用』を参照してください。
使用できる値:
v 0 = 拡張動的サポートを使用不可にする
v 1 = 拡張動的サポートを使用可能にする
デフォルト: 1
490
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 7. パフォーマンス・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: BLOCKFETCH
ODBC.INI: BlockFetch
説明
1 行の取り出しで内部ブロックを行うかどうかを指定します。これを設定する
と、ドライバーは、あるレコードがアプリケーションによって要求されたとき
に、レコードの取り出しを最適化しようと試みます。そのアプリケーションが
後で検索できるように、ドライバーが複数のレコードを検索し、保管します。
アプリケーションが別の行を要求したときに、ドライバーは、あらためてホス
ト・データベースにフローを送らなくてもその行を獲得することができます。
これを設定しない場合、ブロックは、特定のステートメントに関するアプリケ
ーションの ODBC 設定値に基づいて使用されます。このオプションの設定に
ついて詳しくは、レコード・ブロック化の微調整に関するトピックを参照して
ください。
使用できる値:
v 0 = ODBC 設定値を使用してブロック化を行う
v 1 = 1 行の取り出しでブロックを使用する
デフォルト: 1
接続ストリング: BLOCKSIZE
ODBC.INI: BlockSizeKB
FETCH 要求で取り出されてから、クライアントのキャッシュに入れられるブ
ロック・サイズ (キロバイト単位) を指定します。このプロパティーは、
BLOCKFETCH プロパティーが 1 に設定されていない場合には効果がありま
せん。ブロック・サイズを大きくするほど、サーバーへの通信頻度が少なくな
るため、パフォーマンスが向上する可能性があります。
使用できる値: 1 – 8192
デフォルト: 256
接続ストリング: COMPRESSION
ODBC.INI: AllowDataCompression
サーバーとの間で送受信されるデータを圧縮するかどうかを指定します。多く
の場合には、データ圧縮をおこなうと、ドライバーとサーバーとの間で伝送さ
れるデータが少なくなるため、パフォーマンスが向上します。
使用できる値:
v 0 = 圧縮を使用不可にする
v 1 = 圧縮を使用可能にする
デフォルト: 1
接続ストリング: CONCURRENCY
ODBC.INI: Concurrency
すべてのカーソルを更新可能として開き、ODBC の並行性設定値をオーバーラ
イドするかどうかを指定します。
注: 次の 2 つの場合、このオプションを設定しても効果はありません。
1. SELECT SQL ステートメントを作成するときに、FOR FETCH ONLY ま
たは FOR UPDATE 文節が追加される可能性があります。これらのいずれ
かの文節が SQL ステートメントに存在していると、ODBC ドライバーは
その文節に関連付けられている並行性を優先します。
2. カタログ結果セットは常に読み取り専用です。
使用できる値:
v 0 = ODBC の並行性設定値を使用する
v 1 = すべてのカーソルを更新可能として開く
デフォルト: 0
プログラミング
491
表 7. パフォーマンス・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング:
CURSORSENSITIVITY
説明
カーソルをオープンする場合に使用するカーソル感度を指定します。このオプ
ションは、同じ接続でオープンされるすべての下方専用の動的カーソルに適用
されます。静的カーソルは常にインセンシティブです。
ODBC.INI: CursorSensitivity
使用できる値:
v 0 - 未指定/アセンシティブ
v 1 = インセンシティブ
v 2 = センシティブ
接続ストリング: EXTCOLINFO
ODBC.INI: ExtendedColInfo
拡張列情報は、SQLGetDescField および SQLColAttribute API がインプリメン
テーション行記述子 (IRD) 情報として戻す内容に影響を与えます。拡張列情
報は、SQLPrepare API が呼び出された後で使用可能になります。戻される情
報は以下のとおりです。
v SQL_DESC_AUTO_UNIQUE_VALUE
v SQL_DESC_BASE_COLUMN_NAME
v SQL_DESC_BASE_TABLE_NAME および SQL_DESC_TABLE_NAME
v SQL_DESC_LABEL
v SQL_DESC_SCHEMA_NAME
v SQL_DESC_SEARCHABLE
v
SQL_DESC_UNNAMED
v SQL_DESC_UPDATABLE
注: ドライバーが SQL_DESC_AUTO_UNIQUE_VALUE フラグを設定するの
は、ある列が、数値データ・タイプ (整数など) に関する、ALWAYS オプシ
ョンを指定された識別列である場合のみです。識別列の詳細については、
『DB2 for i SQL 解説書』を参照してください。
使用できる値:
v 0 = 拡張列情報を検索しない
v 1 = 拡張列情報を検索する
デフォルト: 0
接続ストリング: LAZYCLOSE
ODBC.INI: LazyClose
後続の要求があるまでカーソルのクローズを遅延させるかどうかを指定しま
す。遅延を指定すると、要求の合計数が減少し、全体的なパフォーマンスが向
上します。
注: このオプションを指定すると、クローズ要求の後もカーソルが結果セット
行でロックを引き続き維持するために、問題が生じることがあります。
使用できる値:
v 0 = すべてのカーソルを即時にクローズする
v 1 = カーソルのクローズを次の要求まで遅延する
デフォルト: 0
492
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 7. パフォーマンス・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: MAXFIELDLEN
ODBC.INI: MaxFieldLength
説明
結果セットの一部として検索することのできる最大 LOB (ラージ・オブジェ
クト) サイズを、K バイト単位で指定します。このしきい値よりも大きな
LOB は、サーバーとの追加の通信を使用して、分割して検索されます。 LOB
しきい値を大きくすると、サーバーとの通信頻度は減少しますが、使用されな
いものも含め、ダウンロードされる LOB データが多くなります。 LOB しき
い値を小さくすると、サーバーとの通信頻度が増大しますが、必要な LOB デ
ータのみがダウンロードされるようになります。
注:
v このプロパティーを 0 に設定すると、ドライバーは常に LOB 値を追加の
通信の流れとともに取得するように強制されます。
v このプロパティーを 15360 KB より大きく設定すると無効になります。
15360 KB よりも大きいものは、サーバーから分割して取得されます。デー
タを分割して取得することで、どの時点でもクライアント上で必要なメモリ
ー量を減らします。
使用できる値: 0 ― 2097152
v
v
デフォルト: 32
接続ストリング: PREFETCH
ODBC.INI: PreFetch
SELECT ステートメントの実行時にデータを事前取り出しするかどうかを指定
します。事前取り出しを行うと、先頭部分の行にアクセスするときのパフォー
マンスが向上します。
使用できる値:
v 0 = データを事前取り出ししない
v 1 = データを事前取り出しする
デフォルト: 1
接続ストリング: QRYSTGLMT
照会のストレージ制限を指定します。ストレージ使用量の見積もりが、このパ
ラメーターで指定したストレージ制限を上回る場合、照会は実行されません。
ODBC.INI: QueryStorageLimit
使用できる値:
v *NOMAX = 照会制限なし
v 0 から 2147352578
デフォルト: *NOMAX
プログラミング
493
表 7. パフォーマンス・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング:
QUERYOPTIMIZEGOAL
説明
照会の最適化目標を指定します。このパラメーターは、QAQQINI オプション
の OPTIMIZATION_GOAL に対応します。詳しくは、『DB2 for i SQL 解説
書』の QAQQINI オプションを参照してください。
ODBC.INI: QueryOptimizeGoal
使用できる値:
v 0 = 拡張動的サポートが有効な場合は、*ALLIO 目標を使用し、それ以外の
場合は *FIRSTIO 目標を使用する。
v 1 = *FIRSTIO - 最初のデータ・ブロックを可能な限りすぐに戻す。
v 2 = *ALLIO - 完全な結果セットがアプリケーションによって読み取られる
場合と同様に最適化する。
デフォルト: 0
接続ストリング: QUERYTIMEOUT
ODBC.INI: QueryTimeout
ドライバーが照会タイムアウト属性 SQL_ATTR_QUERY_TIMEOUT のサポー
トを使用不可にするかどうかを指定します。使用不可にすると、SQL 照会は
終了するまで実行されます。
使用できる値:
v 0 = 照会タイムアウト属性のサポートを使用不可にする
v 1 = 照会タイムアウト属性を設定できるようにする
デフォルト: 1
表 8. 言語プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: LANGUAGEID
ODBC.INI: LanguageID
説明
ソート・シーケンスの選択に使用する 3 文字の言語 ID を指定します。このプ
ロパティーは、SORTTYPE プロパティーが 2 に設定されていない場合には効
果がありません。
使用できる値:
AFR、ARA、BEL、BGR、CAT、CHS、CHT、CSY、DAN、DES、DEU、ELL、
ENA、ENB、ENG、ENP、ENU、ESP、EST、FAR、FIN、FRA、FRB、FRC、
FRS、GAE、HEB、HRV、HUN、ISL、ITA、ITS、JPN、KOR、LAO、LVA、
LTU、MKD、NLB、NLD、NON、NOR、PLK、PTB、PTG、RMS、ROM、
RUS、SKY、SLO、SQI、SRB、SRL、SVE、THA、TRK、UKR、URD、VIE
デフォルト: ENU
接続ストリング: SORTTABLE
ODBC.INI: SortTable
494
システムに保管されるソート・シーケンス・テーブルのライブラリーおよびフ
ァイル名を指定します。このプロパティーは、SORTTYPE プロパティーが 3
に設定されていない場合には効果がありません。
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 8. 言語プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: SORTTYPE
説明
レコードをクライアントに送信する前にサーバーがそのレコードをどのように
ソートするのかを指定します。
ODBC.INI: SortSequence
使用できる値:
v 0 または 1 = 16 進値に基づいてソートする
v 2 = LANGUAGEID プロパティーに設定されている言語に基づいてソートす
る
v 3 = SORTTABLE プロパティーに設定されているソート・シーケンス・テー
ブルに基づいてソートする
デフォルト: 0
接続ストリング: SORTWEIGHT
ODBC.INI: SortWeight
レコードをソートする際にサーバーが大文字小文字をどのように扱うのかを指
定します。このプロパティーは、SORTTYPE プロパティーが 2 に設定されて
いない場合には効果がありません。
使用できる値:
v 0 = 共通の重み (大文字と小文字を同じ文字としてソート)
v 1 = 固有の重み (大文字と小文字を別の文字としてソート)
デフォルト: 0
表 9. カタログ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
説明
接続ストリング:
CATALOGOPTIONS
カタログ API が情報を戻す方法に影響を与える、1 つまたは複数のオプション
を指定します。
ODBC.INI: CatalogOptions
これはビット・フラグ値です。任意の使用可能値を加算して合計値を計算するこ
とができます。
使用できる値:
v 1 = SQLColumns 結果セット内の別名に関する情報を戻す。
v 2 = SQLTablePrivileges および SQLColumnPrivileges に関する結果セット情報
を戻す。
デフォルト: 3
接続ストリング: LIBVIEW
ODBC.INI: LibraryView
カタログ API でワイルドカードを使用する場合に、情報を戻す際に検索するラ
イブラリーのセットを指定します。多くの場合には、サーバー上のすべてのライ
ブラリーを検索すると時間がかかることから、デフォルトのライブラリー・リス
トまたはデフォルトのライブラリー・オプションを使用してください。
使用できる値:
v 0 = デフォルトのライブラリー・リストを使用する
v 1 = サーバー上のすべてのライブラリー
v 2 = デフォルトのライブラリーのみを使用する
デフォルト: 0
プログラミング
495
表 9. カタログ・プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: REMARKS
説明
カタログ API 結果セット内の REMARKS 列のテキストのソースを指定しま
す。
ODBC.INI: ODBCRemarks
使用できる値:
v 0 = IBM i オブジェクト記述
v 1 = SQL オブジェクト・コメント
デフォルト: 0
接続ストリング:
SEARCHPATTERN
ODBC.INI: SearchPattern
ドライバーがライブラリーおよびテーブル名内のストリング検索パターンおよび
下線をワイルドカード (検索パターン) として解釈するかどうかを指定します。
デフォルトでは、% は「任意の数の文字」のワイルドカードとして処理され、_
は「単一の文字」のワイルドカードとして処理されます。
使用できる値:
v 0 = 検索パターンをワイルドカードとして処理しない。
v 1 = 検索パターンをワイルドカードとして処理する。
デフォルト: 1
表 10. 変換プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング:
ALLOWUNSCHAR
説明
変換できない (サポート対象外であるため) 文字が検出されたときに発生するエラ
ー・メッセージを抑制するかどうかを指定します。
ODBC.INI: AllowUnsupportedChar 使用できる値:
v 0 = 変換できない文字があるときエラー・メッセージを報告する
v 1 = 変換できない文字があるときエラー・メッセージを抑制する
デフォルト: 0
接続ストリング: CCSID
デフォルトのクライアント・コード・ページ設定値をオーバーライドするコー
ド・ページを指定します。
ODBC.INI: CCSID
使用できる値: クライアント・コード・ページ設定値または 0 (デフォルトのクラ
イアント・コード・ページ設定値を使用)
デフォルト: 0
496
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 10. 変換プロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
説明
接続ストリング: GRAPHIC
このプロパティーは、ユニコード以外の CCSID が指定されたグラフィック
(DBCS) データ・タイプ GRAPHIC、VARGRAPHIC、LONG VARGRAPHIC、およ
び DBCLOB の処理に影響を与えます。このプロパティーは、2 つの異なる振る
舞いに影響を与えます。
ODBC.INI: Graphic
1. グラフィックス・フィールドの長さを SQLDescribeCol API が文字カウントで
報告するか、バイト・カウントで報告するか。
2. グラフィックス・フィールドを、SQLGetTypeInfo 結果セット内でサポートさ
れるタイプとして報告するかどうか。
使用できる値:
v 0 = 文字カウントを報告、サポートされないタイプとして報告する
v 1 = 文字カウントを報告、サポートされるタイプとして報告する
v 2 = バイト・カウントを報告、サポートされないタイプとして報告する
v 3 = バイト・カウントを報告、サポートされるタイプとして報告する
デフォルト: 0
SQL 16 進定数を SQL ステートメントでどのように解釈するかを指定します。
接続ストリング:
HEXPARSEROPT
使用できる値:
ODBC.INI: HexParserOpt
v 0 = 16 進定数を文字データとして扱う
v 1 = 16 進定数をバイナリー・データとして扱う
デフォルト: 0
接続ストリング: TRANSLATE
バイナリー・データ (CCSID 65535) をテキストに変換するかどうかを指定しま
す。
ODBC.INI: ForceTranslation
使用できる値:
v 0 = バイナリー・データをテキストに変換しない
v 1 = バイナリー・データをテキストに変換する
デフォルト: 0
接続ストリング: UNICODESQL
ユニコード SQL ステートメントをサーバーに送信するかどうかを指定します。
ODBC.INI: UnicodeSQL
使用できる値:
v 0 = EBCDIC SQL ステートメントをサーバーに送信する
v 1 = UCS-2 ユニコード SQL ステートメントを UCS-2 でサーバーに送信する
デフォルト: 0
接続ストリング: XLATEDLL
ODBC.INI: TranslationDLL注
注 2
2
接続ストリング: XLATEOPT注
ODBC.INI: TranslationOption注
2
2
ODBC ドライバーとサーバーの間でやり取りされるデータを変換するために
ODBC ドライバーが使用する DLL の絶対パス名を指定します。この DLL は、
接続が確立された際にロードされます。
変換 DLL に渡される 32 ビット整数変換オプションを指定します。このパラメー
ターはオプションです。このオプションの意味は、使用されている変換 DLL によ
って異なります。詳細については、変換 DLL とともに提供されている資料を参照
してください。このオプションは、XLATEDLL プロパティーが設定されていない
場合には使用されません。
デフォルト: 0
プログラミング
497
表 11. 診断プロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: QAQQINILIB
ODBC.INI: QAQQINILibrary
接続ストリング: SQDIAGCODE
説明
照会オプションのファイル・ライブラリーを指定します。照会オプションのファイ
ル・ライブラリーが指定されていると、ドライバーは、QRYOPTLIB パラメーター
にライブラリー名を渡して CHGQRYA コマンドを発行します。このコマンドは、
接続が確立された直後に発行されます。このオプションは、使用可能にするとパフ
ォーマンスに悪影響を与えるため、問題のデバッグ時またはサポート提供者によっ
て推奨された場合にのみ使用してください。
設定する DB2 for i SQL 診断オプションを指定します。技術サポートの提供者に
よって指示された場合にのみ使用してください。
ODBC.INI: SQDiagCode
接続ストリング: TRACE
ODBC.INI: Trace
1 つまたは複数のトレース・オプションを指定します。これらのオプションは、パ
フォーマンスに悪影響を与えるため、問題のデバッグ時またはサポート提供者によ
って推奨された場合にのみ使用するようにしてください。
これはビット・フラグ値です。任意の使用可能値を加算して合計値を計算すること
ができます。
使用できる値:
v 0 = トレースを行わない
v 2 = データベース・モニターを使用可能にする
v 4 = デバッグ開始 (STRDBG) コマンドを使用可能にする
v 8 = 切断時にジョブ・ログを印刷する
v 16 = ジョブ・トレースを使用可能にする
v 32 = データベース・ホスト・サーバー・トレースを使用可能にする
デフォルト: 0
表 12. その他のプロパティー用の IBM i Access ODBC 接続ストリング・キーワード
キーワード
接続ストリング: ALLOWPROCCALLS
ODBC.INI: AllowProcCalls
説明
接続属性 SQL_ATTR_ACCESS_MODE が
SQL_MODE_READ_ONLY に設定されている場合にストアード・
プロシージャーを呼び出すことができるかどうかを指定します。
使用できる値:
v 0 = ストアード・プロシージャーを呼び出すことができないよ
うにする
v 1 = ストアード・プロシージャーを呼び出すことができるよう
にする
デフォルト: 0
498
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 12. その他のプロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング:
CONCURRENTACCESSRESOLUTION
ODBC.INI: ConcurrentAccessResolution
説明
同時アクセス解決の設定が入っています。このプロパティーは、
行ロックの競合が検出されるときの処理方法を識別します。この
プロパティーは、分離レベル CS の読み取り専用照会のみに適用
されます。
使用できる値:
v 0 = サーバー設定値を使用する
v 1 = 現在コミットされている行を使用する
v 2 = 結果を待機する
v 3 = ロックをスキップする
デフォルト: 0
接続ストリング: DB2SQLSTATES
ODBC.INI: DB2SQLStates
ODBC で定義された SQL 状態または DB2 の SQL 状態を戻す
かどうかを指定します。 DB2 の SQL 状態について詳しくは、
『DB2 for i SQL 解説書』を参照してください。このオプション
は、ODBC アプリケーションのソース・コードを変更することが
できる場合にのみ使用するようにしてください。ほとんどのアプ
リケーションは、ODBC で定義された SQL 状態のみを処理する
ようにコーディングされているため、ODBC アプリケーションの
ソース・コードを変更することができない場合には、このオプシ
ョンは 0 に設定されたままにしてください。
使用できる値:
v 0 = ODBC 定義の SQL 状態を戻す
v 1 = DB2 の SQL 状態を戻す
デフォルト: 0
接続ストリング: DATETIMETOCHAR
ODBC.INI: ConvertDateTimeToChar
日付、時間、およびタイム・スタンプ・データ・タイプをアプリ
ケーションに報告する方法についての、1 つ以上のオプションを
指定します。このオプションは、24:00:00 のような日付値が使用
されるケースをサポートします。
これはビット・フラグ値です。任意の使用可能値を加算して合計
値を計算することができます。
使用できる値:
v 0 = DATE、TIME、および TIMESTAMP データ・タイプを
SQL_TYPE_DATE、SQL_TYPE_TIME、および
SQL_TYPE_TIMESTAMP としてマップする
v 1 = DATE データ・タイプを SQL_CHAR としてマップする
v 2 = TIME データ・タイプを SQL_CHAR としてマップする
v 4 = TIMESTAMP データ・タイプを SQL_CHAR としてマッ
プする
デフォルト: 0
プログラミング
499
表 12. その他のプロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
ODBC.INI: DBCSNoTruncError
説明
DBCS ストリング変換オーバーフロー・エラーを ODBC 切り捨
てエラーとして報告するかどうかを指定します。
使用できる値:
v 0 = DBCS ストリング変換オーバーフロー・エラーを ODBC
切り捨てエラーとして報告する
v 1 = 切り捨てエラーを無視する
デフォルト: 0
接続ストリング: DEBUG
1 つまたは複数のデバッグ・オプションを指定します。
ODBC.INI: Debug
これはビット・フラグ値です。任意の使用可能値を加算して合計
値を計算することができます。
使用できる値:
v 2 = SQLGetInfo の SQL_IDENTIFIER_CASE オプションとし
て SQL_IC_MIXED を戻す
v 4 = パッケージ内のすべての SELECT ステートメントを保管
する
v 8 = SQLGetInfo の SQL_MAX_QUALIFIER_NAME_LEN オプ
ションとしてゼロを戻す
v 16 = 配置されている UPDATE / DELETE をパッケージに追
加する
v 32 = 静的カーソルを動的カーソルに変換する
v 64 = 可変長フィールド (VARCHAR、VARGRAPHIC、BLOB
など) のデータに相当する合計の列サイズを送信する。このオ
プションは、パフォーマンスに悪影響を与える可能性があるた
め、注意して使用してください。
v 128 = バッファー内の最後の文字がヌル終止符文字の場合に、
SQLBindParameter のソース長から 1 を減算する
v 256 = データ 10 進数エラーを無視する
v 512 = 両方向スクロール・カーソルのキャスト警告 (SQL0402)
を無視する
v 1024 = 可変長圧縮を使用不可にする
v 2048 = SQLGetInfo の SQL_CONVERT_TIMESTAMP オプシ
ョンを呼び出す場合に、SQL_CVT_DATE のサポートを戻さな
い
v 32768 = 照会の結果、列が 0 で除算された場合に、エラーの
代わりにヌル値を戻す
デフォルト: 0
500
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 12. その他のプロパティー用の IBM i Access ODBC 接続ストリング・キーワード (続き)
キーワード
接続ストリング: TRUEAUTOCOMMIT
ODBC.INI: TrueAutoCommit
説明
自動コミット・サポートの処理方法を指定します。従来の ODBC
ドライバーでは、自動コミットをオンにすると、サーバーは
*NONE 分離レベルで実行されました。現在、自動コミットはど
の分離レベルでも実行できます。 SQL 仕様に厳密に準拠する必
要があるアプリケーションでは設定値 1 を使用します。この設
定では、すべてのファイルをジャーナル処理する必要があること
に注意してください。 0 に設定すると、ほとんどのアプリケー
ションのパフォーマンスは向上します。トランザクション分離レ
ベルについて詳しくは、「SQL 解説書」を参照してください。
使用できる値:
v 0 = 自動コミットを *NONE 分離レベルで実行する
v 1 = 自動コミットを、その接続に対して設定された分離レベル
で実行する。接続の分離レベルは、SQLSetConnectAttr API お
よび SQL_ATTR_TXN_ISOLATION オプションを使用して設定
します。
デフォルト: 0
接続ストリング: NEWPWD
ODBC.INI: NewPassword
接続ストリング: XALCS
現行ユーザーの IBM i パスワードを変更するために使用される
新しいパスワードを指定します。このオプションは、アプリケー
ションによって設定される場合にのみ尊重されます。このオプシ
ョンを使用する場合は、UID キーワードおよび PWD キーワー
ドも指定する必要があります。
疎結合分散トランザクション・ブランチ間でロックを共有するか
どうかを指定します。
ODBC.INI: XALooselyCoupledSupport
使用できる値:
v 0 = ロックを共有しない
v 1 = ロックを共有する
デフォルト: 1
接続ストリング: XALOCKTIMEOUT
分散トランザクションがタイムアウトまでロック要求を待機する
最大時間 (秒数) を指定します。
ODBC.INI: XALockTimeout
使用できる値:
v 0 = デフォルトのシステム設定を使用する
v 0 – 999999999 = 待機時間数 (秒)
デフォルト: 0
接続ストリング: XATXNTIMEOUT
分散トランザクションがタイムアウト発生まで待機する時間長
(秒数) を指定します。
ODBC.INI: XATransactionTimeout
使用できる値:
v 0 = トランザクションが終了するまで無限に待機する
v 0 – 999999999 = 待機時間数 (秒)
デフォルト: 0
プログラミング
501
注 1: このドライバー名は Windows 上でのみ登録されるものであるため、非推奨であり、将来のリリース
では登録されないようになる予定です。 IBM i Access ODBC Driver というドライバー名に変えることをお
勧めします。既存の DSN を新しいドライバー名に移行するためには、cwbodbcreg ツールを使用できま
す。
注 2: このキーワードは Windows 上でのみサポートされます。
関連資料:
527 ページの『レコード・ブロックの調整』
レコード・ブロックは、IBM i Access ODBC ドライバーを使用した場合に、ネットワーク・フローの数を
大幅に削減し、それによってパフォーマンスを改善する技法の 1 つです。
バージョンおよびリリースの変更に伴う ODBC ドライバーの振る舞いの変更:
このトピックでは、さまざまなバージョンの ODBC ドライバーおよび対応する IBM i リリースでサポー
トされる新機能について説明します。
以下のリストは、7.1 の重要な変更内容の一部について説明しています。
| ODBC ドライバーを使用して 7.2 IBM i データにアクセスする際に、以下のようなサポートが新たに行わ
| れます。
| v 拡張タイム・スタンプ精度
ODBC ドライバーを使用して 7.1 IBM i データへのアクセスする際に、以下のようなサポートが新たに行
われます。
v XML データ・タイプ
v 128 バイトのスキーマ名
v 複数行 UPDATE、DELETE、および MERGE ステートメント
v 同時アクセス解決のサポート
以下のリストは、V6R1 の重要な変更内容の一部について説明しています。
ODBC ドライバーを使用して V6R1 System i データへのアクセスする際に、以下のようなサポートが新た
に行われます。
v SQL 照会ストレージの制限
v ODBC アプリケーションと QZDASOINIT システム・ジョブの関連付け
v 128 バイトのカーソル名
v 10 進浮動小数点 (DECFLOAT) データ・タイプ
v ストアード・プロシージャーの日時形式の追加
以下のリストは、V5R4 の重要な変更内容の一部について説明しています。
ODBC ドライバーを使用して V5R4 System i データにアクセスする際に、新しい機能が使用可能になりま
した。これらの機能は、以下のとおりです。
v 128 バイト列名のサポート
v 長い SQL ステートメントのサポート (コマンドの長さは、2,097,152 バイトまたは 1,048,576 文字まで)
v i5/OS™ ホストへの IBM Enterprise Workload Manager™ (eWLM) 相関係数引き渡しのサポート
v 大文字だけではないテーブル名および列名に対する改良済みのサポート
502
IBM i: Windows アプリケーション・パッケージ: プログラミング
v 疎結合トランザクションに対する拡張分散トランザクション・サポート
v Linux 64 ビット ODBC ドライバー
ODBC API の制約事項およびサポートされない関数:
IBM i Access の ODBC ドライバーにおける関数のインプリメント方法の中には、「Microsoft ODBC
Software Development Kit Programmer's Reference」に記述されている仕様と一致しないものがあります。
以下の表は、グローバルな制限事項とサポートされない関数を示しています。個々の API およびそれらに
関連する考慮事項については、 475 ページの『ODBC 3.x API に関する注意事項』に示したリストを参照
してください。
表 13. ODBC API 関数の制限事項
関数
説明
グローバルな考慮事項
非同期処理はサポートされません。ただし、SQLCancel を (マルチスレッド化されたア
プリケーションにおいて) 異なるスレッドから呼び出して、実行に時間のかかっている
照会を取り消すことができます。
Translation DLL は、バッファーから得られたデータを変換する際にのみ呼び出されま
す。
SQLSetScrollOptions (2x API)
SQL_CONCUR_ROWVER、SQL_CONCUR_VALUES は Concurrency パラメーターの非
サポート・オプションです。
SQL_SCROLL_KEYSET_DRIVEN は、ドライバーによって SQL_SCROLL_DYNAMIC
にマップされます。
関連資料:
475 ページの『ODBC 3.x API に関する注意事項』
次の表は、IBM i Access ODBC 3.x API をその関連タスクごとにリストし、それぞれの API に関する考
慮事項を示しています。
サインオン・ダイアログの振る舞い:
サインオン・ダイアログ、ユーザー ID、およびパスワード・プロンプトを制御します。
サインオン・ダイアログの振る舞いは、データ・ソースのセットアップ方法およびアプリケーションが接続
に使用する ODBC API (SQLConnect、SQLDriverConnect、SQLBrowseConnect) によって決まります。
ODBC データ・ソースを構成する際に、サインオン・ダイアログの振る舞いに影響する可能性のあるオプ
ションが 2 つあります。これらのオプションは、いずれも DSN セットアップ GUI の「一般 (General)」
タブにある「接続オプション (Connection Options)」をクリックして表示されるダイアログにあります。
注: DSN セットアップ GUI に、サインオン情報のダイアログ・プロンプトを許可するかどうかを制御す
るオプションがあります。 3 層環境で SQLConnect を呼び出すアプリケーションは、必ず「SQLConnect
のプロンプトを出さない (Never prompt for SQLConnect)」を選択する必要があります。この 3 層アプリケ
ーションは、また、SQLConnect の呼び出し時にユーザー ID およびパスワードを必ず指定する必要があり
ます。
v
「デフォルト・ユーザー ID (Default user ID)」セクションでは、使用するデフォルト・ユーザー ID
を以下の中から指定することができます。
– Windows ユーザー名を使用
– 以下で指定したユーザー ID を使用 (Use the user ID specified below)
プログラミング
503
– なし (None)
– IBM iナビゲーターのデフォルトを使用
– Kerberos プリンシパルを使用 (Use Kerberos principal)
v 「サインオン・ダイアログ・プロンプト (Signon dialog prompting)」セクションでは、アプリケーショ
ンが SQLConnect ODBC API を使用する場合に、サインオン・ダイアログのプロンプトを出すかどうか
指定することができます。
アプリケーションをコーディングする際に、ユーザー ID、パスワード、およびサインオン・ダイアログ・
プロンプトの振る舞いを全体的に制御することができます。使用されるユーザー ID およびパスワード
は、以下の順序で評価されます。
1. アプリケーションで指定されたユーザー ID / パスワード引数。
v SQLConnect API はユーザー ID およびパスワード引数を受け入れます。
v SQLDriverConnect API および SQLBrowseConnect API は UID、PWD、および SIGNON 接続ストリ
ング・キーワードを受け入れます。
2. デフォルト・ユーザー ID の GUI 設定
サインオン・ダイアログ・プロンプトは、アプリケーションが接続のために使用する ODBC API によって
決まります。サインオン・ダイアログ・プロンプトの GUI 設定でプロンプトを出さないと指定されていな
い限り、 SQLConnect は、必要に応じてサインオン・ダイアログを表示します。 SQLDriverConnect は、
DriverCompletion の値に従って、サインオン・ダイアログのプロンプトを出します。
SQL_DRIVER_NOPROMPT と設定すると、サインオン・ダイアログのプロンプトは全く出されなくなりま
す。 SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE または SQL_DRIVER_COMPLETE_REQUIRED
と設定すると、必要に応じて、サインオン・ダイアログのプロンプトが出されます。 SQLBrowseConnect
は、必要に応じてサインオン・ダイアログを出します。
ActiveX Data Objects (ADO) prompting
ActiveX Data Objects (ADO) を使用して ODBC アプリケーションをコード化する場合、プロンプトのデフ
ォルトの振る舞いは adPromptNever です。プロンプトの出し方を変えるには、接続の Open メソッドを
呼び出す前に、接続オブジェクトに対してプロンプト・プロパティーを設定します。例えば以下の ADO
コードを指定すると、必要なときのみプロンプトが出されます。 SIGNON、UID、または PWD キーワー
ドを追加することで、プロンプトの量をより制御することができます。
Dim conn As New ADODB.Connection
conn.Properties("Prompt") = adPromptComplete
conn.Open "Provider = MSDASQL;DSN=myODBCDSN;
ODBC データ・タイプおよびそれらと DB2 for i データベース・タイプとの対応:
IBM i Access の ODBC ドライバーのサポートによって、ODBC タイプと DB2 for i データ・タイプの間
でデータ・タイプがマップされます。
次の表は、サポートされているデータ・タイプのデフォルト・マッピングを示しています。データ・タイプ
について詳しくは、DB2 for i データベース・タイプへの関連リンク (以下参照) を選択してください。
|
表 14. DB2 for i データベース・タイプのデータ・タイプ・マッピング
|
DB2 for i データベース・タイプ
3.x ODBC データ・タイプ
|
BIGINT
SQL_BIGINT
|
BINARY
SQL_BINARY
|
BLOB
SQL_LONGVARBINARY
504
IBM i: Windows アプリケーション・パッケージ: プログラミング
|
表 14. DB2 for i データベース・タイプのデータ・タイプ・マッピング (続き)
|
DB2 for i データベース・タイプ
3.x ODBC データ・タイプ
|
CHAR
SQL_CHAR
|
CHAR FOR BIT DATA
SQL_BINARY
|
CLOB
SQL_LONGVARCHAR
|
DATALINK
SQL_VARCHAR
|
DATE
SQL_DATE
|
DBCLOB
SQL_LONGVARCHAR
|
DBCLOB CCSID 1200
SQL_WLONGVARCHAR
|
DBCLOB CCSID 13488
SQL_WLONGVARCHAR
|
DECFLOAT
SQL_VARCHAR
|
DECIMAL
SQL_DECIMAL
|
DOUBLE
SQL_DOUBLE
|
FLOAT
SQL_FLOAT
|
GRAPHIC
SQL_CHAR
|
GRAPHIC CCSID 1200
SQL_WCHAR
|
GRAPHIC CCSID 13488
SQL_WCHAR
|
INTEGER
SQL_INTEGER
|
LONG VARCHAR
SQL_VARCHAR
|
LONG VARCHAR FOR BIT DATA
SQL_VARBINARY
|
LONG VARGRAPHIC
SQL_VARCHAR
|
LONG VARGRAPHIC CCSID 1200
SQL_WVARCHAR
|
LONG VARGRAPHIC CCSID 13488
SQL_WVARCHAR
|
NUMERIC
SQL_NUMERIC
|
REAL
SQL_REAL
|
ROWID
SQL_VARBINARY
|
SMALLINT
SQL_SMALLINT
|
TIME
SQL_TYPE_TIME
|
TIMESTAMP
SQL_TYPE_TIMESTAMP
|
VARBINARY
SQL_VARBINARY
|
VARCHAR
SQL_VARCHAR
|
VARCHAR FOR BIT DATA
SQL_VARBINARY
|
VARGRAPHIC
SQL_VARCHAR
|
VARGRAPHIC CCSID 1200
SQL_WVARCHAR
|
VARGRAPHIC CCSID 13488
SQL_WVARCHAR
|
|
XML
SQL_XML
インプリメンテーションに関する注意:
v 「Microsoft ODBC Software Development Kit Programmer's Reference バージョン 3.5」に記載されている
変換はすべて、これらの ODBC SQL データ・タイプでサポートされています。
v 上記のデータ・タイプについて、個々に詳しく知りたい場合は、ODBC API SQLGetTypeInfo を呼び出
してください。
プログラミング
505
v データベース・タイプ VARCHAR は、指定されている列サイズが 255 よりも大きい場合に、データベ
ースにより LONG VARCHAR に変更されます。
v ODBC ドライバーは、インターバル SQL データ・タイプをサポートしていません。
v 2.x ODBC アプリケーションでは、SQL_TYPE_DATE、SQL_TYPE_TIME、および
SQL_TYPE_TIMESTAMP 定義に代わって、SQL_DATE、SQL_TIME、および SQL_TIMESTAMP 定義を
使用します。
v CCSID が 1200 (UTF-16)、1208 (UTF-8)、または 13488 (UCS-2) のデータ・タイプである Unicode デ
ータは、SQL_WCHAR、SQL_WVARCHAR、および SQL_WLONGVARCHAR の代わりに
SQL_CHAR、SQL_VARCHAR、および SQL_LONGVARCHAR として ODBC 2.x アプリケーションに
報告します。
v サイズが 2 GB までの LOB (BLOB、CLOB、および DBCLOB) がサポートされます。 LOB およびデ
ータ・リンクの詳細については、ラージ・オブジェクト (LOB) の考慮事項に関するトピック集への関連
リンク (以下参照) を選択してください。
v
精度の高い 10 進数フィールドを正しく取得するためには、列を SQL_C_CHAR としてバインドする必
要があることに注意してください。 SQL_C_NUMERIC データを保管する構造では、最大 38 桁を保持
することができます。
関連資料:
508 ページの『ラージ・オブジェクト (LOB) の考慮事項』
大容量のテキスト文書を保管し、それらにアクセスするためには、IBM i Access の ODBC で LOB を使
用します。
関連情報:
DB2 for i データベース・タイプ
XML データ・タイプの処理:
これらの規則は、DB2 for i ODBC 関数で XML データ・タイプを使用する場合のさまざまな局面の処理
に役立ちます。
ODBC アプリケーションにおける XML データ処理
DB2 for i ODBC アプリケーションは、SQL_XML データ・タイプを使用して XML データを検索および
保管することができます。このデータ・タイプは、DB2 for i データベースのネイティブ XML データ・
タイプに相当し、整形式 XML 文書を保管する列の定義に使用されます。SQL_XML タイプは、C タイプ
(SQL_C_BINARY、SQL_VARBINARY、SQL_C_CHAR、SQL_VARCHAR、SQL_C_WCHAR、および
SQL_WVARCHAR) にバインドできます。ただし、文字タイプの使用時に CCSID 変換から生じる可能性が
あるデータ損失や破損を避けるために、文字タイプではなく、バイナリー・タイプの使用をお勧めします。
XML 列の XML データを保管するには、XML 値を含むバイナリー (SQL_C_BINARY または
SQL_VARBINARY) もしくは文字 (SQL_C_CHAR、SQL_VARCHAR、SQL_C_WCHAR、または
SQL_VARWCHAR) バッファーを SQL_XML SQL タイプにバインドし、INSERT または UPDATE SQL
ステートメントを実行します。データベースから XML データを取り出すには、バイナリー
(SQL_C_BINARY または SQL_VARBINARY) もしくは文字
(SQL_C_CHAR、SQL_VARCHAR、SQL_C_WCHAR、または SQL_WVARCHAR) タイプに結果セットをバ
インドします。エンコードの問題があるため、文字タイプの使用には注意してください。XML 値が取り出
され、アプリケーション・データ・バッファーに入れられると、DB2 for i サーバーは、その XML 値で
暗黙シリアライゼーションを実行して、内部形式から、シリアライズされたストリング形式に変換します。
文字タイプのバッファーの場合、XML 値は、文字タイプに関連したアプリケーション CCSID に暗黙的に
506
IBM i: Windows アプリケーション・パッケージ: プログラミング
シリアライズされます。デフォルトでは、XML 宣言が、シリアライズされた出力ストリングに含まれま
す。このデフォルトの動作は、 SQL_ATTR_XML_DECLARATION 接続属性を設定することによって変更
できます。
ODBC アプリケーションにおける XML 列の挿入と更新
データを更新、またはテーブルの XML 列に挿入する場合、入力データは、シリアライズされたストリン
グ形式でなければなりません。XML データの場合、SQLBindParameter() を使用してパラメーター・マーカ
ーを入力データ・バッファーにバインドするときに、入力データ・バッファーのデータ・タイプを
SQL_C_BINARY、SQL_VARBINARY、SQL_C_CHAR、SQL_VARCHAR_、SQL_C_WCHAR、または
SQL_VARCHAR として指定できます。XML データを含むデータ・バッファーを SQL_C_BINARY または
SQL_VARBINARY としてバインドする場合、DB2 for i ODBC は、XML データを内部エンコード・デー
タとして処理します。この方法では、文字タイプを使用する場合の処理の追加や、文字変換で起こり得るデ
ータ損失を回避するので、この方法をお勧めします。XML データを含むデータ・バッファーを
SQL_C_CHAR、SQL_VARCHAR、SQL_C_WCHAR、または SQL_WVARCHAR としてバインドする場
合、DB2 for i ODBC は、XML データを外部エンコード・データとして処理します。
DB2 for i ODBC では、次のようにデータのエンコードが判別されます。
v C タイプが SQL_C_WCHAR または SQL_WVARCHAR である場合、ODBC では、データが UCS-2 と
してエンコードされていることを前提とします。
v C タイプが SQL_C_CHAR または SQL_C_VARCHAR である場合、ODBC では、データがジョブ
CCSID でエンコードされていることを前提とします。
次の例は、推奨される SQL_C_BINARY タイプを使用して、XML 列の XML データを更新する方法を示
しています。
char xmlBuffer[10240];
integer length;
// Assume a table named dept has been created with the following statement:
// CREATE TABLE dept (id CHAR(8), deptdoc XML)
// xmlBuffer contains an internally encoded XML document that is to replace
// the existing XML document
length = strlen (xmlBuffer);
SQLPrepare (hStmt, "UPDATE dept SET deptdoc = ? WHERE id = ’001’", SQL_NTS);
SQLBindParameter (hStmt, 1, SQL_PARAM_INPUT, SQL_C_BINARY, SQL_XML, 0, 0,
xmlBuffer, 10240, &length); SQLExecute (hStmt);
ODBC アプリケーションにおける XML データ検索
テーブルの XML 列からデータを選択する場合、出力データは、シリアライズされたストリング形式で
す。XML データの場合、SQLBindCol() API を使用して、照会結果セット内の列をアプリケーション変数
にバインドするときに、アプリケーション変数のデータ・タイプを
SQL_C_BINARY、SQL_VARBINARY、SQL_C_CHAR、SQL_VARCHAR、SQL_C_WCHAR、または
SQL_WVARCHAR として指定できます。 XML 列から結果セットを取り出す場合、アプリケーション変数
を SQL_C_BINARY または SQL_VARBINARY タイプにバインドすることをお勧めします。文字タイプに
バインドすると、CCSID 変換の結果、データ損失が生じる可能性があります。データ損失が生じる可能性
があるのは、ソース・コード・ページ内の文字をターゲット・コード・ページで表すことができない場合で
す。変数をバイナリー・タイプにバインドすると、これらの問題が回避されます。XML データは、内部エ
ンコード・データとしてアプリケーションに戻されます。
ODBC では、次のようにデータのエンコードが判別されます。
プログラミング
507
v C タイプが SQL_C_BINARY または SQL_VARBINARY である場合、DB2 for i ODBC は、列のエン
コードでデータを戻します。
v C タイプが SQL_C_CHAR または SQL_VARCHAR である場合、DB2 for i ODBC は、ジョブ CCSID
でデータを戻します。
v C タイプが SQL_C_WCHAR または SQL_WVARCHAR である場合、DB2 for i ODBC は、UCS-2 コ
ード化スキームでデータを戻します。
データベース・サーバーは、データの暗黙シリアライゼーションを実行してから、アプリケーションに戻し
ます。XMLSERIALIZE 関数を呼び出すと、XML データを特定のデータ・タイプに明示的にシリアライズ
することができます。ただし、暗黙シリアライゼーションをお勧めします。XMLSERIALIZE を使用して文
字タイプに明示的にシリアライズすると、エンコードの問題が生じる可能性があるからです。
次の例は、XML データを XML 列からバイナリー・アプリケーション変数に取り出す方法を示していま
す。
char xmlBuffer[10240];
// xmlBuffer is used to hold the retrieved XML document
integer length;
// Assume a table named dept has been created with the following statement:
// CREATE TABLE dept (id CHAR(8), deptdoc XML)
length = sizeof (xmlBuffer);
SQLExecute (hStmt, "SELECT deptdoc FROM dept WHERE id=’001’", SQL_NTS);
SQLBindCol (hStmt, 1, SQL_C_BINARY, xmlBuffer, &length, NULL);
SQLFetch (hStmt);
SQLCloseCursor (hStmt);
// xmlBuffer now contains a valid XML document encoded in UTF-8
ラージ・オブジェクト (LOB) の考慮事項:
大容量のテキスト文書を保管し、それらにアクセスするためには、IBM i Access の ODBC で LOB を使
用します。
ラージ・オブジェクト (LOBs):
ラージ・オブジェクト (LOB) データ・タイプを使用すると、アプリケーションでは、大量のデー
タ・オブジェクトをストリングとして保管できます。 ODBC ドライバーは、サイズが最大 2 GB
の LOB にアクセスできます。
大容量の LOB データ・フィールドをサーバーにアップロードする場合には、SQLParamData およ
び SQLPutData API を使用することをお勧めします。SQLPutData API は、受信した LOB データ
をサーバーに送信し、クライアントで必要なメモリーの量を減らします。
LOB データ・タイプ
BLOB バイナリー・ラージ・データ・オブジェクト
CLOB シングルバイト文字のラージ・データ・オブジェクト
DBCLOB
2 バイト文字のラージ・データ・オブジェクト
BLOB データ・タイプの使用例については、
以下のトピック『例: BLOB データ・タイプの使用』を参照してください。
LOB の詳細については、
IBM i Information Center のトピック『SQL プログラミング概念』で、『オブジェクト・
リレーショナル機能の使用』という見出しの下にあるトピック『ラージ・オブジェクトの
使用』を参照してください。
508
IBM i: Windows アプリケーション・パッケージ: プログラミング
データ・リンク
DataLink データ・タイプを使用すると、さまざまな種類のデータをデータベースに保管することが
できます。データは、URL として保管されます。 URL によって、オブジェクトが指定されま
す。オブジェクトは、イメージ・ファイル、音声ファイル、テキスト・ファイルなどの場合があり
ます。
データ・リンクの詳細については、
i5/OS Information Center のトピック『SQL プログラミング概念』で、『特別なデータ・タ
イプの処理』という見出しの下にあるトピック『データ・リンクの使用』を参照してくだ
さい。
関連資料:
504 ページの『ODBC データ・タイプおよびそれらと DB2 for i データベース・タイプとの対応』
IBM i Access の ODBC ドライバーのサポートによって、ODBC タイプと DB2 for i データ・タイプの間
でデータ・タイプがマップされます。
関連情報:
SQL プログラミングの一般概念
例: BLOB データ・タイプの使用:
DB2 for IBM i BLOB データ・タイプを ODBC と一緒に使用する例です。
以下は、C 言語で BLOB データ・タイプを使ったプログラムの一部です。
BOOL params = TRUE; // TRUE if you want to use parameter markers
SQLINTEGER char_len = 10, blob_len = 400;
SQLCHAR szCol1[21], szCol2[400], szRecCol1[21], szRecCol2[400];
SQLINTEGER cbCol1, cbCol2;
SQLCHAR stmt[2048];
// Create a table with a character column and a BLOB column
rc = SQLExecDirect(hstmt, "CREATE TABLE TABBLOB(COL1 CHAR(10), COL2 BLOB(400))", SQL_NTS);
strcpy(szCol1, "1234567890");
if (!params) // no parameter markers
{
strcpy(szCol2, "414243444546"); // 0x41 = ’A’, 0x42 = ’B’, 0x43 = ’C’, ...
wsprintf(stmt, "INSERT INTO TABBLOB VALUES(’%s’, BLOB(x’%s’))", szCol1, szCol2);
}
else
{
strcpy(szCol2, "ABCDEF"); // ’A’ = 0x41, ’B’ = 0x42, ’C’ = 0x43, ...
strcpy(stmt, "INSERT INTO TABBLOB VALUES(?,?)");
}
// Prepare the ’Insert’ statement
rc = SQLPrepare(hstmt, stmt, SQL_NTS);
// Bind the parameter markers
if (params) // using parameter markers
{
cbCol1 = char_len;
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
char_len, 0, szCol1, char_len + 1, &cbCol1);
cbCol2 = 6;
rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_BINARY, SQL_LONGVARBINARY,
blob_len, 0, szCol2, blob_len, &cbCol2);
}
// Execute the ’Insert’ statement to put a row of data into the table
プログラミング
509
rc = SQLExecute(hstmt);
// Prepare and Execute a ’Select’ statement
rc = SQLExecDirect(hstmt, "SELECT * FROM TABBLOB", SQL_NTS);
// Bind the columns
rc = SQLBindCol(hstmt, 1, SQL_C_CHAR, szRecCol1, char_len + 1, &cbCol1);
rc = SQLBindCol(hstmt, 2, SQL_C_BINARY, szRecCol2, blob_len, &cbCol2);
// Fetch the first row
rc = SQLFetch(hstmt);
szRecCol2[cbCol2] = ’¥0’;
// At this point szRecCol1 should contain the data "1234567890"
// szRecCol2 should contain the data 0x414243444546 or "ABCDEF"
接続とステートメントの属性:
IBM i Access ODBC 仕様では、接続属性およびステートメント属性が複数定義されています。
この ODBC 仕様は、IBM i Access のカスタマイズ属性 (次の 2 つの表を参照) で拡張されています。
表 15. カスタマイズ接続属性
属性
説明
CWB_ATTR_PRESERVE_CURSORS
カーソル・コミット動作およびカーソル・ロールバック動作を
制御します。
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_CB_DELETE - SQLGetInfo の
SQL_CURSOR_COMMIT_BEHAVIOR および
SQL_CURSOR_ROLLBACK_BEHAVIOR オプションの場合
は SQL_CB_DELETE が返されます。
v CWB_CB_PRESERVE - SQLGetInfo の
SQL_CURSOR_COMMIT_BEHAVIOR および
SQL_CURSOR_ROLLBACK_BEHAVIOR オプションの場合
は SQL_CB_PRESERVE が返されます。
デフォルト: CWB_CB_PRESERVE
CWB_ATTR_INFO_USERID
ホスト・データベースに送信されるクライアント・ユーザー
ID ストリングを指定します。この属性は、データベースへの
接続後に設定されます。
データ・タイプ: SQLCHAR
使用できる値: 長さが 255 文字以下の任意のストリング。
注: この属性は、CLIENTUSERID 接続ストリング・キーワー
ドを使用して指定することもできます。
510
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 15. カスタマイズ接続属性 (続き)
属性
説明
CWB_ATTR_INFO_WRKSTNNAME
ホスト・データベースに送信されるワークステーション名スト
リングを指定します。
データ・タイプ: SQLCHAR
使用できる値: 長さが 255 文字以下の任意のストリング。
注: この属性は、CLIENTWRKSTNNAME 接続ストリング・
キーワードを使用して指定することもできます。
CWB_ATTR_INFO_APPLNAME
ホスト・データベースに送信されるアプリケーション名ストリ
ングを指定します。
データ・タイプ: SQLCHAR
使用できる値: 長さが 255 文字以下の任意のストリング。
注: この属性は、CLIENTAPPLNAME 接続ストリング・キー
ワードを使用して指定することもできます。
CWB_ATTR_INFO_ACCTSTR
ホスト・データベースに送信されるアカウンティング ID スト
リングを指定します。
データ・タイプ: SQLCHAR
使用できる値: 長さが 255 文字以下の任意のストリング。
注: この属性は、CLIENTACCTSTR 接続ストリング・キーワ
ードを使用して指定することもできます。
CWB_ATTR_INFO_PROGRAMID
ホスト・データベースに送信されるプログラム ID ストリング
を指定します。
データ・タイプ: SQLCHAR
使用できる値: 長さが 255 文字以下の任意のストリング。
注: この属性は、CLIENTPROGRAMID 接続ストリング・キー
ワードを使用して指定することもできます。
CWB_ATTR_PACKAGE_LIBRARY
使用されるデフォルト・パッケージ・ライブラリーを指定しま
す。この属性は、この接続でステートメントを作成する前に設
定する必要があります。
データ・タイプ: SQLCHAR
使用できる値: 長さが 10 文字以下の任意のストリング。
注: この属性は、DFTPKGLIB 接続ストリング・キーワードを
使用して指定することもできます。
CWB_ATTR_PACKAGE_NAME
使用されるパッケージ名を指定します。この属性は、この接続
でステートメントを作成する前に設定する必要があります。
データ・タイプ: SQLCHAR
使用できる値: 長さが 10 文字以下の任意のストリング。
注: この属性は、PKG 接続ストリング・キーワードを使用し
て指定することもできます。
プログラミング
511
表 15. カスタマイズ接続属性 (続き)
属性
説明
CWB_ATTR_SERVER_JOB_CCSID
注 1
この ODBC 接続と関連付けられているサーバー・ジョブのジ
ョブ CCSID を返します。デフォルトでは、SQL ステートメ
ントはこの CCSID でホストに送られます。
データ・タイプ: SQLUINTEGER
ゼロによる値の除算があったときに結果セット内の特定のセル
内のデータに対してエラーを返すかどうかを指定します。
CWB_ATTR_DIVIDE_BY_ZERO
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_DIVIDE_BY_ZERO_ERROR - ゼロ除算によって計算
された値を含む結果セット内のセルがエラーとして返され
ます。
v CWB_DIVIDE_BY_ZERO_NULL - ゼロ除算によって計算さ
れた値を含む結果セット内のセルが NULL 値として返され
ます。エラーは戻されません。
デフォルト: CWB_DIVIDE_BY_ZERO_ERROR
注: この属性は、DEBUG 接続ストリング・キーワードのゼロ
除算オプションを使用して指定することもできます。
サーバーとの間で送受信されるデータを圧縮するかどうかを指
定します。多くの場合には、データ圧縮をおこなうと、ドライ
バーとサーバーとの間で伝送されるデータが少なくなるため、
パフォーマンスが向上します。
CWB_ATTR_DATA_COMPRESSION
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_COMPRESSION_OFF = 圧縮オフ
v CWB_COMPRESSION_ON = 圧縮オン
デフォルト: CWB_COMPRESSION_OFF
注: この属性は、COMPRESSION 接続ストリング・キーワー
ドを使用して指定することもできます。
CWB_ATTR_TRIM_CHAR_FIELDS注
2
CHAR フィールドから返されたデータの末尾スペースを除去
するかどうかを指定します。 CWB_DELETE_BLANKS が指定
されると、CHAR フィールドは VARCHAR フィールドと同
じように表示されます。VARCHAR フィールドの末尾スペー
スは常に除去されるからです。
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_PRESERVE_BLANKS - CHAR フィールドの末尾スペ
ースを除去しない
v CWB_DELETE_BLANKS - CHAR フィールドの末尾スペー
スを除去する
デフォルト: CWB_PRESERVE_BLANKS
512
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 15. カスタマイズ接続属性 (続き)
属性
CWB_ATTR_JOB_INFO
説明
注 1
ODBC 接続が使用している事前開始ジョブに関する情報を含
む文字ストリングを戻します。
データ・タイプ: SQLCHAR
使用できる値: 次の形式を持つ長さが 26 文字のストリング。
v 10 文字のジョブ名 (必要に応じてブランクが埋め込まれま
す)、
v 10 文字のユーザー (必要に応じてブランクが埋め込まれま
す)、
v 6 文字のジョブ番号
CWB_ATTR_EWLM_CORRELATOR
注 2
この属性を指定すると、アプリケーションと eWLM サポート
(Enterprise Workload Manager) を結合することができます。
データ・タイプ: IBM Enterprise Workload Manager (eWLM)
相関係数が入っているバッファーを指すポインター。
CWB_ATTR_CONCURRENT_ACCESS_RESOLUTION トランザクションで検出された競合する行ロックをどのように
処理するかを指定します。これは分離レベル CS に関する読
み取り専用照会にのみ適用されます。
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_CC_USE_SERVER_VALUE - サーバー設定値を使用
する
v CWB_CC_USE_CURRENTLY_COMMITTED - 現在コミット
されている行を使用する
v CWB_CC_WAIT_FOR_OUTCOME - 結果を待機する
v CWB_CC_SKIP_LOCKED_DATA - ロックをスキップする
デフォルト: CWB_CC_USE_SERVER_VALUE
注: この属性は、CONCURRENTACCESSRESOLUTION 接続
ストリング・キーワードを使用して指定することもできます。
CWB_ATTR_XA_TXN_TIMEOUT
分散トランザクションがタイムアウト発生まで待機する時間長
(秒数) を指定します。値 0 は、トランザクションが終了する
まで無限に待機することを示します。
データ・タイプ: SQLUINTEGER
使用できる値: 0 – 999999999
デフォルト: 0
注: この属性は、XATXNTIMEOUT 接続ストリング・キーワ
ードを使用して指定することもできます。
プログラミング
513
表 15. カスタマイズ接続属性 (続き)
属性
説明
CWB_ATTR_XA_LOCK_TIMEOUT
分散トランザクションがタイムアウトまでロック要求を待機す
る最大時間 (秒数) を指定します。値 0 は、デフォルトのシ
ステム設定を使用することを示します。
データ・タイプ: SQLUINTEGER
使用できる値: 0 – 999999999
デフォルト: 0
注: この属性は、XALOCKTIMEOUT 接続ストリング・キーワ
ードを使用して指定することもできます。
XA トランザクション作業に使用する RMID を指定する整数
値。これは随時設定可能です。設定する RMID はプロセスで
固有のものでなければなりません。この値が 0 に設定された
場合、それは、この接続に対する現在の XA トランザクショ
ン作業が完了したことを示します。
CWB_ATTR_XA_RMID
データ・タイプ: SQLINTEGER
デフォルト: 0
CWB_ATTR_XA_DLL_NAME
注 1
XA 呼び出しで呼び出す IBM i Access ドライバーを識別する
文字ストリング。このストリングは CWB_ATTR_XA_RMID
接続属性が設定されている場合のみ有効です。このストリング
は、接続の確立後に設定されます。
データ・タイプ: SQLCHAR
デフォルト: 空ストリング
514
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 15. カスタマイズ接続属性 (続き)
属性
説明
CWB_ATTR_XML_DECLARATION
結果セットで返された XML 列に組み込む XML 宣言のタイ
プを指定します。
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_XML_NO_DECLARATION - 宣言もバイト・オーダ
ー・マーク (BOM) も出力バッファーに追加されない。
v CWB_XML_INCLUDE_BYTE_ORDER_MARK - ターゲッ
ト・エンコードが UTF-16 である場合、該当するエンディ
アンネス内のバイト・オーダー・マーク (BOM) が出力バッ
ファーの前に付加される。
v CWB_XML_INCLUDE_DECLARATION - XML バージョン
のみを含む、最小の XML 宣言が生成される。
v CWB_XML_BOM_AND_DECLARATION CWB_XML_INCLUDE_BYTE_ORDER_MARK と
CWB_XML_INCLUDE_DECLARATION の両方を設定す
る。
v CWB_XML_ENCODING_IN_DECLARATION - ターゲッ
ト・エンコードを識別するエンコード属性が、生成される
任意の XML 宣言に追加される。そのため、この設定は、
この属性の値を計算するときに 2 の設定も含まれている場
合のみ有効です。
v CWB_XML_FULL_DECLARATION CWB_XML_INCLUDE_DECLARATION と
CWB_XML_ENCODING_IN_DECLARATION の両方を設定
する。
v CWB_XML_BOM_AND_FULL_DECLARATION CWB_XML_INCLUDE_BYTE_ORDER_MARK、
CWB_XML_INCLUDE_DECLARATION、および
CWB_XML_ENCODING_IN_DECLARATION を設定する。
デフォルト: CWB_XML_BOM_AND_FULL_DECLARATION
注: この属性は、XMLDECLARATION 接続ストリング・キー
ワードを使用して指定することもできます。
CWB_ATTR_XML_STRIP_WHITESPACE
この属性は、シリアライズされた XML データが検証なしで
暗黙的に構文解析されたときに DB2 がそのデータ内の空白を
除去するか保持するかを指定します。
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_XML_STRIP_WHITESPACE - 空白の除去
v CWB_XML_PRESERVE_WHITESPACE - 空白の保持
デフォルト: CWB_XML_STRIP_WHITESPACE
注: この属性は、XMLCURIMPPARSE 接続ストリング・キー
ワードを使用して指定することもできます。
プログラミング
515
表 15. カスタマイズ接続属性 (続き)
属性
説明
注 1: この属性は SQLGetConnectAttr でのみ有効です。
注 2: この属性は SQLSetConnectAttr でのみ有効です。
表 16. カスタマイズ・ステートメント属性
属性
説明
CWB_ATTR_NUM_RESULT_SETS
注 1
取り出し可能な結果セットの数を返します。これは、ストアー
ド・プロシージャーが呼び出され、アプリケーションが、スト
アード・プロシージャーにより生成された結果セット数を知り
たい場合に役立ちます。
データ・タイプ: SQLUINTEGER
ステートメントの段階で圧縮をオンまたはオフにすることがで
きます。
CWB_ATTR_DATA_COMPRESSION
データ・タイプ: SQLUINTEGER
使用できる値:
v CWB_COMPRESSION_OFF = 圧縮オフ
v CWB_COMPRESSION_ON = 圧縮オン
デフォルト: 接続ハンドルから継承される (デフォルトは
CWB_COMPRESSION_OFF)。
CWB_ATTR_POS_OF_SYNTAX_ERROR注
1
SQL 構文エラーが起こった SQL ステートメントへのオフセ
ットを返します。これは、SQLExecute または SQLExecDirect
が SQL_ERROR 戻りコードを返したときに設定されます。
データ・タイプ: SQLUINTEGER
注 1: この属性は SQLGetStatementAttr でのみ有効です。
接続プール:
IBM i Access ODBC 接続では接続プールがサポートされています。
接続プールとは、アプリケーションが IBM i Access ODBC 接続の切断を要求した後も ODBC 接続を開
いたままにしておく振る舞いのことです。プール内にある接続は、同じアプリケーションで再使用でき、新
しい接続を確立する場合の作業にかかる時間を節約することができます。
アプリケーションが IBM i Access ODBC ドライバーで接続プール・サポートを使用するようにしたい場
合は、以下の資料を参照してください。
|
|
v ODBC Windows を使用している場合は、MSDN ドライバー・マネージャー接続プール資料 (英語) を参
照してください。
|
|
v Linux 上で unixODBC を使用している場合は、unixODBC ODBC 接続プール資料 (英語) を参照してく
ださい。
関連情報:
Microsoft Web サイト
516
IBM i: Windows アプリケーション・パッケージ: プログラミング
SQLPrepare および SQLNativeSQL エスケープ・シーケンスおよびスカラー関数:
IBM i Access ODBC サポートによって、エスケープ・シーケンスとスカラー関数が使用できます。
ODBC のエスケープ・シーケンスとスカラー関数を使用すると、特定のバージョンの DBMS の SQL 構文
に直接コーディングする必要がなくなります。
エスケープ・シーケンスの使用方法については、Microsoft の ODBC 仕様を参照してください。以下の
ODBC エスケープ・シーケンスが、ODBC ドライバーでサポートされています。
エスケープ・シーケンス
v d
v t
v ts
v escape
v oj
v call
v ?=call – このエスケープ・シーケンスは、DB2 for IBM i において、プロシージャーからの戻り値のサ
ポートを利用する場合に使用します。パラメーター・マーカーは、SQLBindParameter API を使用して、
出力パラメーターとして結合する必要があります。このとき、プロシージャーは、整数タイプの値しか
戻せないことに注意してください。
分散トランザクションのサポート:
分散トランザクションでは、1 つの IBM i Access ODBC アプリケーションが複数のデータベース間で作
業単位を調整することができます。
ODBC ドライバーには、分散トランザクションの実行を可能にする 2 つの異なるインターフェースが組み
込まれています。この 2 つのインターフェースは MTS (Microsoft Transaction Server) と XA API サポー
トです。どちらのインターフェースも、XALOCKTIMEOUT と XATXNTIMEOUT の接続ストリング設定
の設定の影響を受けます。
MTS
MTS の詳細については、 Microsoft Transaction Server の使用 (英語) を参照してください。
XA API サポート
|
|
|
|
|
|
XA サポートを有効にするための関連オプションのいくつかについては、『接続とステートメントの属性』
ページ内の
CWB_ATTR_XA_TXN_TIMEOUT、CWB_ATTR_XA_LOCK_TIMEOUT、CWB_ATTR_XA_RMID、および
CWB_ATTR_XA_DLL_NAME 接続属性を参照してください。なお、CWB_ATTR_XA_LOCK_TIMEOUT お
よび CWB_ATTR_XA_TXN_TIMEOUT 接続属性の働きは XALOCKTIMEOUT および XATXNTIMEOUT
接続ストリング設定と同じです。
注:
v xa_open がアプリケーションで呼び出されるのは、リカバリーの場合だけです。 ODBC API の
SQLConnect または SQLDriverConnect を使用した接続では、RMID が CWB_ATTR_XA_RMID 接続属
性を介して設定されていれば、xa_open が自動的に実行されます。
v 接続属性 SQL_ATTR_AUTOCOMMIT は SQL_AUTOCOMMIT_ON として設定しなければなりません。
プログラミング
517
v アプリケーションで XA トランザクションを開始した後に別の XA 以外のトランザクション作業を開始
したい場合は、 RMID を 0 に設定し、XA 作業が完了したことをドライバーに示さなければなりませ
ん。
v XA リカバリーを実行する場合、アプリケーションはストリング
SYSTEM=mySystem;UID=myUserID;PWD="myPassword";DATABASE=myDatabase; を指定して xa_open を
呼び出します。 - ここで、mySystem にはシステム名、myUserID にはそのシステムのユーザー ID、
myPassword にはそのユーザー ID のパスワードを指定します。ストリングは示されているとおりに正確
に入力するようにしてください。または、単に SYSTEM=mySystem; と指定することもできます。
カーソルの動作に関する注意事項:
IBM i Access ODBC ドライバーを使用している場合、カーソルの動作がデータを取り出す方法に影響する
ことがあります。
SQLSetStmtAttr に SQL_ATTR_CURSOR_TYPE オプションを指定して、カーソル・タイプを設定すること
ができます。
カーソル・タイプ
v SQL_CURSOR_FORWARD_ONLY - すべてのカタログ結果セットは、このタイプのカーソルを使用しま
す。カタログ結果セットが生成されている場合には、カーソル・タイプは自動的にこれに変更されま
す。
v SQL_CURSOR_KEYSET_DRIVEN - SQL_CURSOR_STATIC にマップされます。
v SQL_CURSOR_DYNAMIC - サポートされています。
v SQL_CURSOR_STATIC - ステートメントで許可される場合にサポートされています。
注: プロシージャーの結果セット・カーソルはプロシージャーで開かれているため、SQLSetStmtAttr を使用
してカーソル・タイプを設定しても、カーソル・タイプに影響はありません。プロシージャーの結果セット
について詳しくは、『ストアード・プロシージャーの結果セット』を参照してください。
以下のファクターは、カーソルの並行性に影響を与える可能性があります。
v SQL ステートメントに "FOR UPDATE" 文節が含まれている場合、SQL_ATTR_CONCURRENCY の値
は SQL_CONCUR_LOCK に設定されます。
v
CONCURRENCY キーワードの DSN 設定が 1 (チェック) に設定されている場合、SQL ステートメン
トに "FOR FETCH ONLY" 文節がない場合、ODBC ドライバーは結果セットのレコードをロックしま
す。
行セット・サイズ
| ODBC ドライバーは SQL_ROWSET_SIZE および SQL_ATTR_ROW_ARRAY_SIZE の値を同じ値にマップ
| します。
結果セットに LOB がある場合、ロケーターがドライバーによって使用される可能性があります。ロケータ
ーは LOB フィールドに対する内部ハンドルです。ロケーターは、MAXFIELDLEN 接続オプションの設定
値が結果セットの LOB 列のサイズよりも小さい値である場合に使用されます。ロケーターを使用すると、
ドライバーがアプリケーションによって要求されるデータのみを取得するようになるため、パフォーマンス
が向上する場合があります。ロケーターの欠点は、サーバーとの間で余分な通信が必要になるという点で
す。ロケーターを使用しない場合、ドライバーは、使用されないものを含め、より多くの LOB データをダ
518
IBM i: Windows アプリケーション・パッケージ: プログラミング
ウンロードします。ロケーターを使用していない場合には、COMPRESSION 接続オプションを使用可能に
することを強くお勧めします。 MAXFIELDLEN キーワードの詳細については、『接続ストリング・キー
ワード』の説明を参照してください。
SQLGetData は、単一行取り出しで得られたデータにアクセスする場合にのみ使用することができます。複
数行取り出しでは、SQLGetData の呼び出しはサポートされません。
結果セットの行数
データを取り出す前にアプリケーションで行数を判別するために使用する方法はいくつかあります。
v カーソル・タイプを SQL_CURSOR_STATIC に設定することができます。
v アプリケーションが ADO を使用している場合は、クライアント・サイドのカーソルを使用することが
できます。
v アプリケーションは、実際の照会を実行する前に SELECT COUNT(*) FROM MYTABLE を呼び出すこ
とで COUNT() 関数を使用することができます。
拡張動的使用不可エラー:
IBM i Access ODBC ドライバーでは、SQL パッケージが使用できない場合に拡張動的サポート使用不可
メッセージが表示されます。この問題を訂正するには、次の手順を実行します。
1. アプリケーションを実行したときに、パッケージがデフォルトのパッケージ設定で作成されるように、
システム上の SQL パッケージを削除します。
2. SQL パッケージと一緒に保管されている設定と一致するように SQL デフォルト・ライブラリーの接
続ストリング設定を変更します。
3. 「使用できないパッケージの戻りコード (Return code for unusable package)」という ODBC DSN 設定
を「無視する (Ignore)」または「警告 (Warning)」に切り替えます。また、この同じ振る舞いは、PKG
接続ストリング設定を設定することでも実現できます。
4. XDYNAMIC 接続ストリング設定を使用不可にします。
ODBC 64 ビット Windows および Linux に関する考慮事項:
IBM i Access の環境で ODBC ドライバーを使用する際の、ヘッダー・ファイルおよびデータ型を識別し
ます。
IBM i Access の ODBC ドライバーでは、64 ビット ODBC API のサポートを実装しています。通常は、
Microsoft for Windows 環境および unixODBC for Linux 環境で提供される ODBC ヘッダー・ファイルの
定義に合わせて、このサポートが実装されます。 ODBC API を呼び出すコードを作成する場合は、その関
数プロトタイプに該当する ODBC ヘッダー・ファイルを参照してください。ヘッダー・ファイルは以下の
とおりです。
v sql.h
v sqlext.h
v sqltypes.h
v sqlucode.h
Windows、Linux、および 64 ビット間における特有の相違には、以下のようなものがあります。
v 64 ビット Linux 環境では、long C/C++ 型のサイズは 8 バイトになります。その他の環境 (64 ビット
Windows など) では、long 型のサイズは 4 バイトになります。
プログラミング
519
v 32 ビット環境では、ポインターのサイズは 4 バイトになります。 64 ビット環境では、ポインターの
サイズは 8 バイトになります。
v ODBC API の中には、ポインターをパラメーターとして持つものがあります。それらのポインターを使
用して、アプリケーションとドライバーの間で、サイズの異なるデータを受け渡す場合があります。 64
ビット実装環境において、この方法で受け渡されたデータのサイズが 4 バイト値から 8 バイト値に変
更された場合には、若干の変更が生じます。
共通の C/C++ 型の一部とそれぞれのサイズについて、以下の表で説明します。
表 17. 共通の C/C++ 型および各サイズ
C/C++ 型
Linux 64 ビット
Windows 64 ビット
Linux 32 ビット
Windows 32 ビット
int
4
4
4
4
long
8
4
4
4
long long
8
未定義
8
未定義
LONG LONG
未定義
8
未定義
未定義
ポインター・サイズ
8
8
4
1
未定義 4
INT32
1
4
4
1
4
1
未定義 4
8
未定義 8
8
2
2
2
2
SQLINTEGER
4
4
4
4
SQLLEN
8
8
4
4
SQLSETPOSIROW
8
8
2
2
SQLROWCOUNT
8
未定義
4
4
SQLROWSETSIZE
4
未定義
4
4
SQLROWOFFSET
8
未定義
4
4
SQLPOINTER
8
8
4
INT64
未定義 8
SQLSMALLINT
UINT_PTR
1
未定義 8
未定義 4
1
未定義 4
1
ULONG_PTR
未定義 8
1
SQLHANDLE
SQLHDESC
DWORD
SDWORD
8
4
4
4
1
4
1
4
1
4
1
未定義 4
未定義 4
未定義 4
8
未定義 4
4
8
8
4
4
8
8
4
4
注: 1. この型は、標準ヘッダー・ファイルに定義されていません。 Linux アプリケーション・パッケージ
製品に付属するツールキットで、定義を行います。
以下の表にある ODBC API のオプションの、パラメーター・ポインター・データに対する振る舞いは、
ODBC ドライバーが 32 ビットの場合と 64 ビットの場合とで異なります。通常、特に断りがなければ、
64 ビットの ODBC ドライバーが、パラメーター・ポインター・データを 8 バイト (64 ビット) 値として
処理します。
SQLGetConnectAttr
SQL_ATTR_QUIET_MODE
SQLGetConnectOption (この API は、ODBC ドライバー・マネージャーによって、SQLGetConnectAttr
にマップされます。)
SQL_ATTR_QUIET_MODE
520
IBM i: Windows アプリケーション・パッケージ: プログラミング
SQLGetDescField
SQL_DESC_ARRAY_SIZE
SQLGetDiagField
SQL_DIAG_CURSOR_ROW_COUNT
SQL_DIAG_ROW_COUNT
SQL_DIAG_ROW_NUMBER
SQLGetInfo (これらのオプションは、ODBC ドライバー・マネージャーによって、すべて処理されま
す。) SQL_DRIVER_HENV
SQL_DRIVER_HDBC
SQL_DRIVER_HLIB
SQL_DRIVER_HSTMT
SQL_DRIVER_HDESC
SQLGetStmtAttr
SQL_ATTR_APP_PARAM_DESC
SQL_ATTR_APP_ROW_DESC
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_MAX_LENGTH
SQL_ATTR_MAX_ROWS
SQL_ATTR_PARAM_BIND_OFFSET_PTR
SQL_ATTR_ROW_ARRAY_SIZE
SQL_ATTR_ROW_BIND_OFFSET_PTR
SQL_ATTR_ROW_NUMBER
SQL_ATTR_ROWS_FETCHED_PTR
SQL_ATTR_KEYSET_SIZE
SQLGetStmtOption (この API は、ODBC ドライバー・マネージャーによって、SQLGetStmtAttr にマッ
プされます。)
SQL_MAX_LENGTH
SQL_MAX_ROWS
SQL_ROWSET_SIZE
SQL_KEYSET_SIZE
SQLSetConnectAttr
SQL_ATTR_QUIET_MODE
SQLSetConnectOption (この API は、ODBC ドライバー・マネージャーによって、SQLSetConnectAttr
にマップされます。)
SQL_ATTR_QUIET_MODE
SQLSetDescField
SQL_DESC_ARRAY_SIZE
プログラミング
521
SQLSetStmtAttr
SQL_ATTR_APP_PARAM_DESC
SQL_ATTR_APP_ROW_DESC
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_MAX_LENGTH
SQL_ATTR_MAX_ROWS
SQL_ATTR_PARAM_BIND_OFFSET_PTR
SQL_ATTR_ROW_ARRAY_SIZE
SQL_ATTR_ROW_BIND_OFFSET_PTR
SQL_ATTR_ROW_NUMBER
SQL_ATTR_ROWS_FETCHED_PTR
SQL_ATTR_KEYSET_SIZE
SQLSetConnectAttr
SQL_MAX_LENGTH
SQL_MAX_ROWS
SQL_ROWSET_SIZE
SQL_KEYSET_SIZE
64 ビット IBM i Access ODBC ドライバーの制約事項:
64 ビット ODBC ドライバーでは、MTS はサポートされていません。
MTS の詳細については、 Microsoft Transaction Server の使用 (英語) を参照してください。
SQLTables の説明:
IBM i Access ODBC ドライバー SQLTables API テーブルを使用する際には、いくつかの考慮事項があり
ます。
v CatalogName パラメーターは、ワイルドカードを使用しているかどうかにかかわらず、無視されます。
これは、カタログ名が常にリレーショナル・データベース名であるためです。カタログ名の値が問題と
なるのは、サーバーのライブラリーのリストを生成するために空ストリングにしなければならない場合
のみです。
SQL ステートメントの作成時に指定したとおり正確に、TableName パラメーターにテーブル名を指定し
なければなりません。つまり、テーブル名は、二重引用符で囲んで作成していない限り、大文字にしな
ければなりません。二重引用符で囲んだテーブル名でテーブルを作成している場合は、TableName パラ
メーターも、引用符で囲まれる場合と同じように、大文字小文字を区別して指定する必要があります。
v DSN セットアップ GUI の「カタログ」タブの「ライブラリー表示」オプションは、当該サーバーのラ
イブラリー・リストを検索しようとする組み合わせを選択するときにのみ、この API に影響を与えま
す。この場合、特定のテーブルの複数のライブラリーの検索に基づいて、結果セットを生成することは
できません。
522
IBM i: Windows アプリケーション・パッケージ: プログラミング
v DSN セットアップ GUI の「カタログ」タブの「オブジェクト記述タイプ (Object description type)」オ
プションは、テーブルのリストを取得する際に結果セットの「結果」列に得られる出力に影響を与えま
す。
v '¥_' と '_' が混合しているストリングの場合、SQL_ATTR_METADATA_ID が SQL_FALSE であれば、
最初の '¥_' は実際には '_' として処理されますが、 '_' はワイルドカードとして処理されます。
SQL_ATTR_METADATA_ID が SQL_TRUE である場合、最初の '¥_' は実際には '_' として処理され、
'_' も実際には '_' のように処理されます。ドライバーが、2 番目の '_' を '¥_' に内部変換します。
v ワイルドカード文字、下線 (_) をリテラルとして使用するためには、その前に円記号 (¥) を付けます。
例えば、MY_TABLE (MYATABLE でも MYBTABLE でもない) のみを検索するには、検索ストリング
を、MY¥_TABLE と指定する必要があります。
名前に '¥%' を指定しても、無効になります。IBM i オペレーティング・システムでは、ライブラリー名
またはテーブル名内に、実際の '%' を使用することが許可されていないためです。
ライブラリーのリストに照会があると、ドライバーは、意味のあるデータとして TABLE_CAT および
REMARKS フィールドを戻します。
ODBC 仕様では、ヌルとしての TABLE_SCHEM を除いて、すべてを戻すようになっています。
長時間実行照会の処理:
IBM i Access ODBC ドライバーを使用して照会が実行される時間を制限するには、複数の方法がありま
す。 ODBC で使用可能な 2 つのオプションを次に示しています。
1. アプリケーションで SQL_ATTR_QUERY_TIMEOUT 接続属性を設定し、照会が実行できる最大時間を
指定することができます。照会の処理に必要な時間が SQL_ATTR_QUERY_TIMEOUT 値を超えると
SQL Optimizer が判断した場合、その照会は開始されないことに注意してください。見積時間が
SQL_ATTR_QUERY_TIMEOUT 属性の値を超える場合、SQL0666 SQLCODE がアプリケーションに戻
されます。SQL_ATTR_QUERY_TIMEOUT のデフォルト値は 0 で、照会は完了するまで実行されるこ
とを示します。
2. アプリケーションは SQLCancel API を呼び出すことができます。このためには、アプリケーションを
マルチスレッド化する必要があります。長時間実行照会を 1 つのスレッドで実行しながら、別のスレッ
ドで同じステートメント・ハンドルを使用して SQLCancel を呼び出します。
分離レベルの考慮事項:
異なる分離 (コミット) レベルに対する IBM i Access ODBC 自動コミット・サポートを実行します。
IBM i では、ODBC 自動コミット・サポートを実行して、*NONE 以外の分離レベルを使用できます。
*NONE 以外の分離レベルを指定すれば、異なる分離レベルで自動コミットを実行することができます。
*NONE 以外の自動コミットのコミットメント・レベルを使用する場合は、追加でその他の変更を行う必要
があり、一部の機能の振る舞いが変更される場合があることに注意してください。たとえば、ジャーナル記
録されていないファイルの更新機能の除去などです。詳しくは、「SQL 解説書」の『分離レベル』のトピ
ックを参照してください。
接続ストリング・キーワード TRUEAUTOCOMMIT を使用すれば、自動コミットを *NONE 分離レベルの
もとで実行するか、それとも SQL_ATTR_TXN_ISOLATION 設定のもとで実行するかをアプリケーション
が制御できるようになります。 SQLDriverConnect 接続ストリングで TRUEAUTOCOMMIT を 1 に設定す
ると、アプリケーションは SQL_ATTR_TXN_ISOLATION 設定を使用して自動コミットを実行します。
プログラミング
523
TRUEAUTOCOMMIT を設定しない場合は、デフォルト値の 0 が使用されます。デフォルトの振る舞いで
は、自動コミットは *NONE 分離レベルで実行されます。
関連情報:
SQL 解説書分離レベル
ODBC のパフォーマンス
IBM i Access の ODBC パフォーマンスに関しては、以下のトピックを参照してください。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
ODBC のパフォーマンス調整:
DB2 for i Access ODBC アプリケーション開発者にとって重要なのは、クライアント/サーバー・アプリケ
ーションのパフォーマンスを最大限引き出すことです。
以下のトピックでは、クライアント/サーバーのパフォーマンス上の問題を概説し、一般的な照会ツールお
よび開発環境で ODBC を使った場合のパフォーマンスについて記述しています。
サーバー・パフォーマンスの概要:
すべてのコンピューティング環境でのパフォーマンスの特性について、以下の項目を使用して説明します。
応答時間
要求が処理されるまでにかかる時間
使用率要求の処理時に使用されている資源の割合
スループット
単位時間当たり処理される要求のボリューム
容量
最大限可能なスループット量
通常、サーバーのユーザーにとって、応答時間はパフォーマンスにおける重大な問題です。使用率は、サー
バー管理者にとって重要であることが多いと言えます。最大スループットはパフォーマンスのボトルネック
を示しますが、それほど重要ではない場合があります。これらの特性はすべて相互に関連していますが、サ
ーバーのパフォーマンスについて要約すると以下のようになります。
v いかなるコンピューティング・サーバーにも、パフォーマンス、つまりスループットを左右するボトル
ネックがある
v サーバーの使用率が高くなると、応答時間が低下する
多くのサーバーでは、キャパシティーは無視できませんが、ユーザーにとっては重要ではありません。一
方、キャパシティーがパフォーマンス上の最重要問題になっているシステムもあります。応答時間は常にク
リティカルです。管理者にとっての最重要課題の 1 つは、(ユーザーの増加や使用率の増大によって) サー
バーのパフォーマンスが低下しても、ユーザーから苦情が出ないのはどの程度までかということです。
クライアント/サーバーのパフォーマンスの概要:
クライアント/サーバー環境のパフォーマンスにみられる特性は、集中型の環境の場合とは異なります。
その理由は、クライアント/サーバー・アプリケーションがクライアントとサーバーの間で分割されている
ためです。クライアントとサーバーは、要求とメッセージを送ったり、受信したりすることによってコミュ
524
IBM i: Windows アプリケーション・パッケージ: プログラミング
ニケーションしています。このモデルが、集中型の環境と大きく違う点です。集中型の環境では、プログラ
ムが CPU を呼び出し、メモリーとディスク・ドライブはすべて専用に割り当てられています。
それに対して、クライアントがサーバーの処理時間とデータを要求する場合は、クライアントがネットワー
クにその要求を送信します。送信された要求はサーバーに届くと、サーバーで処理可能になるまで待ち行列
に入って待機します。このタイプのアーキテクチャーでのパフォーマンス特性としては、要求の数が増加す
るにつれて指数関数的に低下するという点があります。言い換えれば、要求が増えるごとにそれだけ応答時
間も長くかかってしまいます。その値は、徐々に増えますが、ある時点で飛躍的に増大します。これは、グ
ラフの曲線の急な折れ曲がりとして知られているポイントです。この概念を図で表すと、以下のグラフのよ
うになります。
の #
パフォーマンスの著しい低下が始まるポイントを判別しておくことが重要です。このポイントは、クライア
ント/サーバーのインストール先によって異なります。
クライアント/サーバーの運用に推奨されるガイドラインは、サーバーとの通信は必要な場合にのみ行い、
できる限りデータ転送を少なくすることです。ファイルを開いてレコードを 1 行ずつ読み取る作業は、多
くの場合クライアント/サーバーのプロジェクトとツールに問題を発生させます。
ODBC ドライバーのパフォーマンス・アーキテクチャー:
IBM i Access ODBC ドライバーでは、クライアントとサーバーの間でやりとりされる内部データのフロー
はすべて連鎖しており、必要な場合にのみ送信されます。
通信レイヤーの資源が割り当てられるのは 1 回のみであるため、サーバーの使用率は削減されます。これ
によって、応答時間は短縮されます。
ユーザーは、こうした機能の拡張を意識することはありません。ただし、「IBM i Access ODBC セットア
ップ」ダイアログで構成可能な、いくつかの機能強化が行われています。詳細については、セットアップ
GUI の「パフォーマンス」タブのオンライン・ヘルプ、または『接続ストリング・キーワード』の「パフ
ォーマンス」オプションの説明を参照してください。
コミットメント制御の強制レベルの選択:
IBM i Access ODBC コミットメント制御を使用するにあたって、いくつかの重要な考慮事項があります。
プログラミング
525
不必要に、コミットメント制御を使用しないでください。ロックに伴うオーバーヘッドによって使用率が増
大するほか、並行性が低下します。ただし、アプリケーションが読み取り専用でない場合は、コミットメン
ト制御が必要な場合があります。
一般的な方法としては、最適ロックを使用します。最適ロックには、特定のレコードを一意に決定する
WHERE 文節を使った明示的な UPDATE を発行する必要があります。最適ロックにより、レコードが検索
後に変更されないことが確実になります。
多くの第三者ツールではこの方法が使われているため、更新可能なテーブルに対して固有索引を定義する必
要があります。これによって、レコードの内容全体が完全に限定され、レコードの更新が可能になります。
次の例を参照してください。
UPDATE table SET C1=new_val1, C2=new_val2, C2=new_val3
WHERE C1=old_val1 AND C2=old_val2 AND C3=old_val3
V6R1 リリースでは、DB2 for i には「ROW CHANGE TIMESTAMP」サポートが追加されました。これに
より、アプリケーションは ROW CHANGE TIMESTAMP 列を持つテーブルを作成できます。この列は、
ROW CHANGE 式および RID 関数と一緒に使用すると、後で変更される可能性がある行ごとにすべての
列をキャッシュに入れる必要なく、行の固有性を保証することができます。これは、オプティミスティッ
ク・ロックの優れたソリューションであり、行ロックの維持が必要なく、行内のすべての列値のキャッシン
グを更新する必要がありません。次の例を参照してください。
/*Add a row change timestamp column (called ’RCT’ in this example)*/
/* to the table when it is created
*/
CREATE TABLE TABLEX (col1 int,..., RCT GENERATED ALWAYS FOR
EACH ROW ON UPDATE AS ROW CHANGE TIMESTAMP NOT NULL);
:
/*Add the ROW CHANGE TOKEN expression and the RID function to the */
/* select list of the query (note : a ROW CHANGE expression which */
/*specifies the TIMESTAMP or the column itself can also be used
*/
/*in the query. See the SQL Reference for more details).
*/
/* Note that locks on the rows read by the query do not need to be*/
/* held.
*/
SELECT ROW CHANGE TOKEN FOR tablex,RID(tablex),col1,....,
FROM TABLEX WHERE ...
:
/* For each row, cache away just the value from the ROW CHANGE
*/
/* TOKEN and the value for the result of the RID function.
*/
/* When a row qualifies to be updated, just the ROW CHANGE
*/
/* TOKEN value and the RID()function value need to be specified in*/
/* the criteria for the UPDATE.
*/
UPDATE table SET Col1=new_val1, Col2=new_val2,... WHERE ROW CHANGE
TOKEN for tablex = <saved value> and RID(tablex) = <saved RID value>
:
UPDATE ステートメントで「row not found」エラーが戻される場合、これは、更新しようとした行が、読
み取られたとき以降に更新または削除されたことを示します。ROW CHANGE 式および RID() 関数につい
て詳しくは、「SQL 解説書」を参照してください。
コミットメント制御が必要な場合は、使用可能な最低位レベルのレコード・ロックを使用します。例えば、
可能なときは *CS より *CHG を使い、*CS で事足りる場合は絶対に *ALL を使わないでください。
関連情報:
コミットメント制御
DB2 for i SQL リファレンス
526
IBM i: Windows アプリケーション・パッケージ: プログラミング
レコード・ブロックの調整:
レコード・ブロックは、IBM i Access ODBC ドライバーを使用した場合に、ネットワーク・フローの数を
大幅に削減し、それによってパフォーマンスを改善する技法の 1 つです。
これは、カーソルに対する最初の FETCH 要求のときにサーバーから複数行のブロックを戻すことによっ
て行います。後に続く FETCH 要求は、毎回サーバーに送られるのではなく、ローカルにある行のブロッ
クから取り出されます。この方法を適切に使用することで、パフォーマンスが目覚ましく向上します。たい
ていの場合は、デフォルトの設定で十分です。
レコード・ブロックのパラメーターを変更すると、使用環境のパフォーマンスが 524 ページの『クライア
ント/サーバーのパフォーマンスの概要』に示されている指数関数的なしきい値に近づいたときに、大きな
変化が生じる可能性があります。例えば、ある環境で、通常、1MB のデータを返すような大きな照会を処
理している意思決定支援クライアントが n 個あるとします。
まったく逆の仮定としては、常時ユーザーが大量のデータを要求しているが、通常は数行しか調べないとい
った場合です。数行しか必要でないときに 32 KB の行を戻すことで生じるオーバーヘッドによって、パフ
ォーマンスが低下する可能性があります。 BLOCKSIZE または BlockSizeKB 接続ストリング・キーワード
を低い値に設定するか、BLOCKFETCH 接続ストリング・キーワードを 0 に設定するか (ODBC ブロック
化を使用)、またはレコード・ブロックを完全に使用不可にすると、パフォーマンスが実際に向上します。
クライアント/サーバーでは常にパフォーマンスの結果が異なっています。これらのパラメーターを変更し
ても、はっきりとした変化が見られない可能性もあります。これはつまり、パフォーマンス上のボトルネッ
クがサーバー上のクライアント要求待ち行列にあるのではないと考えられます。ユーザーから苦情が出た場
合のもう 1 つのツールとして、このパラメーターを使用できます。
関連資料:
482 ページの『接続ストリング・キーワード』
IBM i Access の ODBC ドライバー・サポートでは、ODBC 接続の振る舞いを変更するために、複数の接
続ストリング・キーワードを使用します。
拡張動的 SQL の使用:
IBM i 拡張動的機能を使用して、ODBC アプリケーションのパフォーマンスを改善します。
従来の SQL インターフェースでは、組み込み SQL の方法を使用していました。 SQL ステートメント
は、C、COBOL、RPG およびその他のプログラミング言語で記述された高水準言語ステートメントと並ん
で、アプリケーションのソース・コード中に直接配置されました。次に、ソース・コードがプリコンパイル
され、それによって SQL ステートメントはコンパイルの次の段階で処理できるコードに変換されていまし
た。この方式は、静的 SQL と呼ばれました。この方法に対するパフォーマンス上の利点は、SQL ステー
トメントの最適化が、実行時にユーザーが待機している間ではなく、高水準プログラムがコンパイルされる
ときに行われたことにありました。
しかし ODBC は、別の方法を使用する呼び出しレベル・インターフェース (CLI) です。CLI を使用する
と、SQL ステートメントは実行時 API のパラメーター内で DBMS (データベース管理システム) に渡され
ます。SQL ステートメントのテキストは実行時までわからないため、SQL ステートメントが実行されるた
びに最適化処理を行う必要があります。通常、この方法は動的 SQL と呼ばれます。
この機能 (デフォルトで使用可能に設定されています) を使用すると、応答時間が短縮されるだけでなく、
サーバーの使用効率も飛躍的に向上します。これは、SQL 照会の最適化にはコストがかかるものの、この
処理を 1 回実行すれば常に効果があるためです。 DB2 for i の固有の機能においては、非常に効果的で
す。他の DBMS とは異なり、管理者が介入しなくても、パッケージ内に保管されているステートメント
プログラミング
527
が、常に最新の最適化状態に保たれます。ステートメントが最初に準備されたのが数週間または数カ月前で
あったとしても、データベースを適切に変更するために再最適化が必要があると判断された場合には、DB2
for i で自動的にアクセス・プランが再生成されます。
パッケージおよびパッケージに保管されている SQL ステートメントのタイプについて詳しくは、IBM i
Information Center のトピック『SQL パッケージ』を参照してください。
関連情報:
SQL パッケージ
一般的なエンド・ユーザー用ツールでのパフォーマンスの考慮事項:
ご使用の IBM i Access の ODBC ドライバー環境のチューニングに役立つ、各種ツールがあります。
最適の状態に調整された ODBC ドライバーを用意することは、パフォーマンスのバランスをとるために必
要なことの一部に過ぎません。その他に、使用ツールについて、データを照会するためにのみ使用するの
か、または複雑なプログラムを作成するために使用するのかといったことを確認する必要があります。
一般的に使用されているツールには、以下のものがあります。
v Crystal Services Crystal Reports Professional
v Cognos® Impromptu®
v Gupta SQL Windows
v IBM Visualizer for Windows
v Lotus® Approach®
v Lotus Notes
v Notes Pump
v Microsoft Access
v Microsoft Internet Information Server
v Microsoft SQL Server
v Microsoft Visual Basic
v Powersoft PowerBuilder
v Microsoft Visual Studio .NET
このリスト以外にも使用できるツールが多数あります。市販されているツールにはそれぞれ長所も短所も、
パフォーマンス特性もあります。たいていのツールに共通しているのは、ODBC データベース・サーバー
へのサポートです。 ODBC はさまざまなデータベース管理システムに共通の標準として機能しますが、各
ODBC ドライバー間に微妙な違いが存在するため、ツール・プロバイダーの多くは、ごく一般的な ODBC
と SQL インターフェースに合わせたツールを作成しています。これでは、特定のデータベース・サーバー
のユニークな特性を生かすことができません。プログラミング作業が軽減されることもありますが、全体の
パフォーマンスの低下につながることがよくあります。
例: ODBC パフォーマンスを低下させる一般的なツールの動作:
特定の ODBC ドライバーまたはサーバー・データベース管理システムの固有の機能を利用しない、SQL
呼び出しおよび IBM i Access ODBC 呼び出しの作成に関するパフォーマンス上の問題について、以下の
例で説明します。
528
IBM i: Windows アプリケーション・パッケージ: プログラミング
例: 照会ツール A:
この例は、IBM i Access ODBC 列バインドを使用して情報を素早く検索します。
照会ツール A では、以下の ODBC 呼び出しを行って SELECT ステートメントを処理します。
SQLExecDirect("SELECT * FROM table_name")
WHILE there_are_rows_to_fetch DO
SQLFetch()
FOR every_column DO
SQLGetData( COLn )
END FOR
...process the data
END WHILE
ODBC 列バインドはパフォーマンスの維持に役立ちますが、このツールでは使用されません。この処理を
速くする方法は、以下のとおりです。
SQLExecDirect("SELECT * FROM table_name")
FOR every_column DO
SQLBindColumn( COLn )
END FOR
WHILE there_are_rows_to_fetch DO
SQLFetch()
...process the data
END WHILE
テーブルに含まれている列が 1 列の場合、2 つの方法に大きな違いはありません。しかし、100 列あるテ
ーブルの場合は、最初の例では取り出す行ごとに 100 回もの ODBC 呼び出しが行われることになってし
まいます。ツールによって指定されているターゲット・データ・タイプは FETCH ごとに変更されないた
め、SQLGetData 呼び出しごとに変更できるのと同じように、2 番目のシナリオを最適化することもでき
ます。
例: 照会ツール B:
この例では、IBM i Access ODBC 呼び出し全体に対して 1 つの割り振りステートメントを使用します。
照会ツール B を使用すると、複数行から構成されるスプレッドシートを更新し、その更新情報をデータベ
ースに送ることができます。これは、以下の ODBC 呼び出しを行います。
FOR every_row_updated DO
SQLAllocHandle(SQL_HANDLE_STMT)
SQLExecDirect("UPDATE...SET COLn=’literal’...WHERE COLn=’oldval’...")
SQLFreeHandle( SQL_HANDLE_STMT )
END LOOP
初めに注意する点は、このツールでは、行ごとにステートメントの割り当てとドロップが実行されるという
点です。必要な割り当てステートメントは 1 つのみです。この変更を行うと、操作ごとにステートメント
のハンドルを作成および破棄するときのオーバーヘッドを節減できます。パフォーマンス上のもう 1 つの
問題は、パラメーター・マーカーではなくリテラルで SQL を使用している点です。SQLExecDirect() 呼び
出しによって、毎回 SQLPrepare および SQLExecute が発生します。この操作を迅速に行う方法は、以下
のとおりです。
プログラミング
529
SQLAllocHandle(SQL_HANDLE_STMT)
SQLPrepare("UPDATE...SET COL1=?...WHERE COL1=?...")
SQLBindParameter( new_column_buffers )
SQLBindParameter( old_column_buffers )
FOR every_row_updated DO
...move each rows data into the SQLBindParameter buffers
SQLExecute()
SQLFreeHandle( SQL_HANDLE_STMT )
END LOOP
IBM i Access ODBC ドライバーを使用している場合は、これらの一連の ODBC 呼び出しによって、元の
呼び出しよりはるかに効率がよくなります。サーバーの CPU 使用率はそれまでの 10% に縮小され、基準
化のためのしきい値を考慮する必要がなくなります。
例: 照会ツール C:
この例では、複雑な意思決定支援タイプの照会により IBM i Access ODBC 照会の実行が長くなります。
照会ツール C を使用すると、ポイント・アンド・クリック・インターフェースで高度な照会基準を定義す
ることで、複雑な意思決定支援タイプの照会ができます。最終的に、次のような SQL を照会に使用する場
合があります。
SELECT A.COL1, B.COL2, C.COL3 , etc...
FROM A, B, C, etc...
WHERE many complex inner and outer joins are specified
複雑な照会を記述しなくてもよいのは便利ですが、実際にツールがこのステートメントを処理しない場合が
ある点に注意してください。例えば、このステートメントを直接 ODBC ドライバーに渡すツールもあれ
ば、以下のように多数の照会に分割し、その結果をクライアントで処理するツールもあります。
SQLExecDirect("SELECT * FROM A")
SQLFetch() all rows from A
SQLExecDirect("SELECT * FROM B")
SQLFetch() all rows from B
Process the first join at the client
SQLExecDirect("SELECT * FROM C")
SQLFetch() all rows from C
Process the next join at the client
.
.
.
And so on...
この方法では、クライアントに渡されるデータの量が過大になってしまい、パフォーマンスが低下します。
実例として、あるプログラマーは 10 とおりの内部結合と外部結合が ODBC に渡されて、4 行が戻される
と考えました。しかし、実際に渡されたものは、10 個の簡単な SELECT ステートメントとそれらに関連
したすべての FETCH です。最終結果の 4 行が得られたのは、ツールによって 81,000 回の ODBC 呼び
出しが行われた後です。プログラマーは最初、低速パフォーマンスの原因が ODBC にあると考えたわけで
すが、ODBC のトレースを調べたところ、そうではないことがわかりました。
SQL パフォーマンス:
優れたアプリケーション設計には、マシンの資源の有効利用も含まれます。 IBM i Access ODBC 環境
で、エンド・ユーザーが使いやすい方法で実行されるアプリケーション・プログラムとは、動作効率がよ
く、適切な応答時間で実行されるものでなければなりません。
530
IBM i: Windows アプリケーション・パッケージ: プログラミング
SQL パフォーマンスに関する一般的な考慮事項:
ODBC 環境を設計する際の時期、対象、方法などに関する質問への回答が得られます。
アプリケーション・プログラムにおける SQL のパフォーマンスはすべてのサーバー・ユーザーに重要で
す。SQL の使用が非効率であると、サーバー資源を浪費してしまう可能性があるためです。
SQL を使用する第 1 の目的は、データベース要求に対して、正確な結果を適切なタイミングで取得するこ
とです。
パフォーマンスを考慮した設計を始める前に、以下の考慮事項について検討してください。
パフォーマンスについて考察する必要がある場合
v 10,000 行を超える SQL 表 - パフォーマンスへの影響: 要注意
v 100,000 行を超える SQL 表 - パフォーマンスへの影響: 重大
v 複雑な照会を繰り返し使用する場合
v トランザクションの多いワークステーションを複数使っている場合
最適化する資源
v I/O 使用率
v CPU 使用率
v 索引の効果的な使用
v OPEN/CLOSE のパフォーマンス
v 並行性 (COMMIT)
パフォーマンスを考慮した設計方法
v データベース設計
– テーブル構造
– 索引
– テーブル・データ管理
– ジャーナル管理
v アプリケーション設計
– 関連プログラムの構造
v プログラム設計
– コーディング方法
– パフォーマンス・モニター
「SQL 解説書」ブックには、その他の情報が記載されています。IBM i Information Center にある『DB2
for i SQL 解説書』のトピックから、上記ブックの HTML オンライン版を表示するか、PDF 版を印刷する
ことができます。
関連情報:
DB2 for i SQL リファレンス
データベース設計:
DB2 for IBM i データベースに必要なテーブルを判別し、各テーブル間の関係を理解するために、以下の
トピックを役立ててください。
プログラミング
531
正規化:
DB2 for i のデータベース・テーブルとスキーマの設計時に正規化を考慮する必要があります。
いくつかの有効な設計方式を使用すると、技術的に正しいデータベース、および効率のよいリレーショナ
ル・データベース構造を設計できます。これらの方式には、正規化と呼ばれる設計方法をベースにしている
ものがあります。正規化とは、冗長データの保存を少なくしたり、除去したりすることです。
正規化の第 1 の目的は、冗長データの更新に関連する問題を回避することです。
ただし、正規化という設計方法 (例えば、3NF–3rd Normal Form) を使用することで、テーブルの数が膨大
に増えてしまうことがあります。テーブルの結合操作が多い場合は、SQL パフォーマンスの低下が予想さ
れます。データベースを設計するときは、全体の SQL パフォーマンスについても考えてください。冗長デ
ータの量と、完全には正規化されていないテーブルの数とのバランスを考慮してください。
以下の図は、パフォーマンスに影響するテーブルの数と冗長データの割合を示しています。
データ
テーブルの
パフォーマンス
図 1. 冗長データとテーブルの数のバランス
コード・テーブルを使用してもあまり役に立たない場合は、その使用を最小限にしてください。例えば、
EMPLOYEE (従業員) テーブルに 054、057 などのデータ値を持つ JOBCODE (職種コード) 列があるとし
ます。このテーブルを別のテーブルと組み合わせて、コードをプログラマー、技術者などの職種に変換する
必要があります。この結合では、節減された記憶域に比較して、コストの方がかなり大きくなり、冗長デー
タによって更新エラーが発生する可能性もあります。
例えば、以下のとおりです。
532
IBM i: Windows アプリケーション・パッケージ: プログラミング
図 2. 正規化されたデータ形式
EMPLOYEE テーブル
00010
00020
00030
ジョブ
!"#
プログラマー
!"#
...
...
図 3. 冗長データ形式
SQL のセット・レベル (大量操作) の特性によって、特定の冗長データ形式の危険性が著しく小さくなり
ます。例えば、1 つの SQL ステートメントで複数行のセットを更新できる機能によって、このリスクを非
常に低くすることができます。以下の例では、条件に合うすべての行に対して、Engineer という職種を
Technician に変更する必要があります。
SQL を使用して JOBTITLE を更新します。
UPDATE EMPLOYEE
SET JOBTITLE = "Technician"
WHERE JOBTITLE = "Engineer"
テーブル・サイズ:
アプリケーション・プログラムがアクセスするテーブルのサイズは、ODBC アプリケーション・プログラ
ムのパフォーマンスに大きな影響を与えます。
プログラミング
533
以下のことを考慮してください。
行が長い場合
列が多い (100 以上ある) ために行が長くなった順次アクセス・テーブルの場合は、テーブルを小
さく分割するか、ビューを作成するとパフォーマンスを向上させることができます。これは、アプ
リケーションがすべての列にはアクセスしていないことを前提としています。パフォーマンスがよ
くなる主な理由は、ページ当たりの取得行が増えることによって I/O が軽減されるためです。テー
ブルを分割した場合、すべての列にアクセスするアプリケーションでは、テーブルを再度結合する
ことでオーバーヘッドがかかるため影響が出ます。アプリケーションの特性と多くの列に対するア
クセス頻度に基づいて、テーブルの分割位置を決定する必要があります。
行数が多い場合
テーブルに多数の行があり、そのテーブルにアクセスする照会で WHERE 節が常に指定される場
合は、WHERE 節で使用される列の索引を作成してください。この索引により、DB2 for i 最適化
ルーチンは索引を使用してテーブルにアクセスすることができます。最高のパフォーマンスを実現
する上で、索引の使用は非常に重要です。
関連資料:
535 ページの『最適化ルーチン』
最適化ルーチンは、データベースのパフォーマンス向上において重要な役割を担うため、DB2 for i データ
ベース・エンジンの重要な部分です。DB2 for i データにおける最も効率のよいアクセス・パスを検出する
ことが、主な目的となります。
『索引の使用』
索引を使用すると、IBM i Access ODBC アプリケーションのパフォーマンスが著しく向上します。
索引の使用:
索引を使用すると、IBM i Access ODBC アプリケーションのパフォーマンスが著しく向上します。
DB2 for i 照会オプティマイザーは、パフォーマンスの最適化に索引を使用し、場合によっては、照会の対
応に必要なすべてのデータを索引から読み取ることができます。オプティマイザーの詳細については、関連
リンクを参照してください。
索引の作成には、以下の 5 つの方法があります。
v CREATE INDEX (SQL の中で)
v CRTPF (キー使用)
v CRTLF (キー使用)
v CRTLF (結合論理ファイルとして)
v CRTLF (選択 / 除外を指定、キー不使用、動的選択 (DYNSLT) なし)
索引を使用すると、索引対テーブルのスキャン操作によって行を選択することができますが、通常これは処
理が遅くなります。テーブルのスキャンでは、テーブルのすべての行が順次に処理されます。永続索引が使
用できる場合は、一時索引を作成しなくても済みます。索引は、以下に対して必要です。
v テーブルの結合
v ORDER BY
v GROUP BY
永続索引がない場合は、索引が作成されます。
534
IBM i: Windows アプリケーション・パッケージ: プログラミング
索引の数を管理して、更新操作中の索引の維持管理作業にかかる追加のサーバー・コストを最小限に抑えま
す。以下は、特定のタイプのテーブルに対する汎用規則です。
主として読み取り専用のテーブルの場合
必要に応じて、列の索引を作成します。テーブルが 1,000 行分よりも大きく、ORDER BY、
GROUP BY または結合処理で使用される場合にのみ索引を作成するようにしてください。索引の
維持管理作業には、随時テーブル全体をスキャンするよりもコストがかかる可能性があります。
主として読み取り専用で、更新頻度は低いテーブルの場合
必要に応じて、列の索引を作成します。頻繁に更新される列の索引は作成しません。
INSERT、UPDATE、DELETE とともに、MERGE ステートメントにおけるこれらのステートメン
トによって、テーブルに関連するすべての索引に対して維持管理作業が行われます。
更新頻度の高いテーブルの場合
索引を多く作り過ぎないようにします。更新頻度の高いテーブルには、ログや履歴テーブルがあり
ます。
関連資料:
『最適化ルーチン』
最適化ルーチンは、データベースのパフォーマンス向上において重要な役割を担うため、DB2 for i データ
ベース・エンジンの重要な部分です。DB2 for i データにおける最も効率のよいアクセス・パスを検出する
ことが、主な目的となります。
533 ページの『テーブル・サイズ』
アプリケーション・プログラムがアクセスするテーブルのサイズは、ODBC アプリケーション・プログラ
ムのパフォーマンスに大きな影響を与えます。
結合フィールドの属性の突き合わせ:
DB2 for i の場合、テーブルの結合に使用される列には同じ属性が必要です。
列の長さやデータ・タイプ (文字、数値) など、結合されるテーブルの列の属性は、同一でなければなりま
せん。同一でない属性があると、対応する列の索引が既にある場合でも一時索引が作成されることになりま
す。
次の例では、結合によって一時索引が作成され、既存の索引は無視されます。
SELECT EMPNO, LASTNAME, DEPTNAME
FROM TEMPL, TDEPT
WHERE TEMPL.DEPTNO = TDEPT.DEPTNO
最適化ルーチン:
最適化ルーチンは、データベースのパフォーマンス向上において重要な役割を担うため、DB2 for i データ
ベース・エンジンの重要な部分です。DB2 for i データにおける最も効率のよいアクセス・パスを検出する
ことが、主な目的となります。
照会の最適化は、照会実施方法の選択に要する時間と、その実行にかかる時間との間の妥協です。照会の最
適化では、次のようなユーザーの明確なニーズに応える必要があります。
プログラミング
535
v 高速で対話式の応答
v マシン資源全体の有効利用
データへのアクセス方法を決定するために、最適化ルーチンでは以下が行われます。
v 可能な実施方法の判別
v SQL ステートメントの実行に最適な実施方法の選択
関連資料:
534 ページの『索引の使用』
索引を使用すると、IBM i Access ODBC アプリケーションのパフォーマンスが著しく向上します。
533 ページの『テーブル・サイズ』
アプリケーション・プログラムがアクセスするテーブルのサイズは、ODBC アプリケーション・プログラ
ムのパフォーマンスに大きな影響を与えます。
コストの見積もり:
実行時に、DB2 for i 最適化ルーチンは、照会および使用可能な任意のアクセス・パス (索引) で参照され
るテーブルの現在の状態に基づいて実施方法のコストを計算して、照会に対する最適なアクセス方式を選択
します。
最適化ルーチンは、以下のそれぞれについてのアクセス・コストをモデル化します。
v テーブルからの直接の行読み取り (データ・スペース・スキャン処理)
v アクセス・パスを介した行読み取り (キー選択またはキー位置を使用)
v データ・スペースからの直接のアクセス・パス作成
v 既存のアクセス・パスからの新しいアクセス・パスの作成 (索引から索引)
v 照会ソート・ルーチンの使用 (条件が満たされている場合)
特定の方式によるコストは、以下の合計です。
v 開始時のコスト
v 該当の最適化モードに関連するコスト。OPTIMIZE FOR n ROWS 文節は、最適化ルーチンに対して、
達成すべき最適化目標を示しています。最適化ルーチンでは、以下の 2 つの目標のいずれかで SQL 照
会を最適化することができます。
1. テーブルから、行の最初のバッファーを取り出すのに要する時間を最小限にします。この目標では、
最適化が索引の作成をしないように仕向けます。
注: これは、OPTIMIZE FOR n ROWS を使わない場合のデフォルトの設定です。
データ・スキャンまたは既存の索引が選択されます。このモードは、以下によって指定できます。
– ユーザーが照会で検索したい行数を指定できる OPTIMIZE FOR n ROWS。
最適化ルーチンはこの値を使って、戻される行の割合を判別し、それに応じて最適化します。小さ
い値を指定すると、最適化ルーチンは、最初の n 行の取り出しに必要な時間を最小限にするよう
に指示されたことになります。
2. 選択されたすべての行がアプリケーションに戻されていると想定して、照会全体の処理時間を最小限
にします。これによって、最適化ルーチンが特定のアクセス方式に偏ることはありません。
OPTIMIZE FOR n ROWS を使って、このモードを指定します。OPTIMIZE FOR n ROWS を使用す
ると、ユーザーは照会で取り出したい行数を指定できます。
536
IBM i: Windows アプリケーション・パッケージ: プログラミング
最適化ルーチンはこの値を使って、戻される行の割合を判別し、それに応じて最適化します。結果の
行数が予想していた以上の値であれば、最適化ルーチンは照会全体の実行に要する時間を最小限にす
るように指示されます。
v アクセス・パス作成のコスト。
v 行読み取りに予想されるページ不在数によるコスト、および予想される行数の処理によるコスト。
ページ不在数および処理される行数は、最適化ルーチンがデータベース・オブジェクトから取得する以
下の統計値によって予測されることがあります。
– テーブル・サイズ
– 行サイズ
– 索引サイズ
– キー・サイズ
予想される処理行数の重みの基準。これは、行の選択述部 (デフォルトのフィルター係数) の関係演算子
で取り出すと考えられるものに基づいています。
– 10% 「等しい」
– 33% 「未満」「大きい」「以下」「以上」
– 90% 「等しくない」
– 25% BETWEEN 範囲
– 10% 各 IN リスト値
キー範囲の見積もりは、1 つまたは複数の選択述部から選択されている予想行数について、より正確な
見積もりを得るために最適化ルーチンで使用される方式です。最適化ルーチンは、既存の索引の左端の
キーに対して選択述部を適用することで、見積もります。デフォルトのフィルター係数は、キー範囲に
基づく見積もりによって、さらに精度が上がる可能性があります。索引の左端のキーが行選択述部で使
われている列に一致している場合は、その索引を使って選択基準に合うキーの数を見積もります。キー
の数の見積もりは、ページの数とマシン索引のキー密度に基づいています。この見積もりは、実際にキ
ーにアクセスしないで実行されます。選択述部で使用される列の完全な索引があれば、最適化に非常に
役立ちます。
最適化ルーチンの意思決定規則:
DB2 for i 最適化ルーチンでは、実行時に一般的なガイドラインを使って、データベース・テーブルへのア
クセスに最適な方法を選択します。
最適化ルーチンによって、以下が実行されます。
v 選択文節のそれぞれの述部に対して、デフォルトのフィルター係数を判別します。
v 内部に保管された情報からテーブルの属性を抽出します。
v 選択述部が索引の左端のキーに一致している場合に、見積キー範囲を実行して、述部の実際のフィルタ
ー係数を判別します。
v 索引が必要な場合は、テーブルに索引を作成するコストを判別します。
v 選択基準が適用でき、索引が必要な場合は、ソート・ルーチンの使用によるコストを判別します。
v 索引が必要でない場合は、データ・スペースのスキャン処理によるコストを判別します。
v 最適化ルーチンでは、使用できるそれぞれの索引について、最近作成されたものから古い順に、時間制
限を超えるまで以下の処理が行われます。
– 内部に保管されている統計データから索引の属性を抽出します。
プログラミング
537
– 索引が選択基準を満たしているかどうか判別します。
– 見積ページ不在と述部フィルター係数を使って、索引使用によるコストを判別します。
– この索引の使用によるコストと前のコスト (現在最適のもの) を比較します。
– 最も低い値を選択します。
– タイムアウトになるか、または索引がなくなるまで、続けて最適な索引を検索します。
時間制限係数によって、実施方法の選択に要する時間が制御されます。この時間は、所要時間と現在の最適
な実施方法に基づいています。動的 SQL 照会は、最適化ルーチンの時間制限に左右されます。静的 SQL
照会には時間制限がありません。
テーブルが小さい場合は、最適化ルーチンで照会の最適化にあまり時間がかかりません。テーブルが大きい
場合は、最適化ルーチンで扱う索引が多くなります。一般に、最適化ルーチンは最適化時間が切れるまでに
(結合する各テーブルに対して) 5、6 個の索引を検討します。
複数行ステートメントに対する ODBC サポート:
DB2 for IBM i および ODBCは、以下で説明している手法を使用して、INSERT、UPDATE、DELETE、お
よび MERGE ステートメントにおける複数行操作をサポートします。この例では、ODBC で複数行
INSERT ステートメントを使用して複数の行を 1 つの DB2 for i テーブルに挿入する方法を示していま
す。
複数行 INSERT ステートメントによって、単一の SQLExecute 要求で複数の行を挿入することができま
す。パフォーマンスの観点から見れば、テーブルにデータを入れるための最適の方法を提供し、他の方法よ
りも効率がはるかに良いことも多々あります。
ODBC から実行することのできる INSERT ステートメントの形式は、以下の 3 つです。
v VALUES に定数を使用した INSERT ステートメント
v VALUES にパラメーター・マーカーを使用した INSERT ステートメント
v 複数行 INSERT
VALUES に定数を使用した INSERT ステートメントは、挿入を実行するメソッドで最も効率の悪いもので
す。それぞれの要求に対して、単一の INSERT ステートメントがサーバーに送られます。サーバーでは
INSERT ステートメントの準備、基礎テーブルのオープン、レコードの書き込みが行われます。
例:
INSERT INTO TEST.TABLE1 VALUES(’ENGINEERING’,10,’JONES’,’BOB’)
VALUES にパラメーター・マーカーを使用した INSERT ステートメントは、定数を使用したステートメン
トよりも効率よく実行されます。この形式の INSERT ステートメントでは、そのステートメントを 1 回の
み準備して、次の実行で再利用することができます。また、サーバー上のテーブルをオープンしたままにし
ておけるので、挿入のたびにファイルをオープンしたりクローズしたりする手間を省くことができます。
例:
INSERT INTO TEST.TABLE1 VALUES (?, ?, ?, ?)
複数の行がクライアントにキャッシュされ、同時に送信される場合、複数行の INSERT ステートメントは
テーブルの挿入を最も効率よく実行します。複数行の INSERT ステートメントの利点は以下のとおりで
す。
538
IBM i: Windows アプリケーション・パッケージ: プログラミング
v 複数の行にあるデータが、行ごとに 1 つずつの要求ではなく、1 つの通信要求にまとめて送信される。
v サーバーが、複数行の INSERT ステートメントのサポート用にデータベース内に組み込まれた最適化パ
スをもつ。
例:
INSERT INTO TEST.TABLE1 ? ROWS VALUES (?, ?, ?, ?)
INSERT ステートメントには複数行の INSERT ステートメントを識別する構文も加えられています。この
オプション構文 "? ROWS" 文節は、追加されたパラメーターがこの INSERT ステートメント用に指定さ
れることを示し、また、そのパラメーターがそのステートメントの実行時に送信される行数を含むことを示
します。行数は SQLSetStmtAttr API によって指定する必要があります。この余分の文節は必要ないこと
に注意してください。複数行 INSERT ステートメントは、パラメーター・マーカーを使用する VALUES
形式のステートメントで INSERT を作成し、SQLSetStmtAttr API で行数を設定してから、ステートメン
トを実行することによっても実行できます。
複数行ステートメントに対する、C プログラムから使用される API の例を表示するには、複数行挿入およ
び複数行取り出しの C 例のトピックを参照してください。
カタログ関数:
カタログ関数は、操作中の DB2 for i のデータベース・オブジェクトに関する情報を戻します。
ODBC の SQLTables 要求を処理するために、ライブラリー QSYS のサーバー相互参照ファイル
QADBXREF についての論理ファイルが作成されます。 QADBXREF は、データベースによって保持され
る相互参照情報 (サーバーのディクショナリー機能の一部) 用のデータベース・ファイルです。
以下に、TableType の設定ごとに、SQLTables に対応する処置を示します。
NULL SQL SQL テーブルおよびビューを含む、すべての論理ファイル、物理ファイルを選択します。
TABLE
サーバー・ファイル (相互参照、またはデータ・ディクショナリー) ではない SQL テーブルを含
む、すべての物理ファイルを選択します。
VIEW サーバー・ファイル (相互参照、またはデータ・ディクショナリー) ではない SQL ビューを含
む、すべての論理ファイルを選択します。
SYSTEM TABLE
サーバー・ファイルまたはデータ・ディクショナリー・ファイルである SQL ビューを含む、すべ
ての物理ファイルと論理ファイルを選択します。
TABLE, VIEW
サーバー・ファイルまたはデータ・ディクショナリー・ファイルではない SQL テーブルとビュー
を含む、すべての論理ファイルと物理ファイルを選択します。
非リレーショナル・ファイル (複数のファイル形式を持ったファイル) は選択されません。また、索引ファ
イル、フラット・ファイル、そして IDDU 定義済みファイルも選択されません。
カタログ関数によって戻される結果セットは、テーブル・タイプ順になっています。システムでは、テーブ
ルとビューというタイプに加え、論理ファイルと物理ファイルという、データ・ソース特有のタイプ識別コ
ードを使用しています。物理タイプはテーブルとして取り扱われ、論理タイプはビューとして取り扱われま
す。
プログラミング
539
ODBC の SQLColumns 要求を処理するために、QSYS ライブラリーのサーバー相互参照ファイル
QADBIFLD についての論理ファイルが作成されます。この論理ファイルは、インデックス以外のすべての
リレーショナル・データベース・ファイルを選択します。QADBIFLD は、データベースによって保持され
る相互参照情報 (サーバーのディクショナリー機能の一部) 用のデータベース・ファイルです。特に、この
ファイルには、データベース・ファイルの列とフィールドに関する情報が含まれています。
詳細については、以下を参照してください。
「SQL 解説書」の付録に追加情報が記載されています。 IBM i Information Center にある『DB2
for i SQL 解説書』のトピックから、上記ブックの HTML オンライン版を表示するか、PDF 版を
印刷してください。
関連情報:
DB2 for i SQL リファレンス
出口プログラム:
IBM i Access の ODBC 出口プログラムを呼び出すための要件があります。
出口プログラムは、呼び出し側プログラムから制御が渡されるプログラムです。出口プログラムを指定する
と、サーバーはその要求を実行する前に、以下の 2 つのパラメーターを出口プログラムに渡します。
v 1 バイトの戻りコード値。
v ユーザー要求に関する情報を含んだ構造。この構造は、それぞれの出口点ごとに異なります。
出口プログラムはこの 2 つのパラメーターによって、要求が許可されたかどうかを判別できます。出口プ
ログラムで戻りコードが X'F0' に設定されている場合は、サーバーは要求を拒否します。戻りコードがそ
れ以外の値に設定されている場合は、サーバーは要求を許可します。
複数の出口点で同じプログラムを使用できます。プログラムは 2 番目のパラメーター構造の中のデータを
見ることによって、現在どの関数が呼び出されているのかを判別できます。
出口プログラムをデータベースの出口点に追加するためには、「登録情報処理」(WRKREGINF) コマンドを使
用します。
データベース・サーバーには、以下の 5 つの異なる出口点が定義されています。
QIBM_QZDA_INIT
サーバーの開始時に呼び出されます。
QIBM_QZDA_NDB1
ネイティブ・データベース要求に対して呼び出されます。
QIBM_QZDA_SQL1
SQL 要求に対して呼び出されます。
QIBM_QZDA_SQL2
SQL 要求に対して呼び出されます。
QIBM_QZDA_ROI1
オブジェクト情報の取り出し要求や SQL カタログ関数に対して呼び出されます。
注: この出口点は、V5R1 およびそれ以前のクライアント・アクセス ODBC ドライバーの場合に
比べると、呼び出される頻度は低くなります。この出口点を使用する出口プログラムがある場合に
は、引き続き意図されたとおりに機能するかどうかを検査してください。
540
IBM i: Windows アプリケーション・パッケージ: プログラミング
例: ユーザー出口プログラム:
以下の例では、プログラミングに関する考慮事項または技法のすべてが示されているわけではありません。
これらの例をよく検討してから、IBM i Access ODBC アプリケーションの設計やコーディングを開始して
ください。
例: 出口点 QIBM_QZDA_INIT のための ILE C/400 ユーザー出口プログラム:
以下の ILE C/400 プログラムは、特定のユーザーからの要求をリジェクトすることで、IBM i Access の
ODBC セキュリティーを処理します。これをシェルとして使用して、ご使用の稼働環境に合わせた出口プ
ログラムを開発することができます。
/******************************************************************/
/*
Sample Exit Program
*/
/*
*/
/*
Exit Point Name
: QIBM_QZDA_INIT
*/
/*
*/
/*
Description
: The following ILE C Language program
*/
/*
handles ODBC security by rejecting
*/
/*
requests from users who use ODBC and
*/
/*
signon using a user profile of ’GUEST’. */
/*
It can be used as a shell program
*/
/*
for developing exit programs tailored
*/
/*
for your environment.
*/
/******************************************************************/
#include <stdio.h>
#include <string.h>
#include <ezdaep.h>
/* ZDA exit program formats */
main(int argc, char *argv[])
{
Qzda_Init_Format_t input;
/* input format
*/
/**************************************************************/
/* Copy format parameter to local storage
*/
/**************************************************************/
memcpy(&input,(Qzda_Init_Format_t *) argv[2],
sizeof(Qzda_Init_Format_t));
/**************************************************************/
/* If user profile is ’GUEST’ and interface type is ’ODBC’
*/
/* reject the connection.
*/
/**************************************************************/
if (memcmp(input.User_Profile,"GUEST
",10)==0 &&
memcmp(input.Interface_Type,"ODBC",4) == 0)
/**************************************************************/
/* Reject the connection.
*/
/**************************************************************/
strcpy(argv[1],"0");
else
/**************************************************************/
/* Allow the connection.
*/
/**************************************************************/
strcpy(argv[1],"1");
return;
}
例: 出口点 QIBM_QZDA_INIT のための CL ユーザー出口プログラム:
以下の CL プログラムは、特定のユーザーからの要求をリジェクトすることで、IBM i Access の ODBC
セキュリティーを処理します。これをシェルとして使用して、ご使用の稼働環境に合わせた出口プログラム
を開発することができます。
プログラミング
541
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
/*
@@ss1s@@ Servers - Sample Exit Program
/*
/*
Exit Point Name
: QIBM_QZDA_INIT
/*
/*
Description
: The following Control Language program
/*
handles ODBC security by rejecting
/*
requests from certain users.
/*
It can be used as a shell for developing
/*
exit programs tailored for your
/*
operating environment.
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
PGM PARM(&STATUS &REQUEST)
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Program call parameter declarations
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
DCL VAR(&STATUS) TYPE(*CHAR) LEN(1) /* Accept/Reject indicator
*/
DCL VAR(&REQUEST) TYPE(*CHAR) LEN(34) /* Parameter structure
*/
/* * * * * * * * * * * * * * * * * * * *
/* Parameter declares
/* * * * * * * * * * * * * * * * * * * *
DCL VAR(&USER) TYPE(*CHAR) LEN(10) /*
DCL VAR(&SRVID) TYPE(*CHAR) LEN(10) /*
DCL VAR(&FORMAT) TYPE(*CHAR) LEN(8) /*
DCL VAR(&FUNC) TYPE(*CHAR) LEN(4)
/*
* * * * * * * * * * * * * * * * */
*/
* * * * * * * * * * * * * * * * */
User profile name calling server*/
database server value (*SQL)
*/
Format name (ZDAI0100)
*/
function being preformed (0)
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Extract the various parameters from the structure
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
CHGVAR VAR(&USER)
VALUE(%SST(&REQUEST 1 10))
CHGVAR VAR(&SRVID) VALUE(%SST(&REQUEST 11 10))
CHGVAR VAR(&FORMAT) VALUE(%SST(&REQUEST 21 8))
CHGVAR VAR(&FUNC)
VALUE(%SST(&REQUEST 28 4))
/*-----------------------------------------------------------------------------------------------------------------------------------------------*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* Begin main program
*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/* set return code to allow the request.
CHGVAR VAR(&STATUS) VALUE(’1’)
*/
/* if user name is GUEST set return code to reject the request.
IF (&USER *EQ ’GUEST’) THEN( +
CHGVAR VAR(&STATUS) VALUE(’0’) )
*/
EXIT:
ENDPGM
例: 出口点 QIBM_QZDA_SQL1 のための ILE C/400 プログラム:
以下の ILE C/400 プログラムは、GUEST ユーザーのすべての UPDATE 要求をリジェクトします。これ
をシェルとして使用して、ご使用の稼働環境に合わせた IBM i アクセス ODBC 出口プログラムを開発す
ることができます。
/*-------------------------------------------------------------------------*
@@ss1s@@ Servers - Sample Exit Program
*
*
Exit Point Name
: QIBM_QZDA_SQL1
*
*
Description
: The following ILE C/400 program will
*
reject any UPDATE request for user GUEST.
542
IBM i: Windows アプリケーション・パッケージ: プログラミング
*
It can be used as a shell for developing
*
exit programs tailored for your
*
operating environment.
*
*
Input
: A 1-byte return code value
*
X’F0’ server rejects the request
*
anything else server allows the request
*
Structure containing information about the
*
request. The format used by this program
*
is ZDAQ0100.
*------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------*
Includes
*------------------------------------------------------------------------*/
#include <string.h>
/* string functions
*/
#include <stdio.h>
/* standard IO functions
*/
#include <ctype.h>
/* type conversion functions
*/
/*========================================================================
*
Start of mainline executable code
*========================================================================*/
main(int argc, char *argv[])
{
long i;
_Packed struct zdaq0100 {
char name[10];
char servid[10];
char fmtid[8];
long funcid;
char stmtname[18];
char cursname[18];
char prepopt[2];
char opnattr[2];
char pkgname[10];
char pkglib[10];
short drdaind;
char commitf;
char stmttxt[512];
} *sptr, stx;
/*-----------------------------------------------------------------------------------------------------------------------------------------------*/
/* initialize return variable to indicate ok status
*/
strncpy(argv[1],"1",1);
/**********************************************************************/
/* Address parameter structure for @@sqll@@ exit program and move local
/* parameters into local variables.
*/
/* (note : this is not necessary to evaluate the arguments passed in). */
/**********************************************************************/
sptr = (_Packed struct zdaq0100 *) argv[2];
*/
strncpy(stx.name, sptr->name, 10);
strncpy(stx.servid, sptr->servid, 10);
strncpy(stx.fmtid, sptr->fmtid, 8);
stx.funcid = sptr->funcid;
strncpy(stx.stmtname, sptr->stmtname, 18);
strncpy(stx.cursname, sptr->cursname, 18);
strncpy(stx.opnattr, sptr->opnattr, 2);
strncpy(stx.prepopt, sptr->prepopt, 2);
strncpy(stx.pkglib, sptr->pkglib, 10);
strncpy(stx.pkgname, sptr->pkgname, 10);
stx.drdaind = sptr->drdaind;
stx.commitf = sptr->commitf;
strncpy(stx.stmttxt, sptr->stmttxt, 512);
/**********************************************************************/
/* check for user GUEST and an UPDATE statement
*/
プログラミング
543
/* if found return an error
*/
/**********************************************************************/
if (! (strncmp(stx.name, "GUEST
", 10)) )
{
for (i=0; i<6; i++)
stx.stmttxt[i] = toupper(stx.stmttxt[i]);
if (! strncmp(stx.stmttxt, "UPDATE", 6) )
/* Force error out of @@sqll@@ user exit pgm
strncpy(argv[1], "0", 1);
else;
}
}
return;
/* End of mainline executable code
*/
*/
/*-----------------------------------------------------------------------------------------------------------------------------------------------*/
/* initialize return variable to indicate ok status
strncpy(argv[1],"1",1);
*/
/**********************************************************************/
/* Address parameter structure for @@sqll@@ exit program and move local
/* parameters into local variables.
*/
/* (note : this is not necessary to evaluate the arguments passed in). */
/**********************************************************************/
sptr = (_Packed struct zdaq0100 *) argv[2];
*/
strncpy(stx.name, sptr->name, 10);
strncpy(stx.servid, sptr->servid, 10);
strncpy(stx.fmtid, sptr->fmtid, 8);
stx.funcid = sptr->funcid;
strncpy(stx.stmtname, sptr->stmtname, 18);
strncpy(stx.cursname, sptr->cursname, 18);
strncpy(stx.opnattr, sptr->opnattr, 2);
strncpy(stx.prepopt, sptr->prepopt, 2);
strncpy(stx.pkglib, sptr->pkglib, 10);
strncpy(stx.pkgname, sptr->pkgname, 10);
stx.drdaind = sptr->drdaind;
stx.commitf = sptr->commitf;
strncpy(stx.stmttxt, sptr->stmttxt, 512);
/**********************************************************************/
/* check for user GUEST and an UPDATE statement
*/
/* if found return an error
*/
/**********************************************************************/
if (! (strncmp(stx.name, "GUEST
", 10)) )
{
for (i=0; i<6; i++)
stx.stmttxt[i] = toupper(stx.stmttxt[i]);
if (! strncmp(stx.stmttxt, "UPDATE", 6) )
/* Force error out of @@sqll@@ user exit pgm
strncpy(argv[1], "0", 1);
else;
}
}
return;
/* End of mainline executable code
*/
*/
例: 出口点 QIBM_QZDA_ROI1 のための ILE C/400 プログラム:
以下の ILE C/400 プログラムは、カタログ関数に対するすべての要求を、QGPL 内の ZDALOG ファイル
に記録します。これをシェルとして使用して、ご使用の稼働環境に合わせた IBM i アクセス ODBC 出口
プログラムを開発することができます。
544
IBM i: Windows アプリケーション・パッケージ: プログラミング
/*-------------------------------------------------------------------------*
@@ss1s@@ Servers - Sample Exit Program
*
*
Exit Point Name
: QIBM_QZDA_ROI1
*
*
Description
: The following ILE C/400 program logs all
*
requests for catalog functions to the
*
ZDALOG file in QGPL.
*
It can be used as a shell for developing
*
exit programs tailored for your
*
operating environment.
*
*
Input
: A 1-byte return code value
*
X’F0’ server rejects the request
*
anything else server allows the request
*
Structure containing information about the
*
request. The format used by this program
*
is ZDAR0100.
*
*
Dependencies
: The log file must be created using the
*
following command:
*
CRTPF FILE(QGPL/ZDALOG) RCDLEN(132)
*------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------*
Includes
*------------------------------------------------------------------------*/
#include <recio.h>
/* record IO functions
*/
#include <string.h>
/* string functions
*/
/*-----------------------------------------------------------------------*
User Types
*------------------------------------------------------------------------*/
typedef struct {
/* Exit Point QIBM_QZDA_ROI1 format ZDAR0100 */
char User_profile_name[10];
/* Name of user profile calling server*/
char Server_identifier[10];
/* database server value (*RTVOBJINF) */
char Exit_format_name[8];
/* User exit format name (ZDAR0100)
*/
long Requested_function;
/* function being preformed
*/
char Library_name[20];
/* Name of library
*/
char Database_name[36];
/* Name of relational database
*/
char Package_name[20];
/* Name of package
*/
char File_name[256];
/* Name of file
*/
char Member_name[20];
/* Name of member
*/
char Format_name[20];
/* Name of format
*/
} ZDAR0100_fmt_t;
/*-----------------------------------------------------------------------------------------------------------------------------------------------*/
/*========================================================================
*
Start of mainline executable code
*========================================================================*/
int main (int argc, char *argv[])
{
_RFILE *file_ptr;
/* pointer to log file
*/
char output_record[132];
/* output log file record
*/
ZDAR0100_fmt_t input;
/* input format record
*/
/* set return code to allow the request.
*/
memcpy( argv[1], "1", 1);
/* open the log file for writing to the end of the file
if (( file_ptr = _Ropen("QGPL/ZDALOG", "ar") ) == NULL)
{
/* open failed
return;
}
*/
/* copy input parm into structure
memcpy(&input, (ZDAR0100_fmt_t *)argv[2], 404);
*/
*/
プログラミング
545
switch /* Create the output record based on requested function
*/
(input.Requested_function)
{
case 0X1800: /* Retrieve library information
*/
sprintf(output_record,
"%10.10s retrieved library %20.20s",
input.User_profile_name, input.Library_name);
break;
case 0X1801: /* Retrieve relational database information
*/
sprintf(output_record,
"%10.10s retrieved database %36.36s",
input.User_profile_name, input.Database_name);
break;
case 0X1802: /* Retrieve @@sqll@@ package information
sprintf(output_record,
"%10.10s retrieved library %20.20s package %20.20s",
input.User_profile_name, input.Library_name,
input.Package_name);
break;
case 0X1803: /* Retrieve @@sqll@@ package statement information
sprintf(output_record,
"%10.10s retrieved library %20.20s package %20.20s statement info",
input.User_profile_name, input.Library_name,
input.Package_name);
break;
/*-----------------------------------------------------------------------------------------------------------------------------------------------*/
}
case 0X1804: /* Retrieve file information
*/
sprintf(output_record,
"%10.10s retrieved library %20.20s file %40.40s",
input.User_profile_name, input.Library_name, input.File_name);
break;
case 0X1805: /* Retrieve file member information
*/
sprintf(output_record,
"%10.10s retrieved library %20.20s member %20.20s file %40.40s",
input.User_profile_name, input.Library_name,
input.Member_name, input.File_name);
break;
case 0X1806: /* Retrieve record format information
*/
sprintf(output_record,
"%10.10s retrieved library %20.20s format %20.20s file %40.40s",
input.User_profile_name, input.Library_name,
input.Format_name, input.File_name);
break;
case 0X1807: /* Retrieve field information
*/
sprintf(output_record,
"%10.10s retrieved field info library %20.20s file %40.40s",
input.User_profile_name, input.Library_name, input.File_name);
break;
case 0X1808: /* Retrieve index information
*/
sprintf(output_record,
"%10.10s retrieved index info library %20.20s file %40.40s",
input.User_profile_name, input.Library_name, input.File_name);
break;
case 0X180B: /* Retrieve special column information
*/
sprintf(output_record,
"%10.10s retrieved column info library %20.20s file %40.40s",
input.User_profile_name, input.Library_name, input.File_name);
break;
default : /* Unknown requested function
*/
sprintf(output_record, "Unknown requested function");
break;
/* end switch statement
*/
/* write the output record to the file
546
IBM i: Windows アプリケーション・パッケージ: プログラミング
*/
*/
*/
_Rwrite(file_ptr, &output_record, 132);
/* close the log file
_Rclose ( file_ptr );
}
*/
/* End of mainline executable code
*/
出口プログラムのパラメーター・フォーマット:
ネイティブ・データベース用の出口点、およびオブジェクト情報取り出し用の出口点には、
QIBM_QZDA_SQL1、QIBM_QZDA_SQL2 の 2 つの形式が定義されています。要求された IBM i データ
ベース関数のタイプに応じて、これらの形式のうちの 1 つが使用されます。
QIBM_QZDA_SQL2 出口点は、データベース・サーバーに対する特定の SQL 要求時に、出口プログラム
を実行するように定義されています。この出口点は、QIBM_QZDA_SQL1 出口点よりも優先されます。
QIBM_QZDA_SQL2 出口点にプログラムが登録されると、そのプログラムが呼び出され、
QIBM_QZDA_SQL1 に登録されたプログラムは呼び出されません。
出口プログラムを呼び出す関数
v 準備
v オープン
v 実行
v 接続
v パッケージの作成
v パッケージのクリア
v パッケージの削除
v パッケージ情報の戻し
v ストリーム取り出し
v 即時実行
v 準備および記述
v 準備および実行、または準備およびオープン
v オープンおよび取り出し
v 実行またはオープン
ZDAQ0200 形式の出口点 QIBM_QZDA_SQL2 のパラメーター・フィールド:
ZDAQ0200 形式を使用する出口点 QIBM_QZDA_SQL2 で呼び出された IBM i データベース出口プログラ
ムのパラメーター・フィールドとその説明を以下の表に示します。
表 18. ZDAQ0200 形式の出口点 QIBM_QZDA_SQL2
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
この出口点に対する値は *SQLSRV です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。
QIBM_QZDA_SQL1 の形式名は ZDAQ0100
です。
プログラミング
547
表 18. ZDAQ0200 形式の出口点 QIBM_QZDA_SQL2 (続き)
オフセット
10 進
16 進
28
1C
タイプ
フィールド
説明
BINARY(4)
要求された関数
実行される関数。
このフィールドの内容は、次のいずれかで
す。
v X'1800' - 準備
v X'1803' - 準備および記述
v X'1804' - オープン / 記述
v X'1805' - 実行
v X'1806' - 即時実行
v X'1809' - 接続
v X'180C' - ストリーム取り出し
v X'180D' - 準備および実行
v X'180E' - オープンおよび取り出し
v X'180F' - パッケージの作成
v X'1810' - パッケージのクリア
v X'1811' - パッケージの削除
v X'1812' - 実行またはオープン
v X'1815' - パッケージ情報の戻し
32
20
CHAR(18)
ステートメント名
準備関数や実行関数に使用するステートメン
トの名前。
50
32
CHAR(18)
カーソル名
オープン関数に使用されるカーソル名。
68
44
CHAR(2)
準備オプション
準備関数に使用されるオプション。
70
46
CHAR(2)
オープン属性
オープン関数に使用されるオプション。
72
48
CHAR(10)
拡張動的パッケージ名拡張動的パッケージの名前。
82
52
CHAR(10)
パッケージ・ライブラ拡張動的 SQL パッケージ用ライブラリー
リー名
の名前。
92
5C
BINARY(2)
DRDA インディケー
ター
94
5E
CHAR(1)
v 0 - ローカル RDB に接続
v 1 - リモート RDB に接続
コミットメント制御レ v 'A' - コミット *ALL
ベル
v 'C' - コミット *CHANGE
v 'N' - コミット *NONE
v 'S' - コミット *CS (カーソル固定性)
548
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 18. ZDAQ0200 形式の出口点 QIBM_QZDA_SQL2 (続き)
オフセット
10 進
16 進
95
5F
タイプ
フィールド
説明
CHAR(10)
デフォルト SQL コレ IBM i データベース・サーバーによって使
クション
用される、デフォルト SQL スキーマの名
前。実際のデフォルト SQL スキーマ名が
10 バイトより大きい場合、次の特殊値が渡
され、デフォルトの SQL スキーマ名が「拡
張デフォルト SQL スキーマ」フィールドか
ら取得される必要があることを示します。
v *EXTDSCHMA
注: 「拡張デフォルト SQL スキーマ」フィ
ールドは、長さが 10 未満であっても常に設
定されます。ユーザーは、デフォルトの
SQL スキーマ名を取得するために、常にこ
のフィールドを参照できます。
105
69
CHAR(1)
命名モード
v '0' - SQL 命名
v '1' - システム命名
106
6A
CHAR(2)
予約済み
将来使用されるパラメーターのための予約フ
ィールド
108
6C
BINARY(4)
拡張カーソル名へのオこの構造内での拡張カーソル名へのオフセッ
フセット
ト
112
70
BINARY(4)
拡張カーソル名の長さ拡張カーソル名の長さ (バイト数)
116
74
BINARY(4)
拡張デフォルト SQL この構造内での拡張デフォルト SQL スキー
スキーマへのオフセッマへのオフセット
ト
120
78
BINARY(4)
拡張デフォルト SQL
スキーマの長さ
拡張デフォルト SQL スキーマの長さ (バイ
ト数)
124
7C
CHAR(110)
予約済み
将来使用されるパラメーターのための予約フ
ィールド
234
EA
BINARY(4)
SQL ステートメント
のテキストの長さ
後に続くフィールドに入る SQL ステートメ
ント・テキストの長さ。最大で 2 MB
(2,097,152 バイト) の長さ。
238
EE
CHAR(*)
SQL ステートメント
のテキスト
SQL ステートメント全文。
*
*
CHAR(*)
拡張カーソル名
拡張カーソル名
*
*
CHAR(*)
拡張スキーマ名
拡張スキーマ名
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
出口点 QIBM_QZDA_INIT は、サーバー開始時に出口プログラムを実行するように定義されています。プ
ログラムがこの出口点を使用するように定義されている場合は、データベース・サーバーが開始されるたび
に、呼び出されます。
プログラミング
549
ZDAI0100 形式の出口点 QIBM_QZDA_INIT のパラメーター・フィールド:
ZDAI0100 形式を使用する出口点 QIBM_QZDA_INIT で呼び出される IBM i データベース出口プログラム
のパラメーター・フィールドとその説明を以下の表に示します。
表 19. ZDAI0100 形式の出口点 QIBM_QZDA_INIT
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
この出口点に対する値は *SQL です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。
QIBM_QZDA_INIT の形式名は ZDAI0100
です。
28
1C
BINARY(4)
要求された関数
実行される関数。
この出口点に対する有効な値は 0 のみで
す。
32
20
CHAR(63)
インターフェース・タサーバーを呼び出すアプリケーションから渡
イプ
されるインターフェースのタイプ。
95
5F
CHAR(127)
インターフェース名
222
DE
CHAR(63)
インターフェース・レサーバーを呼び出すアプリケーションから渡
ベル
されるインターフェースのレベル。
サーバーを呼び出すアプリケーションから渡
されるインターフェースの名前。
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
QIBM_QZDA_NDB1 出口点は、データベース・サーバーに対するネイティブ・データベース要求時に、出
口プログラムを実行するように定義されています。この出口点に対して、2 つの形式が定義されています。
ZDAD0100 形式を使用する関数
v ソース物理ファイルの作成
v 既存ファイルに基づいた、データベース・ファイルの作成
v データベース・ファイル・メンバーの追加、クリア、削除
v データベース・ファイル一時変更
v データベース・ファイル一時変更削除
v ファイルの削除
注: ZDAD0200 形式は、ライブラリー・リストに対するライブラリーの追加要求が受け取られた時に使用
されます。
ZDAD0100 形式の出口点 QIBM_QZDA_NDB1 のパラメーター・フィールド:
ZDAD0100 形式を使用する出口点 QIBM_QZDA_NDB1 で呼び出された IBM i データベース出口プログラ
ムの、パラメーター・フィールドとその説明を以下の表に示します。
550
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 20. ZDAD0100 形式の出口点 QIBM_QZDA_NDB1
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
この出口点に対する値は *NDB です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。
これ以降の関数についての形式名は
ZDAD0100 です。
28
1C
BINARY(4)
要求された
関数
実行される関数。
このフィールドの内容は、次のいずれかで
す。
v X'1800' - ソース物理ファイルの作成
v X'1801' - 既存ファイルに基づいた、デー
タベース・ファイルの作成
v X'1802' - データベース・ファイル・メン
バーの追加
v X'1803' - データベース・ファイル・メン
バーの消去
v X'1804' - データベース・ファイル・メン
バーの削除
v X'1805' - データベース・ファイル一時変
更
v X'1806' - データベース・ファイル一時変
更削除
v X'1807' - 保管ファイルの作成
v X'1808' - 保管ファイルの消去
v X'1809' - ファイルの削除
32
20
CHAR(128)
ファイル名
要求された関数に使用されるファイルの名
前。
160
A0
CHAR(10)
ライブラリー名
ファイルが含まれているライブラリーの名
前。
170
AA
CHAR(10)
メンバー名
追加、消去、削除するメンバーの名前。
180
B4
CHAR(10)
権限
作成されたファイルに対する権限。
190
BE
CHAR(128)
ファイル名による
既存ファイルに基づいてファイルを作成する
ときに使用されるファイルの名前。
318
13E
CHAR(10)
ライブラリー名による基本となるファイルを含むライブラリー名。
328
148
CHAR(10)
変更ファイル名
338
152
CHAR(10)
一時変更ライブラリー一時変更されるファイルを含むライブラリー
名
の名前。
348
15C
CHAR(10)
一時変更メンバー名
一時変更されるファイルの名前。
一時変更されるメンバーの名前。
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
プログラミング
551
ZDAD0200 形式の出口点 QIBM_QZDA_NDB1 のパラメーター・フィールド:
ZDAD0200 形式を使用して出口点 QIBM_QZDA_NDB1 で呼び出される IBM i データベース出口プログラ
ムのパラメーター・フィールドとその説明を、以下の表で紹介します。
表 21. ZDAD0200 形式の出口点 QIBM_QZDA_NDB1
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
この出口点に対する値は *NDB です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。ライブラ
リー・リストへの追加の関数の形式の名前
は、ZDAD0200 です。
28
1C
BINARY(4)
要求された関数
実行される関数。
v X'180C' - ライブラリー・リストの追加
32
20
BINARY(4)
ライブラリー数
(次のフィールドの) ライブラリーの数。
36
24
CHAR(10)
ライブラリー名
それぞれのライブラリーの名前。
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
QIBM_QZDA_SQL1 出口点は、データベース・サーバーに対する、特定の SQL 要求時に出口プログラム
を実行するために定義されています。この出口点に対しては、1 つの形式のみ定義されています。
ZDAD0200 形式を使用する関数
v 準備
v オープン
v 実行
v 接続
v パッケージの作成
v パッケージのクリア
v パッケージの削除
v 即時実行
v 準備および記述
v 準備および実行、または準備およびオープン
v オープンおよび取り出し
v 実行またはオープン
ZDAQ0100 形式の出口点 QIBM_QZDA_SQL1 のパラメーター・フィールド:
ZDAQ0100 形式を使用する出口点 QIBM_QZDA_SQL1 で呼び出される IBM i データベース出口プログラ
ムのパラメーター・フィールドとその説明を以下の表に示します。
552
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 22. ZDAQ0100 形式の出口点 QIBM_QZDA_SQL1
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
この出口点に対する値は、*SQLSRV です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。
QIBM_QZDA_SQL1 の形式名は ZDAQ0100
です。
28
1C
BINARY(4)
要求された
関数
実行される関数。
このフィールドの内容は、次のいずれかで
す。
v X'1800' - 準備
v X'1803' - 準備および記述
v X'1804' - オープン / 記述
v X'1805' - 実行
v X'1806' - 即時実行
v X'1809' - 接続
v X'180D' - 準備および実行、または準備お
よびオープン
v X'180E' - オープンおよび取り出し
v X'180F' - パッケージの作成
v X'1810' - パッケージのクリア
v X'1811' - パッケージの削除
v X'1812' - 実行またはオープン
v X'1815' - パッケージ情報の戻し
32
20
CHAR(18)
ステートメント名
準備関数や実行関数に使用するステートメン
トの名前。
50
32
CHAR(18)
カーソル名
オープン関数に使用されるカーソル名。
68
44
CHAR(2)
準備オプション
準備関数に使用されるオプション。
70
46
CHAR(2)
オープン属性
オープン関数に使用されるオプション。
72
48
CHAR(10)
拡張動的パッケージ名拡張動的 SQL パッケージの名前。
82
52
CHAR(10)
パッケージ・ライブラ拡張動的 SQL パッケージ用ライブラリー
の名前。
リー名
92
5C
BINARY(2)
DRDA インディケー
ター
94
5E
CHAR(1)
v 0 - ローカル RDB に接続
v 1 - リモート RDB に接続
コミットメント制御レ v 'A' - コミット *ALL
ベル
v 'C' - コミット *CHANGE
v 'N' - コミット *NONE
v 'S' - コミット *CS (カーソル固定性)
95
5F
CHAR(512)
SQL ステートメント
のテキストの最初の
512 バイト
SQL ステートメントの最初の 512 バイト。
プログラミング
553
表 22. ZDAQ0100 形式の出口点 QIBM_QZDA_SQL1 (続き)
オフセット
10 進
16 進
タイプ
フィールド
説明
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
QIBM_QZDA_ROI1 出口点は、データベース・サーバーに対する特定のオブジェクト情報の取り出し要求
時に出口プログラムを実行するように定義されています。また、この出口点は SQL カタログ関数にも使用
されています。
この出口点には、2 つの形式が定義されています。
ZDAR0100 形式は、次のオブジェクトの情報を取り出す際に使用されます。
v フィールド (または、列)
v ファイル (または、テーブル)
v ファイル・メンバー
v インデックス
v ライブラリー (または、コレクション)
v レコード様式
v リレーショナル・データベース (RDB)
v 特殊列
v SQL パッケージ
v SQL パッケージ・ステートメント
ZDAR0200 形式は、次のオブジェクトの情報を取り出す際に使用されます。
v 外部キー
v 基本キー
ZDAR0100 形式の出口点 QIBM_QZDA_ROI1 のパラメーター・フィールド:
ZDAR0100 形式を使用する出口点 QIBM_QZDA_ROI1 で呼び出された IBM i データベース出口プログラ
ムの、パラメーター・フィールドとその説明を以下の表に示します。
表 23. ZDAR0100 形式の出口点 QIBM_QZDA_ROI1
オフセット
10 進
16 進
0
554
タイプ
フィールド
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
データベース・サーバーに対する値は、
*RTVOBJINF です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。これ以降
の関数についての形式名は ZDAR0100 で
す。
IBM i: Windows アプリケーション・パッケージ: プログラミング
説明
表 23. ZDAR0100 形式の出口点 QIBM_QZDA_ROI1 (続き)
オフセット
10 進
16 進
28
1C
タイプ
フィールド
説明
BINARY(4)
要求された
関数
実行される関数。
このフィールドの内容は、次のいずれかで
す。
v X'1800' - ライブラリー情報の取り出し
v X'1801' - リレーショナル・データベース
情報の取り出し
v X'1802' - SQL パッケージ情報の取り出
し
v X'1803' - SQL パッケージのステートメ
ント情報の取り出し
v X'1804' - ファイル情報の取り出し
v X'1805' - ファイル・メンバー情報の取り
出し
v X'1806' - レコード様式情報の取り出し
v X'1807' - フィールド情報の取り出し
v X'1808' - インデックス情報の取り出し
v X'180B' - 特殊列情報の取り出し
32
20
CHAR(20)
スキーマ名
スキーマ、パッケージ、パッケージ・ステー
トメント、ファイル、メンバー、レコード様
式、フィールド、インデックス、および特殊
列の情報を取り出すときに使用されるスキー
マや検索パターン。スキーマ名の長さまたは
検索パターンの長さが 20 より大きい場合、
次の特殊値が渡され、スキーマ名が「拡張ス
キーマ名」フィールドから取得される必要が
あることを示します。
v *EXTDSCHMA
注: 「拡張スキーマ名」フィールドは、長さ
が 20 未満であっても常に設定されます。ユ
ーザーは、スキーマ名を取得するために、常
にこのフィールドを参照できます。
52
34
CHAR(36)
リレーショナル・デー RDB の情報を取り出すのに使用されるリレ
タベース名
ーショナル・データベース名や検索パター
ン。
88
58
CHAR(20)
パッケージ名
パッケージまたはパッケージ・ステートメン
ト情報を取り出すために使用されるパッケー
ジ名や検索パターン。
108
6C
CHAR(256)
ファイル名 (SQL エ
イリアス名)
ファイル、メンバー、レコード様式、フィー
ルド、インデックス、または特殊列情報を取
り出すために使用されるファイル名やサーチ
検索パターン。
364
16C
CHAR(20)
メンバー名
ファイル・メンバー情報を取り出すために使
用される、メンバー名や検索パターン。
プログラミング
555
表 23. ZDAR0100 形式の出口点 QIBM_QZDA_ROI1 (続き)
オフセット
10 進
16 進
タイプ
フィールド
説明
384
180
CHAR(20)
形式名
レコード様式情報を取り出すために使用され
るフォーマット名や検索パターン。
404
194
CHAR(256)
拡張スキーマ名
使用される拡張スキーマ名または検索パター
ン。
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
ZDAR0200 形式の出口点 QIBM_QZDA_ROI1 のパラメーター・フィールド:
ZDAR0200 形式を使用する出口点 QIBM_QZDA_ROI1 で呼び出された IBM i データベース出口プログラ
ムの、パラメーター・フィールドとその説明を以下の表に示します。
表 24. ZDAR0200 形式の出口点 QIBM_QZDA_ROI1
オフセット
10 進
16 進
タイプ
フィールド
0
説明
0
CHAR(10)
ユーザー・プロファイサーバーを呼び出すユーザー・プロファイル
ル名
の名前。
10
A
CHAR(10)
サーバー識別コード
データベース・サーバーに対する値は、
*RTVOBJINF です。
20
14
CHAR(8)
形式名
使用されるユーザー出口の形式名。これ以降
の関数についての形式名は ZDAR0200 で
す。
28
1C
BINARY(4)
要求された関数
実行される関数。
このフィールドの内容は、次のいずれかで
す。
v X'1809' - 外部キー情報の取り出し
v X'180A' - 基本キー情報の取り出し
32
20
CHAR(10)
基本キー・テーブルの基本キーや外部キーの情報を取り出す際に使
スキーマ名
用する基本キー・テーブルが含まれているス
キーマ名。名前が 10 バイトより大きい場
合、次の特殊値が渡され、基本キー・テーブ
ルのスキーマ名が「基本キー・テーブルの拡
張スキーマ名」フィールドから取得される必
要があることを示します。
v *EXTDSCHMA
注: 「基本キー・テーブルの拡張スキーマ
名」フィールドは、長さが 10 未満であって
も常に設定されます。ユーザーは、スキーマ
名を取得するために、常にこのフィールドを
参照できます。
42
556
2A
CHAR(128)
基本キー・テーブル名基本キー、または外部キーの情報を取り出す
(エイリアス名)
際に使用する基本キーが含まれているテーブ
ル名。
IBM i: Windows アプリケーション・パッケージ: プログラミング
表 24. ZDAR0200 形式の出口点 QIBM_QZDA_ROI1 (続き)
オフセット
10 進
16 進
170
AA
タイプ
フィールド
説明
CHAR(10)
外部キー・テーブル・外部キーの情報を取り出す際に使用する外部
スキーマ名
キー・テーブルが含まれるスキーマ名。名前
が 10 バイトより大きい場合、次の特殊値が
渡され、外部キー・テーブルのスキーマ名が
「外部キー・テーブルの拡張スキーマ名」フ
ィールドから取得される必要があることを示
します。
v *EXTDSCHMA
注: 「外部キー・テーブルの拡張スキーマ
名」フィールドは、長さが 10 未満であって
も常に設定されます。ユーザーは、スキーマ
名を取得するために、常にこのフィールドを
参照できます。
180
64
CHAR(128)
外部キー・テーブル名外部キーの情報を取り出す際に使用する外部
(エイリアス名)
キーが含まれているテーブル名。
308
134
CHAR(128)
基本キー・テーブルの基本キーの情報を取り出す際に使用する基本
拡張スキーマ名
キー・テーブルが含まれているスキーマ名。
436
1B4
CHAR(128)
外部キー・テーブルの外部キー情報を検索するときに使用する外部
拡張・スキーマ名
キー・テーブルが入っているスキーマの名
前。
注: この形式は、ライブラリー QSYSINC にある、ファイル H のメンバー EZDAEP、QRPGSRC、QRPGLESRC、
QCBLSRC および QCBLLESRC によって定義されています。
SQL および外部プロシージャー:
SQL および外部プロシージャーは、データベース・アクセスのために IBM i でサポートされています。
プロシージャーは、一般に、SQL CALL ステートメントを使用して実行できる任意のプログラムです。プ
ロシージャーは、パフォーマンス、トランザクションの保全性、およびセキュリティーを高めることから、
クライアント/サーバー・アプリケーション、特にオンライン・トランザクション処理 (OLTP) の分野で、
ごく一般的に使用されています。 DB2 for i では、プロシージャーは、SQL プロシージャー型言語または
いくつかの外部プログラミング言語 (例: ILE RPG または ILE COBOL) で作成できます。これらのプロシ
ージャーの例で使用されている特定の SQL ステートメントについての情報は、IBM i Information Center
にある『DB2 for i の SQL 解説書』のトピック集を参照してください。
次の図では、1 つのトランザクションが 4 つの別々の I/O オペレーションから構成され、そのそれぞれが
SQL ステートメントの処理を要求しているアプリケーションを示しています。この図で示しているよう
に、このアプリケーションでは、サーバーとクライアントとの間で少なくとも 8 つのメッセージのやりと
りが必要とされます。これによって、特に、通信速度が遅い場合 (例えば、ダイヤル呼び出し回線を介する
場合) あるいは、接続のターンアラウンド・タイムが遅い場合 (例えば、サテライト・リンクを介する場合)
に、かなりのオーバーヘッドが発生する可能性があります。
プログラミング
557
(り*の+,
(り*
(り*-.の+,
(り*
-.
/012の+,
/0
12
34の+,
34
クライアント・
アプリケーション
サーバー
ストアード・プロシージャーを
BCしないクライアント/サーバー・アプリケーション
RV3W347-0
図 4. ストアード・プロシージャーを使用しないクライアント/サーバー・アプリケーション
次の図は、同じトランザクションをサーバー上のストアード・プロシージャーによって実行したものです。
この図で示されているように、通信量は、一対のメッセージにまで減少されています。このほかにも、利点
はあります。例えば、プロシージャーでは、絶対に必要なデータ (長い列からの数個の文字) のみを送り返
すように調整することも可能です。ストアード・プロシージャー用の DB2 for i は、任意の IBM i プログ
ラムにすることが可能で、データ・アクセスに SQL を使用する必要はありません。
HI
SQLExecDirect ('Call Ordentry
(:CUSTNUM, :INVNO, :ITEM1,
:QTY1, :ITEM2, :QTY2)',
SQL_NTS);
(り*の+,
(り*
(り*-.の
+,
(り*
-.
/012の
+,
/0
12
34の
+,
34
クライアント・
アプリケーション
サーバー
ストアード・プロシージャーを
BCしたクライアント/サーバー・アプリケーション
RV3W348-0
図 5. ストアード・プロシージャーを使用したクライアント/サーバー・アプリケーション
関連資料:
558
IBM i: Windows アプリケーション・パッケージ: プログラミング
566 ページの『ODBC プログラム例』
IBM i Access の照会およびストアード・プロシージャーについて、ODBC のプログラミング例を使って説
明します。
関連情報:
DB2 for i SQL リファレンス
プロシージャーの結果セット:
IBM i SQL プロシージャーの結果セットをスクロールできます。
アプリケーションには、SQL CALL ステートメントを使用して実行されたプロシージャーから、スクロー
ル可能な結果セットが戻される場合があります。このサポートを活用するには、以下の 2 つの変更を行っ
てください。
1. スクロール可能として定義されたカーソルを持つプロシージャーを作成します。
a. これは、プロシージャー定義内部でカーソル宣言に SCROLL キーワードを追加することで実行でき
ます。以下の 2 つの例では、ストアード・プロシージャーはスクロール可能結果セットを戻します
が、2 つ目は戻しません。
v CREATE PROCEDURE MYLIB.SCROLLSP ( ) RESULT SETS 1 LANGUAGE SQL
sqlproc: begin
DECLARE CUR1 SCROLL CURSOR FOR
SELECT * FROM QIWS.QCUSTCDT;
OPEN CUR1;
SET RESULT SETS CURSOR CUR1;
end
v CREATE PROCEDURE MYLIB.NOSCROLLSP ( ) RESULT SETS 1 LANGUAGE SQL
sqlproc: begin
DECLARE CUR1 CURSOR FOR
SELECT * FROM QIWS.QCUSTCDT;
OPEN CUR1;
SET RESULT SETS CURSOR CUR1;
end
2. ODBC を使用してアプリケーションをコード化し、両方向スクロール・カーソル・タイプを要求しま
す。
a. SQLSetStmtAttr API を呼び出します。
b. SQL_ATTR_CURSOR_TYPE オプションを SQL_CURSOR_DYNAMIC に設定します。
両方向スクロール・カーソルを指定していないプロシージャーを使用して逆方向へのスクロールが試
行された場合、複数の問題が発生する可能性があります。ほとんどの場合では、スクロールが無効で
あることを示すエラーがサーバーから戻されますが、誤ったデータが戻される場合もあります。
プロシージャーが複数の結果セットを戻す場合でも、単一のカーソル・タイプのみを使用することが
できます。 2 つ目の結果セット用に異なるカーソル・タイプが指定されている場合、ODBC はエラ
ーを戻すか、そのカーソル・タイプを無視します。スクロール可能結果セットを結果セットの 1 つ
として使用するには、上記のように、アプリケーションでそのカーソル・タイプをスクロール可能に
設定する必要があります。
結果セット・カーソルを更新可能カーソルとして使用しようとすると、エラーが戻されるか、無視さ
れます。プロシージャーの結果セットは、読み取り専用です。
プロシージャーの実行時にカーソルが開かれていたため、カーソル・センシティビティーは、プロシ
ージャーの結果セットでは保持されない場合があります。カーソル・センシティビティーは、プロシ
ージャーの作成時にカーソルが定義された方法で制御されます。
プログラミング
559
例: ストアード・プロシージャー:
DB2 for IBM i プロシージャーの例は、以下を参照してください。
例: SQL ストアード・プロシージャーと ODBC による CL コマンドの実行:
ストアード・プロシージャー・サポートは、SQL の CALL ステートメントを使用して IBM i 制御言語
(CL) コマンドを実行する手段を提供します。
以下の状況で、CL コマンドを使用することができます。
v ファイルに対する一時変更を行う場合
v デバッグを開始するとき
v 他のコマンドを使用することによって、それに続く SQL ステートメントのパフォーマンスに影響を与え
ることができる場合
v アプリケーションに他の環境セットアップを行う場合
CL コマンドを実行するためのプログラムを SQL から呼び出す CALL ステートメントを使用して、IBM i
CL コマンドを実行するケースを、以下の例で説明します。このプログラム (ライブラリー QSYS2 の
QCMDEXC) には以下の 2 つのパラメーターがあります。
1. 実行するコマンド・テキストを含むストリング
2. コマンド・テキスト長を示す整数
コマンドを正確に解釈させるために、必ずこれらの属性をパラメーターに含めます。
以下の例は、PC 上の C のプログラムが 65 文字 (組み込みブランクを含む) の OVRDBF コマンドを実行
しているものです。 OVRDBF コマンドのテキストは以下のとおりです。
OVRDBF FILE(TESTER) TOFILE(JMBLIB/TESTER) MBR(NO2) OVRSCOPE(*JOB)
ODBC の API を使用して、このコマンドを実行する場合のコードは、以下のとおりです。
HSTMT hstmt;
SQLCHAR stmt[301];
rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
strcpy(stmt,"CALL QSYS2.QCMDEXC(’OVRDBF FILE(TESTER) TOFILE(MYLIB/");
strcat(stmt,"TESTER) MBR(NO2) OVRSCOPE(*JOB)’,64)");
rc = SQLExecDirect(hstmt, stmt, SQL_NTS);
これで、MYLIB/TESTER ファイルに対して実行されるステートメントは、最初のメンバーではなく、NO2
のメンバーを参照するようになります。
データベース・サーバー・ジョブに対して実行できる有用な CL コマンドには他に STRDBG コマンドがあ
ります。ただし、このコマンドを呼び出すためにストアード・プロシージャーを呼び出す必要はありませ
ん。 DSN セットアップ GUI の「診断」タブには、接続試行時に STRDBG コマンドを自動的に実行するオ
プションがあります。
関連概念:
475 ページの『IBM i Access ODBC ドライバーに固有の詳細』
IBM i Access ODBC API を使用したインプリメンテーション時の問題について確認します。
560
IBM i: Windows アプリケーション・パッケージ: プログラミング
例: Visual Basic からの、戻り値を伴うストアード・プロシージャーの呼び出し:
DB2 for IBM i のプロシージャーを呼び出して、Visual Basic 変数に戻り値を取り込む方法について、以
下の Visual Basic ソース・コードの例で説明します。
Visual Basic は、DLL の中にある外部関数を呼び出すことができます。すべての ODBC ドライバーは、
DLL であるため、Visual Basic を使用して、ODBC API を直接コーディングすることができます。 ODBC
API に直接コーディングすることによって、Visual Basic アプリケーションで、 DB2 for IBM i のプロシ
ージャーを呼び出し、結果値を戻すことができます。
’***********************************************************************
’*
*
’* Because of the way Visual Basic stores and manages the String data *
’* type, it is recommended that you use an array of Byte data type
*
’* instead of a String variable on the SQLBindParameter API.
*
’*
*
’***********************************************************************
Dim sTemp As String
Custnum As Integer
Dim abCustname(34) As Byte
Dim abAddress(34) As Byte
Dim abCity(24) As Byte
Dim abState(1) As Byte
Dim abPhone(14) As Byte
Dim abStatus As Byte
Dim RC As Integer
Dim nullx As Long
’Used
Dim lpSQL_NTS As Long
’Used
Static link(7) As Long
’Used
’each
to pass null pointer, not pointer to null
to pass far pointer to SQL_NTS
as an array of long pointers to the size
parameter which will be bound
’***********************************************************************
’*
*
’* Initialize the variables needed on the API calls
*
’*
*
’***********************************************************************
link(1)
link(2)
link(3)
link(4)
link(5)
link(6)
link(7)
=
=
=
=
=
=
=
6
Ubound(abCustname) +1
Ubound(abAddress) +1
Ubound(abCity) +1
Ubound(abState) +1
Ubound(abPhone) +1
1
RC = 0
nullx = 0
lpSQL_NTS = SQL_NTS
’ -3 means passed as sz string
’***********************************************************************
’*
*
’* Create an IBM i procedure. This will define the
*
’* procedure’s name, parameters, and how each parameter is passed.
*
’* Note: This information is stored in the server catalog tables and
*
’* and only needs to be executed one time for the life of the stored
*
’* procedure. It normally would not be run in the client application. *
’*
*
’***********************************************************************
sTemp
sTemp
sTemp
sTemp
=
=
=
=
"Create
sTemp &
sTemp &
sTemp &
Procedure Storedp2 (:Custnum in integer, "
":Custname out char(35), :Address out char(35),"
":City out char(25), :State out char(2),"
":Phone out char(15), :Status out char(1))
プログラミング
561
sTemp = sTemp & "(External name rastest.storedp2 language cobol General)"
RC = SQLExecDirect(Connection.hstmt, sTemp, Len(sTemp))
’Ignore error assuming that any error would be from procedure already
’created.
’***********************************************************************
’*
*
’* Prepare the call of the procedure to the system.
*
’* For best performance, prepare the statement only one time and
*
’* execute many times.
*
’*
*
’***********************************************************************
sTemp = "Call storedp2(?, ?, ?, ?, ?, ?, ?)"
RC = SQLPrepare(Connection.hstmt, sTemp, Len(sTemp))
If (RC <> SQL_SUCCESS) Then
DescribeError Connection.hdbc, Connection.hstmt
frmMain.Status.Caption = "Error on SQL_Prepare " & RTrim$(Tag)
End If
’***********************************************************************
’*
*
’* Bind all of the columns passed to the procedure. This will
*
’* set up the variable’s data type, input/output characteristics,
*
’* length, and initial value.
*
’* The SQLDescribeParam API can optionally be used to retrieve the
*
’* parameter types.
*
’*
*
’* To properly pass an array of byte to a stored procedure and receive *
’* an output value back, you must pass the first byte ByRef.
*
’*
*
’***********************************************************************
RC = SQLBindParameter(Connection.hstmt, 1, SQL_PARAM_INPUT, SQL_C_SHORT, _
SQL_NUMERIC, 6, 0, Custnum, 6, link(1))
RC = SQLBindParameter(Connection.hstmt, 2, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 35, 0, abCustname(0), UBound(abCustname)+1, link(2))
RC = SQLBindParameter(Connection.hstmt, 3, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 35, 0, abAddress(0), UBound(abAddress)+1, link(3))
RC = SQLBindParameter(Connection.hstmt, 4, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 25, 0, abCity(0), UBound(abCity)+1, link(4))
RC = SQLBindParameter(Connection.hstmt, 5, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 2, 0, abState(0), UBound(abState)+1, link(5))
RC = SQLBindParameter(Connection.hstmt, 6, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 15, 0, abPhone(0), UBound(abPhone)+1, link(6))
RC = SQLBindParameter(Connection.hstmt, 7, SQL_PARAM_OUTPUT, SQL_C_CHAR,
SQL_CHAR, 1, 0, abStatus, 1, link(7))
’***********************************************************************
’*
*
’* The Prepare and Bind only needs to be execute once. The Stored
*
’* procedure can now be called multiple times
*
’*
*
’***********************************************************************
Do While
’***********************************************************************
’* Read in a customer number
*
’*
*
’***********************************************************************
562
IBM i: Windows アプリケーション・パッケージ: プログラミング
_
_
_
_
_
_
Custnum = Val(input.text)
’***********************************************************************
’*
*
’* Execute the call of the procedure to the system.
*
’*
*
’***********************************************************************
RC = SQLExecute(Connection.hstmt)
frmMain.Status.Caption = "Ran Stored Proc" & RTrim$(Tag)
If (RC <> SQL_SUCCESS) Then
DescribeError Connection.hdbc, Connection.hstmt
frmMain.Status.Caption = "Error on Stored Proc Execute " & RTrim$(Tag
End If
’***********************************************************************
’*
*
’* Set text labels to display the output data
*
’* You must convert the array of Byte back to a String
*
’*
*
’***********************************************************************
lblCustname = StrConv(abCustname(), vbUnicode)
lblAddress = StrConv(abAddress(), vbUnicode)
lblCity = StrConv(abCity(), vbUnicode)
lblState = StrConv(abState(), vbUnicode)
lblPhone = StrConv(abPhone(), vbUnicode)
lblStatus = StrConv(abStatus(), vbUnicode)
Loop
例: Visual Basic を使用した IBM i ストアード・プロシージャーの呼び出し:
以下の Visual Basic プログラミングは、準備される IBM i プロシージャー呼び出しの例です。
以下の 2 つのステートメントが示されています。
1. プロシージャー作成のためのステートメント
2. 呼び出しの準備のためのステートメント
プロシージャーを、1 回のみ作成します。ODBC アプリケーションでも、そのストアード・プロシージャ
ーが提供する定義を利用することができます。
Visual Basic が String データ・タイプを保管して、管理する方法を考えると、次のパラメーター・タイプ
に対しては、String 変数ではなく Byte データ・タイプの配列を使用することをお勧めします。
v 入出力パラメーター
v 出力パラメーター
v 2 進データを含む (標準 ANSI 文字ではなく) 任意のパラメーター
v 設定は 1 回であるが、複数回参照される可変のアドレスを持つ任意の入力パラメーター
最後のケースは、アプリケーションが、それぞれの呼び出しの間に Parm1 を変更しながら SQLExecute
への呼び出しを何度も行う場合に該当します。以下の Visual Basic 関数は、バイトのストリングと配列の
変換の際に役立ちます。
プログラミング
563
Public Sub Byte2String(InByte() As Byte, OutString As String)
’Convert array of byte to string
OutString = StrConv(InByte(), vbUnicode)
End Sub
Public Function String2Byte(InString As String, OutByte() As Byte) As Boolean
’vb byte-array / string coercion assumes Unicode string
’so must convert String to Byte one character at a time
’or by direct memory access
’This function assumes Lower Bound of array is 0
Dim I As Integer
Dim SizeOutByte As Integer
Dim SizeInString As Integer
SizeOutByte = UBound(OutByte) + 1
SizeInString = Len(InString)
’Verify sizes if desired
’Convert the string
For I = 0 To SizeInString - 1
OutByte(I) = AscB(Mid(InString, I + 1, 1))
Next I
’If size byte array > len of string pad with Nulls for szString
If SizeOutByte > SizeInString Then
’Pad with Nulls
For I = SizeInString To UBound(OutByte)
OutByte(I) = 0
Next I
End If
String2Byte = True
End Function
Public Sub ViewByteArray(Data() As Byte, Title As String)
’Display message box showing hex values of byte array
Dim S As String
Dim I As Integer
On Error GoTo VBANext
S = "Length: " & Str(UBound(Data) - LBound(Data) + 1) & " Data (in hex):"
For I = LBound(Data) To UBound(Data)
If (I Mod 8) = 0 Then
S = S & " "
’add extra space every 8th byte
End If
S = S & Hex(Data(I)) & " "
VBANext:
Next I
MsgBox S, , Title
End Sub
例: SQL CALL ステートメントを使用した CL コマンドの呼び出し:
SQL CALL ステートメントを使用することによって、IBM i コマンドを実行することが可能です。ここに
記されている 2 つの例は、ODBC プログラムに適用されます。
コマンドを実行するには、コマンド実行 (QCMDEXC) を呼び出すだけです。このプロセスは簡単です。コマ
ンド・ストリングとコマンド・ストリングの長さを CALL ステートメントのパラメーターとして提供する
だけです。リモート・コマンド API も代替として使用することができます。
最初の例では、SQL を実行しているジョブ (この例の場合は、サーバー・ジョブ) のジョブ・ログにデー
タを書き込む、強力な SQL トレース機能を使えるようにします。
564
IBM i: Windows アプリケーション・パッケージ: プログラミング
2 番目の例では、マルチ・メンバー・ファイルの最初のメンバー以外のメンバーに、SQL を使用してアク
セスすることができます。CREATE TABLE コマンドでは、通常マルチ・メンバー・ファイルを作成する
ことはできません。しかし、次の例では、DDS で作成したマルチ・メンバー・ファイルの最初のメンバー
以外のメンバーにアクセスする方法が示されています。
Dim hStmt
As Long
rc = SQLAllocHandle(SQL_HANDLE_STMT, ghDbc, hStmt)
If rc <> SQL_SUCCESS Then
Call DspSQLError(SQL_HANDLE_DBC, ghDbc, "Problem: Allocating Debug Statement Handle")
End If
’ Note that the string within single quotes ’STRDBG UPDPROD(*YES)’ is exactly 20 bytes
cmd = "call qsys2.qcmdexc(’STRDBG UPDPROD(*YES)’,20)"
’ Put the system job in debug mode
rc = SQLExecDirect(hStmt, cmd, SQL_NTS)
If rc <> SQL_SUCCESS Then
Call DspSQLError(SQL_HANDLE_STMT, hStmt, "Problem: Start Debug")
End If
rc = SQLAllocHandle(SQL_HANDLE_STMT, ghDbc, ovrhstmt)
If rc <> SQL_SUCCESS Then
Call DspSQLError(SQL_HANDLE_DBC, ghDbc, "Problem: Allocating Override Statement Handle")
End If
’ Note that the string within single quotes ’OVRDBF FILE(BRANCH)... OVRSCOPE(*JOB)’
is exactly 68 bytes
cmd = "call qsys.qcmdexc(’OVRDBF FILE(BRANCH) TOFILE(HOALIB/BRANCH) MBR(FRANCE)
OVRSCOPE(*JOB)’,68)"
’ Override the IBM i file to point to the ’france’ member
rc = SQLExecDirect(hStmt, cmd, SQL_NTS)
If rc <> SQL_SUCCESS Then
Call DspSQLError(SQL_HANDLE_STMT, hStmt, "File Override")
End If
ヒント: IBM i プロシージャーの実行と呼び出し:
DB2 for IBM i プロシージャーの実行と呼び出しに関するヒントです。
IBM i プロシージャーの実行
ODBC は、データベース・プロシージャーを呼び出す標準インターフェースを提供しています。データベ
ース・プロシージャーの実施方法は、データベースによって大きく異なってきます。 IBM i プロシージャ
ーの実行方法における推奨例を、この簡単な例で説明します。
1. プロシージャー作成ステートメントをストアード・プロシージャー用に設定し、プロシージャーを作成
します。プロシージャーの作成によりプロシージャーが定義され、この作成は 1 回のみ行う必要があり
ます。 ODBC アプリケーションを含めて、データベースに対して実行されるすべてのアプリケーショ
ンから、そのプロシージャーが提供する定義を利用することができます。
2. プロシージャーを呼び出すための CALL ステートメントを作成します。
3. それぞれのパラメーターが、プロシージャーへの入力に使用されるのか、プロシージャーからの出力に
使用されるのか、または入出力のいずれに使用されるのかを示して、プロシージャーのパラメーターを
バインドします。
4. プロシージャーを呼び出します。
プログラミング
565
Visual Basic を使用した IBM i プロシージャーの呼び出し
SQLBindParameter 関数をコーディングする際には注意してください。列 (SQLBindCol) またはパラメー
ター (SQLBindParameter) をバインドしている場合は、Visual Basic ストリングをバッファーとして使用
しないでください。代わりに、バイト配列を使用してください。バイト配列は、ストリングとは異なり、メ
モリー内を移動しません。詳しくは、 563 ページの『例: Visual Basic を使用した IBM i ストアード・プ
ロシージャーの呼び出し』を参照してください。
使用するデータ・タイプには、特に注意してください。使用されるデータ・タイプ、例えばユーザーが選択
ステートメントに使用するデータ・タイプには微妙な相違がある場合があります。また、出力と入出力パラ
メーター用に適当なサイズのバッファーが確保できていることを確認する必要があります。IBM i プロシ
ージャーのコーディング方法によっては、パフォーマンスに大きな影響を与える可能性があります。可能な
限り、C 言語の exit()、RPG の SETON LR を使用してのプログラムのクローズは行わないようにしてく
ださい。可能であれば、RETRN または return を使用してください。ただし、これを行うと、呼び出しの
たびに変数を再度初期設定して、ファイル・オープンをバイパスしなければならなくなる場合もあります。
ODBC プログラム例
IBM i Access の照会およびストアード・プロシージャーについて、ODBC のプログラミング例を使って説
明します。
以下の IBM i Access ODBC プログラミング例では、簡単な照会を実行する方法と、ストアード・プロシ
ージャーを呼び出して、データへのアクセスやデータの戻しを行う方法を説明しています。 C/C++、Visual
Basic、および RPG の各プログラム言語のバージョンが提供されています。
C/C++ サンプルの多くは完全なプログラムではありません。詳しい説明とプログラミング例については、
以下の情報を確認してください。
v ODBC プログラミング例 (Visual Basic、C++、および Lotus Script のプログラミング環境用) にアクセ
スするには、Web 上にある IBM ftp サイトへの関連リンク (以下参照) を選択してください。使用可能
なプログラミング例を調べ、PC にダウンロードするには、index.txt を選択してください。
v ストアード・プロシージャーの説明、およびその呼び出し方法の例については、IBM i Information
Center にある『ストアード・プロシージャー』のトピック集を参照してください。
v Visual Basic、ADO、および C/C++ の例については、Microsoft の MSDN ライブラリーまたは ODBC
の Web ページで、ODBC サンプルを検索してください。
v Programmer's Toolkit の C プログラミングの例も参照してください。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
関連資料:
557 ページの『SQL および外部プロシージャー』
SQL および外部プロシージャーは、データベース・アクセスのために IBM i でサポートされています。
関連情報:
IBM FTP サイト
MSDN ライブラリー
例: Visual C++ - プロシージャーの呼び出しによるデータへのアクセスと戻し:
Visual C++ を使用して DB2 for IBM i のストアード・プロシージャーを呼び出し、データにアクセスし
て、そのデータを戻す方法を、この例で説明します。
566
IBM i: Windows アプリケーション・パッケージ: プログラミング
この例では、プロシージャー呼び出しに関連したコードのみが含まれています。このコードでは、接続が既
に確立されていることを前提としています。プロシージャーのソース・コードについては、トピック『例:
RPG- ODBC プロシージャーのホスト・コード』を参照してください。
プロシージャーの作成
//* Drop the old Procedure
strcpy(szDropProc,"drop procedure apilib.partqry2");
rc = SQLExecDirect(m_hstmt, (unsigned char *)szDropProc, SQL_NTS);
// This statement is used to create a procedure
// Unless the
// procedure is destroyed, this statement need never be run again
strcpy(szCreateProc,"CREATE PROCEDURE APILIB.PARTQRY2 (INOUT P1 INTEGER," );
strcat(szCreateProc,"INOUT P2 INTEGER)");
strcat(szCreateProc,"EXTERNAL NAME APILIB.SPROC2 LANGUAGE RPG GENERAL")
//’ Create the new Procedure
rc = SQLExecDirect(m_hstmt, (unsigned char *)szCreateProc, SQL_NTS);
if (rc != SQL_SUCCESS &&; rc != SQL_SUCCESS_WITH_INFO) {
DspSQLError(m_henv, m_hdbc, SQL_NULL_HSTMT);
return APIS_INIT_ERROR;
}
if(rc != SQL_SUCCESS) {
DspSQLError(m_henv, m_hdbc, SQL_NULL_HSTMT);
return APIS_INIT_ERROR;
}
プロシージャーを呼び出すためのステートメントの作成
// Prepare the procedure call
strcpy(szStoredProc, "call partqry2(?, ?)");
// Prepare the CALL statement
rc = SQLPrepare(m_hstmt, (unsigned char *) szStoredProc, strlen(szStoredProc));
if(rc != SQL_SUCCESS &&; rc != SQL_SUCCESS_WITH_INFO) {
DspSQLError(m_henv, m_hdbc, m_hstmt);
return APIS_INIT_ERROR;
}
パラメーターのバインド
// Bind the parameters for the procedure
rc = SQLBindParameter(m_hstmt, 1, SQL_PARAM_INPUT_OUTPUT, SQL_C_LONG,
SQL_INTEGER, sizeof(m_lOption), 0, &m_lOption, sizeof(m_lOption), &lcbon),
&lcbOption);
rc |= SQLBindParameter(m_hstmt, 2, SQL_PARAM_INPUT_OUTPUT, SQL_C_LONG,
SQL_INTEGER, sizeof(m_lPartNo), 0, &m_lPartNo, sizeof(m_lPartNo), &lcbon),
&lcbOption);
// Bind the Columns
rc = SQLBindCol(m_hstmt, 1, SQL_C_SLONG, &m_lSPartNo,
sizeof(m_lSPartNo), &lcbBuffer);
rc |= SQLBindCol(m_hstmt, 2, SQL_C_CHAR, &m_szSPartDesc,
26, &lcbBuffer);
rc |= SQLBindCol(m_hstmt, 3, SQL_C_SLONG, &m_lSPartQty,
sizeof(m_lSPartQty), &lcbBuffer);
rc |= SQLBindCol(m_hstmt, 4, SQL_C_DOUBLE, &m_dSPartPrice,
sizeof(m_dSPartPrice), &lcbBuffer);
rc |= SQLBindCol(m_hstmt, 5, SQL_C_DATE, &m_dsSPartDate,
10, &lcbBuffer);
プログラミング
567
プロシージャーの呼び出し
// Request a single record
m_lOption = ONE_RECORD;
m_lPartNo = PartNo;
// Run the procedure
rc = SQLExecute(m_hstmt);
if (rc != SQL_SUCCESS) {
DspSQLError(m_henv, m_hdbc, m_hstmt);
return APIS_SEND_ERROR;
}
// (Try to) fetch a record
rc = SQLFetch(m_hstmt);
if (rc == SQL_NO_DATA_FOUND) {
// Close the cursor for repeated processing
rc = SQLCloseCursor(m_hstmt);
return APIS_PART_NOT_FOUND;
}
else if (rc != SQL_SUCCESS) {
DspSQLError(m_henv, m_hdbc, m_hstmt);
return APIS_RECEIVE_ERROR;
}
// If we are still here we have some data, so map it back
// Format and display the data
.
.
.
例: Visual Basic - プロシージャーの呼び出しによるデータへのアクセスと戻し:
DB2 for IBM i のプロシージャーの作成、準備、バインド、および呼び出しについて、Visual Basic の例
を使って説明します。
Visual Basic は、DLL の中にある外部関数を呼び出すことができます。 ODBC ドライバーはすべて DLL
であるため、プロシージャーを呼び出して結果値および結果セットを戻すように、Visual Basic アプリケー
ションで ODBC API に直接コーディングすることができます。詳しくは、トピック『ODBC API への直
接コーディング』を参照してください。プロシージャーのソース・コードについては、トピック『例:
RPG- ODBC プロシージャーのホスト・コード』を参照してください。
プロシージャーの作成
’ This statement will drop an existing procedure
szDropProc = "drop procedure apilib.partqry2"
’* This statement is used to create a procedure
’* Unless the
’* procedure is destroyed, this statement need never be run again
szCreateProc = "CREATE PROCEDURE APILIB.PARTQRY2 (INOUT P1 INTEGER,"
szCreateProc = szCreateProc & "INOUT P2 INTEGER)"
szCreateProc = szCreateProc & "EXTERNAL NAME APILIB.SPROC2 LANGUAGE RPG GENERAL"
’* Allocate statement handle
rc = SQLAllocHandle(SQL_HANDLE_STMT, ghDbc, hStmt)
If rc <> SQL_SUCCESS Then
Call DisplayError(rc, "SQLAllocStmt failed.")
Call DspSQLError(henv, SQL_NULL_HDBC, SQL_NULL_HSTMT)
End If
’* Drop the old Procedure
rc = SQLExecDirect(hstmt, szDropProc, SQL_NTS)
568
IBM i: Windows アプリケーション・パッケージ: プログラミング
’ Create the new Procedure
rc = SQLExecDirect(hstmt, szCreateProc, SQL_NTS)
If rc <> SQL_SUCCESS And rc <> SQL_SUCCESS_WITH_INFO Then
Call DisplayError(rc, "SQLCreate failed.")
Call DspSQLError(henv, hdbc, hstmt)
End If
プロシージャーを呼び出すためのステートメントの作成
’* This statement will be used to call the procedure
szStoredProc = "call partqry2(?, ?)"
’* Prepare the CALL statement
rc = SQLPrepare(hstmt, szStoredProc, Len(szStoredProc))
If rc <> SQL_SUCCESS And rc <> SQL_SUCCESS_WITH_INFO Then
Call DisplayError(rc, "SQLPrepare failed.")
Call DspSQLError(henv, hdbc, hstmt)
End If
パラメーターのバインド
’Bind the parameters for the procedure
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, _
SQL_INTEGER, lLen1, 0, sFlag, lLen1, lCbValue)
If rc <> SQL_SUCCESS Then
Call DisplayError(rc, "Problem binding parameter ")
End If
rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SLONG, _
SQL_INTEGER, 4, 0, lPartNumber, lLen2, lCbValue)
If rc <> SQL_SUCCESS Then
Call DisplayError(rc, "Problem binding parameter ")
End If
プロシージャーの呼び出し
rc = SQLExecute(hstmt)
If lRc <> SQL_SUCCESS Then
’ Free the statement handle for repeated processing
rc = SQLFreeHandle(
Call DspSQLError(henv, hdbc, hstmt)
End If
rc = SQLFetch(hstmt)
If rc = SQL_NO_DATA_FOUND Then
mnuClear_Click
’Clear screen
txtPartNumber = lPartNumber ’Show the part number not found
Call DisplayMessage("RECORD NOT FOUND")
.
.
Else
’Get Description
rc = SQLGetData(hstmt, 2, SQL_C_CHAR, sSDescription, _
25, lcbBuffer)
’Get Quantity. SQLGetLongData uses alias SQLGetData
rc = SQLGetLongData(hstmt, 3, SQL_C_SLONG, lSQuantity, _
Len(lSQuantity), lcbBuffer)
’Get Price. SQLGetDoubleData uses alias SQLGetData
rc = SQLGetDoubleData(hstmt, 4, SQL_C_DOUBLE, dSPrice, _
Len(dSPrice), lcbBuffer)
’Get Received date
rc = SQLGetData(hstmt, 5, SQL_C_CHAR, sSReceivedDate, _
10, lcbBuffer)
txtDescription = sSDescription ’Show description
プログラミング
569
txtQuantity = lSQuantity
’Show quantity
txtPrice = Format(dSPrice, "currency")
’Convert dSPrice to
txtReceivedDate = CDate(sSReceivedDate) ’Convert string to d
Call DisplayMessage("Record found")
End If
関連資料:
『例: ILE RPG - ODBC プロシージャーのホスト・コード』
この例ではプログラム、SPROC2 は、CALL ステートメントを使用して、IBM i Access ODBC を介して
プロシージャーとしてクライアントから呼び出されます。このプログラムは、データを、PARTS (パーツ)
データベース・ファイルからクライアントへ戻します。
例: ILE RPG - ODBC プロシージャーのホスト・コード:
この例ではプログラム、SPROC2 は、CALL ステートメントを使用して、IBM i Access ODBC を介して
プロシージャーとしてクライアントから呼び出されます。このプログラムは、データを、PARTS (パーツ)
データベース・ファイルからクライアントへ戻します。
ILE-RPG の例
* This example is written in ILE-RPG
*
* Define option and part as integer
D#opt
s
10i 0
D#part
s
10i 0
* Define part as packed 5/0
Dpart
s
5p 0
C
C
C
*entry
C
C
C
#opt
#opt
C
C
part
plist
parm
parm
#opt
#part
caseq
caseq
endcs
1
2
eval
return
*inlr = *on
onerec
allrec
*
****************************
C
onerec
begsr
****************************
* Process request for a single record.
C/EXEC SQL DECLARE C1 CURSOR FOR
C+ SELECT
C+ PARTNO,
C+ PARTDS,
C+ PARTQY,
C+ PARTPR,
C+ PARTDT
C+
C+ FROM PARTS
-- FROM PART MASTER FILE
C+
C+ WHERE PARTNO = :PART
C+
C+
C+ FOR FETCH ONLY
-- READ ONLY CURSOR
C/END-EXEC
C*
C/EXEC SQL
C+ OPEN C1
C/END-EXEC
C*
C/EXEC SQL
570
IBM i: Windows アプリケーション・パッケージ: プログラミング
C+ SET RESULT SETS CURSOR C1
C/END-EXEC
C
endsr
****************************
C
allrec
begsr
****************************
* Process request to return all records
C/EXEC SQL DECLARE C2 CURSOR FOR
C+ SELECT
C+ PARTNO,
C+ PARTDS,
C+ PARTQY,
C+ PARTPR,
C+ PARTDT
C+
C+ FROM PARTS
-- FROM PART MASTER FILE
C+
C+
C+ ORDER BY PARTNO
-- SORT BY PARTNO
C+
C+ FOR FETCH ONLY
-- READ ONLY CURSOR
C/END-EXEC
C*
C/EXEC SQL
C+ OPEN C2
C/END-EXEC
C*
C/EXEC SQL
C+ SET RESULT SETS CURSOR C2
C/END-EXEC
C
endsr
関連資料:
568 ページの『例: Visual Basic - プロシージャーの呼び出しによるデータへのアクセスと戻し』
DB2 for IBM i のプロシージャーの作成、準備、バインド、および呼び出しについて、Visual Basic の例
を使って説明します。
IBM i Access データベースの API
IBM i Access の専有 C/C++ データベース API で提供されていた機能のうち、現在は拡張が行われていな
い機能には、他のテクノロジーを使用します。
IBM i Access の専有 C/C++ データベース API では、IBM i データベース・ファイルへの SQL アクセス
のほかに、IBM i のデータベース機能およびカタログ機能へのサポートも提供していました。
以下のテクノロジーでは、これらの非推奨 API の機能を引き続き提供しています。これらの詳細について
は、他のトピック集を参照してください。
v NET フレームワーク・クラス
v ADO/OLE DB
v ODBC
v JDBC
v データベース転送
v ActiveX オートメーション・オブジェクト
関連資料:
17 ページの『データベース API の戻りコード』
以下のデータベース API の戻りコードがあります。
プログラミング
571
ActiveX プログラミング
ActiveX オートメーションは、Microsoftによって定義されたプログラミング・テクノロジーであり、IBM i
Access Client ソリューション製品でサポートされています。
注: コード例を使用することで、 573 ページの『コードに関するライセンス情報および特記事項』の条件に
同意します。
IBM i Access Client ソリューションでは、ActiveX オートメーションを使用して IBM i 資源にアクセス
する方法として、以下の方法を備えています。
オートメーション・オブジェクト
これらのオブジェクトは、以下のサポートを提供します。
v IBM i データ待ち行列へのアクセス
v IBM i アプリケーション・プログラミング・インターフェースとユーザー・プログラムの呼び出
し
v IBM i 接続の管理とセキュリティーの検証
v IBM i CL コマンドの実行
v データ・タイプ変換とコード・ページ変換の実行
v データベース転送の実行
v ホスト・エミュレーション・セッションとのインターフェース
IBM i Access Client ソリューション OLE DB provider:
Microsoft の ActiveX Data Objects (ADO) を使用して、OLE DB Provider を呼び出すと、以下の
IBM i 資源にアクセスできます。
v レコード・レベルのアクセスを介した IBM i データベース
v SQL を介した IBM i データベース
v SQL ストアード・プロシージャー
v データ待ち行列
v プログラム
v CL コマンド
カスタム・コントロール
以下のための ActiveX カスタム・コントロールが提供されます。
v
IBM i データ待ち行列
v
IBM i CL コマンド
v
以前に接続されていたシステムの IBM i 名
v
IBM i ナビゲーター
Programmer's Toolkit:
ActiveX の詳細については、製品の Programmer's Toolkit 構成要素のトピック『ActiveX』を参照
してください。このツールキットには、ADO と ActiveX オートメーション・オブジェクトに関す
るすべての資料、および ActiveX の情報源へのリンクが含まれています。
ActiveX のトピックにアクセスする方法
1. Programmer's Toolkit がインストールされていることを確認します (『Programmer's
Toolkit のインストール』を参照してください)。
572
IBM i: Windows アプリケーション・パッケージ: プログラミング
2. Programmer's Toolkit の立ち上げ (『Programmer's Toolkit の立ち上げ』を参照してく
ださい)。
3. 「概要」トピックを選択します。
4. 「プログラミング・テクノロジー」を選択します。
5. 「ActiveX」を選択します。
関連タスク:
4 ページの『Programmer's Toolkit のインストール』
Programmer's Toolkit は、Windows アプリケーション・パッケージのフィーチャーの 1 つとしてインスト
ールされます。
5 ページの『Programmer's Toolkit の立ち上げ』
Programmer's Toolkit は、IBM i Access Client ソリューション製品のフィーチャーの 1 つとして立ち上げ
られます。
関連資料:
473 ページの『OLE DB Provider』
IBM i データベース・ファイルへのレコード・レベル・アクセスおよび SQL アクセスをサポートしま
す。このサポートを活用するためには、ActiveX データ・オブジェクト (ADO) および OLE DB インター
フェースを使用します。
コードに関するライセンス情報および特記事項
IBM は、お客様に、すべてのプログラム・コードのサンプルを使用することができる非独占的な著作使用
権を許諾します。お客様は、このサンプル・コードから、お客様独自の特別のニーズに合わせた類似のプロ
グラムを作成することができます。
強行法規で除外を禁止されている場合を除き、IBM、そのプログラム開発者、および供給者は「プログラ
ム」および「プログラム」に対する技術的サポートがある場合にはその技術的サポートについて、商品性の
保証、特定目的適合性の保証および法律上の瑕疵担保責任を含むすべての明示もしくは黙示の保証責任を負
わないものとします。
いかなる場合においても、IBM および IBM のサプライヤーならびに IBM ビジネス・パートナーは、そ
の予見の有無を問わず発生した以下のものについて賠償責任を負いません。
1. データの喪失、または損傷。
2. 直接損害、特別損害、付随的損害、間接損害、または経済上の結果的損害
3. 逸失した利益、ビジネス上の収益、あるいは節約すべかりし費用
国または地域によっては、法律の強行規定により、上記の責任の制限が適用されない場合があります。
プログラミング
573
574
IBM i: Windows アプリケーション・パッケージ: プログラミング
特記事項
本書は米国 IBM が提供する製品およびサービスについて作成したものです。
本書に記載の製品、サービス、または機能が日本においては提供されていない場合があります。日本で利用
可能な製品、サービス、および機能については、日本 IBM の営業担当員にお尋ねください。本書で IBM
製品、プログラム、またはサービスに言及していても、その IBM 製品、プログラム、またはサービスのみ
が使用可能であることを意味するものではありません。これらに代えて、IBM の知的所有権を侵害するこ
とのない、機能的に同等の製品、プログラム、またはサービスを使用することができます。ただし、IBM
以外の製品とプログラムの操作またはサービスの評価および検証は、お客様の責任で行っていただきます。
IBM は、本書に記載されている内容に関して特許権 (特許出願中のものを含む) を保有している場合があ
ります。本書の提供は、お客様にこれらの特許権について実施権を許諾することを意味するものではありま
せん。実施権についてのお問い合わせは、書面にて下記宛先にお送りください。
〒103-8510
東京都中央区日本橋箱崎町19番21号
日本アイ・ビー・エム株式会社
法務・知的財産
知的財産権ライセンス渉外
以下の保証は、国または地域の法律に沿わない場合は、適用されません。 IBM およびその直接または間接
の子会社は、本書を特定物として現存するままの状態で提供し、商品性の保証、特定目的適合性の保証およ
び法律上の瑕疵担保責任を含むすべての明示もしくは黙示の保証責任を負わないものとします。国または地
域によっては、法律の強行規定により、保証責任の制限が禁じられる場合、強行規定の制限を受けるものと
します。
この情報には、技術的に不適切な記述や誤植を含む場合があります。本書は定期的に見直され、必要な変更
は本書の次版に組み込まれます。IBM は予告なしに、随時、この文書に記載されている製品またはプログ
ラムに対して、改良または変更を行うことがあります。
本書において IBM 以外の Web サイトに言及している場合がありますが、便宜のため記載しただけであ
り、決してそれらの Web サイトを推奨するものではありません。それらの Web サイトにある資料は、こ
の IBM 製品の資料の一部ではありません。それらの Web サイトは、お客様の責任でご使用ください。
IBM は、お客様が提供するいかなる情報も、お客様に対してなんら義務も負うことのない、自ら適切と信
ずる方法で、使用もしくは配布することができるものとします。
本プログラムのライセンス保持者で、(i) 独自に作成したプログラムとその他のプログラム (本プログラム
を含む) との間での情報交換、および (ii) 交換された情報の相互利用を可能にすることを目的として、本
プログラムに関する情報を必要とする方は、下記に連絡してください。
IBM Corporation
Software Interoperability Coordinator, Department YBWA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.
© Copyright IBM Corp. 2013
575
本プログラムに関する上記の情報は、適切な使用条件の下で使用することができますが、有償の場合もあり
ます。
本書で説明されているライセンス・プログラムまたはその他のライセンス資料は、IBM 所定のプログラム
契約の契約条項、IBM プログラムのご使用条件、またはそれと同等の条項に基づいて、IBM より提供され
ます。
この文書に含まれるいかなるパフォーマンス・データも、管理環境下で決定されたものです。そのため、他
の操作環境で得られた結果は、異なる可能性があります。一部の測定が、開発レベルのシステムで行われた
可能性がありますが、その測定値が、一般に利用可能なシステムのものと同じである保証はありません。さ
らに、一部の測定値が、推定値である可能性があります。実際の結果は、異なる可能性があります。お客様
は、お客様の特定の環境に適したデータを確かめる必要があります。
IBM 以外の製品に関する情報は、その製品の供給者、出版物、もしくはその他の公に利用可能なソースか
ら入手したものです。 IBM は、それらの製品のテストは行っておりません。したがって、他社製品に関す
る実行性、互換性、またはその他の要求については確証できません。 IBM 以外の製品の性能に関する質問
は、それらの製品の供給者にお願いします。
IBM の将来の方向または意向に関する記述については、予告なしに変更または撤回される場合があり、単
に目標を示しているものです。
本書はプランニング目的としてのみ記述されています。記述内容は製品が使用可能になる前に変更になる場
合があります。
本書には、日常の業務処理で用いられるデータや報告書の例が含まれています。より具体性を与えるため
に、それらの例には、個人、企業、ブランド、あるいは製品などの名前が含まれている場合があります。こ
れらの名称はすべて架空のものであり、名称や住所が類似する企業が実在しているとしても、それは偶然に
すぎません。
著作権使用許諾:
本書には、様々なオペレーティング・プラットフォームでのプログラミング手法を例示するサンプル・アプ
リケーション・プログラムがソース言語で掲載されています。お客様は、サンプル・プログラムが書かれて
いるオペレーティング・プラットフォームのアプリケーション・プログラミング・インターフェースに準拠
したアプリケーション・プログラムの開発、使用、販売、配布を目的として、いかなる形式においても、
IBM に対価を支払うことなくこれを複製し、改変し、配布することができます。このサンプル・プログラ
ムは、あらゆる条件下における完全なテストを経ていません。従って IBM は、これらのサンプル・プログ
ラムについて信頼性、利便性もしくは機能性があることをほのめかしたり、保証することはできません。こ
れらのサンプル・プログラムは特定物として現存するままの状態で提供されるものであり、いかなる保証も
提供されません。 IBM は、お客様の当該サンプル・プログラムの使用から生ずるいかなる損害に対しても
一切の責任を負いません。
それぞれの複製物、サンプル・プログラムのいかなる部分、またはすべての派生的創作物にも、次のよう
に、著作権表示を入れていただく必要があります。
© (お客様の会社名) (西暦年). このコードの一部は、IBM Corp. のサンプル・プログラムから取られていま
す。
© Copyright IBM Corp. _年を入れる_.
576
IBM i: Windows アプリケーション・パッケージ: プログラミング
プログラミング・インターフェース情報
この「IBM i Access」資料には、プログラムを作成するユーザーが、IBM i のサービスを使用するための
プログラミング・インターフェースが記述されています。
商標
IBM、IBM ロゴおよび ibm.com は、世界の多くの国で登録された International Business Machines
Corporation の商標です。他の製品名およびサービス名等は、それぞれ IBM または各社の商標である場合
があります。現時点での IBM の商標リストについては、『www.ibm.com/legal/copytrade.shtml』をご覧く
ださい。
Adobe、Adobe ロゴ、PostScript、PostScript ロゴは、Adobe Systems Incorporated の米国およびその他の国
における登録商標または商標です。
インテル、Intel、Intel ロゴ、Intel Inside、Intel Inside ロゴ、Intel Centrino、Intel Centrino ロゴ、
Celeron、Intel Xeon、Intel SpeedStep、Itanium、および Pentium は、Intel Corporation または子会社の米国
およびその他の国における商標または登録商標です。
Linux は、Linus Torvalds の米国およびその他の国における登録商標です。
Microsoft、Windows、Windows NT および Windows ロゴは、Microsoft Corporation の米国およびその他の
国における商標です。
UNIX は The Open Group の米国およびその他の国における登録商標です。
Java およびすべての Java 関連の商標およびロゴは Oracle やその関連会社の米国およびその他の国におけ
る商標または登録商標です。
他の製品名およびサービス名等は、それぞれ IBM または各社の商標である場合があります。
使用条件
これらの資料は、以下の条件に同意していただける場合に限りご使用いただけます。
個人使用: これらの資料は、すべての著作権表示その他の所有権表示をしていただくことを条件に、非商業
的な個人による使用目的に限り複製することができます。ただし、IBM の明示的な承諾をえずに、これら
の資料またはその一部について、二次的著作物を作成したり、配布 (頒布、送信を含む) または表示 (上映
を含む) することはできません。
商業的使用: これらの資料は、すべての著作権表示その他の所有権表示をしていただくことを条件に、お客
様の企業内に限り、複製、配布、および表示することができます。ただし、IBM の明示的な承諾をえずに
これらの資料の二次的著作物を作成したり、お客様の企業外で資料またはその一部を複製、配布、または表
示することはできません。
ここで明示的に許可されているもの以外に、資料や資料内に含まれる情報、データ、ソフトウェア、または
その他の知的所有権に対するいかなる許可、ライセンス、または権利を明示的にも黙示的にも付与するもの
ではありません。
資料の使用が IBM の利益を損なうと判断された場合や、上記の条件が適切に守られていないと判断された
場合、IBM はいつでも自らの判断により、ここで与えた許可を撤回できるものとさせていただきます。
特記事項
577
お客様がこの情報をダウンロード、輸出、または再輸出する際には、米国のすべての輸出入関連法規を含
む、すべての関連法規を遵守するものとします。
IBM は、これらの資料の内容についていかなる保証もしません。これらの資料は、特定物として現存する
ままの状態で提供され、商品性の保証、特定目的適合性の保証および法律上の瑕疵担保責任を含むすべての
明示もしくは黙示の保証責任なしで提供されます。
578
IBM i: Windows アプリケーション・パッケージ: プログラミング
特記事項
579
IBM®
プログラム番号: 5770-XJ1
Printed in Japan