<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>

