home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 152.lha / Startups / UsingAmigaStartups < prev    next >
Text File  |  1988-04-26  |  7KB  |  186 lines
  1.  
  2.                          Using Amiga Startups
  3.                          ====================
  4.                 
  5.    The new 1.3 startup.asm can be conditionally assembled into a
  6.    variety of startups, including startups for reentrant code and
  7.    startups which provide an application-specified CON: window for
  8.    input and output when run from Workbench.
  9.  
  10.    This document explains the standard non-reentrant Amiga startups, who
  11.    can use them, and how to use them.  If your code can use these startups,
  12.    then with a bit of recoding you should be able to use the reentrant
  13.    versions (Rstartup.obj and RWstartup.obj) to write reentrant programs
  14.    which can be made Resident for the 1.3 shell.  Note that the reentrant
  15.    startups pass the WBenchMsg differently (in argv) and do not set up
  16.    the stdio handles (so stdio must be done via the Input() and Output()
  17.    file handles).  See the source code comments of startup.asm and
  18.    the WritingReentrantC tutorial for more information on startup
  19.    variations and using the reentrant startups.
  20.  
  21.  
  22. 1. ASTARTUP.OBJ
  23.  
  24.    The Astartup code is a replacement for the 1.2 version of Astartup.
  25.    This is NOT a replacement for Lstartup.obj (also know as "c.o").
  26.    (Lstartup contains many additional variables required by LC.lib)
  27.  
  28.  
  29.    FOR THOSE OF YOU WHO HAVE NEVER USED ASTARTUP:
  30.  
  31.    Amiga/MCC assembler programs and many Amiga/Lattice C programs
  32.    can be linked with Astartup.obj.  The Astartup code sets up
  33.    _DOSBase and _SysBase (required by Amiga.lib), sets up Amiga
  34.    stdio (for use with Amiga.lib's abbreviated stdio functions),
  35.    and provides a consistent interface for receiving command line
  36.    and Workbench arguments.  The arguments are passed to "main"
  37.    in standard C fashion, as argc and argv (longs) on the stack.
  38.  
  39.        main(argc,argv)
  40.        int argc;
  41.        char **argv;
  42.           {
  43.  
  44.    If the program is started from CLI, argc is non-zero and is
  45.    equal to the number of command line args including the name
  46.    of the program itself.  Argv is an array of pointers to the
  47.    null terminated argument strings.
  48.  
  49.    Example command line:  myprogram file1 file2
  50.                           argc = 3
  51.                           argv[0] = "myprogram"
  52.                           argv[1] = "file1"
  53.                           argv[2] = "file2"
  54.  
  55.    If the program is started from Workbench, argc will be zero, and
  56.    the pointer _WBenchMsg defined in Astartup will point to a
  57.    WBStartup structure containing the names and locks of the program
  58.    and any WBargs passed via extend select or default tool.
  59.    (in C, extern struct WBStartup *WBenchMsg;  in asm, XREF _WBenchMsg)
  60.  
  61.    Note that unlike Lstartup (c.o), Astartup does NOT open a default
  62.    stdio window when a program is started from Workbench.  If your
  63.    code needs an Amiga stdio window when started from Workbench,
  64.    also see the information below on AWstartup.obj.
  65.  
  66.  
  67.    USING ASTARTUP WITH AMIGA/MCC ASSEMBLER PROGRAMS:
  68.  
  69.    Assembler programs that accept command line or Workbench arguments
  70.    can use the Astartup code for a consistent system interface.
  71.    The entry point of the assembler program must be named _main:
  72.    and this label must be XDEF'd.  When linking, put Astartup.obj
  73.    before your .obj.
  74.  
  75.  
  76.    USING ASTARTUP WITH AMIGA/LATTICE C PROGRAMS:
  77.  
  78.    Many Amiga C programs call mostly Amiga system functions and use
  79.    very few LC.lib functions.  Such programs can often be linked with
  80.    Astartup.obj and with Amiga.lib first to produce a smaller executable.
  81.    Any C code to be linked this way must be compiled with the -v flag
  82.    on the second pass (LC2) of the compiler.  This disables the
  83.    insertion of Lattice stack checking code which would reference two
  84.    variables in Lstartup (_base and _xcovf).  Any other unresolved
  85.    external references are caused by using LC.lib functions which
  86.    depend on Lstartup.
  87.  
  88.    In general, if your program does not use Lattice file IO functions
  89.    or Lattice floating point, you may be able to link with Astartup.
  90.    Amiga stdio (AmigaDOS filehandles stdin, stdout, stderr) are set
  91.    up by Astartup, and Amiga.lib contains a number of abbreviated
  92.    file IO and stdio functions for use with AmigaDos filehandles.
  93.    See the Addison Wesley Rom Kernel manual "Exec" for a description
  94.    of the C-support functions in Amiga.lib.  They include a printf()
  95.    and a getchar().  The printf() does not do floating point and it
  96.    seems to want %lc instead of %c for character formatting.
  97.  
  98.    By linking LC.lib after Amiga.lib, certain functions such as
  99.    string functions and non-power-of-two integer math can be picked
  100.    up from LC.lib without requiring Lstartup.
  101.  
  102.    If you want to use Astartup's stdio handles in your code:
  103.       (in C)  extern LONG stdin, stdout, stderr;
  104.       (in assembler)
  105.               XREF _stdin
  106.               XREF _stdout
  107.               XREF _stderr
  108.  
  109.    Remember that unless you use AWstartup (below) you have NO stdio
  110.    if your program is started from Workbench.
  111.  
  112.    To use Astartup, don't #include <lattice/stdio>, compile your
  113.    code with the -v flag on LC2, and link in this order:
  114.  
  115.    Astartup.obj, your.o ... LIBRARY Amiga.lib, LC.lib
  116.  
  117.  
  118.  
  119. 2. AWSTARTUP.OBJ
  120.  
  121.    The AWstartup code is a revised Astartup which can open an Amiga
  122.    stdio window when a program is started from Workbench.  The
  123.    CON: spec for the window is defined in YOUR code, so you can
  124.    easily modify the placement, size, and title of the window.
  125.    By defining it as a null string (""), you can suppress the
  126.    opening of the window.
  127.  
  128.    In C:
  129.     Above main() in your code:
  130.       
  131.    /* CON: spec for Wstartups */
  132.    UBYTE  AppWindow[] = "CON:0/0/640/200/ My Window Title ";
  133.    /*
  134.     * For safety, include these lines to generate a linker error
  135.     * if your code is linked with a non-window startup
  136.     */ 
  137.    extern UBYTE  NeedWStartup;
  138.    UBYTE  *HaveWStartup = &NeedWStartup;
  139.  
  140.  
  141.      and if you want to use the stdio handles directly:
  142.               extern LONG stdin, stdout, stderr;
  143.  
  144.  
  145.     In assembler: (should work this way - haven't tried it)
  146.      Above your _main:
  147.  
  148.               XDEF _main
  149.               XDEF _AppWindow
  150.  
  151.               XREF _stdin       <--- Add these if you want direct
  152.               XREF _stdout           access to the stdio handles
  153.               XREF _stderr
  154.  
  155.      And one of these (for window or no window) in your DATA section:
  156.  
  157.      _AppWindow  DC.B  'CON:0/0/640/200/Test',0
  158.      _AppWindow  DC.B  0
  159.  
  160.  
  161.    Astartup programs which use stdio (printf(), getchar(), etc.) can
  162.    easily be modified for Workbench startup using AWstartup.
  163.    The only modifications required in the application are usually:
  164.  
  165.       - Set a flag to let you know you started from WorkBench (argc==0)
  166.            BOOL fromWB;
  167.            fromWB = (argc==0) ? TRUE : FALSE;
  168.  
  169.       - If you exit with an error message and started fromWB,
  170.         do something like printf("PRESS RETURN TO EXIT") and
  171.         wait for the user before exiting.  Otherwise the exit
  172.         code in AWstartup will close the stdio window before
  173.         the user can read your error message.
  174.  
  175.       - If your program accepts command line flags or filenames,
  176.         you must add code to check for WBArgs passed via WBenchMsg
  177.         and if you wish, flags passed in the Tooltypes array of
  178.         your program's icon.
  179.  
  180.  
  181.    The AWstartup code is also valuable for printf() debugging of
  182.    Workbench programs that do not normally use use stdio
  183.  
  184.  
  185.  
  186.