MISCELLANEOUS Statements
Updated: Jan 18, 2007

BYTESWAP MyVar

  BYTESWAP i, where i is a 32-bit, non-floating value (INTEGER, LONG, etc)
  reverses the byte order of variable i.  Among other things, BYTESWAP can
  be used to convert back and forth from little-endian to big-endian
  representations.

  BYTESWAP is also a Numeric Function:  j = BYTESWAP (i).

DEC(MyVar[,amount])
INC(MyVar[,amount])

  Can use real numbers and fractional values for INC/DEC amount.

  The second optional operand in INC/DEC statements (amount) can be a numeric
  expression.  Thus, we can write:

    INC(i, j+k)

  or 

    INC(i, INSTR(s$,t$))

  INC/DEC are optimized to autodetect non-float values.

    INC(i,10): DEC(j,2): INC(k)

  is faster than

    i = i + 10: j = j - 2: k = k + 1

DOEVENTS + processes pending messages in $APPTYPE GUI.

  Used primarily in event procedures which generate messages or which require
  multiple time slices to complete.

END terminates program; same as Application.Terminate; not same as end of
  source code.

ENVIRON string; string is {variable}={value}; e.g, ENVIRON "TEMP=C:\temp"

FREECONSOLE "frees console window".  Typically used in GUI applications after
  SHOWCONSOLE, if no more console display or PRINT's are wanted.

GOTO label; jumps to code at label.

INITARRAY array; clears array data.

  DIM dat(99) As LONG
  'code
  INITARRAY dat

  INITARRAY is *not* needed at program startup for any array.

LPRINT string; sends string expression to lpt1

  LPRINT "hello world"+crlf  'prints one line
  mystring.loadfromfile("myfile.txt")
  LPRINT mystring  'prints entire file
  MyVar = RETFUNC  'optionally retrieve number of bytes sent to lpt1

  Note: LPRINT supported in PentHouse registered version.

OUT addr, integer; write byte value integer to I/O port address.

OUTW addr, integer; write word value integer to I/O port address.

POPUP integer + displays popup menu where integer is a POPUPMENU handle.

  POPUP MyPopUpMenu.handle  'POPUPMENU is an alias for MAINMENU

  POPUP may show a POPUPMENU under program control or in GUI event procedures,
  as response to user input or other event (hotpopup.bas).

RANDOMIZE integer; sets RND function seed value; e.g., RANDOMIZE TIMER

REDIM array(subscripts); redefine subscript usage and/or size of an array.

  Decreasing overall array size will not erase previous data or reduce its ram
  allocation.  Array item size or type cannot be changed.

  DIM dat(99) As LONG
  'code
  REDIM dat(9,19)

  For FORM objects, REDIM will not destroy, recreate or create additional
  objects if overall array size is changed.  If a FORM object array size is
  increased, REDIMEX (Statements > Advanced Techniques) is used after REDIM
  to initialize the new array items.

RUN string; string = command line (executable pathname and arguments);
  does not block application.

SHELL string; string = command line (executable pathname and arguments);
  blocks application while shelled program runs.

  If pipe symbols are used in string, then "command.com /c" or "cmd.exe /c"
  may have to be added as a prefix to the argument string.

SHELL1 string; same as SHELL but starts executable with "detached console".

  Application.ErrorLevel after SHELL/SHELL1 retrieves error level value. 
  SHELL and SHELL1 may also be used as Numeric Functions to retrieve error
  level.

SHOWCONSOLE   Please see description in CONSOLE section.

SHOWMESSAGE string; string = message.

SLEEP number

  number is seconds with millisecond resolution; suspends application.
  Use SLEEP to save CPU time if application is waiting for an input or event.

  SLEEP 0.05 '50 milliseconds for 20/second frame rate.

SWAP MyVar1, MyVar2; exchanges values for 2 or 4 byte variables.

  MyVars should be the same size: WORD, SHORT, SINGLE, DWORD, LONG, INTEGER

THIS +

  THIS facilitates access to UDT/Custom Objects by pointer.  With THIS
  syntax, code blocks may process data from different Objects.  Example:

  $apptype console

  TYPE MyUDT
    item1 as LONG
    item2 as LONG
  END MyUDT

  DECLARE SUB ProcessData (x as LONG, y as LONG)

  SUB ProcessData
  this.item1 = x
  this.item2 = y
  print this.item1 + this.item2
  END SUB

  DIM abc as MyUDT
  DIM xyz as MyUDT

  THIS = abc: ProcessData (10, 20)
  THIS = xyz: ProcessData (30, 40)

  pause
  end

  Notice that the SUB code block using this.SomeProperty syntax appears
  after the UDT to which THIS will refer.  Thus, at compile-time, the 
  proper offsets to .item1 and .item2 will be used.  At run-time, the
  SUB will use the pointer obtained from a THIS = <name of UDT instance>
  statement.

  THIS syntax is based on the BYREF() and BYREF$() keywords and has the
  same limitations, such as 8-byte numbers are not supported.

  HotBasic internal variable hbThis is associated with THIS syntax.  E.g.,
  THIS = abc results in two actions: (1) hbThis = OBJPTR(abc) and (2)
  code using this.SomeProperty will use MyUDT item offsets.

  THIS = NOTHING  'set THIS to undefined state

  If THIS is used for multiple UDT's, it is suggested that procedures
  using THIS to refer to a particular UDT be located after its TYPE ...
  END TYPE block and before the next TYPE ... END TYPE block.
  Alternatively, one can force a code block using this.SomeProperty to
  compile with proper offsets by preceding it with a THIS = 
  <name of any UDT instance> even where such statement is never executed
  at run-time.

  The Commander Keene download shows an example of THIS usage.

WAITTHREAD(ID) causes code to wait until thread ID completes, where the
  ID value is obtained from the CREATETHREAD Numeric Function.  For each
  thread ID launched, only one WAITTHREAD statement is needed, since upon
  completion, the thread will have terminated.

  Typically, a WAITTHREAD(ID) statement is placed immediately before a
  code section that requires the results of thread ID.  If WAITTHREAD
  statements are placed as far as possible from the thread's launch, there
  may be no wait at all, since, with good planning, the thread in question
  will have had time to complete.

  In short, with good design, the WAITTHREAD statement merely assures that
  a particular thread has completed before code using the thread's results.

  For a non-blocking query on thread status, please see the WAITTHREAD
  Numeric Function.

  WAITTHREAD is part of HotBasic's Multi-Threading, Multi-CPU support.

WITH string; string is object or type name.

  WITH FPU: .load x: .load y: .mul: END WITH

  WITH may be used with destination values located first in a statement or
  preceding an "=" character.


+ Penthouse (registered) version

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