

    ICTARI USER GROUP             ISSUE #9                     April 1994

         ___   ______     ___       _________   _________   ___
         \__\  \   __\    \  \__    \______  \  \   _____\  \__\
           ___  \  \       \  __\     _____\  \  \  \         ___
           \  \  \  \       \  \      \  ____  \  \  \        \  \
            \  \  \  \_____  \  \____  \  \__\  \  \  \        \  \
             \  \  \       \  \      \  \        \  \  \        \  \
              \__\  \_______\  \______\  \________\  \__\        \__\

                     *   m   a   g   a   z   i   n   e   *

    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
                       I C T A R I   U S E R   G R O U P
       63 Woolsbridge Road, Ringwood, Hants, BH24 2LX   Tel. 0425-474415
    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

                               INDEX FOR ISSUE 9
                               =================

    FOLDER                          SUBJECT
                              
    ASSEMBLY       Cookie Jar find program and documentation.
                   Cookie Jar find source code.
                   Assembler MACRO tutorial.
                   Two MACRO files for system TOS calls.
                   Twist scroll demo program and source (needs fixing).
                   Mouse problem answered.

    C              C Tutorial Chapters 8-14, (see last month also).
                   Program to delete .BAK files and source code.

    GFA            Handy tips for GFA programmers.
                   Horizontal scroll routine.

    PASCAL         Address book program and source code.

    MISC           Atari Explorer Online Programmers Journal  Issue 1.
                   'The Atari Compendium' book review.
                   Pexec TOS call information.
                   Executable file structure information.
                   Index for ICTARI disk magazines issues 1-8.
                   List of current members.

                                 ------------

    In next months issue of ICTARI (this may change) :-

    ASSEMBLY       Complete set of floating point arithmetic routines.
                   Routine to read command line text.
                   The event_multi 'right button' problem solved at last.

    C              Boink, a Break-out type game with source code.
                   The event_multi 'right button' problem solved at last.

    GFA            Code to read command line on TTP programs.

    PASCAL         Pipe monitor.

    MISC           Atari Explorer Online Programmers Journal  Issue 2.
                   Various GEM bugs discussed.
                   Program to display active GEM/TOS/BIOS/AES/VDI  calls.
                   The LZW and GIF compression algorithms explained.

    For future issues :-

    Binary/Decimal/Hex/ASCII conversion routines in machine code.
    Polyline drawing routines in machine code.
    Bezier curve drawing routines.
    Picture decompression routines for IMG, Degas, Tiny, PCX, PAC, etc.
    Picture compression routine for IMG pictures.
    HP DeskJet/LaserJet compression routines (Mode 2 TIFF).
    Using the Xbtimer chip.
    Tutorial for using GEM commands from machine code and C.
    Playing sound samples on non STE machines.
    Picture switching techniques.
    VBL queue information.
    Printer driver code for printing mono/colour images.
    Sprite tutorial and code.

    -----------------------------------------------------------------------
                                   EDITORIAL
                                   =========
    ADVERTISEMENTS
    
    We have started  advertising  the  existence  of  the  group by sending
    letters to ST User and ST Format  magazines,  we shall have to wait and
    see if they publish them and if they generate any response as a result.
    We have also sent letters to 11  Public Domain libraries and have had 2
    letters of support so far.

    We have sent letters to  17  Atari  User  Groups around the country and
    have posted a notice on some of the computer network systems.

    We have also sent letters  to  40  software authors that have published
    programs in the past and as a  result  have  had 7 new members, so far.
    Several of the new members are  very  well known in the Atari community
    and we would especially like  to  welcome  them  to  the group, see the
    MEMBERS.TXT file for more information.

    We have sent an advert to Computer  MicroMart which only costs a stamp.
    Thanks to several members who have  sent  us blank adverts, we shall be
    sending those off during the coming months.

    ATARI EXPLORER ONLINE PROGRAMMERS JOURNAL  Issue 1.
    
    This document file in  the  MISC  folder  is  the  ICTARI equivalent in
    America and contains a wealth  of  programming and related information.
    It covers all languages and so we  have not been able (due to copyright
    requirements) to split it  up  into  the  appropriate  folders. It also
    covers other topics such as source  code  on CD-ROM, for example, so we
    feel it is well worth ALL members printing out the text, but be warned,
    it runs to over 60 pages. It  does, however, have a comprehensive index
    at the beginning so you  can  choose  what  you  want to read. We shall
    publish issue 2 next month and maybe  later  issues if we can get them.
    The file is compressed with STZIP, copy  the AEOPJ1.TOS file to a blank
    disk before running it, the file will automatically uncompress itself.
    -----------------------------------------------------------------------
                                CORRESPONDENCE
                                ==============

    To ICTARI
    From Nick Bates

    RE: GEM TUTORIALS
    This would be an excellent idea, although I'm pretty OK with GEM in  C,
    I  haven't a clue about GEM in 68k.   I tend  to  save  any programs  I
    write that need GEM in C.  I would very much like  to see a tutorial in
    68K for GEM.  Anyone whose struggling  with   GEM and  C,  should  read
    C-Manship complete by  Clayton   Walnum.   It  really  is  good for the
    beginner.

    Transferring data between machines is  also  a  good point,  I would be
    interested  if any one has contributed anything about it.  I am writing
    a  chess game and  I  hope  to  be  able  to  have  two machines linked
    together to  play.  I'd   rather  use  the  RS-232  port  though.  I've
    haven't looked into it yet, and probably  a long way from doing so, but
    if any one can help - it would be appreciated.

    */ We did read somewhere that the RS-232 hardware and software is a bit
    'buggy', anyone have any detailed info on this ?   ICTARI /*

    To *.*
    FROM: Nick Bates

    I  need  a  BJ  printer  driver  for  Protext,   but  it's  not  needed
    desperately  any more,  as   I   read  the   manual   (SHOCK)  for  the
    printer,  and  found  that a flip of a dipswitch turned  it  into Epson
    mode. There's a moral to be learned there I think :-)

    To: Mike Barnard
    FROM: Nick Bates

    I  agree  with your article on comments,  people  should  comment their
    programs more. In future I intend  to  make sure any programs I  submit
    are well commented,  as otherwise  it's  hardly  worth contributing the
    source - if no one can understand it.

    Also  thanks  for   the  non-GEM  Mouse  article,   I   found  it  very
    useful in programming my own  routine  for  my  Chess Game. I think you
    deserve  a  greet  in the Credits list -  if  and  when  it's complete.

    To: *.*
    FROM: Nick Bates

    Everyone  wants  to  make  sure  their  programs  are  compatible  with
    other  machines and  all TOS versions,  does  anyone  have  any general
    rules  to  follow in order   to   ensure  compatibility  - particularly
    with the Falcon ?

    To Peter Hibbs
    FROM: Nick Bates

    The  article  on  in-line  data  transfer  to   subroutines   was  very
    useful,  and something I didn't quite understand.  Now at least  I have
    a rough idea of what the concept is about.
    -----------------------------------------------------------------------
    To ICTARI
    From Si(gh)

    I have decided  to  start  giving  you  library  routines  that  I have
    written, as and when I use them  and/or they are asked for. The problem
    is that all my code is based  on  a  large  macro table. As a result, I
    have decided to give you  the  entire  contents of my include directory
    with this issue. This will allow  people  to assemble my source without
    having to rewrite the macro bits. I will also include runnable programs
    for those who don't want to worry about the ins and outs.

    Since the include files will  grow  with  time (especially MACRO_V1), I
    will send updates as and  when  necessary.  These should be copied over
    the old files. I would recommend keeping  the files zipped so that only
    those interested need unzip them.

    Basically, as Peter Hibbs  states,  treat  the  macros and libraries as
    black boxes; the contents may change,  but the basic function will stay
    the same.

    Note: All my macros have notes  above them describing any oddities that
    I have found with the operating system  while using them and any useful
    equates that I have set up while using them.

    Hope it helps someone - please tell me  if  you use it (or if you don't
    want it) as it will then tell me whether or not to bother!

    */ Thanks for very  useful  info  in  these MACROs. See ASSEMBLY/MACROS
    folder for more info.  ICTARI /*

    The journey router sounds great  in  theory,  but  has anyone given any
    consideration to the actual data it would have to contain and how  long
    it would take to put in ?

    On a different note, I have  commented  the mouse routine from the last
    issue  for   Mike   Barnard.   Hope   it's   of   use   to   him.  (See
    ASSEMBLY/MOUSPROB.ANS folder).

    I disagree that source code  should  be  commented every seven lines or
    so, although I am well aware  of  the  seven line rule (useful note for
    menus). I do agree that source  is  not  well commented, but if I spent
    time commenting all my source, it would  never get written. I also find
    it harder to wade through  all  the  comments  than to wade through the
    source, but  I  suppose  that  is  probably  me,  as  most  of  my work
    programming tends to involve  modifying  other  people's  code. I think
    that a paragraph of what each module (not necessarily sub-routine) does
    should be sufficient, unless the aim is specifically to teach, in which
    case the program is secondary to the aim.

    I have commented your code and  corrected it to work properly; although
    some of my comments may seem picky,  they are generally to get you into
    faster methods of programming as a normal style. As usual, it's do as I
    say, not as I  do!  No  doubt  other  programmers  will  have their own
    distinct view and you will no doubt form your own after looking through
    ours.

    */ We agree with Mike that  source code should be adequately documented
    and with Simon that TOO many comments are unnecessary and time wasting.
    This does raise an  interesting  subject  for  programmers: what is the
    best way to write  source  code,  especially  in  assembler.  We have a
    number of ideas on this issue ourselves, here are some examples :-

    (a) We like to have only one  RTS instruction in a sub-routine (even if
    it means jumping to it) so if  any  code  is  added to the exit path it
    will be valid whichever way the routine exits.

    (b) We usually save and restore  all registers used within library sub-
    routines (except where timing  is  critical)  which avoids accidentally
    using the same register for two different functions.

    (c) We avoid jumping from one sub-routine into another which is often a
    recipe for disaster when later amendments are made to one of them.

    These examples may be trivial but  they  can  help to avoid the dreaded
    bombs that we seem to see too often.

    We would like to invite members (in all languages) to send in their own
    programming tips and techniques and why  they  use  them so that we can
    combine them into  a  document  on  'how  to  write  safe programs' and
    publish it in a later issue. ICTARI /*
    -----------------------------------------------------------------------
    To *.*
    From Paul Laddie [Byteman]

    I was wondering if any other members  of  the group have any GFA source
    code to play either Quartet music or soundtracker MODs under interrupt,
    I have a routine which will play Quartet music under interrupt in STOS,
    but I prefer to program in GFA basic as it is more structured.
    -----------------------------------------------------------------------
    To *.*
    From Peter Hibbs

    After  the  recommendations  by  Jonathan  (see  MISC  folder)  and  ST
    Applications magazine I have also  purchased The Atari Compendium book.
    As they say it is an excellent  reference book for all things Atari but
    don't expect much in the way of tutorials. It would be a rare book that
    had absolutely NO errors so if  anyone  who  owns this book should find
    any errors perhaps they could  let  us  know  so that other members can
    make the necessary corrections. Incidently  can  anyone explain how the
    footer text 'The Atari Compendium'  on  page  9.4  got printed in lower
    case while the other 799 pages are printed in capitals ?
    -----------------------------------------------------------------------
    To *.*
    From Mike Barnard

    Instruction timings! Our CPU's run at 8  Mhz. That means it generates 8
    million timing pulses (cycles) a second.  Or, on a 50hz colour monitor,
    you have 160 thousand cycles to get  all  of your graphics moved if you
    want the maximum frame display rate for your mega game.

    Different instructions take different  amounts  of  cycles to run, with
    the addressing modes also varying the  time taken. E.g. Clearing a byte
    or word in a data register  takes  just  4  cycles, a longword takes 6.
    (clr.l d0 - 6 cycles). The trap  command takes 38 cycles and dividing a
    signed word where  the  source  is  an  absolute  long  address takes a
    staggering 170 cycles!

    I keep reading about how important  fast  routines  are. But how do you
    know how fast they are? How do  I  know how long each instruction takes
    in each addressing mode? You can't  use  a stopwatch! Then some luck. I
    was in the library and I  asked  the librarian 'Please will you display
    on your pretty little computer  screen  a  list  of all books available
    which refer to Atari, ST or  68000?'.  She  did and I chose, at random,
    'MC68000 Assembly Language Programming',  (second  edition reprinted in
    1993 by Bramer  &  Bramer.  Isbn  number  0-340-54451-1,  Edward Arnold
    publishing, 17.99p).

    It's not specific to the ST but it's very educational. And on pages 276
    to 283 there are some beautiful  big,  clear tables telling you all how
    many cycles and how many  memory  bytes a particular instruction takes!
    Bingo. So, now you know. Go to your library and order it, now!

    So, you can't / won't / aren't  allowed  in! OK, I'm  good. If you send
    an A4 sized envelope, stamped and   addressed,  I'll  send  you  a copy
    of the tables. But send  more  than  just  the  envelope. Not money you
    fool! Some help. Maybe you  can  explain   IN  PLAIN  ENGLISH  how some
    fast sprite / screen  copying  /  backgrounds  /   scrolling  /  text /
    anything! routines are done. If not,  don't despair.  You'll  still get
    your tables. Like I said, I'm good. (Puuuurrrrrrrr!).

    I am, MIC.
    Mike Barnard, 52 Westbourne Avenue, Worthing, West Sussex, BN14 8DF.
    No uninvited callers please and only clean mail. Thanks.

    */ See Issue 7 for  some  comprehensive sprite routines using Neochrome
    Master, we are also planning to publish some more code for sprites from
    Nick Bates in later issues hopefully.  ICTARI /*
    -----------------------------------------------------------------------
    To *.*
    From ICTARI

    We would like to hear from members about what they would like to see in
    future ICTARI magazines, no guarantees that we can find the information
    but if you don't ask you won't  get  what you want. Also, we still need
    more contributions  from  you  for  future  issues.  We  have  got some
    material which is already in the  public  domain but we would prefer to
    use as much  original  material  as  possible  so  if  you haven't sent
    anything in before perhaps you could have  a go. You can always ring us
    on the number in the header above if you want to discuss any particular
    project or article. If you do  send  any  programs or source code could
    you also PLEASE send a text file  as well explaining what the code does
    and how to use it.

    We try to prepare the  disks  about  one  month  in advance so that any
    articles that are submitted will probably not appear for a month or two
    although any requests for help  will  be  put  into  the next issue. It
    would help a lot if you could send  the  disks to us BEFORE the 10th of
    the month so that we don't have a lot of work to do just before we send
    out the disks as it takes some time to prepare the disks, duplicate and
    then post them.

    Also any general comments about programming topics or anything else for
    this correspondence section are always interesting to read.

                       ---------- End of file ----------
