Class Log

Defined in File LogApi.h

Class Documentation

class Log

This class contains log functions.

Public Functions

Log(WMX3Api *f): Constructor to initialize an object of this class. The device created by the WMX3Api object passed to this constructor is used to execute API functions. Also see Devices.

Log(const Log &src): Copy constructor to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

Log &operator=(const Log &src): Copy assignment operator to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

Log(): Constructor to initialize an object of this class with a self device. Also see Self Devices.

~Log(): Destructor for this class.

bool IsDeviceValid()

Return TRUE if this class object has access to a device, and FALSE otherwise. A device is required to execute most functions in this class. If this function returns FALSE, a device can be created by calling the CreateDevice function from the WMX3Api object that was passed to the constructor of this class.

WMX3APIFUNC GetVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module rtdll.

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.

WMX3APIFUNC StartLog(unsigned int channel)

Start logging data.

Before starting to log data, data logging settings must first be set using the SetLog API function.

Remark

When this function is called, a file will be immediately created at the file path specified by the SetLog API function. Data will be collected and written to this file until the specified sample time elapses or an error is encountered.

Call the GetLogStatus API function to obtain the status of the logging operation.

See also

Data Log

Parameters:: channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.

WMX3APIFUNC StopLog(unsigned int channel)

Stop logging data.

Data logging can be finished before the specified sample time elapses using this function. When this function is called, data logging will stop. Data that had already been written to the log file remain written.

Remark

Parameters:: channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.

WMX3APIFUNC ResetLog(unsigned int channel)

Reset the log settings, options, and statuses for the specified log channel.

When this function is called, all log settings, options, and statuses are cleared for the specified channel.

Remark

This function cannot be called while a logging operation is active. The state of the log channel obtained with the GetDetailLogStatus function must be Finished, WriteFail, or BufferOverflow.

Parameters:: channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.

WMX3APIFUNC SetLogHeader(unsigned int channel, char **ppLine, unsigned int numLines)

Set the log header string that is copied to the beginning of the log file.

This function sets the header string that is printed at the beginning of the log file. This function is optional, and it is not necessary to call this function when collecting log data. If this function is not called, no header will be printed at the beginning of the log file.

Remark

The maximum number of lines that may constitute the header is defined by the maxLogHeaderLines constant. The maximum number of characters total in the header (including the new line character at the end of each line) is defined by the maxLogHeaderBytes constant.

The log header can be removed by calling the ResetLog function. All other log settings and options will also be cleared, and will need to be set again.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
ppLine – [in] An array of pointers to null-terminated char arrays. Each null-terminated char array contains one line of the header.
numLines – [in] The number of elements (pointers to null-terminated char arrays) in the value passed to the “ppLine” parameter. Each pointer (to a null-terminated char array) contains one line of the header string, so the “numLines” value effectively specifies the number of lines in the header.

WMX3APIFUNC SetLog(unsigned int channel, LogInput *input)

Specify data to be collected by the logging operation.

This function specifies which data to be collected by the logging operation.

Remark

Each module that contains data that can be logged defines a class that inherits the LogInput class. For example, the CoreMotion module defines the CoreMotionLogInput class, which can be used to collect axis data such as position commands. The IO module defines the IoLogInput, which can be used to collect I/O data.

Data from multiple modules may be logged simultaneously. To do so, call this function multiple times, passing in a different LogInput object each time. For example, to collect the position command data of an axis and I/O data in a single log file, call this function passing an CoreMotionLogInput object, and then call this function again passing an IoLogInput object.

If the data to collect from a module has been specified already, calling this function again for the same module will overwrite the set of data to collect.

This function allocates memory each time it is called. If there is not enough contiguous memory in the real time operating system space, an error will be returned.

The memory allocated by this function is released when the log operation finishes. To start another log operation, this function must be called again.

See also

Data Log

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
input – [in] A pointer to an object of a class that inherits the LogInput class.

WMX3APIFUNC SetLogOption(unsigned int channel, LogChannelOptions *pOption)

Set the log options for a log channel.

This function sets the log options for a log channel. These options are applied each time a log operation is started by the specified channel.

Remark

Before this function is called for a log channel, the default log options are applied (these default log options can be obtained by calling GetLogOption before calling this function).

See also

Data Log

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pOption – [in] A pointer to an object of the LogChannelOptions class that contains the log options.

WMX3APIFUNC GetLogOption(unsigned int channel, LogChannelOptions *pOption)

Get the log options for a log channel.

This function gets the log options for a log channel.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pOption – [out] A pointer to an object of the LogChannelOptions class will contain the log options.

WMX3APIFUNC SetLogFilePath(unsigned int channel, LogFilePathA *pPath)

Set the file path for a log channel.

This function sets the file path for a log channel. Log operations started by the specified channel will save the log file to this file path.

Remark

The directory specified in dirPath must exist. Otherwise, the log operation will generate a WriteFail error.

The file path is specified as a char string. To specify the file path as a wchar_t string, use the SetLogFilePath function.

If a log operation is started for a log channel before calling this function, the log file is saved to the default file path of “C:\wmx3_logfile.txt”.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [in] A pointer to an object of the LogFilePathA class that contains the file path.

WMX3APIFUNC GetLogFilePath(unsigned int channel, LogFilePathA *pPath)

Get the file path for a log channel.

This function gets the file path of a log channel. This is the file path that the log file will be saved to when a log operation is started by the log channel.

Remark

The file path is obtained as a char string. To obtain the file path as a wchar_t string, use the GetLogFilePath function.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [out] A pointer to an object of the LogFilePathA class that will contain the file path.

WMX3APIFUNC SetLogFilePath(unsigned int channel, LogFilePathW *pPath)

Set the file path for a log channel.

This function sets the file path for a log channel. Log operations started by the specified channel will save the log file to this file path.

Remark

The directory specified in dirPath must exist. Otherwise, the log operation will generate a WriteFail error.

The file path is specified as a wchar_t string. To specify the file path as a char string, use the SetLogFilePath function.

If a log operation is started for a log channel before calling this function, the log file is saved to the default file path of “C:\wmx3_logfile.txt”.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [in] A pointer to an object of the LogFilePathW class that contains the file path.

WMX3APIFUNC GetLogFilePath(unsigned int channel, LogFilePathW *pPath)

Get the file path for a log channel.

This function gets the file path of a log channel. This is the file path that the log file will be saved to when a log operation is started by the log channel.

Remark

The file path is obtained as a wchar_t string. To obtain the file path as a char string, use the GetLogFilePath function.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [out] A pointer to an object of the LogFilePathW class that will contain the file path.

WMX3APIFUNC GetLogStatus(unsigned int channel, LogStatus *pStatus)

Get the current status of the data logging operation.

This function obtains the status of the current logging operation. This function may be called after starting a logging operation using StartLog to observe the progress of the logging operation.

Remark

The samplesToCollect, samplesCollected, and samplesWritten values contain the same information as the millisecondsToCollect, millisecondsCollected, and millisecondsWritten values. The difference between these two groups of values is the unit.

If logging is stopped because of write failure, verify that the application calling the log function has permission to write to the specified file path of the log file.

If logging is stopped because of buffer overflow, reduce the number of axes to log data, reduce the number of types of data to log, increase the sampling period (reduce the sampling frequency), or improve the file write speed of the PC.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pStatus – [out] A pointer to a LogStatus that will contain the current status of the logging operation.

WMX3APIFUNC GetDetailLogStatus(unsigned int channel, DetailLogStatus *pStatus)

Get the current status of the data logging operation. Compared to GetLogStatus, more detailed statuses can be obtained.

This function obtains the detailed status of the current logging operation.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pStatus – [out] A pointer to a DetailLogStatus that will contain the current status of the logging operation.

WMX3APIFUNC SetCustomLog(unsigned int channel, unsigned int moduleId, void *data, unsigned int dataSize, LogType::T type)

Reserved.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
moduleId – [in] The module ID of the module that defines the class inheriting LogInput passed to data.
data – [in] A pointer to an object of a class that inherits the LogInput class.
dataSize – [in] The size of the object passed to data, in bytes.
type – [in] The type of log to set.

WMX3APIFUNC SetLog(unsigned int channel, char *pPath, unsigned int milliseconds, unsigned int samplePeriodInCycles, AxisSelection *pAxisSelection, LogOptions *pOptions, unsigned int mode, unsigned int burstWriteLines = 4, unsigned int scale = 9)

Set data logging settings.

This function sets the data log settings, but will not start logging data. Use the StartLog API function to start collecting log data using the specified settings.

Remark

The log function can collect the command and feedback data for every communication cycle during the logging period. This information can be used to obtain an accurate picture of the operation of the machine.

The logged data is saved to a text file.

Each row of the data log contains data for a particular communication cycle. Data values are separated by tab characters. The first row of the data log contains a text representation of the data stored in that column. The first column of the data log always stores the communication cycle number.

A sample data log is as follows:

CYCLE	CMDPOS 0	FBPOS 0	CMDPOS 1	FBPOS 1
10000	150000.000000	150000.000000	320000.000000	320000.000000
10001	150000.000000	150000.000000	320000.000000	320000.000000
10002	150000.000000	150000.000000	320000.000000	320000.000000
10003	150000.000000	150000.000000	320000.000000	320000.000000
10004	150000.000000	150000.000000	320000.000000	320000.000000

In this example, the first column contains the cycle time, the second column contains the position command for axis 0, the third column contains the position feedback for axis 0, the fourth column contains the position command for axis 1, and the fifth column contains the position feedback for axis 1.

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [in] The absolute file path to save the log file to.
milliseconds – [in] The number of milliseconds to collect data samples to write to the log.
samplePeriodInCycles – [in] The sampling period in units of communication cycles. This value determines the frequency at which data samples are taken. When set to 1, samples will be collected every cycle.
pAxisSelection – [in] A pointer to an AxisSelection class object that specifies the axes to collect the data of.
pOptions – [in] A pointer to a LogOptions class object that specifies what data to collect.
mode – [in] Reserved. This value is ignored.
burstWriteLines – [in] The number of lines to write at once. This value must be between 4 and 1020. A value that is too small can increase the load on the engine due to frequent file writing, and a value that is too large can put a large instantaneous load on the engine (although these loads should not affect the cyclic operation of the engine). In most cases, the default value of 4 is suitable.
scale – [in] The number of decimal places to write for floating point data.

WMX3APIFUNC SetLog(unsigned int channel, wchar_t *pPath, unsigned int milliseconds, unsigned int samplePeriodInCycles, AxisSelection *pAxisSelection, LogOptions *pOptions, unsigned int mode, unsigned int burstWriteLines = 4, unsigned int scale = 9)

Set data logging settings.

This function is a variation of SetLog that accepts a wchar_t array for the file path string. Use this function when using Unicode character sets.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pPath – [in] The absolute file path to save the log file to.
milliseconds – [in] The number of milliseconds to collect data samples to write to the log.
samplePeriodInCycles – [in] The sampling period in units of communication cycles. This value determines the frequency at which data samples are taken. When set to 1, samples will be collected every cycle.
pAxisSelection – [in] A pointer to an AxisSelection class object that specifies the axes to collect the data of.
pOptions – [in] A pointer to a LogOptions class object that specifies what data to collect.
mode – [in] Reserved. This value is ignored.
burstWriteLines – [in] The number of lines to write at once. This value should be between 4 and 1020 to prevent write buffer overflow errors. Increasing this value may reduce the load on the CPU.
scale – [in] The number of decimal places to write for floating point data.

WMX3APIFUNC SetIOLog(unsigned int channel, IOAddress *pInputIOAddress, unsigned int inputSize, IOAddress *pOutputIOAddress, unsigned int outputSize)

Set data logging settings for logging I/O data.

This function can be called to specify the data log function to log I/O data when StartLog is called. I/O data can be logged alongside position/velocity data by calling both SetLog and SetIOLog.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pInputIOAddress – [in] An array of I/O input addresses. The size parameter must be specified. Multiple contiguous bits can be specified by setting size to the number of bits.
inputSize – [in] The number elements in the pInputIOAddress array.
pOutputIOAddress – [in] An array of I/O output addresses. The size parameter must be specified. Multiple contiguous bits can be specified by setting size to the number of bits.
outputSize – [in] The number of elements in the pOutputIOAddress array.

WMX3APIFUNC SetIOLogFormat(unsigned int channel, IOLogFormat *pInputIOLogFormat, unsigned int inputIOFormatCount, IOLogFormat *pOutputIOLogFormat, unsigned int outputIOFormatCount)

Set data logging settings for logging I/O data in a custom format.

This function is an alternate way to log I/O data. This function allows contiguous sequences of I/O to be logged under a single column, whereas the SetIOLog function logs each individual I/O bit under a separate column. This function is useful when logging I/O data for systems which contain entities that are represented by multiple I/O bits, such as analog I/O modules.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pInputIOLogFormat – [in] A pointer to an array of IOLogFormat objects. Each IOLogFormat object defines a contiguous region of I/O input addresses to log using a particular format. The byte member specifies the starting byte address of the region of I/O inputs to log. The bit member specifies the starting bit address of the region of I/O inputs to log. The ioFormatType member specifies the format of the logged data.
inputIOFormatCount – [in] The number of elements in the inputIOLogFormat array.
pOutputIOLogFormat – [in] A pointer to an array of IOLogFormat objects. Each IOLogFormat object defines a contiguous region of I/O output addresses to log using a particular format. The byte member specifies the starting byte address of the region of I/O outputs to log. The bit member specifies the starting bit address of the region of I/O outputs to log. The ioFormatType member specifies the format of the logged data.
outputIOFormatCount – [in] The number of elements in the outputIOLogFormat array.

WMX3APIFUNC SetMLog(unsigned int channel, MAddress *pMAddress, unsigned int size)

Set data logging settings for logging user memory data.

This function can be called to specify the data log function to log user memory data when StartLog is called. User memory data can be logged alongside position/velocity data by calling both SetLog and SetMLog.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pMAddress – [in] An array of user memory addresses. The size parameter must be specified. Multiple contiguous bits can be specified by setting size to the number of bits.
size – [in] The number elements in the pMAddress array.

WMX3APIFUNC SetMLogFormat(unsigned int channel, MLogFormat *pMLogFormat, unsigned int mFormatCount)

Set data logging settings for logging user memory data in a custom format.

This function is an alternate way to log user memory data. This function allows contiguous sequences of user memory to be logged under a single column, whereas the SetMLog function logs each individual user memory bit under a separate column. This function is useful for logging a contiguous segment of user memory that represents a single entity.

Remark

Parameters:

channel – [in] The channel of the log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxLogChannel constant.
pMLogFormat – [in] A pointer to an array of MLogFormat objects. Each MLogFormat object defines a contiguous region of user memory addresses to log using a particular format. The byte member specifies the starting byte address of the region of user memory to log. The bit member specifies the starting bit address of the region of user memory to log. The mFormatType member specifies the format of the logged data.
mFormatCount – [in] The number of elements in the pMLogFormat array.

WMX3APIFUNC OpenMemoryLogBuffer(unsigned int channel)

Open the memory log buffer.

This function opens the memory log buffer. The memory log buffer must be opened before memory log operations can be performed.

Remark

The memory log buffer should be opened as early as possible if memory log operations will be used by the application, as this function can fail if the system does not have enough memory to open the log buffer.

If a function that requires the memory log buffer (SetMemoryLog) is called before the memory log buffer is opened, the function will attempt to open the memory log buffer automatically.

Once the memory log buffer has been opened, it does not need to be opened again unless the log buffer is closed with the CloseMemoryLogBuffer function or the engine is restarted.

Parameters:: channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.

WMX3APIFUNC CloseMemoryLogBuffer(unsigned int channel)

Close the memory log buffer.

This function closes the memory log buffer that has been opened by the OpenMemoryLogBuffer function. This frees the memory that has been used for the memory log buffer. Once the memory log buffer is closed, memory log functions will be unavailable until the memory log buffer is reopened using the OpenMemoryLogBuffer function.

Remark

It is not neccessary to close the memory log buffer once it is opened. For most cases, the memory log buffer should be opened during initialization and kept open for the entire session.

It is not necessary to call this function before closing the WMX3 engine. All buffers that were open at the time that the WMX3 engine closes will be closed automatically.

Parameters:: channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.

WMX3APIFUNC SetMemoryLog(unsigned int channel, LogInput *input)

Specify data to be collected by the memory log operation.

This function specifies which data to be collected by the memory log operation.

Remark

Each module that contains data that can be logged defines a class that inherits the LogInput class. For example, the CoreMotion module defines the CoreMotionLogInput class, which can be used to collect axis data such as position commands. The IO module defines the IoLogInput, which can be used to collect I/O data.

Data from multiple modules may be logged simultaneously. To do so, call this function multiple times, passing in a different LogInput object each time. For example, to collect the position command data of an axis and I/O data in a single log file, call this function passing an CoreMotionLogInput object, and then call this function again passing an IoLogInput object.

If the data to collect from a module has been specified already, calling this function again for the same module will overwrite the set of data to collect.

The collected data can be read out with GetMemoryLogData function.

This function allocates memory each time it is called. If there is not enough contiguous memory in the real time operating system space, an error will be returned.

The memory allocated by this function is not released until CloseMemoryLogBuffer function or ResetMemoryLog function is called or the WMX3 engine is closed. As an exception, the memory allocated by specifying LogApiLogInput as an argument to this function will not be freed by ResetMemoryLog function.

See also

Memory Log

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
input – [in] A pointer to an object of a class that inherits the LogInput class.

WMX3APIFUNC SetMemoryLogOption(unsigned int channel, MemoryLogOptions *pOption)

Set the memory log options for a memory log channel.

This function sets the memory log options for a log channel. These options are applied each time a memory log operation is started by the specified channel.

Remark

Before this function is called for a memory log channel, the default memory log options are applied (these default memory log options can be obtained by calling GetMemoryLogOption before calling this function).

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pOption – [in] A pointer to an object of the MemoryLogOptions class that contains the memory log options.

WMX3APIFUNC GetMemoryLogOption(unsigned int channel, MemoryLogOptions *pOption)

Get the memory log options for a memory log channel.

This function gets the memory log options for a memory log channel.

Remark

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pOption – [out] A pointer to an object of the MemoryLogOptions class will contain the memory log options.

WMX3APIFUNC StartMemoryLog(unsigned int channel)

Start the memory log operation.

Memory log settings must first be set using the SetMemoryLog API function.

Remark

When this function is called, the data specified by functions such as SetMemoryLog will be recorded to a preallocated buffer every cycle. The recording continues until the StopMemoryLog function is called or an error is encountered.

Call the GetMemoryLogStatus API function to obtain the status of the logging operation.

Parameters:: channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.

WMX3APIFUNC StopMemoryLog(unsigned int channel)

Stop the memory log operation.

When this function is called, the engine will stop recording data to the memory log.

Remark

Parameters:: channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.

WMX3APIFUNC ResetMemoryLog(unsigned int channel)

Reset the memory log settings, options, and statuses for the specified memory log channel.

When this function is called, all memory log settings, options, and statuses are cleared for the specified channel.

Remark

This function cannot be called while a memory log operation is active. The logState of the memory log channel obtained with the GetMemoryLogStatus function must be Idle.

Parameters:: channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.

WMX3APIFUNC GetMemoryLogStatus(unsigned int channel, MemoryLogStatus *pStatus)

Get the current status of the memory log operation.

This function obtains the status of the memory log.

Remark

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pStatus – [out] A pointer to a MemoryLogStatus that will contain the current status of the logging operation.

WMX3APIFUNC GetMemoryLogData(unsigned int channel, LogOutput *pOutput)

Retrieve data from memory log of a single module.

This function retrieves a maximum of maxLogOutputDataSize cycles of log data from memory log buffer each time it is called.

Remark

Only the data of the module specified in pOutput is retrieved. If SetMemoryLog is called multiple times to set multiple modules to the memory log, this function will discard the log data of the same cycle for modules other than the one specified in the argument pOutput. To retrieve log data of multiple modules at the same time, use the GetMemoryLogData function.

The memory log buffer stores up to maxMemLogBufferSize cycles of data at one time. If the logged data is not read using GetMemoryLogData fast enough, log data will be overwritten starting from the oldest data (this can be observed by checking for skipped cycles in the cycleCounter or the overflowFlag value of the log data.

Calling this function and retrieving data from the buffer will clear the overflowFlag until the buffer overflows again.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pOutput – [out] A pointer to an object of a class that inherits the LogOutput class object that will contain the logged data.

WMX3APIFUNC GetMemoryLogData(unsigned int channel, LogOutput **ppOutput, unsigned int size)

Retrieve data from memory log of multiple modules.

This function retrieves a maximum of maxLogOutputDataSize cycles of log data from memory log buffer each time it is called.

Remark

Datas of the all module specified in ppOutput are retrieved. If SetMemoryLog is called multiple times to set multiple modules to the memory log, this function will discard the log data of the same cycle for modules other than the one specified in the argument ppOutput.

The log data of multiple modules retrieved at the same time will be the data logged in the same cycle.

The memory log buffer stores up to maxMemLogBufferSize cycles of data at one time. If the logged data is not read using GetMemoryLogData fast enough, log data will be overwritten starting from the oldest data (this can be observed by checking for skipped cycles in the cycleCounter or the overflowFlag value of the log data.

Calling this function and retrieving data from the buffer will clear the overflowFlag until the buffer overflows again.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
ppOutput – [out] An array of pointers to objects of a class that inherits the LogOutput class object that will contain the logged data.
size – [in] The number of elements in the ppOutput array.

WMX3APIFUNC SetMemoryLog(unsigned int channel, AxisSelection *pAxisSelection, MemoryLogOptions *pOption)

Set memory log settings.

The memory log function is used to collect command and feedback data at a high frequency, and instead of the logged data being saved to a text file, the logged data is recorded within memory. The logged memory is read by periodically calling the GetMemoryLogData function.

Remark

I/O and user memory data can also be recorded by the memory log function.

After calling this function, the StartMemoryLog function can be called to start collecting memory log data. Collection of memory log data can be stopped with the StopMemoryLog function.

The GetMemoryLogData function should be called periodically to read the log data that is stored in memory. This function will check the buffer for any log data that has been stored but not yet read, and returns them. The number of cycles of data returned can be found in the count value of the returned data. The first count indices of the logData array will contain valid log data.

The buffer for the log data can store maxMemLogBufferSize communication cycles worth of data. If data is not retrived fast enough, data will be erased from the buffer starting with the oldest data. Each call of the GetMemoryLogData function retrives maxMemLogDataSize cycles worth of data.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pAxisSelection – [in] A pointer to an AxisSelection class object that specifies the axes to collect the data of.
pOption – [in] A pointer to a MemoryLogOptions class object that specifies the logging options.

WMX3APIFUNC SetMemoryIOLog(unsigned int channel, IOAddress *pInputIOAddress, unsigned int inputSize, IOAddress *pOutputIOAddress, unsigned int outputSize)

Set I/O memory log settings.

This function should be called before calling StartMemoryLog to specify regions of the I/O to log with the memory log function.

Remark

The total amount of I/O that will be logged cannot be greater than maxMemLogIoInputByteSize for inputs and maxMemLogIoOutputByteSize for outputs. Bytes count against this limit even if only one bit of the byte is actually logged.

The memory log buffer stores up to maxMemLogBufferSize cycles of data at one time. If the logged data is not read using GetMemoryLogData fast enough, log data will be overwritten starting from the oldest data (this can be observed by checking for skipped cycles in the cycleCounter or the overflowFlag value of the log data.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pInputIOAddress – [in] An array of I/O input addresses. Multiple contiguous bits can be specified by setting size to the number of bits.
inputSize – [in] The number elements in the pInputIOAddress array.
pOutputIOAddress – [in] An array of I/O output addresses. Multiple contiguous bits can be specified by setting size to the number of bits.
outputSize – [in] The number of elements in the pOutputIOAddress array.

WMX3APIFUNC SetMemoryMLog(unsigned int channel, MAddress *pMAddress, unsigned int size)

Set user memory memory log settings.

This function should be called before calling StartMemoryLog to specify regions of the user memory to log with the memory log function.

Remark

The total amount of user memory that will be logged cannot be greater than maxMemLogMDataByteSize. Bytes count against this limit even if only one bit of the byte is actually logged.

The memory log buffer stores up to maxMemLogBufferSize cycles of data at one time. If the logged data is not read using GetMemoryLogData fast enough, log data will be overwritten starting from the oldest data (this can be observed by checking for skipped cycles in the cycleCounter or the overflowFlag value of the log data.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pMAddress – [in] An array of user memory addresses. Multiple contiguous bits can be specified by setting size to the number of bits.
size – [in] The number elements in the pMAddress array.

WMX3APIFUNC GetMemoryLogData(unsigned int channel, MemoryLogData *pData)

Retrieve data from memory log.

This function retrieves a maximum of maxMemLogDataSize cycles of log data each time it is called.

Remark

The memory log buffer stores up to maxMemLogBufferSize cycles of data at one time. If the logged data is not read using GetMemoryLogData fast enough, log data will be overwritten starting from the oldest data (this can be observed by checking for skipped cycles in the cycleCounter or the overflowFlag value of the log data.

Calling this function and retrieving data from the buffer will clear the overflowFlag until the buffer overflows again.

Parameters:

channel – [in] The channel of the memory log operation. Each channel operates independently from all other channels. The first channel is 0. The number of available channels is defined by the maxMemLogChannel constant.
pData – [out] A pointer to a MemoryLogData class object that will contain the logged data.

WMX3APIFUNC SetApiLog(char *pPath, ApiLogOptions *pOptions = NULL, unsigned int buffSize = 16777216)

Set the parameters for the API log.

This function sets the parameters for the API log. This function must be called before calling the StartApiLog function.

Remark

The API log records API function call data to file. Information is extracted from the API log file with the GetApiLogData function. For additional information, see the link under “See also” below.

This function allocates memory each time it is called. If there is not enough contiguous memory in the real time operating system space, an error will be returned.

See also

Configuring the API Log

Parameters:

pPath – [in] The absolute file path to save the API log file to.
pOptions – [in] An optional argument that specifies options for the API log.
buffSize – [in] An optional argument that specifies the size of the buffer memory to allocate for the API log, in units of bytes. If not specified, a buffer memory of the default size will be allocated.

WMX3APIFUNC SetApiLog(wchar_t *pPath, ApiLogOptions *pOptions = NULL, unsigned int buffSize = 16777216)

Set the parameters for the API log.

This function is a variation of SetApiLog that accepts a wchar_t array for the file path string. Use this function when using Unicode character sets.

Remark

Parameters:

pPath – [in] The absolute file path to save the log file to.
pOptions – [in] An optional argument that specifies options for the API log.
buffSize – [in] The size of the buffer memory to allocate for the API log, in units of bytes.

WMX3APIFUNC StartApiLog()

Start logging data to the API log.

This function starts logging data to the API log file.

Remark

The SetApiLog function must be called before calling this function to set the API log parameters and allocate the buffer memory.

See also

Saving the API Log File

WMX3APIFUNC StopApiLog()

Stop logging data to the API log.

This function stops logging data to the API log file.

Remark

Logging of data must first be started with the StartApiLog function.

WMX3APIFUNC GetApiLogStatus(ApiLogStatus *pStatus)

Get the current status of the API log.

This function gets the current status of the API log. This function can be called periodically to monitor the API log state.

Remark

Parameters:: pStatus – [out] A pointer to an ApiLogStatus class object that will contain the current status of the API log.

WMX3APIFUNC OpenApiLogFile(char *pPath, FILE **ppFile)

Open an API log file to extract information from the contents.

This function opens an API log file that is created with the StartApiLog function. The StopApiLog function must first be called to close the file.

Remark

See also

Extracting the API Log Information

Parameters:

pPath – [in] The absolute or relative file path of the API log file to open.
ppFile – [out] A pointer to a FILE pointer that will return a pointer to a FILE object representing the opened file.

WMX3APIFUNC OpenApiLogFile(wchar_t *pPath, FILE **ppFile)

Open an API log file to extract information from the contents.

This function is a variation of OpenApiLogFile that accepts a wchar_t array for the file path string. Use this function when using Unicode character sets.

Remark

Parameters:

pPath – [in] The absolute or relative file path of the API log file to open.
ppFile – [out] A pointer to a FILE pointer that will return a pointer to a FILE object representing the opened file.

WMX3APIFUNC GetApiLogData(FILE *pFile, unsigned char *pDataBuff, unsigned int buffSize, ApiLogInfo *pApiLogInfo = NULL)

Extract the information of one API function call from the API log file.

This function extracts the information of one API function call from the API log file opened with the OpenApiLogFile function. The raw data can be converted to a string message with the ApiLogToString function that is defined in the module that defines the called API function.

Remark

For additional information, see the link under “See also” below.

See also

Extracting the API Log Information

Parameters:

pFile – [in] A pointer to a FILE object that represents the opened API log file.
pDataBuff – [in] A pointer to a char buffer that contains the extracted raw data.
buffSize – [in] The size of the buffer pointed by pDataBuff in units of bytes.
pApiLogInfo – [out] An optional argument that is a pointer to an ApiLogInfo class object that returns additional information regarding the API function call data.

WMX3APIFUNC CloseApiLogFile(FILE *pFile)

Close an API log file.

This function closes an API log file that has been opened with the OpenApiLogFile function.

Remark

Parameters:: pFile – [in] A pointer to a FILE object that represents the opened API log file.

Public Static Functions

static WMX3APIFUNC ErrorToString(int errCode, char *pString, unsigned int size)

Get a string representation of the specified error code.

This function returns a string representation of the specified error code. The error code must be defined in the LogErrorCode enum or the ErrorCode enum in the WMX3Api.h header. All errors returned by functions in class Log will be defined in one of these enums. Errors returned by functions in other classes may not be defined in one of these enums, and when such errors are passed to this function, an ErrorCodeNotDefined error will be returned and pString will contain the string representation of this error.

Remark

If pString is too small to contain the entire string representation of the error code, pString will be set to an empty string. An array size of 256 characters will be enough to hold all string representations.

This function is static, and may be called without declaring an instance of the Log class or creating a device.

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A char array that will contain the string representation of the error.
size – [in] The size of the char array in number of characters.

static WMX3APIFUNC ErrorToString(int errCode, wchar_t *pString, unsigned int size)

Get a string representation of the specified error code.

This function is a variation of ErrorToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A wchar_t array that will contain the string representation of the error.
size – [in] The size of the wchar_t array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, char *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function converts the raw data for one API function call that was extracted from the API log with the GetApiLogData function.

Remark

See also

Extracting the API Log Information

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the pLogData char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A char array that will contain the string representation of the raw data of the API log.
size – [in] The size of the pString char array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, wchar_t *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function is a variation of ApiLogToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

pLogData – [in] A char array containing the raw data.
logDataSize – [in] The size of the char array. This size must be equal to or greater than the size of the raw data.
pString – [out] A wchar_t array that will contain the string representation of the raw data of the API log.
size – [out] The size of the pString wchar_t array in number of characters.

static WMX3APIFUNC TimestampToString(long long timestamp, char *pString, unsigned int size)

Get a string representation of a timestamp.

The timestamp is the number 100-ns ticks since 1 January 1601 00:00:00 UTC.

Remark

The timestamp member of the ApiLogInfo class can be passed to this function.

The returned string will be in the format “YYYY-MM-DD HH:mm:SS.sss” (sss is the number of milliseconds) in the local system time.

Parameters:

timestamp – [in] The timestamp to convert to a string.
pString – [out] A char array that will contain the string representation of the timestamp.
size – [in] The size of the pString char array in number of characters.

static WMX3APIFUNC TimestampToString(long long timestamp, wchar_t *pString, unsigned int size)

Get a string representation of a timestamp.

This function is a variation of TimestampToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

timestamp – [in] The timestamp to convert to a string.
pString – [out] A wchar_t array that will contain the string representation of the timestamp.
size – [out] The size of the pString wchar_t array in number of characters.

static WMX3APIFUNC GetLibVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module library.

This function is static, and may be called without declaring an instance of this class or creating a device.

Remark

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.