Copyright (c) 2012-2016 Hyperion Entertainment and contributors.

Difference between revisions of "BattClock Resource"

From AmigaOS Documentation Wiki
Jump to: navigation, search
m (Make use of Note template)
(Polished the page, added OS4-updated example code by Doug Stastny, and removed the WIP banner.)
 
Line 1: Line 1:
{{WIP}}
+
== Introduction ==
 +
 
 
The battery-backed clock (BattClock) keeps Amiga time while the system is powered off. The time from the BattClock is loaded into the Amiga system clock as part of the boot sequence.
 
The battery-backed clock (BattClock) keeps Amiga time while the system is powered off. The time from the BattClock is loaded into the Amiga system clock as part of the boot sequence.
  
The battclock resource provides access to the BattClock. Three functions allow you to read the BattClock value, reset it and set it to a value you desire.
+
The BattClock Resource component provides access to the BattClock. Three [[#Function reference|functions]] allow you to read the BattClock value, reset it and set it to a value you desire.
  
'''BattClock Resource Functions'''
+
The [[Utility Library]] contains time functions which convert the number of seconds since 12:00 AM, January 1, 1978 to a date and time we can understand, and vice versa. You will find these functions useful when dealing with the BattClock. The example program below uses the Amiga2Date() utility function to convert the value returned by ReadBattClock(). See the [[Utility Library]] page for a discussion of the scope of the library, and the [[Autodocs:Main|autodocs]] for a listing of its functions.
  
{| class="wikitable"
+
{{Note|title=''So, you want to be a Time Lord?''|This resource will allow you to set the BattClock to any value you desire. Keep in mind that this time will endure a reboot and could adversely affect your system!}}
| ReadBattClock() || Read the time from the BattClock and returns it as the number of seconds since 12:00 AM, January 1, 1978.
+
|-
+
| ResetBattClock() || Reset the BattClock to 12:00 AM, January 1, 1978.
+
|-
+
| WriteBattClock() || Set the BattClock to the number of seconds you pass it relative to 12:00 AM, January 1, 1978.
+
|}
+
  
The utility.library contains time functions which convert the number of seconds since 12:00 AM, January 1, 1978 to a date and time we can understand, and vice versa. You will find these functions useful when dealing with the BattClock. The example program below uses the Amiga2Date() utility function to convert the value returned by ReadBattClock(). See the [[Utility_Library|Utility Library]] for a discussion of the utility.library and the SDK for a listing of its functions.
+
== Example ==
  
{{Note|title=''So, You Want to Be A Time Lord?''|This resource will allow you to set the BattClock to any value you desire. Keep in mind that this time will endure a reboot and could adversely affect your system.}}
+
<syntaxhighlight>
 +
#include <exec/types.h>
 +
#include <dos/dos.h>
 +
#include <utility/date.h>
 +
#include <resources/battclock.h>
  
<pre>
+
#include <proto/exec.h>
/*
+
#include <proto/dos.h>
* Read_BattClock.c
+
#include <proto/battclock.h>
*
+
#include <proto/utility.h>
* Example of reading the BattClock and converting its output to
+
* a useful measure of time by calling the Amiga2Date() utility function.
+
*
+
* Compile with SAS C 5.10  lc -b1 -cfistq -v -y -L
+
*
+
* Run from CLI only
+
*/
+
  
#include &lt;exec/types.h&gt;
 
#include &lt;dos/dos.h&gt;
 
#include &lt;utility/date.h&gt;
 
#include &lt;resources/battclock.h&gt;
 
  
#include &lt;clib/exec_protos.h&gt;
+
int main()
#include &lt;clib/alib_protos.h&gt;
+
{
#include &lt;clib/battclock_protos.h&gt;
+
    STRPTR ampm;
#include &lt;clib/utility_protos.h&gt;
+
    uint32 AmigaTime;
 +
    struct ClockData MyClock;
 +
    CONST CONST_STRPTR Days[] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};
 +
    CONST CONST_STRPTR Months[] = {"January", "February", "March", "April", "May", "June", "July", "August",
 +
    "September", "October", "November", "December"};
  
#include &lt;stdio.h&gt;
 
  
#ifdef LATTICE
+
    struct Library *BattClockBase = IExec->OpenResource(BATTCLOCKNAME);
int CXBRK(void) { return(0); }  /* Disable SAS CTRL/C handling */
+
    struct BattClockIFace *IBattClock = (struct BattClockIFace *) IExec->GetInterface(BattClockBase, "main", 1, NULL);
int chkabort(void) { return(0); }  /* really */
+
#endif
+
 
+
VOID main(VOID);
+
 
+
struct Library *UtilityBase = NULL;
+
struct Library *BattClockBase;
+
 
+
VOID main(VOID)
+
{
+
UBYTE *Days[] ={&quot;Sunday&quot;,&quot;Monday&quot;,&quot;Tuesday&quot;,&quot;Wednesday&quot;,&quot;Thursday&quot;,&quot;Friday&quot;,&quot;Saturday&quot;};
+
UBYTE *Months[] = {&quot;January&quot;,&quot;February&quot;,&quot;March&quot;,&quot;April&quot;,&quot;May&quot;,&quot;June&quot;,
+
                  &quot;July&quot;,&quot;August&quot;,&quot;September&quot;,&quot;October&quot;,&quot;November&quot;,&quot;December&quot;};
+
UBYTE *ampm;
+
ULONG AmigaTime;
+
struct ClockData MyClock;
+
  
if (UtilityBase = (struct Library *)OpenLibrary(&quot;utility.library&quot;,33))
+
     if (IBattClock != NULL) {
    {
+
     if (BattClockBase= OpenResource(BATTCLOCKNAME))
+
        {
+
 
         /* Get number of seconds till now */
 
         /* Get number of seconds till now */
         AmigaTime = ReadBattClock();
+
         AmigaTime = IBattClock->ReadBattClock();
 
+
 
         /* Convert to a ClockData structure */
 
         /* Convert to a ClockData structure */
         Amiga2Date(AmigaTime,&amp;MyClock);
+
         IUtility->Amiga2Date(AmigaTime, &MyClock);
 
+
         IDOS->Printf("\nRobin, tell everyone the BatDate and BatTime");
         printf(&quot;\nRobin, tell everyone the BatDate and BatTime&quot;);
+
  
 
         /* Print the Date */
 
         /* Print the Date */
         printf(&quot;\n\nOkay Batman, the BatDate is &quot;);
+
         IDOS->Printf("\n\nOkay Batman, the BatDate is ");
         printf(&quot;%s, %s %d, %d&quot;,Days[MyClock.wday],Months[MyClock.month-1],
+
         IDOS->Printf("%s, %s %ld, %ld", Days[MyClock.wday], Months[MyClock.month-1], MyClock.mday, MyClock.year);
                              MyClock.mday,MyClock.year);
+
  
 
         /* Convert military time to normal time and set AM/PM */
 
         /* Convert military time to normal time and set AM/PM */
         if (MyClock.hour &lt; 12)
+
         if (MyClock.hour < 12) {
             ampm = &quot;AM&quot;;        /* hour less than 12, must be morning */
+
             ampm = "AM";        /* hour less than 12, must be morning */
         else
+
        }
            {
+
         else {
             ampm = &quot;PM&quot;;        /* hour greater than 12,must be night */
+
             ampm = "PM";        /* hour greater than 12,must be night */
 
             MyClock.hour -= 12;  /* subtract the extra 12 of military */
 
             MyClock.hour -= 12;  /* subtract the extra 12 of military */
            };
+
        };
  
         if (MyClock.hour == 0)
+
         if (MyClock.hour == 0) {
            MyClock.hour = 12;  /* don't forget the 12s */
+
                MyClock.hour = 12;  /* don't forget the 12s */
 +
        }
  
 
         /* Print the time */
 
         /* Print the time */
         printf(&quot;\n            the BatTime is &quot;);
+
         IDOS->Printf("\n            the BatTime is ");
         printf(&quot;%d:%02d:%02d %s\n\n&quot;,MyClock.hour,MyClock.min,MyClock.sec,ampm);
+
         IDOS->Printf("%02ld:%02ld:%02ld %s\n\n", MyClock.hour, MyClock.min, MyClock.sec, ampm);
        }
+
    else
+
      printf(&quot;Error: Unable to open the %s\n&quot;,BATTCLOCKNAME);
+
  
    /* Close the utility library */
+
        IExec->DropInterface((struct Interface*) IBattClock);
    CloseLibrary(UtilityBase);
+
 
     }
 
     }
 +
    else
 +
      IDOS->Printf("Error: Unable to open the %s\n", BATTCLOCKNAME);
  
else
+
     return 0;
     printf(&quot;Error: Unable to open utility.library\n&quot;);
+
 
}
 
}
</pre>
+
</syntaxhighlight>
  
Additional programming information on the battclock resource can be found in the include files and the Autodocs for the battclock resource and the utility library.
+
Additional programming information on the BattClock Resource can be found in the respective include files and in the BattClock Resource and Utility Library [[Autodocs:Main|autodocs]].
 +
 
 +
== Function reference ==
 +
 
 +
{| class="wikitable"
 +
| ReadBattClock() || Read the time from the BattClock. Returns the time as the number of seconds since 12:00 AM, January 1, 1978.
 +
|-
 +
| ResetBattClock() || Reset the BattClock to 12:00 AM, January 1, 1978.
 +
|-
 +
| WriteBattClock() || Set the BattClock to the number of seconds you pass it relative to 12:00 AM, January 1, 1978.
 +
|}

Latest revision as of 13:03, 6 December 2017

Introduction

The battery-backed clock (BattClock) keeps Amiga time while the system is powered off. The time from the BattClock is loaded into the Amiga system clock as part of the boot sequence.

The BattClock Resource component provides access to the BattClock. Three functions allow you to read the BattClock value, reset it and set it to a value you desire.

The Utility Library contains time functions which convert the number of seconds since 12:00 AM, January 1, 1978 to a date and time we can understand, and vice versa. You will find these functions useful when dealing with the BattClock. The example program below uses the Amiga2Date() utility function to convert the value returned by ReadBattClock(). See the Utility Library page for a discussion of the scope of the library, and the autodocs for a listing of its functions.

So, you want to be a Time Lord?
This resource will allow you to set the BattClock to any value you desire. Keep in mind that this time will endure a reboot and could adversely affect your system!

Example

#include <exec/types.h>
#include <dos/dos.h>
#include <utility/date.h>
#include <resources/battclock.h>
 
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/battclock.h>
#include <proto/utility.h>
 
 
int main()
{
    STRPTR ampm;
    uint32 AmigaTime;
    struct ClockData MyClock;
    CONST CONST_STRPTR Days[] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};
    CONST CONST_STRPTR Months[] = {"January", "February", "March", "April", "May", "June", "July", "August", 
    "September", "October", "November", "December"};
 
 
    struct Library *BattClockBase = IExec->OpenResource(BATTCLOCKNAME);
    struct BattClockIFace *IBattClock = (struct BattClockIFace *) IExec->GetInterface(BattClockBase, "main", 1, NULL);
 
    if (IBattClock != NULL) {
        /* Get number of seconds till now */
        AmigaTime = IBattClock->ReadBattClock();
 
        /* Convert to a ClockData structure */
        IUtility->Amiga2Date(AmigaTime, &MyClock);
        IDOS->Printf("\nRobin, tell everyone the BatDate and BatTime");
 
        /* Print the Date */
        IDOS->Printf("\n\nOkay Batman, the BatDate is ");
        IDOS->Printf("%s, %s %ld, %ld", Days[MyClock.wday], Months[MyClock.month-1], MyClock.mday, MyClock.year);
 
        /* Convert military time to normal time and set AM/PM */
        if (MyClock.hour < 12) {
            ampm = "AM";        /* hour less than 12, must be morning */
        }
        else {
            ampm = "PM";         /* hour greater than 12,must be night */
            MyClock.hour -= 12;  /* subtract the extra 12 of military */
        };
 
        if (MyClock.hour == 0) {
                MyClock.hour = 12;   /* don't forget the 12s */
        }
 
        /* Print the time */
        IDOS->Printf("\n             the BatTime is ");
        IDOS->Printf("%02ld:%02ld:%02ld %s\n\n", MyClock.hour, MyClock.min, MyClock.sec, ampm);
 
        IExec->DropInterface((struct Interface*) IBattClock);
    }
    else
       IDOS->Printf("Error: Unable to open the %s\n", BATTCLOCKNAME);
 
    return 0;
}

Additional programming information on the BattClock Resource can be found in the respective include files and in the BattClock Resource and Utility Library autodocs.

Function reference

ReadBattClock() Read the time from the BattClock. Returns the time as the number of seconds since 12:00 AM, January 1, 1978.
ResetBattClock() Reset the BattClock to 12:00 AM, January 1, 1978.
WriteBattClock() Set the BattClock to the number of seconds you pass it relative to 12:00 AM, January 1, 1978.