LOGICON the logical number manipulator.

What does AND 5FH actually do?  Why is XOR (HL) used in that
program?  What mask will give me the result I need. What will
happen to the Carry flag if I do this...Every assembly language
programmer, beginner or advanced, will ask some of these
questions and hundreds of others over and over.  Logicon has
been designed to save many hours of programming and learning
time.
Any time you wish to see the effect of a Z80 CPU instruction on
a number or on the flags you can now do so, plus you can see it
in Hexadecimal, Decimal and Binary...all at the same time!
Instant conversion from any of 4 bases is available at the
press of your fingers and you can now see how binary and Hex
arithmetic actually works.
Masks and other techniques are right here for you to use, even
if you haven't yet mastered the maths!


The instructions below are not intended to be a tutorial on Z80
CPU operation, only as a guide to using Logicon.

INSTRUCTIONS FOR USE.

Disk:
From DOS READY type: LOGICON and press ENTER.

Tape:
Press ENTER in response to the Memory Size? prompt.
Type SYSTEM then press ENTER.
Type LOGI then press ENTER.
The program will load for about 1 minute.
When the prompt re-appears:
Type /20992 then press ENTER.

The program will load, relocate itself to highest available RAM
as contained in the pointer at 4049H (disk) or 40B1H (tape) and
alter that pointer to protect itself.
From then on LOGICON may be accessed whenever required by the
simultaneous pressing of the 3 keys marked 4,5 & 6.

LEARNING TO USE LOGICON.

The easiest way to learn how to use Logicon is to experiment
with a good summary of Z80 instructions alongside you. As there
are no memory or file altering facilities, no damage can be
done, so go to it with..I hesitate to say...gay abandon.
Just refer to the instruction sheet and/or HELP screens as you
progress and you'll soon get the idea and even come to
understand these instructions!

A few things to keep in mind:
Logicon only manipulates numbers, not registers, it is up to
the operator to provide the correct numerical input that go
with the various operations when simulating those operations.

Any of the logical, arithmetic or shift and rotate Z80 CPU
instructions can be simulated.

For a 2 operand operation, ADD HL,DE for instance, the input
format is: xx ADD yy with xx representing the contents of HL
and yy the contents of DE.

CP ss becomes xx CP yy where xx is the contents of <A> and yy
is the numerical contents or value of any legal operand.

For a 1 operand instruction like RCLA... RLCA xx, or SLA xx
etc. with xx = <A>.

See HINTS AND EXAMPLES at the end of the instuctions.

If you have invoked Logicon from within an executing program,
when you Exit via the E command, control is exactly where it
was at the time of pressing 456 although the original screen
contents are not restored.
Level 2 users will find that no prompt is visible on return to
Basic but can still continue the previous task if they wish.
Pressing ENTER will restore the cursor after an exit.


WARNING: Some programs do not honour the HIMEM pointer and
these may overwrite Logicon.
Programs which do not use the keyboard DCB at 4015H will not
accept the 456 for entry into Logicon.  Fortunately most
programs do use it.
Disk users: If 456 has no effect from within a program (some
Scripsit versions for instance) and if your DOS has a minidos
or some other means of temporarily leaving and re-entering a
program, then use this means to get out and then try 456.


DATA ENTRY
When invoked, the program is in the command mode from which the
Flag and Suffix defaults may be set (see COMMANDS). Press ENTER
and data may be entered for processing..(an ENTER without any
other input will display the Help screens).
A number typed in without an operator will produce a straight
conversion operation when ENTER is pressed or the designated
operation will be performed if an operator is present.
The results of the operation will be displayed on the work area
and the program will go to the command mode to allow saving,
printing etc.
Note that a backslash (/) will abort the current task and
return you to the command mode at any time.


COMMANDS.
Whenever the prompt: "S,C,D,F,P,R,E or ENTER" appears on the
message line, Logicon is waiting for one of those keys to be
pressed and will ignore any not in the list. ENTER is
synonomous with "continue without a command", while any of the
others will perform the tasks designated below.

S...Save.
This command allows results to be kept on view once an
operation has been performed and are returned intact to the
host program for reference when Logicon is exited.
The area from the screen line upon which the command message
appears through to the bottom of the screen is the save area,
while the lines above to the one containing the defaults are
the work area.  When S is pressed as a command, any results on
display in the work area are cleared and transferred to the top
left corner of the save area in a column of half screen width,
while any information already there is moved toward the bottom
of the screen and if the left hand column is full, that data is
moved to the right hand column to eventually be lost from the
bottom right of the screen. Note that Save executed with a
blank work area will insert 1 blank column line.  This is
useful for formatting information on the 16 half-lines
available for storage.

C...Clear Save Area.
Data on display in the save area is erased. Nothing else is
effected.

D...change Default suffix.
Pressing this key produces a short message: "K,B,D or H..."
which is an invitation to select the type of number all
un-suffixed numbers will assume.  On entry HS is the default.

F...Change preset Flag status.
Many of the operations of the Z80 use the contents of the flag
register <F> during execution and others effect that register
according to the results, so it is convenient when planning,
deciphering or debugging a program to be able to have the flags
set to a particular pattern in order to have an accurate
simulation of in-program operations.  On entry to Logicon all
the flags are reset.
When the F command is used, the work area is cleared and 
SZ-H-PNC appears just above the input line while the cursor
flashes directly below the S.  Now you may type a 0 beneath the
flags you want reset, or a 1 for the ones to be set.  Once
ENTER is pressed you will see that the chosen status is
reflected above, on the default line.
Note that if any of the 8 flags are not marked with a 0 or 1
they will be designated as reset (0).  eg. if F mode is entered
and a 0 placed beneath the S and a 1 beneath the Z, and ENTER
is pressed, the flags following Z will show 0's.  Any input
past the 8 will be ignored.
If / is typed before flag setting is complete, the operation
will return to the command mode without affecting any changes.

P...Print the results on the line printer.
The current results on display in the work area will be sent to
the printer after a prompt.  A ROM routine has been used to
send the data in order to allow the use of drivers, spoolers
etc so the system may hang if the printer is not ready.

R...Reset.
This command returns Logicon to the power-up state, clearing
the screen and resetting all defaults.

E...Exit.
This will return control to the host program.  The contents of
the work and save areas will still be visible and if an editor
assembler is being used the appropriate EDIT command will allow
editing of the byte that was under the cursor at the time
Logicon was invoked.  (This works with EDAS and some copies of
Apparat's modified EDTASM).


NUMBER TYPES.
Logicon will accept any mix of 4 types, any of which may be
designated as the default type. ie a number entered without a
suffix will be treated as the default type.
Blank or Asc 0 separators are optional between but not within
numbers and operators.

HS..Hexadecimal
    Range: 00 to FFFF. The last 2 or 4 digits (depending on
operation type) only will be processed if over length with a
default value of 0 if under length.
Single hex characters or digits are acceptable.

BS..Binary or Bit
    Range: 0 to 11111111. As with all number types, leading
zero's are added if the input is less than the length for the
type. So RLCA 101 is processed as RLCA 00000101. The last 8
digits only are considered.                          
DS..Decimal
Range: 0 to 65535 with the last 5 digits being processed. 
However if a number greater than 65535 and less than 100,000 is
.nput then it will have 65536 subtracted from it. eg if input
is 65537 then 00001 will be processed.

KS..Key value
    Range: Any key or SHIFT & key (includes SHIFT DOWNARROW Z
etc).
If the character produced by the key is not normally
displayable, ie below 1FH (CLEAR), then the character echoed to
the screen on the input line will be the key value with 40H
added (bit 5 set) but will be processed as its true value. eg
BREAK has a value of 01 but is displayed as the letter 'A'
which is 41H. Remember that this is only on the input line as
the results display will print Asc values of between 1FH and
FFH only (32 to 255 Dec).
Three keys cannot be entered directly from the keyboard when KS
is the default as they are used to control the modes. These are
ENTER (0DH) and '/' (2FH) and SHIFT LEFTARROW (18H). Full
conversions of those keys must be obtained by inputting their
Hex,Decimal or Binary equivalents.
If a KS is appended to a number when another base is the
default, it is as if the actual key had been pressed. Eg if 1KS
ENTER is the input then tha number processed is 31H (Asc 1).
Logicon uses a RAM routine to obtain most of its keyboard input
in order to allow the use of custom keyboard drivers but if
such drivers are present then the KS values may not be standard
and some keys may not be availabla from the keyboard at all.
Some DOS's also may alter or disable some keys.

TYPES OF OPERATION.
Logicon supports 26 Z80 CPU operations and is intended as a
programmer's aid rather than a general purpose calculator,
though operators + and - are included for easy address and
value calculations during programming.  These 2 operators are
exactly the same as xx ADD yy and xx SUB yy and so can be used
as shorthand when using those operations.

LOGICAL OPERATIONS. (8 bit only).

OR, XOR, AND.
Entry Format: xx OP yy where xx & yy are any value to FF Hex
(255 Dec) and xx represents register A and yy any legal Z80
operand.

Examples: (assuming default suffix HS) 1C AND 05, 10100111BS
XOR 243DS, FFORFF.

GENERAL PURPOSE ARITMETIC AND CPU CONTROL. (8 bit only).

DAA, CPL, NEG.
Entry format: OP xx where xx is the contents of reg <A>.
Eg: DAA 44, CPL01110011BS, NEG126DS.

16 AND 8 BIT ARITHMETIC.

ADD (+), ADC, SUB (-), SBC
Entry Format:  xxxx OP yyyy.

INC,DEC
Entry Format: OP xxxx

All of the above can be done by the Z80 CPU in either 8 bit,
eg...ADD A,ss, or 16 bit...ADD HL,ss, so wherever either method
could be used ie. if both operands are less than or equal to
FFH (255Dec), Logicon displays the results of both 8 & 16 bit
operations with 2 sets of flags. The left set are the 8 bit and
the right are the 16 bit.  If one of the operands is greater
than FFH then only the right hand (16 bit) set of flags will be
shown as the sum could not be done in two 8 bit registers.


CP. (8 bit).
Entry Format:  xx CP yy...xx = <A> and yy = operand #2

As the contents of <A> reg remain unchanged after this
operation, the 3rd line of the result displays the original
contents. ie only the flags are changed.

ROTATE AND SHIFT. (All 8 bit operations).

RLCA,RLA,RRCA,RRA,RLC,RL,RR,RRC,SLA,SRA,SRL.
Entry format: OP xx  where xx is the contents of reg <A>.
The results reflect the contents of <A> after the op.
RLD,RRD.
Entry Format: xx OP yy...xx = <A> and yy representd (HL).  The
contents of the <A> and (HL) after the op. are displayed in
that same order.


The Flag displays.
An underline character (5FH) is used to represent a reset flag
while the initial is displayed if set. Note that the dual
purpose P/V flag shows P whenever it is set, even during
arithmetic operations when it represents the overflow flag. 
Bits 3 and 5 of <F> are apparently random in their status but
have been included in the flag displays ...subtract sign (-)
means set.  Who knows, you may be able to find some use for
them!


HINTS AND EXAMPLES.
You are programming and you have a piece of code like:
CALL  KEYIN      ;Get a keypress in <A>
CP    ?          ;is it shift uparrow?

You need to know the value returned when SHIFT UPARROW is
pressed.  This is the procedure you would use....

1/ Press 456...invoke Logicon
2/ Press the key marked D...for change Default
3/ Press the key marked K...for the Key input mode
      (the work area will clear and a block cursor will
      blink at the left hand side, awaiting input.  Above
      that you will see that the Default Suffix reads KS.)
4/ Press the SHIFT and UPARROW keys simultaneously
      (you will see an uparrow character (5BH) appear at
      the cursor position.)
5/ Press ENTER
       (the value of the shift uparrow combination is
       printed on the right side of the work area thus:
       001B 00027 00000000 00011011
       all beneath the appropriate headings.)
       The effect on the flags is also displayed.

       You now have the option of printing this data on
       your printer by pressing "P".

6/ Press "E" and you will be returned to your editor

You can circumvent steps 2 and 3 above by simply pressing  
ENTER to get to data entry mode, the SHIFT UPARROW as the key
for conversion and typing KS after it.

It is useful to know that if, at the time you pressed 456, you
were editing or inserting data, when you return after pressing
"E" you can continue as if you never left.  ie, say you type
the CP in the example above and now you hit the right arrow
ready for the key value.  You press 456, do the conversion and
press "E" to exit.  The top line of the video display clears
and (in most programs) the editor's cursor re-appears on the
left.  You can now type in the value from the screen left by
Logicon (1BH in this example) plus any comments or whatever. 
When you press ENTER you will see that the data has been
entered even though you could not see the line you were
editing.


During planning a program, you decide you would like to use a
3-key press to invoke an action like a screen print or to load
or execute a m/l module but your binary isn't good enough to
figure out what mask you need.

Enter Logicon and press ENTER to get into the data entry mode. 
Find an illustration of the keyboard matrix in one of your
books and find 3 keys on the same row.  Say you decide that the
keys 234 are the ones you want.  Working from the left of the
row labelled 3810 (where 2,3 & 4 reside) type a 0 for any key
you do not want and a 1 for 4,3,2 and place a BS for binary
suffix after it:
00011100BS 
is what it should look like.  Hit ENTER and you will see that
the number you must CP in your program is 1CH.  So your code
would be:
KBINT   LD   A,(3810H)   ;get keyboard row 
        CP   1CH         ;is 234 pressed?
        JR   Z,SPRINT    ;JR if yes.


You have been reading an assembler listing and you see:
        CALL  KEYIN   ;get key pressed in <A>
        AND   5FH     ;ensure uppercase.

Okay, you know that AND 5F makes a lowercase alphabetic
character into an uppercase one...but how?

Get into Logicon and enter a lowercase "a" (if you have
lowercase on your computer just use the KS suffix after the "a"
but if you haven't, type 61 which is the hex value) then the
AND 5F thus:
61 AND 5F (for no lowercase) or:  a KS AND 5FH
On ENTER you will see the results (ignoring the flags):
     61 00097 01100001
AND  5F 00095 01011111
     41 00065 01000001

Press "S" to save that data on the screen and type 41 ENTER to
confirm that 41H is indeed an uppercase "A".
Examining these results brings a couple of things to light.
..Only 1 bit (bit 5, counting from the right) is changed when
we compare the u/c with the l/c and remembering the rules for
logical AND:
Set a bit only if BOTH bits of the 2 numbers are set.
We could say about this particular example:
ANDing by 5FH ensures that bits 7 and 5 can only be 0's (reset)
no matter what the other number is.
Try AND DF, (11011111B) that works too as bit 5 cannot be 1
after the AND.
This process is known as "masking" and is very useful.
After trying a number of different characters and masks on
Logicon you'll probably get the hang of it and add another
skill to your programming.


You want to know what will happen to the flags when CP 20H is
executed so you can make a conditional jump. The code you have
in mind is:
TSTCHA  LD   A,(HL)      ;get character from buffer
        CP   20H         ;is it a control char?
        JR   ?,CONTRL    ;JR if control char.

Do some tests in Logicon like:
0D CP 20H 
and observe the effect on the flag display in the work area. 
You will see that the Carry flag is set whenever the first
number (which represents the character in <A> register) is less
than 20H so that last line becomes:
        JR   C,CONTRL    ;JR if control char.


As stated earlier, you can do no damage by hitting wrong keys
or entering bad inputs so plunge in and muck about.

If you have problems or just want to talk give me a call or
drop me a line, I'd appreciate your suggestions and comments.
        Grant Glastonbury,
        PO Box 36,
        Langhorne Creek,
        South Aust.  5255.
Telephone (085) 373181 any day from 6am -12 noon or 4pm to 10pm
only please.

Fin.

                                                                                                     