Formatspezifikation

Diese Formatspezifikation wird von dem Funktionsbaustein FB_FormatString und der Funktion F_FormatArgToStr verwendet. Während bei dem Funktionsbaustein die Formatspezifikation über eine String-Eingangsvariable übergeben wird, geschieht es bei der Funktion über die einzelnen Funktionsparameter.

Die Formatspezifikation, welche die erforderlichen und optionalen Parameterfelder beinhaltet, hat folgende Form:

%[ ] [ ] [ . ] Flags Width Precision Type

Die einfachste Formatspezifikation beinhaltet nur das Prozentzeichen und das Typfeld ( z.B. %s). Alle Zeichen, die dem Prozentzeichen folgen werden bis zu dem Typfeld als Parameterfelder ausgewertet. Zeichen vor dem Prozentzeichen und hinter dem Typfeld werden in den Ausgabestring kopiert. Beim Auftreten von nicht identifizierbaren oder unzulässigen Zeichen wird die Formatierung mit einem Fehler abgebrochen. Um das Prozentzeichen in dem Ausgabestring auszugeben benutzen Sie zwei nacheinander folgende Prozentzeichen (%%)

Type

Ein erforderliches Parameterfeld. Es ist ein ASCII-Zeichen (Character), welches bestimmt, ob das dazugehörige Argument als String, Integer oder Fließkommazahl interpretiert wird. Bitte beachten Sie dass einige der Typfeld-Parameter "case-sensitive" sind.

Typ	Argument	Ausgabe
b, B	BYTE, WORD, DWORD, REAL, SINT, INT, *DINT, USINT, UINT, UDINT	Binärstring ( z.B.: '101010111000' ).
o, O	BYTE, WORD, DWORD, REAL, SINT, INT, *DINT, USINT, UINT, UDINT	Oktalstring.
u, U	BYTE, WORD, DWORD, SINT, INT, **DINT, USINT, UINT, UDINT	Dezimalstring ohne Vorzeichen.
c, C	BYTE, USINT	Einzelner (ASCII) Byte-Character.
f, F	***REAL, LREAL	Fließkommazahl. Der String hat die Form: [ – ]dddd.dddd, (dddd sind Dezimalzahlen). Die Anzahl der Zahlen vor dem Dezimalpunkt hängt von dem Wert der Fließkommazahl ab. Die Anzahl der Zahlen hinter dem Dezimalpunkt hängt von der geforderten Präzision ab. Ein Vorzeichen erscheint nur bei negativen Werten. Bei einem unendlichen positiven Wert wird '#INF' und bei unendlichem negativen Wert: '-#INF' zurückgeliefert. Wenn die übergebene Variable einen unzulässigen Wert besitzt (NaN, Not-a-Number), dann wird '#QNAN' oder '-#QNAN' zurückgeliefert. Wenn die Länge des formatierten Strings die maximal zulässige Länge des resultierenden Strings überschreitet, dann wird '#OVF' oder '-#OVF' zurückgeliefert.
d, D	BYTE, WORD, DWORD, SINT, INT, DINT, USINT, UINT, UDINT	Dezimalstring. Ein Vorzeichen erscheint nur bei negativen Werten.
s, S	STRING	Single-byte–character string. Zeichen werden ausgegeben bis zur abschließenden Null oder bis der Parameter precision erreicht wurde.
X	BYTE, WORD, DWORD, REAL, SINT, INT, *DINT, USINT, UINT, UDINT	Hexadezimalstring. Für die Formatierung werden die (upper-case) Zeichen benutzt ('ABCDEF').
x	BYTE, WORD, DWORD, REAL, SINT, INT, *DINT, USINT, UINT, UDINT	Hexadezimalstring. Für die Formatierung werden die (lower-case) Zeichen benutzt ('abcdef').
E	Not implemented. Reserved for future use!.	Fließkommazahlen in der wissenschaftlichen Notation.
e	Not implemented. Reserved for future use!.	Fließkommazahlen in der wissenschaftlichen Notation.

* Es wird der Speicherinhalt der REAL-Variable als Binärstring-, Oktalstring, Hexadezimalstring oder Dezimalstring ausgegeben.

** Es wird der Speicherinhalt der vorzeichenbehafteten Typen als Binärstring-, Oktalstring, Hexadezimalstring oder Dezimalstring ausgegeben.

*** Die REAL-Variable wird in den LREAL-Typ konvertiert und dann formatiert.

Flags

Optionales Parameterfeld. Es können eins oder mehrere Flags in einer beliebigen Reihenfolge bestimmt werden. Diese Parameter bestimmen die Ausrichtung des formatierten Wertes, Ausgabe von Vorzeichen, Leerzeichen und der Binär-/Oktal-/Hex-Prefixe.

Flag	Bedeutung	Type	Standard
-	Linksausrichtungs-Flag. Linksausrichtung des formatierten Wertes innerhalb der vorgegebenen Breite im Parameter: Width.	Kann in Verbindung mit allen Typen benutzt werden.	Rechtsausrichtung.
+	Vorzeichen-Flag. Erzwingt die Ausgabe des positiven Vorzeichens bei vorzeichenbehafteten positiven Zahlen.	Nur in Verbindung mit e, E, f, F, d,D, sonst wird das Flag ignoriert.	Das negative Vorzeichen erscheint nur bei negativen Werten.
0	Null-Flag. Wenn dieses Flag dem Width-Parameter vorangestellt wurde, wird der resultierende String von Links mit Nullen aufgefüllt bis die gewünschte Breite erreicht wurde.	Nur in Verbindung mit e, E, f, F, s, S, sonst wird das Flag ignoriert. Das Null-Flag wird auch ignoriert wenn zusätzlich auch das Linksausrichtungs-Flag (-) gesetzt wurde.	Kein Auffüllen mit Nullen.
Leerzeichen (' ')	Leerzeichen-Flag. Ein Leerzeichen wird einem positiven Wert vorangestellt	Nur in Verbindung mit e, E, f, F, d, D, sonst wird das Flag ignoriert. Das Leerzeichen-Flag wird auch ignoriert wenn gleichzeitig auch das Vorzeichen-Flag (+) gesetzt wurde	Kein Leerzeichen.
#	Prefix-Flag. Dem formatierten Wert wird ein "IEC" oder "Standard C" Prefix vorangestellt. "IEC"-Prefixe: 2#, 8#, 16# (default) "Standard C"-Prefixe: 0, 0x, 0X	Nur in Verbindung mit b, B, o, O, x, X, sonst wird das Flag ignoriert. Der "Standard-C"-Prefix-Typ kann durch das Setzen der globalen Variablen GLOBAL_FORMAT_HASH_PREFIX_TYPE im Programm aktiviert werden: GLOBAL_FORMAT_HASH_PREFIX_TYPE := HASHPREFIX_STDC;	Kein Prefix.

Width

Optionales Parameterfeld. Dieser Parameter muss einen positiven dezimalen Wert haben. Er bestimmt die minimale Anzahl der ausgegebenen Zeichen im Ausgabestring. Es werden Leerzeichen (Links oder Rechts, abhängig von dem Ausrichtungs-Flag) dem Ausgabestring hinzugefügt, bis die gewünschte Breite erreicht wurde. Wenn das Null-Flag dem Width-Parameter vorangestellt wurde, wird der resultierende String von Links mit Nullen aufgefüllt, bis die gewünschte Breite erreicht wurde. Der Ausgabestring wird niemals durch den Width-Parameter auf die gewünschte Länge abgeschnitten!

Für den Width-Parameter kann auch ein Sternchen (*) angegeben werden. Der benötigte Wert wird dann von einem Argument geliefert (zulässige Typen: BYTE, WORD, DWORD, USINT, UINT, UDINT). Dem Argument für den Width-Parameter folgt dann das Argument für den zu formatierenden Wert.

Precision

Optionales Parameterfeld. Dieser Parameter folgt nach dem Punkt (.) und muss einen positiven dezimalen Wert besitzen. Folgt dem Punkt kein Wert, dann wird für die Präzision der Standardwert genommen (siehe Tabelle).

Typ	Bedeutung	Standard
b, B, o, O, u, U, x, X, d, D	Der Präzisionsparameter legt fest, wie viele Dezimalzeichen (digits) in dem Ausgabestring ausgegeben werden. Bei fehlenden Zeichen wird von Links mit Nullen aufgefüllt. Der Ausgabestring wird aber niemals abgeschnitten.	Standard: 1
c, C	Hat keine Bedeutung und wird ignoriert.	Ein Zeichen wird ausgegeben.
f, F	Der Präzisionsparameter legt die Anzahl der Nachkommastellen fest. Der Argument-Wert wird immer auf die entsprechende Anzahl der Nachkommastellen gerundet.	Standard: 6 Nachkommastellen
s, S	Der Präzisionsparameter legt fest, wie viele Zeichen aus dem Argument-String ausgegeben werden. Zeichen, die den Präzisionswert überschreiten werden nicht ausgegeben.	Es werden alle Zeichen bis zur abschließenden Null ausgegeben.

Für den Precision-Parameter kann auch ein Sternchen (*) angegeben werden. Der benötigte Wert wird dann von einem Argument geliefert (zulässige Typen: BYTE, WORD, DWORD, USINT, UINT, UDINT). Dem Argument für den Precision-Parameter folgt dann das Argument für den zu formatierenden Wert.

Voraussetzungen

Entwicklungsumgebung	Zielplattform	Einzubindende SPS Bibliotheken
TwinCAT v2.9.0 Build >1021	PC or CX (x86)	TcUtilities.Lib
TwinCAT v2.10.0 Build >= 1301	CX (ARM)	TcUtilities.Lib