FB_CMA_BufferConverting
Copies data from one MultiArray to another MultiArray.
If the defined input buffer of an algorithm function block does not match the output buffer of the preceding function block of the analysis chain, the transfer can be achieved with this functionality. A different number of dimensions can be converted accordingly.
Another option is to use only a subset of the data for further processing, for example in order to take into account only relevant frequency ranges of a spectrum.
Inputs and outputs
The input and output buffers correspond to one of the following definitions (input / output shape). The variable parameters are part of the function block input stInitPars
.
MultiArray in the | Element type | Dimensions | Dimensional variables |
---|---|---|---|
output stream | eTypeCode |
|
|
VAR_INPUT
stInitPars : ST_MA_MultiArray_InitPars; // init parameter
nOwnID : UDINT; // ID for this FB instance
aDestIDs : ARRAY[1..cCMA_MaxDest] OF UDINT; // IDs of destinations for output
nResultBuffers : UDINT := 4; // number of MultiArrays which should be initialized for results (0 for no initialization)
tTransferTimeout : LTIME := LTIME#500US; // timeout checking off during access to inter-task FIFOs
END_VAR
Input parameters
The input parameters of this function block represent initialization parameters and must already be assigned in the declaration of the FB instance! (Alternatively: Init() method). They may only be assigned once. A change at runtime is not possible.
stInitPars
: Function-block-specific structure with initialization parameters of the type ST_MA_MultiArray_InitPars. The parameters must correlate to the above definition of the input and output buffers.nOwnID
: Identifies the function block instance with a unique ID. This must always be greater than zero. A proven approach is to define an enumeration for this purpose.aDestIDs
: Defines the destinations to which the results are to be forwarded by specifying the IDs of the destinations. The definition of the output buffer (as described above) must correlate to the definition of the input buffer of each selected destination.nResultBuffers
: The function block initializes a Transfer Tray Stream with the specified number of MultiArray buffers. The default value is four.tTransferTimeout
: Setting of the synchronous timeout for internal MultiArray forwardings. See section Parallel processing.
Output parameters
VAR_OUTPUT
bError : BOOL; // TRUE if an error occurs. Reset by next method call.
hrErrorCode : HRESULT; // '< 0' = error; '> 0' = info; '0' = no error/info
ipErrorMessage : I_TcMessage := fbErrorMessage; // Shows detailed information about occurred errors, warnings and more.
nCntResults : ULINT; // Counts outgoing results (MultiArrays were calculated and sent to transfer tray).
END_VAR
-
bError
: The output isTRUE
if an error occurs. -
hrErrorCode
: If an error occurs, a corresponding error code of the typeHRESULT
is output. Possible values are described in the List of error codes. -
ipErrorMessage
: Contains more detailed information on the current return value. Refer here to the section Error description and information. This special interface pointer is internally secured so that it is always valid/assigned.
Methods
Copy1D():
Copies one-dimensional data from one MultiArray to another MultiArray.
METHOD Copy1D : HRESULT
VAR_INPUT
nWorkDimIn : UDINT; // It designates the dimension in the input MultiArray being processed.
nWorkDimOut : UDINT; // It designates the dimension in the output MultiArray being processed.
nElements : UDINT; // optional: default:0->full copy; It designates the number of elements to be copied out of the MultiArray.
pStartIndexIn : POINTER TO UDINT; (* optional: default:0->internally handled as [0,0,..]; It designates the index of the first element to be copied out of the MultiArray.
If allocated it must point to a onedimensional array of UDINT with so many elements as dimensions of the MultiArray. *)
pStartIndexOut : POINTER TO UDINT; (* optional: default:0->internally handled as [0,0,..]; It designates the index of the first MultiArray element to be copied.
If allocated it must point to a onedimensional array of UDINT with so many elements as dimensions of the MultiArray. *)
nOptionPars : DWORD; // option mask
END_VAR
VAR_OUTPUT
bNewResult : BOOL; // TRUE every time when outgoing MultiArray was calculated and sent to transfer tray.
bError : BOOL; // TRUE if an error occurs.
hrErrorCode : HRESULT; // '< 0' = error; '> 0' = info; '0' = no error/info
END_VAR
nWorkDimIn
: If the input MultiArray is multi-dimensional, you can select the dimension whose data you want to copy. The first dimension would be 0 (0-based).nWorkDimOut
: If the output MultiArray is multi-dimensional, you can select the dimension to which you want to copy data. The first dimension would be 0 (0-based).nElements
: To copy the complete data of a MultiArray dimension, this parameter can be set to 0. The total number is determined internally in this case. Alternatively, you can specify the number of elements to be copied.bError
: The output isTRUE
if an error occurs.hrErrorCode
: If an error occurs, a corresponding error code of the typeHRESULT
is output. Possible values are described in the List of error codes. This output is identical to the return value of the method.
If a timeout occurs or no MultiArray buffer is available for the result, then neither the input data nor the result data are lost. They are forwarded on the next call. |
Transpose():
Transposes two dimensions so that the output buffer is the transposition of the input buffer. This operation is only possible for one and two-dimensional input buffers.
METHOD Transpose : HRESULT
VAR_INPUT
nOptionPars : DWORD; // option mask
END_VAR
VAR_OUTPUT
bNewResult : BOOL; // TRUE every time when outgoing MultiArray was calculated and sent to transfer tray.
bError : BOOL; // TRUE if an error occurs.
hrErrorCode : HRESULT; // '< 0' = error; '> 0' = info; '0' = no error/info
END_VAR
bNewResult
: The output isTRUE
every time an output MultiArray is calculated and sent to the TransferTray.bError
: The output isTRUE
if an error occurs.hrErrorCode
: If an error occurs, a corresponding error code of the typeHRESULT
is output. Possible values are described in the List of error codes. This output is identical to the return value of the method.
If a timeout occurs or no MultiArray buffer is available for the result, then neither the input data nor the result data are lost. They are forwarded on the next call. |
METHOD Init : HRESULT
VAR_INPUT
stInitPars : ST_MA_MultiArray_InitPars; // init parameter
nOwnID : UDINT; // ID for this FB instance
aDestIDs : ARRAY[1..cCMA_MaxDest] OF UDINT; // IDs of destinations for output
nResultBuffers : UDINT := 4; // number of MultiArrays which should be initialized for results (0 for no initialization)
END_VAR
Init():
This method is not usually necessary in a Condition Monitoring application. It offers an alternative to the function block initialization. The Init()
method may only be called during the initialization phase of the PLC. It cannot be used at runtime. You are referred to the use of an FB_init
method or the attribute 'call_after_init'
(see TwinCAT PLC reference). In addition, this facilitates the function block encapsulation.
The input parameters of the function block instance may not be assigned in the declaration if the initialization is to take place using the Init() method.
- Return value: If an error occurs, a corresponding error code of the type
HRESULT
is output. Possible values are described in the List of error codes.
stInitPars
: Function-block-specific structure with initialization parameters of the type ST_MA_MultiArray_InitPars. The parameters must correlate to the above definition of the input and output buffers.nOwnID
: Identifies the function block instance with a unique ID. This must always be greater than zero. A proven approach is to define an enumeration for this purpose.aDestIDs
: Defines the destinations to which the results are to be forwarded by specifying the IDs of the destinations. The definition of the output buffer (as described above) must correlate to the definition of the input buffer of each selected destination.nResultBuffers
: The function block initializes a Transfer Tray Stream with the specified number of MultiArray buffers. The default value is four.
PassInputs():
As long as an FB_CMA_Source
instance is called and signal data are thus transferred to a target block, all further function blocks of the analysis chain have to be called cyclically as explained in the API PLC Reference.
Sometimes it is useful not to execute an algorithm for a certain time. For example, some algorithms should be executed only after prior training or configuration. The function block must be called cyclically, but it is sufficient for the data arriving at the function block to be forwarded in the communication ring. This is done using the PassInputs()
method in place of the Call()
method. The algorithm itself is not called here, and accordingly no result is calculated and no output buffer generated.
- Return value: If an error occurs, a corresponding error code of the type
HRESULT
is output. Possible values are described in the List of error codes.
METHOD PassInputs : HRESULT
VAR_INPUT
END_VAR
Requirements
Development environment | Target platform | PLC libraries to include |
---|---|---|
TwinCAT v3.1.4022.25 | PC or CX (x86, x64) | Tc3_CM, Tc3_CM_Base, Tc3_MultiArray |