next up previous
Next: Diagnostic Functions Up: Host (PC) RTDX API Previous: Channel Write Functions

Query Functions



Get channel ID


long GetChannelID( BSTR Channel_String, long * chanId )

Retrieves the internal ID for a given RTDX event/data channel.

Parameters:

channel_string Name of event/data channel.
chanId Internal ID of channel.
   
Returns:

long Success - Data query is valid.
  Failure - Error occurred during query.


Get message ID


long GetMsgID( long * pMsgId )

Retrieves the internal ID for the message currently being read. The message ID corresponds to the channel ID of the channel that the message was written to. This function can be used to synchronize messages when reading the "ALL" data channel by comparing a message's ID to the channel's ID.
The function GotoNextMsg must be called successfully before calling this function; otherwise, failure will be returned.

Parameters:

pMsgId Pointer to the ID of the current message.
   
Returns:

long Success - The ID was successfully returned.
  Failure - Unopened channel or the channel is not read-only.
  ENoDataAvailable - No data was available. However, more data may be available in the future as the target application has not yet terminated.
  EEndOfLogFile - The end of the log file has been reached.


Get message length


long GetMsgLength( long * pLength )

GetMsgLength returns the number of bytes in the current message. The value is returned in *pLength. The function GotoNextMsg must be called successfully before calling this function; otherwise, failure will be returned.

Parameters:

pLength Pointer to the length of the current message in terms of bytes.
   
Returns:

long Success - The length was successfully returned.
  Failure - Unopened channel or the channel is not read-only.
  ENoDataAvailable - No data was available. However, more data may be available in the future as the target application has not yet terminated.
  EEndOfLogFile - The end of the log file has been reached.


Get message number


long GetMsgNumber( long * pMsgNum )

Messages are stored sequentially in the log file. This function returns the sequence number of the current message. It can be used to synchronize data retrieved from multiple channels. The function GotoNextMsg must be called successfully before calling this function; otherwise, failure will be returned.

Parameters:

pMsgNum Pointer to the sequence number of the current message.
   
Returns:

long Success - The sequence number was successfully returned.
  Failure - Unopened channel or the channel is not read-only.
  ENoDataAvailable - No data was available. However, more data may be available in the future as the target application has not yet terminated.
  EEndOfLogFile - The end of the log file has been reached.


Get number of messages


long GetNumMsgs( long * pNum )

The GetNumMsgs function returns the total number of messages in the log file.

Parameters:

pNum Pointer to the number of messages in the log file.
   
Returns:

long Success - The number of messages was successfully returned.
  Failure - Unopened channel or the channel is not read-only.
  ENoDataAvailable - No data was available. However, more data may be available in the future as the target application has not yet terminated.
  EEndOfLogFile - The end of the log file has been reached.


Go to next message


long GotoNextMsg( )

Advance to the first or next message in the log file. This function must be called and return a successful status in order for any of the other Query functions to return valid results. This function must be used to read event messages.

Parameters:

none  
   
Returns:

long Success - The next message was found.
  Failure - The next message was not found.



next up previous
Next: Diagnostic Functions Up: Host (PC) RTDX API Previous: Channel Write Functions
H. Rogalla 2005-12-07