例 8: CICS® VSAM ファイルを順次読み取る

次の例では、File Manager Service Provider REST API 呼び出しを実行して CICS® VSAM データ・セット内のレコードを読み取る永続セッションを開始し、テンプレートを使用して各レコードのフィールドをマップします。

この例では、一致するテンプレートまたはコピーブックを使用して CICS® VSAM ファイルをマップするサービス・アーカイブが作成され、デプロイされていることを前提とします。例えば、サービス・アーカイブは次のプロパティー・ファイルを使用して作成できます。

name=fmExample4
description=CICSR01:MYKSDS MAPPED BY MY.TEMPLATE(MYKSDS)
version=1.0
provider=filemanager
host=10.1.1.2
port=9043
userid=admin
passwd=s3cr3t
file=FI:CICSR01:MYKSDS
template=MY.TEMPLATE(MYKSDS)
timeout=300
connid=default

この例は、MY.TEMPLATE(MYKSDS) で見つかったテンプレートを使用して CICS® 領域 CICSR01 にある CICS® VSAM ファイル MYKSDS をマップします。この例では、生成された SAR ファイルと関連する組み込みの API が z/OS® Connect WLP サーバーにデプロイされていることを前提としています。

初回要求

データ・リソースからデータを読み取る初回 API 呼び出しには、z/OS® データ・リソースへの以降のアクセスで呼び出し元を認証できるように、HTTP Basic 認証ヘッダーが必要です。例:

Authorization : Basic dXNlcmlkOnBhc3N3b3Jk

ここで、Basic キーワードに続くストリングは、userid:password の Base64 エンコードを示します。

また、JSON ペイロードがあるすべての要求でも、値が application/json の Content-Type ヘッダーが必要です。

初回要求では、データ・リソースに命名したり、テンプレート情報を指定したりする必要はありません。この情報は API に関連付けられたサービス・アーカイブに既に含まれています。このため、API 呼び出し元が指定する必要があるのは、必要に応じて、オプションの operation パラメーターと position パラメーターのみです。

{
    "operation" :
    {
        "numRecords" : 1,
        "session" : true
    }
}

この要求は、CICS® 領域 CICSR01 にある VSAM ファイル MYKSDS の先頭から 1 レコードを読み取ります。読み取られたレコードは、SAR ファイルの作成時に MY.TEMPLATE(MYKSDS) で見つかったテンプレートによって応答にマップされます。

File Manager が true に設定されているため、サービス・プロバイダーは session セッションを維持します。セッションは、以降、session が false に設定された要求が実行されるまで、またはセッションでアクティビティーがない状態で 300 秒 (5 分) のタイムアウト期間が経過するまでアクティブのままになります。このタイムアウト期間はサービス・アーカイブで事前設定されています。

session が true に設定されている場合、呼び出し元は初回要求でトークンが戻ることを期待し、Basic 認証ヘッダーを渡す必要なく後続の呼び出しでトークンを使用できます。

成功時の応答

成功時の応答 (HTTP ステータス・コード 200) は次のようになります。

{
    "records" : 
    [
        {
            "layouts" : 
            [
                {
                    "CUSTOMER-ADDRESS" :
                    {
                        "CUSTOMER-NO" : 5788,
                        "CUSTOMER-STREET" : "177A BLEEKER STREET",
                        "CUSTOMER-CITY" : "NEW YORK",
                        "CUSTOMER-COUNTRY" : "USA"    
                    }
                }
            ]
        }
    ] ,
    "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
}

後続の読み取り要求

API 呼び出し元は、応答トークンを使用して後続の要求を実行し、サービス・プロバイダーによって保守される File Manager セッションを再使用できるようになります。例:

{
    "operation" :
    {
        "numRecords" : 1,
        "session" : true,
        "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
    }
}

API 呼び出し元は、最後のレコードが読み取られたことを示す、last が true に設定された応答レコード・オブジェクトがあるまで、1 つ以上のレコードを読み取り続けることができます。例:

{
    "records" : 
    [
        {
            "last" : true, 
            etc.
        }
    ]
}

セッションの終了

現時点では、API 呼び出し元はアクティブな File Manager セッションを終了する要求を送信します。

{
    "operation" :
    {
        "numRecords" : 0,
        "session" : false,
        "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
    }
}

トークンが有効な場合、session が false に設定された要求を送信すると File Manager セッションは常に終了します。呼び出し元は既に最後のレコードを読み取っているため、"numRecords" : 0 を設定することでもうレコードを読み取らないようサービス・プロバイダーに指示します。