21. NS BASIC Tech Note: Global Functions                    29 April 1996.
-------------------------------------------------------------------------
Contributed by Jonathan Kipling Knight (KKnight-COS3© Kaman.com), Colorado
Springs, CO.

If you are interested in knowing everything your MessagePad can do, you 
might
be frustrated to find out that most of the global functions in NOS 2.0 are
either hidden or undocumented.  In an endeavor to fill the void that Apple 
has
created I've been compiling a list of functions I've found in explorations 
of
the internal architecture.  In NOS 1.3, Apple had visible 619 global 
functions
in GetGlobals().functions.  When I upgraded to 2.0 they were all made
invisible.  After many searches I was finally able to write an NS BASIC
program
to find all the references to the functions.  I have now compiled a list of
1252 functions. All the ROM functions (1246) occur in the magic pointer 
object
© 4098 but be very carefull in handling this object -- it is very large.  
Four
of the slots in © 4098 do not have functions as values so they need software
overrides to be used.  The following table summarizes what is documented 
from
various sources.

		Fns	Not
	Source	Doc'd	in 2.0
	------	-----	------
	B	 74	0
	A	218	0
	P	273	4
	W	397	13
	------	-----	------
	Union	399	15

Sources:
B -  NS BASIC Handbook by George Henne. 1995. NS BASIC Corp.

A - The NewtonScript Programming Language by Apple Computer, Inc. Feb 21, 
1996
(http://devworld.apple.com/dev/newton/techinfo.html)

P - Programming for the Newton by Julie McKeehan and Neil Rhodes. 1994
Academic
Press.

W - Wireless for the Newton by Julie McKeehan and Neil Rhodes. 1995 
Academic
Press.

That leaves at least 868 undocumented functions that currently exist in NOS
2.0.  The following is a list of some of the more interesting ones I've 
been
able to figure out.

AnnoyUser()
	This will do the annoying three beeps you hear
	for a meeting.  It returns nil.

BadWickedNaughtyNoot(object1,object2)
	This function prints the objects to the inspector
	but besides that I haven't been able to figure
	anything out.  Nifty name though.

BatteryStatus(integer)
	This call will return an information frame on
	the battery supplies.  If the input is 0 then
	the main source (AA cells or AC).  If the input
	is 1 then the lithium backup battery.  One
	interesting bit of info in the frame is the
	actual voltage of the source.

CircleDistance(long1,lat1,long2,lat2,x)
	This returns the km between two positions rounded
	to the nearest 10 km.  The longitude and latitude
	must be the integer form that is stored in the
	Newton.  They are described in more detail in the
	Tech Note "How to find your Longitude and Latitude."
	As far as I can tell, x is unused.

Clicker()
	This will produce a click with random tone.

DESCreatePasswordKey(string)
	A call to this will return a DES encrypted key to
	the inputed string.  The key is 8 bytes long and
	of Class deskey.

Gestalt(integer)
	If integer is 16777219,16777220,16777222,16777225
	then this returns a wealth of information on the
	system that your operating under.
	Gestalt(16777219).ScreenResolutionX provides the number
	of pixels per inch (85 for MessagePad 120) of your screen
	in the X direction (similarly for Y).

GetCardInfo()
	This will return a frame of chip information on
	the card that is inserted in your card slot.

GetCityEntry(string)
	This will return an array of entries in the
	"cities" soup whose name matches the string.

GetHeapStats(frameOrNil)
	If you input a frame or nil it will return a
	frame of information on the byte useage of
	the heap.  I don't know what the numbers mean.

GetOrientation()
	This returns 0 if in portrait mode or 3 if in
	landscape mode.

InitiatePlan9()
	Sounds scary but does no damage.  This was part 
	of the Area 51 Easter Egg that the CIA forced 
	Apple to take out.  Executing this function will
	change all the icons in the Dates application to
	little spacemen and spaceships.  It returns a
	frame with the new icons.

LatitudeToString(integer)
	This and its counterpart for Longitude return a
	string of the degrees and minutes with N/S.  The
	input is Newton's internal representation number.
	They effectively replace the routines in the Tech
	Note "How to find your Longitude and Latitude."

ReBoot()
	This will reboot your computer.

Ref(integer)
	This function will return an object that is attached
	to the integer.  Every non-immediate value has an
	integer associated with it.  Plug that integer into
	Ref and you'll get the value back.  For instance,
	Ref(699) returns the proto frame for endpoints © 174.

RefOf(object)
	This is the opposite of Ref and will return an
	integer associated with the object.

StrParse(string,delimString)
	This will return an array of strings from the first
	input parsed according to the second.

Functions too scary to experiment with:

AddProcrastinatedSend(a,b,c,d,e)
PowerOffJooHooShuuShuu(x)
PowerOffYobiKaiGi(x)
PackageEntryFromThingy(x)
SetTimeHardware(x)
ViewAutopsy(x)

These are all great functions to work with but as Apple says: "Undocumented
functions, methods and data objects are not supported nor are they 
guarenteed
to work in future Newton devices. Using them may produce undesirable 
effects
on current and future Newton devices."