💾 Archived View for mirrors.apple2.org.za › archive › www.textfiles.com › apple › DOCUMENTATION › ni… captured on 2024-08-19 at 03:11:42.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
**************************************
* *
* NIBBLES AWAY III *
* *
* Complete Documentation *
* by *
* Mr. Wiz *
* *
**************************************
Nibbles Away III utilizes a unique programming language called NADOL, the Nibbles Away Disk Optimized Language. This program can be modified by the user at will. This allows NAIII to remain current, no matter what new developments in copy-protection take place. An added benefit is that users can create their own programs under this powerful language. A few examples would be programs which can convert DOS 3.3 files to CP/M, or one which could display a color disk map of files on a disk. NADOL is used in much the same way as Applesoft, so, if you can program in Applesoft, you should feel comfortable with NADOL.
All of the screens, menus and prompts you will use with NAIII were created with the NADOL language.
Using NADOL
-----------
NADOL is an interactive language that can have 2 distinct modes. The first is "immediate" mode where commands are executed as they are typed in. The second is "deferred" mode, where a series of commands is typed in and executed later. From the Main Menu prompt choose the NADOL option. This will display a period (.), which is the prompt for the NADOL immediate mode. Try this command:
PRINT "HELLO" <return>
The word HELLO is printed on the screen. Numeric expressions work in the same manner, such as:
PRINT 5*4 <return> which will print 20 on the screen.
Some commands require variables be passed to their parameters. The variables must first be defined. In this example, the following sequence of commands will read in and display data from sector 5 on track 4:
DEFINE INTEGER TRACK,SECTOR,COUNT,ERR
TRACK=4
SECTOR=5
COUNT=1
RSECT(RBUF,TRACK,0,SECTOR,COUNT,6,1,ERR)
DISPLAY(RBUF,256)
The DEFINE statement creates the four variables which are needed to pass to the RSECT routine. Then the track and sector numbers are assigned to the variables with the "=" operator. The variable COUNT is set to 1 since only one sector is to be read. The RSECT procedure is called to perform the actual read operation. Then the DISPLAY procedure is called to show the data which was just read in. The predefined variable RBUF is a section of memory normally used for raw data reads, but it can be used for any other purpose. In this case, we used it for a temporary storage buffer for the data that was read and displayed.
At any time NADOL is waiting for a response (with the blinking cursor), the CTRL-P key will print the contents of the screen to the printer. The predefined variable PRTSLOT (printer slot) is set to 1 but may be changed with the configuration menu.
Integer variables can range from -32767 to +32768. For some operations, byte variables are desirable. They range from 0 to 255. Integers occupy 2 bytes in memory, bytes occupy 1 byte.
NADOL also allows the use of arrays or groupings of variables. They are referred to by the same name, with the "subscript" distinguishing them. Below is an example of how to create and use an integer array:
DEFINE INTEGER[10] MINE
MINE[0]=1
MINE[4]=5
PRINT MINE[0]+MINE[4]
This would print 6, since the 2 values would be added together. Note that on the Apple II and II+ the right bracket can be entered with shift-M and the left bracket with shift-N from NADOL.
All data managed by NADOL is stored in either integers or bytes or arrays. Many times it is desired to store text data in a program. NADOL has provisions for handling this. Text is stored in byte arrays in a special format. The text starts at element 0, with each additional character in the next sequential location. The last element should be zero indicating the end of the text string.
Normally when an array variable is specified in a PRINT statement, the value of the first element is displayed. In order to print the text contained in a byte array, an exclamation point should be placed in front of its name in the PRINT statement:
DEFINE BYTE[30] STRING
STRING[0]="H"
STRING[1]="I"
STRING[2]=0
PRINT !STRING
Would print HI on the screen.
NADOL uses a number of built-in mathematical expressions including addition (+), subtraction (-), multiplication (*), and division (/); as well as logical operators, <>, <=, =>, =, etc. The order of precedence means that the expression:
5*6+3*4
will result in 42. NADOL first evaluates the 2 multiplcations, since they have highest precedence, then the addition will be performed. Parentheses may also be used in mathematical operations. Logical operators include: AND, OR, XOR. The comparison will return a 1 or 0 depending on the result of the logical operation.
The ASCII value of a character can be used in an expression or comparison. This is accomplished by enclosing the ASCII character in double quotes ("), such that "A" would result in the hexadecimal value 65 being used.
The Editor
----------
NADOL's built-in editor allows scanning of a program as well as insertion and deletion of lines or characters. The editor can handle lines up to 250 characters in length and supports horizontal scrolling to allow long lines to be displayed. The standard editor uses the 40-column display but versions are included to support many 80-column displays.
If no program is in memory, the cursor will be at the top of the screen with [END OF PROGRAM] displayed. This shows that there are no lines of program currently stored.
The editor is invoked by typing EDIT at the '.' prompt. This will display the current program and place the cursor at the top of the screen. The commands of the editor and their descriptions follow:
left arrow Move cursor left one space
right arrow Move cursor right one space
ctrl-A Selects Add mode. All subsequent characters will be
inserted into the current line.
ctrl-B Move to Beginning of line.
ctrl-C Page downwards.
ctrl-D Delete character to right of cursor.
ctrl-E Cursor up one page.
ctrl-F Restores previous contents of line. Undo any changes.
ctrl-I Tab to next tab stop. Tab stops are set every 2 characters.
ctrl-L Insert a new Line at cursor position.
ctrl-N Moves to End of line.
ctrl-Q Quit editor and return to NADOL.
ctrl-R Scroll page upwards.
ctrl-W Move cursor upwards.
ctrl-X Move cursor downwards.
ctrl-Y Deletes the line which the cursor currently occupies.
ctrl-Z Scroll downwards.
NADOL
-----
NADOL is a structured language borrowing from Pascal, Basic, and C. Programs are arranged as one statement per line. Branching is allowed to another part of the program. Programs are entered using the Editor function and executed with the RUN command.
There are 4 options that NADOL can use depending upon the program line contents:
1. Statement - "PRINT (5*6)/3"
2. Assignment - "I=5"
3. Procedure call - "DISPLAY($800,40)"
4. Flow control - IF/ELSE/ENDIF, GOTO, WHILE/ENDWHILE, etc.
Entering the following sample program:
DEFINE INTEGER ME
ME=0
WHILE ME<5
PRINT ME
ME=ME+1
ENDWHILE
PRINT "DONE"
and running it with RUN would procduce:
0
1
2
3
4
5
DONE
The WHILE/ENDWHILE lines are called a block. As long as the contents of the block remain true, the program will stay within the block. In the above example, when ME became greater than 5, the program jumped out of the block. Multiple blocks, or nesting of blocks, are allowed with 8 blocks deep being the maximum.
Several sample programs are contained on the disk. Try running them and changing them to see how the editor and NADOL work together.
Procedures and Functions
------------------------
NADOL has 2 different ways to create subroutines in a program. Procedures perform a set of instructions and return to the main program. Functions pass back a value to the main program.
A sample of a Procedure follows:
DEFINE INTEGER J
PROCEDURE TIMESTWO
J=J*2
ENDPROC
J=8
PRINT J
TIMESTWO
PRINT J
When RUN the results 8 and 16 would be printed.
Functions operate in much the same way as Procedures, except they act as expressions rather than statements. Example:
DEFINE INTEGER J
FUNCTION OURS
%1 = %1 + 1
RESULT = %1 * %1
ENDFUNC
PRINT OURS(7)
J=OURS(6)
PRINT J
As shown, a function is used on the right side of an equate, and returns a value.
NADOL Built-In Statements
-------------------------
The following layout will help explain each statement:
NAME TYPE
---------------------------------------
Purpose
Syntax (optional fields in parentheses)
AUXMOVE Procedure
To move data to or from auxiliary memory in a IIe or IIc.
AUXMOVE(apple addr,aux addr,length,direction)
BEEP Procedure
Sounds a tone.
BEEP(tone,time) range 0-255
CALL Procedure
Executes a machine-language subroutine.
CALL(address,accumulator,X-reg,Y-reg,status)
CATALOG Statement
Display the catalog of a data disk and free space remaining.
CATALOG
CLEAR Statement
Clears all variables.
CLEAR
CLREOL Statement
Clears all text to right of cursor.
CLREOL
CLREOP Statement
Clears all text to right of cursor to end of current page.
CLREOP
COLOR= Statement
Sets the color used in lo-res graphics.
COLOR=expression (0-15)
CONVERT Procedure
Convert a byte array containing ASCII text into an array of hex or decimal values.
CONVERT(source,destina,type,size,count1,count2)
COPY Procedure
Copies a block of data from one location to another.
COPY(source,destina,length)
DEFINE Statement
Allocates space for one or more variables.
(DEFINE) type (n) name (,name)..
DELAY Statement
Pauses for a specific amount of time.
DELAY(expression) in milliseconds
DELETE Command
Removes a file from work disk.
DELETE filename
DISASM Statement
Displays a disassembled listing of machine code.
DISASM(start,label,lines,offset)
DISPLAY Procedure
Displays a block of data in hex.
DISPLAY(start,length)
EDIT Command
Invokes the built-in program editor.
EDIT
FILL Procedure
Fills a section of memory with a value.
FILL(start,length,value)
FIND Procedure
Finds a specified pattern with the ability to ignore bit 7 and
perform wildcard matching.
FIND(start,length1,pattern,length2,7 flag,wild flag,offset)
FLASH Statement
Sets flash mode for printed characters.
FLASH
FILTER Procedure
Copies data into a write buffer, passing it through a 'filter' to
remove unwanted values.
FILTER(start,length,table,number)
FORMAT Procedure
Formats a range of tracks. FORMAT(first,last,volume,interleave,nsect,slot,drive,error)
interleave=name of byte array containing numbers for sectors on tracks
to be formatted
FREE Function
Returns the amount of space available for programs and data.
variable=FREE(x) where x is a dummy expression, usually 0.
GOTO Statement
Transfers program execution to another location.
GOTO labelname
GOTOXY Procedure
Moves cursor to a new location on screen.
GOTOXY(x,y)
HCOLOR Procedure
Sets color for high-res plotting.
HCOLOR=expression (0-7)
HEXPACK Statement
Reads HEX data into byte array, with optional checksum.
HEXPACK name WITH "text" (,checksum)
HIRES Statement
Initializes hi-res graphics mode.
HIRES
HLINE Procedure
Draws a line on lo-res screen.
HLINE(x1,y1,x2)
HOME Statement
Clears screen and places cursor in upper left corner.
HOME
HPLOT Statement
Plots points or draws lines on hi-res screen.
HPLOT(x,y) (TO x,y)...
HSCRN Function
Returns value of a dot on hi-res screen.
variable=SCRN(x,y)
IF, ELSE, and ENDIF Statement
Alters program flow based on a condition.
IF expression
.
(statement executed on true)
(ELSE)
.
(statement executmd on false)
.
ENDIF
IN# Statement
Takes program input from a peripheral slot.
IN#expresion (1-7)
INIT Command
Formats a blank disk for storage.
INIT name
INPUT Procedure
Reads ASCII data from keyboard into a byte array.
INPUT(name,max,count) where max is maximum characters allowed, and
count is name of variable.
INVERSE Statement
Sets inverse mode for all printed characters.
INVERSE
LABEL Statement
Sets a location which can be branched to with a GOTO statement.
LABEL name
LCMOVE Procedure
Moves data to or from the language card.
LCMOVE(mem address,lc address,length,,direction)
where if direction=0 then from LC, if 1 then to LC
LENGTH Function
Returns the length of the text in a byte aray.
variable=LENGTH(name)
LIST Command
Displays the current program.
LIST
LOAD Command
Loads a file from current workdisk.
LOAD filename (AT address)
LORES Statement
Initializes lo-res graphics.
LORES
LSCRN Function
Returns the color of a point on screen.
variable=LSCRN(x,y)
MAKE Procedure
Creates a filter in the specified array.
MAKE(address,length,start,num zeroes,bit length)
MASK Procedure
Sets and clears bits in range of memory.
MASK(start,length,or value, and value)
NEW COMMAND
Erases current program and clears variable space.
NEW
NOT Function
Returns the logical inverse of a value.
variable=NOT(expression)
NORMAL Statement
Returns text display to normal characters.
NORMAL
PACK Procedure
Places a text string into a byte array.
PACK name WITH "text"
PDL Function
Reads a game paddle.
variable=PDL(expression)
PLOT Procedure
Plots a dot on lo-res screen.
PLOT(x,y)
PR# Command
Sends all text output to perpherial slot.
PR#expression (1-7)
PRBLOCK Procedure
Displays a section of memory in a variety of formats.
PRBLOCK(start,length,label,digits,format,count1,count2,space)
where:
length=# of bytes to display
label=first # to show on left margin of screen
digits=# of digits to show of label above (0-4).
format-0=ASCII, 1=HEX, 2=HEX with bytes <$80 in inverse.
count1=# of bytes displayed per line.
count2=# of bytes displayed per grouping on line.
space=# of bytes displayed between groupings on a line.
PRINT Procedure
To display data on screen.
PRINT (expression)(,)(;)(expresion)(,)(;)...
PRINTBYTE Statement
Prints 8 bit hex values.
PRINTBYTE(expression)(,)(;)...
PRINTHEX Statement
Print 16 bit hex values.
PRINTHEX(expression)(,)(;)...
PROCEDURE Statement
Defines a user subroutine.
PROCEDURE name
RECAL Procedure
Moves read/write disk head to track 0.
RECAL(slot,drive)
RENAME Command
Changes name of disk file.
RENAME oldname,newname
READ Function
Reads a character from keyboard.
variable=READ(expression)
RBLOCK Procedure
Reads 1 or more blocks from a ProDOS format disk.
RBLOCK(address,block,count,slot,drive,error)
RESULT Statement
Evaluates expression to be returned as the result of a user defined
function.
RESULT=expression
RSECT Procedure
Reads 1 or more sectors from a disk.
RSECT(address,track,half,sector,count,slot,drive,error)
RTRACK Procedure
Reads raw data from a specified track into the read buffer.
RTRACK(address,track,half,slot,drive)
RSYNC Procedure
Functionally identical to RTRACK, except that a reference mark on
track 0 is checked before reading.
WSYNC Procedure
Functionally identical to RTRACK, except a reference mark on track 0
is checked before writing.
WTRACK Procedure
Writes a section of raw data to a disk from write buffer.
WTRACK(sync size,pre fill,track,half,slot,drive,error)
where pre fill=# of sync bytes to write prior to data.
RUN Command
Begins the execution of a user program.
RUN
SAVE Command
Stores programs or data on disk.
SAVE filename (AT address,length)
SETFORMAT Procedure
Selects the format, address header, data header, and interleave for
RSECT, WSECT and FORMAT procedures.
SETFORMAT(type,address header,data header,interleave)
SIZEOF Function
Determines size of a NADOL disk file.
variable=SIZEOF(filename)
STOP Statement
Terminates a program.
STOP
TEXT Statement
Switches off graphics mode and return to full screen text.
TEXT
VLINE Procedure
Draws a vertical line on lo-res screen.
VLINE(x1,y1,y2)
WBLOCK Procedure
Writes 1 or more blocks to a PorDOS disk. WBLOCK(address,block,count,slot,drive,error)
WHILE/ENDWHILE Statement
Causes a section of a program to be executed repeatedly until a
condition is met.
WHILE expression
.
.
(executable statement)
.
.
ENDWHILE
WORKDRIVE Statement
Defines drive for file operations.
WORKDRIVE(slot,drive)
WSECT Procedure
Writes 1 or more sectors to a disk. WSECT(address,track,half,sector,count,slot,drive,error)
Predefined Variables
--------------------
These are predefined and always avaliable for the user in immediate mode.
MEMORY Byte Array
An array which encompasses the entire Apple memory range. MEMORY[0] is
memory location $0. MEMORY[4000] is memory location $4000.
BREAK Byte
Controls operation of Ctrl-C. If set to 0 then Ctrl-C will halt a
program. If set to 1, will not halt and reset will cause current
program to start executing from beginning.
ERROR Byte
Contains number of any error that occurred. 0=no errors.
PRTSLOT Byte
Slot number of printer interface card.
MACHID Byte
Indicates type of Apple used, set during boot:
0=Apple II 1=Apple II+ 2=AppleIIe 3=Apple IIc
HASLC Byte
Indicates presence of 16K RAM card in slot 0.
HASAUX Byte
Indicates presence of additional 64K memory in IIe or IIc.
RBUF Byte Array
Read buffer used for raw nibble reads. $3FFF in length.
WBUF Byte Array
Write buffer used for raw data writing. $29FF in length.
ADDR16 Byte Array
Contains normal address mark for 16-sector disks (D5 AA 96 DE AA EB)
DATA16 Byte Array
Contains normal data mark for 16-sector disks (D5 AA AD DE AA EB)
ADDR13 Byte Array
Contains normal address mark for 13-sector disk (D5 AA B5 DE AA EB)
DATA13 Byte Array
Contains normal data mark for 13-sector disk (D5 AA AD DE AA EB)
FORM16 Byte Array
Contains the numbers for the sectors on a normally interleaved
16-sector disk. (00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F)
FORM13 Byte Array
Contains the numbers for the sectors on a normally interleaved
13-sector disk. (00 0A 07 04 01 0B 08 05 02 0C 09 06 03)
WNDLEFT Byte
Value of left margin of screen, normally 0.
WNDWIDTH Byte
Value of width of screen, normally 40.
WNDTOP Byte
Value of upper line of screen, normally 0.
WNDBOT Byte
Value of bottom line of screen, normally 23.
Nibbles Away III
Docs Part 2
by
Mr. Wiz
Using Nibbles Away III Copier
-----------------------------
Option #1 from the Main Menu enters the Bit Copier. A menu if presented to allow toggling or changing items. They are self-explanatory. At any time, pressing Ctrl-P will cause the screen to be sent to your printer VIA whatever slot you have specified in the Configuration section (default=slot 1).
During the copy process, several keys can be pressed to invoke special functions. They are:
Q - Abort current copy process
S - Skip to next track
G - Enable hi-res graphics display mode
T - Disable hi-res graphics, back to text screen
Included in NAIII is a Fast Sector Copy program to copy standard DOS 3.3, Pascal, and CP/M disks. If you have an Apple IIe or IIc with additional memory, then the additional memory will be used to speed up the copy process.
Track Editor
------------
This option is used to view raw data present on any track. Several options are available to allow the data to be scanned or modified, and then written back to disk.
When first selected, this function will display several hundered bytes of information from the start of the read buffer. A blinking cursor will appear in the upper left corner of the data. In the upper right corner is the track number.
Different keys invoke different functions. They are:
arrows - Move cursor in appropriate direction.
I - Move cursor up 1 line.
J - Move cursor left 1 byte.
K - Move cursor right 1 byte.
M - Move cursor down 1 line.
> - Move cursor down 1 page.
< - Move cursor up 1 page.
+ - Increment track number.
- - Decrement track number.
T - Asks for a new track number to be entered.
O - Shows Options page for different slot/drive.
F - Asks for HEX string to Find. The cursor will move to that
location if found.
C - Shows count of the number of bytes to next occurence of bytes
at cursor location.
P - Shows print menu.
S - Sets the 'Track Start' value to the cursor location.
E - Sets the 'Track End' value to the current location.
M - Moves the currently marked track into the write buffer.
/ - Toggles between read and write buffers.
G - Prompts for new location for cursor.
R - Reads current track into buffer.
W - Writes data in write buffer to disk.
Q - Quit track editor.
SPACE - Enters modify mode. Once entered:
Typing HEX values will change value of byte.
Space Bar will move to next value.
RETURN will accept current value.
Arrows move cursor.
ESC will abort modify function.
Data which has its high bit clear will be written as SYNC bytes, and will display as inverse on screen.
Sector Editor
-------------
Option #4 will invoke the Sector Editor. DOS 3.2, DOS 3.3, Pascal, and CP/M disks can be viewed and modified. A disassembly of the data may be presented.
The following keys will perform certain functions:
arrows - Move cursor in appropriate direction.
I - Move cursor up 1 line.
J - Move cursor left 1 byte.
K - Move cursor right 1 byte.
M - Move cursor down 1 line.
+ - Increment sector number
- - Decrement sector number.
> - Increment track number.
< - Decrement track number.
/ - Toggle between HEX and ASCII display.
SPACE - Enter modify mode:
HEX digits are accepted on HEX side, space moves to next
value.
ASCII characters may be entered directly on ASCII side.
Arrows move cursor.
RETURN accepts current value.
ESC aborts modify mode.
R - Read current sector.
W - Write current sector.
D - Disassemble data in buffer from cursor. RETURN to abort.
T - Prompt for new track number.
S - Prompt for new sector number.
F - Selects Find mode.
1 - Prompt for start track.
2 - Prompt for starting sector.
3 - Prompt for end track.
4 - Prompt for ending sector.
5 - Toggle HEX/ASCII searching.
6 - Switches search direction between ascending and
descending.
7 - Prompt for search string (32 characters maximum)
RETURN to start search.
Q to abort search.
O - Display Options screen.
Q - Quit sector editor.
NADOL Error Messages
--------------------
1 - Syntax error
2 - ()Mismatch error
3 - Parameter count error
4 - Stack overflow error
5 - Duplicate variable error
6 - Duplicate Proc/Func error
7 - Symbol table full error
8 - Undefined symbol error
9 - Unexpected end of file error
11 - Value range error
13 - Nested label error
14 - Subscript error
15 - No begin error
16 - Wrong type of parameter error
17 - Read only error
19 - Immediate only error
20 - No language card error
21 - No auxiliary memory error
22 - IF/ENDIF mismatch error
23 - WHILE/ENDWHILE mismatch error
24 - Program too large error
25 - I/O error
26 - Disk full error
28 - File not found error
29 - No Applesoft error
NADOL Memory Map
---------------------------------------------------------------------$FFFF
Monitor $F800
---------------------------------------------------------------------$F7FF
.
Applesoft . .
---------------------------------------------------------------------$D000
System I/O $C000
---------------------------------------------------------------------$BFFF
.
.
NADOL Program Code .
.
.
---------------------------------------------------------------------$8000
Read Buffer
---------------------------------------------------------------------$4000
Write Buffer
---------------------------------------------------------------------$2700
User Program
--------------------------------------------------------------------- .
Data for Variables
--------------------------------------------------------------------- .
Free Space
---------------------------------------------------------------------
Symbol Table
---------------------------------------------------------------------$0C00
NADOL Workspace
---------------------------------------------------------------------$0800
Zero page, Stack and Screen
---------------------------------------------------------------------$0000