Before you can begin to write an application it is necessary to include certain information in the ROM card which tells the system what the card contains. This section explains how to set up the static structures, including menu topic help, which define your application. Following this, actual programming techniques and facilities can be examined.
Introduction
The most unusual facet of the Z88 is its ability to deal with many applications and suspend and reactivate them as required. An application may be set up on a ROM or EPROM card and inserted into one of the slots at the front of the machine. If the appropriate data structures are set up on the card, then the operating system can make application appear like the in built programs, such as Pipedream. Applications are rather confusingly divided into 'Applications' and 'Popdowns'. When we talk about applications in general this includes popdowns, but when talking about the two together an application is distinct from a popdown. The actual difference between the two, when a contrast is being drawn, is that a popdown will receive a KILL request from the system whenever the user attempts to switch applications. A popdown is useful for functions like the clock and calculator which on ce they have been used do not really need to remember what they were doing before, so it is perfectly allright to close them down completely and start them up from scratch when they are required again. An application, as opposed to a popdown, can be returned to after application switching, so that the user can continue to use it as before.
Applications are further divided into good and bad types. Most applications are 'good': they only take RAM as they need it, using the memory management routines, and do not demand more than 256 bytes of continuous RAM. 'Bad' applications, demanding larger blocks of memory, can use up to a 40K of continuous RAM - this feature was included in order to be able to run standard BBC BASICZ80 - a binary image designed for a normal Z80 system. There is also an 'ugly' application type, which is similar to 'bad' but refers only to popdowns ie. a bad popdown.
None of the built in applications is of this type. Applications types are, therefore:
| Good | An application application not requiring large continuous workspace. |
| Bad | An application application requiring large continuous workspace. |
| Popdown | A popdown application not requiring large continuous workspace. |
| Ugly | A popdown application requiring large continuous workspace. |
The following pages will describe all the structures available to implement application cards that can hold one or more types as listed above.
Bad Applications
An application can be made 'bad' (or a popdown 'ugly') if it requires a large area of continuous memory since the Z88 cannot allocate more than 256 bytes to an application at any time. Although this appears to be very restrictive, most programs can be made to work under this regime. All the internal applications, bar BBC BASIC, are 'good', and BBC BASIC is only bad because it was not written for the Z88 but simply imported. If, however, you are simply unable to write an application without large continuous areas, you may have to make your application bad. Similarly if your application is intended to be the only one running on the Z88, there is no problem with it being bad.
Bad application memory is provided from address $2000 onwards. The amount given depends on the value of the 'continuous RAM size' byte in the application DOR header. This byte should be set to the number of 256 byte pages required. If it is set to zero then the default value is used (40K in an expanded machine, 8K in an unexpanded machine). The value of the default can be changed, via the PANEL, but bear in mind this is something which affects the whole system, and should not be undertaken lightly. When a bad application is first entered, the IX register points to an information block as follows:
1 byte $03 Number of information bytes
1 byte x Start page of continuous memory, $20
1 byte x End page of continuous memory, this cannot
be used, for example $C0 for a 40K bad
application.
1 byte x Ususally zero. Reserved for future
expansion.
Whenever BBC BASIC is exited an area of unused memory, between the program and the stack, is given back to the system. When BBC BASC is re-entered memory is found to fill this hole back up again. It is this mechanism that allows several 40K BBC BASIC's to co-exist on a 128K Z88 computer. All the BBC BASIC's have a 40K continuous space while they are active and running, but when inactive (pre-empted) they occupy considerably less memory. To give memory back to the system, the enquiry entry point is used. The enquiry entry point is three bytes above the application entry point and must be in segment 3, which effectively forces all entry points into segment 3. Normally the enquiry entry point should simply return with Fc = 1. However, if Fc = 0 the memory starting from the address specified in register BC and ending at the address specified in register DE (not including the byte at (DE)) is given back to the system. The following code might be used:
.app_entry jp main_entry ; JP instruction 3 bytes long
.app_enquiry ld bc, (hole_start) ; enquiry entry point
ld de, (hole_end)
or a ; Fc = 0
ret
Bad applications not giving memory back to the system (and all other application) should use the following code for the enquiry entry point:
.app_entry jp main_entry
.app_enquiry scf ; enquiry entry point
ret
Z88 Developers Team: We've had no problems with good applications & popdowns that ignores the above <SCF> header, even though the original documentation explicitly specifies it to be coded.
Bad applications place a lot of strain on the system, by using large areas of memory. A 40K bad application which gives no memory back to the system is unlikely to co-exist well with other applications, so it is strongly recommended that if you must write bad applications you give memory back to the system. It is almost always possible to design data structures so that a continuous block can be kept empty. Programmer laziness is not an excuse to use a 40K bad application by default!
Mailboxes
The Z88 provides a facility for applications to pass on information to the next application started up. This is used by PipeDream and the Diary to read the name of a marked file from the Filer. The way this works is that the Filer drops the address and length of the name of the last marked file into a mailbox from time to time. When the Filer is exited (eg. by pressing <ESC>) the system looks at the mailbox and if there is something there, it copies the information to a safe area of memory. When another application is started it can ask the system if there is any mail. All mail is tagged by an name, which describes the type of information, and an application must give the system the name of the information it is after. If information is present then the system copies it from the safe area into the bottom stack area of the application's memory. The interface for mailboxing is provided by the OS_Sr call with the reason codes SR_WPD (write parameter data) and OS_RPD (read parameter data). See OS_Sr reference for details of parameter specification.
The system uses two information types; filenames and dates. These have the information type names of "NAME" and "DATE", both null-terminated. If you transfer information of one of these types, then you must use the appropriate name, otherwise the internal appliations will not be able to collect your mail. Similarly you won't be able to receive mail from the Filer, Calendar, Diary, etc., unless you try and read mail with these names. If you do use the mail system please inform the programmers in your documentation of the information type name you use (which should be a mnemonic upper case alpha string), so other applications can share data with yours. The internal applications use mail as follows:
Filer exports filenames
Diary imports filenames, imports dates, exports dates
PipeDream imports filenames
Calendar imports dates, exports dates
Alarm imports dates
The mailboxing system can be seen in operation using PipeDream and the Filer. Use <>FL from PipeDream and enter the Filer from this menu. Mark a file (eg. with <TAB>) and press <ESC> to return to PipeDream. The marked file will then be copied into the 'Name of file to load' field. Similarly selecting the Diary from the Calendar will set the Diary date to the date which was highlighted by the Calendar. When you go to the Calendar from the Diary, the Calendar moves to the Diary date.
Environment on entry to an application
When you enter an application the stack pointer is established and you will have a stack space of the order of 1.5K. The memory used for the stack is a shared resource, however. The 2K space between address $1800 and address $2000 is used for the following purpose:
- As the system stack. This will usually be quite lightly used, but can be quite big in some circumstances.
- For the safe and unsafe workspace which applications request. The bigger these are, the less stack you will have.
- For storing mailbox information between application switches. If a lot of lengthy mail is being passed around, the maximum stack size is reduced. We recommend that mail is restricted to a maximum of 64 bytes.
The stack space looks like this:
$2000 +------------------+
| System use |
|------------------|
$1FFD | Unsafe workspace |
|------------------|
| Safe workspace |
|------------------|
| Stack pointer |
|------------------|
| |
| Stack expands |
| downwards... |
| |
|------------------|
| Mailbox data |
$1800 | from here... |
|------------------|
$17FF | System use |
...
...
$0000 +------------------+
Even with all these demands it is unlikely that you will have much less than 1.5K to use for the stack, but clearly if you might need more space you will need to make your own arrangements, such as allocating memory and implementing you own stack procedures, or if really necessary using a bad application to provide continuous memory for a stack.
If you change the stack pointer within your application you must save the old stack pointer and restore it (below $2000 in segment 0) before making any system calls. This is because system calls swap memory banks during execution; the stack may get 'paged' out and a system crash would then most likely occur.
If your applications requires access to other banks in your card then you can use the bank switching call, OS_Mpb, to bind them in. However, your card could be placed in any of the three slots so you need to determine where your card is. This can simply be done by using OS_Mgb while running ROM'ed code and then using bank offsets relative to this value.