All Databases MacTech Vol 02-1986

Scrap

Volume Number: 2

Issue Number: 5

Column Tag: Fortran's World

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, e specially 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.

Referenced by (41):