
**************************  README.TXT  **************************

This file contains important last-minute information concerning
APL*PLUS III.

Last updated: 4/8/94

******************************************************************

I.  Installation notes
	A.  If you get the message 'Bindtime error:
	''EXITWINDOWSEXEC'' not found in specified 
	library' when trying to run the Setup program, 
	make sure you are not running Windows 3.0.  APL*PLUS III 
	can only be installed and run on machines running 
	Windows 3.1 or later.

	B.  If Win32s was installed as part of your setup, a 
	backup copy of SYSTEM.INI was created in your Windows 	
	directory.  The name of the backup is SYSTEM.OLD.  The 
	only change to SYSTEM.INI was the addition of the line
	
		device=(Windows path)\SYSTEM\WIN32S\W32S.386

	C.  On some systems it may be faster to run the Setup 
	program from the machine's hard drive.  To do this, 
	create the directories \DISK1, \DISK2 and \DISK3, copy 
	the files from the appropriate distribution disks to 
	the new directories, and run \DISK1\SETUP.EXE from the 
	Windows File/Run menu.  

	D.  If you already have an older version of Win32s 
	installed, Setup may not update all the files in the 
	\WINDOWS\SYSTEM\WIN32S directory.  The internal 
	versions of the files are identical with those on the 
	APL*PLUS III distribution even though the date-stamps 
	are different. They will function normally.  

	E.  The Setup program creates the file \WINDOWS\APLW.INI. 
	The first time you leave APL*PLUS III, this file is 
	updated to include many of the defaults for the system.  
	It can be edited with any text editor. 

	F. If you are installing APL*PLUS III on a network
	drive and Windows is installed on the network drive,
	you will need to have write access to the Windows
	directory.  The Setup program creates a 
	\WINDOWS\SYSTEM\WIN32S subdirectory and copies the
	Win32s files to this directory.  If you don't have
	write access, contact your network administrator or
	helpdesk and have them first install APL*PLUS III
	using the Custom Setup option.  In the Custom
	Installation setup window, de-select the options for
	the APL*PLUS III System Files and the Workspaces and
	Component Files.  This will install only the Win32s
	and font files. 

	Further installations will detect the presence of
	Win32s, and will only copy the APL*PLUS III related
	files.

	G.  If you are using an anti-virus software package,
	it may signal an alert when the Setup program modifies
	SYSTEM.INI and WIN.INI.  You can either ignore the 
	alert or disable the virus checking during the setup. 

II. Release notes 

	A.  The Setup program will notify you if SHARE.EXE has 
	not been run on your machine.  APL*PLUS III will run if 
	SHARE has not been loaded, but file sharing will not work 
	safely.  It is possible without SHARE for two users to 
	exclusively open the same file, leading to possible 
	data loss.  We strongly recommend that SHARE be run if 
	there is the slightest chance that files will be 
	accessed by more than one application at a time.

	B.  APL*PLUS III does not support the old APL keyboard
	layout.  Use ]KB or see Appendix E in the Reference
	Manual if you are unfamiliar with the "text" keyboard
	layout used by APL*PLUS III.

	C.  After a fresh installation of APL*PLUS III, user
	commands will only work in the default directory.  Be 
	sure to follow the steps outlined on page xii of the
	User Manual to customize the user command file to 
	contain your installation path.  Otherwise, ]WED, along
	with several other user commands, will fail if you change
	directories.

	D.  For the first release of APL*PLUS III, []USERID
	has been set to be all blanks.   
	
	E.  If you were a Beta tester for APL*PLUS III and have 
	created some workspaces with one of the Beta versions, 
	you should clean the workspaces up with the newest 
	interpreter.  To do this, use the WSTOFILE and FILETOWS 
	functions from the WFCARE workspace.
	
	F.  You may want to add Tools to the APL*PLUS III menu
	for the ]WED and ]KB user commands.  To do this, choose
	Options/Tools from the APL*PLUS III menu.  For ]WED, 
	enter "&Wed Ctrl+W" in the Menu Item field and 
	"]WED" in the Command field.  For ]KB, enter
	"&Keybd Ctrl+K" in the Menu Item field and "]KB" in the
	command field.  This will allow you to show a keyboard
	template by pressing Ctrl-K.

	G.  If you are migrating a GUI application from APL*PLUS II,
	you should be aware that []WARG has changed for the 
	KeyDown and KeyUp events.  In APL*PLUS II, []WARG returned
	a 6 item vector.  In APL*PLUS III, []WARG returns a 
	7 element vector.

	H.  The functions delta-delta-VR in the UTILITY and WSCOMP
	workspaces and delta-underscore-PCVRFMT in the UCMDUTIL
	workspace and the UCMDS user command file are written
	in APL in this release in order to handle control structure
	formats correctly.  If you need the faster performance
	of an assembler routine, and don't care about the formatting
	of control structures, you can replace these functions
	with delta-delta-VR found in the ASMFNS workspace.
	
	I.  The quad-NA support file referred to in the documentation
	as VARINFO.TXT is named VARINFO.WRI.  It is in Microsoft Write
	format.

	J.  Under Win32s, there is currently a limit of 5 concurrent
	APL*PLUS III sessions.

	K.  In order to print APL characters when using a Laserjet
	printer, you must first switch from the default APLFONT screen
	font to the APLPLUS TrueType font via the Options/Fonts menu.
	This is not neccessary when printing on a dot-matrix printer.

	L.  The following are differences in the behavior of )CMD
	and []CMD from other APL*PLUS systems:

		1.  Under Win32s, )CMD and []CMD do not execute in  
	the current APL directory.  They use the startup directory
	identified in the _default.pif file located in the \WINDOWS
	directory.  

		2.  A )CMD or []CMD session runs asynchronously.
	This means that APL*PLUS III is likely to continue 
	execution of the next statement before the command started
	by )CMD or []CMD has completed.
	
		3.  Under Win32s, a CMD session will not start
	until the next time the APL*PLUS III system is idle unless
	you use []WGIVE.  For example, you should use []WGIVE
	immediately before calling []CMD in a function, or else
	[]CMD may not execute until the function terminates.

	M.  The Microsoft Visual C++ Development System (32-bit
	Edition) compiler, linker, nmake, and resource compiler tools
	can be run as DOS commands under Windows 3.1 or DOS.
	These tools can be used to build 32-bit dynamic link
	libraries without installing Windows-NT.  However, Windows-NT
	is necessary to use the Visual Workbench integrated
	development environment. 

	See the file \msvc32s\pharlap\read.me on the Visual C++
	distribution CDROM for advice on setting up the tools to
	run without the integrated environment.  Command line options
	for the tools are described in the "Build Tools User's Guide"
	section of the Visual C++ documentation.


	N.  The editor in this version of APL*PLUS III supports
	a maximum of 1024 characters in a line.

	O.  If you are migrating to APL*PLUS III from APL*PLUS PC
	version 6.0 or earlier, you should use the WSTOFILE function
	in the W2FF2W.AWS workspace included in the \TOOLS 
	subdirectory of this distribution.  The WSTOFILE function
	included with your original APL*PLUS PC system produces
	an incompatible file format.

	P.  In this release, []NA does not support the X0 datatype.
	It will probably be supported in a future release.  The
	G0 datatype, which points to live arrays in the APL
	workspace, can be used in place of the X0 datatype in some
	cases.  G0 is subject to the following restrictions:
	
		1.  The arrays they point to are subject to 
	relocation during a garbage collection.

		2.  []NA can return a G0 result, but they are hard
	to construct unless the result is a pointer to an array
	that already exists in the workspace.  The facilities
	for creating new arrays inside the workspace are very
	limited at the moment, and are intended only for use with 
	[]CALL assembler routines.  You must not return a pointer
	to something that is not in the workspace as a G0 result.

	[]WCALL supports the X0 parameter in this release, both
	as arguments and as results.  X0 parameters in APL*PLUS III
	are arrays that have been copied outside of the workspace,
	which means they are not in danger of being moved.  Any
	pointers that a nested array contains will be addresses,
	not offsets.  The subarrays therefore do not need to be
	contiguous.  Your DLL needs to build a nested array result
	where each subarray is in a block of memory that has been
	obtained by a separate malloc() call.  APL assumes this has
	been done, and will do a free() for each M-entry that is
	part of a nested result.

	When you return an X0 result from []WCALL, the interpreter
	takes charge of getting it copied into the workspace and
	then frees it and its children.  The reference count should
	be 1 for any array that you have created new in Windows
	memory.

	The array manipulation routines (avRank, etc.) that were
	provided with APL*PLUS II are not currently supplied with
	APL*PLUS III.  If you do not have these routines, they
	are available through the HelpLine.  If you recompile the
	APL*PLUS II versions, (aplval.c and aplval.h), you must use
		#pragma pack(1)
	so that the data field in a HET object will not be forced
	to an 8-byte alignment.  The storage management routines
	AplAlloc() and AplFree() should NOT be used in APL*PLUS III.
	Instead, use the regular Windows malloc() and free() calls.
	Be sure to keep the reference count right in any arrays 
	that you will return to APL.

	Q.  There is a difference in the values reported by 'where',
	'size', and 'extent' that depend upon whether an object
	is open or closed.  When an object is closed, these 
	properties return the most recently specified values.  If
	an object's size is specified by setting a 4-element
	'where' property, then when you reference 'where', it
	will return a 4-element vector.  If you reference 'size'
	or 'extent' they will return empty vectors when the object
	is closed and 2-element vectors when the object is open.

	However, if you specify the size of an object by setting
	its 'size' or 'extent', then when the object is closed
	'size and 'extent' will return 2-element vectors.  In
	this case 'where' will also return a 2-element vector.
	The trailing elements of 'where' are missing because the
	size is determined by the 'size'/'extent' properties.  When
	an object is closed, we can't know the trailing 'where'
	dimensions, because they depend on border thickness that
	can only be determined when the object is open.

	R.  For drop-down combo boxes, Windows will report different
	sizes depending on whether the control is open or closed.
	If the combo box is closed, 'where' will return the size
	you specified.  However, if the combo box is open, the
	third element of the 'where' vector will normally be 
	reported as 1.5, regardless of whether the drop-down list
	is extended or hidden.  The drop-down list of a combo box
	is actually a separate window that may extend either down
	or up.  Windows only reports the size of the edit-control/
	drop-button portion of the combo box.

	List boxes exhibit similar differences between the specified
	and reported size when the object is open.  With the
	default style, Windows rounds the list box height to display
	a whole number of lines of text.  If you reference the 'where'
	property, the third element may not be exactly what you 
	specified.  However, when the list object is closed, it
	reports the specified dimensions.

	S.  Forms can be sizable and movable by the user.  With a
	form, APLGUI remembers the last 'where', 'size', and/or
	'extent' you specified.  But if the user changes the 
	position or size of the form while it is open, APLGUI
	updates the stored 'where', 'size' and 'extent' properties
	as though you had specified new values under program control.

	With forms, it is most useful to specify the dimensions of 
	the object using a two-element 'where' property to control
	location and a two-element 'size' or 'extent' property to
	specify the internal dimensions of the client area.  Forms
	can have very thick borders (including the caption and menu
	bar line) that make the internal and external dimensions
	substantially different.  For control objects on a form, 
	you will ususally want to specify dimensions using a
	4-element 'where' property.

	The 'state' property always reports specified dimensions 
	as though you referenced the property while the object is
	closed, regardless of whether it is really open or closed.
	Similarly,  the 'def' property always reflects the
	specified dimensions of an object.  Both 'state' and 'def'
	are designed to allow you to return to the original object
	state.

	T.  The 'range' property is only useful while an object is
	open and is NOT saved in the 'def' property or reported by
	'state'.  If you specify its value to change the number of
	lines displayed by an object, that setting is not remembered
	when you close the object or save its 'def' property.
	Unfortunately, 'range' appears in the ]WED editor as a
	property you can set.  This is misleading since it is not
	saved.  Changes to the 'range' property made using ]WED
	are forgotten and therefore useless.  However, while an object
	is open you can use 'range' to change the height of an object.

	Using 'range' to change the height of an object may have
	an effect on the referenced value of the 'where', 'size' or
	'extent' properties, but it does not affect the closed
	values of these properties.  'range' is most useful for
	changing the height of drop-down combo objects.  When you
	reference the 'where' property, it will continue to report
	the visible size of the non-dropped size of the object,
	(usually about 1.5 character units.)  You should set 'range'
	during an onOpen or onDropDown handler, or when you change
	the contents of the list in a combo box.
	
