View source for Webtags/Parameters

= Introduction =

Using a Webtag is described on the [[Webtags#Using_Webtags|Webtag]] page. Only the GET API interface can't use parameters. All the other possibilities use the general Webtag format:

  <#tag_name [optional input selection parameters] [optional output modification parameters]>

In the following the input and output parameters are described.

# An input parameter is used where the same tag name can represent a value for a number of different past time instants e.g. temperature for several days or several hours ago. 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 CumulusMX select the value you want to see. Whether a particular tag name can use input modification parameters will be shown in the Full list of Webtags.
# 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
#* Tag names representing floats or doubles can have modifications :
#*# modification of the number of decimal places shown after processing
#*# modification of the decimal separator (comma or point)
#* Tag names representing time intervals, clock times, [[meterological day|dates]] or representing both time/date for an extreme record may have the format changed

== Case sensitivity ==

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. The [[Webtags#The_local_List|local list]] is a useful reference here.

The ''optional input modification parameters'' always use lower case, so please type them exactly as shown in the [[#Input modification Parameters|section below]].

The content of ''optional 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 ==

The following Webtags (can) use input modification parameters:
#Tag names listed in the table at [[Full_list_of_Webtags#Recent_History|Recent History]]  (see also [[Recent history]] page)
#*Produces one value for each minute in last 7 days
#* '''d''' : specifies number of days ago
#* '''h''' : specifies number of hours ago
#* '''m''' : specifies number of minutes ago 
#* You can use any combination of the three parameters
#* All values supplied for parameters must be whole numbers
#* If you don't supply any parameters, the result is an illegal web tag for CumulusMX
#Tag names listed in the table at [[Full_list_of_Webtags#Monthly_All_Time_Records|monthly all-time extreme records]]
#* Produces the extreme record values (and corresponding time-stamps) for any particular month in all years
#* Optional input parameter is '''mon=N''' where N is the index of the month (1 is January, and so on, to 12 is December) 
#* If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used
#* You can use both an input parameter and an output parameter for any tag name, separate these with a space
#* '''NOTE''': If you use <code><#RecentRainToday d=2></code> remember that rainfall accumulates 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!
# The Webtags [[Full_list_of_Webtags#Monthly|Only <#SunshineHoursMonth>]] and [[Full_list_of_Webtags#Yearly|Only <#SunshineHoursYear>]]
#* Produces values available for current month/year, and for a past month/year. 
#* Omit input modification parameter to get value for current month/year. Alternatively include one of the following options:
#*# '''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''' ('''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

=== Examples for Recent History ===
# <#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 h=1 m=1> will give the temperature one day, one hour and one minute ago.

'''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. 

=== Examples for Monthly Records ===
#<#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.
#<#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature

'''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. 
'''NOTE:''' 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.

=== Examples Solar ===
#Monthly examples
#* <#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 r=-1> for last month's total
#* <#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 y=2019> for the total for 2019
#* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that returns total for 2019 as previous example)

(And of course you need a solar sensor for this)

== Output modification parameters ==
The output format for numbers and dates is ruled by the international settings (Windows) or locale settings (Linux). These settings are hereafter named the locale or locale settings. So if you want to have other formats for numbers and dates than you are seeing in your website or your reports, than your first step should be to check and possibly reconsider your locale. Beside that you must know that javascript does not handle a comma as decimal seperator. So if you wish to see a comma as decimal separator you probably must take some special precautions.

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.

=== Numbers ===

==== Changing the decimal separator ====

CumulusMX 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 <code><#RCtag_name></code> could force the output to use a decimal point (regardless of locale), that option remains available in CumulusMX for backward compatibility.

The current possibilities are:
{| class="wikitable" border="1"
|-
!style="width:150px" | Parameter
!style="width:600px" | Explanation
!style="width:600px" | 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
|}

==== Controlling the 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:
* <tt>dp=i</tt> rounds output to number of decimal places specified by "i"
* <tt>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.

 ====== Intermezzo ======
 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.
 
 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 [[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.

'''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 ===
In general '''all date/time tags will accept format strings''' with some exceptions. CumulusMX just passes the format string to the datetime formatter, it does not do any of its own formatting and therefore the Microsoft page are the only valid reference:
# [https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings Standard date and time format strings]
# [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings Custom date and time format strings] 

The user is advised to study those pages, relate to what he wants and experiment before getting to the forum and ask questions.

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 "--:--".  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. When hyphens are output, output modifiers have no effect.

To give you an idea what these modifiers are about let's 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 the [[Full_list_of_Webtags|Full list of Webtags]] page)
# 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 2, but all the rest is typed as shown.
# To explain each element in that format value, look in links above.

'''NOTE:''' The character '''%''' used in the format strings defines the following character as a custom format specifier. E.g. ''<#date format=%h>'' produces the hour while ''<#date format=h>'' produces an error because the 'h' as single standard format character does not exist.

'''NOTE:''' The character '''\''' used in format strings takes the next character as a literal in the output string. E.g. ''<#date format="%h \h">'' produces '10 h'.

'''NOTE:''' Any other character is copied to the result string unchanged. E.g. ''<#date format="Some text %h \h">'' produces 'So16e aexa 10 h' and ''<#date format="So\m\e \tex\t %h \h">'' produces 'Some text 10 h'.

==== Locales ====

The default format for webtags reporting date and/or time is dependent on the locale you are using. 

The effect of some output format modifiers is also dependent on locale.

For CumulusMX date and time formats within Windows Operating System, you must use the '''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 CumulusMX running on most operating systems (other than Microsoft Windows),  type <code>locale</code> to see the default locale that will be adopted by CumulusMX. It will, by default, take locale setting through Mono. When you start CumulusMX, 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 <code>locale -a</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====

All web tag outputs are in local time, except '''<#timeUTC>'''. 

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. To actually do that it would require programming in some language.

====Time resolution====

Seconds are supported but may be rounded down or up to 00 (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute. It is up to the user to format what he wants and adjust that format.

==== Conversion from legacy Cumulus to CumulusMX ====

You have to change, at least check, all date/time formatting for Webtags you use when moving from the legacy Cumulus 1 to CumulusMX. 

Best method probably is to migrate to CumulusMX. Then first check your log on Webtag error and then look at your website or reports - wherever you use your Webtags - and check your date/time formats. Then modify where you think it is required.

[[Category:Cumulus_MX]]