'
'
'
'         ###############
'       ###################
'      ###               ###
'     ###    ###          ###
'    ###    ## ##         ###
'    ###   ##   ##        ###
'    ###  ##     ##       ###
'    ###  ##      ##      ###
'    ###  ##      ##      ###
'    ###   ####  ##      ###
'     ###    ####       ###
'      ###             ###
'       ###           ###
'         #############
'           #########


' ...  show as bold
' __     show white space


oxykeyw.txt
o2 database

'======================
'>>O2H LOW LEVEL MACROS
'======================




key:      "true 18"
action:   insert -1
use:      universal value for boolean true
example:  int a=true
remarks:
related:  false, not bits, not conditional
group:    system macro
updated:  27/03/2017
.


key:      "false 18"
action:   insert 0
use:      universal value for boolean false
example:  int a=false
remarks:
related:  true, not bits, not conditional
group:    system macro
updated:  27/03/2017
.


key:      "#view 18"
key:      "#endv 18"
action:   creates a window for compiler listings.
use:      Allows the programmer to see a selected part of the compiled code
example:  sys a,b,c
  ###
  a=b+c
  ###
  s="Value "+str(a)
remarks:  These markers restrict the listing to a window so that the code can be studied in detail.
  #view and #endv are generated internally from the pair of '###' symbols.
related:  #show
group:    directives
updated:
.


key:      "version 18"
action:   returns current version number and DateTimeStamp.
use:      identification of version
example:  print version
related:  o2version
group:    info
updated:  24/06/2019
.


key:      "o2version 18"
action:   returns current version number.
use:      version matching 
example:  $ rtlversion "0.2.1"
  '
  #if not match(rtlversion,o2version)
    #error "RTL version mismatches o2 version "+o2version
  #endif
related:  version
group:    info
updated:  24/06/2019
.


key:      "lobyte 18"
action:   return the lower 8 bits of an integer expression
example:  wl=lobyte(wParam)
related:  hibyte, loword, hiword
group:    system macro
updated:  14/02/2018
.


key:      "loword 18"
action:   return the lower 16 bits of an integer expression
example:  wl=loword(wParam)
related:  hiword, hibyte, lobyte
group:    system macro
updated:  14/02/2018
.


key:      "hibyte 18"
action:   return bits 8..15 of an integer expression
example:  wh=hibyte(wParam)
related:  lobyte, loword, hiword
group:    system macro
updated:  14/02/2018
.


key:      "hiword 18"
action:   return bits 16..31 of an integer expression
example:  wh=hiword(wParam)
related:  loword, lobyte, hibyte
group:    system macro
updated:  14/02/2018
.


key:      "redim 18"
same:     dyn 
action:   create or resize a dynamic array, preserving contents within range
use:      extend or reduce an array size at run-time
example:  redim string s(n)
remarks:  to flush an array's contents, redim it with 0 elements first. But avoid
  doing this with arrays of strings; the orphaned strings are not garbage-collected
  until the end of the program, and will accumulate on each iteration where the redim
  reduces the number of elements.
related:  dim, new, indexbase
group:    system macro
updated:  30/09/2022
.


key:      "new 18"
action:   create a dynamic object and call its constructor method.
use:      to create and initialise persistent objects
example:  new shape cuboid(1,1,1)
related:  Classes, del, redim, dim
group:    system macro
updated:  22/06/2018
.


key:      "del 18"
action:   Call a dynamic object's destructor method and disallocate its memory block.
use:      to delete dynamic objects
example:  del cuboid
remarks:  'del' may also be used to delete the content of individual strings and bstrings.
  Strings are set to null; the contents are released and removed from the garbage collector's lists.
related:  Classes, new
group:    system macro
updated:  10/03/2017
.


'===============================
'>>O2H SYSTEM TERMINATION MACROS
'===============================



key:      "terminate 19"
action:   Deallocate all Strings, static variables and free DLL libraries (at end of program).
  This is automatically appended unless it is detected in the program.
  It is composed of the three macros below: FreeLibs FreeStrings. If either
  of these are used then Terminate itself will not be automatically appended.
use:      explicit termination of program
example:  terminate
related:  freestrings, freelibs
group:    system macro
updated:  
.


key:      "freestrings 19"
action:   deallocate all remaining static strings only (at end of program)
use:      allow the program to terminate without freeing libraries
example:  freestrings
related:  terminate, freelibs
group:    system macro
updated:  
.


key:      "freelibs 19"
action:   free all loaded DLL libraries only (at end of program)
use:      allow the program to terminate but all static strings are retained
example:  freelibs
related:  terminate, freestrings
group:    system macro
updated:  
.




'=======================
'>>O2H HIGH LEVEL MACROS
'=======================

key:      "right 20"
action:   returns right part of a string by length
use:      string=right(sourcestring, length)
example:  s=right("abcdef",3)
result:   s="def"
related:  left, mid, ltrim, rtrim
group:    system macro
updated:  28/02/2017
.


key:      "reindex 20"
action:   create an index for a data array
use:      filter and index a set of data, with user-defined criteria
example:  
  uses console
  int d={8,9,6,7,4,5,2,3,0,1}
  int m=10
  '
  macro filter(r,i)
  if d[i]>=5
    r=1
  endif
  end macro
  '
  macro compare(r,i,j)
  if d[i]>d[j] 'ascending
  'if d[i]<d[j] 'descending
    r=1
  endif
  end macro
  '
  reindex idx,m,n,filter,compare
  '
  print "total " n cr cr
  int i,j
  for i=indexbase to n+indexbase-1
    j=idx[i]
    print i tab j tab d[j] cr
  next
  print cr cr
  del idx
  wait
remarks:  
related:  
group:    system macro
updated:  07/11/2022
.



'========================
'>>O2 LOW LEVEL FUNCTIONS
'========================



key:      "getmemory 4"
action:   allocate block of memory and return its base address
use:      address=getmemory bytes
example:  m=getmemory 8000
related:  freememory, news, frees
group:    low level oxygen functions
updated:  
.


key:      "freememory 4"
action:   free previously allocated memory block
use:      freememory address
example:  freememory m
related:  getmemory, news, frees
group:    low level oxygen functions
updated:  
.


key:      "loadlibrary 4"
action:   load a library (if not already loaded) and return its handle
use:      handle=loadlibrary "library filename"
example:  h=loadlibrary "kernel32.dll"
related:  freelibrary, library, getprocaddress
group:    low level oxygen functions
updated:  
.

key:      "freelibrary 4"
action:   free library
use:      freelibrary handle
example:  freelibrary h
related:  loadlibrary, library, getprocaddress
group:    low level oxygen functions
updated:  
.


key:      "getprocaddress 4"
action:   get procedure address
use:      getprocaddress libraryHandle "proc name"
example:  a=getprocaddress h, "AllocConsole"
related:  loadlibrary, freelibrary, library
group:    low level oxygen functions
updated:  
.


key:      "copy0 4"
action:   copy null terminated string to another location
use:      copy DestinationAddress, SourceAddress
example:  copy0 &a,&b
related:  copy00, copy
group:    low level oxygen functions
updated:  
.


key:      "copy00 4"
action:   copy null terminated string of wide (2 byte) characters to another location
use:      copy DestinationAddress, SourceAddress
example:  copy00 &v,&w
related:  copy0, copy, copyn
group:    low level oxygen functions
updated:  
.


key:      "copyn 4"
key:      "copy 4"
action:   string to another location by a specified number of bytes
use:      copy DestinationAddress, SourceAddress, NumberOfBytes
example:  copy &dest,&src,n
remarks:  copy and copyn are the same
related:  copy0, copy00
group:    low level oxygen functions
updated:  
.


key:      "mbox 4"
action:   display message null-terminated ascii string
use:      mbox String-expression
example:  mbox "Value " v
remarks:  
  unlike print, mbox does not check the expression-type so
  it is important to start with a string or char expression
related:  print, str
group:    low level oxygen functions
updated:  21/06/2022
.


key:      "comparestr 4"
action:   compare first string with second string
use:      comparestr bstr1, bstr2 : jg ifgreater : jl ifless : jz ifequal      
example:  comparestr bs1,bs2
related:  string, char, str
group:    low level oxygen functions
updated:  21/06/2022
.

'=============================
'>>COMMON RESERVED WORDS
'=============================
'key:  "exit   9 1"
'key:  "repeat 9 1"
'key:  "call   9 1"
'key:  "jmp    9 1"
'key:  "and    9 0"
'key:  "or     9 0"
'key:  "xor    9 0"
'key:  "not    9 1"
'
'key:  "db     9 1"
'key:  "dw     9 1"
'key:  "dd     9 1"
'key:  "dq     9 1"
'key:  "mov    9 0"
'key:  "lea    9 0"
'key:  "add    9 0"
'key:  "sub    9 1"
'key:  "mul    9 0"
'key:  "div    9 0"
'key:  "jz     9 0"
'key:  "jnz    9 0"
'key:  "shl    9 0"
'key:  "shr    9 0"
'key:  "sal    9 0"
'key:  "sar    9 0"
''
''groupref: common_asm
''group:    common x86 assembly instructions
'updated:  


''neg,test,ja,jb,jg,jl,jae,jbe,jge,jle




'===========================
'>>O2 ATTRIBUTE MACROS
'===========================



key:      "sizeof 11"
action:   return length of variable element (in bytes)
use:      nbytes=sizeof variable
example:  n=sizeof a
related:  offsetof, spanof, typeof typecodeof
group:    variable and type attributes
updated:  
.


key:      "offsetof 11"
action:   return offset of variable from index register
use:      nbytes=offsetof variable
example:  n=offsetof a
related:  sizeof, spanof, typeof, typecodeof, recordof
group:    variable and type attributes
updated:  
.


key:      "spanof 11"
action:   return span of array variable dimension
use:      nbytes=spanof variable dimension
example:  dim as long v(10) : n=spanof v
result:   n=10
related:  sizeof, offsetof, typeof, typecodeof, recordof
group:    variable and type attributes
updated:  
.


key:      "typeof 11"
action:   return name of the variable type
use:      name=typeof variable
example:  dim as long v : s=typeof v
result:   s="long"
related:  typecodeof sizeof, offsetof, spanof, recordof
group:    variable and type attributes
updated:  
.


key:      "structureof 11"
action:   return data structure of compund (UDT) or variabe
use:      obtain data for diagnostics or reflective programming
example:  type vt long v,double d
  dim as vt v :  r=recordof v
result:   r="
  v 0 4 1 A0 , long
  d 4 4 1 A0 , double
  "
related:  prototypeof sizeof, offsetof, spanof, typeof, typecodeof, recordof, #recordof
group:    variable and type attributes
updated:  
.


key:      "encodingof  11"
action:   return the operand encoding of a variable or macro
use:      obtain data for diagnostics or reflective programming
example:  sys v
  print encodingof v 'example: [ebx+4100]
related:  prototypeof, sizeof, offsetof, spanof, typeof, typecodeof, recordof, #recordof
group:    variable and type attributes
updated:  
.


key:      "prototypeof  11"
action:   return prototype(s) of functions, subs and high level macros
use:      obtain data for diagnostics or reflective programming
related:  recordof, sizeof, offsetof, spanof, typeof, typecoedof, #recordof
group:    variable and type attributes
updated:  
.


key:      "typecodeof  11"
action:   return type code number of variables and literals.
use:      obtain data for diagnostics or reflective programming
example:  
  #if typecodeof(A) > 0
    #print "A type: " + typeof(A) ' int
  #endif
related:  typeof recordof, sizeof, offsetof, spanof, prototypeof, #recordof
group:    variable and type attributes
updated:  17/06/2022  
.


key:      "recordof    11"
action:   return record of compound (UDT) variable
use:      obtain data for diagnostics or reflective programming
example:  type vt long v,double d
  dim as vt v :  r=recordof v
result:   r="
  v 0 4 1 A0 , long
  d 4 4 1 A0 , double
  "
related:  #recordof prototypeof, sizeof, offsetof, spanof, typeof, typecodeof, #recordof
group:    variable and type attributes
remarks:  use #recordof to display the record during compilation.
group:    variable and type attributes
updated:  
.


key:      "strptr 11"
action:   return a string pointer
use:      obtain base address of string contents
example:  string s="Hello"
  sys a=strptr s
related:  typecodeof, addr
group:    variable and type attributes
updated:  27/03/2017
.


key:      "lpartof 11"
action:   return left part of dotted name
use:      exract main part from dotted name
  for use in macros.
example:  lpartof(a.b.c).x 'returns a.x
related:  rpartof, vtypeof
group:    variable and type attributes
updated:  11/01/2021
.


key:      "rpartof 11"
action:   return mid part of dotted name
use:      exract part from dotted name, for use
  in macros.
example:  rpartof(a.b.c) 'returns b.c
related:  lpartof, vtypeof
group:    variable and type attributes
updated:  11/01/2021
.


key:      "vtypeof 11"
action:   return typename of variable
use:      refer to variable type , for use
  in macros.
example:   double a
  vtypeof(a) 'returns double
related:  lpartof, rpartof, sizeof
group:    variable and type attributes
updated:  11/01/2021
.


'===========================
'>>O2 KEYWORDS
'===========================




key:      "incl 13"
action:   expand macro non recursively without parameter substitutions
use:      incl aMacro   
example:  def helo "hello " %1
  incl helo
result:   substitution: "hello " %1
related:  def
group:    Oxygen keywords
updated:  
.

key:      "#semicolon 13"
action:   switch use of semicolon as comment marker or separator
use:      so semicolons can be recognised as separators when using C syntax
example:  #semicolon separator
  s="ok"  ; print s
  #semicolon comment
  print "ok" ; this is a comment
remarks:  #semicolon can be confined to a scope (function etc)
related:  #case, indexbase
group:    Oxygen keywords
updated:  
.

key:      "retn 13"
action:   macro ret n. Releases correct number of bytes at end of procedure (in stdcall convention)
use:      internal
example:  
related:  ret, return, function
group:    Oxygen keywords
updated:  10/01/2018
.


key:      "rem 13"
action:   comment till end of line
use:      
example:  rem this is a comment
related:  skip  '   /*   */   //  ;
group:    Oxygen keywords
updated:  24/02/2017
.


key:      "with 13"
action:   specify a variable name prefix for assignments
use:      Allows long names to be shortened when assigning values
example:  dim as vector4 vectorI
  with vectorI : .x=1 : .y=0 : .z=13 : .w=0 : end with
group:    Oxygen keywords
updated:  25/04/2018
.


key:      "o2 13"
action:   start a block of o2 machine code notation
use:      inserting inline machine code and other binary data.
  direct use of o2 language (used by the o2 linker)
example:  o2 b8 00 01 00 00 'machine code for mov eax,256
related:  Blocks
group:    Oxygen keywords
updated:  02/03/2017
.

key:      "bind 13"
action:   bind a list of procedures from a Dynamic Link Library (DLL)
use:      for low level (without protoype) calls to DLL functions.
  the first name is the one used in the program. The second is the name used in the DLL.
example:
  sys Kernel32
  kernel32=LoadLibrary "kernel32.dll"

  bind kernel32
  (
  GetExitCodeProcess GetExitCodeProcess   ; @8
  ExitProcess        ExitProcess          ; @4
  GetCommandLine     GetCommandLineA      ; @0
  GetModuleHandle    GetModuleHandleA     ; @4
  QueryPerformanceCounter QueryPerformanceCounter ; @4
  )
result:   the first column of keywords is recognised as procedure calls. A prototype may be attached
  to any of these keywords later. Otherwise the programmer must ensure that the parameters
  passed are a perfect match for each procedure call.
remarks:  Comments are supported - both semicolon and single quote marks.
related:  loadlibrary, freelibrary, getprocaddress, declare, library
group:    Oxygen keywords
updated:  
.  


key:      "enum 13"
action:   create an enumeration
use:      assign a numeric identity to a name
example:  
incfile1: demos\basics\Enumerations.o2bas

remarks:  C syntax is supported for this construct. Also enum bit
  assigns values 1,2,4,8,16.. instead of 0,1,2,3,4..
related:  typedef, enum, #define, %
group:    Oxygen keywords
updated:  16/06/2018  
.


key:      "def 13"
key:      "#def 13"
action:   define a low level macro
use:      
example: 
  'DEFINE MACRO:

  def Create
    dim as %1 %2
    %2.new("%2")
  end def

  'INVOKE MACRO

  create SomeClass SomeObject
  
  'EXPANDS TO:

  dim as SomeClass SomeObject
  SomeObject.new("SomeObject")

remarks:  def and #def are the same
related:  macro, #define, deff
group:    Oxygen keywords
updated:  
.


key:      "type 13"
action:   define a compound variable type
use:      
example:
  type rgbacolor
    red   as byte
    green as byte
    blue  as byte
    alpha as byte
  end type

  rgbacolor c
  c.red=100 : c.green=50 : c.blue=100

related:  typedef, struct, class
group:    Oxygen keywords
updated:  
. 


key:      "struct 13"
action:   define a compound variable type (C Syntax)
use:      
example:  
  struct rgbacolor
  {
    red   as byte
    green as byte
    blue  as byte
    alpha as byte
  }
related:  type, typedef, class
group:    Oxygen keywords
updated:  
.


key:      "class 13"
action:   define a class (strucure and methods for objects)
use:      
example:
  'DEFINE CLASS
  '  
  class rgbacolor
    red   as byte
    green as byte
    blue  as byte
    alpha as byte
    '
    method in(sys r, sys g, sys b, sys a)
      red=r : green=g : blue=b : alpha=a
    end method
    '
  end class

  'INSTANTIATE

  dim as rgbaColor c

  'INVOKE METHOD
  '
  c.in(100,200,100,128)

related:  Classes, type, typedef, struct
group:    Oxygen keywords
updated:  
.


key:      "var 13"
action:   define a set of variables
use:      low-level dimensioning of variables
example:  var string s,t,u(64),v  
remarks:  var is normally only used internally. it accepts * for indirect variables
  and "at" for variable mapping. Arrays are also supported.
related:  dim
group:    Oxygen keywords
updated:  
.


key:      "include 13"
key:      "#include 13"
action:   include source code from another file
use:      used for including header files and other files of source code
example:  #include "rtl32.inc"
remarks:  include and #include are the same
related:  uses, includepath, embedfile
group:    Oxygen keywords
updated:  24/06/2019  
.


key:      "use 18"
key:      "uses 18"
key:      "using 18"
action:   include source code from another file
use:      for including header files and other files of source code
example:  uses RTL32 'include once "RTL32.inc"
remarks:  use, uses, using are equivalent
related:  include, includepath, embedfile
group:    Oxygen keywords
updated:  24/06/2019  
.


key:      "packed 13"
action:   prevent padding between members of a type or typedef
use:      allow programmer to have full control over padding to align the members
example:  
  packed type point
    word x,y,z
    dword color
  end type
  
  packed type point
    word x,y,z
    align 4
    dword color
  end type
remarks:  By default, the members will be aligned to a boundary matching their size.
related:  type, typedef, struct
group:    Oxygen keywords
updated:  20/06/2022
.


key:      "_def 13"
action:   define a low level system macro
remarks:  the terminate, freelibs and freestatics macros are specified in RTL32.inc and RTL64.inc
group:    Oxygen keywords
updated:  27/03/2017
.


key:      "includepath 13"
action:   define a filepath for source files specified by include.
use:      
example:  
related:  include, librarypath
group:    Oxygen keywords
updated:  
.


key:      "librarypath 13"
action:   define a filepath for DLL files
use:      tells the computer where to find Dynamic Link Libraries
  required to run the program. (System DLLs  do not require this.)
example:  
related:  library, extern, includepath
group:    Oxygen keywords
updated:  
.


key:      "#file 13"
action:   specifiy a filename for compiled code ( .EXE or .DLL )
use:      creates an executable .EXE or  Dynamic Link Library .DLL file
example:  #file FileName independent 64 bit
remarks:  only used in runtimes: rtl32.inc and rl64.inc
related:  
group:    Oxygen keywords
updated:  18/10/2022
.


key:      "embedfile 13"
action:   specifiy a file to be embedded in the data section
use:      store data file in a program, and get a pointer to it.
example:  sys dat : embedfile "data.txt",dat
related:  include, strptr, getfile
remarks:  
  Text or binary files may be embedded with this command. The data is read-only. 
  Either a sys or a bstring variable may be used to reference the data.
  An upper limit of 255 files can be embedded.
group:    Oxygen keywords
updated:  
.


key:      "quote 13"
action:   specify tagname for superquotes
use:      supports almost unlimited nesting of quotes. Can be used for containing
  embedded scripts which themselves use quotes and have different syntax.
example:  quote !!! this quote contains other quotes "containing "other quotes"   " !!!
related:  "    `
group:    Oxygen keywords
updated:  
.

key:      "typedef 13"
action:   define a set of types (C syntax)
use:      create type definitions for creating other types
example:
  typedef Double *pDouble

  'CREATE TYPES FROM ANONYMOUS STRUCT

  typedef struct
   {
     single x;
     single y;
     single z;
   } vector, *pVector;

   'CREATE VARIABLE

   vector v;

   v.x=42.01

   'FROM WINBASE.H:
   '
   typedef struct _OVERLAPPED {
       ULONG_PTR Internal;
       ULONG_PTR InternalHigh;
       union {
           struct {
       DWORD Offset;
       DWORD OffsetHigh;
           };

           PVOID Pointer;
       };

       HANDLE  hEvent;
   } OVERLAPPED, *LPOVERLAPPED;

related:  type, struct, class, union, enum
group:    Oxygen keywords
updated:  27/02/2017
.




key:      "union 13"
action:   define a union (C syntax)
use:      allows different variables to occupy the same space.
example:  
  union utype
  {
    byte  b
    short w
    long  i
  }


  utype v

  v.b=42
result:   v.b=42 : v.w=42 : v.i=42
remarks:  a union may also be nested inside a type.
related:  typedef, type, struct, class, enum
group:    Oxygen keywords
updated:  
.


key:      "#case 13"
action:   specify mode of case sensitivity.
use:      case can be sensitive, insensitive, or capital
example:   
  #case insensitive 'AbC is the same as 'aBC' and 'ABC'
  #case sensitive   'AbC and 'abc' are not the same
  #case capital     'AbC is the same as 'aBC' but not 'ABC'
remarks:  The default is 'insensitive'.
  #case has block scope and reverts to its previous state when
  the block ends.
related:  #semicolon, indexbase
group:    directives
updated:  27/03/2017
.



key:      "#lookahead 13"
action:   internally creates header declarations for all procedures.
use:      allows procedure calls to forward reference
example:  
  #lookahead
  ff "ok"
  '...
  sub ff(s as string)
    print s
  end sub

remarks:  
  procedures in inner blocks are ignored, so each block must
  have its own '#lookahead'
related:  scope
group:    directives
updated:  23/06/2022
.


key:      "#autodim 13"
action:   enable variables to be created without a Dim statement
use:      for mall, informal programs.
example:  #autodim on
related:  
group:    directives
updated:  24/04/2019
.


key:      "#alert 13"
action:   generates a compiler message (like an error)
use:      used to alert programmer about an area of code
  that requires attention
example:  #alert (please implement methods for this interface)
related:  #error, #print
group:    directives
updated:  16/06/2018
.


key:      "#error 13"
action:   generates a compiler error message
use:      used to alert programmer about inconsistencies
  that require attention.
example:  #error (please implement methods for this interface)
related:  #alert, #print
group:    directives
updated:  16/06/2018
.


key:      "#pragma 13"
action:   ignored (C style compiler directives)
use:      compilers use it for platform or compiler-specific mode changes
example:  #pragma warning(push)
related:  
group:    directives
updated:  
.


key:      "#unique 13"
action:   flags an error if a a symbol definition is not unique (in the same nesting level)
use:      prevent symbols from being redefined
example:  #unique enabled
  #unique disabled 'default
group:    directives
updated:  
.


key:      "#console 13"
action:   programs compiled to EXE/DLL will run in an existing console (MS Subsystem 3)
use:      prevents new console from being created. Inputs and outputs are with the existing console.
example:  #console
remarks:  When Oxygen is embedded it will use the Host's subsystem'
group:    directives
updated:  
.


key:      "#show 13"
action:   displays the translated code of a statement during compilation
use:      Allows the programmer to see a selected part of the compiled code
example:  sys a,b,c
  #show a=b+c 'display coding in a messagebox
   #show "s.txt" a=b+c 'save coding in file 's.txt'
related:  #view
group:    directives
updated:  27/03/2017
.


key:      "@ 51"
action:   return the address of a variable
use:      reading writing data of variables and arrays of variables, by reference
example:  int a=42
  print @a 'address of a
  int *b 'indirect (pointer) variable
  @b=@a   'coupled by address
  print b '42
remarks:  Unlike C, pointer resolution is handled implictly. So the @ operator is required
  for manipulating pointers. It is similar to the & operator in C. 
related:  *, ?, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "* 51"
action:   return the integer value located by the address contained in the variable
use:      reading writing data, using pointers
example:  int a=42
  print @a 'address of a
  sys b    'sys' ensures an integer large enough to hold a pointer
  b=@a     'assin address of a to b
  print *b '42
remarks:  Unlike C, pointer resolution is normally handled implictly. 
related:  @, ?, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "? 51"
action:   return the integer value contained in the variable
use:      casting variables as integers
example:  float f=100
  print hex(?f) 'display the hexadecimal form of float f
remarks:  
related:  cast, *, @, strptr, addr
group:    operators
updated:  28/03/2017
.


key:      "addr 13"
action:   resolve address of a variable (assembler)
use:      load address of a variable to a register
example:  sys a
  addr ecx,a
related:  @, *, ?, strptr
group:    directives
updated:  27/03/2017
.


key:      "cast 51"
action:   change or specify the type of a variable temporarily, in an expression
use:      
example:  float f=100
  print hex( cast(int) f) 'display the hexadecimal form of float f
  print hex( (int) f )    'the same without using the 'cast' word
remarks:  
related:  convert, ?, union
group:    operators
updated:  28/03/2017
.


key:      "convert 51"
action:   explicitly convert the type of an expression.
use:      pass values, in the required type, to an unprototyped function
example:  float f=2.5
  sleep ( convert int ( f*1000 ) )
remarks:  
related:  cast
group:    operators
updated:  28/03/2017
.


key:      "#compact 13"
action:   remove unused code
use:      minimise size of compiled binaries
example   #compact on
remarks:  removes unused methods from classes, as well as unused general functions.
related:  #file
group:    directives
updated:  28/03/2017
.


'===========================
'>>O2H KEYWORDS
'===========================

key:      "let 14"
action:   defines a variable or object
use:      create a new variable or indirect object
example:  let s="this is a string"
  print typeof s 'result: 'string'
related:  dim, var
remarks:  Similar to using 'dim' but the type is inferred from the assigned value.
group:    Oxygen Basic structures
updated:  
.



key:      "const 14"
action:   create read-only variables
use:      constants
example:
  const int a=40, b=60
  const float f[]={ 1, 1.5, 2, 2.5, 3.0 }  
  const as string s="HelloWorld"
remarks:   
related:  dim, #unique
group:    Oxygen Basic keywords
updated:  23/06/2022
.


key:      "dim 14"
action:   define a set of variables
use:      create variables and arrays of variables with optional initial values
example:  
  dim as string s="Hello World"
  dim int i[100]
  dim float yx[480,640]
related:  local, static, redim, let, var, const
group:    Oxygen Basic keywords
updated:  30/09/2022
.


key:      "local 14"
action:   define a local set of variables
example:
  local string s
  dim local string t
related:  dim, static
group:    Oxygen Basic keywords
updated:  30/09/2022
.


key:      "static 14"
action:   define a static set of variables, (persistant but invisible outsid the block)
example:  
  static string s
related:  dim, local
group:    Oxygen Basic keywords
updated:  30/09/2022
.


key:      "! 14"
action:   declare a procedure with its prototype (may be external or declared in advance)
example:  
  ! fun(float a,b,c,d) as float
  ! function fun(float a,b,c,d) as float
remarks:  There is a wide range of options for Declare statements. Please look at the examples and header files.
related:  declare, library, lib, alias, dim
group:    Oxygen Basic keywords
updated:  24/02/2017
.


key:      "declare 14"
action:   declare a procedure with its prototype (may be external or declared in advance)
example:  
  declare fun(float a,b,c,d) as float
  declare function fun(float a,b,c,d) as float
related:  !, library, lib, alias, dim
remarks:  There is a wide range of options for Declare statements. Please look at the examples and header files.
group:    Oxygen Basic keywords
updated:  23/06/2022
.


key:      "function 14"
action:   define a function
example:  
  function triple(i as int) as int
    return i*3
  end function
related:  Procedures, sub, method
group:    Oxygen Basic keywords: procedures
updated:  23/06/2022
.


key:      "sub 14"
action:   define a sub. (like a function but not returning a value)
example:  
  sub triple(i as int, j as int)
    j=i*3
  end sub
related:  Procedures, function, method
group:    Oxygen Basic keywords: procedures
updated:  23/06/2022
.


key:      "method 14"
action:   
use:      define a procedure for objects.
example:  
  method triple(int i) as int
    return i*3
  end method
remarks:  Any function or sub defined inside a class/methods block are treated as methods of the class.
  But the term 'method' can only be used inside a class block.
related:  Procedures, function, sub, methods
group:    Oxygen Basic keywords: procedures
updated:  23/06/2022
.


key:      "operator 14"
action:   define a customised operator
use:      for operations between objects and other user defined types
example:  
  operator maxv 1 'name precedence level
  '
  type hInt int v
  '
  macro hInt_"move"(a,b)
    a.v=b.v
  end macro
  macro hInt_"maxv"(acc,a,b)
    if b.v>a.v
      acc.v=b.v
    else
      acc.v=a.v
    endif
  end macro
  '
  hInt a,b,c,d
  ...
  d=a maxv b maxv c
related:  type, class, macro
group:     keywords: operators
updated:  01/09/2022
.


key:      "if 14"
action:   start a conditional block with a test
use:      conditional execution
example:  
  'single liner
  if a<b then a=b
  '
  'block ('then' is optional)
  if a<b
    a=b
  endif
related:  Conditionals, then, else, elseif, endif, while
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "then 14"
action:   starts the conditional block where the prior test is met.
use:      conditional execution
example:  
  'single line
  if a>b then print a
  '
  'multi-line
  if a>b then
    print a
  endif       
remarks:  'then' is optional in mult-line blocks
related:  Conditionals, if, elseif, endif
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "else 14"
action:   starts the alternative block where none of the prior conditions are met
use:      conditional execution
example:  
  'single line
  if a>b then print a else print b 
  '
  'multi-line
  if a>b
    print a
  else
    print b
  endif
related:  Conditionals, if, elseif, endif
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "elseif 14"
action:   make an alternative test if the previous condition was not met.
use:      conditional execution
example:
  if a<=0
    'do nothing  
  elseif a>b
    print a
  else
    print b
  endif
related:  Conditionals, if, else, endif select, case
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "endif 14"
same:     end if
action:   end the conditional block
use:      conditional execution
example:  
  if a>b then
    a=b
  endif
related:  Conditionals, if, then, elseif, else, end if
group:    Oxygen Basic: control structures
updated:  23/06/2022
.



key:      "endselect 14"
same:     end select
action:   end the select block
use:      
example:  
related:  Selection, select, switch, case
group:    Oxygen Basic: control structures
updated:  12/09/2022
.


key:      "do 14"
action:   start a block for repetition (looping)
use:      
example:  
  a=0
  do
    '...
    a+=1 : if a=4 then exit do
  loop
result:   a=4 '4 loops
related:  Loops, while, continue, exit, enddo, loop
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "while 14"
action:   start a block for conditional repetition
use:      
example:  
  a=0
  while a<4
    a+=1
  wend
result:   a=4 '4 loops
remarks:  while is a combination of do and if.
related:  Loops, do, continue, exit, wend, enddo
group:    Oxygen Basic: control structures
updated:  23/06/2022
.


key:      "loop 14"
same:     end do, enddo
action:   end a do repeating block 
related:  Loops, do, continue, exit
group:    Oxygen Basic: control structures
updated:  12/01/2021
.

key:      "repeat 14"
same:     redo, continue
action:   goto the beginning of a do/while block 
related:  Loops, do, continue, exit
example:
  '
  do
    if a>b
      repeat do
      'same as continue do
    else
      exit do
  loop
  '
  'conditional repeating
  do
    ...
    repeat while a>b
    repeat when a>b
    repeat until a>b
    repeat if a>b
    exit loop
  loop
  '
  'structured assembler repeat
  (
   ...
   dec ecx
   jle exit
   repeat
  )
related:  exit, do, while, if, for
group:    Oxygen Basic: control structures
updated:  21/06/2022
.


key:      "enddo 14"
same:     end do, loop
action:   end a do  repeating block 
related:  Loops, while, do, loop, continue, exit
group:    Oxygen Basic: control structures
updated:  12/01/2021
.


key:      "endwhile 14"
key:      "wend 14"
same:     end while, loop
action:   end a while block
related:  Loops, do, while, continue, exit
group:    Oxygen Basic: control structures
updated:  12/01/2021
.


key:      "exit 14"
action:   exit a do  while for  (...) block immediately
use:      leave a loop, usually after a condition has been met
example:  
  a=0 : b=1
  do
    a+=1
    if a>4 then exit do
    b+=b
  end do
  '
  'conditional exit
  do
    ...
    exit when a>b
    exit if a>b
  loop
  '
  'structured assembler exit
  (
   ...
   dec ecx
   jle exit
   repeat
  )
related:  Loops, do, while, continue, repeat
group:    Oxygen Basic: control structures
updated:  21/06/2022
.


'itr: exit 2 exit 3 repeat 2


key:      "continue 14"
action:   go back to the beginning of a do, while or for block
use:      to "short circuit" a loop
remarks:  continue do and continue while will loop back to the
  nearest do or while at the same nesting level.

  continue for will jump to the iterator stepper before looping back.
related:  Loops, do, while, for, break, exit, wend, enddo, repeat
group:    Oxygen Basic: control structures
updated:  03/01/2018
.


key:      "break  14"
action:   exit a switch block or do/while block
related:  case, switch, while, do, continue
updated:  02/01/2018 
.


key:      "switch 14"
key:      "select 14"
action:   Start a Case block (C style)
use:      
example:  
related:  Selection, case, endselect, end
group:    Oxygen Basic: control structures
updated:  12/09/2022
.


key:      "case 14"
action:   specify a case to match followed by actions to perform
use:      
example:  
related:  Selection, select, endselect, end
group:    Oxygen Basic: control structures
updated:  12/09/2022
.


key:      "for 14"
action:   start an iteration block
use:      
example:  
related:  Iteration, to, step, next
group:    Oxygen Basic: control structures
updated:  24/02/2017
.


key:      "to 14"
action:   specify limit of an iteration
use:      
example:  
related:  Iteration, for, step, next
group:    Oxygen Basic: control structures
updated:  24/02/2017
.


key:      "step 14"
action:   specify increment of an iteration
use:      for iterator = start to end step step increment
example:  for i=1 to 10 step 2 : ... : next
result:   i increeases by 2 with each cycle : 1 3 5 7 9
comments: step can be omitted, a step of 1 is then assumed.
  a negative step can also be used for down counting.
related:  Iteration, for, to, next
group:    Oxygen Basic: control structures
updated:  24/02/2017
.


key:      "next 14"
action:   end iteration block
use:      
example:  
related:  Iteration, for, to, step
group:    Oxygen Basic: control structures
updated:  24/02/2017
.


key:      "goto 14"
action:   jump to a specified label in the code
use:      
example:  
  function cube(f as float) as float {return f*f*f}

  function cube(f as float) as float
  {
    return f*f*f
  }
related:  jmp, gosub
group:    Oxygen Basic: control structures
updated:  27/02/2017
.


key:      "gosub 14"
action:   call a labelled subroutine
use:      invoke local subroutines inside a procedure
example:  
incfile1: demos\basics\Gosub.o2bas
remarks:  Always exit subroutines with 'ret'
related:  Procedures, call, goto
group:    Oxygen Basic: procedures
updated:  18/08/2022
.


key:      "methods 14"
action:   start a methods block for a class of objects.
use:      
example:  
related:  method, class
group:    procedures block
group:    Oxygen Basic: structures
updated:  
.


key:      "return 14"
action:   exit from a procedure returning a value (in a function or method)
use:      
example:  float product(float a,b) { return a*b }
related:  Procedures, ret
group:    Oxygen Basic: procedures
updated:  24/02/2017
.


key:      "% 14"
key:      "$ 14"
action:   define an equate
use:      as a single-line macro
example:
  '$' can be used instead of '%'
  '=' is optional
  % green = 0x00ff00
  % green 0x00ff00
  % BigPhi 1.618033
  % compiler "OxygenBasic"
  print compiler
  '
  'SPECIALISED EQUATES
  '
  '%=' precalculate 
  %  mol 42
  %= hmol mol*0.5 'stored as 21
  '
  '%*' iterative
  %* ResetNum %1=0  :
  %* ResetStr %1="" :
  int a,b,c,d
  string s,t,u,v
  ResetNum a,b,c,d  'a=0 : b=0 : ...
  ResetStr s,t,u,v  's="" : t="" : ...
  '
  'USE FOR PREFIXES
  '
  % ad Antediluvian
  ad.X 'AntediluvianX'

remarks:  Equates can be used instead of constants  
related:  Equates, Macros, #define. #def. def,deff
group:    Oxygen Basic: macros
updated:  30/08/2022
.


key:      "inner 14"
action:   define a scope
use:      encapsulate concealed code for a module
example:  
  module
    sys p1,p2,p3,p4
    inner
      ============
      uses console
      ============
      p1=@input
      p2=@output
      p3=@cls
      p4=@getkey
    end inner
    '
    interface
    ! input() as string at p1
    ! output(string s)  at p2
    ! cls  ()           at p3
    ! pause() as int    at p4 
  end module
related:  Blocks, scope, module, inferface, namespace
group:    Oxygen Basic: code structures
updated:  29/08/2022
.


key:      "scope 14"
action:   start a scope
use:      create a block where variables and functions may be locally defined
example:  :
incfile1: demos\basics\scope.o2bas
remarks:  when the scope ends any definitions created within the scope will be forgotten.
related:  Blocks, namespace
group:    Oxygen Basic: code structures
updated:  06/06/2018
.


key:      "module 14"
action:   define a module block
use:      create a block of deployable code
example:  
  ==============
  module console
  ==============
    namespace cn
    uses console 'inc\console.inc'
    end namespace
    '
    interface
    ---------
    'relative namespaces with prefixed ..
    $ cprint  ..cn..output 
    $ cwait   ..cn..getkey
    $ tab     ..cn..tab
    $ cr      ..cn..cr
  end module
  '
  cprint 12345 tab "okay" cr
  cwait

related:  interface, inner, namespace
group:    Oxygen Basic: code structures
updated:  29/08/2022
.


key:      "interface 14"
action:   mark the start of shared code
use:      define shareable code in a module
example:  
related:  module, inner, namespace
group:    Oxygen Basic: code structures
updated:  29/08/2022
.


key:  "namespace 13"
action:   start a namspace
use:      create a region where symbols are locally defined
example:  '
  'NESTABLE NAMESPACES
  dim int x=1
  namespace a
    namespace b
      namespace c
        dim int x=56
      end namespace
    end namespace
  end namespace
  '
  namespace a..b..c
    print x '56
  end namespace
  '
  print a..b..c..x '56
  print x '1
remarks:   
related:  module, inner
group:    Oxygen Basic: code structures
updated:  28/08/2022
.


key:      "indexbase 14"
action:   define the index base for an array
use:      most software assumes an indexbase of 0 or 1
example:  indexbase 0
remarks:  the default indexbase is 1 but C code normally assumes 0.
  If the indexbase is defined inside a scope, such as a function then it
  only applies within the scope and reverts to its previous value outside the scope.
related:  dim, #case, #semicolon
group:    Oxygen Basic: directives
updated:  22/03/2017 
.


key:      "#majorminor 14"
action:   sets storage order for arrays
use:      row-major array compatibility
example:  
  #majorminor
  dim int yx[768,1024] 'y rows, x columns
remarks:  This is the default mode for multidimensional arrays
related:  #minormajor, indexbase, dim
group:    Oxygen Basic: directives
updated:  30/09/2022
.


key:      "#minormajor 14"
action:   sets storage order for arrays
use:      column-major array compatibility
example:  
  #minormajor
  dim int xy[640,480] 'minor first
remarks:  
related:  #majorminor, indexbase, dim
group:    Oxygen Basic: directives
updated:  30/09/2022
.


key:      "lib 14"
key:      "library 14"
action:   specify the name of a DLL library to associate
          with a set of procedure declarations
use:      
example:  lib "kernel32.dll"
related:  declare
group:    Oxygen Basic: directives
updated:  
.


key:      "extern 14"
action:   associate declared procedures with a calling convention and/or dll name
use:      
example:  
  extern stdcall lib "kernel32.dll"
    declare function QueryPerformanceCounter(lpPerformanceCount as quad) as sys
    declare function QueryPerformanceFrequency(lpPerformanceFrequency as quad) as sys
  end extern
remarks:  
  note ther is no need to use an Alias in these declarations if you give the exact name
  of the procedures in their original case.
related:  lib, library, calling conventions
group:    Oxygen Basic: linkage
updated:  17/06/2022
.


key:      "that 14"
action:   suppress automatic "this" prefix inside OOP methods
use:      resolving name conflict between an object member and another variable
example:  this.voice=that voice
  voice=that voice
related:  method, this
group:    Objects
updated:  
.


key:      "this 14"
action:   explicitly refer to an object's own members
use:      distinguish a member from a local variable, param or function of the same name
example:  this.len=len(s)
incfile1: OOP\features\ThisThat.o2bas
related:  method, class, that
group:    Objects
updated:  
.


key:      "#noprec 14"
action:   directive to evaluate an expression from left to right, ignoring standard operator precedence rules.
use:      
example:  
related:  #noinit, indexbase, #byref, #byval, #assign
group:    Oxygen Basic: directives
updated:  04/05/2019
.


key:      "#noinit 14"
action:   prevent variables from being automatically initialised to nul within a procedure
use:      
example:  
related:  #noprec, #byref, #byval, #assign, indexbase
group:    Oxygen Basic: directives
updated:  04/05/2019
.


key:      "#byval 14"
action:   pass parameter by value (not by its address)
use:      
example:  
related:  #byref, #noinit, #noprec, #assign, indexbase
group:    Oxygen Basic: directives
updated:  04/05/2019
.


key:      "#byref 14"
action:   pass parameter using its address instead of its value
use:      
example:  
related:  #byval, #noinit, #noprec, #assign, indexbase
group:    Oxygen Basic: directives
updated:  04/05/2019
.


key:      "#assign 14"
action:   '=' always to be an assignment operator in conditional statements
use:      emulate the C convention for the '=' operator
example:  #assign on
  if hresult=QueryInterface(gu,ob) then ...
related:  #byref, #byval, #noinit, #noprec, indexbase
group:    Oxygen Basic: directives
remarks:  when #assign is active then '==' must always be used to test equality
updated:  04/05/2019
.


key:      "deff 14"
action:   create an assembly code macro for the FPU  (metatype -17)
use:      to create floating point maths functions
example:  deff sine fsin
remarks:  Deff macros make use of the FPU. All float functions are defined this way.
  These are non-recursive macros and take no macro arguments. The expression parser is FPU- 
  aware and takes care of passing parameters onto the FPU stack.
related:  Macros, def, #define, macro, sin, cos 
group:    macros
updated:  24/02/2017
.


'============
'METACOMMANDS
'============


key:      "#if 13"
action:   include block of code if conditions are met
use:      
example:  
related:  #else, #elseif, #endif
group:    meta control
updated:  08/02/2018
.


key:      "#else 13"
action:   alternative block of code to include if prior conditions are not met.
use:      
example:  
related:  #if, #elseif, #endif
group:    meta control
updated:  08/02/2018
.


key:      "#endif 13"
action:   end of conditional code inclusion block
use:      
example:  
related:  #if, #elseif
group:    meta control
updated:  08/02/2018
.


key:      "#elseif 13"
action:   include block of code if these alternative conditions are met
use:      
example:  
related:  #if, #else, #endif, #fi
group:    meta control
updated:  08/02/2018
.


key:      "#define 13"
action:   define a macro (C syntax)
use:      C preprocessor statements
example:  #define X 32
related:  Macros, macro, def, #ifdef, #ifndef
group:    macro
updated:  24/02/2017
.


key:      "#ifdef 13"
key:      "#ifndef 13"
action:   include code if symbol already defined
use:      to allow blocks of code to be included or omitted at compile time
example:  #ifdef MSWIN
    #include "windows.inc"
  #endif
related:  #if, #elseif, #endif
group:    meta control
updated:  08/02/2018
.


key:      "undef 13"
same:     "#undef 13"
same:     "#undefine 13"
action:   remove a previously defined symbol
use:      remove access to private symbols in a module.
example:  
  undef a,b,c,d
remarks:  will not work for procedures or labels.
related:  scope #define, def, deff, dim
group:    macro
updated:  23/06/2022
.


key:      "macro 13"
action:   define a high level macro
use:      many uses. Often a pseudo function for producing
  inline code instead of a call
example:  
incfile1: demos\basics\Macros.o2bas
related:  macros, #define, #def, def, deff
group:    Oxygen Basic macro
updated:  16/06/2018
.


key:      "#print 13"
action:   display a constant expression during compilation
use:      Compile time diagnostics.
example:  #print "not implemented"
related:  #recordof, #if, #alert, #error
group:    compile-time diagnostics
updated:  16/06/2018
.

key:      "#blockdepth 13"
action:   return block nesting depth.
use:      to checking block depth at compile time.
example:  #blockdepth node x 'use any descriptive label on the line
remarks:  this command was introduced to catch unclosed blocks which
  are often hard to trace.
related:  scope, #recordof
group:    compile-time diagnostics
updated:  
.


key:      "#recordof 13"
action:   return internal record of a declared entity.
use:      to check status at compile time.
example:  #recordof MyStructure
remarks:  this command was introduced to aid debugging at compile time
  are often hard to trace.
related:  #blockdepth
group:    compile-time diagnostics
updated:  
.


'================================
'primitives (Basic and C style
'================================


key:  "void      15"
action:   
use:      specify a null type
example:  'Variables:
  void * pv = getmemory(100 * sizeof float)
  ...
  freememory pv
  '
  'In function headers:
  function foo(byref v as void) as void ptr
  void* foo(void*v)
  
  'Procedures not returning a value:
  void foo()
  '
remarks:  Void cannot be used directly.
related:  sys, any, types
group:    primitive types
updated:  15/02/2018
.

key:  "sbyte     15"
action:   
use:      specify a signed byte type (8 bits wide)
example:  sbyte x=-10
remarks:  limited to values ranging from -128 to 127 / 0x80 to 0x7F
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "byte     15"
action:   
use:      specify a byte type (8 bits wide)
example:  byte colon=58
remarks:  limited to values 0..255 / 0x00 to 0xFF
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "ubyte     15"
action:   
use:      specify a byte type (8 bits wide)
example:  ubyte semicolon=59
remarks:  limited to values 0..255 / 0x00 to 0xFF
related:  types
group:    primitive types
updated:  05/04/2017
.


key:  "string    15"
action:   
use:      specify a string type with 8-bit characters
example:  string s="name: "
remarks:  strings are automatically destroyed when out of scope.
related:  wstring, types
group:    primitive types
updated:  05/04/2017
.


key:  "wstring   15"
action:   
use:      specify a string type with 16-bit characters, supporting unicode
example:  wstring sw
  getfile "greek.txt",sw
remarks:  strings are automatically destroyed when out of scope.
related:  unic, types
group:    primitive types
updated:  05/04/2017
.

key:  "bstring   15"
action:   
use:      specify a bstring type with 8-bit characters
example:  bstring s="name: "
  ...
  frees s
remarks:  bstrings must be freed before going out of scope.
related:  wbstring, types
group:    primitive types
updated:  05/04/2017
.


.

key:  "bstr      15"
action:   
use:      specify a bstring type with 8-bit characters
example:  bstr s="name: "
  ...
  frees s
remarks:  bstrings must be freed before going out of scope.
related:  wbstring, types
group:    primitive types
updated:  05/04/2017
.


key:  "wbstring  15"
action:   
use:      specify a bstring type with 16-bit characters, supporting unicode
example:  wbstring sw
  getfile "greek.txt",sw
  ...
  frees sw
remarks:  bstrings must be freed before going out of scope.
related:  bstring, types
group:    primitive types
updated:  22/06/2019
.


key:  "char      15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  char w="world"
  char buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to C char, but is not conflated with byte which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "wchar     15"
action:   
use:      specify a string of wide characters (16 bits wide)
example:  wchar w="world"
  wchar buf[1024]
  buf=w
  print buf
remarks:  
related:  char, types
group:    primitive types
updated:  05/04/2017
.



key:  "asciiz    15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  asciiz w="world"
  asciiz buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to C char, but is not conflated with byte which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "zstring   15"
action:   
use:      specify a string of ascii characters (8 bits wide)
example:  zstring w="world"
  zstring buf[1024]
  buf=w
  print "hello "+buf
remarks:  similar to C char, but is not conflated with byte which is a numeric type
related:  wchar, types
group:    primitive types
updated:  05/04/2017
.


key:  "wzstring  15"
action:   
use:      specify a string of wide characters (16 bits wide)
example:  wzstring w="world"
  wzstring buf[1024]
  buf=w
  print buf
remarks:  
related:  char, types
group:    primitive types
updated:  22/06/2019
.


key:  "short     15"
use:      specify a short integer (16 bits wide). Also used in conjunction
  with other types to halve the bit width
example:  short a
  short int b
  short short c 'an sbyte
remarks:  
related:  long, types
group:    primitive types
updated:  05/04/2017
.


key:  "wide      15"
use:      specify a wide character string (16 bits wide). Also used in conjunction
  with other types to double the bit width
example:  wide s
  wide char sw
  wide float fw 'a double precision float
remarks:  
related:  short, types
group:    primitive types
updated:  05/04/2017
.


key:  "long      15"
use:      specify a long integer (32 bits wide). Also used in conjunction
  with other types to double the bit width
example:  long i
   long sbyte w  'a 16 bit integer
  long char sw  'a wchar character
  long float fw 'a double precision float
remarks:  
related:  short, types
group:    primitive types
updated:  05/04/2017
.


key:  "int       15"
use:      specify a long signed integer (32 bits wide)
example:  int i=0x7fffffff
remarks:  
related:  dword, types
group:    primitive types
updated:  05/04/2017
.


key:  "integer   15"
use:      specify a long signed integer (32 bits wide)
example:  integer i=0x7fffffff
remarks:  
related:  dword, types
group:    primitive types
updated:  05/04/2017
.


key:  "float     15"
use:      specify a floating point variable (32 bits wide)
example:  float f=1/100
remarks:  same as single
related:  single, double, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "single    15"
use:      specify a floating point variable (32 bits wide)
example:  single f=1/100
remarks:  same as float
related:  float, double, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "double    15"
use:      specify a double precision floating point variable (64 bits wide)
example:  double f=1/3
remarks:  
related:  single, float, extended, types
group:    primitive types
updated:  30/12/2017
.


key:  "extended  15"
use:      specify an extended precision floating point variable (80 bits wide)
example:  extended e=1/3
remarks:  this type holds the full precision of the pentium floatin point processor (FPU)
related:  single, float, double, types
group:    primitive types
updated:  30/12/2017
.


key:  "quad      15"
use:      specify a double precision signed integer (64 bits wide)
example:  quad q
remarks:  In a 64 bit system, these are processed directly on the CPU.
  In a 32 bit system, quads are passed to the FPU for processing
related:  qword, int, short, sbyte types
group:    primitive types
updated:  30/12/2017
.


key:  "word      15"
use:      specify a short unsigned integer (16 bits wide)
example:  word w=0xA000
remarks:  
related:  short, int, dword, types
group:    primitive types
updated:  30/12/2017
.


key:  "dword     15"
use:      specify a long unsigned integer (32 bits wide)
example:  dword ui=0xA0000000
remarks:  
related:  word, long, int, quad, types
group:    primitive types
updated:  30/12/2017
.


key:  "ulong     15"
use:      specify a long unsigned integer (32 bits wide)
example:  ulong u=0xA0000000
remarks:  same as uint  
related:  uint, word, types
group:    primitive types
updated:  30/12/2017
.


key:  "uint      15"
use:      specify a long unsigned integer (32 bits wide)
example:  uint u=0xA0000000
remarks:  same as dword and ulong  
related:  dword, word, byte, types
group:    primitive types
updated:  30/12/2017
.


key:  "qword     15"
use:      specify a 64 bit operand in assembly code
example:  fld qword d
remarks:  Only used in assembly code, not Basic.
related:  integer, quad, types
group:    primitive types
updated:  05/04/2017
.


key:  "any       15"
use:      specify a parameter of uncertain type, nominally a signed integer of system width (32/64 bits wide)
example:  function f(any*a) {...}
remarks:  Parameter of any type may be passed by-reference. Like C void*.
related:  sys, types
group:    primitive types
updated:  05/04/2017
.


key:  "sys       15"
use:      specify a signed integer of system width (32/64 bits wide)
example:  sys i=42
remarks:  this type is always wide enough to hold a pointer.
related:  any, int, quad, types
group:    primitive types
updated:  30/12/2017
.


key:  "bool      15"
use:      specify a variable to hold Boolean true/false states
example:  bool t=true
  if not t then ...
remarks:  Notionally a Boolean type, but in reality. it is a 32bit signed integer, as in C  
related:  any, types
group:    primitive types
related:  boolean, int, types
updated:  30/12/2017
.


key:  "boolean   15"
use:      specify a variable to hold Boolean true/false states
example:  boolean t=true
  if not t then ...
remarks:  Notionally a Boolean type, but in reality. it is an sbyte (8 bit signed integer  
related:  bool, byte, int, any, types
group:    primitive types
related:  boolean, types
updated:  30/12/2017
.


key:      "signed 15"
action:   specifies the type to be of signed integer
use:      signed type variable
example:  signed int v
result:   a signed int (long) called v is created.
related:  unsigned, int, long, types
group:    primitive types
updated:  30/12/2017
.


key:      "unsigned 15"
action:   specifies the type to be of positive numbers only
use:      unsigned type variable
example:  unsigned long v
result:   an unsigned long (dword) called v is created.
related:  signed, long, word, dword, types
group:    primitive types
updated:  30/12/2017
.



key:  "void      15"
key:  "sbyte     15"
key:  "ubyte     15"
key:  "byte      15"
key:  "string    15"
key:  "wstring   15"
key:  "bstring   15"
key:  "bstr      15"
key:  "wbstring  15"
key:  "char      15"
key:  "wchar     15"
key:  "asciiz    15"
key:  "zstring   15"
key:  "wzstring  15"
key:  "short     15"
key:  "wide      15"
key:  "long      15"
key:  "int       15"
key:  "integer   15"
key:  "float     15"
key:  "single    15"
key:  "double    15"
key:  "extended  15"
key:  "quad      15"
key:  "word      15"
key:  "dword     15"
key:  "ulong     15"
key:  "uint      15"
key:  "qword     15"
key:  "any       15"
key:  "sys       15"
key:  "boolean   15"
key:  "bool      15"
use:      to specify the types of variables and create them
example:  int x
  dim as int x
  dim x as int
  var int x
group:    primitive types
groupref: types
updated:  25/06/2019
.


'===========================================
'>>OVERLOADABLE INTEGER AND STRING FUNCTIONS
' overloadable functions -16
' integer and string
' TREATED AS STDCALL
'===========================================



key:      "news 16"
action:   allocates a bstring of null characters given the length in bytes
use:      bstring=news length
example:  b=news 1000
  '...
  frees b
result:   b contains address of a string of 1000 nul characters . Then the sting is freed
remarks:  Oxygen strings are automatically freed but Bstrings must be explicitly freed when no longer needed.
related:  frees, nuls, space, bstring, getmemory
group:    memory functions
updated:  
.


key:      "frees 16"
action:   deallocates a bstring
use:      frees bstring freememory
example:  b=news 1000
  '...
  frees b
result:   b contains address of a string of 1000 nul characters . Then the sting is freed
remarks:  Oxygen strings are automatically freed but Bstrings must be explicitly freed when no longer needed.
related:  news nuls, freememory, getmemory
group:    memory functions
updated:  
.


key:      "error 16"
action:   returns a string containing the most recent compile or runtime errors (cleared at start of compiling)
use:      to trap runtime errors
example:  string e=error
  if e then print e : 'followied by exit procedures
result:   displays the last error, if it exists.
remarks:  the error buffer is automatically cleared after using this function.
related:  #error, #alert
group:    string functions
updated:  
.


key:      "nuls 16"
action:   returns the address of a string of null characters given the length.
use:      string=nuls length
example:  s=nuls 1000
result:   s is a string of 1000 null characters
remarks:  for wide strings use string(n,wchr 0) instead
related:  space, string, news, frees, getmemory
group:    string functions
updated:  
.



key:      "val 16"
action:   returns numeric value of string
use:      value=val string
example:  v=val "2.5"
result:   v=2.5
related: str hex asc
group:    string, functions
updated:  
.


key:      "ltrim 16"
action:   returns string with white space on the left trimmed off
use:      string=rtrim(string)
example:  s=ltrim "   abc"
result:   s="abc"
related:  rtrim, space, str, lcase, ucase
group:    string functions
updated:  
.


key:      "rtrim 16"
action:   returns string with white space on the right trimmed off
use:      string=rtrim(string)
example:  s=rtrim "abc   "
result:   s="abc"
related:  ltrim, space, str, lcase, ucase
group:    string functions
updated:  
.


key:      "lcase 16"
action:   returns lowercase of string
use:      string=lcase(string)
example:  s=lcase "ABCDEF"
result:   s="abcdef"
related:  ucase, ltrim, rtrim, asc
group:    string functions
updated:  
.


key:      "ucase 16"
action:   returns uppercase of string
use:      string=ucase(string)
example:  s=ucase "abcdef"
result:   s="ABCDEF"
related:  lcase, ltrim, rtrim, asc
group:    string functions
updated:  
.


key:      "string 16"
action:   returns a string of characters
use:      string=string(length,character)
example:  string=string(4,"a")
result:   s="aaaa"
related:  space, nuls, asc
group:    string functions
updated:  
.


key:      "space 16"
action:   returns a string of spaces
use:      string=space length
example:  s=space 10
result:   s="  " ' 10 spaces (ascii 32)
remarks:  for wide strings use string(n,wchr 32) instead
related:  nuls, string, ltrim, rtrim
group:    string functions
updated:  
.


key:      "left 16"
action:   returns left part of a string by length
use:      string=left string1,length
example:  s=left "abcdef",3
result:   s="abc"
related:  right, mid, ltrim, rtrim
group:    string functions
updated:  27/03/2017
.


key:      "mid function 16"
title:    mid function
action:   returns part of string1 at position with length
use:      string=mid string1, position, length 'if length is omitted then the rest of string1 is returned
example:  s=mid "abcdef",3 : t=mid "abcdef",3,2
result:   s="cdef" : t="cd"
remarks:  also works with untyped pointers
related:   left, ltrim, rtrim, instr, mid command
group:    string functions
updated:  27/03/2017
.


key:      "mid command 16"
title:    mid command
action:   patches string2 into string1 as position
use:      mid(string1,position)=string2 : mid string1,position,string2
example:  s="abcdef" : mid s,2,"BC"
result:   s="aBCdef"
related:  mid function, left, ltrim, rtrim
group:    string command
updated:  
.


key:      "instr 16"
action:   returns position of String2 within string1 searching from start position
use:      location=instr(string1,string2) : location=instr(start,string1,string2)
example:  p=instr("abcdef abcdef","def") : q=instr(8,"abcdef abcdef","def")
result:   p=4 : q=11
remarks:  also works with untyped pointers
related:  replace, mid
group:    string functions
updated:  
.


key:      "getfile 16"
action:   copies file content to a string
use:      String=getfile FileName : getfile FileName,String
example:  string s : getfile "t.txt",s
result:   s contains content of "t.txt"
related:  putfile, print
group:    string functions
updated:  
.


key:      "putfile 16"
action:   saves a string to a file
use:      putfile FileName, String
example:  putfile "t.txt","Hello"
result:   A file named "t.xt" is created or overwritten containing "Hello"
related:  getfile, print
group:    string functions
updated:  
.


key:      "print 16"
action:   Displays strings and numbers
use:      print String : print Number
example:  print "ABC" : print 123 : print "ABC: " 123 " DEF: " 456
result:   ABC
  123
  ABC: 123 DEF: 456
remarks:  strings can be combined with numbers as sys as the first element is a string
related:  val, str, hex, putfile, getfile
group:    string functions
updated:  
.


key:      "asc 16"
action:   returns ascii encoding of a character in a string
use:      AsciiCode=asc(String,CharacterPosition)
example:  
  'as function:
  a=asc("ABCDEF",2) 'a=66 'B'
  'as pseudo-command:
  asc(s,2)=98 's="AbCDEF"
related:  unic, chr, mid, val, len, str
group:    string functions
updated:  16/06/2022
.


key:      "unic 16"
action:   returns encoding of a character in a wide string
use:      uni=unic(String,CharacterPosition)
example:  a=unic(L"ABCDEF",2)
result:   a=0x0042 'character='B'
related:  asc, wchr, chr, val, mid, len, str
remarks:  Can also be used as a pseudo-command like asc()
group:    string functions
updated:  16/06/2022
.


key:      "len 16"
action:   returns length of string in charaters
use:      length=len(string)
example:  v=len("Hello")
result:   v=5 characters
remarks:  characters may be one or two bytes (wide characters)
related:  string, space, mid, sizeof
group:    string functions
updated:  16/06/2022
.


key:      "chr 16"
action:   returns string of 1 character of ascii encoding (0..255)
use:      string=chr(AsciiValue)
example:  
  'as function:
  s=chr(65) 's="A"
  'as pseudo-command:
  string s="abcdef"
  chr(s,2)="B" 's="aBcdef"
related:  wchr, asc, unic, mid string
group:    string functions
updated:  16/06/2022
.


key:      "wchr 16"
action:   returns wide string of a 2 byte character (encoding 0..65535 / 0xffff)
use:      widestring=wchr(WideCharValue)
example:  wstring ws=wchr(65)
result:   ws contains unicode character 0x0041
remarks:  Can also be used as a pseudo-command like chr()
related:  unic, asc, mid, string
group:    string functions
updated:  16/06/2022
.


key:      "str 16"
action:   returns string representation of number
use:      String=str(value)
example:  s=str(-1.23456)   ' result: -1.23456
  s=str(-1.23456,3) ' result: -1.235
remarks:  rounding is automatically applied before decimal places are truncated.
related:  hex, val
group:    string functions
updated:  
.


key:      "hex 16"
action:   returns hexadecimal string representation of integer part of number
use:      hexString=hex(value)
example:  print hex(14.4)      'result 'E'
  print hex(14.4, 4)   'result '000E'
related:  str, val
group:    string functions
updated:  
.


key:      "guidval 16"
action:   converts guid string to guidval
use:      COM interfaces
example:  guid clsid
  guidval clsid,"{96749377-3391-11D2-9EE3-00C04F797396}"
related:  guidtxt, com
group:    string functions
updated:  
.


key:      "guidtxt 16"
action:   converts guidval to guidstring
use:      COM interfaces
example:  print guidtxt(clsid)
result:   displays: {96749377-3391-11D2-9EE3-00C04F797396}
related:  guidval, com
group:    string functions
updated:  
.


key:      "numberformat 16"
action:   control how numbers are converted to strings
use:      change the format of numbers
example:  numberformat 3,0,0,0 : print 3.14159
  'result: 3.142
remarks:  there are 6 parameters:
  1 decimal places (0..16)
  2 strip trailing zeros (0 or 1)
  3 always use scientic notation E format (0 or 1)
  4 suppress 0 before decimal point: 0.1 becomes .1 (0 or 1)
  5 insert extra leading space for non-negative numbers (0 or 1)
  6 width allocated before decimal point: (0..31)
    (inserting lead padding spaces)

  when no parameters are given, it reverts to the default settings:
  16,1,0,0,0,0
  rounding is automatically performed before the decimal places are truncated.
related:  print, frac, float
group:    intrinsic procedure
updated:  
.






'===========================
'>>FLOATING POINT MACRO
' macro function
'===========================


key:      "abs 17"
action:   returns the absolute value of a number (removes negative sign)
use:      AbsoluteValue=abs(value)
example:  a=abs(-2.5)
result:   a=2.5
related:  round, frac, trunc, floor, ceil
group:    floating point functions
updated:  
.


key:      "acos 17"
action:   returns angle in radians given the ratio x/radius
use:      angle=acos(YRRatio)
example:  a=acos(0.5)
result:   a=pi/3
related:  cos, asin, atn, atan
group:    floating point functions
updated:  
.


key:      "asin 17"
action:   returns angle in radians given the ratio y/radius
use:      angle=asin(YRRatio)
example:  a=asin(0.5)
result:   a=pi/6
related:  sin, acos, atn, atan
group:    floating point functions
updated:  
.


key:      "atan  17"
action:   returns angle in radians given the values of y and x
use:      angle=atan(y,x)
example:  a=atan(0.5,sqr(0.75))
result:   a=pi/6
related:  atn, asin, acos, tan
group:    floating point functions
updated:  
.


key:      "atn 17"
action:   returns angle in radians given ratio y/x
use:      angle=atn(YXRatio)
example:  a=atn(1)*4
result:   a=pi
related:  atan, asin, acos, tan
group:    floating point functions
updated:  
.


key:      "cos 17"
action:   returns cosine value (ratio of x/r)  given angle in radians
use:      Cosine=cos(radians)
example:  c=cos(pi/3)
result:   c=0.5
related:  sin, tan
group:    floating point functions
updated:  
.


key:      "deg 17"
action:   returns degrees from value given in radians
use:      degrees=deg(radians)
example:  d=deg(pi)
result:   180
related:  rad, atan
group:    floating point functions
updated:  
.


key:      "frac 17"
action:   returns the fractional part of a value
use:      FractionValue=frac(value)
example:  n=frac(123.456)
result:   n=0.456
related:  round, abs
group:    floating point functions
updated:  
.


key:      "hypot 17"
action:   returns the hypotenuse (longest side) of a right angle triangle given the other 2 sides.
use:      hypotenuse=hypot(side1,side2)
example:  h=hypot(3,4)
result:   h=5
related:  sqr, pow
group:    floating point functions
updated:  
.


key:      "lin 17"
key:      "log 17"
action:   returns the logarthm of the first value to base e (2.71828182845904523536.)
use:      LogValue=log(Value)
example:  a=log(10)
result:   a=2.30258092...
related:  lin2, log10, logn, pow
group:    floating point functions
updated:  
.


key:      "log2 17"
action:   returns the logarthm of the first value to base 2
use:      LogValue=log2(Value)
example:  a=log2(32)
result:   a=5
related:  log, log10, logn, pow
group:    floating point functions
updated:  
.


key:      "log10 17"
action:   returns the logarthm of the first value to base 10
use:      LogValue=log10(Value)
example:  a=log10(100)
result:   a=2
related:  log, log2, logn, pow
group:    floating point functions
updated:  
.


key:      "logn 17"
action:   returns the logarthm of the first value to the base of the second value.
use:      value=logn(value1,value2)
example:  u=logn 1000,10) : v=logn(pow(10,1.5),10)
result:   u=3 : v=1.5
related:  log, log2, log10, pow
group:    floating point functions
updated:  
.


key:      "mod 17"
action:   returns the remainder of first value divided by the second value
use:      modulus=mod(value1,value2)
example:  m=mod(83.5, 10)
result:   m=3.5
related:  round, trunc, floor, ceil, frac, abs
group:    floating point functions
updated:  
.


key:      "pi 17"
action:   returns pi, the ratio of the circumference of a circle to its diameter
use:      p=pi ' or pi()
example:  p=pi*2
result:   p=6.283185...
related:  tan, atan
group:    floating point functions
updated:  
.


key:      "exp 17"
action:   returns exponent of a value
use:      a=exp(value)
example:  a=exp(1)
result:   a=2.718281828
remarks:  This is the Euler number e, equivalent operation e^v
related:  pow,log, logn
group:    floating point functions
updated:  
.


key:      "pow 17"
action:   returns the value of the first value to the power of the second value
use:      a=pow(value,exponent)
example:  a=pow(2,3)
result:   a=8
remarks:  this is equivalent to 2^3
related:  log, logn
group:    floating point functions
updated:  
.


key:      "rad 17"
action:   returns value in radians, given degrees
use:      radians=rad(degrees)
example:  v=rad(180)
result:   v=pi
related:  deg, pi
group:    floating point functions
updated:  
.


key:      "recip 17"
action:   returns reciprocal of value: a=1/v
use:      reciprocal=recip(value)
example:  a=recip(5/4)
result:   a=0.8
related:  sqr, mod, round, pow, log
group:    floating point functions
updated:  
.


key:      "round 17"
action:   returns a value rounded to the nearest whole number (rounded up or down)
use:      WholeNumber=round(number)
example:  m=round(1.49) : n=round(1.5)
result:   m=1 : n=2
related:  frac, trunc, floor, ceil, mod, abs
group:    floating point functions
updated:  
.


key:      "sgn 17"
action:   returns -1 for negative values, 0 for zero and 1 for positive values
use:      extract the sign of a number
example:  a=sgn(-42)
result:   a=-1
related:  abs, frac, round, mod
group:    floating point functions
updated:  
.


key:      "sin 17"
action:   returns the sine of a value given in radians
use:      Sine=sin(Radians)
example:  v=sin(pi/6)
result:   v=0.5
related:  asin, cos, tan
group:    floating point functions
updated:  
.


key:      "sqr 17"
key:      "sqrt 17"
action:   returns the square root of a value
use:      SquareRoot=sqr(value)
example:  v=sqr(9)
result:   3
remarks:  sqr and sqrt are the same
related:  pow, log, hypot
group:    floating point functions
updated:  
.


key:      "tan 17"
action:   returns the tangent of a value given in radians
use:      tangent=tan(radians)
example:  t=tan(a)
result:   t= ratio y/x
related:  atan, atn, sin, cos
group:    floating point functions
updated:  
.


key:      "floor 17"
action:   round down the value to the most negative integer
use:      IntegerValue=floor(FloatValue)
example:  i=floor(-123.456)
result:   i=-124
related:  ceil, round, trunc, frac
group:    floating point functions
updated:  
.


key:      "ceil 17"
action:   round up the value to the most positive integer
use:      IntegerValue=ceil(FloatValue)
example:  i=ceil(123.456)
result:   i=124
related:  floor, round, trunc, frac
group:    floating point functions
updated:  
.


key:      "trunc 17"
action:   truncate the fractional part of a value and return it
use:      IntegerValue=trunc(FloatValue)
example:  i=trunc(123.456)
result:   i=123
group:    floating point functions
related:  round, floor, ceil, frac
updated:  
.





'==============
'OTHER KEYWORDS
'==============



'METACODINGS
'===========
' 50 misc
' 51 operators
' 52 conditionals and loops
' 53 metatypes
' 54 class qualifier keywords etc
' 55 calling conventions
' 56 comments
' 57 secondary metalanguage
'
' 99 topics (not keywords)
'updated:  16/06/2016
.


key:      "null 50"
action:   force pointer value to be 0
use:      passing 0 as a string or structure pointer
example:  ofn.lpstrFileTitle = null
   MessageBox null,"text","title",0
remarks:  When used as a parameter, null is equivalent to byval 0.
related: byval
updated:  15/02/2018
.


key:      "byval 50"
action:   pass a parameter by value  
use:      In function prototypes and calls
example:  'In prototypes: receiving a value directly
  function foo(byval v as long)
  'equivalent in C notation:
  long foo(long v)
  
  'In calls: passing a value directly
  err=CoCreateInstance VoiceObjGuid, pUnkouter, context, ISpVoiceGuid, byval @@voice
  
remarks:  
related:  byref, null, #byval, #byref
updated:  15/02/2018
.


key:      "byref 50"
action:   pass a parameter by reference (address)  
use:      In function prototypes and calls
example:  'In prototypes: receiving a value indirectly
  function foo(byref v as long) as long
  'equivalent in C notation:
  long foo(long * v)
  
  'In dim statements:
  dim as word byref a = getmemory(1024)
  'equivalent in C notation:
  word * v = getmemory(1024)
  'equivalent using 'at':
  word v at getmemory(1024)
  
remarks:  
related:  byval, null, #byref, #byval
updated:  15/02/2018
.

key:      "not conditional 51"
action:   invert conditional logic
use:      inversion of condition
example:  'if not a>42 then' ...  'if a<=42 then'
remarks:  'not' inverts the outcome of the rest of the conditional expression
related:  true, false, not bits
group:    conditional modifier
updated:  27/03/2017
.


key:      "not bits 51"
action:   inverts bits
use:      invert bits of variable or expression
example:  int b=0x55 : a=not(b) 'bitwise inversion a=0xaa
remarks:
related:  not conditional, true, false
group:    operators
updated:  27/03/2017
.


key:      "extends 54"
group:    secondary keyword
remarks:  'of', and 'from' and extends are equivalent. They 
  indicate derivation from a single parental class.
  COM interfaces us single inheritance
related:  has, class, classes
updated:  03/03/2017
.


key:      "of 54"
group:    secondary keyword
remarks:  'of', and 'from' and extends are equivalent. They 
  indicate derivation from a single parental class.
  COM interfaces us single inheritance
related:  has, class, classes
updated:  03/03/2017
.


key:      "from 54"
group:    secondary keyword
remarks:  'of', and 'from' and extends are equivalent. They 
  indicate derivation from a single parental class.
  COM interfaces us single inheritance
related:  has, class, classes
updated:  03/03/2017
.


key:      "has 54"
group:    secondary keyword
example:  class person
    has mind
     has body
    ...

remarks:  <b>'has'</b> is used when the class is derived from more than a single
  parental class. ie: multiple inheritance. 'has' may be omitted. It is sufficient
  to provide the class/type name without this qualifier.
related:  of, from, extends, class, classes
updated:  03/03/2017
.


key:      "lib 54"
group:    secondary keyword
remarks:  lib may be specified in the Declare statement or it may be
  specified in an extern statement, referring to an entire group
  of declarations.
related:  library, declare, extern, alias, link, at
updated:  20/02/2017
.


key:      "export 54"
group:    secondary keyword
remarks:  procedures with this attribute are visible to external callers
  when they are compiled as part of a DLL (Dynamic Link Library)
related:  external, function, sub, extern
updated:  20/02/2017
.


data:     "at 54"
group:    secondary keyword
remarks:  used to specify the loction of the procedure.
  This could be a register operand [ebx+4] or a simple variable
related:  link, dim
updated:  20/02/2017
.


key:      "external 54"
group:    secondary keyword
remarks:  functions with the external attribute expect to be called from
  procedures external to Oxygen. Additional register management is
  enlisted to support external calls.

  Objects of classes with this attribute have virtual function table
  pointers embedded in their structures to enable their methods to
  be invoked externally. For internally used objects, the methods table
  is known to the objects at compile time so VFT pointers are not used.
related:  extern, com, export, callback, com, virtual, function, sub, method
updated:  20/02/2017
.

key:      "com 54"
related:  virtual external export class of inherits
group:    secondary keyword
remarks:  COM is a protocol used by Microsoft to provide Object interfaces. Classes
  with this attribute are considered Virtual.
related:  extern, virtual, class
updated:  20/02/2017
.


key:      "virtual 54"
related:  com external export class
group:    secondary keyword
remarks:  objects of virtual classes are usually created by some
  kind of server or class factory. The client only receives
  a reference (pointer) to the object from the server and only knows
  how to invoke its methods. It assumes no knowledge of its inner workings.
related:  extern, com, class
updated:  20/02/2017
.


key:      "public 54"
use:      determines the scope of a class member
remarks:  this term is now ignored in class definitions
related:  protected, private
updated:  10/01/2018
.


key:      "protected 54"
use:      determines the scope of a class member
remarks:  this term is now ignored in class definitions
related:  public, private
updated:  10/01/2018
.


key:      "private 54"
use:      determines the scope of a class member
remarks:  this term is now ignored in class definitions
related:  protected, public
updated:  10/01/2018
.


'============
'GROUP TOPICS
'============

key:      "dim 53"
key:      "as 54"
key:      "ptr 54"
key:      "* 54"
key:      "at 54"
key:      "global 54"
key:      "static 54"
key:      "local 54"
groupref: dimsyntax
group:    creating variables
incfile1: demos\basics\DimSyntax.o2bas
remarks:  C style instantiations is a simpler alternative to using 'Dim'.

  When autodim is active (by default), variables can be automatically 
  instantiated unless they are arrays or referenced (byref) variables.
related:  global, local, static
updated:  16/01/2021
.


key:      "type 53"
key:      "typedef 53"
key:      "truct 53"
use:      specify compund structure for a variable
groupref: inhstructures
group:    inherited structures
incfile1: demos\basics\types.o2bas
related:  struct, typedef
updated:  20/02/2017
.


key:      "end 53"
action:   marks the end of a code block
use:      terminating various block structures
example:  if a>b then
    b=a
  end if
remarks:  An isolated 'end' terminates the program.
related:  scope, if, do, while, select, function, sub, method, class, macro, def
group:    Oxygen Basic keywords
updated:  20/02/2017
.


key:      "once 54"
action:   ensures that a file is included in the source code one only.
example:  #include once "../../MinWin.inc"
related:  include, #include, includepath
groupref: includes
group:    secondary keyword
updated:  20/02/2017
.


key:      "$ 53"
key:      "% 53"
groupref: equates
group:    equates
incfile1: demos\basics\equates.o2bas
remarks:  $ and % are equivalent
related:  def, #def, macro, #define
updated:  20/02/2017
.


key:      "arrays 99"
groupref: arrays
group:    creating arrays
remarks:  Only single dimensioned arrays are directly supported
related:  dim
incfile1: demos\basics\Arrays.o2bas
updated:  20/02/2017
.


key:      "scope 52"
key:      "skip 52"
key:      "o2 52"
key:      "( 52"
groupref: blocks
group:    blocks
incfile1: demos\basics\macros.o2bas
related:  procedures, macros
updated:  24/02/2017
.


key:      "macro 52"
key:      "#define 52"
key:      "def 52"
key:      "deff 52"
key:      "% 52"
key:      "$ 52"
groupref: macros
group:    macros
related:   macro functions, macro operators, procedures
updated:  26/02/2017
.


key:      "init 59"
key:      "free 59"
key:      "conv 59"
key:      "move 59"
key:      "save 59"
key:      "neg 59"
action:   supports operation on compund types  
use:      formulating expressions, in conjunction with higher operands
example:  
incfile1: demos\basics\OperatorsVector.o2bas
remarks:  
group:    macro operators
groupref: macro operators
related:  macros, macro functions, operators
updated:  15/01/2021
.


key:      "macro functions 99"
action    replaces macro with a temp variable.
use:      invoke multi-line macros within expressions
example:  
incfile1: demos\basics\MacroFunctions.o2bas
remarks:  implements in-line functions
related:  macros, macro operators
updated:  16/06/2018
.


key:      "function 52"
key:      "sub 52"
key:      "method 52"
key:      "gosub 52"
key:      "as 54"
key:      "link 54"
key:      "export 54"
key:      "external 52"
key:      "noproto 52"
groupref: procedures
group:    procedural blocks
incfile1: demos\basics\procedures.o2bas
related:  macro
updated:  24/02/2017
.


key:      "if 52"
key:      "then 52"
key:      "elseif 52"
key:      "else 52"
key:      "endif 52"
groupref: conditionals
group:    conditional blocks
incfile1: demos\basics\conditionals.o2bas
related:  selection, loops
updated:  24/02/2017
.


key:      "do 52"
key:      "while 52"
key:      "exit 52"
key:      "continue 52"
key:      "wend 52"
key:      "enddo 52"
groupref: loops
group:    loop blocks
incfile1: demos\basics\loops.o2bas
related:  iteration, conditionals
updated:  24/02/2017
.


key:      "for 52"
key:      "to  52"
key:      "step 52"
key:      "next 52"
groupref: iteration
group:    iteration blocks
incfile1: demos\basics\iteration.o2bas
related:  loops
updated:  24/02/2017
.


key:      "select 52"
key:      "case 52"
key:      "switch 52"
key:      "case else 52" 'itr case else
key:      "endselect 52" 'itr end select
groupref: selection
group:    case selection
incfile1: demos\basics\select.o2bas
related:  conditionals
updated:  14/01/2021
.


key:      "declare 54"
key:      "! 54"
key:      "function 53"
key:      "sub 53"
key:      "ptr 53"
key:      "alias 53"
key:      "lib 53"
key:      "stdcall 53"
key:      "cdecl 53"
key:      "pascal 53"
key:      "ms64 53"
key:      "as 53"
key:      "export 53"
key:      "extern 53"
key:      "external 53"
key:      "callback 53"
key:      "link 53"
key:      "at 53"
key:      "= 53"
key:      "label 53"
key:      "nosig 53"
groupref: declarations
group:    declaring procedures
keywords: 

  <b>Left-side keywords:</b>

  declare
  !
  same as 'declare'
  function
  optional
  sub
  optional 
  ptr
  function pointer
  *
  function pointer
  alias
  exact name of the function in the dll (dynamic link library)
  optional if the function name is an exact match
  lib
  name of dll
  stdcall
  calling convention (32bit default)
  cdecl
  C calling convention (32bit)
  pascal
  pascal calling convention (32bit)
  ms64
  MS calling convention (64bit default)


  <b>Right-side keywords:</b>

  as
  type of return value
  link
  store function location to specified variable.
  at
  specify pointer to the function location
  =
  same as 'at'
incfile1: 
related:  procedures, types
updated:  18/01/2021
.


key:      "type 53"
action:   define a compound structure for variables
use:      User defined types (UDT)
groupref: structures
group:    compound structures
incfile1: demos\basics\types.o2bas
related:  structures, classes, class
updated:  14/01/2021
.


key:      "class 53"
key:      "objects 53"
key:      "OOP 53"
key:      "has 54"
key:      "of 54"
key:      "from 54"
key:      "inherits 54"
key:      "virtual 54"
key:      "pure 54"
key:      "com 54"
key:      "new 54"
key:      "del 54"
groupref: classes
group:    object oriented programming
incfile1: demos\basics\classes.o2bas
related:  structures, type
updated:  10/01/2018
.


key:      "' 56"
action:   comment till end of line
use:      
example:  'this is a comment
related:  rem   /*   */   //  ;
group:    Oxygen keywords
updated:  25/02/2017
.


key:      "; 56"
action:   comment till end of line
use:      
example:  'this is a comment
related:  rem   '   /*   */   //
group:    Oxygen keywords
updated:  25/02/2017
.


key:      "// 56"
action:   comment till end of line
use:      
example:  // this is a comment
related:  rem   '   ;   /*   */
group:    Oxygen keywords
updated:  25/02/2017
.


key:      "/* 56"
action:   comment till end of block
use:      
example:  /* this is a comment */

  /*
    this is also a comment
  */
related:  skip rem   '   ;   */   //
group:    Oxygen keywords
updated:  25/02/2017
.


key:      "*/ 56"
action:   terminate comment block
use:      
example:  /* this is a comment */

  /*
    this is also a comment
  */
related:  skip  rem   '   /*   //   ;
group:    Oxygen keywords
updated:  25/02/2017
.


'---------
'OPERATORS
'=========


key:  "and 51"
same:     &
remarks:  bitwise operator
related:  and, or, xor, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "or 51"
same:     |
remarks:  bitwise operator
related:  and, or=, xor, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "xor 51"
remarks:  bitwise operator
related:  and, or, xor=, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "and= 51"
same:     &=
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "or= 51"
same:     |=
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "xor= 51"
remarks:  bitwise assign operator
related:  and, or, xor, operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "&& 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "|| 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "^^ 51"
remarks:  logical operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "&&= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "||= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "^^= 51"
remarks:  logical assign operator
related:  &&, ||, ^^ operators
group:    Oxygen keywords
updated:  10/01/2018
.


key:  "and 51"
key:  "or 51"
key:  "xor 51"
key:  "= 51"
key:  ":= 51"
key:  "+ 51"
key:  "- 51"
key:  "* 51"
key:  "/ 51"
key:  "\ 51"
key:  "^ 51"
key:  "+= 51"
key:  "-= 51"
key:  "*= 51"
key:  "/= 51"
key:  "== 51"
key:  "!= 51" 'itr check
key:  "<> 51"
key:  "< 51"
key:  "> 51"
key:  "<= 51"
key:  "> 51"
key:  ">= 51"
key:  "<= 51"
key:  "and= 51"
key:  "or= 51"
key:  "xor=" 51"
key:  "& 51"
key:  "| 51"
key:  "&= 51"
key:  "|= 51"
key:  "&& 51"
key:  "|| 51"
key:  "^^ 51"
key:  "&&= 51"
key:  "||= 51"
key:  "^^= 51"
key:  "<< 51"
key:  ">> 51"
key:  "<<< 51"
key:  ">>> 51"
action:   changes the state of an accumulator  
use:      formulating expressions, in conjunction with operands
example:  a*b+c/4
remarks:  universal feature of maths and programming languages
group:    operators and comparators
groupref: operators
related:  types
updated:  10/01/2018
.


'-------------------
'CALLING CONVENTIONS
'===================


key:  "stdcall 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions
example:  ! Sleep lib "kernel32.dll" stdcall (int msec)
remarks:  this is the default calling convention on 32bit Windows platforms.
group:    calling conventions
related:  calling conventions, cdecl, ms64, pascal
updated:  17/06/2022
.


key:  "pascal 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions
example:  ! Sleep lib "kernel32.dll" stdcall (int msec)
remarks:  this is a legacy calling convention on 32bit platforms.
group:    calling conventions
related:  calling conventions, stdcall, cdecl, ms64
updated:  17/06/2022
.


key:  "cdecl 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions, and variadic functions
example:  
remarks:  this is a common calling convention on 32bit platforms. The stack is cleaned up
  after the call by the caller.
group:    calling conventions
related:  calling conventions, cdecl, ms64, pascal, callback
updated:  17/06/2022
.


key:  "ms64 55"
action:   determines how parameters are passed on the stack   
use:      declaring external functions, and variadic functions
example:  
remarks:  this is the default Windows calling convention on 64bit platforms.
  The first four parameters are passed in registers. 
  The stack is cleaned up after the call by the caller.
group:    calling conventions
related:  calling conventions, stdcall, cdecl, pascal
updated:  17/06/2022
.


key:  "stdcall 55"
key:  "cdecl 55"
key:  "ms64 55"
key:  "pascal 55"
keylinks: yes
title:    calling conventions
action:   determines how parameters are passed on the stack, when making a call
groupref: calling_conventions
group:    calling conventions
related:  extern
updated:  17/06/2022
.


key:      "defined 57"
key:      "undefined 57"
key:      "match 57"
key:      "leftmatch 57"
key:      "rightmatch 57"
key:      "anymatch 57"
keylinks: yes
title:    meta keywords
related:  #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
groupref: metakeywords
group:    meta control
updated:  20/06/2022
.


key:      "defined 57"
title:    defined
action:   test whether a symbol exists
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if defined X
  #else
    dim string X
  #endif
related:  undefined, #ifdef, #ifndef, #if, #elseif, #else, #endif, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "undefined 57"
title:    undefined
action:   test whether a symbol exists
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if undefined X
    dim string X
  #endif
related:  defined, #ifdef, #ifndef, #if, #elseif, #else, #endif, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "match 57"
title:    match
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if leftmatch X, "vector"
    'X must be vector
    #include "mathutil.inc"
  #endif
related:  leftmatch, rightmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "leftmatch 57"
title:    leftmatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if leftmatch X, "vector"
    'X could be vector vector2f vector3f
    #include "mathutil.inc"
  #endif
related:  match, rightmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.


key:      "rightmatch 57"
title:    rightmatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if rightmatch X, "Vec"
    'X could be aVec bVec FloatVec
    #include "mathutil.inc"
  #endif
related:  match, leftmatch, anymatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.

key:      "anymatch 57"
title:    anymatch
action:   match testing of symbol names
use:      to allow blocks of code to be included or omitted at compile time
example:  
  #if anymatch X, "Vec"
    'X could be aVec FloatVec2 vector3f
    #include "mathutil.inc"
  #endif
related:  match, leftmatch, rightmatch, #if, #elseif, #else, #endif, typeof, typecodeof, def, macro
remarks:  generally for use inside macros
group:    meta control
updated:  20/06/2022
.



'===========================
'>>REGISTERS
'===========================

key:  "al    10"
key:  "cl    10"
key:  "dl    10"
key:  "bl    10"
key:  "ah    10"
key:  "ch    10"
key:  "dh    10"
key:  "bh    10"
key:  "ax    10"
key:  "cx    10"
key:  "dx    10"
key:  "bx    10"
key:  "sp    10"
key:  "bp    10"
key:  "si    10"
key:  "di    10"
key:  "eax   10"
key:  "ecx   10"
key:  "edx   10"
key:  "ebx   10"
key:  "esp   10"
key:  "ebp   10"
key:  "esi   10"
key:  "edi   10"
key:  "st0   10"
key:  "st1   10"
key:  "st2   10"
key:  "st3   10"
key:  "st4   10"
key:  "st5   10"
key:  "st6   10"
key:  "st7   10"
key:  "mmx0  10" 
key:  "mmx1  10" 
key:  "mmx2  10" 
key:  "mmx3  10" 
key:  "mmx4  10" 
key:  "mmx5  10" 
key:  "mmx6  10" 
key:  "mmx7  10" 
key:  "xmm0  10"
key:  "xmm1  10"
key:  "xmm2  10"
key:  "xmm3  10"
key:  "xmm4  10"
key:  "xmm5  10"
key:  "xmm6  10"
key:  "xmm7  10"
key:  "xmm8  10"
key:  "xmm9  10"
key:  "xmm10 10"
key:  "xmm11 10"
key:  "xmm12 10"
key:  "xmm13 10"
key:  "xmm14 10"
key:  "xmm15 10"
key:  "cr0   10" 
key:  "cr2   10" 
key:  "cr3   10" 
key:  "cr4   10" 
key:  "dr0   10"
key:  "dr1   10" 
key:  "dr2   10" 
key:  "dr3   10" 
key:  "dr4   10"
key:  "dr5   10" 
key:  "dr6   10" 
key:  "dr7   10" 
key:  "es    10"
key:  "cs    10" 
key:  "ss    10" 
key:  "ds    10" 
key:  "fs    10"
key:  "gs    10" 
key:  "rax   10"
key:  "rcx   10"
key:  "rdx   10"
key:  "rbx   10"
key:  "rsp   10"
key:  "rbp   10"
key:  "rsi   10"
key:  "rdi   10"
key:  "r8    10"
key:  "r9    10"
key:  "r10   10"
key:  "r11   10"
key:  "r12   10"
key:  "r13   10"
key:  "r14   10"
key:  "r15   10"
key:  "r8l   10"
key:  "r9l   10"
key:  "r10l  10"
key:  "r11l  10"
key:  "r12l  10"
key:  "r13l  10"
key:  "r14l  10"
key:  "r15l  10"
key:  "r8w   10"
key:  "r9w   10"
key:  "r10w  10"
key:  "r11w  10"
key:  "r12w  10"
key:  "r13w  10"
key:  "r14w  10"
key:  "r15w  10"
key:  "r8d   10"
key:  "r9d   10"
key:  "r10d  10"
key:  "r11d  10"
key:  "r12d  10"
key:  "r13d  10"
key:  "r14d  10"
key:  "r15d  10"

action:   
use:      access CPU registers directly using Assembly code
example:  mov eax,42
  add eax,ecx
result:   eax now contains 42 plus the value in ecx
remarks:  many of these registers are only accessible if the CPU
  is runnig in a particular mode - eg: the R* registers require
  64 bit mode.
group:    X86 CPU registers
groupref: registers
updated:  10/01/2018
.




'===
'END
'===
