Webtags/Parameters (preserving history): Difference between revisions
m (→Date formats) |
|||
(35 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Template:Version badge Mx}}{{Version badge 1}}This Wiki page applies to both flavours of Cumulus currently available. |
|||
=Introduction= |
=Introduction= |
||
Put simply, a [[Webtags|Cumulus tag]] is included to indicate where Cumulus should insert values when it [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes the command/file]] that quotes the tags. |
|||
This page is about parameters used for modifying Cumulus web tags. To put these into context, let us learn the terminology with cross-references to where those features are explained further. |
|||
The general format for every Cumulus tag is: <code><#tag_name [optional input selection parameters] [optional output modification parameters]></code> |
|||
==What is a web tag? == |
|||
{{TOCright}} |
|||
Put simply, a [[Webtags|web tag]] is included in a [[Cumulus template file]] to indicate where Cumulus should insert values when it [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes that template]] and produces an output file. A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags, and need to be processed before they actually include values. |
|||
This page is about those (generally optional) parameters used for modifying Cumulus tags. |
|||
The output file can be: |
|||
* a [[Customised_templates#HTML_5_-_a_very_quick_guide_to_structure|web page]], |
|||
* a [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript Object Notation (.json) file]] |
|||
* a [[Feels_Like#HTML_code_to_translate_web_tags_to_JavaScript_variables_.28as_modified_for_additional_parameters.29|JavaScript file]], |
|||
* a [[PHP]] script file, or |
|||
*a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file. |
|||
# An input parameter is used where the same tag name can represent a value for a number of different past time instants. |
|||
==General Format for Web Tags== |
|||
#* Each of those past time instants is represented by a different value for the input parameter. |
|||
#* So a combination of a tag name and input modification parameter lets Cumulus select the value you want to see. |
|||
#* Whether a particular tag name can use input modification parameters will depend on both which tag name has been chosen, and which Cumulus release you are using. |
|||
# An output parameter is used when a particular tag name can be fed through a process that alters how the output is shown |
|||
#* Tag names representing integer values cannot have their output format modified |
|||
#* Internally Cumulus handles numbers in binary, for numbers that have an integer and a decimal part, there is no exact conversion between the way the decimal part of a number is stored in binary, and the way the decimal part (after the decimal comma/point) appears on output. Therefore, non-integer numbers have to be rounded, and there are some output parameters that modify the output: |
|||
#*# You can modify the number of decimal places shown for some tag names |
|||
#*# With Cumulus MX, you can modify whether number is output with a decimal comma, or a decimal point |
|||
#* Tag names representing time intervals, clock times, [[meterological day|dates]] or representing both time/date for an extreme record, may have a fixed format that cannot be changed, or may be able to be processed through a date-time routine that changes how either time or date or both are output |
|||
In the position in the file where Cumulus is to insert the relevant data, place a web tag in the '''general format''' specified here: |
|||
All this parameter information was originally on [[Webtags]] page, but has been moved to this separate page as part of an attempt to make the Wiki easier to read by shortening pages. |
|||
<pre><#tag_name [optional input selection parameters] [optional output modification parameters]></pre> |
|||
==== Case sensitivity for tag names ==== |
|||
=Legacy software= |
|||
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [[Webtags|web tags page]]. |
|||
The legacy Cumulus 1 software can only use tag names, and whatever parameters are permitted, within a file. Steve Loft used [[Cumulus template file|'''Cumulus Template File''']] for a file that used tags: |
|||
== What is a web tag parameter?== |
|||
* The legacy Cumulus 1 software, and MX releases up to release 3.9.7 - build 3107, provided a selection of template files (see [[Customised templates]] that produced 'standard' web pages, see [[Cumulus.ini_(Cumulus_1)#Section:_FTP_site|"IncludeSTD" here]]. |
|||
* A Cumulus user could specify an alternative [[Customised_templates#HTML_5_-_a_very_quick_guide_to_structure|web page]], |
|||
* A Cumulus user could transfer data to a web server using a [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript Object Notation (.json) file]] |
|||
* A Cumulus user could transfer data to a web server using a [[Feels_Like#HTML_code_to_translate_web_tags_to_JavaScript_variables_.28as_modified_for_additional_parameters.29|JavaScript file]], |
|||
* A Cumulus user could transfer data to a web server using a [[PHP]] script file, or |
|||
* A Cumulus user could transfer data to a web server using a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file. |
|||
For information on how to process, and upload, non-standard files, see [[Cumulus.ini_(Cumulus_1)#Section:_FTP_site|"ExtraProcessxx"]]. |
|||
Now we get to the terminology for what this Wiki page will document. |
|||
=Cumulus MX software= |
|||
The parameters shown in the general format above are of two kinds: |
|||
*Input modifying |
|||
*Output modifying |
|||
MX can process template files, using [[Cumulus.ini#Extra_Web_Files|Extra web file settings]], but tag names (and input/output parameters as permitted) can also be used in: |
|||
These are explained below, after the warning on case sensitivity. |
|||
* standard [[websitedataT.json]] template file, or a tailored file that is processed into same destination file |
|||
* on demand using [[Cumulus_MX_Local_API|Cumulus MX Local API]] |
|||
* standard or custom interval use of [[Cumulus.ini#Optional_Structured_Query_Language_Settings|"My SQL Connector"]] |
|||
* Customised [[Cumulus.ini_(MX_3.0.0_to_3.7.0)#MQTT|MQTT]] commands |
|||
=Rules= |
|||
=== Case sensitivity for parameters === |
|||
Tag names and parameters must obey certain rules. |
|||
The optional input parameters always use lower case, so please type them exactly as shown in the sections dealing with input parameters on this page. |
|||
The optional output parameters are case insensitive when used in Cumulus 1. But for Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully. |
|||
== Case sensitivity for tag names == |
|||
= Input modification Parameters = |
|||
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in lists of tag names. |
|||
'''Most web tags do not require any input parameters'''. |
|||
== Case sensitivity for parameters == |
|||
* An input parameter is used where the same web tag can represent a value for a number of different past time instants. |
|||
* Each of those past time instants is represented by a different value for the input parameter. |
|||
The optional input modification parameters always use lower case, so please type them exactly as shown in the [[#Input modification Parameters|section below]]. |
|||
* So a combination of web tag name and input modification parameter lets Cumulus select the value you want to see. |
|||
* The web tags that can use input modification parameters will depend on which Cumulus release you are using |
|||
The content of optional output parameters are mostly case insensitive when used in legacy Cumulus 1 (a few are case sensitive as explained in [[#For the legacy software]]. For Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully. |
|||
* To supply both optional input modification, and optional output modification parameters, separate them with spaces, e.g. <#ByMonthTempHT mon=7 format=hh:nn>. In that example, the time only is returned for the highest ever temperature in July, after processing by Cumulus of the time-stamp web tag. |
|||
== Tag names and Parameters available== |
|||
=== Input modification Parameters === |
|||
'''Most web tags do not require any input parameters'''. Luckily, where they are needed, it is quite simple to use them, see table below. |
|||
{| class="wikitable" border="1" |
{| class="wikitable" border="1" |
||
|- |
|- |
||
!style="width: |
!style="width:15px" | Tag names |
||
!style="width:100px" | Values Available |
!style="width:100px" | Values Available |
||
!style="width: |
!style="width:200px" | Input Modification Parameters |
||
!style="width:60px" | Introduced |
!style="width:60px" | Introduced |
||
!style="width:500px" | Examples |
!style="width:500px" | Examples |
||
!style="width: |
!style="width:900px" | Description |
||
|- |
|- |
||
! scope="row"| Tag names listed at [[Webtags#Table of Recent History tag names available|'''Table of Recent History tag names available''']] (see [[Recent history]] page for explanation) |
|||
| [[Webtags#Recent_History|'''recent history tags''']] |
|||
| One value for each minute in last 7 days |
| One value for each minute in last 7 days |
||
| |
| * '''d''' specifies number of days ago, |
||
* '''h''' specifies number of hours ago, |
|||
* and '''m''' specifies number of minutes ago. |
|||
* You can use any combination of the three parameters. |
* You can use any combination of the three parameters. |
||
* The same d, h, and m, parameters are used by Cumulus 1 and MX. |
* The same d, h, and m, parameters are used by Cumulus 1 and MX. |
||
| Cumulus 1.9.3 beta build 1033 |
| Cumulus 1.9.3 beta build 1033 (remain available in MX) |
||
| Examples for outside temperature: |
| Examples for outside temperature: |
||
* <#RecentOutsideTemp m=1> will give the temperature one minute ago, <#RecentOutsideTemp h=1> will give the temperature one hour ago (as will <#RecentOutsideTemp m=60>). |
* <#RecentOutsideTemp m=1> will give the temperature one minute ago, <#RecentOutsideTemp h=1> will give the temperature one hour ago (as will <#RecentOutsideTemp m=60>). |
||
* <#RecentOutsideTemp d=1> will give the temperature one day ago. |
|||
* <#RecentOutsideTemp d=1> will give the temperature one day ago. '''Please note:''' Some Cumulus users say that using <#RecentOutsideTemp d=1 m=1> is more reliable at getting the temperature at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you. |
|||
** ''''''Please note:''' Some Cumulus users say that using <#RecentOutsideTemp d=1 m=1> is more reliable at getting the temperature (or whatever tag name you have quoted) at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you. |
|||
|- |
|||
* <#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago. |
* <#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago. |
||
|All values supplied for parameters must be whole numbers. |
|All values supplied for parameters must be whole numbers. |
||
* If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX. |
* ''If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX''. |
||
* '''Beware: If you use <code><#RecentRainToday d=2></code> remember that rainfall can accumulate during a day, so "d=2" returns an estimate of the rain between rollover 2 days ago and the same time as now 48 hours ago, it does not return the total rainfall 2 days ago! |
|||
* '''Please note that parameters specify time-stamped array element to retrieve based on counting back from current local time''' so the result for ''any period including when clocks change'' may not be quite what you anticipated. |
|||
! scope="row"| [[Webtags#Monthly_All_Time_Records|'''monthly all-time extreme records''']] tag names |
|||
* When Cumulus is re-started the array it sets up will be based on reading any station log that exists, so the contents will initially have a resolution according to the logger interval you have set in Cumulus and/or your station. You'll get the nearest value if you ask for a time for which there is currently no exact match, and the first tag [[Webtags#Recent_History|listed here]] tells you that nearest time. |
|||
| These tag names represent extreme record values (and corresponding time-stamps) for any particular month (1 =January, and so on, to 12 =December) in all years |
|||
* Before build 1098, the recent history array did not initialise correctly from the station logger for the period since Cumulus was last run. |
|||
| Optional input parameter is '''mon=N''' where N is the index of the month in which the extreme record occurs considering all years |
|||
* The input parameters are same for Cumulus 1 and Cumulus MX, they always use lower case d, h or m. |
|||
| Cumulus 1.9.3 beta build 1033 (remain available in MX) |
|||
* The list of recent history web tags available has not changed between last Cumulus 1 release and any MX release. |
|||
| * <#ByMonthDewPointH mon=3> is highest monthly dew point for month of March considering all years, and <#ByMonthDewPointHT mon=3> is the related time and date. |
|||
* Any new derivatives introduced by MX, will have current value web tags, and may have tags for extremes this month, extremes this year, all-time extremes, and monthly-all-time-extremes but do not have equivalent new recent history tags. |
|||
* <#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature |
|||
'''Beware: If you use <code><#RecentRainToday d=2></code> remember that rainfall can accumulate during a day, so "d=2" returns an estimate of the rain between rollover 2 days ago and the same time as now 48 hours ago, it does not return the total rainfall 2 days ago!''' |
|||
| * If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used. |
|||
|- |
|||
| [[Webtags#Monthly_All_Time_Records|'''monthly all-time extreme records''']] |
|||
| These exist for all occurrences of the current month, and for all occurrences of each month |
|||
| '''mon=N''' where N is the index of the month of the year that you want the value for (1 =January, and so on, to 12 =December) |
|||
| Cumulus 1.9.3 beta build 1033 |
|||
| e.g. <#ByMonthDewPointH mon=3> is highest monthly dew point for any March and <#ByMonthDewPointHT mon=3> is the related time and date. |
|||
<#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature |
|||
| Only one input parameter applies: |
|||
* The value of "N" supplied should be an integer between 1 and 12 |
* The value of "N" supplied should be an integer between 1 and 12 |
||
* You can use both an input parameter and an output parameter for any tag name, separate these with a space |
|||
* If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used. This is useful if you want to write a template that will always supply values for the current month and don't want to process a script, to calculate the correct input parameter, before Cumulus processes the template. |
|||
'''NOTE:''' Use without an input parameter in "MySQLConnect", "MQTT", or a template file, and then you don't need to rewrite the instruction when current month changes. If processed at rollover, the current month will change on first day of a month, and so not relate to month that has just finished. |
|||
|- |
|- |
||
| Only <#SunshineHoursMonth> and <#SunshineHoursYear> |
! scope="row"| [[Webtags#Monthly|Only <#SunshineHoursMonth>]] and [[webtags#Yearly|Only <#SunshineHoursYear>]] |
||
| Values available for current month/year, and for past month/year |
| Values available for current month/year, and for past month/year |
||
| Omit input modification parameter to get value for current month/year. Alternatively include one of the following options: |
|||
| All web tags take '''r=-ww''' |
|||
* '''r=-ww''' (note minus sign and up to 2 digits) representing that number of months/years ago |
|||
* Monthly tags also take: '''m=N y=nnnn''' |
|||
* |
* Monthly tags also take: '''m=N y=nnnn''' ('''N''' can be 1 to 12, ''nnnn'' is 4 digit year), these parameters specify exact month required |
||
* Yearly tags also take: '''y=nnnn''', this parameter specifies exact year required |
|||
Omit input modification parameter to get value for current month/year |
|||
| MX release 3.12.0 |
| MX release 3.12.0 |
||
| Monthly examples: |
| Monthly examples: |
||
* <#SunshineHoursMonth> gives total sunshine hours since 1 minute past midnight at start of current month |
* <#SunshineHoursMonth> gives total sunshine hours since 1 minute past midnight at start of current month |
||
* <#SunshineHoursMonth y=2021 m=1> for the January 2021 total |
* <#SunshineHoursMonth y=2021 m=1> for the January 2021 total |
||
* <#SunshineHoursMonth r=-1> for last |
* <#SunshineHoursMonth r=-1> for last month's total |
||
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago |
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago |
||
Yearly examples: |
|||
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day |
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day |
||
* <#SunshineHoursYear y=2019> for the total for 2019 |
* <#SunshineHoursYear y=2019> for the total for 2019 |
||
* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that |
* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that returns total for 2019 as previous example) |
||
| Returns the sunshine hours total in selected period |
| Returns the sunshine hours total in selected period |
||
|} |
|||
(You need a sensor to be monitoring this throughout selected period) |
|||
= Output modification parameters = |
|||
|} |
|||
=== Output modification parameters availability by tag name === |
|||
*A few web tags always need an output format specifier |
|||
*Some web tags never use an output format specifier |
|||
*The majority of web tags either can use an output format parameter, but they have a default output if there is no output format modifier. |
|||
Each tag name falls into one of these 3 types: |
|||
* Some tag names have a fixed output format (so they ignore any output format parameters, although obviously better not to specify any) |
|||
* Some tag names always need an output format specifier |
|||
* The majority of tag names have a default output if there is no output format modifier, but accept either one or two output format parameters, allowing you to change what they output. |
|||
This Wiki page does not include a table showing which tags belong to which type, simply because it is dependent on which Cumulus release you are running. An attempt to indicate some general guidance has been included on another [[Webtag_Applicability|discussion about applicability]] Wiki page, but contributors need to update that page and start listing tag name and release specific information. |
|||
===Output modification parameters available in legacy Cumulus 1=== |
|||
* if your locale specifies that integer and decimal parts of real numbers are separated by a comma, there is an ouput parameter to replace that decimal comma by a decimal point for any script that does not recognise decimal commas |
|||
* there are two output modifiers for changing number of decimal places |
|||
* there are multiple output modifiers for changing date and/or time format |
|||
Your options are described under the following subheadings: |
|||
Each of these will be explained in turn. |
|||
* [[#Rounding to a specific number of decimal places]] |
|||
* [[#Multiple Output Format Modifier parameters for times and dates]] |
|||
===Additional output modification parameters that are only available for MX users=== |
|||
==Output Modification Parameter for Removing Commas== |
|||
[[File:Badge vMx.png]] offers those listed above for Cumulus 1, plus: |
|||
General format: <tt><#tag_name rc=y></tt> |
|||
* [[#Output Modification Parameter for changing any decimal comma into a decimal point]] |
|||
* [[#Controlling the number of decimal places]] |
|||
* [[#Two Output (format modifier) parameters for decimal places]] |
|||
* [[#Truncation of unwanted decimal places]] |
|||
=Documentation for Output modification parameters= |
|||
This only applies: |
|||
*if the web tag name represents a real number with integer and decimal parts |
|||
*if you are using MX |
|||
**From beta release 3.0.0, build 3047 (3 February 2019), up to and including release 3.5.3, only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge) |
|||
**From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers. |
|||
**From release 3.10.5 onwards (29 March 2021), the use of <tt><#tag_name rc=n></tt> became also possible, to ensure decimal comma shown when locale specifies it |
|||
Use the links above to skip to the particular parameters that you wish to use. |
|||
==Output Modification Parameter for changing any decimal comma into a decimal point== |
|||
This output modification format parameter can be used to replace all commas in the output by a full stop (don't worry, MX does not use a comma for separating off thousands, so it is the decimal comma that becomes a decimal full stop like character when this remove comma specifier is used). |
|||
Note that Cumulus software never uses a comma for separating off thousands, and there is no way to make it output numbers above 999 with a space or comma to separate out thousands. |
|||
If you run MX on a computer using Microsoft Windows, then the "locale" mentioned below is determined by settings in either '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") or using "Settings app" (go directly to "Language"). |
|||
If the tag name represents a real number with integer and decimal parts, then Cumulus by default will output that number using whatever your locale defines as the separator character (decimal comma or decimal point). The legacy Cumulus 1 provided a few derivatives where a prefix of "RC" before tag name as in <code><#RCtag_name></code> could force the output to use a decimal point (regardless of locale), that option remains available in MX for forward compatibility. |
|||
On computers running other operating systems, the locale is set when you install "Mono-complete". You can overide the default locale with [[MX_on_Linux#Parameter_for_changing_Locale|-lang]] parameter when starting MX. |
|||
In Cumulus MX (only), you can alternatively use an output modification parameter in format <tt><#tag_name rc=y></tt> to select whether the output should use decimal comma or decimal point: |
|||
*From beta release 3.0.0, build 3047 (3 February 2019), up to and including release 3.5.3, only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge) |
|||
*From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers. |
|||
*From release 3.10.5 onwards (29 March 2021), the use of <tt><#tag_name rc=n></tt> became also possible, to ensure decimal comma shown when locale specifies it |
|||
{| class="wikitable" border="1" |
{| class="wikitable" border="1" |
||
|- |
|- |
||
Line 153: | Line 170: | ||
|rc=n |
|rc=n |
||
|This is the default, so does not need to be specified. The output from the web tag will use either decimal comma or decimal point as specified by the locale in which MX is running |
|This is the default, so does not need to be specified. The output from the web tag will use either decimal comma or decimal point as specified by the locale in which MX is running |
||
For more information about how the computer determines whether decimal commas is your default, see [[#Locale]] section later. |
|||
| Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts |
| Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts |
||
|- |
|- |
||
Line 161: | Line 180: | ||
'''Why would you want to remove decimal commas?''' Well because the JavaScript language cannot understand decimal commas, and MX has several scripts written in this language, equally some third party alternative web pages rely on ajax to update them (and Ajax uses JavaScript). |
'''Why would you want to remove decimal commas?''' Well because the JavaScript language (and some other languages) cannot understand decimal commas, and MX has several scripts written in this language, equally some third party alternative web pages rely on ajax to update them (and Ajax uses JavaScript). |
||
== |
==Controlling the number of decimal places== |
||
If the tag name represents a real number (with both integer and decimal parts) then there are a number of ways to control the number of decimal places: |
|||
This functionality was trialled in the original Cumulus, but has been properly implemented in MX. |
|||
* [[File:Badge v1.png]]Cumulus 1.x.y: <tt>dp=i</tt> rounds output to number of decimal places specified by "i" |
|||
* [[File:Badge vMx.png]] All MX releases: <tt>dp=i</tt> rounds output to number of decimal places specified by "i" |
|||
* <tt><#tag_name tc=y></tt> truncates output, display as integer, no rounding, simply ignoring all decimal places |
|||
If the tag name gives an output that is defined as text, or as an integer, then none of these can be used. It depends upon which release you are using whether a particular "real number" tag name will accept any of the above output modification parameters, gradually Cumulus has allowed more and more of its output to take an output format modifier that allows people to control number of decimal places shown. |
|||
From release 3.10.5 (which did a big rewrite of web tag handling), you can modify the way real numbers (with integer and decimal parts) are output using output modification parameters in either of the following formats: |
|||
* <tt><#tag_name dp=i></tt> and |
|||
*<tt><#tag_name tc=y></tt> |
|||
These can be applied to any tag names that represent real numbers (with integer and decimal parts). |
|||
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2. |
|||
If you are using an early release of MX: |
|||
#From beta releases (3.0.0) onwards, <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> were able to be output with "i" decimal places |
|||
#*But this output modification parameter could not be applied to any other tags in the MX beta. |
|||
#MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>). |
|||
#*Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234" |
|||
#In later releases of MX, any tag that gives a decimal output, can use the "dp=n" modifier. |
|||
Weather stations report [[Calculate_Missing_Values#Source_value|values]] as integers. Cumulus converts these to the user's desired units, and that processing can add decimal places, as it may involve division by a factor of 10, or multiplication by a conversion factor. Obviously, the sensor has a particular accuracy, and this conversion process can introduce additional errors, as can the storing in binary, Cumulus generally (not in every case) stores to a precision that would generally give about 24 significant figures when expressed in base 10. |
|||
If you are using the legacy Cumulus (1.9.4), only <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> were able to be output with "i" decimal places, e.g. <#latitude dp=5> gives "59.24250". |
|||
The handling of each tag name is coded individually, so there are no simple rules for defining the default number of decimal points that will be shown by default. In general, Cumulus does consider the units chosen for outputs. As Cumulus has been developed, people have commented that these defaults do not reflect the precision of their instrumentation (weather stations used with Cumulus tend not to have the accuracy of those used by meteorologists, or are not re-calibrated as often). |
|||
===Controlling the number of decimal places=== |
|||
[[File:Badge vMx.png]]From release 3.12.0, you can set the default number of decimal places to output for all derivatives of temperature, pressure, etc. by [[Cumulus.ini#Units.2C_Derivative_Options.2C_and_Decimal_Places|advanced settings]]. Those settings can force output as integers, in which case the parameter for controlling number of decimal places have no effect. |
|||
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2. Therefore, Cumulus stores to a precision that would generally give about 24 significant figures when expressed in base 10. |
|||
===Two Output (format modifier) parameters for decimal places=== |
|||
The number of decimal places output by default in any web tag varies, as each is coded individually. The default output from a web tag is generally rounded to one, or two decimal places, although in a few cases it is rounded to nearest integer. People have found that default does not always suit them, maybe they feel their instrumentation does not produce measurments to that precision, and so gradually Cumulus has allowed more and more of its output to take an output format modifier that allows people to control number of decimal places shown with rounding. |
|||
Depending on tag name and release you are using, there may be two ways to control decimal places: |
|||
*<tt>dp=i</tt> is used for both Cumulus 1 and MX. |
|||
* <tt><#tag_name dp=i></tt> and |
|||
**The value '''i''' following the attribute '''dp''' is an integer, it represents how many decimal places you want for the output you see. |
|||
* <tt><#tag_name tc=y></tt> |
|||
**If you are not using latest MX release, you may find this is not available for particular web tag names |
|||
====Rounding to a specific number of decimal places==== |
|||
Use <tt>dp=i</tt> (the value '''i''' following the attribute '''dp''' is an integer, it represents how many decimal places you want for the output you see): |
|||
* [[File:Badge v1.png]]Cumulus 1.x.y: only <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> are able to be output with "i" denoting number of decimal places, e.g. <#latitude dp=5> gives "59.24250". |
|||
* [[File:Badge vMx.png]] Depends on MX release: |
|||
*# From beta releases (3.0.0) onwards, <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> were able to be output with "i" decimal places |
|||
*#* But this output modification parameter could not be applied to any other tags in the MX beta. |
|||
*# MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>). |
|||
*#* Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234" |
|||
*# From release 3.10.5 (which did a big rewrite of web tag handling) any tag names that output as real numbers |
|||
====Truncation of unwanted decimal places==== |
|||
<tt>tc=y</tt> is the truncation parameter, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>. |
|||
===Truncation of unwanted decimal places=== |
|||
[[File:Badge vMx.png]]This output format modifier is only available in MX: |
|||
* If you are using an early release of MX, you will need to research whether this is available for particular tag names |
|||
* Later releases of MX implement this for any tag that by default outputs decimal places. |
|||
Note, truncation by MX converts real numbers to integers. There is no option to truncate to one decimal place, Airports are expected to report air field level (QFE), and sea level (QNH), pressures truncated to one decimal place rather than rounded. |
|||
*<tt>tc=y</tt> is the truncation parameter, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>. |
|||
**If you are using an early release of MX, you will need to research whether this is available for particular web tag names |
|||
**Later releases of MX implement this for any tag that by default outputs decimal places. |
|||
== Multiple Output Format Modifier parameters for times and dates == |
== Multiple Output Format Modifier parameters for times and dates == |
||
Output modification parameters for times and dates are highly complicated! |
|||
These are highly complicated, and so have been left until after the simpler ones! |
|||
To start with a simple example, suppose you want date/time in ISO 8601 format: |
|||
# This means, something like ''2019-02-28 06:59:05''. |
|||
# Take the tag name (from tables on [[Webtags]] page) |
|||
# Next check in [[#Which tag names take date/time output formatting modifiers]] to see if that tag accepts both time and date modifiers |
|||
# If your tag name does accept both date and time modifiers, simply modify the web tag as shown here <code><#tag_name format="yyyy-MM-dd HH:mm:ss"></code> where tag_name is set from step 1, but all the rest is typed as shown. |
|||
# To explain each element in that format value, look in [[#Time formats]], [[#Year formats]], [[#Month formats]], [[#Day formats]], [[#Use of spaces]], [[#Including literals in format parameters]]. |
|||
Should you want a different date/time format, then the sub-sections just referenced should help you to select a different arrangement, although there are some more options in [[#Date formats]]. |
|||
===Where date format codes are used=== |
|||
===Which tag names take date/time output formatting modifiers=== |
|||
Time/Date format codes are used in two places: |
|||
# As part of report names for NOAA style reports (see [[Reports_folder#Additional_Information_for_NOAA_reports|this page]] for full details) |
|||
# As part of web-tags that report either times or dates, or report both a date and a time (this is what the rest of this page covers) |
|||
When counted some time ago MX already offered a thousand different tag names. |
|||
===Which web tag names take date/time output formatting modifiers=== |
|||
There are a few time-related tag names labelled as being fixed format, that means any time/date output modifiers you might try would be ignored. |
|||
Cumulus includes a lot of web tags that can output dates, times, or both. In many cases, it will not be obvious from the web tag name whether it can return both time and date information. Sometimes, the default (without any output format modification codes) will reveal whether date and time information are both available, but unfortunately that does not always work. The following table shows some examples of which web tags will accept time and/or date output modifiers. '''Be aware''', some of the tags shown in the table may return "---" or "--:--" or some other non-numerical output in two circumstances: |
|||
#where the event they report does not happen that day (e.g. moon rise and set do not always happen within a calendar day on Earth. |
|||
#where the related data is not defined until at least one whole day has been recorded (e.g. some monthly and yearly web tags do not contain data until second day of month/year) |
|||
Some tag names, although it can be hard to tell which, report durations. You can use time modifiers to change how these are reported. Examples include '''<#daylength format=H:mm:ss>''' which reports day length and '''<#MonthDailyRainHD format=H:mm>''' which reports how much of a day it was raining. |
|||
Remember, the default format for web tags reporting date and/or time is often dependent on the locale you are using for running MX (and we will discover below the effect of some output format modifiers is also dependent on locale): |
|||
Time modifiers can also be used to change the way that clock times are reported, you might only want the hour, or you might (if resolution is available) want to also see seconds. The [[webtags]] page has columns headed "Time" to clearly identify all tag names that report clock times. |
|||
If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in either '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") or using "Settings app" (go directly to "Language"). |
|||
There are some tag names (e.g. moon rise) that relate to an event that does not happen each Earth day, so those tags have to be able to report "--:--", and you cannot modify their output. Equally, many of the tag names that describe extreme records for this month/year/all-time are not defined until the respective period reaches its second day, so again those tags may output hyphens and so any modification parameters will be ignored. For example, highest temperature range in month/year has been coded in Cumulus to report "--" for value, and "--:--" for time, on the first day of that period (because there is only a partial day to consider you might not yet have experienced a true maximum and a true minimum), so modifying the time output can only be done on subsequent days. |
|||
On computers running other operating systems, the locale is set when you install "Mono-complete". You can overide the default locale with [[MX_on_Linux#Parameter_for_changing_Locale|-lang]] parameter when starting MX. |
|||
It is not practical to indicate which time/date modifiers are accepted on a tag by tag basis. It would involve a lot of repetition. Instead, the following table, explains much more simply, which web tags will accept time and/or date output modifiers: |
|||
{| class="wikitable" border="1" |
{| class="wikitable" border="1" |
||
|- |
|- |
||
!style="width:100px" | Cross-reference |
!style="width:100px" | Cross-reference to table on web tag names page |
||
!style="width:300px" | |
!style="width:300px" | Tag names that accept only time output modifiers |
||
!style="width:300px" | |
!style="width:300px" | Tag names that accept only date output modifiers |
||
!style="width:300px" | |
!style="width:300px" | Tag names that accept both time and date output modifiers |
||
|- |
|- |
||
|[[Webtags#Date_.26_Time|Date &Time]], [[Webtags#Day/Night/Sun/Moon]] |
|||
|<#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk> |
|||
|<#LatestErrorDate>, <#date> |
|||
|<#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT> |
|||
|- |
|- |
||
! scope="row"| Any tag names that don't report times nor dates |
|||
|[[Webtags#Today]], [[Webtags#Yesterday]] |
|||
| None |
|||
| any tag in "Time" column of linked table |
|||
| None |
| None |
||
| None |
| None |
||
|- |
|- |
||
| |
! scope="row"| [[Webtags#No_Commas]] |
||
| None |
|||
| any tag in "Time" column of linked table in first column |
|||
| None |
|||
| any tag in "Date" column of linked table in first column |
|||
| None |
|||
| Not advised (see ^ note after table) |
|||
|- |
|- |
||
|[[Webtags# |
! scope="row"| [[Webtags#Date_.26_Time]], [[Webtags#Day/Night/Sun/Moon]] |
||
| Only <#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk> |
|||
|n/a |
|||
| Only <#LatestErrorDate>, <#date> (but no others) |
|||
|n/a |
|||
| Only <#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT> |
|||
|any tag in "Date/Time" column of linked table |
|||
|- |
|||
! scope="row"| [[Webtags#Today]], [[Webtags#Yesterday]] |
|||
| Any tag name in "Time" column of linked table |
|||
| None |
|||
| None |
|||
|- |
|||
! scope="row"| [[Webtags#Monthly]], [[Webtags#Yearly]] |
|||
| Those tag names in "Time" column of linked table in first column that represent spot value extreme records. For notes see ~ below this table |
|||
| Any tag name in "Date" column of linked table in first column that represent either daily extremes or spot value extreme records. For notes see † below this table |
|||
| None of the tag names. For explanation see the ^ below this table |
|||
|- |
|||
! scope="row"| [[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]] |
|||
| None (all tag names combine both time and date) |
|||
| Those tag names in "Date/Time" column of linked table that represent daily extremes |
|||
| Those tag names in "Date/Time" column of linked table that represent spot value extreme records |
|||
|- |
|||
! scope="row"| [[Webtags#Davis]] |
|||
| None |
|||
| <#StormRainStart> only |
|||
| None |
|||
|} |
|} |
||
~ For rainfall, only '''<#LastRainTip>''' can have output modifiers added to report a clock time. |
|||
^ Note: There are some monthly/yearly web tags (e.g wettest day) where a date tag is available (i.e. <#MonthDailyRainHD>), but not a time tag. You may get a time back if you put output time parameters into such a date tag, but the time returned may be wrong (especially if you don't use midnight rollover, for that wettest day example <#MonthDailyRainHD format=H:mm> it does return a time when the rain stopped, but the hour is out by 9 or 10 hours on a 9 or 10 am rollover). |
|||
† Daily extremes (e.g. wettest day <#MonthDailyRainHD>, and temperature ranges <#MonthHighDailyTempRangeD>) have no time tag. |
|||
^ For the monthly and yearly web tags, the date and time are in separate tag names. It is not possible to get both time and date out of either tag name. |
|||
===Locales=== |
|||
===What can time/date output modifiers do?=== |
|||
The default format for many tag names reporting date and/or time is dependent on the locale you are using for running Cumulus (1 or MX). |
|||
These output format modifiers allow you to override the default display format for a particular web tag (subject to restrictions seen in last sub-section), |
|||
using the format specifiers to be described later. The characters used to represent year, month, day, hour, minute, second, microsecond, and am/pm; all differ between C1 and MX. |
|||
The effect of some output format modifiers is also dependent on locale. |
|||
#You can choose whether 12-hour clock is used with am/pm, or the 24-hour clock is used. |
|||
#You can choose to include/exclude leading zero for hours. |
|||
#You can only report the hour if you don't care about the minutes, or only report the minutes if you don't need the hour. |
|||
#In most cases you can add seconds to the output, and in some cases either milliseconds or microseconds. |
|||
#* This does not imply that Cumulus calculates everything every microsecond, in fact for the legacy software many derivatives are only calculated once a minute, but the flexibility is there for time outputs. |
|||
#* It is also worth remembering that if the required derivative relates to a period when Cumulus was in catch-up ('''reading archive data''' is how MX describes it), then the time-stamp resolution is restricted by the station's logging interval, even if that is only every half an hour! |
|||
For Microsoft Windows Operating Systems, a Language is defined within the "Region" page of the Settings app. That should be sufficient for the legacy software that uses Delphi. However for MX date and time formats within Windows Operating System, you must use the older '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") because it is only there that you can adjust all the defaults used by .NET. |
|||
===Use of double quotation marks=== |
|||
[[File:Badge vMx.png]]For MX running on most operating systems (other than Microsoft Windows), type <code>locale</code> to see the default locale that will be adopted when mono-complete is installed as MX will, by default, take locale setting from Mono. When you start MX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at [[MX_on_Linux#Parameters]]. For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8. |
|||
The general syntax is <code><#tag_name format=x></code> where '''x''' can represent a single chacter, or multiple characters without any spaces. |
|||
The available locales on your computer in Linux are listed by <code>locale -a</code>. For example, the Russian locale would be selected as the one your computer uses ''for the current session only'' by using <code>LANG=ru_RU.utf8</code> either typed into a terminal session before you start MX, or used as a parameter (preceded by "-") as you start MX interactively. |
|||
If we need to include spaces, then we have to add double quotation matrks round the right hand side as shown here <code><#tag_name format="x y z"></code> |
|||
For permanently changing the locale used by your system, the instructions vary considerably according to the kernel used in your operating system, so you need to look up the instructions for yourself. However, if you have a graphical user interface, such as the full Raspberry Pi Operating System provides, you might have a configuration command in terminal mode and a configuration app accessed (within ''Preferences'') from the "Raspberry" key on the official keyboard. For the Raspberry Pi, please read [[Raspberry Pi computer page]] for more details. |
|||
===Time zones=== |
|||
Before I explain what time/date output modifiers can do, something they can't do. |
|||
All web tag outputs are in local time, except '''<#timeUTC>'''. |
|||
Cumulus 2 internally stored all date/times in UTC, and the development of MX is planned to attach UTC date-times to all data although (at time of typing this) this is not yet implemented so MX maintains compatibility with Cumulus 1 legacy software. |
|||
[[File:Badge vMx.png]]In most MX releases, you can use a script to convert a time to UTC. This is not the place to tell you how to write the script, but taking time of highest pressure today as an example, you would use <#TpressTH format=Hh:mm> and <#TpressTH format=zzz>, the first gives hours and minutes in your local time, and the second gives the offset that needs to be applied to that time to convert it to UTC. |
|||
===Time resolution=== |
|||
For the legacy software, there may be no point in asking for seconds, as Cumulus 1 did some actions at one minute intervals. For MX, it depends on which tag name you are using whether it supports seconds (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute). |
|||
If Cumulus obtained archive data, as part of the catch-up process it can do when it restarts, any time-stamps for that historic period can only be the time of a particular archive record, so that might be every half an hour, but not aligned precisely with hour changes. |
|||
===Dependency on Cumulus flavour=== |
===Dependency on Cumulus flavour=== |
||
You have to change all date/time formatting when moving from the original (legacy) Cumulus to MX. |
|||
There are differences between the original (legacy) Cumulus and MX. The characters used for specifying the required output modification vary, so all tables showing details of time and date modifiers have separate columns showing what is used in each flavour. |
|||
[[Category:Cumulus MX]] |
|||
All the tables explaining what is used in each flavour for each type of output, both by including separate columns for each flavour, and by giving examples in each flavour. |
|||
====For the legacy software==== |
====For the legacy software==== |
||
Line 289: | Line 349: | ||
====The complications with MX==== |
====The complications with MX==== |
||
The [[:Category:Ini Files|*.ini Files]] in MX have adopted the ISO 8601 date format where year comes first (yyyy-MM-dd), although for compatibility with the legacy software, any lines in these files ported from Cumulus 1 retain their day before month before year format until they are updated. Most dates reported by web tags derive their content from entries in these files. |
|||
In Cumulus MX the same character can have 4 different meanings depending on its case (capital letter or lower-case letter), and depending on whether it is on its own (standard format) or not (custom format). '''Sounds confusing?''' Well it is complicated. |
|||
The [[:Category:MX txt Files|*.txt Files]] have so far stuck to date formats as used in the legacy definitions, the intention to swap to ISO format for the .txt files from September 2020, having been postponed to an unannounced future date, because of the continuing need for compatibility while there is use of the legacy software by a significant number of users. |
|||
For Cumulus MX output formatting, the date and time modifiers are complicated by the fact that ''the same character can have 4 different meanings'' depending on its case (capital letter or lower-case letter), and depending on whether it is on its own (standard format) or with another modifier (custom format). One more confusion, Microsoft have reversed the use of capital 'M' and lower case 'm' from the standard used very widely, and you may have got to know. '''Sounds confusing?''' Well it is complicated. |
|||
Consider context first: |
Consider context first: |
||
Line 303: | Line 367: | ||
**".NET" was originally operating system independent, later only Microsoft Windows specific components were included, but since November 2020 ".Net" is used for an operating system independent version that originally Microsoft issued under another name! |
**".NET" was originally operating system independent, later only Microsoft Windows specific components were included, but since November 2020 ".Net" is used for an operating system independent version that originally Microsoft issued under another name! |
||
**(actually it is possible to install and run "Mono" in Windows Operating Systems). |
**(actually it is possible to install and run "Mono" in Windows Operating Systems). |
||
*If Cumulus MX is running on any Linux distribution (including Raspberry Pi Operating Systems) or Mac OS X, or any other device that uses an UNIX derived operating system, then MX uses '''Mono''' software for same purposes. (MONO is a operating system independent version of .NET, although they are developed independently, they have common origins). |
*If Cumulus MX is running on any Linux distribution (including Raspberry Pi Operating Systems) or Mac OS X, or any other device that uses an UNIX derived operating system, then MX uses '''Mono''' software for same purposes. (MONO is a operating system independent version of .NET, although they are developed independently, they have common origins). |
||
===Effect of Locales=== |
|||
Locales have already been mentioned twice on this page, now it is time to say what is defined in these locales. |
|||
====Date formats==== |
|||
Cumulus works with dates specified in either a day before month before year format, or ISO 8601 date format where year comes first (yyyy-MM-dd). If you are in the USA, Cumulus will not use your month first date internally, but you can see your preferred format in any output as you can can combine the month specifier, with the day specifier, in that order, to get an output where the month appears first (see example in table below). <big>Please could an American contributor please check if the "M" modifier works for them and update the table below</big>. |
|||
Locales will define a '''Short Date Format''' and a '''Long Date Format'''. Which date format is used as the default, depends on which web tag is used. What appears in short and long formats depends entirely on the selected locale. |
|||
If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in the (now hidden) '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", and enter the formats you want for long and short here). |
|||
On computers running other operating systems, the locale is set when you install "Mono-complete". That is determined by language settings when you set up your computer, but you may be able to edit the configuration to change what is defined for the long and short formats. You can overide the default locale with [[MX_on_Linux#Parameter_for_changing_Locale|-lang]] parameter when starting MX. |
|||
There is a single character output format modifier ('''G''' or '''c''') that makes the output appear exactly as defined in short date format, followed by long time format. There are other format codes in table below for other date outputs. |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|c |
|||
|G (as single character format) |
|||
|Displays the date using the format given by the Short Date format, followed by the time using the format given by the Long Time format. The time is not displayed in Cumulus 1 if the date-time value indicates midnight precisely. |
|||
|'22/03/2019 09:47:25' produced by {{Version badge 1}}<#time format=c>[[File:Badge vMx.png]]<#time format=G> |
|||
|- |
|||
|"D MMMM YYYY" |
|||
|D |
|||
|Long date format |
|||
|e.g.4 December 2009 |
|||
|- |
|||
|"D MMMM" |
|||
|M |
|||
|Day of month followed by Month name (except USA locales). |
|||
Compared with next table where '''format=%M''' used, '''format=M''' on its own returns both Month and Day according to local format |
|||
| e.g. 22 July (English Locale) |
|||
|- |
|||
|"MMMM D" |
|||
|"MMMM d" if M alone does not work |
|||
| USA format of month before day of month |
|||
| e.g. July 4 (USA format) |
|||
|- |
|||
|TT |
|||
|T (as single character format) |
|||
|Displays the time using the '''Long Time format'''. |
|||
[[File:Badge vMx.png]] Note that this is a full time specifier and "T" is on its own as we are using a single character format. |
|||
|'09:47:56' (might not use colon in your locale) produced by |
|||
*{{Version badge 1}}<#LastDataReadT format=TT> |
|||
*[[File:Badge vMx.png]]<#LastDataReadT format=T> |
|||
|} |
|||
====Month formats==== |
|||
All locales offer both numerical and alphabetical formats for representing months. |
|||
*In the following table "MMM" is shown as producing short month name. |
|||
**What language is used, and what characters appear, depend on what is set up for your language in your settings (by default or by you changing your settings) |
|||
**In British English (UK) locale this will be the appropriate 3 letter abbreviation that starts with "Jan" and runs to "Dec" |
|||
**It appears that language settings in many locales (not "en-gb"), add a full stop to any abbreviations (e.g. Australia settings default to "Jan." to "Dec.") |
|||
*** MX has been coded to remove that full stop in various places (like in standard log file naming and NOAA report naming), but at the time this section was edited, "MMM" still reports the full stop if your locale uses it |
|||
*In the following table "MMMM" is shown as producing the full name for a month |
|||
**This will depend on the language defined in your locale |
|||
**In English locales, this will be "January" - "December" |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|M (or ''m'') |
|||
|%M |
|||
|Displays the month as a number without a leading zero (1-12). |
|||
*{{Version badge 1}}Cumulus 1.x.y:If the 'M' or 'm' specifier immediately follows an h, hh, HH, or H specifier, the minute rather than the month is displayed. |
|||
*[[File:Badge vMx.png]]Cumulus MX: Note that including a ' ' (space) or '%' before the M makes it a custom modifier, so different from the '''format=M''' included in previous table. |
|||
|2 |
|||
|- |
|||
|MM (or ''mm'') |
|||
|MM |
|||
|Displays the month as a number with a leading zero (01-12). |
|||
*{{Version badge 1}}Cumulus 1.x.y:If the 'm' or 'M' specifier immediately follows an h, H, HH, or hh specifier, the minute rather than the month is displayed. |
|||
|'03' produced by <#LastDataReadT format=MM> or <#metdate format="MM"> |
|||
|- |
|||
|MMM (or ''mmm'') |
|||
|MMM |
|||
|Displays the month using the strings defined for '''short month name''' in the Locale. |
|||
|'Jun' produced by <#metdate format="MMM"> (English locale) |
|||
|- |
|||
|MMMM (or ''mmmm'') |
|||
|MMMM |
|||
|Displays the month as a full name using the strings appropriate to the Locale. |
|||
|'June' produced by <#metdate format="MMMM"> (English locale) |
|||
|} |
|||
====Day formats==== |
|||
All locales offer both numerical and alphabetical formats for representing a day. |
|||
The table below relates just to the day part of any date specifications. As for month above, the short and full day names that are generated depend on your locale, so you might see additional punctuation defined in some locales. |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|d |
|||
|%d |
|||
|Displays the day as a number without a leading zero (1-31). [[File:Badge vMx.png]]Note that Cumulus MX requires a ' ' (space), '%' or other modifier to be included, as 'd' on its own returns full 'short date'). |
|||
|27 produced by {{Version badge 1}}<#metdate format="d">[[File:Badge vMx.png]]<#metdate format="%d"> |
|||
|- |
|||
|dd |
|||
|dd |
|||
|Displays the day as a number with a leading zero (01-31). |
|||
|07 produced by <#metdate format="dd"> |
|||
|- |
|||
|ddd |
|||
|ddd |
|||
|Displays the day as an abbreviation (Sun-Sat) using the strings appropriate to the Locale. |
|||
|'Wed' produced by <#metdate format="ddd"> (English locale) |
|||
|- |
|||
|dddd |
|||
|dddd |
|||
|Displays the day as a full name (Sunday-Saturday) using the strings appropriate to the Locale. |
|||
|'Friday' produced by <#metdate format="dddd"> (English locale) |
|||
|- |
|||
|ddddd |
|||
|d (as single character format) |
|||
|{{Version badge 1}}Cumulus 1.x.y: Displays the date using the format given by the Short Date format. [[File:Badge vMx.png]]This MX parameter (when on its own) displays inconsistent behaviour as its effect depends on the tag name with which it is used (see examples). |
|||
|e.g. '22/03/2019' (British Locale) produced by {{Version badge 1}}<#metdate format=dddd> |
|||
[[File:Badge vMx.png]]<#metdateyesterday format=d> ''but not'' <#yesterday=d> which would return just '22' |
|||
|- |
|||
|dddddd |
|||
|D (as single character format) |
|||
|Displays the date using the format given by the Long Date format. [[File:Badge vMx.png]]The MX parameter cannot be combined with any other parameters. |
|||
|e.g. '22 March 2020' (British Locale) |
|||
|} |
|||
===Year formats=== |
|||
These are the simplest output format modifiers. We choose from 2 options, and because both involve more than one character their context does not matter. Although the legacy Cumulus will accept upper case, it is simplest if we just show the lower case options: |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | Specifier |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|yy |
|||
|Displays the year as a two-digit number (00-99). |
|||
|19 produced by <#LastDataReadT format=yy> |
|||
|- |
|||
|yyyy |
|||
|Displays the year as a four-digit number (2000-9999). |
|||
|2009 produced by <#LastDataReadT format=yyyy> |
|||
|} |
|||
===Time formats=== |
===Time formats=== |
||
Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table. |
Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table. As explained earlier, time formats can be used with both time-duration reporting and clock time reporting. |
||
In some rows of this table, square brackets [] indicate optional items, they are included just to make it clearer how items can be combined in a single output parameter. If you want to include what is shown in square brackets you don't type the square brackets e.g. <tt><#LastDataReadT format="h:nn am/pm"></tt> |
In some rows of this table, square brackets [] indicate optional items, they are included just to make it clearer how items can be combined in a single output parameter. If you want to include what is shown in square brackets you don't type the square brackets e.g. <tt><#LastDataReadT format="h:nn am/pm"></tt> |
||
{| class="wikitable" border="1" |
{| class="wikitable" border="1" |
||
|- |
|- |
||
!style="width:150px" | |
!style="width:150px" | [[File:Badge v1.png]]Delphi Specifier for Cumulus 1.9.x |
||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
||
!style="width:600px" | Displays |
!style="width:600px" | Displays |
||
Line 483: | Line 385: | ||
|%h |
|%h |
||
|Displays the hour (12 hour clock) without a leading zero (1-12) |
|Displays the hour (12 hour clock) without a leading zero (1-12) |
||
| 7 |
|||
|- |
|- |
||
|h ''AM/PM'' |
|h ''AM/PM'' |
||
|h ''tt'' |
|%h ''tt'' |
||
|Displays the hour (12 hour clock) without a leading zero (1-12) in combination with AM/PM. |
|Displays the hour (12 hour clock) without a leading zero (1-12) in combination with AM/PM. |
||
[[File:Badge v1.png]]For Cumulus 1 the formats for am/pm depend on the case in which you type the parameter as shown later in this table |
|||
[[File:Badge vMx.png]]What "tt" produces depends on locale settings for your device, it might be capitals or it might be lower case (in Windows use Control Panel, not Settings app, to get to these regional additional settings). |
[[File:Badge vMx.png]]What "tt" produces depends on locale settings for your device, it might be capitals or it might be lower case (in Windows use Control Panel, not Settings app, to get to these regional additional settings). |
||
| [[File:Badge v1.png]]7 PM |
|||
|- |
|- |
||
|h:nn [''AM/PM''] |
|h:nn [''AM/PM''] |
||
|h:mm [''tt''] |
|%h:mm [''tt''] |
||
|Displays the hour (using 12 hour clock) without a leading zero (1-12) followed by 2 digit minutes [optionally in combination with AM/PM whose case varies as explained in previous entry]. |
|Displays the hour (using 12 hour clock) without a leading zero (1-12) followed by 2 digit minutes [optionally in combination with AM/PM whose case varies as explained in previous entry]. |
||
[[File:Badge v1.png]]For Cumulus 1, the minutes can be represented by 'mm' (instead of "nn") only when appearing in combination with 'h' |
|||
|'10:27 am' produced by |
|'10:27 am' produced by [[File:Badge v1.png]] <#LastDataReadT format="h:nn am/pm">[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt"> |
||
|- |
|- |
||
|H (or ''H'') |
|H (or ''H'') |
||
|%H |
|%H |
||
|Displays the hour |
| Displays the hour part of any duration or clock time, without a leading zero (0-23). |
||
[[File:Badge vMx.png]]Note that '%' before the "H", this makes it a custom modifier, needed because H is on its own. |
|||
|7 produced by |
|7 produced by |
||
* |
* [[File:Badge v1.png]]<#daylength format=H> |
||
*[[File:Badge vMx.png]]<#daylength format=%H> |
*[[File:Badge vMx.png]]<#daylength format=%H> |
||
|- |
|- |
||
|H:mm (or ''H:nn'') |
| H:mm (or ''H:nn'') |
||
|H:mm |
| H:mm |
||
|Displays the hour |
| Displays the hour part of any duration or clock time, without a leading zero (0-23) followed by 2 digit minutes for that duration or clock time. |
||
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm"> |
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm"> |
||
|- |
|- |
||
|HH (or ''hh'') |
|HH (or ''hh'') |
||
|HH |
|HH |
||
|Displays the hour using 24 hour clock with a leading zero (00-23). |
| Displays the hour part of any duration or clock time, using 24 hour clock with a leading zero (00-23). |
||
|'06' or '17' produced by <#LastDataReadT format=HH> |
|'06' or '17' produced by <#LastDataReadT format=HH> |
||
|- |
|- |
||
|hh [''am/pm''] |
|hh [''am/pm''][''AM/PM''] |
||
|hh [''tt''] |
|hh [''tt''] |
||
|Displays the hour (12 hour clock) with a leading zero (01-12) [optionally in combination with am/pm]. |
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) [optionally, if it is a clock time, in combination with am/pm]. |
||
[[File:Badge v1.png]]For Cumulus 1, two optional terms are shown because the case output for the optional 'am/pm' depends on the case used for that parameter |
|||
[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon but before midnight |
[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon but before midnight. |
||
|'07 am' produced by |
|'07 am' produced by |
||
* |
* [[File:Badge v1.png]] <#LastDataReadT format="hh am/pm"> |
||
*[[File:Badge vMx.png]] <#LastDataReadT format="hh tt"> |
*[[File:Badge vMx.png]] <#LastDataReadT format="hh tt"> if locale specifies lower case |
||
|- |
|- |
||
|hh:mm (or ''hh:nn'' or 'HH:NN') [''am/pm''] |
|hh:mm (or ''hh:nn'' or 'HH:NN') [''am/pm''][''AM/PM''] |
||
|hh:mm [''tt''] |
|hh:mm [''tt''] |
||
|Displays the hour (12 hour clock) with a leading zero (01-12) followed by 2 digit minutes [optionally in combination with am/pm]. |
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) followed by 2 digit minutes [optionally, if it is a clock time, in combination with am/pm]. |
||
* |
* [[File:Badge v1.png]]For Cumulus 1, the minutes can be represented by 'mm' only when in combination with 'h', in other contexts 'mm' is interpreted as month number, two optional terms are shown because the case output for the optional 'am/pm' depends on the case used for that parameter |
||
*[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight |
*[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight |
||
|'8:27 am' produced by |
|'8:27 am' produced by |
||
* |
* [[File:Badge v1.png]] <#LastDataReadT format="h:nn am/pm"> |
||
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt"> |
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt"> if locale specifies lower case |
||
|- |
|- |
||
|n |
|n |
||
|%m |
|%m |
||
|Displays the |
|Displays the minutes of any duration or clock time, without a leading zero (0-59). |
||
[[File:Badge vMx.png]] As other examples show, the % is only needed when "m" is on its own. |
[[File:Badge vMx.png]] As other examples show, the % is only needed when "m" is on its own. |
||
|7 produced by |
| 7 produced as a duration in minutes by |
||
* |
* [[File:Badge v1.png]]<#daylength format=n> |
||
*[[File:Badge vMx.png]]<#daylength format=m> |
*[[File:Badge vMx.png]]<#daylength format=m> |
||
|- |
|- |
||
|nn |
|nn |
||
|mm |
|mm |
||
|Displays the |
|Displays the minutes of any duration or clock time, with a leading zero (00-59). |
||
|'07' produced |
|'07' produced as a duration in minutes by |
||
* |
* [[File:Badge v1.png]]<#daylength format=nn> |
||
*[[File:Badge vMx.png]]<#daylength format=mm> |
* [[File:Badge vMx.png]]<#daylength format=mm> |
||
|- |
|- |
||
|s |
|s |
||
|%s |
|%s |
||
|Displays the |
|Displays the seconds for any duration or clock time, that has resolution to less than a minute, without a leading zero (0-59). |
||
[[File:Badge vMx.png]] As other examples show, the % is recommended when "s" is on its own, although I have not found any alternative meaning for "s" on its own. |
[[File:Badge vMx.png]] As other examples show, the % is recommended when "s" is on its own, although I have not found any alternative meaning for "s" on its own. |
||
Line 568: | Line 474: | ||
|Displays the millisecond without a leading zero (Cumulus 1: displays 0-999, Cumulus MX: displays either nothing, or displays 1-999, so don't write any code that assumes the MX output is numeric). |
|Displays the millisecond without a leading zero (Cumulus 1: displays 0-999, Cumulus MX: displays either nothing, or displays 1-999, so don't write any code that assumes the MX output is numeric). |
||
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Windows. |
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows. |
||
| |
| |
||
|- |
|- |
||
Line 580: | Line 486: | ||
|Displays the millisecond with a leading zero (000-999). |
|Displays the millisecond with a leading zero (000-999). |
||
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Windows. |
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows. |
||
[[File:Badge vMx.png]]The 'fff' modifier in MX can actually be extended to 'ffffff' for output to a millionth of a second! |
[[File:Badge vMx.png]]The 'fff' modifier in MX can actually be extended to 'ffffff' for output to a millionth of a second! |
||
| 09:47:25.000' produced by |
| 09:47:25.000' produced by |
||
* |
* [[File:Badge v1.png]]<#time format=hh:nn:ss.zzz> |
||
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff> |
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff> |
||
|- |
|- |
||
Line 594: | Line 500: | ||
|(not available) |
|(not available) |
||
|"h:mm K" |
|"h:mm K" |
||
|Effectively another way of including time zone after a time, but it can only be used for |
|Effectively another way of including time zone after a time, but it can only be used for time-zones never matching UTC (if I understand correctly) |
||
|(no examples supplied yet) |
|(no examples supplied yet) |
||
|- |
|- |
||
|t |
|t |
||
|%t |
|%t |
||
|Displays the time using the Short Time format. |
|Displays the time using the Short Time format. |
||
[[File:Badge vMx.png]]Remember that 't' combined with other specifiers (or preceded by space or '%') has a different meaning - see below. |
|||
| '09:47' produced by <#LastDataReadT format=t> (might not use colon in your locale) for both flavours of Cumulus |
| '09:47' produced by <#LastDataReadT format=t> (might not use colon in your locale) for both flavours of Cumulus |
||
|- |
|- |
||
|am/pm or Am/Pm or AM/PM |
|am/pm or Am/Pm or AM/PM |
||
|tt |
|tt |
||
| |
| [[File:Badge v1.png]]Uses the 12-hour clock for the preceding h or H specifier, and displays 'am' for any (clock time) hour from midnight until just before noon, and 'pm' for any hour from noon onwards. The am/pm specifier for Cumulus 1 can use lower, upper, or mixed case, and the result is displayed accordingly. |
||
[[File:Badge vMx.png]] For MX, 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight, so whether it displays in capitals or lower case is determined by the locale settings, not the case of "tt". |
[[File:Badge vMx.png]] For MX, 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight, so whether it displays in capitals or lower case is determined by the locale settings, not the case of "tt". |
||
| |
| [[File:Badge v1.png]] 'am' produced by <#LastDataReadT format=am/pm>, 'AM' produced by <#LastDataReadT format=AM/PM> |
||
|- |
|- |
||
|h a/p |
|h a/p |
||
|h t |
|h t |
||
|Uses the 12-hour clock for the preceding h or H specifier, and displays 'a' for any hour from midnight until before noon, and 'p' for noon or any hour after noon. |
|Uses the 12-hour clock for the preceding h or H (clock time) specifier, and displays 'a' for any hour from midnight until before noon, and 'p' for noon or any hour after noon. |
||
{{Version badge 1} The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly. |
|||
[[File:Badge v1.png]]The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly. |
|||
[[File:Badge vMx.png]]whether it displays the "a" or "p" in capitals or lower case is determined by the locale settings, not the case of "t". |
[[File:Badge vMx.png]]whether it displays the "a" or "p" in capitals or lower case is determined by the locale settings, not the case of "t". |
||
Line 620: | Line 529: | ||
|(see above for 12 hour formats) |
|(see above for 12 hour formats) |
||
|This displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight. |
|This displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight. |
||
[[File:Badge v1.png]]Uses the 12-hour clock for the preceding h or H specifier |
|||
| see previous examples |
| see previous examples |
||
|- |
|- |
||
Line 636: | Line 545: | ||
|} |
|} |
||
===Year formats=== |
|||
These are the simplest output format modifiers. We can only choose from 2 options, and because both involve more than one character their context does not matter. Although the legacy Cumulus will accept upper case as meaning same as lower case, it is simplest if we just show the lower case options that are mandatory for MX: |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | Specifier |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|yy |
|||
|Displays the year as a two-digit number (00-99). |
|||
|19 produced by <#LastDataReadT format=yy> |
|||
|- |
|||
|yyyy |
|||
|Displays the year as a four-digit number (2000-9999). |
|||
|2009 produced by <#LastDataReadT format=yyyy> |
|||
|} |
|||
===Month formats=== |
|||
All locales offer both numerical and alphabetical formats for representing months. |
|||
*In the following table "MMM" is shown as producing short month name. |
|||
**What language is used, and how many characters appear, depend on what is set up for your language in your settings (by default or by you changing your settings) |
|||
** In Australian locale, this would output 4 characters representing a month abbreviation that runs from "Jan." to "Dec." |
|||
** In British English (UK) locale, abbreviations do not incude a full stop, so output is a 3 letter abbreviation that starts with "Jan" and runs to "Dec" |
|||
*In the following table "MMMM" is shown as producing the full name for a month |
|||
**The output you get will depend on the language defined in your locale |
|||
**In all English based locales, the output will be in the range "January" to "December" |
|||
[[File:Badge vMx.png]]'''CAUTION:''' Cumulus MX has yet another complication, a web tag can return different months depending on whether the output modifier for month is used with, or without, an output modifier for day. Take two examples <code><#metdateyesterday format=yyyy-MM-dd></code> and <code><#metdateyesterday format=yyyy-MM></code>, these can produce different months when processed by MX on same day at near enough same time! Let us assume the first is reporting (in a particular year) the first day of June, the second would report the month of May in same year! |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | [[File:Badge v1.png]]Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
|M (or ''m'') |
|||
|%M |
|||
|Displays the month as a number without a leading zero (1-12). |
|||
* [[File:Badge v1.png]]Cumulus 1.x.y:If the 'M' or 'm' specifier immediately follows an h, hh, HH, or H specifier, the minute rather than the month is displayed. |
|||
* [[File:Badge vMx.png]]Cumulus MX: Note that including a ' ' (space) or '%' before the M makes it a custom modifier, so giving a different output to the '''format=M''' included in table in [[#Date formats]] subsection. |
|||
|2 |
|||
|- |
|||
|MM (or ''mm'') |
|||
|MM |
|||
|Displays the month as a number with a leading zero (01-12). |
|||
* [[File:Badge v1.png]]Cumulus 1.x.y:If the 'm' or 'M' specifier immediately follows an h, H, HH, or hh specifier, the minute rather than the month is displayed. |
|||
|'03' produced by <#LastDataReadT format=MM> or <#metdate format="MM"> |
|||
|- |
|||
|MMM (or ''mmm'') |
|||
|MMM |
|||
|Displays the month using the strings defined for '''short month name''' in the Locale. |
|||
|'Jun.' or 'Jun' produced by <#metdate format="MMM"> (varies depending which English locale as explained before table) |
|||
|- |
|||
|MMMM (or ''mmmm'') |
|||
|MMMM |
|||
|Displays the month as a full name using the strings appropriate to the Locale. |
|||
|'June' produced by <#metdate format="MMMM"> (English locale) |
|||
|} |
|||
===Day formats=== |
|||
All locales offer both numerical and alphabetical formats for representing a day. |
|||
[[File:Badge vMx.png]]Again, there are extra complications with MX, the "d" modifier is not shown because it is inconsistent, the format it returns depends on which tag name it is used with - see [[#Date formats]] table later! For some tag names it returns just "day of month" (like "%d"), for others it returns the full "Short date format" (like "ddddd")! |
|||
The table below is the definitive guide to how to ensure you do specify just the day part of any date specifications. |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | [[File:Badge v1.png]]}Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
| d (single character) |
|||
| %d |
|||
|Displays the day as a number without a leading zero (1-31). |
|||
[[File:Badge vMx.png]]Note that Cumulus MX requires a ' ' (space), '%' or another modifier to be included, as 'd' on its own is inconsistent - see [[#Date formats]] table). |
|||
| 27 produced by: |
|||
* [[File:Badge v1.png]]<#metdate format="d"> |
|||
* [[File:Badge vMx.png]]<#metdate format="%d"> |
|||
|- |
|||
|dd (2 characters long) |
|||
|dd |
|||
|Displays the day as a number with a leading zero (01-31). |
|||
|07 produced by <#metdate format="dd"> |
|||
|- |
|||
|ddd (3 characters long) |
|||
|ddd |
|||
|Displays the day as an abbreviation (in Australian will output "Sun." to "Sat.") using the strings appropriate to the Locale (see note for month abbreviation). |
|||
|'Wed' produced by <#metdate format="ddd"> (UK English locale) |
|||
|- |
|||
|dddd (4 characters long) |
|||
|dddd |
|||
|Displays the day as a full name (Sunday-Saturday) using the strings appropriate to the Locale. |
|||
|'Friday' produced by <#metdate format="dddd"> (English locale) |
|||
|} |
|||
===Date formats=== |
|||
The [[#Year formats]], [[#Month formats]], and [[#Day formats]] listed above can be combined to make up a date output modifier, but there are some other modifiers available that can produce whole dates. |
|||
[[#Locales]] will define a '''Short Date Format''' and a '''Long Date Format'''. You will see references to those in the table below explaining available output format modifiers, for example the single character output format modifier ('''G''' or '''c''') listed at the start of the table below. |
|||
If you are in the USA, Cumulus will only use your month first date internally for the start date (see [[Cumulus.ini (Cumulus 1)]] and [[Cumulus.ini|Cumulus.ini (Cumulus MX)]]), that format will not be used in any files in the [[Data folder|'''data''' sub-folder]], but you can see your preferred format in the settings pages, in the extreme record editing pages, and by default as an output from many (not all) web tags. For any web tags that do permit use of output date modification format parameters, you can can combine any month specifier, with any day of month specifier, in that order, to get an output where the month appears first (see example in table below). |
|||
<big>Please could an American contributor please check if the "M" modifier works for their locale as shown and update the table below if necessary, and edit this comment into a confirmation</big>. |
|||
{| class="wikitable" border="1" |
|||
|- |
|||
!style="width:150px" | [[File:Badge v1.png]]Delphi Specifier for Cumulus 1.9.x |
|||
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX |
|||
!style="width:600px" | Displays |
|||
!style="width:600px" | Example |
|||
|- |
|||
| c |
|||
| G (as single character format) |
|||
| Displays the date using the format given by the Short Date format, followed by the time using the format given by the Long Time format. The time is not displayed in Cumulus 1 if the date-time value indicates midnight precisely. |
|||
| '22/03/2019 09:47:25' produced by [[File:Badge v1.png]]<#time format=c>[[File:Badge vMx.png]]<#time format=G> |
|||
|- |
|||
| ddddd (5 characters long) |
|||
| ddddd (5 characters long) |
|||
| 'ddddd' will output the date using the format given by the Short Date format. |
|||
[[File:Badge vMx.png]]'d' (when on its own, without space or '%' prefix) may or may not work, it displays inconsistent behaviour as its effect depends on the tag name (sorry, there is no definitive list from the MX author specifying effect by individual tag name) with which it is used (you will need to experiment for yourself and compare with the two examples). |
|||
| * Short date format e.g. '22/03/2019' (British Locale) produced by <#metdate format=ddddd> |
|||
* [[File:Badge vMx.png]] For some tag names can use "d": |
|||
** <#metdateyesterday format=d> e.g. '22/03/2019' (British Locale) |
|||
** <#yesterday=d> e.g. '22' returned |
|||
|- |
|||
|dddddd (6 characters long) |
|||
|D (as single character format) |
|||
|Displays the date using the format given by the Long Date format. |
|||
[[File:Badge vMx.png]]The MX 'D' parameter '''cannot be combined''' with any other parameters. |
|||
|e.g. '22 March 2020' (British Locale) |
|||
|- |
|||
|"D MMMM YYYY" |
|||
|D |
|||
|Long date format |
|||
|e.g.4 December 2009 |
|||
|- |
|||
|"D MMMM" |
|||
|M |
|||
|Day of month followed by Month name. |
|||
[[File:Badge vMx.png]] Note this is different output to '''format=%M''' or ''format=" M"'' (see [[#Month formats]]). Not applicable to USA locales. |
|||
| e.g. 22 July (English Locale) |
|||
|- |
|||
|"MMMM D" |
|||
|"MMMM d" if M alone does not work |
|||
| USA format of month before day of month |
|||
| e.g. July 4 (USA format) |
|||
|- |
|||
|TT |
|||
|T (as single character format) |
|||
|Displays the time using the '''Long Time format'''. |
|||
[[File:Badge vMx.png]] Note that this is a full time specifier and "T" is on its own as we are using a single character format. |
|||
|'09:47:56' (might not use colon in your locale) produced by |
|||
* [[File:Badge v1.png]]<#LastDataReadT format=TT> |
|||
*[[File:Badge vMx.png]]<#LastDataReadT format=T> |
|||
|} |
|||
=== Literals in scripts=== |
|||
If you are considering use of literals (such as a space) within a output format modifier in a script, then don't. Instead include whatever precedes the literal in a tag specification, then concatenate on the literal, and finally concatenate another tag specification for whatever is to follow the literal. An example to make this clearer is <code>$MXDateTime = '<#date format=yyyy-MM-dd>' . 'T' . '<#time format=hh:mm:ss>';</code>, which is written in PHP Hypertext Pre-processor format, the literal 'T' has been inserted by using two separate web tags surrounding the literal. The same approach applies if you wanted to replace that "T" with a space. (The explanation is that Cumulus (1 and MX) requires single quotes round a literal, but the script language requires any string to be enclosed in quotes, and double quotes are required by Cumulus round any complex specifier including any that include a space or other literal). |
|||
===Use of spaces=== |
|||
[[File:Badge vMx.png]]The first complication is that the parser that interprets time/date characters has two ways of interpreting a space character, depending on what immediately follows. In the tables, below, I have used a "%" in various places. In any of those places with a "%", you can insert a space instead, understanding that space is not a gap between format characters, but simply an alternative to "%" as a special character. To explain the two ways of interpreting spaces consider as an example '''<#TpressTH format=" h:mm tt">'''. In that example the two spaces are interpreted in two different ways! The "space" before "h" is treated as the same as "%", but as the ''mm'' and ''tt'' are multi-character symbols, that does insert a space after the minutes but before the am/pm. I discuss this later in [[#Migrating from legacy Cumulus 1 to MX]] section. |
|||
If you want spaces to appear between symbols in an output format: |
|||
* [[File:Badge v1.png]]Cumulus 1.x.y: Add double quotation marks around everything after equals sign if spaces are present anywhere after that equals sign. |
|||
* [[File:Badge vMx.png]] In MX, add double quotation marks around everything after equals sign if spaces are wanted as separators, but you also need to add single quotation marks around the included space. |
|||
** If the first symbol after equals sign is a single character modifier, then it has a different meaning depending on whether it is first specificatiion or is preceded by a "%" or "space" as in example above. If the first modifier inclues more than one letter, then it does not ever take a prefix. |
|||
** If the space appears after double characters and the symbol that appears after the space is also double characters (as in example above) the single quotes round the space are optional. |
|||
** If we have single character specifiers, then a space has to be enclosed in single quotes to mark it as a literal, not a modification of the subsequent single character. |
|||
Literals are discussed fully in the [[#Including literals in format parameters]] sub-section later. If we want to include other characters not to be interpreted by the date time parameter parser, and spaces, then both double and single quotes must be used, and the spaces must be within the single quotes. An example, that shows all the options that MX allows, with literals is <code> <#TpressH format="\a't 'h:mm' ' tt' <nowiki><small>on 'd/M/yyyy' </small></nowiki>'"> </code>. |
|||
=Some Extra Information= |
=Some Extra Information= |
||
Line 648: | Line 742: | ||
==Including literals in format parameters== |
==Including literals in format parameters== |
||
[[#Use of spaces]] explained how double quotes were needed for date/time output specifiers containing spaces. It briefly talked about including literals, and we will expand on that now. |
|||
As stated long ago on this page, if you are going to include spaces, or any other characters not defined in tables above, you must put double quotes round the whole specifier folowing the equals sign e.g. <tt><#YearTempHT format="hh nn"></tt> can be used with Cumulus 1.9.x. Consequently, you cannot include double quote characters in any other position (see [[Php_webtags#Web_tag_Complications| here for work-around]]). |
|||
Consequently, you cannot include double quote characters in any other position (see [[Php_webtags#Web_tag_Complications| here for work-around]]). |
|||
You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier. In MX, such single quotation marks should include the spaces round the additional literal text. |
You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier. In MX, such single quotation marks should include the spaces round the additional literal text. |
||
Line 692: | Line 788: | ||
== Migrating |
== Migrating from legacy Cumulus 1 to MX== |
||
If you have created any legacy cumulus template files, then in each template, you will need to do some editing. Everywhere a web tag appears with an output modifiers that is used to specify a date and/or time format, has to be edited before that template will work for MX. |
|||
If you use NOAA type report functionality, and choose to transfer your existing [[Cumulus.ini (Cumulus 1)|existing configuration file (cumulus.ini)]] to [[Cumulus.ini|MX]], you need to be concerned about how to represent a month. |
|||
Here are the main reasons: |
|||
If you have created any Cumulus template files, then every place in each template, where an output modifiers is used to specify a date and/or time format, has to be edited. For web tags it is much more complicated, simply because it is not just month we may be representing, and we might require only one specifier (being careful whether we use a standard or custom modifier) or we might want to specify a combination of modifiers (and we might want to add a space character or other literals). It is difficult to summarise, but here are some potential issues: |
|||
* the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps) |
* the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps) |
||
* the Delphi in legacy Cumulus is case insensitive, so for example "H" and "h" have the same meaning |
|||
* MX is case sensitive, and symbols mostly have different meanings when one symbol is used to when that symbol is used with others, so for example "H" and "h" have different meanings, and if not used with other symbols will need to be preceded with a "%" to have same meaning as they have in combination with other symbols |
|||
* In the legacy cumulus, a symbol like "d" has the same meaning for any tag |
|||
* MX is inconsistent, a symbol like "d" changes its meaning depending on the tag it is used with (e.g. the script conditional ''''<#metdateyesterday format=d>' == '<#yesterday format=d)>'''' will never be equal as the LHS returns a full date and the right hand side returns day of month only) |
|||
* the symbols used for representing such modifiers as minutes, month, am/pm, are different between C1 and MX. |
|||
* MX introduces the concept of escaping characters (a '''\''' placed before a character can be either a control sequence or an instruction to display the character) |
* MX introduces the concept of escaping characters (a '''\''' placed before a character can be either a control sequence or an instruction to display the character) |
||
* In the legacy Cumulus, a space is a gap between characters |
|||
* MX is inconsistent e.g. '''format=d''' gives a different result depending on the tag it is applied to (e.g. the script conditional ''''<#metdateyesterday format=d>' == '<#yesterday format=d)>'''' will never be equal as the LHS returns a full date and the right hand side returns day of month only) |
|||
* |
* In MX, a space must be within a literal, as a space before a symbol has the same effect as "%", (it changes the interpretation of a modifier character). |
||
'''Confused even more now?''' I'm not surprised, but maybe some examples will help |
'''Confused even more now?''' I'm not surprised, but maybe some examples will help. |
||
=== Examples === |
=== Examples === |
||
Line 725: | Line 826: | ||
** but alternatively you can escape each verbatim character with a backslash as prefix (Cumulus MX). |
** but alternatively you can escape each verbatim character with a backslash as prefix (Cumulus MX). |
||
* You may need to use both single quotes and back slashes in some format specifiers, depending whether the characters you want to include can be interpreted as control characters (yes, backslash is also used to escape control characters, so backslash will NOT work for some characters such as those in "on" and "at" [\n will produce new line not the letter n, \t will produce a tab not the letter t]), consequently for some characters you must use the literal approach to include them in your format. |
* You may need to use both single quotes and back slashes in some format specifiers, depending whether the characters you want to include can be interpreted as control characters (yes, backslash is also used to escape control characters, so backslash will NOT work for some characters such as those in "on" and "at" [\n will produce new line not the letter n, \t will produce a tab not the letter t]), consequently for some characters you must use the literal approach to include them in your format. |
||
== Past history for this page== |
== Past history for this page== |
||
Line 736: | Line 836: | ||
== Forum reference == |
== Forum reference == |
||
Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=17888 Cumulus MX forum]. The table there was based on the table that |
Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=17888 Cumulus MX forum]. The table there was based on the table that appeared in this Wiki when only the original Cumulus existed, so it was designed to help people migrate to his MX beta, it was not intended as a definitive list of what modifiers were available for MX (Steve instructed people to look them up on some Microsoft sites). |
||
The subsequent comments in the forum suggested his layout got people confused. Most of that confusion came in two circumstances: |
The subsequent comments in the forum suggested his layout got people confused. Most of that confusion came in two circumstances: |
||
*When someone wanted to use one date or time modifier on its own |
*When someone wanted to use one date or time modifier on its own |
||
*When someone who had been using Cumulus 1 swapped to MX and wanted to replace a combination of output modifier characters |
*When someone who had been using Cumulus 1 swapped to MX and wanted to replace a combination of output modifier characters that was not explicitly shown in his table. |
||
That all comes from the fact that when a MX modifier consists of a single character it can mean something different to when it appears with other characters. |
|||
In Cumulus 1, "m" or "M" had two meanings depending whether it was combined with "H" or "h" (when it represented minutes), or on its own or with any other code (when it represented month). But for Cumulus 1, there is no other case where it matters what context a modifier is put in by the use of other modifiers, and no other modifier takes more than one meaning. |
|||
In MX it is much more complicated, to take a few examples "D", "H", "M" represent different items on their own to what they represent when combined with other characters. That other character can be as simple as using a space or a "%" to modify the meaning of the character. |
|||
That all comes from the fact that when a MX modifier consists of a single character it can mean something different to when it appears with other characters. In Cumulus 1, "m" or "M" meant something different when it was combined with "H" or "h" (when it represented minutes), but in all other contexts it represented month. But for Cumulus 1, there is no other case where it matters what context a modifier is put in by the use of other modifiers, and no other modifier takes more than one meaning. |
|||
Looking at the tables, now included above, you can see "G" is used on its own because it represents a full date-time specifier. "D" is similarly used on its own represents the long date format. If we only want the day of month number we must use "%d" to avoid the meaning of short date format that "d" on its own represents. |
|||
In MX it is much more complicated, to take a few examples "D", "H", "M" represent different items on their own to what they represent when combined with other characters. That other character can be as simple as a space or a "%" which modify the meaning of the character. |
|||
If we want the typical Cumulus date-stamp of day of month number and month, then we have two choices, because both "d M" and "M" will work. This illustrates how "M" has a different meaning on its own and with another modifier. |
|||
Hopefully, the way that information is now presented on this page makes any use of parameters for web tags much easier now. |
Hopefully, the way that information is now presented on this page makes any use of parameters for web tags much easier now. |
Revision as of 20:17, 22 June 2022
This Wiki page applies to both flavours of Cumulus currently available.
Introduction
Put simply, a Cumulus tag is included to indicate where Cumulus should insert values when it processes the command/file that quotes the tags.
The general format for every Cumulus tag is: <#tag_name [optional input selection parameters] [optional output modification parameters]>
This page is about those (generally optional) parameters used for modifying Cumulus tags.
- An input parameter is used where the same tag name can represent a value for a number of different past time instants.
- Each of those past time instants is represented by a different value for the input parameter.
- So a combination of a tag name and input modification parameter lets Cumulus select the value you want to see.
- Whether a particular tag name can use input modification parameters will depend on both which tag name has been chosen, and which Cumulus release you are using.
- An output parameter is used when a particular tag name can be fed through a process that alters how the output is shown
- Tag names representing integer values cannot have their output format modified
- Internally Cumulus handles numbers in binary, for numbers that have an integer and a decimal part, there is no exact conversion between the way the decimal part of a number is stored in binary, and the way the decimal part (after the decimal comma/point) appears on output. Therefore, non-integer numbers have to be rounded, and there are some output parameters that modify the output:
- You can modify the number of decimal places shown for some tag names
- With Cumulus MX, you can modify whether number is output with a decimal comma, or a decimal point
- Tag names representing time intervals, clock times, dates or representing both time/date for an extreme record, may have a fixed format that cannot be changed, or may be able to be processed through a date-time routine that changes how either time or date or both are output
All this parameter information was originally on Webtags page, but has been moved to this separate page as part of an attempt to make the Wiki easier to read by shortening pages.
Legacy software
The legacy Cumulus 1 software can only use tag names, and whatever parameters are permitted, within a file. Steve Loft used Cumulus Template File for a file that used tags:
- The legacy Cumulus 1 software, and MX releases up to release 3.9.7 - build 3107, provided a selection of template files (see Customised templates that produced 'standard' web pages, see "IncludeSTD" here.
- A Cumulus user could specify an alternative web page,
- A Cumulus user could transfer data to a web server using a JavaScript Object Notation (.json) file
- A Cumulus user could transfer data to a web server using a JavaScript file,
- A Cumulus user could transfer data to a web server using a PHP script file, or
- A Cumulus user could transfer data to a web server using a eXtensible Mark-up Language (XML) file.
For information on how to process, and upload, non-standard files, see "ExtraProcessxx".
Cumulus MX software
MX can process template files, using Extra web file settings, but tag names (and input/output parameters as permitted) can also be used in:
- standard websitedataT.json template file, or a tailored file that is processed into same destination file
- on demand using Cumulus MX Local API
- standard or custom interval use of "My SQL Connector"
- Customised MQTT commands
Rules
Tag names and parameters must obey certain rules.
Case sensitivity for tag names
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in lists of tag names.
Case sensitivity for parameters
The optional input modification parameters always use lower case, so please type them exactly as shown in the section below.
The content of optional output parameters are mostly case insensitive when used in legacy Cumulus 1 (a few are case sensitive as explained in #For the legacy software. For Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.
Tag names and Parameters available
Input modification Parameters
Most web tags do not require any input parameters. Luckily, where they are needed, it is quite simple to use them, see table below.
- <#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
Tag names | Values Available | Input Modification Parameters | Introduced | Examples | Description | |
---|---|---|---|---|---|---|
Tag names listed at Table of Recent History tag names available (see Recent history page for explanation) | One value for each minute in last 7 days | * d specifies number of days ago,
|
Cumulus 1.9.3 beta build 1033 (remain available in MX) | Examples for outside temperature:
| ||
All values supplied for parameters must be whole numbers.
|
monthly all-time extreme records tag names | These tag names represent extreme record values (and corresponding time-stamps) for any particular month (1 =January, and so on, to 12 =December) in all years | Optional input parameter is mon=N where N is the index of the month in which the extreme record occurs considering all years | Cumulus 1.9.3 beta build 1033 (remain available in MX) | * <#ByMonthDewPointH mon=3> is highest monthly dew point for month of March considering all years, and <#ByMonthDewPointHT mon=3> is the related time and date.
|
* If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used.
NOTE: Use without an input parameter in "MySQLConnect", "MQTT", or a template file, and then you don't need to rewrite the instruction when current month changes. If processed at rollover, the current month will change on first day of a month, and so not relate to month that has just finished. |
Only <#SunshineHoursMonth> and Only <#SunshineHoursYear> | Values available for current month/year, and for past month/year | Omit input modification parameter to get value for current month/year. Alternatively include one of the following options:
|
MX release 3.12.0 | Monthly examples:
Yearly examples:
|
Returns the sunshine hours total in selected period
(You need a sensor to be monitoring this throughout selected period) |
Output modification parameters availability by tag name
Each tag name falls into one of these 3 types:
- Some tag names have a fixed output format (so they ignore any output format parameters, although obviously better not to specify any)
- Some tag names always need an output format specifier
- The majority of tag names have a default output if there is no output format modifier, but accept either one or two output format parameters, allowing you to change what they output.
This Wiki page does not include a table showing which tags belong to which type, simply because it is dependent on which Cumulus release you are running. An attempt to indicate some general guidance has been included on another discussion about applicability Wiki page, but contributors need to update that page and start listing tag name and release specific information.
Output modification parameters available in legacy Cumulus 1
Your options are described under the following subheadings:
- #Rounding to a specific number of decimal places
- #Multiple Output Format Modifier parameters for times and dates
Additional output modification parameters that are only available for MX users
offers those listed above for Cumulus 1, plus:
- #Output Modification Parameter for changing any decimal comma into a decimal point
- #Controlling the number of decimal places
- #Two Output (format modifier) parameters for decimal places
- #Truncation of unwanted decimal places
Documentation for Output modification parameters
Use the links above to skip to the particular parameters that you wish to use.
Output Modification Parameter for changing any decimal comma into a decimal point
Note that Cumulus software never uses a comma for separating off thousands, and there is no way to make it output numbers above 999 with a space or comma to separate out thousands.
If the tag name represents a real number with integer and decimal parts, then Cumulus by default will output that number using whatever your locale defines as the separator character (decimal comma or decimal point). The legacy Cumulus 1 provided a few derivatives where a prefix of "RC" before tag name as in <#RCtag_name>
could force the output to use a decimal point (regardless of locale), that option remains available in MX for forward compatibility.
In Cumulus MX (only), you can alternatively use an output modification parameter in format <#tag_name rc=y> to select whether the output should use decimal comma or decimal point:
- From beta release 3.0.0, build 3047 (3 February 2019), up to and including release 3.5.3, only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge)
- From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers.
- From release 3.10.5 onwards (29 March 2021), the use of <#tag_name rc=n> became also possible, to ensure decimal comma shown when locale specifies it
Parameter | Explanation | Example |
---|---|---|
rc=n | This is the default, so does not need to be specified. The output from the web tag will use either decimal comma or decimal point as specified by the locale in which MX is running
For more information about how the computer determines whether decimal commas is your default, see #Locale section later. |
Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts |
rc=y | the attribute rc takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value. | <#tempYH rc=y> will return yesterday's highest temperature as integer part then full stop then decimal part, regardless of local |
Why would you want to remove decimal commas? Well because the JavaScript language (and some other languages) cannot understand decimal commas, and MX has several scripts written in this language, equally some third party alternative web pages rely on ajax to update them (and Ajax uses JavaScript).
Controlling the number of decimal places
If the tag name represents a real number (with both integer and decimal parts) then there are a number of ways to control the number of decimal places:
- Cumulus 1.x.y: dp=i rounds output to number of decimal places specified by "i"
- All MX releases: dp=i rounds output to number of decimal places specified by "i"
- <#tag_name tc=y> truncates output, display as integer, no rounding, simply ignoring all decimal places
If the tag name gives an output that is defined as text, or as an integer, then none of these can be used. It depends upon which release you are using whether a particular "real number" tag name will accept any of the above output modification parameters, gradually Cumulus has allowed more and more of its output to take an output format modifier that allows people to control number of decimal places shown.
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2.
Weather stations report values as integers. Cumulus converts these to the user's desired units, and that processing can add decimal places, as it may involve division by a factor of 10, or multiplication by a conversion factor. Obviously, the sensor has a particular accuracy, and this conversion process can introduce additional errors, as can the storing in binary, Cumulus generally (not in every case) stores to a precision that would generally give about 24 significant figures when expressed in base 10.
The handling of each tag name is coded individually, so there are no simple rules for defining the default number of decimal points that will be shown by default. In general, Cumulus does consider the units chosen for outputs. As Cumulus has been developed, people have commented that these defaults do not reflect the precision of their instrumentation (weather stations used with Cumulus tend not to have the accuracy of those used by meteorologists, or are not re-calibrated as often).
From release 3.12.0, you can set the default number of decimal places to output for all derivatives of temperature, pressure, etc. by advanced settings. Those settings can force output as integers, in which case the parameter for controlling number of decimal places have no effect.
Two Output (format modifier) parameters for decimal places
Depending on tag name and release you are using, there may be two ways to control decimal places:
- <#tag_name dp=i> and
- <#tag_name tc=y>
Rounding to a specific number of decimal places
Use dp=i (the value i following the attribute dp is an integer, it represents how many decimal places you want for the output you see):
- Cumulus 1.x.y: only <#latitude dp=i> and <#longitude dp=i> are able to be output with "i" denoting number of decimal places, e.g. <#latitude dp=5> gives "59.24250".
- Depends on MX release:
- From beta releases (3.0.0) onwards, <#latitude dp=i> and <#longitude dp=i> were able to be output with "i" decimal places
- But this output modification parameter could not be applied to any other tags in the MX beta.
- MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>).
- Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234"
- From release 3.10.5 (which did a big rewrite of web tag handling) any tag names that output as real numbers
- From beta releases (3.0.0) onwards, <#latitude dp=i> and <#longitude dp=i> were able to be output with "i" decimal places
Truncation of unwanted decimal places
tc=y is the truncation parameter, the attribute tc takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>.
This output format modifier is only available in MX:
- If you are using an early release of MX, you will need to research whether this is available for particular tag names
- Later releases of MX implement this for any tag that by default outputs decimal places.
Note, truncation by MX converts real numbers to integers. There is no option to truncate to one decimal place, Airports are expected to report air field level (QFE), and sea level (QNH), pressures truncated to one decimal place rather than rounded.
Multiple Output Format Modifier parameters for times and dates
Output modification parameters for times and dates are highly complicated!
To start with a simple example, suppose you want date/time in ISO 8601 format:
- This means, something like 2019-02-28 06:59:05.
- Take the tag name (from tables on Webtags page)
- Next check in #Which tag names take date/time output formatting modifiers to see if that tag accepts both time and date modifiers
- If your tag name does accept both date and time modifiers, simply modify the web tag as shown here
<#tag_name format="yyyy-MM-dd HH:mm:ss">
where tag_name is set from step 1, but all the rest is typed as shown. - To explain each element in that format value, look in #Time formats, #Year formats, #Month formats, #Day formats, #Use of spaces, #Including literals in format parameters.
Should you want a different date/time format, then the sub-sections just referenced should help you to select a different arrangement, although there are some more options in #Date formats.
Which tag names take date/time output formatting modifiers
When counted some time ago MX already offered a thousand different tag names.
There are a few time-related tag names labelled as being fixed format, that means any time/date output modifiers you might try would be ignored.
Some tag names, although it can be hard to tell which, report durations. You can use time modifiers to change how these are reported. Examples include <#daylength format=H:mm:ss> which reports day length and <#MonthDailyRainHD format=H:mm> which reports how much of a day it was raining.
Time modifiers can also be used to change the way that clock times are reported, you might only want the hour, or you might (if resolution is available) want to also see seconds. The webtags page has columns headed "Time" to clearly identify all tag names that report clock times.
There are some tag names (e.g. moon rise) that relate to an event that does not happen each Earth day, so those tags have to be able to report "--:--", and you cannot modify their output. Equally, many of the tag names that describe extreme records for this month/year/all-time are not defined until the respective period reaches its second day, so again those tags may output hyphens and so any modification parameters will be ignored. For example, highest temperature range in month/year has been coded in Cumulus to report "--" for value, and "--:--" for time, on the first day of that period (because there is only a partial day to consider you might not yet have experienced a true maximum and a true minimum), so modifying the time output can only be done on subsequent days.
It is not practical to indicate which time/date modifiers are accepted on a tag by tag basis. It would involve a lot of repetition. Instead, the following table, explains much more simply, which web tags will accept time and/or date output modifiers:
Cross-reference to table on web tag names page | Tag names that accept only time output modifiers | Tag names that accept only date output modifiers | Tag names that accept both time and date output modifiers |
---|---|---|---|
Any tag names that don't report times nor dates | None | None | None |
Webtags#No_Commas | None | None | None |
Webtags#Date_.26_Time, Webtags#Day/Night/Sun/Moon | Only <#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk> | Only <#LatestErrorDate>, <#date> (but no others) | Only <#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT> |
Webtags#Today, Webtags#Yesterday | Any tag name in "Time" column of linked table | None | None |
Webtags#Monthly, Webtags#Yearly | Those tag names in "Time" column of linked table in first column that represent spot value extreme records. For notes see ~ below this table | Any tag name in "Date" column of linked table in first column that represent either daily extremes or spot value extreme records. For notes see † below this table | None of the tag names. For explanation see the ^ below this table |
Webtags#All_Time, Webtags#Monthly_All_Time_Records | None (all tag names combine both time and date) | Those tag names in "Date/Time" column of linked table that represent daily extremes | Those tag names in "Date/Time" column of linked table that represent spot value extreme records |
Webtags#Davis | None | <#StormRainStart> only | None |
~ For rainfall, only <#LastRainTip> can have output modifiers added to report a clock time. † Daily extremes (e.g. wettest day <#MonthDailyRainHD>, and temperature ranges <#MonthHighDailyTempRangeD>) have no time tag. ^ For the monthly and yearly web tags, the date and time are in separate tag names. It is not possible to get both time and date out of either tag name.
Locales
The default format for many tag names reporting date and/or time is dependent on the locale you are using for running Cumulus (1 or MX).
The effect of some output format modifiers is also dependent on locale.
For Microsoft Windows Operating Systems, a Language is defined within the "Region" page of the Settings app. That should be sufficient for the legacy software that uses Delphi. However for MX date and time formats within Windows Operating System, you must use the older Control Panel (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") because it is only there that you can adjust all the defaults used by .NET.
For MX running on most operating systems (other than Microsoft Windows), type locale
to see the default locale that will be adopted when mono-complete is installed as MX will, by default, take locale setting from Mono. When you start MX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at MX_on_Linux#Parameters. For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8.
The available locales on your computer in Linux are listed by locale -a
. For example, the Russian locale would be selected as the one your computer uses for the current session only by using LANG=ru_RU.utf8
either typed into a terminal session before you start MX, or used as a parameter (preceded by "-") as you start MX interactively.
For permanently changing the locale used by your system, the instructions vary considerably according to the kernel used in your operating system, so you need to look up the instructions for yourself. However, if you have a graphical user interface, such as the full Raspberry Pi Operating System provides, you might have a configuration command in terminal mode and a configuration app accessed (within Preferences) from the "Raspberry" key on the official keyboard. For the Raspberry Pi, please read Raspberry Pi computer page for more details.
Time zones
Before I explain what time/date output modifiers can do, something they can't do.
All web tag outputs are in local time, except <#timeUTC>.
Cumulus 2 internally stored all date/times in UTC, and the development of MX is planned to attach UTC date-times to all data although (at time of typing this) this is not yet implemented so MX maintains compatibility with Cumulus 1 legacy software.
In most MX releases, you can use a script to convert a time to UTC. This is not the place to tell you how to write the script, but taking time of highest pressure today as an example, you would use <#TpressTH format=Hh:mm> and <#TpressTH format=zzz>, the first gives hours and minutes in your local time, and the second gives the offset that needs to be applied to that time to convert it to UTC.
Time resolution
For the legacy software, there may be no point in asking for seconds, as Cumulus 1 did some actions at one minute intervals. For MX, it depends on which tag name you are using whether it supports seconds (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute).
If Cumulus obtained archive data, as part of the catch-up process it can do when it restarts, any time-stamps for that historic period can only be the time of a particular archive record, so that might be every half an hour, but not aligned precisely with hour changes.
Dependency on Cumulus flavour
You have to change all date/time formatting when moving from the original (legacy) Cumulus to MX.
All the tables explaining what is used in each flavour for each type of output, both by including separate columns for each flavour, and by giving examples in each flavour.
For the legacy software
I deal with this first, just because it is simple!
From version 1.9.1, most web-tags that report any form of time or date will accept an optional 'output format' parameter (we have already seen whether this can only affect time, only affect date, or both).
The legacy Cumulus uses Delphi to interpret the output modifiers:
- For most modifiers, a particular character produces the same output regardless whether the output modification specifier is in capitals or lower-case
- There is an exception, the case you use for any am/pm output format modifiers determines the case that is output.
- In general, the context of a modifier does not affect the output it produces
- Again, there is an exception, "m" or "M" has two different meanings (minutes or month) depending on context.
The complications with MX
The *.ini Files in MX have adopted the ISO 8601 date format where year comes first (yyyy-MM-dd), although for compatibility with the legacy software, any lines in these files ported from Cumulus 1 retain their day before month before year format until they are updated. Most dates reported by web tags derive their content from entries in these files.
The *.txt Files have so far stuck to date formats as used in the legacy definitions, the intention to swap to ISO format for the .txt files from September 2020, having been postponed to an unannounced future date, because of the continuing need for compatibility while there is use of the legacy software by a significant number of users.
For Cumulus MX output formatting, the date and time modifiers are complicated by the fact that the same character can have 4 different meanings depending on its case (capital letter or lower-case letter), and depending on whether it is on its own (standard format) or with another modifier (custom format). One more confusion, Microsoft have reversed the use of capital 'M' and lower case 'm' from the standard used very widely, and you may have got to know. Sounds confusing? Well it is complicated.
Consider context first:
- <#tag_name format=x>
- If the x in the above general syntax is a single character, it represents a standard format code
- The standard characters for dates and times are defined at standard-date-and-time-format-strings
- <#tag_name format=xyz>
- If the xyz in the above general syntax is replaced by two or more characters, it becomes a custom format code (combinations of characters, or single characters prefixed by %)
- The custom characters for dates and times are defined at custom-date-and-time-format-strings
Consider case next:
- Cumulus MX (when running on Windows) uses the .NET software which is provided as standard by Microsoft Windows.
- ".NET" was originally operating system independent, later only Microsoft Windows specific components were included, but since November 2020 ".Net" is used for an operating system independent version that originally Microsoft issued under another name!
- (actually it is possible to install and run "Mono" in Windows Operating Systems).
- If Cumulus MX is running on any Linux distribution (including Raspberry Pi Operating Systems) or Mac OS X, or any other device that uses an UNIX derived operating system, then MX uses Mono software for same purposes. (MONO is a operating system independent version of .NET, although they are developed independently, they have common origins).
Time formats
Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table. As explained earlier, time formats can be used with both time-duration reporting and clock time reporting.
In some rows of this table, square brackets [] indicate optional items, they are included just to make it clearer how items can be combined in a single output parameter. If you want to include what is shown in square brackets you don't type the square brackets e.g. <#LastDataReadT format="h:nn am/pm">
Year formats
These are the simplest output format modifiers. We can only choose from 2 options, and because both involve more than one character their context does not matter. Although the legacy Cumulus will accept upper case as meaning same as lower case, it is simplest if we just show the lower case options that are mandatory for MX:
Specifier | Displays | Example |
---|---|---|
yy | Displays the year as a two-digit number (00-99). | 19 produced by <#LastDataReadT format=yy> |
yyyy | Displays the year as a four-digit number (2000-9999). | 2009 produced by <#LastDataReadT format=yyyy> |
Month formats
All locales offer both numerical and alphabetical formats for representing months.
- In the following table "MMM" is shown as producing short month name.
- What language is used, and how many characters appear, depend on what is set up for your language in your settings (by default or by you changing your settings)
- In Australian locale, this would output 4 characters representing a month abbreviation that runs from "Jan." to "Dec."
- In British English (UK) locale, abbreviations do not incude a full stop, so output is a 3 letter abbreviation that starts with "Jan" and runs to "Dec"
- In the following table "MMMM" is shown as producing the full name for a month
- The output you get will depend on the language defined in your locale
- In all English based locales, the output will be in the range "January" to "December"
CAUTION: Cumulus MX has yet another complication, a web tag can return different months depending on whether the output modifier for month is used with, or without, an output modifier for day. Take two examples <#metdateyesterday format=yyyy-MM-dd>
and <#metdateyesterday format=yyyy-MM>
, these can produce different months when processed by MX on same day at near enough same time! Let us assume the first is reporting (in a particular year) the first day of June, the second would report the month of May in same year!
Delphi Specifier for Cumulus 1.9.x | Mono/.NET Specifier for Cumulus MX | Displays | Example |
---|---|---|---|
M (or m) | %M | Displays the month as a number without a leading zero (1-12).
|
2 |
MM (or mm) | MM | Displays the month as a number with a leading zero (01-12). | '03' produced by <#LastDataReadT format=MM> or <#metdate format="MM"> |
MMM (or mmm) | MMM | Displays the month using the strings defined for short month name in the Locale. | 'Jun.' or 'Jun' produced by <#metdate format="MMM"> (varies depending which English locale as explained before table) |
MMMM (or mmmm) | MMMM | Displays the month as a full name using the strings appropriate to the Locale. | 'June' produced by <#metdate format="MMMM"> (English locale) |
Day formats
All locales offer both numerical and alphabetical formats for representing a day.
Again, there are extra complications with MX, the "d" modifier is not shown because it is inconsistent, the format it returns depends on which tag name it is used with - see #Date formats table later! For some tag names it returns just "day of month" (like "%d"), for others it returns the full "Short date format" (like "ddddd")!
The table below is the definitive guide to how to ensure you do specify just the day part of any date specifications.
}Delphi Specifier for Cumulus 1.9.x | Mono/.NET Specifier for Cumulus MX | Displays | Example |
---|---|---|---|
d (single character) | %d | Displays the day as a number without a leading zero (1-31).
Note that Cumulus MX requires a ' ' (space), '%' or another modifier to be included, as 'd' on its own is inconsistent - see #Date formats table). |
27 produced by: |
dd (2 characters long) | dd | Displays the day as a number with a leading zero (01-31). | 07 produced by <#metdate format="dd"> |
ddd (3 characters long) | ddd | Displays the day as an abbreviation (in Australian will output "Sun." to "Sat.") using the strings appropriate to the Locale (see note for month abbreviation). | 'Wed' produced by <#metdate format="ddd"> (UK English locale) |
dddd (4 characters long) | dddd | Displays the day as a full name (Sunday-Saturday) using the strings appropriate to the Locale. | 'Friday' produced by <#metdate format="dddd"> (English locale) |
Date formats
The #Year formats, #Month formats, and #Day formats listed above can be combined to make up a date output modifier, but there are some other modifiers available that can produce whole dates.
#Locales will define a Short Date Format and a Long Date Format. You will see references to those in the table below explaining available output format modifiers, for example the single character output format modifier (G or c) listed at the start of the table below.
If you are in the USA, Cumulus will only use your month first date internally for the start date (see Cumulus.ini (Cumulus 1) and Cumulus.ini (Cumulus MX)), that format will not be used in any files in the data sub-folder, but you can see your preferred format in the settings pages, in the extreme record editing pages, and by default as an output from many (not all) web tags. For any web tags that do permit use of output date modification format parameters, you can can combine any month specifier, with any day of month specifier, in that order, to get an output where the month appears first (see example in table below).
Please could an American contributor please check if the "M" modifier works for their locale as shown and update the table below if necessary, and edit this comment into a confirmation.
Delphi Specifier for Cumulus 1.9.x | Mono/.NET Specifier for Cumulus MX | Displays | Example |
---|---|---|---|
c | G (as single character format) | Displays the date using the format given by the Short Date format, followed by the time using the format given by the Long Time format. The time is not displayed in Cumulus 1 if the date-time value indicates midnight precisely. | '22/03/2019 09:47:25' produced by <#time format=c><#time format=G> |
ddddd (5 characters long) | ddddd (5 characters long) | 'ddddd' will output the date using the format given by the Short Date format.
'd' (when on its own, without space or '%' prefix) may or may not work, it displays inconsistent behaviour as its effect depends on the tag name (sorry, there is no definitive list from the MX author specifying effect by individual tag name) with which it is used (you will need to experiment for yourself and compare with the two examples). |
* Short date format e.g. '22/03/2019' (British Locale) produced by <#metdate format=ddddd> |
dddddd (6 characters long) | D (as single character format) | Displays the date using the format given by the Long Date format.
The MX 'D' parameter cannot be combined with any other parameters. |
e.g. '22 March 2020' (British Locale) |
"D MMMM YYYY" | D | Long date format | e.g.4 December 2009 |
"D MMMM" | M | Day of month followed by Month name.
Note this is different output to format=%M or format=" M" (see #Month formats). Not applicable to USA locales. |
e.g. 22 July (English Locale) |
"MMMM D" | "MMMM d" if M alone does not work | USA format of month before day of month | e.g. July 4 (USA format) |
TT | T (as single character format) | Displays the time using the Long Time format.
Note that this is a full time specifier and "T" is on its own as we are using a single character format. |
'09:47:56' (might not use colon in your locale) produced by |
Literals in scripts
If you are considering use of literals (such as a space) within a output format modifier in a script, then don't. Instead include whatever precedes the literal in a tag specification, then concatenate on the literal, and finally concatenate another tag specification for whatever is to follow the literal. An example to make this clearer is $MXDateTime = '<#date format=yyyy-MM-dd>' . 'T' . '<#time format=hh:mm:ss>';
, which is written in PHP Hypertext Pre-processor format, the literal 'T' has been inserted by using two separate web tags surrounding the literal. The same approach applies if you wanted to replace that "T" with a space. (The explanation is that Cumulus (1 and MX) requires single quotes round a literal, but the script language requires any string to be enclosed in quotes, and double quotes are required by Cumulus round any complex specifier including any that include a space or other literal).
Use of spaces
The first complication is that the parser that interprets time/date characters has two ways of interpreting a space character, depending on what immediately follows. In the tables, below, I have used a "%" in various places. In any of those places with a "%", you can insert a space instead, understanding that space is not a gap between format characters, but simply an alternative to "%" as a special character. To explain the two ways of interpreting spaces consider as an example <#TpressTH format=" h:mm tt">. In that example the two spaces are interpreted in two different ways! The "space" before "h" is treated as the same as "%", but as the mm and tt are multi-character symbols, that does insert a space after the minutes but before the am/pm. I discuss this later in #Migrating from legacy Cumulus 1 to MX section.
If you want spaces to appear between symbols in an output format:
- Cumulus 1.x.y: Add double quotation marks around everything after equals sign if spaces are present anywhere after that equals sign.
- In MX, add double quotation marks around everything after equals sign if spaces are wanted as separators, but you also need to add single quotation marks around the included space.
- If the first symbol after equals sign is a single character modifier, then it has a different meaning depending on whether it is first specificatiion or is preceded by a "%" or "space" as in example above. If the first modifier inclues more than one letter, then it does not ever take a prefix.
- If the space appears after double characters and the symbol that appears after the space is also double characters (as in example above) the single quotes round the space are optional.
- If we have single character specifiers, then a space has to be enclosed in single quotes to mark it as a literal, not a modification of the subsequent single character.
Literals are discussed fully in the #Including literals in format parameters sub-section later. If we want to include other characters not to be interpreted by the date time parameter parser, and spaces, then both double and single quotes must be used, and the spaces must be within the single quotes. An example, that shows all the options that MX allows, with literals is <#TpressH format="\a't 'h:mm' ' tt' <small>on 'd/M/yyyy' </small>'">
.
Some Extra Information
Having covered the basics of both date and time modifiers above, it is time to talk about incorporating other information in an output modifying date/time format specification.
Basically, we can include literal characters, and we can include HyperText Manipulation Language tags, in our specifiers.
Finally, there will be a section on migrating from the legacy Cumulus to MX and how to modify the web tags in your templates to keep them working.
Including literals in format parameters
#Use of spaces explained how double quotes were needed for date/time output specifiers containing spaces. It briefly talked about including literals, and we will expand on that now.
Consequently, you cannot include double quote characters in any other position (see here for work-around).
You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier. In MX, such single quotation marks should include the spaces round the additional literal text.
- For example, the word "on" contains the character "n", which for Cumulus versions 1.9.1 to 1.9.4 will be interpreted as a time format modifier unless you put it into single quotation marks. Example of valid Cumulus 1 syntax: <#TtempH format="'at' hh: mm 'on' dd / mm / yyyy">.
- You can include HTML tags (but they cannot have any attributes because both single and double quote characters have defined meanings) and special characters as quoted text within the 'format' parameter.
Example of valid syntax: <#TapptempH format="'at 'h:nn' 'am/pm '<small>on' d/m/yyyy'</small>'">.- See next sub-section for more information on incorporating HTML if you are using MX.
Note for MX - you can use single quotation marks round spaces and text (e.g. ' on '), but you can also use '\' as escape character (e.g. for 'on' use \o\n). However for at the only alternative is \a't' because the character t has another meaning and escape followed by a "t" i.e. "\t" becomes a tab!
Using HTML tags within format parameters (available in MX only)
Example using a class to change the look of part of the output
<#TapptempH format="dd' 'MMM' 'yyyy'<span class=\'xx\'> at 'HH:mm'</span>'">
the output from this will look like 04 Dec 2018 at 10:12
Note where the quotes are, and where you need to use '\' escape characters.
Example using HTML tags
<#RecentTS d=2 format="h:mm' 'tt'<small>on' d/M/yyyy'</small>'">
This puts the date in a smaller font than the time
Migrating from legacy Cumulus 1 to MX
If you have created any legacy cumulus template files, then in each template, you will need to do some editing. Everywhere a web tag appears with an output modifiers that is used to specify a date and/or time format, has to be edited before that template will work for MX.
Here are the main reasons:
- the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps)
- the Delphi in legacy Cumulus is case insensitive, so for example "H" and "h" have the same meaning
- MX is case sensitive, and symbols mostly have different meanings when one symbol is used to when that symbol is used with others, so for example "H" and "h" have different meanings, and if not used with other symbols will need to be preceded with a "%" to have same meaning as they have in combination with other symbols
- In the legacy cumulus, a symbol like "d" has the same meaning for any tag
- MX is inconsistent, a symbol like "d" changes its meaning depending on the tag it is used with (e.g. the script conditional '<#metdateyesterday format=d>' == '<#yesterday format=d)>' will never be equal as the LHS returns a full date and the right hand side returns day of month only)
- the symbols used for representing such modifiers as minutes, month, am/pm, are different between C1 and MX.
- MX introduces the concept of escaping characters (a \ placed before a character can be either a control sequence or an instruction to display the character)
- In the legacy Cumulus, a space is a gap between characters
- In MX, a space must be within a literal, as a space before a symbol has the same effect as "%", (it changes the interpretation of a modifier character).
Confused even more now? I'm not surprised, but maybe some examples will help.
Examples
- Examples related to case selection
- In Delphi, "nn" means "minutes" for Cumulus 1, but "minutes" is "mm" for .NET or MONO in Cumulus MX.
- The hour in 24-hour format with leading zero, in non case sensitive Delphi (Cumulus 1) 'HH' or 'hh' would be treated as same, but in .NET or MONO it must be "HH" (Cumulus MX).
- The hour in 24-hour format without leading zero, in non case sensitive Delphi (Cumulus 1) 'H' or 'h' would be treated as same, but in .NET or MONO it must be "%H" (Cumulus MX).
- For 12-hour specifiers, please see the table, as this is far more complicated.
- You might be put off by references within .NET and MONO (Cumulus MX) to single/standard characters and custom modifiers, the following 3 examples may add clarity:
- For example, <#MonthTempHD format="d"> is a single character format modifier, therefore the 'd' acts as a standard modifier, and causes for a date of 22 July 2014 for the highest temperature in the month to be returned in the standard short date format e.g. '22/07/2014' (exact contents for any one date vary by locale).
- Similarly, <#MonthTempHD format="M"> is a single character format modifier and therefore the 'M' acts as a standard modifier and causes the date for the highest temperature in the month to be returned in the standard day and month format e.g. '22 July' (exact contents for any one date vary by locale).
- Whilst <#metdate format="d M"> is not a single character format modifier and therefore both the 'd' and the 'M' are interpreted as custom modifiers and cause the current date to be returned as a digit(s) for the day and a digit(s) month (in a without leading zeroes format) e.g. '6 7' would be returned for 6 July.
- Alternatively, <#MonthTempHD format="%d"> is NOT a single character format modifier, therefore the 'd' acts as a custom modifier, and causes a date of 22 July 2014 for the highest temperature in the month to be returned as the day of the month only '22' in all locales.
- Similarly, <#MonthTempHD format="%M"> is NOT a single character format modifier and therefore the 'M' acts as a custom modifier and causes the same date for the highest temperature in the month to be returned as the month number '7'.
In both Cumulus 1 and MX if you want a space character within your output, the output specifiers must be enclosed in double quotes. If that space character is next to a non modifier (e.g. around word "at") then the single quote needing to surround the at should be widened to include the spaces in MX, but Cumulus 1 does not care if single quotes excluded spaces. However, with MX, single quotes enclose multiple characters, but there is an alternative way to deal with some single verbatim characters to cover next.
So let us compare these two alternative ways that MONO and .NET escape any characters that are not being used as format specifiers.
- In Delphi you can put the 'verbatim' characters inside single quotes (Cumulus 1); this is often used to (in English) include words like ' on ' and ' at ' in the formatted output.
- in .NET or MONO you can still use single quotes (as mentioned above extended to include adjacent spaces),
- but alternatively you can escape each verbatim character with a backslash as prefix (Cumulus MX).
- You may need to use both single quotes and back slashes in some format specifiers, depending whether the characters you want to include can be interpreted as control characters (yes, backslash is also used to escape control characters, so backslash will NOT work for some characters such as those in "on" and "at" [\n will produce new line not the letter n, \t will produce a tab not the letter t]), consequently for some characters you must use the literal approach to include them in your format.
Past history for this page
This page is a complete redesign of how to present information that was previously on the Webtags page, so look there for past content by selecting "history" tab.
Trying to make the old design made for the original Cumulus software, work for MX which is now very different, made the old page unwieldy.
Forum reference
Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at Cumulus MX forum. The table there was based on the table that appeared in this Wiki when only the original Cumulus existed, so it was designed to help people migrate to his MX beta, it was not intended as a definitive list of what modifiers were available for MX (Steve instructed people to look them up on some Microsoft sites).
The subsequent comments in the forum suggested his layout got people confused. Most of that confusion came in two circumstances:
- When someone wanted to use one date or time modifier on its own
- When someone who had been using Cumulus 1 swapped to MX and wanted to replace a combination of output modifier characters that was not explicitly shown in his table.
That all comes from the fact that when a MX modifier consists of a single character it can mean something different to when it appears with other characters.
In Cumulus 1, "m" or "M" had two meanings depending whether it was combined with "H" or "h" (when it represented minutes), or on its own or with any other code (when it represented month). But for Cumulus 1, there is no other case where it matters what context a modifier is put in by the use of other modifiers, and no other modifier takes more than one meaning.
In MX it is much more complicated, to take a few examples "D", "H", "M" represent different items on their own to what they represent when combined with other characters. That other character can be as simple as using a space or a "%" to modify the meaning of the character.
Looking at the tables, now included above, you can see "G" is used on its own because it represents a full date-time specifier. "D" is similarly used on its own represents the long date format. If we only want the day of month number we must use "%d" to avoid the meaning of short date format that "d" on its own represents.
If we want the typical Cumulus date-stamp of day of month number and month, then we have two choices, because both "d M" and "M" will work. This illustrates how "M" has a different meaning on its own and with another modifier.
Hopefully, the way that information is now presented on this page makes any use of parameters for web tags much easier now.