$clock

Return the system time or convert the argument to the Time data type.

$clock { (Source) }

Example: $clock(vString)

Parameters

Parameters
Parameter Data Type Description
Source String String, field, variable or parameter to convert to the time data type. If the value of Source is numeric, it is first converted to a string.

Return Values

  • Used without Source, $clock returns a string containing the system clock time as 00000000hhnnsstt that is accurate to one hundredth of a second (1 tick).

    If a service or report component is running in a remote environment, $clock returns the system time of the server (not of the client).

  • Used with Source, $clock returns the value as a time data type value (which does not include ticks). However, if Source is a string with the format "00000000hhnnsstt", it does return a time value that includes ticks. For example, "0000000012345678" returns "12:34:56.78".
  • If Source contains characters that are not valid or if any of the parts of the time (hours, minutes, or seconds) are not in the appropriate range, $clock returns an empty string (""). (For example, both $clock("A") and $clock("240000") return an empty string.)

If an error occurs, $procerror contains a negative value that identifies the exact error.

Values Commonly Returned by $procerror after $datim
Value Error Constant Meaning
-1005 UPROCERR_TIME Not a valid Time value.

Use

Allowed in all component types.

Description

You can use $clock to put a timestamp on occurrences (using data type String, for example), or assign the current system time to fields in header or footer frames (using data type Time, for example).

Used with Source, $clock converts Source to a value with data type Time. The way the data is interpreted and formatted depends on the locale, as determined by the values of $nlslocale and $nlsformat. For more details, see $date.

Using $clock with Source

$clock can be used with the Source argument when you are loading ASCII text files into a database and you have to convert time data stored as text into a field stored as Time.

When using $clock with Source:

  • If Source is formatted with one or two colons (:) used as separators (for example, hh:nn or hh:nn:ss), $clock converts Source to a time without considering the length of Source.

    If Source only contains one separator, it is interpreted as hh:nn.

  • If Source is a free-format number, with no colon separators included, $clock uses the number of digits in Source to determine the way Source is converted into a Time.
Converting strings to time with $clock

Number of digits

Interpreted as

1

h

2

hh

3

h : nn

4

hh : nn

5

h : nn : ss

6

hh : nn : ss

>6

NULL

The following table shows the different values returned by $clock, $number, and $clock($number), depending on the length of the Source operand:

Examples of Values Returned by $clock, $number, and $clock($number)
$1 $clock($1) $number($1) $clock($number($1))
"00:2:" 00:02:00 0 00:00:00
"2" 02:00:00 2 02:00:00
"02" 02:00:00 2 02:00:00
002" 00:02:00 2 02:00:00
"0002" 00:02:00 2 02:00:00
"00002" 00:00:02 2 02:00:00
"102" 01:02:00 102 01:02:00
"1002" 10:02:00 1002 10:02:00
"10002" 01:00:02 10002 01:00:02
"111002" 11:10:02 111002 11:10:02
"999002" NULL 999002 NULL
"240000" NULL 240000 NULL
"2400" NULL 2400 NULL
"235959" 23:59:59 235959 23:59:59
"1" 01:00:00 1 01:00:00
"02" 02:00:00 2 02:00:00
"003" 00:03:00 3 03:00:00
"0004" 00:04:00 4 04:00:00
"00005" 00:00:05 5 05:00:00
"000006" 00:00:06 6 06:00:00

Using $clock to Convert Text Data

When loading free-format time data from an ASCII text file, use a global or component variable defined as data type String. Define the layout for the variable as either DIS(999999) for hhnnss data, or DIS(9999) for hhnn data, then copy the data into this variable. Use $clock on the variable to convert the numeric string to a Time.

When loading text data, you should ensure that the date is correctly converted. Ensuring correct conversion depends on the way the source text is stored. If the data is completely raw (that is, it contains no separators, and has leading spaces, such as " 412"), declare a Numeric global or component variable with DIS(999999), and copy the data into it. This ensures the correct number of digits for hhnnss, since leading blanks are converted to leading zeros.

If, however, the data is partially formatted (such as ‘2:3:12’), you must declare a String global or component variable, because a Numeric variable only accepts digits before the first colon (:) (the first ‘2’ in ‘2:3:12’). A layout is not required for this type of variable. Copy the data into the variable, then use $clock to convert the data in the variable into a time.

Using $clock

The following example assigns the current system time to the field REPORTTIME.HEADER: 

REPORTTIME.HEADER = $clock

Converting Raw or Formatted Data into Time Data

The following example shows a global ProcScript that converts raw or formatted data into actual time data. This ProcScript converts a free format text field into a time field. It uses a numeric or string global variable, depending on whether the data is formatted or not. 

; Uses: 
; $1 - source 
; $2 - result, as a time 
; $$STRING_TIME - global variable, string 
; $$NUMBER_TIME - global variable, number, dis(999999)  

scan $1,’:’ ;is $1 formatted ? 

if ($result > 0) ; $1 contains a ’:’ 
  $$STRING_TIME = $1 ;keep format 
  $2 = $clock($$STRING_TIME) ;convert to time using formatted data 
else ;$1 does not contain a ’:’ 
  $$NUMBER_TIME = $1 ;$1 is raw text data, so force leading zeros 
  $2 = $clock($$NUMBER_TIME) ;convert six digit number to time endif
History
Version Change
9.2.01 When Source is omitted, accuracy is to one hundredth of a second (1 tick) instead of to the second.

Related Topics