BAL SYSTEM is a new development system package designed for À Plus4. Based on the B.A.L. (Business Assembler Language), an already existing standard for business machines, the enviroment has been improved with many high-level new commands and features. These improvements can easy manage Plus/4 memory and ports, so that BAL SYSTEM is candidated to become the ideal enviroment to run any program, expecially external applications and monitoring like devices and electronic cards.

The package is a complete all-in-one tool: Editor/Debugger/Executer. As I’m a coder J I designed inside it some additional tools to better (and easily) perform testing and debugging. I hope you all enjoy with it, by executing programs under BALSYS, but also by writing your own code.

Original BAL machines had a memory RAM of 1 Kb, expandable to 4 Kb. The standard machines were sold 2 Kb expanded. With BALSYS you can set any memory amount between 1 to 4096 bytes.

Mass storage was a magnetic-cards system (read/write). The user could insert one or more magnetic cards on the reader, and the data went onto/from the memory. Each card could contain till 256 bytes. In this way you could have individual cards (for example one for each customer) or cards-packs programs to be loaded and executed. In BALSYS I’ve maintained the "cards" only as an animation during I/O operations. The real mass storage is now modern disk/tape files.

The output monitor was an integrated two-color printer that could print on any of its three sectioned platen. The output of BALSYS is a screen-window with paper simulation (scrolled); but you can also print (on a real printer) the listing of the program in memory.

For monitoring and signalling there is a console with operating/warning lights. Apart the system lights (Magnetic card request, Keyboard enable, CPU error) the user is enabled to manage (see/set) 8 different programmable lights. With BALSYS you can even show on them icons, to better indicate special status’s or warnings.

To have an idea of the powerful of this package, run the sample program "MC-POWER" on the D64 disk-image. It does a math calculation of the power of a number you input (x^y). The elaboration is done without any specific function but only using basic operations (+, -, *, /). All the input requests, the controls, the calcoulus’s and the printing (formatted) of result occupy only 76 bytes of code!

But I added new hi-level commands in BAL-SYS, to easy obtain hi-level special performances. For example, there are 3 lines of IRQ available, to monitor the status of a location, or if/when an event happens. This feature works while the program is running, processing something else. Furthermore there are a timer/clock to easily measure times, show it as a watch, or determine timings (stop-watch features can be obtained with only 2 commands).

And many other of course… be curious and read on.

• Press any Status-key (see chapter 2.0) if you want to change the Mode (À -S for SERVICE; À -T for STEPRUN);

There are also 4 special "program-keys":

BAL-SYSTEM emulates the cards by an USR file named "MC-…" on floppy or on tape. The management of multiple cards is automatic: it is signaled by a flashing icon on the reader. During I/O operations, [M.C.]-key turns on. To see the BAL-files inside the online disk, type .DIR pseudo from Service-Mode of from StepRun-Mode.

• Pointers’ values
• Stack level
• System flags
• Enabled Function-keys and Program-keys
• Alarm/IRQ status
• Mnemonic whose execution caused the error
• The values of PC, SC, and CND (Condition-Register) are shown on display.

If the error condition appears while you are in Run-mode (execution of a program), be informed that after the cleaning operation, system will attempt to execute again the same mnemonic. Then, in order to exit from this situation, you could need to change Mode (entering for example into Service-Mode) instead of cleaning the error: Simply press À -S (for Service-mode) or À -T (for StepRun-Mode).

To stop the program running (but while it’s waiting for an input), keep pressed [STOP] until you are deviated onto SERVICE mode. Running is stopped too, when any "halt" command is met during code execution (WAIT / HLT / ON), or when an Error is detected.

• Execute any pseudo command;
• Insert a new program;
• Edit a program in memory;
• Load/save program or memory areas.

• Execute a program’ mnemonic one at a time, by monitoring values and conditions.

• Execute any pseudo command;
• Load/save program or memory areas.

• Execute a program in memory (written or loaded), free running.

• Bypass an error condition (program, memory and counters are NOT erased). After a [clear] the machine returns to the mode where the error happened.

• Restart the virtual machine. All pointers, settings and values are cleared. After resetting system does search for PREFERENCES.BAL file on the online device: if found, it loads the preferences and then asks for a program-loading just like when it is just turned on.

The Condition-code is affected by the pressed [Return]-like key, so that you can test it and decide a different program path.

Pattern of [Return]-like keys can be enabled/disabled to guide the user inside legal choices (see table 2.15).

They are special keys on a real BAL machine, that are here substituted by the following combinations:

They are used to directly set flags on BALSYS system memory. When enabled, the user can set till 4 flags, following program execution requirements. A Program-key hit does not end the input because it is not a [RETURN]-like key.

For example, if system is waiting for an input:

you enter the value 135, but you also set Program-key #1 to inform program of something to remember. The program could take a decision later on the grounds of it.

The nice aspects of Program-keys is that you could press more then one (for example [p1] then [p3]) and that they never affect the input operation. Program keys are normally disabled: only the command KEP inside a BAL program can enable some of them (or all them). When an enabled Program-key is pressed, its bit is stored (set to 1) in a nibble of Condition Register (see table below), so that it can be tested (by mnemonic TIC), or manipulated (ANDed, ORed, XORed or even forced).

BAL is a middle level language. It can be put at midway between BASIC and Assembler.

Main features:

• Each command is 2 bytes in length, always starting in an even address (0, 2, 128…. and not not 1, 3, 127).
• Each keyword (named mnemonic) is from 1 to 4 characters long (see table below).
• Easy math division and multiply commands.
• Registers feature. Like BASIC variables, each register is a group of 8 bytes used for calculuses. (Memory addresses from 0…to…7 stand for Register #0, memory addresses from 8…to…15 stand for Register #1, and so on). Registers are easily involved in math calculuses, tranferts and manipulations. Even if the maximum value stored in a Register could be theorically 999,999,999,999,999 the real accepted value by BAL-SYS is 999,999,999 (se image on next paragraph 2.5)
• No floating point is managed. To use decimals, you can take care of them by considerig that the whole values are always stored (123,45 is stored as 12345). Math commands allows to shift (left or right) the results, so that you can easy obtain the correct sizes of result values.

BALSYS’ memory RAM can be utilized:

• to store data (characters, values, flags, etc.)
• to store program code. (The first statement of a program must always be LAB 255)
• to be utilized as registers (groups of 8 bytes). See above chapt. 2.4.

All Pointers, Registers and Data have to be input as decimal values. Only when specifically necessary you have to input a hexadecimal datum: in this case datum has to be single quoted (See table of Mnemonics below). Registers can easy be indicated by their number (0 is the first Register, 1 the second Register, and so on). In this way you can specify Registers from #0 to #15.

Indirect addressing mode is allowed to aim Registers out that range (#16, #17,…#218, and so on). To refer to one of these Registers, you only have to put its number (as index-value) into one of the direct Registers (0…15) and refer to it by placing as prefix a point "."

step 1: Insert value 30 into one of the direct Register (say #7);

step 2: Refere to ".7" into statement (it becomes: ARI .7,10)

They are commands to be executed immediately. Their names always start by a dot "."

[Color Blue means non-standard BAL commands)

After a BALSYS reset (and when just turned it on), you are asked to hit a key to perform autoloading, from autodetected device, of the a BAL program file. You can write a filename or accept the prompt (see chapt. 1.1), or do change mode (see chapt. 2.1) by entering À -S (Service mode), À -T (Step-run mode).

To perform a manual load, you have first to set the Pointer 1 to the address in memory (loading address, normally 0) by using .TSP xxxx (where xxxx is the address), then enter .RMC xxx where xxx is the amount of bytes to load from file. You will be requested for a filename (starting by "MC-"; wildcards accepted). If you don’t remember the name of your files, just hit .DIR to see all them.

If the file is larger than 256 bytes, you must repeat the .RMC xxx command as many times it is necessary.

When a program is in memory (loaded or typed), you can edit it. This can be done only by SERVICE mode (À -S). The main operations are:

To navigate inside the code, you can utilize the bi-directional listing: press [CRSR]-[DOWN] to view the next statement(s); press [CRSR]-[UP] to view previous one(s). Service Counter follows the movements.

To view what mnemonic is pointed by the PC, hit [SHIFT]+[=] that is the left-arrow key. For example this is necessary when you want to see which mnemonic is "under" the PC, while you are inserting new mnemonics, because in this case the PC is always aiming the next address.

To skip to a specific location, please use one of the following pseudos:

• .TSP xxxx (Transfer Service Pointer to address xxxx)
• .TSL xxx (Trasnfer Service Pointer to Label xxx)
• .TSR xxx (Transfer Service Counter to Register #xxx)

Even if B.A.L. is not a hi-level language considering that each mnemonic always occupies 2 bytes only, I made it able to accept comments inside the (machine) code. How is this possible? J Well: to insert a comment, many characters long as you wish, you only have to hit ";" then a space, and your comment. For example:

The comments will be saved with the program and then will be automatically present inside the listing.

To save a program to file, first you have to set the Service Counter to start of area to be saved (by .TSP). If you accept the current device (see icon at top left corner of screen), you only have to hit .WMC xxx (where xxx is the number of bytes to save). If you want to change the device, please utilize the pseudo .DEV x (where x is the device number; 1 for tape, 8…15 for disk drivers). When prompted enter the filename starting by prefix "MC-".

If you wish to save further bytes appending them to previous ones, you can do it, simply by typing further .WMC xxx how many times you want. Please watch the "multiple cards" icon on the I/O device-card, flashing on the screen (bottom-right). If there is, then you can continue the appending operations. When it disappears, then the file is closed and you can not append anymore. Be sure to not execute any command between a .WMC and another one in order to not stop the appending chain operation.

If an already existing file with the same name was found, you are asked to confirm its overwriting: if yes, the previous file is backed up with the name "MC-OLD.USR" and your saved program acquires the name you entered plus ".USR".

Icons can be managed by mnemonics ICON, IDEF or pseudo .IC

(To enable a pattern use KES mnemonic)

Last [RETURN]-like key is stored in nibble 9 of Condition-Register

Use bit value for mnemonics FIC, NIC, OIC, TIC, XIC.

Use position value for menmonic ICON.

To write a program you must operate as follow:

• Enter into SERVICE-mode (À -S);

• Locate the Service Counter (SC) to the starting point you wish (.TSP xxxx).

1. 0…7
2. 8…15
3. 16…23

• Input as first mnemonic "LAB 255". This tells the O.S. where the code starts, being the entry address. All before data are ignored (registers and/or data). When the user loads the program and runs it, the first code to be executed is the one that follows LAB 255.

• Remember that each mnemonic and its data are always stored into 2 bytes of memory. All the mnemonics do this, even the ones that have no data (i.e. DRD, HLT, DE2).

• Mnemonics have to be stored in memory starting from even-address numbers, that is:

• Input Mnemonics or Data. When inputing mnemonics (being in SERVICE-mode), the SC is automatically increased so that you have not to care of it. Inserting mode is normally enabled, so that if you input a new mnemonic over existing code, the existing code is shifted up and your new mnemonic is inserted in: i.e.:

• Deleting of a mnemonic is done by [F2]-key pressing. All the remaining code is automatically shift down to fill the gap i.e.

When not in RUN-mode, the system is on a debug-like status, and you could use all the tools at disposal, in particular the pseudo commands, to test memory, insert data, change pointers, etc. All these pseudo commands (starting by a dot ".", see pseudo table 2.7) are at disposal of coder in STEPRUN-mode too, so that you can test (and modify) the values at any step of processing.

Furthermore there are the following tools:

• Disables all the displays. This speeds up the execution of a program. (Error messages still remain enabled). (default = on)

Press the keys (one or more) you wish to set / reset any of the above features, and [ESC] when finished, to return.

Each time you set/reset a flag, you are informed of current updated status of all settings.

An important feature of .SET pseudo is that when you exit from it, the PREFERENCES.BAL file is automatically updated, with current sets, current memory amount, current I/O device, and last filename used. Next time you run BalSys (or even if you reset it) system will use these data to be self configurated.

[?]-key while in Error-status. When [E]-light is turned on in the console, system is in Errror Status. The display shows the description of the error. Before clearing it with [CBM]-[E], you may press [?] + [Return] to view more info, as values of pointers, stack deep, enabled keys, alarms, and the mnemonic whose execution caused the error. The error condition will remai, until you clear it by [CBM]-[E], or change mode.

.PSE pseudo command Lists all the pseudos supported by BAL-SYSTEM

.MNE pseudo command Lists in alphabetic order, all the mnemonics of BAL-SYS language.

.? xxxx pseudo command. This is the help to any mnemonic (xxx=mnemonic name). By typing it you can easy know:

1. if that mnemonic exists J ;
2. what is its binary code to store it in memory;
3. if the data (operands and/or values) fits the second byte only, or a part of the first byte too;
4. format of data;

Furthermore if the mnemonic has two forms (absolute or conditioned), you are showed the 2 forms with their separate values. For example: F mnemonic are shown as F alone (unconditioned skip) and as F+ (conditioned skip – F0, F1, F2, F3 according to Condition-Register value).

WAIT mnemonic. It is a break-point like instruction. When RUN process meets this mnemonic, execution is paused and on display you’ll see a message telling you "WAIT AT: xxxx" where xxxx is the address in memory where processing is arrived. You can press [Return] to continue running by executing next mnemonic, or press [À ]+key to switch to other modes (SERVICE / STEPRUN / CLEAR / RESET).

.LIS pseudo command Allows you to have a list of your program, on a real printer.

In order to speed up the running of a BAL program, system compiles a table of the labels that are used by the program in memory. This is performed automatically before the launch of first running, and all the times a following modification affects the code, since the last time the labels-table was compiled.

The user has not care about it, being automatic and fast, he only see a blinking system message during the processing.

The programmer could make a good use of it too, in order to check if there are Labels that are duplicated. To do this, please set the warning-option by .SET L. After this if a duplicate label is found, a proper message is shown on the panel, waiting for:

• [Return] to continue Label-table compiling (label will maintain its first value); In most cases

• [Shift]-[Return] to continue Label-table compiling (with updating the value with which one just

• [S] to stop the processing and enter into Service mode (in order to edit the program)
• [?] to view what is the Label affected by the duplication, and at which addresses are

POWER CALCULATOR (by S\_/S 2003)

We plan: Register#0 for calcoluses and result

Register#1 number to be powered

Register#2 power

Register#3 (future expansions :)

….. Room for Registers 0, 1, 2, 3 (4 x 8 = 32 bytes; addresses: 0…31)

46 LR 1,0 Copy value of Register #0 onto Register #1 (Number to be powered)

value into Register #0.

54 LR 2,0 Copy value of Register #0 into Register #2 (Power)

56 CRI 2,0 Compare Register #2 with "0" (this affects the "Condition-code")

60 FD 1 Let Register #0 = 1 (set result as 1)

62 B 102 Goto LAB 102 (Print result)

68 LR 0,1 If yes, Register #0 (result) will be loaded by Register #1 (number)

70 B 102 Goto LAB 102 (Print result)

74 LR 0,1 Let Register #0 = Register #1

#0 (Register #0 = Register #0 * Register #1)

78 SRI 2,1 Subtract "1" from Register #2 (power)

80 CRI 2,1 Compare Register #2 with "1" (power = 1?)

90 DE1 Enable European using for number (#.###,##)

108 WAIT End of program

(you can see them by .PAS or .PX)

(you can see them by .PAS or .PX)

(not necessary to BalSys)