表17-3は、この項で説明しているStreamsアドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
表17-3 アドバンスト・キューイング関数およびパブリッシュ・サブスクライブ関数
関数 | 用途 |
---|---|
|
アドバンスト・キューイングのデキュー操作を実行します。 |
|
メッセージ配列をデキューします。 |
|
アドバンスト・キューイングのエンキュー操作を実行します。 |
|
メッセージ配列をエンキューします。 |
|
リストのエージェントの代理として1つ以上のキューをリスニングします。バッファ・メッセージおよび永続キューをサポートします。 |
|
サブスクリプションの登録を使用禁止にして、通知をオフにします。 |
|
サブスクリプションについての通知を使用可能にします。 |
|
通知を受信するようにサブスクリプションに転記します。 |
|
サブスクリプションを登録します。 |
|
サブスクリプションの登録を解除します。 |
構文
sword OCIAQDeq ( OCISvcCtx *svch, OCIError *errh, OraText *queue_name, OCIAQDeqOptions *dequeue_options, OCIAQMsgProperties *message_properties, OCIType *payload_tdo, void **payload, void **payload_ind, OCIRaw **msgid, ub4 flags );
パラメータ
OCIサービス・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
デキュー操作のためのターゲット・キューです。
デキュー操作のオプションです。OCI型定数OCI_DTYPE_AQDEQ_OPTIONS
を使用してOCIAQDeqOptions
記述子に格納されます。
OCI_DTYPE_AQDEQ_OPTIONS
には、次の値を持つ追加属性OCI_ATTR_MSG_DELIVERY_MODE
があります(Oracle Database 10gリリース2から導入されました)。
OCI_MSG_PERSISTENT
(デフォルト)
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
メッセージ用のメッセージ・プロパティです。プロパティは、OCI型定数OCI_DTYPE_AQMSG_PROPERTIES
を使用してOCIAQMsgProperties
記述子に格納されます。この定数には、次の値があります。
OCI_AQ_PERSISTENT
(デフォルト)
OCI_AQ_BUFFERED
オブジェクト型のTDO (型記述子オブジェクト)です。RAWキューでは、このパラメータがSYS.RAW
のTDOを指し示す必要があります。
オブジェクト型のインスタンスであるプログラム変数バッファのポインタへのポインタです。RAWキューでは、このパラメータがOCIRaw
のインスタンスを指し示す必要があります。
payload用のメモリーは、オブジェクト・キャッシュに動的に割り当てられます。payloadインスタンスが不要になったときは、アプリケーションからOCIObjectFree()をコールし、割当て解除もできます。プログラム変数バッファへのポインタ(*payload
)がNULL
で渡された場合、そのバッファは暗黙的にキャッシュに割り当てられます。
アプリケーションでは、OCIAQDeq()
が最初にコールされたときにpayload
にNULL
を渡し、そのpayloadに、OCIでメモリーを割り当てるようにできます。後続のOCIAQDeq()
コールでは、前に割り当てられたメモリーへのポインタが使用されます。
payload用にTDOを取得するには、OCITypeByName()またはOCITypeByRef()を使用します。
OCIによって、ユーザーがpayloadの属性(テキストなど)を設定できる関数が提供されます。これらの属性の設定については、「オブジェクト属性の操作」を参照してください。
オブジェクト型のパラレル・インジケータ情報構造を含むプログラム変数バッファ・ポインタへのポインタです。
payload_ind
へのメモリー割当てルールは、payload
に対するルールと同じです。
メッセージIDです。
現行では使用されていません。OCI_DEFAULT
として渡されます。
コメント
このコールを使用するには、ユーザーがAQ_USER_ROLE
またはDBMS_AQ
パッケージを実行する権限を所有している必要があります。このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。
構文
sword OCIAQDeqArray ( OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name, OCIAQDeqOptions *deqopt, ub4 *iters, OCIAQMsgProperties **msgprop, OCIType *payload_tdo, void **payload, void **payload_ind, OCIRaw **msgid, void *ctxp, OCICallbackAQDeq (cbfp) ( void *ctxp, void **payload, void **payload_ind ), ub4 flags );
パラメータ
OCIサービス・コンテキストです(OCIAQDeq()から変更なし)。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです(OCIAQDeq()から変更なし)。
メッセージのデキュー元となるキューの名前です(OCIAQDeq()から変更なし)。
OCIAQDeqOptions
記述子へのポインタです(OCIAQDeq()から変更なし)。
OCI_DTYPE_AQDEQ_OPTIONS
OCI型定数には、次の値を持つ追加属性OCI_ATTR_MSG_DELIVERY_MODE
があります(Oracle Database 10gリリース2から導入されました)。
OCI_MSG_PERSISTENT
(デフォルト)
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
入力では、デキューするメッセージ数です。出力では、正常にデキューされたメッセージ数です。
OCI型定数OCI_DTYPE_AQMSG_PROPERTIES
のOCIAQMsgProperties
記述子へのポインタの配列です。この定数には、次の値があります。
OCI_AQ_PERSISTENT
(デフォルト)
OCI_AQ_BUFFERED
キュー・テーブルのペイロード列のTDOへのポインタです。
デキューされたメッセージへのポインタの配列です。
インジケータへのポインタの配列です。
デキューされたメッセージのメッセージIDへのポインタの配列です。
コールバック関数に渡されるコンテキストです。
デキューされたメッセージが格納されるバッファ・ポインタを指定するために登録できるコールバックです。NULL
の場合、メッセージはpayload
が指し示すバッファにデキューされます。
現行では使用されていません。OCI_DEFAULT
として渡されます。
コメント
このコールを使用するには、ユーザーがAQ_USER_ROLE
またはDBMS_AQ
パッケージを実行する権限を所有している必要があります。このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。
OCIAQDeqOptions
で指定した0 (ゼロ)以外の待機時間は、キューにメッセージがない場合のみ認識されます。キューに、デキューの対象であるメッセージが含まれる場合、OCIAQDeqArray()
関数はiters
メッセージまでをデキューし、ただちに戻します。
この関数は、非ブロック化モードではサポートされません。
構文
sword OCIAQEnq ( OCISvcCtx *svch, OCIError *errh, OraText *queue_name, OCIAQEnqOptions *enqueue_options, OCIAQMsgProperties *message_properties, OCIType *payload_tdo, void **payload, void **payload_ind, OCIRaw **msgid, ub4 flags );
パラメータ
OCIサービス・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
エンキュー操作のためのターゲット・キューです。
エンキュー操作のオプション。OCIAQEnqOptions
記述子に格納されています。
メッセージ用のメッセージ・プロパティです。プロパティは、Oracle Database 10gリリース2で導入されたOCI型定数OCI_DTYPE_AQMSG_PROPERTIES
のOCIAQMsgProperties
記述子に格納されます。
OCI_DTYPE_AQMSG_PROPERTIES
記述子には、次の値を持つOCI_ATTR_MSG_DELIVERY_MODE
属性があります。
OCI_MSG_PERSISTENT
(デフォルト)
OCI_MSG_BUFFERED
オブジェクト型のTDO (型記述子オブジェクト)です。RAWキューでは、このパラメータがSYS.RAW
のTDOを指し示す必要があります。
オブジェクト型のインスタンスを指し示すポインタへのポインタです。RAWキューでは、このパラメータがOCIRaw
のインスタンスを指し示す必要があります。
OCIによって、ユーザーがpayloadの属性(テキストなど)を設定できる関数が提供されます。
オブジェクト型のパラレル・インジケータ情報構造を含むプログラム変数バッファ・ポインタへのポインタです。
メッセージIDです。
現行では使用されていません。OCI_DEFAULT
として渡されます。
コメント
このコールを使用するには、ユーザーがAQ_USER_ROLE
またはDBMS_AQ
パッケージを実行する権限を所有している必要があります。
このコールを使用するには、OCI環境をオブジェクト・モードで初期化する必要があります(OCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)を使用)。
関連項目:
|
payload用にTDOを取得するには、OCITypeByName()またはOCITypeByRef()を使用します。
構文
sword OCIAQEnqArray ( OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name, OCIAQEnqOptions *enqopt, ub4 *iters, OCIAQMsgProperties **msgprop, OCIType *payload_tdo, void **payload, void **payload_ind, OCIRaw **msgid, void *ctxp, OCICallbackAQEnq (cbfp) ( void *ctxp, void **payload, void **payload_ind ), ub4 flags );
パラメータ
サービス・コンテキストです(OCIAQEnq()から変更なし)。
エラー・ハンドルです(OCIAQEnq()から変更なし)。
メッセージがエンキューされるキューの名前です(OCIAQEnq()から変更なし)。
OCIAQEnqOptions
記述子へのポインタです(OCIAQEnq()から変更なし)。
入力では、エンキューするメッセージ数です。出力では、正常にエンキューされたメッセージ数です。
Oracle Database 10gリリース2で導入されたOCI型定数OCI_DTYPE_AQMSG_PROPERTIES
のOCIAQMsgProperties
記述子へのポインタの配列です。
OCI_DTYPE_AQMSG_PROPERTIES
には、次の値を持つOCI_ATTR_MSG_DELIVERY_MODE
属性があります。
OCI_MSG_PERSISTENT
(デフォルト)
OCI_MSG_BUFFERED
キュー・テーブルのペイロード列のTDOへのポインタです。
エンキューされるメッセージへのポインタの配列です。
インジケータへのポインタの配列、またはNULL
ポインタの配列です(標識変数が使用されていない場合)。
エンキューされたメッセージのメッセージIDへのポインタの配列、またはNULL
ポインタの配列です(メッセージIDが戻されない場合)。
登録されたコールバック関数に渡されるコンテキストです。
メッセージを動的に提供するために登録できるコールバックです。NULL
の場合、OCIAQEnqArray()
をコールする前に、すべてのメッセージを具体化する必要があります。
現行では使用されていません。OCI_DEFAULT
として渡されます。
構文
sword OCIAQListen2 (OCISvcCtx *svchp, OCIError *errhp, OCIAQAgent **agent_list, ub4 num_agents, OCIAQListenOpts *lopts, OCIAQAgent **agent, OCIAQLisMsgProps *lmops, ub4 flags);
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
メッセージを監視するエージェントのリストです。
エージェント・リスト内のエージェント数です。
型定数OCI_DTYPE_AQLIS_OPTIONS
には、次の属性があります。
OCI_ATTR_WAIT
- リスニング・コールの最大待機時間(秒単位)
OCI_ATTR_MSG_DELIVERY_MODE
- 次のいずれかの値です。
OCI_MSG_PERSISTENT
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
メッセージの出力先のエージェントです。OCIAgent
はOCI記述子です。
OCI_DTYPE_AQLIS_MSG_PROPERTIES
(リスニング・メッセージ・プロパティ)には、1つの属性、OCI_ATTR_MSG_DELIVERY_MODE
があります。この属性は、次の値を持ちます。
OCI_MSG_PERSISTENT
OCI_MSG_BUFFERED
現行では使用されていません。OCI_DEFAULT
として渡されます。
パラメータ
OCI_ATTR_SUBSCR_NAME
およびOCI_ATTR_SUBSCR_NAMESPACE
属性が設定されたサブスクリプション・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コール固有モードです。有効な値はOCI_DEFAULTのみです。OCI_DEFAULT
は、デフォルトのコールを実行します。サブスクリプションが使用可能になるまで、このサブスクリプションの通知をすべて破棄します。
コメント
このコールは、一時的に通知をオフにするときに使用します。コードの重要なセクションを実行しているときに使用して、アプリケーションが中断されないようにします。
この操作をするときは、接続または認証は必要ありません。このコールの前に、サブスクリプション・ハンドルによって指定されたサブスクリプションの登録を行ってください。
OCISubscriptionDisable()
を実行した後は、OCISubscriptionEnable()を実行するまですべての通知が破棄されます。
パラメータ
OCI_ATTR_SUBSCR_NAME
およびOCI_ATTR_SUBSCR_NAMESPACE
属性が設定されたサブスクリプション・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コール固有モードです。有効な値はOCI_DEFAULTのみです。この値は、デフォルトのコールを実行します。次の使用可能化が実行されるまで、このサブスクリプションの通知はすべてバッファリングされます。
構文
ub4 OCISubscriptionPost ( OCISvcCtx *svchp, OCISubscription **subscrhpp, ub2 count, OCIError *errhp ub4 mode );
パラメータ
OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。
サブスクリプション・ハンドルの配列です。この配列の各要素は、OCI_ATTR_SUBSCR_NAME
およびOCI_ATTR_SUBSCR_NAMESPACE
属性が設定されたサブスクリプション・ハンドルにしてください。
このコールの前に、各サブスクリプション・ハンドルに対してOCI_ATTR_SUBSCR_PAYLOAD
属性を設定する必要があります。設定されていない場合、ペイロードはNULL
であるとみなされ、重要な登録を行ったクライアントが通知を受信したときに、ペイロードが配布されません。OCIAttrSet()
コールでは、ペイロードへの参照は記録されますが、内容はコピーされないため、コール元は転送が行われるまでペイロードを保存する必要があります。
サブスクリプション・ハンドル配列の要素数です。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コール固有モードです。有効な値はOCI_DEFAULTのみです。この値は、デフォルトのコールを実行します。
構文
ub4 OCISubscriptionRegister ( OCISvcCtx *svchp, OCISubscription **subscrhpp, ub2 count, OCIError *errhp ub4 mode );
パラメータ
OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。
サブスクリプション・ハンドルの配列です。この配列の各要素は、次のすべての属性が設定されたサブスクリプション・ハンドルである必要があります。
OCI_ATTR_SUBSCR_NAME
OCI_ATTR_SUBSCR_NAMESPACE
OCI_ATTR_SUBSCR_RECPTPROTO
それ以外の場合はエラーが戻されます。
次のいずれかの属性も設定する必要があります。
OCI_ATTR_SUBSCR_CALLBACK
OCI_ATTR_SUBSCR_CTX
OCI_ATTR_SUBSCR_RECPT
subscrhpp[i]
によって示された登録に対して通知を受信すると、subscrhpp[i]
に対してコンテキスト(OCI_ATTR_SUBSCR_CTX
)が設定された状態で、subscrhpp[i]
に対して設定されたユーザー定義コールバック関数(OCI_ATTR_SUBSCR_CALLBACK
)が呼び出されるか、subscrhpp[i]
に対して設定された(OCI_ATTR_SUBSCR_RECPT
)に電子メールが送信されます。あるいは、subscrhpp[i]
のサブスクライバにプロシージャに対する適切な権限がある場合は、subscrhpp[i]
に対して設定されたPL/SQLプロシージャ(OCI_ATTR_SUBSCR_RECPT
)がデータベースで呼び出されます。
サブスクリプション・ハンドル配列の要素数です。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コール固有モードです。次の値が有効です。
OCI_DEFAULT
: サーバーのDN記述子にサーバーのDNが1つのみ存在する場合に使用します。登録要求がデータベースに送信されます。データベース接続を使用できない場合、登録要求は迂回してLDAPサーバーに送信されます。
OCI_REG_LDAPONLY
- 登録要求は直接LDAPサーバーに送信されます。サーバーのDN記述子にサーバーのDNが複数存在する場合、またはデータベース接続を使用できないことが確かである場合に、このモードを使用します。
新しいクライアント・プロセスが起動するか、または以前のクライアント・プロセスが停止して再度起動するときは常に、重要なすべてのサブスクリプションに対して登録する必要があります。クライアントが起動したまま、サーバーが最初に停止してから再度起動した場合、クライアントはDISCONNECTEDである登録に対して引き続き通知を受信します。ただし、CONNECTED登録に対する通知は、サーバーが停止して再度起動した後は欠落するため、クライアントが受信することはありません。
コメント
このコールは、サブスクリプションの登録に対して呼び出します。重要なサブスクリプション名および呼び出される関連コールバックを識別します。重要な複数のサブスクリプションを同時に登録できます。
このインタフェースは、非同期モードのメッセージ配信の場合にのみ有効です。非同期モードでは、サブスクライバが登録コールの発行およびコールバックの指定を行います。サブスクリプション条件と一致するメッセージを受信すると、コールバックが呼び出されます。次に、コールバックから明示的なmessage_receive
(デキュー)が発行され、メッセージが取り出されます。
ユーザーは、登録時にネームスペース属性をOCI_SUBSCR_NAMESPACE_AQ
に設定して、サブスクリプション・ハンドルを指定する必要があります。
サブスクリプション名は、シングル・コンシューマ・キューの登録の場合は文字列SCHEMA.QUEUE
で、マルチ・コンシューマ・キューの登録の場合は文字列SCHEMA.QUEUE:CONSUMER_NAME
です。この文字列は大文字にします。
各ネームスペースには、独自の権限モデルがあります。登録を行っているユーザーに、指定されたサブスクリプションのネームスペースで登録する権限がない場合は、エラーが戻されます。
構文
ub4 OCISubscriptionUnRegister ( OCISvcCtx *svchp, OCISubscription *subscrhp, OCIError *errhp ub4 mode );
パラメータ
OCIサービス・コンテキストです(バージョン7より後)。このサービス・コンテキストには、有効な認証されたユーザー・ハンドルが必要です。
OCI_ATTR_SUBSCR_NAME
およびOCI_ATTR_SUBSCR_NAMESPACE
属性が設定されたサブスクリプション・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コール固有モードです。次の値が有効です。
OCI_DEFAULT
: サーバーのDN記述子にサーバーのDNが1つのみ存在する場合に使用します。登録要求がデータベースに送信されます。データベース接続を使用できない場合、登録要求は迂回してLDAPサーバーに送信されます。
OCI_REG_LDAPONLY
- 登録要求は直接LDAPサーバーに送信されます。サーバーのDN記述子にサーバーのDNが複数存在する場合、またはデータベース接続を使用できないことが確かである場合に、このモードを使用します。