Promotic
Login logon

PmFormat object formatting string

Format of conversion between value and text string.

The formatting value can be of the following types:
- Float = real number (i.e. with a decimal point)
- Int = integer
- Bool = value true or false
- String = text string
- DateTime = date and time
- TimeSpan = time span (i.e. value does not contain month and year)
- Enum = numeric value representing text. (e.g. 1=Monday, 2=Tuesday, ..., 7=Sunday)


Parameters of a text string are in the KeyVal format, which is filled from the value of of the sFormat parameter of the SetFormat or CreatePmFormat method.

Keys common to all types:

Type:xx; - Value type. For example "Type:Float;".
Float (default) - real number
Int - integer
Bool - logical value (1/0)
String - text string
DateTime - Date and time
TimeSpan - Time span
Enum - Numeric value representing text.
Len:nn - The total number of characters excluding LTxt and RTxt. For example "Len:6;". For numeric values it is including Sign, DSep, Group.
See: Examples for Float type.
-1 (default) - unlimited, for Scan find end of a number
n - defined number of characters
IfShort:nn - What to do if the value is shorter than Len. For example "Len:4;IfShort:2;".
0 (default) - do nothing
1 - add space character from the left
2 - add space character from the right
7 - only for numeric values: add zeros from the left between the sign and the first digit (for non-numeric values like IfShort:1)
IfLong:nn - What to do if the value is longer than Len. For example "Len:4;IfLong:2;".
See: Examples for Float type.
0 (default) - do nothing, it means keep long
1 - crop from the left to length Len
2 - crop from the right to length Len
4 - fill with the character specified in IfLongPar to the length of Len
5 - replace with text defined in IfLongPar
7 - only for numeric values: scientific format max to IfLongPar (for non-numeric values like IfLong:2)
IfLongPar:ss - Specifies the character(s) to fill in for the IfLong parameter. For example "Len:4;IfLong:5;IfLongPar:MyErr;".
ss - Character(s)
for IfLong:4; - the character to fill with (default="", uses the asterisk "*" to fill)
for IfLong:5; - replacement text (default="")
IfNull:nn - What to do when the value is null. For example "IfNull:1;".
See: Examples for null:.
0 (default) - When converting a null value to a string, it will be converted to a 0 value or an empty string "" and then further converted according to the format string.
1 - When converting a null value to a string, a replacement string is used in IfNullPar and no further formatting occurs. When converting a string value back to a value, if the string value exactly matches the replacement string in IfNullPar, the result is null.
IfNullPar:ss - Substitute string for the null value (default=""). For example "IfNull:1;IfNullPar:null;".
LTxt:ss - Text to the left of the value For example "LTxt:Value ;".
See: The usage of Radix for formatting numbers into hexadecimal form.
RTxt:ss - Text to the right of the value (for Scan there must not be RTxt inside the value). For example "RTxt:°C;".
See: Examples for Float type.
Case:nn - Conversion to upper/lower case characters (characters in LTxt and RTxt are not converted). For example "Case:2;".
See: Examples for String type.
0 (default) - keep unchanged
1 - UpperCase - upper case characters
2 - LowerCase - lower case characters

Keys common to Int and Float:

Radix:nn - Other numeric system (for Int type). For example "Type:Int;Radix:16;".
See: The usage of Radix for formatting numbers into hexadecimal form.
2 - binary
8 - octal
10 (default) - decimal
16 - in hexadecimal. Hex characters will be small but can be enlarged using Case:1;
Sign:nn - How to to display the plus sign. For example "Sign:1;".
See: Examples for Float type.
0 (default) - do not display (display only "-")
1 - display "+" (if zero, then space)
2 - display " " (space)
Group:nn - Grouping groups of numbers into triples. For example "Group:1;".
See: Examples for Float type.
0 (default) - no grouping
1 - group to the left of the decimal separator (thousands)
2 - group to the right of the decimal separator (thousandths)
3 - group to the left and to the right of the decimal separator (thousands and thousandths)
GroupSep:nn - Separator between groups For example "Group:1;GroupSep:2;".
0 (default) - space
1 - dot
2 - comma
DLen:nn - Number of characters to the right of the decimal separator. For example "DLen:3;".
See: Examples for Float type.
-1 (default) - unlimited (filling up to the number specified in Len, but if Len=-1 then DLen:3)
n - integer including Group separator (3=default).
DSep:nn - Decimal point type (relevant only if DLen!=0). For example "DSep:1;".
0 (default) - period "."
1 - comma ","
DZero:nn - Zeros to the right of the number (relevant only if DLen!=0). For example "DZero:1;".
0 (default) - keep the zeroes
1 - replace zeroes by spaces
2 - Optimize (delete zeros and eventually also the decimal separator)

Keys for DateTime:

Formatting rule for date and time (DateTime) Formatting rule for time DateTime specifies the text (formatted) form of the time. A properly created formatting rule allows bidirectional conversion between a text representation and a value of the DateTime type without loss of information.
 
Formatting rule contains both constant items (e.g. separators inside time) and also individual time items. The time items can be in any order. Each time item (day, hour, minute, etc.) has an identifier (character: D, H, M, etc.).
 
The time entry in the formatting rule is indicated by the percentage sign %, thus distinguishing it from constant items (separators). This is followed by an optional number of digits (where the asterisk * char means the minimum required size with no zeros from the left, e.g., instead of 01.01. it would be 1.1.). The time entry is terminated with the mandatory time entry identifier.
 
Fmt:ss - Time format (default "%Y.%m.%d %H:%M:%S.%T"). For example "Type:DateTime;Fmt:%Y.%m.%d %H:%M:%S.%T;".
See: Examples for DateTime type.
 
Syntax of one time item: %[*|1-9]id

Time items:
Y - year (e.g. 2025) [4 digits].
See the PmDateObject.GetYear method.
y - Only the last two digits of the year (e.g. 25) [2 digits].
m - month (1-12) [2 digits].
See the PmDateObject.GetMonth method.
d - day (1-31) [2 digits].
See the PmDateObject.GetDay method.
H - hour (0-23) [2 digits].
See the PmDateObject.GetHour method.
M - minute (0-59) [2 digits].
See the PmDateObject.GetMinute method.
S - second (0-59) [2 digits].
See the PmDateObject.GetSecond method.
T - millisecond (0-999) [3 digits].
The number of digits here means the precision after the decimal point, so 1=tenths, 2=hundredths, and 3=thousandths.
See the PmDateObject.GetMillisecond method.
D - day of year (1-366) [3 digits].
It works only for conversion the time (DateTime) to the text form.
See the PmDateObject.GetDayOfYear method.
Wi - week of year (1-53) [2 digits] according to ISO 8601.
It works only for conversion the time (DateTime) to the text form.
See the PmDateObject.GetWeekOfYear method.
ws - day of the week starting on Sunday (0-6) [1 digit].
It works only for conversion the time (DateTime) to the text form.
See the PmDateObject.GetWeekday method.
wm - day of the week starting on Monday (1-7) [1 digit] according to ISO 8601.
It works only for conversion the time (DateTime) to the text form.


Note! Items do not all have to be entered. But then the information is lost in the text form.
When converting back from text to DateTime it must not miss items from the date part (year, month, day). Other missing items are considered to be 0.

Keys for TimeSpan

Formatting rule for the time span (TimeSpan) specifies the text (formatted) form of time span. A properly created formatting rule allows bidirectional conversion between a text expression and a value of the TimeSpan type without loss of information.
 
Formatting rule contains both constant items (e.g. separators inside the time span) and also individual time span items. The time span items must be in a mandatory order from the largest item (day) to the smallest item (millisecond). Each time span item (day, hour, minute, etc.) has its own identifier (character: D, H, M, etc.).
 
The time span item in the formatting rule is indicated by the percentage sign %, this distinguishes it from constant items (separators). This is followed by an optional number of characters (where the asterisk * char means the minimum required size with no zeros from the left, e.g., instead of 01.01. it would be 1.1.). This is followed by the mandatory identifier of time span item.
 
Fmt:ss - User-defined format of time span (default "Fmt:%*N%*d-%H:%M:%S.%T"). Only for FmtType is 0. For example "Type:TimeSpan;FmtType:0;Fmt:%*N%*d-%H:%M:%S.%T;".
See: Examples for TimeSpan type.
 
Syntax of one time item %[*|1-9]id

Time span items:
N - How to to display the plus sign.
d - day (1-31) [2 digits].
H - hour (0-23) [2 digits].
M - minute (0-59) [2 digits].
S - second (0-59) [2 digits].
T - millisecond (0-999) [3 digits].
The number of digits here means the precision after the decimal point, so 1=tenths, 2=hundredths, and 3=thousandths.
FmtType:nn (optional) - Time span format type. For example "Type:TimeSpan;FmtType:10;".
See: Examples for TimeSpan type.
0 (default) - User-defined format of time span defined by formatting string. See Fmt key.
10 - System format of time span. The values of time span items used are listed along with a letter indicating the item type. Items with a null value are not shown.
Syntax: [-][Nd][Nh][Nm][Ns][Nt], where N is number and:
d - Number of days. For example 2d means 2 days or 1.5d means 36 hours.
h - Number of hours. For example 2h means 2 hours or 1.5h means 90 minutes.
m - Number of minutes. For example 2m means 2 minutes or 1.5m means 90 seconds.
s - Number seconds. For example 2s means 2 seconds or 1.5s means 1500 miliseconds.
t - Number of milliseconds. For example 10t means 10 miliseconds or 500t means 500 miliseconds.


Note! The order of time span items must be listed from the largest (day) to the smallest item (millisecond). However, it does not have to start with day, but with any of the other items. The first (largest) time span item found:
1) will be incremented by the recalculated missing higher items.
2) It will have: default number of characters = *, so as needed.
 
Note! Items of time span do not need be listed down to the smallest items either. It may end with any item. But then the information is lost in the text form. When converting back from text form to TimeSpan form, these missing items are considered to be 0.
 
Note! Formatting rule allows to set the user-defined format of time span. In addition, there is a system format of time span.

Keys for Enum

The formatting rule for Enum specifies, how the numeric value is to be converted to text that represents its intended meaning. For example 1=Monday, 2=Tuesday, ... , 7=Sunday.
This is what the conversion table between the numeric value in the data and the text with the meaning of the value for displaying is for.
Rows:{keyval} - Conversion table in the form of an array (PmArray) of rows (PmMap). A row (map) is made of a pair of numeric value (v) and text (n).
KeyVal - saving format of named values (in pseudo-array mode) is used to write the conversion table.
For example "Rows:{0:{v:1;n=Monday};1:{v:2;n=Tuesday};2:{v:3;n=Wednesday};3:{v:4;n=Thursday};4:{v:5;n=Friday};5:{v:6;n=Saturday};6:{v:7;n=Sunday};};".
See: Examples for Enum type:.

Other keys:

FmtC:ss - C language conversion format (obsolete way kept to maintain compatibility). Description see: C language formatting rule. For example "FmtC:%5.2f;".
See: The usage of FmtC for C language formatting:.

Examples for Float type

Combination of keys RTxt and DLen:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Float;RTxt: %;DLen:2;");
var sVal = oFmt.Format(90.845);   // sVal = "90.84 %"
The usage of Group to split the number into digits triples:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Len:12;DLen:7;IfLong:2;Group:3;");
var sVal = oFmt.Format(-1234567.123456);   // sVal = "-1 234 567.1"
The usage of Sign to align plus and minus values:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Sign:2;");
var sVal;
sVal = oFmt.Format(1235.67);   // sVal = " 1235.670"
sVal = oFmt.Format(-1235.67);   // sVal = "-1235.670"

Examples for Int type

The usage of Radix for formatting numbers into hexadecimal form:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Int;Radix:16;LTxt:0x;Case:1;");
var sVal = oFmt.Format(10.58);   // sVal = "0xB"
var nVal = oFmt.Scan(sVal);   // nVal = 11
The usage of Radix for formatting numbers into octal form:
JavaScriptVBScriptSelect and copy to clipboard

oFmt = Pm.CreatePmFormat("Type:Int;Radix:8;LTxt:0o;");
sVal = oFmt.Format(10.58);   // sVal = "0o13"
nVal = oFmt.Scan(sVal);   // nVal = 11
The usage of Radix for formatting numbers into binary form:
JavaScriptVBScriptSelect and copy to clipboard

oFmt = Pm.CreatePmFormat("Type:Int;Radix:2;LTxt:0b;");
sVal = oFmt.Format(3.4);   // sVal = "0b11"
nVal = oFmt.Scan(sVal);   // nVal = 3

Examples for Bool type

Example1:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Bool;");
var sVal;
sVal = oFmt.Format(3.14);   // sVal = "1"
sVal = oFmt.Format(0);   // sVal = "0"
Example2:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Bool;LTxt:Ln;RTxt:V;");
var sVal;
sVal = oFmt.Format(true);   // sVal = "Ln1V"
sVal = oFmt.Format(false);   // sVal = "Ln0V"

Examples for String type

Example1:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:String;LTxt:x;RTxt:q;Case:1;");
var sVal = oFmt.Format("aBcD");   // sVal = "xABCDq"
Example2:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:String;LTxt:X_;RTxt:_Q;Len:6;IfLong:2;");
var sVal = oFmt.Format("abcdefgh");   // sVal = "X_abcdef_Q"

Examples for DateTime type

Example:
JavaScriptVBScriptSelect and copy to clipboard

var t = Pm.CreateDate(2025, 2, 13, 4, 15, 6, 789);

var oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%2d.%2m.%4Y %2H:%2M:%2S.%T;");
var sVal = oFmt.Format(t);   // sVal = "13.02.2025 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%2d.%2m.%4Y %2H:%2M:%2S;");
sVal = oFmt.Format(t);   // sVal = "13.02.2025 04:15:06"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%4Y.%2d.%2m %2H:%2M:%2S;");
sVal = oFmt.Format(t);   // sVal = "2025.13.02 04:15:06"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*d.%*m.%*Y %*H:%*M:%*S.%T;");
sVal = oFmt.Format(t);   // sVal = "13.2.2025 4:15:6.789"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*Y.%*m.%*d;");
sVal = oFmt.Format(t);   // sVal = "2025.13.2"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*H:%*M:%*S;");
sVal = oFmt.Format(t);   // sVal = "4:15:6"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%Y%m%d%H%M%S;");
sVal = oFmt.Format(t);   // sVal = "20251302041506"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%Y.%m.%d %H:%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "2025.2.13 4:15:6.789"

// this notation conforms to ISO 8601
oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%Y.%m.%d %HT%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "2025.2.13 4T15:6.789"

// notation in the form for the MS SQL database
oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:'%Y-%m-%d %H:%M:%S.%T';");
sVal = oFmt.Format(t);   // sVal = "'2025-2-13 4:15:6.789'"

// notation in the form for the MySQL database
oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:'%Y-%m-%d %H:%M:%S';");
sVal = oFmt.Format(t);   // sVal = "'2025-2-13 4:15:6'"

// notation in the form for the Oracle database
oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:TIMESTAMP'%Y-%m-%d %H:%M:%S.%T';");
sVal = oFmt.Format(t);   // sVal = "TIMESTAMP'2025-2-13 4:15:6.789'"

// notation in the form for the Microsoft Access, dBase, PARADOX databases on setting the direct access
oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:#%m %d %Y %H:%M:%S#;");
sVal = oFmt.Format(t);   // sVal = "#2 13 2025 4:15:6#"

Examples for TimeSpan type

Example:
JavaScriptVBScriptSelect and copy to clipboard

var t = Pm.CreateDate(0, 0, 53, 4, 15, 6, 789);

var oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%2d %2H:%2M:%2S.%T;");
var sVal = oFmt.Format(t);   // sVal = "53 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*d %*H:%*M:%*S;");
sVal = oFmt.Format(t);   // sVal = "53 4:15:6"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%H:%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "1276:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%N%2d %2H:%2M:%2S.%T;");
sVal = oFmt.Format(-t);   // sVal = "-53 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10");
sVal = oFmt.Format(-t);   // sVal = "-53d4h15m6s789t"

t = Pm.CreateDate(0, 0, 1053, 4, 15, 6, 789);

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%d-%H:%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "1053-04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%H:%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "25276:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "1516575:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%S.%T;");
sVal = oFmt.Format(t);   // sVal = "90994506.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10;");
sVal = oFmt.Format(t);   // sVal = "1053d4h15m6s789t"

t = Pm.CreateDate(0, 0, 0, 1, 30, 0, 0);

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%d-%H:%M:%S.%T;");
sVal = oFmt.Format(t);   // sVal = "0-01:30:00.000"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10;");
sVal = oFmt.Format(t);   // sVal = "1h30m"

Examples for Enum type:

Example:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Enum;Rows:{0:{v:1;n=Monday};1:{v:2;n=Tuesday};2:{v:3;n=Wednesday};3:{v:4;n=Thursday};4:{v:5;n=Friday};5:{v:6;n=Saturday};6:{v:7;n=Sunday};};");
var sVal;
sVal = oFmt.Format(2);   // sVal = "Tuesday"
sVal = oFmt.Format(6);   // sVal = "Saturday"

Examples for null:

Example:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Float;");
var sVal = oFmt.Format(null);   // sVal = "0.000"

var oFmt = Pm.CreatePmFormat("Type:Float;IfNull:1;");
var sVal = oFmt.Format(null);   // sVal = ""
var vVal = oFmt.Scan("");   // vVal = null

var oFmt = Pm.CreatePmFormat("Type:Float;IfNull:1;IfNullPar:null;");
var sVal = oFmt.Format(null);   // sVal = "null"
var vVal = oFmt.Scan("null");   // vVal = null

The usage of FmtC for C language formatting:

Example:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("FmtC:%d;");
var sVal = oFmt.Format(1);   // sVal = "1"

oFmt = Pm.CreatePmFormat("FmtC:x%dq;");
sVal = oFmt.Format(1);   // sVal = "x1q"

oFmt = Pm.CreatePmFormat("FmtC:%f;");
sVal = oFmt.Format(12.3456789);   // sVal = "12.3456789"

oFmt = Pm.CreatePmFormat("FmtC:%13.2f;");
sVal = oFmt.Format(123456789.123456789);   // sVal = " 123456789.12"

oFmt = Pm.CreatePmFormat("FmtC:%x");
sVal = oFmt.Format(255);   // sVal = "ff"

oFmt = Pm.CreatePmFormat("FmtC:%03X;");
sVal = oFmt.Format(10.58);   // sVal = "00B"

oFmt = Pm.CreatePmFormat("FmtC:n=%03X;");
sVal = oFmt.Format(10.58);   // sVal = "n=00B"
See also:
- Pm.CreatePmFormat (method)
- PmFormat.SetFormat (method)
History:
Pm9.00.32:
- New option "type:Enum;" allows entering the format for enumeration of values.
- New option IfNull:nn and IfNullPar:ss allows to enter a replacement string for the null value.
Pm9.00.26: New option FmtType allows entering the system format for TimeSpan.
Pm9.00.20:
- New option D = day of year.
- New option Wi = week of year.
- New option ws = day of the week (week starting on Sunday).
- New option wm = day of the week (week starting on Monday).
Pm9.00.17: Created
PROMOTIC 9.0.32 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.Update cookies preferences