100 REM PORTHELP        Alpha Products Co. Software Division
110 CLS:DEFINT A-Y:DEFSTR Z:Z=CHR$(34):PRINT:PRINT"Alpha Products Newclock-80 port tutorial":PRINT:PRINT
120 PRINT"     This program is an aid to programmers who wish to access":PRINT"the clock directly from the ports, instead of using TSTRING,":PRINT"HITIME, or one of the patches.  ":GOSUB 1080
130 PRINT"The port assignments are:":PRINT
140 PRINT"   INP(188)     --      year, tens digit"
150 PRINT"   INP(187)     --      year, ones digit
160 PRINT"   INP(186)     --      month, tens digit
170 PRINT"   INP(185)     --      month, ones digit
180 PRINT"   INP(184)     --      day, tens digit
190 PRINT"                        also leap year bit
200 PRINT"   INP(183)     --      day, ones digit
210 PRINT"   INP(182)     --      day of week, sun=0,mon=1,...sat=6
220 GOSUB 1080
230 PRINT"and also...":PRINT
240 PRINT"   INP(181)     --      hour, tens digit
250 PRINT"                        also 12/24 hour mode bit
260 PRINT"                        and AM/PM bit
270 PRINT"   INP(180)     --      hour, ones digit
280 PRINT"   INP(179)     --      minutes, tens digit
290 PRINT"   INP(178)     --      minutes, ones digit
300 PRINT"   INP(177)     --      seconds, tens digit
310 PRINT"   INP(176)     --      seconds, ones digit
320 GOSUB 1080:PRINT"If you are using a Model III, you must enable the ports before":PRINT"you can "Z"INP"Z" from them.  This is done by the following BASIC":PRINT"instruction:":PRINT:PRINT"   OUT 236,16":PRINT
330 PRINT"That instruction will enable the ports until an OUT 236 is done":PRINT"which disables them.  Basic does this each time your program":PRINT"exits to the  >";CHR$(95);"  prompt."
340 PRINT"To prevent Basic from doing this, do the following":PRINT:PRINT"   POKE 16912,16":PRINT:PRINT"Do not execute this poke if you have a Model I!!"
350 OUT 236,16:IF PEEK(262)=101 THEN POKE 16912,16
360 GOSUB 1080:PRINT"A technical note for the curious:":PRINT:PRINT"Don't worry if you don't understand the explanation below.  You":PRINT"don't need it to use all of the Newclock's capabilities.":PRINT
370 PRINT"Early Newclocks pull the high bits of the ports low, even though":PRINT"these bits aren't used.  This means that "Z"INP"Z"'s will give you":PRINT"values between 0 and 15.  Alpha Products, may, at some time in"
380 PRINT"the future, change the design so that these bits are left high.":PRINT"This means that "Z"INP"Z"'s will give a value between 240 and 255.":PRINT"If the values that we are "Z"INP"Z"utting are "Z"AND"Z"ed with 15, the"
390 PRINT"highest four bits are ignored (masked).  All the programs":PRINT"supplied with your Newclock ignore these bits, and the examples":PRINT"in this program do as well.":GOSUB 1080
400 PRINT"To read the date, the following lines can be used:":PRINT
410 PRINT"   MNTH = (15 AND INP(186))*10 + (15 AND INP(185))
420 PRINT"   DAY  = (INP(184) AND 3)*10 + (15 AND INP(183))
430 PRINT"   YEAR = (15 AND INP(188))*10 + (15 AND INP(187))
440 PRINT:PRINT"Notice the (INP(184) AND 3).":PRINT"The "Z"AND 3"Z" masks off the leap year bit. (discussed later)":PRINT
450 PRINT"Note:  The parenthesis are mandatory around every one of the":PRINT"(15 and inp( ))'s because of the order of operations in BASIC":PRINT:PRINT"Here's what you get if you execute these statements:
460 MNTH = (15 AND INP(186))*10 + (15 AND INP(185))
470 DAY  = (INP(184) AND 3)*10 + (15 AND INP(183))
480 YEAR = (15 AND INP(188))*10 + (15 AND INP(187))
490 PRINT"   MNTH =";MNTH,"   DAY  =";DAY,"   YEAR =";YEAR
500 GOSUB 1080:PRINT"Here's how the day of the week is read:":PRINT
510 PRINT"   DAYOFWEEK = INP(182) AND 15":PRINT
520 PRINT"DAYOFWEEK will be a number from zero to six."
530 PRINT"     0 = Sunday":PRINT"     1 = Monday":PRINT"     2 = Tuesday":PRINT"     3 = Wednesday":PRINT"     4 = Thursday":PRINT"     5 = Friday":PRINT"     6 = Saturday"
540 DAYOFWEEK = INP(182) AND 15
550 DAYOFWEEK$ = MID$("Sunday   Monday   Tuesday  WednesdayThursday Friday   Saturday  ",DAYOFWEEK*9+1,9)
560 PRINT:PRINT"Your clock says that today is number";DAYOFWEEK;"which is ";DAYOFWEEK$
570 GOSUB 1080:PRINT"Now for the time:":PRINT
580 PRINT"   HOUR = (INP(181) AND 3)*10 + (15 AND INP(180))
590 PRINT"   MIN  = (15 AND INP(179))*10 + (15 AND INP(178))
600 PRINT"   SEC  = (15 AND INP(177))*10 + (15 AND INP(176))":PRINT
610 PRINT"Notice the (INP(181) AND 3) in the HOUR line. This AND 3 masks":PRINT"off the 12/24 hour mode bit and the AM/PM bit.":PRINT
620 PRINT"Remember the parenthesis around all the "Z"AND"Z"'s that you use!!":PRINT:PRINT"Your clock says:":PRINT
630 HOUR = (INP(181) AND 3)*10 + (15 AND INP(180))
640 MIN  = (15 AND INP(179))*10 + (15 AND INP(178))
650 SEC  = (15 AND INP(177))*10 + (15 AND INP(176))
660 PRINT"   HOUR =";HOUR,"   MIN  = ";MIN,"   SEC  =";SEC
670 GOSUB 1080:PRINT"There are three bits that you can read for more information:
680 PRINT:PRINT"These bits are:":PRINT
690 PRINT"The leap year bit":PRINT"The 12 hour/24 hour clock mode bit":PRINT"The AM/PM bit"
700 :PRINT:PRINT"Each bit is either a 0 or a one, but its position within the":PRINT"port will give it a larger value when read in.
710 GOSUB 1080:PRINT"The leap year bit:":PRINT
720 PRINT"The leap year bit will be set if next February gets 29 days.":PRINT"It will be zero if there is no leap year for at least another   year.
730 PRINT:PRINT"To read the leap year bit:"
740 PRINT"   LEAPYEAR = INP(184) AND 4":PRINT
750 PRINT"The "Z"AND 4"Z" masks off the tens digit of the day.  LEAPYEAR will":PRINT"either be a 0, if the bit isn't set, or 4 if it is set.
760 LEAPYEAR = INP(184) AND 4
770 PRINT:PRINT"Your LEAPYEAR is";LEAPYEAR:PRINT"Which means: ";
780 IF LEAPYEAR = 0 THEN PRINT "No leap year for at least 366 days." ELSE PRINT "Next February has 29 days."
790 GOSUB 1080:PRINT"The 12/24 hour mode bit:":PRINT
800 PRINT"Your Newclock-80 can either be a 12 hour clock or a 24 hour":PRINT"clock.  The Newclock-80 knows which type of clock it is by":PRINT"reading the 12/24 hour mode bit.  If the bit is set, the clock"
810 PRINT"is a 24 hour clock. If it isn't, the clock is a 12 hour clock."
820 PRINT:PRINT"To read the 12/24 bit:"
830 PRINT"   HOURMODE = INP(181) AND 8":PRINT
840 PRINT"On your clock:"
850 HOURMODE = INP(181) AND 8
860 PRINT"   HOURMODE =";HOURMODE:PRINT"Which means: ";
870 IF HOURMODE = 0 THEN PRINT "12 hour mode." ELSE PRINT "24 hour mode.
880 GOSUB 1080:PRINT"The AM/PM bit:":PRINT
890 PRINT"If your clock is in the 24 hour mode, this bit is meaningless.":PRINT"If your clock is in the 12 hour mode, this bit is set if it is":PRINT"now PM, or not set if it is now AM.":PRINT
900 PRINT"To read the AM/PM bit:"
910 PRINT"   AMPM = INP(181) AND 4":PRINT
920 PRINT"On your clock:"
930 AMPM = INP(181) AND 4
940 PRINT"   AMPM =";AMPM:PRINT"Which means: ";
950 IF HOURMODE=8 THEN PRINT"Nothing, your clock is in the 24 hour mode.":GOTO 970
960 IF AMPM = 0 THEN PRINT "Ante Meridian." ELSE PRINT"Post Meridian.
970 GOSUB 1080
980 PRINT"That's all there is to reading your Newclock from the ports.
990 PRINT"If you want to set the time in your program, you can use the    "Z"OUT"Z" command."
1000 PRINT:PRINT"For example, to set the minutes, use the following sequence:"
1010 PRINT"   OUT 179, MIN/10":PRINT"   OUT 178, MIN-INT(MIN/10)*10
1020 PRINT:PRINT"Note: you cannot set the seconds directly. Any "Z"OUT";Z;" to ports":PRINT"177 and 176 will reset the seconds to zero, no matter what value":PRINT"you send!"
1030 GOSUB 1080:PRINT"The only "Z"OUT"Z"'s that are tricky are the two that contain extra bits":PRINT:PRINT"For example: If you want to set the time as 10 PM, you must     "Z"OUT"Z" the proper 12/24 bit and the proper AM/PM bit.":PRINT
1040 PRINT"   OUT 181, HOURMODE OR AMPM OR (HOUR/10)"
1050 PRINT"   OUT 180, HOUR-INT(HOUR/10)*10
1060 GOSUB 1080
1070 PRINT"The end.":PRINT:PRINT:PRINT"Hit R to return to main menu, or any other key to review this   information":GOSUB 1090:IF ZX="R" OR ZX="r" THEN RUN"RUNFIRST/BAS" ELSE RUN
1080 PRINT@0,STRING$(15,26);"Hit any key to continue.";
1090 ZX=INKEY$:IF ZX="" THEN 1090 ELSE CLS: OUT 236,16: RETURN
