The C64 OS Programmer's Guide is being written
This guide is being written and released and few chapters at a time. If a chapter seems to be empty, or if you click a chapter in the table of contents but it loads up Chapter 1, that's mostly likely because the chapter you've clicked doesn't exist yet.
Discussion of development topics are on-going about what to put in this guide. The discusssions are happening in the C64 OS Community Support Discord server, available to licensed C64 OS users.
C64 OS PROGRAMMER'S GUIDE
Library Reference: calendar.lib
Overview
Calendar.lib has routines that help when drawing dates and elements of a calendar. It is used primarily by the Today Utility.
| Name | calendar.lib |
|---|---|
| code | ca |
| size | 5 pages |
| Link | Yes |
| Unlink | No |
| Emits Memory Warnings | No |
Related libraries
Library Routines
Date to Screencodes (datetos_)
| Purpose | Convert an int to two reverse screencode digits |
|---|---|
| Jump offset | $03 |
| Communications registers | A, X, Y |
| Stack requirements | 4 |
| Zero page usage | None |
| Registers affected | A, X, Y |
| Input parameters | A → Date (int 1 to 31) |
| Output parameters |
Y ← Tens Digit (reverse screencode) X ← Ones Digit (reverse screencode) Raises an exception if input is out of range. |
Description: This routine helps draw dates directly to screen memory. It's most useful when implementing a Toolkit control that needs to draw. Pass an integer value from 1 to 31 in the accumulator. If the value in the accumulator is less than 1 or greater than 31 an exception is raised. It returns the date as two reverse screencodes.
Example, pass $03 in the accumulator, Y comes back as $B0,
X comes back as $B3. Pass $29 in the accumulator, Y comes back
as $B2, X comes back as $B9. Pass $32 in the
accumulator, an exception is raised. See: Commodore 64
Screen Codes for reference.
Day of Week (firstdow_)
| Purpose | Get day of week for a date |
|---|---|
| Jump offset | $06 |
| Communications registers | A, X, Y |
| Stack requirements | 4 |
| Zero page usage | None |
| Registers affected | A, X, Y |
| Input parameters |
Y → Year (1900 = 0) X → Month (January = 1) A → Date (int 1 to 31) |
| Output parameters | A ← Day of week (Sunday = 0) |
Description: This routine gives you an integer representing the day of the week for a given date. Sunday = 0 through Saturday = 6, for any date between January 1, 1900 and December 31, 2155. If the date is not valid no exception is raised, but the result will be unpredictable.
Example, pass 125 ($7D) in the accumulator for 2025 (1900 + 125 = 2025),
pass 12 ($0C) in the X register for December, pass 25 ($19) in
the accumulator, and it returns $04 (Thursday) in the accumulator.
Day of Year (dayofyr_)
| Purpose | Get day of year for a date |
|---|---|
| Jump offset | $09 |
| Communications registers | A, X, Y |
| Stack requirements | 8 |
| Zero page usage | $63, $64 |
| Registers affected | A, X, Y |
| Input parameters |
Y → Year (1900 = 0) X → Month (January = 1) A → Date (int 1 to 31) |
| Output parameters | dividnd ← Day of year + 6 |
Description: This routine gives you an integer representing the
day of the year + 6 for a given date. Leap years are taken into account. Pass the Year,
month and date in Y, X and A registers, same format as for firstdow,
the result is found in the zero page address dividnd which is defined by
//os/s/:math.s.
The result is plus 6 for ease of internally computing the week number. To get the actual day
of the year, subtract 6 from dividnd.
Week Number (weeknum_)
| Purpose | Get week number in which a date falls in a year |
|---|---|
| Jump offset | $0C |
| Communications registers | A, X, Y |
| Stack requirements | 10 |
| Zero page usage | $61, $62, $63, $64, $65, $66, $C8, $C9, $CA |
| Registers affected | A, X, Y |
| Input parameters |
Y → Year (1900 = 0) X → Month (January = 1) A → Date (int 1 to 31) |
| Output parameters | RegWrd ← Week Number |
Description: This routine gives you an integer representing the week number of the year in which a given date falls. Leap years are taken into account. Pass the Year, month and date in Y, X and A registers, same format as for firstdow, the result is returned as a RegWrd. Because there are only 52 weeks in a year, X holds the week number and Y is always returned as 0.
Example, pass 125 ($7D) in the accumulator for 2025 (1900 + 125 = 2025),
pass 12 ($0C) in the X register for December, pass 25 ($19) in
the accumulator, and it returns 52 ($34) (week number 52) in the X register and
$00 in the Y register.
Days in Month (daysinm_)
| Purpose | Get the number of days in a month |
|---|---|
| Jump offset | $0F |
| Communications registers | A, X, Y |
| Stack requirements | 5 |
| Zero page usage | None |
| Registers affected | A, X, Y |
| Input parameters |
Y → Year (1900 = 0) X → Month (January = 1) |
| Output parameters | A ← Number of days (int 28 to 31) |
Description: This routine returns an integer with the number of days in the month of a given year. Leap years are taken into account. Pass the Year and month in the Y and X registers, same format as for firstdow, the result is returned in the accumulator.
Example, pass 125 ($7D) in the accumulator for 2025 (1900 + 125 = 2025),
pass 11 ($0B) in the X register for November, and it returns 30 ($1E)
in the accumulator.
Is Leap Year (isleap_)
| Purpose | Compute if the given year is a leap year |
|---|---|
| Jump offset | $12 |
| Communications registers | Y, Carry |
| Stack requirements | 3 |
| Zero page usage | None |
| Registers affected | X |
| Input parameters | Y → Year (1900 = 0) |
| Output parameters |
C ← Clear = Not a leap year C ← Set = Is a leap year |
Description: This routine returns with the carry set if the year is a leap year. This can be used in calculations that incorporate the carry to add an extra day. Note that only the X register is modified by calling this routine.
Example, pass 125 ($7D) in the accumulator for 2025 (1900 + 125 = 2025), the
carry is returned clear because 2025 is not a leap year. Pass 128 ($80) in
the accumulator for 2028 (1900 + 128 = 2028), the carry is returned set because 2028 is
a leap year.
Month Name (mnthname_)
| Purpose | Get the string name of a month |
|---|---|
| Jump offset | $15 |
| Communications registers | A, X, Y |
| Stack requirements | 3 |
| Zero page usage | None |
| Registers affected | A, X, Y |
| Input parameters | X → Month (January = 1) |
| Output parameters |
RegPtr ← Pointer to string ("January", "February", etc.) A ← String length Raises an exception if input is out of range. |
Description: This routine returns a pointer to a string containing the full English name of the month. The string is not null-terminated. The length of the string is returned in the accumulator. The month is passed in the X register, same format as for firstdow.
Example, pass 3 ($03) in the accumulator for March, a RegPtr is returned to
a string (not null-terminated) "March", and the accumulator holds $05 because
there are 5 characters in the string "March".
Day Name (dayname_)
| Purpose | Get the string name of a day of the week |
|---|---|
| Jump offset | $18 |
| Communications registers | A, X, Y |
| Stack requirements | 3 |
| Zero page usage | None |
| Registers affected | A, X, Y |
| Input parameters | X → Day of Week (Sunday = 0) |
| Output parameters |
RegPtr ← Pointer to string ("Sunday", "Monday", etc.) A ← String length Raises an exception if input is out of range. |
Description: This routine returns a pointer to a string containing the full English name of the day of the week. The string is not null-terminated. The length of the string is returned in the accumulator. The day of the week is passed in the X register, same as the return format from firstdow.
Example, pass 3 ($03) in the accumulator for Wednesday, a RegPtr is returned to
a string (not null-terminated) "Wednesday", and the accumulator holds $09 because
there are 9 characters in the string "Wednesday".
Previous Section: Library Reference
Next Chapter: Using Toolkit
Table of Contents
This document is subject to revision updates.
Last modified: Jan 24, 2025