UNIX PORTING GUIDE
			==================

    1. Identify the set of *.CDF, *.CIN, *.UID, *.UIC, and *.UIH files that
       will be needed and copy them in your area on UNIX via ftp.
       Make sure the files get copied in lowercase.

    2. Edit your .cdf files looking for UIPACK calls.
       On UNIX no optional arguments are allowed, so you have to use the
       argument N$A in place of missing arguments.
       This special argument is defined in a S_I include file.
       If you use the N$A argument, make sure you include the following line
       in your .cdf file:

	$$INCLUDE 'S_I$LIBRARY:NOARGINC.INC'

    3. If you have more than one .cdf files that you need to port to UNIX
       than you might consider to use the FIND_BAD_UICALLS utility on the
       VAX to make your files UNIX compatible:
		a) On the VAX put the .CDF files you need to convert into 
		   your scratch area.
		b) Define the following global symbol:
		   $ U_T_FILE :== USR$SCRATCH:[<username>]*.CDF
		c) $ SETUP UNIX_TOOLS
		d) $ FIND_BAD_UICALLS
		e) Purge the area and copy the resultant files into a safe
		   directory.

    4. Fix any HBOOK* or HFILL, HF*, etc... calls so they are HBOOK4
       compatible.  This means these calls can have no missing arguments.

    5. Search for "OPEN(" statements.
        - Formated files are allowed.
        - Only YBOS unformated files are allowed, all others must be
          excluded with $$If UNIX
                        $$Else     expander directives.
        - Check that the file name is specified correctly.  If CHKLOG is
          used no changes are necessary.  If an explicit VMS file spec. is
          used in the FILE= key, then you must change this to first pass
          the file spec. though the system_interface routine SITRFN.  For
          example:
          $$IF UNIX
                STATUS = SITRFN('C$SVX:SVNOIS.PAR', UNXTRL, UNXLEN)
                OPEN(UNIT=#,FILE=UNXTRL(1:UNXLEN)...
          $$Else
                OPEN(UNIT=#,FILE='C$SVX:SVNOIS.PAR'...
          $$Endif

          The Mips compiler has many of the same extended f77 fortran keys
          that the VAX uses, for instance the READONLY key is supported.  
          However you should check any non-standard one used against the
          documentation in the purple MIPS FORTRAN Programing Language
          reference manual, pages 8-19 to 8-27.  (This goes for any other
          nonstandard I/O key or feature, but I haven't found any.)

    6. You can search for explicit VMS system service calls by searching
       for lib$,sys$,ots$,dtk$,str$ in *.cdf.  You must replace them!

    7. Use the CDF EXPANDER to expand the .cdf files:
	% expand mytest.cdf
       You can also specify options on the command line:
        % expand -output=mytest.vax -option=FORTRAN mytest.cdf

       To compile the resultant .f file use the following command:
        % for mytest.f
       or to compile in debug mode:
        % dfor mytest.f

       The xfort command is also available to expand and compile a .cdf
       file.

   8. Pay attention to any EXPAND, and/or for (FORTRAN) errors reported.

   9. Edit and repeat steps 7 and 8 as necessary until you have 
      successfully compiled your code.

   10. IF you have one, you can add all of the files you needed to your
       CMS library's UNIX group, once it all compiles on UNIX.

   11. Create a job on FNALD to test the code using a test_build.uic and a
       test_run.uic.  Note that UNIX does not understand the concept of
       default file extensions you must therefor specify all extensions
       explicitly.  Since this doesn't hurt things on the VAX I suggest
       your start out by specifing them on the VAX as well.  For instance
       in your build_job file use: DICT mydict.uic  NOT  DICT mydict.

   12. Login to UNIX, copy the UIC files and run build_job with the
       following command:
       % build_job test_build.uic

   13. Run the expander on the output with the following command:
       % expand test_build.cdf

   14. Compile the resulting file:   % dfor test_build.f

   15. Create an "options" file.  This is a free format file.  You may 
       specify any file that the f77 command will accept.  The f77 command
       accepts *.f, *.o, *.dlb and *.olb files as input.  Input file
       specifications and option flags (see below) must be separated by a 
       space.  You may use environmental variables.  
       Here is an example file:

       % cat myopt.opt

       algo.f test_build_job.o
       $MY_LIB/mylib.olb

       You may also specify f77 or ld option flags.  For example -v added
       to this file will produce a verbose linker listing.  If you want
       to use an ld option you must tell f77 that it is a linker flag by 
       prefacing it with "-Wl,".  For example -Wl,-U tells the linker to 
       make an exe even if there are undefined symbols.  Do a "man ld"
       and "man f77" for complete information about option flags.

   16. Now use link_ana to get an executable.  An example follows:

       % link_ana mytest.exe myopt.opt all

       The first argument is the name of the exe, the second is the name of
       the options file and the last parameter is a keyword indicating the
       level of debugging desired.  Keyword values are:

           a. no   - no debugging is desired, use (O1) optimised libraries

           b. user - only user code is to be debugged, ie things in the opt
                     file
           c. all  - user and utility/offline code is to be debugged

           d. O2   - all code should be optimized at the highest (O2) level

       Note that the file extensions must be specified.  Also if you only
       want to debug your own code it is strongly suggested that you use
       offline version_7_0*.  To do this execute:
       % setup offline
       It is up to you to know your code well enough to know that there
       will not be any include file conflicts introduced by mixing
       versions.  The same situation is true on the VAX so if it works
       there it should work on UNIX.

       If you have undefined symbols there are two possible reasons for
       this:

           a. The routine has not been ported to UNIX yet.  To track this
              down do a "$ LOCS <routine name without the underscore>" on
              FNALD this will tell you which library it is supposed to be
              in as well as the file it comes from.  See if it is in the
              corresponding version_6_0 area.  If it is not then you will
              have to work with the appropriate librarian to get it ported.
              If it is there then it is probably possibility b.

           b. Like the VAX the Mips linker is single pass, so it is 
              possible that a file may be ported but there are recursive
              library references in your link which cause the symbol to be
              left undefined.  This is a harder problem to solve, you
              should contact Flavia or I for help.

       You can also request that link_ana produce a UNIX link map.  This
       map is not as useful as the corresponding map generated on VMS.
       However it is sometime useful to have both.  To get link_ana to
       produce a map do:

       % setenv MAPFILE <name of map file>
       % link_ana ...

       a directory may be specified along with the map file name otherwise
       it is written to the current directory.

   17. To run the executable non-debug do: %./mytest.exe to run it with the
       debugger do: % dbx mytest.exe.  See the "UNIX for VMS Users" book
       page 220 for a quick table of commands (given you know the VMS
       debugger you can find the equivalent commands).