HyperArrays

By Fred Stauder, Scott Vore, Indianapolis, IN

on HyperChat

HyperMedicine: Using Hypercard to Solve Problems

This month we will look at ways people have solved problems in the medical field (my origin) using Hypercard. One of the reasons Hypercard is so popular in the medical field is that after spending so many years learning to be a doctor people feel that investing more to be a computer programmer is not justified. There is very much a “We want solutions now!” mentality.

The first problem was how do you get the patient more involved in his/her case decision making process without tying up too much of your surgeon’s time? Harold Lyon from Dartmouth Medical School used Hypercard and a laserdisc to form an interactive decision making tool. The topic is “Prostatectomy or Watchful Waiting”. The disc shows the risks and rewards of having the operation. Patients are interviewed and even doctors that have been patients. It gives you all the pros and cons of having the operation. The other purpose of the laserdisc is to gather data about patients and follow up treatments. This program that they have created has legal, ethical, educational, and research implications. It also protects the doctor by documenting the patients informed consent.

Harold Lyon gives some useful tips in preparing a videodisc>

- Always put SMPTE on the source tape.

- Flowchart the disc

- Use the same microphones at the same distance to maintain sound quality

- Train the speakers not to speak at the same time

- Work with one studio and film group

- Use small organized teams

- Never try to insert single words in audio

- Reach final script consensus prior to off-line edit

- Use colorbars on original source tapes

- Keep good track of script versions for team

- Plan the important details first

- Prepare more before on-line edit

- The video editor must be part of the team not someone hired for piecemeal work

- Consider carefully the use of one versus two camera shoots

- Ask interviewee the questions on video. Tape record these questions, play them back, and write them down. Take some head shots for cutaways. Then take the interviewer asking the same questions with a delay between each. Also take shots of interviewer sitting quietly for cutaways.

- Allow some spontinaity on line

- Film making and videodisc film making require different skills- be careful who you hire.

- Evaluate the disc before it is pressed changes are hard to make after pressing

- MacRecorder from Farralon was invaluable

- Consult experts

- Study other potential markets for your videodisc before shooting. With minor additions different applications can be made.

These tips are typical of the type of problems you will encounter when you make a videodisc.

The second interesting application is an article on XCMD’s written By Scott Vore MD. He is an anesthesiologist who wanted to track patients blood pressure, heart rate, drugs administered etc. He decided to do it in Hypercard however he found that he had to keep track of an array of data. So he wrote an XCMD called Hyperarray to do just that.

If you hear of any interesting applications Hypercard has been put to send them to us.

Send articles ideas, comments etc to Applelink: STAUDER

end HyperChat

HYPER ARRAYS

[Scott’s background is entirely self taught but he has been at it for 3 plus years now]

First of all, before you read any further I feel compelled to make the following disclaimers:

I am not, never have been, never plan to be a ‘real’ programmer. I’m totally self taught, thanks in most part to a handful of books and one excellent journal (we know which one)-consequently my programming ‘style’, if ‘style’ can describe it, contains bits and pieces of code examples I’ve seen elsewhere and often; in my haste to get things to work, I’ll leave in bits and pieces of code that serve no real purpose but should be removed if programming correctness were to be maintained. I’m sorry if this has happened here- with more time I could make it all prettier but I hope I’ve given someone enough to work with that they too can write and make things neat. My only motivation has been to make this machine work for me ,(with no formal training I have never felt competent to try and teach others). In that process, however I have learned a few things and some of those things seem important ( I guess I’ll let the editors decide just how important). Oh well, on with the show...

In my programming experience with Hypercard, I have never ceased to be amazed at the power , elegance, and simplicity inherent in this product. Every now and again, however, we all run up against ‘the wall’ and are forced to either change our approach or find another method to solving a particular problem.

Currently I am writing a stack that will be used in an Operating Room environment to allow an Anesthesiologist to record various pieces of data at specific time intervals throughout a case. Typically, the blood pressure, heart rate, and various other measurements are kept track of throughout a case so that the Anesthesiologist can keep track of the trend in these parameters as time passes, additional drugs are administered, and as the surgery progresses.

My particular problem was in storing the information in a way that was accessible in a random fashion, retrievable between calls to different stacks and between calls to shutdown that stack. In other words I wanted a data structure that was ‘global’ in nature and that acted as an array.

Being a faithful MacTutor reader I am aware that we are being admonished to always try and solve our problems in Hypertalk before resorting to writing an XCMD, so in all fairness I must say that the XCMD described below does have a Hypertalk counterpart although somewhat more cumbersome. The example stack I have enclosed will compare the two methods.

Ok, enough of all this, what is my problem?

I wanted to create an array that was accessible throughout Hypercard. Fine. How? One method is to create a field somewhere in my stack that has each line representing a different time point and each item on that line representing a different array variable.

 e.g.   put 10 into line 10 of cd fld “array”

While this approach does serve its purpose well a multi-dimensional array must rely on scripting to enter the various data points with commas interspersed between items and those same commas must be stripped off as the data is retrievable- doable but messy.

My approach was to create a one dimensional array (though a multidimensional array can easily be created) as a resource, attach that resource to the stack in question and access that array with calls to an XCMD. The array is very quickly accessed, is ‘global’ in nature and can be accessed easily through Hypercard.

The first step consists in determining the size of the array. For the example stack I have created a 60 element array since in a time based environment 60 works out well. Now, the array Resource must be created. There are two options here- the resource can be created from the program (from the XCMD) or it can be created with Rmaker and pasted into the stack in question. I chose the latter approach ( to me, it was the easiest way).

At this point decide on a Resource type too.

I chose ANES for the simple reason that I am an anesthesiologist .

The Rmaker source code is as follows:

/* 1 */

 ANESTH.RSRC

 type ANES = GNRL
 ,1005
 .H
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000
 0000 00000000 0000

This, obviously initializes the values to zero and sets the values in hexadecimal format though integer or any other Rmaker legal format could have been used. If the hex format is maintained and you want to store character values then be sure and use some variation of the numtostring function to convert the character to its ASCI value and the reciprocal function to convert it back on retrieval.

After running Rmaker, the resource would exist with id 1005 and could then be pasted into the stack of your choice with Resedit. So, assuming this has all been done the next step is to write the XCMD’s.

At this point knowing exactly what you want the XCMD to do will save all sorts of frustration and reworking later (trust me). So, a small digression is in order as we set up the stack and decide what it is we want to accomplish with our array.

First, and foremost, the book that everyone is talking about, Gary Bond’s XCMD’s for Hypercard, should be your computer side companion if you want quick access to terminology, examples and good programming style while writing your commands. Next, depending on the development system you are using open the HyperX... interface files to see the exact format that the procedures are written in since they aren’t all written the same way that the examples in Gary Bond’s book assumes (some pass the paramblock ptr in all procedures).

For the sake of illustration and simplicity we will set up our stack in such a way that we will

(1) fill the array with 60 values from some source (a quick and dirty method will be to use Hypercard’s random number generator to generate 60 values) although these values could come from a field, an ask dialog, anywhere.

(2) we will access these values in two ways

(a) randomly-just to prove it works and

(b) in sequence to fill in a graph.

(3) as an added feature we will also continually update the graph described in 2b above so that new points can be added and the old ones removed.

The above stack will require at least three but probably four XCMD’s to fulfill it’s requirements. The first will fill the array RSRC with values on a random access basis. The second will retrieve values from the array and the third will create a ‘buffer array’ that will serve to save 60 data points- in the example stack this will hold the previous 60 points that the program generated so that they can be erased as the new points are plotted. This means that an additional ‘ANES’ RSRC must be created with a different id to serve as a buffer- but that is simply done with Resedit(copy/paste), and it’s get info menu item. The fourth XCMD will then access the buffer array and not the working array to retrieve previous ‘saved’ values’

Again, a slight digression is in order here, to stand back and see exactly what these items can allow us to do. In the example stack, the array is somewhat simple minded, but with a little imagination, the possibilities of such a Resource are wide. For example, the id of all cards can be kept in the array to give a ‘recording’ of movement throughout the stack, a record of any and all users of a stack can be kept, initialization values can be kept here, the buffer array can be huge so that it can be updated every time the working array is filled. Ok, maybe I’m the only one excited about all these possibilities, but hopefully some of you out there will be turned on too.

So, the first XCMD to write will be the one to access the array at any point and fill in the data at that point.

I have chosen to call it (in a fit of imagination and creativity- PUTDATA). The XCMD expects to receive two parameters- the time or array index and the value at that point. Below is the source code of the PUTDATA xcmd:

{2}
unit putdataXcmd;
interface
 uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, HyperXCMD, QDAccess;

procedure putdata(ParamPtr: XCMDPtr);

implementation
 type
   timeDarray=array[0..59] of integer;
procedure arrayrsc(ParamPtr:XCMDPtr);forward;

  procedure putdata(paramptr:xcmdptr);
 begin
   arrayrsc(paramptr);
 end;

procedure arrayrsc(ParamPtr: XCMDPtr);
  var
 MYTIMEHAND:HANDLE;
 REFNUM:INTEGER;
 TIMEARRAY:TIMEDARRAY;
 temphandle:handle;
 tempstr:str255;
 horiz,vert:longint;
{*************** get points ************}
procedure getpoints( paramptr :xcmdptr;var  horiz,vert:longint);
begin zerotopas(paramptr,paramptr^.params[1]^,tempstr);
 horiz:=strtonum(paramptr,tempstr);
zerotopas(paramptr,paramptr^.params[2]^,tempstr);
 vert:=strtonum(paramptr,tempstr);
end;
{************************************}
begin
 mytimehand :=(getresource(‘ANES’,1005));
 hlock(mytimehand);
 blockmove(mytimehand^,@timearray, sizeof(timearray));
 getpoints(paramptr,horiz,vert);
 if  horiz > 59 then horiz := 59;
 timearray[horiz] := vert;
 blockmove(@timearray,mytimehand^,sizeof(timearray));
 refnum:=curresfile;
 changedresource(mytimehand);
 writeresource(mytimehand);
 releaseresource(mytimehand);
 end;
end.

The XCMD is lacking in many things, I didn’t error check after the call to getresource so the user will have no way of knowing whether the call was successful or not. Also there is no check on the number of parameters passed to the XCMD- shear laziness I guess. But, assuming that the user is the one writing the XCMD it should be his/her decision as to whether or not to make this XCMD general enough for the public at large or specific to his/her application (the latter approach implies that the programmer using the XCMD would be versed in it’s parameter requirements and would pass the correct values).

The second XCMD is very similar to the first, and in fact the two could be combined in such a way that a parameter check would tell if two parameters were passed indicating the user wanted to set the array value of param[1] to param[2] or if one parameter were passed indicating the user desired to retrieve the array value of param[1]. Again I’ve stuck with my original version of writing these things, not because they are better, but because they serve to indicate in some small sense, the evolution that these XCMD’s have undergone and they serve to suggest a number of ways to improve upon and write better XCMD’s. The second XCMD is titled ‘GetData’ and expects one argument as a parameter- the value of the array index to be read. The result is passed back to Hypercard in the result field but could easily be placed in a global variable or field.(See Gary Bond’s book for the gory details).

{3}

unit getdataXcmd;
interface
 uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, HyperXCMD, QDAccess;
 procedure getdata(ParamPtr: XCMDPtr);
implementation
type
timeDarray=array[0..59] of integer;
procedure arrayrsc(ParamPtr: XCMDPtr);forward;
procedure getdata(paramptr:xcmdptr);
 begin
   arrayrsc(paramptr);
 end;
procedure arrayrsc(ParamPtr: XCMDPtr);
var
 MYTIMEHAND:HANDLE;
 REFNUM:INTEGER;
 TIMEARRAY:TIMEDARRAY;
 temphandle:handle;
 a:integer; 
 tempstr:str255;
 horiz:longint;
procedure getpoints(Paramptr:xcmdPtr;var num:longint);
var tempstr1:str255;
begin
  zerotopas(paramptr,paramptr^.params[1]^,tempstr1);
 horiz:=strtonum(paramptr,tempstr1);
end;

begin
 mytimehand :=(getresource(‘ANES’,1005));
 hlock(mytimehand);
  blockmove(mytimehand^,@timearray,sizeof(timearray));
 getpoints(paramptr,horiz);
 a:=timearray[horiz];
 longtostr(paramptr,a,tempstr);
 paramptr^.returnvalue:= pastozero(paramptr,tempstr);
  hunlock(mytimehand);
 releaseresource(mytimehand);
 end;
end.

Again, no error checking on getresource or number of params.

By themselves, or combined as a single XCMD, these examples will allow random access to a 60 point array from within Hypercard. The array size can easily be changed in the above examples and, in the initial resource definition, to allow any size array to be used--though I think the 32K limit also applies to resources.

The third XCMD I’ve written is used to set up a buffer so that the initial array can continue to be updated while the ‘old values’ are saved. An example of it’s use is in the example stack and has been described above. It’s call ‘DATABUFF’ and requires no parameters- assuming that the two array rsrc’s are present in the stack file and that their id’s are known. Clearly this approach does not allow much room for error but,with careful planning ,should not be much of a problem.

{4}

unit databuffXcmd;
interface
 uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, HyperXCMD, QDAccess;

procedure databuff(ParamPtr: XCMDPtr);

implementation
type
 timeDarray=array[0..59] of integer;
procedure arrayrsc(ParamPtr: XCMDPtr);forward;
procedure databuff(paramptr:xcmdptr);
 begin
   arrayrsc(paramptr);
 end;

procedure arrayrsc(ParamPtr: XCMDPtr);
var 
  mytimehand,buffarrayH:HANDLE;
  REFNUM:INTEGER;
  TIMEARRAY,buffarray:TIMEDARRAY;
  temphandle:handle;
  tempstr:str255;
  horiz,vert:longint;
  numparams :integer;

begin
mytimehand := (getresource(‘ANES”,1005));
hlock(mytimehand); BLOCKMOVE(MYTIMEHAND^,@timearray,
                                 SIZEOF(TIMEARRAY));
releaseresource(mytimehand);
buffarrayH:=(getresource(‘ANES’,1010));
hlock(buffarrayH);
blockmove(buffarrayH^,@buffarray, sizeof(buffarray));
buffarray := timearray;
blockmove(@buffarray,buffarrayH^, sizeof(buffarray));
 
REFNUM:=CURRESFILE;
changedresource(buffarrayH);
writeresource(buffarrayH);
hunlock(buffarrayH);
releaseresource(buffarrayH);
end;
end.

The fourth XCMD must be used with the databuff XCMD. It is actually a copy of the XCMD ‘getdata’ with the exception that it accesses the buffer array (with a different id number) so that saved values can be read back and acted upon accordingly.

{5}

unit getprevdataXcmd;
interface
 uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, HyperXCMD, QDAccess;
 procedure getprevdata(ParamPtr: XCMDPtr);
implementation
type
timeDarray=array[0..59] of integer;
procedure arrayrsc(ParamPtr: XCMDPtr);forward;
procedure getprevdata(paramptr:xcmdptr);
 begin
     arrayrsc(paramptr);
 end;
procedure arrayrsc(ParamPtr: XCMDPtr);
 var
 MYTIMEHAND:HANDLE;
 REFNUM:INTEGER;
 TIMEARRAY:TIMEDARRAY;
 temphandle:handle;
 tempstr:str255;
 a :integer;
 vert,b:integer;
 horiz:longint;
procedure getpoints(Paramptr:xcmdPtr;var;num:longint);
 var tempstr1:str255;
begin
 zerotopas(paramptr,paramptr^.params[1]^,tempstr1);
 horiz:=strtonum(paramptr,tempstr1);
end;
 begin
 mytimehand:=(getresource(‘ANES’,1010));
 HLOCK(MYTIMEHAND);
 blockmove(mytimehand^,@timearray,sizeof(timearray));
 getpoints(paramptr,horiz);
 a:=timearray[horiz];
 longtostr(paramptr,a,tempstr);
 paramptr^.returnvalue:=pastozero(paramptr, tempstr);
 releaseresource(mytimehand);
 end;
end.

Figure 1 is a table summarizing the syntax of the XCMD’s and the id’s of the array resources.

Well, that’s about it for the XCMD’s. There is a lot of room for improvement here and I believe a lot of room to explore. I’ve included the XCMD’s and an example stack that demonstrates their use as well as the Hypertalk method of using an array. I apologize again for my lack of programming expertise and hope that it doesn’t detract from the overall article. I would like to write another article in the near future that gives a few tricks to use the third party product “Programmer’s Extender” in XCMD’s in order to save even more time and effort in writing XCMD’s- let me know if anyone is interested in this.

The example stack contains three buttons:

The first will demonstrate the use of a Hypertalk array in the best way I know how - it’s entitled “the old way” and basically initializes 50 lines of an invisible card field to some random number .

It’s script is as follows:

--6

on mouseup
put 1 into linecount
 repeat(50)
  put random(50) into line linecount of cd fld “array
  put linecount + 1 into linecount
 end repeat
end mouseup

The user can then access any point in the array with the button “get data”- it’s sript is as follows:

--7
on mouseup

 ask “what point”
 put line it of cd fld “array” 
end mouseup

The next card will do basically the same thing except it will use the XCMD’s Putdata and Getdata.

The script of cd btn “new way” is:

--8

on mouseup
 put 1 into linecount
  repeat(50)
   putdata linecount,random(50)
   put 1 + linecount into linecount
 end repeat
end mouseup

The script of card button “get data” is :

--9

on mouseup
 ask “what point”
 put the result into pointvar
 put getdata pointvar
end mouseup

The final card will draw a graph of points - the horizontal coordinates will represent the array index and the vertical will represent the array index value.

It demonstrates the use of the databuff XCMD in that the graph will be continuously updated until the user presses the mouse button.

Well, that’s it for my first attempt at sharing the few things I’ve learned about Macintosh programming. If there are questions my address is

915 N. Bolton Ave