WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 作業系統: Linux, Windows

Session

階段作業為傳送和接收訊息時所用的一種單一執行緒環境定義。

有關 XMS 所定義的 Session 內容清單, 請參閱Session 內容

函數

函數摘要:
函數 說明
xmsSessClose 關閉階段作業。
xmsSessCommit 確定現行交易中所有已處理的訊息。
xmsSessCreateBrowser 為指定的佇列建立佇列瀏覽器。
xmsSessCreateBrowserSelector 使用訊息選取器為指定的佇列建立佇列瀏覽器。
xmsSessCreateBytesMessage 建立位元組訊息。
xmsSessCreateConsumer 為指定的目的地建立訊息使用端。
xmsSessCreateConsumerSelector 使用訊息選取器為指定的目的地建立訊息使用端。
xmsSessCreateConsumerSelectorLocal 使用訊息選取器為指定的目的地建立訊息使用端,如果目的地為一個主題, 並指定訊息使用端是否接收其本身連線所發佈的訊息。
xmsSessCreateDurableSubscriber 為指定的主題建立延續訂閱者。
xmsSessCreateDurableSubscriberSelector 使用訊息選取器為指定的主題建立延續訂閱者, 並指定延續訂閱者是否接收其本身連線所發佈的訊息。
xmsSessCreateMapMessage 建立對映訊息。
xmsSessCreateMessage 建立一則沒有主體的訊息。
xmsSessCreateObjectMessage 建立物件訊息。
xmsSessCreateProducer 建立訊息生產者以傳送訊息給指定的目的地。
xmsSessCreateStreamMessage 建立串流訊息。
xmsSessCreateTextMessage 建立一則空主體的文字訊息。
xmsSessCreateTextMessageInit 建立文字訊息,並使用指定文字來起始設定其主體。
xmsSessGetAcknowledgeMode 取得階段作業的確認模式。
xmsSessGetTransacted 判斷階段作業是否為交易式。
xmsSessRecover 回復 (Recover) 階段作業。
xmsSessRollback 回(Rollback)復現行交易中所有已處理的訊息。
xmsSessUnsubscribe 刪除延續訂閱。

xmsSessClose – 關閉階段作業

介面:
xmsRC xmsSessClose(xmsHSess *session,
                   xmsHErrorBlock errorBlock);

關閉階段作業。如果階段作業為交易式, 則會回復任何進行中的交易。

所有和階段作業相依的物件都會刪除。如需哪些物件會被刪除的相關資訊, 請參閱刪除物件

如果應用程式試著關閉已關閉的階段作業, 則會忽略該呼叫。

參數:
session(輸入/輸出)
在輸入方面,為階段作業的控點。在輸出方面,函數會傳回空值控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
執行緒環境定義:
任何
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCommit – 確定

介面:
xmsRC xmsSessCommit(xmsHSess session,
                    xmsHErrorBlock errorBlock);

確定現行交易中所有已處理的訊息。

參數:
session(輸入)
階段作業的控點。階段作業必須是交易式階段作業。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION
  • XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION

xmsSessCreateBrowser – 建立佇列瀏覽器

介面:
xmsRC xmsSessCreateBrowser(xmsHSess session,
                           xmsHDest queue,
                           xmsHQueueBrowser *browser
                           xmsHErrorBlock errorBlock);

為指定的佇列建立佇列瀏覽器。

參數:
session(輸入)
階段作業的控點。
queue(輸入)
代表佇列的 Destination 物件控點。
browser(輸出)
佇列瀏覽器的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateBrowserSelector – 建立佇列瀏覽器(使用訊息選取器)

介面:
xmsRC xmsSessCreateBrowserSelector(xmsHSess session,
                                   xmsHDest queue,
                                   xmsCHAR *messageSelector,
                                   xmsINT length,
                                   xmsHQueueBrowser *browser
                                   xmsHErrorBlock errorBlock);

使用訊息選取器為指定的佇列建立佇列瀏覽器。

參數:
session(輸入)
階段作業的控點。
queue(輸入)
代表佇列的 Destination 物件控點。
messageSelector(輸入)
字元陣列形式的訊息選取器表示式。只有內容符合訊息選取器表示式的訊息會遞送給佇列瀏覽器。

空值或空字串值表示佇列瀏覽器沒有訊息選取器。

length(輸入)
訊息選取器表示式的長度(以位元組計)。如果訊息選取器表示式在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
browser(輸出)
佇列瀏覽器的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateBytesMessage – 建立位元組訊息

介面:
xmsRC xmsSessCreateBytesMessage(xmsHSess session,
                                xmsHMsg *message,
                                xmsHErrorBlock errorBlock);

建立位元組訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
位元組訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateConsumer – 建立消費者

介面:
xmsRC xmsSessCreateConsumer(xmsHSess session,
                            xmsHDest destination,
                            xmsHMsgConsumer *consumer,
                            xmsHErrorBlock errorBlock);

為指定的目的地建立訊息使用端。

參數:
session(輸入)
階段作業的控點。
destination(輸入)
目的地的控點。
consumer(輸出)
訊息使用端的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateConsumerSelector – 建立消費者(使用訊息選取器)

介面:
xmsRC xmsSessCreateConsumerSelector(xmsHSess session,
                                    xmsHDest destination,
                                    xmsCHAR *messageSelector,
                                    xmsINT length,
                                    xmsHMsgConsumer *consumer,
                                    xmsHErrorBlock errorBlock);

使用訊息選取器為指定的目的地建立訊息使用端。

參數:
session(輸入)
階段作業的控點。
destination(輸入)
目的地的控點。
messageSelector(輸入)
字元陣列形式的訊息選取器表示式。只有內容符合訊息選取器表示式的訊息會遞送給訊息使用端。

空值或空字串值表示訊息使用端沒有訊息選取器。

length(輸入)
訊息選取器表示式的長度(以位元組計)。如果訊息選取器表示式在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
consumer(輸出)
訊息使用端的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateConsumerSelectorLocal – 建立消費者(使用訊息選取器和本端訊息旗標)

介面:
xmsRC xmsSessCreateConsumerSelectorLocal(xmsHSess session,
                                         xmsHDest destination,
                                         xmsCHAR *messageSelector,
                                         xmsINT length,
                                         xmsBOOL noLocal,
                                         xmsHMsgConsumer *consumer,
                                         xmsHErrorBlock errorBlock);

使用訊息選取器為指定的目的地建立訊息使用端,如果目的地為一個主題, 並指定訊息使用端是否接收其本身連線所發佈的訊息。

參數:
session(輸入)
階段作業的控點。
destination(輸入)
目的地的控點。
messageSelector(輸入)
字元陣列形式的訊息選取器表示式。只有內容符合訊息選取器表示式的訊息會遞送給訊息使用端。

空值或空字串值表示訊息使用端沒有訊息選取器。

length(輸入)
訊息選取器表示式的長度(以位元組計)。如果訊息選取器表示式在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
noLocal(輸入)
xmsTRUE 表示訊息使用端不接收其本身連線所發佈的訊息。值 xmsFALSE 表示訊息使用端將接收其本身連線所發佈的訊息。預設值為 xmsFALSE
consumer(輸出)
訊息使用端的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateDurableSubscriber – 建立延續訂閱者

介面:
xmsRC xmsSessCreateDurableSubscriber(xmsHSess session,
                                     xmsHDest topic,
                                     xmsCHAR *subscriptionName
                                     xmsHMsgConsumer *subscriber,
                                     xmsHErrorBlock errorBlock);

為指定的主題建立延續訂閱者。

此函數不適用於和分配管理系統間的即時連線。

如需延續訂閱者的相關資訊, 請參閱延續訂閱者

參數:
session(輸入)
階段作業的控點。
topic(輸入)
代表主題之 Destination 物件的控點。主題不得為暫時主題。
subscriptionName(輸入)
識別延續訂閱的名稱。此名稱在連線的用戶端 ID 中必須是唯一的, 且其格式為空值終止字串。
subscriber(輸出)
代表延續訂閱者之 MessageConsumer 物件的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateDurableSubscriberSelector – 建立延續訂閱者(使用訊息選取器和本端訊息旗標)

介面:
xmsRC xmsSessCreateDurableSubscriberSelector(xmsHSess session,
                                             xmsHDest topic,
                                             xmsCHAR *subscriptionName
                                             xmsCHAR *messageSelector,
                                             xmsINT length,
                                             xmsBOOL noLocal,
                                             xmsHMsgConsumer *subscriber,
                                             xmsHErrorBlock errorBlock);

使用訊息選取器為指定的主題建立延續訂閱者, 並指定延續訂閱者是否接收其本身連線所發佈的訊息。

此函數不適用於和分配管理系統間的即時連線。

如需延續訂閱者的相關資訊, 請參閱延續訂閱者

參數:
session(輸入)
階段作業的控點。
topic(輸入)
代表主題之 Destination 物件的控點。主題不得為暫時主題。
subscriptionName(輸入)
識別延續訂閱的名稱。此名稱在連線的用戶端 ID 中必須是唯一的, 且其格式為空值終止字串。
messageSelector(輸入)
字元陣列形式的訊息選取器表示式。只有內容符合訊息選取器表示式的訊息會遞送給延續訂閱者。

空值或空字串值表示延續訂閱者沒有訊息選取器。

length(輸入)
訊息選取器表示式的長度(以位元組計)。如果訊息選取器表示式在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
noLocal(輸入)
xmsTRUE 表示延續訂閱者不接收其本身連線所發佈的訊息。值 xmsFALSE 表示延續訂閱者將接收其本身連線所發佈的訊息。預設值為 xmsFALSE
subscriber(輸出)
代表延續訂閱者之 MessageConsumer 物件的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateMapMessage – 建立對映訊息

介面:
xmsRC xmsSessCreateMapMessage(xmsHSess session,
                              xmsHMsg *message,
                              xmsHErrorBlock errorBlock);

建立對映訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
對映訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateMessage – 建立訊息

介面:
xmsRC xmsSessCreateMessage(xmsHSess session,
                           xmsHMsg *message,
                           xmsHErrorBlock errorBlock);

建立一則沒有主體的訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateObjectMessage – 建立物件訊息

介面:
xmsRC xmsSessCreateObjectMessage(xmsHSess session,
                                 xmsHMsg *message,
                                 xmsHErrorBlock errorBlock);

建立物件訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
物件訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateProducer – 建立生產者

介面:
xmsRC xmsSessCreateProducer(xmsHSess session,
                            xmsHDest destination,
                            xmsHMsgProducer *producer,
                            xmsHErrorBlock errorBlock);

建立訊息生產者以傳送訊息給指定的目的地。

參數:
session(輸入)
階段作業的控點。
destination(輸入)
目的地的控點。

如果您指定空值控點,則會建立一個沒有目的地的訊息生產者。在此情況下, 應用程式每當使用訊息生產者來傳送訊息時,即必須指定一個目的地。

producer(輸出)
訊息生產者的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateStreamMessage – 建立串流訊息

介面:
xmsRC xmsSessCreateStreamMessage(xmsHSess session,
                                 xmsHMsg *message,
                                 xmsHErrorBlock errorBlock);

建立串流訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
串流訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessage – 建立文字訊息

介面:
xmsRC xmsSessCreateTextMessage(xmsHSess session,
                               xmsHMsg *message,
                               xmsHErrorBlock errorBlock);

建立一則空主體的文字訊息。

參數:
session(輸入)
階段作業的控點。
message(輸出)
文字訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessageInit – 建立文字訊息(已起始設定)

介面:
xmsRC xmsSessCreateTextMessageInit(xmsHSess session,
                                   xmsCHAR *text
                                   xmsINT length
                                   xmsHMsg *message,
                                   xmsHErrorBlock errorBlock);

建立文字訊息,並使用指定文字來起始設定其主體。

參數:
session(輸入)
階段作業的控點。
text(輸入)
內含用以起始設定文字訊息主體之文字的字元陣列。
length(輸入)
文字的長度(以位元組計)。如果文字在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
message(輸出)
文字訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessGetAcknowledgeMode – 取得確認模式

介面:
xmsRC xmsSessGetAcknowledgeMode(xmsHSess session,
                                xmsINT *acknowledgeMode,
                                xmsHErrorBlock errorBlock);

取得階段作業的確認模式。確認模式是在建立階段作業時指定。

交易式階段作業沒有確認模式。

如需確認模式的相關資訊,請參閱在階段作業中確認收到訊息

參數:
session(輸入)
階段作業的控點。
acknowledgeMode(輸出)
確認模式。假使階段作業不是交易式, 則確認模式的值可為下列之一:
  • XMSC_AUTO_ACKNOWLEDGE
  • XMSC_CLIENT_ACKNOWLEDGE
  • XMSC_DUPS_OK_ACKNOWLEDGE
如果階段作業為交易式,則函數會傳回 XMSC_SESSION_TRANSACTED
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessGetTransacted – 判斷是否為交易式

介面:
xmsRC xmsSessGetTransacted(xmsHSess session,
                           xmsBOOL *transacted,
                           xmsHErrorBlock errorBlock);

判斷階段作業是否為交易式。

參數:
session(輸入)
階段作業的控點。
transacted(輸出)
如果階段作業為交易式,則值為 xmsTRUE。如果階段作業不是交易式, 則值為 xmsFALSE

若為和分配管理系統間的即時連線, 此值固定是 xmsFALSE

errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsSessRecover – 回復

介面:
xmsRC xmsSessRecover(xmsHSess session,
                     xmsHErrorBlock errorBlock);

回復 (Recover) 階段作業。訊息遞送會停止, 然後使用最舊的未確認訊息重新啟動。

階段作業不得為交易式階段作業。

如需回復 (Recover) 階段作業的相關資訊, 請參閱在階段作業中確認收到訊息

參數:
session(輸入)
階段作業的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsSessRollback – 回復(Rollback)

介面:
xmsRC xmsSessRollback(xmsHSess session,
                      xmsHErrorBlock errorBlock);

回(Rollback)復現行交易中所有已處理的訊息。

參數:
session(輸入)
階段作業的控點。階段作業必須是交易式階段作業。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsSessUnsubscribe – 取消訂閱

介面:
xmsRC xmsSessUnsubscribe(xmsHSess session,
                         xmsCHAR *subscriptionName,
                         xmsHErrorBlock errorBlock);

刪除延續訂閱。傳訊伺服器會刪除它所維護的延續訂閱記錄, 且不會傳送任何進一步的訊息給延續訂閱者。

只要是下列情況,應用程式即無法刪除延續訂閱:
  • 延續訂閱有一個處於作用中的訊息使用端
  • 使用的訊息為擱置交易的一部分
  • 使用的訊息未經過確認

此函數不適用於和分配管理系統間的即時連線。

參數:
session(輸入)
階段作業的控點。
subscriptionName(輸入)
識別延續訂閱的名稱。此名稱採用空值終止字串格式。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

Reference topic

使用條款 | 評比此網頁

時間戳記前次更新: 25 Apr 2006
(C) Copyright IBM Corporation 2005. All Rights Reserved.
本資訊中心採用 Eclipse 技術。(http://www.eclipse.org)