Variables and Types
Updated: Apr 1, 2006

In coding jargon, a "qualified type" is a symbol which the compiler understands
as an item it can dimension.  "Dimension" just means the compiler allocates
memory space for the item and gives it the name used in the source code.

  DIM MyVar As INTEGER

sets aside 4 bytes of memory named with user symbol MyVar.


Qualified Types -- Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TYPE   SUFFIX BYTES  CATEGORY SIGNED   
BYTE     ?     1     integer   No    0 to 255
WORD     ??    2     integer   No    0 to 65535
DWORD    ???   4     integer   No    [often pointer or larger + integer]
SHORT    %     2     integer   Yes   -32768 to 32767
INTEGER  &     4     integer   Yes   -2147483648 to 2147483647
LONG     &     4     integer   Yes   [LONG is an alias for INTEGER]
INT64          8     integer   Yes   64-bit integer
SINGLE   !     4     floating  Yes   [aka REAL4]
DOUBLE   #     8     floating  Yes   [aka REAL8]
REAL10        10     floating  Yes
VARIANT       16     varies    --    [see usage in variant.bas]
STRING   $    Varies string    N.A.  [is an "Object" in HotBasic]

The suffix may be used with $TYPECHECK OFF (not recommended) so i& and c$ are
implicitly dimensioned as LONG and STRING respectively.

Use of a variable suffix does not change the need to specify Type for DECLARE
statement arguments and affects destination, not source, variables.

You probably know well that memory just contains bits -- 0 or 1.  The types
above help the coder to track what source code is doing and tell the compiler
how to handle the data, such as when one type is assigned to another type,
e.g., MyWordVar = MyReal4Var.  The hottypes.bas program shows exactly how
assignments are done.

This list of types is long enough to do any job and not so long that you have
to read long manuals to understand source coding.


Qualified Types -- Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~
Objects used without DIM statements are

  APPLICATION, CLIPBOARD, CONSOLE, FILEREC, FPU, MOUSE, PRINTER +,
  PROPERTIES +, SCREEN, VERSION

Objects which may be dimensioned are

  BITMAP +, COMPORT +, DATE, FILE, FPU **, LIST, MEMORY, RECT, REGISTRY,
  SOCKET, SQLDATA, SQLITE, STRING, TIMER, VARIANT

with GUI (+) objects

  BUTTON, CANVAS, CHECKBOX, COLORDIALOG, COMBOBOX, DATETIME, EDIT,
  FILELISTBOX, FINDDIALOG, FONT, FONTDIALOG, FORM, GUAGE, GRID, GROUPBOX,
  HEADER, IMAGE, LABEL, LISTBOX, LISTVIEW, MAINMENU, MENUITEM, OPENDIALOG,
  PAGEDIALOG, PANEL, POPUPMENU, PRINTDIALOG, RADIOBUTTON, REPLACEDIALOG,
  RICHEDIT, RICHEDIT2, SAVEDIALOG, SCROLLBAR, SPLASH, STATUSBAR, SYSTRAY,
  TABCONTROL, TOOLBAR, TRACKBAR, TREEVIEW, UPDOWN

and properties, methods and events for each are described in a section of these
notes.

Please note that STRING is an object in HotBasic and all the properties and
methods of the MEMORY and LIST objects apply to an ordinary STRING.  However,
strings as items in a STRING array or in a TYPE/OBJECT are fixed-length
buffers, not STRING objects themselves.

Object dimension example:

  DIM F As FILE, M As MEMORY
  F.OPEN("myfile.txt",2): M.LoadFromFile("myfile.ini")

User code may name (dimension) a number of objects for each of the above object
types.  For example, i, j and k may all be dimensioned As LONG.


Qualified Types -- User-Defined Types (UDT) and Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What if you don't see above what you need?  Just define your own type.
arrayudt.bas, construc.bas, hotudt.bas and typebyte.bas in HotTrial show
examples.

It is a one-two process: (1) TYPE statement block defines the type and
(2) DIM statement names instances or arrays of the UDT for use in code.

OBJECT is an alias for TYPE.  Please see Objects > Custom Objects for
constructor syntax in UDT structures and for EXTENDS syntax, used to add
properties, methods and/or functions to native HotBasic Objects listed above.

  TYPE INVENTORY
    description as string*64
    supplier as string
    part as long
    'etc
  END INVENTORY

The *n syntax above specifies its ram allocation -- 64 bytes.  If *n syntax is
omitted as for "supplier" above, the default length is 256 bytes.

For "As STRING" UDT items, HotBasic will never allow a UDT buffer overflow
when writing a text string to the item.  If your source data string is too
long, it is truncated.

With Custom Object syntax, "As SUB" and "As FUNCTION" represent additional
qualified types for new Object methods and functions respectively.

HotBasic does not (yet) have arrays as elements inside a UDT.  Many methods
may be used.  Here is a simple method using BYREF():

  TYPE HasArrays
    array1 as string*400
    array2 as string*800
    'etc
  END HasArrays

  DIM MyData As HasArrays, i As LONG, x As LONG

MyData.array1 has ram for 100 4-byte values.  To read 0-based value i:

  x = BYREF(@MyData.array1 + i * 4)  'x may be INTEGER or SINGLE

Reverse the above to write value i:

  BYREF(@MyData.array1 + i * 4) = x

Another approach is to

(1) dimension "scatch" ARRAYs with 1 to 5 subscripts,
(2) MEMCPY your UDT string into the ARRAY,
(3) do your data processing using conventional array subscripting and
(4) if necessary, MEMCPY back to UDT.

Nested types are often seen in reference material:

  TYPE POINT
    x as dword
    y as dword
  END POINT

  TYPE GRAPHIC
    item1 as dword
    pt1 as POINT  'nested type
    pt2 as POINT      
    'etc
   END GRAPHIC

GRAPHIC is in fact a contiguous ram area, just like POINT.  So we cut and paste
to write GRAPHIC in a usable form:

  TYPE GRAPHIC
    item1 as dword
    x1 as dword  'was .pt1.x
    y1 as dword
    x2 as dword  'was .pt2.x
    y2 as dword
    'etc
   END GRAPHIC

   DIM MyGraphic as GRAPHIC

Multi-dot syntax -- MyGraphic.pt1.x -- falsely implies a tree structure,
requires needless extra typing, is error prone and is not used.

Instead we write

   MyGraphic.x1 = x

[Don has written a program to automate this cut and paste and member-naming
process to translate from reference material to working TYPE structures for
source code; Yahoo! HotBasic > FILES.]


Constructor Syntax
~~~~~~~~~~~~~~~~~~
In a UDT, its "properties" are all read/write items.

Any TYPE/OBJECT (UDT) may be defined with default values with simple
CONSTRUCTOR syntax.  Both numeric and string OBJECT/TYPE items may be assigned
default values.

CONSTRUCTOR syntax is similar to that used in DEF... dimensioning statements
for variables (DEFINT, DEFSTR, etc).  See construc.bas in HotTrial.

One simply appends " = value" to the OBJECT/TYPE item line.  The value must be
an "immediate" or "literal" value -- that is, a number for numeric items or a
quoted string for string items in your OBJECT/TYPE code block.  The value
cannot be a variable or expression.

For numeric items, the value should match the item type (floating vs
non-floating).  "MyFloat as double = 1.5" and "MyInt as integer = 10" meet
this requirement.  A hex value such as &HA000 may be used.

For string items, consider the optional "* n" syntax where n is a literal
integer for maximum string length, exactly as done in DIM of string arrays.
If "* n" syntax is omitted, n defaults to 256.

The quoted string is truncated if longer than the item size.  With

  MyText As STRING*12 = "HotBabe Hello"

"HotBabe Hello" is truncated and the default .MyText item will be
"HotBabe Hell" -- something nobody wants!

At run-time all string assignments to OBJECT/TYPE string items are similarly
truncated if necessary to avoid buffer overflows.

  MyUDT.MyText = s$

is always logically the same as

  MyUDT.MyText = left$(s$,n) 'where n is maximum item size


Internal Variables +
~~~~~~~~~~~~~~~~~~
Case-sensitive, pre-dimesioned read/write variables include

For $AppType GUI:

  nCode (notify code), hWnd, uMsg, wParam, lParam 

For .OnDialog procedures (please see DIALOGS):

  hDlg, mDlg, wDlg, lDlg  'message information

For .OnPaint procedures and in .BeginPaint/.EndPaint or .GetDC/.ReleaseDC
code blocks,

  hbDC   'device context handle.

For SUB and FUNCTION procedures defined in Custom Objects:

  hbObj  'address of calling Object/Type structure
  hbHnd  'handle of extended FORM object, if applicable
         'or address of extended non-FORM object
  hbArgs 'pointer to variant array of input parameters
         'for Custom Object Invoke, Method, GetNum or GetStr


** Planned future additions to HotBasic

+  Penthouse (Registered) version

Copyright 2003-2006 James J Keene PhD
Original Publication: Oct 9, 2003
