Miscellaneous useful routines

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...)
$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:

OS_Nq, enquire

RST 20H, DEFB $66

IN:

            BC = reason code
            ADEHLIX parameters

OUT if call succeeded:

            Fc = 0
            Depends on BC and other arguments

Out if call failed:

            Fc = 1
            A = return code:
                        RC_BAD ($04), incorrect reason code or parameters
                        RC_UNK ($03), unknown request

Window 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 call specification.

Process Management

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 handle

Memory 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 string

Director 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 handle

Specifies

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:

OS_Sp, specify

RST 20H, DEFB $69

IN:

            BC = reason code
            HL = pointer to data
            A = length (size) of data

OUT, if call succeeded:

            Fc = 0

OUT, if call failed:

            Fc = 1
            A = return code:
                        RC_BAD ($04), incorrect reason code or parameter
                        RC_UNK ($03), unknown request

System 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 K

Application 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 device

Serial 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 sequence

The 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 character

The 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 character

Highlight 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 Defined

Translations

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)                      C

PA_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 match

Interrupts

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

OZ_DI, disable interrupts

CALL $0051

IN:

OUT:

            A = old I register
            Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled)

Registers changed after return:

            ..BCDEHL/IXIY same
            AF....../.... different

OZ_EI, restore old interrupt state

CALL $0054

IN:

            A = old I register
            Fc = old interrupt status (Fc = 1 disabled; Fc = 0 enabled)

OUT:        -

Registers changed after return:

            AFBCDEHL/IXIY same
            ......../.... different

Thus one might do:

            call OZ_DI
            push af

            ; operations requiring disabled interrupts

            pop  af
            call OZ_EI

and 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:

OS_Sr

RST 20H, DEFB $6C

IN:

            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 = arguments

OUT, 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_PWT


SR_SUS ($01)            Save user screen

This 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_RUS ($02)            Restore user screen

Restores the previously saved image and releases the corresponding memory. Please refer to OS_Sr reference for parameter call details.

SR_FUS ($05)            Free user screen

This 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 wait

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

OS_Fc, select fast code (fast bank switching)

RST 20H, DEFB $8A

IN:

            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 size

Registers 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 initialization

OUT:

            AFBCDEHL/IXIY/afbcdehl same
            ......../..../........ different

Notes:

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