# 日本語 Compaq OpenVMS
DEC XTPU
リファレンス・マニュアル

前へ | 次へ | 目次 | 索引

# 第 6 章
コール可能なDEC XTPU

この章では，コール可能なDEC XTPU ルーチンを説明し，コール可能なルーチンの目的と使用できるパラメータおよび主なステータス・リターンについて説明します。

# 6.1 概要

コール構文のパラメータは，DEC XTPU ルーチンに渡されるオブジェクトを表現します。各パラメータの説明には，データ・タイプとオブジェクトの受渡しメカニズムが示されています。データ・タイプは OpenVMS 標準データ・タイプです。受渡しメカニズムはパラメータ・リストがどのように解釈されるかを示しています。

コール可能なDEC XTPU を使用すると，他のプログラム言語やアプリケーションから DEC XTPU の機能を利用できます。DEC XTPU は標準の OpenVMSプロシージャ呼び出し/条件処理を使って，他の言語で作成されたプログラムからコールすることができ，また，MAIL などの OpenVMS ユーティリティからもコールすることができます。コール可能なDEC XTPU を使用すれば，ユーザのプログラムの内部でテキスト処理機能を実行することができます。

コール可能なDEC XTPU はDEC XTPU の共有可能イメージである XTPUSHR.EXE に存在するコール可能なルーチンから構成されます。コール可能なDEC XTPU を使用するためには，この共有可能イメージとリンクします。共有可能イメージには，コール可能なインタフェース・ルーチン名と定数が含まれています。DCL レベルの DEC XTPU インタフェースの場合と同様に，コール可能なDEC XTPU への入力として，また出力として，ファイルを使用することができます。さらに入力，出力，およびメッセージを処理するために独自のルーチンを作成することもできます。

この章は，システム・プログラマを対象としたものであり，以下の事項について十分理解しているものと仮定しています。

- 標準の OpenVMS プロシージャ呼び出しおよび条件処理

- OpenVMS ランタイム・ライブラリ(RTL)

- VAX および Alpha (AXP) コンピュータでのデータ・タイプの表現方法

- メイン・プログラムで使用している言語と異なる言語で作成されたルーチンをコールする方法

コール可能なDEC XTPU を使用するプログラムは，パラメータをDEC XTPU プロシージャで使用できるタイプにして渡す必要があります。

この章で説明しているDEC XTPU ルーチンは，ルーチンの終了ステータスを示す条件値を返します。戻される条件値とテスト値を比較する場合には，ランタイム・ライブラリの LIB$MATCH_COND を使用しなければなりません。条件値を単純な整数としてテストしないようにしてください。

## 6.1.1 コール可能なDEC XTPU に対する2つのインタフェース

コール可能なDEC XTPU は，単純なコール可能インタフェースと完全なコール可能インタフェースの2通りの方法でアクセスすることができます。

単純なコール可能インタフェース

コール可能なDEC XTPU を使用するためのもっとも簡単な方法は，単純なコール可能インタフェースを使用することです。DEC XTPU には，単純なコール可能インタフェースで使用できる2つのルーチンがあります。これらのルーチンはさらに以下の操作を実行する他のルーチンをコールします。

- エディタを初期化する

- エディタの操作に必要なパラメータをエディタに与える

- 編集セッションを制御する

- エラー処理を実行する

単純なコール可能インタフェースを使用する場合には， XTPU$XTPU ルーチンの場合， DEC XTPU に対する OpenVMS コマンド・ラインを指定します。また， XTPU$EDIT ルーチンを使って，入力ファイルと出力ファイルを指定することも可能です。XTPU$EDIT はコマンド文字列を作成し，そのコマンド文字列は XTPU$XTPUルーチンに渡されます。これらの2つのルーチンについては， 第 6.2 節 で詳しく説明します。

完全なコール可能インタフェース

完全なコール可能インタフェースを使用する場合には，コール可能な DEC XTPU のメイン・ルーチンを直接アクセスするプログラムを使用します。これらのルーチンは以下の操作を実行します。

エディタを初期化する | XTPU$INITIALIZE
DEC XTPU プロシージャを実行する | XTPU$EXECUTE_INIFILE XTPU$EXECUTE_COMMAND
エディタを制御する | XTPU$CONTROL
編集セッションを終了する | XTPU$CLEANUP

この方法でコール可能なDEC XTPU を使用する場合には，特定のパラメータに対して，値を指定しなければなりません。場合によっては，指定する値がルーチンのアドレスになることがあります。たとえば，XTPU$INITIALIZE をコールする場合には，初期化オプションを指定するルーチンのアドレスを指定しなければなりません。各アプリケーションに応じて，ユーザが追加ルーチンを自分で作成しなければならないこともあります。たとえば，ファイル操作を実行するルーチンやエラーを処理するルーチン，あるいは編集セッションを制御するルーチンを作成しなければならないことがあります。コール可能なDEC XTPU には，これらの作業の一部を実行できるユーティリティ・ルーチンが準備されています。これらのユーティリティ・ルーチンは以下の操作を実行することができます。

- OpenVMS コマンド・ラインを解析して，エディタを初期化するときに使用するアイテム・リストを作成する

- ファイル操作を処理する

- エラー・メッセージを出力する

- 条件処理を行う

完全なコール可能インタフェースについては，以下の各節に詳しく説明されています。

第 6.3 節 | まずインタフェースの簡単な説明が示されていますが，この節の大部分はコール可能なDEC XTPU のメイン・ルーチンの説明にあてられています (XTPU$INITIALIZE，XTPU$EXECUTE_INIFILE，XTPU$CONTROL， XTPU$EXECUTE_COMMAND，XTPU$CLEANUP)。
第 6.3.2 項 | 完全なコール可能インタフェースで使用できる追加ルーチンが説明されています。
第 6.3.3 項 | 完全なコール可能インタフェースで使用できるルーチンを作成するための必要条件が定義されています。

完全なコール可能インタフェースは，コール可能なDEC XTPU メイン・ルーチンと DEC XTPU ユーティリティ・ルーチンから構成されます。

## 6.1.2 共有可能イメージ

単純なコール可能インタフェースを使用する場合も，完全なコール可能インタフェースを使用する場合も， DEC XTPU の共有可能イメージにリンクすることにより，コール可能なDEC XTPU にアクセスすることができます。このイメージにはアプリケーションで使用できるルーチン名と定数が含まれています。さらに，XTPUSHR.EXE には，以下のシンボルも含まれています。

XTPU$GL_VERSION | 共有可能イメージのバージョン
XTPU$GL_UPDATE | 共有可能イメージの更新番号
XTPU$_FACILITY | DEC XTPU のファシリティ・コード

共有可能イメージ，XTPUSHR.EXE のリンク方法については，『日本語 Compaq OpenVMS 概説書』を参照してください。

## 6.1.3 コール可能なDEC XTPU ルーチンに対するパラメータの受渡し

パラメータは参照またはディスクリプタによってコール可能なDEC XTPU に渡されます。パラメータがルーチンの場合には，パラメータはバウンド・プロシージャ値(BPV) データ・タイプとしてディスクリプタによって渡されます。

バウンド・プロシージャ値とは，2つのロングワードから構成される値であり，最初のロングワードにはプロシージャのアドレスが含まれており，2番目のロングワードには環境値が含まれています。 図 6-1 を参照してください。環境値は最初のバウンド・プロシージャ値を作成するときに言語特有の方法で決定されます。バウンド・プロシージャがコールされると，コーリング・プログラムは 2番目のロングワードをR1にロードします。

図 6-1 バウンド・プロシージャ値

## 6.1.4 エラー処理

単純なコール可能インタフェースを使用する場合，DEC XTPU はすべてのエラーを処理するために独自の条件ハンドラである XTPU$HANDLER を設定します。完全なコール可能インタフェースを使用する場合には，以下の2通りの方法でエラーを処理することができます。

- DEC XTPU の省略時の条件ハンドラである XTPU$HANDLER を使用することができる

- 一部のエラーを処理するために独自の条件ハンドラを作成し，他のエラーは XTPU$HANDLER をコールすることにより処理することができる

省略時の条件ハンドラである XTPU$HANDLER については XTPU$FILEIO を参照してください。また，ユーザ独自の条件ハンドラを作成する方法については，『OpenVMS Programming Concepts Manual』を参照してください。

## 6.1.5 戻される値

DEC XTPU の条件コードはすべてユニバーサル・シンボルとして宣言されます。したがって，自分のプログラムを共有可能イメージにリンクすると，自動的にこれらのシンボルにアクセスできるようになります。DEC XTPU は条件コード値を R0 にセットします。DEC XTPU のリターン・コードについては，『DEC Text Processing Utility Reference Manual』を参照してください。DEC XTPU が返すリターン・コードとそのメッセージについては，Help/Message ファシリティを参照してください。

この後の節では，コール可能なDEC XTPU ルーチンの説明の中に条件コードに関する情報も示されています。この情報は“戻される条件値”という見出しの下に示されており，省略時の条件ハンドラが設定されているときに戻される値を示しています。

# 6.2 単純なコール可能インタフェース

DEC XTPU の単純なコール可能インタフェースは XTPU$XTPU と XTPU$EDIT という 2つのルーチンから構成されています。DEC XTPU に対するこれらのエントリ・ポイントは，以下のアプリケーションで使用することができます。

- 1行のコマンド・ラインにすべての編集パラメータを指定できるアプリケーション

- 入力ファイルと出力ファイルだけを指定するだけでよいアプリケーション

## 6.2.1 単純なインタフェースの例

以下の例は XTPU$EDIT を呼びだして，INFILE.DAT 中のテキストを編集し，その結果を OUTFILE.DAT に書き込みます。XTPU$EDIT に渡すパラメータはディスクリプタ渡しでなければなりません。

## 例

>     /*
>       Sample C program that calls DEC XTPU.  This program uses XTPU$EDIT to
>       provide the names of the input and output files
>     */

>     #include descrip

>     int return_status;

>     static $DESCRIPTOR (input_file, "infile.dat");
>     static $DESCRIPTOR (output_file, "outfile.dat");

>     main (argc, argv)
>         int argc;
>         char *argv[];

>         {
>         /*
>           Call DEC XTPU to edit text in "infile.dat" and write the result
>           to "outfile.dat".  Return the condition code from DEC XTPU as the
>           status of this program.
>         */

>         return_status = XTPU$EDIT (&input_file, &output_file);
>         exit (return_status);
>         }

以下の例は，上の例と同じ動作をします。ここではエントリ・ポイントとして XTPU$XTPUを使います。XTPU$XTPU は引数として "XTPU" で始まるコマンド文字列を受け取ります。コマンド文字列には "EDIT/XTPU" コマンドに使用できるすべての修飾子を使用できます。

## 例

>     /*
>       Sample C program that calls DEC XTPU.  This program uses XTPU$XTPU and
>       specifies a command string
>     */

>     #include descrip

>     int return_status;

>     static $DESCRIPTOR (command_prefix, "XTPU/NOJOURNAL/NOCOMMAND/OUTPUT=");
>     static $DESCRIPTOR (input_file, "infile.dat");
>     static $DESCRIPTOR (output_file, "outfile.dat");
>     static $DESCRIPTOR (space_desc, " ");

>     char command_line [100];
>     static $DESCRIPTOR (command_desc, command_line);

>     main (argc, argv)
>         int argc;
>         char *argv[];

>         {
>         /*
>           Build the command line for DEC XTPU.  Note that the command verb
>           is "XTPU".  The string we construct in the buffer command_line
>           will be
>             "XTPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat"
>         */

>         return_status = STR$CONCAT (&command_desc,
>                                     &command_prefix,
>                                     &output_file,
>                                     &space_desc,
>                                     &input_file);
>         if (! return_status)
>             exit (return_status);

>         /*
>           Now call DEC XTPU to edit the file
>         */
>         return_status = XTPU$XTPU (&command_desc);
>         exit (return_status);
>         }

以下の節では，完全なコール可能インタフェースによってコールされるルーチンについて，詳しく説明します。単純なコール可能インタフェースを使用した場合には，これらのルーチンが呼び出されます。完全なコール可能インタフェースを使用する場合には，直接これらのルーチンを呼び出します。

# 6.3 完全なコール可能インタフェース

DEC XTPU の完全なコール可能インタフェースは，以下の作業を実行するために使用できる複数のルーチンから構成されています。

- 初期化パラメータを指定する

- ファイルの入出力を制御する

- エディタが実行するコマンドを指定する

- 条件の処理方法を制御する

単純なコール可能インタフェースを使用する場合には，上記の操作は自動的に実行されます。これらの機能を実行する各DEC XTPU ルーチンはユーザ作成プログラムからコールすることができ，DEC XTPU の完全なコール可能インタフェースと呼ばれます。このインタフェースには2種類のルーチンが含まれています。それはDEC XTPU のコール可能なメイン・ルーチンとDEC XTPU ユーティリティ・ルーチンです。これらの DEC XTPU ルーチンと，DEC XTPU ルーチンにパラメータを渡すユーザ・ルーチンを使用することにより，アプリケーション・プログラムがDEC XTPU を制御します。

以降の節では，コール可能なメイン・ルーチン，これらのルーチンに対するパラメータの受渡し方法，DEC XTPU ユーティリティ・ルーチン，およびユーザ作成ルーチンの必要条件について説明します。

## 6.3.1 主なコール可能なDEC XTPU ユーティリティ・ルーチン

この節では，以下のコール可能なDEC XTPU ルーチンについて説明します。

- XTPU$INITIALIZE

- XTPU$EXECUTE_INIFILE

- XTPU$CONTROL

- XTPU$EXECUTE_COMMAND

- XTPU$CLEANUP

注意 これらのルーチンをコールする場合には， XTPU$HANDLER を設定するか，または独自の条件ハンドラを作成しなければなりません。条件ハンドラの設定について詳しくは，この章の終わりの XTPU$HANDLER ルーチンの説明と『OpenVMS Calling Standard』を参照してください。

## 6.3.2 その他のDEC XTPU ユーティリティ・ルーチン

完全なコール可能インタフェースには，他にもいくつかのユーティリティ・ルーチンが含まれており，これらのユーティリティ・ルーチンに対してパラメータを渡すことができます。アプリケーションによっては，自分のルーチンを作成せずに，これらのルーチンを使用することができます。以下に DEC XTPU ユーティリティ・ルーチンとその説明をします。

XTPU$CLIPARSE | コマンド・ラインを解析し，XTPU$INITIALIZE のためにアイテム・リストを作成する
XTPU$PARSEINFO | コマンドを解析し，XTPU$INITIALIZE のためにアイテム・リストを作成する
XTPU$FILEIO | 省略時のファイル入出力ルーチン
XTPU$MESSAGE | MESSAGE 組込みプロシージャを使ってエラー・メッセージと文字列を出力する
XTPU$HANDLER | 省略時の条件ハンドラ
XTPU$CLOSE_TERMINAL | CALL_USER ルーチンの実行中，ターミナルへの DEC XTPU のチャネルをクローズする
XTPU$SPECIFY_ASYNC_ACTION | XTPU$CONTROL ルーチンを中断する非同期イベントを指定する
XTPU$TRIGGER_ASYNC_ACTION | 特定の非同期イベントで XTPU$CONTROL ルーチンを中断する

XTPU$CLIPARSE と XTPU$PARSEINFO は，コマンドを解析するために CLI$ ルーチンによって保持されている内容を破壊します。

## 6.3.3 ユーザ作成ルーチン

この節では，ユーザ作成ルーチンの必要条件を定義します。これらのルーチンを DEC XTPU に渡す場合には，バウンド・プロシージャ値として渡さなければなりません (バウンド・プロシージャ値については 第 6.1.3 項 を参照してください)。各アプリケーションに応じて，以下に示されているルーチンの中から，1つまたはすべてを作成しなければなりません。

- 初期化コールバックのためのルーチン
  このルーチンは初期化パラメータの値を入手するために， XTPU$INITIALIZE がコールするルーチンです。初期化パラメータはアイテム・リストとして戻されます。

- ファイル入出力のためのルーチン
  このルーチンはファイル操作を処理するルーチンです。独自のファイル入出力ルーチンを作成するかわりに， XTPU$FILEIO ユーティリティ・ルーチンを使用することもできます。ただし，ジャーナル・ファイル操作や SAVE 組込みプロシージャによって実行される動作ではこのルーチンは使用されません。

- 条件処理のためのルーチン
  このルーチンはエラー条件を処理するルーチンです。独自の条件ハンドラを作成するかわりに，省略時の条件ハンドラである XTPU$HANDLER を使用することもできます。

- CALL_USER 組込みプロシージャのためのルーチン
  このルーチンは CALL_USER 組込みプロシージャがコールするルーチンです。このルーチンを使用すると，編集セッションからユーザ・プログラムに制御を渡すことができます。

# 6.4 DEC XTPU ルーチンの使用例

例 6_1 ， 例 6_2 ，および 例 6-3 は，コール可能な DECXTPU を使用したものです。これらの例は解説を目的としたものであり，DEC はこれらの信頼性について，その責任を負いません。

例 6-1 DEC FORTRAN における通常のDEC XTPU セットアップ
    C       A sample FORTRAN program that calls DEC XTPU to act
    C       normally, using the programmable interface.
    C
    C       IMPLICIT NONE

            INTEGER*4       CLEAN_OPT       !options for clean up routine
            INTEGER*4       STATUS          !return status from DEC XTPU routines
            INTEGER*4       BPV_PARSE(2)    !set up a Bound Procedure Value
            INTEGER*4       LOC_PARSE       !a local function call

    C       declare the DEC XTPU functions

            INTEGER*4       XTPU$CONTROL
            INTEGER*4       XTPU$CLEANUP
            INTEGER*4       XTPU$EXECUTE_INIFILE
            INTEGER*4       XTPU$INITIALIZE
            INTEGER*4       XTPU$CLIPARSE

    C       declare a local copy to hold the values of DEC XTPU cleanup variables

            INTEGER*4       RESET_TERMINAL
            INTEGER*4       DELETE_JOURNAL
            INTEGER*4       DELETE_BUFFERS,DELETE_WINDOWS
            INTEGER*4       DELETE_EXITH,EXECUTE_PROC
            INTEGER*4       PRUNE_CACHE,KILL_PROCESSES
            INTEGER*4       CLOSE_SECTION
            INTEGER*4       CLOSE_KANJI_DIC

    C       declare the DEC XTPU functions used as external

            EXTERNA         XTPU$HANDLER
            EXTERNAL        XTPU$CLIPARSE

            EXTERNAL        XTPU$_SUCCESS    !external error message

            EXTERNAL        LOC_PARSE       !user supplied routine to

    C                                       call TPUCLIPARSE and setup
    C       declare the DEC XTPU cleanup variables as external these are the
    C       external literals that hold the value of the options

            EXTERNAL        XTPU$M_RESET_TERMINAL
            EXTERNAL        XTPU$M_DELETE_JOURNAL
            EXTERNAL        XTPU$M_DELETE_BUFFERS,XTPU$M_DELETE_WINDOWS
            EXTERNAL        XTPU$M_DELETE_EXITH,XTPU$M_EXECUTE_PROC
            EXTERNAL        XTPU$M_PRUNE_CACHE,XTPU$M_KILL_PROCESSES
            EXTERNAL        XTPU$M_CLOSE_KANJI_DIC

    100     CALL LIB$ESTABLISH ( XTPU$HANDLER ) !establish the condition handler

    C       set up the Bound Procedure Value for the call to XTPU$INITIALIZE

            BPV_PARSE( 1 ) = %LOC( LOC_PARSE )
            BPV_PARSE( 2 ) = 0

    C       call the DEC XTPU initialization routine to do some set up work

            STATUS = XTPU$INITIALIZE ( BPV_PARSE )

    C       Check the status if it is not a success then signal the error

            IF ( STATUS .NE. %LOC ( XTPU$_SUCCESS ) ) THEN

                    CALL LIB$SIGNAL( %VAL( STATUS ) )
                    GOTO 9999

            ENDIF

    C       execute the XTPU$_ init files and also a command file if it
    C       was specified in the command line call to DEC XTPU

            STATUS = XTPU$EXECUTE_INIFILE ( )

            IF ( STATUS .NE. %LOC ( XTPU$_SUCCESS ) ) THEN

                    CALL LIB$SIGNAL( %VAL( STATUS ) )
                    GOTO 9999

            ENDIF

    C       invoke the editor as it normally would appear

            STATUS = XTPU$CONTROL ( )        !call the DEC XTPU editor

            IF ( STATUS .NE. %LOC ( XTPU$_SUCCESS ) ) THEN

                    CALL LIB$SIGNAL( %VAL( STATUS ) )
    C               GOTO 9999
            ENDIF

    C       Get the value of the option from the external literals.  In FORTRAN you
    C       cannot use external literals directly so you must first get the value
    C       of the literal from its external location.  Here we are getting the
    C       values of the options that we want to use in the call to XTPU$CLEANUP.

            DELETE_JOURNAL  = %LOC ( XTPU$M_DELETE_JOURNAL )
            DELETE_EXITH    = %LOC ( XTPU$M_DELETE_EXITH )
            DELETE_BUFFERS  = %LOC ( XTPU$M_DELETE_BUFFERS )
            DELETE_WINDOWS  = %LOC ( XTPU$M_DELETE_WINDOWS )
            EXECUTE_PROC    = %LOC ( XTPU$M_EXECUTE_PROC )
            RESET_TERMINAL  = %LOC ( XTPU$M_RESET_TERMINAL )
            KILL_PROCESSES  = %LOC ( XTPU$M_KILL_PROCESSES )
            CLOSE_SECTION   = %LOC ( XTPU$M_CLOSE_SECTION )
            CLOSE_KANJI_DIC = %LOC ( XTPU$M_CLOSE_KANJI_DIC )

    C       Now that we have the local copies of the variables we can do the
    C       logical OR to set the multiple options that we need.

            CLEAN_OPT = DELETE_JOURNAL .OR. DELETE_EXITH .OR.
            1       DELETE_BUFFERS .OR. DELETE_WINDOWS .OR. EXECUTE_PROC
            1       .OR. RESET_TERMINAL .OR. KILL_PROCESSES .OR. CLOSE_SECTION
            1       .OR. CLOSE_KANJI_DIC

    C       do the necessary clean up
    C       XTPU$CLEANUP wants the address of the flags as the parameter so
    C       pass the %LOC of CLEAN_OPT which is the address of the variable

            STATUS = XTPU$CLEANUP ( %LOC ( CLEAN_OPT ) )

            IF ( STATUS .NE. %LOC (XTPU$_SUCCESS) ) THEN

                    CALL LIB$SIGNAL( %VAL(STATUS) )

            ENDIF

    9999    CALL LIB$REVERT         !go back to normal processing -- handlers

            STOP
            END

    C
    C
            INTEGER*4  FUNCTION LOC_PARSE

            INTEGER*4       BPV(2)          !A local Bound Procedure Value

            CHARACTER*13    EDIT_COMM       !A command line to send to XTPU$CLIPARSE

    C       Declare the DEC XTPU functions used

            INTEGER*4       XTPU$FILEIO
            INTEGER*4       XTPU$CLIPARSE

    C       Declare this routine as external because it is never called directly and
    C       we need to tell FORTRAN that it is a function and not a variable

            EXTERNAL        XTPU$FILEIO

            BPV(1) = %LOC(XTPU$FILEIO)       !set up the BOUND PROCEDURE VALUE
            BPV(2) = 0

            EDIT_COMM(1:18) = 'EDIT/XTPU TEST.TXT'

    C       parse the command line and build the item list for XTPU$INITIALIZE
    9999     LOC_PARSE = XTPU$CLIPARSE (EDIT_COMM, BPV , 0)

            RETURN
            END

前へ | 次へ | 目次 | 索引