AE TimeMaster II H.O. Programmers Supplement

AE TimeMaster II H.O. Programmers Supplement
TimeMaster II H.O.
User’s Manual
Programmer's
Supplement
TimeMaster ProDOS
Command Extensions
vl.0
Any comments or suggestions for improving this manual would be appreciated. Please forward your remarks to:
Applied Engineering
P.O. Box 798
Carroliton, Texas 75006
Attention:
Manager, Technical Publications
This manual and the software (computer programs) described herein are copyrighted by Applied Engineering with all
rights reserved. Under the copyright laws, this manual or the programs may not be copied, in whole or in part, without
the written consent of Applied Engineering, except in the normal use of the software or to make an archival copy. This
exception does not allow copies to be made for others, whether or not sold, but all of the materials purchased (with all
archive copies) may be sold, loaned, or given to another person. Under the law, copying includes translating into
another language or format.
You may use this software on any computer owned by you but extra copies cannot be made for this purpose.
Applied Engineering cannot guarantee that you will receive notice of revisions to the software or products described
in this manual. Be sure to check with your dealer or Applied Engineering for information on possible updates.
Apple® is a registered trademark of Apple Computer, Inc.
DOS 3.3™, and ProDOS™ are trademarks of Apple Computer, Inc.
Applied Engineering® is a registered trademark of Applied Engineering.
TimeMaster II H.O.™ is a trademark of Applied Engineering.
Applied Engineering
P.O. Box 798
Carrollton,
Texas 75006
Sales: (214) 241-6060 9AM 11 PM 7 days
Technical Support: (214) 241-6069 9AM 5 PM Monday Friday
-
-
-
Contents
Introduction.......................................................................................................................1
Read Me First I .........................................................................1
About TPCE (TimeMaster ProDOS Command Extensions)...1
For More Information.................................................................1
Getting Started................................................................................................................2
What is Required......................................................................2
Installing TPCE........................................................................2
Command Syntax ....................................................................3
TimeMaster II H.O.
ProDOS Command
Extensions.........................................................................................................................3
The New Commands...............................................................3
Time and Date Commands......................................................4
TIME.....................................................................................4
CLOCK ................................................................................4
ALARM.................................................................................5
SET ......................................................................................5
Stopwatch Timer Commands..................................................6
RESET...............................................................................7
START ...............................................................................7
STOP .................................................................................7
WATCH ..............................................................................7
TIMER................................................................................7
Interrupt Commands.................................................................8
RATE.................................................................................8
LINK...................................................................................8
Miscellaneous Commands........................................................8
BSR...................................................................................8
SLOT.................................................................................9
QUIT..................................................................................9
HELP..................................................................................9
Calling TPCE from
Assembly Language
Programs..................................................................................................................................9
Introduction
Read Me First!
This manual is included as a supplement to the Applied Engineering TimeMaster II
HO. User’s Manual and is intended for use by Applesoft BASIC and assembly
language programmers It explains how to install and use the TimeMaster ProDOS
Command Extensions. You will have no need for this information unless you are
writing your own programs.
About TPCE (TimeMaster ProDOS Command Extensions)
The program file, TPCE, on the TimeMaster II H.O. ProDOS Time Utilities disk ,
when executed, will add 15 new BASIC commands. These commands provide a kit
of convenient and powerful tools for using the many features of the TimeMaster II
HO. clock card from within your ProDOS programs. You will be able to use these
commands to set and display the TimeMaster II HO. time; use a Stopwatch timer
which runs concurrently with your program; use your TimeMaster II H.O., card as
an alarm clock; set the desired interrupt rate; schedule a call to an assembly
language subroutine at specific intervals; send command strings to a BSR X-10
device; and more. The uses are limited only by your imagination!
TPCE was designed to work with ProDOS version 1.1.1 and BASIC.SYSTEM
version 1.1, both of which are included on the TimeMaster II H.O. ProDOS Time
Utilities disk. TPCE will not operate with other command interpreters; only
BASIC.SYSTEM TPCE was also designed to utilize the many features available
ONLY on the TimeMaster II H.O. clock card.
TPCE uses 4096 bytes of memory and installs between the ProDOS file buffers
and BASIC.SYSTEM HIMEM is automatically lowered to $8600. The actual
location of TPCE is from $8A00 to $99FF.
For More Information
This supplement assumes the reader is somewhat familiar with Apple’s
Professional Disk Operating System (ProDOS), the Applesoft BASIC programming
language, and the internal operation of the //e computer. Additional information
can be found in the following manuals:
Applesoft BASIC Reference Manual
(Addison-Wesley Publishing 1-800-238-3801)
Apple lle Reference Manual (Apple Computer, Inc.)
ProDOS User’s Manual (Apple Computer, Inc.)
Beneath Apple ProDOS (Quality Software) by Don Worth and Pieter
Lechner
BASIC Programming with ProDOS
(Addison-Wesley Publishing 1-800-238-3801)
TimeMaster II HO. User’s Manual (Applied Engineering)
1
Getting Started
What Is Required
This is all you need to use the TimeMaster ProDOS Command Extensions:
•
•
•
•
•
An Apple II+ or //e (standard or enhanced) with at least 64K of memory.
A TimeMaster II HO. card installed in the proper expansion slot.
(see the TimeMaster II HO. User’s Manual)
One disk drive
A monitor capable of displaying a 40 column screen
ProDOS 1.1.1, BASIC.SYSTEM 1.1 and TPCE.
The switches on the TimeMaster II HO. should be in the following configuration.
Switch 1
Switch 2
Switch 3
Switch 4
Closed (on)
Open (off)
Open (off)
Closed (on)
Set-protect disabled
TimeMaster Mode enabled
Non-Maskable Interrupts disabled
Interrupt Request enabled
The revision of the TimeMaster Il H.O. ROM should be .5 or greater. (The revision
number label is on the 24 pin ROM chip on the TimeMaster II HO. card.) Earlier
ROM will work,but make sure to use the TPCE commands to read the clock, NOT
Applesoft BASIC IN# and PR# commands.
Note: Apple Computer’s FILER program (version 1.1) has been included on the
TimeMaster II HO. Time Utility disk. Please use it to make a backup copies of the
TimeMaster II H.O. utility disks. Then store your originals in a safe place!
CON VERT (version 1.2) is also included to allow conversion of DOS 3.3 files to
ProDOS format. See the TimeMaster II H.O. User’s Manual for details on which
files are convertible.
Installing TPCE
The installation of the TimeMaster ProDOS Command Extensions is accomplished
by loading PRODOS, BASIC.SYSTEM, then executing the binary file named
TPCE. TPCE can be executed from either the immediate (keyboard) or deferred
(program) mode. TPCE can also be installed by booting the TimeMaster II HO.
ProDOS Time Utility disk and selecting the option “Install TPCE and exit to BASIC”
from the main menu.
The TimeMaster II H.0. slot is automatically determined during execution of TPCE,
which takes about two to three seconds. Successful installation from the
immediate mode is indicated by an on-screen message. No message is presented
upon successful installation from the deferred mode.
2
TPCE remains active until one of the following conditions is encountered:
• TPCE ‘QUIT command
• System power-down or re-boot
• Execution of another ProDOS SYSTEM file.
• Execution of another BASIC enhancement program
(Double-Take, GPLE, APA)
Command Syntax
In the descriptions and examples which follow, the commands are all shown in
upper case, with spaces inserted merely for clarity. TPCE will, however, accept
both upper and lower case characters and ignore all spaces between commands
and arguments.
TimeMaster II H.O.
ProDOS Command
Extensions
The New Commands
This section contains descriptions of each of the 15 new BASIC TPCE commands.
The command are grouped into four categories; time and date commands,
stopwatch commands, interrupt commands, and miscellaneous commands.
For your convenience, one of the new commands is HELP. The HELP command
displays a screen full of information, listing and describing the other 14 TPCE
commands. Figure 1 is an illustration of the HELP screen.
Figure 1 TPCE “HELP” Screen
--
TIMEMASTER PRODOS COMMAND EXTENSIONS
--
TIME....... RETURN CURRENT DATE AND TIME
CLOCK.. SHOW DATE AND TIME CONTINUOUSLY
ALARM.. SETALARMATSPECIFIED TIME
SET .......SETORADJUSTDATE OR TIME
RESET.... STOP AND CLEAR ELAPSED TIMER
START....START ELAPSED TIMER
STOP..... STOP ELAPSED TIMER
TIMER.... RETURN ELAPSED TIMER VALUE
WATCH.. SHOW ELAPSED TIMER CONTINUOUSLY
RATE ......SET OR RETURN INTERRUPT RATE
LINK........ LINK USER PROGRAM TO INTERRUPT
SLOT...... RETURN SLOT NO. OF TIMEMASTER
BSR........ SEND BSR COMMANDS (*,A~V)
QUIT....... DEACTIVATE TPCE
3
Time and Date Commands
TPCE allows you to read the current time and date in any of six formats, provides
an option to display the time and date continuously on the screen, set the
TimeMaster II H.O. to a new time and date, and set an alarm to go off at a specified
time.
TIME
The TIME command displays the current date and time. If no format is specified
the default format will be used. When you specify a particular format, that format
becomes the new default.
TIME
TIME:
TIME S
TIMEM
TIME &
TIME%
TIME#
display date and time in the default format
display as: FRI 11/15/85 15:45:25 (initial default)
display as:
15-NOV-85 15:45
display as:
11/15 15:45:25.234
display as:
FRI NOV 15 15:45:25
display as:
FRI NOV 1503:45:25 PM
display as:
85,11,05,15,15,45,25.234
This also allows you to read the time from an Applesoft program, in whatever
format you choose. The sample routine, below, will read the date and time in the
":" format into the string variable TM$.
1200 PRINT CHR$(4); “TIME:”
1210 INPUTTM$
The first six TIME formats above will return strings. The “#“ format returns seven
numeric values, the sequence of which is detailed in the SET command
description. This format would be read in the following manner:
1200 PRINT CHR$(4) ;IiME#”
1210 INPUTY, MO, W, D, H, MI, S
CLOCK
This displays the time and date in the MO/DD HH:MM:SS format on the screen at a
specified position. If you do not specify a position, the display will appear on the
top line, starting at column 26 on a 40-column screen or column 51 on an
80-column screen. (Only standard Apple lie 80-column display is supported.)
CLOCK
CLOCK 24,1
CLOCK OFF
display at line 1, column 26 (initial default)
display at line 24, column 1
turn off the date/time display.
If you are using a standard Apple //e 80-column display, the column number will be
doubled and decremented by one. Therefore, CLOCK 1,26 will display the date
and time starting at column 51.
You may specify any line or column number you wish, between 0 and 99. If you
specify a line number greater than 24, TPCE will assume you really meant 24 (the
bottom line). If the column argument specified is larger than 26 while in the 40
column mode, the CLOCK display will default to column 26. The display will be
justified against the right side of the screen. The same is true for the 80 column
display except that the default column will be 51.
4
The CLOCK display is written directly to the screen, so it will not appear on any
other output device. If you select any line below the top line, copies of old times
will be scrolled up the screen whenever the screen scrolls.
ALARM
This command allows you to use your l /e and TimeMaster II H.O. as an alarm
clock. The alarm can be set to “go off” at a specific time or at an interval measured
from the present time. The examples, below, illustrate the various arguments used
to set the ALARM.
ALARM +10
Set alarm to go off in ten minutes (interval)
ALARM +3:15
Set alarm to go off in 3 hours and 15 minutes (interval)
ALARM 5:30 PM
Set alarm to go off at 5:30 PM
ALARM 5:30 AM
Set alarm to go off at 5:30 AM
ALARM 17:30
24 hour clock notation; same as 5:30 PM
ALARM 5:30
24 hour clock notation; same as 5:30 AM
ALARM
Silence alarm or cancel a previously set alarm.
The alarm sounds for one minute, beeping the lie speaker at two-second intervals.
You can silence the alarm by typing “ALARM”. The beep is a lower pitch than the
standard Apple “bell”. Depending on the interrupt RATE, there are two possible
ALARM tones.
You can only have one alarm setting active at a time. The interval ALARM is
accurate to the nearest TimeMaster II HO. minute cycle.
SET
This command allows you to reset the date or time on the TimeMaster II HO. card.
There are actually six commands in one, allowing many different ways of changing
the date and time. One of them is very useful for changing back and forth between
Standard and Daylight Savings Time. Another makes it easy to synchronize, down
to the second, with another clock.
SETH
SETH +x
SETH -x
SETHx
Allows you to increment, decrement, or set the hour.
Add x to the current hour (modulo 24)
Subtract x from the current hour
Set the hour to x
The parameter “x” may be any value from 0 to 99. The arithmetic is done modulo
24. For example, if you type “SETH+20” when the hour is 11, the result will be 7.
(11+20 = 31 = 7mod24).
In the Fall if you switch to Standard time, type SETH-1 to adjust your TimeMaster II
H.O. When Daylight Savings Time starts, type SETH+1.
SETM
SETM +x
SETM -x
SETM x
Allows you to increment, decrement, or set the minute.
Add x to the current minute (modulo 60)
Subtract x from the current minute
Set the minute to x
The parameter “x” may be any value from 0 to 99. The arithmetic is done modulo
60. For example, if you type “SETM+20” when the minute is 51, the result will be
11. (51+20=71=11mod6O)
5
SETW
SETW +x
SETW -x
SETWx
Allows you to increment, decrement, or set the day of week.
Add x to the current day of week (modulo 7)
Subtract x from the current day of week
Set the day of week to x
The parameter “x” may be any value from 0 to 99. The arithmetic is done modulo 7.
For example, if you type “SETW+5” when the day of week is 4, the result will be 2.
(4+5= 9=2mod7)
The days of the week are represented by the integers 0 through 6, where
0=Sunday, 1=Monday, 6=Saturday.
...
SETT Command: lets you directly specify the time of day.
SETT 5:30
Sets time to 5:30 AM
SETT 5:30 PM
Sets time to 5:30 PM
SETT 17:30
24 hour clock notation; sets time to 5:30 PM
Note that the TimeMaster II H.O. is always in 24-hour mode internally, but will
format the time any way you wish. Remember that the hour starting at midnight is
called either 00:xx or 12:xx AM; the hour starting at noon is called either 12:xx or
12:xx PM.
SETD Command: permits you to set a new date into the TimeMaster II HO, card.
You can specify the date in either of two formats:
SETD mm/dd/yy
SETD yylmm/dd
Also, you may separate the fields with any non-numeric character, including “"-"“ or
comma. TPCE distinguishes which of the two formats you have used by the fact
the the year must be at least 85. After 1999) this feature will stop working until
2085. If you are still using TPCE after 1999 A.D., congratulations!
SETS Command: stores 00 into the seconds register on the TimeMaster II HO.
card.
There are no parameters, you merely type “SETS” and press the RETURN key.
This allows you to easily synchronize to the seconds display with another time
source. Simply use the “CLOCK” command so that the time with seconds is
continuously displayed on the screen. Then type “SETS” (don’t hit RETURN yet)
and start watching your other time source. At the instant you see 59 seconds on
the external time source, hit the RETURN key. Then you can use SETM, SETH, or
SETT to adjust the hours and minutes if necessary.
Stopwatch Timer Commands
A stopwatch-like timer is included in TPCE. It can measure time intervals with
either second or millisecond precision, according to the interrupt RATE you select.
The total value of the accumulated time can go to 6 days, 23 hours, 59 minutes,
and 59.999 seconds. (After that it starts over.)
6
If you have the interrupt rate set at one-per-second, the times are also useful for
timing programs. If the interrupt rate is set at 1024-per-second, the interrupt
overhead slows the Apple down significantly; in this case, timing of program
execution is meaningless. The faster interrupt rate is quite handy for timing
external events, though.
At the 1024-per-second interrupt rate, a six-digit
.000977 on every interrupt. The counter is initialized
ticks. If you do disk I/O or other operations which
millisecond ticks may be missed. On the next second
re-synchronized.
counter is incremented by
to .000528 when the second
disable the interrupts, some
tick, the milliseconds will be
RESET
This command stops the stopwatch if it is running,
time to 0.
and clears the accumulated
START
This command starts the stopwatch from where it last stopped. (If the stopwatch
is already running, this does nothing.)
STOP
This stops the stopwatch timer, unless it is already stopped.
WATCH
This command is similar to the CLOCK command, except that the stopwatch time
is displayed continuously rather than the date/time. The default position is line 1,
column 1. You may place it anywhere on the screen, just like the CLOCK
command. Both CLOCK and WATCH can be active at the same time.
WATCH
WATCH 13,5
WATCH OFF
TIMER
Display stopwatch value at line 1, column 1
Display stopwatch value at line 13, column 5
Turn off stopwatch display
The display will show millisecond values if the interrupt rate is set to
1024-per-second. At a one-per-second rate, the millisecond display will always
show".000”.
The stopwatch value at the instant this command is entered is displayed. If you
issue this command from an Applesoft program, a following INPUT statement will
read the stopwatch time into a string variable:
1200 PRINT CHR$(4);”TIMER”
1210 INPUT SW$
7
Interrupt Commands
RATE
This command sets the interrupt rate, and displays the setting. You may select
one of three interrupt rates: never, slow, and fast. When you first install TPCE,
the interrupt rate is set at 1 Hz (once per second). Consequently, all times will be
shown in exact seconds, with .000” for the millisecond portion. If you use the
RATE command to change this rate to 1024-per-second, milliseconds will be
counted and displayed.
RATE
RATE 0
RATE 1
RATE 2
display the current RATE selection
stop the interrupts (until a new RATE)
interrupt at 1024-per-second rate
interrupt at one-per-second rate (initial default)
In all four cases, TPCE responds by printing the selected rate. If you issue the
RATE command from an Applesoft program, follow it with an INPUT command to
read the rate into a string variable.
The overhead at the 1024-per-second rate is extremely high, slowing execution of
programs down to a snails pace (still faster than some other personal computers,
though). This overhead is mostly inside the Apple monitor ROM and the ProDOS
interrupt handler.
LINK
This allows you to schedule your assembly language subroutine to be called (with
a JSR command) at a specific interval. The examples, below illustrate this.
LINK $300
LINK 0:0:1 0,$300
LINK 5:20,$300
LINK
JSR $300 at every TimeMaster II HO. interrupt
JSR $300 every 10 seconds
JSR $300 every 5 hours, 20 minutes
stop calling your interrupt subroutine
When your interrupt subroutine is called, the registers have already been saved.
You can do whatever you wish, then return with an RTS instruction. You cannot
depend on the monitor ROM being switched on; in fact, it probably will not be. If
you change any soft-switches, be sure to put them back like they were before you
return.
If the carry flag is set when you return from your interrupt subroutine, the LINK will
stay engaged. If carry is clear, the LINK will be disabled.
Miscellaneous Commands
BSR
This command allows you to send command strings to your BSR X-1 0 device,
assuming you have one connected to your TimeMaster II HO. The format is
straightforward:
BSR xxxx where “xxxx” indicates any string of BSR codes.
The valid BSR codes are the letters A through V, and (See pages 11-14 of the
TimeMaster II HO. User’s Manual.)
~.
8
SLOT
This command returns the slot number of the TimeMaster II HO. card. If you issue
this command from an Applesoft program, follow it with an INPUT command to
read the slot number:
1200 PRINT CHR$(4);”SLOT
1210 INPUTS
QUIT
This command removes all trace of TPCE from memory. (Don’t worry, it is still on
the disk.) The installation process is reversed, returning BASIC.SYSTEM to its
original state.
HELP
This command displays the HELP screen, providing an on-screen summary of
WOE commands.
Calling TPCE from
Assembly Language
Programs
You can use TPCE from assembly language programs, as long as you are
operating under BASIC.SYSTEM. There are two pre-defined entry points.
JSR $8A03 will read the current time and date, and store it into the nine bytes
starting at $8A06. The clock values assigned to the memory locations $8A06
through $8AOE are shown below.
$8A06: year
$8A07: month
$8A08: day of month
$8A09: day of week
$8AOA: hour
$8AOB: minute
$8AOC: second
$8AOD: milliseconds (most significant 2 digits)
$8AOE: milliseconds (least significant digit)
Each of the values is stored in BCD form. Therefore, if the year is 1985, $8A06 will
contain $85. The millisecond count is in two bytes: the first two digits in $8AOD,
and the third digit in $8AOE (as $xO).
JSR $8A00 will allow you to issue any of the TPCE commands, in either
immediate or deferred mode. In immediate mode, the output from the TIME,
TIMER, RATE, and SLOT commands goes directly to the current output device
(usually the screen, but not necessarily). In deferred mode, the output from those
four commands is placed in the buffer starting at $0200. The output will be in
ASCII, with high bit set, and terminated by a return character ($8D).
9
In the routines shown below, the string address must be the address of your
command buffer. It must contain an ASCII string terminated by a return character
($8D or $0D). The contents of the ASCII string should be a valid TPCE command.
TPCE copies the string to the buffer at $200, and then calls the regular TPCE
parser to execute your command.
CLC
;signal immediate mode
JSR $8A00
;call TPCE
.DA string.address
BCS ...error
SEC
;signal deferred mode
JSR $8A00
;call TPCE
.DA string.address
BCS ...error
If the carry flag is set when $8A00 returns, an error is indicated. The possible error
codes, stored in the accumulator, are:
$01
did not recognize the command name
$02
command string was longer than 63 characters
$10
syntax error or range error in command
10
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement