例 1: MVS™ データ・セットを順次読み取る

初回要求

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

Authorization : Basic dXNlcmlkOnBhc3N3b3Jk

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

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

初回要求にはまた、データ・リソースの名前と、オプションとして、データをマップする File Manager テンプレートまたはコピーブックの名前も必要です。

{
    "resource" : 
    {
        "resourceName" : "MY.MVS.DATASET"
    },
    "template" :
    {
        "templateName" : "MY.TEMPLATE(MVSDS)"
    },
    "operation" :
    {
        "numRecords" : 1,
        "session" : true,
        "timeout" : 1800
    }
}

この要求は、データ・セット MY.MVS.DATASET の先頭から 1 レコードを読み取り、MY.TEMPLATE(MVSDS) で見つかったテンプレートを使用して応答のレコード・フィールドをマップします。

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

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

成功時の応答

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

{
    "records" : 
    [
        {
            "layouts" : 
            [
                {
                    "layout" : "CUSTOMER-ADDRESS",
                    "fields" : 
                    [
                        {
                            "field" : "CUSTOMER-NO",
                            "type" : "PD",
                            "value" : 5788
                        },
                        {
                            "field" : "CUSTOMER-STREET",
                            "type" : "AN",
                            "value" : "177A BLEEKER STREET"
                        },
                        {
                            "field" : "CUSTOMER-CITY",
                            "type" : "AN",
                            "value" : "NEW YORK"
                        },
                        {
                            "field" : "CUSTOMER-COUNTRY",
                            "type" : "AN",
                            "value" : "USA"
                        }
                    ]
                }
            ]
        }
    ] ,
    "token" : ""+WCCd/9g8fXy8PT58vfz9mD39fL48fU="
}

後続の読み取り要求

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

{
    "operation" :
    {
        "numRecords" : 1,
        "session" : true,
        "token" : "+WCCd/9g8fXy8PT58vfz9mD39fL48fU="
    }
}

トークンを渡すとき、resource パラメーターまたは template パラメーターはトークンと関連付けられたセッションによって既に知られているため、呼び出し元はこれらのパラメーターを渡す必要がありません。API 呼び出し元は、最後のレコードが読み取られたことを示す、last が true に設定された応答レコード・オブジェクトがあるまで、1 つ以上のレコードを読み取り続けることができます。例:

{
    "records" : 
    [
        {
            "last" : true, 
            other response fields
        }
    ]
}

セッションの終了

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

{
    "operation" :
    {
        "numRecords" : 0,
        "session" : false,
        "token" : "+WCCd/9g8fXy8PT58vfz9mD39fL48fU="
    }
}

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