# flag may alter the format, depending on the
converter (see below).
-The ' ' (space) and + flags print a space
-or a + sign before positive numbers, where negative
+The ' ' (space) and + flags usually print a
+space or a + sign before positive numbers, where negative
numbers would have a -.
+Some converters may redefine the meaning of these flags (see below).
-The 0 flag says that numbers should be left padded with
-0 if width is larger than required.
-
0 flag usually says that numbers should be left padded
+with 0 if width is larger than required.
+Some converters may redefine the meaning of this flag (see below).
-The - flag specifies that output is left justified if
-width is larger than required.
+The - flag usually specifies that output is left justified
+if width is larger than required.
+Some converters may redefine the meaning of this flag (see below).
The ? flag makes failing input conversions succeed with
@@ -90,31 +92,31 @@ This feature has been added by Klemen Vodopivec, SNS.
in "%f"; |
- float | +Read a float value |
out "%(HOPR)7.4f"; |
- the HOPR field as 7 char float with precision 4 | +Write the HOPR field as 7 char float with precision 4 |
out "%#010x"; |
- 0-padded 10 char alternate hex (with leading 0x) | +Write a 0-padded 10 char hex integer using the alternative format (with leading 0x) |
in "%[_a-zA-Z0-9]"; |
- string of chars out of a charset | +Read a string of alphanumerical chars or underscores |
in "%*i"; |
- skipped integer number | +Skip over an integer number |
in "%?d"; |
- decimal number or nothing (read as 0) | +Read a decimal number or if that fails pretend that value was 0 |
in "%=.3f"; |
- compare input to the current value formatted as a float with precision 3 | +Assure that the input is equal to the current value formatted as a float with precision 3 |
Every conversion character corresponds to one of the data types DOUBLE,
-LONG, ENUM, or STRING.
-In opposite to to printf() and scanf(), it is not
-required to specify a variable for the conversion.
+LONG, ULONG, ENUM, or STRING.
+In contrast to to the C functions printf() and scanf(),
+it is not required to specify a variable for the conversion.
The variable is typically the VAL or RVAL field
of the record, selected automatically depending on the data type.
Not all data types make sense for all record types.
@@ -141,23 +143,50 @@ exist in StreamDevice formats.
-To use other fields of the record or even fields of other records on the
-same IOC for the conversion, write the field name in parentheses directly
-after the %.
-For example out "%(EGU)s"; outputs the EGU
-field formatted as a string.
-Use in "%(otherrecord.RVAL)f"; to write the floating
-point input value into the RVAL field of
-otherrecord.
-If no field is given for an other record .VAL is assumed.
-When a record name conflicts with a field name use .VAL explicitly.
+To use formats with other than the default fields of a record or even with
+fields of other records on the same IOC, use the syntax
+%(record.FIELD).
+If only a field name but no record is given, the active record is assumed.
+If only a record name but no field name is given, the VAL
+field is assumed.
-This feature is very useful when one line of input contains many values that should
-be distributed to many records.
-If otherrecord is passive and the field has the PP
+Example 1: out "%(EGU)s"; outputs the
+EGU field of the active record.
+
+Example 2: in "%(otherrecord.RVAL)i";
+stores the received integer value in the RVAL field of the
+other record and then processes that record.
+The other record should probably use DTYP="Raw Soft Channel"
+in order to convert RVAL to VAL.
+
+Example 3: in "%(otherrecord)f";
+stores the received floating point value in the VAL field
+of the other record and then processes that record.
+The other record should probably use DTYP="Soft Channel".
+In the unlikely case that the name of the other record is the same as a field
+of the active record (e.g. if you name a record "DESC"), then use .VAL
+explicitly to refer to the record rather than the field of the active record.
+
+This feature is quite useful in the case that one line of input contains more
+than one value that need to be stored in multiple records or if one line of
+output needs to be contructed from values of multiple records.
+In order to avoid using full record names in the protocol file, it is recommended
+to pass the name or part of the name (e.g. the device prefix) of the other
+record as a protocol argument.
+In that case the redirection usually looks like this:
+in "%(\$1recordpart)f" and the record calls the protocol
+like this:
+field(INP, "@protocolfile protocol($(PREFIX)) $(PORT)")
+using a macro for the prefix part which is then used for \$1.
+
+If the other record is passive and the field has the PP attribute (see Record Reference Manual), the record will be processed. @@ -166,17 +195,20 @@ compatible to the the data type of the converter. STRING formats are compatible with arrays of CHAR or UCHAR.
-Note that using this syntax is by far not as efficient as using the
+Be aware that using this syntax is by far not as efficient as using the
default field.
-At the moment it is not possible to set otherrecord to an alarm
-state when anything fails.
+At the moment it is not possible to set the other record to an alarm
+state if anything fails. It will simply not be processed if the fault
+happens before or while handling it and it will already have been
+processed if the fault happens later.
Some formats are not actually converters.
They format data which is not stored in a record field, such as a
-checksum.
+checksum or
+regular expression substitution.
No data type corresponds to those pseudo-converters and the
%(FIELD) syntax cannot be used.
%d, %i,
+%d, %i,
%u, %o, %x, %X)
Output: %d and %i print signed decimal,
@@ -306,7 +338,8 @@ Unassigned strings increment their values by 1 as usual.
If one string is the initial substing of another, the substing must come
later to ensure correct matching.
-In particular if one string is the emptry string, it must be the last one.
+In particular if one string is the emptry string, it must be the last one
+because it always matches.
Use # and = to renumber if necessary.
@@ -323,14 +356,14 @@ a \ must be used to escape the character.
Output: Depending on the value, one of the strings is printed, -or the default if no value matches. +or the default if given and no value matches.
Input: If any of the strings matches, the value is set accordingly.
-%b, %Bzo)%b, %Bzo)This format prints or scans an unsigned integer represented as a binary string (one character per bit). @@ -360,7 +393,7 @@ one character.
-%r)%r)The raw converter does not really "convert". A signed or unsigned integer value is written or read in the internal @@ -405,7 +438,7 @@ The width must be 4 (float) or 8 (double). The default is 4.
-%D)%D)
Packed BCD is a format where each byte contains two binary coded
decimal digits (0 ... 9).