| Z88 Developers' Notes | ||
|---|---|---|
| Previous | Contents | Next |
22. Miscellaneous useful routines
This section explains how to manipulate system parameters, i.e. from
the Panel, the Printer Editor and other system resources. The rest of this
section displays useful routines which does not conveniently fit in any
of the other sections.
System resource parameters
These parameters are divided into 5 groups. Their mnemonic identifier is a 16bit identifier code where the high byte of the code identifies the related group:
$80xx PANEL system parameters (timeout, baud rates, date format...)Enquiries
$83xx Window management parameters.
$86xx Process management parameters.
$89xx Memory management parameters.
$8Cxx Director/CLI parameters.
The OS_Nq call is used to read the system parameters, including information on the screen, memory, available streams and settings from the Panel and Printer Editor. A call is made by loading the BC register with a reason code (the system parameter mnemonic) and the other registers with values specific to that reason code. Register changes and output specifications are different for each reason code.
Here is the call specification for OS_Nq:
RST 20H, DEFB $66
IN:
BC = reason codeOUT if call succeeded:
ADEHLIX parameters
Fc = 0Out if call failed:
Depends on BC and other arguments
Fc = 1Window Management
A = return code:
RC_BAD ($04), incorrect reason code or parameters
RC_UNK ($03), unknown request
The following enquiry calls are for fetching low level window information:
NQ_WBOX (BC = $8300), return window information NQ_WCUR (BC = $8303), return cursort information NQ_RDS (BC = $8306), read text from the screen
The above window enquiry calls are described in detail in the OS_Nq
call specification.
Process Management
The following codes return system handles in IX:
NQ_Ain ($8600) Application enquiry (system use only)Memory Management
NQ_Khn ($8603) read keyboard handle (use ":INP" device instead)
NQ_Shn ($8606) read screen handle (use ":SCR" device instead)
NQ_Phn ($8609) read printer indirected handle
NQ_Nhn ($860C) read null handle (use ":NUL" device instead)
NQ_Wai ($860F) Who am I? (system use only)
NQ_Com ($8612) read comms handle (use ":COM" device instead)
NQ_Ihn ($8615) read IN handle (use ":INP" device instead)
NQ_Ohn ($8618) read OUT handle (use ":OUT" device instead)
NQ_Rhn ($861B) read direct printer handle
NQ_Mfs ($8900) read free space information (system use only)Director and CLI
NQ_Slt ($8903) read slot type information (system use only)
NQ_Mfp ($8906) get total of free RAM pages in slot (OZ 4.2 and newer)
These enquiries return extended pointers of a null-terminated string in BHL:
NQ_Dev ($8C00) fetch current deviceDirector and CLI handles
NQ_Dir ($8C03) fetch current directory
NQ_Fnm ($8C06) fetch current filename match string
The following calls return system handles in IX
NQ_Dmh ($8C09) fetch Director special memory handle (system use only)Specifies
NQ_Inp ($8C0C) read std. input handle
NQ_Out ($8C0F) read std. output handle
NQ_Prt ($8C12) read printer stream handle
NQ_Tin ($8C15) read input-T handle
NQ_Tot ($8C18) read output-T handle
NQ_Tpr ($8C1B) read printer-T stream handle
NQ_Chn ($8C1E) read comms handle
The OS_Sp call is a companion to the OS_Nq and is used to set system parameters, notably the Panel and the PrinterEd settings. A call is made by loading register pair BC with a reason code and the other registers with values specific to that reason code. Register changes and output specifications are different for each reason code. The OS_Sp interface call is as follows:
RST 20H, DEFB $69
IN:
BC = reason codeOUT, if call succeeded:
HL = pointer to data
A = length (size) of data
Fc = 0OUT, if call failed:
Fc = 1System Values
A = return code:
RC_BAD ($04), incorrect reason code or parameter
RC_UNK ($03), unknown request
Symbol (reason code) Size MeaningApplication values
PA_Gfi ($8000) 0 Install changed settings
PA_Mct ($8001) 1 Timeout in minutes
PA_Rep ($8002) 1 Repeat rate
PA_Kcl ($8003) 1 Keyclick 'Y' or 'N'
PA_Snd ($8004) 1 Sound 'Y' or 'N'
PA_Bad ($8005) 1 Default bad process size in K
Symbol (reason code) Size MeaningSerial port values
PA_Iov ($8010) 1 Insert/Overtype 'I' or 'O'
PA_Dat ($8011) 1 Date format 'E' or 'A' (European, American)
PA_Map ($8012) 1 PipeDream map 'Y' or 'N'
PA_Msz ($8013) 1 Map size in pixels
PA_Dir ($8014) 12 Default directory
PA_Dev ($8015) 16 Default device
Symbol (reason code) Size MeaningPrinter Editor values (highlights & translation tables)
PA_Txb ($8016) 2 (or 1) Transmit baud rate - binary
PA_Rxb ($8017) 2 (or 1) Receive baud rate - binary
PA_Xon ($8018) 1 Xon/Xoff 'Y' or 'N'
PA_Par ($8019) 1 Parity 'O', 'E', 'M', 'S' or 'N'
Symbol (reason code) Size MeaningThe format of each highlight sequence is as follows:
PA_Ptr ($8020) 9 Printer name
PA_Alf ($8021) 1 Allow Linefeed, 'Y' or 'N'
PA_Pon ($8022) 31 (max) Printer On sequence
PA_Pof ($8023) 31 (max) Printer Off sequence
PA_Eop ($8024) 31 (max) End of page sequence
PA_Mip ($8025) 31 (max) HMI prefix sequence
PA_Mis ($8026) 31 (max) HMI suffix sequence
PA_Mio ($8027) 31 (max) HMI offset sequence
PA_On<n> 31 (max) Highlight ON sequenceThe printer editor has a facility for overprinting characters, which is most often used to implement underlining on certain printers, by printing a character followed by a backspace and an underline character. The user enter a ? (query), to represent the character being printed, in the ON sequence (the OFF sequence being blank), and this sequence is output for every character with the current character being substituted for the query. Internally the Printer Editor usually represents the current character as an $FF (it will show up like this in the Printer Editor, if a string is installed, updated, and the Printer Editor is KILL'ed and re-entered). However, because it might be necessary to use an $FF in your overprinting sequence, it is possible to change the internal representation of the current character to some other value. If you want to use an overprinting sequense you must set up PA_SP<n> yourself and use your value in the ON string to represent the current character. To implement backspace underlining you might set the ON sequence and special character like this:
PA_On<n>+1 31 (max) Highlight OFF sequence
PA_On<n>+2 1 OFF at CR 'Y' or 'N'
PA_On<n>+3 1 Highlight n special character
PA_ON1 255,8,95 eg. ?, BS, "_"Highlight bases
PA_SP1 255 special highlight character
PA_On1 ($8028) UnderlineTranslations
PA_On2 ($802C) Bold
PA_On3 ($8030) Extended sequence
PA_On4 ($8034) Italics
PA_On5 ($8038) Subscript
PA_On6 ($803C) Superscript
PA_On7 ($8040) Alternate font
PA_On8 ($8044) User Defined
The format of each translation code sequence is as follows:
Symbol (reason code) Size MeaningPA_Fr<n> will normally be one character long. If there are more characters in this sequence then the first character is replaced by the translation string, nut the others are printed as well.
PA_Fr<n> (base+0) 31 (max) Translate from character
PA_To<n> (base+1) 31 (max) Translate to sequence
Symbol (reason code) Size Meaning
PA_Tr1 ($8048) Row 1, Entry A
PA_Tr2 ($804A) B
PA_Tr3 ($804C) C
PA_Tr4 ($804E) Row 2, Entry A
PA_Tr5 ($8050) B
PA_Tr6 ($8052) C
PA_Tr7 ($8054) Row 3, Entry A
PA_Tr8 ($8056) B
PA_Tr9 ($8058) C
International versions of the machine have an extra page of 28 translations (using the <>ISO command). The reason codes for these translations start at $8080 up to $80B6.
The settings do not come into effect until OS_Sp is called with the reason code PA_GFI and A = 0, which installs both the Panel and Printer Editor values. No error checking is done, so make sure the values are valid.
In addition to the Panel and Printer Editor, the following parameters can be set. They expect HL to point to a null-terminated string:
SP_Dev ($8C00) Set current deviceInterrupts
SP_Dir ($8C03) Set current directory
SP_Fnm ($8C06) Set current name match
Two system calls are available to enable and disable interrupts. It is very important to use these calls and not use the Z80 interrupt instructions because of a hardware bug in the Z80, which allows for interrupts to occur while reading the interrupt status. Note that disabling interrupts should be avoided if possible and that NMI (Non Maskable Interrupts) will still occur. If a HALT is executed when interrupts are disabled the system will stop. HALT should not be used anyway, nor should EI, DI or IM <n>.
CALL $0051
IN:
-OUT:
A = old I registerRegisters changed after return:
Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled)
..BCDEHL/IXIY sameOZ_EI, restore old interrupt state
AF....../.... different
CALL $0054
IN:
A = old I register
Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled)
OUT: -
Registers changed after return:
AFBCDEHL/IXIY sameThus one might do:
......../.... different
call OZ_DIand be assured for the interrupt status is preserved.
push af
; operations requiring disabled interrupts
pop af
call OZ_EI
Save and restore
The OS_Sr call was designed for internal use, but has a three rather handy features which can be used by applications:
RST 20H, DEFB $6C
IN:
A = reason code:OUT, if call successful:
SR_SUS ($01) Save user screen
SR_RUS ($02) Restore user screen
SR_WPD ($03) Write parameter data (mailbox)
SR_RPD ($04) Read parameter data (mailbox)
SR_FUS ($05) Free user screen
SR_CRM ($06) Remove card (system use only)
SR_CIN ($07) Insert card (system use only)
SR_PWT ($08) Page wait
SR_RND ($09) Occasionally a random number (system use)
BC = arguments
DE = arguments
HL = arguments
IX = arguments
Fc = 0OUT, if call failed:
returned values depend on A(in)
Fc = 1This is a very powerful call, but should not be over used. Most of the time it is perfectly possible to regenerate a screen without resorting to this kind of sledge-hammer approach, requiring around 2K a time. It is probably preferable to use this call, rather than making your application one which has its screen saved automatically (as BBC BASIC), if there are only a few situations in your application where saving the screen is essential. One final point is that it is essential to check that the call was successful and to try and cope if it fails, as it is likely to do on an unexpanded heavily used machine. Please refer to OS_Sr reference for parameter call details.
A = error code:
RC_UNK ($03), unknown request
RC_BAD ($04), bad arguments
RC_HAND ($08), bad handle
RC_ROOM ($07), no room
RC_SUSP ($69), with SR_PWT
RC_DRAW ($66), with SR_PWT
RC_QUIT ($67), with SR_PWT
SR_SUS ($01) Save user screen
SR_RUS ($02) Restore user screenRestores the previously saved image and releases the corresponding memory. Please refer to OS_Sr reference for parameter call details.
SR_FUS ($05) Free user screenThis performs the function of freeing the memory that was used to save a screen but without actually affecting the screen image. Please refer to OS_Sr reference for parameter call details.
SR_WPD ($03) Write parameter data (mailbox)Please refer to OS_Sr reference for parameter call details. Mailboxing is explained in greater detail in "Application Static Structures".
SR_RPD ($04) Read parameter data (mailbox)
SR_PWT ($08) Page waitThis call displays the page-wait message at the edge of the screen and then does the equivalent of OS_In. It is very important that you check for all pre-emption codes, especially RC_QUIT, when using this call if they are not coped within an error handler. Please note that a successfull return only return keyboard output with A = <BACKSPACE> ($08), and otherwise the error return codes. When output is redirected, page waits are conveniently surpressed. Please refer to OS_Sr reference for parameter call details.
SR_RND ($09) Occasionally a random number (system use)The return value (random number) only changes when certain operating system functions occur in between calls to OS_Sr. Repeated fetching a random number may well result in the same value being returned!
Fast code
Some operations, such as bank switching, can take up quite a lot of processing time. In order to speed up such tasks the operating system provides a facility for making certain system calls operate more rapidly. The fast code interface call provides a fragment of code to perform a particular task and places it an address supplied by the application. The current version of the Z88 has only one fast code routine which is to rapidly switch bank bindings.
RST 20H, DEFB $8A
IN:
A = 1, for fast bank switchingOUT:
DE = address to copy fast bank code into
HL = 0, for code to terminate with RET
HL <> 0, for code to terminate with JP (HL)
C = segment for bank switching (MS_Sx)
Fc = 0Registers changed after return:
A = code size
..BCDEHL/IXIY same
AF....../.... different
The OS_Fc fast bank switching code has now been established. Subsequent calls to OS_Fc with:
IN: A = bank to bind to segment specified by OS_Fc initializationOUT:
AFBCDEHL/IXIY/afbcdehl sameNotes:
......../..../........ different
OS_Fc has only been implemented with the above bank switching routine.
The bank switching code can now be accessed at the address supplied in DE(in). If HL(in) = 0 then use CALL DE(in), else use JP DE(in).
Bank switching is a fairly simple process of updating a softcopy and writing to a hardware register. The reason for using the fast-code interface is that on any future versions of the machine the application will still work even though the bank switching process may be different. For this reason at least 30 bytes should be available for the code. Since the actual length is returned, memory can be reclaimed if necessary. One final point to bear in mind is that you must not place the fast code in the segment which it is rebinding! Think of cutting the branch you are sitting on...
| Previous | Contents | Next |
| The Map Area | Miscellaneous useful routines | Miscellaneous useful information |