Sortz VBX, Version 1.0
Copyright (c) 1995, Martin Bryant, All Rights Reserved

Introduction
------------
The SORTZ.VBX file is a custom control suitable for use with such
programming languages as Visual Basic, Visual C++ and Delphi. It provides an
efficient sort engine for numeric or string data stored in arrays of simple
data types or user-defined types, and can work with 'huge' arrays (>64K).

Shareware Notice
----------------
Sortz VBX is shareware. You are welcome to use it for a trial period but if
you continue to use it then please register and support the shareware
concept. You may freely copy/distribute the shareware version as long as you
make no charge for it. If you register, then you may use it in commercial
products with no royalty fee. Thank you for trying Sortz VBX!
You can register by sending £10 sterling or equivalent foreign currency
(cash preferred!) to Martin Bryant, 71 Hunstanton Drive, Brandlesholme,
Bury, Lancashire BL8 1XH, England.
Registered users receive free updates and a full list of our other products.
Constructive comments/criticisms welcome at the above address or email
martinbr@colossus.demon.co.uk

Compatibility
-------------
SORTZ.VBX is compatible with level 1 VBX controls.

Appearance
----------
When added to a program the control appears in the toolbox as some sorted
data. It is non-sizable on a form and is invisible at run-time.

Properties
----------
In addition to the standard properties of Name, Index, Left and Top it also
has the following custom properties...

About (read only)
Gives version and copyright information.

Action (write-only/run-time only)
Set to any value to initiate the sort.
e.g. Sortz1.Action=0

ArrayPointer (write only/run-time only)
Passes the base address of your array into the control using the Windows API
Lstrcpy function. See the examples section later for exact details of how to
do this.
e.g. Sortz1.ArrayPointer = Lstrcpy(a(), a()) 'pass address of VB HAD
or...Sort\1.ArrayPointer = Lstrcpy(a(1), a(1)) 'pass address of 1st element

ArrayPointerType
The base address of your array can be passed in two ways. Firstly it can
simply be a far pointer to the first element of the array. This works fine
for single segment arrays (VB and Delphi arrays <64K) and huge memory object
arrays (memory allocated by GlobalAllocPtr possibly >64K). Alternatively,
because VB has its own internal format for 'huge' arrays, you can pass the
address of the array descriptor (HAD) to the control. Either way, you must
inform the control what type of pointer you are passing.
e.g. Sortz1.ArrayPointerType = 1

ArraySize
Defines the number of elements (NOT the number of bytes) in the array.
e.g. Sortz1.ArraySize = UBound(a) - LBound(a) + 1

BeepOnError
If the control detects any errors it will, by default, produce a 'beep'.
This can be turned off by setting this property to false.
e.g. Sortz1.BeepOnError = False

ElementSize
Defines the number of bytes per array element.
e.g. Sortz1.ElementSize = 2
will define each element to have 2 bytes.
Common VB data types have the following sizes:- Integer(2), Long(4),
Single(4), Double(8), Currency(8), String(4), String*N(N). Arrays of
user-defined types obviously have to have their size calculated manually and
CAREFULLY to avoid internal errors.

Error (read-only/run-time only)
May return an error number as follows...
0 - no error
1 - array address not specified (via ArrayPointer property)
2 - SortFieldSize too big (limited to 16384 bytes)
3 - SortFieldStartOffset/SortFieldSize/ElementSize value(s) invalid
4 - ElementSize cannot be less than SortFieldSize
5 - specified SortFieldDataType not supported in shareware version

SortFieldDataType
An enumerated list allows you to tell the control what type of data the sort
field contains.
e.g. Sortz1.SortFieldDataType = 0
defines the data type to be a signed integer.
Note that the shareware version only supports integer fields e.g. Integer,
Long and Currency (stored internally as an 8-byte signed integer). The
registered version also supports all standard floating point formats and
variable-/fixed-length strings.
Note that the SortFieldSize property can be used to specify the length of
integers and fixed-length strings.

SortFieldSize
Defines the number of bytes the sort field occupies. If the array is of a
simple type, then SortFieldSize will be equal to ElementSize. However in
user-defined types the field to sort the array on, may be one of many, and
hence SortFieldSize would usually be less than ElementSize.
e.g. Sortz1.SortFieldSize = 2
Common VB data types have the following sizes:- Integer(2), Long(4),
Single(4), Double(8), Currency(8), String(4), String*N(N).

SortFieldStartOffset
Defines the byte offset from the start of each array element at which the
sort field begins. If the array is of a simple data type then
SortFieldStartOffset will be zero. However in user-defined types you must
calculate how many bytes into each element the sort field starts.
e.g. Sortz1.SortFieldStartOffset = 4

SortOrder
Select 0 for ascending sort, 1 for descending sort.
e.g. Sortz1.SortOrder = 1

The default Name property prefix and class name is 'Sortz'.

Example
-------
The following code segment sorts an array of 100 integers.

Declare Function Lstrcpy Lib "kernel" (p1() As Any, p2() As Any) As Long

Dim a(1 To 100) As Integer

Dim i

For i = LBound(a) To UBound(a) 'initialise array to random values
    a(i) = Rnd * 64000 - 32000
Next

sortz1.ArraySize = UBound(a) - LBound(a) + 1 '100-1+1=100
sortz1.ArrayPointerType = 1 'VB 'HAD' ('Handle to Array Descriptor')
sortz1.ElementSize = 2 'VB 'Integer' occupies 2 bytes
sortz1.SortFieldDataType = 0 'signed integer
sortz1.SortFieldStartOffset = 0 'simple data type array
sortz1.SortFieldSize = 2 'VB 'Integer' occupies 2 bytes
sortz1.SortOrder = 0 'ascending order
sortz1.ArrayPointer = Lstrcpy(a(), a()) 'pass address of 'HAD'
sortz1.Action = 0 'do it!

Notes
-----
Sortz VBX can handle arrays of VB fixed length strings but you will have
to modify the declaration of the Windows API Lstrcpy function as follows,
as VB fixed length strings are NOT compatible with the 'Any' type!
e.g. for 100 character strings
Declare Function Lstrcpy Lib "kernel" (p1() As String * 100, p2() As String * 100) As Long
Dim a(1 To 10) As String * 100

Delphi users should pass the address of the 1st element of the array to the
control. (VB users can do this but only for single segment arrays. It is
also slightly more efficient to use this method.)

Note that the control has a different SortFieldDataType for VB variable
length strings when in a simple array and in a user-defined type.

Events
------
The control has no pre-defined events.