______________________________________________________________________________
..............................................................................
...................................................................2222222....
................................................................22222222220...
...................................................222........222222.....222..
..............................................2202222222222..22000............
..................................22000.....20222222222200000200002...........
.................................2002202...2222200222.220000000200000000022...
....................220002......22222200..2200002.......2200000...20000000000.
....................22222202....2220000022200000..........200002........200000
.....200000.........2222200000222200220000000002..........200002........20000.
.....00222202........2220022000000002200002000002........2000002000020000000..
....2222200000.......220002200000002.2000000000000222222000000..2000000002....
....220000200002......20000..200002..220000200000000000000002.......22........
...2220002.2200002....220002...22.....200002..0000000000002...................
...220000..222000002...20000..........200000......2222........................
...000000000000000000..200000..........00002..................................
..220000000022020000002.200002.........22.......______________________________
..0000002........2000000220022.................|
.200000............2002........................| JVP-NoKids Extension
.200002........................................| for AMOS Pro v1.0+
220002.........................................|______________________________
______________________________________________________________________________

 Welcome to the JVP-NoKids Extension for AMOS Pro.....
 (Sorry for my bad English)

 This Extension is "MailWare", please send me a mail if you use it and maybe
 tell me what you'd like to see included....

 -----------------------------------------------------------------------------

 You can contact me by snail-mail:                          Jens Vang Petersen
                                                                       Nyvej 8
                                                               DK-4450 Jyderup
                                                                       Danmark

 Or E-mail:                                              top_cat@post8.tele.dk

 -----------------------------------------------------------------------------

 Ohh just a quick one, I hate writing manuals, so this will have to do, if
 anyone outthere loves to write, then feel free to improve this doc..
  - I am a programer, not a bookauthor -

/-----------------------------------------------------------------------------\
|  Why another extension ???                                                  |
\-----------------------------------------------------------------------------/
 Good question, I made a music-database recently and gave it to a friend of
 mine, well, when I should demonstrate it on his A2000, I happend to click on
 the sortfunction with more than 2000 posts in.. Yack, Boy was that slow,
 anyway I needed a quick sort-routine that also should be customiseable to
 the stupidious limit...
 That's how it started out, I've later added some extra commands I needed
 when programing large serious programs.
 Oh yes, I promise that this won't be an extension wich include Disk-commands
 and PT-replayer, there are enough of them allready.

 NOTE: None of the commands in this extension is dedicated to the beginner in
       AMOS, they are almost all very easy to foul up with. Please read the
       folowing very carefully before using the commands, and remember to
       save you work often.


/-----------------------------------------------------------------------------\
|  How to install ???                                                         |
\-----------------------------------------------------------------------------/
 Well, if you're a experienced AMOS-user, then I need not to tell you how to
 install extensions onto your system. If you're not, then I don't think this
 extension will be usefull to you..
 Just plain and simple: The extension is supposed to be at slot nr. 25..
 (Feel free to recompile the source-code with another number..)


/-----------------------------------------------------------------------------\
|  What happens when ??                                                       |
\-----------------------------------------------------------------------------/
 Default/Run: Several things are done, for a full explination of each step
              look further down in this docs.
              - "Jvp Str Len" are set to 20 for all strings
              - "Jvp Str Sep" are set to " " for all strings
              - "Jvp Bin Sort Type" are set to 0 (Dos-strings)
              - "Jvp Set Msg Bank" are restored to point a NO bank


/-----------------------------------------------------------------------------\
|  [01] Sorting commands (02 commands):                                       |
\-----------------------------------------------------------------------------/
 Syntax:  Jvp Bin Sort Type VAL
 Options: VAL currently either 0 or 1, determains what type of string you
          would like to sort on. 0 indicates DOS-type strings, 1 indicates
          standard AMOS-Strings.
 NOTE:    VAL defaults to 0 (Dos strings), you should call this command before
          starting a Sort operation to be sure..
          If you use the wrong VAL before a sort, it might crash your computer
          or at least give stange results, no checking is done..
          VAL can take values between 0 and 255, if you enter anything else
          that 0 then the sort will asume AMOS strings, this might change in
          future versions, so keep the 0 or 1 value..

 -----------------------------------------------------------------------------
 Syntax:  Jvp Bin Sort SRC,ANT,MAP to DEST,WORK
 Options: SRC  Depends on the Sort Type, see later..
          ANT  How many strings have you got
          MAP  Translation map for characters, see later..
          DEST Memoryarea to hold indexes for the sorted list    (!)min 4*ANT
          WORK Memoryarea to use for workspace              (!)min 16*(ANT+3)
 NOTE:    This command has been optimized for speed, and contains no error-
          checking at all. You MUST make sure that the memory needed is
          present at the adresses you deliver to the routine. The command
          needs quit a large amount of memory, due to the fact that it uses
          a Binary sort (also know as Tree-Sort). Good for speed, bad for
          memory..
          Remember: If you are comming from an array, then the ANT number is
          LastElement+1 (0 is an element too) !!!!

 - SRC    This is a pointer to an adress-list of the strings you want to sort,
          each string should be adresses at it's ABSOLUTE adress as a Long-
          Word, the type of strings these adresses point at depends on what
          you have set using "Jvp Bin Sort Type".
          DOS-Strings: Each adress MUST point at the FIRST character of the
                       string. The string MUST be terminated by a control-
                       character [<Chr$(32)]. Normaly you should use Chr$(0)
                       for standard DOS format, but eg. code 10 or 13 would
                       do just fine
          AMOS-Str's:  Each adress MUST point to the start of an AMOS-String
                       definition, NOT the first character. The AMOS format
                       has the length of the string put in the first two
                       positions of the definition, folowed by the string
                       itselfe.. (This way opens for a little twist later on)
                       if you want to create your list with Varptr calls,
                       then you should use adress=Varptr(n$)-2, that should
                       take care of it...
          The SCR-list itselfe could be reserved as a bank with the length of
          ANT*4, but due to the layout they can also be layed as a one-
          dimensional array, simply put an adress into each position of the
          array and call the instruction with : Varptr(a(0)) as SRC.
          There's another little catch for people calling with AMOS-strings
          only, if your strings are in a standard one-dimensional array, then
          you can transfer the adresses by simply calling the instruction with
          Array(n$(0))+6 as SRC, the +6 is becouse of the header information
          in the Array data area. THIS ONLY WORK IN AMOS-STRING MODE...
          (There are some tricks for multidimensional array's see HINTS)

 - MAP:   That's the big one, the one that enabels you to make almost any type
          of sorting. This should point to a bank of 256 bytes here you place
          values on how the verious characters should be treated. Using this
          correctly, opens up for making A=a or the opposite, have the system
          sort special characters as you'd like, or even backwood sorting..
          The map is working like this:
           -Every time a comparison is made the map is used like this:
                       SortValue=Peek(MAP+Asc(Char$))
          A simple map would be to just poke 1 at MAP+1, 2 at MAP+2 etc.
          but by changing these values you can make lots of stuff:
          put asc("A") at asc("a") would equel these characters. When you
          start a new bank you should start out by putting 1 at 1, 2 at 2
          until 255 at MAP+255, after that you can start moving the values..
          NOTE: If you don't set up you map properly, then the sorting will
          work strange. Some characters will sudenly be placed in front of
          all others..

 - DEST:  Should point to an area where the search results can be
          placed. this area should be just as long as the ADLIST, in
          fact, you could simply use the same area (See HINTS)
          NOTE: you won't get any adresses or strings back, but an index-
          number that shows where the string should be placed.
          If you'd like to make things easy then point this to a one-dim.
          integer-array with "Varptr(n(0))" then you can get your strings
          with something like: "String$=T$(n(nr))

 - WORK:  (Adress or Bank number)
          Points to a safe area of memory, to be used internaly by the sort,
          length of this area MUST be at least (Ant+3)*16, Normaly you should
          reserve a workbank for this use, and simply hand over the bank-
          number..
          NOTE: The memory area is NOT checked in any way, so make sure you got
          it right, or CRASH......
          Everything in the memoryarea will be ERASED, so don't point it to
          something importaint...



 HINTS: - To save some memory you could let the SRC and DEST point to the same
          adresses in memory, just remember that you'll lose your adresslist,
          if you do that..
          If you have an adress list in a 2 dimensional array and want to sort
          on e.g. A(6,n) where the n is just indexnumber of the varoius strings
          you can call it up with Varptr(A(6,0)) that should do the trick. As
          long as the last dimension in the array is the one to run through a
          sort then this will work. but if you want to sort A(n,6), well then
          you have to transfer all the adresses to somewhere else and then run
          the sort....


 Example: There should be 2 example programs included with this extension
          "SortExample1" shows sorting on AMOS-Type strings.
          "SortExample2" shows sorting on DOS-Type strings.
          Both exampels also shows how to build a MAP definition..


/-----------------------------------------------------------------------------\
|  [02] Stringformating commands (04 commands):                               |
\-----------------------------------------------------------------------------/
 Whenever you need to show something on screen, you need to format it somehow
 but if you wanna use the AL in the interface, and have more than a simple
 list of itims to show, then you need to fill in some spaces and perhaps
 shorten some of the strings to make it look good, in plain AMOS this is
 complicated, and not very quick.. This group of commands makes this process
 a bit easier and faster, and can combine up to 6 varoius strings 
 -There should be an example somewhere, showing what this can do

 -----------------------------------------------------------------------------
 Syntax:  Jvp Set Str Len s1,s2,s3,s4,s5,s6
 Usage:   Simple instruction, indicates how many character should be used form
          each string when using the functions later on, if the strings are
          shorter than indicated they will be padded by spaces.
 NOTE:    Set the length to 0 if you don't want to use this pos.
          All lengths defaults to 20

 -----------------------------------------------------------------------------
 Syntax:  Jvp Set Str Sep s1,s2,s3,s4,s5,s6
 Usage:   Determains what character should be placed AFTER each string, simply
          enter the ASCII code you'd like.
 NOTE:    If a seperator is set to 0, the there won't be placed a seperator,
          use this to disable the seperators you don't want.
          If a string-length is set to 0 then NO seperator will be added.
          All Seperators defaults to " "=Chr$(32)..

 -----------------------------------------------------------------------------
 Syntax:  Jvp Set Str Sep s1
 Usage:   Like previous, but sets ALL seperators to chr$(s1)

 -----------------------------------------------------------------------------
 Syntax:  Jvp Set Str Sep
 Usage:   Like previous, but sets ALL seperators to DEFAULT (" ")

 -----------------------------------------------------------------------------
 Syntax:  s$=Jvp Str$(ad1,ad2,ad3,ad4,ad5,ad6)
 Usage:   Combines the DOS-strings at the entered adresses as defined by the
          commands above.. (All strings MUST be terminated by <chr$(32)

 -----------------------------------------------------------------------------
 Syntax:  s$=Jvp Cstr$(s1$,s2$,s3$,s4$,s5$,s6$)
 Usage:   Combines the entered strings as defined by the commands above..
          (These strings are standard AMOS strings, and do NOT need to be
          terminated by anything special, they may if you'd like..)


/-----------------------------------------------------------------------------\
|  [05] Message Banks Commands (0? commands)                                  |
\-----------------------------------------------------------------------------/
 Ever tried to localize a program ?, ok used the Local extension ?, well that
 don't work on 1.3. Hmm. Ok then check this out, a bank to hold all your texts
 to be used in a program. Install a number of banks with various texts, and
 alow the user to chose a bank, then set that bank and don't bother anymore
 sounds good ??... Ok, then this is for YOU....
 The Msg system is build like a 3 dimensional array (Group,Sub,Itim), the
 reason is that I've found that you would normaly have a Group for each
 main-part of the program, then you have a Subgroup for pull-down-menus, one
 for click-buttons, one for errors etc.......
 NOTE: These commands are curently the only ones which includes errortexts..
 - There is an accessory program included with the extension, that converts
   a standard text-file into a message bank, check out the included text-file
   to see how to write your message-texts...
 - An example text-file for use with the accessory is included in the exampels
   drawer..

 -----------------------------------------------------------------------------
 Syntax:  Jvp Set Msg Bank NR
 Usage:   Sets the bank to be used by all other Msg commands...

 -----------------------------------------------------------------------------
 Syntax:  =Jvp Msg Bank
 Usage:   Returns the number of the current MsgBank, 0 if none is active

 -----------------------------------------------------------------------------
 Syntax:  =Jvp Msg Exists(G,SG,IT)
 Usage:   Checks if a given message is present, Returns:
          -3 If Itim-number is out of range
          -2 If SubGroup is out of range
          -1 If Groupnumber is out of range
          0  If the numbers are legal, but no message has been defined.
          Other values means that a message was found, and points to the
          structure of the text (See later)
 Note:    If you havn't set a correct Bank then an error will be reported.

 -----------------------------------------------------------------------------
 Syntax:  =Jvp Msg$
 Usage:   Returns the special Tittle field of the bank, if none have been
          defined then you'll get an empty string
 Note:    If you havn't set a correct Bank then an error will be reported.

 -----------------------------------------------------------------------------
 Syntax:  =Jvp Msg$(G,SG,IT)
 Usage:   Return the message of the given cordinates, if no message have been
          defined or the numbers are out of range, you'll get an empty string.
 Note:    If you havn't set a correct Bank then an error will be reported.

 -----------------------------------------------------------------------------
 Message Banks:
 -Ok here are the format of the message banks, so if you like to write your
  own without using the included accessory, then kick it...
  Remember that ALL pointers in the bank are relative to the start of the
  bank, they are not offsets from a present location...

  The main header structure:
    0000 $0000 "MSGB" ; Identifier for a msg-bank
    0004 $0004 Lw     ; Pointer to title stored in a stringstructure
    0008 $0008 Lw     ; Pointer to Grouplist-structure (Normaly 20/$14)
    0012 $000B Lw     ; Reserved, leave to 0
    0016 $0010 Lw     ; Reserved, leave to 0

  The grouplist-structure (Normaly starting at 20/$14):
    0000 $0000 W      ; Last groupnr in bank (Total-1)
    0002 $0002 Lw     ; Pointer to GroupStructure 0
    0006 $0006 Lw     ; Pointer to GroupStructure 1
    0010 $000A Lw     ; Pointer to GroupStructure 2
    .
    .
    ---- $---- Lw     ; Pointer to Groupstructure (Last)
   NOTE: even if no group is defined group 0 MUST be setup

  The Group-structure
    0000 $0000 W      ; Last subgroup in group
    0002 $0002 Lw     ; Pointer to SubStructure 0
    0006 $0006 Lw     ; Pointer to SubStructure 1
    .
    .
    ---- $---- Lw     ; Pointer to SubStructure (Last)
   NOTE: If no subgroup is defined in the group, Substructure 0 MUST be
         created.

  The Sub-Structure
    0000 $0000 W      ; Last itim in Subgroup
    0002 $0002 Lw     ; Pointer to string 0
    0006 $0006 Lw     ; Pointer to string 1
    .
    .
    ---- $---- Lw     ; Pointer to string (last)
   NOTE: If no strings is defined in the subgroup, stringstructure 0 MUST
         be pointed (Just set it to 0 for no string defined)
         If no string is to be defined at the current position, leave the
         pointer to 0..

  The String-Structure (Folows standard AMOS-format)
    0000 $0000 W      ; Length of string
    0002 $0000 "....  ; The string itselve.

 NOTE: ALL structures MUST begin at EVEN adress....
       The Subgroups are independent of eachother, that means that you may
       have 100 texts in one subgroup and just 2 in another without defining
       98 you don't need. The same goes for the number of subgroups in each
       group, just define as many as you need in each area, you may also
       jump in the numbers anywhere, just leave the space for the pointers.
       If you'd like to jump in group-numbers then you have to define a
       subgroup 0 with a string 0 in (The string may be empty). Should you
       need many of these empty groups, then you can make them point to the
       same structure, thereby saving 12 bytes in each group.

/-----------------------------------------------------------------------------\
|  [04] Misc. Commands (01 commands)                                          |
\-----------------------------------------------------------------------------/
 Syntax:  v=Jvp Version
 Usage:   Simple function, returns the versionnumber*100 of this extension
 Example: Version 1.00 will return 100 in v
 Note:    This function should be in all extensions, I've seen too many that
          didn't have it.....

/-----------------------------------------------------------------------------\
|  [A]  Extension History                                                     |
\-----------------------------------------------------------------------------/

 V0.5, First version to be released
  - Includes:
     Jvp Bin Sort

 V0.6
  - New Commands
     Jvp Bin Sort Type
  - Changed:
     Jvp Bin Sort : To accept AMOS-strings

 V0.7
  - New Commands
     Jvp Set Str Len
     Jvp Set Str Sep
     =Jvp Str$

 V0.8
  - New Commands
     =Jvp Cstr$

 V0.9
  - New Commands
     =Jvp Version

 V1.0
  - New Commands
     Jvp Set Msg Bank
     =Jvp Msg Bank
     =Jvp Msg Exists
     =Jvp Msg$

 Future Plans:
  - MemorySaving Sorting

 -----------------------------------------------------------------------------