@database Easylife.guide @author "Paul Hickman" @$VER: Easylife.guide 1.10 (09.09.94) @width 77 @index SubjectIndex @node main "Easylife - An Extension For AMOS Creator & AMOS Professional" @next Introduction @{u}@{b}Easylife Extension V1.10 - By Paul Hickman@{uu} E-Mail: ph@doc.ic.ac.uk@{ub} Welcome to Easylife. Use the @{"Browse >>" link Introduction} Button to read the entire manual for the first time, or the hypertext links for reference. @{"Introduction/Distribution " link Introduction} @{u}Section 1: Internal AMOS Improvements@{uu} @{"Zone Commands " link ZoneContents} @{"String Commands " link StringContents} @{"Bitwise Commands " link BitContents} @{"Structured Variables " link EasyLifeSTRUCT.guide/main} @{"Miscellaneuos Commands " link MiscContents} @{u}Section 2: Amiga OS & Library utilisation@{uu} @{"Powerpacker & XPK Commands " link PackContents} @{"Pattern Matching " link PatternContents} @{"AmigaDOS / Intuition Commands" link DosContents} @{u}Section 3: Magic User Interface programming@{uu} @{"MUI Introduction " link EasylifeMUI.guide/MUIintro} @{"Taglist Parsing " link EasylifeMUI.guide/TagContents} @{"MUI Commands & Functions " link EasylifeMUI.guide/MUIContents} @{u}Section 4: Support Program & Accessoriess@{uu} @{"AMOS Guide Viewer " link AmosGuide.guide/main} @{"Editor Enhancer " link EditorEnhancer.guide/main} @{"Variable Checker " link VarChecker.guide/main} @{"Program Optimser " link Optimse.guide/main} (Not Written Yet) @{"Equates To Tags " link EquatesToTags.guide/main} @{"Taglist Editor " link TaglistEditor.guide/main} @{"Tabifier " link Tabifier.guide/main} @{"Structures Compiler " link EasylifeSTRUCT.guide/Compiler} @{u}Section 5: Appendices@{uu} @{"Complete Command Index " link CommandIndex} @{"Complete Subject Index " link SubjectIndex} @{"Changes To AMOS Commands " link CommandEffects} @{"To-Do List " link todo} @endnode @node Introduction "Introduction" @{u}@{b}Welcome To Easylife V1.10@{ub}@{uu} This manual is presented as a amigaguide document, to allow quick reference. However, this often hinders reading it as an instruction manual for the first time. To overcome this use the @{"Browse >>" link howtolead} button to move through the pages in a logical order. You will see all pages of the manual except Menus/Indexes. Press @{"Browse >>" link howtolead} now to continue. @{"How To Lead An EASY LIFE " link howtolead} @{"What Else To I Need? " link alsoneeded} @{"Installation of Easylife " link installation} @{"Coventions used in this manual " link conventions} @{"Compatibility with old versions" link compatibility} @endnode @node howtolead "Introduction / How to lead an EASY LIFE" @toc Introduction @{u}@{b}How To Lead An EASY LIFE@{ub}@{uu} The EASY LIFE extension is designed to do just that - make life easier - especially the parts of said life spent writing AMOS programs. The commands included are not designed to speed up graphics to amazing levels, even on an bog standard A500 which has the MC68000 pulled out, and replaced with a lego brick, or to put a starfield in the background (Why is it virtually every AMOS extension written has starfied commands???), but to speed up the actual computing work done in the background, to allow you access to some of AMOS's internal variables, and to provide support for powerpacker, pattern matching, message banks, zone banks, and in the latest version XPK and MUI. @endnode @node alsoneed "Introduction / What else to I need?" @toc Introduction @{u}@{b}What else do I need?@{ub}@{uu} This distribution contains everything you need for the majority of easylifes commands & functions to run. However, you will also need: - The XPKmaster & XPK compressors libraries, if you wish to use the @{"Elxpk commands" link PackContents}. These can be obtained from aminet in the directory /pub/aminet/util/pack/. I think the filename is xpk25usr.lha, but don't quote me on that... - The MUI user & developers archives, if you wish to use the Elmui commands. You will also need Kickstart 2.04+ to use MUI. Download /pub/aminet/dev/gui/mui22usr.lha & mui22dev.lha. (The version numbers may be 23, 24 or even 30 (hope) by the time you read this...) I have tested versions 2.1 & 2.2. Don't use anything lower. Install the user archive with the installer program, and copy the AUTODOCS, mui-developer's guide, C examples, and assembler mui.i files from the mui22dev archive to somewhere on your harddisk (Don't even *think* of running MUI from a floppy - I suppose it is theoretically possible), and ditch the rest of the developers archive, unless you also want to program MUI from other languages. These are not required, but you will benefit from having them: - The AMOS intuition extension. - Powerpacker V3.0 / V4.0 @endnode @node installation "Introducton / Installation" @toc Introduction @{u}@{b}Installation@{ub}@{uu} There are 2 parts to installing easylife - getting the files in the right places on your system, and telling AMOS they are there. The Installer script will to the first part, but you must do the second. If you don't have the installer: - Copy the /libs directory to your AMOSPro bootdisk / harddisk LIBS:, checking that these are *newer* versions of any library you replace. - Copy the accesories to AMOSPro_Accessories: , or some other permanent location if there is no space. - Copy the demo, docs, Procedures and Mui drawers somewhere permanent - Edit you user startup to add the docs drawer to the HELP: path. For KS 1.3 people, thsi means assign HELP: to the docs drawer. For KS2.0+ if HELP: is already assigned (And it should be), use Assign ADD. To install for AMOS Creator: (NOTE: AMOS Creator version is not in this archive) - Copy Lib/Easylife.Lib to the AMOS_System directory if you didn't run the installer script. - Run Config1_3.AMOS, load the default configuration, select 'Loaded Extensions' and enter :AMOS_System/Easylife.Lib" into slot 16. Then save the default configuration. To install for AMOS Professional - Copy Lib/AMOSPro_Easylife.Lib to AMOSPro_System:APSystem/ if you didn't run the installer script. - Load AMOSPro, and select "Set Interpreter" from the config menu. Load the default configuration, click on loaded extensions, and enter 'AMOSPro_Easylife.Lib' into slot 16. Then save the default configuration. Both Versions. - Now quit & reload your version of AMOS. NOTE: Additional installation may be required to use @{"MUI" link EasylifeMUI.guide/MUIIntro} @endnode @node Conventions "Introduction / Conventions" @{u}@{b}Conventions Used In This Manual@{ub}@{uu} Each page of this manual describes a group of related commands, and/or function calls, and is divided into the following sections. @{u}Command Syntax@{uu} @toc Introduction This shows the syntax of all commands & functions covered on the page. If a keyword is preceeded with an '=' sign, then it defines a function call. This means that it should be used as an AMOS expession - E.g. A = Znsx(10) Print Pp Len(0); If it does not, then it is an AMOS command, and should only be used at the start of a statement - E.g. Set Bank Name 10,"Fred " If A=10 Then Pp Load 1,"RAM:Test",2 The command/function name is followed by it's arguments, which are in capitals. If a particular command/function can have several argument formats, all are listed here. Any words in @{i}italics @{ui}are the formal parameters of the command / function, in all sections. @{u}Description@{uu} This section contains a few paragraphs describing the usual action of the command / function in general terms. @{u}Notes@{uu} This section describes any special cases for the command where it does not behave in the expected manner, exceptions to the explanation given in the description section, and any conditions under which it should not be used etc. @{u}Errors@{uu} This section lists all possible errors messages generated by the command / function, and explains their most likely causes. NOTE: 'Out of variable space', and 'Out of memory' may also occur with some commands, but are not listed, as they as generally not a result of a problem with the specific instruction, but with the entire program. @{u}See Also@{uu} This section list related commands that are not in the same sub-section of the manual that you are reading, or are not easylife commands. @{u}Bugs@{uu} This section is non-existant (I Hope) :-) @endnode @node Compatibility "Introduction / Compatibility with older versions of easylife" @{b}@{u}Compatibility with older versions of easylife@{ub}@{uu} Firstly, this may be a little confusing, since I changed version numbers halfway thourgh development to comform to commodore standards. The versions so far are: Phase 1 ======= V1.0 Original AMOS Creator Version V1.1 Improved Version Creator Version V1.2 Ditto. Phase 2 ======= V1.3.1 Dual Creator / Pro version. Some new commands. V1.3.2 Bugfix to previous version. V1.3.3 More Bugfixes / AMOSPro specified optimisations. Phase 3 ======= V1.3.4 Added the 'El' prefix to all command names. V1.4 Internal restructuring - Bug fixes. V1.4.1 XPK commands added. V1.4.2 Bug fixes. V1.4.3 Bug fixes. V1.4.4 Elf Char now search for many characters. V1.5 Primitive MUI support added. Intuition routines improved. V1.06 Switched to commodore version numbering. Refined MUI functions. Phase 4 ======= V1.07 Taglist editor support added & all MUI commands renamed. Various other improvements. Structure variable commands added. V1.08 Easylife.Library created. Structure variable commands moved to library. V1.09 Amigaguide Viewer Written & AMOSPro help replaced. Minor bug fixes & changes to the other programs. Due to an error in the V1.08 token table, programs which use the new font commands will need retokenising. This version should be nearly 100% compatible with other Phase 4 versions. The only changes are that the Ellock Font & Elunlock Fonts commands were removed in V1.08. Use Elopen Font instead. Converting Phase 3 programs should mainly be done by Retokenising them (AMOSPro_Tutorials/ReTokenise.AMOS) - A few commands may need changing (E.g. Old style MUI comands / XPK commands). Phase 1 & 2 versions would have to changed by hand from a text editor using AMOSPro's Save AscII as the command names have all changed. @endnode @node ZoneContents "Zone Commands & Functions - Contents" @toc main @{u}@{b}Screen Zone Support@{ub}@{uu} The AMOS Manuals imply that the only use of screen zones is to detect when objects or points lie within them. Easylife provides the commands necessary for you to use zones for any purpose that requires an area of the screen to be marked, and is particularly useful for control buttons. There are three types of zone support command: @{u}Section 1: Reading / Modifing standard zones@{uu} @{"Reading a zones co-ordinates" link C_Elznsx} @{"Moving zones " link C_ElznShift} @{u}Section 2: Multi-Zones@{uu} @{"What is a multi-zone " link WhatIsMultiZone} @{"Reserving multi-zones " link C_ElmzReserve} @{"Deallocating multi-zones" link C_ReserveZone} @{"Defining a multi-zone " link C_ElmzSet} @{"Reading co-ordinates " link C_Elmznsx} @{"Checking multi-zones " link C_Elmzone} @{"Erasing a multi-zone " link C_ElmzSet} @{"Erasing groups of zones " link C_ElmzErase} @{u}Section 3: Zonebanks@{uu} @{"What is a zone bank " link ZoneBank} @{"Installing a group as standard zones" link C_ElzbAdd} @{"Installing a group as multi zones " link C_ElzbMultiAdd} @{"Installing all groups as multi zones" link C_ElzbInstall} @endnode @node C_Elznsx "Zones / Read a zones co-ordinates" @toc ZoneContents @{b}Command Syntax@{ub} =ElZnsx( @{i}ZONE @{ui}) =ElZnsy( @{i}ZONE @{ui}) =ElZnex( @{i}ZONE @{ui}) =ElZney( @{i}ZONE @{ui}) =ElZnsx( @{i}SCREEN , ZONE @{ui}) =ElZnsy( @{i}SCREEN , ZONE @{ui}) =ElZnex( @{i}SCREEN , ZONE @{ui}) =ElZney( @{i}SCREEN , ZONE @{ui}) @{b}Description@{ub} When you use the AMOS command Set Zone, you supply it with the parameters 'sx,sy to ex,ey' to define the co-ordinates of the zone. These function calls allow you to read back the current values of these parameters for a given @{i}ZONE@{ui}. E.g. Set Zone 1,10,20 To 30,40 Print ElZnsx(1);",";ElZnsy(1) Print ElZnex(1);",";ElZney(1) Will display the values: 10, 20 30, 40 The optional @{i}SCREEN @{ui}parameter specifies the screen number the zones are defined on. If as above, it is omitted, it is assumed they are defined on the current screen. @{b}Notes@{ub} These commands return signed integers. (-32768 to 32767) If a zone has been reserved, but not defined with Set Zone, all four functions will return 0. @{b}Errors@{ub} @{u}Screen Not Opened@{uu} The @{i}SCREEN @{ui}number you have defined is not open. If you have omitted this parameter, this error means that no screens are open. @{u}Illegal Function Call@{uu} This means the specified @{i}ZONE @{ui}has not been reserved on the specified @{i}SCREEN@{ui}. @endnode @node C_ElznShift "Zones / Moving Zones" @toc ZoneContents @{b}Command Syntax@{ub} ElZn Shift @{i}SCREEN , DX , DY @{ui} ElZn Shift @{i}SCREEN , DX , DY , START @{ui}To @{i}FINISH @{ui} @{b}Description@{ub} The first instruction will scroll all the zones defined on the given @{i}SCREEN DX @{ui}pixels to the right, and @{i}DY @{ui}pixels downwards. To scroll to the left, make @{i}DX @{ui}negative. To scroll upwards, make @{i}DY @{ui}negative. If specified @{i}START @{ui}and @{i}FINISH @{ui}allow only the zones with numbers between @{i}START @{ui}and @{i}FINISH @{ui}(Inclusive) to be scrolled. E.g. Elzn Shift 0,-16,10,4 To 7 Will scroll zoes 4,5,6 & 7 to the left by 16 pixels, and down 10 on screen 0. @{b}Notes@{ub} - Scrolling a zone does not change the image displayed on the screen, it merely moves the co-ordinates of your zones to reflect the changes to the image made by screen copy, scroll, or the AMOS Turbo Plus Blit commands. - You can shift a single zone by making both @{i}START @{ui}and @{i}FINISH @{ui}equal to the zone number. - ElZn Shift does not work with multi-zones. - It is not an error to shift a zone off the screen. - The arithmatic for zone co-ordinates is done modulo 65536. This means if you shift a zone with co-ordinates 10,10 to 50,20 by 20 pixels to the left, the new co-ordinates will be 65526,10 to 30,20. This will confuse the AMOS =Zone(X,Y), Mouse Zone, and related functions, but not @{"Elznsx" link C_Elznsx} and the other easylife zone reading commands. @{b}Errors@{ub} @{u}Screen Not Opened@{uu} The given @{i}SCREEN @{ui}is not open. @{u}Illegal function call@{uu} Either: - No zones are reserved on the given screen - @{i}START @{ui}or @{i}FINSH @{ui}is greater than the number of zones reserved - @{i}START @{ui}is greater than @{i}FINISH @{ui} @endnode @node WhatIsMultiZone "Multi Zones / What is a multi zone" @toc ZoneContents @{b}@{u}What Is A Multi Zone?@{ub}@{uu} A multi zone is similar to a normal screen zone. It is a rectangular area of the screen, and you can detect if given co-ordinates fall within it. The differences are: - Multi zones are identified by a GROUP number, and a ZONE number. Neither need be sequential, you can define zones 1,3,10 of group 1, then zone 431 of group 839 if you want - it will still only take 4 zones worth of memory. - All Multi zones can in one group can be erased with one command, without affecting the other groups. - You can detect if co-ordinates lie in any multi zone, or if they lie in any multi zone from one particular group. - You can find all the zones a point lies in, not just the first one in the list (unlike standard zones). @endnode @node C_ElmzReserve "Multi Zones / Reserving Space" @toc ZoneContents @{b}Command Syntax@{ub} ElMz Reserve @{i}NUM @{ui} @{b}Description@{ub} This command is the equivilent of the Reserve Zone command. It reserves memory for the chosen number of zones. NUM should be even. If the value you supply is not, it is rounded up. A maximum of 5460 multi zones can be defined. (There is a good reason for that number!) The Multi zones take the place of the normal screen zones in the screen data structure, so they cannot be used at the same time. Multi zone commands will produce an error message if you attempt to use them when normal screen zones are defined. Normal screen zones will not work with multi zones installed, but will not produce error messages, just unreliable results. @{b}Notes@{ub} - When you call ElMz Reserve, the previously installed zones/multi zones are erased - you do not get a Zones already reserved error. @(b}Errors@{ub} @{u}Out of memory@{uu} Not enough memory could be reseved for the zone table. @endnode @node C_ReserveZone "Multi Zones / Eraseing All Multi Zones" @toc ZoneContents @{b}Command Syntax@{ub} Reserve zone @{b}Description@{ub} This the standard AMOS reserve zone command. Used with no parameters, it will erase all multi zones. They are also erased properly when the screen is closed / default command used, or under any other circumstance when normal screen zones are removed. @{b}See Also @{ub} @{"Changes to AMOS Commands" link CommandEffects} @endnode @node C_ElmzSet "Multi Zones / Defining & Erasing A Multi Zone" @toc ZoneContents @{b}Command Syntax@{ub} ElMz Set @{i}GROUP , ID , X1 , Y1 @{ui}To @{i}X2 , Y2 @{ui} ElMz Set @{i}GROUP , ID @{ui} @{b}Description@{ub} This is virtually identical to Set Zone command, except you must supply a @{i}GROUP @{ui}number. @{i}GROUP @{ui}and @{i}ID @{ui}can be any number between 1 and 65535. @{i}X1,Y1,X2,Y2 @{ui}can be between -32768 and 32767. @{i}X1,Y1 @{ui}and @{i}X2,Y2 @{ui}are automatically sorted so @{i}X1 @{ui}<= @{i}X2@{ui}, and @{i}Y1 @{ui}<= @{i}Y2@{ui}, so @{"Elmznsx" link C_Elmznsx} etc. always return the correct values. The second form of the instruction erases the specified zone. @{b}Notes@{ub} - If you call ElMz Set twice with the same @{i}GROUP & ID @{ui} numbers, the old co-ordinates are overwritten. @{b}Errors@{ub} @{u}Illegal Funciton Call@{uu} Neither @{i}GROUP @{ui}or @{i}ID @{ui}can be 0, or greater than 65535. @{u}Zone table full@{uu} You have already used all @{"Reserved" link C_ElmzReserve} multi zone space. @{u}Multi Zones Not Reserved@{uu} You have not reserved any multi zone space with the @{"ElMz Reserve" link C_ElmzReserve}, or have since used the standard @{"Reserve Zone" link C_ReserveZone} command. @endnode @node C_Elmznsx "Multi Zones / Reading multi zone co-ordinates" @toc ZoneContents @{b}Command Syntax@{ub} = ElMznsx( @{i}GROUP , ID @{ui}) = ElMznsy( @{i}GROUP , ID @{ui}) = ElMznex( @{i}GROUP , ID @{ui}) = ElMzney( @{i}GROUP , ID @{ui}) @{b}Description@{ub} These are multi zone equvilents of the commands to read a standard AMOS zone's co-ordinates, @{"Elznsx" link C_Elznsx} etc. Each function call returns the coresponding co-ordinate of the edge of the zone. @{b}Notes@{ub} - All operate on the current screen only. - @{"Elmz Set" link C_ElmzSet} sorts X1,X2,Y1,Y2 so ElMznsx/y are always greater than ElMznex/y. - The values returned are signed (-32768 to 32767). @{b}Errors@{ub} @{u}Multi Zone Not Defined@{uu} The zone with the specified (@{i} GROUP , ID @{ui}) does not exist. @{u}Screen Not Opened@{uu} Since these commands operate on the current screen, this error means that no screen was open. @endnode @node C_Elmzone "Multi Zones / Find the multi-zones containing a point" @toc ZoneContents @{b}Command Syntax@{ub} = ElMzone( @{i}X , Y @{ui}) = ElMzone( @{i}X , Y , GROUP @{ui}) = ElMzonen = ElMzoneg @{b}Description@{ub} The first form of ElMzone returns the zone ID of the first multi zone on the current screen that the point @{i}X,Y @{ui}lies within. The second form of Mzone only checks the zones in one particular @{i}GROUP@{ui}. ElMzonen returns the zone ID of the next multi zone that the point specified in the last ElMzone command lies within. If the second form of ElMzone was used to specify the point, ElMzonen will return the next zone in the searched @{i}GROUP @{ui}that contains the point. Mzoneg returns the group number of the last multi-zone ID returned by the previous ElMzone or ElMzonen commnad. @{b}Notes@{ub} - All of these commands return 0 if there is no remaining zone which contains the point specified. - ElMzoneg will still work if you specify a group in the ElMzone command, but it will only ever return group number @{i}GROUP@{ui}, or 0 if no zone was found in the @{i}GROUP @{ui}that contained the point. - The zones containing the point won't be returned in any particular order. @{b}Errors@{ub} @{u}Multi Zones Not Reserved@{uu} No multi zones have been reserved on the current screen. @endnode @node C_ElmzErase "MultiZones / Removeing A Multi Zone Group" @toc ZoneContents @{b}Command Syntax@{ub} ElMz Erase @{i}GROUP @{ui} @{b}Description@{ub} This command erases all zones in the given @{i}GROUP@{ui}. Unlike standard AMOS zones, when you reserve multi-zones, you reserve space for a certain number of zones, but those zones may have any group and zone id numbers. Erasing a group of zones frees the space in the zone table for use by other groups. @{b}Notes@{ub} - This command does not deallocated any memory. - To remove all multi zones & deallocate the memory, use the standard AMOS @{"Reserve Zone" link C_ReserveZone} command. - A single zone can be erased with the {"ElMz Set" link C_ElmzSet} command. @{b}Errors@{ub} @{u}Multi Zones Not Reserved@{uu} You have not reserved any multi zones on the current screen. @endnode @node ZoneBank "Zone Banks / What Is A Zone Bank?" @toc ZoneContents @{u}@{b}What Is A Zone Bank@{ub}@{uu} A zone bank is an AMOS bank, which contains one or more sets of AMOS zone descriptions, created by the Zone Editor program. Zone banks have the same structure as multi zones - the bank is split into groups, and each group contains any number of zones, However unlike multi zones, a zone bank has all groups defined in numerical increasing order, e.g. With multi zones you can just define groups 1 & 10, but with a zone bank groups 2 - 9 must also be defined. The same applies to the zone numbers within each group of the bank. Easylife allows you to use zones from a zone bank in 3 ways: @{"Install A Single Group As AMOS Zones " link C_ElzbAdd} @{"Install A Single Group As Multi Zones" link C_ElzbMultiAdd} @{"Install All Groups As Multi Zones " link C_ElzbInstall} @endnode @node C_ElzbAdd "Zone Bank / Installing A Group As AMOS Screen Zones" @toc ZoneContents @{b}Command Syntax@{ub} ElZb Add @{i}SCREEN , BANK , GROUP @{ui} @{b}Description@{ub} This command installs zones from a @{"Zone Bank" link C_ZoneBank}, created by the zone editor program. @{i}SCREEN @{ui}is the screen you wish to set the zones on. @{i}BANK @{ui}is the bank number containing the zones, and @{i}GROUP @{ui}is the set of zones within the bank you wish to install. @{b}Notes@{ub} - Any previously reserved zones or multi zones are removed when this command is executed. - Once installed, all normal AMOS & Easylife zone operations can be performed on the zones as if they were created by set zone instructions @{b}Errors@{ub} @{u}Bank does not exist@{uu} The bank number given is that of a non-existant bank. @{u}Not a Zone Bank@{uu} The bank number given is that of another type of bank. Zone banks are identified by them having the name "Zones " @{u}Illegal Function Call@{uu} The group number you have specified does not exist in the selected zone bank. @{u}Screen not opened@{uu} The screen number you have selected is not open. @endnode @node C_ElzbMultiAdd "Zone Bank / Installing A Zone Bank Group As Multi Zones" @toc ZoneContents @{b}Command Syntax@{ub} ElZb Multi Add @{i}BANK , GROUP @{ui} @{b}Description@{ub} This command installs all zones from the chosen group as multi zones. Unlike the other install instructions, this does not erase the currently defined zones. This means that you will have to reserve enough multi zones to contain the group first. The only zones overwriten by the command are those with the same GROUP & ID numbers as those in the bank. @{b}Errors@{ub} @{u}Bank does not exist@{uu} The bank number given is that of a non-existant bank. @{u}Not a Zone Bank@{uu} The bank number given is that of another type of bank. Zone banks are identified by them having the name "Zones " @{u}Illegal Function Call@{uu} The group number you have specified does not exist in the selected zone bank. @{u}Screen not opened@{uu} The screen number you have selected is not open. @{u}Multi Zones Not Reserved@{uu} You must have already reserved some multi zones to contain the zone bank group. @{u}Zone Table Full@{uu} There is not enough room in the space reserved for multi zones remaining to hold the entire group. @endnode @node C_ElzbInstall "Zone Bank / Installing an entire zone bank as Multi Zones" @toc ZoneContents @{b}Command Syntax@{ub} ElZb Multi Add @{i}BANK @{ui} @{b}Description@{ub} This command installs all zones in all groups the @{i}BANK @{ui}as multi zones. @{b}Notes@{ub} - This command erases any previously defined (multi) zones and reserves the exact number of multi zones required to hold the entire zone bank. - The zones are installed on the current screen. @{b}Errors@{ub} @{u}Bank does not exist@{uu} The bank number given is that of a non-existant bank. @{u}Not a Zone Bank@{uu} The bank number given is that of another type of bank. Zone banks are identified by them having the name "Zones " @{u}Screen not opened@{uu} The screen number you have selected is not open. @endnode || @node StringContents "String Functions - Contents" @toc main @{u}@{b}String support functions@{ub}@{uu} @{u}Section 1: Character Search Functions@{uu} @{"Character Searching " link SearchIntro} @{"Forwards Searches " link C_ElfAsc} @{"Backward Searches " link C_ElfLastAsc} @{"Control Character Searches" link C_ElfControl} @{"Nth Occurance Searches " link C_ElfNthAsc} @{"Character Counting " link C_ElfNumasc} @{u}Section 2: Bank Name Strings@{uu} @{"Reading A Bank Name " link C_ElBankName} @{"Changing A Bank Name " link C_ElsBankName} @{u}Section 3: String Storage@{uu} @{"Strings & Integers " link C_Ellong} @{"Reading Memory As A String" link C_ElmemRead} @{"Writing Strings To Memory " link C_ElmemWrite} @{"Padded Strings " link C_ElpadAsc} @{u}Section 4: Message Bank Support@{uu} @{"Strings From Message Banks" link C_Elmessage} @{"Check if Messages Exist" link C_ElmessageExists} @endnode @node SearchIntro "Character Search Functions" @toc StringContents @{u}@{b}Character Search Functions@{ub}@{uu} If you want to find the first occurance of a character in a string, you can use the AMOS functinon =instr$, but as this is designed to find substrings, it is in-efficient for single characters. However more sigificantly, to find the last occurance of a character, or the first occurance of any of a set of characters in a string requies a loop in AMOS which is *very* inefficient. To overcome this, Easy Life provides a variety of string searching commands, most of which accept either AscII values to search for a single character, or a second string to search for any of the characters that occur in the string. There are also commands to search for any character but those list, and to search backwards. All EasyLife 'Find' character commands begin with the prefix 'Elf'. @endnode @node C_ElfAsc "String Searches / Forwards Searhing" @toc StringContents @{b}Command Syntax@{ub} =Elf Asc( @{i}S$ , A @{ui}) =Elf Char( @{i}S$ , A$ @{ui}) =Elf Asc( @{i}S$ , A , P @{ui}) =Elf Char(@{i}S$ , A$ , P @{ui}) =Elf Not Asc( @{i}S$ , A @{ui}) =Elf Not Char( @{i}S$ , A$ @{ui}) =Elf Not Asc( @{i}S$ , A , P @{ui}) =Elf Not Char( @{i}S$ , A$ , P @{ui}) @{b}Description@{ub} The Asc & Char varients of each form of the find function are identical, except the second argument (The character to find) is given as either an AscII value between 0 and 255, or a second string of characters. When a string is given, the search is for any of the characters in the string. These commands will not search for substrings. The first form, =Elf Asc(@{i}S$,A@{ui}) returns the first occurance of the character in the string @{i}S$@{ui}. The second form, =Elf Asc(@{i}S$,A,P@{ui}) begins searching a position @{i}P@{ui}+1. Any occurance in position @{i}P@{ui}, or before are ignored. The "Elf Not" forms are equivilent to the simple forms with the same arguments, except they return the position of the first character found that is not the character specifed in @{i}A@{ui}, or the first character that does not occur in the string @{i}A$@{ui}. @{b}Notes@{ub} - If no character is found, these functions return all return 0. - When you specify the argument @{i}P@{ui}, the search begins at position @{i}P@{ui}+1. The AMOS =instr$ function would begin at position @{i}P@{ui}. The reason for what at first seems strange behaviour is that the most frequent use of these commands is to parse a string which contains seperator characters e.g. spaces. With my method, to find the next occurance, you simply put the position of the last occurance as the @{i}P @{ui}parameter of the next search. - Any value of @{i}P @{ui}is accepted, but is taken to be unsigned, so negative numbers are treated as very high positive numbers. If @{i}P @{ui}is greater than the length of the string, 0 is returned. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} Either @{i}A$ @{ui}is an empty string, or @{i}A @{ui}is not between 0 and 255. @endnode @node C_ElfLastAsc "String Searches / Backwards Searching" @toc StringContents @{b}Command Syntax@{ub} =Elf Last Asc( @{i}S$ , A @{ui}) =Elf Last Char( @{i}S$ , A$ @{ui}) =Elf Last Asc( @{i}S$ , A , P @{ui}) =Elf Last Char( @{i}S$ , A$ , P @{ui}) =Elf Last Not Asc( @{i}S$ , A @{ui}) =Elf Last Not Char( @{i}S$ , A$ @{ui}) =Elf Last Not Asc( @{i}S$ , A , P @{ui}) =Elf Last Not Char( @{i}S$ , A$ , P @{ui}) @{b}Description@{ub} Each of these commands coresponds to a @{"Forward Searching" link C_ElfAsc} command, but begins the search from the end of the string @{i}S$@{ui}, and works backwards. The Asc varients take the AscII value of the character to search for, whereas the Char varients take a second string containing the set of characters to search for. = Elf Last searches from the end of the string for the chosen character, returning the first position from which it occurs. If the optional parameter @{i}P @{ui}is specified, the search begins at position @{i}P@{ui}-1. = Elf Last Not searches from the end of the string for any character other than the chosen character, and is very useful for removing the padding from padded strings, or for removing trailing spaces. @{b}Notes@{ub} - If no character is found, these functions return 0. - When you specify the argument @{i}P@{ui}, the search begins at position @{i}P@{ui}-1. This is so the second occurance can be found by returning the position of the first as the argument @{i}P@{ui}. - Any value of @{i}P @{ui}is accepted, but is taken to be unsigned, so negative numbers are treated as very high positive numbers. If @{i}P @{ui}is greater than the length of the string, the search begins at the end of the string. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} Either @{i}A$ @{ui}is an empty string, or @{i}A @{ui}is not between 0 and 255. @endnode @node C_ElfControl "String Searches / Finding Control Characters" @toc StringContents @{b}Command Syntax@{ub} = Elf Control( @{i}S$ @{ui}) = Elf Control( @{i}S$ , P @{ui}) @{b}Description@{ub} These special versions of the forward search commands find the first occurance of a character with AscII below 32 in the string S$ (Starting at position P+1 if P is supplied). The position of the first control character is returned, or 0 if the string contains no control characters. E.g. This can be used to determine if a string is printable. A string which contains control characters may invoke any of the AMOS text formatting functions in chapter 8 of the AMOS Creator manual such as At(X,Y), Pen$(C), Cdown$, etc. (Chapter 5.06 of the AMOS Pro manual) If Not Elf Control(A$) Print A$ Else Print "String Is Unprintable" End If @endnode @node C_ElfNthAsc "String Searches / Finding the Nth Occurance" @{b}Command Syntax@{ub} = Elf Nth Char( @{i}S$ , A$ , N @{ui}) = Elf Nth Asc( @{i}S$ , A , N @{ui}) @{b}Description@{ub} This varient of the find function finds the Nth occurance a character in a string. @{i}S$ @{ui}is the string to search, and @{i}N @{ui}is the occurance number you wish to find. The character to search for is the character with AscII value @{i}A @{ui}in the Elf Nth Asc function, or the any characters in the string @{i}A$ @{ui}in the Elf Nth Char functino. The position of the Nth occurance of the character is returned, or 0 if the character(s) does/do not occur @{i}N @{ui}times in the string. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} Either @{i}A$ @{ui}is an empty string, or @{i}A @{ui}is not between 0 and 255. @endnode @node C_ElfNumAsc "String Searches / Character Counting" @toc StringContents @{b}Command Syntax@{ub} = Elf Num Char( @{i}S$ , A$ @{ui}) = Elf Num Asc( @{i}S$ , A @{ui}) @{b}Description@{ub} These functions return the number of times the specified character(s) are found in the string S$. In the Asc varient, A is the AscII code of the character to be counted. In the Char varient, occurances of any character from A$ are counted. @{b}Notes@{ub} - If the string A$ contains more than one occurance of the same character it is still only counted once. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} Either @{i}A @{ui}is not between 0 and 255, or @{i}A$ @{ui} is an empty string. @endnode @node C_ElBankName "Strings / Read a banks name" @toc StringContents @{b}Command Syntax@{ub} = ElBank Name$( @{i}BANK @{ui}) @{b}Description@{ub} This function call returns the name of the given @{i}BANK@{ui}. This is the 8 character string displayed when you use the AMOS listbank command. The string returned is always 8 characters long, and is padded with trailing spaces, which may be removed with: NAME$ = ElBank Name$(BANK) NAME$ = Left$(NAME$,Elf Last Not Asc(NAME$,32)) @{b}Errors@{ub} @{u}Bank Not Reserved@{uu} The obvious - you can't get the name of a non-existant bank. @endnode @node C_ElsBankName "Strings / Setting A Banks Name String" @toc StringContents @{b}Command Syntax@{ub} Els Bank Name BANK , NAME$ @{b}Description@{ub} This command changes the name of the @{i}BANK @{ui}which is returned by the @{"ElBank Name$" link C_ElBankName} function and the ListBank command to @{i}NAME$ @{ui} @{b}Notes@{ub} - NAME$ must be exactly 8 characters long, so shorter strings should be padded with spaces E.g. Els Bank Name BANK,ElPad Asc(NAME$,32,8) - Some AMOS commands / programs use the bank name to detect the bank type, so you should be careful when changing the name of bank types other than Work or Data. Easylife itself uses the bank name to detect Message Banks and @{"Zone Banks" link ZoneBank} @{b}Errors@{ub} @{u}Bank Not Reserved@{uu} The bank specified does not exist. @{u}Illegal Function Call@{uu} Either the bank number specified was not a legal bank number (e.g. it was negative), or @{i}NAME$ @{ui}was not exactly 8 characters long. @endnode @node C_Ellong "Strings / String <--> Integer Conversion" @toc StringContents @{b}Command Syntax@{ub} = ElLong$( @{i}NUM @{ui}) = ElLong( @{i}NUM$ @{ui}) = ElWord$( @{i}NUM @{ui}) = ElWord( @{i}NUM$ @{ui}) @{b}Description@{ub} ElLong$ converts the integer into a 4 byte string holding that integer, so that it may be output to a file compactly with a fixed length, or so that a list of integers may be built within a string easily. ElLong converts the first 4 bytes of a string back into an AMOS integer. ElWord$ and ElWord do the same thing, except only two bytes are used. This means that the integer must be between -32768 and 32767. @{b}Notes@{ub} - The integer is stored in the string as it is stored in memory - most sigificant byte first. - ElWord$ does not give error messages if the value is out of range, it simply stores the lower 2 bytes. Therefore you can use word$ to store unsigned words (0-65535), but you must then read them bank with: NUM = Asc(NUM$)*256+Asc(Mid$(NUM$,2)) As Elword will return negative numbers for 32768-65535. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} The @{i}NUM$@{ui} string must be at least 2 bytes long in ElWord$, and at least 4 bytes in length in ElLong$. @endnode @node C_ElmemRead "Strings / Reading Memory As A String" @toc StringContents @{b}Command Syntax@{ub} =ElMem$( @{i}ADDR , SLENGTH @{ui}) =ElMem$( @{i}ADDR , SLENGTH , DELIMITER @{ui}) @{b}Description@{ub} The first format copies then next @{i}SLENGTH@{ui} bytes from address @{i}ADDR@{ui} into an AMOS string, and returns that string. The second version attempts to do the same thing, but stops when it finds the first occurance of a character with AscII code @{i}DELIMETER@{ui}. AMOS already has peek,deek & leek - thing of this as 'Seek' (!) @{b}Notes@{ub} - A COPY of the memory area is returned. It may be modified like any other string, without affecting the memory area, and conversly any changes to the memory made since it was read are not reflected in the string. - If the memory reading is terminated by reading a @{i}DELIMETER@{ui} character, that character is not returned as the last character of the string - only those characters up to the @{i}DELIMETER@{ui} are returned. 0 is a useful delimeter for reading strings from Amiga OS functions, which are null- terminated. @{b}Errors@{ub} @{u}Variable Buffer Full / Out Of Memory @{uu} These may occur at any time, but this command is particularly susceptable if the string is very large, or the delimeter does not occur where you expect it to. @{u}Illegal Function Call@{uu} @{i}SLENGTH@{ui} must be between 1 and 65535 inclusive, and @{i}DELIMETER@{ui} between 0 and 255. @endnode @node C_ElmemWrite "Strings / Writing A String To Memory" @toc StringContents @{b}Command Syntax@{ub} Elmem @{i}ADDR , S$ @{ui} = Elmem inc( @{i}ADDR , S$ @{ui}) @{b}Description@{ub} This command copies the string @{i}S$@{ui} into memory begining at address @{i}ADDR@{ui}. Only the actual characters in the string are copied - the length does not preceed it as with AMOS strings within the variable buffer, and it is not automatically null terminated like C strings. The second format returns ADDR+Len(S$) as a result, allowing many strings to be copied into consecutive memory addresses easily using: ADDR = Elmem Inc(ADDR,S1$) ADDR = Elmem Inc(ADDR,S2$) Elmem ADDR,S3$ @{b}Notes@{ub} - If @{i}S$@{ui} is an empty string, this command has effect. @{b}Errors@{ub} If you write to just any memory address, *anything* can happen - make sure you know what is at the address you write to. @endnode @node C_ElpadAsc "Strings / Padded Strings" @toc StringContents @{b}Command Syntax@{ub} = ElPad Asc(S$,A,L) = ElPad Char(S$,A$,L) @{b}Description@{ub} If the length of the string @{i}S$@{ui} is greater than or equal to @{i}L@{ui}, these two functions return @{i}S$@{ui}. Otherwise they return a string which is @{i}S$@{ui} followed by enough repetitons of the character @{i}A/A$@{ui} to make it's length L. The first varient takes the AscII code of the "pad character" in the @{i}A@{ui} argument. The second varient uses the first character of @{i}A$@{ui}. @{b}Notes@{ub} - If A$ contains more than one character, the second and subsequent characters are ignored. In the future I intend to change this to repeatedly use the whole of A$ to pad S$. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} @{i}A@{ui} must be between 0 and 255, and @{i}A$@{ui} must not be and empty string. @endnode @node C_Elmessage "Strings / Message Banks" @toc StringContents @{b}Command Syntax@{ub} = ElMessage$( BANK , GROUP , NUMBER ) = ElMessage$( ADDR , GROUP , NUMBER ) @{b}Description@{ub} Easy Life makes life much easier when using the Message Bank Compiler PratchED extension program. This command reads a message from a bank into a string. @{i}BANK@{ui} is the bank number to read the message from, @{i}GROUP@{ui} and @{i}NUMBER@{ui} give the identifier of the message your wish to read. Alternatively, you may give the absolute address of the message bank in memory in the @{i}ADDR@{ui} parameter. For more information, read the message bank compiler documentation. (Which one day, I might even release!) Example: To read a message 1,2 from a crunched message bank that has been loaded into powerpacker buffer 0, use the call: M$ = ElMessage$(ElPp Buf(0)+20,1,2) The +20 is because all AMOS banks have a header of 20 bytes. @{b}Notes@{ub} - The method defined in the above example is not the only way to read crunched message banks - you can use {"Elxpk Load" link C_Elxpkload} - A COPY of the message is returned in the string, and modifying it will not affect the stored message. - The use of message banks in AMOS professional is limited in AMOSPRO, as the text string part of resource banks do pretty much the same thing, except message banks will be AMOS Creator compatible. @{b}Errors@{ub} @{u}Bank Not Reserved@{uu} The first parameter is a valid bank number, but that bank does not exist. If the first parameter is not a legal bank number, it is taken to be the absolute address of the message bank. @{u}Not A Message Bank@{uu} The chosen bank exists, but is not a message bank, or there is not message bank at the specified address. Message banks are recognised by thier name, so you must not rename them with the @{"Els Bank Name" link C_ElsBankName} command. @{u}Illegal Function Call@{uu} Either the GROUP or message NUMBER is illegal for this particular bank. The error can be avoided using the @{"Message Exists" link C_ElmessageExists} function first. @endnode @node C_ElmessageExists "Strings / Testing if a message exists" @toc StringContents @{b}Command Syntax@{ub} = ElMessage Exists( @{i}BANK , NAME , START @{ui}) = ElMessage Exists( @{i}ADDR , NAME , START @{ui}) @{b}Description@{ub} This command is used to return whether a given message has been defined within a message bank, or not as a boolean. The arguments, and error conditions are the same as for the @{"ElMessage$" link C_Elmessage} function, but you will never get an illegal function call as the purpose of this function is to determine whether the message exists. @endnode @node BitContents "Bitwise Commands - Contents" @toc main @{u}@{b}Bitwise Commands@{ub}@{uu} @{"Bit Testing " link C_ElWtst} @{"Bit Modifying " link C_ElWset} @{"Sign Extension" link C_Elextw} @endnode @node C_ElWtst "Bits / Bit Testing" @toc BitContents @{b}Command Syntax@{ub} =ElWtst( @{i}BIT , ADDR @{ui}) =ElLtst( @{i}BIT , ADDR @{ui}) @{b}Description@{ub} The AMOS =Btst function allows you to detect if a bit is set in a given byte of memory, or in an integer variable. EasyLife provides these two functions to test if a bit is set in words/longwords of memory. @{i}BIT @{ui}is the bitnumber to test. Bits are numbered from the right, 15 being the highest bit of a word, and 31 the highest bit of a longword. @{i}ADDR@{ui} is the address of the word/longword to test. True is returned if the bit is set in the given word/longword. @{b}Notes@{ub} - The second argument @{i}ADDR @{ui}is always taken as an address, even if it is a simple variable, and not a complex expression. To test the bits of a variable use the AMOS =btst function - this allows you to test all 31 bits of integer variables. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} BIT must be in the range 0-15 for words, and 0-31 for longwords. @{i}ADDR @{ui} must be a valid even address. @endnode @node C_ElWset "Bits / Bit Modifying" @toc BitContents @{b}Command Syntax@{ub} ElWset @{i}BIT , ADDR @{ui} ElLset @{i}BIT , ADDR @{ui} ElWclr @{i}BIT , ADDR @{ui} ElLclr @{i}BIT , ADDR @{ui} ElWchg @{i}BIT , ADDR @{ui} ElLchg @{i}BIT , ADDR @{ui} @{b}Description@{ub} These commands are equivilent to AMOS Bset,Bclr and Bchg instructions, but they allow you to modify the bits of words & longwords of memory. ElWset sets bit @{i}BIT @{ui}of the word at address @{i}ADDR@{ui}. ElWclr clears bit @{i}BIT @{ui}of the word at address @{i}ADDR@{ui}. ElWchg inverts bit @{i}BIT @{ui}of the word at address @{i}ADDR@{ui}. The ElL... commands perform the same functions on longwords. @{b}Errors @{ub} @{u}Illegal Function Call@{uu} @{i}BIT @{ui}must be in the range 0-15 for words, and 0-31 for longwords. @{i}ADDR @{ui} must be a valid even address. @endnode @node C_Elextw "Bits / Sign Extension" @toc BitContents @{b}Command Syntax@{ub} = ElExtb( @{i}NUM @{ui}) = ElExtw( @{i}NUM @{ui}) @{b}Descrition@{ub} These functions will sign extend numbers from bytes/words to long words. To see what this means, imagine AMOS integers as 32 bit binary numbers e.g. 42 is: 00000000 00000000 00000000 00101010 * Sign extending from a byte (ElExtb) looks at bit 7 (*) and copies it's value into all the bits to it's left. This has no effect on the number 42, but 139 is changed: 00000000 00000000 00000000 10001011 * returns: 11111111 11111111 11111111 10001011 AMOS will interpret the new bit pattern as -117,because 10001011 is the bit pattern for -117 in signed 8 bit arithmatic, but for 139, in unsigned 8 bit arithmatic. ElExtw copies bit 15 into all the places to it's left. Extb & Extw can be used to translate signed bytes & words into AMOS integers. @{b}Notes@{ub} - The state of bits 32-16 (Elextw) / 32-8 (Elextb) is ignored by the sign extension. Only bits 15/7 count. - Both commands sign extend to a longword unlike the 68000 sign extension instructions on which they are based. @endnode @node FontContents "Fonts / Contents" @toc main @{b}@{u}New Font Commands@{ub}@{uu} The original font handling of AMOS was, to put it mildly abyssmal. Easylife provides you with a system to locate the font you want quickly & easily, and you won't have to worry about it being flushed out of memory because AMOS thinks your not using it anymore. @{"=Elopen Font " link C_ElopenFont} @{" Elset Font " link C_ElsetFont} @{" Elclose Font " link C_ElcloseFont} @{" Elclose Fonts " link C_ElcloseFont} @{"=Ellock Font " link C_EllockFont} @{" Elunlock Fonts " link C_EllockFont} @endnode @node C_ElopenFont "Fonts / Opening A Font" @{b}Command Syntax@{ub} =Elopen Font ( @{i}NAME$ , SIZE @{ui}) @{b}Description@{ub} When you want to use a new font, call Elopen Font giving the name of the font (Including a ".font" at the end), and the point size of the font, and you will be returned a font ID number to use with Elset Font. If the font you request is not in memory, it will be loaded from disk. @{b}Notes@{ub} - The value returned is a pointer, not a consecutive integer like AMOS font numbers. - You do not need to use any of the AMOS 'Get Fonts' commands - Elopen Font is a replacement for these. - If you open the same font twice, you are returned the original pointer the second time, and the font is only actually opened once. Therefore you should only close it once. - You can access the AmigaOS 'TextFont' structure of the opened font with: F=Open Font("topaz.font",8) TF=Leek(F+4) TF is now the address of the TextFont structure for topaz 8. @{b}Errors@{ub} @{u}Can't open diskfont.library@{uu} Either diskfont.library is not in LIBS:, or there is not enough memory to load it. @{u}Unable to lock font@{uu} The font you have specified cannot be found. @endnode @node C_ElsetFont "Fonts / Using Fonts" @{b}Command Syntax@{ub} Elset Font @{i}FONTID@{ui} @{b}Description@{ub} This command behaves the same as the AMOS 'Set Font' command, except it take a FONTID returned from Elopen Font as a parameter instead of an AMOS font number. See the AMOSPro manual on Set Font for more information. @{b}Notes@{ub} - You do not need to use any of the 'Get Fonts' commands before using Elset Font. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} The parameter you supplied is not a FONTID returned from Elopen Font (Or it has been closed again). @endnode @node C_ElCloseFont "Fonts / Closing A Font" @{b}Command Syntax@{ub} Elclose Font @{i}FONTID@{ui} Elclose Fonts @{b}Description@{ub} Elclose Font is called to tell the OS that you are finished using a font you have previously opened, and that it is free to deallocate the memory assigned to that font if no other task is using it. The parameter must be a font returned by Elopen Font. Elclose Fonts closes all fonts that are currently open. This command is automatically called by the easylife default routine. @{b}Errors@{ub} @{u}Illegal Function Call@{uu} The parameter you have passed to Elclose Font is not an open FONTID. @endnode @node C_EllockFont "Fonts / Old Commands" @{b}Command Syntax@{ub} =Ellock Font( @{i}NAME$ , SIZE @{ui}) Elunlock Fonts @{b}Description@{ub} These 2 commands have been removed from easylife, as they were unreliable with KS2.0+, and have been superceeded by the new Open/Close/Set font commands. @endnode @node PackContents "XPK / Powerpacker Compression - Contents" @toc main @{u}@{b}Powerpacker & XPK Compression@{ub}@{uu} @{u}Section 1: Powerpacker@{uu} @{"What Is Powerpacker? " link WhatIsPp} @{"Loading The Library " link C_ElppKeep} @{"Loading Crunched Data " link C_ElppLoad} @{"Accessing Buffers " link C_ElppBuf} @{"Removing Buffers " link C_ElppFree} @{"Manual Buffer Allocation" link C_ElppAllocate} @{"Saving Crunched Data " link C_ElppCrunch} @{"Loading via XPK " link C_ElxpkBload} @{u}Section 2: XPK@{uu} @{"What Is XPK? " link WhatIsXPK} @{"Loading Crunched Banks" link C_ElxpkLoad} @{"Loading Crunched Data " link C_ElxpkBload} @{"Saving Crunched Banks " link C_ElxpkSave} @{"Saving Crunched Data " link C_ElxpkBSave} @{"Length of an XPK file " link C_ElxpkLof} @{"Listing Packers " link C_ElxpkList} @{"Handling XPK Errors " link C_ElxpkError} @endnode @node WhatIsPp "Compression / What Is Powerpacker?" @toc PackContents @{u}@{b}What Is Powerpacker ?@{ub}@{uu} Powerpacker is a popular Program and Data cruncher for the amiga, written by nico francois (Also author of reqtools). Early versions were public domain, but more recent & much faster, not to mention more efficient versions are commerical programs. Easylife not only allows you to load data crunched with powerpacker into your AMOS programs, but also lets you save data crunched with the powerpacker algorithmn using the speed & high compression ration of the latest commerical version. (I.E. It calls powerpacker.library :-) You Can: - Read files crunched in data mode by powerpacker or any compatable program. - Load the files crunched by Easylife into powerpacker, ppmore etc. - Crunch any block of memory and save it to a file. However, you cannot: - Read or Write crunched executable files / segments. Easylife only loads & crunches as data. - Use Powerpackers encrypted mode for reading or crunching. This is because it pops the password window up on an intuition screen. You can also load powerpacked data directly to an AMOS bank using the @{"Elxpk Bload" link C_ElxpkBload} function. @endnode @node C_ElppKeep "Compression / Loading The Powerpacker Library" @toc PackContents @{b}Command Syntax@{ub} ElPp Keep On ElPp Keep Off @{b}Description@{ub} To use the commands @{"ElPp Load" link C_ElppLoad} & @{"ElPp Crunch" link C_ElppCrunch}, the powerpacker library version 35 or greater is needed, therefore the file powerpacker.library (supplied) must be in LIBS: The library is loaded into memory when you first use either of these commands, but may sometimes be removed again by the exec memory manger afterwards. To make sure the library stays in memory these two commands are provided. Using Pp Keep On makes Easylife load the powerpacker library if it is not already in memory, and prevents being removed from memory until you use Pp Keep Off. Pp Keep Off does not always removed the library from memory - other processes may also be using it, but it informs the memory manager that EasyLife has no objection to it being removed. @{b}Notes@{ub} - Pp Keep Off is automatically called when you use the AMOS @{"Default" link CommandEffects} command. @{b}Errors@{ub} @{u}Unable To Load PowerPacker Library V35+@{uu} Either the file powerpacker.library is not in LIBS:, the device LIBS: could not be accessed, or the version of the library in LIBS: is not high enough. A suitable version of the library is supplied with EasyLife. @endnode @node C_ElppLoad "Loading Powerpacked Data" @toc PackContents @{b}Command Syntax@{ub} ElPp Load @{i}BUF , FILE$ , DECRUNCH @{ui} @{b}Description@{ub} This command will load a file into memory, then decrunch it, if it was compacted with powerpacker. @{i}BUF @{ui}is a number from 0-7 used to choose which of the 8 buffers to load the file into. @{i}FILE$ @{ui}is the name of the file to load. It is important that the full path be given, and that the file exists. E.g. If F$<>"" If Exist(F$) Pp Load 0,F$,2 Else Print "File Not Found" End If End If @{i}DECRUNCH @{ui}must be an integer between 0 and 4, and determines what happens while the file is decrunched. I recommend that option 3 is not used with AMOS screens, but it does not generate an error message, as your program may run on an intuition screen, if you have the intuition extension. 0 : Flash colour 0 1 : Flash colour 1 2 : Flash colour 17 (Mouse Pointer - Recomended) 3 : Wobble Screen (No effect on AMOS screens) 4 : Do nothing while decrunching @{b}Notes@{ub} - If the chosen buffer already contained data, it is freed first. - Pp Load will load uncrunched data without any problems, so you don't have to worry about whether the file you are loading is crunched or not. The only problem is if it was not crunched with powerpacker. - AMAL & Bobupdates etc. are temporarily suspended while decrunching takes place. @{b}Errors@{ub} @{u}Can't Load Powerpacker Library V35+@{uu} The [4\2\Powerpacker Library] is required to be in LIBS: even if the file your are loading in not crunched. @{u}Illegal Powerpacker Header@{uu} Either the file is corrupt, was crunched with unrecognised version of powerpacker, or was not crunched as a "Data File". @{u}File Encrypted - Can't Decrunch@{uu} Easylife does not support decrunching encrypted files. @{u}Out of Memory while Loading / Decrunching File@{uu} Oh no! (As the lemming said to the warhead...) @{u}Unable To Open File@{uu} Powerpacker library could not open the filename you passed it. It probably means it doesn't exist, but it could be read protect bits, or another reason. @{u}Error Reading File@{uu} A Disk Error occured while reading in the crunched file. @endnode @node C_ElppBuf "Compression / Accessing PowerPacker Buffers" @toc PackContents @{b}Command Syntax@{ub} = ElPp Buf( @{i}NUM @{ui}) = ElPp Len( @{i}NUM @{ui}) @{b}Description@{ub} An Easylife Powerpacker Buffer is similar to an AMOS bank of type "work". ElPp Buf returns the address of the start of the buffer. It is similar to the start() function for banks. ElPp len returns the length of the buffer. It is similar to the length() function for banks. Vaild buffer numbers are 0 - 7. The main differences between buffers & 'work' banks are: - A Buffer can be created explicitly with the ElPp Allocate command, or implicitly by the ElPp load function. ElPpLoad cannot load directly to a bank. (However this can be done via the @{"Elxpk Load" link C_ElxpkLoad} function. - If you try to recreate an existing buffer, the old buffer is freed first. You do not get an error, as you would with AMOS banks. - In AMOS Creator, one set of powerpacker buffers is shared between all AMOS programs. If you have two programs loaded into AMOS, and one Prun's the other, the second will share the same buffers with the first. Therefore powerpacker buffers can be used to hold shared data. @{b}Notes @{ub} - ElPp Buf & ElPp Len do not require the powerpacker library. - The buffer can be saved with either Bsave, or @{"ElPp Crunch" link C_ElppCrunch}, or @{"Elxpk Bsave" link C_ElxpkBsave}. - If the buffer is not allocated, both functions return 0. - You can also use @{"Elmem$" link C_ElmemRead} to transfer the buffer contents to the AMOS variable buffer. If the file is a text file, you can read it one line at a time with: ElPp Load 0,file$,2 POS=0 While POS