AppleIIAsm-Collection/documentation/AppleIIAsm Library Collection Technical Manual/0.6.0/31.0 Detailed_Reference_D2_STDIO.md

Disk 2 : STDIO Library and Aliases

• Part I: The STDIO Library
  • STDIO Components
  • STDIO Header File
  • Next Up: STDIO Macros
    • The COL40 Macro
    • The COL80 Macro
    • The DIE80 Macro
    • The MTXT0 Macro
    • The MTXT1 Macro
    • The TGBDC Macro
    • The TGBEC Macro
    • The CURF Macro
    • The CURB Macro
    • The CURU Macro
    • The CURD Macro
    • The RCPOS Macro
    • The SCPOS Macro
    • The SETCX Macro
    • The SETCY Macro
    • The INP Macro
      • The SINPUT Subroutine
    • The GKEY Macro
    • The WAIT Macro
    • The PBX Macro
    • The PDL Macro
    • The PRN Macro
      • The XPRINT Subroutine
      • The DPRINT Subroutine
    • The SPRN Macro
      • The PRNSTR Subroutine
    • The PRNC Macro
      • The COLPRINT Subroutine
    • The PRNM Macro
    • The PRNW Macro
    • The PRNMW Macro
    • The TLINE Macro
      • The TBLINE Subroutine
    • The TCIRC Macro
      • The TCIRCLE Subroutine
    • The TVLIN Macro
      • The TVLINE Subroutine
    • The THLIN Macro
      • The THLINE Subroutine
    • The TRECF Macro
      • The TRECTF Subroutine
    • The TPUT Macro
      • The TXTPUT Subroutine
    • The TCLR Macro
      • The TXTCLR Subroutine
    • The TPNT Macro

PART I: STDIO Macros and Subroutine Library

The second disk inthe AppleIIAsm Collection includes all of the macros, subroutines, vectors and reserved memory locations for standard input and output on the Apple II. Note that by "Standard Output," we are primarily referring to the text screen only, and 40-column mode at that. A separate disk, as part of the "inessential" collection, will deal with 80-column mode as well as devices like printers. As for "Standard Input," here we refer to the keyboard and game paddle, though there are plans to also include optional mouse macros and subroutines (in some cases, the mouse is dealt with in the same fashion as the game paddle). Note that as with all libraries, the STDIO library will not function properly without the REQUIRED library.

---

STDIO Components

The STDIO library contains the following components:

• A header file with various hooks, vectors and definitions for the rest of the library as well as use by the end programmer.
• Macros and subroutines dedicated to standard input and output, which includes keyboard and paddle input routines, 40-column text printing routines, basic text-mode drawing routines, and various macros and subroutines that support other functions provided by the Apple II that don't fit into the previous categories so well.
• Note that some routines use COUT, while others use direct screen memory manipulation (which is why some macros, especially those for drawing, will not translate to 80-column mode). Whether a macro uses COUT or direct memory access is revealed in the macro's or subroutine's given entry.

Macros are largely grouped here by function rather than by a more arbitrary aphabetical scheme, as used in the REQUIRED library documentation. First, macros and subroutines that do not fit in with any of the other categories will be covered. This seems counterintuitive at first, but hopefully the reasoning for it will reveal itself as the documentation is read (long story short: these miscellaneous subroutines can have drastic effects on the rest of the subroutines). Next, COUT cursor macros and subroutines are detailed, followed by standard input routines and screen output routines that rely on COUT for funtionality.

Lastly, macros and subroutines that directly access screen memory to output characters are covered. Usually, these subroutines and macros are dedicated to creating shapes, lines, and ASCII art in general. Note that while this can be used in tandem with the macros and subroutines that use COUT, the standard COUT routine will not recognize that these characters have been plotted, and the cursor position will remain the same as before.

---

STDIO Header File

Summary

The STDIO header file is required for all macros and subroutines to work correctly, although there may be a select few that can get away without its inclusion. Primarily, this header file contains vectors and hooks that point to routines found in the Monitor.

Condition	Value
Name	File: HEAD.STDIO.ASM
Type	Header File
Author	Nathan Riggs
Last Revision	19-JAN-2020
Assembler	Merlin 8 Pro
OS	Apple DOS 3.3
Purpose	Provide appropriate hooks for standard input and output
Dependencies	none
Bytes	0
Notes	Repeatedly used subroutines by the library may be placed here in the future

---

DETAILS

As with all files in the collection, this header file includes a short heading that provides contact information, date last changed, number of bytes, a short description, etc.

Listing 2.0: HEAD.STDIO File Heading

*
*``````````````````````````````*
* HEAD.REQUIRED                *
*                              *
* THESE ARE HOOKS THAT ARE     *
* USED BY THE STDIO LIBRARY.   *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      19-JAN-2020       *
* ASSEMBLER: Merlin Pro 8      *
* OS:        DOS 3.3           *
*                              *
* BYTES: 0                     *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*

Most of the pointers in the STDIO header are rather self-explanatory, and therefore will not be covered here. When used, some of these may be explained more in the macro or subroutine documentation.

Listing 2.1: HEAD.STDIO CODE

*
*``````````````````````````````*
* HEAD.STDIO.ASM               *
*                              *
* THESE ARE HOOKS, VECTORS AND *
* POINTERS THAT ARE USED BY    *
* THE STDIO LIBRARY.           *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      19-JAN-2020       *
* ASSEMBLER: MERLIN 8 PRO      *
* OS:        DOS 3.3           *
*                              *
* BYTES: 0                     *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
* OUTPUT
*
COUT1	EQU		$FDF0 		; FASTER SCREEN OUTPUT
COUT	EQU 	$FDED 		; MONITOR STD OUTPUT
HOME	EQU 	$FC58 		; CLEAR SCREEN, HOME CURSOR
VTAB	EQU 	$FC22 		; MONITOR CURSOR POS ROUTINE
CURSH	EQU 	$24  		; HPOS OF COUT CURSOR
CURSV	EQU 	$25 		; VPOS OF COUT CURSOR
KEYBUFF	EQU 	$0200 		; KEYBUFFER START
GSTROBE	EQU 	$C040 		; GAME CONNECTOR STROBE
GBCALC	EQU 	$F847 		; SCREEN CALCULATION
GBPSH	EQU 	$26 		; VALUE RETURNED BY GBCALC
*
* INPUT
*
KYBD	EQU		$C000   	; LDA SINGLE KEYPRESS
STROBE	EQU		$C010   	; CLEAR KYBD BUFFER
GETLN	EQU		$FD6F 		; MONITOR GET LINE OF KB INPUT
GETKEY	EQU		$FD0C 		; MONITOR GET SINGLE KEY INPUT
*
* PADDLE ADDRESS LABELS
*
PREAD	EQU		$FB1E 		; READ STATE OF PADDLE
PB0		EQU 	$C061 		; PADDLE BUTTON 0
PB1		EQU		$C062 		; PADDLE BUTTON 1
PB2		EQU		$C063 		; PADDLE BUTTON 2
PB3		EQU		$C060 		; PADDLE BUTTON 3
*
** UNUSED BY LIBRARY
*
WNDLEFT	EQU 	$20 		; SCROLL WINDOW LEFT
WNDWIDTH EQU  	$21 		; SCROLL WINDOW WIDTH
WNDTOP	EQU 	$22 		; SCROLL WINDOW TOP
WNDBOT	EQU 	$23 		; SCROLL WINDOW BOTTOM
TEXTP1	EQU 	$0400 		; START OF TEXT PAGE 1
TEXTP2	EQU 	$0800 		; START OF TEXT PAGE 2
PAGE1	EQU 	$C054 		; SOFT SWITCH USE PAGE 1
PAGE2	EQU 	$C055 		; SOFT SWITCH USE PAGE 2
S80COL	EQU 	$C01F 		; READ ONLY; CHECK IF 80C
TXTSET	EQU 	$C051 		; TEXT ON SOFT SWITCH
SETWND	EQU 	$FB4B 		; SET NORMAL WINDOW MODE
CURADV	EQU 	$FBF4 		; ADVANCE CURSOR RIGHT
CURBS	EQU 	$FC10 		; CURSOR LEFT
CURUP	EQU 	$FC1A 		; CURSOR UP
CR		EQU 	$FC62 		; CARRIAGE RETURN TO SCREEN
LF		EQU 	$FC66 		; LINE FEED ONLY TO SCREEN
CLEOL	EQU 	$FC9C 		; CLEAR TEXT TO END OF LINE
OPAPP	EQU 	$C061 		; OPEN-APPLE KEY
CLAPP	EQU 	$C062 		; CLOSED-APPLE KEY