Changes
/* Examples */
The Task now knows that it has been saved successfully. The Task now needs to reset the 'Secured Bit' and jump to address &4000.
Tasks saved by the Caruh system are loaded (like any other) to address &4000 and also started there.
= OS functions for Tasks =
The Tasker Caruh provides several additional OS functions for Tasks.
Furthermore, certain parameters can be queried from RAM variables.
Please refer to the chapter on Task variables above.
=== Caruh's GUI and OS functions ===
Both screen mode and screen format can be set by the user in Caruh.
This is done using options.
These settings can be read from the following RAM variables:
* Memory address &000E contains the screen mode (0-3) which was set by the user. Each task can read the desired screen mode from this byte if the Task is switched to the Foreground.
* Memory address &000F contains the screen format (0 for 80x25, 1 for 68x30 and 3 for 64x32 format) that was set by the user. Each Task can read the desired screen format from this byte if the Task is switched to the Foreground.
* MENU SYSTEM
The 'M_DISP2' menu system known from CBM can be called up with the 'RST 1' command. For parameter transfer see source code.
* DRAW WINDOW
The 'DR_WIN' window drawer known from CBM can be called with 'CALL &000B'. To call DR_WIN:
HL = Pointer to start of Parameter- and Text-Block
'''Such a data block looks like this:'''
DB LOCATE_YY ;Upmost line
DB LOCATE_XX ;Leftmost row
DB LINES ;Number of lines in Window-Frame
DB ROWS ;Number of rows / columns
DB "Sample text",&00 ;Text of first line, terminated by byte &00
Now the text of the following lines may follow here...
Every line must be terminated by an &00 byte
A text line can use control codes for screen MODE 2
As for example the locate control code (80x25 format):
DB &1F,YY,XX,"Text sample",&00
'''ATTENTION:''' DR_WIN at &000B will switch the Interrupts OFF. The calling Task must switch them on again by itself.
* REQUEST SQUARE ON COMMON SCREEN SOMEWHERE
Calling the 'SAOMS' function at address &0003 allows the user to reserve a piece of the general multi-screen (regular view).
This OS function must be called by a Task.
'''To call this function:'''
Task number in TTNS3 = &BE03 (A Task can read its number from address TNUME = &7FFD)
YL = Total number of rows of area to be reserved (width, MODE 2 chars)
YH = Total number of lines of the area to be reserved (height)
'''Return from function:''' First you need to take a look at the Z-Flag, then see for data in XL and XH.
Z-Flag set '1' -> User Break using ESC key! Do not use values in IX!
Z-Flag cleared -> All fine! -> See registers XL and XH: XL = Upmost line / Y position of frame (0-24). XH = Leftmost raw / X position of Frame (0-79)
* REQUEST DEFINED SQUARE ON COMMON SCREEN ON DEFINED POSITION
If the 'RFMSA' function is called using the 'CALL &0013' command at address &0013, a Task can use it to reserve a part of the shared screen. The parameters are required as follows:
XL = Upmost line / Y position of frame (0-24)
XH = Leftmost raw / X position of Frame (0-79)
YL = Total Rows of Frame (1-80)
YH = Total Lines of Frame (1-25)
Address (TTNS3 = &BE03) = Number of requesting the Task
'''Return from function:''' When returning, the zero flag provides information about the success:
Z-Flag cleared -> Areas overlapping! Area can NOT be used!
Z flag set '1' -> Requested area CAN be used!
* SET PRIORITY OF A TASK
If the function 'SEPRI' is called using the Z80 command 'RST 2' at address &0010, a Task can change its priority (new priority in A).
Each task is started with the highest priority '1' after loading.
Often, however, a Task does not have to be called up that often (e.g. display time or temperature, send data to the printer, etc.). In such a case, the priority can be reduced.
The new priority is transferred in the accumulator; values from 1 to 255 are permissible. Smaller values have higher priority.
* If a task currently has nothing to do, it can actively switch to the next Task. This is done using the commands:
DI ;Disable interrupts (command before each 'RST 7' necessary!)
RST 7 ;Call up the Task Manager or the next Task
* Testing the content of address &7FFB on &7x allows integrity tests. Since the E-RAM status (high byte) is read here, the upper nibble must be '7'. If it's not equal to '7', the task E-RAM has been corrupted!
= Examples =
== Set a regular Background Task as the Foreground Task ==
If any Background Task is made the only Foreground Task, then control of the
screen and keyboard scanning is passed to that new Foreground Task.
This is done either using the Task function 'Switch <t>o' of Caruh's menu or by clicking on one of the four Task names in the task bar (at the bottom of the screen).
This process cannot be initiated by the Task itself. However, if the user wants to switch a Task to the Foreground, this Task must also be able to react to it!
== Process log: A Background Task becomes a Foreground Task ==
* Caruh reads and evaluates byte at memory location &7FF8 (TCON8) of the task:
If bit 1 is cleared, the task cannot become a Foreground Task!
If bit 1 is set, however, the task can be switched as a Foreground Task
* Caruh now sets bit 0 of memory location &7FF8 (TCON8) in the E-RAM of the Task to '1'. This tells the Task that it has now become the Foreground Task. The Task must now take control of the screen and the keyboard scanning.
* To inform Caruh that the Task has taken over screen control, the Task must set bit 0 in memory location &BE02 (CCON2). As soon as this bit is set, Caruh will relinquish screen control.
* At this point Caruh is now waiting for bit 0 to be set to '1' at address &BE02 (CCON2)! If that does not happen, Caruh will take over control again after a while (90 * DI: RST 7), as the Task appears incapable of doing so.
* As soon as bit 0 at address &BE02 (CCON2) is set to '1', Caruh waits for it to be reset in order to take control back again. See next paragraph
* The screen and keyboard are now available to the newly baked Foreground Task. Now it makes sense to first clear the screen, set the screen MODE 0-2 and possibly the screen format.
* The foreground task takes its course ...
* It's essential to test for 'ESCape' being pressed and to give control back to Caruh when the user's using the 'ESCape' key.
How does it work?
Continue reading please ... ;-)
== How can a Foreground Task return control to Caruh? ==
When a Task has taken control of the screen and keyboard, it must also test whether the ESC key is pressed. If this is the case, control must be returned to Caruh.
The same applies if the Task simply wants to give back control.
* The Task deletes bit 0 at address &7FF8 (TCON8) in its own E-RAM. This turns the Task into a Background Task (regular state). But the Task also has to tell Caruh! This is how it happens ...
* The Foreground Task also deletes bit 0 at address &BE02 (CCON2)!
* As soon as bit 0 at address &BE02 (CCON2) is cleared, Caruh takes control of the screen and keyboard (as before). The former Foreground Task is now working in the Background again.
* Caruh is in the Foreground again :-)
'''Note:''' If the newly appointed Foreground Task is not able to set bit 0 of memory address &BE02 (CCON2) to 1, the Foreground status will be withdrawn after 192 cycles (192 times 'DI: RST 7')!
That means nothing else than that Caruh will take control again.
== Reserve parts of the common screen ==
It's possible for each task to use certain parts of the general screen.
The position and extent of the claimed area are transferred. This request can be approved or rejected, depending on whether the claimed area is available.
This way it's possible for each task to always reserve the same sections for itself, since it can remember the coordinates of the first-time selection.
Either by saving the Task, using nvRAM or a configuration file.
The screen is divided into 80 columns (0-79) and 25 lines (0-24).
The table begins with the leftmost character on the top line.
When the Caruh system is started, Caruh reserves the first four lines (0-3) and
the bottom line (24).
This is how a Task can reserve a part of the general screen:
Entry (from the Task) at address &0003
'''Parameter:'''
The number of the reserving Task is stored in TTNS3 = address &BE03
The number of MODE 2 columns is transferred in register YL
The number of lines is transferred in register YH
The command 'LD IY, &0309' would therefore display 3 rows and 9 columns
* The current table is now graphically displayed on the screen. Only every 'empty' position can be assigned. A box - consisting of lines - can now be moved using the cursor keys and pressing Copy reserves the corresponding area of the screen and enters the position in the multi-screen Table.
* If the frame can't be set at the current position, the BORDER is shown in orange color (15). Either a valid area is found or the process can be canceled using the 'ESC' key.
* The Task is finally informed whether the setting of the frame was successful.
Furthermore, X (0-79 in XL) and Y (4-23 in XH) coordinates are transferred. These correspond to the left (XL) and upper (XH) corner on the screen. Register IX contains these two values.
In addition, the corresponding screen address of the top left corner is transferred (in RAM variable C_POS).
