APDL Public Domain 1/APDL_PD1A.iso/program/assembler/sasm/Docs/FrontEnd

Text File | 1995-10-02 | 11.1 KB | 214 lines

                      =========================
                       SAsm Front End program
                      =========================

    This is supplied with all recent versions of SAsm. It is not of any use
    on its own, it just provides a multi-tasking Desktop interface for SAsm.
    This supplement does not describe the use of the SAsm assembler, you
    should familiarise yourself with SAsm before you attempt to use this
    program, and it will be assumed that you understand how SAsm works. In
    order to distinguish between the front end and SAsm itself the former
    will be referred to as '!SAsm' and the latter as 'SAsm'

    This description will be brief, because once you understand how SAsm
    works you will not need detailed instructions as most functions will be
    self-evident.

    Like the SAsm assembler !SAsm is Shareware and is © David Holden. For
    details of how to register see the main SAsm Manual.

            Introduction

    !SAsm installs itself on the icon bar in the usual way. If you click
    SELECT on the icon the Control Window will open. You will see that this
    enables most of the filenames and parameters that are be used by SAsm to
    be defined.

    !SAsm does not operate by passing all the parameters to SAsm. It creates
    a 'Make' file (filetype &2EF) which does the actual work. In order to
    use !SAsm to best advantage you should understand how this was designed
    to be used.

    It is assumed that your entire project is contained in its own directory
    which I shall refer to as the 'project directory'. Inside this will be a
    sub-directory holding the files to be assembled, and I shall refer to
    this as the 'source directory', although other 'external' files eg.
    containing sub-routines you regularly use, may also be included. The
    Make file should be saved in the source directory. The names of these
    directories is not important, they can be called anything you choose.

    The object code would normally be saved in the project directory,
    although if it is an application then the application directory should
    be placed here and the object file saved into the application directory.
    Error files, x-ref files, etc. can be saved either in the source
    directory or the project directory (or elsewhere if you prefer).

            The SAsmProj$Dir variable

    If you click on the Save button in the control window a 'Save' window
    will open. When you drag the Make file icon to a directory (normally the
    source directory) an OS variable 'SAsmProj$Dir'  is set. This can be
    used as the 'anchor' for all other files. For example, to save the
    object file as 'Runimage' in the application directory '!MyApp' in the
    project directory (eg. the parent directory of the source directory) you
    would set the object filename to '<SAsmProj$Dir>.^.!MyApp.Runimage. The
    advantage of this system is that if you move the whole project elsewhere
    or rename directories or drives everything will still work as it is
    independent of absolute paths.

    As well as being set when you save a Make file this variable is set when
    you load one. Make files are loaded into !SAsm by simply double-clicking
    on them, and each time you do this SAsmProj$Dir will be reset to suit.

    Once the SAsmProj$Dir variable has been set the Make file can be
    re-saved by clicking on 'Set' in the Control window. This updates the
    Make file, but if you have changed some options temporarily you may want
    to make sure that you don't do this by accident. Therefore the Set
    button can be shaded to make it inoperative by clicking on 'Lock Set' on
    the main menu. This toggles the state of the Set button. You can still
    update the Make file by opening the Save window and clicking on 'OK'.

            The Control window

    The 'Type', 'Code size' and 'Origin' icons should need little
    explanation. 'Memory' simply defines how much memory will initially be
    allocated to SAsm when it is run, if it isn't enough SAsm can grab more,
    but it's probably best to try to allocate as much as you expect it to
    need. All of these are writeable, and some have menus from which you can
    select the most useful options.

    The filenames in the bottom part of the control window should again be
    self evident. They set the names for all the various files that SAsm
    uses and creates. The Library filename can be set by either typing it in
    manually or dragging a Library file to it.

    The buttons to the right of each filename set the functions on or off.
    for example, if the button beside the object filename is off then no
    object file will be created. If the button beside the Library filename
    is off then the library will not be used even if it is named. The Cross
    ref. and Labels buttons are mutually exclusive as you can't have both of
    these enabled simultaneously.

    Each time you save the Make file all of these parameters are updated.

    Clicking on 'GO' begins assembly by starting up SAsm and passing the
    parameters to it. The most important parameter passed is the name of the
    Make file. The object and error filenames will be included in the Make
    file but the ones shown in the Control window are also passed directly.
    This enables you to change the name of these files for a 'single shot'
    if required without updating the Make file.

    The filename passed to SAsm for the Make file is the name that was last
    used to save the Make file, normally the name appearing in the Save
    window. This therefore need not be 'Make', although it normally would
    be, so you can have two or more different Make files to assemble
    alternative object files.

    Don't forget - When you click on 'GO' it is the Make file that is passed
    to SAsm and actually does the work. If you haven't saved or updated the
    Make file then SAsm won't have the correct instructions so things will
    go wrong!

            Interactions

    There may be interaction between options set in the last Make file you
    saved and those set in the Command window when you carry out the
    assembly. For example, if you had saved the Make file with X-ref
    selected then the X-ref directive will be included in it, so
    de-selecting later will have no effect. However, if the Make file was
    saved with X-ref de-selected then selecting it before you assemble will
    add the 'X' parameter to the command line so you will get a X-ref.

    I am sure you will be able to think of other instances, and I suggest
    you look at Make files saved with various options in a text editor to
    familiarise yourself with how it works. You can see the various command
    line switches inserted by saving the Obey file as described later.

            File list

    Clicking ADJUST on the icon bar icon opens the file list window. This
    will contain the list of filename to be assembled. To create the list
    just drag the files, in he correct order, to this window.

    You might think this should be done before you save a new Make file, but
    you should save your Make file BEFORE you create the file list. The
    reason for this is that saving the Make file sets SAsmProj$Dir. Once
    this is set any files which are 'downstream' of it will have their names
    truncated to <SAsmProj$Dir>.[path.]<name>,which will make the whole
    project position independent (as well as making the filenames shorter).
    If the variable is not correctly set first then the filenames will be
    absolute path/filenames. Similarly any filenames which cannot be
    sucessfully truncated, eg. files of sub-routines taken from another
    place, will be absolute.

    Clicking MENU on the File List window displays a menu enabling you to
    manipulate the files. If you click SELECT on a file this menu will
    enable you to delete it or move it up or down the list. You can also
    delete all the files as sometimes it can be easier to wipe them all out
    and start again if you need to change the order.

            Task window or CLI

    By default SAsm is run in a Task window in the desktop. This is slightly
    slower than using the CLI and presupposes that you have enough RAM to
    run the required modules. Speed can be increased by using the CLI
    directly outside the desktop. This may be advantageous if you only have
    an ARM 2 processor.

    'Taskwindow' on the main menu is normally ticked, and this means that
    SAsm will be run in a Task window. However, if it is not ticked then
    SAsm will be run from the CLI outside the desktop, as if you had pressed
    F12 and typed the required command line.

            Saving the options

    'Save Opts' on the main menu saves the entire contents of the Control
    Window, with the state of all the buttons (including the 'Set' button)
    to an Options file. This will be reloaded the next time !SAsm is run.
    Note that the contents of the File List are not saved, as they will
    relate to a specific project, whereas many of the items in the Control
    window will not be project specific.

            Saving an Obey file

    'Save Obey' from the main menu will enable you to save an 'Obey' file
    which will reflect the command that is used by !SAsm to open a Task
    window and run SAsm. This also has an additional line that sets
    SAsmProj$Dir. If, instead of using the GO button in the Command window,
    you save this file to the directory that your Make file is saved in then
    you can run SAsm by double-clicking on this instead of running !SAsm.
    Under some circumstances this might be more convenient, especially on a
    1Mb machine where you will not need to have !SAsm loaded.

            The Make file

    Although this has its own filetype it is actually a plain text file and
    can be edited. However, beware of changing it because when it is loaded
    into !SAsm the file itself is not retained. !SAsm reads all the
    parameters and #INCLUDE filenames and remembers them instead, so when
    you save a Make file it is actully re-created. If you put commands in
    the Make file which cannot be duplicated by !SAsm then you will be
    warned that !SAsm doesn't understand them.

    The Make file produced by !SAsm is therefore rather basic. It can only
    contain the normal pre-assembly directives and a list of #INCLUDE files.
    If you do want to use other setup information or directives these must
    be put in a separate file.

            Running SAsm

    As normally supplied !SAsm will load the Relocatable Module version of
    SAsm which will be in its application directory. This is simply a
    convenience. You may prefer to put SAsmMod in your System:Modules
    directory and edit the !Run file, or use the Utility version of SAsm
    from your Library directory, in which case you can delete the line which
    loads the Module.

    Whichever version of SAsm you use the command line syntax is identical
    so !SAsm will work with either.

    Because the registered version of SAsm contains the name of the person
    to whom it is registered SAsmMod may not be included with !SAsm in the
    application directory with the registered version. You will need to copy
    it from the SAsm directory.