A Shell Application

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

This month's column deals with designing an application shell to be used with ported Fortran programs. While the basics of an application shell have been documented in other MacTutor articles, I felt a shell in Fortran would give users a good starting point for integrating their ported programs.

Porting to a Shell

Most mainframe Fortran programs can be viewed (at least for our purposes) as a straightline or sequential process. The user starts the program, it executes (probably not in a pure straightline fashion), and it stops at one or more predefined points in the code. Rewritng this straightline code into a Mac user interface will probably (always?) involve massive restructuring of the code. Given that the third of the stated goals in the previous month's column was minimizing conversion effort, complete restructuring is likely to be undesirable in a large number of situations. This presents the basic dilemma: the user wants to port Fortran programs from the mainframes with a minimal amount of conversion effort, but the user does want to include a Mac user interface.

One solution to this dilemma is to treat the ported program as a subroutine, to be executed upon request from a menu choice. This let's the user have a covering application shell which has the standard Mac features available until execution of the ported program begins. Just before starting execution of the ported program, the Mac features can be completely or selectively disabled. Upon completion of the ported program, the user is returned to the application shell. This design gives the user the ability to rerun the ported program several times without exiting to the desktop.

Of possibly greater benefit to the user from this design is that it provides a starting point for integrating the ported Fortran program. If no further integration is desired, none needs to be done. However, in the application shell the user has the basic structure in place for integrating those Mac features desired to the ported program. This could even include importing information via desk accessories and/or cut, copy, and paste. Users have the freedom to integrate as much or as little as they like.

The Shell Program

The application shell given in Listing 1 has parentage from several other programs. The initial basic design came from the Demo.for program included with MacFortran. However, the program goes well beyond that demo. Design ideas also came both from a translation to Fortran of the sample edit program on the developers disks (graciously provided by Absoft) and from previous MacTutor articles. I find that the assembly shell by Dave Smith (Vol 1 #'s 3 and 4) and that the C Workshop series by Bob Denny (Vol 1, #'s 2 thru 7) very useful for design assistance. Reviewing these articles yields many insights into the program design. In fact, I wrote the shell mostly from review of the aforementioned articles and program listings, with very little direct reference to Inside Macintosh. The program is written using MacFortran version 2.1, now being distributed by Microsoft, and in particular, uses the include files from the 2.1 version.

Fig. 1 Fortran Compilation

The shell program makes heavy use of the toolbox using the toolbx.sub subroutine calls. Toolbox procedures that return a value are accessed by the toolbx function call. For example: mywindow = toolbx (FRONTWINDOW) would return a pointer (integer*4) to the front window on the screen to the variable mywindow. Toolbox procedures that do not return variables are accessed as a toolbx subroutine call. For example: call toolbx (DRAWMENUBAR) executes the toolbox routine that draws the menu bar given the current menu list.

Given that MacFortran does not type or range check values passed to the toolbx routine, it is a good idea to compile your programs using an implicit none statement in the main and all subprograms. This forces the compiler to report any undeclared names. This is particularly important for the names for the toolbx calls.

[Access to information contained in toolbox parameters is done by defining appropriate length data constructs, then using equivalence statements to access those elements needed. In converting this program from 2.0 to the Microsoft version 2.1, a problem arose regarding the use of the include files. The include file for the Event manager contains the definitions to translate the Pascal type event record structure into a fortran array. Equivalence statements then equate labels such as what, where or modify to the appropriate array item. In most of the include files, only the dimension statements are given; the equivalence statements should be in your main program. However, in the Event include file, equivalence statements are given for the event record array to the typical MDS field names mentioned above. Since this include file must be present in all your subroutines, a subtle error can occour where an equivalenced variable (from the Event include file) is also referenced as the dummy arguement in a subroutine parameter list. In the program listing in figure 1, I had this problem. Rather than change the include file, I used another dummy variable, mouse, to replace the where(1) field in the parameter list for the Menu subroutine, thus eliminating the conflit with the fact that the where(1) variable was equivalenced to Eventrecord(6) in the Event include file. A cleaner way to solve this problem, and what you should do is to remove all the equivalence statements from the Event include file and any other include files, leaving those files only for variable definitions. Instead place the equivalence statements in your main program and that way, they won't conflict with dummy variables in external subroutine calls. -Ed.]

Examination of Listing 1 reveals that the program consists of three main parts. First, the main program initializes the menu bar and window using resources created by the Rmaker utility. Listing 2 gives the input file for Rmaker to create these resources. Rmaker is extremely picky about syntax. For example, a blank line means a blank line; there can be no characters other than a carriage return in that line. Use the show invisibles option of the editor to locate any extraneous characters. The resources are retrieved using toolbox calls (e.g. GETMENU).

During the initialization of Mac features, the default I/O window provided by the MacFortran run time library is removed by getting a handle to it using window = toolbx (FRONTWINDOW). The window is then closed by call toolbx (CLOSEWINDOW, window). This is all well and fine, except when you try to run the debugger on a program that removes the default window in this manner. When you are using the debugger, the call to FRONTWINDOW will return a handle to the statement list window since it is the active front window on the screen, rather than the defualt I/O window. I typically do not close the default I/O window until the program is fully debugged

A further note about the debugger is in order. Given the resource file shown in Listing 2, the debugger will not work, because the file type and creator have been changed to allow a custom icon. The strategy for debugging that I follow is to have two resource files: the full file that includes icon resource information and bundling information, and another shorter resource file, that is compatible with the debugger (ie does not have icon, bundle or fref resources). This second resource file adds resources to an existing file by using

!Shell apl

at the start of the file to identify the existing unlinked compiled code file. The only resource types added are the menu, window, and dialog definitions. This allows a fairly smooth process for debugging. The source is edited, then compiled with the symbol table option for debugging on. From the compiler transfer menu, I use the select application option to transfer to Rmaker to add the resources. Then I can run the interactive debugger on the compiled code with resources attached.

After initializing the Mac features, the program enters the event loop. This loop detects when an event has occurred (GETNEXTEVENT), processes the event, and then returns for the next event in the queue. The loop decodes the event using the select case statement with the "what" portion of the eventrecord. The mouse down event is of primary importance because it locates where the mouse button was clicked using FINDWINDOW. The mouse down event is decoded using if-then-else constructs. Menu events are passed to the subroutine "menus" for decoding. This subroutine decodes the menu item choosen using select case constructs.

The only portion of the program design given in Listing 1 that caused serious exploration of Inside Macintosh and the MacFortran manual for an answer was the modal dialog box in the About menu choice. Modal dialogs force the user to respond to the dialog by "locking" out all other interfaces (menus, etc.). Calling a modal dialog defined in the resource fork would be done in MacFortran by:

dlg=toolbx(GETNEWDIALOG,dlgid,dstorage,behind)
call toolbx(SETPORT,dlg)
call toolbx(MODALDIALOG,userfilt, itemh)
call toolbx(DISPOSEDIALOG,dlg)

where dlg is a pointer to the dialog structure, dstorage is set to 0 to allocate the storage on the heap, behind is set -1 to bring the dialog to the front of the windows on the screen, itemh is the item number clicked on by the user, and userfilt is a pointer to the starting address of the user supplied filter function. The user controls the events on the screen during the modal dialog with the filter function (see Bob Denny's C Workshop Volume 1, # 7 for an example).

No Filter Functions in MacFortran

The problem with implementing this structure in MacFortran is that there currently is no easy or reliable way to get the handle to the user filter function, userfilt. Absoft states that they are working on a fix for this problem. However, in the mean time, users cannot write their own custom modal dialog boxes. I will report any solution as soon I discover one. Note that this problem does not exist for modeless dialog boxes. For an example of a modeless dialog used for the About menu option, see Dave Smith's Assembly Lab (Vol. 1, #4).

Instead of using a modeless dialog for the About menu, I elected to stay with a modal dialog, but use a simple control button from a dialog resource to exit the dialog box.

Creating the Standalone Application

Compiling and linking the resources should proceed in the following manner. First compile the application source code using the Macfortran compiler. Next, if you want to create standalone code, use the MacFortran linker to link the output of the compiler with toolbx.sub and f77.rl, the run time support package. After linking, then compile your resource file with Rmaker, and use an include statement in your resource file to move in the linked fortran code file. If you compile and link the resources using Rmaker before linking the runtime package, the MacFortran linker will get lost. So compile, then link, then run Rmaker! The result will be a stand alone application file with it's own icon as shown in figure 1.

The required MacFortran linker commands to link the application code to the external subroutines and run time package is:

>f  shell 
>f  toolbx
>l  f77.rl
>o Shell Prog
>g

The toolbx subroutine is the external subroutine that handles the toolbox interfacing, while the f77.rl file is the library of run time support routines necessary for stand alone operation. Remember to have the linker and all the files on the same disk (I have found the 2.0a linker to be unreliable in getting the run time library from another disk).

Concluding Remarks

The discussion of the construction of the shell program has been delibrately brief, since most of the programming ideas have been explored in other languages in previous MacTutors. Listing 1 is heavily commented to assist in your analysis of the program. The output of the program is shown in figure 2.

[One area of research that the MacTutor staff is engaged in is the compatiblity between the Fortran linker and the MDS linker. As we reported last month, you can compile your fortran routine to assembler source code with the Fortran compiler, and then assemble the source code with the MDS assembler. The only change is that the START label must be declared XREF and the period prefix removed from the asm file. The MDS assembler will then assemble this source and create a .REL file that can be linked with other MDS files and resources into an application. But the resulting assembly source code contains an include file init.asm that causes the Fortran run time package to be opened, and hence that package must be available when the program is run. The solution to this lies in either getting the MDS linker to link in the toolbx.sub and f77.rl files to the MDS .REL files, or, getting the Fortran linker to open MDS application files. So far, both attempts have failed. The MDS linker does not recognize the two required Fortran routines, and the Fortran linker does not recognize MDS application files. What is needed is further study of the Fortran compiler output file format with the .REL file format of the MDS system. Between these two files, a method for compatiblity can be found. The motivation for this research is that the new Consulair smart linker is downward compatible with the MDS linker, and hence could be used as a substitute for the Fortran linker, allowing one smart linker to link MDS, C and Fortran files together. We invite reader participation in this effort. -Ed.]

*
*  The following program demonstrates the MacFortran
*  interface to the Macintosh tool box by creating an
*  application 'shell'. It uses Quickdraw, the Menu Manager,
*  the Window Manager, and the Event Manager. The program 
*  is originally based on the demo program provided by Absoft
*  with the MacFortran package.  This program uses resource
* files to load  the menu and the window.
*
*  Mark E. McBride   8/15/85
*

 program Shell
 
 implicit none ! helps keep us out of trouble
 
 
 include desk.inc
 include dialog.inc
 include event.inc
 include menu.inc
 include quickdraw.inc
 include misc.inc
 include textedit.inc
 include window.inc
*
* event strucutures defined in event.inc
*

 
*
* menu definitions
*

 integer*4 menuhandle! pointer to menu
 
 
 
*
* window strucutures
*
 integer*4 d_window! pointer to the Shell window
 integer*1 d_record(154)  ! shell window record
*
* general variables
*
 integer*4 toolbx! the tool box interface
 integer*4 window! general purpose pointer
 integer*4 size,w,h! for growing documents
 integer*2 rect(4)        ! rectangle coordinates
 integer mouseloc       ! mouse location from FINDWINDOW
 integer*4 hte,trect(4) ! text edit handle and rectangle
 integer*2 mouse(2)! where() field of eventrecord()
*
*  Flush the event manager before calling
*
 eventmask = -1
*
*  Close MacFortran I/O window 
*
 window=toolbx(FRONTWINDOW)
 call toolbx(CLOSEWINDOW,window)
*
*  Call Text Edit initilization.  This is the only package you
*  need to initilize.  MacFortran handles all the others.
*
 call toolbx(TEINIT)
*
*  Build the menu from the resource file 
*
 menuhandle=toolbx(GETMENU,29)! get 1st menu
 call toolbx(INSERTMENU,menuhandle,0)
! insert at end of list   
 call toolbx(ADDRESMENU,menuhandle,'DRVR') 
! add desk accessories
 menuhandle=toolbx(GETMENU,30)! get 2nd menu
 call toolbx(INSERTMENU,menuhandle,0)
! insert at end of list
 menuhandle=toolbx(GETMENU,31)! get 3rd menu
 call toolbx(INSERTMENU,menuhandle,0)
! insert at end of list
 menuhandle=toolbx(GETMENU,32)! get 4rd menu
 call toolbx(INSERTMENU,menuhandle,0)
! insert at end of list
 call toolbx(DRAWMENUBAR) ! display menu bar
*
*  Create the window. the SETPORT call allows FORTRAN I/O
*  to take place: The window is created using a resource and 
*  the GETNEWWINDOW toolbox call.
*
 d_window = toolbx(PTR,d_record)
 d_window = toolbx(GETNEWWINDOW,1,d_window,-1)
 call toolbx(SETPORT,d_window)
*
*  constraints on window dragging 
*
 rect(1) = 30
 rect(2) = 1
 rect(3) = 350
 rect(4) = 510
*
*  build a text edit record
*
 trect(1)=50
 trect(2)=4
 trect(3)=245
 trect(4)=405
 hte=toolbx(TENEW,trect,trect)
*
*  main event processing loop
*
 do
*
*  handle system jobs
*
 call toolbx(SYSTEMTASK)
*
*  handle events
*
 if (toolbx(GETNEXTEVENT,eventmask,eventrecord)) then
   select case (what)
     case (1)    
 ! mouse down
       mouseloc = toolbx(FINDWINDOW,where,window)              
 ! locate mouse
       if (mouseloc=1) then
          mouse(0)=where(0)
 mouse(1)=where(1)
 call menus(mouse,d_window,hte)    
 ! in menu bar
       else if (mouseloc=2) then
 call toolbx(SYSTEMCLICK,eventrecord,window) ! in system window
       else if (mouseloc=3) then
 call toolbx(SELECTWINDOW,window)  ! in content region
       else if (mouseloc=4) then
 call toolbx(DRAGWINDOW,window,where,rect)   ! in drag region
       else if (mouseloc=6) then
 if (toolbx(TRACKGOAWAY,window,where)) then  ! in goaway region
   call toolbx(HIDEWINDOW,window)
   menuhandle=toolbx(GETMHANDLE,32)
   call toolbx(ENABLEITEM,menuhandle,1)  
   call toolbx(DISABLEITEM,menuhandle,2) 
 end if
       end if
     case (6)    ! update event
       call Up_window(d_window)
     case (8)    ! activate event
       if (mod(modifiers,2) .ne. 0) then
 call toolbx(TEACTIVATE,hte)
 menuhandle=toolbx(GETMHANDLE,31)
 call toolbx(DISABLEITEM,menuhandle,1) 
 call toolbx(DISABLEITEM,menuhandle,3) 
 call toolbx(DISABLEITEM,menuhandle,4) 
 call toolbx(DISABLEITEM,menuhandle,5) 
 call toolbx(DISABLEITEM,menuhandle,6) 
 call toolbx(SETPORT,d_window)
       else
 call toolbx(TEDEACTIVATE,hte)
 menuhandle=toolbx(GETMHANDLE,31)
 call toolbx(ENABLEITEM,menuhandle,1) 
 call toolbx(ENABLEITEM,menuhandle,3) 
 call toolbx(ENABLEITEM,menuhandle,4) 
 call toolbx(ENABLEITEM,menuhandle,5) 
 call toolbx(ENABLEITEM,menuhandle,6) 
       end if
     case default! ignore other events
   end select
 end if
 repeat ! repeat for another event
 end

*
* menus: a mouse down event was detected in the menu area
*
 subroutine menus(mouse,d_window,hte)
 
 implicit none
 include desk.inc
 include dialog.inc
 include event.inc
 include menu.inc
 include quickdraw.inc
 include misc.inc
 include textedit.inc
 include window.inc

 integer*4 toolbx
 integer*2 where(2)! mouse location from event record
 integer d_window! d window pointer
 integer window  ! general window pointer
 integer*4 dlg ! dialog pointer
 integer*2 ditemh! item hit in dialog
 integer*4 menuhandle! menuhandle pointer
 character*256 name
 integer*4 refnum,item4,hte
 integer*2 mouse(2)! where() field of eventrecord()
*
*  variables for making menu selections
*
 integer*2 menuselection(2)   ! menu selection information
 integer*4 menudata! for use left of equals sign
 equivalence (menuselection,menudata)
*
*  Menu selection constants:
*
 integer Apple ! menu
 integer About ! "Apple" menu selections
 integer File  ! menu
 integer Quit  ! "File" menu selections
 integer Edit  ! menu
 integer Undo,Cut,Copy,Paste,Clear   ! "Edit" menu 
 integer Options ! menu
 integer Smsg,Hmsg ! "Options" menu selections

 parameter (Apple=29,File=30,Edit=31,Options=32)
 parameter (About=1)
 parameter (Quit=1)
 parameter (Undo=1,Cut=3,Copy=4,Paste=5,Clear=6)
 parameter (Smsg=1,Hmsg=2)
*
* Start of Subroutine
*
 menudata=toolbx(MENUSELECT,mouse)
                  ! get selected menu data
 item4=menuselection(2) ! convert to 4 bytes
 select case (menuselection(1))  ! which menu?
   
 case (Options)  ! "Options" menu
      menuhandle=toolbx(GETMHANDLE,Options)
 ! get "Options" handle
      select case (menuselection(2))
 ! "Options" menuitem selected
      
    case (Smsg)
 call toolbx(SHOWWINDOW,d_window)
 call toolbx(SELECTWINDOW,d_window)
 call toolbx(DISABLEITEM,menuhandle,Smsg)
 call toolbx(ENABLEITEM,menuhandle,Hmsg)
        case (Hmsg)
 call toolbx(HIDEWINDOW,d_window)
 call toolbx(DISABLEITEM,menuhandle,Hmsg)
 call toolbx(ENABLEITEM,menuhandle,Smsg)
        case default
          end select
   case (File)   ! "File" menu selected
     menuhandle=toolbx(GETMHANDLE,File)
 ! get "File" handle
     select case(menuselection(2)) ! "File" menuitem selected
       case(Quit)
 stop
       case default
     end select
   case(Apple)                 ! "Apple" menu selected
     menuhandle=toolbx(GETMHANDLE,Apple)                 ! get "Apple" 
handle
     select case(menuselection(2)) ! "Apple" menuitem selected
       case(About) ! About item selected
 dlg=toolbx(GETNEWDIALOG,200,0,-1)
 do
   call toolbx(MODALDIALOG,0,ditemh)
   if (ditemh=3) goto 100
 repeat
 100    call toolbx(DISPOSEDIALOG,dlg)
       case default! Desk Accessory selected
 call toolbx(GETITEM,menuhandle,item4,name)
 refnum=toolbx(OPENDSKACC,name)
     end select
   case (Edit)
     if (.not. toolbx(SYSTEMEDIT,item4-1)) then                
 ! edit not in dsk acc
       call toolbx(SETPORT,d_window)
       select case (menuselection(2))
 case (Cut)
   call toolbx(TECUT,hte)
 case (Copy)
   call toolbx(TECOPY,hte)
 case (Paste)
   call toolbx(TEPASTE,hte)
 case default    ! ignore other edit menu items.
       end select
     end if
   case default  ! just playing with the mouse
 end select
 call toolbx(HILITEMENU,0)! unhilites menu
 end    ! end of menus subroutine
*
*  MSG: clear the window and postion the pen at 3,12 (v,h)
*  and put up message
*
 subroutine MSG
 
 implicit none
 integer*4 toolbx
 include desk.inc
 include dialog.inc
 include event.inc
 include menu.inc
 include quickdraw.inc
 include misc.inc
 include textedit.inc
 include window.inc
 
 call toolbx(MOVETO,30,30)
 call toolbx(TEXTFONT,1)  ! system font
 call toolbx(TEXTSIZE,12) ! 12 point
 call toolbx(TEXTFACE,1)  ! bold
 type "Porting to the Mac"
 call toolbx(MOVETO,100,100)
 type "A series devoted to porting"
 call toolbx(MOVETO,100,130)
 type "fortran program to the Mac"
 call toolbx(MOVETO,100,160)
 type "from mainframe and minicomputers"
 
 end
*
*  subroutine to update window after event processed using 
*  window
*
 subroutine Up_window(d_window)
 
 implicit none
 include desk.inc
 include dialog.inc
 include event.inc
 include menu.inc
 include quickdraw.inc
 include misc.inc
 include textedit.inc
 include window.inc
 integer*4 toolbx,d_window

 call toolbx(BEGINUPDATE,d_window)
 call toolbx(SETPORT,d_window)
 call MSG
 call toolbx(ENDUPDATE,d_window)

 end  



* 
* Edit date: 08/13/85
* This is a RMAKER file initially generated by the  EDITOR.
* 
Shell
APPLMEMM

* Include resource code generated by MacFortran
INCLUDE Shell Prog

*
* Set up id string
TYPE MEMM = GNRL
 ,0        ;; id name is signature
.I
11
.P
MARKMCBRIDE

*
* Set up file reference
TYPE FREF
 ,4000        ;; resource id
 APPL 0      ;; file type, id of icon

 ,4001       ;; resource id
 WIND 1      ;; file type, id of icon

*
* Set up bundle resource
*
TYPE BNDL
  ,4000         ;; resource id
MEMM 0          ;; bndl owner
ICN#            ;; resource type
0 4000 1 4001   ;; local ID 0 maps to resource ID 128
FREF            ;; resource type
0 4000 1 4001   ;; local ID 0 maps to resource ID 128

Type ICN# = GNRL     ;; icon list for application
  ,4000              ;; resource ID
.H
00000000
FFFFFE00
B9F1D200
B9F1D200
B9F1DE00
FFFFFE00
80001000
80001000
BFFFD000
A4045000
A4045000
A4045000
FFFFF000
02000000
00000000
02000000
00000000
02000000
000007FF
02000401
000025FD
02001505
00000D05
02AAAD05
00000DFD
00001401
00002405
0000047D
00000401
00000401
000007FF
000003FE
*
00000000
FFFFFE00
FFFFFE00
FFFFFE00
FFFFFE00
FFFFFE00
FFFFF000
FFFFF000
FFFFF000
FFFFF000
FFFFF000
FFFFF000
FFFFF000
02000000
02000000
02000000
02000000
02000000
020007FF
020007FF
020027FF
020037FF
02003FFF
03FFFFFF
00003FFF
000037FF
000027FF
000007FF
000007FF
000007FF
000007FF
000003FE
 

* This is the definition for the MENU.

Type MENU
 ,29
\14
About Shell
(-

 ,30
File
Quit

 ,31
Edit
(Undo 
(-
(Cut
(Copy
(Paste
(Clear

 ,32
Options
(Show 
Hide

* Definition to setup window
*
Type WIND
,1
Shell Window
50 20 250 400
Visible GoAway
4
0

* Definition to setup dialog box
Type DLOG
,200
;; no name for this resource
50 50 212 404
Visible NoGoAway
1
0
200

Type DITL
,200
3
StatText Disabled
14 38 34 316
An application shell in MacFortran

StatText Disabled
94 20 114 339
Mark E. McBride            August 15, 1985

BtnItem Enabled
126 136 141 182
ok