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

StreamMessage

串流訊息是一種其主體包含一個值串流(其中每一個值都有一個相關聯的資料類型)的訊息。

主體的內容會依序寫入和讀取。

當應用程式從訊息串流中讀取值時,該值可由 XMS 轉換成另一種資料類型。如需這種隱含轉換形式的相關資訊,請參閱串流訊息

相關參考
串流訊息

函數

函數摘要:
函數 說明
xmsStreamMsgReadBoolean 從訊息串流中讀取 Boolean 值。
xmsStreamMsgReadByte 從訊息串流中讀取一個帶正負號的 8 位元整數。
xmsStreamMsgReadBytes 從訊息串流中讀取位元組陣列。
xmsStreamMsgReadBytesByRef 取得訊息串流中之位元組陣列的指標, 並取得陣列的長度。
xmsStreamMsgReadChar 從訊息串流中讀取一個二位元組字元。
xmsStreamMsgReadDouble 從訊息串流中讀取一個 8 位元組的倍精準度浮點數。
xmsStreamMsgReadFloat 從訊息串流中讀取一個 4 位元組的浮點數。
xmsStreamMsgReadInt 從訊息串流中讀取一個帶正負號的 32 位元整數。
xmsStreamMsgReadLong 從訊息串流中讀取一個帶正負號的 64 位元整數。
xmsStreamMsgReadObject 從訊息串流中讀取一值,並傳回其資料類型。
xmsStreamMsgReadShort 從訊息串流中讀取一個帶正負號的 16 位元整數。
xmsStreamMsgReadString 從訊息串流中讀取一個字串。
xmsStreamMsgReset 將訊息主體變成唯讀模式, 並將游標重新定位在訊息串流開頭。
xmsStreamMsgWriteBoolean 將 Boolean 值寫入訊息串流中。
xmsStreamMsgWriteByte 將位元組寫入訊息串流中。
xmsStreamMsgWriteBytes 將位元組陣列寫入訊息串流中。
xmsStreamMsgWriteChar 將字元當成 2 位元組寫入訊息串流中, 並從次序高的位元組開始。
xmsStreamMsgWriteDouble 將倍精準度浮點數轉換成長整數, 並將長整數當成 8 位元組寫入訊息串流中,且從次序高的位元組開始。
xmsStreamMsgWriteFloat 將浮點數轉換成整數, 並將整數當成 4 位元組寫入訊息串流中,且從次序高的位元組開始。
xmsStreamMsgWriteInt 將整數當成 4 位元組寫入訊息串流中, 並從次序高的位元組開始。
xmsStreamMsgWriteLong 將長整數當成 8 位元組寫入訊息串流中, 並從次序高的位元組開始。
xmsStreamMsgWriteObject 使用指定的資料類型,將值寫入訊息串流中。
xmsStreamMsgWriteShort 將短整數當成 2 位元組寫入訊息串流中, 並從次序高的位元組開始。
xmsStreamMsgWriteString 將字串寫入訊息串流中。

xmsStreamMsgReadBoolean – 讀取 Boolean 值

介面:
xmsRC xmsStreamMsgReadBoolean(xmsHMsg message,
                              xmsBOOL *value,
                              xmsHErrorBlock errorBlock);

從訊息串流中讀取 Boolean 值。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的 Boolean 值。如果您在輸入中指定一個空值指標, 則呼叫會略過 Boolean 值而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadByte – 讀取位元組

介面:
xmsRC xmsStreamMsgReadByte(xmsHMsg message,
                           xmsSBYTE *value,
                           xmsHErrorBlock errorBlock);

從訊息串流中讀取一個帶正負號的 8 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的位元組。如果您在輸入中指定一個空值指標, 則呼叫會略過該位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadBytes – 讀取位元組

介面:
xmsRC xmsStreamMsgReadBytes(xmsHMsg message,
                            xmsSBYTE *buffer,
                            xmsINT bufferLength,
                            xmsINT *returnedLength,
                            xmsHErrorBlock errorBlock);

從訊息串流中讀取位元組陣列。

參數:
message(輸入)
訊息的控點。
buffer(輸出)
內含所讀取之位元組陣列的緩衝區。

如果陣列中的位元組數小於或等於緩衝區的長度, 則會將整個陣列讀入緩衝區中。如果陣列中的位元組數大於緩衝區長度, 則緩衝區中會填入一部分的陣列, 且內部游標會標出下一個要讀取的位元組位置。後續的 xmsStreamMsgReadBytes() 呼叫會從游標現行位置開始讀取陣列中的位元組。

如果您在輸入中指定一個空值指標, 則呼叫會略過位元組陣列而不會讀取。

bufferLength(輸入)
緩衝區的長度(以位元組計)。如果您指定的是 XMSC_QUERY_SIZE, 則不會將位元組讀入緩衝區中,但陣列中所剩的位元組數(從游標的現行位置算起)會放在 returnedLength 參數中傳回,且游標不會前進。
returnedLength(輸出)
要讀入緩衝區中的位元組數。如果緩衝區只局部填入, 則其值小於緩衝區長度,這表示陣列中已無位元組要讀取。在呼叫前,如果陣列中已無留待讀取的位元組, 則其值為 XMSC_END_OF_BYTEARRAY

如果您在輸入中指定一個空值指標, 則函數不會傳回任何值。

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

xmsStreamMsgReadBytesByRef – 讀取參照形式的位元組

介面:
xmsRC xmsStreamMsgReadBytesByRef(xmsHMsg message,
                                 xmsSBYTE **array,
                                 xmsINT *length,
                                 xmsHErrorBlock errorBlock);

取得訊息串流中之位元組陣列的指標, 並取得陣列的長度。

如需如何使用此函數的相關資訊, 請參閱會以參照形式來傳回字串或位元組陣列的 C 函數

參數:
message(輸入)
訊息的控點。
array(輸出)
位元組陣列的指標。
length(輸出)
陣列中的位元組數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadChar – 讀取字元

介面:
xmsRC xmsStreamMsgReadChar(xmsHMsg message,
                           xmsCHAR16 *value,
                           xmsHErrorBlock errorBlock);

從訊息串流中讀取一個二位元組字元。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的字元。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadDouble – 讀取倍精準度浮點數

介面:
xmsRC xmsStreamMsgReadDouble(xmsHMsg message,
                             xmsDOUBLE *value,
                             xmsHErrorBlock errorBlock);

從訊息串流中讀取一個 8 位元組的倍精準度浮點數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的倍精準度浮點數。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadFloat – 讀取浮點數

介面:
xmsRC xmsStreamMsgReadFloat(xmsHMsg message,
                            xmsFLOAT *value,
                            xmsHErrorBlock errorBlock);

從訊息串流中讀取一個 4 位元組的浮點數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的浮點數。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadInt – 讀取整數

介面:
xmsRC xmsStreamMsgReadInt(xmsHMsg message,
                          xmsINT *value,
                          xmsHErrorBlock errorBlock);

從訊息串流中讀取一個帶正負號的 32 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的整數。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadLong – 讀取長整數

介面:
xmsRC xmsStreamMsgReadLong(xmsHMsg message,
                          xmsLONG *value,
                          xmsHErrorBlock errorBlock);

從訊息串流中讀取一個帶正負號的 64 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的長整數。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadObject – 讀取物件

介面:
xmsRC xmsstreamMsgReadObject(xmsHMsg message,
                             xmsSBYTE *buffer,
                             xmsINT bufferLength,
                             xmsINT *actualLength,
                             xmsOBJECT_TYPE *objectType,
                             xmsHErrorBlock errorBlock);

從訊息串流中讀取一值,並傳回其資料類型。

如需如何使用此函數的相關資訊, 請參閱會以值形式來傳回位元組陣列的 C 函數

參數:
message(輸入)
訊息的控點。
buffer(輸出)
內含值(以位元組陣列形式傳回)的緩衝區。如果值為一個字串而需要轉換資料, 則此為轉換後的值。

如果您在輸入中指定一個空值指標, 則呼叫會略過該值而不會讀取。

bufferLength(輸入)
緩衝區的長度(以位元組計)。如果您指定的是 XMSC_QUERY_SIZE, 則不會傳回值,而會將其長度放在 actualLength 參數中傳回。
actualLength(輸出)
值的長度(以位元組計)。如果值為一個字串而需要轉換資料, 則此為轉換後的長度。如果您在輸入中指定一個空值指標, 則不會傳回長度。
objectType(輸出)
值的資料類型,可為下列一種物件類型:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsStreamMsgReadShort – 讀取短整數

介面:
xmsRC xmsStreamMsgReadShort(xmsHMsg message,
                            xmsSHORT *value,
                            xmsHErrorBlock errorBlock);

從訊息串流中讀取一個帶正負號的 16 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的短整數。如果您在輸入中指定一個空值指標, 則呼叫會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadString – 讀取字串

介面:
xmsRC xmsStreamMsgReadString(xmsHMsg message,
                             xmsCHAR *buffer,
                             xmsINT bufferLength,
                             xmsINT *actualLength,
                             xmsHErrorBlock errorBlock);

從訊息串流中讀取一個字串。必要時, XMS 會將字串中的字元轉換成區域字碼頁。

如需如何使用此函數的相關資訊, 請參閱會以值形式來傳回字串的 C 函數

參數:
message(輸入)
訊息的控點。
buffer(輸出)
內含所讀取之字串的緩衝區。如果需要轉換資料, 則此為轉換後的字串。
bufferLength(輸入)
緩衝區的長度(以位元組計)。

如果您指定 XMSC_QUERY_SIZE, 則不會傳回字串,而會將其長度放在 actualLength 參數中傳回,且游標不會前進。

如果您指定 XMSC_SKIP, 則函數會略過該字串而不會讀取。

actualLength(輸出)
字串的長度(以位元組計)。如果需要轉換資料, 則此為轉換後的字串長度。如果您在輸入中指定一個空值指標, 則不會傳回長度。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION
附註:
  1. 如果緩衝區不夠儲存整個字串,XMS 會傳回截斷成符合緩衝區長度的字串, 以及將 actualLength 參數設為字串的實際長度,並傳回 XMS_E_DATA_TRUNCATED 錯誤碼。XMS 不會使內部游標前進。
  2. 如果在試著讀取字串期間發生其他任何錯誤, XMS 會報告錯誤,但不會設定 actualLength 參數或使內部游標前進。

xmsStreamMsgReset – 重設

介面:
xmsRC xmsStreamMsgReset(xmsHMsg message,
                        xmsHErrorBlock errorBlock);

將訊息主體變成唯讀模式, 並將游標重新定位在訊息串流開頭。

參數:
message(輸入)
訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgWriteBoolean – 寫入 Boolean 值

介面:
xmsRC xmsStreamMsgWriteBoolean(xmsHMsg message,
                               xmsBOOL value,
                               xmsHErrorBlock errorBlock);

將 Boolean 值寫入訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的 Boolean 值。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteByte – 寫入位元組

介面:
xmsRC xmsStreamMsgWriteByte(xmsHMsg message,
                            xmsSBYTE value,
                            xmsHErrorBlock errorBlock);

將位元組寫入訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的位元組。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteBytes – 寫入多個位元組

介面:
xmsRC xmsStreamMsgWriteBytes(xmsHMsg message,
                             xmsSBYTE *value,
                             xmsINT length,
                             xmsHErrorBlock errorBlock);

將位元組陣列寫入訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的位元組陣列。
length(輸入)
陣列中的位元組數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteChar – 寫入字元

介面:
xmsRC xmsStreamMsgWriteChar(xmsHMsg message,
                            xmsCHAR16 value,
                            xmsHErrorBlock errorBlock);

將字元當成 2 位元組寫入訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的字元。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteDouble – 寫入倍精準度浮點數

介面:
xmsRC xmsStreamMsgWriteDouble(xmsHMsg message,
                              xmsDOUBLE value,
                              xmsHErrorBlock errorBlock);

將倍精準度浮點數轉換成長整數, 並將長整數當成 8 位元組寫入訊息串流中,且從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的倍精準度浮點數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteFloat – 寫入浮點數

介面:
xmsRC xmsStreamMsgWriteFloat(xmsHMsg message,
                             xmsFLOAT value,
                             xmsHErrorBlock errorBlock);

將浮點數轉換成整數, 並將整數當成 4 位元組寫入訊息串流中,且從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的浮點數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteInt – 寫入整數

介面:
xmsRC xmsStreamMsgWriteInt(xmsHMsg message,
                           xmsINT value,
                           xmsHErrorBlock errorBlock);

將整數當成 4 位元組寫入訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteLong – 寫入長整數

介面:
xmsRC xmsStreamMsgWriteLong(xmsHMsg message,
                            xmsLONG value,
                            xmsHErrorBlock errorBlock);

將長整數當成 8 位元組寫入訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的長整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteObject – 寫入物件

介面:
xmsRC xmsStreamMsgWriteObject(xmsHMsg message,
                              xmsSBYTE *value,
                              xmsINT length,
                              xmsOBJECT_TYPE objectType,
                              xmsHErrorBlock errorBlock);

使用指定的資料類型,將值寫入訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
內含所要寫入之值的位元組陣列。
length(輸入)
陣列中的位元組數。
objectType(輸入)
值的資料類型,其物件類型必須是下列之一:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

xmsStreamMsgWriteShort – 寫入短整數

介面:
xmsRC xmsStreamMsgWriteShort(xmsHMsg message,
                             xmsSHORT value,
                             xmsHErrorBlock errorBlock);

將短整數當成 2 位元組寫入訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的短整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteString – 寫入字串

介面:
xmsRC xmsStreamMsgWriteString(xmsHMsg message,
                              xmsCHAR *value,
                              xmsINT length,
                              xmsHErrorBlock errorBlock);

將字串寫入訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
內含所要寫入之字串的字元陣列。
length(輸入)
字串的長度(以位元組計)。如果字串在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Reference topic

使用條款 | 評比此網頁

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