Attaching Assembly Routines to Fortran

By Mark E. McBride, Miami University, Oxford, OH

This month's column will cover several diverse topics that have a common underlying theme: increased access to the toolbox and an introduction to integrating assembly language subroutines. However, before undertaking the new topics several additionalng the new Microsoft version of MacFortran.

First, the Microsoft version of MacFortran is on the streets (2.1 of the Absoft version). This is not entirely news since both the October and November issues used the 2.1 version. However, for those of you who have not upgraded yet from 2.0, the new version has different parameter equates for the subroutine toolbx. The 2.0 version uses decimal numbers for the parameters and the new 2.1 version uses hex and the two do not match. So, if you are trying to run a program written in the other version, watch those parameter definitions in calls to the subroutine toolbx.

Second, the 2.1 version does make life somewhat easier in setting up the parameter definitions for the subroutine toolbx by providing a set of text files grouped by areas of the toolbox, i.e., event manager, window manager. These text files can be included in the main file, relieving the drudgery of typing all that information in over and over. However, beware of the event.inc file. This text file also contains a variable definition for the array variable eventrecord and equivalence statements to variables identifying specific elements of eventrecord in addition to the toolbx parameter definitions. Inclusion of the variable eventrecord and its equivalenced variables in this file means that every program segment in which you include event.inc knows those variables. Now consider the following situation, the main program contains

Program Main
...
include event.inc
...
call menus(where)
....

and the subroutine is defined as

subroutine menus(where)
...
include event.inc
...

In this situation the compiler will generate an error, apparently due to the equivalenced variables. The best way to avoid this problem is to remove the eventrecord variable definition and the equivalences from the event.inc file (I put it in a separate file) and explicitly declare an event record type of variable in each program segment that needs it. It's odd, but the event.inc file was the only file of the ones provided by Microsoft that contained both a variable definiton for a Mac record structure and the parameter definitions for the toolbx subroutine.

Third, the upgrade for the new version for existing 2.0 owners will cost $100 which I believe is steep. Given the limited new features (DO WHILE, a few new compiler options, increased access to the toolbox, and a completely rewritten linker) and that I would consider the last two in that list as fixes to existing problems, I was taken aback by the price. In addition, my understanding of Microsoft's 'require everything of you and promise nothing in return licensing agreement' is that it does not allow you to distribute programs which are standalone applications: compiled and completely linked code which includes the runtime library. I talked to Microsoft about the latter of these two issues. The reply was that in order to include the runtime in a compiled application code you distribute (commercially or via public domain) you need to execute a second agreement with Microsoft. This second agreement gives you the right to use the runtime in application packages and evidently does not cause you to pay royalties (but I am not positive that it is royalty free, I am trying to get official word on royalties). Microsoft said to contact the Legal department of Microsoft for further information on this additional licensing agreement. I am requesting a copy of the agreement and will report on my experience in a future column. [What nonsense! -Ed.]

Using Assembly Subroutines

Assembly language subroutines can improve your Fortran program in two ways. First, for those subroutines in applications where speed is critical, a tightly coded assembly subroutine may outperform the code of the compiler. The gain from this approach may be minimal since the compiler produces fairly tight code. Second, shortcomings in the access to the toolbox routines can be addressed through assembly language subroutines. For example, in November's shell application, a modaldialog box was used in the 'About this program' menu choice in the desk accessory menu. The dialog box used the default userfilter function provided in the toolbox because of MS Fortran's inability to handle user written Fortran filter functions. Conversations with Absoft indicate that given the incompatable use of CPU registers between MacFortran and the Mac, user filter functions are probably best written in assembly. The number of tricks necessary to write the filter function in Fortran will be large and probably more difficult to implement than just writing the filter function in assembly.

The example program provided below illustrates a simple call to the toolbox routine MODALDIALOG via an assembly language subroutine. If a special user supplied filter function is required, it can be coded in assembly and integrated with the assembly program presented in Listing 1. The subroutine is called from Fortran with a 'Call Mdlg(dnum,itm)' statement where dnum is the dialog box resource number as an integer*2 and itm is the dialog item to check for as an integer*2. This assembly subroutine, thus, does not do anything particularly overwhelming. However, it does illustrate several items about accessing assembly subroutines from Fortran; including how to pass values to the assembly subroutine. Listing 1 is given in MacAsm format and would require a few modifications for the MDS system (see MacTutor Vol 1 No. 9 page 20 for the synatx differences between MacAsm and MDS).

The first few lines set up the MacAsm environment. The include files define the macros for TBX, OST, and DC directives and are stripped down versions of the file 'Library.Asm' provided on the MacAsm program disk. The equates define the toolbox trap values for the routines that will be called by this subroutine. Notice that none of the intialization routines (TEINIT, etc.) need to be called because they will have been previously called by the MS Fortran system. The Tfile directive gives the name of the file to store the compiled object code in. The compiled code is relocatable, so for convenience the origin will be set at address $00000000.

The next block of lines define the local dynamic storage for the subroutine and set up the ability to get the values passed to and from the assembly subroutine. Upon entry to the subroutine, MacFortran has pushed the following onto the stack (the top item listed is the first item on the stack) which is referenced off register A7 -

RTS - calling procedures return address
an - address of nth argument in items passed
...
a2 - address of 2nd argument in items passed
a1 - address of 1st argument in items passed
s1 - length of 1st item passed
s2 - length of 2nd item passed
...
sn - length of nth item passed

Character items have their length passed, numeric items do not. Constants which are passed are copied to a memory location and the address of the memory location is passed. A pointer to the stack memory location which contains the addresses of the first variable passed is put in register A3 in line 190. Variable offsets relative to A3 are defined in lines 120 and 130. This will let us access the items passed later in the program. Figure 1 illustrates the contents of the stack upon entry to Mdlg.sub as executed in a test program.

In addition to the items on the stack, the following information is contained in the registers of the CPU

A0 : pointer to communications area
A4 : pointer to MacFortran library jump table
A5 : pointer to MacFortran work stack !!
A6 : pointer to stack frame
D0 : the number of arguments passed.

Label "Start" simply checks D0 to see if the proper number of variables has been passed, exiting the routine if they have not. Only one local variable will be needed, ITMHT, which is two bytes long. If a second local variable of 4 bytes, called COUNT, was needed it would be handled with the following statement 'COUNT equ ITMHT-4' in the equates portion of the program. When combined with the LINK statement, a local dynamic variable area indexed off register A6 is set up on the stack in a data structure known as a stack frame. MS Fortran depends heavily on stack frame constructs for passing arguments and it is critical that you maintain the integrity of the A6 register.

Next we save all the registers except A6 & A7 onto the stack (indexed off the stack pointer, A7). MS Fortran uses the A5 register extensively for a work stack. So does the Mac. MacFortran resolves the conflict by relocating the Mac pointer! Thus, to be able to use the Mac pointer, we must restore it to the A5 register, in the line with the comment 'restore quickdraw globals'. Figure 2 illustrates the stack after execution of the link statement and the save registers statement at the beginning of the routine. At Exit, we restore all the registers to their initial values when the subroutine finishes. Be sure that your subroutine hasn't left any stray items on the stack before restoring. Finally, we unlink the dynamic storage return to the Fortran program. This sequence of tag the location of the addresses of variables passed, LINK local dynamic storage, save the world (except A6 & A7), move the Mac pointer back to A5, restore the world (except A6 & A7), and UNLINK will allow you to successfuly setup and maintain local dynamic storage, pass values back and forth to Fortran, and use the A5 register as the Mac developers intended you to.

As you saw, Fortran passes arguments to subroutines by addresses on the stack. Values can be returned to the variables used in the call to the subroutine via these same addresses. External functions return their values in registers D0 and D1 (address in A1 for character functions). See the examples discussed in Appendix E of the manual for further aspects of passing arguments.

Line 230-360: Finally, we can establish our modal dialog box by getting it from the resource fork and then use the toolbox trap MODALDIALOG with the default userfilter function to handle interaction with the modaldialog box. Notice how we get the value of dnum for the call to modaldialog. Dnum's address was passed to the subroutine via the stack. In line 241 we load the address of dnum to register A1 with the pointer we saved in A3 and an offset. Then in line 242 we use indirect addressing off A1 to push the value of dnum onto the stack. This trick is also used to retrieve the value of itm for comparison to the item number clicked by the user in lines 320-340. If the item number 'hit' by the user matches with the itm value passed from the Mdlg call, the routine exits, otherwise it retruns for another call to modaldialog. Before leaving, we close the dialog window in lines 350-360.

Finally, we can establish our modal dialog box by getting it from the resource fork and then use the toolbox trap MODALDIALOG with the default userfilter function to handle interaction with the modaldialog box. Notice how we get the value of dnum for the call to modaldialog. Dnum's address was passed to the subroutine via the stack. Refering to fig. 1, we load the address of dnum to register A1 with the pointer we saved in A3 and an offset. Then just prior to label ".0", we use indirect addressing off A1 to push the value of dnum onto the stack. This trick is also used to retrieve the value of itm for comparison to the item number clicked by the user prior to Exit. If the item number 'hit' by the user matches with the itm value passed from the Mdlg call, the routine exits, otherwise it retruns for another call to modaldialog. Before leaving, we close the dialog window.

Introduction of a user written filter function in assembly could now be accomplished. Label ".0" passes the effective address of the filter function. If a null value is passed, as is in Listing 1, the Mac supplied default filter function gets used. However, changing this CLR.L -(SP) to PEA (Myfilter,PC) allows the assembly coded filter function located at Myfilter to be used. The relative addressing off of the program counter is necessary to maintain code position independence. Given the memory management of the Mac, we must also lock the subroutine in memory, so that the absolute address passed in the PEA instruction remains correct even during the call to modaldialog. Conversations with Absoft revealed that you can lock an external assembly language subroutine by using the command 'MOVE.W #1,-8(A1)'. This pushes an immediate 1 into the proper place to lock the subroutine. This should be done before any of the registers (notably A1!) are modified by your subroutine. At the start of the program (between lines 160 and 170 in Listing 1) would be a good choice. Notice that the subroutine will remain locked in memory for the duration of the Fortran program.

Assembling the program in Listing 1 under MacAsm generates a relocateable object code file that cannot be used with the MS Fortran linker. The MDS system will generate a compatible file that can be used with MS Fortran if the code file is put in the data fork. [This can be done by assembling the file with MDS, linking it with itself with MDS to create a code resource, and then using FEdit to swap it from the resource fork to the data fork. Then strip the 121 byte header from the file so the first byte is the first program byte, or insert a jump instruction at the top of the file. -Ed] The difference lies in that MacAsm tags two 32 bit addresses onto the start of the file as load information for the MacAsm linker. Stripping these bytes provides the second example program for this month's column. Once the extra bytes generated by MacAsm are stripped, the modaldialog can be used simply by calling the subroutine. For example, in November's shell program the revised section of the code would be:

case(Apple) ! "Apple" menu selected
  menuhandle=toolbx(GETMHANDLE,Apple) ! get "Apple" 
 select case(menuselection(2))   ! "Apple" menuitem 
 case(About)! About item selected
 dnum=200
  itemnum=3
 call Mdlg(dnum,itm)
   case default  ! Desk Acc.  selected
 call toolbx(GETITEM,menuhandle,item4,name)
 refnum=toolbx(OPENDSKACC,name)
 end select

As long as the assembled object code file is on the disk with the name Mdlg.sub (6 or less characters, not counting the .sub!!!), the shell program will use the external assembly subroutine. Further, the external assembly language subroutine can be linked to the application code with the MS Fortran linker.

File Handling in MS Fortran

The need to strip the header bytes from the MacAsm object file provided a perfect opportunity to explore the standard getfile and putfile routines in the Mac. MS Fortran makes the job much easier by providing a general purpose function, stdfil, on the source disks included with version 2.1. The calling sequence is:

stdfil(what, prompt, file, n, types)

where the input arguments are

what: 0=SPUTFILE and 1=SFGETFILE

prompt: prompt string for SFPUTFILE

file: default file name for SFPUTFILE

n: number of 'types'

type: character*4 array of file type filters

and the output arguments are

file: file name as "Volume:filename"

stdfil: true if 'file' is valid.

The short program given in Listing 2 provides an example of using stdfil to open a file, strip the MacAsm header bytes, and save the new file. Examining the code illustrates how stdfil can be used to make the file preconnections that Fortran requires.

Fig 3.

The stripper program first removes the default MS Fortran window and then opens a new window using a toolbx call to NEWWINDOW and sets the current grafport using SETPORT. Next the program sets the textfont and size using toolbox calls. The last call, to the toolbox routine GETFONTINFO, returns the font characteristics in the font information record, fontinfo. This gives us information about the font which is useful in spacing our displays.

Figure 3, a variation on the diagram given in Font Manager section of Inside Mac, shows the interpretation of these characterisitics. Ascent is the distance from the base line of the font to the top of font. Descent is the distance from the base line of the font to the bottom of the font. Widmax is the greatest distance the pen will move when a character in the font is drawn. Finally, leading is the vertical distance between the descent line and the ascent line of the line below it. Thus, the height of a character can be interpreted as the sum of the ascent, the descent, and the leading or the distance from the ascent of one character and the ascent of the character on the line below.

After getting the font information, the program uses a call to stdfil to get the name of the file to be opened and stripped, as shown in Figure 4. Notice that stdfil will select only those files of type 'YBIN' which is the MacAsm tag and the selected file name will be returned in the character*64 variable ofile. The program then opens unit 10 as the sequential unformatted file. If stdfil returns false (e.g. cancel button pushed) the program skips to printing the final screen.

After opening the file to be stripped, the program uses stdfil to retreive the output file name from the user, see. The output file is assigned to unit 11 as a sequential unformatted file.

Once both input and output files have been opened, the program loops through the file one byte at a time, outputting the bytes after the header information has been passed. Notice that the font information is used to control the printing of the hex bytes, particularly to space between the lines. The 'type' statement is used instead of 'write' so that the font selected will be used to print on the screen.

Fig 4.

When the entire file has been read, the program exits to short program segment which draws a box around those bytes stripped from the file and displays information on the screen about the file selected and outputted. Again, the font characteristics are used to space out the display, as shown in Figure 5.

Use of the toolbx routines SFGETFILE and SFPUTFILE are relatively easy given the MS Fortran supplied subroutine stdfil. Studying the source code for stdfil can give you ideas about how to improve the handling of the filenames with SFGETFILE and SFPUTFILE.

Accessing Mac Global Variables

The final topic for this month's column deals with accessing Mac global variables which are discussed in the Quickdraw Programmers Guide portion of Inside Mac. Why would you care about accessing these globals from Fortran? Well, in the original September 1985 column I discussed that in Version 2.0 you could not use the toolbox random number generator because you had no way to seed the generator. The random seed is located as a global variable index off register A5. Version 2.1 will let you access those global variables. Also note that in the October fractuals program, the call to toolbx(RANDOM) will always generate the same random sequence because the intialization of quckdraw by the toolbox sets the seed to 0 and the fractuals Fortran program has not reset the seed.

Accessing the Mac global variables is done through a toolbx subroutine call to GETGLOBAL with an offset to the particular global variable desired. These offsets are not included on the MacFortran diskettes. Absoft graciously provided me with a copy of a file they call a5glob.inc which has been reprinted in Listing 3. This include file defines the offsets for the global variables. Now, if we wish to get a pointer to the random number seed location, we just need to use 'toolbx(GETGLOBAL)+RANDSEED'. We then can use this pointer with the LONG function to read or modify the value of the random seed. The following short program will generates a different random sequence each time run by reseeding the toolbox random number generator with the system tickcount. Note the the toolbox random number generator returns an integer value between -32768 and 32767.

Fig 5.

program random test
  integer*4 i,toolbx
  include quickdraw.inc
  include a5glob.inc
  include misc.inc
  include event.inc
  long(toolbx(GETGLOBAL)+RANDSEED) 
 =toolbx(TICKCOUNT)
  do (i=1,25)
    write(6,*) toolbx(RANDOM)
   repeat
end

This ends our exploration this month of the world of MacFortran.

Listing 1
 ;SAVE"Mdialog.Asm"
 *--------------------------------
  LIST OFF
 *--------------------------------
 INCLUDE "ShortLibrary.Asm"
 INCLUDE "DCs.Asm"
 *--------------------------------
 GetNewDialog      equ  $A97C
 CloseDialog       equ  $A982
  ModalDialog      equ  $A991
 ITMHT           equ  -2
 NARG              equ  2
 DNUM            equ  0
 ITM               equ  DNUM-4
 LIST    ON
TFILE   "Mdialog.sub"
 *--------------------------------
START    CMP.L   #NARG,D0          ;check for number of args
 BNE      NOARG           ;wrong number of arguments
 LEA      NARG*4(A7),A3 ;point at last argument
 LINK     A6,#ITMHT       ;get local storage
 MOVEM.L  A0-A5/D0-D7,-(SP) ;save the world
 MOVE.L   -4(A0),A5       ;restore quickdraw globals
 CLR.L    -(SP)           ;returned hande
 MOVE.L DNUM(A3),A1     ;get dnum address
 MOVE.W   (A1),-(SP)      ;put dnum to stack
 CLR.L    -(SP)           ;store on heap
 MOVE.L   #-1,-(SP)       ;in front
 TBX      GetNewDialog    ;get new dialog
 MOVE.L   (SP)+,D7        ;save handle
.0 CLR.L    -(SP)           ;use default filterproc
 PEA      ITMHT(A6)       ;storage for item hit result
 TBX      ModalDialog     ;call modaldialog routine
 MOVE.W   ITMHT(A6),D0    ;get item hit result
 MOVE.L   ITM(A3),A1      ;get item number to check
 CMP.W    (A1),D0         ;and compare to item result
 BNE.S    .0               ;do it again if not 'ok'
 MOVE.L   D7,-(SP)        ;push dialog handle on stack
 TBX      CloseDialog     ;close dialog window
Exit  MOVEM.L  (SP)+,A0-A5/D0-D7 ;restore the world
 UNLK     A6              ;deallocate local storage
NOARG    RTS
 *--------------------------------
END

Listing 2
*  The following program strips the first 8 bytes (two 32 bit
*  words) from the start of a MacAsm binary file.  Thus, the
*  program can be dangerous. Its intended use is to strip off
*  the bytes placed at the start of a MacAsm object file created
*  using either the TFILE or BSAVE commands. MacAsm uses
*  these two 32 bit words as load information.
* 
*  The program is written for the MS Fortran V2.1 compiler and
*   makes use of a subroutine Stdfil developed by
*  Microsoft/Absoft.
* 
*  Mark E. McBride
*  211 N. University Ave.
*  Oxford, OH  45056
* (513) 523-1438
*
 Program Stripper
 
 implicit none !keeps us out of trouble
 
 include window.inc
 include dialog.inc
 include quickdraw.inc
 include misc.inc
 
 integer*2 word  ! a two byte word
 logical stdfil  ! external get and put file routine
 character*64 ofile,nfile ! old file name and new file name
 character*256 strg! general purpose string variable
 integer*2 rect(4) ! general purpose rectangle info
 integer*4 i! looping variable
 integer*4 toolbx! toolbox interface
 integer*4 window,ow ! general purpose wind. handles
 integer*1 o_record(154)  ! window record
 integer*2 fontinfo(4)  ! font information record
 integer*2 ascent,descent,widmax,leading ! font style
 integer*2 height! height from top of font to top
 integer*4 normal,bold  ! textface styles
 
 equivalence(fontinfo(1),ascent)
 equivalence(fontinfo(2),descent)
 equivalence(fontinfo(3),widmax)
 equivalence(fontinfo(4),leading)
 data normal,bold /0,1/
*
*  Close MacFortran I/O window
*
       window=toolbx(FRONTWINDOW)
       call toolbx(CLOSEWINDOW,window)
*
*  Open viewing windows
*
 rect(1)=50
 rect(2)=20
 rect(3)=350
 rect(4)=500
 strg=char(len(trim("Stripper")))//"Stripper"
 ow=toolbx(PTR,o_record)
 ow=toolbx(NEWWINDOW,ow,rect,strg,.true.,4,-1,.false.,0)
 call toolbx(SETPORT,ow)
*
*  Set textfont and size
call toolbx(TEXTFONT,4)   ! monaco font
 call toolbx(TEXTSIZE,9)  ! 9 point
 call toolbx(TEXTFACE,normal) ! normal
 call toolbx(MOVETO,20,20)! move to start point of text
 call toolbx(GETFONTINFO,fontinfo) ! get font stuff
 height=ascent+descent+leading
*
*  Get input and output file names and process
*
if (stdfil(1,' ',ofile,1,'YBIN')) then
   open(10,file=ofile,access='sequential',form='unformatted')
   nfile="untitled"
   if (stdfil(0,'Save File Name',nfile,1,'')) then
     open(11,file=nfile,status='new',form='unformatted',
     +      access='sequential')
*
*  loop through the file a byte at a time
*
      i=1
      do
        read(10,end=100) word
        if (i>4) write(11) word
        type 1000,word,' '
 1000 format(z4.4,a1)
        call toolbx(MOVE,widmax,0)
        if (mod(i,8)=0)
     +  call toolbx(MOVETO,20,20+int(i/8)*height)
        i=i+1
        repeat
   endif
 endif
*  box part of the screen display
*
 100  call toolbx(MOVETO,20,20)  ! start of hex values
 rect(1)=20-height ! set up rect bounds
 rect(2)=20-0.5*widmax    ! leave room on left
 rect(3)=20+descent+0.5*leading  ! leave room on bottom
 rect(4)=20+(widmax*20)-3 ! leave room on right
 call toolbx(PENMODE,9)   ! set penmode to pator
 call toolbx(FRAMERECT,rect)! fill in rectangle
 call toolbx(MOVETO,20,20)! upper left corner
*
*  put out message at side of hex listing
*
 call toolbx(MOVETO,20+widmax*40+15,20)
 type "The boxed values have been"
 call toolbx(MOVETO,20+widmax*40+15,20+height)
 type "stripped from the file "
 call toolbx(TEXTFACE,bold)
 call toolbx(MOVETO,20+widmax*40+20,20+2*height)
 type *,ofile
 call toolbx(TEXTFACE,normal)
 call toolbx(MOVETO,20+widmax*40+15,20+4*height)
 type "and stored in the file "
 call toolbx(TEXTFACE,bold)
 call toolbx(MOVETO,20+widmax*40+20,20+5*height)
 type *,nfile
 call toolbx(MOVETO,20+widmax*40+15,20+10*height)
 type "Press return to continue."
 pause
 stop
 end

Listing 3
* This file contains constants useful for accessing certain
* system globals kept off A5.  You can get a pointer to this
* area from FORTRAN using the toolbx function.  For example,
* to seed the Macintosh random number generator;
*
*include toolbx.par
*include a5glob.inc
*integer toolbx
*...
*
*long(toolbx(GETGLOBAL)+RANDSEED)=5
*
* After executing the above, the random number seed will be 5.
* the globals accessable in this way are given on page 34 of
* the QuickDraw Programmer's Guide in Inside Macintosh.
*
* This file has been graciously provided by Absoft and is not
* included on the MS Fortran Version 2.1 diskettes.  Save this
* file under the name 'a5glob.inc'. 

 INTEGER ATTHEPORT
 PARAMETER (ATTHEPORT=0)
 INTEGER THEPORT
 PARAMETER (THEPORT=-4)
 INTEGER WHITE
 PARAMETER (WHITE=-12)
 INTEGER BLACK
 PARAMETER (BLACK=-20)
 INTEGER GRAY
 PARAMETER (GRAY=-28)
 INTEGER LTGRAY
 PARAMETER (LTGRAY=-36)
 INTEGER DKGRAY
 PARAMETER (DKGRAY=-44)
 INTEGER ARROW
 PARAMETER (ARROW=-126)
 INTEGER SCREENBITS
 PARAMETER (SCREENBITS=-126)
 INTEGER RANDSEED
 PARAMETER (RANDSEED=-130)