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.
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.