Variables and Types
Updated: June 2, 2005

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]
SINGLE   !     4     floating  Yes   [aka REAL4]
DOUBLE   #     8     floating  Yes   [aka REAL8]
REAL10        10     floating  Yes
VARIANT        4     integer   No    [Usually a pointer (address)] 
STRING   $    Varies string    N.A.  [Is an "Object" in HotBasic]

The suffix is 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 in Declare
statements 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, especially 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.

For example, REAL10 provides 63-bit integer precision, most of what INT64 has.


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 +, FILE, FPU **, LIST, MEMORY, RECT, REGISTRY, SOCKET, SQLDATA,
  SQLITE, STRING, TIMER

with GUI (+) objects

  BUTTON, CANVAS, CHECKBOX, COLORDIALOG, COMBOBOX, 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, 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, should that be convenient, just like 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.
hotudt.bas and arrayudt.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 "Custom Objects" (hotobj)
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
    '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 as many dimensions (subscripts) as you want,
(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

Multi-dot syntax -- MyGraphic.pt1.x -- implies a tree structure and is not
used.  Instead we write MyGraphic.x1.  [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.]


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


###########

** Planned future additions to HotBasic

+  Penthouse (Registered) version

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