                Release Notes for extern/src files for Matlab 4.2
                -------------------------------------------------

    Table of Contents
    -----------------

        1. Compiling *.c examples

           1.1   General information
           1.2   engtest*.c
           1.3   mattest*.c
           1.4** mexmat.c
           1.5** mextest1*.c
           1.6** yprime.c

        2. .f versus .F files

           2.1 'pointers' in Fortran
           2.2 What statements are 'pointers' in the examples?
           2.3 When to use .f files?
           2.4 Creating .f files on the alpha and cray
           2.5 Staying with .F files

        3. Compiling *.F examples.

           3.1   General information
           3.2   engtest*.F
           3.3   mattest*.F
           3.4** mextst1.F mextst1g.F
           3.5** yprime.F yprimeg.F

        4. Problems

        ** (Not on convex or cray)


    1. Compiling *.c examples

       1.1 General information

           The C examples below use the following variables:

                <matlab> = MATLAB install directory
                <arch>   = machine architecture

                           sun4      (SOLARIS 1 on sun4)
                           sol2      (SOLARIS 2 on sun4)
                           hp700     (HP 9000/700 series)
                           dec_risc  (ULTRIX on DEC MIPS)
                           alpha     (OSF1 on DEC Alpha)
                           hp300     (HP 9000/300 series)
                           sgi       (SGI IRIS Seris 4D) 
                           ibm_rs    (IBM RS/6000)
                           c2mp      (ConvexOS)
                           cray      (UNICOS)

       1.2 engtest*.c

           Example for engtest1.c. The others work similiarly.

           cc -I<matlab>/extern/include -o engtest1 engtest1.c  \
                <matlab>/extern/lib/<arch>/libmat.a -lm

       1.3 mattest*.c

           Example for mattest1.c. The others work similiarly.

           cc -I<matlab>/extern/include -o mattest1 mattest1.c  \
                <matlab>/extern/lib/<arch>/libmat.a -lm

       1.4 mexmat.c (Not on convex or cray)

           Use the MATLAB cmex script:

                cmex mexmat.c

       1.5 mextest1.c (Not on convex or cray)

           Use the MATLAB cmex script:

                cmex mextest1.c

       1.6 yprime.c (Not on convex or cray)

           Use the MATLAB cmex script:

                cmex yprime.c

    2. .f versus .F files

       2.1 'pointers' in Fortran

           Because of the dynamic nature of its memory management, MATLAB
           makes use of pointers for referencing data.  Since Fortran does
           not have intrinsic support for pointers, MATLAB external
           programs use integer parameters.  Unfortunately, there is no
           universal integer data type that is guaranteed to be appropriate
           for holding a pointer.  For example, on most 32-bit machines, a
           pointer is 32-bits wide and will fit in an INTEGER*4.  On 64-bit
           machines like the Alpha and the Cray, a pointer is 64-bits wide
           and requires an INTEGER*8. 

       2.2 What statements are 'pointers' in the examples?

           For the .f files each group of Fortran declarations that are
           used as pointers are surrounded by Fortran comments like,

c-----------------------------------------------------------------------
c (pointer) Replace integer*4 by integer*8 on alpha and cray
c
      integer*4 mxCreateFull, engOpen, engGetMatrix
      integer*4 ep, a, d
c-----------------------------------------------------------------------

           For the .F files the non-standard datatype 'pointer' is used
           instead of 'integer*' to designate the variables as being
           pointers. For example,
           
      pointer mxCreateFull, engOpen, engGetMatrix
      pointer ep, a, d

       2.3 When to use .f files?

           If you are NOT on either the alpha or cray you can use the
           .f files immediately.

       2.4 Creating .f files on the alpha and cray

           If you are on the alpha or cray create new .f files by running

               bf2f *.F

           IMPORTANT: To generate the original .f files you will have
                      to run 'bf2f *.F' command  on a MATLAB supported
                      platform other than the alpha or cray.

       2.5 Staying with .F files

           If you comfortable with and have access to the C language
           preprocessor see section 3 about how to do everything using
           .F files which are recognized by many Fortran compilers as
           well as MATLAB's fmex.

    3. Compiling *.F examples

       3.1 General information

           The Fortran examples below use the following variables:

                <matlab> = MATLAB root directory
                <fc>     = Fortran Compiler
                <arch>   = machine architecture

                <fc>      <arch>

                f77        sun4      (SOLARIS 1 on sun4)
                f77        sol2      (SOLARIS 2 on sun4)
                f77        hp700     (HP 9000/700 series)
                f77        dec_risc  (ULTRIX on DEC MIPS)
                f77        alpha     (OSF1 on DEC Alpha)
                f77        hp300     (HP 9000/300 series)
                f77        sgi       (SGI IRIS Seris 4D) 
                f77        ibm_rs    (IBM RS/6000)
                fc         c2mp      (ConvexOS)
                cf77       cray      (UNICOS)

           Because of the dynamic nature of its memory management, MATLAB
           makes use of pointers for referencing data.  Since Fortran does
           not have intrinsic support for pointers, MATLAB external
           programs use integer parameters.  Unfortunately, there is no
           universal integer data type that is guaranteed to be appropriate
           for holding a pointer.  For example, on most 32-bit machines, a
           pointer is 32-bits wide and will fit in an INTEGER*4.  On 64-bit
           machines like the Alpha and the Cray, a pointer is 64-bits wide
           and requires an INTEGER*8. 

           In order to accommodate these platform-specific differences, it is
           necessary to run MATLAB external programs through a preprocessor
           as part of the compilation process so as to perform the proper
           mapping of pointers onto integers.  This mapping is handled by an
           include file fintrf.h, which is located in the extern/include
           subdirectory.  The need for this mapping is indicated by naming
           the Fortran source files with a .F extension (as opposed to a .f
           extension).  For Fortran Mex-Files the fmex shell script will
           automatically take care of this extra step.  When compiling stand-
           alone mat or engine Fortran programs, you will need to specify
           the path to the include directory as one of the compiler command
           line options.

           The Fortran compiler on the following platforms does not recognize
           the .F extension:

                ibm_rs   c2mp (convex)  cray
           
           For these platforms a utility called:

                F2f

           in this directory must be to used to preprocess a .F file into
           a regular .f file. This utility requires the MATLAB root
           directory which may be specified as a command line argument to
           F2f or it can be 'hardwired' in an assignment statement in F2f.
           This utility should be used as the first step for the cases
           that fmex is not used.

       3.2 engtest*.F

           Example for engtest1.F. The others work similiarly.
           
           .F can be used: (except ibm_rs, c2mp, cray)
           
           <fc> -I<matlab>/extern/include -o engtest1 engtest1.F \
                 <matlab>/extern/lib/<arch>/libmat.a -lm

           .f must be used: (ibm_rs, c2mp, cray)
           
           F2f engtest1.F
           <fc> -I<matlab>/extern/include -o engtest1 engtest1.f \
                 <matlab>/extern/lib/<arch>/libmat.a -lm

       3.3 mattest*.F

           Example for mattest1.F. The others work similiarly.

           .F can be used: (except ibm_rs, c2mp, cray)

           <fc> -I<matlab>/extern/include -o mattest1 mattest1.F \
                 <matlab>/extern/lib/<arch>/libmat.a -lm

           .f must be used: (ibm_rs, c2mp, cray)

           F2f mattest1.F
           <fc> -I<matlab>/extern/include -o mattest1 mattest1.F \
                 <matlab>/extern/lib/<arch>/libmat.a -lm

       3.4 mextst1.F mextst1g.F (Not on convex and cray)

           Use the MATLAB fmex script.

                fmex mextst1.F mextst1g.F

       2.5 yprime.F yprimeg.F (Note on convex and cray)

           Use the MATLAB fmex script:

                fmex yprime.F yprimeg.F


    4. Problems

       If you have questions or want to report problems please contact:

           The MathWorks, Inc. Technical Support:

           Phone: 508-653-1415
           FAX:   508-653-2997
           Email: support@mathworks.com

-------------------------------------------------------------------------------
Copyright (c) 1993-94 by The MathWorks, Inc.
$Revision: 1.9 $  $Date: 1994/04/01 14:44:32 $
-------------------------------------------------------------------------------
