Zeobase - A multivalue-compatible database & development environment

Get Started

This manual describes how to install, configure and use the Zeobase multivalue database environment. Zeobase is built to be installed on 64-bit linux platforms, and has been tested on multiple linux distributions including Debian, Ubuntu, and Red Hat Enterprise Linux.

What can I do with Zeobase?

The zeobase environment is a self-contained relational database management system and development environment all in one. The Zeobase database utilizes a three-dimensional design and organizes information into an on-disk hash table. The Zeobase development environment is based around a DATA/BASIC programming language, and an simple data storage and retrievel language.

For more information about Multivalue systems, visit https://en.wikipedia.org/wiki/MultiValue

Installation

Installing Zeobase is straightforward, and involves downloading the installer file, adjusting it's permissions, and then following the prompts from the Zeobase installer. Because of Zeobase's very small footprint, there are very few configurable parameters to worry about at installation time.

To install Zeobase, follow these steps:

First, visit to download base on this site to download the latest version of the installer. The installer file will be named zeobase-installer-[version].bin, where [version] is replaced with the current latest version of the software (e.g. 0.3). Once you have downloaded the installer, place it on your linux machine into a place available for temporary storage - such as /tmp

NOTE: Installation of zeobase must be done by the administrator, or "root" user account

              
                root@linux:/tmp# ls -l zeobase-installer-0.1.bin 
		-rw-r--r-- 1 root root 467124 Apr  9 11:29 zeobase-installer-0.1.bin

Ensure that the installer file has execute permissions

              
                root@linux:/tmp# chmod +x zeobase-installer-0.1.bin
                root@linux:/tmp# ls -l zeobase-installer-0.1.bin
                -rwxr-xr-x 1 root root 467124 Apr  9 11:29 zeobase-installer-0.1.bin

Run the self extracting installer and follow the prompts.

              
                root@linux:/tmp# ./zeobase-installer-0.1.bin

When the installer is complete, it will ask if you would like to start the Zeobase server and launch the zeobase environment (this is the equivilent if running the command "/usr/bin/zeobase -s" after installation. If you would like to start zeobase immediately, answer this question with a "Y". If not, you can choose to start the Zeobase server at a later time.

Configuration

The Zeobase configuration is all contained in a single text file, which is installed in /etc/zeobase/config. (This is a fixed location, not editable during installation). To make changes to the way that Zeobase behaves, add accounts or printers - you'll need to be able to make changes to this file. The configuration file is broken down in sections, and each section is described below:

Section: [system]

This section includes the system-wide parameters which control how zeobase behaves. There are only a few configurable paramters.

Setting	Description	Default
zdbport	zdbport is the tcp port number that your zdb server runs on. The zeobase server binds to "localhost" at this port and listens for connections from zeobase clients.	37200
user_count	The number of concurrent users that zeobase is licensed for. Must match the license key.	2
license_code	The license code, authorizing the activation of the requested user count..	""

Section: [accounts]

This section allows you to define "accounts", which are logical locations that databases are held. By default, two locations are created during installation - "DM", and "DEMO". Also included with the installation is a folder called TEMPLATE, which can be used to create your own accounts later.

Setting	Description	Default
DM	DM or Data Manager is the default account for Zeobase, and is the one that users are directed to if no other account is available in thier current working directory.	/usr/zeobase/DM
DEMO	The DEMO contains some simple example programs designed to show the usage of some of the database and development features.	/usr/zeobase/DEMO

Section: [printers]

The [printers] section allows the administrator to define system-wide print queues available to all users. Two examples are provided, and adding new printers is a simple as chosing a destination name and adding the associated command. Note that any printable content from Zeobase is redirected to these commands through standard input

Setting	Description	Default
PDF	A sample Printer destination called "PDF"	lp -d PDF
P0	A sample Printer destination called "P0", which directs input to /dev/null	lp -d /dev/null

Licensing

Zeobase is free to use for any purpose, whether private or commercial. By default Zeobase is internally limited to 1000 concurrent database sessions while we work through the bugs, however, it's usage is not restricted. Note: Zeobase should be considered "Beta", and using for a commercial purpose is solely at your own risk!

Zeobase Server

In order to use zeobase, you must install and run the zeobase server. The server process can run in two modes, "Background" and "Interactive". In background mode, the server runs without any user interaction - serving requests from zeobase users quietly in the background. To start the Zeobase server in background mode, issue the command:

              
root@linux:/tmp# zeobase -s
Initializing zeobase...

Checking Licensing status...
ERROR: License code in config is not valid for user count!
Zeobase activation code not found or invalid, launching for default user count.

Launching ZDB Server for 2 licensed users.
Starting ZDBserver on port 37200...
DM Folder is: '/usr/zeobase/DM'
Loading initialization routines...

Waiting for the system to initialize........
System is started.

Welcome to zeoBase version 0.3
You are connected on line: /dev/pts/1

:

This command will launch the zeobase server, and also make a connection to the first available line. From here, you can start to use the Zeobase environment, or you can simply type "EXIT" to close your session. The Zeobase server will continue to run in the background until is is explicitly killed.

To launch zeobase in interactive mode, issue the command zeobase -is. This command will launch the server process, but instead of detatching from the terminal - the process will continue to run in the foreground and will give a detailed accounting of all of the connections and requests being submitted by zeobase clients. This is mainly used for debugging, and should not be used during normal operation.

TCL Environment

After starting the zeobase environment, your first stop will be TCL or "The Command Line". At the TCL prompt, you will be able to do many different things, including use the builtin commands, write "paragraphs" - which are a list of commands to execute, or work with the database and programming environment. The first thing that you type at the TCL prompt is known as the VERB, and is followed by any number of parameters. The verb can be:

A Builtin Command
A Paragraph Name
A Cataloged Basic Program

Following the verb, a list of paramaters and flags may be added to modify the behavior of the verb. Each verb must be appropriately defined in the MD database file.

To enter the zeobase environment, enter the following command at your linux shell prompt:

              
root@linux:/tmp# zeobase
Welcome to zeoBase version 0.3
You are connected on line: /dev/pts/0

:

Note that, if you would like to just run a command from within zeobase and not launch the full zeobase environment you can do that with the "-c" command line argument:

              
root@linux:/tmp# zeobase -c "COUNT MD"
42 Records Counted.
root@linux:/tmp#

Paragraphs

Paragraphs are defined in the MD file as a simple list of commands to be executed at the TCL prompt. The first attribute of a TCL record must contain the two letters PA. A sample paragraph is shown below:

              
:CT MD LISTF
001  PA
002  LIST MD WITH A1 = "F" A1

When executed, this paragraph runs the TCL command LIST MD WITH A1 = "F" A1 at TCL and reports the results back to the user as if they typed the command themselves. So, instead of typing the entire command the user is just able to type LISTF instead. Any number of commands can be placed in a paragraph, and they will be executed in the order they are entered in the file.

Linux users can think of paragraphs as a simple version of a script.

Q Pointers

Q Pointers are designed to allow access to a file in an account that is not the one that you are currently in, or to create an alias for a file your current account. Q Pointers are manually created by editing the MD file with the keyword "Q" in attribute 1, the account name in attribute 2, and the file name in the linked account as attribute 3. A sample Q pointer is shown below:


:CT MD DM.MD.POINTER
001  Q
002  DM
003  MD

When a Q pointer is created, it can be accessed just like a regular database file. The example above shows a pointer called DM.MD.POINTER which is a pointer to the MD file in the DM account.

TCL Built-ins

The Zeobase environment comes with 30 built-in commands that are used for everything from editing code to manipulating database records. Each builtin command, including it's usage and output is listed below:

TCL.!:

Syntax:

![system_command]

Description:

The TCL "!" operator is used to tell Zeobase that anything following that charachter should be executed using the Linux system shell (generally bash). If the first character of your TCL command is a !, anything following will be passed to system() to be executed by the operating system

Example:

              
:!uname -a
Linux linux 3.16.0-4-amd64 #1 SMP Debian 3.16.7-ckt25-2+deb8u3 (2016-07-02) x86_64 GNU/Linux

TCL.ACCT-NAME:

Syntax:

ACCT-NAME

Description:

The Zeobase ACCT-NAME command prints the current account name, using the information listed in the zeobase configuration file. This verb does not take any command line arguments.

Example:

              
:ACCT-NAME
DM

TCL.BASIC:

Syntax:

BASIC [FILE.NAME] [PROGRAM.NAME] ([ARGS]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains your ZBASIC program. Note that programs can only be compiled in "DIR" type files, which coorespond to a operating system directory.
PROGRAM.NAME	Replace [PROGRAM.NAME] in the above usage with the Zeobase ZBASIC source code file that contains your program. Once complete, your object file will be saved in the destination folder using the same name as your program, but proceeded with an underscore (_)
ARGS	[ARGS] is an optional list of single character codes used to debug compiler features. Currently only two arguments are supported: "T" - shows a representation of the generated symbol table. "A" - shows a reprentation of the opcodes and operands in the generated intermediate (non-optomized) p-code.

Description:

The Zeobase BASIC builtin command compiles a ZBASIC program and outputs the optimized object code to an object file. Programs written in ZBASIC are automatically saved with debugging symbols and all of the information needed to later execute the program. During compilation, if the compiler detects any pre-runtime errors in the generated code, it reports those errors to the user and aborts compilation. These error reports will contain the line number that the error occured on, and a brief summary of the problem. Once all of the errors have been corrected and the compiler can successfully finish, it optimizes and saves the object code to later be executed by the Zeobase virtual machine.

Example:

              
:BASIC BP HELLO.WORLD
Starting Compilation of HELLO.WORLD
Compilation Succeeded, Object file is 417 bytes.

TCL.CATALOG:

Syntax:

CATALOG [FILE.NAME] [PROGRAM.NAME]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains your ZBASIC program. Note that programs can only be cataloged in "DIR" type files, which coorespond to a operating system directory.
PROGRAM.NAME	Replace [PROGRAM.NAME] in the above usage with the Zeobase ZBASIC object code file that contains your program.

Description:

The Zeobase CATALOG verb creates an entry in your MD file, telling the Zeobase to execute your program if the program name is typed at TCL - effectively creating a new VERB. The cataloged program must be a successfully compiled basic program which exists in [FILE.NAME]. When completed, your program can be run - and will take any passed in command line arguments that you present to it.

Example:

              
:CATALOG BP HELLO.WORLD
'HELLO.WORLD' Cataloged.

TCL.CLEAR-STACK:

Syntax:

CLEAR-STACK

Description:

The Zeobase CLEAR-STACK verb unconditionally removes all items from the command stack.

Example:

              
:CLEAR-STACK
The TCL stack is empty.
:

TCL.CLEAR-FILE:

Syntax:

CLEAR-FILE [FILE.NAME]

FILE.NAME

Replace [FILE.NAME] in the above usage with the Zeobase file name that you would like to permenantly remove all of the records from.

Description:

The Zeobase CLEAR-FILE verb unconditionally removes all data records from the file specified and leaves the file empty. This command is immediate and irreversable, so do not clear a file unless you are sure that you don't want to preserve any of the records contained in it.

Example:

              
:CLEAR-FILE TEST
Really clear this file, losing 44 records? Y/N: Y
'TEST' cleared.

TCL.CLEARSELECT:

Syntax:

CLEARSELECT
CLS

Description:

The Zeobase CLEARSELECT verb clears any actively selected list of records in your environment, and releases any associated memory back to the operating system. Note that, if a basic program calls a nested list of subroutines, each of the subroutines essentially creates a new environment and can contain it's own records list. The CLEARSELECT verb only clears and releases the current list, not all lists inside a process. There is no indication that your record list has been cleared, other than the TCL prompt changes from an arrow (>), to a colen (:).

Example:

              
>CLEARSELECT
:

TCL.CS:

Syntax:

CS

Description:

The Zeobase CS verb clears the screen and resets the cursor to the top left cleared position. Note, that this relys on your terminal to be set up correctly and operate correctly under linux. Also note that at this time, only ANSI compatible terminals are supported

Example:

              
:CS
<screen clears>

TCL.COPY:

Syntax:

COPY [FILE.NAME] ([RECORD.NAME]) (ARGS TO:([TO.FILE.NAME]) ([TO.RECORD.NAME])

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD which contains the record (or records) that you would like to copy.
RECORD.NAME	The optional RECORD.NAME parameter is used to specify the record that you would like to copy. Note that this parameter is required unless there is an active record list specifying the record names.
ARGS	The optional ARGS parameter contains any command line arguments to the COPY verb. Currently the only argument supported is "O", which tells COPY to overwrite any records that exist in the target file.
TO.FILE.NAME	The optional TO.FILE.NAME is required to copy records from one file to another. If the first character of this parameter is a left parenthesis "(", then it is interpreted to be a file name. If it does not begin with a "(", then it is interpreted as the TO.RECORD.NAME which will be created in the same file by COPY
TO.RECORD.NAME	The optional TO.RECORD.NAME is required to specify the resulting record name that copy should use when copying. This flag is required unless there is an active select list which specifies the source and destination record names.

Description:

The Zeobase COPY verb copies one or more records, either to new names in an existing file or to a different file. Depending on the syntax used, this verb will either copy the record specified or will use an active select list as a list of records to copy. Generally, the COPY program will prompt if any resulting record would be overwritten by the copy process, but the optional "O" command line argument tells copy to just overwrite the records without prompting.

Example:

Copying the single record "ACCT-NAME" from the MD file to the TEST file:

              
:COPY MD ACCT-NAME
TO: (TEST
1 records copied.

Copying the single record "ACCT-NAME" from the MD file to another record named BLARG, also in MD:

              
:COPY MD ACCT-NAME
TO: BLARG
1 records copied.

Copying ALL records from the file MD, into a new file called TEST:

              
:SELECT MD
45 records selected to list 0
>COPY MD
TO: (TEST
45 records copied.
:

TCL.COPY-LIST:

Syntax:

COPY-LIST [LIST.NAME]

LIST.NAME

Replace [LIST.NAME] in the above usage with the name of the key list that you would like to copy.

Description:

The Zeobase COPY-LIST command is used to copy an existing saved key list (existing in the SAVEDLISTS file), to another list name. Internally, zeobase executes a COPY SAVEDLISTS [ITEM.NAME] at TCL, and allows you to specify the new list name in the same way that a normal COPY would work.

Example:

              
:COPY-LIST RECLIST
TO: OTHERLIST
1 records copied.
:

TCL.COUNT:

Syntax:

COUNT [FILE.NAME]

FILE.NAME

Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which you would like to count the records in.

Description:

The Zeobase COUNT verb counts the records in a selected file. Unlike most variations of multivalue databases, this verb does not allow you to specify any other paramters or qualifications, and is only used to count all records in a file. If there is an active select list, it is ignored.

Example:

              
:COUNT MD
45 Records Counted.

TCL.CREATE-FILE:

Syntax:

CREATE-FILE [FILE.NAME] [MODULO]
- or -
CREATE-FILE DIR [FILE.NAME]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file that you would like to create
MODULO	The MODULO parameter is required, and specifies the number of 2048 byte groups that will be created in the file to contain your data.

Description:

The Zeobase CREATE-FILE command creates a new database hash or DIR type file that can be used to store information, and also creates the associated data dictionary file to describe that information. Be default, all dictionary files are created with a modulo of "3", except when creating pseudo-hash files as operating system directories.

When creating a data file, it's important to ensure that you have enough groups in your data file to hold all of the information that you expect to store. If there is not enough space in a file to hold your information, the file will automatically grow to accomidate any additional data, but performance for every query will suffer until database maintenance is performed and the file is resized. As a general rule of thumb, try to calculate the total amount of data (in bytes)that you expect to be stored in the file, then divide that amount by 2048 to figure out your modulo. Generally, this number is much smaller than you might expect. For example, the ZIPCODES file shipped with Zeobase contains all US zipcodes and their associated city names. The total data bytes is about 500k, so the optimum data file size is about 249 groups - assuming a uniform distribution of records in the file. In the case of zipcodes, the records keys are generally pretty uniformly distributed, however a modulo of 307 is required to make sure that no database extents are created and performance is optimized.

Database maintenance should be performed regularly to ensure that database files are kept within a reasonable size and that performance does not degrade. In general, it's much better to oversize a file than undersize it - as the performance implications of an undersized file are very high, and the performance implications of an oversized file are very, very low. The only real downsize to a file that is to large is the waste of disk space.

Example:

              
:CREATE-FILE TEST 101
Creating 'TEST', table size is: 101
Success.
Creating 'D_TEST', table size is: 3
Success.

DIR type files:
If using the optional keyword "DIR" as the first argument to CREATE-FILE, zeobase will create operating system directories for the file and dictionary, and then create a DIR pointer for the filename in your MD file. DIR type files have many different uses, but more importantly are used for ZBASIC source code.

Example:

              
:CREATE-FILE DIR DIR.TEST
Creating DIR.TEST. Success.
Creating D_DIR.TEST. Success.

TCL.CT:

Syntax:

CT [FILE.NAME] [ITEM.NAME]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains the records that you would like to list
ITEM.NAME	Replace [ITEM.NAME] in the above usage with the Zeobase data item that you would like to view.

Description:

The Zeobase CT verb is used to list the contents of a record inside a file. This can be used to list a program item or data item, and includes a listing of the associated line numbers (cooresponding to lines if the item is inside a DIR type file, or value marks if the record is inside a Zeobase data file.

Example:

In this example, the CT command is used to list the contents of a data record in the MD file:

              
:CT MD HELLO.WORLD
001  BX
002  BP/_HELLO.WORLD

In this example, the CT command is used to list the contents of a basic program:

              
:CT BP HELLO.WORLD
001  PRINT "HELLO WORLD FROM ZEOBASE!"
002  STOP
003

TCL.DELETE:

Syntax:

DELETE [FILE.NAME] (ITEM.NAME])

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains the records that you would like to remove
ITEM.NAME	Replace [ITEM.NAME] in the above usage with the Zeobase data item that you would like to remove. NOTE: if you have an active select list, ITEM.NAME is not required.

Description:

The Zeobase DELETE verb is used to remove an item from a data file or DIR type file. If the record exists, Zeobase will prompt you to answer Y or N to confirm that you want to remove the item.

Example:

              
:DELETE TEST ITEM.NAME
Are you sure Y/N: Y
1 Records Deleted.
:

TCL.DELETE-CATALOG:

Syntax:

DELETE-CATALOG [ITEM.NAME]

ITEM.NAME

Replace [ITEM.NAME] in the above usage with name of the cataloged basic program that you would like to remove from the MD file.

Description:

The Zeobase DELETE-CATALOG verb is used to remove the catalog entry from the MD file for a basic program. If the record exists, Zeobase will prompt you to answer Y or N to confirm that you want to remove the item.

Example:

              
:DELETE-CATALOG TEST.PROGRAM
Are you sure Y/N: Y
1 Records Deleted.
:

TCL.DELETE-FILE:

Syntax:

DELETE-FILE [FILE.NAME]

FILE.NAME

Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, that you would like to permenantly remove

Description:

The Zeobase DELETE-FILE verb is used to unconditionaly and permenantly remove a data file from the system. After confirming your request, zeobase will remove the file and all associated records, and also delete the data file definition record from your MD.

Note on DIR type files:
DIR type files in zeobase are not completed removed by the DELETE-FILE command, because this would create some risk of mistakingly deleting important operating system files. For this reason, DELETE-FILE will remove the MD entry for the DIR file, but will not actually remove the data. To remove the data, you must use operating system commands.

Example:

              
:DELETE-FILE TEST
Are you sure Y/N: Y
1 File(s) Deleted.
:

TCL.DELETE-LIST:

Syntax:

DELETE-LIST [LIST.NAME]

Description:

The DELETE-LIST command is used to remove the previously saved list LIST.NAME. If LIST.NAME is missing or the list does not exist, an error message is displayed.

Example:

              
:DELETE-LIST TESTLIST
Really remove 1 Records(s) from 'SAVEDLISTS'? Y/N: 
1 Records Deleted.
:

TCL.DISPLAY:

Syntax:

DISPLAY [MESSAGE]

Description:

The DISPLAY command is used to output a message to the screen, typical of what the bash "echo" command would do.

Example:

              
:DISPLAY Test Message
Test Message
:

TCL.ED:

Syntax:

ED [FILE.NAME] ([ITEM.NAME])

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains the record that you would like to edit.
ITEM.NAME	Replace [ITEM.NAME] in the above usage with the Zeobase data file item that you would like to edit. NOTE: If you have an active select list, ITEM.NAME is not required.

Description:

The Zeobase ED command is a built-in line editor which can be used to edit data items. The editor can be used on records in both data file and DIR format, and can be used to edit data records or source code items. If the record item specified to the editor is inside a zeobase data file, then any attribute marks in the record are covered to lines, which are numbered in the editor. If the record item specified in the editor is inside a DIR type file, then the line items shown in the editor coorspond to the line numbers inside the file. Once an active buffer is loaded into the editor (or a new one is created by specifying a non-existant record id) the following commands are available:

## - Entering a number inside the editor immediatly goes to that line and makes it the active line.
- Pressing the enter key with nothing specified increments the active line by one and displays the active line. If the user is at the end of the file, the active line rolls to 1 - the beginning of the file.
T - Entering a "T" command restarts the active line count at 1, and makes line 1 the active line in the file
F - The "F" command is ignored and exists only for compatibility with other multivalue systems
EX - The "EX" command exists the editor session and discards any changes made to the buffer.
FI - The "FI" command immediately file (saves) the current buffer and exits the editor. NOTE, this will overwrite any the record in the data file and make your changes permenant.
R - The "R" command replaces the active line, prompting the user to enter a new value for that line.
P - The "P" command lists a page of lines for the user, showing them a number of lines starting at thier currently active line.
D - The "D" command is used to delete the current line.
I - The "I" command is used to insert a new line in the item, and the editor prompts the user to enter a value for that line.

Example:

              
:ED MD NEW.RECORD
'NEW.RECORD', 0 lines, top
.I
001 This is the first item!
002 This is the second line or attribute
003 
.2
002 This is the second line or attribute
.t
huh?
.T
001 This is the first item!
.P
001 This is the first item!
002 This is the second line or attribute
eoi 2
.FI
:CT MD NEW.RECORD
001  This is the first item!
002  This is the second line or attribute

TCL.EDIT:

Syntax:

EDIT [FILE.NAME] [ITEM.NAME]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains the record that you would like to edit.
ITEM.NAME	Replace [ITEM.NAME] in the above usage with the Zeobase data file item that you would like to edit. NOTE: If you have an active select list, ITEM.NAME is not required.

Description:

The EDIT command uses the system editor of your choice to edit a database item stored in a DIR type file. This command is similar to ED or VI, except that it uses the system editor defined in the configuration file under the [system].editor variable.

Example:

In this example, your system editor is launched, and the BP item TEST is loaded into the buffer

              
:EDIT BP TEST

TCL.EDIT-LIST:

Syntax:

EDIT-LIST [LIST.NAME]

Description:

The EDIT-LIST command is used to edit the previously saved list LIST.NAME, using the system editor. If LIST.NAME is omitted or invalid, an error message is displayed.

Example:

              
:EDIT-LIST TESTLIST
'TESTLIST', 57 lines, top
.EX
:

TCL.EDIT-STACK:

Syntax:

EDIT-STACK

Description:

The Zeobase EDIT-STACK command is used to edit items in your existing TCL command stack. Internally, this is acheived by executing a SAVE-STACK, invoking the line editor to edit the record, and the a RESTORE-STACK to restore the edited record back to your active command stack. Note: In order for this command to work, the TCL.STACK file must exist and be writable. If it is not, the results are undefined.

Example:

              
:EDIT-STACK
Saved your TCL stack to record 'EDSTACK-1' in TCL.STACK
'EDSTACK-1', 3 lines, top
.P
001 LIST MD
002 COUNT MD
003 EDIT-STACK
eoi 3
.1
001 LIST MD
.R
001 LIST MD WITH A1 = "F"
.
002 COUNT MD
.
003 EDIT-STACK
.FI
TCL Stack restored from 'EDSTACK-1'
1 Records Deleted.
:.L
3: LIST MD WITH A1 = "F"
2: COUNT MD
1: EDIT-STACK
There are 3 items on the stack
:

TCL.EXIT:

Syntax:

EXIT

Description:

The Zeobase EXIT command is used to leave the Zeobase environment, clearing all internal buffers and releasing all memory back to the operating system. All unsaved changes will be rolled back unconditionally and the session will be closed. Exiting the system using this command also gracefully releases the user license back into the unused pool to be used by the next user connecting to the Zeobase server.

Note that if the zeobase is exited in some other way (i.e., the process is killed or the users session dies), the license will still be freed, however - the system must go through it's scheduled detection cycle and the operating system will have had to have detected the connection loss. There are some conditions where system may not recognize that the terminal has detached, and the process will have to be manually killed.

Example:

              
:EXIT
root@linux:/usr/zeobase/DM#

TCL.GET-LIST:

Syntax:

GET-LIST [LIST.NAME]

LIST.NAME

The LIST.NAME parameter should be replaced with the name of the list that was created using SAVE-LIST

Description:

The builtin GET-LIST command is used to retrieve a previously created list that was saved using the SAVE-LIST builtin. When a GET-LIST or SAVE-LIST is executed, Zeobase looks to the SAVEDLISTS data file in your MD to figure out what to do. Records in this file are always overwritten without prompting by SAVE-LIST, and the attributes in the file are always assumed to be a list of record keys.

Example:

              
:GET-LIST RECLIST
Selected 45 records from 'RECLIST'
>

TCL.LIST:

Syntax:

LIST | SORT (["DICT"]) [FILE.NAME] (["WITH"] [CONDITION] AND|OR) ([CONDITIONS]) (["BY"]/["BY-DNSD"]) [DICT.ITEMS]

[DICT]	The optional "DICT" keyword is used to tell Zeobase that you would like to list or sort records out of the files data dictionary instead of the datafile itself.
[FILE.NAME]	The FILE.NAME paramter is required and tells Zeobase with database file you would like to list records in
(["WITH"] [CONDITION] AND\|OR)	If the first word after file name is the keyword "WITH", the next list of parameters is expected to be a list of dict/conditional/value cuplets to limit the records listed in the search. Conditionals can include either a "=", "#", "<" or ">" symbol, followed by the value. If the special characters "[" or "]" are included in the value specification, they are extrapolated to be a wildcard character. An unlimited number of conditions can be specified for record selection, seperated by AND or OR, and grouped together using parenthesis.
[BY/BY-DSND]	The keywords BY or BY-DSND are used to specify the sort order for the returned records. The keyword should be followed by the name of a dictionary item that will be used for sorting. NOTE: Only one sort criteria may be used in a LIST, SORT or SELECT statement.
[DICT.ITEMS]	The optional DICT.ITEMS arguments can be used to specify the values that should be displayed as part of the formatted list. For example, if you are listing a file containing zipcodes, you may want to list the zipcode and include the CITY dictionary for each record.

Description:

The builtin LIST (or SORT) verbs are used to create a formatted list of records matching the specified criteria from a data file. This list can be used by the user on screen or redirected to a printer as a formatted report. If a dictionary item is specified in the command, its formatting information is applied to each value before it is displayed. If an active select list exists, it is used as the starting point for record matching.

Zeobase currently only supports "D" type dictionary items. Defined with each attribute as follows:

Attribute 1 must contain the single character "D"
Attribute 2 contains the item attribute number that the dictionary item refers to
Attribute 3 contains the format code. Any code supported by OCONV/ICONV can be used here. For example, to present the value in all lowercase, enter MCL in this attribute
Attribute 4 is the name of the field, displayed on all LIST or SORT commands
Attribute 5 contains the field length for reporting and a single character alignment flag

              
:CT DICT ZIPCODES CITY
001  D
002  1
003   
004  CITY NAME
005  20L

NOTE: If the LIST verb is called using the word SORT instead, the records are automatically presented in key order if no other sort criteria are specified.

Example:

              
:LIST ZIPCODES WITH ZIP > "0" AND ZIP < "1000" AND CITY = "B]" BY CITY CITY
Page	1	ZIPCODES
@ID................. CITY NAME...........
00616                BAJADERO 
00617                BARCELONETA
00794                BARRANQUITAS
00959                BAYAMON
00960                BAYAMON
00961                BAYAMON
00956                BAYAMON
00957                BAYAMON
00622                BOQUERON

TCL.LISTF:

Syntax:

LISTF

Description:

The LISTF comman is used to list all of the files that exist in an account. It is implemented as a paragraph, with the command: LIST MD WITH A1 = "F" A1

Example:

              
:LISTF
Page	1	MD
@ID................. A1........
MD                   F         
SAVEDLISTS           F         
:

TCL.LIST-LOCKS:

Syntax:

LIST-LOCKS

Description:

The Zeobase LIST-LOCKS command is used to list all of the currently active database locks that Zeobase is managing. The lock display is broken into the following componants:

File Locks - File locks lock the entire file, and are used when a group must be extended into overflow blocks. If this type of file operation is required, the entire file must be locked until the operation is complete. If an entire file is locked, no other write operations may be completed against that file.
Group Locks - Group locks are used when a specific group must be updated in a file, but the group does not need to be extended. When a group lock is active, no other process may update that group or recieve a item read lock
Item Locks - Item locks are used to specify that a particular data item is being updated. These locks are used primarily by the editor or basic programs that are updating a record.

Example:

              
:LIST-LOCKS
File Locks:
Lock ID    Account        File Name      Username       When
----------  --------------  --------------  --------------  --------------------
TOTAL: 0

Group Locks:
Lock ID    Account        File Name      Group #        Username       When
----------  --------------  --------------  --------------  --------------  --------------------
TOTAL: 0

Item Locks:
Lock ID    Account        File Name      Item ID        Username       When
----------  --------------  --------------  --------------  --------------  --------------------
TOTAL: 0

Note the first field, lock ID. This globally unique lock identifer can be used to release a lock if it is held by a process that isn't releasing it.

TCL.LOGTO:

Syntax:

LOGTO [ACCOUNT.NAME]

ACCOUNT.NAME

The ACCOUNT.NAME parameter should be replaced with the name of the database account that you would like to make your active database.

Description:

The LOGTO verb is used to change your current working database from one to another. If LOGTO successfully finds an entry in your configuration file, your current working direction is changed to the cooresponding folder and that database becomes active.

Example:

              
:LOGTO DM
Now in 'DM', cwd='/etc/zeobase/accounts/dm'
:

TCL.PAUSE:

Syntax:

PAUSE

Description:

The PAUSE command suspends execution until the users presses the ENTER key.

Example:

              
:PAUSE
Press return to continue...?
:

TCL.PHANTOM:

Syntax:

PHANTOM [TCL.COMMAND]

Description:

The PHANTOM command is used to launch a background process. This can be used if you want a TCL Command to run, but do not want to wait for it to finish. When executed, the output from your process is placed in a COMO file, and the name of the COMO item name is displayed on the terminal. In the example below, the tcl command "RUN BP HELLO.WORLD" is being run as a phantom, and its output is being saved in the como item "comok7D9HR". NOTE: this is the same as running a command from the linux command line and specifying the "-p" flag. In fact, this is what zeobase is doing under the covers when you use the PHANTOM keyword at TCL.

Example:

              
:PHANTOM RUN BP HELLO.WORLD
Phantom Starting, COMO file is 'COMO/comok7D9HR'
:CT COMO comok7D9HR
001  HELLO WORLD FROM ZEOBASE!
002  
:

TCL.RELEASE:

Syntax:

RELEASE [LOCK.ID]

LOCK.ID

The LOCK.ID parameter should be replaced with the globally unique lock identifier as listed in LIST-LOCKS.

Description:

The RELEASE verb unconditionally releases the File, Group or Item lock identified by LOCK.ID. Any processes that are waiting for the lock to be released will be able to continue, and the locking process with terminate with an error. Note that this is a very dangerous command and may lead to data integrity issues. Generally, the Zeobase database can handle, anticipate and resolve and locking issues that arise, so this command should not normally be used except in the case of a run-away or broken user program. Any use of this command, at any time, has the ability to corrupt a database file so use with caution.

Example:

              
:RELEASE 123
RELEASE: Lock 123 cleared.
:

TCL.RESTORE-STACK:

Syntax:

RESTORE-STACK [NAME]

NAME	The NAME parameter should be replaced with the name of the saved stack record that you would like to restore to your active command stack.

Description:

The RESTORE-STACK verb unconditionally restores a previously saved stack record in the TCL.STACK file to you active TCL command stack. This can be used when you want to keep a record of the commands executed at TCL to be re-run at a later time.

Example:

              
:RESTORE-STACK MYSTACK
TCL Stack restored from 'MYSTACK'
:

TCL.RESIZE:

Syntax:

RESIZE (["DICT"]) [FILE.NAME] [MODULO]

DICT	The optional string "DICT" may be entered before the file name in this command to indicate that the resize operation should happen on the data dictionary, and not the file.
FILE.NAME	The FILE.NAME parameter should be replaced with the Zeobase data file name that you want to resize.
MODULO	The MODULO parameter should be replaced with the new size for the file. This number can be larger, smaller, or the same as the current modulo.

Description:

Zeobase database files are implemented as an on-disk hashtable. When creating these data files, you need to specify the number of groups to start the file with - giving the file enough room to grow and change over time. Often it becomes necessary to review the file sizing for your database files and make sure that they are still as efficient as possible.

When resizing files, it is important to select your balance between a large enough file to be efficient and allow for growth, while at the same time not making the file too large and wasting disk space. Generally, you can follow the guidelines outlined the the CREATE-FILE documentation to determine your selected file size. Also, the VERIFY-FILE verb can be used to check database file integrity and show the overflow count - which could lead to poor database performance in some circumstances.

Example:

              
:RESIZE TESTFILE 1001
Resizing hash file 'TESTFILE' to '1001' groups...
- Checking File Consistancy...
- Creating Temporary file...
- Cloning 101 Groups............................................................
.........................................
- Checking new file consistancy...
Resize Complete.
:

TCL.RUN:

Syntax:

RUN [FILE.NAME] [ITEM.NAME]

FILE.NAME	The FILE.NAME parameter should be replaced with the Zeobase DIR type file containing the program that you would like to execute
ITEM.NAME	The ITEM.NAME parameter should be replaced with the Zeobase program item that you would like to execute

Description:

Once a ZBASIC program has been compiled, it is ready to be executed by the Zeobase virtual machine. Programs can either be executed directly from TCL by creating a CATALOG entry in the MD folder, or by using the RUN verb to tell zeobase to execute the code. Note that the source code file for the program you are trying to execute does not have to exist as an item in the database file, however, the source debugger will not allow you to debug the program without specifying the source file.

Example:

              
:RUN BP HELLO.WORLD
HELLO WORLD FROM ZEOBASE!
:

TCL.SAVE-LIST:

Syntax:

SAVE-LIST [LIST.NAME]

LIST.NAME

The LIST.NAME parameter should be replaced with the name of the list that you would like to create.

Description:

The Zeobase SAVE-LIST command takes the record keys from the currently active select list and saves them as a record in the SAVEDLISTS data file. In order to execute correctly, there must be an active SELECT list in the users session and the SAVEDLISTS file must exist and be defined in the MD. When completed, a regular record will be saved in SAVEDLISTS that can be edited directly or retrieved with GET-LIST.

Example:

              
>SAVE-LIST RECLIST
Saved 45 records to 'RECLIST'
:

TCL.SAVE-STACK:

Syntax:

SAVE-STACK [NAME]

NAME	The NAME parameter should be replaced with the name you would like to use to save the stack.

Description:

The Zeobase SAVE-STACK command saves the current TCL command stack to the name item in a local file called TCL.STACK. Once the stack is saved, it can be edited using the normal Zeobase tools and then optionally restored using the RESTORE-STACK command. NOTE: The TCL.STACK file must exist and be writable, otherwise this command returns an error message

Example:

              
:SAVE-STACK MYSTACK
Saved your TCL stack to record 'MYSTACK' in TCL.STACK
:

TCL.SELECT:

Syntax:

SELECT | SSELECT (["DICT"]) [FILE.NAME] (["WITH"] [CONDITION] AND|OR) ([CONDITIONS]) (["BY"]/["BY-DNSD"] [DICT.NAME])

[DICT]	The optional "DICT" keyword is used to tell Zeobase that you would like to select records out of the files data dictionary instead of the datafile itself.
[FILE.NAME]	The FILE.NAME paramter is required and tells Zeobase with database file you would like to select records from.
(["WITH"] [CONDITION] AND\|OR)	If the first word after file name is the keyword "WITH", the next list of parameters is expected to be a list of dict/conditional/value cuplets to limit the records listed in the search. Conditionals can include either a "=", "#", "<" or ">" symbol, followed by the value. If the special characters "[" or "]" are included in the value specification, they are extrapolated to be a wildcard character. An unlimited number of conditions can be specified for record selection, seperated by AND or OR, and grouped together using parenthesis.
[BY/BY-DSND]	The keywords BY or BY-DSND are used to specify the sort order for the returned records. The keyword should be followed by the name of a dictionary item name that will be used for sorting. NOTE: Only one sort criteria may be used in a SELECT or SSELECT statement.

Description:

The builtin SELECT or SSELECT commands are used to gather a list of records from the database and to put that list into your active select list.

Zeobase currently only supports "D" type dictionary items. Defined with each attribute as follows:

Attribute 1 must contain the single character "D"
Attribute 2 contains the item attribute number that the dictionary item refers to
Attribute 3 contains the format code. Any code supported by OCONV/ICONV can be used here. For example, to present the value in all lowercase, enter MCL in this attribute
Attribute 4 is the name of the field, displayed on all LIST or SORT commands
Attribute 5 contains the field length for reporting and a single character alignment flag

              
:CT DICT ZIPCODES CITY
001  D
002  1
003
004  CITY NAME
005  20L

NOTE: If the SELECT verb is called using the word SSELECT instead, the records are automatically selected in key order if no other sort criteria are specified.

Example:

              
:SELECT ZIPCODES WITH ZIP > "0" AND ZIP < "1000" AND CITY = "B]" BY CITY
9 records selected to list 0
>

TCL.SET-EXIT-VALUE:

Syntax:

SET-EXIT-VALUE [NUM]

[NUM]

The [NUM] parameter should be replaced with the number you would like returned to the operating system on a successful termination of the zeobase process.

Description:

The SET-EXIT-VALUE command is used to adjust the exit value of the zeobase process in order to pass status or other information to the executing process.

Example:

              
linux$ zeobase
Welcome to zeoBase version 0.9.1
You are connected on line: /dev/pts/0

:SET-EXIT-VALUE 33
:EXIT
linux$ echo $?
33
linux$

TCL.SLEEP:

Syntax:

SLEEP [SECONDS]

Description:

The SLEEP command is used to pause execution for the specified number of seconds. If the SECONDS parameter is omitted or not a valid integer, SLEEP defaults to 1 second.

Example:

This example pauses execution for 10 seconds:

              
:SLEEP 10
:

TCL.SP-ASSIGN:

Syntax:

SP-ASSIGN ([PRINTER])

[PRINTER]

The optional parameter [PRINTER] is used to specify which printer should become active.

Description:

The SP-ASSIGN verb is used to display and/or change the currently active print queue. Typing SP-ASSIGN without any paramters will show the list of print queues configured and available in Zeobase. The printers are defined in the zeobase configuration file and available to all users. If a parameter is supplied, it is expected to be the name of an print queue - and that queue will become the active printer.

Example:

Displaying a list of available print queues:

              
:SP-ASSIGN
System-defined print queues:
----------------------------
PDF			= "lp -d PDF"
P0			= "lp -d /dev/null"

There is no active print queue.

:

Assigning the active print queue.

              
:SP-ASSIGN P0
Print Queue Assigned to "P0"
:

TCL.UPDATE-MD:

Syntax:

UPDATE-MD

Description:

The UPDATE-MD Command is used to update the MD file to the current version and to ensure that all of the required commands are available to users in that account. This command should only need to be run at times when zeobase is updated or installed.

Example:

              
:UPDATE-MD
EXIT CLS LOGTO TERM ED CT DELETE COUNT CREATE-FILE DELETE-FILE CLEAR-FILE COPY GET-LIST LIST SELECT CLEARSELECT CLEAR-SELECT RESIZE SAVE-LIST SORT SP-ASSIGN BASIC VERIFY-FILE SELECT SSELECT RUN CATALOG VI LIST-LOCKS RELEASE ACCT-NAME WHO UPDATE-MD EDIT 


"MD" Updated to 0.8.4.

TCL.VERIFY-FILE:

Syntax:

VERIFY-FILE [FILE.NAME]

FILE.NAME

The FILE.NAME parameter should be replaced with the Zeobase database file name that you want to verify

Description:

The VERIFY-FILE command is used to check the integrity of a database file and also report to the user the file size, modulo and data blocks. The information can be used later by the user to determine if the file needs to be resized. VERIFY-FILE presents quite a bit of information to the user:

Table Size: The table size reported by VERIFY-FILE is the current size of the file, either set when it was originally created or from a resize
Extents: The extents size reported by VERIFY-FILE lists the total number of group extentions that have been added to the file. Database tuning is beyond the scope of this manual, but as a general rule - if your records are generally much smaller than the data block size (2048 bytes), then extents are a bad thing and you want as few as possible. If the records in your file are larger than the block size, it's ok to have some extents - but each extended file group requires another physical read for each extent - reducing performance.
Data Bytes: This field reports the total size of all data in the file, and number can get pretty large. You can use this information and the file size to calculate how much room is wasted by inefficiency in the file size.
Hash Size: If the hash size matches the table size as reported above, the word "match" will be displayed.
Extent Size: If the number of extents reported above matches the number found in the file, the word "match" will be displayed here.

Example:

              
:VERIFY-FILE ZIPCODES
Checking header...
	Table Size: 307
	Extents: 0
Checking blocks...
	Data Bytes: 510794
	Hash Size:    match
	Extent Size:  match
:

TCL.VI:

Syntax:

VI [FILE.NAME] [ITEM.NAME]

FILE.NAME	The FILE.NAME parameter should be replaced with the name of the Zeobase database file containing the item that you would like to edit.
ITEM.NAME	The ITEM.NAME parameter should be replaced with the name of the item that you want to edit.

Description:

VI is used as an interface to your system's "vi" editor, allowing it to be used to edit programs and files. The VI verb only works with records contained in DIR type files.

Example:

              
:VI BP TEST
>The editor is launched<

-1	Clears the screen, and home cursor to the 0,0 position
-2	Home cursor to the 0,0 position
-3	Erase the screen from the current position to the end of the screen.
-4	Erase the screen from the current position to the end of the current line.
-5	Enable blinking text mode.
-6	Disable blinking text mode.
-7	Enable Conceal Characters mode.
-8	Disable Conceal Characters mode.
-9	Erase a single character and go back one space.
-10	Move the cursor up one line.
-11	Enable "Faint" characters mode.
-12	Disable "Faint" characters mode.
-13	Enable Reverse characters mode.
-14	Disable Reverse characters mode.
-15	Enable underline characters mode.
-16	Disable underline characters mode.
-17	Move the cursor down one line.
-18	Move the cursor to the right one column.
-19 to -80	Reserved / System Specific.
-81	Enable Bold characters mode.
-82	Disable Bold characters mode.
-90	Right lower box drawing character.
-91	Right upper box drawing character.
-92	Left upper box drawing character.
-93	Left lower box drawing character.
-94	Cross (+) box drawing character.
-95	Horizontal line box drawing character.
-96	Right vertical "T" box drawing character.
-97	Left vertical "T" box drawing character.
-98	Upside down "T" box drawing character.
-99	Rightside up "T" box drawing character.
-100	Vertical line box drawing character.

Example:

              
CRT @(-1) ;* Clear the screen
CRT @(10,10) ;* Position the cursor at the 10,10 position.

ZBASIC.Operator.[ / ZBASIC.Operator.]

Syntax:

expression = string[1,10]
expression = string[10]

Description:

The ZBASIC operators [ and ] are used to extract a substring from a larger string variable. The first number inside brackets indicates the starting position, and the second number - following a comma is used to indicate the length of string. So, [1,10] would create a substring of the first 10 characters of a variable.

Example:

              
NAME="JOHNATHON MCDOGAL"
NICKNAME = NAME[1,4]
PRINT NAME ;* Will print the word "JOHN"

BASIC Keywords

Zeobase comes with a powerful programming language called ZBASIC. This programming environment allows you to create complex programs to interact with users and manipulate data - ultimating creating very comprenensive software solutions. To use ZBASIC, you must develop an understanding of the many different keywords and data structures used. Below, we have listed all of the available keywords and examples of their use.

ZBASIC.$INCLUDE

Syntax:

$INCLUDE [FILE.NAME] [ITEM.NAME]

FILE.NAME	Replace [FILE.NAME] in the above usage with the Zeobase data file definition name, listed in your MD, which contains the ZBASIC source code that you would like to insert into this part of your program
ITEM.NAME	Replace [ITEM.NAME] in the above usage with the Zeobase ZBASIC source code file that contains your program.

Description:

The ZBASIC $INCLUDE keyword inserts the source code referenced in the statement into the program it is currently compiling. Source code is compied verbatum into the program, and it's instructions will become part of the final p-code. Note that when included code is executed inside the debugger, the entire included portion will appear to the debugger as a single line.

Example:

              
$INCLUDE BPD FI.SCREEN.VARS

ZBASIC.ABORT

Syntax:

ABORT ([OPTIONAL.MSG])
STOP ([OPTIONAL.MSG])

[OPTIONAL.MSG]

If specified, this string will be printed before aborting execution of the ZBASIC virtual machine.

Description:

The ZBASIC ABORT Keyword (or, it's synonym STOP) is used to unconditionally exit a ZBASIC program and return control back to TCL. This command will abort the program, free any associated memory back to the operating system, and optionally print a message before closing. Unlike other multivalue implementations, there is no provision to specify an error code number - only a message to the user.

Example:

              
OPEN "","MD" TO F.MD ELSE STOP "I CAN'T OPEN THE MD!"

NAME = "JOE"
IF (NAME # "JOE") THEN
  ABORT "The Space-time continuum is broken!"
END
*
STOP

ZBASIC.ABS

Syntax:

ABS([expression])

[OPTIONAL.MSG]

If specified, this string will be printed before aborting execution of the ZBASIC virtual machine.

Description:

The ZBASIC ABS() function will return the positive numeric value (absolute value) of [expression]. [expression] can be any numeric value, or any function or expression which returns a numeric value.

Example:

              
NEW.NUM = ABS(-234)
PRINT NEW.NUM ;* Prints "234"

ZBASIC.CALL

Syntax:

CALL [SUB.NAME]([ARG1], [ARG...])

[SUB.NAME]	Replace SUB.NAME in the above usage with the cataloged basic program that you would like to transfer execution to.
[ARG...]	[ARG...] can contain any number of comma seperated simple expressions (variables, numbers, or strings) that will be passed to the subroutine.

Description:

The ZBASIC CALL function transfers execution to the subroutine listed, and pushs the arguments passed onto the calling programs call stack. The called program must terminate with a RETURN statement, returning execution back to the calling program. If the subroutine has made any changes to the arguments passed to it, they will replace the values in the caller.

Arguments must be seperated by commas, and the entire argument list must be enclosed by parentheses. Unlike other multivalue implementations, parenthesis must always be included after the subroutine name, even if no arguments are being passed.

Any subroutine called using a CALL statement must begin with the keyword SUBROUTINE. This line defines the program as a subroutine that must be called from another program and cannot be called directly. The argument count listed in the subroutine definition must match the argument count when the subroutine is called, otherwise a runtime error will occur.

Example:

In the example below, our hypothetical program calls the subroutine GET.FIRST.NAME, passing the argument "ARG". The variable ARG contains a persons name, and conceviably the subroutine would be implemented to get only the first name from a string.

              
ARG = "Joe Blow"
CALL GET.FIRST.NAME(ARG)

ZBASIC.CHAR

Syntax:

CHAR([expression])

Description:

The ZBASIC CHAR() function takes a numeric input in [expression] and returns the ASCII character equivilent to that number. Some characters are printable, while others are not. For example, the ASCII character 10 represents a newline (or enter), so PRINT CHAR(10) would output a newline character. Other characters include control codes, line feeds, etc. For more information, look up ASCII Chart in your favorite search engine.

Example:

              
MY.CODE = CHAR(7)
PRINT MY.CODE ;* outputs ASCII character 7, the Bell.

ZBASIC.CLEARSELECT

Syntax:

CLEARSELECT

Description:

The ZBASIC CLEARSELECT statement clears any active select list in the process and releases it's memory back to the operating system. This statement takes no arguments, and only clears the processes active select list. SO, if for example you execute the CLEARSELECT statement inside a subroutine, it will only clear the active select list created by that subroutine, and not the list belonging to the caller. In ZBASIC, each subroutine pushes an execution level, creating a new workspace for it to use. So, this statement is only effective on the current workspace.

Example:

              
EXECUTE "SELECT MD"
CLEARSELECT	;* No select list is now acctive.

ZBASIC.CLOSE

Syntax:

CLOSE [FILE.VARIABLE]

[FILE.VARIABLE]

Replace FILE.VARIABLE in the above usage with the name of the file variable representing the open file you want to close

Description:

The ZBASIC CLOSE statement closes the open file represented by FILE.VARIABLE, and makes any future READS or WRITEs from that variable fail. The file variable must have previously been opened using the OPEN keyword. If the file variable is invalid, this statement has no effect.

This statement does not return a value, and always succeeds.

Note: Zeobase automatically closes file variables and operating system files as needed, so this statement often has no effect on the actual file itself, and releases very little in the way of resources back to the operating system. This function is included mostly for compatibility reasons.

Example:

              
OPEN "","MD" TO MD.FILE THEN
  CLOSE MD.FILE
END

ZBASIC.CONTINUE

Syntax:

CONTINUE

Description:

The ZBASIC CONTINUE statement unconditionally jumps to the start of the innermost LOOP or FOR/NEXT and resumes execution. Any instructions that are enclosed in the loop construct but following the CONTINUE statement are skipped. Note that because this statement is unconditional it can cause perpetual loops.

Example:

              
X=1
LOOP
  X = X + 1
  IF (X = 10) THEN  
   PRINT "X IS 10"
   EXIT
  END ELSE
   CONTINUE ;* Skip printing.
  END
  PRINT "I did a loop!"
REPEAT

ZBASIC.CONVERT

Syntax:

CONVERT {expression1} TO {expression2} IN [TO.VAR]

[TO.VAR]

Replace TO.VAR in the above example with the variable you would like to modify

Description:

The ZBASIC CONVERT statement converts characters listed in expression1 to the coorresponding characters in expresion two in the target variable IN.VAR. Each expression can contain strings with one or more characters to be converted.

Example:

              
STRING = "THE SKY IS BLUE"
CONVERT "SK" TO "FL" IN STRING
PRINT STRING ;* Prints "THE FLY IS BLUE"

ZBASIC.COUNT

Syntax:

COUNT({expression1},{expression2})

Description:

The ZBASIC COUNT function searches expression1 for the character represented in expression2, returning the positive integer number of occourances of the character. If no occourances are found, zero is returned. If the character in expression2 is being used as a delimited, note that the returned value from COUNT only returns the number of occurances of the delimeter itself, not the delimited values. For that, see DCOUNT.

Example:

              
STRING = "THE RAIN IN SPAIN FALLS MAINLY ON THE PLAIN"
ACOUNT = COUNT(STRING, "A")
PRINT ACOUNT ;* Prints the number "5"

ZBASIC.CRT

Syntax:

CRT {expression}
PRINT {expression}

Description:

The ZBASIC CRT statement, and it's synonym PRINT are used to output characters to the terminal, file, or captured variable. When envoked, this statement expands and formats the expression as required by the syntax, then outputs the characters to the selected output device (which is typically the screen, but could be a printer or variable), and then prints a trailing newline to advance the cursor. Optionally, the printed string can be terminated with the concatenation operator ":", which instructs CRT to omit the trailing newline.

CRT/PRINT can be used in conjunction with the screen control and positioning @ functions to position the cursor or control the terminal.

To redirect output to a printer, see the PRINTER ON/OFF statement.

Example:

In this example, a simple print statement is used to output a string.

              
STRING = "THE RAIN IN SPAIN FALLS MAINLY ON THE PLAIN"
CRT STRING ;* String is printed to the screen.

In a more complicated example, screen control functions are used to change the position of the printer characters.

              
STRING = "THE RAIN IN SPAIN FALLS MAINLY ON THE PLAIN"
CRT @(-1) ;* Clear the screen
CRT @(10,10) ;* Print the string at this X/Y Position on the screen.

ZBASIC.DATE

Syntax:

DATE()

Description:

The ZBASIC DATE function returns the internal representation of todays date. This returned number is the count of days elapsed since December 31st, 1967.

Example:

              
TODAY = DATE() ;* Today now contains todays date.

ZBASIC.DCOUNT

Syntax:

DCOUNT({expression1},{expression2})

Description:

The ZBASIC DCOUNT function searches expression1 for the character represented in expression2, returning the positive integer number of delimited values in expression1. This function differs from COUNT in that the delimited values are counted, not the delimiter.

Example:

              
STRING = "A" : @AM : "B" : @AM : "C"
VALS = DCOUNT( STRING, @AM )
PRINT VALS ;* Will print the number 3

ZBASIC.DEBUG

Syntax:

DEBUG

Description:

ZBASIC is shipped with a comprehensive interactive debugger that can be used to search your basic programs for errors. When involed, the ZBASIC debugger halts execution of your program, displays the current line and waits for user input. Pressing the configured interrupt key (CRTL-C) will also invoke the debugger unless disabled by an administrator.

The following commands are available in the debugger:

S [FILE] [ITEM]	At invocation, the ZBASIC debugger trys to load the source code for your running program (using the currently available source code in the file and item configured at compile time. If your would like to load source from a different file/item, use the S command - followed by the MD data file and item name that you would like to load.
X	Exit to TCL. The X Command unconditionally ends program execution and returns control to TCL.
$	The "$" command shows the current program source file name and line number.
L	The "L" command lists the previous 5, current, and next 5 lines to be executed by the virtual machine.
D	Show breakpoint. If a breakline has been configured using the "B" command, it is displayed.
B [LINENO]	Set breakpoint. The "B" Command sets the breakline to LINENO. Execution is not resumed until explicitly instructed using the "E" or "G" commands.
/[VARIABLE]	Display / Edit Variable. The "/" command, followed by a program variable name displays the contents of that variable and prompts the user to change it's contents. Note that this command looks up variable names in the compile-time symbol table, so addressing changes made durring runtime may not be accurately reflected. Also, arrays can only be shown and edited in their entire string representation, not using subscripts.
E[NUM]	Execute Lines. The "E" command followed by a number executes that many lines of the source program, resuming the debugger when that many lines have completed or a breakpoint is hit.
G	Resume program execution. After entering the "G" command, the program is resumed until it is completed or a breakpoint is hit.
T	Show symbol table. This command displayes the compile time symbol table, including initial values for each symbol. Note that this does not reflect variable changes or additions during runtime. For that, it is necessary to use the "/" command"
H	Show Help. This command displays a help screen.

Example:

              
:RUN BP HELLO.WORLD
Debugger Called for 'BP/HELLO.WORLD', at line 1
(1): DEBUG
!E1
HELLO WORLD FROM ZEOBASE!
Debugger Called for 'BP/HELLO.WORLD', at line 2
(2): PRINT "HELLO WORLD FROM ZEOBASE!"
!E1
HELLO WORLD FROM ZEOBASE!
(3): STOP
!E1
:

ZBASIC.EQU

Syntax:

EQU {variable} TO {expression}
{variable} = {expression}

Description:

The ZBASIC EQU operator is a synonym to the assignment operator (=). Unlike other multivalue implementations, this keyword is not implemented as a compile-time equivelent, but a runtime assignment. Future implementations may change this implementation to act at compile time.

Example:

              
EQU NAME TO "Jim"
NAME = "Jim"

ZBASIC.EXECUTE

Syntax:

EXECUTE {expression}
EXECUTE {expression} CAPTURING {variable}

Description:

The ZBASIC EXECUTE statement is used to execute commands at TCL, such as SELECT statements. Whatever is put in place of {expression} is executed as if it was typed by the user at the TCL prompt. The optional CAPTURING keyword, followed by a variable expression allows adjusts the behavior of EXECUTE to redirect the output of whatever is executed into a variable.

The expression can be as complex as required, and can be a literal string or variable, or output from another function.

Example:

In this example, the EXECUTE keyword contains the optional CAPTURING keyword - stopping the output of the SELECT from being show in the terminal.

              
EXECUTE "SELECT MD" CAPTURING JUNK
LOOP
  READNEXT ID ELSE EXIT
  PRINT ID
REPEAT

In this example, the output of the EXECUTE is not redirected, so the output of the TCL command is shown directly on the terminal:

              
PRINT "ACCOUNT NAME IS: ":
EXECUTE "ACCT-NAME"

ZBASIC.EXIT

Syntax:

EXIT

Description:

The ZBASIC EXIT keyword is used to unconditionally exit the innermost loop, jumping to the first instruction following the end of the loop. The keyword works with LOOP/REPEAT and FOR/NEXT loops, and always jumps to the end of the loop.

Example:

In this example, the loop will continue unless READNEXT returns FALSE, indicating that there are no more records to read:

              
EXECUTE "SELECT MD" CAPTURING JUNK
LOOP
  READNEXT ID ELSE EXIT
  PRINT ID
REPEAT

ZBASIC.EXTRACT

Syntax:

EXTRACT({var_expression},{expression}, {expression}, {expression})
{var_expression}<{expression},({expression}),({expression})>

Description:

The ZBASIC EXTRACT keyword, and it's short form notation are used to extract array data from a multidimentional string. All arrays in ZBASIC are stored a delimited strings, using @AM, @VM, and @SVM special characters to delimit the data. The EXTRACT function is used to extract specific peices of information out of the multivalue string by addressing the data field directly.

Example:

In the first form, the extract function is used to pull information out of the multivalued string:

              
STRING = "A" : @AM : "B" : @AM : "C"
PRINT "Here's a B: ":EXTRACT(STRING, 2, 0, 0)

In the second form, the same expression is data is displayed but using the short form of EXTRACT instead of the long form.

              
STRING = "A" : @AM : "B" : @AM : "C"
PRINT "Here's a B: ":STRING<2>

ZBASIC.FIELD

Syntax:

FIELD({var_expression},{delim_expression}, {which_expression}

Description:

The ZBASIC FIELD function is used to extract delimited data from a string. Unlike the EXTRACT function, which is designed to work with multivalued fields specificly using the multivalue special characters, the FIELD function can be used with any kind of data, and any single character delimiter. A typical use for FIELD is to extract information from comma or tab seperated data.

Example:

In this example, FIELD is used to extract information from a space-delimited string.

              
STRING = "Herbert Walker Bush"
FIRST = FIELD( STRING, " ", 1)
MIDDLE = FIELD(STRING, " ", 2)
LAST = FIELD(STRING," ", 3)
*
PRINT "Short name is: ":FIRST: " " : LAST

ZBASIC.FMT

Syntax:

FMT({var_expression},{fmt_expression})
{var_expresison}"{fmt_expression}"

Description:

The ZBASIC FMT function, or it's associated short form is used to format variables using a format code. This function can be invoked directly be calling the FMT function on a variable, or in it's short form by specifying a double-quoted format string after a variable name in your ZBASIC code. Note that, when using the short form of FMT unlike other multivalue implementations, the first double quote must be directly after the variable name, with no spaces. If a space is included following the variable name before the format string it will be a syntax error.

Format strings consist of three characters outlining the alignment, padding character and length of the formatted string. The following table summarizes the available options for each of character.

The Alignment character:

L	Align characters to the left, and optionally adding any necessary padding to the right
C	Align characters to the center, and optionally adding any necessary padding to both sides.
R	Align characters to the center, and optionally prepending any necessary padding to the left.

The Padding character:

%	Specify a SPACE ( ) as the padding character
#	Specify a ZERO (0) as the padding character

The Length:

{number}

Any positive integer can be used to specify the total length of the string. If the resulting string is longer than length, the string is truncated. If the resulting string is shorter than this length, it is padded using the padding character above

Example:

Short Form:

              
ZIP.NO = 123
PRINT ZIP.NO"R#5" ;* Prints "00123"

Long Form:

              
ZIP.NO = 123
PRINT FMT(ZIP.NO, "R#5") ;* Prints "00123"

ZBASIC.FOR...NEXT

Syntax:

FOR {var.experssion} = {num_expression} TO {num_expression} ({STEP}) {num_expression}
NEXT {var.expression}

Description:

The ZBASIC FOR...NEXT structure is used to implement logical loop and statement repetition. The statements enclosed in a FOR...NEXT block are executed in succession for the number of times described in the statement. The optional STEP keyword is used to indicate how ZBASIC should increment the var_expression at each iteration. By default, var_expression is incremented by 1 in each iteration of hte loop.

Example:

In this example, the FOR...NEXT structure is used to print the numbers 1 thought 10 in succession:

              
FOR X = 1 TO 10
  PRINT X:" ":
NEXT X

In this example, the STEP keyword is used and the loop is reversed, printing the numbers 10 through 1:

              
FOR X = 10 TO 1 STEP -1
  PRINT X:" ":
NEXT X

ZBASIC.GOSUB

Syntax:

GOSUB [STMT_LABEL]

STMT_LABEL

Replace STMT_LABEL in the above usage to identify the statement label that you would like to transfer execution to.

Description:

The ZBASIC GOSUB statement saves the current instruction pointer and unconditionally jumps to the instruction labeled by STMT_LABELl. You program will continue to run from that point until either the program is terminated or a RETURN instruction is executed, which resets exection back to the instruction point saved earlier.

Internally, ZBASIC keeps a "level count" which is incremented by GOSUBs and decremented by RETURNS. If a return instruction is encountered with a level count less than 1, the program is terminated.

In ZBASIC, all variables are globally scoped inside a file (including any $INCLUDE file). So, variables defined outside of a labeled statement block will be addressabile inside and vice-versa.

Example:

In the example below, the virtual machine will jump to the PRINT.NUMBER block at each iteration of the loop, printing the loop counter inside the PRINT.NUMBER statement block instead of inside the loop itself.

              
FOR X = 1 TO 10
  GOSUB PRINT.NUMBER
NEXT X
*
PRINT.NUMBER:
  PRINT X:" ":
RETURN

ZBASIC.GOTO

Syntax:

GOTO [STMT_LABEL]

STMT_LABEL

Replace STMT_LABEL in the above usage to identify the statement label that you would like to transfer execution to.

Description:

The ZBASIC GOTO statement saves the current instruction pointer and unconditionally jumps to the instruction labeled by STMT_LABEL. You program will continue to run from that point until either the program is terminated. Unlike a GOSUB instruction, GOTO does not save the instruction pointer or increment the level count, so it is not possible to return execution to the point of the GOTO instruction by a later RETURN.

In ZBASIC, all variables are globally scoped inside a file (including any $INCLUDE file). So, variables defined outside of a labeled statement block will be addressabile inside and vice-versa.

Example:

In the example below, the virtual machine will jump to the PRINT.NUMBER block at the first iteration of the loop. However, because this is a GOTO statement and not a GOSUB statement, the program will terminate after a single iteration.

              
FOR X = 1 TO 10
  GOTO PRINT.NUMBER
NEXT X
*
PRINT.NUMBER:
  PRINT X:" ":
RETURN

ZBASIC.ICONV

Syntax:

ICONV({var_expression},{fmt_expression})

Description:

The ZBASIC ICONV function reformats the argument supplied in var_expression using the information provided in fmt_expression. ICONV is used to reformat information into Zeobase's internal format, and can be used on many types of information. The tables below provides a list of the available conversion codes for each type of conversion:

Date Conversions:

Format Code	Description
D	The ZBASIC data conversion code "D" is specified to convert an externally formatted date into ZBASIC's internal format. The "D" conversion attempts to identify the formatting of your date and make the conversion. Currently, dates must be formatted with the month first, then date, then year. Many delimiters are allowed, including " ", "/", "-" and ".".

Character Masks:

Format Code	Description
MCN	Remove all non-numeric characters from the string. Returning only numbers
MCA	Remove all numeric characters from the string. Returning only non-numeric characters
MCL	Convert all letters to their lowercase equivilent
MCU	Convert all letters to their uppercase equivilent
MCT	Uppercase the first letter of all words in the string, lowercase all others.

Decimal Masks:

Format Code	Description
MD#	The conversion code MD, followed by a number moves the decimal point in var_expression that number of places to the right.

Time of day Masks:

Format Code	Description
MT	The conversion code MT converts the external time specified in var_expression into internal format, represented as the number of seconds since 11:59:59 the previous day.

Example:

              
PRINT ICONV("12/31/1969","D") ;* Prints the internal representation of that date.
PRINT ICONV("Joe","MCL") ;* Prints "joe"
PRINT ICONV("Joe","MCU") ;* Prints "JOE"
PRINT ICONV("JOE","MCT") ;* Prints "Joe"
PRINT ICONV("JOE123","MCA") ;* Prints "JOE"
PRINT ICONV("JOE123","MCN") ;* Prints "123"
PRINT ICONV("12:30:54","MT") ;* Prints the internal representation of that time.
PRINT ICONV("12.50","MD2") ;* Prints "1250"

ZBASIC.IF

Syntax:

IF ({expression}) THEN ({END}) || ({END ELSE}/{END})

Description:

The ZBASIC IF statement is used to test logical conditions and jump to the appropriate instruction based on the outcome of the logical test. IF statement blocks must be terminated by an END statement, and can optionally contain a single "END ELSE" clause and statement block to be executed if the logical test is false.

As of version 0.3, only one boolean expression is allowed to be inside each IF expression block. (i.e., you can't use AND or OR to test multiple conditions). I expect this feature to be on the short list of new features as ZBASIC expands.

Unlike other multivalue implementations, logical expressions following an IF statement must be enclosed in parenthesis. There are a couple of bad reasons for this: 1) It was easier to parse this way, and 2) I think it makes the code look cleaner anyways.

Example:

              
TODAY = "FRIDAY"
IF (TODAY = "FRIDAY") THEN
  PRINT "I love Fridays!"
END ELSE
  PRINT "It will be friday soon!"
END

ZBASIC.INDEX

Syntax:

INDEX({var_expression},{substring_expression},{num_expression})

Description:

The ZBASIC INDEX function search the specified var_expression for the {num_expression}'s occourance of {substring_expression}, returning the character position of that occurance of {substring}.

Example:

In this example, INDEX is used to search for a single character inside a string.

              
STRING = "My name is mud"
FIRST.M = INDEX( STRING, "m", 1)
PRINT FIRST.M ;* Prints the number "6", indicating the the first "m" in STRING is located at position 6.

In this example, INDEX is used to search for a word in string.

              
STRING = "My name is mud"
FIRST.MUD = INDEX( STRING, "mud", 1)
PRINT FIRST.MUD ;* Prints the number "12", indicate that the first occurance of the string "mud" is at position 12 in STRING.

ZBASIC.INPUT

Syntax:

INPUT {var_expression} ({:})
INPUT {var_expression}(,{num_expression}) ({:})

Description:

The ZBASIC INPUT function is used to gather character input from the user, storing that input in var_expression. When invoked, INPUT starts looking for character input from the user, and stores that input in {var_expression} when either the enter key is pressed (as shown in the first usage example), or if the optional {num_expression} is provided - INPUT will return when the specified number of characters have been read.

The optional concatenation character can be included to indicate that Zeobase should capture the trailing newline character if send by the user and not display on the terminal or include it in the return {var_expression}.

Example:

In this example, INPUT captures a string from the user, terminating when the used presses enter.

              
PRINT "What is your name ":
INPUT NAME
PRINT "Hello ":NAME:
PRINT " Nice to meet you!"

In this example, INPUT requests only a single character from the user, returning as soon as something is pressed.

              
PRINT "Enter a single character: ":
INPUT THE.CHAR, 1
PRINT "You typed the ":THE.CHAR:" character!"

In this example, INPUT keeps getting user input until the enter key is pressed, but captures the enter key so that it is not part of the returned string.

              
PRINT "Enter your birthday: ":
INPUT BDAY:
PRINT "  ":Great, I love that day!"

ZBASIC.INT

Syntax:

INT({expression})

Description:

The ZBASIC INT expression returns the integer portion of the provided expression, removing all non-numeric characters. If the string expression provided contains non-numeric characters they are removed. If the expression contains a decimal representation, the decimal portion is removed and only the full integer portion is returned.

Note that this function does not do any rounding, it only removes the non integer portion of a numeric expression.

Example:

              
PI = 3.14159
PRINT INT(PI) ;* Prints "3"

ZBASIC.LEN

Syntax:

LEN({expression})

Description:

The ZBASIC LEN function counts the number of characters in {expression} and returns the total count.

Example:

              
ZIPCODE = "43123"
PRINT LEN(ZIPCODE) ;* Prints the number "5".

ZBASIC.LOCATE

Syntax:

LOCATE {expression} IN {mv_expression} ({SETTING} {var_expression}) THEN ({END ELSE}/{END}) {END}

Description:

The ZBASIC LOCATE function searches the provided {mv_expression} for occurances of {expression}. If invoked using the optional SETTING keyword, the position in the multivalue string is returned into the {var_expression} variable. In either case, the instructions in the following THEN or ELSE block are executed based on weather or not {expression} is located.

{mv_expression} may represent an entire variable or a portion of a multivalued string by specifying which attribute, value or subvalue to search in. For example, specifying VARIABLE<3> in mv_expression would instruct LOCATE to look for {expression}, seperated by value marks, inside the third attribute of VARIABLE.

Example:

              
MV.STRING = "A" : @AM : "B" : @AM : "C"
LOCATE "C" IN MV.STRING SETTING POS THEN
  PRINT "Found C, at position ":POS
END ELSE
  PRINT "I can't find the C character?!"
END

ZBASIC.LOOP...REPEAT

Syntax:

LOOP
({statement_list})
REPEAT

Description:

The ZBASIC LOOP...REPEAT construct is used to repeat execution of a set of instructions defined in {statement_list}. The created loop will continue indefinately until another jump instruction is encountered inside of the loop. Jump instructions include CONTINUE, RETURN, GOTO, or EXIT.

LOOP...REPEAT blocks are repeated indefinately and unconditionally. Conditions to exit the loop must be created seperately inside the loop using one of the jump instructions outined above.

Example:

In this example, ZBASIC will print the word "Looping!" 10 times, and then exit the loop.

              
X = 1
LOOP
  PRINT "Looping!"
  IF (X = 10) THEN
   EXIT
  END
  X = X + 1

REPEAT

ZBASIC.MOD

Syntax:

MOD({num_expresion2}, {num_expression2})

Description:

The ZBASIC MOD function is used to calculate and return the mathmatical remainder when dividing {num_expression1} by {num_expression1}.

Example:

              
PRINT MOD(10,6) ;* Prints "4", the remainder portion of this formula.

ZBASIC.NUM

Syntax:

NUM({num_expresion})

Description:

The boolean ZBASIC NUM expression is used to test {num_expression} to determine weather or not it is a number. If the condition is true, the NUM expression returns a true value, if not it returns a false value.

Example:

In this example, the boolean condition will fail:

              
STRING = "ABC123"
IF (NUM(STRING)) THEN
  PRINT "It's a number" ;* This won't happen.
END

In this example, the boolean condition will succeed:

              
STRING = "123"
IF (NUM(STRING)) THEN
  PRINT "It's a number" ;* This will happen.
END

ZBASIC.OCONV

Syntax:

OCONV({string_expression},{fmt_expression})

Description:

The ZBASIC OCONV expression is used to convert internally formatted data into it's external format. This function can be considered the inverse of ICONV, and supports many of the same conversion codes:

Date Conversions:

Format Code	Description
D(#)(delim)	The ZBASIC data conversion code "D" is specified to convert an internally formatted date to it's external representation. By default, the D conversion code will format a date with a 4 digit year, using a '/' for a delimiter, in the format MM/DD/YYYY. Optionally, you can specify the number of year characters (2 or 4), and the delimiter including ("."," ","/", or "-"

Character Masks:

Format Code	Description
MCN	Remove all non-numeric characters from the string. Returning only numbers
MCA	Remove all numeric characters from the string. Returning only non-numeric characters
MCB	Remove all non alphanumeric characters from the string
MCL	Convert all letters to their lowercase equivilent
MCU	Convert all letters to their uppercase equivilent
MCT	Uppercase the first letter of all words in the string, lowercase all others.

Decimal Masks:

Format Code	Description
MD#(thousands delim)(currency char)	The conversion code MD, followed by a number moves the decimal point in var_expression that number of places to the left. Optionally, a thousands delimiter (i.e. ",") may be specified and a currency character (i.e. "$"). By default, neither of these is included in the returned string.

Time of day Masks:

Format Code	Description
MT	The conversion code MT converts the external time specified in var_expression into internal format, represented as the number of seconds since 11:59:59 the previous day.

Example:

              
PRINT OCONV("12345","D2/") ;* Prints the external representation of this date in MM/DD/YY format.
PRINT OCONV("Joe","MCL") ;* Prints "joe"
PRINT OCONV("Joe","MCU") ;* Prints "JOE"
PRINT OCONV("JOE","MCT") ;* Prints "Joe"
PRINT OCONV("JOE123","MCA") ;* Prints "JOE"
PRINT OCONV("JOE123","MCN") ;* Prints "123"
PRINT OCONV("12:30:54","MT") ;* Prints the external representation of that time.
PRINT OCONV("125000","MD2") ;* Prints "1250.00"
PRINT OCONV("125000","MD2,$") ;* Prints "$1,250.00"

ZBASIC.OPEN

Syntax:

OPEN "{DICT}",{file_expression} TO {var_expression} ({THEN}/{ELSE}) ({END ELSE}/{END}) {END}

Description:

The ZBASIC OPEN function is used to open a Zeobase data or DIR type file so that it's information can be accessed within the ZBASIC program. Optionally, if the word "DICT" is specified before the file name - the Dictionary of the file is opened instead of the data file itself. The {file_expression} provided must include a string representation of the file name, listed in the MD file of the current account. If OPEN succeeds, {var_expression} is recast as a file pointer and the file is accessible from the program to be read or written.

The OPEN statement must include either a THEN or ELSE clause, specifying what to do if the it succeeds or fail. Only one of THEN or ELSE is required. If the ELSE clause is specified, no END keyword is needed assuming the entire clause is specified on a single line. OPEN statements followed by THEN clauses are required to span multiple lines and be terminated with an END clause.

Unlike other multivalue implementations, ZBASIC requires that complete file definitions are provided in the OPEN statement, so - to open the data portion of a file the string "","FILENAME" must be used to address the file. If the Dictionary portion is to be opened, the string "DICT","FILENAME" must be used. Using the short form (omitting the quotes and commas) used in many other platforms is not supported in Zeobase. Maybe someday.

Example:

Long form:

              
OPEN "","MD" TO F.MD THEN
  PRINT "It's open"
END

Condensed form:

              
OPEN "","MD" TO F.MD ELSE STOP "I can't open it!"

ZBASIC.PRINTER

Syntax:

PRINTER {ON} || {OFF}

Description:

The ZBASIC PRINTER statement, followed by one of the keywords ON or OFF, instructs ZBASIC to redirect output from the screen to a temporary file, and the ultimately print the output to the currently active and selected print queue. The print queue must have previously been set up with the SP-ASSIGN builtin at TCL.

As noted above, ZBASIC creates a temporary file (typically in /tmp, but wherever your system-defined temp location is) to hold the printed data before sending it to the printer. You will need to ensure that your system's tmp space is large enough to hold your print jobs.

Example:

              
PRINT "TEST TO SCREEN" ;* Printed to screen
PRINTER ON
PRINT "TEST TO PRINTER" ;* Sent to the printer.
PRINTER OFF
PRINT "BACK TO SCREEN"  ;* And back to the screen again.

ZBASIC.PWR

Syntax:

PWR({num_expression}, {pwr_expression})

Description:

The ZBASIC PWR function calculates the value of num_expression raised to the power specified in pwr_expression. Once calculated, the result is returned.

Example:

              
PRINT PWR(10,10) ;* Prints 10000000000

ZBASIC.READ

Syntax:

READ {var_expression} FROM {file_expression), {key_expression} ({THEN} || {ELSE}) ({END ELSE/END}) (END})

Description:

The ZBASIC READ statement is used to read information from a multivalue database or DIR type file which was opened in a previous invocation of OPEN and identified with file_expression), using the key specified in {key_expression} and then placing the results of the read into the variable specified in var_expression.

The READ statement must include either a THEN or ELSE clause, specifying what to do if the read succeeds or fail. Only one of THEN or ELSE is required. If the ELSE clause is specified, no END keyword is needed assuming the entire clause is specified on a single line. READ statements followed by THEN clauses are required to span multiple lines and be terminated with an END clause.

Example:

This example shows both the short and long form of READ statements:

              
OPEN "","MD" TO F.MD ELSE STOP "I CANT OPEN MD!"
*
READ REC FROM F.MD, "MD" ELSE REC = "I CAN'T READ IT."
PRINT REC
*
READ REC FROM F.MD, "CT" THEN
  PRINT "The CT record exists in MD"
END ELSE
  PRINT "Where the heck is CT?"
END

ZBASIC.READNEXT

Syntax:

READNEXT {var_expresion} ({THEN} || {ELSE}) ({END})

Description:

The ZBASIC READNEXT statement gathers the next record ID from the currently active select list, removing it from the list and placing it into the variable identified by {var_expression}.

Select lists in Zeobase are implemented as sorted or unsorted stack data structures, so READNEXT effectively pops the first record off the select list each time it's called. Therefore, if a program is aborted after a select list is active but before all of hte keys have been popped by READNEXT, your environment will still have an active select list with the remaining records still in it at program completion.

The READNEXT statement must include either a THEN or ELSE clause, specifying what to do if the it succeeds or fail. Only one of THEN or ELSE is required. If the ELSE clause is specified, no END keyword is needed assuming the entire clause is specified on a single line. READNEXT statements followed by THEN clauses are required to span multiple lines and be terminated with an END clause.

Example:

              
EXECUTE "SELECT MD"
LOOP
  READNEXT ID THEN
    PRINT ID
  END ELSE
    EXIT
REPEAT

ZBASIC.READU

Syntax:

READU {var_expression} FROM {file_expression), {key_expression} ({THEN} || {ELSE}) ({END ELSE/END}) (END})

Description:

The ZBASIC READU statement behaves exactly in the same manner as the ZBASIC READ statement, except that before reading the record it obtains an exclusive lock on the record, prohibiting any other locks from being created, or the record from being written in another process. For usage information, See READ.

The READ statement must include either a THEN or ELSE clause, specifying what to do if the read succeeds or fail. Only one of THEN or ELSE is required. If the ELSE clause is specified, no END keyword is needed assuming the entire clause is specified on a single line. READ statements followed by THEN clauses are required to span multiple lines and be terminated with an END clause.

A note about locking: All locks in Zeobase are advisory, meaning that they can be ignored. For instance, a locked record can still be read using a READ command, held while the record is locked, and then written later (overwriting any changes). For this reason, it is critical that programmers use READU if their intention is to later update a record.

Example:

              
*
* In this example, the records both stay locked until
* the program has exited and released all of it's locks.
* An alternative way to release the lock would have been to WRITE it back.
*
OPEN "","MD" TO F.MD ELSE STOP "I CANT OPEN MD!"
*
READU REC FROM F.MD, "MD" ELSE REC = "I CAN'T READ IT."
PRINT REC
*
READU REC FROM F.MD, "CT" THEN
  PRINT "The CT record exists in MD and is locked"
END ELSE
  PRINT "Where the heck is CT?"
END

ZBASIC.READV

Syntax:

READV {var_expression} FROM {file_expression), {key_expression}, {attrib_expression} ({THEN} || {ELSE}) ({END ELSE/END}) (END})

Description:

The ZBASIC READ statement is used to read information from a multivalue database or DIR type file which was opened in a previous invocation of OPEN and identified with file_expression), using the key specified in {key_expression} and value specified in {value_expression} and then placing the results of the read into the variable specified in var_expression.

READV reads only a specific attribute from the file instead of the entire record. This helps in that it is significantly more efficient for the compiler to read and parse a multivalue database record than it is to do it in multivalue code (about 12 times more efficient). SO, if you only need a selected part of the file - this is the best way to do it. If you are ultimately going to need data from more than one attribute in a record, it would be much more efficient to read the entire record and parse it inside your ZBASIC code.

The READ statement must include either a THEN or ELSE clause, specifying what to do if the read succeeds or fail. Only one of THEN or ELSE is required. If the ELSE clause is specified, no END keyword is needed assuming the entire clause is specified on a single line. READ statements followed by THEN clauses are required to span multiple lines and be terminated with an END clause.

Example:

This example shows both the short and long form of READV statements:

              
OPEN "","MD" TO F.MD ELSE STOP "I CANT OPEN MD!"
*
READV SYSNAME FROM F.MD, "MD",2 ELSE REC = "I CAN'T READ IT."
PRINT SYSNAME
*
READV B.CODE FROM F.MD, "CT", 2 THEN
  PRINT "The builtin code for CT is ":B.CODE
END ELSE
  PRINT "Where the heck is CT?"
END

ZBASIC.RELEASE

Syntax:

RELEASE {file_expression}, {key_expression}

Description:

The ZBASIC RELEASE statement is used to release a record that was previously locked using a READU statement. Records locks are unconditionally released, and performing a RELEASE on an record that is already unlocked has no effect.

Example:

              
OPEN "","MD" TO F.MD ELSE STOP "I CANT OPEN MD!"
*
READU MD.REC FROM F.MD, "MD" ELSE MD.REC = "" ;* Record is currently locked.
*
RELEASE F.MD, "MD" ;* Record is now unlocked

ZBASIC.REM

Syntax:

REM ...

Description:

The ZBASIC REM statement is a synynom for the "*" character. This keyword and everything after it until the next newline are ignored by the compiled and omitted from the resulting P-Code.

Example:

              
REM this_garbage_is_ignored

ZBASIC.RETURN

Syntax:

RETURN

Description:

The ZBASIC RETURN statement is used to return to a calling program or saved instruction pointer.

Internally, ZBASIC keeps a "level count" which is incremented by GOSUBs and decremented by RETURNS. If a return instruction is encountered with a level count less than 1, the program is terminated and returns control to it's caller. If the program is a subroutine, that caller is typically another basic program. If the program stands alone, the caller is TCL.

If a RETURN instruction is encounted inside a subroutine, and the subroutine's level count is zero - ZBASIC will load the final values of any subroutine arguments onto the stack of it's caller - transferring the final values into the same variable names in it's caller.

Example:

In this example, RETURN is used to go back to a saved instruction pointer:

              
*
X = 1
GOSUB ADD.ONE.TO.X
PRINT X
STOP
*
ADD.ONE.TO.X:
  X = X + 1
RETURN ;* Go back to line 2 of the program.

In this example, the program's level count is zero when the RETURN statement is encountered, so control is passed to it's caller:

              
SUBROUTINE ADD.ONE.TO.X( X )
X = X + 1
RETURN ;* Go back to the calling program

ZBASIC.RND

Syntax:

RND({max_expression})

Description:

The ZBASIC RND function generates a random number between zeo and the number specified in max_expression. This function uses your systems random number generator, seeded at each call with the current time since epoch. For this reason, calls made twice in a row (in the same second) could potentially return the same value.

Example:

              
PRINT "Here's a random number between 1 and 10: ":RND(10)

ZBASIC.SLEEP

Syntax:

SLEEP({time_expression})

Description:

The ZBASIC SLEEP expression suspends execution of the basic program for the specified number of seconds. During this time, no activities are completed by the associated Zeobase process, and CPU time is available for the operating system.

Example:

              
* Sleep for 10 seconds
SLEEP(10)

ZBASIC.SPACE

Syntax:

SPACE({num_expression})

Description:

The ZBASIC SPACE function returns a string consisting of num_expression spaces.

Example:

              
* This program is worthless and just prints 10 spaces, see:
PRINT SPACE(10)

ZBASIC.STR

Syntax:

STR({char_expression},{num_expression})

Description:

The ZBASIC STR function creates a string of char_expression characters that is num_expression in length. If char_expression is more than a single character, only the first character of the string is used.

Example:

              
* This program is worthless and just prints 10 stars, see:
PRINT STR("*", 10)

ZBASIC.SUBROUTINE

Syntax:

SUBROUTINE({arg_expression,({arg_expression})...)

Description:

The ZBASIC SUBROUTINE statement is used to define a subroutine and it's arguments. When specified, this statement is used by the compiler to identify and pass arguments between subroutines and calling programs. It must be the first executable line of a program, and must always contain parenthesis.

Unlike most other multivalue implementations, parenthesis are always required when defining or calling a subroutine with ZBASIC.

Example:

              
SUBROUTINE PRINT.STARS( NUM.STARS )

* Print some stars!
PRINT STR("*", NUM.STARS)

RETURN

ZBASIC.SWAP

Syntax:

SWAP {str_expression1} WITH {str_expression2} IN {var_expression}

Description:

The ZBASIC SWAP function converts all occurances of {str_expression1} with {str_expression2} in the string {var_expression}. Unlike the CONVERT statement, which does this one character at a time, the SWAP statement swaps only the entire string at a time. So, only exact matches to the string specified are converted.

Example:

              
STRING = "My name is John Doe"
SWAP "hn" WITH "e" IN STRING
PRINT STRING ;* prints "My name is Joe Doe"

ZBASIC.TCLREAD

Syntax:

TCLREAD()

Description:

The ZBASIC TCLREAD function reads the last TCL command entered by the user at TCL and returns the entire command.

Example:

              
TCL.CMD = TCLREAD() ;* TCL.CMD contains the last typed string at TCL

ZBASIC.TIME

Syntax:

TIME()

Description:

The ZBASIC TIME function returns the current system time as seconds since 11:59:59 the previous day.

Example:

              
NOW = TIME() ;* The variable NOW contains the number of seconds since midnight.

ZBASIC.TRIM

Syntax:

TRIM( {var_expression} )

Description:

The ZBASIC TRIM function removes any leading or trailing whitespace characters from the string specified in var_expression.

Example:

              
STRING = "  BLA  "
PRINT "'": TRIM(STRING) : "'" ;* Prints 'BLA'

ZBASIC.WRITE

Syntax:

WRITE {var_expression} ON {file_expression}, {key_expression}

Description:

The ZBASIC WRITE statement writes the data specified in var_expression to the file specified in file_expression, using the key {key_expression}. This function should not ever fail unless there is a permissions issue with the file being written to. Any errors will be reported at runtime.

Notes on locking: When a WRITE command is finished, it releases any exclusive locks currently held on the file and key. If the file is not locked, this has no effect. If the file/key combination is locked by another process when the write is executed, it will block until the lock is release and it is allowed to continue. There is no timeout, and the process will continue to block forever until killed or manually released.

Example:

              
OPEN "","MD" TO F.MD ELSE PRINT "I CAN'T OPEN MD"
RECORD = "BLA"
WRITE RECORD ON F.MD, "newkey"

ZBASIC.WRITEV

Syntax:

WRITE {var_expression} ON {file_expression}, {key_expression}, {attr_expression}

Description:

The ZBASIC WRITE statement writes the data specified in var_expression to the file specified in file_expression, using the key {key_expression} and value position attr_expression. This function should not ever fail unless there is a permissions issue with the file being written to. Any errors will be reported at runtime.

This function behaves in exactly the same manner as WRITE, except that it only modifies the data in a single attribute in an existing or new database record.

Example:

In this example, ZBASIC writes to the 4th attribute of the record "newkey". If the record exists, the fouth attribute is modified. If not, it is created with data only in the fouth attribute.

              
OPEN "","MD" TO F.MD ELSE PRINT "I CAN'T OPEN MD"
RECORD = "BLA"
WRITE RECORD ON F.MD, "newkey", 4