Introduction to Branching

Case via A Register  - ACASE1, ACASE2, ACASE3
Case via HL Reg Pair - HCASE1, HCASE2, HCASE3
Computed GOTO via A  - AGOTO1, AGOTO2, BGOTO1, BGOTO2
Computed GOTO via HL - HGOTO1, HGOTO2, DGOTO1, DGOTO2
Arithmetic IF via A  - AIF1, AIF2
Arithmetic IF via HL - HIF1, HIF2
-------------------------------------------------------------
		Introduction to Branching

The routines in this section deal with conditional branching
via CASE, Computed GOTO, and Arithmetic IF constructs.  The
following example illustrates the case concept:

          < register A = key value >
	CALL	ACASE1
	DEFB	SIZE		; Number of Entries in Table
	DEFW	ERROR		; ..Go Here if No Match
	DEFB	VAL1		; First value to test for
	DEFW	ADDR1		; ..Go Here if A = VAL1
	DEFB	VAL2		; 2nd value to test for
	DEFW	ADDR2		; ..Go Here if A = VAL2
	...
	DEFB	VALSIZE		 'SIZE' value to test for
	DEFW	ADDRSIZE	; ..Go here if A = VALSIZE

The following example illustrates the Computed GOTO:
	 < register A = index (zero-relative) >
	CALL	AGOTO1
	DEFW	ADDR0		; Go Here if A = 0
	DEFW	ADDR1		; Go Here if A = 1
	...
	DEFW	ADDRN		; Go Here if A = N

The following example illustrates the Computed GOTO with
limits:
	 < register A = index (zero-relative) >
	 < register B = limit >
	CALL	AGOTO1
	DEFW	ADDR0		; Go Here if A = 0
	DEFW	ADDR1		; Go Here if A = 1
	...
	DEFW	ADDRN		; Go Here if A = N
	 < error code >		; ..come here if A > B

The following example illustrates the Arithmetic IF:

	 < register A = key value >
	 < register B = test value >
	CALL	AIF1
	DEFW	ADDRLT		; Go Here if A < B
	DEFW	ADDREQ		; Go Here if A = B
	DEFW	ADDRGT		; Go Here if A > B

The following routines are provided:

     Routine   Comments
     =======   ========
     ACASE1    Case statement with A = key value
     ACASE2    Like ACASE1, but DE = address of case table
     ACASE3    Like ACASE2, but return address is left on stack

     HCASE1    Like ACASE1, but HL = key value
     HCASE2    Like ACASE2, but HL = key value
     HCASE3    Like ACASE3, but HL = key value

     AGOTO1    Computed GOTO with A = key value
     AGOTO2    Like AGOTO1, but JPs rather than DEFW follow

     HGOTO1    Computed GOTO with HL = key value
     HGOTO2    Like AGOTO2, but HL = key value

     Routine   Comments
     =======   ========
     BGOTO1    Like AGOTO1, but B = limit value
     BGOTO2    Like AGOTO2, but B = limit value

     DGOTO1    Like HGOTO1, but DE = limit value
     DGOTO2    Like HGOTO2, but DE = limit value

     AIF1      Arithmetic IF with A, B = values
     AIF2      Like AIF1, but JPs rather than DEFW follow

     HIF1      Arithmetic IF with HL, DE = values
     HIF2      Like AIF2, but HL, DE = values

ACASE1 - Multiway Jump from A Reg Value, Embedded Table

  ENTER: A = Value to test for Branch
  EXIT : None  (branch is made)
  USES : None

 Usage:  ACASE1 is a case statement processor which acts as a
  multiway Jump instruction, since the return address from the
  Call to ACASE1 is not retained.  The value to test is
  compared to values in a case table and control is transferred
  to an associated address if a match is found.

Example:
	LD	A,TEST
	CALL	ACASE1
	DEFB	N	; number of entries in the table
	DEFW	DEFAULT	; go to this address if no match
	DEFB	VAL1	; test for TEST = VAL1
	DEFW	ADDR1	; go here if TEST = VAL1
	...
	DEFB	VALN	; test for TEST = VALN
	DEFW	ADDRN	; go here if TEST = VALN
 ACASE2 - Multiway Jump from A Reg Value, External Table

  ENTER:  A = Value to test for Branch
	 DE = Address of Case Table
  EXIT : None (branch is made)
  USES : None

 Usage:  ACASE2 is a case statement processor which acts as a
  multiway Jump.  The Return Address from the call to ACASE2
  is not retained.  An entry value is compared to values in an
  External Case table and control is transferred to the
  associated address upon a match.

Example:
	LD	A,TEST		; value to test for
	LD	DE,TABLE	; address of table
	CALL	ACASE2
	...
 TABLE:	DEFB	N	; number of entries in the table
	DEFW	DEFAULT	; go to this address if no match
	DEFB	VAL1	; test for TEST = VAL1
	DEFW	ADDR1	; go here if TEST = VAL1
	...
	DEFB	VALN	; test for TEST = VALN
	DEFW	ADDRN	; go here if TEST = VALN

 ACASE3 - Multiway Call from A Reg, External Table

  ENTER:  A = Value to test for Call
	 DE = Address of Case Table
  EXIT : None (branch is made)
  USES : None

 Usage:  ACASE3 is a case statement processor which functions
  as a multiway CALL instruction with the return address from
  the CALL to ACASE3 left on the stack.  The routine is entered
  with a value which is compared to those in a Table and
  control is transferred to an associated address if a match is
  made.

Example:
	LD	A,TEST		; Value to test for
	LD	DE,TABLE	; Address of table
	CALL	ACASE3
     < resume execution here if routines execute a RET instr >
	...
 TABLE:	DEFB	N		; Number of entries in table
	DEFW	DEFAULT		; ..Go here if no match
	DEFB	VAL1		; Test for TEST = VAL1
	DEFW	ADDR1		; ..Go here if TEST = VAL1
	...
	DEFB	VALN		; Test for TEST = VALN
	DEFW	ADDRN		; ..Go here if TEST = VALN

HCASE1 - Multiway Jump from HL, Embedded Table

  ENTER: HL = Value to test for
  EXIT : None  (branch is made)
  USES : None

 Usage:  HCASE1 is a case statement processor where a 16-bit
  value is compared to entries in a table.  Upon a match,
  control is transferred to an associated address.  The Return
  Address from the CALL to HCASE1 is not retained making this
  analagous to a Jump instruction.

Example:
	LD	HL,TEST
	CALL	HCASE1
	DEFW	N		; Number of entries in table
	DEFW	DEFAULT		; ..Go here if no match
	DEFW	VAL1		; Test for TEST = VAL1
	DEFW	ADDR1		; ..Go here if TEST = VAL1
	...
	DEFW	VALN		; Test for TEST = VALN
	DEFW	ADDRN		; ..Go here if TEST = VALN
 HCASE2 - Multiway Jump from HL, External Table

  ENTER: HL = Value to test for
	 DE = Address of Case Table
  EXIT : None  (branch is made)
  USES : None

 Usage:  HCASE2 is a case statement processor where a 16-bit
  value is compared to entries in an addressed table.  If a
  match is found, control is transferred to an associated
  address from the table.  The return address from the CALL to
  HCASE2 is not retained, so this routine functions as a Jump.

Example:
	LD	H,TEST		; Value to test for
	LD	DE,TABLE	; Address of Table
	CALL	HCASE2
	...
 TABLE:	DEFW	N		; Number of Entries in Table
	DEFW	DEFAULT		; ..Go here if no match
	DEFW	VAL1		; Test for TEST = VAL1
	DEFW	ADDR1		; ..Go here if TEST = VAL1
	...
	DEFW	VALN		; Test for TEST = VALN
	DEFW	ADDRN		; ..Go here if TEST = VALN

 HCASE3 - Multiway CALL from HL, External Table

  ENTER: HL = Value to test for
	 DE = Address of Case Table
  EXIT : None  (branch is made)
  USES : None

 Usage:  HCASE3 is a case statement processor where a 16-bit
  value is compared to entries in an addressed table.  Ia a
  match is found, control is transferred to an associated
  address from the table.  The return address from the CALL to
  HCASE3 is retained so this routine functions as a CALL.

Example:
	LD	HL,TEST		; Value to test for
	LD	DE,TABLE	; Address of Table
	CALL	HCASE3
     < resume execution here if routines execute an RET instr >
	...
 TABLE:	DEFW	N		; Number of Entries in Table
	DEFW	DEFAULT		; ..Go here if No Match
	DEFW	VAL1		; Test for TEST = VAL1
	DEFW	ADDR1		; ..Go here if TEST = VAL1
	...
	DEFW	VALN		; Test for TEST = VALN
	DEFW	ADDRN		; ..Go here if TEST = VALN

AGOTO1 - Computed GOTO on A Register

  ENTER:  A = Index Value (zero-relative)
  EXIT : None
  USES : None

 Usage:  AGOTO1 is a computed GOTO based on a specified 8-bit
  value.  No range or limit checking is done s you must insure
  that the computed GOTO does not exceed the table limit.

Example:
	LD	A,INDEX		; Index value
	CALL	AGOTO1
	DEFW	ADDR0		; Go Here if A = 0
	DEFW	ADDR1		; Go Here if A = 1
	...
	DEFW	ADDRN		; Go Here if A = N

 AGOTO2 - Computed GOTO on A Register

  ENTER:  A = Index Value (zero-relative)
  EXIT : None
  USES : None

 Usage:  AGOTO2 is a computed GOTO based on a specified 8-bit
  value.  No range or limit checking is done s you must insure
  that the computed GOTO does not exceed the table limit.

Example:
	LD	A,INDEX		; Index Value
	CALL	AGOTO2
	JP	ADDR0		; Return to this JP if A = 0
	JP	ADDR1		; Return to this JP if A = 1
	...
	JP	ADDRN		; Return to this JP if A = N
	< next instr >		; Return here if A = N+1

 BGOTO1 - Computed GOTO on A Register with Limit Check

  ENTER:  A = Index Value (zero-relative)
	  B = Maximum Index Value allowed
  EXIT : None
  USES : None

 Usage:  BGOTO1 is a computed GOTO based on a specified 8-bit
  value.  A second byte is passed specifying a limit value.
  If the Test value exceeds the Limit, control is transferred
  to after the last address in the table.

Example:
	LD	A,INDEX		; Index Value
	LD	B,LIMIT		; Maximum Index Value
	CALL	BGOTO1
	DEFW	ADDR0		; Go Here if A = 0
	DEFW	ADDR1		; Go Here if A = 1
	...
	DEFW	ADDRLIMIT	; Go Here if A = LIMIT
	< next instruction >	; Return here if A > LIMIT

 BGOTO2 - Computed GOTO on A Register with Limit Check

  ENTER:  A = Index Value (zero-relative)
	  B = Maximum Index Value
  EXIT : None
  USES : None

 Usage:  BGOTO2 is a computed GOTO based on a specified 8-bit
  value.  A second byte is passed specifying a limit value.
  If the Test value exceeds the Limit, control is transferred
  to after the last address in the table.

Example:
	LD	A,INDEX		; Index Value
	LD	B,LIMIT		; Maximum Index Value
	CALL	BGOTO2
	JP	ADDR0		; Return to this JP if A = 0
	JP	ADDR1		; Return to this JP if A = 1
	...
	JP	ADDRLIMIT	; Return to this JP if A=LIMIT
	< next instr >		; Return here if A > LIMIT

HGOTO1 - Computed GOTO on HL Register Pair

  ENTER: HL = Index Value (zero-relative)
  EXIT : None
  USES : None

 Usage:  HGOTO1 is a computed GOTO based on a specified 16-bit
  value.  No range or limit checks are performed, so you must
  insure that the range of the computed GOTO is not exceeded.

Example:
	LD	HL,INDEX	; Index Value
	CALL	HGOTO1
	DEFW	ADDR0		; Go Here if HL = 0
	DEFW	ADDR1		; Go Here if HL = 1
	...
	DEFW	ADDRN		; Go Here if HL = N

 HGOTO2 - Computed GOTO on HL Register Pair

  ENTER: HL = Index Value (zero-relative)
  EXIT : None
  USES : None

 Usage:  HGOTO2 is a computed GOTO based on a specified 16-bit
  value.  No range or limit checks are performed, so you must
  insure that the range of the Computed GOTO is not exceeded.

Example:
	LD	HL,INDEX	; Index Value
	CALL	HGOTO2
	JP	ADDR0		; Return to this JP if HL = 0
	JP	ADDR1		; Return to this JP if HL = 1
	...
	JP	ADDRN		; Return to this JP if HL = N
	< next instr >		; Return here if HL = N+1

 DGOTO1 - Computed GOTO on HL with Limit Check

  ENTER: HL = Index Value (zero-relative)
	 DE = Maximum Index Value allowed
  EXIT : None
  USES : None

 Usage:  DGOTO1 is a computed GOTO based on a specified 16-bit
  value.  A second 16-bit value is passed specifying the upper
  limit of computed values.  If the specified Test value
  exceeds the Limit value, then control is transferred to after
  the last address in the table.

Example:
	LD	HL,INDEX	; Index Value
	LD	DE,LIMIT	; Maximum Index Value
	CALL	DGOTO1
	DEFW	ADDR0		; Go Here if HL = 0
	DEFW	ADDR1		; Go Here if HL = 1
	...
	DEFW	ADDRLIMIT	; Go Here if HL = LIMIT
	< next instruction >	; Return here if HL > LIMIT
 DGOTO2 - Computed GOTO on HL with Limit Check

  ENTER: HL = Index Value (zero-relative)
	 DE = Maximum Index Value
  EXIT : None
  USES : None

 Usage:  DGOTO2 is a computed GOTO based on a specified 16-bit
  value.  A second 16-bit value is passed specifying the upper
  limit of computed values.  If the specified Test value
  exceeds the Limit value, then control is transferred to after
  the last address in the table.

Example:
	LD	HL,INDEX	; Index Value
	LD	DE,LIMIT	; Maximum Index Value
	CALL	DGOTO2
	JP	ADDR0		; Return to this JP if HL = 0
	JP	ADDR1		; Return to this JP if HL = 1
	...
	JP	ADDRLIMIT	; Return to this JP if HL = LIMIT
	< next instr >		; Return here if HL > LIMIT

AIF1 - Arithmetic IF on A Register

  ENTER:  A = Test Value
	  B = Key Value
  EXIT : None
  USES : None

 Usage:  AIF1 is an arithmetic IF facility where a specified
  Key value (in B) is compared to a specified Test value (in
  A).  Branching is done depending on the following tests:
  A < B, A = B, and A > B.

Example:
	LD	A,TEST		; Test Value
	LD	B,KEY		; key value
	CALL	AIF1
	DEFW	ALTB		; Go Here if A < B
	DEFW	AEQB		; Go Here if A = B
	DEFW	AGTB		; Go Here if A > B

 AIF2 - Arithmetic IF on A Register

  ENTER:  A = Test Value
	  B = Key Value
  EXIT : None
  USES : None

 Usage:  AIF2 is an arithmetic IF facility where a specified
  Key value (in B) is compared to a specified Test value (in
  A).  Branching is done depending on the following tests:
  A < B, A = B, and A > B.

     Example:
	LD	A,TEST		; Test Value
	LD	B,KEY		; Key Value
	CALL	AIF2
	JP	ALTB		; Resume at this JP if A < B
	JP	AEQB		; Resume at this JP if A = B
	JP	AGTB		; Resume at this JP if A > B

HIF1 - Arithmetic IF on HL Register Pair

  ENTER: HL = Test Value
	 DE = Key Value
  EXIT : None
  USES : None

 Usage:  HIF1 is an arithmetic IF facility where a specified
  Key value (in DE) is compared to a specified Test value (in
  HL).  Branching is done depending on the following tests:
  HL < DE, HL = DE, and HL > DE.

Example:
	LD	HL,TEST		; Test Value
	LD	DE,KEY		; Dey Value
	CALL	HIF1
	DEFW	HLTD		; Go Here if HL < DE
	DEFW	HEQD		; Go Here if HL = DE
	DEFW	HGTD		; Go Here if HL > DE

 HIF2 - Arithmetic IF on HL Register Pair

  ENTER: HL = Test Value
	 DE = Key Value
  EXIT : None
  USES : None

 Usage:  HIF2 is an arithmetic IF facility where a specified
  Key value (in DE) is compared to a specified Test value (in
  HL).  Branching is done depending on the following tests:
  HL < DE, HL = DE, and HL > DE.

Example:
	LD	HL,TEST		; Test Value
	LD	DE,KEY		; Key Value
	CALL	HIF2
	JP	HLTD		; Resume at this JP if HL < DE
	JP	HEQD		; Resume at this JP if HL = DE
	JP	HGTD		; Resume at this JP if HL > DE