The Clipboard and Desk Scrap Revealed

By Mark E. McBride, MacTutor Contributing Editor

Before moving to this month's topic, there are two items of news. First, I have received Apple's new 20 megabyte hard disk . As reported in the January issue of MacTutor the new HD20 will not work with the current 2.1 release of MacFortran, nor will it work on a Mac Plus or under HFS. Discussion with Absoft/Microsoft revealed that a solution will be forthcoming, probably with the 2.2 version (which is to be released sometime this spring or early summer). I will pass along any information I receive.

[We at MacTutor think it is a disgrace that Microsoft is dragging their feet on the Fortran Upgrade. All the other languages for the Mac now run correctly under HFS. Fortran not only is buggy under HFS, it doesn't run at all! It is unfair to Fortran customers for Microsoft to be so slow to respond to the new systems, especially since they have taken great pains to see that their own internally developed software works! Obviously, those products which Microsoft distributes from other vendors take a back seat to their own products. Absoft has supplied Microsoft with the new version of Fortran and we think if Microsoft can't speed that product to market, they should return the rights back to Absoft so the product may be properly supported and upgraded in a timely manner. -Ed.]

The move to the hard disk forced me to upgrade memory. Actually, I find it fairly amazing that I have written the current and all the previous columns using 128k and two drives. The only time I have felt constrained by the 128k is trying to debug programs with large data structures. The debugger takes about 40k, leaving very little room for your program. Note, however, that the shell application in the November 1985 issue was compiled and debugged on a 128k machine.

The second piece of news of some importance is that the include files in MacFortran 2.1 have some errors in the parameter definitions. These errors became apparent the first time I tried to do memory management related toolbox calls from MacFortran. I talked with Absoft about the problems I was having and they disclosed the existence of the errors. Fortunately, these errors can be corrected by editing the toolbox include files. Listing 1 is a reprint Absoft sent to me which shows the correct parameter definitions for the affected toolbox calls. Be sure to correct the parameter definitions in both the toolbx.par file and in the memory.inc and OSutilities.inc files. You will need to correct these include files to use this month's function program.

A related note is that some of the update/ correction files have been appearing on Compuserve's MAUG board. They can be found under the Mac Developer's download library on programming tools.

The Desk Scrap

All of us are familiar with the clipboard in the standard Macintosh application. The clipboard holds a copy of the last item cut or copied so that it can be pasted back in at a later time. Further, we know that cutting or copying to the clipboard allows us to exit the application to the finder and then enter a different application with the clipboard intact (if the second application conforms to the standards for cutting and pasting). The desk scrap is the vehicle for transferring information between applications. These other applications can be standalone programs or desk accessories. The desk scrap normally resides in the heap in memory, but it can be moved to a disk by an application if memory space is a problem. Figure 1 illustrates the typical relationship between two applications, a desk accessory, and the TEscrap and the desk scrap. This article will focus on the use of a private scrap in an application with the desk scrap.

The application program is responsible for insuring that the proper information is retrieved from the desk scrap or moved to the desk scrap. Although it is possible to read and write information directly to the desk scrap, most applications use a private scrap for cut, copy, and paste operations and then pass information to and from the desk scrap using routines supplied in the toolbox. Also, it is important to note that the rom text edit routines (accessed via TExxxx toolbox calls) maintain their own private scrap. We will save the discussion of the TE scrap and the desk scrap for another time. The TEfromScrap and TEtoScrap Pascal calls are not part of the rom and are not availabe from MacFortran.

Upon entry to an application the desk scrap resides on the application heap and has the format shown in Figure 2. The information in the desk scrap may be passed in more than one format. The two standard format types are 'TEXT' and 'PICT'. Desk scrap information of type 'TEXT' is simply a series of plain unformatted ASCII text codes. Desk scrap information of type ' PICT' is data representing commands to draw a Quickdraw picture (see Pascal Procedures, MacTutor Vol 1 #11 October 1985 for an example of a Pascal routine which puts a ' PICT' type to the desk scrap). Inside Macintosh states that applications should write at least one of these two types of information to the scrap with the preferred format written first. Applications should be able to read at least one, if not both of these data formats. Additionally, user can put data types of their own construction out to the desk scrap for passing of information to other applications which can recognize those private types.

Using the Desk Scrap from Fortran

From within an application there are several approaches to using the desk scrap. The basic approach I take is using general purpose subroutines to move data between an application's private scrap and the desk scrap. The basic toolbox calls available to use the scrap from Fortran are:

Function InfoScrap :Inquire Deskscrap

Function UnLoadScrap :Deskscrap to disk

Function LoadScrap :Disk to Deskscrap

Function GetScrap :Deskscrap to Private Scrap

Function ZeroScrap :Empty Deskscrap

Function PutScrap :Private Scrap to Deskscrap

The source code for a routine called RScrap is given in Listing 2. The routine is accessed by 'call RScrap(Priscrap, scraplength)'. The argument Priscrap is a handle to the application's private scrap. The length of the scrap copied to the private scrap is returned in the argument scraplength. If there was a problem in copying the desk scrap into the private scrap, the error code generated (a negative value) will be returned in the argument scraplength. RScrap is set up so that the first call to it from an application automatically forces a transfer of the desk scrap to the private scrap. Any further calls to RScrap during execution of the application transfers the desk scrap only if the desk scrap's contents have changed since the last call.

To be able to use the desk scrap effectively, RScrap defines the variables to be able to access information about the desk scrap using InFOSCRAP. A data structure for the scrap record is constructed using a pointer and offsets (reviewing sections 1.06 and 1.07 of the Toolbox appendix of the MacFortran manual might be useful at this point). This data record allows access to any of the information contained in the scrapStuff structure. This same technique is used to access information in a grafport record structure or a window record structure under MacFortran. RScrap gets the scrap record information as its first step. It uses this information, along with calls to GETSCRAP (with a NIL private scrap handle) and MAXMEM to see if enough available memory exists.

Before calling the routine RScrap from the application, the user will want to create space on the heap for the private scrap. This handle is passed to RScrap as the Priscrap argument. RScrap makes a call to GETSCRAP with an appropriate specification of data type (e.g., 'PICT' or 'TEXT') and with the private scrap handle passed (RScrap could easily be modified to pass the type specification as an argument). GETSCRAP will resize the private scrap to the appropriate size, move a copy of the data of the type specified from desk scrap to the private scrap, and return the length of the scrap copied. If the length returned is negative, it represents the operating system error result or the scrap manager error result. Next, RScrap gets the current scrap count by making a call to INFOSCRAP and using the record structure offset given in scrapCount. If the user has a show clipboard option, then the loaded copy of the desk scrap could be displayed after exiting RScrap.

A subroutine similiar to RScrap (called PScrap) could easily be developed which moves the private scrap to the desk scrap. The routine would need to pass the private scrap handle and length. The PScrap routine will need to zero the desk scrap with ZEROSCRAP and then use PUTSCRAP to copy the private scrap to the desk scrap. Development of PScrap will be left to the reader.

Integrating the desk scrap and a private scrap in an application becomes a matter of calling RScrap and PScrap at the appropriate times. During the processing of the main event loop, there are five places where the user will want to concern themselves with the interaction of the private scrap and the desk scrap. First, the user should call RScrap during the initialization portion of the application program. This will load the desk scrap into the private scrap and will set the Count variable within RScrap to the current scrapCount value. Second , on each pass through the main event loop, after the check for SYSTEMTASK, the user will want to call RScrap. This allows RScrap to check for a change in the desk scrap (because of a desk accessory) and recopy the desk scrap to the private scrap, when necessary. Third, in the routine that handles menu events, if the user selects a desk accessory the application should call PScrap, before calling the desk accessory. Fourth, the user should call RScrap or PScrap (as appropriate) during activate and deactivate events if a system window (i.e., desk accessory) is involved. Finally, the application should call PScrap to update the desk scrap when exiting the application.

Importing Data via the Desk Scrap

My original motivation for investigating the desk scrap was to see if I could import data for statistical subroutines from either Multiplan or a word processor, simplifying data entry. The integer function Import given in Listing 3 (as part of the TestImport program) reads TEXT from the desk scrap into a Fortran array. The formal call to Import is:

result=Import(A,rmax,cmax)

where A is the array of maximum size rmax rows and cmax columns. The integer value returned will be zero if Import successfully read TEXT scrap into the array; otherwise the integer value returned will be the error code returned during the GETSCRAP process (which was returned by the call to RScrap). The function reads data from the desk scrap assuming that blanks, commas, or tabs separate the data values (thus handling data cut from Multiplan as well as a word processor). The routine will not handle non-numeric characters in the fields. If the desk scrap exceeds the dimensions of the array, the sub-array bounded by (rmax, cmax) will be read. If the data doesn't fill the array, the remaining elements of the array maintain their values from entry, but rmax and cmax are set to the size read in. Elements in the scrap which are not specified (i.e., two succesive tabs or commas) are left unchanged in the array.

Examination of Listing 3 reveals how the function works. First, space for the private scrap is allocated on the heap using NEWHANDLE. Then the 'TEXT' contents (if any) of the desk scrap is copied to the private scrap using the routine RScrap. The private scrap is then locked in memory for the duration of the function. If the RScrap routine returned a negative result, then the function sets its result to the error code, unlocks and disposes the private scrap, and exits.

If the RScrap routine returns a positive number for scrapLength, then data of type 'TEXT' was copied to the private scrap and its length is the positive number returned. The Import function result is set to zero. In this case, the function loops through the private scrap creating a string variable for each data value found and counting the number of data elements for that line. If data is found for a particular row and column element then the data element is read into the array A. If no data is found (e.g. two commas or tabs in a row), then the element of A is left unchanged. The process continues for as long as their is data in the private scrap or room in the array A.

After all the data has been read into the array A, the values of rm and cm are reset to the largest values used (if less than the original values passed). Finally, the private scrap is unlocked, its handle disposed, and the function exits to the calling program.

A short program to test the function is also given as part of Listing 3. This program simply prints the data array A to the screen twice, once for the full dimensions of A and once based on the dimensions returned by Import. A test data set is given in Listing 4, but your own could be created with any text editor or Multiplan. The test data contains many strange combinations of commas, tabs, and spaces to separate the values. Figure 3 shows the screen from the program in Listing 3 and the data from Listing 4.

This ends our introduction to the desk scrap. Till next time, happy computing.

Listing 1
* This file contains parameter definitions which were incorrect
* in the initial release of Microsoft Fortran 2.1.  Several OS
* traps were defined with the 'save A0' flag set to zero (this
* indicates that A0 should be restored) for OS functions which * return 
a value in A0.
* These traps are found in the following Fortran include files:
*toolbx.par
*memory.inc
*OSutilities.inc
*

* Maxmem is a special case in that it returns 2 values.  Pascal
* returns one of these in the function's argument; the
* FORTRAN toolbx.sub function has no provision for this.  For
* those requiring the Grow value, the MAXMEM2 definition 
* below should work.  MAXMEM will return only
* the size of the largest contiguous block, MAXMEM2 will
* return only the Grow size.

* Function MaxMem (VAR Grow: Size): Size;
 INTEGER MAXMEM
 PARAMETER (MAXMEM=Z'11DA0024')
 INTEGER MAXMEM2
 PARAMETER(MAXMEM2=Z'11DA00A4')

* Function NewHandle (LogicalSize: Size): Handle;
 INTEGER NEWHANDLE
 PARAMETER(NEWHANDLE=Z'122000A8')

* Function HandleZone (H: Handle): THz;
 INTEGER HANDLEZONE
 PARAMETER (HANDLEZONE=Z'126800A8')

* Function RecoverHandle (P: Ptr): Handle;
 INTEGER RECOVERHANDLE
 PARAMETER(RECOVERHANDLE=Z'128800A4')

* Function NewPtr (LogicalSize:  Size):  Ptr;
 INTEGER NEWPTR
 PARAMETER (NEWPTR=Z'11E000A8')

* Function GetTrapAddress (trapNum:  INTEGER): LongInt;
 INTEGER GETTRAPADDRESS
 PARAMETER (GETTRAPADDRESS=Z'146000A0')

* Function GetZone : THz;
 INTEGER GETZONE
 PARAMETER(GETZONE=Z'11A000A8')

* Function PtrZone (P: Ptr): THz;
 INTEGER PTRZONE
 PARAMETER(PTRZONE=Z'148800A8')
subroutine RScrap(Priscrap,scraplength)
*
*  This subroutine reads the deskscrap into a private scrap
*  located at the handle given by Priscrap.  It only loads the
*  deskscrap if the scrap has changed (read is automatically
*  forced during the first call) and if there is enough available
*  memory  to read in the deskscrap.
*
*  Mark E. McBride
*  211 N. University Ave.
*  Oxford, OH  45056
*  (513) 523-1438
*
 implicit none   ! keep us out of trouble
 
 include scrap.inc
 include memory.inc
*
*  Variables needed to get private scrap
*
 integer*4 Priscrap! handle to private scrap
 integer*4 scraplength  ! length of private scrap
 integer*4 offset! desk scrap offset
 integer*2 Count ! scrap count
*
*  This defines the PscrapStuff information record structure
*
 integer*4 PscrapStuff  ! Pointer to Infoscrap record
 integer*4 scrapSize ! size of desk scrap
 integer*4 scrapHandle  ! handle to desk scrap
 integer*2 scrapCount! count changed by Zeroscrap
 integer*2 scrapState! tells where desk scrap is
 integer*4 scrapName ! pointer to desk scrap name
 
parameter(scrapSize  =z'0') ! offset to scrapSize
parameter(scrapHandle=z'4') ! offset to scrapHandle
parameter(scrapCount =z'8') ! offset to scrapCount
parameter(scrapState =z'A') ! offset to scrapState
parameter(scrapName  =z'C') ! offset to scrapName

*
*  Other general variables needed
*
 integer*4 toolbx,Grow
*
*  Keep Count between successive calls of RScrap
*
 Save Count
*
*  Initial data values to force reading of desk scrap for first
*  call of RScrap

 data Count,Grow/-9999,100/
*
*  Begin subroutine by checking to see if desk scrap has
*  changed then copy only if 'TEXT' available in desk scrap and
*  if there is memory available.
*
PscrapStuff=toolbx(INFOSCRAP) ! get desk scrap info record
if (word(PscrapStuff+scrapCount).ne.Count) then
 Count=word(PscrapStuff+scrapCount)! scrap changed
 Grow=toolbx(MAXMEM,Grow) ! compact & check memory
 ! check for 'TEXT' without copy
 scraplength=toolbx(GETSCRAP,0,'TEXT',offset)
  if ((scraplength>=0).and.(scraplength<Grow)) then 
 ! get available scrap
     scraplength=toolbx(GETSCRAP,Priscrap,'TEXT',offset)
      Count=word(PscrapStuff+scrapCount) ! update Count
 end if
end if
end
Program TestImport
 implicit none   ! keep us out of trouble
 
 include quickdraw.inc
 include misc.inc
 include event.inc
 
 integer*4 kmax,nmax,toolbx,i,j,Import
 real*8 B(10,5)
 data B/50*-1.0/
 data nmax,kmax/10,5/
 
 write(*,*) 'The matrix is set to 10 rows and 5 columns max'
 
 if (Import(B,nmax,kmax)=0) then
   write(*,*)
   write(*,*) 'The matrix as the full 10 by 5 '
   write(*,100) ((B(i,j),j=1,5),i=1,10)
100  format(5f8.1) 
   write(*,*)
   call toolbx(MOVETO,300,100)
   type 'Press return to continue'
   pause
   call toolbx(MOVETO,300,160)
   write(*,*)
   write(*,*) 'The submatrix of the 10 by 5 which was read in'
   do 120 i=1,nmax
120  write(*,100) (B(i,j),j=1,kmax)
   write(*,*)
   call toolbx(MOVETO,300,250)
   type 'Press return to continue'
   pause
 else
   write(*,*)
   write(*,*) 'No type TEXT found in Clipboard'
 end if
 stop
 end
 

 integer*4 function Import(A,rm,cm) 
*
*  This function pulls an array of numbers from the deskscrap
*  The array size is passed in cm (number of columns) and rm
*  (number of rows).  The program reads in the data assuming that 
*  blanks, commas, or tabs separate the data values.  The routine 
*  will not handle non-numeric characters in the fields.
*  If the deskscrap data exceeds the dimensions of the matrix
*  only those elements within (rm,cm) will be read.  If the
*  data doen't fill the matrix, the remaining elements of the 
*  matrix maintain their values from entry and rm,cm are set 
*  to the size read in.
*
*
*  Mark E. McBride
*
*
 implicit none   ! keeps us out of trouble
 
 include window.inc
 include dialog.inc
 include quickdraw.inc
 include misc.inc
 include scrap.inc
 include memory.inc
 
 integer*4 rm,cm ! maximum number of rows and columns
 real*8 A(rm,cm) ! array of elements to be passed
 character*256 strg! general purpose string variable
 integer*4 i,j,col,row,cmax,rmax ! assorted looping variables
 integer*4 toolbx,temp  ! toolbox interface
 integer*4 PriScrap! handle to copy of desk scrap
 integer*4 length! private scrap length
 integer*4 space,comma,tab,return ! delimiting characters
 integer*1 c1    ! single character as integer
 character*1 ch  ! single character as character
 equivalence (c1,ch)
 parameter (space=32)
 parameter (comma=44)
 parameter (tab=9)
 parameter (return=13)
*
*  Set up scrap handles
*
 Import=-102
 length=0
 PriScrap=toolbx(NEWHANDLE,0) ! get handle for private scrap
 call RScrap(PriScrap,length) ! read in scrap of type 'TEXT'
 call toolbx(HLOCK,PriScrap)! lock copy down temporarily
 if (length > 0) then! got something in scrap
   Import=0
   temp=long(PriScrap)  ! get ptr from handle to data
*
* get the data
*
   i=0
   col=0
   row=1
   cmax=0 ! observed maximum column
   rmax=0 ! observed maximum row
   while (i<length)
     while(byte(temp+i)=space .and. i<=length) 
 ! skip leading spaces
       i=i+1
     repeat
     if (i>length) goto 10
     j=1! indexes current character in strg
     strg=""! set current string null
     c1=byte(temp+i) ! get first byte
     while ((c1.ne.space).and.(c1.ne.comma).and.(c1.ne.tab).and.
     1             (c1.ne.return)) ! process if not separator
              strg(j:j)=ch! stuff character to string
       j=j+1
       i=i+1
       if (i<=length) then! test for end of scrap
         c1=byte(temp+i)
       else
         c1=return
       end if
     repeat
     col=col+1   ! bump column counter
     if ((col<=cm).and.(strg.ne."")) read(strg,*) A(row,col) ! read data 
value
     cmax=min(col,cm)! reset  column used count
     if (c1=return) then  ! check for end of line
       rmax=row
       row=row+1
       if (row>rm) goto 10! check array boundary
       col=0
     end if
     i=i+1
   repeat
 end if
10 call toolbx(HUNLOCK,PriScrap) ! unlock copy of scrap
 call toolbx(DISPOSHANDLE,PriScrap) ! dispose 
 rm=rmax! set rm for exit
 cm=cmax! set cm for exit
 return
 end

Fig. 3 Program reads and displays clipboard

LIsting 4: A random sample of test date to try

1 11,,1111
 22,222 2222  22222
3,33,333   3333    33333 333333
 4,44,444     4444 44444
,55,555,5555,55555,555555
     6 66 666 6666 66666
  7 77 777 7777 77777
8 88 888 8888 88888 888888
999 999  9999    99999