Version 2.0 15 Jan-90
CALL LC the LONG CALL command
There is only 1 command associated with the LONG CALL. It allows you to directly access any tool you want. You must know the specific requirements of the tool being called in order to avoid problems, such as a system CRASH!
The basic format of the call is to pass any necessary parameters, pass the function number and tool set number, and to provide variables for any returned values.
CALL LC,(parl),par2), ... ,(parN)\$TFTN\(varl),(var2), ... ,(varN)
(par)
A parameter that is to be passed to the tool. The call will pass values until it encounters the "\" delimiting character.
$TFTN
The function (TF) and the toolset number (TN) that is to be called. It is best to specify this value in hex.
(var)
The variables that will contain any returned values from the call to the toolset.
This is perhaps the most powerful call provided. However, you must know exactly what parameters the tool needs passed to it and what values it will pass back in order to use this call correctly. Otherwise unpredictable results may occur, one of which may be a system crash. (This information can be obtained from the Toolbox Reference Manuals published by Addison-Wesely).
Each parameter passed, through CALL LC is one word in length (or 2 bytes) unless otherwise specified. To specify a longword value (4 bytes) or variable, use the underline character "_" before the value or variable. In other words, a long value of zero would be denoted as "_0" and a long variable could be denoted as "_A".
Example:
Suppose you wanted to display in hex the total memory in your system on the super hi-res screen. You need to access three different tools to accomplish this. These tools are:
Memory Manager (always active) TotalMem ($TFTN = $lD02)
IntegerMath (always active) Long2Hex ($TFTN = $230B)
Quickdraw II (always active) DrawText ($TFTN = $A704)
You will also need to use a few Call Box calls to set the background and foreground colors, as well as the vertical and horizontal position for the text plot.
TotalMem
Find the total memory in your system using the Memory Manager function TotalMem ($1D02). The toolbox reference manual specifies making this call in this manner:
Stack before call
| previous contents | ----------------------- | | |-- longspace --| Longword value (CO) for result | | ----------------------- | | <- Stack PointerStack after call
| previous contents | ----------------------- | | |-- totalsize --| Total size in bytes of memory, including the special 256K. (Banks 0,1,E0 and E1) | | ----------------------- | | <- Stack Pointer
If you don't know what the stack is or what it does, don't worry about it. All you need to know is the order of the parameters which is specified by the stack diagram. Therefore, to pass the parameter through the LONG CALL and return the memory size to your BASIC program you would do the following:
10 CALL LC,_0/$1D02/_S
The "_0" is a long "result space," which makes room for the result being returned. The "_S" is a long variable. The underline is just a convention that is used to denote that you expect a long value returned from the call. The variable name is actually "S" and you would use it just as you would any other variable.
At this point, you could actually convert the variable into an Applesoft string if you wanted to print out the value in decimal rather than hex. To do this, you would use the following statements:
100 S$= STR$(S) : REM Convert the variable to a string
110 CALL TX,1 ,0,15 : REM Set black text, white bkgnd
120 CALL PN,2,40,20 : REM Set position to H=40, V=20
130 CALL TX,O,O,S$ : REM Plot the string using def font
To print out the string in hex you would ignore the previous Applesoft program lines and continue as shown below.
Long2Hex
This tool converts a Long Integer value into an Integer Math hex string. The toolbox reference manual specifies the call in this fashion:
Stack before call
| previous contents | ----------------------- | | |-- longvalue --| Unsigned long integer value | | ----------------------- | | |-- strptr --| Pointer to space for integer math string | | ----------------------- | strlength | Length of string ----------------------- | | <- Stack PointerStack after call
| previous contents | ----------------------- | | <- Stack Pointer
No value is returned from this call. The value is instead put in a buffer, assigned by you. For our purposes, since no DOS operation will take place during the plotting, we will use the User DOS Buffer as a temporary string storage area. To do this. you need to know where the buffer is located. The variable "UA" points to the memory location that holds the starting address of the buffer. We can use a long peek command to get the address into the variable "BF".
The calls look like this:
150 CALL PE,2,UA,BF : REM Get address of user buffer
160 CALL LC,_S,_BF,8\$230B\ : REM Make a Hex String
The long peek call "CALL PE" gets the two byte value (denoted by the number two following the call statement) which is stored at the memory location held by the variable UA. The two byte value that is returned from the call is placed in the variable BF.
The "CALL LC" takes the long word value of the variable "S", makes an Integer Math Hex string out of it, and places the string at the location held by the value of the variable "BF". The "_S" holds the Total Memory in your system. It is the longword variable returned from the TotalMem call above. The "_BF" holds the user buffer address which serves as our temporary string buffer. The "8" is the length of the string in characters (hex digits are two characters each).
At this point, you need to set the current pen location as well as the foreground and background colors. To do this, you would use the following statements:
210 CALL TX,1,0,15 : REM Set black text, white bkgnd.
220 CALL PN,2,40,20 : REM Set position to H=40, V=20.
 | Note: You don't need to set the foreground and background colors each time you draw with the pen. They will retain the same values that they had the last time that you used them. This goes for the pen position as well. |
DrawText
This tool function will draw specified text at the current pen location and updates the pen location.
Stack before call
| previous contents | ----------------------- | | |-- textptr --| Pointer to text to be drawn | | ----------------------- | textlength | Length of text to be drawn ----------------------- | | <- Stack PointerStack after call
| previous contents | ----------------------- | | <- Stack Pointer
This call will finish up by placing the string in the user buffer onto the Super Hi-Res Screen. The call looks like this:
300 CALL LC,_SF ,8\$A704\
You now should have the size of your systems memory on the super hi- res screen in hex (and/or decimal if you used the first example):
You can follow this format to make similar calls to any toolbox function provided you know the parameters expected by the tool. The best way to get this information is to use the Apple llgs Toolbox Reference Manuals published by Addison-Wesely and available from A.P.D.A (Apple Programers and Developers Association).