[ 前のページ ] [ 次のページ ] [ 目次 ] [ 索引 ] [ DOC Home ]

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節で詳しく説明します。

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

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

エディタを初期化する 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のリンク方法については, 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$XTPUXTPU$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

例 6-2 DEC FORTRANでのコール・バック項目リストの作成

       PROGRAM  TEST_TPU
C
       IMPLICIT NONE
C
C       Define the expected DEC XTPU return statuses
C
       EXTERNAL        XTPU$_SUCCESS
       EXTERNAL        XTPU$_QUITTING

C
C       Declare the DEC XTPU routines and symbols used
C
       EXTERNAL        XTPU$M_DELETE_CONTEXT
       EXTERNAL        XTPU$HANDLER
       INTEGER*4       XTPU$M_DELETE_CONTEXT
       INTEGER*4       XTPU$INITIALIZE
       INTEGER*4       XTPU$EXECUTE_INIFILE
       INTEGER*4       XTPU$CONTROL
       INTEGER*4       XTPU$CLEANUP

C
C        Declare the external callback routine
C
       EXTERNAL        TPU_STARTUP       ! the DEC XTPU set-up function
       INTEGER*4       TPU_STARTUP

       INTEGER*4       BPV(2)            ! Set up a bound procedure value

C
C       Declare the functions used for working with the condition handler
C       
       INTEGER*4       LIB$ESTABLISH
       INTEGER*4       LIB$REVERT

C
C       Local Flags and Indices
C
       INTEGER*4       CLEANUP_FLAG       ! flag(s) for DEC XTPU cleanup
       INTEGER*4       RET_STATUS

C
C      Initializations
C
       RET_STATUS       = 0
       CLEANUP_FLAG     = %LOC(XTPU$M_DELETE_CONTEXT)

C
C      Establish the default DEC XTPU condition handler
C
       CALL LIB$ESTABLISH(%REF(XTPU$HANDLER))

C
C      Set up the bound procedure value for the initialization callback
C
       BPV(1)  =  %LOC (TPU_STARTUP)
       BPV(2)  =  0

C
C      Call the DEC XTPU procedure for initialization
C
       RET_STATUS = XTPU$INITIALIZE(BPV)

       IF (RET_STATUS .NE. %LOC(XTPU$_SUCCESS)) THEN
       CALL LIB$SIGNAL (%VAL(RET_STATUS))
       ENDIF

C
C      Execute the DEC XTPU initialization file
C
       RET_STATUS = XTPU$EXECUTE_INIFILE()

       IF (RET_STATUS .NE. %LOC(XTPU$_SUCCESS)) THEN
       CALL LIB$SIGNAL (%VAL(RET_STATUS))
       ENDIF

C
C      Pass control to DEC XTPU
C
       RET_STATUS = XTPU$CONTROL()

       IF (RET_STATUS .NE. %LOC(XTPU$_QUITTING)
     1         .OR. %LOC(XTPU$_QUITTING)) THEN
               CALL LIB$SIGNAL (%VAL(RET_STATUS))
       ENDIF

C
C      Clean up after processing
C
       RET_STATUS = XTPU$CLEANUP(%REF(CLEANUP_FLAG))

       IF (RET_STATUS .NE. %LOC(XTPU$_SUCCESS)) THEN
       CALL LIB$SIGNAL (%VAL(RET_STATUS))
       ENDIF

C
C      Set the condition handler back to the default
C
       RET_STATUS = LIB$REVERT()

       END

       INTEGER*4 FUNCTION TPU_STARTUP

       IMPLICIT NONE

       INTEGER*4       OPTION_MASK       ! temporary variable for DEC XTPU
       CHARACTER*44       SECTION_NAME   ! temporary variable for DEC XTPU

C
C      External DEC XTPU routines and symbols
C
       EXTERNAL        XTPU$K_OPTIONS
       EXTERNAL        XTPU$M_READ
       EXTERNAL        XTPU$M_SECTION
       EXTERNAL        XTPU$M_DISPLAY
       EXTERNAL        XTPU$K_SECTIONFILE
       EXTERNAL        XTPU$K_FILEIO
       EXTERNAL        XTPU$FILEIO
       INTEGER*4       XTPU$FILEIO

C
C      The bound procedure value used for setting up the file I/O routine
C
       INTEGER*4       BPV(2)

C
C       Define the structure of the item list defined for the callback
C
       STRUCTURE /CALLBACK/
       INTEGER*2       BUFFER_LENGTH
       INTEGER*2       ITEM_CODE
       INTEGER*4       BUFFER_ADDRESS
       INTEGER*4       RETURN_ADDRESS
       END STRUCTURE

C
C      There are a total of four items in the item list
C
       RECORD /CALLBACK/ CALLBACK (4)

C
C      Make sure it is not optimized!
C
       VOLATILE /CALLBACK/

C
C       Define the options we want to use in the DEC XTPU session
C
       OPTION_MASK = %LOC(XTPU$M_SECTION) .OR. %LOC(XTPU$M_READ)
     1        .OR. %LOC(XTPU$M_DISPLAY)

C
C      Define the name of the initialization section file
C
       
       SECTION_NAME = 'SYS$SHARE:JEVE$SECTION_V3.XTPU$SECTION'

C
C      Set up the required I/O routine.  Use the DEC XTPU default.
C
       BPV(1) = %LOC(XTPU$FILEIO)
       BPV(2) = 0

C
C      Build the callback item list
C
C      Set up the edit session options
C
       CALLBACK(1).ITEM_CODE = %LOC(XTPU$K_OPTIONS)
       CALLBACK(1).BUFFER_ADDRESS = %LOC(OPTION_MASK)
       CALLBACK(1).BUFFER_LENGTH = 4
       CALLBACK(1).RETURN_ADDRESS = 0

C
C      Identify the section file to be used
C
       CALLBACK(2).ITEM_CODE = %LOC(XTPU$K_SECTIONFILE)
       CALLBACK(2).BUFFER_ADDRESS = %LOC(SECTION_NAME)
       CALLBACK(2).BUFFER_LENGTH = LEN(SECTION_NAME)
       CALLBACK(2).RETURN_ADDRESS = 0

C
C      Set up the I/O handler
C
       CALLBACK(3).ITEM_CODE = %LOC(XTPU$K_FILEIO)
       CALLBACK(3).BUFFER_ADDRESS = %LOC(BPV)
       CALLBACK(3).BUFFER_LENGTH = 4
       CALLBACK(3).RETURN_ADDRESS = 0

C
C      End the item list with zeros to indicate we are finished
C
       CALLBACK(4).ITEM_CODE = 0
       CALLBACK(4).BUFFER_ADDRESS = 0
       CALLBACK(4).BUFFER_LENGTH = 0
       CALLBACK(4).RETURN_ADDRESS = 0

C
C      Return the address of the item list
C
       TPU_STARTUP = %LOC(CALLBACK)
       RETURN
       END

例 6-3 DEC Cでのユーザ作成ファイルの入出力ルーチンの指定

/*
Simple example of a C program to invoke DEC XTPU.  This program provides its
own FILEIO routine instead of using the one provided by DEC XTPU.
*/
#include descrip
#include stdio

/* data structures needed */

struct bpv_arg                  /* bound procedure value */
    {
    int *routine_add ;          /* pointer to routine */
    int env ;                   /* environment pointer */
    } ;

struct item_list_entry          /* item list data structure */
    {
    short int buffer_length;    /* buffer length */
    short int item_code;        /* item code */
    int *buffer_add;            /* buffer address */
    int *return_len_add;        /* return address */
    } ;

struct stream_type
    {
    int ident;                  /* stream id */
    short int alloc;            /* file size */
    short int flags;            /* file record attributes/format */
    short int length;           /* resultant file name length */
    short int stuff;            /* file name descriptor class & type */
    int nam_add;                /* file name descriptor text pointer */
    } ;

globalvalue xtpu$_success;       /* DEC XTPU Success code */
globalvalue xtpu$_quitting;      /* Exit code defined by DEC XTPU */

globalvalue                     /* Cleanup codes defined by DEC XTPU */
    xtpu$m_delete_journal, xtpu$m_delete_exith,
    xtpu$m_delete_buffers, xtpu$m_delete_windows, xtpu$m_delete_cache,
    xtpu$m_prune_cache, xtpu$m_execute_file, xtpu$m_execute_proc,
    xtpu$m_delete_context, xtpu$m_reset_terminal, xtpu$m_kill_processes,
    xtpu$m_close_section, xtpu$m_delete_others, xtpu$m_last_time;

globalvalue                     /* Item codes for item list entries */
    xtpu$_fileio, xtpu$_options, xtpu$_sectionfile,
    xtpu$_commandfile ;

globalvalue                     /* Option codes for option item */
    xtpu$m_display, xtpu$m_section, xtpu$m_command, xtpu$m_create ;
    
globalvalue                     /* Possible item codes in item list */
    xtpu$k_access, xtpu$k_filename, xtpu$k_defaultfile,
    xtpu$k_relatedfile, xtpu$k_record_attr, xtpu$k_maximize_ver,
    xtpu$k_flush, xtpu$k_filesize;

globalvalue                     /* Possible access types for xtpu$k_access */
    xtpu$k_io, xtpu$k_input, xtpu$k_output;

globalvalue                     /* RMS File Not Found message code */
    rms$_fnf;

globalvalue                     /* FILEIO routine functions */
    xtpu$k_open, xtpu$k_close, xtpu$k_close_delete,
    xtpu$k_get, xtpu$k_put;
int lib$establish ();           /* RTL routine to establish an event handler */
int xtpu$cleanup ();            /* XTPU routine to free resources used */
int xtpu$control ();            /* XTPU routine to invoke the editor */
int xtpu$execute_inifile ();    /* XTPU routine to execute initialization code */
int xtpu$handler ();            /* XTPU signal handling routine */
int xtpu$initialize ();         /* XTPU routine to initialize the editor */

/*
   This function opens a file for either read or write access, based upon
   the itemlist passed as the data parameter.  Note that a full implementation
   of the file open routine would have to handle the default file, related
   file, record attribute, maximize version, flush and file size item code
   properly.
 */
open_file (data, stream)

int *data;
struct stream_type *stream;

{
    struct item_list_entry *item;
    char *access;               /* File access type */
    char filename[256];         /* Max file specification size */

    /* Process the item list */

    item = data;
    while (item->item_code != 0 && item->buffer_length != 0)
        {
        if (item->item_code == xtpu$k_access)
            {
            if (item->buffer_add == xtpu$k_io) access = "r+";
            else if (item->buffer_add == xtpu$k_input) access = "r";
            else if (item->buffer_add == xtpu$k_output) access = "w";
            }

        else if (item->item_code == xtpu$k_filename)
            {
            strncpy (filename, item->buffer_add, item->buffer_length);
            filename [item->buffer_length] = 0;
            lib$scopy_r_dx (&item->buffer_length, item->buffer_add,
                                                        &stream->length);
            }

        else if (item->item_code == xtpu$k_defaultfile)
            {                           /* Add code to handle default file  */
            }                           /* spec here                        */

        else if (item->item_code == xtpu$k_relatedfile)
            {                           /* Add code to handle related       */
            }                           /* file spec here                   */

        else if (item->item_code == xtpu$k_record_attr)
            {                           /* Add code to handle record        */
            }                           /* attributes for creating files    */

        else if (item->item_code == xtpu$k_maximize_ver)
            {                           /* Add code to maximize version     */
            }                           /* number with existing file here   */

        else if (item->item_code == xtpu$k_flush)
            {                           /* Add code to cause each record    */
            }                           /* to be flushed to disk as written */
        
        else if (item->item_code == xtpu$k_filesize)
            {                           /* Add code to handle specification */
            }                           /* of initial file allocation here  */
        ++item;         /* get next item */
        }
    stream->ident = fopen(filename,access);
    if (stream->ident != 0)
        return xtpu$_success;
    else
        return rms$_fnf;
}
/*
  This procedure closes a file
 */
close_file (data,stream)
struct stream_type *stream;

{
    close(stream->ident);
    return xtpu$_success;
}

/*
  This procedure reads a line from a file
 */
read_line(data,stream)
struct dsc$descriptor *data;
struct stream_type *stream;

{
    char textline[984];                 /* max line size for XTPU records */
    int len;

    globalvalue rms$_eof;               /* RMS End-Of-File code */

    if (fgets(textline,984,stream->ident) == NULL)
        return rms$_eof;
    else
        {
        len = strlen(textline);
        if (len> 0)
            len = len - 1;
        return lib$scopy_r_dx (&len, textline, data);
        }
}

/*
  This procedure writes a line to a file
 */
write_line(data,stream)
struct dsc$descriptor *data;
struct stream_type *stream;

{
    char textline[984];                 /* max line size for XTPU records */

    strncpy (textline, data->dsc$a_pointer, data->dsc$w_length);
    textline [data->dsc$w_length] = 0;
    fputs(textline,stream->ident);
    fputs("\n",stream->ident);
    return xtpu$_success;
}

/*
   This procedure will handle I/O for XTPU
 */
fileio(code,stream,data)
int *code;
int *stream;
int *data;

{
    int status;

/* Dispatch based on code type.  Note that a full implementation of the      */
/* file I/O routines would have to handle the close and delete code properly */
/* instead of simply closing the file                                        */

    if (*code == xtpu$k_open)                    /* Initial access to file */
        status = open_file (data,stream);
    else if (*code == xtpu$k_close)              /* End access to file */
        status = close_file (data,stream);
    else if (*code == xtpu$k_close_delete)       /* Treat same as close */
        status = close_file (data,stream);

    else if (*code == xtpu$k_get)                /* Read a record from a file */
        status = read_line (data,stream);
    else if (*code == xtpu$k_put)                /* Write a record to a file */
        status = write_line (data,stream);
    else
        {                                       /* Who knows what we got? */
        status = xtpu$_success;
        printf ("Bad FILEIO I/O function requested");
        }
    return status;
}

/*
   This procedure formats the initialization item list and returns it as
   is return value.
 */
callrout()
{
    static struct bpv_arg add_block =
        { fileio, 0 } ;         /* BPV for fileio routine */
    int options ;
    char *section_name = "XTPU$SECTION";
    static struct item_list_entry arg[4];

    /* Setup file I/O routine item entry */
    arg[0].item_code = (unsigned short int) xtpu$_fileio;
    arg[0].buffer_length = 4;
    arg[0].buffer_add = &add_block;
    arg[0].return_len_add = 0;

    /* Setup options item entry.  Leave journaling off. */
    options = xtpu$m_display | xtpu$m_section;
    arg[1].item_code = (unsigned short int) xtpu$_options;
    arg[1].buffer_length = 4;
    arg[1].buffer_add = &options;
    arg[1].return_len_add = 0;

    /* Setup section file name */
    arg[2].item_code = (unsigned short int) xtpu$_sectionfile;
    arg[2].buffer_length = strlen(section_name);
    arg[2].buffer_add = section_name;
    arg[2].return_len_add = 0;

    arg[3].item_code = 0;
    arg[3].buffer_length = 0;
    arg[3].buffer_add = 0;
    arg[3].return_len_add = 0;

    return arg;
}

/*
   Main program.  Initializes XTPU, then passes control to it.
 */
main()
{
    int return_status ;
    int cleanup_options;
    struct bpv_arg add_block;

/* Establish as condition handler the normal DEC XTPU handler */

    lib$establish(xtpu$handler);

/* Setup a BPV to point to the callback routine */

    add_block.routine_add = callrout ;
    add_block.env = 0;

/* Do the initialize of XTPU */

    return_status = xtpu$initialize(&add_block);
    if (!return_status)
        exit(return_status);

/* Have XTPU execute the procedure XTPU$INIT_PROCEDURE from the section file */
/* and then compile and execute the code from the command file */

    return_status = xtpu$execute_inifile();
    if (!return_status)
        exit (return_status);

/* Turn control over to XTPU */

    return_status = xtpu$control ();
    if (!return_status)
        exit(return_status);

/* Now clean up. */

    cleanup_options = xtpu$m_last_time | xtpu$m_delete_context;
    return_status = xtpu$cleanup (&cleanup_options);
    exit (return_status);

    printf("Experiment complete");
}


6.5 DEC XTPUルーチン

この節では,ルーチン・テンプレート形式で個々のDEC XTPUルーチンを説明します。


FILEIO

DEC XTPUでファイルの処理を行うのに使用するユーザ定義のファイル入出力ルーチンです。 このルーチンの名前は,ユーザが作成した独自のファイル入出力ルーチン, またはDEC XTPUのファイル入出力ルーチンの名前(XTPU$FILEIO)です。


形式

     FILEIO   code, stream, data 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 参照による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

code

OpenVMS用法  符号なしロングワード
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

実行する機能を指定するDEC XTPUからのアイテム・コードです。 code 引数は実行する機能を指定する DEC XTPUからのアイテム・コードを含むロングワードのアドレスです。

stream

OpenVMS用法  未指定
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

ファイル記述です。 stream 引数は,4つのロングワードを含むデータ構造のアドレスです。 このデータ構造は,操作するファイルを記述するために使用されます。

data

OpenVMS用法  アイテム・リスト3
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

ストリーム・データです。 data 引数はアイテム・リストのアドレス,またはディスクリプタのアドレスです。

このパラメータの値は,どのアイテム・コードを指定したかによって異なります。


説明

このルーチンのバウンド・プロシージャ値は, コールバック・ルーチンによって作成されたアイテム・リストで指定されます。 このルーチンはファイル操作を実行するためにコールされます。 ユーザが作成した独自のファイル入出力ルーチンを使用するかわりに, XTPU$FILEIOをコールし, ユーザが自分で処理したくないファイル操作に対するパラメータを渡すことができます。 しかし,XTPU$FILEIOは,それがオープンしたファイルに対して, すべての入出力要求を処理しなければなりません。 また,XTPU$FILEIOがファイルをオープンしなかった場合には, そのファイルに対する入出力要求を処理することはできません。 言い換えれば,ユーザ作成ファイル入出力ルーチンと DEC XTPUから提供されるルーチンとを組み合わせて,ファイル操作を実行することはできません。


戻される条件値

戻される条件値はユーザによって決められ,操作の正常終了あるいは失敗を指示します。


HANDLER

このルーチンは,条件処理を実行するユーザ作成ルーチンです。


形式

     HANDLER   signal_vector, mechanism_vector 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。


引数

signal_vector

OpenVMS用法  引数リスト
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

シグナル・ベクタです。条件ハンドラに渡されるシグナル・ベクタについての説明は, 『OpenVMS System Services Reference Manual』を参照してください。

mechanism_vector

OpenVMS用法  引数リスト
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

メカニズム・ベクタです。 条件ハンドラに渡されるメカニズム・ベクタについての説明は, 『OpenVMS System Services Reference Manual』を参照してください。


説明

条件ハンドラの作成方法と, OpenVMS条件処理標準についての詳しい説明が必要な場合には, 『OpenVMS Programming Interfaces: Calling a System Routine』または 『OpenVMS Calling Standard』を参照してください。

自分で独自の条件ハンドラを作成するかわりに, 省略時の条件ハンドラであるXTPU$HANDLERを使用することができます。 独自のルーチンを作成したい場合には,DEC XTPUの内部シグナルを操作するために, ユーザの作成したルーチンが受け取ったものと全く同じパラメータで XTPU$HANDLERをコールする必要があります。


INITIALIZE

このルーチンは,XTPU$INITIALIZEにバウンド・プロシージャ値として渡され, DEC XTPUを初期化するために必要な情報を供給するために呼び出されます。


形式

     INITIALIZE   [user_arg] 


戻り値

OpenVMS用法  アイテム・リスト
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 参照による

このルーチンは,アイテム・リストのアドレスを返します。


引数

user_arg

OpenVMS用法  ユーザ引数
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 値による


説明

このユーザ作成初期化コールバック・ルーチンは, XTPU$INITIALIZEにバウンド・プロシージャ値として渡され, DEC XTPUを初期化するのに必要な情報を与えるために呼び出されます。

XTPU$INITIALIZEで user_arg パラメータが指定された時には, 初期化コールバック・ルーチンは,そのパラメータだけを使って呼ばれます。 XTPU$INITIALIZEで user_arg パラメータが指定されなかった時には, 初期化コールバック・ルーチンはパラメータなしで呼ばれます。

パラメータ user_arg によって, アプリケーションはXTPU$INITIALIZEを通してユーザによって書かれた初期化ルーチンに情報を渡すことができます。 DEC XTPUはこのデータを解釈しません。

この初期化コールバック・ルーチンは, 初期化パラメータのアイテム・リストのアドレスを返すものと期待されています。 そのアイテム・リストはこの初期化コールバック・ルーチンのスコープの外で用いられるため, 静的メモリ内に割り当てられる必要があります。

このアイテム・リスト・エントリはXTPU$INITIALIZEのセクションに記述されています。 ほとんどの初期化パラメータには省略値があります。 省略時の文字列はヌル文字列です。省略時のフラグはFALSEです。 唯一必要な初期化パラメータはファイル入出力のためのルーチンのアドレスです。 ファイル入出力ルーチンのアドレスがアイテム・リストにないと, XTPU$INITIALIZEはfailure statusを返します。


USER

このルーチンを使用すれば, ユーザ・プログラムはDEC XTPU編集セッションで制御を受け取ることができます (たとえば,エディタを一時的に終了し,計算を実行する場合などです)。

このユーザ作成ルーチンは,DEC XTPUのCALL_USER組込みプロシージャによって呼び出されます。 CALL_USER組込みプロシージャはこのルーチンに2つのパラメータを渡します。 次に,これらのパラメータは,アプリケーションの適切な部分に渡され, 指定されているとおりに使用されます(たとえば, FORTRANプログラムで計算オペランドとして使用することができます)。 ランタイム・ライブラリが提供する文字列ルーチンを使って, ユーザ・アプリケーションはコールユーザ・ルーチンで stringout パラメータに値を格納し,stringout の値をCALL_USER組込みプロシージャに戻します。


形式

     USER   integer, stringin, stringout 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。


引数

integer

OpenVMS用法  符号なしロングワード
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

CALL_USER組込みプロシージャに渡される最初のパラメータです。 これは入力専用パラメータであり,変更してはなりません。

stringin

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

CALL_USER組込みプロシージャに渡される2番目のパラメータです。 これは入力専用パラメータであり,変更してはなりません。

stringout

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

この文字列は,CALL_USER組込みプロシージャの return value として使用されます。 ユーザ・プログラムは, ランタイム・ライブラリが提供する文字列ルーチンから割り当てられた動的文字列をこのディスクリプタに格納しなければなりません。 DEC XTPUエディタは,必要な場合,この文字列を解放します。


説明

『DEC Text Processing Utility Reference Manual』の CALL_USER組込みプロシージャの説明には, コールユーザ・ルーチンを示したBASICプログラムの実例が含まれているので参照してください。


     INTEGER FUNCTION XTPU$CALLUSER  (x,y,z)
         IMPLICIT NONE
         INTEGER X
         CHARACTER*(*) Y
         STRUCTURE /dynamic/ Z
                   INTEGER*2 length
                   BYTE    dtype
                   BYTE    class
                   INTEGER ptr
         END STRUCTURE
         RECORD /dynamic/ Z
         CHARACTER*80 local_copy
         INTEGER rs,lclen
         INTEGER STR$COPY_DX
         local_copy = '<' // y // '>'
         lclen = LEN (Y) + 2

         RS = STR$COPY_DX(Z,local_copy(1:lclen))
         XTPU$CALLUSER = RS
         END

このFORTRANプログラムをDEC XTPUプロシージャとしてコールすることができます。 以下はそのようなプロシージャの例の1つです:

     PROCEDURE MY_CALL
          local status;
          status := CALL_USER (0,'ABCD');
          MESSAGE('"' + status + '"');
     ENDPROCEDURE


XTPU$CLEANUP

内部データ構造をクリーンアップし,メモリを解放し,ターミナルを初期状態に戻します。 これは最後にコールされるルーチンです。


形式

     XTPU$CLEANUP   flags 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはすべて, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値については, "戻される条件値" にまとめられています。


引数

flags

OpenVMS用法  ロングワード・マスク
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

クリーンアップ・オプションを定義するフラグ(あるいはマスク)です。 flags 引数は,クリーンアップ・オプションを定義するロングワード・ビット・マスクのアドレス, または32ビット・マスクのアドレスです。 このマスクは,セットしたいフラグ・ビットの論理和(OR)です。 XTPU$V...はビット・アイテムを示し,XTPU$M...はマスクを示します。 クリーンアップ・オプションは表 6-1に示されているとおりです。

表 6-1 クリーンアップ・オプション

シンボル[1] 機能
XTPU$M_CLOSE_KANJI_DIC かな漢字変換辞書をオープンしていた場合,かな漢字変換辞書をクローズします。
XTPU$M_CLOSE_KANJI_DIC かな漢字変換辞書をオープンしていた場合,かな漢字変換辞書をクローズします。
XTPU$M_CLOSE_SECTION[2] セクション・ファイルをクローズし,関連するメモリを解放します。 バッファ,ウィンドウ,およびプロセスがすべて削除されます。キャッシュは整理され, 初期化ファイルと初期化プロシージャの再実行のためのフラグがセットされます。 セクションがクローズされ, しかもオプション・ビットがSECTION修飾子の存在を示している場合には, 次にXTPU$INITIALIZEをコールすると,新しいセクション・ファイルが読み込まれます。
XTPU$M_DELETE_BUFFERS すべてのテキスト・バッファを削除します。 このあともDEC XTPUをコールする場合には,これらのデータ構造を参照する変数はすべて, DELETE組込みプロシージャの場合と同様にリセットされます。 バッファが削除される場合には,そのバッファに含まれるレンジとマーカ, およびそのバッファを使用するサブプロセスもすべて削除されます。
XTPU$M_DELETE_CACHE 仮想ファイル・マネージャのデータ構造とキャッシュを削除します。 この削除が要求された場合には,バッファもすべて削除されます。 キャッシュが削除される場合には,次にコールされるときに, 初期化ルーチンは仮想ファイル・マネージャを再初期化しなければなりません。
XTPU$M_DELETE_CONTEXT DEC XTPUのコンテキスト全体を削除します。 このオプションが指定されている場合には, 初期化ファイルと初期化プロシージャの実行のためのオプションを除き, 他のオプションもすべて指定されているものと解釈されます。
XTPU$M_DELETE_EXITH DEC XTPUの終了ハンドラを削除します。
XTPU$M_DELETE_JOURNAL ジャーナル・ファイルがオープンされている場合には, そのファイルをクローズし,削除します。
XTPU$M_DELETE_OTHERS 前もって割り当てられているすべてのデータ構造を削除します。 これらのデータ構造のために使用されていたメモリは, 次にXTPU$INITIALIZEをコールするときに再割り当てされます。
XTPU$M_DELETE_WINDOWS すべてのウィンドウを削除します。 このあともDEC XTPUをコールする場合には, これらのデータ構造を参照する変数はすべて, DELETE組込みプロシージャの場合と同様にリセットされます。
XTPU$M_EXECUTE_FILE XTPU$EXECUTE_INIFILEをもう一度コールしたときに, コマンド・ファイルを再実行します。 コマンド・ファイルに新しいファイル名を指定したい場合には, このビットをセットしなければなりません。 このオプションは/COMMAND修飾子の存在を示すために, XTPU$INITIALIZEに渡されるオプション・ビットといっしょに使用します。
XTPU$M_EXECUTE_PROC XTPU$INIT_PROCEDUREを検索し, XTPU$EXECUTE_INIFILEが次にコールされたときに,XTPU$INIT_PROCEDUREを実行します。
XTPU$M_KILL_PROCESSES セッションで生成されたすべてのサブプロセスを削除します。
XTPU$M_LAST_TIME このビットは,DEC XTPUを最後にコールする場合にだけセットしなければなりません。 このビットをセットしたのに,そのあとでDEC XTPUをコールした場合には, 結果は予測できないものとなります。
XTPU$M_PRUNE_CACHE バッファにページが割り当てられていない仮想ファイル・マネージャ・キャッシュをすべて解放します。 このオプションは,セッションで作成されたあと, 現在は不要になったキャッシュを解放します。
XTPU$M_RESET_TERMINAL DEC XTPUを起動したときの状態にターミナルをリセットします。 ターミナル・メールボックスとウィンドウもすべて削除されます。 ターミナルがリセットされた場合には,次にXTPU$INITIALIZEをコールするときに, ターミナルは再初期化されます。
[1] プリフィックスは XTPU$M_ または XTPU$V_ です。XTPU$M_ は, ビットがセットされるマスクが特定のフィールドに対応することを示しています。 XTPU$V_ はビット番号です。

[2] 単純なコール可能インターフェイスを使用する場合には, XTPU$CLOSE_SECTION はセットされません。 この機能を使用すれば,XTPU$XTPU を2回以上呼び出すときに, コールする度にセクション・ファイルをオープン/クローズされません。


説明

クリーンアップ・ルーチンは,DEC XTPUを使用するときに, 最後にコールしなければならないルーチンです。 このルーチンは,内部データ構造をクリーンアップし, 次の呼び出しのための準備をするように,DEC XTPUに指示を与えます。 このルーチンが何をリセットするかは, 上記のフラグをセットまたはクリアすることによって,制御することができます。

DEC XTPUの使用を終了する場合には,このルーチンをコールすることにより, メモリを解放し,ターミナルの設定を初期状態に戻しておかなければなりません。

XTPU$CLEANUPをコールしたあとすぐにユーザ・アプリケーションを終了する場合には, データ構造を削除しないでください。OpenVMSが自動的にデータ構造を削除します。 OpenVMSシステムがデータ構造を削除することで,プログラムの性能は向上します。


注意

  1. 単純なインターフェイスを使用する場合には, DEC XTPUは以下のフラグを自動的にセットします。

    • XTPU$V_DELETE_BUFFERS

    • XTPU$V_DELETE_EXITH

    • XTPU$V_DELETE_JOURNAL

    • XTPU$V_DELETE_WINDOWS

    • XTPU$V_EXECUTE_FILE

    • XTPU$V_EXECUTE_PROC

    • XTPU$V_KILL_PROCESSES

    • XTPU$V_PRUNE_CACHE

    • XTPU$V_RESET_TERMINAL

  2. このルーチンがサクセス・ステータスを戻さなかった場合には, 再度エディタを呼び出さないようにしなければなりません。


戻される状件値

XTPU$_SUCCESS  正常終了したことを示します。


XTPU$CLIPARSE

コマンド・ラインを解析し,XTPU$INITIALIZEのためにアイテム・リストを作成します。

このルーチンは,CLI$DCL_PARSEをコールし, 解析するコマンドとコマンド・テーブルを設定します。 次にXTPU$PARSEINFOをコールし,XTPU$INITIALIZEのためにアイテム・リストを作成します。

ユーザのアプリケーションがDEC XTPUの動作に無関係の情報をコマンド・ラインから解析している時には, アプリケーションはXTPU$CLIPARSEを呼び出す前にすべての情報の解析を終っていなければなりません。 XTPU$CLIPARSEはXTPU$CLIPARSEを呼びだす前に得たコマンド行の解析の情報を破壊します。


形式

     XTPU$CLIPARSE   string, fileio, call_user 


戻り値

OpenVMS用法  アイテム・リスト
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

このルーチンはアイテム・リストのアドレスを返します。


引数

string

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

コマンド・ラインです。 string 引数は,DEC XTPUコマンドのディスクリプタのアドレスです。

fileio

OpenVMS用法  符号なしロングワード・ベクタ
データ型 バウンド・プロシージャ値
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

ファイル入出力ルーチンです。 fileio 引数は,ファイル入出力ルーチンのデスクリプタのアドレスです。

call_user

OpenVMS用法  符号なしロングワード・ベクタ
データ型 バウンド・プロシージャ値
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

コールユーザ・ルーチンです。 call_user 引数は,コールユーザ・ルーチンのディスクリプタのアドレスです。


XTPU$CLOSE_TERMINAL

このルーチンはターミナルへのチャネルをクローズします。


形式

     XTPU$CLOSE_TERMINAL


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンのほとんどは, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値については, "戻される条件値" にまとめられています。


引数

なし


説明

このルーチンはCALL_USER組込みプロシージャと対応するコールユーザ・ルーチンとともに用いて, DEC XTPUの端末へのアクセスを制御します。 コールユーザ・ルーチンがXTPU$CLOSE_TERMINALを呼ぶと, DEC XTPUは端末へのチャネルと,対応するDEC XTPUのメイル・ボックスをクローズします。

コールユーザ・ルーチンから制御が戻されると, DEC XTPUは自動的に端末へのチャネルを再オープンし, 他のウィンドウで隠されていないウィンドウを再表示します。

コールユーザ・ルーチンは, そのプログラム中でいつでもXTPU$CLOSE_TERMINALを使用することができます。 また,必要に応じて何度でも使用することができます。 XTPU$CLOSE_TERMINALを使用したときに, すでにターミナルがクローズされている場合は,そのコールは無視されます。


戻される状件値

 XTPU$_SUCCESS  正常終了したことを示します。


XTPU$CONTROL

DEC XTPUエディタのメイン処理ルーチンです。このルーチンは, テキストとコマンドを読み取り,それを実行します。 このルーチンをコールすると(XTPU$INITIALIZEをコールしたあと),制御はDEC XTPUに渡されます。


形式

     XTPU$CONTROL   [integer] 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

integer

OpenVMS用法  整数
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

呼び出しプログラムがDEC XTPUに制御を渡した時に, "Editing Session is not being journaled" というメッセージが表示されないようにします。 将来のコンパティビリティを保つために,真(奇数)の整数を指定してください。 引数を省略した場合,ジャーナリングされていないときには, DEC XTPU はメッセージを表示します。


説明

このルーチンは編集セッションを制御します。 このルーチンは,テキストとコマンドを読み取り,それを実行します。 実行された編集内容を示すように,スクリーン上のウィンドウが更新されます。 XTPU$SPECIFY_ASYN_ACTIONルーチンをXTPU$TRIGGER_ASYN_ACTIONルーチンとともに使って, DEC XTPUを中断しユーザ・プログラムがコントロールを取り戻すようにすることもできます。

注意
制御がユーザ・プログラムに戻されるのは,エラーが発生した場合, またはQUIT組込みプロシージャかEXIT組込みプロシージャを実行したあとだけです。


戻される状件値

 XTPU$_EXITING EXITの結果として戻されます (省略時の条件ハンドラが設定されている場合)。
 XTPU$_NONANSICRT 処理の中断の結果として戻されます。この条件値が戻されるのは, XTPU$_DISPLAYFILEをNODISPLAYに設定してDEC XTPUを呼び出し, スクリーン関係のコマンドを実行しようとしたときです。
 XTPU$_QUITTING QUITの結果として戻されます(省略時の条件ハンドラが設定されている場合)。
 XTPU$_RECOVERFAIL  回復操作が異常終了したことを示します。


XTPU$EDIT

このルーチンは,パラメータからコマンド文字列を作成し, そのコマンド文字列をXTPU$XTPUルーチンに渡します。

XTPU$EDITは, もうひとつのDEC XTPUの単純なコール可能インターフェイスのエントリ・ポイントです。


形式

     XTPU$EDIT   input, output 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。 このルーチンから戻される可能性のある条件値については, "戻される条件値" にまとめられています。


引数

input

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

入力ファイル名です。 input 引数は,ファイル指定のディスクリプタのアドレスです。

output

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

出力ファイル名です。 output 引数は,出力ファイル指定のディスクリプタのアドレスです。 これは/OUTPUTコマンド修飾子で使用される文字列です。


説明

このルーチンはコマンド列を作成し,それをXTPU$XTPUに渡します。 出力文字列の長さが0より大きい場合には,以下に示されているように, 出力文字列は/OUTPUT修飾子を使ってコマンド・ラインに指定します。
     EDIT/XTPU [/OUTPUT= output] input
もし,アプリケーションがDEC XTPUの操作に関係しない修飾子情報を解析するときには, そのアプリケーションがXTPU$EDITをコールする前にすべての DEC XTPUに関係しない修飾子情報を入手している必要があります。 その理由は, XTPU$EDITはXTPU$EDITが呼ばれる前のすべての修飾子情報を破壊してしまうからです。


戻される条件値

XTPU$XTPUから戻される値。


XTPU$EXECUTE_COMMAND

このルーチンは, ユーザ・プログラムがDEC XTPUステートメントを実行できるようにします。


形式

     XTPU$EXECUTE_COMMAND   string 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

string

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

DEC XTPUステートメントです。 string 引数は, 1つかまたはそれ以上のDEC XTPUステートメントを示す文字列のディスクリプタのアドレスです。


説明

このルーチンは,『DEC Text Processing Utility Reference Manual』 に説明されているEXECUTE組込みプロシージャと同じ機能を実行します。


戻される状件値

 XTPU$_SUCCESS  正常終了したことを示します。
 XTPU$_EXITING  EXIT組込みプロシージャが呼び出されたことを示します。
 XTPU$_QUITTING  QUIT組込みプロシージャが呼び出されたことを示します。
 XTPU$_EXECUTEFAIL  実行が異常終了したことを示します。 これは,実行エラーまたはコンパイラ・エラーが発生したためです。


XTPU$EXECUTE_INIFILE

このルーチンは,ユーザがユーザ作成初期化ファイルを実行できるようにします。

このルーチンは,エディタを初期化したあとで, 他のコマンドを処理する前に実行しなければなりません。


形式

     XTPU$EXECUTE_INIFILE


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

なし


説明

XTPU$EXECUTE_INIFILEルーチンを呼び出すと,DEC XTPUは以下の手順で実行します。

  1. バッファにコマンド・ファイルが読み込まれます。 省略時のファイルはXTPU$COMMAND.TPUです。 もし,コマンド・ラインで指定したファイルが見つからなかった場合には, エラー・メッセージが表示され,ルーチンは強制終了されます。

  2. /DEBUG修飾子をコマンド・ラインで指定した場合には, バッファにDEBUGファイルが読み込まれます。 省略時のファイルはSYS$SHARE:XTPU$DEBUG.TPUです。

  3. DEBUGファイルをコンパイルし,実行します。

  4. TPU$INIT_PROCEDUREを実行します。

  5. コマンド・バッファをコンパイルし,実行します。

  6. TPU$INIT_POSTPROCEDUREを実行します。

注意
XTPU$CLEANUPをコールしたあと,このルーチンをコールする場合には, XTPU$_EXECUTEPROCEDUREフラグと XTPU$_EXECUTEFILEフラグをセットしなければなりません。 これらのフラグをセットしなかった場合には,初期化ファイルは実行されません。


戻される条件値

 XTPU$_SUCCESS  正常終了。
 XTPU$_EXITING  EXITの結果として戻されます。 省略時の条件ハンドラを使用している場合には,セッションは終了します。)
 XTPU$_QUITTING  QUITの結果として戻されます。 省略時の条件ハンドラを使用している場合には,セッションは終了します。)
 XTPU$_COMPILEFAIL  初期化ファイルのコンパイルが異常終了したことを示します。)
 XTPU$_EXECUTEFAIL  初期化ファイルに含まれるステートメントの実行が異常終了したことを示します。)
 XTPU$_FAILURE  他のすべてのエラーを示す汎用コード。


XTPU$FILEIO

このルーチンはファイル操作を処理します。 ユーザが作成したファイル入出力ルーチンは, 何らかの操作を実行するためにこのルーチンを呼び出すことができます。 しかし,ファイルをオープンするルーチンは, そのファイルに対してすべての操作を実行しなければなりません。 たとえば,XTPU$FILEIOがファイルをオープンする場合には, そのファイルをクローズする操作も実行しなければなりません。


形式

     XTPU$FILEIO   code, stream, data 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値"にまとめられています。


引数

code

OpenVMS用法  符号なしロングワード
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

あるDEC XTPU機能を指定するアイテム・コードです。 code 引数は, 実行する機能を指定するDEC XTPUからのアイテム・コードを含むロングワードのアドレスです。

ファイル入出力ルーチンに指定できるアイテム・コードは,以下のとおりです。

  • XTPU$K_OPEN − このアイテム・コードは, data 引数がアイテム・リストのアドレスであることを指定します。 このアイテム・リストには,ファイルをオープンするのに必要な情報が含まれます。 stream 引数には, このファイルを将来参照するために使用される固有の値を指定しなければなりません。 この結果作成されたファイル名は, 動的な文字列ディスクリプタといっしょにコピーしなければなりません。

  • XTPU$K_CLOSE − stream 引数によって指定されるファイルがクローズされます。 構造が使用しているメモリをすベて解放することができます。

  • XTPU$K_CLOSE_DELETE − stream 引数によって指定されるファイルがクローズされ,削除されます。 構造が使用しているメモリをすべて解放することができます。

  • XTPU$K_GET − data 引数は,stream 引数によって指定されるファイルの, 次のレコードが格納される動的な文字列ディスクリプタのアドレスです。 このルーチンは,テキストをこのディスクリプタにコピーするために, OpenVMSランタイム・ライブラリが提供するルーチンを使用しなければなりません。 DEC XTPUは,ファイルの最後に到達したことをファイル入出力ルーチンが示したときに, 読み取られるデータのために割り当てられたメモリを解放します。

  • XTPU$K_PUT − data 引数は,stream 引数によって指定されるファイルに書き込まれるデータのディスクリプタのアドレスです。

stream

OpenVMS用法  不定
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

ファイル指定です。 stream 引数は,4つのロングワードで構成されるデータ構造のアドレスです。 このデータ構造は,操作されるファイルを記述するために使用されます。

このデータ構造は,すべてのファイルを参照するために使用されます。 ファイル・オープン要求が実行されたときには, このデータ構造にデータが書き込まれます。 他の要求はすべて,この構造の情報を使って,どのファイルが参照されているかを判断します。

図 6-2はストリーム・データ構造を示しています。

図 6-2 ストリーム・データ構造

最初のロングワードは,各ファイルの固有の識別子を格納するために使用されます。 ユーザ作成ファイル入出力ルーチンは,0から511までの値に制限されています。 したがって,最大512のファイルを同時にオープンすることができます。

2番目のロングワードは3つのフィールドに分かれています。 下位ワードは,FAB (FAB$L_ALQ)から割り当てられるサイズ,つまり, このファイルに割り当てられるブロック数を格納するために使用されます。 この値はあとで,ディスク空間を前もって割り当てるために出力ファイル・サイズを計算するときに使用されます。 2ワード目の下位バイトは,既存のファイルをオープンするときに, レコード属性バイト(FAB$B_RAT)を格納するために使用されます。 上位バイトは,既存のファイルをオープンするときに, レコード・フォーマット・バイト(FAB$B_RFM)を格納するために使用されます。 これらは,入力ファイルと同じフォーマットで出力ファイルを作成するために使用されます。 これらのフィールドには,ファイルをオープンするルーチンがデータを書き込みます。

最後の2つのロングワードは, 作成または拡張されるファイル名のディスクリプタとして使用されます。 この名前はあとで,EXITを処理するときに使用されます。 このディスクリプタには,オープン操作のあとで,ファイル名が書き込まれます。 このディスクリプタは,ランタイム・ライブラリの LIB$SCOPY_R_DXルーチンまたは LIB$SCOPY_DXルーチンを使って割り当てなければなりません。 この空間が不要になった場合には,DEC XTPUによって解放されます。

data

OpenVMS用法  アイテム・リスト3
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

ストリーム・データです。data 引数はアイテム・リストのアドレス, またはディスクリプタのアドレスです。


注意
このパラメータの意味は, コード・フィールドに指定したアイテム・コードによって異なります。

XTPU$K_OPENアイテム・コードを指定した場合には, data 引数は, オープン要求に関する情報を含むアイテム・リストのアドレスです。 オープン要求に関する情報を指定する場合には, 以下のDEC XTPUアイテム・コードを使用できます。

  • XTPU$K_ACCESS − このアイテム・コードを使用すれば, バッファ・アドレス・フィールドに以下のいずれかのアイテム・コードを指定できます。

    • XTPU$K_IO

    • XTPU$K_INPUT

    • XTPU$K_OUTPUT

  • XTPU$K_FILENAME − このアイテム・コードは, オープンしようとするファイル名として使用する文字列のアドレスを指定するために使用されます。 長さフィールドには文字列の長さを指定し, アドレス・フィールドにはそのアドレスを指定します。

  • XTPU$K_DEFAULTFILE − このアイテム・コードは, オープンしようとするファイルに省略時のファイル名を割り当てるために使用されます。 バッファ長フィールドには長さを指定し, バッファ・アドレス・フィールドには省略時のファイル名のアドレスを指定します。

  • XTPU$K_RELATEDFILE − このアイテム・コードは, オープンしようとするファイルの関連ファイル名を指定するために使用されます。 バッファ長フィールドには長さを指定し,バッファ・アドレス・フィールドには, 関連ファイル名として使用する文字列のアドレスを指定します。

  • XTPU$K_RECORD_ATTR − このアイテム・コードは, ファイルを作成するために使用されるFABのレコード属性バイト(FAB$B_RAT) の値がバッファ・アドレス・フィールドに含まれていることを指定します。

  • XTPU$K_RECORD_FORM − このアイテム・コードは, ファイルを作成するために使用されるFABのレコード・フォーマット・バイト(FAB$B_RFM) の値がバッファ・アドレス・フィールドに含まれていることを指定します。

  • XTPU$K_MAXIMIZE_VER − このアイテム・コードは, 出力ファイルのバージョン番号を現存する最大のバージョン番号より1つだけ大きな値にしなければならないことを指定します。

  • XTPU$K_FLUSH − このアイテム・コードは, ファイルに書き込む操作のたびに各レコードが実際にファイルに書き出されることを指定します。

  • XTPU$K_FILESIZE − このアイテム・コードは,ファイルを作成するときに, 割り当てサイズとして使用される値を指定するために使用されます。 値はバッファ・アドレス・フィールドに指定します。


説明

省略時の状態では, XTPU$FILEIOはキャリッジ・リターン・レコード属性を持った可変長ファイルを作成します (fab$b_rtm=var, fab$b_rat=cr)。 XTPU$K_RECORD_ATTRアイテムまたはXTPU$K_RECORD_FORMアイテムを指定した場合には, それらのアイテムが使用されます。 使用できるフォーマットと属性の組み合わせは以下のとおりです。

フォーマット 属性
STM, STMLF, STMCR O, BLK, CR, BLK+CR
VAR O, BLK, FTN, CR, BLK+FTN, BLK+CR

他の組み合わせはすべて,CR属性を持ったVARフォーマットに変換されます。

このルーチンは常に, ストリーム・データ構造の最初のロングワードに511より大きな値をセットします。 ユーザ作成ファイル入出力ルーチンは0−511の値に制限されているため, このルーチンがセットするファイル制御ブロック(FCB) とユーザが作成したブロックは簡単に区別することができます。


注意
DEC XTPUは単純なコール可能インターフェイスを使用する場合には, 省略時の値によりXTPU$FILEIOを使用します。 完全なコール可能インターフェイスを使用する場合には,XTPU$FILEIOを呼び出すか, または自分で作成した入出力ルーチンを使用しなければなりません。


戻される条件値

ファイル入出力ルーチンは,RMSステータス・コードをDEC XTPUに戻します。 エラー・メッセージが必要な場合には, ファイル入出力ルーチンがすべてのエラーを通知しなければなりません。


XTPU$HANDLER

このルーチンはDEC XTPUの条件ハンドラです。DEC XTPU条件ハンドラは, Put Message(SYS$PUTMSG)システム・サービスを呼び出し, そのシステム・サービスに XTPU$MESSAGEのアドレスを渡します。


形式

     XTPU$HANDLER   signal_vector, mechanism_vector 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。


引数

signal_vector

OpenVMS用法  引数リスト
データ型 符号なしロングワード
アクセス 変更
受け渡し方 参照による

シグナル・ベクタです。条件ハンドラに渡されるシグナル・ベクタについての説明は, 『OpenVMS System Services Reference Manual』を参照してください。

mechanism_vector

OpenVMS用法  引数リスト
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

条件ハンドラに渡されるメカニズム・ベクタについての説明は, 『OpenVMS System Services Reference Manual』を参照してください。


説明

XTPU$MESSAGEルーチンは実際のメッセージ出力を実行します。 Put Message (SYS$PUTMSG)システム・サービスはメッセージをフォーマッティングするだけです。 このルーチンは,第6.1.2項 で説明した変数からメッセージ・フラグの設定と機能名を入手します。 これらの値を変更できるのは,DEC XTPUのSET組込みプロシージャだけです。

ハンドラが受け取った条件値にFATALステータスが含まれている場合や, DEC XTPUのファシリティ・コードが含まれていない場合には, 条件が再通知されます。

条件がXTPU$_QUITTING,XTPU$_EXITING,またはXTPU$_RECOVERFAILの場合には, 条件ハンドラを設定したルーチンに対して,UNWIND要求が与えられます。

メッセージを処理したあと,条件ハンドラは継続ステータスを戻します。 DEC XTPUエラー・メッセージ要求は, どのメッセージを出力しなければならないかを示す条件を通知することによって実行されます。 シグナル・アレイに含まれる引数は, 正しくフォーマッティングされたメッセージ引数ベクタです。 このベクタには,関連するメッセージに対する複数の条件とフォーマッティングされた ASCII出力(FAO)引数が含まれていることがあります。 たとえば,存在しないファイルをエデイタがオープンしようとした場合には, DEC XTPUのメッセージとしてXTPU$_NOFILEACCESSが通知されます。 このメッセージに対するFAO引数は,ファイルの名前を示す文字列です。 この条件にはエラー・ステータスが含まれており, そのあとにRMSのステータス・フィールド (STS)とステータス値フィールド(STV)が続きます。 この条件には回復不可能な重大なエラーは含まれていないので, エラーを処理したあと,エディタは処理を継続できます。

エディタはXTPU$CONTROLから自動的に戻るわけではありません。 したがって,XTPU$CONTROLルーチンをコールする場合には, 制御をエディタに戻すための方法を設定しておかなければなりません (たとえば,CALL_USER組込みプロシージャを使用します)。 また,ユーザ作成条件ハンドラを設定したものの, 特定の条件に対してはDEC XTPUハンドラをコールする場合には, プログラムの中で制御を戻したい場所に, 省略時の条件ハンドラを設定しておかなければなりません。 また,XTPU$SPECIFY_ASYN_ACTIONおよびXTPU$TRIGGER_ASYNC_ACTIONの非同期ルーチンを使って, XTPU$CONTROLを中断することもできます。

『OpenVMS Calling Standard』を参照してください。


XTPU$INITIALIZE

このルーチンは編集を行えるようにDEC XTPUを初期化します。 このルーチンはグローバル・データ構造を割り当て,グローバル変数を初期化し, 仮想ファイル・マネージャやスクリーン・マネージャ,入出カサブシステムも含めて, エディタの主要コンポーネントのそれぞれに対して, 適切なセットアップ・ルーチンをコールします。


形式

     XTPU$INITIALIZE   callback [,user_arg] 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

callback

OpenVMS用法  符号なしロングワード・ベクタ
データ型 バウンド・プロシージャ値
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

コールバック・ルーチンです。callback 引数は, 初期化パラメータを含むアイテム・リストのアドレスを戻すユーザ作成ルーチンまたはファイル入出力操作を処理するルーチンのアドレスです。 このコールバック・ルーチンはXTPU$CLIPARSEまたはユーザ作成のパース・ルーチンのどちらかを呼び出さなければなりません。

コール可能なDEC XTPUは, 初期化パラメータを指定するために使用できるアイテム・コードを定義しています。 これらのコードを使用するときには,以下の基準に従ってください。

  • XTPU$_OTHER_FILENAMESは,XTPU$_FILENAMEの後で使わなければなりません。

  • XTPU$_CHAINまたはXTPU$_ENDLISTはリストの最後のアイテムでなければなりません。

図 6-3は,アイテムディスクリプタの一般的な形式を示しています。 アイテム・リストの作成方法についての詳しい説明は, 使用する各言語のプログラマ・マニュアルを参照してください。

図 6-3 アイテムディスクリプタのフォーマット

アイテムディスクリプタのリターン・アドレスは,通常0です。

使用できるアイテム・コードは表 6-2に示すとおりです。

表 6-2 使用できるアイテム・コード

アイテム・コード 説明
XTPU$_OPTIONS コマンド修飾子を使用可能にします。 バッファ・アドレス・フィールドの14ビットは, いろいろなDEC XTPUコマンド修飾子に対応しています。 バッファ・アドレス・フィールドの残りの18ビットは使用されません。
XTPU$_JOURNALFILE /JOURNAL修飾子に指定されている文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスです。 これは,GET_INFO (COMMAND_LINE,"JOURNAL_FILE")で使用できる文字列です。 この文字列はヌル文字列でもかまいません。
XTPU$_SECTIONFILE マッピングされるバイナリ初期化ファイル(セクション・ファイル) の名前を示す文字列を渡します。バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスです。 DEC XTPUの CLDファイルには,この文字列の省略時の値が含まれています。 XTPU$V_SECTIONビットがセットされている場合には, このアイテム・コードを指定しなければなりません。
XTPU$_OUTPUTFILE /OUTPUT修飾子に指定されている文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスを指定します。 これは, GET_INFO (COMMAND_LINE,"OUTPUT_FILE")組込みプロシージャから戻される文字列です。 文字列はヌル文字列でもかまいません。
XTPU$_DISPLAYFILE /DISPLAY修飾子に指定されている文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスを指定します。
XTPU$_COMMANDFILE /COMMAND修飾子に指定されている文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスです。 この文字列は, GET_INFO (COMMAND_LINE,"COMMAND_FILE")組込みプロシージャから戻される文字列です。 文字列はヌル文字列でもかまいません。
XTPU$_FILENAME コマンド・ラインに指定されている入力ファイルの名前を示す文字列を渡します。 バッファ長フィールドはこの文字列の長さを指定し, バッファ・アドレス・フィールドはアドレスを指定します。これは, GET_INFO (COMMAND_LINE,"FILE_NAME")組込みプロシージャから戻される文字列です。 このファイル名はヌル文字列でもかまいません。
XTPU$_OTHER_FILENAMES コマンド・ラインに指定されている入力ファイルのうち一番目を除くものの名前を示す文字列を渡します。 バッファ長フィールドはこの文字列の長さを指定し, バッファ・アドレス・フィールドはアドレスを指定します。 2番目以降の入力ファイルはそれぞれXTPU$_OTHER_FILENAMESのエントリが必要です。 これは,GET_INFO (COMMAND_LINE,"NEXT_FILE_NAME") 組込みプロシージャから戻される文字列です。
XTPU$_FILEIO ファイル操作を処理するために使用されるルーチンのバウンド・プロシージャ値を渡します。 自分で作成したファイル入出力ルーチンを使用することができ,また, ファイル操作を処理するためにDEC XTPUが提供するユーティリティ・ルーチンである XTPU$FILEIOをコールすることもできます。 ファイル入出力ルーチンのアドレスは, バッファ・アドレス・フィールドに指定します。
XTPU$_CALLUSER CALL_USER組込みプロシージャがコールするユーザ作成ルーチンのバウンド・プロシージャ値を渡します。 このルーチンのアドレスはバッファ・アドレス・フィールドに指定します。
XTPU$_INIT_FILE /INITIALIZATION修飾子に指定されている文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスです。この文字列は, GET_INFO (COMMAND_LINE, "INIT_FILE")組込みプロシージャから戻される文字列です。
XTPU$_KANJI_DICFILE /KANJI_DICTIONARY修飾子に指定されている文字列を渡します。 バッファ長フィールドはこの文字列の長さを指定し, バッファ・アドレス・フィールドはアドレスを指定します。これは, GET_INFO(COMMAND_LINE, "KANJI_DICTIONARY_FILE")組込みプロシージャから戻される文字列です。
XTPU$_START_LINE その編集セッションの開始行番号を渡します。 バッファ・アドレス・フィールドは/START_POSITION修飾子で指定した2つの整数値の最初の値です。 この値はGET_INFO (COMMAND_LINE,"LINE")組込みプロシージャから戻される値です。 通常,初期化プロシージャがこの情報を用いて, 編集するバッファの先頭位置を設定します。バッファの先頭行はline 1です。
XTPU$_START_CHAR その編集セッションの開始カラム位置を渡します。 バッファ・アドレス・フィールドは/START_POSITION修飾子で指定した2つの整数値の2番目の値です。 この値はGET_INFO(COMMAND_LINE,"CHARACTER")組込みプロシージャから戻される値です。 通常,初期化プロシージャがこの情報を用いて, 編集するバッファの先頭位置をを設定します。 バッファの先頭カラムはcharacter 1です。
XTPU$_WORKFILE /WORK修飾子で指定される文字列を渡します。 バッファ長フィールドはこの文字列の長さを指定し, バッファ・アドレス・フィールドはアドレスを指定します。これは, GET_INFO (COMMAND_LINE, "WORK_FILE")組込みプロシージャから戻される文字列です。
XTPU$_CHAIN バッファ・アドレス・フィールドに次のアイテム・リストのアドレスを指定します。
XTPU$_ENDLIST アイテム・リストの最後を示します。
XTPU$_CTRL_C_ROUTINE Ctrl/C ASTを処理するためのルーチンのバウンド・プロシージャ値を渡します。 DEC XTPUはCtrl/C ASTが発生すると,そのルーチンを呼び出します。 そのルーチンがFALSE値を返すと,DEC XTPUはCtrl/Cが処理されたものと仮定します。 TRUE値が返されると, DEC XTPUは現在実行しているDEC XTPUプロシージャの実行を強制終了させます。 バッファ・アドレス・フィールドは,2つのロングワード・ベクタのアドレスを指定しています。 最初のロングワードはルーチンのアドレスであり, 2番目のロングワードはそのルーチンを呼ぶ前にR1にDEC XTPUがロードする環境値です。
XTPU$_DEBUGFILE /DEBUG修飾子で指定された文字列を渡します。 バッファ長フィールドは文字列の長さであり, バッファ・アドレス・フィールドは文字列のアドレスです。

表 6-3は, XTPU$K_OPTIONSアイテム・コードによって与えられるビットと対応するマスクをまとめたものです。

表 6-3 XTPU$OPTIONS アイテム・コードによって与えられるビットと対応するマスク

マスク フラグ 機能
XTPU$M_RECOVER[1] XTPU$V_RECOVER[2] 回復操作を実行します。
XTPU$M_JOURNAL XTPU$V_JOURNAL 編集セッションをジャーナルします。
XTPU$M_READ XTPU$V_READ メイン・バッファに対してはREAD_ONLY編集セッションとします。
XTPU$M_SECTION XTPU$V_SECTION 起動時にバイナリ初期化ファイル( DEC XTPUセクション・ファイル)にマッピングします。
XTPU$M_CREATE XTPU$V_CREATE 指定した入力ファイルが存在しない場合,入力ファイルを作成します。
XTPU$M_OUTPUT XTPU$V_OUTPUT セッションを終了するときに,変更された入力ファイルを書き出します。
XTPU$M_COMMAND XTPU$V_COMMAND 起動時にコマンド・ファイルを実行します。
XTPU$M_DISPLAY XTPU$V_DISPLAY スクリーンを使用する編集と表示のために,ターミナルを使用します。
XTPU$M_INIT XTPU$V_INIT イニシャライゼーション・ファイルがあります。
XTPU$M_COMMAND_DFLTED XTPU$V_COMMAND_DFLTED コマンド・ラインのユーザが指定した省略値の名前があるかどうかを指示します。 これがTRUEである場合には, ユーザがコマンド・ファイルを指定しなかったことを意味します。 このビットがFALSEにセットされていて,かつファイルが指定されていなかったら, XTPU$INITIALIZEは失敗します。
XTPU$M_WRITE XTPU$V_WRITE /WRITEがコマンド・ラインで指定されたかどうかを示します。
XTPU$M_MODIFY XTPU$V_MODIFY /MODIFYがコマンド・ラインで指定されたかどうかを示します。
XTPU$M_NOMODIFY XTPU$V_NOMODIFY /NOMODIFYがコマンド・ラインで指定されたかどうかを示します。
XTPU$M_NOKANJI_DIC XTPU$V_NOKANJI_DIC /NOKANJI_DICTIONARYがコマンド・ラインで指定されたかどうかを示します。
XTPU$M_SEC_LNM_MODE XTPU$V_SEC_LNM_MODE イメージが特権付きでインストールされ,このビットがセットされていると, セクション・ファイルを開けるときに信用のある論理名のみが使用されます。
[1] XTPU$M... マスクを示します。

[2] XTPU$V... ビット・アイテムを示します。

フラグを作成するには,0という値から開始し, セットしたい各アイテムのマスク(XTPU$M…)に対して,OR演算子を使用します。 また,フラグを作成する別の方法として,32ビットをビット・ベクタとして取り扱い, 希望するアイテムに対応するビット(XTPU$V…)をセットする方法もあります。

user_arg

OpenVMS用法  ユーザ引数
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 値による

ユーザ引数。 user_arg 引数はユーザによって書かれた初期化ルーチンINITIALIZEに渡されます。 user_arg 引数によって, アプリケーションはXTPU$INITIALIZEを通してユーザによって書かれた初期化ルーチンに情報を渡すことができます。 DEC XTPUはこのデータを解釈しません。


説明

このルーチンは, 条件ハンドラを設定したあとで最初にコールしなければならないルーチンです。

このルーチンは, コールバック・ルーチンから受け取った情報に応じてエディタを初期化します。 初期化ルーチンは,省略時の値として,すべてファイル指定をヌル文字列に設定し, すべてのオプションをオフの状態に設定します。しかし, ファイル入出力ルーチンやコールユーザ・ルーチンの省略時のアドレスは設定しません。

セクション・ファイルを指定しなかった場合には, エディタのソフトウェア機能は制限されます。


戻される条件値

 XTPU$_SUCCESS  初期化が正常終了したことを示します。
 XTPU$_SYSERROR  システム・サービスが正しく機能しなかったことを示します。
 XTPU$_NONANSICRT  入力装置(SYS$INPUT)がサポートされないターミナルであることを示します。
 XTPU$_RESTOREFAIL  復元操作でエラーが発生したことを示します。
 XTPU$_NOFILEROUTINE  ファイル操作を実行するためのルーチンが設定されていないことを示します。
 XTPU$_OPENDIC  かな漢字変換辞書がオープンできなかったことを示します。
 XTPU$_INSVIRMEM  エディタが初期化を実行するのに十分な仮想メモリが存在しないことを示します。
 XTPU$_FAILURE  初期化を実行しているときに発生した他のすべてのエラーを示す汎用コードです。


XTPU$MESSAGE

このルーチンは, MESSAGE組込みプロシージャを使って,エラー・メッセージと文字列を出力します。

このルーチンをコールすれば,DEC XTPUと同じ方法で, メッセージを出力し,処理することができます。 このルーチンは,XTPU$EXECUTE_INFILEを実行したあとで使用しなければなりません。


形式

     XTPU$MESSAGE   string 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。


注意
Put Message(SYS$PUTMSG)システム・サービスで使用されるので, 戻されるリターン・ステータスは無視しなければなりません。


引数

string

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

フォーマットされたメッセージです。 string 引数は,出力されるテキストのディスクリプタのアドレスです。 これは完全にフォーマッティングしておかなければなりません。 このルーチンはメッセージ・プリフィックスを追加しません。 しかし,メッセージ・バッファが存在する場合には, テキストがメッセージ・バッファに追加されます。 さらに,バッファがウィンドウにマッピングされている場合には, そのウィンドウは更新されます。


XTPU$PARSEINFO

このルーチンはコマンドを解析し, XTPU$INITIALIZEのためにアイテム・リストを作成します。


形式

     XTPU$PARSEINFO   fileio, call_user 


戻り値

OpenVMS用法  アイテム・リスト
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

このルーチンは,アイテム・リストのアドレスを返します。


引数

fileio

OpenVMS用法  符号なしロングワード・ベクタ
データ型 バウンド・プロシージャ値
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

ファイル入出力ルーチンです。 fileio 引数は,ファイル入出力ルーチンのディスクリプタのアドレスです。

call_user

OpenVMS用法  符号なしロングワード・ベクタ
データ型 バウンド・プロシージャ値
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

コールユーザ・ルーチンです。 call_user 引数は,コールユーザ・ルーチンのディスクリプタのアドレスです。


説明

XTPU$PARSEINFOルーチンはコマンドを解析し, XTPU$INITIALIZEのためにアイテム・リストを作成します。

このルーチンは,現在のコマンドを解析するために, コマンド言語インタプリタ(CLI)ルーチンを使用し, DEC XTPUが期待するコマンド・パラメータと修飾子に関する照会を行います。 この照会結果は,アイテム・リストに正しい情報を設定するときに使用されます。 リストに含まれる各アイテムに対して,ユーザ・ルーチンのアドレスが使用されます。 このリストのアドレスが,ルーチンから戻される値として使用されます。

ユーザのアプリケーションがDEC XTPUの動作に無関係の情報をコマンド・ラインから解析している時には, アプリケーションはXTPU$PARSEINFOを呼び出す前にすべての情報の解析を終っていなければなりません。 XTPU$PARSEINFOはXTPU$PARSEINFOを呼びだす前に得たコマンド行の解析の情報を破壊します。


XTPU$SPECIFY_ASYNC_ACTION

このルーチンはDEC XTPUの完全なコール可能インターフェイスを使用したアプリケーションがDEC XTPUに非同期動作を登録するときに使用されます。


形式

     XTPU$SPECIFY_ASYNC_ACTION   facility_index ,[xtpu_statement] 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。 ユーティリティ・ルーチンはほとんど,条件値をR0に戻します。 このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

facility_index

OpenVMS用法  符号なしロングワード
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

facility_index 引数は非同期動作のINDEXを指定します。 このINDEXは,XTPU$TRIGGER_ASYNC_ACTIONルーチンと共に用いられ, DEC XTPUに実行される動作を知らせます。 xtpu_statement 引数を指定しなければ,動作の取り消しができます。 アプリケーションが必要ならば,複数個の非同期動作を登録することもできます。 値は任意の正の整数です。

xtpu_statement

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

XTPU$TRIGGER_ASYNC_ACTIONが呼ばれたときに実行されるDEC XTPUステートメントです。 ステートメントはコンパイルされ内部に格納されます。 この引数を指定しないと,DEC XTPUは非同期イベントのリストから指定した動作を削除します。


説明

このルーチンはXTPU$TRIGGER_ASYNC_ACTIONと共にXTPU$CONTROLが呼ばれた後に, アプリケーションがDEC XTPUを中断する手段を提供します。 指定されたDEC XTPUステートメントは実行アイテムのキューに登録され, 他の実行アイテムがなくなったら処理されます。 このため,DEC XTPUは実行中の動作を終了でき, コマンドの実行の前に環境を安定させることができます。 このルーチンはXTPU$INITIALIZEの後に呼ばれなければなりません。 しかし,キー・ジャーナリングが動作していると正常終了しません。 実行される動作はDEC XTPUのXTPU$INITIALIZEの呼び出しの後で指定しなければならないため, 簡単なコール可能インターフェイスのXTPU$XTPUと共には使用できません。


戻される条件値

 XTPU$_SUCCESS  正常終了したことを示します。
 XTPU$_COMPILEFAIL  xtpu_statement引数に指定されたコードが正常にコンパイルできません。
 XTPU$_INVPARM  引数が正しくありません。
 XTPU$_JNLACTIVE  キー・ジャーナリングが動作中です。 このルーチンを正しく動作させるためにはバッファ・ジャーナリングが必要です。


XTPU$TRIGGER_ASYNC_ACTION

このルーチンは, DEC XTPUの完全なコール可能インターフェイスを使用したアプリケーションが DEC XTPUのXTPU$CONTROLループを非同期に中断させるときに使用されます。


形式

     XTPU$TRIGGER_ASYNC_ACTION   facility_index 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値"にまとめられています。


引数

facility_index

OpenVMS用法  符号なしロングワード
データ型 符号なしロングワード
アクセス 読み取りのみ
受け渡し方 参照による

facility_index 引数は非同期動作のINDEXを指定します。 このINDEXは,実行されるDEC XTPUステートメントを登録するときに XTPU$SPECIFY_ASYNC_ACTIONルーチンに渡された値です。


説明

このルーチンはXTPU$SPECIFY_ASYNC_ACTIONと共にXTPU$CONTROLが呼ばれた後に, アプリケーションがDEC XTPUを中断する手段を提供します。 指定されたDEC XTPUステートメントは実行アイテムのキューに登録され, 他の実行アイテムがなくなったら処理されます。 このため,DEC XTPUは実行中の動作を終了でき, コマンドの実行の前に環境を安定させることができます。 このルーチンはXTPU$CONTROLルーチンでDEC XTPUに制御を渡した後で呼ばれなければなりません。


戻される条件値

 XTPU$_SUCCESS  正常終了したことを示します。
 XTPU$_UNKFACILITY  このルーチンに渡されたfacility_index引数が XTPU$SPECIFY_ASYNC_ACTIONに渡されたINDEXと一致しません。


XTPU$XTPU

このルーチンはDEC XTPUを起動します。これはDCLのDEC XTPUコマンドと同じです。


形式

     XTPU$XTPU   command 


戻り値

OpenVMS用法  条件値
データ型 符号なしロングワード
アクセス 書き込みのみ
受け渡し方 値による

ロングワードの条件値です。ユーティリティ・ルーチンはほとんど, 条件値をR0に戻します。このルーチンから戻される可能性のある条件値は, "戻される条件値" にまとめられています。


引数

command

OpenVMS用法  文字列
データ型 文字列
アクセス 読み取りのみ
受け渡し方 ディスクリプタによる

コマンド文字列です。 command 引数は,コマンド・ラインのディスクリプタのアドレスです。 コマンド名には,XTPUを使います。


説明

このルーチンは,指定されたコマンド文字列を使用し,それをエディタに渡します。 DEC XTPUは,DCLレベルからコマンドをタイプした場合と同様に, 初期化のために,このコマンド文字列の情報を使用します。

単純なコール可能インターフェイスを使用する場合には, XTPU$CLOSE_SECTIONはセットされません。 この機能を使用すれば,XTPU$XTPUを2回以上コールすることができ, コールするたびにセクション・ファイルをオープン/クローズする必要はありません。

もし,アプリケーションがDEC XTPUの操作に関係しない修飾子情報を解析するときには, そのアプリケーションがXTPU$EDITをコールする前にすべての DEC XTPUに関係しない修飾子情報を入手している必要があります。 その理由は,XTPU$EDITが呼ばれる前のすべての修飾子情報を破壊してしまうからです。


戻される条件値

XTPU$INITIALIZE,XTPU$EXECUTE_INIFILE,XTPU$CONTROL,および XTPU$CLEANUPから戻されるすべての条件値です。


[ 前のページ ] [ 次のページ ] [ 目次 ] [ 索引 ] [ DOC Home ]