FB_CMA_BufferConverting

Kopiert Daten von einem MultiArray zu einem anderen MultiArray.

Falls der definierte Eingangspuffer eines Algorithmus-Funktionsbausteins nicht mit dem Ausgangspuffer des vorhergehenden Funktionsbausteins der Analysekette übereinstimmt, kann mit dieser Funktionalität die Übergabe erreicht werden. Eine unterschiedliche Anzahl von Dimensionen kann entsprechend konvertiert werden.

Ebenfalls bietet sich die Möglichkeit nur eine Teilmenge der Daten weiterzuverarbeiten, um beispielsweise nur relevante Frequenzbereiche eines Spektrums zu berücksichtigen.

Ein- und Ausgänge

Die Ein- und Ausgangspuffer entsprechen einer der folgenden Definitionen (input / output shape). Die variablen Parameter sind Teil des Bausteineingangs stInitPars.

MultiArray im	Elementtyp	Dimensionen	Dimensionsgrößen
output stream	eTypeCode	`nDims`	`aDimSizes`

Eingangsparameter

Die Eingangsparameter dieses Bausteins repräsentieren Initialisierungsparameter und müssen bereits bei der Deklaration der FB Instanz zugewiesen werden! (Alternativ: Init()-Methode). Sie dürfen nur einmalig zugewiesen werden. Eine Änderung zur Laufzeit ist nicht möglich.

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

stInitPars: Baustein-spezifische Struktur mit Initialisierungsparametern vom Typ ST_MA_MultiArray_InitPars. Die Parameter müssen mit der obigen Definition der Ein- und Ausgangspuffer übereinstimmen.
nOwnID: Identifiziert die Bausteininstanz mit einer eindeutigen ID. Diese muss immer größer als null sein. Eine bewährte Vorgehensweise ist die Definition einer Enumeration für diesen Zweck.
aDestIDs: Legt die Ziele durch Angabe derer IDs fest, zu denen die Ergebnisse weitergeleitet werden sollen. Die Definition des Ausgangspuffers (wie oben beschrieben) muss mit der Definition des Eingangspuffers jedes gewählten Zieles übereinstimmen.
nResultBuffers: Der Funktionsbaustein initialisiert einen Transfer Tray Stream mit der gegebenen Anzahl an MultiArray Puffern. Der Defaultwert ist vier.
tTransferTimeout: Einstellung des synchronen Timeout für interne MultiArray Weiterleitungen. Siehe Kapitel Parallelverarbeitung.

Ausgangsparameter

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: Der Ausgang ist TRUE, falls ein Fehler auftritt.
hrErrorCode: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
ipErrorMessage: Beinhaltet nähere Informationen zum aktuellen Rückgabewert. Siehe hierzu den Abschnitt Fehlerbeschreibung und Information. Für diesen speziellen Schnittstellenzeiger ist intern sichergestellt, dass er immer gültig/zugewiesen ist.

Methoden

Copy1D():

Kopiert eindimensionale Daten von einem MultiArray zu einem anderen 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: Falls das Eingangs-Multiarray mehrdimensional ist, kann die Dimension gewählt werden, dessen Daten kopiert werden sollen. Hierbei wäre die erste Dimension mit 0 anzugeben (0 basierend).
nWorkDimOut: Falls das Ausgangs-Multiarray mehrdimensional ist, kann die Dimension gewählt werden, auf welche die Daten kopiert werden sollen. Hierbei wäre die erste Dimension mit 0 anzugeben (0 basierend).
nElements: Um die vollständigen Daten einer Multiarray-Dimension zu kopieren, kann dieser Parameter auf 0 gesetzt werden. Die Gesamtanzahl wird in dem Fall intern ermittelt. Alternativ kann hier die Anzahl der zu kopierenden Elemente angegeben werden.
bError: Der Ausgang ist TRUE, falls ein Fehler auftritt.
hrErrorCode: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert. Dieser Ausgang ist identisch zum Rückgabewert der Methode.

	Falls ein Timeout eintritt oder kein MultiArray Puffer für das Ergebnis verfügbar ist, so gehen weder die Eingangsdaten noch die Ergebnisdaten verloren. Sie werden beim nächsten Aufruf weitergeleitet.

Transpose():

Transponiert zwei Dimensionen, sodass der Ausgangspuffer das Transponierte des Eingangspuffers ist. Diese Operation ist nur für ein- und zweidimensionale Eingangspuffer möglich.

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: Der Ausgang ist TRUE, jedes Mal, wenn ein Ausgangs-MultiArray berechnet und an das TransferTray gesendet wurde.
bError: Der Ausgang ist TRUE, falls ein Fehler auftritt.
hrErrorCode: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert. Dieser Ausgang ist identisch zum Rückgabewert der Methode.

	Falls ein Timeout eintritt oder kein MultiArray Puffer für das Ergebnis verfügbar ist, so gehen weder die Eingangsdaten noch die Ergebnisdaten verloren. Sie werden beim nächsten Aufruf weitergeleitet.

Init():

Üblicherweise ist diese Methode in einer Condition Monitoring Applikation nicht notwendig. Sie bietet eine Alternative zur Bausteininitialisierung. Die Init() Methode darf nur während der Initialisierungsphase der SPS aufgerufen werden. Sie kann nicht während der Laufzeit verwendet werden. Es sei auf die Verwendung von einer FB_init Methode oder dem Attribut 'call_after_init' hingewiesen (siehe TwinCAT SPS Referenz). Hiermit wird zudem die Bausteinkapselung erleichtert.

Die Eingangsparameter der Bausteininstanz dürfen nicht bei der Deklaration zugewiesen werden, falls die Initialisierung mit der Init() Methode erfolgen soll.

Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.

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

stInitPars: Baustein-spezifische Struktur mit Initialisierungsparametern vom Typ ST_MA_MultiArray_InitPars. Die Parameter müssen mit der obigen Definition der Ein- und Ausgangspuffer übereinstimmen.
nOwnID: Identifiziert die Bausteininstanz mit einer eindeutigen ID. Diese muss immer größer als null sein. Eine bewährte Vorgehensweise ist die Definition einer Enumeration für diesen Zweck.
aDestIDs: Legt die Ziele durch Angabe derer IDs fest, zu denen die Ergebnisse weitergeleitet werden sollen. Die Definition des Ausgangspuffers (wie oben beschrieben) muss mit der Definition des Eingangspuffers jedes gewählten Zieles übereinstimmen.
nResultBuffers: Der Funktionsbaustein initialisiert einen Transfer Tray Stream mit der gegebenen Anzahl an MultiArray Puffern. Der Defaultwert ist vier.

PassInputs():

Solange eine FB_CMA_Source Instanz aufgerufen wird und somit Signaldaten zu einem Zielblock übertragen werden, müssen wie in der API SPS Referenz erläutert alle weiteren Blöcke der Analysekette zyklisch aufgerufen werden.
Manchmal ist es sinnvoll, einen Algorithmus für eine bestimmte Zeit nicht auszuführen. Beispielsweise sollten manche Algorithmen nur nach vorherigem Training bzw. Konfiguration ausgeführt werden. Zwar muss der Funktionsbaustein dennoch zyklisch aufgerufen werden, aber es ist ausreichend, wenn die am Baustein ankommenden Daten im Kommunikationsring weitergeleitet werden. Dies geschieht mittels der Methode PassInputs() anstelle der Methode Call(). Hierbei wird der Algorithmus selbst nicht aufgerufen und entsprechend kein Ergebnis berechnet sowie kein Ausgangspuffer generiert.

Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.

METHOD PassInputs : HRESULT
VAR_INPUT
END_VAR

Voraussetzungen

Entwicklungsumgebung	Zielplattform	Einzubindende SPS-Bibliotheken
TwinCAT v3.1.4022.25	PC or CX (x86, x64)	Tc3_CM, Tc3_CM_Base, Tc3_MultiArray