type1 ::= '['['0':'?']*['':'/']*{'@':DEL}
type2 ::= [';'|'?'|'O']['':'/']*{'0':DEL}
ここで使用されている構文記号の意味は次のとおりです。
記号 |
説明 |
: |
x:y は、ASCII シーケンスで x から y の指定範囲の文字を意味します。 |
| |
x|y は、x または y を意味します。 |
[ ] |
0 あるいは指定されたセットのいずれか 1 つのメンバを指定します。 |
[ ]* |
0 あるいは指定されたセットのいずれか 1 つ以上のメンバを指定します。 |
{ } |
指定されたセットのいずれか 1 つのメンバを指定します。 |
InterSystems IRIS が ESCAPE を検出すると、他のエスケープ・シーケンスが出現するかどうか 1 秒間待機します。エスケープ・シーケンスがこの構文に一致しない場合、長さが 15 文字を超過する場合、あるいは有効なエスケープ・シーケンスが 1 秒以内に到着しない場合、InterSystems IRIS は、一部のエスケープ・シーケンスを $ZB に配置し、“BADESC” ビット (256) を $ZA に設定します。
ストリーム・モード (S モード)
ストリーム・モードでは、InterSystems IRIS は データ・ストリームに TCP メッセージの範囲を保存しようとしません。送信時、データがメッセージ・バッファ・サイズに適合しない場合、InterSystems IRIS は、データをバッファに配置する前に、バッファをフラッシュします。
受信時、最大長までの文字列データを受信できます。すべての読み取りは、ターミネータが完全なタイムアウトに達するまで、あるいはバッファが一杯になるまで待機します。このモードが無効の場合 (既定)、パケット・モードになります。
TCP デバイスを継承するジョブ起動プロセスは、自動的にストリーム形式に設定されます。USE コマンドを使用して、この形式をリセットできます。
バッファ・サイズ
TCP デバイスの ibufsiz パラメータおよび obufsiz パラメータは、TCP 入出力の内部 InterSystems IRIS バッファのサイズを指定します。これにはサポート対象のすべてのプラットフォーム上で、1 KB から 1 MB の範囲内の値を指定できます。ただし、オペレーティング・システムのプラットフォームは、それ自体の入出力バッファに異なるサイズを使用する場合があります。オペレーティング・システム・プラットフォームのバッファが InterSystems IRIS バッファよりも小さい場合 (1 MB に対して 64 KB しかないなど)、パフォーマンスが影響を受ける可能性があります。例えば、WRITE 操作は InterSystems IRIS バッファ全体を送信するために OS に何度も要求を出すことが必要になる可能性があり、READ 操作は OS バッファ・サイズにより制限される複数の小さいチャンクを返す可能性があります。最適なパフォーマンスを得るために、ibufsiz および obufsiz にどの値を指定すると最適な結果になるかを見極めるには、現在の OS でテストすることが必要です。
サーバ側の OPEN コマンド
サーバ側で OPEN コマンドが処理されると、TCP ソケットが構築され、適切なポート番号に接続要求が入力されるのをソケットで待ち受けます。ポート番号は、パラメータ・リストで明示的に指定します。指定していない場合は、devicename の数値部から取得されます。ソケットが待ち受け状態になるとすぐに、OPEN コマンドが返されます。
OPEN が失敗した場合、別のプロセスがポート番号の接続要求を既に待ち受けている場合があります。
以下の例は、サーバ側の OPEN でデバイスを指定します。これにより、最大文字列サイズ以下の文字列を読み書きできます。また、最大文字列読み取りを使用し、TCP チャネルの使用を統合する処理を書き込みます。
OPEN "|TCP|4":(:4200:"PSTE"::32767:32767)
この例の parameters 引数は次のようになります。これは、サーバ側の OPEN コマンドなので、最初のパラメータ (hostname) が省略されています。2 番目のパラメータには明示的にポート番号 (4200) を指定します。3 番目のパラメータは、mode コード文字です。4 番目のパラメータ (terminators) は省略されています。5 番目のパラメータは入力バッファのサイズを指定します。6 番目のパラメータは出力バッファのサイズを指定します。
以下の例では、ポート番号はパラメータとして指定されません。devicename の数値部から取得します。この例では、パラメータを指定せず、10 秒のタイムアウトでポート 4200 を開きます。
OPEN "|TCP|4200"::10
サーバ側の OPEN の入力バッファのサイズ (ibufsiz) と出力バッファのサイズ (obufsiz) の既定のパラメータ値は 1,048,576 バイト (1 MB) です。
サーバ側の OPEN コマンドは、オプションの queuesize パラメータと、オプションの “G” モード・パラメータをサポートしています。これらのオプションは、クライアント側の OPEN コマンドでは利用できません。
サーバ側の OPEN は、オプションの /CLOSELISTEN キーワード・パラメータをサポートします。このオプションは、クライアント側の OPEN コマンドでは利用できません。
クライアント側の OPEN コマンド
クライアント側の OPEN コマンドがサーバ側の OPEN コマンドと異なる点は、接続するホストを最初のデバイス・パラメータで指定する必要があるということだけです。ホストを指定するには、クライアントでホストあるいはインターネット・アドレスとして認識できる名前を使用します。
OPEN コマンドは、接続されるとすぐに実行します。この時点で、TCP デバイスへの読み取り、あるいは書き込みが可能です。ただし、サーバ側の接続が別の InterSystems IRIS プロセスの場合、WRITE コマンドによるクライアントからサーバへのデータ送信が実行されない限り、サーバ側の接続は完了しません。したがって、READ コマンドの発行前に WRITE コマンドを発行する必要があります。
詳細は、“TCP デバイスの WRITE コマンド” のセクションを参照してください。
以下は、クライアント側の OPEN コマンドの例です。
OPEN "|TCP|4":("hal":4200::$CHAR(3,4)):10
このコマンドは、ポート 4200 にホスト hal への接続を開きます。モード文字は指定されていません。2 つのターミネータ (ASCII $CHAR(3) および $CHAR(4))、既定の入力バッファ・サイズと出力バッファ・サイズを指定します。さらに、10 秒のタイムアウトを指定します。
以下のコマンドは、宛先の IP アドレスを IPv4 形式で明示的に記述している以外は、上記のコードと同じです。
OPEN "|TCP|4":("129.200.3.4":4200::$CHAR(3,4)):10
OPEN キーワード /USEIPV6 を使用して、使用するプロトコルを指定できます。IPv4 および IPv6 の形式に関する詳細は、"サーバ側プログラミングの入門ガイド" の “サーバ構成オプション” の章にある “IPv6 アドレスの使用” のセクションを参照してください。
以下のコマンドは、リモート・ホスト “larry” の時刻サーバに接続し、主要入力デバイスにリモート・ホストの日時を ASCII 形式で出力します。このコマンドではサービス名 daytime を使用しますが、これはローカル・システムでポート番号に解決されます。
OPEN "|TCP|4":("larry":"daytime":"M")
USE "|TCP|4"
READ x
USE 0
WRITE x
以下のコマンドは、x を “hello” に設定します。
OPEN "|TCP|4":("larry":"echo":"M")
USE "|TCP|4"
WRITE "hello",!
READ x
以下のコマンドは、インターネット・アドレス 128.41.0.73、ポート番号 22101 を、30 秒のタイムアウトで接続します。
OPEN "|TCP|22101":"128.41.0.73":30
TCP デバイスの OPEN コマンド・キーワードと USE コマンド・キーワード
上記で説明した位置パラメータ、またはキーワード・パラメータを使用できます。以下のテーブルは、OPEN コマンドと USE コマンドの両方を使用して、TCP デバイスを制御するキーワードの説明です。OPEN コマンドのみで指定可能な OPEN コマンド専用のキーワード (この章で後述) もあります。キーワード・パラメータはすべてオプションです。
TCP デバイスの OPEN コマンド・キーワードと USE コマンド・キーワード
キーワード |
既定 |
説明 |
/ABSTIMEOUT[=1] |
0 |
読み取りタイムアウトの動作を指定します。データを受信した際に TCP によってタイムアウト期間を再初期化するかどうかを決定します。/ABSTIMEOUT=0 (既定) の場合は、各時刻データの受信時にタイムアウトを元の値にリセットします。/ABSTIMEOUT もしくは /ABSTIMEOUT=1 の場合は、データを受信する間、タイムアウト期間のカウント・ダウンを続けます。 |
/ACCEPT[=n]
または
/ACC[=n] |
0 |
“A” モード・パラメータ文字に相当します。クライアント・ジョブからの接続が受け入れられるとすぐに、サーバでの初期の読み取りが長さ 0 の文字列で終了するように指定します。/ACCEPT と /ACCEPT=n の n が 0 以外の場合、A モードが有効になります。/ACCEPT=n の n が 0 の場合、A モードが無効になります。 |
/CLOSEFLUSH[=n] |
1 |
デバイスが閉じられている場合、出力バッファに残っているデータの処理を指定します。 /CLOSEFLUSH と /CLOSEFLUSH=n の n が 0 以外の場合、残りのデータをフラッシュします。/CLOSEFLUSH=n の n が 0 の場合、残りのデータを破棄します。 |
/COMPRESS=str |
"" |
ストリーム・データの圧縮タイプを指定します。圧縮タイプ ZLIB または ZSTD を有効にすることができます。/COMPRESS="" を指定すると、圧縮を無効にすることができます。/COMPRESS="zlib" は /GZIP=1 と同等です。文字列を圧縮するには、%SYSTEM.Util.Compress()Opens in a new tab を使用します。 |
/CRLF[=n] |
0 |
“C” モード・パラメータ文字に相当します。入出力を戻すキャリッジ・リターン処理を変更します。/CRLF と /CRLF=n の n が 0 以外の場合、C モードが有効になります。/CRLF=n の n が 0 の場合、C モードが無効になります。 |
/ESCAPE[=n]
または
/ESC[=n] |
0 |
“E” モード・パラメータ文字に相当します。入力ストリームでエスケープ・シーケンスを構文解析し、$ZB に配置するように指定します。/ESCAPE と /ESCAPE=n の n が 0 以外の場合、E モードが有効になります。/ESCAPE=n の n が 0 の場合、E モードが無効になります。 |
/GZIP[=n] |
1 |
GZIP と互換性のあるストリーム・データ圧縮を指定します。/GZIP を指定した場合、または /GZIP=n (n は 0 以外) を指定した場合、WRITE の発行時に圧縮、READ の発行時に解凍が有効になります。/GZIP=0 を指定した場合は、圧縮と解凍が無効になります。/GZIP=0 を発行して、圧縮/解凍を無効にする前に、$ZEOS 特殊変数をチェックして、ストリーム・データの読み込みが実行中でないことを確認してください。/GZIP 圧縮は、/IOTABLE を使用して構築した変換などの入出力変換には影響しません。これは、圧縮がその他すべての変換 (暗号化を除く) の後に適用され、解凍がその他すべての変換 (暗号化を除く) の前に適用されるためです。圧縮データで使用する WRITE に関する詳細は、この章の "WRITE コントロール・コマンド" を参照してください。 |
/IOTABLE[=name]
または
/IOT[=name] |
name が指定されない場合、デバイスの既定の入出力変換テーブルを使用します。 |
デバイスの入出力変換テーブルを構築します。 |
/KEEPALIVE=n |
システムの既定 |
(Windows、AIX、Linux のみ) このデバイスに、システムの既定とは異なるキープアライブ・タイマを設定することができます。TCP 接続を保持する秒数を指定する整数。keepalivetime 位置パラメータと同じです。有効値は、30 ~ 432000 の範囲 (432,000 秒は 5 日) です。30 未満の値は、既定で 30 となります。省略した場合または 0 に設定した場合は、システムの既定値が使用されます。/NOKEEPALIVE を使用して、この設定を無効にできます。一度無効にすると、TCP デバイスが閉じるまで再度有効にすることはできません。 |
/NODELAY=n |
1 |
パケットをまとめて送信するか、個々に送信するかを指定します。/NODELAY=1 (既定) に指定すると、パケット単位で直ちに転送されます。/NODELAY=0 に指定すると、最適化アルゴリズムを使用して TCP ドライバでパッケージが 1 つにまとめられます。これにより、パケット単位で見るとわずかな転送遅延が生じる場合がありますが、ネットワーク・トラフィックが減少することで、全体的なパフォーマンスの向上が望めます。/NODELAY に相当するモード・パラメータ文字はありません。/NODELAY は、/SENDIMMEDIATE との関係を考慮して使用する必要があります。 |
/NOKEEPALIVE |
|
指定した場合、システム規模の TCP キープアライブ・タイマはこのデバイスに対して無効になります。InterSystems IRIS の既定では、TCP デバイスを開く際に、このタイマが有効になります。OPEN または USE で /NOKEEPALIVE オプションを使用すると、この既定がオーバーライドされます。/KEEPALIVE を使用して既定以外のキープアライブ・タイマを設定している場合は、/NOKEEPALIVE によりそのキープアライブ・タイマを無効にできます。一度キープアライブ・タイマを無効にすると、TCP デバイスを閉じるまで再度有効にすることはできません。"/KEEPALIVE" を参照してください。 |
/NOXY [=n] |
0 |
$X および $Y の処理なし : /NOXY を指定した場合、または /NOXY=n (n は 0 以外の値) を指定した場合、$X および $Y の処理が無効になります。例えば、CSP などで、デバイスの $X/$Y を使用しない場合に、パフォーマンスを向上できます。これにより READ 操作および WRITE 操作のパフォーマンスを大幅に向上させることができます。このオプションは、スーパーサーバ・ワーカ・ジョブの既定の設定です。/NOXY=1 の場合、$X および $Y の変数値が不確定であるため、マージン処理 ($X に依存) は無効になります。/NOXY=0 の場合は、$X および $Y の処理が有効になります。これが既定です。/TCPNOXY は /NOXY の非推奨の同義語です。 |
/OBCOUNT=n |
16 |
/ZEROCOPY で使用する出力バッファの数。既定の出力バッファ数は 16 です。出力バッファの最小数は 2 で、最大数は 128 です。n の値は 2 の累乗である必要があります。2 の累乗でない値を指定すると、2 の累乗に切り上げられます。 |
/PAD[=n] |
0 |
“P” モード・パラメータ文字に相当します。これは WRITE ! (LF ターミネータ) または WRITE # (FF ターミネータ) の実行時に、出力にレコード・ターミネータ文字が埋め込まれることを指定します。/PAD と /PAD=n の n が 0 以外の場合、P モードが有効になります。/PAD=n の n が 0 の場合、P モードが無効になります。 |
/PARAMS=str
または
/PAR=str |
既定なし |
mode 位置パラメータに相当します (位置に依存しない方法でモード文字列を指定する方法を提供します)。 |
/POLL[=n]
または
/POLLDISCON[=n] |
|
切断の非同期監視を指定する “D” モード・パラメータ文字に相当します。/POLL または /POLL=1 は +D に相当し、/POLL=0 は -D に相当します。 |
/PSTE[=n] |
0 |
“M” モード・パラメータ文字に相当します。これは、P、S、T、E モード・パラメータ文字を指定する省略表現です。/PSTE と /PSTE=n の n が 0 以外の場合、P、S、T、E モードが有効になります。/PSTE=n の n が 0 の場合、これらのモードが無効になります。 |
/SENDIMMEDIATE[=n]
または
/SEN[=n] |
0 |
“Q” モード・パラメータ文字に相当します。これは、即時送信モードを指定します。 |
/SSL="cfg[|pw] [|DNShost]"
or
/TLS="cfg[|pw] [|DNShost]" |
既定なし |
クライアントが指定した構成とサーバ要件に従い、SSL/TLS で保護された接続のネゴシエーションをデバイスで試行するようにクライアントから指定します。サーバとしてソケットを保護する場合は、サーバが指定した構成とクライアント要件に従い、SSL/TLS で保護された接続をサーバで必要とすることを指定します。
cfg は、接続またはソケットの構成名を指定します。pw は、秘密鍵ファイルのオプションのパスワードを指定します。DNShost は、特定のサーバの完全修飾された DNS ホスト名を指定します。これは、サーバー ネーム インディケーション (SNI) の TLS Extension で使用します。詳細は以下を参照してください。
この構成名は、OPEN または USE コマンド後の初回の I/O 動作時にのみ使用されます。それ以降の呼び出しは無視されます。/SSL="" または /TLS="" は無視されます。詳細は、インターシステムズの "TLS ガイド" を参照してください。
重要 : SSL/TLS を使用している新規の TCP 接続を開くときまたはそのような既存の接続を保護するときにパスワードを含める機能は、リアルタイムのインタラクティブを使用する場合にのみ有効です。保護していない秘密鍵パスワードを永続的に保存することは絶対に避けてください。そのようなパスワードを保存する必要がある場合は、Security.SSLConfigsOpens in a new tab クラスの PrivateKeyPassword プロパティを使用します。 |
/STREAM[=n]
または
/STR[=n] |
0 |
“S” モード・パラメータ文字に相当します。TCP メッセージ範囲を保存しないデータを処理するストリーム・モードを指定します。/STREAM と /STREAM=n の n が 0 以外の場合、S モードが有効になります。/STREAM=n の n が 0 の場合、S モードが無効になります。 |
/TCPNOXY |
|
非推奨。/NOXY の同義語です。 |
/TCPRCVBUF=n |
既定の受信バッファ・サイズ。 |
受信キューのバッファ・サイズをバイト単位で設定します。TCP プロトコルでサイズの大きいウィンドウをサポートするために、バッファ・サイズを既定値から増やす場合に使用できます。ウィンドウのサイズが大きいと、長い遅延を持つリンクまたは広帯域リンクのパフォーマンスが向上します。適切な値については、使用しているオペレーティング・システムやハードウェアのドキュメントを参照してください。 |
/TCPSNDBUF=n |
既定の送信バッファ・サイズ。 |
送信キューのバッファ・サイズをバイト単位で設定します。TCP プロトコルでサイズの大きいウィンドウをサポートするために、バッファ・サイズを既定値から増やす場合に使用できます。ウィンドウのサイズが大きいと、長い遅延を持つリンクまたは広帯域リンクのパフォーマンスが向上します。適切な値については、使用しているオペレーティング・システムやハードウェアのドキュメントを参照してください。 |
/TERMINATOR=str
または
/TER=str |
既定なし |
ユーザ定義のターミネータを構築する terminators 位置パラメータに相当します。 |
/TMODE[=n]
または
/TMO[=n] |
0 |
“T” モード・パラメータ文字に相当します。標準読み取りターミネータで CR、LF、FF を指定します。/TMODE と /TMODE=n の n が 0 以外の場合、T モードが有効になります。/TMODE=n の n が 0 の場合、T モードが無効になります。 |
/TRANSLATE[=n]
または
/TRA[=n] |
1 |
/TRANSLATE を指定した場合、または /TRANSLATE=n の n が 0 以外の場合、デバイスの入出力変換が有効になります。/TRANSLATE=n の n が 0 の場合はデバイスの入出力変換が無効になります。 |
/WAIT[=n] |
0 |
“W” モード・パラメータ文字に相当します。出力バッファが、WRITE ! と WRITE # コマンドでフラッシュされないようにします。フラッシュは次の WRITE *-3 コマンドまで待機します。/WAIT と /WAIT=n の n が 0 以外の場合、W モードが有効になります。/WAIT=n の n が 0 の場合、W モードが無効になります。 |
/WRITETIMEOUT[=n] |
-1 |
TCP の書き込み操作のためのタイムアウト (秒) を設定します。書き込みが n 秒以内で完了しない場合、InterSystems IRIS は <TCPWRITE> エラーを発行します。<TCPWRITE> エラーが発行された場合、ユーザ・アプリケーションで即座に TCP デバイスを閉じて、データ損失を防止する必要があります。InterSystems IRIS では、<TCPWRITE> エラーに続けて TCP の書き込み操作を試行することはありません。n の最小値はシステムによって異なります。n がプラットフォームの最小タイムアウト値よりも小さい場合、InterSystems IRIS ではプラットフォームの最小値が使用されます。n を 2 未満とすることはできません。既定 (-1) はタイムアウトの強制がないことを示しています。 |
/XYTABLE[=name]
または
/XYT[=name] |
name が指定されていない場合、デバイスの既定の $X/$Y アクション・テーブルを使用します。 |
デバイスの $X/$Y アクション・テーブルを構築します。/NOXY を参照してください。 |
/ZEROCOPY[=bool] |
0 |
/ZEROCOPY または /ZEROCOPY=1 が指定されている場合、この TCP デバイスの ZEROCOPY 機能を有効にします。ZEROCOPY は send() 時に MSG_ZEROCOPY を利用するために、TCP デバイスの複数の出力バッファをサポートします。バッファが TCP スタックからの通知によって確認されるまで、TCP デバイスは出力バッファを再利用できません。TCP デバイスの出力バッファ数を設定するには、/OBCOUNT キーワードを使用します。/ZEROCOPY=0 が指定されている場合、この TCP デバイスの ZEROCOPY 機能を無効にします。MSG_ZEROCOPY は、Linux 4.15 以降でサポートされます。オペレーティング・システムで MSG_ZEROCOPY がサポートされない場合、TCP デバイスの ZEROCOPY は常に無効です。 |
SSL/TLS コンポーネント
TCP デバイス OPEN または USE /SSL または /TLS キーワード・パラメータの値は、引用符付き文字列です。この文字列は、1 つ、2 つ、または 3 つのコンポーネントを '|' 文字で区切って持つことができます。
パラメータ |
説明 |
cfg |
この接続に使用する SSL 構成の名前。このコンポーネントは必須です。 |
pw |
オプション — ローカルの秘密鍵ファイルのパスワード。ユーザが昇格されて実行時にパスワードを入力するとき、これはインタラクティブなアプリケーション専用です。これは、永続的に格納されるパスワードでは使用しないでください。永続ストレージには Security.SSLConfigs.PrivateKeyPassword プロパティを使用します。 |
DNShost |
オプション — SSL クライアント専用。サーバ選択証明書 (ホスト名検証用) または特定のサーバの完全修飾 DNS ホスト名 (サーバ名表示用) のいずれかを指定します。 pw を省略した場合、プレースホルダ '|' 文字を指定する必要があります。
ホスト名検証は、クライアントがサーバから受信した証明書に、クライアントが接続しようとしたホスト名のフィールドが含まれていることを、クライアントが確認できるようにする機能です。これは、URL のサーバ名に対応する、完全修飾されたサーバ DNS ホスト名がサーバの X.509 証明書 (subjectAltName Extension または Subject CN フィールド) に含まれていることを確認するクライアント・アプリケーション (%Net.HttpRequest() など) が使用します。これにより、クライアントは、中間者攻撃で間違ったドメインに対して有効な証明書を使用するケースを検出することができます。
サーバ名表示 (SNI) は、クライアントが要求しているホスト名をサーバに送信できるようにする機能です。これにより、複数のドメインを処理するサーバが、複数の証明書のうちの 1 つを選択して返すことができます。サーバは、クライアント上のホスト名の照合に一致するものを選択できます。 |
以下に示すのは、有効な /TLS キーワード・パラメータの例です。
/TLS="Client"
/TLS="Client|password"
/TLS="Client||www.intersystems.com"
/TLS="Client|password|www.intersystems.com"
TCP デバイスの OPEN コマンドのみのキーワード
以下の表は、OPEN コマンドのみで指定可能な TCP デバイスを制御するキーワードの説明です。OPEN コマンドまたは USE コマンドで指定可能な OPEN/USE コマンドのキーワード (この章で前述) もあります。キーワード・パラメータはすべてオプションです。
TCP デバイスの OPEN コマンドのみのキーワード
キーワード |
既定 |
説明 |
/BINDTO[=address] |
|
接続の開始時に使用される指定ローカル・アドレスにバインドします。クライアントの場合は、InterSystems IRIS からの TCP/IP 接続をオープンするときに使用されるソース・アドレスです。サーバの場合は、InterSystems IRIS プロセスが TCP/IP 接続をオープンするときに接続を受け付ける IP アドレスです。/BINDTO=address は、接続で使用されるネットワーク・インタフェースを制御するために使用します。/BINDTO を指定した場合、または /BINDTO=”“ を指定した場合、以前に指定したアドレスは削除されます。指定された address が存在しない場合、OPEN コマンドはタイムアウトします。 |
/CLOSELISTEN |
|
(サーバのみ) 待ち受けポートへの複数のリモート接続を防止します。指定すると、最初の接続が受け入れられた後、待ち受けソケットが閉じられます。接続を試みる追加クライアントは、OPEN コマンドでタイムアウトします。 |
/CONNECTIONS=n
または
/CON=n |
5 |
queuesize 位置パラメータに相当します。サーバへの接続のために待機できるクライアント数を決定します。 |
/HOSTNAME=str
または
/HOS=str |
既定なし |
hostname 位置パラメータに相当します。IP ホスト名か、IPv4 または IPv6 アドレス形式の IP アドレスを指定します。/USEIPV6 キーワードを使用して、使用するプロトコルを指定できます。IPv4 および IPv6 の形式に関する詳細は、"サーバ側プログラミングの入門ガイド" の “サーバ構成オプション” の章にある “IPv6 アドレスの使用” のセクションを参照してください。 |
/IBUFSIZE=n
または
/IBU[=n] |
1024 |
ibufsiz 位置パラメータに相当します。ネットワークからデータを読み取り、アプリケーションに送信するまで保持する TCP 入力バッファのサイズを指定します。 |
/OBUFSIZE=n
または
/OBU[=n] |
1024 |
obufsiz 位置パラメータに相当します。連続する "SEND" 処理間でデータを保持する TCP 出力バッファのサイズを指定します。 |
/PORT=n |
既定なし |
port 位置パラメータに相当します。接続に使用する TCP ポート番号あるいはサービス名です。 |
/SOCKET=n
または
/SOC=n |
既定なし |
“G” モード・パラメータ文字に相当します。port 位置パラメータが、既に開いているデータ・ソケットのソケット記述子として解釈されます。このキーワードはソケット記述子の値を取得し、/PORT=n キーワードの代わりに使用されます (ソケット記述子は、InterSystems IRIS のコールインまたはコールアウト・メカニズムを使用して、C など他のプログラミング環境から ObjectScript に渡されます)。 |
/USEIPV6 |
既定なし |
/USEIPV6 または /USEIPV6=1 が指定されている場合、インバウンド接続とアウトバウンド接続の両方に IPv6 アドレスを使用して、IPv6 システム・スイッチをオーバーライドします。/USEIPV6=0 が指定されている場合、インバウンド接続とアウトバウンド接続の両方に IPv4 アドレスを使用して、IPv6 システム・スイッチをオーバーライドします。
/USEIPV6 が指定されていない場合、IPv6 システム・スイッチが動作を制御します。IPv6 システム・スイッチが設定されている場合、アウトバウンド接続はまず IPv4 アドレスで接続を試みます。失敗した場合、IPv6 アドレスで接続を試みます。インバウンド接続では、TCP デバイスは IPv4 接続と IPv6 接続の両方をリッスンします。IPv6 が設定されていない場合、インバウンド接続とアウトバウンド接続の両方に IPv4 アドレスのみが使用されます。 |
次は、キーワード構文を使用して TCP/IP デバイスを開く例です。
SET dev="|TCP|"_123
SET portnum=57345
OPEN dev:(/PSTE:/HOSTNAME="128.41.0.73":/PORT=portnum)
現在の TCP デバイス
%SYSTEM.TCPDeviceOpens in a new tab クラスのメソッドを使用して、現在の TCP デバイスの IP アドレスおよびポート番号を返すことができます。以下のように Help() メソッドを使用してこれらのメソッドをリスト表示できます。
DO $SYSTEM.TCPDevice.Help()
以下の例に示すように、Help() でメソッド名を指定して、特定のメソッドの情報を表示できます。
DO $SYSTEM.TCPDevice.Help("LocalAddr")
TCP デバイスの USE コマンド
クライアント、サーバのいずれかから発行された USE コマンドにより、事前に開いている TCP 接続を使用して、データの送受信の準備をします。このコマンドの構文は次のとおりです。
USE devicename:(::mode:terminators)
各項目の内容は次のとおりです。
パラメータ |
説明 |
devicename |
フォーム |TCP| の後ろにいくつかの数字を持つ文字列です。デバイス名の数字部分は、デバイス識別子といいます。OPEN のパラメータでポート番号を指定していない場合、このデバイス識別子には一意な 5 桁の TCP ポート番号を指定する必要があります。OPEN のパラメータでポート番号を指定している場合は (指定することをお勧めします)、1 つのジョブで使用するすべての TCP デバイス名が識別できる限り、このデバイス識別子には任意の一意の番号を指定できます。 |
mode |
オプション — USE コマンドは、OPEN と同じパラメータをサポートします。詳細は、“TCP デバイスの OPEN コマンド・キーワードと USE コマンド・キーワード” を参照してください。 |
terminators |
オプション — TCP バインディング・デバイスで読み取りを終了するユーザ・ターミネータ文字を 8 つまでリストできます。T モードとユーザ・ターミネータの両方を同時に指定する必要はなく、両方を指定すると、T モードが無視されます。 |
USE コマンドの最も簡素な形は、次の例に示すように、モード・パラメータとターミネータ・パラメータを OPEN コマンドから受け取るものです。
USE "|TCP|4"
デバイスを開いた後で、モード・パラメータとユーザ・ターミネータを置き換え、追加、または削除できます。
OPEN コマンドで指定したパラメータを置き換えるには、置き換える値を USE コマンドで指定します。以下の例にある USE コマンドは、OPEN モードを PSTE モードに置き換え、すべてのユーザ・ターミネータをオフにします。
USE "|TCP|4":(::"PSTE")
OPEN で指定したモード・パラメータを追加または削除するには、“+” 記号を使用して、オンにするモード・パラメータを導き、“-” 記号を使用して、オフにするモード・パラメータを導きます。“+” も “-” も指定しない場合、既存のすべてのモード・パラメータは新規のモード・パラメータ一式に置き換えられます。次の例にある USE コマンドでは、Q モード (直ちに送信) をオンにし、W モード (待機) をオフにします。モード文字列の残り部分は、変更されないままとなります。
USE "|TCP|4":(::"-Q+W")
以下の例では、USE コマンドはモード文字列を変更せずに、新規のユーザ・ターミネータ一式を指定します。
USE "|TCP|4":(::"+":$CHAR(3,4))
TCP デバイスの READ コマンド
サーバ、クライアントのいずれかから発行した READ コマンドは、クライアント、サーバのいずれかで設定されたあらゆる文字を読み取ります。
構文は、以下のとおりです。
READ var:timeout
READ *var:timeout
READ var#length:timeout
timeout 引数は、オプションですが、強くお勧めします。これは、timeout が指定されている場合、READ の成功または失敗が、$TEST 特殊変数の値によって示されるためです。$TEST は、時間内に読み取りが成功すると 1 に設定されます。時間が切れると、$TEST は 0 に設定されます。
timeout 引数は、秒および 1/100 秒までの小数部をサポートします。例えば、10、10.5、.5、.05 です。
SSL 接続では、接続の確立後に他方が読み取りコマンドまたは書き込みコマンドを発行したことがない場合、最初の読み取りコマンドまたは最初の書き込みコマンドでジョブは待機できます。この状況で InterSystems IRIS は、READ コマンドの読み取りタイムアウトおよび WRITE コマンドの書き込みタイムアウト (/WRITETIMEOUT=n オプション) をサポートします。読み取りまたは書き込みのタイムアウトが指定されていない場合、ジョブは他方が読み取りコマンドまたは書き込みコマンドを発行するまで待機します。
%SYSTEM.INetInfoOpens in a new tab クラスの TCPStats()Opens in a new tab メソッドを使用すると、現在の TCP 接続で実行する読み取りの回数を指定できます。
READ による $ZA および $ZB の変更
アプリケーションは、$ZA と $ZB の値を検証し、接続と読み取りがどのように成功したかを認識できます。
$ZA と READ コマンド
$ZA は、接続の状態を通知します。設定が 0x1000 ビット (4096) の場合、TCP デバイスはサーバ・モードで機能しています。0x2000 ビット (8192) の場合、リモート・ホストと対話している接続状態です。
例えば、サーバ側の TCP デバイスが、新規 TCP 接続を受け取ると仮定します。InterSystems IRIS プログラムでは、初期のタイムアウト付き読み取り後の $ZA と $TEST は、以下の 3 つに区分できます。
$ZA 値 |
$TEST 値 |
意味 |
4096 |
0 |
接続は構築されませんでした |
12288 |
0 |
接続されましたが、データは受信しませんでした |
12288 |
1 |
接続され、データを受信しました |
以下のテーブルは、$ZA の各ビットの意味を示しています。
$ZA の 10 進数値 |
$ZA の 16 進数値 |
意味 |
2 |
0x2 |
読み取りがタイムアウトになりました |
4 |
0x4 |
入出力エラーです |
256 |
0x80 |
不正なエスケープ・シーケンスを受信しました |
4096 |
0x1000 |
サーバ・モードです |
8192 |
0x2000 |
接続されました |
$ZB と READ コマンド
$ZB は、読み取りを終了した文字を保持します。文字は以下のうちの 1 つです。
-
キャリッジ・リターンなどの終端文字
-
固定長 READ x#y の y 番目の文字
-
READ *X の単一文字
-
読み取りがタイムアウトになったときの空文字列
-
エスケープ・シーケンス
文字列が CR LF で終了した場合、CR のみが $ZB に配置されます。
TCP デバイスの WRITE コマンド
OPEN と USE で接続を構築後、WRITE コマンドは、クライアントあるいはサーバから TCP デバイスにデータを送信します。
構文は、以下のとおりです。
WRITE による $X および $Y の変更
InterSystems IRIS は、$X 特殊変数に、バッファ内の文字数を格納します。
ASCII 文字 <return> と <line feed> はレコードの一部と見なされないため、文字数にカウントされません。WRITE ! でバッファをフラッシュすると、$X を 0 にリセットし、$Y の値を 1 増加します。WRITE # でバッファをフラッシュすると、別のレコードとして ASCII 文字 <form feed> を書き込み、$Y を 0 にリセットします。
WRITE コマンド・エラー
以下のような場合、<WRITE> エラーを受け取ります。
-
バッファをフラッシュせず、最大文字列サイズ (1,024 文字) を超えた場合
-
文字が存在しない書き込みバッファ (TCP/IP は長さ 0 のレコードを無視します) をフラッシュした場合
-
サーバがクライアントから接続要求を受け取る前に、サーバからクライアントに WRITE コマンドを送信した場合 (InterSystems IRIS は、サーバに <WRITE> エラーを生成します)
WRITE コントロール・コマンド
InterSystems IRIS TCP バインディング・デバイスは、WRITE *-n 構文の一連のコントロール・コマンドをサポートします。
構文 |
説明 |
WRITE *-2 |
現在、クライアントに接続されているサーバ・モード・セッションで、このコマンドはセッションから切断します。新規セッションを受け入れるには、デバイスで新規に READ コマンドを実行します。 |
WRITE *-3 |
TCP 接続にバッファされた出力を送信します。つまり、出力バッファのデータに TCP SEND 操作を実行します。/GZIP を指定して圧縮したストリーム・データでは、*-3 を指定すると、圧縮エンドポイントのマークなしでデータが送信されます。$X を 0 にリセットし、$Y を 1 ずつインクリメントします。バッファする出力が存在しない場合、このコマンドは何も実行しません。 |
WRITE *-99 |
/GZIP を指定して圧縮されたストリーム・データを送信します。出力バッファにあるデータに圧縮エンドポイントのマークを付けた後、その出力バッファのデータに対して TCP SEND 操作を実行することで圧縮ストリーム・データを送信します。 |
接続管理
サーバは、一度に 1 つの接続のみ維持できます。したがって、あるクライアントがサーバに接続しているときに 2 番目のクライアントが接続しようとすると、TCP/IP はそのクライアントをキューに格納します。2 番目のクライアントはキューの間、あたかも接続されているかのように、ポートに書き込むことができます。2 番目のクライアントが書き込むデータは、最初の接続が閉じ、2 番目のクライアントに接続するまでバッファに維持されます。
接続が構築される前に READ を発行すると、2 番目のクライアントは停止します。2 番目の接続がキューに入っている間に、3 番目のクライアントが接続を試行しても、その接続は失敗します。
最初の接続がまだ存在しているときに、TCP デバイスを既に開いているクライアントが、2 回目の接続を試行した場合、2 回目の OPEN コマンドでは <COMMAND> エラーが発生します。この状況を USE コマンドではなくエラーとして処理することで、予想できない結果を予防します。例えば、誤ったプログラムが新規に接続を開いたと判断した場合でも、実際には異なる宛先あるいは異なるパラメータを持つ既存の接続を再利用しているたけであると、予測不可能な結果が生じる場合があります。
複数のクライアントを処理する方法は、以下を参照してください。
TCP デバイスを使用した JOB コマンド
JOB コマンドを使用して、TCP 並行サーバ を実装することができます。TCP 並行サーバを使用すると、複数のクライアントを同時に処理できます。このモードでは、クライアントは、サーバが他のクライアント処理を終了するまで待機する必要はありません。代わりに、クライアントがサーバに要求を送信するたびに、開いているクライアントに対して必要に応じて個別のサブジョブを生成します。このサブジョブが生成された直後に (JOB コマンドから制御が戻ります)、他のクライアントが処理を要求することがあります。サーバは、そのクライアントのサブジョブも同様に生成します。
非並行モードおよび並行モードのクライアント/サーバ接続
並行サーバは、switch 並行サーバ・ビット (ビット 4 またはビット 16) を設定した JOB コマンドを使用します。お勧めの設定はビット 16 です。
-
ビット 4 が設定されている場合、JOB コマンドは、生成したプロセスに、principal input および principal output のプロセス・パラメータの TCP デバイスを渡します。switch にビット 4 が含まれている場合、常に、プロセス・パラメータ principal input および principal output の両方の TCP デバイスを指定する必要があります。また、principal input および principal output の両方に同じデバイスを使用する必要があります。ビット 4 の使用はお勧めしません。詳細は、"ObjectScript リファレンス" の "JOB" コマンドを参照してください。
-
ビット 16 が設定されている場合、JOB コマンドは、生成したプロセスに、TCP デバイス、principal input プロセス・パラメータ、および principal output プロセス・パラメータの 3 つの異なるデバイスを渡します。principal input プロセス・パラメータと principal output プロセス・パラメータを使用して、JOB コマンドでこれらの TCP デバイスのうち 2 つを指定します。以下の例に示すように、これらのパラメータを既定に設定することも可能です。JOB child:(:16:input:output) または JOB child:(:16::))。
詳細は、"ObjectScript リファレンス" の "JOB" コマンドを参照してください。
JOB コマンドを実行する前に、principal input および principal output に指定するデバイスは、以下の状態になる必要があります。
-
接続されている
-
TCP ポートで待ち受け状態にある
-
接続を受け入れ済みである
JOB コマンドの後、生成されているプロセスのデバイスは継続して TCP ポートで待ち受け状態にありますが、アクティブな接続は既に存在していません。アプリケーションは、JOB コマンドの実行後に $ZA を確認し、TCP デバイスの状態で CONNECTED ビットがリセットされていることを確認する必要があります。
生成されたプロセスは、指定の TCP デバイスを使用して指定のエントリ・ポイントで開始します。子プロセスの TCP デバイス名は、親プロセスの名前と同じです。TCP デバイスには、付属のソケットが 1 つあります。継承された TCP デバイスは、S (ストリーム) モードです。しかし、子プロセスは、USE コマンドでモードを変更できます。サーバは、TCP デバイスを A (受信) モードで開くことをお勧めします。
生成したプロセスにある TCP デバイスは、接続状態です。これは、デバイスをクライアントから開いた後に受け取る状態と同じです。生成されたプロセスは、TCP デバイスを USE 0 あるいは USE $P で使用します。TCP デバイスを暗黙的に使用することもできます (switch=4 の場合)。ただし、以下の理由により switch=16 が switch=4 よりも優先されます。
-
switch=4 の場合、<READ> エラーが主デバイス上で発生すると、エラー・トラップをせず、ジョブは単に停止します。これは、switch=4 の場合、TCP デバイスが主デバイスであるためです。エラー・トラップをサポートするには、switch=16 を使用し、TCP デバイスに別のデバイスを指定します。
-
switch=4 の場合、リモート TCP デバイスが接続を終了すると、エラー・トラップをせず、ジョブは単に停止します。この既定の動作をオーバーライドし、<DSCON> エラーを生成するには、%SYSTEM.ProcessOpens in a new tab クラスの DisconnectErr()Opens in a new tab メソッドを設定する必要があります。
JOB コマンドではなく %SYSTEM.SocketOpens in a new tab クラス・メソッドを使用して並行 TCP サーバ接続を作成できます。ただし、%SYSTEM.SocketOpens in a new tab メソッドはワーカ・ジョブが既に開始されていることを想定していることに注意してください。ワーカ・ジョブを開始するためにリスナ・ジョブが不要な場合、並行 TCP サーバ接続にこれらのメソッドを使用できます。リスナ・ジョブはワーカ・ジョブのプロセス ID (PID) を認識しています。
Job コマンドの例
以下の例は、非常に単純な並行サーバです。このサーバは、クライアントからの接続を検出するたびに子ジョブを生成します。JOB により並行サーバ・ビットの switch の値 (値 16) を指定して、シンボル・テーブル (値 1) を渡します :16+1=17。
server
SET io="|TCP|1"
SET ^serverport=7001
OPEN io:(:^serverport:"MA"):200
IF ('$TEST) {
WRITE !,"Cannot open server port"
QUIT }
ELSE { WRITE !,"Server port opened" }
loop
USE io READ x ; Read for accept
USE 0 WRITE !,"Accepted connection"
JOB child:(:17:io:io) ;Concurrent server bit is on
GOTO loop
child
WRITE $JOB,! ; Send job id on TCP device to be read by client
QUIT
client
SET io="|TCP|2"
SET host="127.0.0.1"
OPEN io:(host:^serverport:"M"):200 ;Connect to server
IF ('$TEST) {
WRITE !,"cannot open connection" Quit }
ELSE {
WRITE !,"Client connection opened"
USE io READ x#3:200 ;Reads from subjob
}
IF ('$TEST) {
WRITE !,"No message from child"
CLOSE io
QUIT }
ELSE {
USE 0 WRITE !,"Child is on job ",x
CLOSE io
QUIT }
子ジョブは、継承した TCP 接続を使用して、ジョブ ID (この場合は 3 文字とします) をクライアントに渡します。その後、子プロセスは終了します。クライアントは、サーバとの接続を開き、その状態で子のジョブ ID を読み取ります。この例では、変数 host に IPv4 形式で指定した値 “127.0.0.1” により、ローカル・ホスト・マシンへのループバック接続であることを示しています。host にサーバの IP アドレスまたは名前を設定すれば、そのサーバとは別のマシンにクライアントをセットアップすることもできます。IPv4 および IPv6 の形式に関する詳細は、"サーバ側プログラミングの入門ガイド" の “サーバ構成オプション” の章にある “IPv6 アドレスの使用” のセクションを参照してください。
原則では、子プロセスとクライアントは広範囲の通信を実行できます。複数のクライアントが同時に対応するサーバの子と通信できます。
この単純な例には、切断または失敗した読み取り処理を検出し、処理するロジックは含まれていません。
レコードの連結
特定の環境で、TCP は、別々のレコードを 1 つのレコードに連結します。クライアントあるいはサーバ・プロセスが、バッファをフラッシュするために WRITE ! あるいは WRITE # コマンドで区切られた一連の WRITE コマンドを TCP ポートに発行した場合、READ コマンドが他の接続の切断を待機しているかどうかにかかわらず、レコードの連結が可能です。
最初の例は、Process B が TCP ポートに 2 つのレコードを書き込む間、READ コマンドを持つ Process A がどのように 2 つのレコードを受信するのかを説明しています。
Process A Process B
%SYS> USE "|TCP|41880" R A U 0 W A %SYS> USE "|TCP|41880" WRITE "ONE",!,"TWO"
<RETURN> <RETURN>
ONE
%SYS> USE 41880 R A U 0 W A
<RETURN>
TWO
2 番目の例は、Process B が TCP ポートに 2 つのレコードを記述し、その後、READ コマンドを発行した Process A がどのように 1 つの連結レコードを受信するのかを説明しています。
Process A Process B
. %SYS> USE "|TCP|41880" WRITE "ONE",!,"TWO"
. <RETURN>
ONE
%SYS> USE "/TCP/41880" R A U 0 W A
<RETURN>
ONETWO
接続の切断
クライアントあるいはサーバのいずれでも、TCP バインディング接続を切断できます。接続を閉じるには、クライアントが TCP デバイスに対して CLOSE コマンドを発行することをお勧めします(または、クライアントが HALT コマンドを発行します)。サーバは、その後、そのデバイスに別の READ コマンドを発行して <READ> エラーを受け取り、さらに TCP デバイスに対して CLOSE コマンドを発行する必要があります。
この順序にするのは、TCP/IP 標準に従って、CLOSE の後 2 分間、“アクティブなクローザ“ (CLOSE を最初に実行するプロセス) に対してのみ、接続リソースを維持するためです。したがって、サーバのリソースは通常クライアントのリソースよりも制約が多いため、クライアントを最初に閉じることをお勧めします。
CLOSE コマンドによる切断
以下の形式で、クライアントあるいはサーバから CLOSE コマンドを発行します。
上述のように、クライアントが最初に CLOSE コマンドを発行することをお勧めします。サーバが CLOSE コマンドを発行する場合、クライアントは <WRITE> エラーを取得するので、CLOSE コマンドを発行する必要があります。
JOBSERVER リソース
管理下にないクライアントにアクセスするよう InterSystems IRIS サーバを記述している場合、サーバ・プロセスは、CLOSE を発行して TCP 接続を閉じる必要があります。CLOSE コマンドは、InterSystems IRIS に関しては接続を閉じますが、内部的に TCP/IP は、最大 2 分間サーバ上でこの接続のためのリソースを保持します。
これによって、TCP/IP ジョブへのサービスの提供のために JOBSERVER が使用される場合、予期しない結果が生じる可能性があります。JOBSERVER プロセスが停止を実行すると、プロセスは、直ちに使用可能な JOBSERVER プロセスのプールに戻りますが、そのリソースは、最大 2 分間内部的に保持されます。JOBSERVER プロセスは、最初に使用可能なものから割り当てられるので、比較的少数のクライアントからの重い負荷が JOBSERVER プロセスのリソースを使い果たす可能性があります。
この問題を回避するために、JOBSERVER の下で実行されている JOB によって開かれた TCP/IP サーバは、明示的に CLOSE を発行し、その後、最後の QUIT (または HALT) コマンドの前に短い HANG コマンドを発行する必要があります。TCP/IP の仕様に従って、JOBSERVER における各状態の間でリソースが使用中のままにならないことを保証するには HANG 120 が必要です。実際には、通常、JOBSERVER プロセス間でリソースの負荷を均等に分散するには、1 秒の HANG で十分です。
自動切断
以下の条件の場合、TCP バインディング接続は自動的に切断します。
切断の影響
出力バッファに残っているデータへの切断の影響は、OPEN または USE 中に確立される /CLOSEFLUSH 設定によって決まります。既定では、データをフラッシュします。
片方で接続を切断し、もう一方で新規に WRITE コマンドを発行すると、最初の WRITE コマンドは成功する場合があります。続けて WRITE コマンドを発行すると、<WRITE> エラーを受け取ります。
クライアント側から、接続を切断した側へ READ コマンドを発行すると、<READ> エラーを受け取ります。サーバで通信を再構築するため、デバイスを一度閉じてから再度開く必要があります。
<READ> エラーまたは <WRITE> エラーの後で、サーバ側から発行した最初の READ コマンドは、新規接続を待機して受け入れます。
%SYSTEM.TCPDevice.GetDisconnectCode()Opens in a new tab を使用すれば、現在の TCP デバイスで <READ> または <WRITE> エラーとなった内部エラーを返すことができます。$IO は TCP デバイスとする必要があります。
FeedbackOpens in a new tab