CATaclysme 1.2b                            A GPA production (c) 2004/05/21                            Last update : 20/12/2021 Introduction What's new ? 1) How to use the software 2) Basic's syntax of the listing 3) Cataclysme's limits 4) A deeper approach...  Structure of a directory entry  Restrictions due to the catalog print routine Credits and acknowledgments                        *************************** Sorry to all Shakespeare' lovers, once again this is "french computing"  english. CATaclysme is a little tool that allow you to create easily "catalog intros" with a minimum knowledges of Basic (yes !). What is a "catalog intro" ? It is a kind of catalog that executes commands instead of printing on screen filenames ! Basically, when you type the CAT command, the screen clears, colours and graphic mode change, then a nice message appears ! This strange technic has been usually used by software houses (Ere informatique, Chip, U.s.Gold) and of course demo-makers (Voyage 93, The Demo, Face Hugger Megademo). How this little miracle is possible ? You can thanks the &BB5A system vector. This routine, used by the CPC to print the directory, executes commands when the ASCII code value to print is lower than 32. For further informations, you should try to read the CPC user book, chapter 7 page 3 (for a french CPC 6128 book !). Do no be too optimistic, it is not possible to do whatever you want with these nice command characters. Some are useless (&1B, &17). We must consider too the numerous limits due to the fact the CPC try to display a catalog, not simply texts. What's new ? ------------ This release of CATaclysme has two improvments in LOCATE mode. Now, it is possible to force the PEN command on every entry. The aim is to easily create text presentations with colors ! CATaclysme now handle correctly the cursor location at the end of the "presentation". It adds some empty entries so that the last entry displayed is always the same in MODE 0, 1 or 2 ! CATaclysme 1.2 has no new function, but it is CPC 464 compatible ! This text has been updated. You should have a look to the chapter 3. Your beloved CPC 464 is full of surprises... Last minute update ! I have killed a little bug, that could prevent the last entry of a catalog to be generated. CATAclysme 1.2a is a special release for Pulko Mandy. Now, you can use both commands PRINT" or PRINT " in your Basic presentation. Parados D10 format is now supported (128 directory entries on the sector &11 to &18 of the track &0). I suppose it will not concern many people :-). 1.2b release corrects a bug reported by Roudoudou. In LOCATE mode, you could have in certain conditions a blank entry that would alter the display of the catalog. I have made too a little change that allow you to changed the END LOCATE values just adding a LOCATE command at the end of your Basic listing. After this short introduction, let's see what CATaclysme can do. 1) How to use the software -------------------------- Cataclysme is divided in two parts : 1) an ASCII file interpreter    The program reads a Basic file saved in ASCII, parses it    and make a conversion of the known commands in ASCII ones. 2) a catalog generator module    It reads the data in memory generated by the first program    and creates a directory structure in memory. After that, it    saves it onto the first four sectors of a diskette. To create a "Catalog Intro", before to launch CATaclysme, you must create a Basic file that "executes" your presentation. Let's see an example !  100 MODE 1  110 INK 0,0  120 INK 1,24  130 PAPER 0  140 PEN 1  150 LOCATE 13,12  160 PRINT "THIS IS A TEST !"  170 LOCATE 1,24 When your listing is ready, save it in ASCII format (SAVE "PRESENT.TXT",A) then launch -CATA.BAS. The first part will ask you the filename to load plus two important informations :  * Vertical position update (-2 to 1) :    Add or remove value from the vertical axys position in the LOCATE    and WINDOW commands. Usefull when or presentation is not well    lined up.  * LOCATE mode (Y/N)    Allows you to create a generic presentation, correctly printed    whatever the starting graphic mode is. In this mode, you cannot     know the order where the catalog will be displayed. So, it is    sadly logical to limitate your creations to simple texts.    One exception, the first entry of the directory is always the    first printed. So, you must put the MODE command in the    beginning of your presentation.    If the LOCATE mode is inactive, CATaclysm considers that the    'beginning' mode is MODE 1. So, if the "real" mode is not the    good one, the presentation will not be displayed in the right    order, and does not do what you want !    With CATaclysme 1.1, there is two new options in LOCATE mode !    The PEN forced mode : if you activate this option, a PEN command is    done in every entry. It is now easy to create text with many colours !    Unfortunately, each PEN command uses two bytes.    The End LOCATE mode : the only way to know exactly know the text cursor    will be at the end of the "presentation". CATaclysme creates empty    entries so that the number of entries is a multiple of four. The last    entry has two commands, LOCATE and PEN.    CATAclysme 1.2b allow you to change the END LOCATE values (default are    x=1 and y=24) adding at the end of your listing a LOCATE command. After these boring questions, the program takes its time to do his job. Then, it awaits you for writing the catalog intro. To view the final result, just type the CAT command and enjoy ! On the archive, there are three examples in mode 0, 1 and 2. The last one is a "generic" one but only displays texts. It is possible to do better things if you know exactly how works a intro catalog.  MODE0.TXT       : presentation in MODE 0 (no LOCATE mode). It uses                    CHR$(x) instruction to display nice color bars.  MODE1.TXT       : presentation in MODE 1 (no LOCATE mode) with big                     letters done with WINDOW commands.  MODE2.TXT       : presentation in MODE 2 (LOCATE mode). It runs ok                    even if the active MODE before you type the CAT                    command is not MODE 2.   FORCE1.TXT      : presentation in MODE (LOCATE mode with PEN forced). When you have finished your intro catalog, I suppose you would be interested in copying on the diskette some files. Fortunately, it is possible. The only thing you must do is to protect the files from been displayed by the  directory command. This is really easy, just activate the flag "System" of the files (every good filemanager can do that). 2) Basic's syntax of the listing -------------------------------- To be properly understood by CATaclysm, the Basic listing must obey some rules : * only one command per line * no variable ! * all values must be in decimal (no hexadecimal) CATaclysme recognizes the following instructions :  REM or '         Displays REMak in the listing, of course, not                   converted into commands !  MODE a           Graphical MODE  PEN a            Selects pen ink  PAPER a          Selects paper ink  INK a,b,c        Defines colors of an ink  BORDER a,b       Defines BORDER colors  WINDOW a,b,c,d   Defines a WINDOW  PRINT            Displays text (Warning, it acts as  PRINT "";)  PRINT CHR$(x)    Displays character ( = PRINT CHR$(x); )  CLS              Clears the screen  LOCATE x,y       Moves text cursor to position X, Y Some commands are not exactly the same as in "real" Basic : * It is impossible to display characters whose value is higher than 127.   CATaclysm won't blame you, but it will be the character char-128 that    will be displayed ! Let's thank the system CAT routine, that make   disapear the seventh bit of every byte printed. * In LOCATE mode, excepted for the first entry, unlike you now exactly what   you do, you should not use WINDOW command, try to change an ink several    times, and use the transparent mode. Why, because you don't know when these    commands will be activated ! 3) CATaclysme limits... ----------------------- You cannot use the character " in your text (Basic text separator... ). Replace it by an ', and after having generated you intro catalog, play with a sector editor you you want absolutly having inverted commas... CATaclysme is NOT designed to display intro catalog with the |DIR command. It only creates problems in MODE 2, because the catalog is displayed with five columns. See chapter 5 for more informations. Anyway, who still uses this forgotten instruction :-) CATAclysme does not produce intro catalog compatible with the CPC 464 in "normal" mode. This damned computer does not display the directory exactly the same way as his brothers. When a "files line" is printed, it does go to the next line. Nothing strange, isn't it ? Well, this carriage return is not desactivated by the ASCII character &15. Try to generate the file  464BAD.BAS to have a look at the result. It runs perfectly on a CPC 664/6128 and does not on a 464. What is the solution, dear Lord ? A new release of CATaclysme ? No, sorry... By putting LOCATE commands at the right places (before the first character displayed at the bad place), your presentation can be usable on all CPC. If we consider our upper example, the file 464GOOD.BAS is the response to this problem. 4) A deeper approach... ----------------------- Structure of a directory entry ****************************** Classical mode : ----------------  00 id 06 dd dd dd dd dd 17 dd dd 15 00 00 00 00  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  06 = allows text display.  15 = lock text display : obligatory because the CPC add blanks and       filelength after its name.  17 = Does nothing, but needs a parameter. Nice trick to mask the dot       between the filename and its extension.  id = index number : force the CPC to display the entries in a defined       order. Another nice idea, in fact...  dd = data LOCATE mode : --------------  Entry if the PRINT command is used :   00 06 1F xx yy dd dd dd 17 dd dd 15 00 00 00 00  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  06 = allows text display.  15 = lock text display : obligatory because the CPC add blanks and       file's length after its name.  17 = Does nothing, but needs a parameter. Nice trick to mask the dot       between the filename and its extension.  1F = ASCII code of the LOCATE command  xx & yy : LOCATE parameters.  Entry if the PRINT command is not used :   00 06 dd dd dd dd dd dd 17 dd dd 15 00 00 00 00  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Entry if the forced PEN option is active : 00 06 1F xx yy 0F pp dd 17 dd dd 15 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Well, it is obviously possible to do better in some circunstances. CATaclysme does not pretend to be the ultimate intro Catalog generator ! Restrictions due to the catalog print routine ********************************************* * When you type the CAT command, the CPC reads the MODE value to know   how to display files. It orders alphabetically the files and send it   to the screen in one (MODE 0), two (MODE 1) or four columns (MODE 2).   Note that the files are ordered by column ! This strange way of doing   this job explains why a presentation designed to be display in MODE 1   does not work properly in other resolutions.   CATaclysme try to solve this equation using two ways :   - it uses an index byte for every directory entry, so it can know the     order where the CPC will sort the file entries. So, it is possible     to create easly complex effects. Huge limit, CATaclysm considers that     the "departure mode" is MODE 1. If it is not so, the introduction     will be badly displayed... Fortunately, when you reset you CPC, MODE 1     is activated !   - On every directory entry, the text cursor position is obligatory     defined with a LOCATE command. This is the LOCATE mode. On one hand,     you can create a generic presentation, without index byte, in the     other hand, it cannot allow you to make complex things easily. * Directory printing routine inserts a dot between the filename and its   extension, followed by filelength. These unwanted informations must be   "hidden" so the presentation runs correctly.   There are several ways to kill the dot ! The first one is to lock/unlock   display, but it costs two bytes (&15 &06). We can use the CHR$(8) char   (moves cursor one char back) but we must be sure to display after it    another character.   The better way in my mind, found by the illustrous Sylvestre, is to use   the CHR$(&17). It does absolutely nothing, but, as it needs a parameter,   it reserves the dot !   To avoid the file length printing, the easy way is to lock/unlock the   text display. I advice you to unlock the printing at the beginning of   an entry, because all commands that have consequences on the text cursor   position needs it ! * The CPC does not allow us to display ASCII values upper than 127.   No way to cheat the machine. Sad comfort, you can print chars 0 to 31.   They are not terrific, but that is better than nothing... * Commands CAN NOT overflow an entry to another.     If you command "overflows", it will not take parameters it needs on the   next entry, but in the chars usually displayed by the catalog   (filelength) ! This can sometimes be a way to optimise an intro, most   of the time, it does horrible things on screen...   CATaclysme DOES NOT deal with this kind of trick, and fill with 00 unused   areas. * Commands SYMBOL (CHR$(&19)), CHR$(&5), CHR$(&17) are not functionnal.   - CHR$(&5) and CHR$(&17) because the graphical MODE can't be activated.   - SYMBOL for two reasons : default init of the SYMBOL array at 240,     command too long (9 bytes). Credits and acknowledgments --------------------------- CATaclysme has been programmed by Tom et Jerry / GPA. This little tool has been coded in a short time (about a  month), it does explains why its looking is to poor and its capabilities so limited :-). A big hello to Super Sylveste, who has supported me to create such an utility. To be honest, during the Amstrad Expo 2004, Iron asked me for a tool like this one, but, at the moment, I found the subject uninteresting. Thanks to Super Sylvestre, I have opened my eyes : finaly, this strange  particularity of the CPC is amazing ! Greetings to all CPC survivors. Hi to my unfortunate roomates, Tronic and Tenebros, who may, in their caverns, try to create evil CPC programs :-)