sdUTDx Function

Description

Returns a Universal Time Day (UTD) time value.

sdUTDx converts a 24 hour UT clock time into a portion of a day for use by the sdxH function.

Syntax

sdUTDx(hour, minute, second, timezone)

`hour`	any positive or negative number of Hours. 0 is midnight, 12 is midday and 18 is 6 pm.
`minute`	any positive or negative number of Minutes
`second`	any positive or negative number of Seconds
`timezone`	a timezone value between -13 and 12

Return Values

sdUTDx returns an XML String. Assuming "nnn" stands for the numeric UTD value between 0 and 1 that is returned and "tz" the numeric value of the timezone, the UTD time value will have the following format:

"nnn <UTD> nnn </UTD><TimeZone> tz </TimeZone>"

Errors

If the function detects an error in any of it's input parameters then it returns: "-99999999<Error>-99999999</Error>"

If the function returns an error value, then:
sdxGetv("Error",sdUTDx(...)) will return a non-zero value.

Remarks

This function calculates it's return value by converting the sum of the hours, timezone, minutes, and seconds to a number of days then returning the decimal (part of day) portion.

More formally this can be expressed in the following Basic language snippet:
days = (hour+timezone+minute/60+second/3600)/24 return days-int(days)

The string UTD time value may be converted to a simple numeric value using the sdxGetv function.

The XML string that this function returns has the numerical value of the result at the beginning of the string followed by the result in proper XML format. This value is the default numeric value of the string. It may be returned using the sdxGetv("",) function. For example:

Find the numeric value of the UTD value corresponding to 7:12pm UT:
sdxGetv("",sdUTDx(19,12,0))equals .8

This avoids the duplication inherent in it's equivalent:
sdxGetv("UTD",sdUTDx(19,12,0))equals .8

In a UTD time value with an appended Time Zone - for example: ".3<UTD> .3</UTD><TimeZone> 5 </TimeZone>"The TimeZone value is informational only and doesn't affect the UTD value.

The useful resolution of this time measure is approximately 1/10 of a millisecond.

Example

Find the UTD value corresponding to 2:12 pm Eastern Standard Time (USA) (+5 gives UT):
sdUTDx(2,12,0,5) equals ".3<UTD> .3</UTD><TimeZone> 5 </TimeZone>"

Find the numeric value of the UTD value corresponding to 7pm in Amsterdam (not Daylight saving):

    sdxGetv("",sdUTDx(19,0,0,-1)) equals .75

And also using an explicit reference to the time value:

    sdxGetv("UTD",sdUTDx(19,0,0,-1)) equals .75

And also retrieve the TimeZone from the time value:

   sdxGetv("TimeZone",sdUTDx(19,0,0,-1)) equals -1

Find the UTD value of 10,800 seconds past midnight in Almaty Kazakhstan (-6 gives UT):
sdUTDx(0,0,10800,-6) equals ".875<UTD>.875</UTD><TimeZone> -6 </TimeZone>"

Find the UTD value of 10,800 seconds before midnight UT:
sdUTDx(0,0,-10800, 0) equals "0.875 <UTD> 0.875 </UTD><TimeZone> 0 </TimeZone>"