AmigaBASIC Tutorial #1

			         Written by
			       Pierre Fortin

  --------------------------------------------------------------------------
INTRODUCTION:

     The following tutorial is for the use of AmigaBASIC programmers both
novice and intermidiate programmers can benfit from this tutorial.
Part 1 (this tutorial) contains information which is quite useful so if
possible, read this file with a program that can let you print your current
screen so that you can create yourself a quick refrence card.  The following
tutorial will cover the following:

		How to access libraries in AmigaBASIC
		How to use CLI commands
		How to interface I/O with your modem
	and	How to create a console window in AmigaBASIC.

  --------------------------------------------------------------------------
Accessing libraries in AmigaBASIC
  --------------------------------------------------------------------------

     AmigaBASIC has a very extensive command set of 198 commands.  More than
enough to accomplish many tasks.  Though limitiations do arrise.  For
example, what if you wanted to read the current color pallete values?  There
is no specific command to do so!  What does one do when faced with such a
problem?  One uses specific commands within those 198 commands in the
AmigaBASIC set to call up ROM Kernal routines.  I won't go much further
into the subject of libraries for it is all documented with the AmigaBASIC
manual included with your Amiga.  I mentioned libraries for many of the
routines and tips in this file and hopefully others include access to
libraries.  This is why you MUST have the following libraries in your
current directory from when you boot up AmigaBASIC or in the LIBS:
directory of your system disk.

	dos.bmap
	intuition.bmap
	exec.bmap

  --------------------------------------------------------------------------
How to use CLI commands in AmigaBASIC
  --------------------------------------------------------------------------

     The following part of this text file includes code to call CLI
commands from AmigaBASIC.  CLI is a medium used by a large majority of
Amiga users.  This enviroment is controlled by small programs called
commands.  These commands do many tasks such as list the content of the
disk, give you information about the disk, delete files, copy files,
and much, much more...  To access these programs (refered as commands
from here on) would greatly increase the power and complexity of your
AmigaBASIC program(s).  The following list can be typed into the
AmigaBASIC editor and saved as ASCII. (Saving in ASCII is explained at
the end of this document.)  These files can then be merged to your program
and by CALLing this subroutine, you will be able to execute CLI commands
from AmigaBASIC.

Place the following at the beginning of your program:

DECLARE FUNCTION xOpen& LIBRARY
DECLARE FUNCTION Execute% LIBRARY
LIBRARY "dos.library"

This is the subroutine:

SUB CLI (Command$) STATIC
  SHARED error.code%
  work$=Command$+CHR$(0)
  count%=0
  
  out.filename$="RAM:CLI.OUT"
  out$=out.filename$+CHR$(0)
  
  out.handle&=xOpen&(SADD(out$),1006)
  IF out.handle&=0 THEN
    error.code%=1
    EXIT SUB
  END IF
  
  follow%=Execute%(SADD(work$),0,out.handle&)
  IF follow%=false THEN
    error.code%=2
    EXIT SUB                                          
  END IF

  CALL xClose(out.handle&)
  text.height%=PEEKW(WINDOW(8)+58)
  window.height%=PEEKW(WINDOW(7)+10)-11
  lines%=INT(window.height%/text.height%)-3

OPEN out.filename$ FOR INPUT AS 1
  WHILE (EOF(1)=0)
    INPUT #1,reader$
    count%=count%+1
    IF count%>lines% THEN
      count%=0
      PRINT "<< Press any key to continue >>";
      WHILE INKEY$="":WEND
      PRINT
    END IF
  WEND
  PRINT "## End output ##"
CLOSE 1
  KILL out.filename$
END SUB  

The following syntax should be used to call this routine.

	CLI "{COMMAND}"

   Ex.  CLI "dir df1:"

The previous example would read the directory of DF1: and output it to
a file in RAM: called CLI.OUT.  This file would then be displayed and the
subroutine would return to where you called from within your program.

  --------------------------------------------------------------------------
How to interface I/O with your modem
  --------------------------------------------------------------------------

     Accessing your modem from AmigaBASIC is very simple.  There is
no LIBRARY call's to use your modem from AmigaBASIC, the routine uses 
internal commands.  You simply open the communication port at the baud
rate of your choice (also depends on the highest speed of your modem.)

	OPEN "COM1:{Baud Rate},{Parity},{Data Bits},{Stop Bits} AS #1

Just replace the name in brackets with the appropriate values.  These
values are explained in your AmigaBASIC manual.

     You must then place yourself in a wait state and wait for input
from the modem.  This is achieved with the help of the LOC command.

	WHILE LOC(1)=0:WEND
	{Rest of routine goes here}

This particular syntax wait's until a character is pending from the modem
and then goes on to continue where you place your routine.  (Porperly
marked in the above example.)  These are a few other commands you can
use with the modem.

	modeminput$=INPUT$({Number of Characters},1) 'Modem input
		    INPUT$ #1,modeminput$

	PRINT #1,"This is going to the modem!!"

* NOTE: The number 1 [ONE] in the above examples is the file number and
may be changed at will!

  --------------------------------------------------------------------------
How to create a console window in AmigaBASIC
  --------------------------------------------------------------------------

     The proper title to this final section in this tutorial would be a
faster print command.  The routine is fairly complex so I will
display it and then comment on it.

Place these at the beginning of your program:

DECLARE FUNCTION OpenDevice% LIBRARY
DECLARE FUNCTION AllocMem& LIBRARY
DECLARE FUNCTION AllocSignal% LIBRARY
DECLARE FUNCTION FindTask& LIBRARY
DECLARE FUNCTION DoIO& LIBRARY
LIBRARY "exec.library"

C1$=CHR$(155)       ' Control Sequence Introducer
C2$=CHR$(8)         ' Backspace
C3$=CHR$(10)        ' Line Feed
C4$=CHR$(11)        ' VTab
C5$=CHR$(12)        ' Form Feed
C6$=CHR$(13)        ' CR
C7$=CHR$(14)        ' SHIFT IN
C8$-CHR$(15)        ' SHIFT OUT
C9$=CHR$(155)+"1E"  'RETURN

The subroutines:

SUB ConPrint(text$) STATIC
  SHARED c.io&
  IF c.io&=0 THEN :SystemOn
  POKEL c.io&+36,LEN(text$)
  POKEL c.io&+40,SADD(text$)
  e&=DoIO&(c.io&)
END SUB

SUB SystemOff STATIC
  SHARED c.io&
  CloseConsole c.io&
END SUB

SUB SystemOn STATIC
  SHARED c.io&,c.c$
  OpenConsole c.io&
  POKEW c.io&+28,3
END SUB

SUB OpenConsole(result&) STATIC
  CreatePort "basic.con",0,c.port&
  IF c.port&=0 THEN ERROR 255
  CreateStdIO c.port&,c.io&
  POKEL c.io&+36,124
  POKEL c.io&+40,WINDOW(7)
  dev$="console.device"+CHR$(0)
  c.error%=OpenDevice%(SADD(dev$),0,c.io&,0)
  IF c.error%<>0 THEN ERROR 255
  result&=c.io&
END SUB

SUB CloseConsole(io&) STATIC
  port&=PEEKL(io&+14)
  CALL CloseDevice(io&)
  RemovePort port&
  RemoveStdIO io&
END SUB

SUB CreateStdIO (port&,result&) STATIC
  opt&=2^16
  result&=AllocMem&(48,opt&)
  IF result&=0 THEN ERROR 7
  POKE result&+8,5
  POKEL result&+14,port&
  POKEW result&+18,50
END SUB

SUB RemoveStdIO (io&) STATIC
  IF io&<>0 THEN
    CALL FreeMem(io&,48)
  END IF
END SUB

SUB CreatePort (port$,pri%,result&) STATIC
  opt&=2^16
  byte&=38+LEN(port$)
  port&=AllocMem&(byte&,opt&)
  IF port&=0 THEN ERROR 7
  POKEW port&,byte&
  port&=port&+2
  sigBit%=AllocSignal%(-1)
  IF sigBit%=-1 THEN
    CALL FreeMem(port&,byte&)
    ERROR 7
  END IF
  sigTask&=FindTask&(0)
  
  POKE port&+8,4
  POKE port&+9,pri%
  POKEL port&+10,port&+34
  POKE port&+15,sigBit%
  POKEL port&+16,sigTask&
  POKEL port&+20,port&+24
  POKEL port&+28,port&+20
  FOR loop%=1 TO LEN(port$)
    char%=ASC(MID$(port$,loop%,1))
    POKE port&+33+loop%,char%
  NEXT loop%
  CALL AddPort(port&)
  result&=port&
END SUB

SUB RemovePort(port&) STATIC
  byte&=PEEKW(port&-2)
  sigBit%=PEEK(port&+15)
  CALL RemPort(port&)
  CALL FreeSignal(sigBit%)
  CALL FreeMem(port&-2,byte&)
END SUB

The above collection of SUBroutines will allow to print to your current
window using all ANSI escape codes, and will also create a CLI type cursor
and control it for you.  I will document the code for it is an extract
of the Abacus book "Amiga Tricks and Tips."  (More on this at the end
of this tutorial.)  You simply call the routine like this:

	ConPrint "Hello, this is printing using ConPrint!!!"

Just do the following and the routine will create a console window
on it's own.  If you wish to open the console first, just type:

	SystemOn

And when you are finished and your program quits, type:

	SystemOff

SystemOff is VERY important because it clears up allocated memory and
relases ports and signals allocated to create the console window.  To use
ANSI, just include the control codes within the quotes in ConPrint or
use the pre-defined variables which should be placed at the beginning of
your program.

  --------------------------------------------------------------------------
DISCLAIMER
  --------------------------------------------------------------------------

     The following file uses extractions from the following book(s):

	Abacus' Amiga Tips And Tricks

     References were tooken from the following book(s):

	Advanced Amiga Basic by Compute Publications
	AmigaBASIC Manual by Microsoft

I highly recommend Abacus' Amiga Tips And Tricks to ALL AmigaBASIC
programmers.  It is an EXTREAMLY userfull refrence guide.  I also
recommend Advanced Amiga Basic by Compute Publications, it to is
a great refrence manual.  Both these publications should be on the
shelf of EVERY AmigaBASIC programmer.

if you find this tutorial handy, usefull, or even profit from it's
contents, please write to me:

	Pierre Fortin
	8035 Jeanne D'Arc Bd.
	Orleans, Ontario, Canada
	K1E 1B1

I can also be reached on:

	OMX - Steve Tibbett's BBS(X)
	613-731-3419

	Compuerve
	ID # 73667,3525

I will only continue this series of tutorials if there is demmand for it.

I am sorry for the spelling errors, but I don't own a spell checker!!!!

I would like to thank, Patrick Lalonde for help in writting some routines
and to Peter Kaminski for his help.  I am currently writting a BBS in
AmigaBASIC and it is comming along quite well.  Once completed I will
send copies of the demo out to those who write to me.  The BBS will support
the following:

		XMODEM, YMODEM, ZMODEM w/ 32bit-CRC (I already have the
						     routines!)
		Complete message system
		255 security level system
		Voting
		Configurable menus
		more...

A demo version will be available to those interested in putting up the bbs.
Producing tutorial's of this type is hard work, to those who find this
tutorial useful, a small donation of about 5$ would be greatly appreciated.
Send donations to the above address.  Those who send donations will
receive a copy of my BBS (when it's finished) and all the updates.