Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File9.1  About XCONTROL                                                TOS

XControl is a modular (extendable) control field desk accessory that 
was first shipped by Atari with the TT030 and Mega-STE series of 
computers.




The individual modules are files with the extension '.CPX' (Control 
Panel eXtension), and XControl itself can be taken as the control 
program for these modules.

Important: XControl should be used only as a tool for configuration 
dialogs, and not misused for other purposes.

The communication between XControl and its modules takes place via two 
structures that are denoted XCPB and CPXINFO. The former makes some 
flags as well as a whole string of help functions available.

At system start-up XControl loads all available CPX headers, using up 
to 512 bytes of system memory per header; provided the corresponding 
flag is set in the header, each of the CPX files is called once for 
initialization. One can specify for each individual module whether it 
is to be loaded as resident or not (this can be changed also with the 
bundled configuration CPX). In addition it is possible to write CPX 
modules that set only certain values; these so-called 'set only' 
modules are called only during booting or renewed loading of the CPX 
modules with XControl, and simply return a NULL-pointer during the 
initialization.

As soon as a user selects a CPX module, XControl loads it into memory 
and calls the function cpx_init. Subsequently cpx_call is called, for 
which essentially the module itself now takes control.

One can differentiate between a Form CPX and an Event CPX. The former 
are relatively simple to program, but offer only limited flexibility. 
The latter are more flexible, since they evaluate the AES events 
directly. All the CPX modules supplied with XControl 1.0 are Form CPX 
files, from which one can deduce that Form CPXs suffice in most cases.

The following terminology applies for the filenames of CPX modules:

 Suffix   Meaning 
 *.CP     Standard CPX without header 
 *.CPX    Standard CPX, ready for use 
 *.CPZ    Inactive CPX (deactivated by XControl) 
 *.HDR    Header for the CPX file 
 *_R.CPX  Resident CPX file 
 *_S.CPX  Set-only CPX file 

The format of a CPX file is very similar to that of a normal program. 
It consists of a 512-byte header and the remaining file content that 
is almost a normal GEMDOS program file, including a standard 28-byte 
GEMDOS header.

typedef struct
{
    uint16_t magic;                 /* Magic constant = 100   */

    struct
    {
        unsigned reserved : 13;  /* Reserved                */
        unsigned resident :  1;  /* RAM-resident if set     */
        unsigned bootinit :  1;  /* Boot initialize if set  */
        unsigned setonly  :  1;  /* Set-only CPX if set     */

    } flags;

    int32_t  cpx_id;                /* Unique CPX ID                   */
    uint16_t cpx_version;           /* CPX version number              */
    int8_t   i_text[14];            /* Icon text                       */
    uint16_t sm_icon[48];           /* Icon bitmap (32*24 pixel)       */
    uint16_t i_color;               /* Icon colour                     */
    int8_t   title_text[18];        /* Name of the CPX (16 chars. max) */
    uint16_t t_color;               /* Text colour                     */
    int8_t   buffer[64];            /* Non-volatile buffer             */
    int8_t   reserved[306];         /* Reserved                        */

} CPXHEAD;

Some notes about the header:

   . The first function in the TEXT segment has to be the 
     initialization routine for the CPX
   . There are everal toolkits for the construction of a CPX header
   . Header and linked program file can be joined in most UNIX-like 
     shells (e.g. Mupfel from Gemini) with the command 'cat'
   . During CPX development it is very practical that XControl can be 
     launched also as a program (alter the suffix!); this allows 
     working without permanent rebooting of the computer
   . CPX ID and version number ensure that each CPX appears only once 
     (and also only the latest version)

While programming a CPX module one should note some subtleties: As 
such a module has no non-volatile memory available (apart from 64 
bytes), nothing is permitted that reserves fixed memory in any way. In 
particular, all variable contents are lost when leaving the CPX as a 
rule!

Hence one should:

   . Incorporate resources statically
   . Only permit short-term memory allocation
   . Not create permanent virtual VDI workstations

For the programming of a CPX module one can fall back on the functions 
from the following categories:

   . CPX functions

   . XCONTROL functions

Note: There are several alternatives to XCONTROL, which is not being 
developed by Atari any more. One that is particularly recommended is 
COPS (COntrol Panel Server, which not only permits simultaneous 
opening of any mumber of CPX modules, but also allows control fields 
with a larger working area than XCONTROL.

Other alternatives are ZCONTROL and a supplementary function of the 
Freedom2 file-selector.