• Home
• Funktionen/Funktionsbausteine - Referenz
• Erweiterte Funktionen und Funktionsbausteine
• Datenverarbeitung
• STRING_COPY

STRING_COPY

Typ	Funktion
Beschreibung	Kopiert jedes Zeichen eines Eingangsstrings (STRING- oder WSTRING-Datentyp) bitweise in einen Puffer (beliebiges Array, typischerweise ein Byte-Array). Der Array-Index, ab dem das erste Zeichen des Eingangsstrings kopiert werden soll, wird mit dem Parameter BUF_OFF vorgegeben. Dieser Parameter bestimmt den Byte-Offset im Puffer. Der Offset wird wie folgt berechnet:         BUF_OFF = Array-Index, ab dem kopiert werden soll x Größe in Bytes, die jedes Array-Element belegt Beispiel: In einem Array aus DINT-Elementen (jedes Element belegt 4 Bytes) soll ab Array-Index [3] kopiert werden. BUF_OFF muss in diesem Fall auf den folgenden Wert gesetzt werden (siehe auch nachfolgende Beispiele):         MyArray : ARRAY[0..5] OF DINT;         BUF_OFF = 3 x SIZEOF(DINT) = 3 x 4 = 12
Hinweise	Stellen Sie sicher, dass die Länge des Puffers (BUFFER) beginnend bei BUF_OFF größer/gleich dem Wert an CNT ist, andernfalls wird nicht kopiert. Die Funktion liefert dann den Wert FALSE. Wenn der am Eingang IN anliegende String weniger Zeichen enthält als für CNT angegeben, werden keine Zeichen in das Array kopiert. Die Funktion liefert den Wert FALSE zurück. Das Endezeichen \0 in Zeichenfolgen wird nicht kopiert. Es werden nur die Zeichen in das Array geschrieben. Die Eingangsparameter IN, BUFFER und CNT müssen zusammenpassen, um die Funktion korrekt auszuführen und den gesamten Eingangsstring in den Puffer zu kopieren. Einzelne Zeichen des Eingangsstrings werden in folgenden Fällen abgeschnitten und nicht in den Puffer kopiert: Der am Eingang IN anliegende String enthält mehr Zeichen als für CNT angegeben. Die Funktion liefert den Wert TRUE. Die Anzahl der Zeichen (am Eingang CNT vorgegeben) des Eingangsstrings wird in das Array kopiert. Die Größe der Array-Elemente (beginnend bei BUF_OFF) ist kleiner als CNT; die Funktion liefert den Wert FALSE. Es werden keine Zeichen in das Array kopiert. Beachten Sie beim Kopieren eines Puffers mit STRUCTs die Startadresse. Eine Struktur kann bedingt durch das Alignment (Ausrichtung) Padding-Bytes (Füllbytes) enthalten, die auch geschrieben werden. Die Funktion SIZEOF berücksichtigt diese Padding-Bytes nicht bei der Berechnung der Anzahl an Bytes, die durch die STRUCT-Elemente belegt sind. Diese Funktion sollten Sie nur verwenden, wenn ein Array benötigt wird. In allen anderen Fällen sollten Sie die Funktion GET_CHAR einsetzen.
Parameter	Eingänge IN Datentyp: ANY_STRING Beschreibung: Zu kopierender Eingangsstring. BUFFER Datentyp: ANY Beschreibung: Array, Struktur oder String, in das der Eingangsstring kopiert wird. Das erste Zeichen des Eingangsstrings wird in das erste Array-Element kopiert. BUF_OFF Datentyp: ANY_INT Beschreibung: Byte-Offset im BUFFER, ab dem das erste Zeichen des Eingangsstrings kopiert werden soll. CNT Datentyp: ANY_INT Beschreibung: Anzahl der Zeichen, die in den BUFFER kopiert werden sollen. Ausgang OUT Datentyp: BOOL Beschreibung: Anzeige, ob der Eingangsstring erfolgreich kopiert wurde. TRUE: Eingangsstring erfolgreich kopiert. FALSE: Eingangsstring nicht erfolgreich kopiert.
Fehlerverhalten	Fehlerverhalten Die folgende Tabelle zeigt die Fehler, die bei der Ausführung der Funktion auftreten können, und den von der Funktion im entsprechenden Fehlerfall zurückgegebenen Wert. Fehlerfall Ausgabewert CNT < 0 FALSE CNT > len(IN) (len(...) = aktuelle Länge der Zeichenfolge) FALSE CNT > INT_MAX FALSE BUF_OFF < 0 FALSE BUF_OFF + CNT > sizeof(BUFFER) FALSE Wenn einer der ausgeführten Fehler auftritt, behält BUFFER seinen letzten Wert.
Zusätzliche Informationen	EN/ENO-Verhalten Die POE wird nur dann ausgeführt, wenn TRUE am Eingang EN anliegt. Wenn EN = FALSE ist, wird die POE nicht ausgeführt und ENO auf FALSE gesetzt (FU/FB inaktiv). Wenn bei der Ausführung der Funktion einer der unter "Fehlerverhalten" aufgeführten Fehler auftritt, wird ENO auf FALSE gesetzt. Weitere Infos Weitere Informationen finden Sie im Thema "Allgemeine Informationen zur Ausführungssteuerung mit EN/ENO".
Beispiele	Beispiele in ST Beispiel 1 Im folgenden Beispiel werden sechs Zeichen (CNT = UDINT#6) des Eingangsstrings 'MyTextString' in die Array-Variable My_Int_Array (INT-Array mit 10 Elementen) kopiert. Das Kopieren des ersten Zeichens des Eingangsstrings startet bei Array-Index [2] (BUF_OFF = 2 x SIZEOF(INT) = 4). Datentyp-Deklaration:    TYPE          MyArray : ARRAY[0..10] OF INT;    END_TYPE 'Variablen'-Tabelle mit Deklarationen: Code in ST:    /* STRING_COPY(IN:STRING, BUFFER:ANY, BUF_OFF:ANY_INT, CNT:ANY_INT) */    Out := STRING_COPY(MyString, My_Int_Array, UDINT#4, UDINT#6); Ergebnis (Anzeige im WATCH-FENSTER): Beispiel 2 Im folgenden Beispiel werden vier Zeichen (CNT = UDINT#4) des Eingangsstrings 'MyTextString' in die Array-Variable My_Byte_Array (INT-Array mit 10 Elementen) kopiert. Das Kopieren des ersten Zeichens 'M' (=16#4D) des Eingangsstrings startet ab Array-Index [3] (BUF_OFF = 3 x SIZEOF(BYTE) = 3). Das zweite Zeichen 'y' (=16#79) wird in das zweite Byte kopiert usw. Datentyp-Deklaration:    TYPE          MyArray1 : ARRAY[0..10] OF BYTE;    END_TYPE 'Variablen'-Tabelle mit Deklarationen: Code in ST:    /* STRING_COPY(IN:STRING, BUFFER:ANY, BUF_OFF:ANY_INT, CNT:ANY_INT) */    Out := STRING_COPY(MyString, My_Byte_Array, UDINT#3, UDINT#4); Ergebnis (Anzeige im WATCH-FENSTER):