:Revision=17
:html
<<
128.110
DateTime-Object|DateTime
--
The IP-Object DateTime provides methods for enquiring and processing date and time specifications. 

In addition it provides 10 timers, which can be used to detect, if a certain time since the start of a timer has passed.
>>
<<
128.110.1
Functions of the DateTime-Object|Functions
--
>>
<<
128.110.1.1
DateTime.TimerExpired|TimerExpired
!128.110.3 - Timer
--
<!DEF>
function <!TW>DateTime.TimerExpired (rNr : real) : real;
<!TXT>
Returnes <!RW>TRUE, if the <!PW>rNr timer has expired.

A timer which has not been started is always expired. A temporarily stopped timer is never expired.
>>
<<
128.110.1.2
DateTime.TestTime|TestTime
--
<!DEF>
function <!TW>DateTime.TestTime : real;
<!TXT>
Returns the test duration of the active DUTs in seconds [s].

For the simultaneous test mode <!SW>Single there is no change in respect to the old implementation. For the modes <!SW>ContactPos and <!SW>Panel the time since the start of the first test step will be returned.

Example
<!CODE>
var
  vrDateTime  : Real;
step
  // Returns the duration of the last or actual test.
  vrDateTime := DateTime.TestTime;
  // Shows the calculated time in the debugging display.
  Debug.SHOW(1,'Duration of the test: ',vrDateTime);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.110.1.3
DateTime.ReadTimer|ReadTimer
--
<!DEF>
function <!TW>DateTime.ReadTimer : real;
<!TXT>
Returns the system time in ms. The reference time is the moment of the last reset or type change. The return value can be used as refernce value  for timeout, but it cannot be converted into an absolute time (UTC, MEZ).

Example
<!CODE>
var
  vrDateTime  : Real;
step
  // Returns the past time since the last system start respectively reset.
  vrDateTime := DateTime.ReadTimer;
  // Shows the calculated time in the debugging display.
  Debug.SHOW(1,'Past time since system start resp. reset: ',vrDateTime);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.110.1.4
DateTime.TimeString|TimeString
--
<!DEF>
function <!TW>DateTime.TimeString (sFormat : string) : string:
<!TXT>
Returns the current time/the current date as string.

<!PW>sFormat determines the formatting.

<!TXT>

Beispiel
<!CODE>
var
  vsDateTime  : String;
step
  // Returns the actual date and time writen as string.
  vsDateTime := DateTime.TimeString('dddd yyyy-mm-dd hh:nn:ss');
  // Shows the calculated string inside of the debuggin display.
  Debug.SHOW(1,'Actual date and time: ',vsDateTime);
  System.SetValue(0);
end.
<!TXT>

<!STBL>
<!+>Code<!+>Result<!>
<!>c<!>standard format, as determined for Windows<!>
<!>d<!>day as number without leading zero (1-31)<!>
<!>dd<!>day as number with leading zero (01-31)<!>
<!>ddd<!>day as abbreviation (Sun - Sat)<!>
<!>dddd<!>day with complete name <!>
<!>m<!>month as number without leading zero (1-12)<!>
<!>mm<!>month as number with leading zero (01-12)<!>
<!>mmm<!>month as abbreviation (Jan - Dec)<!>
<!>mmmm<!>month with full name<!>
<!>yy<!>year as double figure (00-99)<!>
<!>yyyy<!>year as four-digit figure (0000-9999)<!>
<!>h<!>hour without leading zero (0-23)<!>
<!>hh<!>hour with leading zero (00-23)<!>
<!>n<!>minute without leading zero (0-59)<!>
<!>nn<!>minute with leading zero (00-59)<!>
<!>s<!>second without leading zero (0-59)<!>
<!>ss<!>second with leading zero (00-59)<!>
<!>t<!>time in standard format<!>
<!>w<!>MCD week of year without leading zero (1..52)<!>
<!>ww<!>MCD week of year with leading zero (01..52)<!>
<!>f<!>day of year without leading zeros (1..366)<!>
<!>ff<!>day of year with leading zero (001..366)<!>
<!>x<!>day of week 1..7, Monday=1<!>
<!>z<!>day of week 1..7, Sunday=1<!>
<!>'xx', "xx"<!>characters quoted in simple or double quotation marks
are displayed as given and do not influence the formatting.<!>
<!ETBL>
<!REM>
The language of day names (Montag, Monday, Lundi) and month names (Januar, January, Janvier) depends on the Windows-setup.
<!TXT>

>>

<<
128.110.1.4
DateTime.Now|Now
--
<!DEF>
function <!TW>DateTime.Now : real;
<!TXT>
Returns the current date and time in DateTime format.

Example
<!CODE>
var
  vrDateTime  : Real;
step
  vrDateTime := DateTime.Now;                                  // Returns the actual date ad time in real format.
  Debug.SHOW(1,'Date and Time in real format: ',vrDateTime);   // Shows the actual date and time in real format in the debugging display.
  System.SetValue(0);
end.
<!TXT>

>>

<<
128.110.1.5
DateTime.Encode|Encode
--
<!DEF>
function <!TW>DateTime.Encode ( rYear, rMonth, rDay : real [; rHour, rMinute, rSecond : real [; rMSec : real ]]): real;
<!TXT>
Encodes a date/time in the DateTime format.

Example
<!CODE>
var
  vrDateTime     : Real;

  vrYear         : Real;
  vrMonth        : Real;
  vrDay          : Real;
  vrHour         : Real;
  vrMinute       : Real;
  vrSeconds      : Real;
  vrMilliseconds : Real;
step
  // Set the values of the date and time to the real variables.
  vrYear         := 2009;
  vrMonth        := 5;
  vrDay          := 21;
  vrHour         := 14;
  vrMinute       := 35;
  vrSeconds      := 48;
  vrMilliseconds := 250;
  // Convert the real values to the DateTime Format (one real value).
  vrDateTime := DateTime.Encode(vrYear, vrMonth, vrDay, vrHour, vrMinute, vrSeconds, vrMilliseconds);
  // Shows the date and time as one real value in the debugging display.
  Debug.SHOW(1,'Date and time as Real: ',vrDateTime);
  System.SetValue(0);
end.
<!TXT>

>>

<<
128.110.1.6
DateTime.DayOfWeek|DayOfWeek
--
<!DEF>
function <!TW>DateTime.DayOfWeek ( rDateTime : real ) : real;
<!TXT>
Retruns the day of the week from <!PW>rDateTime (Monday = 1, ..., Sonday = 7).

Example
<!CODE>
var
  vrDateTime  : Real;
  vrDayOfWeek : Real;
  vsDayOfWeek : String;
step
  vrDateTime := DateTime.Now;                     // Returns the actual date as real format.
  vrDayOfWeek := DateTime.DayOfWeek(vrDateTime);  // Calculates the weekday out of the actual date (1-7)
  case vrDayOfWeek of                             // TRansforms the weekday from the number format to a written string format.
    1 : vsDayOfWeek := 'Monday';
    2 : vsDayOfWeek := 'Tuesday';
    3 : vsDayOfWeek := 'Wednesday';
    4 : vsDayOfWeek := 'Thursday';
    5 : vsDayOfWeek := 'Friday';
    6 : vsDayOfWeek := 'Saturday';
    7 : vsDayOfWeek := 'Sunday';
    else  vsDayOfWeek := 'Error';
  end;
  Debug.SHOW(1,'Weekday: ',vsDayOfWeek);          // Shows the weekday in the debugging display.
  System.SetValue(vrDayOfWeek);
end.
<!TXT>

>>

<<
128.110.1.7
DateTime.DayOfYear|DayOfYear
--
<!DEF>
function <!TW>DateTime.DayOfYear ( rDateTime : real ) : real;
<!TXT>
Retruns the day of the year from <!PW>rDateTime (Januar 01 = 1).

Example
<!CODE>
var
  vrDateTime  : Real;
  vrDayOfYear : Real;
step
  vrDateTime := DateTime.Now;                     // Returns the actual date as real format.
  vrDayOfYear := DateTime.DayOfYear(vrDateTime);  // Calculates the day of the year out of the actual date (1-365).
  Debug.SHOW(1,'Day of the year: ',vrDayOfYear);  // Shows the calculated day of the year in the debugging display.
  System.SetValue(vrDayOfYear);
end.
<!TXT>

>>

<<
128.110.1.8
DateTime.WeekOfYearISO|WeekOfYearISO
--
<!DEF>
function <!TW>DateTime.WeekOfYearISO ( rDateTime : real ) : real;
<!TXT>
Returns the week from <!PW>rDateTime (DIN 1355 / ISO 8601).

Every Monday and only every Monday starts a new calendar week. The first calendar week is the week which contains at least 4 days of the new year. Every calendar week contains 7 days, there is no exceptional case. Every Year contains 52 or 53 calendar weeks. The 29., 30. and 31. December could be inside of the first calendar week of the new year. The 1., 2. and 3. January could be inside of the last calendar week of the old year.

Beispiel
<!CODE>
var
  vrDateTime  : Real;
  vrWeekOfYear : Real;
step
  vrDateTime := DateTime.Now;                          // Returns the actual date as real format.
  vrWeekOfYear := DateTime.WeekOfYearISO(vrDateTime);  // Calculates the calendar week out of the actual date (1-53).
  Debug.SHOW(1,'Calendar week: ',vrWeekOfYear);        // Shows the calculated calendar week of the year in the debugging display.
  System.SetValue(vrWeekOfYear);
end.
<!TXT>

>>

<<
128.110.2
Procedures of the DateTime-Object|Procedures
--
>>
<<
128.110.2.1
DateTime.Delay|Delay
--
<!DEF>
procedure <!TW>DateTime.Delay (rMSDelay : real [; rYield : real);
<!TXT>
Waites for a period of <!PW>rMSDelay milliseconds.

<!REM>
Attention:
  Windows - typically bad resolution.
  Under Windows NT circa 10ms, under Win95/98 circa 55ms
  (the times are not guaranteed)
<!TXT>

The parameter <!PW>rYield selects, if other processes should get processing time during the waint.
Advantage: the computer is not blocked, the CPU load decreased.
Disadvantage: the delay becomes more inaccurate.

If <!PW>rYield is not specified, and the delay is longer than 200ms the CPU is released for other processes.

<!TXT>

Example
<!CODE>
var
  vrLoops  : Real;
step
  vrLoops := 0;
  // Loop until step is finished or 4 durations are executed.
  repeat
    Inc(vrLoops);
    Debug.SHOW(1,'Loop: ', vrLoops);
    // Stops the process for the passed time and gives other processes the chance to work.
    DateTime.Delay(250, true);
  until ((stepcontinue) or (vrLoops=4));
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.110.2.2
DateTime.Date|Date
!128.110.2.4 - Time
!128.110.2.3 - Week
--
<!DEF>
procedure <!TW>DateTime.Date (var rYear, rMonth, rDay : real);
<!TXT>
Returns the current date in the three variables.

Example
<!CODE>
var
  vrYear  : Real;
  vrMonth : Real;
  vrDay   : Real;
step
  // Returns the actual date in the three passed parameter.
  DateTime.Date(vrYear, vrMonth, vrDay);
  // Shows the calculated values in the debugging display.
  Debug.SHOW(1,'Actual date: ', vrYear, '-', vrMonth, '-', vrDay);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.110.2.3
DateTime.Week|Week
!128.110.2.2 - Date
--
<!DEF>
procedure <!TW>DateTime.Week (var rWeekOfYear : real [; var rDayOfWeek : real]);
<!TXT>
Returns the current week of the year and if a second variable is specified, the day of the week as well (1..7, Sunday=1).

Note: 
The routines takes care that the calendar weeks are always ascending in a year. In December, it does not return WOY 1 of the next year for the last days of the year, even if it should be like that according to the (german) calendar; it will indicate WOY 53. Vice versa, for the first days of January it will be always return WOY 1, even if these days are in WOY 52 / 53 of the previous year according to the (german) calendar.

<!TXT>

Example
<!CODE>
var
  vrWeekOfYear : Real;
  vrDayOfWeek  : Real;
  vsDayOfWeek  : String;
step
  // Returns in the both parameter the actual calendarweek and the weekday.
  DateTime.Week( vrWeekOfYear, vrDayOfWeek );
  // Transforms the weekday from the number format to the written form.
  case vrDayOfWeek of
    1 : vsDayOfWeek := 'Sunday';
    2 : vsDayOfWeek := 'Monday';
    3 : vsDayOfWeek := 'Tuesday';
    4 : vsDayOfWeek := 'Wednesday';
    5 : vsDayOfWeek := 'Thursday';
    6 : vsDayOfWeek := 'Friday';
    7 : vsDayOfWeek := 'Saturday';
    else  vsDayOfWeek := 'Error';
  end;
  // Shows the calendarweek and the weekday in the debugging diplay.
  Debug.SHOW(1,'Calendarweek: ',vrWeekOfYear, ' Day: ', vsDayOfWeek );
  System.SetValue(vrDayOfWeek);
end.
<!TXT>

>>
<<
128.110.2.4
DateTime.Time|Time
!128.110.2.2 - Date
--
<!DEF>
procedure <!TW>DateTime.Time (var rHour, rMinute [, rSecond [, rMSec]] : real);
<!TXT>
Returns the current time. (system time of the computer)

<!TXT>

Example
<!CODE>
var
  vrHour        : Real;
  vrMinute      : Real;
  vrSecond      : Real;
  vrMillisecond : Real;
step
  // Returns the actual time to the three passed parameter.
  DateTime.Time (vrHour, vrMinute, vrSecond, vrMillisecond);
  // Shows the calulated time in the debugging display.
  Debug.SHOW(1,'Actual time: ', vrHour, ':', vrMinute, ':', vrSecond, '.', vrMillisecond);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.110.2.5
DateTime.SetTimer|SetTimer
!128.110.3 - Timer
--
<!DEF>
procedure <!TW>DateTime.SetTimer (rNr, rTimeInMs);
<!TXT>
Sets the running time of timer <!PW>rNr (1..10) to <!PW>rTimeInMS milliseconds.

However, it does not starts or stop the timer. An already running timer is not influenced during its remaining running period. The run time is effective only with the next timer start.
>>
<<
128.110.2.6
DateTime.StartTimer|StartTimer
!128.110.3 - Timer
--
<!DEF>
procedure <!TW>DateTime.StartTimer (rNr);
<!TXT>
Starts the timer <!PW>rNr. This means that the timer is running now and will expire according to its run time set with <!RW>DateTime.SetTimer.

If the timer has been already running or has been temporarily stopped, it will be restarted.
>>
<<
128.110.2.7
DateTime.PauseTimer|PauseTimer
!128.110.3 - Timer
--
<!DEF>
procedure <!TW>DateTime.PauseTimer (rNr);
<!TXT>
Temporarily stops the timer <!PW>rNr. The remaining run time is saved. This does not influence in any way the run time set with <!RW>DateTime.SetTimer.

If the timer was not active (so already temporarily stopped or expired) the call has no effect.
>>
<<
128.110.2.8
DateTime.ResumeTimer|ResumeTimer
!128.110.3 - Timer
--
<!DEF>
procedure <!TW>DateTime.ResumeTimer (rNr);
<!TXT>
Makes the timer <!PW>rNr running again if it has been previously stopped temporarily. The timer expires after the expiration of the remaining run time saved by <!RW>DateTime.PauseTimer.

If the timer was not temporarily stopped, the call has no effect.
>>
<<
128.110.2.9
DateTime.Sleep|Sleep
--
<!DEF>
procedure <!TW>DateTime.Sleep (rMSDelay);
<!TXT>
Waites for a period of <!PW>rMSDelay milliseconds.

Similar to <!RW>DateTime.Delay, but with worse resolution (type. 50 ms) in case of short delays.
On the other hand, <!RW>Sleep has a much lower CPU load.

With DateTime.Sleep (0) the remainder of the time slice can be released to other processes.

<!TXT>

Example
<!CODE>
var
  vrLoops  : Real;
step
  vrLoops := 0;
  // Loop until steb i s finished or 4 durations are executed.
  repeat
    Inc(vrLoops);
    Debug.SHOW(1,'Loop: ', vrLoops);
    // Stops the process for the passed time and give other processes the chance to work.
    DateTime.Sleep(250);
  until ((stepcontinue) or (vrLoops=4));
  System.SetValue(0);
end.
<!TXT>

>>

<<
128.110.2.10
DateTime.Decode|Decode
--
<!DEF>
procedure <!TW>DateTime.Decode ( rDateTime : real; var rYear, rMonth, rDay : real [; var rHour, rMinute, rSecond : real [; var rMSec : real ]]);
<!TXT>
Decodes a date/time in DateTime format in <!PW>rDateTime.

Example
<!CODE>
var
  vrDateTime     : Real;

  vrYear         : Real;
  vrMonth        : Real;
  vrDay          : Real;
  vrHour         : Real;
  vrMinute       : Real;
  vrSeconds      : Real;
  vrMilliseconds : Real;
step
  // Returns the actual date and time in Real format.
  vrDateTime := DateTime.Now;
  // Transform the date and time from the one Real value in different Real values (Year, Months, ...).
  DateTime.Decode(vrDateTime, vrYear, vrMonth, vrDay, vrHour, vrMinute, vrSeconds, vrMilliseconds);
  // Shows the different values of the date and time in the debugging display.
  Debug.SHOW(1, 'Date: ', vrYear, '-', vrMonth, '-', vrDay, ' ', vrHour, ':', vrMinute, ':', vrSeconds, '.', vrMilliseconds);
  System.SetValue(0);
end.
<!TXT>

>>

<<
128.110.3
Function description of the 'Timer'|Timer
!128.110.2.5 - SetTimer
!128.110.2.6 - StartTimer
!128.110.1.1 - TimerExpired
!128.110.2.7 - PauseTimer
!128.110.2.8 - ResumeTimer
--
The IP-Object DateTime provides 10 timers which are addressed by their number and work independently from each other.

A timer has:
<ul indent=12>
<li>a run time</li>
<li>the boolean property 'expired'</li>
<li>a state, that can be: 
  <ul indent=12>
  <li>running</li>
  <li>temporarily stopped</li>
  <li>expired</li>
  </ul></li>
</ul>

The property 'expired' can be read with with <!RW>DateTime.TimerExpired. 
The run time can be set with <!RW>DateTime.SetTimer.
The status can be controlled with the commands <!RW>DateTime.StartTimer, <!RW>DateTime.PauseTimer and <!RW>DateTime.ResumeTimer.

Before each test cycle the timers are set to the expired state and a run time of 0ms is set (-> so they must be initialized under any circumstances).

Examples:
<!CODE>
// Enquiry with a timeout of 1000ms
DateTime.SetTimer (1,1000);     // set timer 1 on 1000ms run time
DateTime.StartTimer (1);        // timer 1 will expire in 1000ms
repeat
  rMeasurementOK:=...           // do the measurement
until rMeasurementOK or DateTime.TimerExpired (1);

// process action 1 every 100ms, action 2 every 350 ms
DateTime.SetTimer (1,100);      // set timer 1 on 100ms run time
DateTime.SetTimer (2,350);      // set timer 2 on 350ms run time
DateTime.StartTimer (1);        // start timer 1
DateTime.StartTimer (2);        // start timer 2
repeat
  if DateTime.TimerExpired (1) then begin
    ...Action 1
    DateTime.StartTimer (1);    // restart timer 1
  end;
  if DateTime.TimerExpired (2) then begin
    ...Action 2
    DateTime.StartTimer (2);    // restart timer 2 
  end;
  rMeasurementOK:=...           // do measurement
until rMeasurementOK;
<!TXT>
>>
