Skip to main content

Libextext

Overview​

libextext has multiple built-in macro functions for formatting and outputting system time or tag values. Users can use these macro functions to format the required text templates.

This module can be used to output email and short message content in event management, or for other applications that need to forward text data, such as MQTT or HTTP forwarding.

Macro function overview​

Function itemFunction descriptionParameter descriptionfmt options
$localtime(fmt)Output local timefmt: Output format configuration%F,%T,%H, ……
$gmttime(fmt)Output Greenwich Mean Timefmt: Output format configuration%F,%T,%H, ……
$ctime(fmt)Output timestampfmt: Output format configurations,ms,sms
$tagLocalTime(tag_name,fmt)Output tag timestamp local timetag_name:tag name
fmt: Output format configuration		%F,%T,%H, ……
$tagGmtTime(tag_name,fmt)Output tag timestamp Greenwich Mean Timetag_name:tag name
fmt: output format configuration		%F,%T,%H, ……
$tagCTime(tag_name,fmt)Output tag timestamp valuetag_name:tag name
fmt: output format configuration		s,ms,sms
$tagName(tag_name)Output tag nametag_name:tag name---
$tagValue(tag_name,fmt)Output tag valuetag_name:tag name
fmt: output format configuration		%.1lf,%.2lf,%.3lf,%g
$tagQuality(tag_name)Output tag qualitytag_name:tag name---
$tagValueDescriptor(tag_name)Output tag value descriptiontag_name: tag name---
$tagDesc(tag_name)Output tag descriptiontag_name: tag name---
$MulTagBegin(tag_list)Multi-point processing template starting position, no output.tag_list: a list of tag names separated by commas, leaving it blank means using the entire point table in the project configuration---
$MulTagEnd(separator)Multi-point processing template end position, output the string specified by separatorseparator: separator, used to add to the middle of each tag output text block.---
$MulDevBegin(tag_list)Multi-device processing module starting position, no output.tag_list: a list of tag names separated by commas. Leaving it blank means using the entire point list in the project configuration.---
$MulDevEnd(separator)The end position of the multi-device processing module, outputs the string specified by separator.separator: a separator, used to be added to the middle of each device output text block.---
$MulVarBegin()The start position of the multi-variable processing module, no output.No parameters---
$MulVarEnd(separator)The end position of the multi-variable processing module, outputs the string specified by separator.separator: a separator, used to be added to the middle of each device output text block.---
$devName()Output device nameNo parameters---
$varName()Output variable nameNo parameters---
$varValue(@,fmt)Output variable corresponding to the tag valuefmt: Output format configuration%.1lf,%.2lf,%.3lf,%g
$varQuality()Output variable corresponding to the tag qualityNo parameters---
$varDesc()Output variable corresponding to the tag descriptionNo parameters---
$varValueDescriptor()Output variable corresponding to the tag value descriptionNo parameters---
$varLocalTime(@,fmt)Output variable corresponding to the tag timestamp local timefmt: Output format configuration%F,%T,%H, ……
$varGmtTime(@,fmt)Output variable corresponds to the Greenwich Mean Time of tag timestampfmt: Output format configuration%F,%T,%H, ……
$varCTime(@,fmt)Output variable corresponds to the value of tag timestampfmt: Output format configurations,ms,sms

Macro function details​

System time function​

$localtime(fmt), $gmttime(fmt) and $ctime(fmt) are three macro functions used to format the current system time into text. The output format is specified by the fmt parameter and supports the following parameter formats.

ParametersFormat descriptionOutput format
%aAbbreviated day of the weekwed
%AFull day of the weekWednesday
%bAbbreviated monthNov
%BFull monthNovember
%cStandard date and time stringWed Nov 11
13:59:53 2020
%CFirst two digits of the year20
%dDecimal day of the month20
%DMonth/day/year11/11/20
%eIn a two-character field,
Decimal day of the month		20
%FYear-Month-Day2020-11-11
%gLast two digits of the year,
using week-based year		20
%GYear, using week-based year2020
%hAbbreviated month nameNov
%HHour in 24-hour format14
%IHour in 12-hour format02
%jDecimal day of year316
%mDecimal month11
%MDecimal minute12
%nNewline---
%pLocal equivalent of AM or PMAM
%r12-hour time02:05:53 PM
%RHours and minutes as hh:mm14:06
%SDecimal seconds39
%tHorizontal tab---
%TDisplay hours, minutes, and seconds: hh:mm:ss14:05:36
%uDay of the week5
%UWeek of the year,
Sunday as first day		46
%VWeek of the year,
using week-based year		47
%wDay of the week as decimal3
%WWeek of the year, Monday as first day45
%xStandard date string11/11/20
%XStandard time string14:04:07
%yDecimal year without century20
%YDecimal year with century2020
%zTime zone name+0800
%ZTime zone abbreviationCST
%%Percent sign%

$localtime(fmt): Output local time​

fmt : Time output format parameter item, the default output format parameter is: %F %T (year month day hour minute second)
Result : Output local time in format
Example :

$localtime(%F %T) : 2020-11-10 17:07:15
$localtime(%T) : 17:07:15

$gmttime(fmt): Output Greenwich Mean Time​

fmt : Time output format parameter item, the default output format parameter is: %F %T (year month day hour minute second)
Result : Output GMT time in format
Example:

$gmttime(%F %T):2020-11-10 09:07:15
$gmttime(%F):2020-11-10

$ctime(fmt): Output timestamp​

fmt: Time output format parameter item, the default output format parameter is: sms (seconds and milliseconds)
Result: Output timestamp in format
Example:

$ctime(s):1604999235
$ctime(ms):291
$ctime(sms):1604999235291

Tag function​

$tagName(tag_name): Output tag name​

tag_name: tag name
Result: Output tag name
Example:

$tagName(tag_2):tag_2

$tagValue(tag_name，fmt): Output tag value​

tag_name: tag name
fmt: retain valid digits, retain 2 decimal places by default (%.2lf)
Separator: comma (,) is used as parameter separator between parameters
Result: Output the corresponding tag value, return: 0 if failed
Example:

$tagValue(tag_8,%.3lf):7.000
$tagValue(tag_9,%.9lf):8.000000
$tagValue(tag_10,%.g):9
$tagValue(tag_,%.2lf):0.00

$tagQuality(tag_name): Output tag quality​

tag_name: tag name
Result: Output tag quality, return if failed: 8080
Example:

$tagQuality(tag_2):0
$tagQuality(tag_):8080

$tagValueDescriptor(tag_name): Output tag description​

tag_name: tag name
Result: Output tag description information, return if failed: 0
Example:

$tagValueDescriptor(test:D1):111
$tagValueDescriptor(tag_): 0.00

$tagLocalTime(tag_name,fmt): Output tag local time​

tag_name: tag name
fmt: time output format parameter, default output format %F %T (year-month-day hour-minute-second)
delimiter: comma (,) is used as parameter delimiter between parameters
result: output tag local timestamp according to format parameter, return if failed: 1970-01-01 08:00:00
example:

$tagLocalTime(tag_9,%F %T):2020-11-10 17:07:16
$tagLocalTime(tag_9,%F):2020-11-10
$tagLocalTime(tag_,%F):1970-01-01 08:00:00

$tagGmtTime（tag_name，fmt）: Output tag Greenwich Mean Time​

tag_name: tag name
fmt: time output format parameter, default output format %F %T(year-month-day hour-minute-second)
delimiter: comma (,) is used as parameter delimiter between parameters
result: output tag GMT timestamp according to format parameter, return if failed: 1970-01-01 00:00:00
example:

$tagGmtTime(tag_9,%F %T):2020-11-10 09:07:16
$tagGmtTime(tag_9,%T):09:07:16
$tagGmtTime(tag_,%T): 1970-01-01 00:00:00

$tagCTime(tag_name，fmt): Output tag timestamp​

tag_name: tag name
fmt: timestamp output format parameter, default time format sms (seconds and milliseconds)
delimiter: comma (,) is used as parameter delimiter between parameters
result: output tag timestamp according to format parameter, return: 0 if failed
example:

$tagCTime(tag_9,s):1604999236
$tagCTime(tag_9,ms):211
$tagCTime(tag_9,sms):1604999236211
$tagCTime(tag_,s):0
$tagCTime(tag_,sms):000
$tagCTime(tag_,sms):0000

Multi-tag custom template function​

This function consists of $MulTagBegin(tag_1,tag_2,……), template, $MulTagEnd(separator), which correspond to the starting part, template part, and ending part respectively. Only when the input text successfully matches the starting part and the ending part can the template output defined by multiple tags be realized.

$MulTagBegin(tags) template $MulTagEnd(separator)​

tags: the name of the tag to be added, with comma (,) as the tag separator
Example: $MulTagBegin(tag_1,tag_2,……)

template: the template to be output for each tag, the template is customized by the user
Example: {“tagname”: $tagName(@)}, the @ character in the template will be replaced by the tag name

separator: template separator.
Example: $MulTagEnd(,), with comma (,) as the separator between tag templates

Multi-tag custom template example:

Input:

$MulTagBegin(tag_8,tag_2,tag_5)
{
$$gmttime(%F %T):$gmttime(%F %T),
$$tagName(@):$tagName(@)
}
$MulTagEnd(,)

Output:

{
    $gmttime(%F %T):2020-11-10 12:13:28,
    $tagName(@):tag_8
}
,
{
    $gmttime(%F %T):2020-11-10 12:13:28,
    $tagName(@):tag_2
}
,
{
    $gmttime(%F %T):2020-11-10 12:13:28,
    $tagName(@):tag_5
}

Sub-device model function​

The sub-device model is to divide the device name and variable name by : in the tag name to organize into structured text data, such as the content in the following format:

{
    "PLC1":{
        "Status":1,
        "PV":123
    },
    "PLC2":{
        "Status":0,
        "PV":456
    }
}

It can be composed by parsing the four tags PLC1:Status, PLC1:PV, PLC2:Status and PLC2:PV. The parsing rule is to separate the tag names with :, the one before : is the device name (devName), and the one after : is the variable name (varName).

The template used to generate the output of the above example is as follows:

{$MulDevBegin(PLC1:Status,PLC1:PV,PLC2:Status,PLC2:PV)
        "$devName()":{$MulVarBegin()
                "$varName()":$varValue(@,%.0lf)$MulVarEnd(,)
        }$MulDevEnd(,)
}

$devName(): Output device name​

This macro function has no parameters and must be parsed normally in a text block that starts with $MulDevBegin(tag_list) and ends with $MulDevEnd(separator).

Result: Output device name
Example:

$devName():PLC1

$varName(): Output variable name​

This macro function has no parameters and must be parsed normally in a text block starting with $MulVarBegin() and ending with $MulVarEnd(separator).

Result: Output variable name
Example:

$varName():Status

Other macro functions starting with $var​

The following macro functions starting with $var are the same as the corresponding macro functions starting with $tag except that the parameter of tag_name must be @, so I will not repeat them here.

  • $varValue(@,fmt)
  • $varQuality()
  • $varDesc()
  • $varLocalTime(@,fmt)
  • $varGmtTime(@,fmt)
  • $varCTime(@,fmt)

Sub-device model custom template example​

Let's take the four tags PLC1:Status, PLC1:PV, PLC2:Status and PLC2:PV as examples.

Example 1​

Template:

[
    $MulDevBegin(PLC1:Status,PLC1:PV,PLC2:Status,PLC2:PV)
    {
        "$devName()": {$MulVarBegin()
            "$varName()": $varValue(@,%.0lf)$MulVarEnd(,)
        }
    }$MulDevEnd(,)
]

Output:

[
    {
        "PLC1": {
            "Status": 1,
            "PV": 123
        }
    },
    {
        "PLC2": {
            "Status": 0,
            "PV": 456
        }
    }
]
Example 2​

Template:

[$MulDevBegin(PLC1:Status,PLC1:PV,PLC2:Status,PLC2:PV)
    {$MulVarBegin()
        "$devName()_$varName()": $varValue(@,%.0lf)$MulVarEnd(,)
    }$MulDevEnd(,)
]

Output:

[
    {
        "PLC1_Status": 1,
        "PLC1_PV": 1
    },
    {
        "PLC2_Status": 1,
        "PLC2_PV": 1
    }
]
Example 3​

Template:

[$MulDevBegin(PLC1:Status,PLC1:PV,PLC2:Status,PLC2:PV)
    {
        "device": "$devName()",
        "data": [$MulVarBegin()
            {
                "name": "$varName()",
                "value": $varValue(@,%.0lf)
            }$MulVarEnd(,)
        ]
    }$MulDevEnd(,)
]

Output:

[
    {
        "device": "PLC1",
        "data": [
            {
                "name": "Status",
                "value": 1
            },
            {
                "name": "PV",
                "value": 123
            }
        ]
    },
    {
        "device": "PLC2",
        "data": [
            {
                "name": "Status",
                "value": 0
            },
            {
                "name": "PV",
                "value": 456
            }
        ]
    }
]

On this page ...

Is this helpful?