|Z88 Developers' Notes|
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...) $83xx Window management parameters. $86xx Process management parameters. $89xx Memory management parameters. $8Cxx Director/CLI parameters.Enquiries
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
BC = reason code ADEHLIX parametersOUT if call succeeded:
Fc = 0 Depends on BC and other argumentsOut if call failed:
Fc = 1 A = return code: RC_BAD ($04), incorrect reason code or parameters RC_UNK ($03), unknown requestWindow Management
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
The following codes return system handles in IX:
NQ_Ain ($8600) Application enquiry (system use only) 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 handleMemory Management
NQ_Mfs ($8900) read free space information (system use only) NQ_Slt ($8903) read slot type information (system use only)Director and CLI
These enquiries return extended pointers of a null-terminated string in BHL:
NQ_Dev ($8C00) fetch current device NQ_Dir ($8C03) fetch current directory NQ_Fnm ($8C06) fetch current filename match stringDirector and CLI handles
The following calls return system handles in IX
NQ_Dmh ($8C09) fetch Director special memory handle (system use only) 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 handleSpecifies
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
BC = reason code HL = pointer to data A = length (size) of dataOUT, if call succeeded:
Fc = 0OUT, if call failed:
Fc = 1 A = return code: RC_BAD ($04), incorrect reason code or parameter RC_UNK ($03), unknown requestSystem Values
Symbol (reason code) Size Meaning 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 KApplication values
Symbol (reason code) Size Meaning 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 deviceSerial port values
Symbol (reason code) Size Meaning 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'Printer Editor values (highlights & translation tables)
Symbol (reason code) Size Meaning 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 sequenceThe format of each highlight sequence is as follows:
PA_On<n> 31 (max) Highlight ON sequence 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 characterThe 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_ON1 255,8,95 eg. ?, BS, "_" PA_SP1 255 special highlight characterHighlight bases
PA_On1 ($8028) Underline 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 DefinedTranslations
The format of each translation code sequence is as follows:
Symbol (reason code) Size Meaning 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) CPA_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.
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 device SP_Dir ($8C03) Set current directory SP_Fnm ($8C06) Set current name matchInterrupts
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>.
A = old I register Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled)Registers changed after return:
..BCDEHL/IXIY same AF....../.... differentOZ_EI, restore old interrupt state
A = old I register Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled) OUT: - Registers changed after return:
AFBCDEHL/IXIY same ......../.... differentThus one might do:
call OZ_DI push af ; operations requiring disabled interrupts pop af call OZ_EIand be assured for the interrupt status is preserved.
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
A = reason code: 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 = argumentsOUT, if call successful:
Fc = 0 returned values depend on A(in)OUT, if call failed:
Fc = 1 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_PWTThis 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.
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) SR_RPD ($04) Read parameter data (mailbox)Please refer to OS_Sr reference for parameter call details. Mailboxing is explained in greater detail in "Application Static Structures".
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!
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
A = 1, for fast bank switching 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)OUT:
Fc = 0 A = code sizeRegisters changed after return:
..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 same ......../..../........ differentNotes:
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...
|The Map Area||Miscellaneous useful routines||Miscellaneous useful information|