<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2009</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>cosTime Examples</title>
    <prepared>Niclas Eklund</prepared>
    <docno></docno>
    <date>2000-01-31</date>
    <rev>A</rev>
    <file>ch_example.xml</file>
  </header>

  <section>
    <title>A Tutorial on How to Create a Simple Service</title>

    <section>
      <title>Initiate the Application</title>
      <p>To use the complete cosTime application Time and Timer Event Services
        must be installed. The application is then started by using 
        <c>cosTime:start()</c>. To get access to Time Service or Timer Event Service,
        use <c>start_time_service/2</c> or <c>start_timerevent_service/1.</c></p>
      <p>The Time Service are global, i.e., there may only exist one instance per
        Orber domain.</p>
      <p>The Timer Event Service is locally registered, i.e., there may only exist 
        one instance per node.</p>
      <note>
        <p>The Time and Timer Event Service use the time base 
          <em>15 october 1582 00:00</em>. Performing operations using other time
          bases will not yield correct result. Furthermore, time and inaccuracy
          must be expressed in 100 nano seconds.</p>
      </note>
    </section>

    <section>
      <title>How to Run Everything</title>
      <p>Below is a short transcript on how to run cosTime. </p>
      <code type="none">
 
%% Start Mnesia and Orber
mnesia:delete_schema([node()]),
mnesia:create_schema([node()]),
orber:install([node()]),
mnesia:start(),
orber:start(),
 
%% Install Time Service in the IFR.
cosTime:install_time(),     

%% Install Timer Event Service in the IFR. Which, require
%% the Time Service and cosEvent or cosNotification 
%% application to be installed.
cosNotification:install(),
cosTime:install_timerevent(),

%% Now start the application and necessary services.
cosTime:start(),
%% Tdf == Time displacement factor
%% Inaccuracy measured in 100 nano seconds
TS=cosTime:start_time_service(TDF, Inaccuracy),
TES=cosTime:start_timerevent_service(TS),

%% Access a cosNotification Proxy Push Consumer. How this is
%% done is implementation specific.
ProxyPushConsumer = ....

%% How we construct the event is also implementation specific.
AnyEvent = ....

%% Create a new relative universal time.
%% Time measured in 100 nano seconds.
UTO='CosTime_TimeService':
      new_universal_time(TS, Time, Inaccuracy, TDF),
EH='CosTimerEvent_TimerEventService':
      register(TES, ProxyPushConsumer, AnyEvent), 

%% If we want to trigger one event Time*10^-7 seconds from now:
'CosTimerEvent_TimerEventHandler':set_timer(EH, 'TTRelative', UTO),

%% If we want to trigger an event every Time*10^-7 seconds, starting
%% Time*10^-7 seconds from now:
'CosTimerEvent_TimerEventHandler':set_timer(EH, 'TTPeriodic', UTO),

%% If we want to use absolute time we must retrieve such an object.
%% One way is to convert the one we got, UTO, by using:
UTO2='CosTime_UTO':absolute_time(UTO),
%% If any other way is used, the correct time base MUST be used, i.e.,
%% 15 october 1582 00:00.
'CosTimerEvent_TimerEventHandler':set_timer(EH, 'TTAbsolute', UTO2),
      </code>
    </section>
  </section>
</chapter>

