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