背景
Caché の以前のリリースにおいて、別のルーチンによるルーチンの生成および操作は、付加的に行なわれていました。つまり、ルーチンの制御は ZLOADZINSERTZREMOVE および関連するコマンドを使用して、1 行ずつルーチンを構築、操作、コンパイル、保存していました。
この方法はエラーを分離するには有効ですが、効率的ではありません。ObjectScript コンパイラの進化に伴い、コンパイラの開始と終了に関連するコストが、コードの 1 行をコンパイルするコストに比べて、大幅に増大しました。その結果、プログラミングにより生成されたルーチンのコンパイル速度を改善するために、Caché バージョン 4 で %R ルーチンが導入されました。%R ルーチンにより、生成されたルーチンを 1 行ごとではなくユニットとして処理することができるようになりました。
1 行ごとにルーチンを操作することも可能ですが、%R を使用する方法を推奨します。
Note:
警告に対し、2 つの対処法があります。アプリケーションが ZINSERT への各呼び出しの後に構文エラーの有無を判断するのに、$ZUTIL(62, 0) を使用する場合、常にエラーは発生していないと報告します。以前は、ZINSERT は挿入を実行するたびにコンパイルを実行していましたが、現在は ZSAVE コマンドが実行されるまでコンパイルしません。しかし、ZSAVE$ZUTIL(62, 0) 機能経由ではエラーを報告しません。
ルーチン名
ルーチン名を供給する文字列は、%R のエントリ・ポイントの多くで使用されています。以下では、この名前をコンポーネントの一部に評価するための一般的な方法について説明します。
通常、ルーチン名は 3 つの部分 (ベース名、ルーチン拡張子、この 2 つの要素が指定するソースのバージョン) から構成され、各部はピリオドで区切られています。しかし以下のような場合は、名前が正確に解釈できない可能性があります。
従来のプログラムが ^%R 機能と互換を持つようにするため、以下の方法により、文字列をベース名、拡張子、バージョン、ネームスペースの構成部分に解析します。
  1. ネームスペース構成要素が空文字列に初期化されます。
  2. 文字列に "|" または "]" の文字が含まれている場合は、フォームの形式であるとみなされます。
    あるいは
    ネームスペースの要素を、(") の間から取り出します。文字列は <REMAINDER> に設定され、処理を継続します。
  3. 文字列がワイルドカード文字 (*) のみから構成されている場合は、拡張子とバージョンの要素は空文字列に設定されます。ベース名はワイルドカード文字に設定され、名前の処理が終了します。
  4. 文字列が "<TEXT>.*.*" という形式であれば、拡張子とバージョンは "*" に、ベース名は <TEXT> に設定され、処理が完了します。
  5. 文字列が "<TEXT>.*" という形式であれば、バージョンは 0、拡張子は "*"、ベース名は <TEXT> に設定され、処理が完了します。
  6. 文字列が "<TEXT>.<EXT>.*" という形式で、<EXT> が有効な拡張子 (以下のうちのいずれか) であれば、
    (この場合大文字・小文字は関係ありません) バージョンは "*" に、拡張子は <EXT> に、ベース名は <TEXT>に設定されます。
    そうでない場合は、バージョンは 0、拡張子は "*"、ベース名は <TEXT>.<EXT> に設定され、処理が完了します。
  7. 文字列が "<TEXT>.<EXT>.<VER>" という形式で、EXT が上記の有効な拡張子のうちのひとつであり、VER が整数であれば (符号付きまたは符号なし)、バージョンは VER、拡張子は <EXT>、ベース名は <TEXT> に設定されます。
    そうでない場合は、バージョンは 0、拡張子は "*"、ベース名は <TEXT>.<EXT>.<VER> に設定され、処理が完了します。
  8. そうでない場合は、バージョンは 0、拡張子は "*"、ベース名は文字列の残りの文字に設定され、処理が完了します。
上記は、名前の構文解析のアルゴリズムの一般的な説明です。名前の構文解析の例は、以下の ParseRoutineName エントリ・ポイントを参照してください。これは、^%R のその他のエントリ・ポイントによって使用されるネーム・パーサーです。
言語のエンコード
いくつかのエントリ・ポイントでは、整数値を使用してサブジェクト・ルーチンが記述されている言語を識別します。言語を指定するエンコードは以下の通りです。
1 から 8 までの値を使用して、古いシステム間のソース・コードの解釈の微妙な相違点に対し、コンパイラをカスタマイズします。
Note:
Caché の現在のユーザは、0 または 9 を使用するようにしてください。その他は、古いアプリケーションの維持および更新に使用してください。
バージョン
%R 内のエントリ・ポイントには、ROUTINE エントリ・ポイントへの "B" オプションと一緒に使用するときに、制約つきのバージョン制御形式を提供するものがあります。これらは、利用可能な特定のルーチンの “古い” バージョンを指定数維持し、必要に応じて再生できるように準備します。詳細は、VERMAXVERMAXSETVERSION1VERSION を参照してください。
エントリ・ポイント
^%R で公式にサポートされているエントリ・ポイントを機能別に分類して、以下に示します。
名前の解析
エントリ・ポイント 目的
ParseRoutineName ルーチン名を、構成部分に分離します
一般的なルーチン操作
エントリ・ポイント 目的
ROUTINE データベースのソース・コードをコンパイルして保存、またはロードします
FMTERR エラーを表示します
CHECK ソース・コードの構文を確認します
DATE 保存されたルーチンの日付を取得します
DEL データベースからルーチンを削除します
EXISTS ルーチンの有無を確認します
LANG ルーチンのソース言語インジケータを取得します
LANGSET ルーチンのソース言語インジケータを設定します
LENGTH ルーチンのソース行をカウントします
SIZE ルーチンのソース文字をカウントします
LINE 保存されたルーチンから 1 行を返します
LINESET 保存されたルーチンに、新しいソース行を挿入/置換します。
LOCK 保存されたルーチンの排他的使用を試みます
UNLOCK 保存されたルーチンの排他的使用を中止します
バージョン制御
エントリ・ポイント 目的
VERMAX バックアップとして保持するバージョンの最大数を返します
VERMAXSET バックアップとして保持するバージョンの最大数を設定します
VERSION1 最も古いバックアップのバージョン番号を返します
VERSION 関連するバージョン番号に一致するバージョン番号を返します
Caché ObjectScript 関数についての詳細は、"Caché ObjectScript の使用法" の 関数 を参照してください。
ParseRoutineName
Synopsis
ParseRoutineName^%R (rtn, .extent, .version, .namesp)
パラメータ
rtn ターゲット・ルーチンの名前
extent パースされた拡張子を持つ文字列
version バージョン番号をあらわす文字列
namesp (ルーチン名にネームスペースがあれば) ネームスペースをあらわす文字列
概要
この関数は、^%R のその他のエントリ・ポイントが使用するネーム・パーサーへのアクセスを提供します。
パラメータ
rtn
データベースから取得する、またはデータベースに保存するルーチンの名前を指定する文字列。ルーチンの名前全部、あるいは一部を表します。この名前は、大文字と小文字を区別します。拡張子は大文字と小文字を区別しません。
extent
出力引数。パースされた拡張子を保持します。
version
出力引数。パースされたバージョン番号を保持します。
namesp
rtn が明示的なネームスペース構成要素を含む場合、この出力引数がそれを含みます。含まない場合は、空文字列に設定されます。
備考
この関数は、^%R のその他のエントリ・ポイントが使用する内部ルーチンです。これはパブリック・エントリ・ポイントですが、パース・ルールが実際どのように適用されるのかを知りたい開発者の方のために、ここで説明します。
この関数は、結果として、出力引数とベース・ルーチン名を返します。
以下の例は、さまざまなルーチン名について ParseRoutineName^%R の使用方法を示します。
    ; Build a list of names
    Set samples = $LISTBUILD("foo",
                             "foo.bar",
                             "foo.mac",
                             "foo*.bar",
                             "foo*.*.13",
                             "foo.mac.-234",
                             "^|""DeltaQuadrant""|Voyager.int.1",
                             "^[""^AlphaQuadrant""]NCC.1701.MAC.4",
                             "^[""twilight"",""zone""]Somewhere.INT.19")
    
    ; show the results
    For i = 1 : 1 : $LISTLENGTH(samples)
    {
        Set (Ext, Ver, Nsp) = "???"
        Set Input = $LIST(samples, i)
        Set BaseName = $$ParseRoutineName^%R(Input, .Ext, .Ver, .Nsp)
        Write Input, ! 
        Write ?3, "Base:", ?15, BaseName, !
        Write ?3, "Extension:", ?15, Ext, !
        Write ?3, "Version:", ?15, Ver, !
        Write ?3, "Namespace:", ?15, Nsp, !, !
    }
ROUTINE
Synopsis
ROUTINE^%R (rtn, .code, .errs, options, langmode, filedate, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
code ソース・コード配列への参照
errs 処理中に検出されたエラーのリストへの参照
options 希望する処理の選択肢を含む文字列
langmode ソースの言語を指定するインジケータ
filedate 結果として作成されたファイルで使用するタイムスタンプ
namesp ルーチンが処理されるネームスペース
概要
この関数は、Caché ObjectScript プログラムがプログラム的にソース・コードを操作することを許可します。関数に渡されるパラメータが実行を指定するプログラムは以下の通りです。
パラメータ
rtn
有効な文字列として評価する式。文字列の内容は、データベースから取得する、またはデータベースに保存するルーチンの名前を指定します。"SomeRoutine.MAC" などのように、名前と拡張子がピリオドで区切られた完全なルーチン名を含む必要があります。この名前は、大文字と小文字を区別します。拡張子は大文字と小文字を区別しません。
code
ソース・コードの配列。この配列は、ルーチンのコンパイル時、あるいは保存時に、ソース・コードを提供します。ルーチンがフェッチされたときに、ソースを受け取ります。
配列の形式は以下の通りです。
errs
options が指定する処理の実行を試行する間に検出されたエラーのリスト。値の $LIST として引数 err が返されます。値は、FMTERR^%R 関数を呼び出して表示できます。
options
ルーチンで試行される処理を示す一連の文字からなる文字列。許可される値およびその意味は以下の通りです。
文字列は、大文字と小文字を区別しません。処理が試行される順番は、文字列に配置されている順番通りです。
langmode
code の文が記述されている言語を示す整数。
filedate
Caché のルーチンが修正された日付として使用するタイムスタンプ。filedate の値は、$HOROLOG 形式で指定します (詳細は、Caché ObjectScript リファレンス を参照)。filedate が指定されていない場合は、現在の日付と時間を使用します。
namesp
指定された処理を実行するネームスペースを値に持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
このルーチンは、ルーチンで最初の引数として指定された処理の実行を試行し、結果を、以下の形式の文字列で返します。
N の値は、この試行が最終的に成功したか、あるいは失敗したかを示します。N が 1 であれば、すべての処理が成功したことを表し、N が 0 であれば、失敗した処理があることを表します。
Status1Status2Status3 などは、対応するオプションの結果の要約を表します。
以下の例は、ROUTINE^%R を使用して 1 つのルーチンをコンパイル、保存、実行する方法を示しています。これは、ルーチンを直接実行します。
この例は、このドキュメントで説明されている、^%R 内の他のエントリ・ポイントを利用しています。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
    
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    ; Note leading spaces on the following entries"
    Set code($INCREMENT(N)) = "    Write ""Starting AnExample"", !"
    Set code($INCREMENT(N)) = "    Set Y = 1"
    Set code($INCREMENT(N)) = "    Set Z = 3"
    Set code($INCREMENT(N)) = "    Write Y, "" + "", Z, "" = "", (Y + Z), !"
    Set code($INCREMENT(N)) = "    Write ""Finished AnExample"", !"
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set name = "AnExample"
    Set ext = "INT"
    Set routine = name _ "." _ ext
    Set options = "CS"              ; Compile and Save
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    
    ; show the simple result
    Write "Compilation result: ", return, !
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
    }
    Else
    {   
        ; run it
        Write "Calling AnExample", !
        Set entrypoint = name _ "^" _ name
        Do @entrypoint
        ; remove the source and object
        for suffix = "int", "OBJ"      
        {
            Set component = name _ "." _ suffix
            Write "Removing ", component, ": ", $$DEL^%R(component), ! 
        }
    }
FMTERR
Synopsis
FMTERR^%R (.errs, .code, .lines)
パラメータ
errs 処理中に検出されたエラーのリストへの参照
code ソース・コード配列への参照
lines 見つかったエラーの解釈を含むテキスト行の配列への参照
概要
この関数は、ROUTINE^%R あるいは CHECK^%R 呼び出しにより生成されたエラーのデータを、ユーザが見やすい表示形式に変換します。
パラメータ
errs
ROUTINE^%R または CHECK^%R の呼び出しにより返された、エラーのリスト。
code
ソース・コードを含む配列。この配列は、ルーチンのソース・コードを供給するので、表示された情報には、テキストの一部として、エラーを起こしたソース行が含まれます。このフォーマットは、ROUTINE^%R エントリ・ポイントが使用するものと同じです。提供されていない場合は、エラー・メッセージには、エラーの内容ではなくエラーが発生した位置のみが表示されます。
lines
エラー・メッセージを生成するテキスト行が書き込まれる配列への参照。このフォーマットは、ソース・コード配列と同じで、lines(0) は、配列内のエラー・メッセージの行数を含みます。
このパラメータが提供されていない場合、結果として生じるテキストは関数呼び出しの値として返されます。$CHAR(13, 10) がある場所には、返される文字列で強制改行が入ります。
lines が提供されている場合、各配列項目は、別の行を表します。内部の強制改行も、返される結果もありません。つまり、ルーチンは、(DO コマンド経由で) サブルーチンとして呼び出すようにしてください。
備考
このルーチンは、ROUTINE^%R に返されたエラー・リストを、ユーザが使いやすい形式に再フォーマットします。
以下は、不正なプログラム上で CHECK^%R を使用して、エラー配列を生成します。この配列は、その後テキストに変換され、表示されます。
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    Set code($INCREMENT(N)) = "    Write ""Starting AnExample"", !"
    Set code($INCREMENT(N)) = "    Write ""A closing quote is missing here^, !"
    Set code($INCREMENT(N)) = "    Quiet"
    Set code(0) = N
    
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$CHECK^%R(.code, .errors)
    
    ; show the simple result
    Write return, !
    If (return = 0)
    {      
        ; format and display the errors
        Write !, "Errors as one text string", !
        Write $$FMTERR^%R(.errors, .code), !
        Write !, "Errors as lines from an array", !
        Set lines = ""
        Do FMTERR^%R(.errors, .code, .lines)
        for i = 1 : 1 : lines(0)
        {
            Write "errors(", i, ") = ", lines(i), !
        }
    }
    Else
    {   
        ; should never get here
        Write "Something is radically wrong", !
    }
CHECK
Synopsis
CHECK^%R (.code, .errs, langmode)
パラメータ
code ソース・コード配列への参照
errs 処理中に検出されたエラーのリストへの参照
langmode ソースの言語を指定するインジケータ
概要
この関数は、提供されたソース・コードの構文チェックを実行し、見つかったエラーを返します。
パラメータ
code
ソース・コードを含む配列。この配列は、正しい構文をチェックするルーチンのソース・コードを提供します。このフォーマットは、ROUTINE^%R エントリ・ポイントが使用するものと同じです。
errs
構文チェッカーによって報告されたエラーのリスト。値の $LIST として返されます。FMTERR^%R ルーチンを呼び出すことにより、その値を表示できます。
langmode
code の文が記述されている言語を指定する整数。許可されている値は、ROUTINE^%R で許可されているものと同じです。
備考
このルーチンは関数として呼び出され、結果として 0 または 1 を返します。結果の意味は以下の通りです。
Note:
返り値 1 は、提供されたソースがコンパイル時にエラーを生じないことを示します。ソース・コードの実行時にエラーが発生しない、あるいは意図した結果を得られることを意味しているわけではありません。
以下の例は、CHECK^%R のインスタンスに対する FMTERR^%R ルーチンの例です。
DATE
Synopsis
DATE^%R (rtn, format, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
format 希望するタイム・スタンプの形式
namesp ルーチンが保存されているネームスペース
概要
この関数は、指定されたルーチンが Caché に保存された日時を返します。
パラメータ
rtn
データベースから取得する、またはデータベースに保存するルーチンの名前を指定している文字列。"SomeRoutine.MAC" などのように、名前と拡張子がピリオドで区切られた完全なルーチン名を含む必要があります。この名前は、大文字と小文字を区別します。拡張子は大文字と小文字を区別しません。
指定されたルーチンが見つからなければ、この関数は NULL 文字列を返します。
format
返される日付と時間の形式を指定する整数。使用できる値は、$ZDATETIME 関数と同じです。format の値を使用して、日付部分をフォーマットします。時間は常に "HH:MM:SS" の形で表されます。
$ZDATETIME で許可されている値以外では、0 を指定すると、タイム・スタンプを $HOROLOG 形式で返します。
与えられた format 値が許可されたものでなければ、関数の値としてエラー・ステータスが返されます。以下はその例です。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、ルーチンに関連するタイム・スタンプを、ルーチンが保存された時間で返します。
Note:
ROUTINE^%R の呼び出し元が filedate パラメータで異なる値を提供している場合は、この値はルーチンが保存された実際の日付や時間と異なる値になります。
以下の例は、許可されているすべての形式で %R が保存された日付と時間を表示します。
    ; set up the data    
    Set name = "%R"
    Set ext = "OBJ"
    Set routine = name _ "." _ ext
    Set namespace = "%CACHELIB"
    
    ; do it
    Write "Timestamp for ", routine, !
    for fmt = 0 : 1 : 12
    {
        Set filedate = $$DATE^%R(routine, fmt, namespace)
        Write "Format ", fmt, ": ", ?10, filedate, !
    }
以下の例は、format の値が不正である場合に発生するエラー・ステータスを表示します。
    ; set up the data    
    Set name = "%R"
    Set ext = "OBJ"
    Set routine = name _ "." _ ext
    Set namespace = "%CACHELIB"
    
    ; do it
    Write "Timestamp for ", routine, !
    Set filedate = $$DATE^%R(routine, 100, namespace)
    Write "Value: ", ?10, filedate, !
指定された名前のルーチンがない場合は、以下の例のような結果になります。関数の値として NULL 文字列が返されます。
    ; set up the data    
    Set name = "%NONEXISTENT"
    Set ext = "OBJ"
    Set routine = name _ "." _ ext
    Set namespace = "%CACHELIB"
    
    ; do it
    Write "Timestamp for ", routine, !
    Set filedate = $$DATE^%R(routine, 1, namespace)
    Write "Return length: ", $LENGTH(filedate), !
    
DEL
Synopsis
DEL^%R (rtn, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
namesp ルーチンが保存されているネームスペース
概要
この関数は、指定されたルーチンを Caché データベースから削除します。
パラメータ
rtn
データベースから取得する、またはデータベースに保存するルーチンの名前を提供する文字列。この名前は、大文字と小文字を区別します。拡張子は大文字と小文字を区別しません。
この名前と拡張子には、ワイルドカードが含まれます。例えば、"Foo*.*" は、拡張子に関わらず最初の 3 文字が "Foo" であるすべてのルーチンを削除します。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、指定されたルーチンをデータベースから削除します。少なくとも 1 つのルーチンが見つかり削除された場合は 1 を返し、それ以外の場合は 0 を返します。
DEL^%R のインスタンスに対する ROUTINE^%R ルーチンの例を参照してください。
EXISTS
Synopsis
EXISTS^%R (rtn, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
namesp ルーチンが保存されているネームスペース
概要
この関数は、Caché データベース内に指定されたルーチンが存在するか否かを判断します。
パラメータ
rtn
検索されるルーチンの名前を指定する文字列。
この名前と拡張子には、ワイルドカードを含むことができます。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、指定されたネームスペースに rtn と一致するルーチンがあれば 1 を返し、なければ 0 を返します。
以下は、この資料の件名の有無を確認します。
    ; set up the data    
    Set ext = "OBJ"
    Set namespace = "%CACHELIB"
    
    ; do it
    for basename = "%R", "ArbitraryName"
    {
        Set routine = basename _ "." _ ext
        Set present = $$EXIST^%R(routine, namespace)
        Write routine, $SELECT(present:" exists",  1:" is missing"), "!", !
    }
LANG
Synopsis
LANG^%R (rtn, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
namesp ルーチンが保存されているネームスペース
概要
この関数は、指定されたルーチンの言語コードの値を返します。
パラメータ
rtn
有効な文字列として評価する式。文字列のコンテンツにより、検索するルーチンの名前を指定します。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、指定されたルーチンの言語モードをエンコードする整数値を返します。エンコードのリストは、このドキュメントの最初の部分に記載されています。
ルーチンの拡張子が無効である場合は、関数は空文字列を返します。拡張子が "MAC" であれば、ルーチンの有無に関わらず、返される値は 0 (ObjectScript) です。
以下の例では、いくつかのルーチンについて、記述される言語を確認します。
    ; set up the data    
    Set namespace = "%CACHELIB"
    
    set languages = $LISTBUILD("ObjectScript",
                               "DSM-11",
                               "DTM",
                               "",
                               "",
                               "DSM-VMS",
                               "DSM-J",
                               "DTM-J",
                               "MSM",
                               "Basic")
    
    ; do it
    for routine = "%R.OBJ", "ArbitraryName.MAC", "SomeOther.RTN"
    {
        Set code = $$LANG^%R(routine, namespace)
        If ($ISVALIDNUM(code))
        {
            Set lang = $LISTGET(languages, (code + 1), "")
            Set:(lang = "") lang = "Unknown"
            Write routine, " language: ", lang, !
        }
        Else
        {
            Write routine, ": invalid extension", !
        }
    }
LANGSET
Synopsis
LANGSET^%R (rtn, langmode)
パラメータ
rtn ターゲット・ルーチンの名前
langmode ソースの新規の言語を指定するインジケータ
概要
この関数は、指定されたルーチンの言語コードの値を返します。
パラメータ
rtn
検索されるルーチンの名前を指定する文字列。
langmode
rtn の文が記述されている言語を指定する整数。
備考
この関数は、データベース内のルーチンのソースが保存された言語エンコードを変更します。これは、従来のアプリケーションのための関数です。従来のアプリケーションは、複数のプラットフォームで動作し、実行時に環境に適応する必要があります。
この関数は、保存された言語モードの変更に成功した場合は 1 を返し、失敗した場合は 0 を返します。
 
LENGTH
Synopsis
LENGTH^%R (rtn, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
namesp ルーチンが保存されているネームスペース
概要
この関数は、データベースに保存されたルーチンの行数を返します。
パラメータ
rtn
検索されるルーチン (文字列として) の名前。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、データベースに保存されたルーチンの行数を整数値で返します。ルーチンが存在しない場合は、0 を返します。
以下はルーチンを生成し、それをデータベースに保存します。これは、ルーチンのインメモリ情報を消去し、その情報をデータベースに問い合わせます。
この例は、このドキュメントで説明されている、^%R 内の他のエントリ・ポイントを利用しています。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
    
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    ; Note leading spaces on the following entries"
    Set code($INCREMENT(N)) = "    Write ""Starting AnExample"", !"
    Set code($INCREMENT(N)) = ""
    Set code($INCREMENT(N)) = "    Write ""Some text"", !"
    Set code($INCREMENT(N)) = ""
    Set code($INCREMENT(N)) = "    Write ""Finished AnExample"", !"
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set routine = "AnExample.INT"
    Set options = "S"               ; Save
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    
    ; show the simple result
    Write "Save result: ", return, !
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
    }
    Else
    {
        ; remove local info
        Kill code
        
        ; find out about it
        Write "Lines in ", routine, ": ", $$LENGTH^%R(routine), !
        
        ; remove the saved source 
           Write "Removing ", routine, ": ", $$DEL^%R(routine), ! 
    }
SIZE
Synopsis
SIZE^%R (rtn, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
namesp ルーチンが保存されているネームスペース
概要
この関数は、データベースに保存されたルーチンの文字数を返します。
パラメータ
rtn
検索されるルーチンの名前を提供する文字列。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、データベースに保存されたルーチンの文字数を整数値で返します。ルーチンが存在しない場合は、0 を返します。
以下はルーチンを生成し、それをデータベースに保存します。これは、ルーチンのインメモリ情報を消去し、その情報をデータベースに問い合わせます。
この例は、このドキュメントで説明されている、^%R 内の他のエントリ・ポイントを利用しています。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
    
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    ; Note leading spaces on the following entries"
    Set code($INCREMENT(N)) = "    Write ""AnExample"", !"
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set routine = "AnExample.INT"
    Set options = "S"               ; Save
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    
    ; show the simple result
    Write "Save result: ", return, !
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
    }
    Else
    {
        ; remove local info
        Kill code
        
        ; find out about it
        Write "Characters in ", routine, ": ", $$SIZE^%R(routine), !
        
        ; remove the saved source 
           Write "Removing ", routine, ": ", $$DEL^%R(routine), ! 
    }
LINE
Synopsis
LINE^%R (rtn, linenum, namesp)
パラメータ
rtn ターゲット・ルーチンの名前
linenum 希望する行数
namesp ルーチンが保存されているネームスペース
概要
この関数は、データベースに保存されたルーチンからソースの行を返します。
パラメータ
rtn
検索されるルーチン名。
linenum
希望するコンテンツを持つルーチンの行の番号。ルーチンの最初の行の番号は常に 1 です。
namesp
指定されたルーチンが保存されているネームスペースを表す値を持つ文字列。このパラメータはオプションです。指定されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、希望する行の内容を文字列として返します。linenum が以下の制約を満たしていない場合、
その行は存在せず、関数は結果として空文字列を返します。この関数だけでは、存在しない行なのか、行に文字が含まれていないのかを見分けることはできません。
以下はルーチンを生成し、それをデータベースに保存します。これは、ルーチンのインメモリ情報を消去し、その情報をデータベースに問い合わせます。
この例は、このドキュメントで説明されている、^%R 内の他のエントリ・ポイントを利用しています。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
    
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    ; Note leading spaces on the following entries"
    Set code($INCREMENT(N)) = "    Write ""AnExample"", !"
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set routine = "AnExample.INT"
    Set options = "S"               ; Save
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    
    ; show the simple result
    Write "Save result: ", return, !
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
    }
    Else
    {
        ; remove local info
        Kill code
        
        ; list the routine backwards
        For i = $$LENGTH^%R(routine) : -1 : 1
        {
            Write "Line ", i, ":: ", $$LINE^%R(routine, i), !
        }
        
        ; remove the saved source 
           Write "Removing ", routine, ": ", $$DEL^%R(routine), ! 
    }
LINESET
Synopsis
LINESET^%R (rtn, linenum, linetext)
パラメータ
rtn ターゲット・ルーチンの名前
linenum 置換する、または追加する行数
linetext 新規の行の内容
概要
この関数は、指定されたルーチンが示す位置にソース・テキストを挿入します。
パラメータ
rtn
修正されるルーチンの名前を指定する文字列。
linenum
希望するコンテンツを持つルーチンの行の番号。ルーチンの最初の行の番号は 1 です。
linetext
ルーチンに挿入されるソース・テキストの文字列。
備考
この関数は、ルーチンの linenum の位置に linetext を挿入します。条件
上記の条件に該当する場合、ルーチン・ソースは空の行をソースに追加することにより効率的に拡張され、
その結果、linenum の範囲は以下のようになります。
そして、その行の既存のテキストが置換されます。
この関数は、置換に成功すると結果として 1 を、それ以外の場合は 0 を返します。
Note:
行を 1 行置換しても、対応するオブジェクト・ルーチンに影響はありません。その変更を有効にするには、ソース・ルーチンをリコンパイルする必要があります。
以下はルーチンを生成し、それをコンパイルしてデータベースに保存します。これは、ルーチンのインメモリの情報を消去し、新しく作成されたルーチンを呼び出します。
そして、ソースの行を変更し、ルーチンを呼び出して、オブジェクトにまだ変更がないことを示します。
最後に、データベースから新しいソースをロードして、リコンパイル、保存し、再度このルーチンを呼び出して変更が有効になっていることを表します。
この例は、このドキュメントで説明されている、^%R 内の他のエントリ・ポイントを利用しています。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
    
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    ; Note leading spaces on the following entries"
    Set code($INCREMENT(N)) = "    Write ""User: """"Hello, world"""""", !"
    Set code($INCREMENT(N)) = "    ; A dummy line to be replaced later"
    Set ReplaceLoc = N
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set name = "AnExample"
    Set ext = "INT"
    Set routine = name _ "." _ ext
    Set options = "CS"              ; Compile and Save
    Set errors = ""                 ; empty list
    
    ; do it
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
        Quit
    }
    
    ; run it
    Set entrypoint = name _ "^" _ name
    Do @entrypoint
    
    Set NewLine = "    Write ""World: """"Hello yourself"""""", !"
    If ($$LINESET^%R(routine, ReplaceLoc, NewLine) '= 1)
    {
        Write "Line replacement failed", !
        Quit
    }
    
    ; show what is in the local array and in database
    Write "Local: ", code(ReplaceLoc), !
    Write "Saved: ", $$LINE^%R(routine, ReplaceLoc), !
    
    ; run it again to show same result
    Do @entrypoint

    ; load, re-compile and save
    Write "Updating...", !
    Set return = $$ROUTINE^%R(routine, .code, .errors, "LCS")
    If (+return = "")
    {      
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
        Quit
    }
    
    ; run it one last time to show change
    Do @entrypoint

    ; remove the source and object
    for suffix = "int", "OBJ"      
    {
        Set component = name _ "." _ suffix
        Write "Removing ", component, ": ", $$DEL^%R(component), ! 
    }
LOCK
Synopsis
LOCK^%R (rtn, timeout)
パラメータ
rtn ターゲット・ルーチンの名前
timeout 試行を中止する前に待機する秒数
概要
この関数は、データベースに保存されたルーチンへの排他的なアクセスを試みます。
パラメータ
rtn
文字列としてロックされるルーチンの名前です。
timeout
ルーチンが、そのルーチンのロックの取得を中止する前に待機する最大秒数を指定する整数。このパラメータはオプションです。これが提供されていない場合は、デフォルトの timeout は 2 です。
備考
これは、データベースに保存されたルーチンへの排他的なアクセスを試みます。この試行が成功すれば 1 を、ロックが取得できなければ 0 を返します。
 
UNLOCK
Synopsis
UNLOCK^%R (rtn)
パラメータ
rtn ターゲット・ルーチンの名前
概要
この関数は、UNLOCK のアクションを取り消します。
パラメータ
rtn
文字列として (ロックされるであろう) ルーチンの名前です。
備考
この関数は、UNLOCK 経由で取得したルーチンのロックを中止します。この試行が成功すれば 1 を返します。また例えば、ルーチンが以前にロックされていなかったなど、オペレーションが失敗した場合は 0 を返します。
 
VERMAX
Synopsis
VERMAX^%R (extent, namesp)
パラメータ
extent 希望するバージョン情報を持つエクステント
namesp このエクステントが保存されているネームスペース
概要
この関数は、ルーチンのバージョン番号を、このエクステントと一緒に返します。このエクステントは維持されます。
パラメータ
extent
希望するバージョン情報に対するエクステントを指定する文字列。
namesp
文字列の内容は、ネームスペースを指定して、エクステントのバージョン情報を調査します。これが提供されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、特定のエクステントについてのバージョン情報を、指定されたネームスペースで調査します。この呼び出しの前に、アプリケーションによって明示的にバージョン情報が設定されていなければ、システムのデフォルト値 (現在は 4) を使用します。
N は関数が返す値です。その他に現在のバージョン (最新またはマスタ・バージョン) が 1 つと N-1 バックアップ・バージョンがあります。
Note:
バックアップとして利用できるバージョン番号は、連番の数列である必要はありません。中間のバージョンは、DEL^%R への呼び出しにより削除されている可能性もあります。
以下の例は、バージョン管理に関する多くのエントリ・ポイントの使用法を示します。
Warning:
この例は、AnExample.INT という SAMPLES ネームスペース内にルーチンを作成します。その名前のルーチンがそのネームスペースにすでにある場合は、オーバーライドします。
    ; Change the namespace we will use
    Znspace "SAMPLES"
        
    ; fill in the source code array
    Set N = 0
    Set code($INCREMENT(N)) = "AnExample ; An example routine"
    Set code($INCREMENT(N)) = "    Write ""Starting AnExample"", !"
    Set code($INCREMENT(N)) = "    Write ""Line to be replaced"", !"
    Set lininx = N
    Set code($INCREMENT(N)) = "    Write ""Finished AnExample"", !"
    Set code($INCREMENT(N)) = "    Quit"
    Set code(0) = N
    
    Set name = "AnExample"
    Set ext = "MAC"
    Set routine = name _ "." _ ext
    Set options = "BCS"              ; Backup, Compile and Save
    Set errors = ""                 ; empty list
    Set abort = 0
    
    ; get the number of backups
    Set maxvers = $$VERMAX^%R(ext)
    Write "Default versions: ", maxvers, !
    ; increase it by one
    Do VERMAXSET^%R(ext, (maxvers + 1))
    ; confirm it
    set maxvers = $$VERMAX^%R(ext)
    Write "Explicit versions: ", maxvers, !
    
    ; process the base version
    Set return = $$ROUTINE^%R(routine, .code, .errors, options)
    ; show the simple result
    Write "Compilation result: ", return, !
    If (+return = "")
    {  
        ; format and display the errors
        Write $$FMTERR^%R(.errors, .code), !
        set abort = 1
    }
    Else
    {
        ; run it
        Write "Calling AnExample", !
        Set entrypoint = name _ "^" _ name
        Do @entrypoint
    }
    Quit:(abort)
    
    ; generate a bunch of versions
    for i = 1 : 1 : 10
    {
        ; process the new version
        Write !, "Loop ", i, !
        Set code(lininx) = "    Write ""Iteration " _ i _ """, !"
        Set return = $$ROUTINE^%R(routine, .code, .errors, options)
        ; show the simple result
        Write "Compilation result: ", return, !
        If (+return = "")
        {  
            ; format and display the errors
            Write $$FMTERR^%R(.errors, .code), !
            set abort = 1
        }
        Else
        {
            ; run it
            Write "Calling AnExample", !
            Set entrypoint = name _ "^" _ name
            Do @entrypoint
        }
        
        ; get the version boundaries
        Set oldest = $$VERSION1^%R(routine)
        Set vername = routine _ "." _ "-1"
        Set youngest = $$VERSION^%R(vername)
        Write "Oldest: ", oldest, "; ", "Youngest: ", youngest, !
    }
    ; remove the source and object
    for suffix
VERMAXSET
Synopsis
VERMAX^%R (extent, max, namesp)
パラメータ
extent 希望するバージョン情報を持つエクステント
max 保存されるバージョンの最大数
namesp このエクステントが保存されているネームスペース
概要
この関数は、ルーチンのバージョン番号を、このエクステントと一緒に設定します。このエクステントは、指定されたネームスペースで保持されます。
パラメータ
extent
文字列の内容は、希望するバージョン情報に対するエクステントを指定します。
max
正のゼロ以外の整数に評価する式。バージョンの番号は、バックアップとして保持されます。
namesp
文字列の内容は、ネームスペースを指定して、エクステントのバージョン情報を調査します。これが提供されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、指定されたネームスペースの特定のエクステントについての、バージョン情報を設定します。max を 1 に設定すると、最新のバージョンのみが保存されます。
新規の最大数が設定されると 1 を返し、そうでない場合は 0 を返します。
VERMAX^%R エントリ・ポイントと提供されている例を参照して下さい。
VERSION1
Synopsis
VERSION1^%R (rtn, namesp)
パラメータ
rtn ルーチン名を与えて文字列に評価される式
namesp このエクステントが保存されているネームスペース
概要
これは、バックアップとして保持されているもののうち、最も古い番号を返します。
パラメータ
rtn
ルーチンの名前を提供する文字列。アプリケーションは、このルーチンの最も古いバージョンに動作します。これは、名前の一部としてエクステントを含みます。この名前は、大文字と小文字を区別します。エクステントは区別しません。rtn の一部として提供される任意のバージョン番号は、無視されます。
namesp
有効な文字列として評価する式。文字列の内容は、ネームスペースを指定して、エクステントのバージョン情報を調査します。これが提供されていない場合は、現在のネームスペースであるとみなします。
備考
この関数は、指定されたネームスペースを調査して、バックアップされた特定のルーチンのバージョンを検索します。最も古いルーチンのバージョン番号が返されます。
VERMAX^%R エントリ・ポイントと提供されている例を参照して下さい。
VERSION
Synopsis
VERSION^%R (rtn, namesp)
パラメータ
rtn ルーチン名を与えて文字列に評価される式
namesp このエクステントが保存されているネームスペース
概要
これは、最新のバージョンに関連するバージョン番号を返します。
パラメータ
rtn
ルーチンの名前を指定する文字列。これは、名前の一部としてエクステントを含みます。この名前は、大文字と小文字を区別します。エクステントは区別しません。バージョン番号は、符号付きの値で表し、最新のバックアップとの関係を示します。例えば、“SomeRoutine.MAC.-1” は、最新のものの 1 つ前のルーチンのバージョン番号を要求します。
namesp
有効な文字列として評価する式。文字列の内容は、ネームスペースを指定して、エクステントのバージョン情報を調査します。これが提供されていない場合は、現在のネームスペースであるとみなします。
備考
名前のバージョン部分が関係ない場合は、指定されたバージョン番号を返します。関係がある場合は、最新バージョンに関連するバックアップのバージョン番号を返します。
指定されたバージョンが存在しない場合は、このルーチンは 0 を返します。
VERMAX^%R エントリ・ポイントと提供されている例を参照して下さい。