Category : BASIC Source Code
Archive   : BB.ZIP
Filename : BB.DOC

First Edition (January, 1990)
(c) 1990 Excess-3/(Gh), All rights reserved including those to reproduce this
manual and software parts thereof in any form without first obtaining written
permission from Excess-3.

This manual may contain technical errors or typographical errors. Every effort
has been made to keep all relevant information up to date and as accurate as
possible. Changes to the contents of this manual will be incorporated in
future releases.


Berlinetta is a copyright of Excess-3 and author Mohsen Al-Ghosein.
Microsoft, GW-BASIC, QuickBASIC, MS-DOS are all trademarks of Microsoft Inc.







BERLINETTA BASIC
User Guide

Version 1.0

Copyright 1990 Excess-3/(Gh). All rights reserved.

Excess-3
TEL (818) 962-0060
FAX (818) 960-4969
===============================================================================

Table Of Contents

1. Copyright notice
2. Introduction
3. Installation
4. Sample session
4.1 Command line format
4.2 Using the editor
4.3 Writing a program
5. Syntax
6. Concepts
6.1 Background processing
6.2 Low level interface
6.3 File handling
6.4 Memory management
6.5 Screen management
7. Command reference
8. Appendices
8.1 Differences between BERLINETTA & GW-Basic (tm)

==============================================================================

2. INTRODUCTION


BERLINETTA BASIC:
A Resident BASIC Interpreter

This TSR interpreter works on the push of a button allowing inexperienced
users to create sophisticated memory resident applications without having
to learn about the PC DOS & memory architecture.

Advanced programmers can create very specialized applications that can even
run in the background and control DOS tasks or display information in
windows or use menus...etc

APPLICATIONS:

1. Resident Programs: Available at the press of a button these include:
- Calculators
- File Managers
- Note Programs
- Calendars
- Monitors (Memory mons., Port Mons., Device Mons...etc)

2. Background Applications:
Programmers can design applications that run in the background
with optionally displaying information in windows or directly
on screen, or even give DOS programs key strokes.
Examples:
- On Screen Clocks
- Background Communications
- Printer Queuing
- Keyboard Macros
- Appointments & P.I.M.
- Time or Date Alarms
- As a sophisticated example, a background task can monitor
the network server for the presence of a particular file and
call a General Ledger to update an entry from AP or AR.
- Monitoring ports (cash registers or bar readers) for
special conditions. A user can set an alarm when the modem
gets dialed to for example.

3. Application Development:
'BB' is interpreted which means that it provides a very
easy and user friendly user environment for program development.
Changes to the program are immediately reflected without the need
to re-compile or re-assemble. Single Stepping and debugging are very
easy.

4. Expression Evaluation
Users can write small pieces of code that they use most frequently
(Calculate next payment on mortgage or loan) and have them available
from within their applications at the press of a button.
Dynamic evaluation of expressions means that you can also use 'BB'
as a very powerful calculator.

BERLINETTA BASIC is a Copyright of Excess-3 & Author Mohsen Al-Ghosein.
All Rights Are Reserved.

==============================================================================
3. INSTALLATION


Berlinetta comes on a 5.25" 360K diskette. The contents of the diskette are as
follows:

File Remarks
___________________________________________________________
BB.COM Berlinetta BASIC Interpreter
ALARM.BAS Alarm & time & date sample code
KEYMAC.BAS Keyboard macro utility sample code
GAME.BAS Sample TSR game
FILEMAN.BAS Small file manager TSR
SCRDMP.BAS A TSR to dump screen to a file

Before you proceed with the installation process, it is advisable to make
a working copy of Berlinetta for backup purposes. You are allowed only to make
one copy for personal use.

To install Berlinetta on your hard disk (e.g. C:),

þ Make a subdirectory called 'BB'
(C:\>MD \BB)

þ Copy all files from the Berlinetta distribution disk to the sub-
directory
(C:\>COPY A:*.* C:\BB)

You are now ready to proceed with using Berlinetta

==============================================================================
4. SAMPLE SESSION

4.1 COMMAND LINE FORMAT

To start Berlinetta, you have to change to the directory in which Berlinetta was
installed (e.g. C:\BB). The command line format is as follows:

C:\BB>BB [-] [mXXXX]

The square brackets '[]' represent optional parameters.

Since Berlinetta is a memory resident program, the program initially only
initializes the workspace, allocate all necessary memory, and then terminate and
stays resident. The actual interpreter is only active when the key combination
is pressed.

To Un-install Berlinetta from memory:

C:\BB>BB -

This removes Berlinetta from memory and restores all memory allocated.

The "m" command line parameter specifies the amount of additional Pool Memory
required for Berlinetta. The value specified in "XXXX" is an actual decimal
number between 1 and 30000.

Example:

C:\BB>BB m20000

This command loads Berlinetta, and specifies that additional memory of 20000
bytes is to be allocated from program and data areas. This feature is very
unique to .COM and .EXE DOS files since all DOS programs have to declare the
amount of memory used prior to installation. Berlinetta on the other hand, can
allocate memory only as required with the advanced Berlinetta memory manager.

For more details about memory allocation consult section 6.4 (Memory
Management).

After Berlinetta is installed a message similar to the following is displayed:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ BERLINETTA BASIC TSR Interpreter v1.0, 01/04/1990 ³
³ Hot Key: + ³
³ (C) 1990 Excess-3/(Gh). All Rights Reserved ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


==============================================================================
4.2 USING THE EDITOR


After Berlinetta becomes resident in memory, it can be activated at any time by
pressing the control keys and simultaneously. The Berlinetta
window pops up displaying a copyright message at the top left corner of the
screen.

The cursor is shown as a highlight that can be moved using the cursor keys.

þ To add a BASIC line just type the line number followed by the code corresponding
to that line.

þ To delete a line just type the line number and press enter (no code).

þ If you type a command without a preceding line number, the command is
executed.

þ While using the editor, the following keys are utilized:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³Key Function ³
³-----------------------------------------------------------------------³
³^C Clear the screen (CLS) ³
³^R Start execution of current program (RUN) ³
³^L Display a listing of the current program (LIST) ³
³ Use PGUP & PGDN to browse the source, press ³
³ to stop the listing ³
³^W Resize the window & Redraw it for programs that ³
³ change the size of the window ³
³ESC Go back to DOS or application, the background of ³
³ the Berlinetta window is restored ³
³PGUP Move cursor to top left corner of the screen ³
³PGDN Move cursor to bottom left corner of the screen ³
³DEL Delete character under the cursor ³
³HOME Go to left of current line ³
³END Go to end of current line ³
³^C Stop execution of program (if program is running) ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

þ For programs that specify ENTRY_EXEC (Execution on entry), you may have to un-
install Berlinetta, and install it again to load the code and change the source
code.

==============================================================================
4.3 WRITING A PROGRAM

In this section, a sample program that reads two numbers and prints out the
result.

þ Start Berlinetta, and pop it up using the Hot Keys
þ Type in the following program:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 CLS ³
³ 20 PRINT "Enter Your Name: " ; ³
³ 30 INPUT n$ ³
³ 40 PRINT "Hello " ; ³
³ 50 PRINT n$ ³
³ 60 PRINT "First #: " ; ³
³ 70 INPUT x ³
³ 80 PRINT "Second #: " ; ³
³ 90 INPUT y ³
³ 100 PRINT "The sum is: " ; ³
³ 110 z = x + y ³
³ 120 PRINT z ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


Note that the commands can be entered in either upper or lower case.
Also Note that variable names must have a space before and after them, eg.

100 a= a +b is incorrect syntax
100 a = a + b is correct syntax

Now type 'RUN' at the prompt, and the program will execute.

==============================================================================
5. SYNTAX

This section presents a brief overview of Berlinetta's Syntax:

þ Data Types

Berlinetta has only two data types:

Integers are two byte variables that can represent unsigned values between 0 and
65535 ( 0 and @FFFF hexadecimal). Unlike languages like 'C', and integer
variable can hold the address of another variable (a pointer), or can be a file
handle (FILE).


String variables are followed by a dollar sign "$", and hold up to 80 bytes of
string data.

Both integer and string variables can have a maximum of two letters for the
variable name with the first one having to be alpha-numeric.

þ Constants

Integer constants are specified as either a decimal number or as a hexadecimal
number. A hexadecimal constant is preceded by the '@' character.

Example:
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 a = 65535 ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

is equivalent to

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 a = @FFFF ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

String constants are represented by a literal string between quotation marks.


þ Expressions

Berlinetta has a simple syntax designed for optimizing its performance and
efficiency. The following rules apply for Berlinetta's expressions:

1. Only variable assignment can have an operator as part of the syntax

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 a = b + c ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

2. No more than one operator can be placed in a single expression

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 a = c + b / d ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
Is wrong and might produce erroneous results.


3. Command and function parameters are either constants or variables only

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 a = GETCHAR( x , 5 ) ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

þ Operators
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ + a + b ³
³ Adds two integers ³
³ ³
³ - a - b ³
³ Subtracts two integers ³
³ ³
³ * a * b ³
³ Multiplies two integers ³
³ ³
³ / a / b ³
³ Divides two integers ³
³ ³
³ & a & b ³
³ Bitwise and two integers ³
³ ³
³ | a | b ³
³ Bitwise or two integers ³

³ ³
³ << a << b ³
³ Return the value of 'a' shifted left 'b' bits ³
³ ³
³ >> a >> b ³
³ Returns the value of 'a' shifted right 'b' bits ³
³ ³
³ COMP COMP( a ) ³
³ Returns ones compliment of 'a' ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

==============================================================================
6. CONCEPTS

6.1 BACKGROUND PROCESSING

One of the unique features of Berlinetta is the capability to develop
applications that run in the background while other DOS applications continue
running in the foreground. Three commands relate directly to background
processing.


þ SET TICKS n

Sets the number of clock ticks required before next execution of a Berlinetta
program. 18 Clock ticks happen every second. In other words, setting the number
of TICKS to 36 instructs Berlinetta to execute a specified program once every
two seconds provided that the program enables background processing with
PROC_BACK.


þ PROC_BACK

This command instructs Berlinetta to go back to DOS. Execution resumes every
n clock ticks specified using the SET command. If a line number is specified in
the command, execution begins at the specified line.


þ BACK_OFF

Stops background processing mode.

The following program illustrates a simple background processing clock that
displays the time on the top right corner of the screen. For more sophisticated
background processing examples see the included programs.

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 10 SET TICKS 18 ³<--- Execute very second
³ 20 ALOCATE 72 , 0 ³<--- Set cursor to 74, 0
³ 30 PRINT TIME$() ³<--- Print current time
³ 40 PROC_BACK 20 ³<--- Go back & re-enter
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

==============================================================================
6.2 LOW LEVEL INTERFACE

Berlinetta hosts a number of low level access features. These features provide
programmers with full bitwise operations, access to the I/O ports, the entire
1MB segment of memory, and intel 8086 software interrupts (for DOS, BIOS, and
applications).

Low level operators provide bitwise operations such as bitwise and '&'.

The commands relating to low level operations are:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ POKE ³
³ PEEK ³
³ POKEB ³
³ PEEKB ³
³ INT86 ³
³ INT86X ³
³ IN ³
³ OUT ³
³ SET R_.. ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

==============================================================================
6.3 FILE & DIRECTORY HANDLING


Files are operated on using file handles. The application obtains a file handle
when it opens a file for writing or reading, or when creating a new file.

Berlinetta handles file I/O in a manner similar to C.
þ FGETC and FPUTC use a sequential mode of file operations.
þ FSEEK moves the file pointer to specific locations.
þ FREAD, and FWRITE dump record buffers to files.
þ FCREATE create a new file.
þ FOPEN opens a file for reading, writing, or both.
þ FPRINT prints formatted data to a file.
þ FEOF checks for the end of the file.
þ FDEL deletes a file.
þ FREN renames a file.
þ MKDIR makes a new directory.
þ RMDIR removes a directory.
þ CHDIR changes to a specific directory.
þ FEXIST, and DIREXIST check for presence of files or directories.

==============================================================================
6.4 MEMORY MANAGEMENT

One of Berlinetta's most unique features is the ability to dynamically allocate
and release (free) memory. Programs can request buffers to be allocated
dynamically for use with file I/O for example. The next diagram provides a view
of Berlinetta's memory architecture:

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ OTHER ³
³ ³
³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij
³ Variables ³
³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij
³ Interpreter ³
³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij
³ Memory Pool ³
³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij
³ DOS ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


When Berlinetta is loaded, only 1000 bytes of Memory Pool space. If the mXXXX
command line parameter is provided , more memory is allocated as required.

The memory pool is used by the editor to allocate storage for newly added lines.
Each line occupies 80 bytes of memory so if you have an application that is to
use 100 lines it is required that you start Berlinetta with a memory pool size
of at least 8000 bytes (BB m8000). In addition a program may request the system
for dynamic memory using the Alloc call. This provides programs with C like
dynamic buffer management.

It is highly recommended that you load Berlinetta with a large memory block
(e.g. 25000 bytes) , and develop your application. After the program is
developed, only the memory required by the program and its buffers needs to be
allocated for Berlinetta saving memory for other DOS applications.

==============================================================================
6.5 SCREEN MANAGEMENT

Berlinetta provides a full set of character screen management functions and
commands. These provide capabilities to:

þ Print Integers and strings PRINT
þ Print hexadecimal values PRINT HEX$( n )
þ Put characters directly to the screen PUTCHAR
þ Write attributes to the screen PUTATTR
þ Read characters from the screen GETCHAR
þ Read attributes from the screen GETCHAR
þ Save portions of the screen to a buffer WSAVE
þ Restore memory from buffer WLOAD
þ Control the system window parameters SET

==============================================================================
7. COMMAND REFERENCE



ALLOC FUNCTION

FORMAT
p = ALLOC(n)

Allocate n bytes, and return pointer to allocated memory. If no memory is
available, a value of zero is returned.

1.
===============================================================================
BEEP COMMAND

FORMAT
BEEP

Make a beep sound. This function uses the BIOS PRINT CHR(7) routine.

2.
===============================================================================
BOXTYPE COMMAND

FORMAT
BOXTYPE n

Change BOX type for next box to be redrawn. The available box types are:

n = 0 ------------> Single Line Box
n = 1 ------------> Double Line Box
n = 2 ------------> Block Box

Note that CLS actually draws a box around the screen, and should be treated like
a draw box command.

3.
===============================================================================
COMINIT FUNCTION

FORMAT
a = COMINIT(p,b,t,s,w)

Initialize COM port 'p' to baud rate 'b', parity 't', stop bits 's', and word
length 'w'. The actual parameter options are:

p = 0 to 3.
b = 150, 300, 600, 1200, 2400, 4800, or 9600 bits per second.
t = 0 for no parity, 1 for even parity, 3 for odd parity.
s = 0 for 1 stop bit, and 1 for 2 stop bits.
w = 0 for 7 bit word length, 1 for 8 bit word length.


Returns the COM port Line Status. See Appendix

4.
===============================================================================
COMGETC FUNCTION

FORMAT
a = COMGETC(p)

Get a character from port 'p' and returns it. To check status of COM port, use
function COMSTATUS(p).


5.
===============================================================================
COMPUTC FUNCTION

COMPUTC(p,c)

Put character 'c' to port 'p'. It returns the line status of the port.


6.
===============================================================================
COMPUTS FUNCTION

FORMAT
COMPUTS(p,s)

Copy string 's' to COM port 'p'. It returns the line status of port 'p'.

7.
===============================================================================
COMSTAT FUNCTION

FORMAT
COMSTAT(p)

Return the line status of COM port 'p'.

8.
===============================================================================
COMP FUNCTION

FORMAT
a = COMP(n)

Return one's compliment of 'n'.

9.
===============================================================================
CHDIR FUNCTION

FORMAT
a = CHDIR(str)

Change directory to string 'str'. If a zero is returned, then the function was
successful, otherwise a value of 65535 (@FFFF) is returned.


10.
===============================================================================
CHR$ FUNCTION

FORMAT
b$ = CHR$(n)

Return a string representing character ASCII 'n'.
11.
===============================================================================
CLS COMMAND

FORMAT
CLS

Clear BERLINETTA's Window, and reset the cursor position to the top left corner
of the window.

12.
===============================================================================
DATA COMMAND

FORMAT
DATA [int const] | [str const] ....

Store data items for use by the READ command.

13.
===============================================================================
DATE$ FUNCTION

FORMAT
a$ = DATE$()

Return today's date in month/day/year format. The date can be set by using the
BIOS setup routine.

14.
===============================================================================
DEBUG COMMAND

FORMAT
DEBUG on/off


Enable or disable the BERLINETTA Source Code Debugger. See 'DEBUGGING' for
details.

15.
===============================================================================
DBOX COMMAND

FORMAT
DBOX x1,y1,x2,y2

Draw a box with corners at (x1,y1) for the top left, and (x2,y2) as the bottom
right corner. The box line type is determined by the BOXTYPE command. Note that
the DBOX command uses absolute (Screen) coordinates.

16.
===============================================================================
DVAL FUNCTION

FORMAT
a = DVAL(str$)

Return the date value of a particular string. The date value is required for
comparing dates.


Example:

10 d$ = DATE$
20 dv = DVAL( d$ )
30 lm = DVAL("12/22")
40 IF dv > lm THEN 60
50 STOP
60 PRINT "Date Alarm Active....!!!!!"

17.
===============================================================================
DIREXIST FUNCTION

FORMAT
a = DIREXIST(str$)

Returns TRUE (1) is the directory exists, and FALSE (0) is it doesn't exist.

18.
===============================================================================
ERASEWINDOW COMMAND

FORMAT
ERASEWINDOW

Restore the system window's background from the background buffer. This command
is used when the actual starting position or dimensions of the system windows
are changed. To actually redraw the system window, two commands must be used:
REDRAW, and CLS respectively.

Example

10 ERASEWINDOW
20 SET WINDOWX 5
30 SET WIDTH 40
40 REDRAW
50 CLS

19.
===============================================================================
ENTRY_EXEC COMMAND

FORMAT
ENTRY_EXEC


Enable automatic execution when the Berlinetta control keys are pressed

20.
===============================================================================
FOR COMMAND

FORMAT
FOR n = start TO end

Initialize variable 'n' to 'start' and start a loop to 'end'. The loop is
executed when a NEXT n command is issued.
21.
===============================================================================
FLAGS SET / GET PARAMETER

FORMAT
SET FLAGS n
a = GET( FLAGS )

Provides access to the flags register.

22.
===============================================================================
FCOLOR SET / GET PARAMETER

FORMAT
SET FCOLOR n
a = GET( FCOLOR )

Provides access to the system window color.

Example

SET FCOLOR @47 Sets the window color to white on red

23.
===============================================================================
FCREATE FUNCTION

FORMAT
h = FCREATE(str$)

Create file 'str$'. A File handle is returned that can be used to close, open,
or write to the file. If the file cannot be created a zero value is returned as
the handle.

24.
===============================================================================
FOPEN FUNCTION

FORMAT
h = FOPEN(str$,mode$)

Open file str$ and return handle of the file to read, write, seek, or close. The
mode$ specifies what the file is opened for:

mode$ = "r" Open file for reading only
mode$ = "w" Open file for write only
mode$ = "rw" Open file for read and write

Example

fp = FOPEN("sys$cfg","rw")

25.
===============================================================================
FCLOSE FUNCTION

FORMAT
a = FCLOSE(n)

Close file with handle 'n', and flush all I/O Buffers associated with the file.
Further use of the file handle is not possible.

26.
===============================================================================
FDEL FUNCTION

FORMAT
f[ = FDEL ( str$ )

Delete file with the name 'str$'.

27.
===============================================================================
FREN COMMAND

FORMAT
FREN f1$ f2$

Rename file 'f1$' to 'f2$'

28.
===============================================================================
FPRINT COMMAND

FORMAT
FPRINT fp, string expression
FPRINT fp, integer expression

Print a string or a value to a file. If the value to be printed is an integer
then the actual value is stored not the string representing the value. To store
the value as a string use the function 'STR$' to convert the integer to a
string, and then use FPRINT.

29.
===============================================================================
FINPUT COMMAND

FORMAT
FINPUT fp, a
FINPUT fp, b$

Read an integer or string from file pointed to by handle 'fp'. Integer input
expects the byte value of the integer and not it's string representation.


30.
===============================================================================
FSEEK FUNCTION

FORMAT
a = FSEEK( fp , mode , offset )

This function sets / returns the offset within a file pointed to by file handle
'fp'. The movement of the pointer depends on 'mode':

If mode = 0 then move relative to beginning of file
If mode = 1 then move relative to the current position
If mode = 2 then move relative to the end of file

This function is very versatile since it can be used to position the file
pointer, return the current position, or determine the file size:

Examples:

þ To determine the size of a file pointed to by handle 'fp':

s = FSEEK( fp , 2 , 0 ) ; Point to end of file and return offset
b = FSEEK( fp , 0 , 0 ) ; Point back to beginning of file

þ To access record 'n' in a file pointed to by 'fp' when the record size is 80
bytes:

p = n * 80 ; Get position of record
a = FSEEK( fp , 0 , p ) ; Point to the record

þ To determine the current position:

p = FSEEK( fp , 1 , 0 )


In all of the previous cases, FSEEK always returns the new offset.

31.
===============================================================================
FEOF FUNCTION

FORMAT
a = FEOF( fp )

Returns TRUE if the file pointer in file 'fp' is at the end.

32.
===============================================================================
FEXIST FUNCTION

FORMAT
a = FEXIST( str$ )

Returns TRUE if file 'str$' exists, otherwise it returns false.


33.
===============================================================================
FFLUSH COMMAND

FORMAT
FFLUSH fp

Flushes all file buffers associated with file 'fp', and writes them to disk.
This command can be used to make sure that all changes are updated to a database
after adding a record for example.

34.
===============================================================================
FREE COMMAND

FORMAT
FREE pt

Frees memory previously allocated by ALLOC function. The memory manager attempts
to un-fragment the memory as much as possible, but that does not guarantee that
memory will be fully restored to previous state.

35.
===============================================================================
FREAD COMMAND

FORMAT
FREAD fp , pt , n

Reads 'n' bytes from file pointed to by 'fp' and store the data to buffer
pointed to by pointer 'pt'.

36.
===============================================================================
FWRITE COMMAND

FORMAT
FWRITE fp, pt , n

Write 'n' bytes to file with handle 'fp' from the buffer pointed to by pointer
'pt'.

37.
===============================================================================
FETCH COMMAND

FORMAT
FETCH pt , a$

Get string 'a$' from buffer 'pt'. This command is used to retrieve a particular
field from a database buffer.

38.
===============================================================================
FILL COMMAND

FORMAT
FILL pt , chr , n

Fill buffer pointed to by pointer 'pt' with 'n' characters 'chr'. This command
is used to initialize a record buffer to a particular state.

39.
===============================================================================
GOTO COMMAND

FORMAT
GOTO n

Branch processing to line number 'n'. If 'n' is beyond the end of the program,
execution stops. If line 'n' does not exist, a jump to the next line is
performed.

40.
===============================================================================
GOSUB COMMAND

FORMAT
GOSUB n

Jump to subroutine at line 'n', and resume processing until a 'RETURN' command
is encountered.

41.
===============================================================================
GETCHAR FUNCTION

FORMAT
a = GETCHAR( x , y )

Returns a word with the low byte as the character ASCII at screen location
(x,y), and the high byte with the attributes of that character. This function is
useful for writing screen dump, or character based games.

42.
===============================================================================
GET FUNCTION

FORMAT
a = GET( sysvar )

Return the value of one of BERLINETTA's System Variables. The system variables
can be set by using the 'SET' command. Currently supported System variables
include:

R_AX, R_BX, R_CX, R_DX, R_SI, R_DI, FLAGS ; 8086 registers
WINDOWX ; Current window x
WINODWY ; Current window y
WIDTH ; Current width
HEIGHT ; Current height
TICKS ; No ticks before
; next execute.


43.
===============================================================================
HEX$ FUNCTION

FORMAT
a$ = HEX$( n )

Return a string representing a four digit hex number of integer 'n'.

44.
===============================================================================
INPUT COMMAND

FORMAT
INPUT a$
INPUT a

Read a string / value from the keyboard and store it in variable.

45.
===============================================================================
IF COMMAND

FORMAT
IF cond THEN line1
IF cond THEN line1 ELSE line2

If condition is true jump to 'line1', if ELSE is required then goto 'line2'.


46.
===============================================================================
INT86 COMMAND

FORMAT
INT86 n

Execute 8086 software interrupt 'n'. To set values of registers use the 'SET'
command. The returned values of registers can be obtained by using the 'GET'
command. This command does not recognize segment registers R_DS, and R_ES.


48.
===============================================================================
INT86X COMMAND

FORMAT
INT86X n

Execute 8086 software interrupt 'n' with access to segment registers.

49.
===============================================================================
INKEY FUNCTION

FORMAT
a = INKEY()

Wait for a key to be pressed and return a word with the high byte representing
the Scan Code, and the low byte representing the ASCII code.

50.
===============================================================================
IN FUNCTION

FORMAT
a = IN( p )

Fetch a byte from port 'p'. This provides access to the 8086 I/O port
addressing.

51.
===============================================================================
KBSTATUS FUNCTION

FORMAT
a = KBSTATUS()

Returns the current status of the keyboard. The byte returned represents the
following:

Bit Significance
7 Insert ON
6 Caps Lock ON
5 Num Lock ON
4 Scroll Lock ON
3 Alt key is down
2 Ctrl key is down
1 Left shift is down
0 Right shift is down

52.
===============================================================================
KBHIT FUNCTION

FORMAT
a = KBHIT()

Returns a character if the keyboard has been hit, otherwise it returns a FALSE
(zero).

53.
===============================================================================
LOCATE COMMAND

FORMAT
LOCATE x , y

Set cursor position to 'x' column, and 'y' row relative to the starting window
coordinates.

54.
===============================================================================
LIST COMMAND

FORMAT
LIST
LIST n

Display a listing of the current program code. This is an editor command.

þ To stop the list press ...
þ To view the previous page press ...
þ To view the next page press ...

55.
===============================================================================
LOAD COMMAND

FORMAT
LOAD "filename"
LOAD a$

Load the program "filename" into memory.

56.
===============================================================================
LOWER FUNCTION

FORMAT
a$ = LOWER("SYSTEM")

Return a lower case representation of its parameter.

57.
===============================================================================
LRTIM FUNCTION

FORMAT
a = LTRIM(str)

Remove blanks from the left (start) of the string.

Example:

PRINT LTRIM( " this is text" )
this is text

58.
===============================================================================
LEN FUNCTION

FORMAT
a = LEN( str )

Return the length of a given string.

59.
===============================================================================
LPTSTAT FUNCTION

FORMAT
a = LPTSTAT( p )

Return the status of Centronics (Parallel) port 'p'. The status byte can be
interpreted as follows:

Bit Significance
7 Printer not busy
6 Printer acknowledge
5 Out of paper
4 Printer selected
3 I/O Error
2 unused
1 unused
0 Printer timed-out

60.
===============================================================================
LPTINIT FUNCTION

FORMAT
a = LPTINIT( n )

Initialize printer port 'n', and return the status of the port (See LPTSTAT).


61.
===============================================================================
LPTPUTC FUNCTION

FORMAT
a = LPTPUTC( p , c )

Output character 'c' to printer port 'p', and return the status of the port.

62.
===============================================================================
MIN FUNCTION

FORMAT
a = MIN( x , y )

Returns the minimum of 'x' and 'y'.
63.
===============================================================================
MAX FUNCTION

FORMAT
a = MAX( x , y )

Returns the Maximum of 'x' and 'y'.
64.
===============================================================================
MID$ FUNCTION

FORMAT
a$ = MID$( s$ , p1 , p2 )

Return the substring of string 's$' starting at position 'p1' with a length of
'p2' characters.

Example

PRINT MID$( "123456789", 3, 2)
34
65.
===============================================================================
MKDIR FUNCTION

FORMAT
a = MKDIR( path )

Make a directory pointed to by string expression 'path' if possible. It returns
a hex value of @FFFF is an error is encountered.

66.
===============================================================================
NEXT COMMAND

FORMAT
NEXT var

Increment the variable 'var', and return to the loop starting with the 'FOR'
command using the same variable.

67.
===============================================================================
NEW COMMAND

FORMAT
NEW

Erase current program from memory.

68.
===============================================================================
OUT COMMAND

FORMAT
OUT port, value

Output a byte 'value' to 'port' through the 8086 I/O port ranges.

69.
===============================================================================
PRINT COMMAND

FORMAT
PRINT string
PRINT int

Display string constant (or variable), or integer value on the screen. If the
end of the command is a semicolon ';' then the cursor position will point to the
end of the displayed value, otherwise the cursor is moved to the first column of
the next line.

70.
===============================================================================
PUTCHAR COMMAND

FORMAT
PUTCHAR a

Display character with the ASCII value of 'a' on the screen and move cursor to
next position.

71.
===============================================================================
PUTATTR COMMAND

FORMAT
PUTATTR x , y , attr , n

Put 'n' 'attr' attributes on the screen starting at column 'x', and row 'y'.

72.
===============================================================================
PROC_BACK COMMAND

FORMAT
PROC_BACK
PROC_BACK n

Restore the background screen and start processing in background mode. If a
parameter 'n' is specified then execution will start at line 'n'.

73.
===============================================================================
PUSHKEY COMMAND

FORMAT
PUSHKEY n

Push a key value into the keyboard buffer. The lower byte of the value specifies
the actual ASCII value, and the upper byte represents the keyboard scan code.

74.
===============================================================================
PUSHWORD COMMAND

FORMAT
PUSHWORD str

Push the word represented by 'str' into the keyboard buffer. This command is
useful if execution of a particular action is required at a specific time.

Example
10 a$ = TIME$()
20 a = TVAL( a$ )
30 b = TVAL( "12:00" )
40 IF a >= b then 100
50 PROC_BACK
60 STOP
100 PUSHWORD "dir/w"
110 PUSHKEY 13
120 BACK_OFF
130 STOP

75.
===============================================================================
PEEKB FUNCTION

FORMAT
a = PEEKB( addr )

Return the byte value stored at memory location 'addr'. The address offset is
always relative to BERLINETTA's data segment.

76.
===============================================================================
PEEK FUNCTION

FORMAT
a = PEEK( addr )

Return the word stored at memory location 'addr'.

77.
===============================================================================
POKEB COMMAND

FORMAT
POKEB addr , value

Store the byte represented by 'value' at memory location 'addr'

78.
===============================================================================
POKE COMMAND

FORMAT
POKE addr , value

Store the word represented by 'value' at memory location 'addr'.

79.
===============================================================================
RUN COMMAND


FORMAT
RUN

Start execution of current program in memory

80.
===============================================================================
READ COMMAND

FORMAT
READ a
READ a$

Get next data value and store it in parameter.

81.
===============================================================================
RESTORE COMMAND

FORMAT
RESTORE

Restore the data pointer to the top of the program.

82.
===============================================================================
RETURN COMMAND

FORMAT
RETURN

Return from subroutine to next line after being called by a 'GOSUB' command.

83.
===============================================================================
REDRAW COMMAND

FORMAT
REDRAW

Redraw background screen and hide editor window.

84.
===============================================================================
REM COMMAND

FORMAT
REM comment line
; comment line

This command places a comment within the file, and is not actually executed.

85.
===============================================================================
RAND FUNCTION

FORMAT
a = RAND()

Returns a random value between 0 and 65535.
86.
===============================================================================
RTRIM COMMAND

FORMAT
RTRIM b$

Remove blanks from the end of string 'b$'.

87.
===============================================================================
RMDIR FUNCTION

FORMAT
a = RMDIR( path )

Remove directory with name 'path' and returns a value of @FFFF if the function
call was not successful.

88.
===============================================================================
SYSTEM COMMAND

FORMAT
SYSTEM

Go back to DOS prompt from the editor.

89.
==============================================================================
SET COMMAND

FORMAT
SET sysvar value

Sets one of BERLINETTA's system variables to the specified value.

Example

SET R_AX @FFE1 ; Sets register AX the hexadecimal value @FFE1

90.
==============================================================================
SAVE COMMAND

FORMAT
SAVE fname

Save current file in memory as 'fname'. If fname does not have an extension, the
extension '.BAS' is automatically appended.


91.
==============================================================================
STOP COMMAND

FORMAT
STOP

Stop execution of current program.

92.
==============================================================================
STR$ FUNCTION

FORMAT
a$ = STR$( n )

Returns a string representation of integer 'n'.

93.
==============================================================================
SUBSTR FUNCTION

FORMAT
a = SUBSTR( s1$ , s2$ )

Returns the position of string 's1$' within string 's2$'. If 's1$' does not
exist in 's2$' a value of @FFFF is returned.

==============================================================================
SCMP FUNCTION

FORMAT
a = SCMP( s$ , i$ )

Compares two strings and returns TRUE if the strings are equal, and false if
they are not.

94.
==============================================================================
SJOIN FUNCTION

FORMAT
a$ = SJOIN( s1$ , s2$ )

Returns a string consisting of the concatenation of 's1$', and 's2$'.

95.
==============================================================================
STORE COMMAND

FORMAT
STORE ptr , s$

Store string variable 's$' at memory location 'ptr'.

96.
==============================================================================
TIME$ FUNCTION

FORMAT
a$ = TIME$()

Returns a string representing the current time in "hh:mm:ss" format. The hour
format is in 24 hours.

97.
==============================================================================
TVAL FUNCTION

FORMAT
a$ = TVAL( s$ )

Returns an integer representing the time in numeric format. This can be used
to compare two time strings.

98.
==============================================================================
UPPER FUNCTION

FORMAT
a$ = UPPER( b$ )

Returns a string representing the upper case of string 'b$'.

99.
==============================================================================
VAL FUNCTION

FORMAT
a = VAL( b$ )

Returns the value of string 'b$'.

100.
==============================================================================
WSAVE COMMAND

FORMAT
WSAVE x , y , w , h , ptr

Save a section of the screen starting at column 'x', row 'y' with width 'w' ,
and height 'h' to buffer pointed to by 'ptr'

101.
==============================================================================
WLOAD COMMAND

FORMAT
WLOAD x , y , ptr

Restore screen portion stored at buffer 'ptr' starting at position 'x', and 'y'.

102.
==============================================================================
LLIST COMMAND

FORMAT
LLIST
LLIST n

Dump current BASIC file to the printer.

==============================================================================
FGETC FUNCTION

FORMAT
c = FGETC( fp )

Get next character from file pointed to by file handle 'fp'.

==============================================================================
FPUTC FUNCTION

FORMAT
c = FPUTC( fp , c )

Put a character to the file and update file pointer.

==============================================================================
8. APPENDICES

8.1 APPENDIX-A BERLINETTA vs. GW-BASIC

GW-BASIC and QuickBASIC (tm) provide a standard for BASIC programming, however,
both languages are oriented towards entry level programming not developing high-
end applications or system utilities. While a number of features in GW-BASIC are
not provided in Berlinetta, Berlinetta is mainly oriented towards providing a
convenient interpreted that is available at the press of a button.

Some of the differences between Berlinetta & GW are outlined below:

Berlinetta GW-BASIC
Floating point No Yes
Full expressions No Yes
Memory Resident Yes No
Develop TSRs Yes No
Char Screen Management Yes No
Graphics No Yes
Bitwise operators Yes No
Dynamic memory Yes No
Memory requirements 23K-64K 128K
Compiler Soon QuickBASIC
C like file handling Yes No

==============================================================================