flash.basic.notes Article/Article

flash.basic.notes

Command flash.basic.notes Article/Article
Applicable release versions: AP 6.0 FlashBASIC
Category Article (24)
Description Unix File Space

When running, FlashBASIC programs do not require Unix file space. However, the C compiler requires about 2 Megs of space in the current Unix directory (This is usually the root directory) and about 5-10 Megs in the /tmp directory. This amount varies depending upon the size of the module(s) being compiled, the number of module's being compiled (The default behavior only allows one compile at any one time), and the platform (The RS6000 uses quite a bit more than the other platforms). Additionally, the current Unix directory from which the "ap" application is run must have write permission. Note that these requirements are probably already met on existing systems.

Pick File Space

FlashBASIC object code is appended to the standard Pick/BASIC object. Assuming one uses the default optimization, the combined size of the two objects will be about 4-5 times that of the original (The SCO version uses slightly less). The Pick file space must be available for this extra object. The amount of object space taken by programs can be found by using the "istat" utility with the "(r" option on the "dict" of each Pick/BASIC program file.

Pick Overflow

An advantage of FlashBASIC is that it uses very little Pick overflow (only 1-2 frames for each module regardless of its size). Therefore, it is not necessary to keep a huge amount of overflow available for applications to use as workspace.

Unix Swap Space

Instead of Pick overflow, FlashBASIC uses Unix swap space making it coexist more easily with other Unix applications. Additionally, FlashBASIC loads all of its object code into swap space as well. Swap space must always be sufficient as the machine crashes brutally when it runs out. Remember that Unix swap space uses disk space that must be taken from either Pick or Unix file space or unallocated disk space. At minimum, the amount of swap space should be at least twice the amount of real memory on an RS6000 and equal to real memory on other platforms. For most systems, this minimum will be too low and a more complicated formula must be used which is as follows:

- Start with 8 megs of swap for the kernel and system processes.

- If other Unix applications are being used on the system, then add their swap space requirements. Obtain this information from the documentation that accompanied those applications or contact the manufacturer.

- Find the size of all standard Pick objects by using the "istat" command with the "(rs" options on every dict of every file containing Pick/BASIC object. The size of the object code will be the "pointer item byte count" field in the record produced by "istat". Add up this byte count for all object files. Multiply this number by four to get the estimated size of the FlashBASIC object and add this number to the total.

- Determine the amount of overflow that the current Pick application uses when completely active. This can be done by noting the amount of overflow available when the machine boots, starting all active users, and noting the amount of overflow available when all users are active. Compute this difference and multiply by the frame size to get the number of bytes. Experimentation has indicated that a small application will require about 100K of overflow work space per user, and medium to large applications require about 500K per user. Multiply this estimate by 1.2 to get a rough estimate of the swap space the FlashBASIC code will need at run time. Add this figure to the total.

- Add 3-5 megabytes for FlashBASIC compiles. If the user wishes to allow more than one concurrent FlashBASIC compilation, then he/she must add 3-5 megabytes for each user that may compile on the system.

- Add a few extra megabytes for safety.

On an RS6000 or DG, extra swap may be added while Unix is running. SCO users must completely reinstall Unix to change the swap space.

Hardware Requirements

The SCO version requires a floating point coprocessor to run. Attempts to run FlashBASIC on a SCO system without a coprocessor will succeed but performance will be slower than standard Pick/BASIC.

Pick Configuration Settings

The "pick0" file is a Unix file in the directory "/usr/lib/pick/" which determines configuration settings for the "ap" application. To edit it, use a Unix editor like "vi". See the Advanced Pick Installation Manual for more information.

A new parameter has been added to the "pick0" file called "basic". This parameter must be equal to or greater than the size of all FlashBASIC objects that are expected to be active at one time. Remember that this size is computed by multiplying current Pick/BASIC object size by 4. Failure to set this parameter sufficiently high can result in extremely poor performance and a large increase in required Unix swap space.

The "core" parameter in the "pick0" file should be reduced when running primarily FlashBASIC applications on a system. To determine a good size, leave this parameter the way it is on Pick 5.2, boot the system, bring up all users in Flash, and run the buffers with the (sl options. Note the "Referenced" number (not the percentage, but the larger number before it), multiply it times the frame size, and divide by 1024 to get a good estimate of the core size required for reasonable performance. Then shutdown the Pick machine, reset the parameter, and reboot.

Real Memory Requirements

Real memory requirements for a given system are generally a function of active Pick/BASIC object size plus work space requirements. FlashBASIC produces much larger objects (4 times the size), but uses only slightly more work space. Thus, a system which uses memory primarily for workspace should run FlashBASIC with the same amount of memory or only slightly more. Systems which use primarily workspace memory are those systems currently running a large number of users (say 50 or more) with standard Pick/BASIC. Even systems with a large amount of object code should not require more real memory, as only a small amount of this object code needs to be available in real memory during normal operations.

For example, a small application (about 250K of Pick/BASIC object) was found to run 60 users in standard Pick/BASIC with 16 Megs of real memory. When FlashBASIC was run on the same configuration, the program sped up by a factor of two despite slightly higher paging activity. Thus performance was adequate with the same amount of memory because the amount of memory the object required was insignificant compared to the workspace requirements for so many users.

A much larger application with about 60 Megabytes of Pick/BASIC was converted to FlashBASIC object with a total size of about 260 Megabytes. Although it would appear that such a large increase in object size would necessitate an increase in real memory useage as well, this was not the case. It turned out that less than 5 Megabytes of the final, FlashBASIC object code was being actively used. This was found by bringing the application to an active state using Flash, and running the "shpstat" utility which displays the amount of memory used by all active FlashBASIC applications on the system.

Note that with any sized application, FlashBASIC will respond much more favorably to extra memory than standard Pick/BASIC. For example, when the small application mentioned above was given another 16 Megs of real memory, standard Pick/BASIC remained at the same performance level, but FlashBASIC nearly doubled its speed.

In summary, the customer should experiment with his/her specific application, but experimentation has indicated that most applications will not require more memory to run FlashBASIC than they do in the current Pick/BASIC.

Terminal Definitions

FlashBASIC will run with standard Pick terminal definitions. However, a speed increase of up to 200% can be realized on screen i/o by creating optimized terminal definitions. To do this, logto dm, and type "term xxx (co" where xxx is the device name. Note that this optimization is not available for printer devices or devices which use user-defined functions.

Shipping Procedures

No FlashBASIC object code will be shipped with the standard release. All FlashBASIC objects and/or optimized terminal definitions must be created by the customer.

Compile Time

Because of the extra optimization FlashBASIC does, its compile time is significantly longer than standard Pick/BASIC (about 4-10 times as long). Memory requirements during compilation are also much higher. Because of this, it is recommended that customers compile only when the machine is inactive. This is particularly critical on the RS6000.

Using FlashBASIC without source

The FlashBASIC compiler does not require source. To compile without source, use the "w" option when compiling. See Advanced Pick Reference Manual for more information.

Known Incompatibilities

Mixing FlashBASIC and Interpreted Code:

If a mainline program is compiled with the FlashBASIC compiler, all its subroutines must also have been produced with the FlashBASIC compiler. (see "compile").

No such limitation is present on programs that "execute" other programs. However, named commons will not be shared between FlashBASIC programs and standard Pick/BASIC programs.

Access:

FlashBASIC code is only run when called from a dictionary definition on releases 6.1.0 and above.

The "chain" statement:

The Pick/BASIC "chain" may be used freely to transfer control to other programs, but variables will NOT be restored if a "run" with the "i" option is attempted later. This restriction holds if a FlashBASIC application is involved with the "chain" in any way.

"%" (Percent) calls:

FlashBASIC currently supports calling C routines, but NOT assembly routines with the percent call. (see the various functions in Pick/BASIC that begin with "%"). Additionly, FlashBASIC cannot pass arrays to % functions.

BASIC subroutines:

FlashBASIC code allows a maximum of 62 parameters on a call. This limitation does not include commons which have no limit.

The Pick/BASIC Debugger:

The FlashBASIC debugger does not support logical conditions on breaks.

The FlashBASIC debugger does not allow any arguments on the "g" command.

The FlashBASIC debugger does not actually do anything when it prints "object verifies" on the "$" command.

The FlashBASIC debugger does not allow continuing after an abort.

The practice of patching variables in the debugger after a warning message does not work.

The FlashBASIC debugger contains several enhancements. Use the "help" command in the debugger to view them.

Arithmetic:

String math is not supported by FlashBASIC.

When using the (f option FlashBASIC uses the host machine's floating point arithmetic, which provides faster and more accurate results. However, if a module is compiled without the (f option, FlashBASIC will truncate addition, subtraction, multiplication, division, and remainder (modulo) in the same manner as R83 and standard Pick/BASIC. Modules compiled with and without the (f switch may be mixed freely in an application.

The maximum size of a number in FlashBASIC is the same as in R83, and AP when not using string math. This maximum number is {+/-} 140737488355327*(10 ^ (-p)) where p is the current precision.

With the (f switch, FlashBASIC will accept and compute numbers exceeding this maximum, maintaining an accuracy of 14 significant digits.

Arrays:

Array bounds checking is absent in FlashBASIC by default to provide greater speed. If this causes problems due to lack of reliability in the application, the user may enable array bounds checking on desired modules with the compile-time "b" switch. Modules compiled with and without the (b switch may be mixed freely in an application.
Syntax
Options
Example
Purpose
Related pointer.item