Do Run Run STWRITER.PRGB„!B„! **** Atari Corp. **** 1196 Borregas Avenue **** Sunnyvale, Ca. 94086 ****** ** ** ** 25 July 1986 ** ** ** ** ** ** INTRODUCTION TO GEM PROGRAMMING-------------------------------T A B L E O F C O N T E N T SIntroduction..........................................1.Who to contact if you have a problem..................1.1Documentation in the package..........................2.Compuserve information................................3.Disks in the package..................................4. Compiler..........................................4.1 Linker............................................4.2 Utilities.........................................4.3 Resource Construction Set.........................4.4 Micro Emacs.......................................4.5Hardware requirements.................................5.Compiling a program on the ST.........................6. Creating a GEM application........................6.1 Creating a GEM desk accessory.....................6.2 C-run time applications...........................6.3Batch processing on the ST............................7. BATCH.TTP.........................................7.1 RM.PRG............................................7.2 WAIT.PRG..........................................7.3 RELMOD.PRG........................................7.4Allocating more stack space...........................8.Global variable names to avoid........................9.INTRODUCTION TO GEM PROGRAMMING------------------------------- 1-@-1. INTRODUCTIONThanks for your interest and support of the ST series of computers. Enclosed is the documentation and software package you have ordered. Read this section first to learn how to organize your documentation and get quickly on the road to ST product development.1.1 WHO TO CONTACT IF YOU HAVE A PROBLEM: Hardware problems Randy Hain (408)745-2466 Software questions John Feagans (408)745-4923 Package administration and equipment orders Cindy Claveran (408)745-25682. DOCUMENTATION IN THIS PACKAGE: The documentation may seem overwhelming at first, but it is really easy to get started. All pages are pre-punched for a three ring binder and the sections you will most commonly access are The Guide (BIOS), GEMDOS, Volume 1--VDI, and Volume 2--AES. To start programming, the first files you should read are on the MicroEMACS disk on how to use the editor. This document contains info on compiling and linking your first program. Later you may refer to other documents in the package for detail on changing parameters of the compiler, linker, and other utilities. 1. Non-disclosure agreement Please sign and return to assure future updates. 2. Question and Answer Newsletters Commonly asked questions by new developers. 3. Introduction to GEM programming 4. A Hitchhiker's Guide to the BIOS 5. Atari GEMDOS Reference Manual 6. GEM Programmer's Guide, Vol. 1--VDI 7. GEM Programmer's Guide, Vol. 2--AES 8. GEM DOS Programmer's Guide 9. C Language Programming Guide (ignore the references for CP/M 68K) The next series of documents are intended for the advanced developer who wants to exercise the lowest level of operating system: 10. Line-A Technical Reference Manual 11. ST Series BIOS listing 12. Intelligent Keyboard (IKBD) Protocol These next documents can be used by developers of add-ons and those persons who just want to know more detail about the machine: 13. Engineering Hardware Specification 14. Application Notes on the ACSI (DMA port) 15. Chip specifications: a. 6850 ACIA b. AY-3-8910 PSG c. 68901 MFP d. Programmable Sound Generator Manual e. WD1770 FDC f. 128K ROM Cartridge Schematic3. COMPUSERVE INFORMATION We have included a Compuserve Starter Pak with $15 of free time. We hope that you have, or will purchase, a modem to use with your ST so you can join us in our special Developer's SIG on Compuserve. Follow the directions for logging in and type GO ATARIDEV. Type MI for membership and follow the directions. You will have access to restricted data libraries into which we are constantly uploading utilities and example programs. You may leave private messages for John Feagans at 70007,1072.4. DISKS IN THIS PACKAGE The ST development package consists of five disks. These disks will enable a developer to compile and link "C" applications or desk accessories for the Atari ST series. 1. C-Compiler. 2. Linker. 3. Utilities. 4. Resource Construction Set. 5. MicroEMACS.WARNING: It is recommended that the developer make BACKUP COPIES of these disks and use the backups as backups ONLY! The following is a list of files, programs, and other information that are included on these disks.4.1 COMPILERCP68.PRG Three pass "C" compiler.C068.PRGC168.PRGAS68.PRG 68000 asembler.AS68INITAS68SYMB.DATBATCH.TTP ST batch processing program.RM.PRG ST delete file program.WAIT.PRG ST WAIT to return to desktop.C.BAT Batch input file. These files when included within a "C" program enable the use of the AES and VDI predefined messages, object types, GEMDOS definitions etc.DEFINE.H Miscellaneous definitions. Ex. NIL, TRUE...GEMBIND.H Do-it-yourself GEM binding kit.GEMDEFS.H Common GEM definitions.VDIBIND.H VDI external definitions.TOSDEFS.H TOS file attributes and error definitions.OBDEFS.H Common GEM OBJECT definitions.OSBIND.H "C" binding to GEMDOS and BIOS.STDIO.H "C" standard I/O file.PORTAB.H DRI recommended.MACHINE.H DRI recommended.TADDR.H Tree address offsets.CTYPE.H "C" typing functions.ERRNO.H DOS errors.MATH.H "C" header file.OSIF.H DOS functions.OSIFERR.H System errors.SETJMP.H "C" header file.STRING.H "C" header file.LARGE.S For compatibility with PC GEM4.2 LINKERLINK68.PRG ST linker with overlay program.LO68.PRG ST simple linker.RELMOD.PRG ST relocation program.BATCH.TTP ST batch processing program.RM.PRG ST delete file program.WAIT.PRG ST WAIT to return to desktop.LINKAP.BAT Batch to link GEM application.LINKACC.BAT Batch to link GEM desk accessory.CLINK.BAT Batch to link C runtime.LINKIO.BAT Batch to link DOS applications.ACCSTART.O GEM accessory start file.APSTART.O GEM application start file.GEMSTART.O "C", VDI, AES library start files.AESBIND AES run time library.VDIBIND VDI run time library.GEMLIB "C" run time library.OSBIND.O GEMDOS trap routine.LIBF Floating point library.4.3 UTILITIESCOMMAND.PRG Command line interpreter.DUMP.PRG Hexadecimal file print utility.FIND.PRG File string locator utility.HIGH.PRG ST medium resolution program.LOW.PRG ST low resolution programKERMIT.PRG File transfer program.NM68.PRG Symbol table print utility.SID.PRG Symbolic Interactive DebuggerSIZE68.PRG Program segment size utility.APSTART.S Source to application start.ACCSTART.S Source to desk accessory start.GEMSTART.S Source to "C", VDI, AES start.ACSKEL.C Example GEM desk accessory program.APSKEL.C Example GEM application program.AR68.PRG Library creation utility.4.4 RESOURCE CONSTRUCTION SETRCS.PRG Resource construction set program.RCS.RSC File for RCS.RCS.DFN This enables you to see RCS.RSC as an example.README Ignore this unless you are converting alpha to beta RCS.DEF2DFN.PRG See above comment.ICON folder containing: SE.PRG Shape editor. SE.RSC SHIC.DOC Shape editor document. ATBALL.C ATBALL.S ATBALL.SHP SDASM.PRG SDASM.S SDC.C SDC.PRG SDCST.SICONA folder containing: ICED.PRG Icon editor. ICED.RSCRSCREAT folder containing: DOC Documentation about resource create. STCREATE.C STCREATE.INP RSC.O RSCRLIB.H4.5 MICRO EMACS This disk contains the text editor you will use for constructing your programs and a number of examples which illustrate use of the AES and VDI.CARDS folder containing: MAKECARD.BAT CARDS.C example dialog box and field usage. CARD.H CARDS.H CTYPE.H CTYPE.O CARDS.RSCDOCUMENT folder containing: NEWFORM.DOC form_keybd() and form_button info. DISK.TXT how to address 1772 through DMA port.DOODLE folder containing: LINKDO.BAT example draw program DOODLE.C DOORSC.C DOODLE.H DOS.H TREEADDR.H DOODLE.INP DOOSTART.O DOODLE.PRG DOODLE.RSC DOOSTART.SEMACS folder containing: ME.TTP the editor. TUTOR.DOC how to... TEXT1 TEXT2 TEXT3FORMDO folder containing: FRMTST.C FORM.DEF FORM.H FRMTST.PRG FORM.RSCMENU folder containing: MLINK.BAT example menu program MENTST.C MENTST.DEF MENTST.H MENTST.RSCTEMPLATE folder containing: TEMPLATE.C put your application in the middle and have a functional GEM app.5. HARDWARE REQUIREMENTS6. COMPILING A PROGRAM ON THE ST. The three development disks have been arranged so that compiling and linking on the ST is a very simple process. The following is an example on how to compile and run the sample APSKEL.C program supplied on the compiler disk.WARNING: Remove the write protection tab from the compiler and linker disks before compiling and linking.IMPORTANT NOTE: The following instructions apply to a dual drive system. Some developers will have a single drive system. There may not be enough disk space on a single drive system to compile, assemble, and link. We urge you to get a second drive if your first drive is single-sided. If you have a double-sided drive, or a 1040, all necessary files should fit on one disk.1)After making backups of the three development disks copy APSKEL.C and ACSKEL.C to a newly formated disk.2)Place the compiler disk in drive A: and the disk containing APSKEL.C and ACSKEL.C in drive B:.3)Select the BATCH.TTP program and open it.4)Type "C B:APSKEL" in the open application dialog box and select "OK". At this point the screen will turn white and the batch program will begin compiling the APSKEL.C program. The compile is finished when the program askes for a carriage return. Hit carriage return to return to the desktop.5)Replace the compiler disk with the linker disk and double click on the BATCH.TTP program. Type "LINKAP b:APSKEL" in the open application dialog box and select "OK". The screen will turn white while the batch program links the proper files together. The link is finished when the wait for carriage return prompt is displayed. Hit the return key to return to the desktop.6)Now just double click on the file APSKEL.PRG on drive B:. The move, size, close, and full boxes are all active in this program. Selecting the close box returns you to the desktop. To compile and link the desk accessory ACSKEL.C program do the following.1)Follow the same procedure to compile and link the ACSKEL.C desk accessory that you moved to the new disk. Remember to use "LINKACC ACSKEL" when linking the desk accessory together.2)Next rename the ACSKEL.PRG program to ACSKEL.ACC. CONTROL.ACC and VT52.ACC are the Control Panel and VT52 Emulator included on your system disk.3)The final step is to transfer the ACSKEL.ACC accessory you have just created to your system disk and reboot the system. (Rebooting the system installs the accessory under "DESK" on the menu bar of the desktop.4)To run, move the mouse to DESK on the menu bar and click on "Sample Accessory". If you resize the window you will see disk icons and other windows on the desktop. Selecting the close box will remove the desk accessory. If you type C.BAT and LINKAP.BAT you will be able to see the proper order of instructions necessary to compile or link a program file. For more information on compiling and linking please consult the ATARI ST developers manuals. The two remaining link batch files -- LINKIO and CLINK -- are used for creating either TOS or TTP type applications with GEMDOS and the C Run-time libraries respectively. No examples are provided for this discussion.INCLUDE / LINK TABLE:-------------------- The following table represents the proper "include" files necessary to link to different portions of the TOS operating system.SYSTEM INCLUDE LINK TO...-----------------------------------------------VDI VDIBIND library AES AESBIND library GEMDOS OSBIND.O objectBIOS XBIOS"C" library GEMLIB library LIBF libraryAll of the above libraries can be mixed depending on the needs of the developer.6.1 TO CREATE A GEM APPLICATION: You must link to APSTART.O as the first file in your link statement.link68 [u,s] file.68k = apstart,program,vdibind,aesbind6.2 TO CREATE A GEM DESK ACCESSORY You must link to ACCSTART.O as the first file in your link statement.link68 [u,s] file.68k = accstart,program,vdibind,aesbind6.3 "C" RUN TIME LIBRARY Using GEMSTART.O you MAY link to AESBIND or VDIBIND libraries and the run time library.link68[u,s]file.68k=gemstart,program, vdibind,aesbind,gemlib,libf7. BATCH PROCESSING ON THE ST7.1 BATCH.TTP This is a batch program for the ST. To use, you must create a file with the extention .BAT. To execute the C.BAT file you must open BATCH.TTP and enter "C PARM1" in the open application dialog box. Where C.BAT is defined as: cp68 %1.c %1.i c068 %1.i %1.1 %1.2 %1.3 -f rm %1.i c168 %1.1 %1.2 %1.s rm %1.1 rm %1.2 as68 -l -u %1.s rm %1.s waitPARM1 is the C file to compile. (B:PARM1 to compile files on drive B:.) PARM1 is substituted for %1 in C.BAT. No file extension is needed -- it is included in C.BAT) There is also a LINKAP.BAT file which is defined as: link68 [u] %1.68k=apstart,%1,vdibind,aesbind relmod %1 rm %1.68K wait Again, to execute just open BATCH.TTP and type "LINKAP APSKEL".REMEMBER: The linker disk must contain link68.prg, rm.prg, batch.prg, link.bat, and relmod.prg.7.2 RM.PRG This is a delete file program necessary for the BATCH.TTP program so that files can be deleted from drive B:.7.3 WAIT.PRG This program waits for a carriage return before continuing.7.4 RELMOD.PRG Converts the output file from LO68 or LINK68 into a form that is executable by GEMDOS. The full form of the commandline is: RELMOD [-]inputfil[.68K] [outputfile[.PRG]] ... (stuff between brackets is optional) If the input file has no extension, ".68K" is automatically appended. If there is no output filename specified, the name of the input file (with a ".PRG" appended) is assumed. If an output file IS specified, it has the default extension of ".PRG". If the input filename begins with a dash ('-'), the dash is ignored, except for the fact that it indicates an input filename. (If that's confusing, don't worry -- read on).EXAMPLES--------RELMOD FOO Will look for a file called "FOO.68K", and produce a file called "FOO.PRG".RELMOD BAR -BAZ.ZIP Will look for a file called "BAR.68K", and produce a file called "BAR.PRG". Similarly, it will look for "BAZ.ZIP" and produce "BAZ.PRG".8. ALLOCATING MORE STACK SPACE Stack space for applications and desk accessories has been preallocated to 1K. We realize that for some application this may not be enough stack room. For this reason we have included the source files APSTART.S and ACCSTART.S on the Utilities disk. You now can make appropriate changes to these files to create the necessary environment for your application or desk accessory.9. GLOBAL VARIABLE NAMES TO AVOID Certain global variable names are present in the binding files which you will link to. The linker takes the most recent definition of anything as being the real definition. An example of this would be if your program has an array names max[] and you link to the VDIBIND library. The linker will confuse your max[] array with the function max() in the VDIBIND. With that in mind, also avoid the following names associated with the named modules. 12 38 46 72apstart.oaccstart.o-----------crystalctrl_cntsgemstart.o-----------_main_exit_start__cpmrv_basesw_sovfbrk__BDOSblkfillindexstrchr__pname__tname__lname__xeofosbind.o--------gemdosbiosxbiosaesbind-------ccontrolglobalint_inint_outaddr_inaddr_outgl_apidad_cvdibind-------i_ptri_ptr2m_lptr2mul_divMUL_DIVsmul_divSMUL_DIVumul_divUMUL_DIVgsx1gsx2iioffiooffpioffpooffvdivec_len