SYSEXT ユーティリティ- Natural アプリケーションプログラミングインターフェイス

SYSEXT ユーティリティを使用すると、現在のシステムライブラリ SYSEXT に含まれている Natural アプリケーションプログラミングインターフェイス（API）を検索し、テストできます。

Natural API は Natural サブプログラム（カタログ化オブジェクト）で、データにアクセスして必要に応じて変更したり、Natural ステートメントではアクセスできないサービスを実行したりする場合に使用します。Natural API は、Natural、サブコンポーネント、またはサブ製品を参照します。

「SYSEXT ユーティリティ- Natural アプリケーションプログラミングインターフェイス」ドキュメントでは、次のトピックについて説明します。

• SYSEXT の概要

• SYSEXT の呼び出しと終了

• SYSEXT ユーティリティの使用

• インターフェイスバージョン

• 予約キーワード

• Natural API の使用

関連トピック：

• 「Application Programming Interfaces」 - 『Natural Security』ドキュメント

SYSEXT の概要

SYSEXT ユーティリティには、各 Natural API について、機能説明、1 つのプログラム例、1 つのカテゴリ、および API に固有のキーワードがあります。

次の図に、SYSEXT で提供されている Natural オブジェクトおよび主な機能の概要を示します。

Natural API に提供されているオブジェクト

各 Natural API に提供されている一般的な Natural オブジェクトのタイプは、次のセクションでリストされています。特定の API 用に存在する可能性のある追加オブジェクトは含まれていません。

API のすべての関連オブジェクトは、システムファイル FNAT のライブラリ SYSEXT に含まれています。

次の表の nnnn は、API、および対応するプログラム例とテキストオブジェクトを識別するための 4 桁の番号を表します。

一部の API では、API に関連する機能を提供するコピーコードを使用できます。コピーコードには USRnnnnX という名前が付けられています。X は識別文字（"Z"、"Y" など）です。

SYSEXT の呼び出しと終了

SYSEXT ユーティリティは、次の構文図で説明されているシステムコマンド SYSEXT によって起動されます。

次の表に、パラメータの説明を示します。

SYSEXT を呼び出すには

• 次のシステムコマンドを入力します。

  SYSEXT

  以下の例に示すようなメニューが表示されます。最初のメニューに応じて、使用可能なすべての Natural API のリストが表示されます。

  10:57:31 ***** NATURAL SYSEXT UTILITY ***** 2012-04-23 User SAG - Menu - Library SYSEXT Cmd Interface Description Prod --- USR*____ _____________________________________________________________ *__ _ USR0010N Get SYSPROF information NAT _ USR0011N Get information on logical file NAT _ USR0020N Read any error message from FNAT or FUSER NAT _ USR0040N Get type of last error NAT _ USR0050N Get SYSPROD information NAT _ USR0060N Copy LFILE definition from FNAT to FUSER NAT _ USR0080N Get or set type and name of editor contents NAT _ USR0120N Read Natural short error message NAT _ USR0210N Save, catalog or stow Natural object NAT _ USR0220N Read Natural long error message NAT _ USR0221N Read Natural long error message NAT _ USR0320N Read user short error message from FNAT or FUSER NAT _ USR0330N Read Natural object directory NAT Category .. ______________________________ Keyword .. ____________________ Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Reset Exit Desc Curr -- - + ++ > Canc

任意のパラメータで SYSEXT を呼び出すことができます。例えば、起動時に 2 番目のメニューを表示することができます。

SYSEXT SECOND

この場合は、次のようなメニューが表示されます。

 10:57:31              ***** NATURAL SYSEXT UTILITY *****             2012-04-23
 User SAG                            - Menu -                   Library SYSEXT

 Cmd Interface Description                        Category
 --- USR*____  __________________________________ *_____________________________
  _  USR0010N  Get SYSPROF information            SYSTEM COMMANDS
  _  USR0011N  Get information on logical file    SYSTEM FILES
  _  USR0020N  Read any error message from FNAT o ERROR MESSAGES
  _  USR0040N  Get type of last error             ERROR HANDLING
  _  USR0050N  Get SYSPROD information            SYSTEM COMMANDS
  _  USR0060N  Copy LFILE definition from FNAT to SYSTEM FILES
  _  USR0080N  Get or set type and name of editor EDITOR
  _  USR0120N  Read Natural short error message   ERROR MESSAGES
  _  USR0210N  Save, catalog or stow Natural obje NATURAL OBJECTS
  _  USR0220N  Read Natural long error message    ERROR MESSAGES
  _  USR0221N  Read Natural long error message    ERROR MESSAGES
  _  USR0320N  Read user short error message from ERROR MESSAGES
  _  USR0330N  Read Natural object directory      NATURAL OBJECTS

 Category .. ______________________________  Keyword .. ____________________
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Reset Exit  Desc  Curr  --    -     +     ++    <           Canc

別の方法として、パラメータなしで SYSEXT を呼び出し、表示されるメニューを調整することもできます。「PF キー」を参照してください。

SYSEXT を終了するには

• SYSEXT ユーティリティメニューで PF3 キーまたは PF12 キーを押します。

  または:
  コマンド行にピリオド（.）または EXIT を入力します。

SYSEXT ユーティリティの使用

このセクションでは、次のトピックについて説明します。

• SYSEXT ユーティリティメニューの要素

• PF キー

• 行コマンド

• ユーティリティコマンド

SYSEXT ユーティリティメニューの要素

SYSEXT ユーティリティメニューには、API のリストが表示されます。各 API には、API 名（［Interface］）、説明（［Description］）、および選択したメニューに応じて製品コード（［Prod］）またはカテゴリ（［Category］）による分類があります。左端の列（［Cmd］）を除き、各列のヘッダーは選択条件を入力できる選択フィールドです。

メニューの下部にある［Category］検索フィールドを使用して、使用可能なカテゴリを検索することもできます。

［Keywords］入力フィールドは、使用可能なキーワードを取得するための検索フィールドとして使用することも、API を取得するための選択フィールドとして使用することもできます。

複数選択フィールドで選択条件を指定することもできます。例えば、キーワード PF-KEY およびカテゴリ NATURAL ENVIRONMENT を使用して、USR4 で始まる API を 1 つの手順で選択できます。

すべてのメニュー要素とその使用方法の詳細を以下に示します。

カテゴリ検索

• アスタリスク（*）を入力するか、オプションでアスタリスクで区切った接頭辞をカテゴリ検索フィールドに入力します。例：

  N*

  これで、次のようなメニューが表示されます。

  Search for Categories Mark Category ---- N*____________________________ _ NATURAL ENVIRONMENT _ NATURAL OBJECTS

  特定のカテゴリを選択条件として選択するには、任意の文字を［Mark］列に入力します。これで、この選択条件を満たすすべての API のリストが表示されます。

キーワード検索

• アスタリスク（*）を入力するか、アスタリスクで区切った接頭辞を入力します。例：

  PF*

  次のようなメニューが表示され、別のウィンドウに PF で始まるキーワードが表示されます。

  Search for Keywords Mark Keyword ---- PF*_________________ _ PF-KEY _ PF-KEY LINE

  特定のキーワードを選択条件として選択するには、任意の文字を［Mark］列に入力します。これで、この選択条件を満たすすべての API のリストが表示されます。

キーワード選択

• キーワード全体を入力します。例：

  PF-KEY

  これで、キーワードが PF-KEY であるすべての API のリストが表示されます。

  注意:
  末尾以外のアスタリスクは文字どおりに解釈されます。例えば、*LANGUAGE を入力すると、キーワードが *LANGUAGE である API のリストが表示されます。

PF キー

次の PF キーを使用できます。

行コマンド

行コマンドを使用すると、オブジェクト操作を実行できます。行コマンドは、目的の API の横の［Cmd］列に入力できます。疑問符（?）を入力するか PF1 キーを押すと、有効な行コマンドがリストされます。

次の行コマンドを使用できます。

ユーティリティコマンド

このセクションでは、コマンド行で入力する次のユーティリティコマンドについて説明します。

• EXIT
  SYSEXT ユーティリティを終了します。

• REFRESH
  現在のライブラリ SYSEXT に含まれているオブジェクトのデータを使用して、API 情報を更新します。REFRESH コマンドは、API の説明またはキーワードが変更されたり、テキストオブジェクトが追加または削除されたりした場合にのみ必要となります。

  正常に完了すると、テキストモジュール EXT-XML1 および EXT-XML2 がライブラリ SYSEXT 内に生成されたことが確認されます。

  注意:
  ソースオブジェクトの EXT-XML1 と EXT-XML2 は変更しないでください。これらは、SYSEXT ユーティリティの設定に必須で、Software AG 内部でのみ使用されます。

インターフェイスバージョン

インターフェイスバージョンは、（ほぼ）機能が同じでも、拡張パラメータ仕様が異なる API のコレクションとみなすことができます。したがって、新しいバージョンと以前のバージョンの互換性を保つために、明確な開発サイクルに対応します。

API にインターフェイスバージョンがある場合は、対応するテキストオブジェクト USRnnnnT に表示されますインターフェイスバージョンは、それが属するバージョンに応じてリスト内で整列されます。右端の要素は現在のバージョンに属します。このステータスは、予約キーワード +CURRENT-VERSION で表されます。他のすべての要素は前のバージョンに属し、予約キーワード +PREVIOUS-VERSION でマークされています。インターフェイスバージョンを持たない API は、「ユニーク」な API と呼ばれています。

インターフェイスバージョンを持つ API は、メニュー上で強調表示されます。

現在の API すべてのリスト（「PF5」を参照）は、すべてのユニークな API、およびインターフェイスバージョンを持つ API の現在のバージョン（キーワード +CURRENT-VERSION を使用）で構成されます。

予約キーワード

予約キーワードとは、API のメタ情報を指し、例えば API が追加された Natural バージョンなどが該当します。予約キーワードは常にプラス記号（+）で始まります。詳細については、次の表を参照してください。

Natural API の使用

システムライブラリ SYSEXT に含まれる Natural API を使用する場合は、次のいずれかの手順を実行します。

• この API を使用する Natural オブジェクトが含まれるユーザーライブラリの steplib ライブラリとして、システムファイル FNAT のシステムライブラリ SYSEXT を定義します。したがって、Natural バージョンをアップグレードする場合は、API 固有のアクションは必要ありません。

• 目的の API をシステムファイル FNAT のシステムライブラリ SYSTEM にコピーします。したがって、Natural バージョンをアップグレードする場合は、1 つのライブラリで API をチェックするだけで済みます。

• 目的の API をシステムファイル FUSER のシステムライブラリ SYSTEM にコピーします（非推奨）。

• 目的の API を、この API を使用する Natural オブジェクトが格納されているシステムファイル FUSER のユーザーライブラリ（またはその steplib の 1 つ）にコピーします（非推奨）。

API は、その API が提供されている Natural バージョンでのみ使用できます。API は FNAT システムファイルにのみ保存することを強くお勧めします。これにより、正しいバージョンが常に実行されます。

インターフェイスを使用するには

1. 呼び出し元のプログラムで DEFINE DATA ステートメントを使用して、その API のテキストオブジェクト USRnnnnT にリストされているパラメータを指定します。プログラム例 USRnnnnP では、DEFINE DATA LOCAL ステートメント内でパラメータを定義しています。または、呼び出し元のプログラム外の別の LDA（ローカルデータエリア）または PDA（パラメータデータエリア）で、そのデータエリアを参照する DEFINE DATA LOCAL USING ステートメントを使用してパラメータを指定できます。

2. 次のステートメントを入力します。

   CALLNAT 'USRnnnnN' parameters

   詳細については、『ステートメント』ドキュメントの「CALLNAT」ステートメントを参照してください。

システムライブラリ SYSEXT に含まれている Natural コピーコードを使用する場合は、次の手順を実行します。

• 目的のコピーコードを、このコピーコードを使用する Natural オブジェクトが格納されているシステムファイル FUSER のユーザーライブラリにコピーします。

コピーコードを使用するには

1. 呼び出し元のプログラムで INCLUDE ステートメントを使用して、その API のテキストオブジェクト USRnnnnT またはコピーコード自体にリストされているパラメータを指定します。プログラム例 USRnnnnP では、DEFINE DATA LOCAL ステートメント内でパラメータを定義しています。または、呼び出し元のプログラム外の別の LDA（ローカルデータエリア）または PDA（パラメータデータエリア）で、そのデータエリアを参照する DEFINE DATA LOCAL USING ステートメントを使用してパラメータを指定できます。

2. 一部のコピーコードでは、追加のデータ定義が必要です。これらは API のテキストオブジェクト USRnnnnT とコピーコード自体に記述します。

3. 次のステートメントを入力します。

   INCLUDE USRnnnnX 'parameter'...

   詳細については、『ステートメント』ドキュメントの「INCLUDE」ステートメントを参照してください。