Webtags/Parameters (preserving history): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Webtags/Parameters (preserving history) (view source)

Revision as of 18:06, 23 July 2021

2,252 bytes added ,  23 July 2021
m
→‎Multiple Output Format Modifier parameters for times and dates: Minor simplification
These are highly complicated, and so have been left until after the simpler ones!
 
===Use of spaces===
 
There are multiple parameters for specifying dates and times, and you might want spaces to appear in that output format.
===Where date format codes are used===
 
If we need to include spaces, then we have to enclose the whole specifier in double quotation marks e.g. <code><#tag_name format="x y z"></code>
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)
 
Any literals (i.e. characters we do not want to be interpreted by the date time parameter parser) are generally enclosed in single quotation marks, within the double quotation marks delimiting the specifier.
===Which web tag names take date/time output formatting modifiers===
 
This can cause you a problem if you want to use a date/time specification in a script because the script wants literal delimiters round the entire web tag, so that delimiters remain when the web tag itself has been processed into a string by Cumulus. The complicated sounding (but actually simple solution) is to avoid placing literals within any output format specifier, but instead put the literals outside with separate web tags before and after each literal. Then you can use single quotes outside. This is employed in some of the scripts at
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)
 
===Which tag names take date/time output formatting modifiers===
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):
 
There are nearly a thousand different tag names.
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 a few tag names labelled as being fixed format, obviously they cannot take any output modifiers.
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.
 
Time modifiers can be used to change the way that durations are reported, for tag names that report durations instead of clock times. Examples include '''<#daylength>''' and '''<#MonthDailyRainHD format=H:mm>'''. The [[webtags]] page clearly identifies those tag names that report clock times, but it is left to you to work out where durations are reported.
 
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.
 
There are some tags (e.g. highest temperature range in month/year), for which Cumulus has been coded to report "--:--" 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 their output can only be done on subsequent days.
 
It is not possible here to list each of these tag names, and indicate which time/date modifiers are accepted on a tag by tag basis. I did consider adding a column for that purpose to each table on the [[webtags]] page, but decided those were complicated enough. Instead, the following table, explains much more simply, which web tags will accept time and/or date output modifiers:
{| class="wikitable" border="1"
|-
!style="width:100px" | Cross-reference to table on web tag names page
!style="width:300px" | AcceptTag timenames modifiersthat accept only (examples)time output modifiers
!style="width:300px" | AcceptTag datenames modifiersthat accept only (examples)date output modifiers
!style="width:300px" | AcceptTag names that accept both time and date modifiersoutput for same tag (examples)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>
|-
| 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
|-
|[[Webtags#Monthly]], [[Webtags#YearlyNo_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#Date_.26_Time|Date &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]]
| Any tag name in "Time" column of linked table in first column
| Any tag name in "Date" column of linked table in first column
| 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)
|n/a
| None (all tag names combine both time and date)
|n/a
|any Any tag name in "Date/Time" column of linked table
|}
^ 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.
^ 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).
 
Note: There are some monthly/yearly web tags (e.g wettest day) where a date tag is available (i.e. <#MonthDailyRainHD>), but there is no time tag. As explained before, in that wettest day example '''<#MonthDailyRainHD format=H:mm>''' returns the duration in hours and minutes since rollover for which rain continued to increase on that date, not the clock time. For rainfall, only '''<#LastRainTip>''' can have output modifiers added to report a clock time.
 
===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 MX running on most operating systems (and therefore using Mono), 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#Parameter_for_changing_Locale]]. 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 <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.
 
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.
 
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.
 
===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>'''.
===What can time/date output modifiers do?===
 
Although Cumulus 2 internally stored all date/times in UTC, no flavour of Cumulus is currently able to output the time-stamp for any weather extreme in UTC, if your current time is not in UTC.
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.
 
However, for MX only, 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.
#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!
 
===Time resolution===
===Use of double quotation marks===
 
For the legacy software, there may be no point in asking for seconds, as Cumulus 1 did some actions at one minute intervals.
The general syntax is <code><#tag_name format=x></code> where '''x''' can represent a single chacter, or multiple characters without any spaces.
 
If Cumulus obtained archive data, as part of the catch-up process it can do when it restarts, any time-stamps for that 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.
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>
 
===Dependency on Cumulus flavour===
 
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]]
 
====For the legacy software====
**(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).
 
 
===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.
 
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>.
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.
 
[[#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.
{| class="wikitable" border="1"
|-
!style="width:150px" | {{Version[[File:Badge badge 1}}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
|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[[File:Badge badge 1}}v1.png]]<#time format=c>[[File:Badge vMx.png]]<#time format=G>
|-
|"D MMMM YYYY"
[[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[[File:Badge 1}}v1.png]]<#LastDataReadT format=TT>
*[[File:Badge vMx.png]]<#LastDataReadT format=T>
|}
{| class="wikitable" border="1"
|-
!style="width:150px" | {{Version[[File:Badge badge 1}}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
|%M
|Displays the month as a number without a leading zero (1-12).
*{{Version badge[[File:Badge 1}}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 different from the '''format=M''' included in previous table.
|2
|MM
|Displays the month as a number with a leading zero (01-12).
*{{Version badge[[File:Badge 1}}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">
|-
{| class="wikitable" border="1"
|-
!style="width:150px" | {{Version[[File:Badge badge 1}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
|%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[[File:Badge badge 1}}v1.png]]<#metdate format="d">[[File:Badge vMx.png]]<#metdate format="%d">
|-
|dd
|ddddd
|d (as single character format)
|{{Version badge[[File:Badge 1}}v1.png]]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[[File:Badge badge 1}}v1.png]]<#metdate format=dddd>
[[File:Badge vMx.png]]<#metdateyesterday format=d> ''but not'' <#yesterday=d> which would return just '22'
|-
===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 durations and clock times.
 
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"
|-
!style="width:150px" | {{Version[[File:Badge badge 1}}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
|%h
|Displays the hour (12 hour clock) without a leading zero (1-12)
| 7
|-
|h ''AM/PM''
|Displays the hour (12 hour clock) without a leading zero (1-12) in combination with AM/PM.
 
{{Version[[File:Badge badge 1}}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 v1.png]]7 PM
|-
|h:nn [''AM/PM'']
|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].
 
{{Version[[File:Badge badge 1}}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 {{Version[[File:Badge badge 1}}v1.png]] <#LastDataReadT format="h:nn am/pm">[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
|-
|H (or ''H'')
|%H
| Displays the hour '''usingpart 24of hourany duration or clock''' time, without a leading zero (0-23). [[File:Badge vMx.png]]Note that including a ' ' (space) or '%' before the "H" makes it a custom modifier, needed because H is on its own.
 
[[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
*{{Version badge[[File:Badge 1}}v1.png]]<#daylength format=H>
*[[File:Badge vMx.png]]<#daylength format=%H>
|-
|H:mm (or ''H:nn'')
|H:mm
| Displays the hour usingpart 24of hourany duration or clock time, without a leading zero (0-23) followed by 2 digit minutes. [[File:Badge vMx.png]]Notefor that %,duration ofor previousclock example,time. is not needed when H is not on its own.
 
[[File:Badge vMx.png]]Note that %, of previous example, is not needed as the H is not on its own.
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm">
|-
|HH (or ''hh'')
|HH
| 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>
|-
|hh [''am/pm'']
|hh [''tt'']
| 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].
 
{{Version[[File:Badge badge 1}}v1.png]]For Cumulus 1 the case output for the optional 'am/pm' depends on the case used for that parameter as shown later in this table
 
[[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
*{{Version badge[[File:Badge 1}}v1.png]] <#LastDataReadT format="hh am/pm">
*[[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 [''tt'']
| 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].
*{{Version badge[[File:Badge 1}}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, and the case output for am/pm depends on the case used for that parameter as shown later in this table. As Cumulus 1 is case insensitive there are variants with capital letters available.
*[[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
* {{Version[[File:Badge badge 1}}v1.png]] <#LastDataReadT format="h:nn am/pm">
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
|-
|n
|%m
|Displays the minuteminutes 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.
| 7 produced as a duration in minutes by
* {{Version[[File:Badge badge 1}}v1.png]]<#daylength format=n>
*[[File:Badge vMx.png]]<#daylength format=m>
|-
|nn
|mm
|Displays the minuteminutes of any duration or clock time, with a leading zero (00-59).
|'07' produced byas a duration in minutes by
*{{Version badge[[File:Badge 1}}v1.png]]<#daylength format=nn>
*[[File:Badge vMx.png]]<#daylength format=mm>
|-
|s
|%s
|Displays the secondseconds 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]]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
*{{Version badge[[File:Badge 1}}v1.png]]<#time format=hh:nn:ss.zzz>
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff>
|-
|am/pm or Am/Pm or AM/PM
|tt
|{{Version badge[[File:Badge 1}}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".
|h a/p
|h t
|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".
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/9545"

Navigation menu