日本語 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 への入力として，また出力として，ファイルを使用することができます。さらに入力，出力，およびメッセージを処理するために独自のルーチンを作成することもできます。

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

コール可能な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 には，これらの作業の一部を実行できるユーティリティ・ルーチンが準備されています。これらのユーティリティ・ルーチンは以下の操作を実行することができます。

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

第 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通りの方法でエラーを処理することができます。

省略時の条件ハンドラである 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 に対するこれらのエントリ・ポイントは，以下のアプリケーションで使用することができます。

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$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つまたはすべてを作成しなければなりません。

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

前へ 次へ 目次 索引