The Manual to
zControl
0.23
December 27, 1995
by
Ralf Zimmermann
Am Ruhwehr 35
D-65207 Wiesbaden
dl1fdt@amsat.org
Contents
========
1 This Version
1.1 English Version
2 Orlando/Florida
3 Copyright
3.1 Shareware
3.2 UK Register
3.3 Price List
4 Motivation
5 Installation
6 Operating the program
6.1 Main dialogue
6.2 Popup-Dialogue 'Options'
6.3 Settings
6.4 Choice Modules
6.5 Select a module
6.6 Activate a module
6.7 Keyboard Handling
6.8 Command Line Parameters for zControl
6.8.1 Anwendung anmelden
6.8.2 AV Protocol
6.8.3 Drag&Drop
6.9 Iconify
7 The INF File
7.1 Debug Function
7.2 Where will the INF file be searched?
8 Undocumented Functions
8.1 KONFIG.CPX
8.2 LINK_CPX.CPX
8.3 DFREE.CPX
Appendix
========
A The Format of the INF File
B The Format of the FILESORT.SYS file
C Sources of supply
D Thanks
E Troubleshooting
F History
1 This Version
==============
This program is not finished! I'd like to describe it as a *very good
tested* Beta-Version.
At this time I have not the time to implement all the things I'd like
to see in the program. And I can't say when I will have the final
version. Within the last few months some people have been asking when
zControl would come. So I decided to release this version to the
public - the program works without major problems. As soon as I have
some more time I will release a new version!
'Without major problems' means:
In this version zControl runs as ACC only under multitasking systems.
As soon as you try to start it under Single-TOS, such as TOS 3.06, as
a ACC you get some bombs.
Until now I didn't know what the problem is and therefore I can't
change it. I am using MagiC!3 and MagicMac and have no problems with
zControl. So let's hope for a magic idea for the future. From then on
zControl will be fully usable for all users, even these with Single-
Tasking systems.
As an ACC under Single-TOS you get a warning message while booting.
No CPX modules will be loaded. You can load the modules afterwards.
If you get problems with this procedure I would appreciate a bug
report to me. Please tell me something about your configuration:
Computer, memory, operating system, HD-driver, AUTO-folder-
programs...
Since version 0.22 there is the option SINGLELOAD. With it, zControl
works normal under Single-TOS - the modules will be loaded. This
option is for testing purposes. In chapter "The Format of the INF
File", you can read how to use it.
*Whoever tries this option under Single-TOS, should write me a report
via email.* Here in Florida I don't have a computer with Single-TOS,
this is why I depend on those reports.
1.1 English Version
-------------------
Version 0.20 of zControl had an English documentation, the version
0.21 now can run in English (and German of course).
In the future, maybe, there will be other languages supported.
Please note: There is an German version of this manual.
2 Orlando/Florida
=================
From end of July 95 to mid of March 96 I am in Orlando/Florida. I am
finishing my studies here. Although Orlando is a very nice place to
stay - I can not access all the Atari equipment I have at home in
Germany. This results in a restricted ability to test this program. I
am sorry for that.
3 Copyright
===========
zControl is a Shareware program by
Ralf Zimmermann
Am Ruhwehr 35
65207 Wiesbaden
Germany
MausNet : Ralf Zimmermann @ OF2
internet : dl1fdt@amsat.org
PacketRadio : DL1FDT@DB0GV
Bank Account:
Nassauische Sparkasse Wiesbaden
Bank code number 510 500 15
Account number 1010 299 72
The fastest way to reach the author should be to use the email!
3.1 Shareware
-------------
This program is distributed as Shareware. This means you can test
this program without any restrictions. By testing I consider 3 weeks.
After this time you should know if you want to use this program or
not.
Which restrictions does this program have in the public version?
*- None -*
There is no other version of zControl! All features of this program
are *not* restricted! Therefore zControl is a *real* representation of
Shareware.
By registering the program you pay for a program that you already
have and that you were able to test thoroughly. I think there is no
fairer way to distribute software. I hope it works.
If you like the program and want to use it in the future, you have to
register it. This can be done by paying the Shareware fee of DM10 to
the author through remittance, cash or crossed cheque, or sending the
registration fee too the appropriate support site.
Please note the following: If you use a Shareware program without
registering, you are using an unauthorized copy!
Standard-Disclaimer:
This program was made carefully. The author is not responsible
for any damages that originate from the usage or non-usage of
zControl.
3.2 UK Register
---------------
UK users may register for zControl via CyberSTrider, the shareware
support scheme run by Denesh Bhabuta. The UK shareware fee for
zControl currently stands at 6 Pounds Sterling, which entitles you to
ù A printed labelled Master Disk with the latest version of
zControl, plus a selection of other shareware supported by
Denesh.
ù Free e-mail, post and telephone support
ù Free update service (as long as the registration fee does not go
up, or it becomes commercial)
If you use zControl, then you must register. Make cheques, postal
orders, international money orders, and eurocheques payable to DENESH
BHABUTA, for the sum of 6 Pounds Sterling (overseas users please add
1 pound), and send with your details to:
CyberSTrider
203 Parr Lane
Unsworth
Bury
Lancashire
BL9 8JW
England
E-mail: dbhabuta@cix.compulink.co.uk
danny@micros.hensa.ac.uk
*Free Update Service*
Registered users may benefit from the free update service by sending
an unlabelled blank floppy disk and stamped self addressed envelope
to Denesh at the above address.
3.3 Price List
--------------
If you register zControl directly at the author, the price to
register one user presently is:
DM 10,-
4 Motivation
============
Since TOS 2.00 you get the XCONTROL.ACC from Atari. It is the
environment for CPX modules. These are modules for configurating your
computer or programs. There are for example modules to configure the
serial interface, the keyboard or the printer. Some modules come with
their own CPX modules. All CPX modules have the file extension
'.CPX'.
The modules do not run without a modular Control Panel (zControl or
XControl)!
We all know that XControl has some nasty bugs. That was the beginning
of my idea to build an alternative.
*zControl is made to be this alternative.*
It loads the same CPX modules as XControl and behaves almost
compatible, as far as the documentation recommends that.
The advantages in contrast to XControl are quite obvious:
ù zControl will be developed in the future, all known bugs will be
removed.
ù zControl supports following protocols:
- Drag&Drop
- Iconify
- AV-protocol
This means that the program fits perfectly into modern user
interfaces.
ù zControl enables you to run up to four different modules at the
same time! Each module runs in its own window.
ù zControl can be controlled through the keyboard.
ù zControl has some more useful features, you may have looked for.
5 Installation
==============
Copy the file ZCONTROL.ACC to the root directory of your boot drive.
Generate a folder named CPX and copy all your CPX modules into that
folder. The folder can be named differently. Then reboot.
Now call the program through the entry in the menu. Click on the
button 'Options' on the main dialog. Choose 'Settings...' in the
popup dialog you get. You get a file selector dialog. Please show
zControl the folder from which the modules should be loaded in
future. Usually this should be the folder
C:\CPX\
Click on the button 'Save' and confirm the security dialog. After
that, zControl should search the CPX modules in the correct folder
while starting.
Under multitasking systems you can run zControl as an application.
Change the file extension from .ACC to .APP or .PRG and you can use
zControl as a normal program.
6 Operating the program
=======================
In the following pages you will learn how to operate the program.
6.1 Main dialogue
-----------------
After entering the program you get the main dialogue. You can see
which programs are loaded and therefor are available. If more modules
were found than fit into the dialogue (as usual), you can scroll to
the other modules by using the vertical slider to the right.
ATTENTION:
The beta version of zControl has a scrolling window name. This should
remind you that this is only a beta version. As soon as the final
version is finished this 'feature' will disappear.
6.2 Popup-Dialogue 'Options'
----------------------------
ù Info...
You can get a short copyright information about this program.
You will find the version number in this dialogue.
ù Settings...
You get to an dialogue where you can configure the program.
ù Open CPX...
You can activate a selected module with this popup entry as if
you make a double click on the module entry.
ù CPX Info...
You can get some information about the selected module.
ù Remove CPX...
The selected module will be removed from the memory.
6.3 Settings
------------
In this dialogue you can
ù reload CPX modules.
ù switch to the dialogue 'Choice Modules'.
ù change the number of CPX entries on the main dialogue.
ù change the language used by zControl. Right now English and
German are available.
ù change the folder in which zControl looks for the CPX modules.
6.4 Choice Modules
------------------
In this dialogue you can change the selection of modules that will be
loaded next time by zControl. Active modules in the list are marked
with a hook.
You can change the status of a module (active/inactive) through a
click on the entry.
Note: De/activating is made by changing the file extension of the
module. Active modules have the extension '.CPX', inactive modules
have the extension '.CPZ'.
6.5 Select a module
-------------------
You can select a module easily by clicking with the left mouse button
on the module entry. The selection is visible through the inverted
display of that entry. If you have a selected module, you get more
options in the 'Options' popup dialog.
6.6 Activate a module
---------------------
You can activate a module through
ù a double click with the mouse on the entry.
ù pressing the Return key while the entry is selected.
(see Keyboard Handling)
ù a VA_START message.
ù a Drag&Drop message.
Each activated module has it's own window. Presently you can have up
to four CPX windows at the same time. This number is arbitrary and
may be changed in future versions.
6.7 Keyboard Handling
---------------------
In the main dialogue zControl can be controlled via the keyboard:
Cursor Up - Moves the selection bar one entry to the top.
- If there is no selection before, the lowest
entry will be selected.
Cursor Down - Moves the selection bar one entry down.
- If there is no selection before, the highest
entry will be selected.
Shift Cursor - Moves the selection bar one page.
Return
Enter - If there is a selection, the selected module
will be activated.
- If there is no selection, the window will be
closed.
Esc - If a selection exists, it will be removed.
Control-U
Control-Q - The window will be closed.
Control-Alternate-Space
- The window will be iconified.
(see Iconify)
6.8 Command Line Parameters for zControl
----------------------------------------
While starting zControl as a program, you can hand over parameters.
Presently the command line is only searched for names of CPX modules.
If the module is found, it will be activated.
zControl also accepts deactivated modules, with the file ending CPZ.
6.8.1 Anwendung anmelden
It is recommended that you announce zControl as application for the
file extension '*.CPX'. On the Atari desktop you can do this by
selecting the program and selecting 'Anwendung anmelden' in the menu.
You enter the extension 'CPX' for the program. You have to save this
adjustment through selecting 'Arbeit sichern' in the menu.
If you now double click on a CPX file, zControl will be activated and
the CPX file will be activated. Through this, you have the option to
put some CPX modules as icons on the desktop and having them
activated directly by double clicking.
With the desktop replacement 'Gemini' you can activate the option
'Versteht VA_START-Meldung' in the dialog 'Anwendungen...'. If
zControl is already started and you request a CPX module, Gemini
hands the name of the module via a VA_START message.
Hint:
You can make an empty file with the extension .CPX which you can use
for activating zControl. My dummy file for example is named _CALL.CPX
and has the size of 0bytes. This file lies as an icon on my desktop.
A double click on this file activates zControl if used as an ACC.
6.8.2 AV Protocol
zControl knows the VA_START message of the AV protocol. The name of
the CPX module will be the parameter. If the module is loaded, it
will be activated. If not, zControl will try to load it.
zControl also knows the VA_DRAGACCWIND message. In Gemini you can
drag a CPX file to the window of zControl. This works like Drag&Drop.
6.8.3 Drag&Drop
zControl knows the Drag&Drop protocol. If you have a operating system
which is capable of Drag&Drop, you can drag a CPX file from the
desktop and drop it onto the window of zControl.
After that, zControl will load the module and activate it.
The following TOS compatible operating systems are capable of the
Drag&Drop protocol:
ù MultiTOS with an AES >= 4.1
ù MagiC! 3.0
ù MagiCMac (on the Apple Macintosh)
6.9 Iconify
-----------
Iconify means the reduction of a normal GEM window to the minimal
size. The window then is very small and shows a symbol in it, not the
original contents. If you have many opened windows, it sometimes is
comfortable to get some of the windows out of the way.
zControl knows two different ways of Iconify:
ù MultiTOS-Iconify
Under MultiTOS you have an iconify button on the right top of
the window. If you klick on that, the window will be iconified.
ù ICFS-Iconify
If no operating system with Iconify capability is found and the
Iconify-Server (ICFS) is present, you get the Iconify via ICFS.
If you click on the close button of the window and hold down one
of the keys
- Control
- Shift
- Alternate
the window will be iconified.
You can initiate the Iconify via keyboard via Control-Alternate-
Space. This means to hold down the Control and the Alternate keys and
then press Space.
7 The INF File
==============
zControl saves his configuration in the file ZCONTROL.INF. This file
will be searched at startup. Presently there are the following
parameters:
ù The path from where the CPX modules will be loaded.
ù How many CPX module entries will be displayed on the main
dialogue.
ù The positions of the main dialogue window.
ù The positions of the CPX windows.
All parameters will be saved if you choose the button 'Save' in the
dialog 'Options/Settings...'.
7.1 Debug Function
------------------
Sometimes there might be a problem with a CPX module. If you have
many modules, you need to find out which one makes the trouble. For
this purpose, you can activate a simple debug function.
If you add the line
DEBUG = STDOUT
by hand to the INF file, you get some information form every module
loading. By this you might find out where the problem is.
7.2 Where will the INF file be searched?
----------------------------------------
zControl looks for the INF file with it's configuration in different
places. The sequence is as follows:
1. By using shel_envrn(), the variable HOME will be searched.
2. The environment handed over while starting the program will be
searched for the variable HOME.
3. By using shel_read(), the start path will be looked for.
4. argv[0] will be examined for the start path.
5. The boot devide will be determined by _bootdev. The file will be
searched on the root directory of that drive, normally C:\.
As soon as one of the methods finds a path, this path will be used
for loading and saving the INF file.
It is recommended to use the HOME variable. In future there will be
more programs that will use this variable.
For the operating system MagiC (or Mag!X) you can create the HOME
variable through adding the following line into the file MAGX.INF:
This line should be before the #_CTR line.
Under MultiTOS you can create the HOME variable through adding the
following line to the GEM.CNF file:
setenv HOME=c:\gemini2\user
8 Undocumented Functions
========================
XControl has at least two undocumented functions. These functions
should not be used by normal CPX modules, but some modules
unfortunately use them.
Presently only the documented functions are supported.
Following is a list of some modules that I know which use
undocumented functions.
8.1 KONFIG.CPX
--------------
There is a CPX module from Atari, named KONFIG.CPX. This module is
used for the configuration of CPX headers, you can change the colors
of the icons and the texts.
This module uses undocumented functions of XControl. This leads to a
crash of the system if used with zControl.
That is why this module would not run under zControl. The program
refuses to activate this module - you get an error message.
8.2 LINK_CPX.CPX
----------------
This module form Richard Kurz uses also undocumented functions of
XControl. But it doesn't lead to a system crash.
But be careful with this module.
8.3 DFREE.CPX
-------------
This module from Andreas Mandel uses a undocumented function
(reserve2()), I don't understand why.
A The Format of the INF File
============================
zControl uses the following key words in the configuration file:
ù CPX_PATH
This parameter determines, from which folder the CPX modules
will be loaded from.
ù ANZ_DISP_ENTRY
This entry determines, how many CPX modules will be displayed in
the main dialogue. Presently you can have four to twelve
entries.
ù COUNTRY
This entry determines the language used by zControl.
ù WIND_MAIN
This saves the position of the zControl window. The window will
be opened at this position after startup.
ù WIND_CPX?
Behind this entry, the position of a CPX window will be saved.
Instead of the question mark there will be the number of the
window, for example 'WIND_CPX2' for the second CPX window.
ù DEBUG
See Debug Function.
ù SINGLELOAD
If the line
SINGLELOAD = TRUE
appears in the INF file, zControl loads all CPX, even if you run
it as an ACC under Single-TOS. This option is needed for
testing, if zControl is running on your computer.
This option is only for those, who run zControl as an ACC under
Single-TOS!
B The Format of the FILESORT.SYS file
=====================================
Running under TOS the CPX modules are loaded in a fixed sequence.
Usually this is the same sequence in that the files were copied into
their folder. If you want to change the sequence of the modules, you
have to copy them by hand in the right sequence.
The order in which the modules are loaded is the same order in which
they will be shown in the control panel.
Under MagiCMac on the Mac this is not working. The modules will be
loaded in alphabetical order. That is quite nice, but not really what
you want.
This is why I created a new way. If zControl finds a file
FILESORT.SYS in the same folder as the CPX modules, this module will
be evaluated. In every line of this file there is one name of a
module, without path. While loading the modules, zControl will first
of all try to load the modules in the sequence given by this file. If
a module in this list is not found, there will be no error message.
After evaluating the file FILESORT.SYS the remaining CPX modules will
be loaded.
By this, you can define the sequence of the modules, at least the
first ones. I know that this procedure is not really easy, you have
to edit this file by yourself. But it is very flexible. The idea is
to make it a lot easier by letting zControl create this file.
Right now, you can create or edit this file with any ASCII editor by
hand.
C Sources of supply
===================
Registered users can get the latest version from the author by
sending a self addressed and stamped envelope with a formatted disk
to the author. Non registered users should add the Shareware fee of
DM10.
If you have a modem, you can get the latest version of zControl in my
home BBS called 'Maus Offenbach 2':
ù Maus OF2: +49-6103-921170
The file name is ZCONTROL.LZH.
The latest version will be announced in the MausNet newsgroup
"ATARI.NEWS".
D Thanks
========
I want to thank some people, without their help zControl would never
got such a nice program. Ok, it was me who had all the coding work,
but some good ideas and informations came from them.
Many thanks to...
ù *Dirk Haun @ WI2*
for his information and the attentive testing.
("Na wer sagt's denn, es hat sich ja doch einer gefunden, der
einen XControl-Clone schreibt")
ù *Julian Reschke @ WI2*
for his information about the Drag&Drop and all this modern
stuff...
ù *Martin Osieka @ OF2*
for his help with several problems. A special thanks belongs to
him for the idea on how to make several CPX modules work at the
same time! Such an information scientist is sometimes really
helpful - I can recommend that!
("Bitte nicht jeden Tag eine neue Release")
ù *Rainer Wiesenfeller @ RS*
for the promised beer, if I will get it some time.
("... finde ich es gut, daž sich mal jemand die Mhe gibt,
dieses Programm neu zu programmieren und zu pflegen.")
ù *Reiner Rosin @ WI2*
who agreed that I use his file directory in the MAUS WI2 for
zControl. It wasn't voluntary, but I don't mind... ;-)
ù *Rene Bartholomay @ OL*
who used the possibility to be the first registered user of
zControl. ;-)
("Endlich mal jemand, der auch an die Grožbildschirmbenutzer
denkt!")
E Troubleshooting
=================
*Not enough memory under MagiC*
Sometimes zControl reports that you don't have enough memory to load
all modules, even if you have plenty of memory. While booting, if a
program reserves all the memory it finds, this can happen. The memory
will be available later.
Under MagiC you can prevent this, through deleting the line with
#_TSL of your file MAGX.INF. The multitasking will be startet by the
MagiC CPX module.
F History
=========
ù *Version 0.23*
- The function cpx_getcookie() now should really work. I didn't
compile the corrected code.
ù *Version 0.22*
This is a beta version, for testing only.
- Now you can drop deactivated modules (those with the file
ending CPZ) on zControls window. It will start the module.
The file ending will not be changed.
- It came like always: I changed only a small part and made a
big mess. The version 0.21 was not really running. I mixed up
the window management.
- Removed the beta-sign in the menu entry as ACC. The English
TOS had a display problem with that.
- If you deleted or renamed a file after booting zControl and
then tried to activate it, you got some bombs. Now you get an
error message and the module will be deleted from the list.
ù *Version 0.21*
- zControl now can be switched in its language. Right now you
can use English and German.
- Iconified modules no longer get mouse clicks and keys.
- CPX-Modules now get the following messages: AP_DRAGDROP and
VA_START
- The function cpx_getcookie() had an error. That is now fixed.
- The time-display had a minor bug. Fixed it.
ù *Version 0.20*
- The first public version of zControl.