; Edit version 1.04
;**************************************************************************
;**************************************************************************
;***									***
;***	MusicBox Utilities						***
;***									***
;**************************************************************************
;**************************************************************************
;
; File Name		: MUTILS.Z80
; Library Name		: MUSICBOX.LBR
; Module Build File	: MUSICBOX.ZEX
; Author		: Edmund Cramp
; Creation Date		: 18-Apr-1987
;
; Assembler Name	: Z80ASM (SLR Systems)
; Linker Name		: SLRNKP (SLR Systems)
;
; Ammendment Record
; *****************
; Name		Date		Details of Ammendment
; ----		----		---------------------
; Edmund Cramp	18-Apr-1987	Initial creation.
; Edmund Cramp	19-Mar-1988	Modified for SLR assembler and linker.
; 
; Module Function
; ***************
;
;	This version requires that the standard ZCPR librarys VLIB, Z3LIB
; and SYSLIB be available.  It consists of various subroutines required
; by the ZCPR Music Box program (ZMUSIC.Z80) and can be assembled and linked
; with the SLR assember Z80ASM, and linker (SLRNKP).
;
;**************************************************************************

		NAME	MUTILS

;		===============
;		Global symbols.
;		===============

		PUBLIC	QUIT,INITENV,CHECKBD

;		===================
;		External Referances
;		===================

		; Module referances.
		EXTRN	CVERS,Z3ENV,STACK
		EXTRN	BDOS,RESTART
		; VLIB referances.
		EXTRN	TINIT,DINIT,Z3VINI,CLS,GXYMSG,AT,EREOL
		; Z3LIB referances.
		EXTRN	Z3INIT
		; SYSLIB referances.
		EXTRN	BIST,BIN,BOUT

;		==============
;		External Files
;		==============

		MACLIB	MACROS.LIB	; Macro library
		.REQUEST VLIB		; ZCPR3 librarys...
		.REQUEST Z3LIB		; ...
		.REQUEST SYSLIB		; ...

;		============
;		Local Macros
;		============

;		n o n e

;		=============
;		Local Equates
;		=============

BYTE		EQU	1
WORD		EQU	BYTE*2

;**************************************************************************
;***	Utilities							***
;**************************************************************************

		COMMON	/AREA/
TEMPO:		DEFS	BYTE		; Tempo value.
SNAME:		DEFS	WORD		; Pointer to title string.
		DEFS	WORD		; Start of song pointers

		CSEG
;+
; Deinitialise terminal and exit.
;-
QUIT:		CALL	CLS		; Clear screen.
		CALL	DINIT		; Deinit terminal.
		; 
		LD	SP,(STACK)	; Restore stack pointer
		RET			; Exit to BDOS.

;+
; Test for a command from the console.
; <Ctl C>... Abort.
; <  +  >... Incress tempo.
; <  -  >... Decress tempo.
;-
CHECKBD:	CALL	GXYMSG		; Position cursor and print...
		DEFB	14,10		; Row/column
		DEFB	'Hit ^C to exit at the end of the song.',0
		CALL	GXYMSG
		DEFB	15,10
		DEFB	'"+" to incress or "-" to decress tempo.',0
		; 
		CALL	BIST		; Get console status.
		RET	Z		; Return if nothing pending.
		; Status is READY...
		CALL	AT		; Position cursor
		DEFB	14,10		; Row/column
		CALL	EREOL		; Erase line.
		; Service input...
		CALL	BIN		; Read console (with echo).
		CP	3		; Test for Ctl C...
		JP	Z,QUIT		; Branch to Exit if Ctl C.
		; Not Ctl C.
		CP	"+"		; Incress tempo ?...
		JP	Z,NEWBEAT	; Branch to incress tempo.
		CP	"-"		; Decress tempo ?...
		JP	Z,NEWBEAT	; Branch to decress tempo.
		JR	CHECKBD		; Branch if not recognised.

;+
; Change tempo - Acc is either "+" or "-".
;-
NEWBEAT:	LD	B,10		; Tempo unit (up or down by 10).
		CP	"-"		; Decress ?
		LD	A,(TEMPO)	; Get tempo from common data area.
		JR	NZ,NEWBEAT2	; Branch to incress tempo

		; Decress tempo.
NEWBEAT1:	INC	A		; 
		CP	0FFH		; 
		JR	Z,NEWBEAT9	; Branch on overflow.
		DJNZ	NEWBEAT1	; 
		JR	NEWBEAT9	; Branch on completion.

		; Incress tempo.
NEWBEAT2:	DEC	A		; 
		JR	Z,NEWBEAT9	; Branch on underflow
		DJNZ	NEWBEAT2	; 
		;
NEWBEAT9:	INC	A		; 
		LD	(TEMPO),A	; Update common value.
		RET			; Exit.
;+
; Initialise our local program environment.
;-
INITENV:	LD	HL,(Z3ENV)	; Point to environment address
		LD	A,L		; Check that we have been installed...
		OR	H		; ...
		JP	Z,NOENV		; Branch if not installed.
		; We are installed - initialise.
		LD	HL,(Z3ENV)	; Get environment address...
		CALL	Z3INIT		; Initialise Z3 environ.
		LD	HL,(Z3ENV)	; 
		CALL	Z3VINI		; Init VLIB environ.
		CALL	TINIT		; Init terminal.
		CALL	PANEL		; Display info panel on console.
		RET

;+
; Display Name, version and creation date along with song title.
;-
PANEL:		CALL	CLS		; Clear the screen
		;
		CALL	GXYMSG		; Sign-on.
		DEFB	5,10
		DEFB	'ZCPR3 Music Box.',0
		;
		CALL	GXYMSG		; Display creation date.
		DEFB	7,10
		DEFB	'Created 20-Apr-1987.',0
		; 
		CALL	GXYMSG		; Display version number.
		DEFB	8,10
		DEFB	'Version ',0
		CALL	PVERS		; Print module version number.
		;
		CALL	GXYMSG		; Position cursor and print string.
		DEFB	10,10		; Row/column
		DEFB	'Selection now Playing:   ',0
		;		
		LD	DE,(SNAME)	; Print the songs title.
		LD	C,9		; BDOS print string...
		CALL	BDOS		; ...
		;
		RET

;+
; Read program version number and display it.
;-
PVERS:		LD	HL,CVERS	; Point to version string.
		LD	B,4		; Character counter.
VLOOP:		LD	A,(HL)		; Read char
		INC	HL		; Bump pointer
		CALL	BOUT		; Print character
		DJNZ	VLOOP		; Branch until all done.
		RET			; Exir - done.
		
;+
; Print and error message - program is not installed.
;-
NOENV:		PRINT	NOTINS		; Display message
		JP	RESTART		; Exit.

		DSEG
NOTINS:		STRING	'Please Z3INStall this program before running it.'

		END