 ' DOS [if]
 variable lfa
 variable help_stream  2variable help_seek
   : help_pos
   BEGIN
   >in @  bl word count nip swap >in !
   WHILE
   'link   dup lfa !
    IF
        lfa @  >hfa 2@ OR
        IF
           ." HELP double defined " here   count type   cr
        THEN
        source-id  file-position drop   lfa @  >hfa 2!
   ELSE
        ."  not found " here    count type cr
   THEN
   REPEAT
 ;
   : help_pos?
   >in @
   bl  parse
   0 ?do dup @char [char] ? = IF [char] / over !char THEN
         sizeof(char) +  LOOP drop
    >in ! help_pos
 ;
 : help? ( lfa -- )
   \ cr
   dup >ncfa count type cr
   ."  Flags = "
   dup >ffa @
   dup   2 and IF ."   immed   " THEN
   dup   4 and IF ."  restrict " THEN
   dup   8 and IF ."   core    " THEN
   dup $20 and IF ."   used    " THEN
       $10 and IF ." coded in C" ELSE ." user definition" THEN
   cr
   dup IF  >hfa 2@  help_seek 2!
         help_seek 2@ OR
         IF  ( seek_pos /= 0 )
            help-file r/o/cli open-file
           0= IF
              help_stream !
              help_seek 2@  help_stream @  reposition-file drop
              BEGIN
                 here $40 +  $400 help_stream @ read-line drop drop drop
                 here $40 +  @char [char] \ =
                 IF   here $40 +  sizeof(char) + .\0  0 cr
                 ELSE 1  \ here $40 +  .\0 cr
                 THEN
              UNTIL
              help_stream @ close-file drop
            ELSE ( could not open help file )
              drop ." could not open the help file " cr
            THEN
         ELSE ( seek_pos = 0 )
           ."  no help available" cr
         THEN
        ELSE ( not found )
          drop    ." not found in vocabulary " cr
        THEN
 ." ============================================================" cr
 ;
 : help
   'link dup lfa !
   IF
     lfa @ help?
   ELSE
     here count nip
     IF    \ a not found word
     ." word " here count type
        ."  not found in search word-list(s)" cr
     ELSE   \ no input string
       s" help help " evaluate
     THEN
   THEN
 ;
 : help*
   [ ' help? ] literal
   get-current  xt-wid-words*
 ;
 [else]
 variable lfa
 variable help_stream  variable help_seek
   : help_pos
   BEGIN
   >in @  bl word count nip swap >in !
   WHILE
   'link   dup lfa !
    IF
        lfa @  >hfa @
        IF
           ." HELP double defined " here   count type   cr
        THEN
        source-id  file-position   drop lfa @  >hfa !
   ELSE
        ."  not found " here    count type cr
   THEN
   REPEAT
 ;
   : help_pos?
   >in @
   bl  parse
   0 ?do dup @char [char] ? = IF [char] / over !char THEN
         sizeof(char) +  LOOP drop
    >in ! help_pos
 ;
 : help? ( lfa -- )
   \ cr
   dup >ncfa count type cr
   ."  Flags = "
   dup >ffa @
   dup   2 and IF ."   immed   " THEN
   dup   4 and IF ."  restrict " THEN
   dup   8 and IF ."   core    " THEN
   dup $20 and IF ."   used    " THEN
       $10 and IF ." coded in C" ELSE ." user definition" THEN
   cr
   dup IF  >hfa @  help_seek !
         help_seek @
         IF  ( seek_pos /= 0 )
            help-file fam=ro fam>cli open-file
            0=
            IF
              help_stream !
              help_seek @  help_stream @  reposition-file drop
              BEGIN
                 here $40 +  $400 help_stream @ read-cline drop drop drop
                 here $40 +  @char [char] \ =
                 IF   here $40 +  sizeof(char) + .\0  0 cr
                 ELSE 1  \ here $40 +  .\0 cr
                 THEN
              UNTIL
              help_stream @ close-file drop
            ELSE ( could not open help file )
              drop ." could not open the help file " cr
            THEN
         ELSE ( seek_pos = 0 )
           ."  no help available" cr
         THEN
        ELSE ( not found )
          drop    ." not found in vocabulary " cr
        THEN
 ." ============================================================" cr
 ;
 : help
   'link dup lfa !
   IF
     lfa @ help?
   ELSE
     here count nip
     IF    \ a not found word
     ." word " here count type
        ."  not found in search word-list(s)" cr
     ELSE   \ no input string
       s" help help " evaluate
     THEN
   THEN
 ;
 : help*
   [ ' help? ] literal
   get-current  xt-wid-words*
 ;
 [then]
 : help_0pos help_pos ;
 : help_0pos? help_pos? ;
\
\ only _forth also
 help_pos help
\ (--)
\ Used in the form HELP  fred
\ Where   fred  is a  FORTH WORD
\ HELP will then display 3 fields :-
\  1.  any active FLAGS for the WORD
\  2.  effect of WORD on the DATA STACK
\  3.  a short description of the WORD
\
\ try  HELP*  fred   to find all help information in the current search
\ vocabulary for any FORTH words with the text string   fred   anywhere within
\ their name

 help_pos help*
\ (--)
\ Used in the form HELP*  <a FORTH WORD> or <a partial FORTH WORD>
\ HELP* will then display 3 fields :-
\  1.  any active FLAGS for the WORD
\  2.  effect of WORD on the DATA STACK
\  3.  a short description of the WORD
\ for ALL FORTH WORDS which match the partial FORTH WORD
\  e.g. HELP* HELP
\  will display the HELP data for the words HELP and HELP*
\

    [then]
  ' app [if]
 help_pos disp
\
\ (  Var --  )
\
\ Given a valid  IDISPATCH (as a variant) object
\ Query the operating system for information about the object
\ 1) oject type TKIND_ ENUM/RECORD/MODULE/INTERFACE/DISPATCH/COCLASS/ALIAS/UNION/MAX
\ 2) for each METHOD and PROPERTY
\   Func/Get/PUT
\   total number of parameters
\   in brackets,  number of optional parameters refer online  FUNCDESC structure MSDN
\   --         spacer
\   number of possible return values
\   name of METHOD /  PROPERTY
\ All info is sent directly to the screen using commands such as   type cr

 help_pos GetPutFun
\ ( varIDISPATCH  --   )
\ Given the Idispatch of an automation object (as a variant)
\ then list all of its supported activites
\ --
\ FLAGS        Bit map of supported activities
\              0x00 = none
\              0x01 = INVOKE_FUNC
\              0x02 = INVOKE_PROPERTYGET
\              0x04 = INVOKE_PROPERTYPUT
\              0x08 = INVOKE_PROPERTYPUTREF

 help_pos NextEnum
\ ( inVARIANT containing IEnumVARIANT  --  outVARIANT containing child object)
\ InVariant should be a variant containing a     IEnumVARIANT object
\ InVariant type must be VT_UNKNOWN
\ Calls the IEnumVARIANT's NEXT method   which returns a Variant (iDispatch)
\ of the next child object in the IEnumVARIANT's collection
\ See also   ForEachEnum
\
\ inVARIANT containing IEnumVARIANT
\ --
\ outVARIANT containing child object

 help_pos ForEachEnum
\ (  inVARIANT containing collection object  --  outVARIANT containing IEnumVARIANT )
\ InVariant should be a variant containing a collection object with a _NewEnum method
\ Code calls the collections objects method _NewEnum    which returns an IEnumVARIANT object.
\ IEnumVARIANT's method RESET is called.
\ IEnumVARIANT object is returned inside a VARIANT of type  UNKNOWN
\ of the next child object in the IEnumVARIANT's collection
\ See also   NextEnum
\
\ inVARIANT containing collection object
\ --
\ outVARIANT containing IEnumVARIANT

 help_pos GetPutFun
\ ( varBSTR , varIDISPATCH  -- flags )
\ Given the Idispatch of an automation object (as a variant)
\ identify whether the METHOD specified in the text of varBSTR (variant)
\ is a member of the Idispatch, and return a bit map of the
\ supported properties.
\ VARBSTR      Variant string containing the METHOD
\ VARDISPATCH  Variant IDispatch of the automation object
\ --
\ FLAGS        Bit map of supported activities
\              0x00 = none
\              0x01 = INVOKE_FUNC
\              0x02 = INVOKE_PROPERTYGET
\              0x04 = INVOKE_PROPERTYPUT
\              0x08 = INVOKE_PROPERTYPUTREF

 help_pos iDisp
\ ( index , varIDISPATCH   --  ( cntOptParams , cntParams, , InvokeFlags, C-addr,u , 1 ) | -1 | 0     )
\ Given the Idispatch of an automation object (as a variant)
\ identify whether the METHOD specified in the text of varBSTR (variant)
\ is a member of the Idispatch, and return a bit map of the
\ supported properties.
\ VARDISPATCH  Variant IDispatch of the automation object
\ VARBSTR      Variant string containing the METHOD
\ --
\ CNTOPTPARAMS Number of optional parameters
\ CNTPARAMS    Number of parameters
\ InvokeFlags
\              0x00 = none
\              0x01 = INVOKE_FUNC
\              0x02 = INVOKE_PROPERTYGET
\              0x04 = INVOKE_PROPERTYPUT
\              0x08 = INVOKE_PROPERTYPUTREF
\ C-ADDR       Address of character string giving the funcName
\ U            Length of funcName
\               1  varIDISPATCH and INDEX are valid
\              ELSE
\              -1  if varIDISPATCH is not IDISPATCH variant
\              -1  if varIDISPATCH is IDISPATCH variant with value 0
\               0  if INDEX is out of range

 help_pos var=clear
\ ( Var   -- )
\ Set the variant pointed at by VAR to be type  VType_EMPTY
\ Do not release any resources.
\ VAR       Pointer at the Variant to be changed
\ --
\ No output parameters

 help_pos var=addrefchk
\ ( Var   --  reference count)
\ If the variant pointed at by VAR is of type  VType_DISPATCH
\ Then the DISPATCH objects AddRef interface will be called.
\ VAR       Pointer at the Variant
\ --
\ int

 help_pos var=addref
\ ( Var   -- )
\ If the variant pointed at by VAR is of type  VType_DISPATCH
\ Then the DISPATCH objects AddRef interface will be called.
\ VAR       Pointer at the Variant
\ --
\ No output parameters

 help_pos var=release
\ ( Var   -- )
\ Release any resources associated with the variant pointed at by VAR.
\ Leave the variant pointed at by VAR as type  VType_EMPTY
\ VAR       Pointer at the Variant to be released
\ --
\ No output parameters

 help_pos VARIANT
\ (--)
\ Used in the form    VARIANT  name
\ Is broadly comparable with the compilation time activity associated with VARIABLE name
\ expect that the storage space associated with a VARIANT is  24 bytes in a 64 bit architecture.
\
\ No input parameters
\ --
\ No output parameters

 help_pos var.new=release
\ (--)
\ Release the resources associated with all of the internal VARIANTS.
\ Set them all to be of type VType_EMPTY
\
\ No input parameters
\ --
\ No output parameters

 help_pos var.copy
\ ( VarSrc, VarDst  --)
\ Copy the VARIANT pointed at by VarSrc to that pointed at by VarDst.
\ First release any resources associated with VarDst.
\ If VarSrc contains an array or a BSTR it too will be copied.
\ VARSRC    Pointer at the source Variant
\ VARDST    Pointer at the destination Variant
\ --
\ No output parameters

 help_pos var.dup
\ ( VarSrc, VarDst  --)
\ Copy the VARIANT pointed at by VarSrc to that pointed at by VarDst.
\ But first release any resources associated with VarDst.
\ VARSRC    Pointer at the source Variant
\ VARDST    Pointer at the destination Variant
\ --
\ No output parameters

 help_pos var.move
\ ( VarSrc, VarDst  --)
\ Move the contents of the VARIANT pointed at by VarSrc to the Variant pointed at by VarDst.
\ But first release any resources associated with VarDst.
\ Afterwards clear VarSrc but do not release any resources from VarSrc
\ VARSRC    Pointer at the source Variant
\ VARDST    Pointer at the destination Variant
\ --
\ No output parameters

 help_pos var.new
\ ( -- Var )
\ Return VAR a pointer to a variant from the internal resources.
\ Initialise it to be free.
\ No input parameters
\ --
\ VAR       Pointer at variant

\ help_pos var.new=vt
\
\ (  --  )
\

 help_pos var@base
\ ( VarSrc -- X )
\ Return the base address of the VARIANT pointed at by VarSrc.
\ IF  VarSrc  is a  ByRef  then it points at the referenced Variant
\ ELSE it returns itself (VarSrc)
\ VARSRC    Pointer at the source Variant
\ --
\ VARBASE   Pointer to the base VARIANT

 help_pos var@type
\ ( VarSrc -- X )
\ Return the TYPE of the VARIANT pointed at by Var.
\ VAR       Pointer at the source Variant
\ --
\ X         Integer giving the TYPE of the variant VAR

 help_pos var=type
\ ( varType ,Var  -- )
\ Set the TYPE of the VARIANT pointed at by Var to be VARTYPE
\ VARTYPE    The type to be assigned to the variant
\ VAR       Pointer at the source Variant
\ --
\ No output parameters

 help_pos var.val=i
\ Create a VARIANT  VAR of  type  VT_I8  containing the value VALUE
\ ( value  --  VAR )
\ VALUE
\ --
\ VAR      VARIANT containing   VALUE

 help_pos var.val=ui
\
\ ( val -- VAR )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the value VAL, an unsigned integer
\ VAL       Vaule to be placed in the variant VAR
\ --
\ VAR       Pointer at variant

 help_pos var.new=i
\ ( val -- VAR )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the value VAL an integer
\ C-ADDR    Address of memory holding a string of characters
\ U         Length of string in characters
\ --
\ VAR       Pointer at variant

 help_pos var.new=ui
\ ( u -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the single precision unsigned integer U
\ U         Single precision unsigned  integer value
 --
\ VAR       Pointer at variant

 help_pos var.val@ui
\
\ ( VAR -- VAL )
\ Extract the 8 byte integer VAL from the variant VAR
\ VAR       Pointer at variant
\ --
\ VAL       8 byte integer

 help_pos var.val@ui
\
\ ( VAR -- VAL )
\ Extract the 8 byte unsigned integer VAL from the variant VAR
\ VAR       Pointer at variant
\ --
\ VAL       8 byte unsigned integer

 help_pos var.val=b
\ ( val , VAR --  )
\ Assign the BOOLEAN VAL to the VARIANT  VAR
\ VAL       Boolean value
\ VAR       Pointer at variant
\ --
\ no output parameters

 help_pos var.new=b
\ ( boolean -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the BOOLEAN value.
\ BOOLEAN   Value to be assigned to the variant
\ --
\ VAR       Pointer at variant

 help_pos var.val@b
\ ( VAR -- BOOLEAN )
\ Read the BOOLEAN value held in the variant VAR
\
\ VAR       Pointer at variant
\ --
\ BOOLEAN   Value read from the variant

 help_pos var.val=s
\
\ ( c-addr , u  -- VAR )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with a characater string.
\ C-ADDR    Address of memory holding a string of characters
\ U         Length of string in characters
\ --
\ VAR       Pointer at variant

 help_pos var.val=l
\
\ (  val , VAR --  )
\ Assign the 8 byte signed integer VAL   to the VARIANT  VAR
\ VAL       Value to be written to the VARIANT VAR
\ VAR       Pointer to the variant to be set
\  --
\ no output parameters

 help_pos var.val=R8
\ ( df , VAR --  )
\ Assign the R8 ( 8 byte floating value) to the VARIANT  VAR
\ Initialise the variant with the double cell floating value DF
\ DF        Double cell floating value
\ VAR       Pointer at variant
\ --
\ no output parameters

 help_pos var.new=l
\ ( highV, lowV -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the double precision integer
\ HIGHV     High word
\ LOWV      Low word
 --
\ VAR       Pointer at variant

 help_pos var.new=ul
\ ( highV, lowV -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the double precision integers
\ HIGHV     High word
\ LOWV      Low word
 --
\ VAR       Pointer at variant

 help_pos var.new=R8
\ ( df -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the double cell floating value DF
\ DF        Double cell floating value
 --
\ VAR       Pointer at variant

 help_pos var.new=bstr
\ ( BSTR -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the Bstring given by BSTR
\ BSTR    Pointer at the string
\ --
\ VAR       Pointer at variant of type BSTR

 help_pos var.new=s
\ ( c-addr, u -- Var )
\ Obtain VAR a pointer to a variant from the internal resources.
\ Initialise the variant with the string given by C-ADDR, U
\ if c-addr is zero, then a VARIANT will be created of the appropriate
\ size with the content set to zeros
\ C-ADDR    Pointer at the string
\ U         Length of string in characters
\ --
\ VAR       Pointer at variant of type BSTR

 help_pos var.auto=link
\ ( vtName , vtResult  -- )
\ Initialise an automation instance of the application identified by
\ the BSTR VARIANT  identified by  vtName, and return the result in the VARIANT identified by vtResult.
\ Is a wrapper for the WIN32 functions:    CLSIDFromProgID   and    CoCreateInstance
\ example of  vtName    for Microsoft Word
\
\    VARIANT   vtBSTR
\    s" Word.Application"     vtBSTR  vt=s
\  Note: instead of the text name, you can use a well formed GUID
\   e.g.
\    s" {00024500-0000-0000-C000-000000000046}"     vtBSTR  vt=s
\  but NO extra spaces with either approaches!
\
\ vtBSTR now contains a VARIANT variable pointing at a BSTR
\
\ VTNAME    Address of a VARIANT structure holding a BSTR identifing the application to be opened
\ VTRESULT  Address of a VARIANT structure to hold the result of the OPEN activity
\ --
\ No output parameters
\           but the VARIANT used for the result should be checked.
\           if result VARIANT type = VT_ERROR    = failure, the associated VARIANT value holds the HRESULT value
\           if result VARIANT type = VT_DISPATCH = okay, the associated VARIANT value holds the DISPATH value of the opened application

 help_pos GetActiveObject
\
\ (  c-addr, u --  DISPATCH )
\ Gets a link to a COM server PROVIDED that it is already active/running
\
\ C-ADDR      Address of character string identifing the wanted server
\ U           Length of character string
\  --
\ DISPATCH    = -1 on error

 help_pos var.auto=open
\  aka  CreateObject
\ ( vtName , vtResult  -- )
\ Initialise an automation instance of the application identified by
\ the VARIANT BSTR identified by  vtName, and return the result in the VARIANT identified by vtResult.
\ Is a wrapper for the WIN32 functions:    CLSIDFromProgID   and    CoCreateInstance
\ example of  vtName    for Microsoft Word
\
\    VARIANT   vtBSTR
\    s" Word.Application"     vtBSTR  vt=s
\  Note: instead of the text name, you can use a well formed GUID
\   e.g.
\    s" {00024500-0000-0000-C000-000000000046}"     vtBSTR  vt=s
\  but NO extra spaces with either approach!
\
\ vtBSTR now contains a VARIANT variable pointing at a BSTR
\
\ VTNAME    Address of a VARIANT structure holding a BSTR identifing the application to be opened
\ VTRESULT  Address of a VARIANT structure to hold the result of the OPEN activity
\ --
\ No output parameters but VTRESULT will hold the result
\           if result VARIANT type = VT_ERROR    = failure, the associated VARIANT value holds the HRESULT value
\           if result VARIANT type = VT_DISPATCH = okay, the associated VARIANT value holds the DISPATH value of the opened application
\
\ Skeletal code to show differences between   var.auto=open  and  var.auto=open2
\   if ( *cp EQU  _TEXT('{') )
\     {
\         hr = CLSIDFromString ( AppName->bstrVal , & clsid ) ;
\     }
\     else
\     {
\         if (SUCCEEDED(hr))
\         {
\             hr = CLSIDFromProgID( AppName->bstrVal, & clsid ) ;
\         }
\     }
\     if (SUCCEEDED(hr))
\     {
\  *      hr = CoCreateInstance( & clsid, NULL, CLSCTX_LOCAL_SERVER, & IID_IDispatch, (void **) &  useIDispatch ) ;
\  *      if (!   SUCCEEDED(hr)  )
\  *      {
\  *          hr = CoCreateInstance( & clsid, NULL, CLSCTX_INPROC_SERVER, & IID_IDispatch, (void **) &  useIDispatch) ;
\  *      }
\     }

 help_pos var.auto=open2
\ ( vtName , vtResult  -- )
\ Initialise an automation instance of the application identified by
\ the VARIANT BSTR identified by  vtName, and return the result in the VARIANT identified by vtResult.
\ Is a wrapper for the WIN32 functions:    CLSIDFromProgID   and    CoCreateInstance
\ example of  vtName    for Microsoft Word
\
\    VARIANT   vtBSTR
\    s" Word.Application"     vtBSTR  vt=s
\        Note: instead of the text name, you can use a well formed GUID
\        e.g.
\          s" {00024500-0000-0000-C000-000000000046}"     vtBSTR  vt=s
\       but NO extra spaces with either approach!
\
\ vtBSTR now contains a VARIANT variable pointing at a BSTR
\
\ VTNAME    Address of a VARIANT structure holding a BSTR identifing the application to be opened
\ VTRESULT  Address of a VARIANT structure to hold the result of the OPEN activity
\ --
\ No output parameters but VTRESULT will hold the result
\           if VTRESULT type = VT_ERROR    = failure, the associated VARIANT value holds the HRESULT value
\           if VTRESULTT type = VT_DISPATCH = okay, the associated VARIANT value holds the DISPATH value of the opened application
\ Skeletal code to show differences between   var.auto=open  and  var.auto=open2
\   if ( *cp EQU  _TEXT('{') )
\     {
\         hr = CLSIDFromString ( AppName->bstrVal , & clsid ) ;
\     }
\     else
\     {
\         if (SUCCEEDED(hr))
\         {
\             hr = CLSIDFromProgID( AppName->bstrVal, & clsid ) ;
\         }
\     }
\     if (SUCCEEDED(hr))
\     {
\         hr = CoCreateInstance( & clsid, NULL, CLSCTX_LOCAL_SERVER, & IID_IDispatch, (void **) &  useIDispatch ) ;
\         if (!   SUCCEEDED(hr)  )
\         {
\  *          hr = CoCreateInstance( & clsid, NULL, CLSCTX_LOCAL_SERVER, & IID_IClassFactory, (void **) &  pCF) ;
\  *          if (SUCCEEDED(hr))
\  *          {
\  *             hr = pCf->lpVtbl->CreateInstance(pCf, NULL, &IID_IDispatch, useIDispatch);
\  *          }
\  *          if (pCf) pCf->lpVtbl->Release(pCf);
\         }
\     }

\ ( [ variant parameter, ] count of variant parameters ,  Variant for RESULT , VARIANT BSTR name of METHOD to be called,  VARIANT DISPATCH , DISPATCH type  -- )
 help_pos objPUTREF
\ refer to    objGET

 help_pos objPUT
\ refer to    objGET

 help_pos objGET
\
\ (  --  )
\ GENERAL regarding COM   aka   OLE     handling.
\ If we have successfully created a COM object instance using   CreateObject  aka  var.auto=open
\ or var.auto=link (to an already running instance)
\ then we can trigger the objects methods and parameters.
\ There are 3 actions: GET, PUT , FUN (function or run)
\
\ \ 1) this code snippet will get access to Excel (if and only if you have Excel installed on you computer!)
\ s" Excel.application"  var.new=s  value varAppName
\ 0  var.new=ui    value varExl
\ varAppName     varExl  var.auto=open
\ varExl   var@type"   type cr
\ 0  var.new=ui    value varResult            \ variant to hold the result
\ \ 2) now we want to set it's VISIBLE PROPERTY = 1   to make the instance visible
    1   var.new=ui                            \ parameter(s) list
\   1                                         \ number of parameters in list
\   varResult                                 \ variant to hold the result
\   s" VISIBLE"  var.new=s                    \ Target Method or Property for the  action
\   varExl                                    \ variant holding the identity of parent OBJECT
\   objPUT                                    \ COM/OLE API that does the action on the METHOD or PROPERTY
\                                             \ always return a VAR result
\   var@type VType_ERROR = .hex cr            \ see if it went wrong
\                                             \ for now assume if okay
\ \ Note: the above structure: pList, pCount, VarRes, Target Method or Property, Parent, ACTION
\ \       for a PUT, and for a function that takes 1 parameter, is the same except for the ACTION.
\ \ In such as case the two actions ( objPUT  and objFUN ) can be replaced by  a  objFUNPUT !
\ \ the called ACTION API will decide whether a PUT or a FUN is appropriate
\
\ \ 3) now let's GET the   VISIBLE PROPERTY
                                              \ empty parameter(s) list
\   0                                         \ number of parameters in list
\   varResult                                 \ variant to hold the result
\   s" VISIBLE"  var.new=s                    \ Target Method or Property for the  action
\   varExl                                    \ variant holding the identity of parent OBJECT
\   objGET                                    \ COM/OLE API that does the action on the METHOD or PROPERTY
\                                             \ always return a VAR result
\   var@type VType_ERROR = .hex cr            \ see if it went wrong
\                                             \ for now assume if okay
\   varResult  var@cell drop .hex

 help_pos objFUN
\ refer to    objGET

 help_pos objFUNGET
\ refer to    objGET

 help_pos objFUNPUT
\ refer to    objGET

 help_pos SafeArray=free
\
\ ( PSA --  )
\
\ PSA       Release all resources associated with te Safe Array PSA
\ --
\ no output parameters

 help_pos SafeArray.copy
\
\ (  inPSA -- newPSA  )
\ Make a copy of a source Safe Array
\
\ inPSA     Address of a Safe Array structure
\ --
\ newPSA    Address of a new Safe Array structure that is a copy of inPSA

 help_pos SafeArrayRedim
\ (  dim , psa     -- hresult )
\ Resize the dimension of the least index (most right) of the Safe Array
\ dim
\ PSA       Address of a Safe Array structure
\ --
\ hresult  = 0 = okay

 help_pos SafeArray.md=new
\ (   dimN , .. dim1 , dimCount, vt_type --  ptr)
\   md   = multi dimensional
\ Creates a N dimensional SAFE ARRAY where  level X is dimensioned by DIMX  by dim, and Variant Type VT_TYPE.
\ Returns the address, PTR, of the created safe arary, or 0 on error.
\ DIMN        Index into n'th dimension of the array
\ ..
\ DIM1        Index into first dimension of the array
\ DIMCOUNT  Number of dimensions
\ VT_TYPE   Variant type of the elements of the Safe Array
\ --
\ PTR       = 0 on Error
\           = address of a memory block containing the Safe Array Descriptor

 help_pos SafeArray=new
\ ( vt_type , dim --  ptr)
\ Creates a one dimensional SAFE ARRAY of dimension , and Variant Type VT_TYPE.
\ Returns the address, PTR, of the created safe arary, or 0 on error.
\ (If you want a multi-dimensional array then see   SafeArray.MD=new )
\
\ VT_TYPE   A VARIANT TYPE defining the content of the ARRAY e.g. VT_I8, VT_BSTR;...
\ DIM       The number of elements to be in the ONE DIMENSIONAL array
\ --
\ PTR       = 0 on Error
\           = address of a memory block containing the Safe Array Descriptor

 help_pos SafeArray.vector=new
\ ( vt_type , dim --  ptr)
\ Creates a one dimensional SAFE ARRAY of dimension , and Variant Type VT_TYPE.
\ Returns the address, PTR, of the created safe arary, or 0 on error.
\ (If you want a multi-dimensional array then see   SafeArray.MD=new )
\
\ VT_TYPE   A VARIANT TYPE defining the content of the ARRAY e.g. VT_I8, VT_BSTR;...
\ DIM       The number of elements to be in the ONE DIMENSIONAL array
\ --
\ PTR       = 0 on Error
\           = address of a memory block containing the Safe Array Descriptor

 help_pos SafeArray@dim
\ Get the number of dimensions of   the SafeArray psa
\ ( psa -- dims  )
\ PSA       Address of a Safe Array structure
\ --
\ DIMS     Numbr of dimensions

 help_pos SafeArray=lbound
\ Set the value of the lower bound to be used when a Safe Array is created.
\ The default value = 0
\ ( lbound  --  )
\
\ LBOUND     lower boundo be used when a Safe Array is created.
\ --
\ no output parameters

 help_pos SafeArray@ele.size
\ Get the size of an element  the SafeArray psa
\ (   psa -- size  )
\ PSA       Address of a Safe Array structure
\ --
\ SIZE       Size of an element in bytes

 help_pos SafeArray@lbound
\ Get the lower bound of the n'th dimension of the SafeArray psa
\ ( dim , psa -- lbound  )
\ DIM       1-based index of wanted dimension
\ PSA       Address of a Safe Array structure
\ --
\ LBOUND    lower bound of the n'th dimension

 help_pos SafeArray@ubound
\ Get the upper bound of the n'th dimension of the SafeArray psa
\ ( dim , psa -- ubound  )
\ DIM       1-based index of wanted dimension
\ PSA       Address of a Safe Array structure
\ --
\ UBOUND    upper bound of the n'th dimension

 help_pos SafeArray@@ele
\ Returns the base address of the array element of the SafeArray as
\ specified by the dimension and indices.
\ (  iIn,...I1 , dim , valueSA , psa -- (value,TRUE)|FALSE )
\ iIn        Index into n'th dimension of the array
\ ..
\ I1        Index into first dimension of the array
\ DIM       Number of dimensions
\ PSA       Address of a Safe Array structure
\ --
\ VALUE     address of the array element
\           VALUE is provided only if  BOOLEAN = TRUE
\ BOOLEAN   0 = failure
\           else okay

 help_pos SafeArray=Access
\ Normally a Safe Array's content is protected.
\ This command sets it to R/W
\ ( psa  --   )
\ PSA       Address of a Safe Array structure
\ --
\ no output parameters

 help_pos SafeArray=UNAccess
\ Normally a Safe Array's content is protected.
\ This command resets it to R/O
\ ( psa  --   )
\ PSA       Address of a Safe Array structure
\ --
\ no output parameters

 help_pos SafeArray@ele
\ Reads a value from a Safe Array element
\ (  iIn,...I1 , dim , valueSA , psa -- ( value,TRUE)|FALSE )
\ iIn        Index into n'th dimension of the array
\ ..
\ I1        Index into first dimension of the array
\ DIM       Number of dimensions
\ VALUESA   Value to added specified element
\ PSA       Address of a Safe Array structure
\ --
\ VALUE     content of specified array element
\           VALUE is provided only if  BOOLEAN = TRUE
\ BOOLEAN   0 = failure
\           else okay

 help_pos vector@ele
\ ( index , vector --  ( value, TRUE) | FALSE )
\ Gets an element from a one dimension safeArray of values (not VARIANTs)
\
\ INDEX          0-based index of wanted array element
\ VECTOR         pointer to the SAFEARRAY descriptor block
\ --
\ either
\ FALSE          on error
\ or
\ VALUE          value of wanted index
\ TRUE           no error

 help_pos SafeArray=pprd
\ (  iIn,...I1 , dim , valueSA , psa -- ( value,TRUE)|FALSE )
\ Add  valueSA  to the current value of the specified Safe Array element, and return
\ the result of the addition.
\ at the array position given by the indices iIn,...I1
\ The code will check the SafeArray to get the number of indices.
\
\ iIn        Index into n'th dimension of the array
\ ..
\ I1        Index into first dimension of the array
\ DIM       Number of dimensions
\ VALUESA   Value to added specified element
\ PSA       Address of a Safe Array structure
\ --
\ VALUE     content of specified array element AFTER addition
\           VALUE is provided only if  BOOLEAN = TRUE
\ BOOLEAN   0 = failure
\           else okay

 help_pos SafeArray=rdpp
\ (  iIn,...I1 , dim , valueSA , psa -- ( value,TRUE)|FALSE )
\ Returns the initial value of the specified Safe Array element, and leave the
\ element with its initial value added to the value   VALUESA .
\ Places the value   VALUESA  in to the Safe Array PSA
\ at the array position given by the indices iIn,...I1
\ The code will check the SafeArray to get the number of indices.
\
\ iIn        Index into n'th dimension of the array
\ ..
\ I1        Index into first dimension of the array
\ DIM       Number of dimensions
\ VALUESA   Value to added specified element
\ PSA       Address of a Safe Array structure
\ --
\ VALUE     content of specified array element BEFORE addition
\           VALUE is provided only if  BOOLEAN = TRUE
\ BOOLEAN   0 = failure
\           else okay

 help_pos SafeArray=ele
\ (  iIn,...I1 , dim , valueSA , psa -- boolean )
\ SET the specified SafeArray element to the value  VALUESA.
\ Places the value   VALUESA  in to the Safe Array PSA
\ at the array position given by the indices iIn,...I1
\ The code will check the SafeArray to get the number of indices.
\
\ iIn       Index into n'th dimension of the array
\ ..
\ I1        Index into first dimension of the array
\ DIM       Number of dimensions
\ VALUESA   Value to be set in the specified element
\ PSA       Address of a Safe Array structure
\ --
\ BOOLEAN   0 = failure
\           else okay

 help_pos vtDebug
\ Sets the value of the internal vtDebug flag
\ (  --  u )
\ U       Value to be given to the internal vtDebug flag
\ --
\ no output parameters

 help_pos sizeof(variant)
\ Returns the size of a VARIANT structure
\ (  --  u )
\ no input parameters
\ --
\ U         Size of a VARIANT structure in bytes

 help_pos var=fixed
\ Sets the value of the    wReserved1   field of a VARIANT at the location VAR to 1
\ ( var --  )
\ VAR      Address of a VARIANT structure
\ --
\ no output parameters

 help_pos var=unfixed
\ Sets the value of the    wReserved1   field of a VARIANT at the location VAR to 0
\ ( var --  )
\ VAR      Address of a VARIANT structure
\ --
\ no output parameters

 help_pos var@fixed
\ Returns the value of the    wReserved1   field of a VARIANT at the location VAR
\ ( var  -- wReserved1 )
\ VAR      Address of a VARIANT structure
\ --
\ wReserved1

 help_pos SysDiskSerialNumber
\
\ Internally uses COM techniques similar to:
\ dim sysDriveLetter =  left(Environ("systemdrive"),1)
\ dim fso = createObject ("Scripting.FileSystemObject")
\ dim SrNbr =  = fso.drives.item(  sysDriveLetter   ).serialnumber
\ (  -- c-addr, u )
\ no input parameters
\ --
\ C-ADDR    Character string address of the Serial number
\ U         Length of character string

 help_pos get-MachineGuid
\ Access the computers  REGISTRY to ge the value of
\   "HKLM\\SOFTWARE\\Microsoft\\Cryptography\\MachineGuid"
\ Internally uses COM techniques
\ dim wss  = createObject ("WScript.Shell")
\ dim MachineGuid = wss.RegRead ( "HKLM\\SOFTWARE\\Microsoft\\Cryptography\\MachineGuid" )
\ (  --  c-addr , u  )
\
\ no input parameters
\  --
\ C-ADDR    Character string address of the MachineGuid
\ U         Length of character string

    [then]
  ' str>b64 [if]
 help_pos str>b64
\ c-addrI, uI -- c-addrO, uO|-1)
\ Convert a character array in to a Binary 64 array
\ C-ADDRI    Start address of character array to be converted
\ U1         Maximum length of data to be read
\ --
\ C-ADDRO    Start address of BYTE array to be converted
\ UI         Length of binary 64 array in bytes
\            = -1 on error

 help_0pos b64>str
\ (b-addrI, uI -- c-addrO, uO|-1)
\ Convert  Binary 64 array in to  BYTE array
\   return u2 = number of BYTES read in, ior = 0
\   else   u2 = indeterminate, ior = -1
\ B-ADDRI    Start address of Binary 64 array to be converted
\ U1         Maximum length of data to be read
\ --
\ B-ADDRO    Start address of BYTE array
\ UI         Length of BYTE array in bytes
\            = -1 on error

 help_pos barray>hex
\ (b-addrI, uI -- c-addrO, uO|-1)
\ Convert a BYTE array in to a Binary 64 array
\   return u2 = number of BYTES read in, ior = 0
\   else   u2 = indeterminate, ior = -1
\ B-ADDRI    Start address of BYTE array to be converted
\ U1         Maximum length of data to be read
\ --
\ B-ADDRO    Start address of BYTE array to be converted
\ UI         Length of binary 64 array in bytes
\            = -1 on error

\ help_pos hex>barray
\ (b-addrI, uI -- c-addrO, uO|-1)
\ Convert a BYTE array in to a Binary 64 array
\   return u2 = number of BYTES read in, ior = 0
\   else   u2 = indeterminate, ior = -1
\ B-ADDRI    Start address of BYTE array to be converted
\ U1         Maximum length of data to be read
\ --
\ B-ADDRO    Start address of BYTE array to be converted
\ UI         Length of binary 64 array in bytes
\            = -1 on error

    [then]
  ' enum [if]
 help_pos struct.value.ptr
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.ptr  mike         // append to the current structure an element
\
\   Mike then behaves as a VALUE which can hold a POINTER value,
\   (= a cell sized value)
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.int
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.int  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a INTEGER sized value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.byte
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.byte  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a BYTE sized value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.char
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.char  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a CHARACTER value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.word
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.word  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a WORD value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.dword
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.dword  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a DWORD value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.qword
\ ( -- )
\ Used in the form:
\    structVal fred                // creates an empty structure called FRED
\    struct.value.qword  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a QWORD value
\
\ No input parameters
\ --
\ No output parameters

 help_pos struct.value.cell
\ ( -- )
\ Used in the form:
\    struct fred                     // creates an empty structure called FRED
\    struct.value.cell  mike         // append to the current structure an element
\
\   Mike then behaves as a  VALUE which can only hold a CELL value
\
\ No input parameters
\ --
\ No output parameters

 help_pos enum
\ (--)
\ used in the form
\    8 enum=new   red
\      enum       blue
\      enum       green
\ Create a constant whose value is 1 higher than the last use of ENUM.
\ The based address of the ENUM is defined by   ENUM=NEW
\ So in this example it will create constants   RED  BLUE and GREEN with
\ the values 8, 9 and  10t respectively.
\ No input parameters
\ --
\ No output parameters

 help_pos enum=new
\ (x --)
\ used in the form
\    8 enum=new   red
\      enum       blue
\      enum       green
\ Define the first constant in a sequence of constants.
\ The based address of the ENUM is defined by   ENUM=NEW
\ So in this example it will create constants   RED  BLUE and GREEN with
\ the values 8, 9 and  10t respectively.
\
\ x          The integer to be used for the first constant in an ENUM seqeuence
\ --
\ No output parameters

 help_pos struct.bytes
\ (x --)
\ Creates an new element in the current structure (either structVal or structVar), that
\ will hold  X  bytes.
\
\ Used in the form:
\    struct fred                // creates an empty structure called FRED
\    5    struct.bytes    mike         // append to the current structure an element
\                               // called MIKE big enough to hold 5 bytes
\
\    2    struct.bytes   jane         // append to the current structure an element
\                               // called JANE big enough to hold 2 bytes
\
\    struct.align               // Pad the current structure so that the
\
\    mike behaves as a VARIABLE i.e. it is the ADDRESS of the data area
\
\ X          Size in address units (bytes)
\ --
\ No output parameters

 help_pos struct.align
\ (--)
\ Force the next    STRUCT   element to be on a CELL aligned address
\ i.e. the next  SIZEOF will be CELL aligned in memory
\ See   sizeof
\ No input parameters
\ --
\ No output parameters

 help_pos sizeof(struct)
\ (-- x)
\ Returns the total number of address units required by the
\ elements in the last created STRUCT
\
\ No input parameters
\ --
\ x          Size of last created STRUCT in address units (bytes)

 help_pos sizeof(struct.element)
\ (-- x)
\ Return the size of the last created element in the current STRUCT
\ in address units
\
\ No input parameters
\ --
\ x          Size of last element in current STRUCT

 help_pos struct.element@add
\ (-- addr)
\ Return the address of the data field of the last accessed structure element
\
\ No input parameters
\ --
\ x          Address of the data field of the last accessed structure element

 help_pos struct.element@ncfa
\ (-- c-addr, u)
\ Return the address C-ADDR and U length in characters
\ of the name field of the last accessed STRUCT  element
\
\ No input parameters
\ --
\ x          Address of the data field of last accessed element
\            in the current STRUCT

 help_pos structVar
\ (--)
\ Starts a structure definition where the base of the structure (in following example  FRED )
\ behaves as a   VARIABLE
\ Used in the form:
\    struct fred                // creates an empty structure called FRED
\    5    sizeof   mike         // append to the current structure an element
\                               // called MIKE big enough to hold 5 bytes
\
\    2    sizeof   jane         // append to the current structure an element
\                               // called JANE big enough to hold 2 bytes
\
\    struct.align               // Pad the current structure so that the
\                               // next   SIZEOF is CELL aligned in memory
\
\    sizeof(dword) sizeof john  // append to the current structure an element
\                               // called JOHN big enough to hold a DWORD
\
\    struct.align               // Pad the current structure so that the
\                               // next   SIZEOF is CELL aligned in memory
\
\    sizeof(word) struct.bytes jake   // append to the current structure an element
\                               // called JAKE big enough to hold a WORD
\
\   pad      FRED  !            // places the structure over the memory area  PAD
\
\ No input parameters
\ --
\ No output parameters

 help_pos structVal
\ (--)
\ Starts a structure definition where the base of the structure (in following example  FRED )
\ behaves as a   VALUE
\ Used in the form:
\    structVal  fred            // creates an empty structure called FRED
\    5    sizeof   mike         // append to the current structure an element
\                               // called MIKE big enough to hold 5 bytes
\
\    2    sizeof   jane         // append to the current structure an element
\                               // called JANE big enough to hold 2 bytes
\
\    struct.align               // Pad the current structure so that the
\                               // next   SIZEOF is CELL aligned in memory
\
\    sizeof(dword) sizeof john  // append to the current structure an element
\                               // called JOHN big enough to hold a DWORD
\
\    struct.align               // Pad the current structure so that the
\                               // next   SIZEOF is CELL aligned in memory
\
\    sizeof(word) struct.bytes jake   // append to the current structure an element
\                               // called JAKE big enough to hold a WORD
\
\   pad  to   FRED             // places the structure over the memory area  PAD
\
\ No input parameters
\ --
\ No output parameters

   [THEN]
  ' ??canvas  [if]
 help_pos canvas=new.istream
\ (Variant(iStream)  -- u-canvas)
\ Create a canvas from an iStream held in a VARIANT
\ Special definition for use with COM objects that use iStreams
\ ISTREAM  = address of a byte array
\ --
\ U-canvas    Identity of created canvas
\             = 0 on error

\ (c-addr, u -- u-canvas)
\ Create a canvas from the image file (bmp/jpg/jpeg/gif) specified by the character string at
\ address c-addr of length U.
\ C-ADDR   Character string at address, the  file name
\ U        Length of character string
\ --
\ U-canvas    Identity of created canvas
\             = 0 on error
 help_pos canvas=new.file
\ (c-addr, u -- u-canvas)
\ Create a canvas from the image file (bmp/jpg/jpeg/gif) specified by the character string at
\ address c-addr of length U.
\ C-ADDR   Character string at address, the  file name
\ U        Length of character string
\ --
\ U-canvas    Identity of created canvas
\             = 0 on error

 help_pos canvas.from.64hash
\ ( hash -- Canvas)
\ Create a 8x8 canvas based on the 64bit  hash value
\ UINT      hash 64bit
\ --
\ U-CANVAS   canvas

 help_pos  phash.from.32x32.grayscale.canvas
\ ( uCanvas -- uint)
\ Create a preceptual hash from the canvas specified by   UCANVAS
\ address c-addr of length U.
\ U-CANVAS   canvas
\ --
\ UINT      phash 64bit

 help_pos  dhash.from.canvas
\ ( uCanvas -- uint)
\ Create a differential hash from the canvas specified by   UCANVAS
\ address c-addr of length U.
\ Techie note: uses StretchBlt with  HALFTONE  handling,
\ U-CANVAS   canvas
\ --
\ UINT      dhash 64bit

 help_pos  phash.from.canvas
\ ( uCanvas -- uint)
\ Create a preceptual hash from the canvas specified by   UCANVAS
\ address c-addr of length U.
\ Techie note: uses StretchBlt with  HALFTONE  handling,
\ U-CANVAS   canvas
\ --
\ UINT      phash 64bit

 help_pos canvas=new.iPic
\ (   c-addr, u -- uCanvas)
\ Create a CANVAS from a image file.
\ Internally uses   OleLoadPicturePath  and   IPICTURE rendering
\ C-ADDR   Character string at address, the  file name
\ U        Length of character string
\ --
\ U-canvas

 help_pos canvas=free
\ (u-canvas --)
\ Release all resources associated with the canvas u-canvas
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas=free.all
\ ( --)
\ Release all resources associated with ALL canvases
\ No input parameters
\ --
\ No output parameters

 help_pos canvas=clear
\ (u-canvas --)
\ Clear the canvas u-canvas. Set all pixels to WHITE
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas>halftone
\ ( HalfTone ,u-canvas --   )
\ Sets a flag controlling whether  Halftone handling in StretchBlt operations is disabled
\ HalfTone    = 0 allowed
\             else allowed
\ U-canvas    Identity of target canvas
\ --
\ no output parameters

 help_pos canvas@halftone
\ ( u-canvas -- HalfTone )
\ Returns a flag showing if Halftone handling in StretchBlt operations is disabled
\ U-canvas    Identity of target canvas
\ --
\ HalfTone    = 0 allowed
\             else allowed

 help_pos canvas@wh
\ (u-canvas -- w, h)
\ Returns the maximum height and width of the canvas identified by U-canvas
\ U-canvas    Identity of canvas
\ --
\ W        Width of bitmap in pixels
\          = 0 on error
\ H        Height of bitmap in pixels
\          = 0 on error

 help_pos canvas@hdc
\ ( u-canvas -- DC )
\ Returns the handle of the  device context
\ canvas identified by u-canvas
\ U-canvas    Identity of target canvas
\ --
\ hDC         handle of the  device context
\             = 0 on error

 help_pos canvas@hbm
\ ( u-canvas -- DC )
\ Returns the handle of the  Bitmap in the
\ canvas identified by u-canvas
\ U-canvas    Identity of target canvas
\ --
\ hDC         handle of the  Bitmap
\             = 0 on error

 help_pos canvas@data
\ (  u-canvas -- ptr to DIB data)
\ Returns a pointer to the first byte of the colour data area.
\ on the canvas identified by u-canvas
\ U-canvas    Identity of target canvas
\ --
\ PTR         Address of first byte of the PIXEL data of the specified canvas
\             = 0 on error

 help_pos canvas@validate
\ (  u-canvas -- 0 || u-canvas )
\ Checks whether the canvas specified by  U-CANVAS  is valid.
\ U-CANVAS    Identity of target canvas
\ --
\ U-CANVAS     if VALID
\              else 0

 help_pos canvas@stride
\ (  u-canvas -- u )
\ Returns the number of bytes of colour data information
\ between two vertially adjacent pixels
\ on the canvas identified by u-canvas
\ U-canvas    Identity of target canvas
\ --
\ U           Number of bytes
\             = 0 on error

 help_pos canvas>copy
\ (--)
\ Set the next canvas=canvas operation to cause the
\ source canvas to be copied on to the destination canvas
\ Under such a transfer, the src canvas is unaffected
\ No input parameters
\ --
\ No output parameters

 help_pos canvas>and
\ (--)
\ Set the next canvas=canvas operation to cause the
\ source canvas to be AND'd with the destination canvas
\ Under such a transfer, the src canvas is unaffected
\ No input parameters
\ --
\ No output parameters

 help_pos canvas>or
\ (--)
\ Set the next canvas=canvas operation to cause the
\ source canvas to be OR'd with the destination canvas
\ Under such a transfer, the src canvas is unaffected
\ No input parameters
\ --
\ No output parameters

 help_pos canvas>xor
\ (--)
\ Set the next canvas=canvas operation to cause the
\ source canvas to be XOR'd with the destination canvas
\ Under such a transfer, the src canvas is unaffected
\ No input parameters
\ --
\ No output parameters

 help_pos canvas>invert
\ (--)
\ Set the next canvas=canvas operation to cause the inverse of
\ the source canvas.
\ No input parameters
\ --
\ No output parameters

 help_pos canvas>user
\ (u --)
\ Set the next canvas=canvas operation to be the user defined value u.
\ Bypasses the commands:
\    canvas>invert, canvas>xor , canvas>or , canvas>and , canvas>copy
\ U       A user defined transfer code. Refer to
\         Microsoft documentation and the BITBLT / StretchBlt  operations
\ --
\ No output parameters

 help_pos canvas@pixel
\ (ux, uy , u-canvas -- u-col)
\ Obtain the colour code of the pixel at the co-ordinates (ux, xy)
\ on the canvas identified by u-canvas
\ UX       X co-ordinate of the pixel to be read
\ UY       Y co-ordinate of the pixel to be read
\ U-canvas    Identity of target canvas
\ --
\ U-COL    Colour value of pixel at (ux, uy) on canvas u-canvas

 help_pos canvas=updateable
\ (boolean,  u-canvas --)
\ Set whether changes to a CANVAS, that has been assigned to a Screen Object,
\ are automatically made visible within that Screen Object.
\ BOOLEAN   0 = changes not automatically visible
\           else = visible
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas=pixel
\ (u-col, ux, uy, u-canvas --)
\ Set the colour code u-col of the pixel at the co-ordinates (ux, xy)
\ on the canvas identified by u-canvas
\ U-COL    Colour value of pixel at (ux, uy) on canvas u-canvas
\ UX       X co-ordinate of the pixel to be read
\ UY       Y co-ordinate of the pixel to be read
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas=flood
\ ( rgb, u-canvas -- )
\ Set all pixels in the canvas  U-CANVAS to the 32 bit value (transparency, red, blue, green)
\ given by   RGB
\ RGB         Colour value to be flooded into the canvas
\ U-canvas    Identity of target canvas (see canvas-col & canvas.mono)
\ --
\ No output parameters

 help_pos canvas=region
\ (x, y, w, h ,  rgb, u-canvas -- )
\ Set all pixels in the canvas  U-CANVAS to the 32 bit value (transparency, red, blue, green)
\ given by   RGB
\ RGB         Colour value to be flooded into the canvas
\ U-canvas    Identity of target canvas (see canvas-col & canvas.mono)
\ --
\ No output parameters

 help_pos canvas>grayscale
\ (  u-canvas -- )
\ Convert all pixels in the canvas  U-CANVAS to grayscale
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas>grayscale.hc
\ (  u-canvas -- )
\ Convert all pixels in the canvas  U-CANVAS to high contrast grayscale
\ Gray values are mapped to occupy the full range 0..255
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas.grayscale>monochrome
\ ( g-canvas --  )
\ Convert a grayscale canvas to simple black and white
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas>grayscale.histogram
\ (  g-canvas -- h-canvas )
\ Convert all pixels in the canvas  U-CANVAS to grayscale
\ U-canvas    Identity of target canvas
\ --
\ No output parameters

 help_pos canvas.draw.line.from
\ (x1, y1, CanvasId --)
\ Mark the start of a line at (x1 , y1)
\ on the canvas identified by CanvasId. Refer to  canvas.draw.line.to
\ X1       X co-ordinate of the start of a line
\ Y1       Y co-ordinate of the start of a line
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.line.shift.to
\ (w, h, CanvasId --)
\ Move from the last LINE position  (x1 , y1) to (x1 + w , y1 + h)
\ on the canvas identified by CanvasId. Refer to  canvas.draw.line.from
\ W        the ammount by which the previuos X co-ordinate is changed
\ H        the ammount by which the previuos Y co-ordinate is changed
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.line.to
\ (x1, y1, CanvasId --)
\ Mark the end of a line at (x1 , y1)
\ on the canvas identified by CanvasId. Refer to  canvas.draw.line.from
\ X1       X co-ordinate of the end point of a line
\ Y1       Y co-ordinate of the end point of aline
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.triangle
\ ( x1,y1  , x2,y2   , x3,y3  ,CanvasId --)
\ Draw a filled
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.polygon
\ ( CanvasId --)
\ Finalise a set of
\ X1       X co-ordinate of the next point of the multi-point line
\ Y1       Y co-ordinate of the next point of the multi-point line
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.polyline
\ (addr, count, CanvasId --)
\ Draw a polyline based on the array of  (x,y) values starting at  ADDR.
\ The number of points in the array is COUNT
\ on the canvas identified by CanvasId.
\ ADDR     Start address of an array of co-ordinates (X,Y)
\ COUNT    number of points in the array
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.line
\ (x1, y1, x2, y2 , CanvasId --)
\ Draw a line from (x1 , y1) to (x2, y2)
\ on the canvas identified by CanvasId
\ X1       X co-ordinate of the start of the line
\ Y1       Y co-ordinate of the start of the line
\ X2       X co-ordinate of the end of the line
\ Y2       Y co-ordinate of the end of the line
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.rectangle
\ ( x, y, w, h , CanvasId --)
\ Draw a rectangle with the top/left coordinates (x1 , y1) of width w and height h
\ on the canvas identified by CanvasId
\ (x, y, width, height --)
\ Draw a rectangle with the top/left coordinates (x1 , y1) and finishing at X+WIDTH , Y+HEIGHT
\ X        X co-ordinate of the top left corner of a rectangle
\ Y        Y co-ordinate of the top left corner of a rectangle
\ WIDTH    horizontal size of rectangle
\ HEIGHT   vertical size of rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.rectangle.rounded
\ ( x, y, w, h , CanvasId --)
\ Draw a rounded rectangle with the top/left coordinates (x1 , y1) of width w and height h
\ on the canvas identified by CanvasId
\ (x, y, width, height --)
\ Draw a rectangle with the top/left coordinates (x1 , y1) and finishing at X+WIDTH , Y+HEIGHT
\ X        X co-ordinate of the top left corner of a rectangle
\ Y        Y co-ordinate of the top left corner of a rectangle
\ WIDTH    horizontal size of rectangle
\ HEIGHT   vertical size of rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.circle
\ (x1 , y1, width, height , CanvasId --)
\ Draw a circle with the top/left coordinates (x1 , y1) of width w and height h
\ on the canvas identified by CanvasId
\ (x, y, width, height , CanvasId --)
\ Draw a rectangle with the top/left coordinates (x1 , y1) and finishing at X+WIDTH , Y+HEIGHT
\ X1       X co-ordinate of the top left corner of a rectangle
\ Y1       Y co-ordinate of the top left corner of a rectangle
\ WIDTH    horizontal size of rectangle
\ HEIGHT   vertical size of rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.pie.radial
\ ( offset , angle ,   radius , x1 , y1,  CanvasId -- )
\ Draw a pie (circle) with an optional slice cut out
\ Circle defined by its  center point and radius
\ Center of circle     coordinates (x1 , y1)
\ Radius of circle     radius
\ Size of segment in degrees
\ Drawn on the canvas identified by CanvasId
\ OFFSET  of the pie's   circumference's mid point from midnight in degrees
\ SEGMENT  visible arc of pie in degrees,    0 degrees = midnight
\                                            45 degrees = midnight  +-  3.75 mins
\                                            90 degrees = midnight  +-  7.5  mins
\                                           180 degrees = midnight  +- 15    mins
\ RADIUS   radius of circle
\ X1       X co-ordinate of the center of the circle
\ Y1       Y co-ordinate of the center of the circle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.circle.radial.filled
\ (  radius , x1 , y1,  CanvasId --)
\ Draw  a circle defined by center point and radius!
\ Center of "circle"     coordinates (x1 , y1)
\ Radius of "circle"     radius
\ Size of segment in degrees
\ Drawn on the canvas identified by CanvasId
\ RADIUS   radius of circle
\ X1       X co-ordinate of the center of the circle
\ Y1       Y co-ordinate of the center of the circle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.circle.radial.segment
\ ( offset , angle , radius , x1 , y1,  CanvasId --)
\ Draw an arc of a circle.
\ Center of "circle"     coordinates (x1 , y1)
\ Radius of "circle"     radius
\ Size of segment in degrees
\ Drawn on the canvas identified by CanvasId
\ Is NOT filled, draw using current PEN
\ OFFSET  of arc's mid point from midnight in degrees
\ SEGMENT  visible arc of segment in degrees, 0 degrees = midnight
\                                            45 degrees = midnight  +-  3.75 mins
\                                            90 degrees = midnight  +-  7.5  mins
\                                           180 degrees = midnight  +- 15    mins
\ RADIUS   radius of circle
\ X1       X co-ordinate of the center of the circle
\ Y1       Y co-ordinate of the center of the circle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_0pos canvas.draw.circle.segment
\ ( angle ,   radius , x1 , y1,  CanvasId --)
\ Draw a segment of a circle.
\ Center of "circle"     coordinates (x1 , y1)
\ Radius of "circle"     radius
\ Size of segment in degrees
\ Drawn on the canvas identified by CanvasId
\ SEGMENT  visible arc of segment in degrees, 0 degrees = midnight
\                                            45 degrees = midnight  +-  3.75 mins
\                                            90 degrees = midnight  +-  7.5  mins
\                                           180 degrees = midnight  +- 15    mins
\ RADIUS   radius of circle
\ X1       X co-ordinate of the center of the circle
\ Y1       Y co-ordinate of the center of the circle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.circle.filled
\ (x1 , y1, width, height , CanvasId --)
\ Draw a circle with the top/left coordinates (x1 , y1) of width w and height h
\ on the canvas identified by CanvasId
\ (x, y, width, height --)
\ Draw a rectangle with the top/left coordinates (x1 , y1) and finishing at X+WIDTH , Y+HEIGHT
\ X1       X co-ordinate of the top left corner of a rectangle
\ Y1       Y co-ordinate of the top left corner of a rectangle
\ WIDTH    horizontal size of rectangle
\ HEIGHT   vertical size of rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text
\ (c-add, u , x1 , y1 , CanvasId --)
\ Draw the text string ( ca-ddr,u) at the top/left coordinates (x1 , y1)
\ on the canvas identified by CanvasId
\ C-ADDR   address of character string
\ U        length of charater string in characters
\ X1       X co-ordinate of the top left corner of a rectangle
\ Y1       Y co-ordinate of the top left corner of a rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text.size
\ (c-add, u , CanvasId --   w,h )
\ Get the size of  the text string ( ca-ddr,u) in pixels (w,h)
\ if it were rendered on the canvas identified by CanvasId
\ C-ADDR   address of character string
\ U        length of charater string in characters
\ CANVASID identity of the target canvas
\ --
\ W        width of text field
\ W        height of text field

 help_pos canvas.draw.text.font
\ (font ,  CanvasId --)
\ Define how future text is to be displayed relative to the (X,Y) co-ordinates
\ supplied with that text!
\ FONT       handle of new FONT
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text.align
\ (x ,  CanvasId --)
\ Define how future text is to be displayed relative to the (X,Y) co-ordinates
\ supplied with that text!
\ TA_NOUPDATECP    0
\ TA_UPDATECP      1
\ TA_LEFT                      0
\ TA_CENTER                    6
\ TA_RIGHT                     2
\ TA_TOP                       0
\ TA_BOTTOM                    8
\ TA_BASELINE                  24
\ TA_RTLREADING                256
\ Wrapper for Windows SetTextAlign function (wingdi.h)
\ X        X co-ordinate of the top left corner of a rectangle
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text.rgb
\ (rgb ,  CanvasId --)
\ Set the colour used for future   canvas.draw.text   commands
\ Wrapper for Windows SetTextColor function (wingdi.h)
\ RGB      RGB value
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text.bk.rgb
\ (rgb ,  CanvasId --)
\ Set the colour used for the background of future   canvas.draw.text   commands
\ Wrapper for Windows SetBkColor function (wingdi.h)
\ RGB      RGB value
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.draw.text.bk.mode
\ (mode ,  CanvasId --)
\ Set the colour used for the background of future   canvas.draw.text   commands
\ Wrapper for Windows SetBkColor function (wingdi.h)
\ MODE     TRANSPARENT = 1. OPAQUE = 2
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.pen@rgb
\ ( CanvasId -- RGB)
\ Get the colour used in current  PEN actions
\ on the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ RGB      colour

 help_pos canvas.pen@width
\ ( CanvasId -- width)
\ Get the width used in current  PEN actions
\ on the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ WIDTH

 help_pos canvas.pen@style
\ ( CanvasId -- style)
\ Get the style used in current  PEN actions
\ on the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ STYLE    0 solid,  1 dash  , 2 dot, 3 dash dot, 4 dash dot dot, , 5 null
\          else:  refer to Microsoft documentation on  PenStyle Enumeration

 help_pos canvas.pen.rgb
\ ( RGB,  CanvasId -- )
\ Change the colour used in future PEN actions
\ on the canvas identified by CanvasId
\ RGB      colour
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.pen.width
\ ( width,  CanvasId --)
\ Change the pen width used in future PEN actions
\ on the canvas identified by CanvasId
\ WIDTH
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.pen.style
\ ( style,  CanvasId --)
\ Change the pen style used in future PEN actions
\ on the canvas identified by CanvasId
\ STYLE    0 solid,  1 dash  , 2 dot, 3 dash dot, 4 dash dot dot, , 5 null
\          6  InsideFrame
\          else:  refer to Microsoft documentation on  PenStyle Enumeration
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.brush.hollow
\ (   CanvasId --)
\ Change the brush style used in future BRUSH actions
\ on the canvas identified by CanvasId to be a black line with hollow/transparent fill
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.brush@style
\ ( CanvasId -- STYLE )
\ Get the current STYLE applicable to
\ the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ STYLE    0 solid,  1 null  , 2 hatch
\          else:  refer to Microsoft documentation on  BrushStyle Enumeration

 help_pos canvas.brush@hatch
\ ( CanvasId -- HATCH )
\ Change the colour used in current BRUSH actions
\ on the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ HATCH    0 horizontal,  1 vertical  , 2 forward diagonal, 3 backward diagonal
\          4 = horiz AND vert   ,   5 = forward AND backward diagonal
\          refer to Microsoft documentation on  BrushHatch Enumeration

 help_pos canvas.brush@rgb
\ ( CanvasId -- RGB )
\ Get the colour used in current BRUSH actions
\ on the canvas identified by CanvasId
\ CANVASID identity of the target canvas
\ --
\ RGB      colour

 help_pos canvas.brush.rgb
\ ( RGB,  CanvasId --)
\ Change the colour used in future BRUSH actions
\ on the canvas identified by CanvasId
\ RGB      colour
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.brush.hatch
\ ( width,  CanvasId --)
\ Change the brush hatch used in future BRUSH actions
\ on the canvas identified by CanvasId
\ HATCH    0 horizontal,  1 vertical  , 2 forward diagonal, 3 backward diagonal
\          4 = horiz AND vert   ,   5 = forward AND backward diagonal
\          refer to Microsoft documentation on  BrushHatch Enumeration
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas.brush.style
\ ( style,  CanvasId --)
\ Change the brush style used in future BRUSH actions
\ on the canvas identified by CanvasId
\ STYLE    0 solid,  1 null  , 2 hatch
\          else:  refer to Microsoft documentation on  BrushStyle Enumeration
\ CANVASID identity of the target canvas
\ --
\ No output parameters

 help_pos canvas=new
\ ( -- u-canvas)
\ Create an empty (black) canvas dimensioned to the default screen.
\
\ No input parameters
\ --
\ U-canvas    Identity of created canvas
\             = 0 on error

 help_pos canvas=new.custom
\ (w, h, -- u-canvas)
\ Create an empty (black) canvas dimensioned to the user provided H height and W width (in pixels)
\ W        width of target canvas
\ H        heigth of target canvas
\ --
\ U-canvas    Identity of created canvas
\             = 0 on error

 help_pos canvas=clone
\ (Orig-canvas -- Clone-canvas)
\ Create a clone of the original canvas
\ ORIG-CANVAS     Identity of original canvas
\ --
\ CLOSE-CANVAS    Identity of clone canvas
\                 = 0 on error

 help_pos Transcanvas=canvas
\ (TransRGB , x1, y1, w1, y1, u-canvas1, x2, y2, w2, h2, u-canvas2 --)
\ Transfer the region of the canvas u-canvas1
\ starting at (x1, y1) and of width w1 and height h1
\ to the region of the canvas u-canvas2
\ starting at (x2, y2) and of width w2 and height h2
\ The type of transfer is taken from the last value
\ provided by canvas>user  (default = copy src to dst )
\ Note: SRC & DST rectangles can be different sizes,
\ a stretch/shrink operation is used.
\ X1,Y1    Start co-ord in the SRC canvas
\ W1,H1    Width and Height of SRC rectangle
\ U-canvas1   Identity of SRC canvas
\ X2,Y2    Start co-ord in the DST canvas
\ W2,H2    Width and Height of DST rectangle
\ U-canvas2   Identity of SRC canvas
\ X2,Y2    Start co-ord in the DST canvas
\ U-canvas    Identity of source canvas
\ --
\ No output parameters

 help_pos canvas=canvas
\ (x1, y1, w1, y1, srcCanvas , x2, y2, w2, h2, dstCanvas -- )
\ Transfer the region of the canvas srcCanvas
\ starting at (x1, y1) and of width w1 and height h1
\ to the region of the canvas dstCanvas
\ starting at (x2, y2) and of width w2 and height h2
\ The type of transfer is taken from the last value
\ provided by canvas>user  (default = copy src to dst )
\ The internal StretchBlt operation will include halftone handling based
\ on the srcCanvas internal halftone flag set/cleared by the command   canvas>halftone
\ Note: SRC & DST rectangles can be different sizes,
\ a stretch/shrink operation is used.
\ X1,Y1      Start co-ord in the srcCanvas
\ W1,H1      Width and Height of srcCanvas rectangle
\ SRCCANVAS  Identity of srcCanvas canvas
\ X2,Y2      Start co-ord in the dstCanvas canvas
\ W2,H2      Width and Height of dstCanvas rectangle
\ DSTCANVAS  Identity of dstCanvas canvas
\ X2,Y2    Start co-ord in the DST canvas
\ U-canvas    Identity of source canvas
\ --
\ No output parameters

 help_pos canvas.rotate
\ ( rotation , srcCanvas  -- newCanvas)
\ Creates a new CANVAS  NEWCANVAS  which is equal to the input CANVAS SRCCANVAS
\ rotated ROTATION degrees (must be one of: 0 , 90, 180, 270)
\
\ rotation     ROTATION in degrees (must be one of: 0 , 90, 180, 270), else forced to 0
\ srcCanvas    Identity of SRC canvas
\ --
\ newCanvas    Identity of output canvas

 help_pos canvas=canvas.stretch
\ ( dstCanvas , srcCanvas  --  )
\ The source CANVAS  SRCCANVAS is stretched/shrunk to fit the destination CANVAS DSTCANVAS.
\ The operation Creates a new CANVAS  NEWCANVAS  which is equal to the input CANVAS SRCCANVAS
\ rotated ROTATION degrees (must be one of: 0 , 90, 180, 270)
\ The internal StretchBlt operation will include halftone handling based
\ on the srcCanvas internal halftone flag set/cleared by the command   canvas>halftone
\ dstCanvas    Identity of DST canvas
\ srcCanvas    Identity of SRC canvas
\ --
\ no output parameters

 help_pos canvas=canvas.trans
\ (x1, y1, w1, y1, srcCanvas , x2, y2, w2, h2, dstCanvas , TransValue -- )
\
\ Transfer the region of the canvas srcCanvas
\ starting at (x1, y1) and of width w1 and height h1
\ to the region of the canvas dstCanvas
\ starting at (x2, y2) and of width w2 and height h2
\ The type of transfer is taken from the last value
\ provided by canvas>user  (default = copy src to dst )
\ Is a wrapper around the Win32 function   TransparentBlt
\ Note: SRC & DST rectangles can be different sizes,
\ a stretch/shrink operation is used.
\
\ X1,Y1      Start co-ord in the srcCanvas
\ W1,H1      Width and Height of srcCanvas rectangle
\ SRCCANVAS  Identity of srcCanvas canvas
\ X2,Y2      Start co-ord in the dstCanvas canvas
\ W2,H2      Width and Height of dstCanvas rectangle
\ DSTCANVAS  Identity of dstCanvas canvas
\ TRANSVALUE The RGB colour in the SRCCANVAS to be treated as TRANSPARENT
\            i.e. pixel in SRCCANVAS with this value are not transfered to DSTCANVAS
\ --
\ No output parameters

 help_pos canvas=canvas.merge
\ (x1, y1, w1, y1, u-canvasS, x2, y2, w2, h2, u-canvasD , blendvalue -- )
\
\ Transfer the region of the canvas srcCanvas
\ starting at (x1, y1) and of width w1 and height h1
\ to the region of the canvas dstCanvas
\ starting at (x2, y2) and of width w2 and height h2
\ The type of transfer is taken from the last value
\ provided by canvas>user  (default = copy src to dst )
\ Is a wrapper around the Win32 function AlphaBlend
\ Note: SRC & DST rectangles can be different sizes,
\ a stretch/shrink operation is used.
\
\ X1,Y1      Start co-ord in the srcCanvas
\ W1,H1      Width and Height of srcCanvas rectangle
\ SRCCANVAS  Identity of srcCanvas canvas
\ X2,Y2      Start co-ord in the dstCanvas canvas
\ W2,H2      Width and Height of dstCanvas rectangle
\ DSTCANVAS  Identity of dstCanvas canvas
\ BLENDVALUE (masked to 8 bit value) the transparency value
\ --
\ No output parameters

 help_pos canvas>file
\ ( c-addr, u , u-canvas  --  bool )
\ Copy the image held on the CANVAS  U-CANVAS
\ to the file identified by the text given by  C_ADDR, U
\ The file name extension defines the image format:
\          png , jpg , jpeg , tif , bmp , gif
\
\ C-ADDR   Character string at address specifin the destination finename
\ U        Length of filename in characters
\ U-CANVAS    Identity of source canvas
\ --
\ BOOL        0 if error, else okay

 help_pos canvas=icon
\ (handle, u-canvas -- 0|x)
\ Copy the ICON identified by HANDLE to the canvas identified by u-canvas.
\ HANDLE   Identity of the ICON to be copied
\ U-CANVAS    Identity of target canvas (see canvas-col & canvas.mono)
\ --
\ RES      = 0 on success, else error

 help_pos ??canvas
\  (-- )
\ Help information for the CANVAS commands.
\ Think of a CANVAS as a piece of paper that you can draw on with a pen and a brush.
\ You can:
\    create an empty CANVAS or a CANVAS preloaded with from a image file (bmp , gif, tif, jpeg, jpg)
\    draw on a CANVAS with a pen and a brush
\    change the style, width and colour of the pen
\    change the style, hatch and colour of the brush
\    read / write individual pixels
\    modify multi-pixels using drawing commands for lines, circle, elipses, rectanges
\    place text of a canvas
\    move (using various transformations) a part canvas to another canvas
\    save a canvas to an image file  (bmp , gif, tif, jpeg, jpg)
\    display a canvas by placing it into a special Screen Object type  (sob.canvas=new)
\    ...
\ In techie talk a CANVAS is a handle to a Device Context that holds a Device INDEPENDANT Bitmap
\
\ No input parameters
\ --
\ No output parameters

 help_pos sob.graphics.upper=canvas
\ aka     sob.canvas=canvas
\ ( u-canvas , sob-id --p-canvas )
\ Assign the canvas  U-CANVAS to the  Screen OBject SOB-ID.
\ If the  Screen OBject SOB-ID already has a CANVAS  then the old CANVAS is
\  removed from that SOB, but is not deleted.
\ Note: SOB-ID  must have been created by   sob.canvas=new
\ U-CANVAS    Identity of source canvas
\ SOB-ID      Identity of target Screen OBject
\ --
\ P-CANVAS    identity of previous canvas

 help_pos sob>file
\  ( char , u , sobId--  )
\ Copy the screen appearance of the specified Screen OBject
\ to the file with the name  c-addr  u
\ This overwrites any previous contents if the file c-addr count already exists.
\ The format of the file is defined by the extension.
\ Supported extensions are:  BMP, GIF, JPG, JPEG, PNG, TIF
\ C-ADDR    address of a character string - destination file name
\ U         length of character string
\ --
\ no output parameters

 help_pos image.file@wh
\ (c-addr, u --  w, h)
\ Return the width W and height H, in pixels, of the image FILE
\ specified by the character string at address c-addr of length u .
\ C-ADDR   Character string at address. Is the image file name
\ U        Length of character string
\ --
\ W        width in pixels
\ H        height in pixels
\          = -1 if the file could not be opened

 help_pos phash.dhash.from.file
\ (c-addr, u --  w, h)
\ WARNING: does a PHASH   and a DHASH  based on the  image file
\ specified by the character string at address c-addr of length u .
\ C-ADDR   Character string at address. Is the image file name
\ U        Length of character string
\ --
\ DHASH    value
\ PHASH    value
\          = 0 ,0  on error

 help_pos  dhash.from.file
\ (c-addr, u --  d)
\  does a DHASH  based on the  image file
\ specified by the character string at address c-addr of length u .
\ C-ADDR   Character string at address. Is the image file name
\ U        Length of character string
\ --
\ D         DHASH    value

\          = 0    on error

 help_pos phash.from.file
\ (c-addr, u --  p)
\ does a PHASH  based on the  image file
\ specified by the character string at address c-addr of length u .
\ C-ADDR   Character string at address. Is the image file name
\ U        Length of character string
\ --
\ p        PHASH    value
\          = 0  on error

  [then]
  ' cryptChar [if]
 help_0pos cryptChar
\ (uByte, index, start -- eByte)
\ Encrypt the byte value   UBYTE    via the INDEX offset from the start point START.
\ UBYTE        The unencrypted byte
\ INDEX        Index offset from the start point START.
\ START        Start location in the encryption block page
\ --
\ UBYTE        The encrypted byte

 help_0pos DecryptChar
\ (eByte, index, start -- UByte)
\ Encrypt the byte value   UBYTE    via the INDEX offset from the start point START.
\ EBYTE        The encrypted byte
\ INDEX        Index offset from the start point START.
\ START        Start location in the encryption block page
\ --
\ UBYTE        The decrypted byte

    [then]
 help_pos char.type.start
\ (   --  BitMap)
\ Return the BitMap mask for a character which preceeds an expression.  ':'  ,   '{'  , '['  ,'('  , ','
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.stop
\ (   --  BitMap)
\ Return the BitMap mask for a character which terminates an expression.  ':'  ,   '}'  , ']'  ,')'  , ',' , '\0'
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.alpha
\ (   --  BitMap)
\ Return the BitMap mask for ASCII alpha characters  a-z, A-Z
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.whitespace
\ (   --  BitMap)
\ Return the BitMap mask for WHITESPACE characters  0x09 , 0x020
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.special
\ (   --  BitMap)
\ Return the BitMap mask for SPECIAL characters whose meaning is possibly dependant on the
\ token before or after this one in a command line.  0x00 , '+' , '-' , ':' , '0' , '"' ,   '\'
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.numeric
\ (   --  BitMap)
\ Return the BitMap mask for ASCII characters that might be numerical (depending on the current BASE)  0-9 , a-z , A-Z
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.name
\ (   --  BitMap)
\ Return the BitMap mask for characters that are allowed inside a NAME
\ Any  character with a value > 127 ,   ASCII 0-9 , a-z , A-Z , @ , _
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.single.keyword
\ (   --  BitMap)
\ Return the BitMap mask for characters which are single character tokens  ':' , '=' , '"' , '\'
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.maths
\ (   --  BitMap)
\ Return the BitMap mask for ASCII characters  + - / *  <  >   =
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.single.unknown
\ (   --  BitMap)
\ Return the BitMap mask for ASCII characters  0x21 to 0x127  which have no other BitMap mask
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char.type.null
\ (   --  BitMap)
\ Return the BitMap mask for ASCII characters  0x00 to 0x20  which have no other BiMap mask
\ This is the default usage, see also    char=type   char@type
\ No input parameters
\ --
\ MASK              BitMap mask for the target character type

 help_pos char=type
\ ( Mask , CHAR   -- )
\ Clear / modify the BitMap mask for CHAR
\ The internally defined BitMaps have single bit values  0x02,0x04, 0x08,.., 0x0400
\ You can freely define your own values/meanings 0x00800 , 0x01000, ... 0x080000000  ( a 32 bit value)
\ MASK              If 0 then  CHAR has a bitmap mask = 0
\                   else the current bitmap mask for CHAR is  Bitwise ORed with MASK
\ CHAR              The target ASCII character  0x00 - 0x7f
\                   if CHAR > 0x7f then  no action
\ --
\ No output parameters

 help_pos char@type
\ ( char  --  Mask)
\ Return the Bitmap mask associated with the character CHAR
\ Predefined BitMap mask values are
\    char.type.alpha
\    char.type.whitespace
\    char.type.special
\    char.type.numeric
\    char.type.name
\    char.type.single.keyword
\    char.type.maths
\    char.type.single.unknown
\    char.type.null
\ CHAR              character to be evaluated
\ --
\ MASK              Bitmap mask (possible multiple bits!) defining the characterstics of the target character

 help_pos char@numerical.value
\ ( char , base --  ( value , -1) | 0)
\ If CHAR represents a valid numeric in the number base given by BASE
\ then return the  number and -1
\ else return 0
\  So 'c' , 0x016    would return   12 , -1
\     'c' , 0x00a    would return   0
\ CHAR              character to be evaluated
\ BASE              base of target number system typically 10 (decimal) , 16 (hexadecimal),..
\ --
\ (
\   VALUE             numerical value of   CHAR
\   BOOLEAN           -1  if CHAR is numeric
\  )   OR
\   BOOLEAN           0   if CHAR is NOT numeric

 help_pos token2text
\ (  tokenid --  caddr, u)
\ Return the text string associated with the token identified by   TOKENID
\ TOKENID    a token id
\ --
\ CADDR      pointer to a 0 terminated character string
\ U          length of character string in characters

 help_pos tkNull
\ (   --  value)
\ Return the value associated with the token  tkNull
\ No input parameters
\ --
\ VALUE             value of the target token

 help_pos tkName
\ (   --  value)
\ Return the value associated with the token  tkName
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkStr
\ (   --  value)
\ Return the value associated with the token  tkStr
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkNum
\ (   --  value)
\ Return the value associated with the token  tkNum
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkParO
\ (   --  value)
\ Return the value associated with the token  tkParO
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkDot
\ (   --  value)
\ Return the value associated with the token  tkDot
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkParC
\ (   --  value)
\ Return the value associated with the token  tkParC
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkComma
\ (   --  value)
\ Return the value associated with the token  tkComma
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkEqual
\ (   --  value)
\ Return the value associated with the token  xtkEqualx
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkEqualColon
\ (   --  value)
\ Return the value associated with the token  tkEqualColon
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkFalse
\ (   --  value)
\ Return the value associated with the token  tkFalse
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkTrue
\ (   --  value)
\ Return the value associated with the token  tkTrue
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkVMunary
\ (   --  value)
\ Return the value associated with the token  tkVMunary
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkVMop
\ (   --  value)
\ Return the value associated with the token  tkVMop
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkFuncVal
\ (   --  value)
\ Return the value associated with the token  tkFuncVal
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkVMfunc
\ (   --  value)
\ Return the value associated with the token  tkVMfunc
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkVar
\ (   --  value)
\ Return the value associated with the token  tkVar
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkConst
\ (   --  value)
\ Return the value associated with the token  tkConst
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkActVal
\ (   --  value)
\ Return the value associated with the token  tkActVal
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkUserFunc
\ (   --  value)
\ Return the value associated with the token  tkUserFunc
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkUserSub
\ (   --  value)
\ Return the value associated with the token  tkUserSub
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkImmediate
\ (   --  value)
\ Return the value associated with the token  tkImmediate
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkunaryImmediate
\ (   --  value)
\ Return the value associated with the token  xx
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkComment
\ (   --  value)
\ Return the value associated with the token  tkComment
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkPtr2ScalerVariable
\ (   --  value)
\ Return the value associated with the token  tkPtr2ScalerVariable
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkEnd
\ (   --  value)
\ Return the value associated with the token  tkEnd
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkEmpty
\ (   --  value)
\ Return the value associated with the token  tkEmpty
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos tkERROR
\ (   --  value)
\ Return the value associated with the token  tkERROR
\ No input parameters
\ --
\  VALUE             value of the target token

 help_pos getcliToken
\ ( lastToken , charPtrIn ,   --  charPtrOut , cPtr tmp token str ,  len Token str , thisToken )
\ Get the next token from a CLI
\
\ LASTTOKEN   value of the previous found token
\             = tkNull if no previous token
\ CHARPTRIN   ptr to the first char of a 0 terminated text string to be examined for a token
\ --
\ CHARPTROUT  ptr to the first char AFTER the found token
\ CPTRTMPSTR  ptr to internal memory holding the text of the found token
\ LENTOKENSTR length in characters of the found token text in characters
\ THISTOKEN  value of the found token
\            The following is not 100% complete but shows the basic rules for identifing a token
\            tkName    a sequence of characters, starting with a [a.z, A.Z], that is not part of a ongoing tkComment or tkStr
\                          Trailing delimiters which are then discarded are:
\                              a space or tab character
\                          Trailing delimiters which are NOT discarded, but treated as a separate token (part)  are:
\                          + - * / > < =
\                          '     "
\                          { } [ ]   !   @    Note: any occurance of one of these is treated as a  tkName  of a single character
\                          (  )   ,  :   EOL
\
\            tkNum     a character representation of a numerical value
\                      the leading character string must be one of
\                      + character followed by a decimal expression
\                      - character followed by a decimal expression
\                      [0-9] character followed by a decimal expression
\                      0 character, base indicator character [b,B, o,O, x,X] (binary, octal, hexadecimal)  followed by a numerical expression in the specified base
\                      Any characater encountered that does not fit these  tkNum  rules is
\                      treated as a Trailing delimiter  which is NOT discarded, but treated as a separate token (part)
\            tkVMop    any sequence of the characters  + - * / > < =  that is not part of a ongoing tkComment or ongoing tkStr
\            tkComment all text following a  '  character that is not part of a ongoing tkComment or ongoing tkStr
\            tkStr     all text following a  "  character that is not part of a ongoing tkComment or ongoing tkStr
\            tkParO    any ( character not part of a tkComment or tkStr
\            tkParC    any ) character not part of a tkComment or tkStr
\            tkComma   any , character not part of a tkComment or tkStr
\            tkEnd     the End Of Line (EOL) character (the character with the numerical value 0x00)
\                      or any  : character that is not part of a ongoing tkComment or tkStr

    [then]
 help_pos collection.release
\ ( cHandle --  )
\ Remove the   collection CHANDLE from the COLLECTIONS, and release all of  CHANDLE's resources
\ CHANDLE   identity (handle) of the collection to be released
\           Should have been created via  call to     collection=new
\ --
\ no output parameter

 help_pos collection.new
\ (  -- cHandle )
\ Create a new collection.
\ no input parameter
\ --
\ CHANDLE   Internal identity (handle) of the created collection
\           Techie Talk:  actually a ptr to the management area of a COLLECTION
\           = 0 on error
\

 help_pos collection.parameters
\ ( cHandle --  )
\ Displays some information about the target COLLECTION
\ CHANDLE   identity (handle) of the collection to be released
\           Should have been created via  call to     collection=new
\ --
\ no output parameter

 help_pos collections.count
\ ( -- nbrConnections )
\ Return NBRCOLLECTIONS the number of collections in the systemCollection
\ No input parameters
\ --
\ NBRCOLLECTIONS     number of collections

 help_pos collection.items
\ ( cHandle -- NbrEntries )
\ Return the number of  entries in the collection identified by  CHANDLE
\ CHANDLE   Handle of the collection that owns the target entry
\           Should have been created via  call to     collection=new
\ --
\ NBRENTRIES     number of entries in the target collection
\                -1 on error

 help_pos unified.release
\ ( eHandle  -- )
\ Release the   eHandle  entry from its collection
\ EHANDLE    handle of the  target entry
\ --
\ no output parameter

 help_pos unified.release.by.index
\ ( eIndex , cHandle -- )
\ Release the eIndex (zero based index) entry of the collection identified by  CHANDLE
\ EINDEX    Zero-based index of the target entry in the COLLECTION
\ CHANDLE   Handle of the collection that owns the target entry
\           Should have been created via  call to     collection=new
\ --
\ no output parameter

 help_pos unified.release.by.index.To.End
\ ( eIndex , cHandle -- )
\ Release / delete all entries from the eIndex (zero based index) entry of the
\ collection upto and including the last entry of the collection identified by  CHANDLE
\ EINDEX    Zero-based index of the target entry in the COLLECTION
\ CHANDLE   Handle of the collection that owns the target entries
\           Should have been created via  call to     collection=new
\ --
\ no output parameter

 help_pos ??unified
\ ( -- )
\ Think of a   UNIFIED  entry, as an entry in a collection.
\ To create a UNIFIED entry (unified.add)  you must supply:
\     the owning collection, a text name, a BLOB (memory area ptr and size of area)
\ OR use    unified.new   which creates the entry in the default collection (sysStringId).
\
\ Once created a UNIFIED entry "knows" everything "knowable" about itself.
\    e.g. owning collection, index, size, contents , name
\
\ A UNIFIED entry is a structure with 3 parts:
\   a) internal header
\   b) a copy of the user's BLOB
\   c) user supplied name for the entry (does not need to be unique)
\
\  e.g.
\   struct me
\  \ a)
\   struct.value.cell  me.this        \ address of this entry (self reference)
\   struct.value.cell  me.pCollection \ pointer to this entry's parent collection
\   struct.value.cell  me.EntrySize   \ TOTAL bytes of all parts in the entry
\   struct.value.cell  me.index       \ 0-based index within this entry's parent  collection
\   struct.value.cell  me.uBlobSize   \ size in bytes of user blob part
\   struct.value.cell  me.uNameSize   \ size of text string/name in characters
\   struct.value.cell  me.uNameOffset \ offset from base of entry to the  text string/name
\   struct.value.cell  me.hashValue   \ hash based on a  MurmurOAAT64   type calculation
\  \ b)
\   \ then  uBlobSize bytes of user data
\
\   \ if the user blob size is less than 8 bytes it is rounded up to 8 .
\   \ if the user blob size is ODD, it is rounded up to be EVEN (ensures that the text string/name starts on a WORD boundary).
\  \ c)
\   \ then comes the user provided text string/name (in wide-characters)
\   \ and finally 2 bytes of zero

 help_pos collection.validate
\ (  cHandle --  0 | cHandle )
\ Checks whether the specified collection handle is VALID or not
\ CHANDLE   Handle  of the target collection
\ --
\ CHANDLE   Handle  of the target collection
\           = 0 if INVALID

 help_pos unified.validate
\ ( eHandle , cHandle --  0 | eHandle )
\ Display some information about the  entry identified by  eHandle
\ EHANDLE   Handle of the target entry
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle  of the target entry
\           = 0 if INVALID

 help_pos unified.show
\ ( eHandle --    )
\ Display some information about the  entry identified by  eHandle
\ EHANDLE   Handle of the target entry
\ --
\ no output parameters.

 help_pos unified.show.by.index
\ ( uIndex , cHandle --     ptr     |  -1  )
\ Display some information about the  entry identified by  eHandle
\ UINDEX    Zero-based index of target entry
\ CHANDLE   Handle  of the target collection
\ --
\ no output parameters.

 help_pos unified.dnif.before.index
\ ( c-addr , u , uIndex , cHandle --     eHandle     |  -1  )
\ Search in the collection  cHandle for an entry with the text string/name given by c-add,u
\ The search Last-in-first-out, starting just before the index  uIndex
\ UINDEX    Zero-based index of starting point  ( -1 implies start at the very end)
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.find.from.index.by.Murmur
\ ( MurmurHash , uIndex , cHandle --  eHandle |  -1  )
\ Search in the collection  cHandle for an entry with the MurmurHash value
\ The search is First-in-first-out, starting at the index  uIndex
\ MURMUR    The Murmur hash of a text string
\ UINDEX    Zero-based index of starting point  ( 0 implies start at the very beginning)
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.find.from.index
\ ( c-addr , u , uIndex , cHandle --  eHandle |  -1  )
\ Search in the collection  cHandle for an entry with the text string/name given by c-add,u
\ The search is First-in-first-out, starting at the index  uIndex
\ UINDEX    Zero-based index of starting point  ( 0 implies start at the very beginning)
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.find.cell.n
\ (  X , nth ,  cHandle --  eHandle |  -1  )
\ Search in the collection  cHandle for an entry whose nth (0 based index) cell in its BLOB =  X
\ X         wanted value in the nth  cell of the entries BLOB
\ NTH       target  cell in the entries BLOB
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.find.cell.zero
\ ( X , cHandle --  eHandle |  -1  )
\ Search in the collection  cHandle for an entry whose first cell in its BLOB =  X
\ X         wanted value in the first cell of the entries BLOB
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.get.by.index
\ ( uIndex , dHandle --  eHandle |  -1  )
\ Get the eHandle of the entry, in the collection cHandle, with the index  INDEX
\ UINDEX    Zero-based index of target entry
\ CHANDLE   Handle  of the target collection
\ --
\ EHANDLE   Handle of found entry
\              -1   on error

 help_pos unified.append
\ ( c-addr, u  , eHandleIn --  eHandleOut  |  -1  )
\ Append to the existing text string/name associated with the entry eHandleIn
\  the text given by  c-addr, u
\ Warning: altering an entry changes its eHandle, but not its  Index.
\ EHANDLEIN    Handle (internal identity) of the target entry
\ --
\ EHANDLEOUT   handle of entry after the text has been appended.
\              -1   on error

 help_pos unified.retext
\ ( c-addr, u  , eHandleIn --     eHandleOut     |  -1  )
\ Replace the text string/name associated with the  entry eHandleIn
\ Warning: altering an entry changes its eHandle, but not its  Index.
\ EHANDLEIN    Handle (internal identity) of the target entry
\ --
\ EHANDLEOUT   handle of entry after the text has been changed.
\              -1  on error

 help_pos unified.reblob
\ ( BlobSize , eHandleIn --  eHandleOut |  -1  )
\ Change the size of the user's BLOB, associated with the  entry eHandleIn.
\ As much of the old BLOB will be copied to the new BLOB as possible.
\ New BLOB space will be filled with zeros
\ Warning: altering an entry changes its eHandle, but not its  Index.
\ BLOBSIZE     Size of the "new" BLOB
\ EHANDLEIN    Handle (internal identity) of the target entry
\ --
\ EHANDLEOUT   handle of entry after the BLOB has been changed.
\              -1  on error

 help_pos unified@name
\ ( eHandle -- c-addr,u )
\  Return the text string/name associated with entry   eHandle.
\
\ EHANDLE   handle of entry whose name is to be obtained
\ --
\ CADDR     Memory address of first character of the name to be found
\ U         length of name to be searched for in characters.
\           0,0    if error

 help_pos unified@index
\ ( eHandle -- Index )
\  Return the zero-based index of this entry in its parent collection.
\
\ EHANDLE   handle of entry whose index is to be obtained
\            -1   on error
\ --
\ INDEX    zero-based index of this entry in its parent collectio
\           -1 if error

 help_pos unified@collection
\ ( eHandle -- ColId )
\  Return the COLLECTION HANDLE ColID of this entry's parent collection.
\
\ EHANDLE   handle of entry whose index is to be obtained
\            -1   on error
\ --
\ COLID     COLLECTION HANDLE of this entry's parent collection
\           -1 if error

 help_pos unified.add
\ ( caddr , u , blobSize , cHandle -- eHandle )
\  Create a  "unified" EMPTY entry with the text field as given by caddr,u.
\  Place the entry in the collection identified by cHandle
\  User blob area is set to zero.
\
\  To enter values in to the  BLOB   use the
\    EHANDLE. It is the address of the BLOB ( 64 bit address   aligned )
\
\ CADDR     Memory address of first character of the name
\ U         length of name to be searched for in characters.
\ BLOBSIZE  Size of user BLOB area to be provided.
\ CHANDLE   Handle of the target collection.
\ --
\ EHANDLE   handle of entry
\            0   on error

 help_pos unified.new
\ ( caddr , u , blobSize   -- eHandle )
\  Create a  "unified" entry with the text field as given by caddr,u.
\  Place the entry in the system internal collection identified by   sysStringId
\  User blob area is set to zero.
\
\ CADDR     Memory address of first character of the name
\ U         length of name to be searched for in characters.
\ BLOBSIZE  Size of user BLOB area to be provided.
\ --
\ EHANDLE   handle of new entry
\            0   on error

\ help_pos unified.str.add
\ (  caddr , u  -- eHandle )
\  Create a  "unified" string entry with the text field as given by caddr,u
\  User blob size is set to zero.
\
\ CADDR     Memory address of first character of the name
\ U         length of name to be searched for in characters.
\ --
\ EHANDLE   handle of entry after the text has been appended.
\            -1   on error

    [then]
  ' s"uni [if]
 help_pos com@status
\ (  -- bool )
\ Returns a boolean value BOOL indicating if the
\ Windows system internal COM library is initialsed for this application.
\ Some of this interpreter's built-in definitions require the COM
\ library to be initialised.
\ no input parameters
\ --
\ BOOL      0 = not initialised
\          else = initialised

 help_pos s">bstr
\ (c-addr, u -- bstr)
\ Convert the character string given by (c-addr,u)  to a BSTR format
\ BSTR type strings are used in interfacing with OLE and COM Automation.
\ C-ADDR    Address of a character string
\ U         Length of character string
\ --
\ BSTR      Address of a BSTR character string

 help_pos bstr>s"n
\ (bstr , N -- bstr , c-addr, u)
\ Get the Nth line (zero based index) from the BSTR type string to a character string given
\ by (c-addr,u)
\ BSTR type strings are used in interfacing with OLE and COM Automation.
\ These are relatively advanced programming issues that are NOT
\ dealt with in any detail within RIPE. The command   BSTR>S"n   is
\ only provide to simplify applications that use OLE and COM via DLL access.
\ BSTR      Address of a BSTR character string
\ N         Zero based index of line to be returned
\ --
\ BSTR      Address of a BSTR character string
\ C-ADDR    Address of a character string
\ U         Length of character string
\           = 0 = string empty
\             or if error then U = 0 and C-ADDR = -1

 help_pos bstr(n)
\ (bstrIn , N -- bstrOut )
\ Get the Nth line (zero based index) from the BSTR type string as a BSTR
\ BSTRIN    Address of a BSTR character string
\ N         Zero based index of line to be returned
\ --
\ BSTROUT   Address of a BSTR character string
\           NULL if  error

 help_pos bstr@len
\ (bstr -- len )
\ Return a string in BSTR format to the system.
\ If you do not then the application will consume system resources.
\
\ BSTR      Address of a character string in BSTR format
\ --
\ LEN       Length of BSTR in Wide Characters

 help_pos bstr.free
\ (bstr -- )
\ Return a string in BSTR format to the system.
\ If you do not then the application will consume system resources.
\
\ BSTR      Address of a character string in BSTR format
\ --
\ no output parameters

 help_pos bstr.split.n
\ (  srcBSTR  , tokenBSTR , CaseSensitiveFlag , n  -- retBSTR )
\ Extract the n'th (0 based) text string contained in the BSTR in VARIANT srcVar,
\ delimited by FIRST character of the BSTR held in
\ the VARIANT   tokenVar
\
\ srcBSTR   address of the BSTR with the source STRING
\ tokenBSTR address of the BSTR whose first character will be the delimiter
\ CaseSensitiveFlag  0 for case insensitive, else is case sensitive
\ n         0 based index of the wanted token
\           -1 = last token
\ --
\ retBSTR   address of a BSTR holding the result of the operation
\

 help_pos bstr.left
\ (  srcBSTR , charCount  -- retBSTR )
\ if   charCount   > 0  then KEEP only the first   charCount characters of the source BSTR
\ if   charCount   < 0  then LOSE      the first   charCount characters of the source BSTR
\ if   charCount   = 0  then LOSE                  all of the characters of the source BSTR
\ Return the address of the BSTR containing the result
\
\ srcBSTR   address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retBSTR   address of  a BSTR containing the result of the operation
\           on error: WARNING you MUST handle the FREEing of the src and ret  BSTRs
\                    use   bstrAdd   bstr.free

 help_pos bstr.mid
\ (  srcBSTR , startIndex , charCount  -- retBSTR )
\ if   charCount   > 0  then KEEP only the first   charCount characters of the source BSTR
\ if   charCount   < 0  then LOSE      the first   charCount characters of the source BSTR
\ if   charCount   = 0  then LOSE                  all of the characters of the source BSTR
\ Return the address of the BSTR containing the result
\
\ srcBSTR   address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retBSTR   address of  a BSTR containing the result of the operation
\           on error: WARNING you MUST handle the FREEing of the src and ret  BSTRs
\                    use   bstrAdd   bstr.free

 help_pos bstr.right
\ (  srcBSTR , charCount  -- retBSTR )
\ if   charCount   > 0  then KEEP only the last    charCount characters of the source BSTR
\ if   charCount   < 0  then LOSE      the last    charCount characters of the source BSTR
\ if   charCount   = 0  then LOSE                  all of the characters of the source BSTR
\ Return the address of the BSTR containing the result
\
\ srcBSTR   address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retBSTR   address of  a BSTR containing the result of the operation
\           on error: WARNING you MUST handle the FREEing of the src and ret  BSTRs
\                    use   bstrAdd   bstr.free

 help_pos bstr>s"
\ (bstr -- c-addr, u)
\ Convert a BSTR type string to a character string given
\ by (c-addr,u)
\ BSTR type strings are used in interfacing with OLE and COM Automation.
\ These are relatively advanced programming issues that are NOT
\ dealt with in any detail within RIPE. The command   BSTR>S   is
\ only provide to simplify applications that use OLE and COM via DLL access.
\ BSTR      Address of a character string
\ --
\ C-ADDR    Address of a character string
\ U         Length of character string

 help_pos s"uni
\ (c-addr, u -- uni-addr)
\ Convert a character string given by (c-addr,u) in to a UNICODE
\ string in memory at uni-addr
\ UNICODE strings are used in interfacing with OLE and COM Automation.
\ These are relatively advanced programming issues that are NOT
\ dealt within in any detail within RIPE. The command   s"uni   is
\ only provide to simplify applications that use  OLE and COM via DLL access.
\ C-ADDR    Address of a character string
\ U         Length of character string
\ --
\ UNI-ADDR  Address of equivalent UNICODE string

 help_pos guid>s"
\ (g-addr  -- c-addr, u )
\ Convert a 16 byte GUID in memory to an character string given by (c-addr,u)
\ G-ADDR    Address of 16 byte GUID in memory
\ --
\ UNI-ADDR  Address of equivalent UNICODE string
\ C-ADDR    Address of a character string
\ U         Length of character string

 help_pos s">guid
\ (c-addr, u , g-addr  --  )
\ Convert a 16 byte GUID in memory to an character string given by (c-addr,u)
\ G-ADDR    Address of 16 byte GUID in memory
\ --
\ UNI-ADDR  Address of equivalent UNICODE string
\ C-ADDR    Address of a character string
\ U         Length of character string

 help_pos VType_EMPTY
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_EMPTY
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_NULL
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_NULL
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_I2
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_I2
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_I4
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_I4
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_R4
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_R4
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_R8
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_R8
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_CY
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_CY
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_DATE
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_DATE
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_BSTR
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_BSTR
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_DISPATCH
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_DISPATCH
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_ERROR
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_ERROR
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_BOOL
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_BOOL
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_VARIANT
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_VARIANT
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UNKNOWN
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UNKNOWN
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_DECIMAL
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_DECIMAL
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_I1
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_I1
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UI1
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UI1
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UI2
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UI2
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UI4
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UI4
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_I8
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_I8
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UI8
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UI8
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_INT
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_INT
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_UINT
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_UINT
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_VOID
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_VOID
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_HRESULT
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_HRESULT
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_PTR
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_PTR
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_SAFEARRAY
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_SAFEARRAY
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_CARRAY
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_CARRAY
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_USERDEFINED
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_USERDEFINED
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_LPSTR
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_LPSTR
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_LPWSTR
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_LPWSTR
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_ARRAY
\ (  -- x)
\ Return the value of the VARIANT identifier for VT_ARRAY
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos VType_BYREF
\ (  -- x)
\ Return the value of the VARIANT identifier for  VT_BYREF
\
\
\ no input parameters
\ --
\ X         the value used to identify the VARIANT type

 help_pos var@type"
\ ( ptrVARIANT  -- c-addr, u)
\ Return the TYPE of the variant  at PTRVARIANT, as a text string
\ PTRVARIANT   Address the VARIANT structure
\ --
\ C_ADDR       Address of character string
\ U            Number of characters in string

 help_pos var!
\ (value, ptrVARIANT  -- flag)
\ Inserts a value into a VARIANT structure.
\ The VARIANT is identified by a pointer.
\ The VT field of the VARIANT must have been set.
\ The definition reads the VT field and then inserts VALUE in
\ the appropriate size / form to the appropriate VARIANT field.
\ Supported VT types are :
\        VT_EMPTY
\        VT_I1      VT_UI1
\        VT_I2      VT_UI2    VT_BOOL
\        VT_I4      VT_UI4    VT_INT    VT_UINT      VT_R4
\        VT_BSTR    VT_DISPATCH         VT_UNKNOWN   VT_R8
\ Not supported VT types are:
\        VT_CY      VT_DATE   VT_DECIMAL
\        VT_ERROR   VT_NULL
\
\ VALUE     Value to tbe placed in the VARIANT structure
\ PTRVARIANT   Address the VARIANT structure
\ --
\ FLAG      0  = the VT type is not supported by this definition
\           else = successful

 help_pos var@cell
\ ( ptrVARIANT  -- value , flag )
\ Read a value from a VARIANT structure.
\ The VARIANT is identified by a pointer.
\ The VT field of the VARIANT must have been set.
\ The definition reads the VT field and then extracts VALUE in
\ the appropriate size / form from the appropriate VARIANT field.
\ Supported VT types are :
\        VT_EMPTY
\        VT_I1      VT_UI1
\        VT_I2      VT_UI2    VT_BOOL
\        VT_I4      VT_UI4    VT_INT    VT_UINT    VT_R4
\        VT_BSTR    VT_DISPATCH         VT_UNKNOWN   VT_R8
\        VT_CY      VT_DATE
\ Not supported VT types are:
\        VT_DECIMAL
\        VT_ERROR   VT_NULL
\
\ PTRVARIANT   Address the VARIANT structure
\ --
\ VALUE     Effective Value held in the VARIANT structure
\           All signed integers  raised to INT64
\           All unsigned integers raised to UINT64
\           IF a FLOATING value is INTEGRAL than it is converted to INT64
\ FLAG      0  = the VT type is not supported by this definition
\           else = successful

 help_pos var@
\ ( VAR  -- value , flag )
\ Read a value from a VARIANT structure.
\ The VARIANT is identified by a pointer.
\ The VT field of the VARIANT must have been set.
\ The definition reads the VT field and then extracts VALUE in
\ the appropriate size / form from the appropriate VARIANT field.
\ Supported VT types are :
\        VT_EMPTY
\        VT_I1      VT_UI1
\        VT_I2      VT_UI2    VT_BOOL
\        VT_I4      VT_UI4    VT_INT    VT_UINT    VT_R4
\        VT_BSTR    VT_DISPATCH         VT_UNKNOWN   VT_R8
\        VT_CY      VT_DATE
\ Not supported VT types are:
\        VT_DECIMAL
\        VT_ERROR   VT_NULL
\
\ PTRVARIANT   Address the VARIANT structure
\ --
\ VALUE     Value held in the VARIANT structure
\ FLAG      0  = the VT type is not supported by this definition
\           else = successful

 help_pos @var
\ ( ptrVARIANT  -- address )
\ Return the memory address where the variant keeps its data
\ The VARIANT is identified by a pointer.
\
\ PTRVARIANT   Address the VARIANT structure
\ --
\ ADDRESS   Address where the variant keeps its data

 help_pos var.type@size
\ ( variantType  -- size  )
\ Returns the size in bytes of the  VT_TYPE field data.
\ So for a VT_BSTR this would be 8, whereas the BSTR text will have its own "size"
\ Supported VT types are :
\        VT_EMPTY
\        VT_I1      VT_UI1
\        VT_I2      VT_UI2    VT_BOOL
\        VT_I4      VT_UI4    VT_INT    VT_UINT    VT_R4
\        VT_BSTR    VT_DISPATCH         VT_UNKNOWN
\        VT_R8      VT_CY     VT_DATE   VT_DECIMAL
\        VT_ERROR   VT_NULL
\
\ VARIANTTYPE   Value
\ --
\ SIZE      Size of data field in bytes

 help_pos var@size
\ ( ptrVARIANT  -- size  )
\ Returns the size in bytes of the data field associated with variant at  ptrVARIANT
\ So for a VT_BSTR it returns the size of the BSTR data structure with the text & Count field.
\ The VARIANT is identified by a pointer.
\ The VT field of the VARIANT must have been set.
\ Supported VT types are :
\        VT_EMPTY
\        VT_I1      VT_UI1
\        VT_I2      VT_UI2    VT_BOOL
\        VT_I4      VT_UI4    VT_INT    VT_UINT    VT_R4
\        VT_BSTR    VT_DISPATCH         VT_UNKNOWN
\        VT_R8      VT_CY     VT_DATE   VT_DECIMAL
\        VT_ERROR   VT_NULL
\
\ PTRVARIANT   Address the VARIANT structure
\ --
\ SIZE      Size of data field in bytes

 help_pos IsWindow
\ ( HWND  -- bool )
\ Checks whether   HWND represent an existing window.
\ Is a wrapper around the WIN32 API IsWindow function.
\ HWND      HWND value to be verifed for existence
\ --
\ BOOL      Boolean = TRUe if HWND valid, else FALSE

 help_pos IsVarNumerical
\ ( VAR -- x)
\ Returns whether a VARIANT, at address VAR,  holds a nummerical value.
\
\
\ VAR       the address of the VARIANT
\ --
\ X         0 if not numerical
\           1 if it fits in a signed 64 bit integer
\           2 if it fits in an unsigned 64 bit integer
\           3 if it fits in a DECIMAL = 96 bit structure
\           -1 if it is a floating number (R8)

 help_pos vtype.pack
\ ( srcVal, srcVtype , dstVtype   -- [x , true]  0 )
 help_pos var@info
\ ( VAR  -- rawValue ,  stdType )
\   ByRef are dereferenced
\   INPUT VAR                   OUTPUT
\    R4                         R8
\    R8                         R8
\     i1   i2    i4    i8       i8
\    ui1  ui2   ui4   ui8       i8
\    ARRAY                      content of data field of VAR
\    BSTR                       ptr to a BSTR
\ VAR       the address of the VARIANT
\ --
\ RAW DATA     = 64bit content of the VARIANT's data field (except ARRAYs = address of array data)
\ STD TYPE     = as given in INPUT OUTPUT table above

 help_pos var@value
\ ( ptrVARIANT  -- (X , Y)|Z    , flag)
\ Returns the value associated with the VARIANT at the address VAR
\ PTRVARIANT   Address the VARIANT structure
\ --
\ FLAG
\          -1  = floating point
\                 Z  =    floating point  WARNING ,
\           0  = unknown
\                  X , Y  = double cell unsigned integer
\           1  = signed integer
\                  X , Y  = double cell signed integer
\           2  = unsigned integer
\                  X , Y  = double cell unsigned integer
\           3  = text string
\                 X , Y  = c-addr , u  of text string

 help_pos var.as.s"
\ ( ptrVARIANT  -- (X , Y)|Z    , flag)
\ Returns the value associated with the VARIANT at the address VAR
\ PTRVARIANT   Address the VARIANT structure
\ --
\ FLAG
\          -1  = floating point
\                 Z  =    floating point  WARNING ,
\           0  = unknown
\                  X , Y  = double cell unsigned integer
\           1  = signed integer
\                  X , Y  = double cell signed integer
\           2  = unsigned integer
\                  X , Y  = double cell unsigned integer
\           3  = text string
\                 X , Y  = c-addr , u  of text string

 help_pos var.mul
\ ( lVar , rVar -- retVar )
\ Returns the result of multiplying
\ the contents of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarMul
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.sub
\ ( lVar , rVar -- retVar )
\ Returns the result of subtracting
\ the contents of the VARIANT rVar from the content of the VARIANT lVAR
\
\ Technical Note: wrapper for OleAut32 VarSub
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.add
\ ( lVar , rVar -- retVar )
\ Returns the result of adding
\ the content of the VARIANT rVar to the content of the VARIANT lVAR
\
\ Technical Note: wrapper for OleAut32 VarAdd
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.cat
\ ( lVar , rVar -- retVar )
\ Returns the result of concatenating
\ the content of the VARIANT rVar to the content of the VARIANT lVAR
\ Result is in a new temporary VARIANT.
\ Technical Note: wrapper for OleAut32 VarCat
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.append
\ ( lVar , rVar -- lVar )
\ Returns the result of concatenating
\ the content of the VARIANT rVar to the content of the VARIANT lVAR
\
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ lVar      = on error:     type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.append"
\ (   lVar , caddr , u  -- lVar )
\ Returns the result of concatenating the text string given by U characters at address C-ADDR
\ to the content of the VARIANT  lVAR
\
\ lVar      address of the left Variant
\ --
\ lVar      = on error:     type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.div
\ ( lVar , rVar -- retVar )
\ Returns the result of dividing
\ the content of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarDiv
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.rem
\ ( lVar , rVar -- retVar )
\ Returns the remainder result of dividing
\ the content of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarMod
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.fix
\ ( uVar   -- retVar )
\ Returns the integer part  of the VARIANT uVar as a VAR FLOAT
\
\ Technical Note: wrapper for OleAut32 VarFix
\ uVar      address of the user supplied Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.int
\ ( uVar   -- retVar )
\ Returns the integer part  of the VARIANT uVar  as an integer VAR
\
\ Technical Note: wrapper for OleAut32 VarFix
\ uVar      address of the user supplied Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.cmp.case
\ ( lVar , rVar -- retVal )
\ Returns the result of comparing (case sensitive if relevant)
\ the content of the VARIANT lVar with the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarCmp
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVal    a value (not a VARIANT) showing the result of the operation
\           0 = lVar < rVar
\           1 = lVar = rVar
\           2 = lVar > rVar
\           3 = Equal

 help_pos var.cmp
\ ( lVar , rVar -- retVal )
\ Returns the result of comparing (case insensitive if relevant)
\ the content of the VARIANT lVar with the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarCmp
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVal    a value (not a VARIANT) showing the result of the operation
\           0 = lVar < rVar
\           1 = lVar = rVar
\           2 = lVar > rVar
\           3 = Equal

 help_pos var@error
\ (  -- eCode )
\ Returns the staus of the last  var.xxx    operation
\
\ Technical Note:  HRESULT  S_OK = 0
\ no input parameters
\ --
\ ECODE     a HRESULT error code
\           0 = no error

 help_pos var.abs
\ ( sVar   -- retVar )
\ Returns the absolute value of the VARIANT sVar
\
\ Technical Note: wrapper for OleAut32 VarNot
\ sVar      address of the user supplied Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           if SVAR is not numerical: retVar   type is  VT_NULL
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.not
\ ( uVar   -- retVar )
\ Returns the bitwide inversion of the VARIANT uVar
\
\ Technical Note: wrapper for OleAut32 VarNot
\ uVar      address of the user supplied Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           if UVAR is not numerical: retVar   type is  VT_NULL
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.neg
\ ( uVar   -- retVar )
\ Returns the logical inversion of the VARIANT uVar
\   i.e. posive number to negative, and vice versa
\
\ Technical Note: wrapper for OleAut32 VarNot
\ uVar      address of the user supplied Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           if UVAR is not numerical: retVar   type is  VT_NULL
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.or
\ ( lVar , rVar -- retVar )
\ Returns the result of a bitwise OR of
\ the content of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarOr
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.xor
\ ( lVar , rVar -- retVar )
\ Returns the result of a bitwise XOR of
\ the content of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarXor
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.and
\ ( lVar , rVar -- retVar )
\ Returns the result of a bitwise AND of
\ the content of the VARIANT lVar by the content of the VARIANT rVAR
\
\ Technical Note: wrapper for OleAut32 VarAnd
\ lVar      address of the left Variant
\ rVar      address of the right Variant
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\                    and the content is a HRESULT error code

 help_pos var.split
\ (  srcVar , tokenVar , CaseSensitiveFlag  -- retVar )
\ Splits the BSTR held in the VARIANT  srcVar  into an array of BSTRs
\ held in the returned VARIANT   retVar
\ The splitting is based on the FIRST character of the BSTR held in
\ the VARIANT   tokenVar
\
\ srcVar    address of the Variant with the source STRING
\ tokenVar  address of the Variant whose first character will be the delimiter
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\

 help_pos var.split.n
\ (  srcVar , tokenVar , CaseSensitiveFlag , n  -- retVar )
\ Extract the n'th (0 based) text string contained in the BSTR in VARIANT srcVar,
\ delimited by FIRST character of the BSTR held in
\ the VARIANT   tokenVar
\
\ srcVar    address of the Variant with the source STRING
\ tokenVar  address of the Variant whose first character will be the delimiter
\ CaseSensitiveFlag  0 for case insensitive, else is case sensitive
\ n         0 based index of the wanted token
\           -1 = last token
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\

 help_pos var.split.string
\ (  srcVar , tokenVar , CaseSensitiveFlag  -- retVar )
\ Splits the BSTR held in the VARIANT  srcVar  into an array of BSTRs
\ held in the returned VARIANT   retVar
\ The splitting is based on ANY character in the BSTR held in
\ the VARIANT   tokenVar
\
\ srcVar    address of the Variant with the source STRING
\ tokenVar  address of the Variant whose first character will be the delimiter
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\

 help_pos var.replace
\ (  srcVar , replaceVar , byVar , CaseSensitiveFlag  -- retVar )
\ Replaces all occurrences of the    BSTR text held in the VARIANT  replaceVAr
\ that are found in the   BSTR text held in the VARIANT   srceVAr
\ by the  BSTR text held in the VARIANT  byVar
\ held in the returned VARIANT   retVar
\ The splitting is based on the FIRST character of the BSTR held in
\ the VARIANT   tokenVar
\ CaseSensitiveFlag  0 for case insensitive, else is case sensitive
\ srcVar    address of the Variant with the source STRING
\ replaceVar  address of the Variant with the text to be replaced
\ byVar     address of the Variant with the text to inserted
\ CaseSensitiveFlag  0 for case insensitive, else is case sensitive
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\           on error: retVar   type is  VT_ERROR
\

 help_pos var.left
\ (  srcVar , charCount  -- retVar )
\ Returns a new VARIANT  retVar which is a substring of the input variant srcVar.
\ srcVar must be of type  VT_BSTR.
\ if   charCount   > 0  then KEEP only the first   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   < 0  then LOSE      the first   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   = 0  then LOSE                 all of the characters of the string contained in the VARIANT srcVAR
\ Return the resulting string in a temporary VARIANT    retVar
\
\ srcVar    address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\

 help_pos var.mid
\ (  srcVar , startAt ,  charCount  -- retVar )
\ Returns a new VARIANT  retVar which is a substring of the input variant srcVar.
\ srcVar must be of type  VT_BSTR.
\ if   charCount   > 0  then KEEP only the first   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   < 0  then LOSE      the first   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   = 0  then LOSE                 all of the characters of the string contained in the VARIANT srcVAR
\ Return the resulting string in a temporary VARIANT    retVar
\
\ srcVar    address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\

 help_pos var.right
\ (  srcVar , charCount  -- retVar )
\ Returns a new VARIANT  retVar which is a substring of the input variant srcVar.
\ srcVar must be of type  VT_BSTR.
\ If  srcVar is not  of tye VT_BSTR then retVar = srcVar i.e. is NOT a new VARIANT
\ if   charCount   > 0  then KEEP only the last   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   < 0  then LOSE      the last   charCount characters of the string contained in the VARIANT srcVAR
\ if   charCount   = 0  then LOSE                all of the characters of the string contained in the VARIANT srcVAR
\ Return the resulting string in a temporary VARIANT    retVar
\
\ srcVar    address of the Variant with the source STRING
\ charCount identifies the number of characters to be kept/lost
\ --
\ retVar    address of a temporary Variant holding the result of the operation
\

 help_pos scan.array
\ (  baseAdd , eleSize , eleNbr , eleOFF ,  wantVal  -- index | -1 )
\ Finds the index of a wanted value within an array of elements.
\ baseAdd    base address of  array  to be scanned
\ elseSize   size of an array element in bytes:  1,2,4,8
\ eleNbr     total number of elementsin the array
\ eleOff     index (0th-based) of first element to be scanned
\ wantVal    value to be found within the scanned elements
\ --
\ index      index (0-based) of first matching element
\            = -1 if not found
\

  [then]
 help_pos versionId
\ (-- c-addr, u)
\ Returns a text string that gives the  data of the executable image compilation.
\ No input parameters
\ --
\ C-ADDR
\ U

 help_pos version
\ (--)
\ Display a text string that shows the version number of this interpreter and
\ the data of the executable image compilation.
\ No input parameters
\ --
\ No output parameters

 help_pos last-error
\ (-- sub-err, main-err)
\ Return the sub and main error code that were last triggered.
\ No input parameters
\ --
\ SUB-ERR    Value of last sub-error
\ MAIN-ERR   Value of last main-error

 help_pos >ffa
\ (lfa-addr -- ffa-addr)
\ Given the Link Field Address lfa-addr of a header then
\ return the Flag Field Address ffa-addr of the same header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addr   The Link Field Address of a definition's header
\ --
\ ffa-addr   The Flag Field Address of the same header

 help_pos >ncfa
\ (lfa-addr -- ncfa-addr)
\ Given the Link Field Address  lfa-addr  of a header then
\ return the Name Count Address ncfa-addr of the same header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addr   The Link Field Address of definition's header
\ --
\ ncfa-addr  The Name Count Field Address of the same header

 help_pos >nfa
\ (lfa-addr -- nfa-addr)
\ Given the Link Field Address  lfa-addr  of a header then
\ return the Name Field Address nfa-addr of the same header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addr   The Link Field Address of definition's header
\ --
\ nfa-addr   The Name Field Address of the same header

 help_pos >lfa
\ (lfa-addrI -- lfa-addrO)
\ Given the Link Field Address  lfa-addrI  of a header then
\ return the Link Field Address lfa-addrO of the previous header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addrI  The Link Field Address of definition's header
\ --
\ lfa-addrO  The Link Field Address of the previous header

 help_pos >cfa
\ (lfa-addr -- cfa-addr)
\ Given the Link Field Address  lfa-addr  of a header then
\ return the Code Field Address nfa-addr of the same header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addr   The Link Field Address of definition's header
\ --
\ cfa-addr   The Code Field Address of the same header

 help_pos >hfa
\ (lfa-addr -- hfa-addr)
\ Given the Link Field Address  lfa-addr  of a header then
\ return the Help Field Address nfa-addr of the same header.
\ If lfa-addr is not a valid Link Field Address then the
\ result is indeterminate.
\ lfa-addr   The Link Field Address of definition's header
\ --
\ hfa-addr   The Help Field Address of the same header

 help_pos #streams
\ (-- u)
\ Return u the maximum number of nested input streams supported
\ No input parameters
\ --
\ u          The maximum number of nested input streams that are supported.

 help_pos #stream
\ (-- u)
\ Return u the index of the current nested input stream.
\ No input parameters
\ --
\ u          The index of the current nested input stream

 help_pos ibuf.next
\ (  --  )
\ Selects the next internal memory block in the barrel list.
\ REFER to help for   iBuf
\
\ no input parameters
\ --
\ no output parameters

 help_pos ibuf
\ (  -- c-addr )
\ Returns the start address of the current internal memory block in the barrel list.
\
\ This executable maintains a number (currently 32) of internal memory blocks in a simple barrel
\ list. Each block has the same size  currently 256 kbytes, actual plus 4 for zero terminations reasons.
\ WHY: say you wanted to add convert a text string to uppercase.
\ If it is safe to do so, then do the conversion in-situ. But if you can not risk changing
\ the input text then you must obtain space to hold the uppercase string.
\ Go ahead and use say  ALLOCATE and FREE to get/return system memory. But you must keep
\ track of such calls otherwise you will create memory leaks.
\ Commands  such as   join"   "toUpper  ...   automatically use internal memory blocks for
\ holding their output string.
\ Providing that the output string is consumed/used/no-longer needed before the next (31)
\ blocks are requested, then there is not problem. Just DO NOT treat the output strings
\ of such commands as anything more than temporary storage.
\
\ no input parameters
\ --
\ C-ADDR    start address of an internal memory buffer ( 256k bytes in size)

 help_pos ibuf.Is
\ ( uAddr , u -- c-addr, u )
\ If  UADDR is an address within the internal buffer area then return the
\ address and size of the owning buffer.
\
\ no input parameters
\ --
\ C-ADDR  address of  temporary buffer
\ U       Size of   temporary buffer in characters

 help_pos ibuf.return
\ ( uAddr, u --   )
\ If  UADDR    is an address within the internal buffer area then return the
\ buffer to the free pool. Else do nothing.
\
\ no input parameters
\ --
\ no output parameters

 help_pos tmpBuf.char
\ (  -- c-addr, u )
\ REFER to help for   iBuf
\
\ no input parameters
\ --
\ C-ADDR  address of  temporary buffer
\ U       Size of   temporary buffer in characters

 help_pos tmpBuf.byte
\ (  -- c-addr, u )
\ REFER to help for   iBuf
\
\ no input parameters
\ --
\ C-ADDR  address of  temporary buffer
\ U       Size of   temporary buffer in bytes

 help_pos ibuf.size
\ (  -- u )
\ REFER to help for   iBuf
\
\ no input parameters
\ --
\ U       Size of an internal managed buffer in BYTES

 help_pos cs-pick
\ (C: lu...l1, l0 -- lu...l1, l0, lu)
\ (S: u --)
\ The value u is removed from the stack.
\ Then the u'th link lu, on the control stack is copied,
\ the control stack is pushed down, and ln is placed on
\ the top of the stack.
\ C: lu .. l0    Link descriptors
\ S: u           Index to link descriptor to be copied
\ --
\ C: lu .. l0,lu Link descriptors
\ S: no output parameters

 help_pos cs-roll
\ (C: lu...l1, l0 -- lu-1...l1, l0, lu)
\ (S: u --)
\ The value u is removed from the stack.
\ Then the top u link descriptors on the control stack are rotated.
\ lu comes to the top, links u-1..0 are pushed down.
\ C: lu .. l0      Link descriptors
\ S: u             Index to link descriptor to be rotated
\ --
\ C: lu-1 .. l0,lu Link descriptors
\ S: no output parameters

 help_pos execute
\ (xt --)
\ Execute the command with the eXecution Token XT.
\ XT         An eXecution Token
\ --
\ No output parameters

 help_pos quit
\ (--)
\ Stop executing eXecution Tokens.
\ De-nest any nested eXecution Token calls.
\ De-nest any nested input streams, first closing any input stream filed
\ Enter normal interpretation state, and accept input from the
\ user on the default input device.
\ No input parameters
\ --
\ No output parameters

  ' catch 0= [if]
 help_pos abort
\ (x?, ..x1 --)
\ Discard all cells on the stack then execute QUIT
\ x?, ..x1   All cells on the stack
\ --
\ No output parameters

 [then]
 help_pos abort"
\ (x?.., x1, x0 --  |(x?.., x1))
\ Used in the form    : fred  ...  abort" Oh Oh" mike ...
\ Compile time action:
\   Parse the input line for a " delimited string.
\   Compile in code to fullfill the following run time action:
\ If the top value x0 on the stack is not zero
\   Display the parsed string
\   Execute the ABORT command
\ Else
\   Discard the string
\   Continue by executing the first instruction after the
\   parsed string.
\ x?.., x1       All cells on the stack except the top cell
\ x0             Top cell on the stack
\ --
\  |(x?.., x1)   Either: stack is empty if ABORT is executed
\                Or: stack is unchanged except for loss of X0

 help_pos >r
\ (x --)
\ The top value x on the stack is moved to the RETURN stack
\ x          Top cell on the stack
\ --
\ No output parameters

 help_pos r>
\ (-- x)
\ The top value on the RETURN stack is moved to the stack
\ No input parameters
\ --
\ x          Top cell on the stack

 help_pos r@
\ (-- x)
\ The top value on the RETURN stack is copied to the stack
\ No input parameters
\ --
\ x          Top cell on the stack

 help_pos cell+
\ (u1 -- u2)
\ Add the number of address units in a cell to the value u1bye
\ U1         A value
\ --
\ U2         = U1 + (number of address units in a cell)

 help_pos cells
\ (u1 -- u2)
\ Return the number of address units in U1 cells
\ U1         The number of cells
\ --
\ U2         = U1 * (number of address units in a cell)

\ (x -- y)
\ Add number of ADDRESS UNITS in a name count field to the top
\ value on the  stack

\ (x -- y)
\ WAITING

 help_pos char+
\ (u1 -- u2)
\ Add the number of address units in a char to the value u1
\ U1         A value
\ --
\ U2         = U1 + (number of address units in a char)

 help_pos sizeIn(cells)
\ ( B -- u)
\ Return the number of CELLS needed to hold the number of bytes B
\ e.g.  How many CELLs are used to hold a FLOATING point value
\ =   siteof(float) sizeIn(cells)
\ B          = number of bytes
\ --
\ U          =  number of address units in a CELL

 help_pos create
\ (--)
\ Used in the form CREATE COMMAND-NAME
\ Parse the input line for a space  delimited string.
\ If the string is empty, then a trap to an error occurs.
\ Else
\   Create a command header with this string as the command name.
\   Compile in code to fullfill the following run time action:
\ When COMMAND-NAME is executed then place the address of the first
\ cell-aligned dataspace location immediately after this command's
\ definition, on the stack
\ The command   DOES>   can be used to link this command to new
\ functionality.
\ No input parameters
\ --
\ No output parameters

 help_pos allot
\ (n --)
\ Move the pointer to the next free space in the dataspace
\ by n address units.
\ Note: n is a signed integer. So if n < 0 then the free dataspace
\ pointer will be moved backwards.
\ Note: Depending on the value of n, the free dataspace pointer may
\ cease to be, or become cell or charater aligned.
\ N          A single precision signed integer
\ --
\ No output parameters

 help_pos variable
\ (--)
\ Used in the form  VARIABLE FRED
\ Creates a new definition FRED
\ When FRED is used the address of a single value will be
\ left on the stack
\ No input parameters
\ --
\ No output parameters

 help_pos constant
\ (x --)
\ Used in the form 12 CONSTANT FRED
\ Creates a new WORD named FRED
\ When FRED is used the value ( in this case 12 ) will be
\ left on the stack
\ X          Cell sized value
\ --
\ No output parameters

 help_pos immediate
\ (--)
\ Sets the last defined word to be IMMEDIATE
\ i.e. is executed at COMPILE time !
\ No input parameters
\ --
\ No output parameters

 help_pos :
\ (--)
\ Used in the form  : FRED    ... ;
\ Create a new definition FRED
\ Structure of header for a WORD is :-
\  LFA    Link Field Address  ptr to previous WORD'S header
\  FFA    Flag Field Address  boolean flags
\  NCFA   Name Count Field Address  length of WORDs name in characters
\  NFA    Name Field Address   ASCII name of WORD , zero terminated
\  HFA    Help Field Address  file-offset into a help file
\
\ The structure of a Code Field Address is:
\  value PRIMITIVE_OPCODE ( 1 )
\  address of the TRACE primitive
\    ptr to the Name of this definition
\  address of this WORDs NFA
\
\  value CALL_OPCODE               } this pair is 'compiled-in' for each
\  ptr to CFA of referenced WORD   } WORD referenced in this : definition
\
\  value  RETURN_OPCODE ( 2 )
\
\ No input parameters
\ --
\ No output parameters

 help_pos recurse
\ (--)
\ Used in the form  : FRED ...   recurse ;
\ causes a call to  FRED to be compiled in to itself
\ No input parameters
\ --
\ No output parameters

 help_pos ;
\ (--)
\ Used in the form  : FRED ... ;
\ ; signifies the end of a : definition
\ No input parameters
\ --
\ No output parameters

 help_pos postpone
\ (--)
\ Used in the form   :  FRED  ...  postpone <name>  ... ;
\ Compile time action:
\   Parse the input line for a string delimited by the space char or
\   the end of line character.
\   Search the wordlists in the current search order for the
\   definition named by the parsed string.
\   If the name is not found then a trap to an error handler occurs.
\   Else compile in code to fullfill the following run time action:
\ Execute the postponed command
\ No input parameters
\ --
\ No output parameters

 help_pos >body
\ (xt -- a-addr)
\ Convert an eXecution Token to the corresponding definitions data area address.
\ This only works correctly if XT corresponds to a definition made
\ using CREATE
\ xt         An eXecution Token
\ --
\ a-addr     Address of corresponding data area

 help_pos ,
\ (x -- )
\ The cell size value X will be written to the next cell sized location
\ of the free dataspace.
\ x          A cell value
\ --
\ No output parameters

 help_pos 1+
\ (n1|u1 -- n2|u2)
\ Adds the value 1 to the top cell on the stack.
\ n1|u1     Top cell on stack
\ --
\ n2|u2     Top cell on stack = n1|u1  +  1

 help_pos 1-
\ (n1|u1 -- n2|u2)
\ Subtract the value 1 from the top cell on the stack.
\ n1|u1     Top cell on stack
\ --
\ n2|u2     Top cell on stack = n1|u1  -  1

 help_pos dup
\ (x -- x, x)
\ Duplicate the top cell on the stack
\ x          A cell value
\ --
\ x          A cell value
\ x          A cell value

 help_pos ?dup
\ (x -- 0|(x, x))
\ Duplicate the top cell on the stack if and only if it does not equal zero
\ No input parameters
\ x          A cell value
\ --
\ 0 |(x,x)   0 if x=0,else or x,x

 help_pos drop
\ (x --)
\ Discard the top cell on the stack
\ x          A cell value
\ --
\ No output parameters

 help_pos over
\ (x1, x2 -- x1, x2, x1)
\ The second cell on the stack is copied to the top
\ x1         A cell value
\ x2         A cell value
\ --
\ x1         A cell value
\ x2         A cell value
\ x1         A cell value

 help_pos swap
\ (x1, x2 -- x2, x1)
\ Exchange the top two cells on the stack
\ x1         A cell value
\ x2         A cell value
\ --
\ x2         A cell value
\ x1         A cell value

 help_pos base
\ (-- a-addr)
\ Return the address of a cell containing the default radix for
\ character/number conversions.
\ No input parameters
\ --
\ a-addr     Address containing the default radix for
\            character/number conversion

 help_pos decimal
\ (--)
\ Set the BASE for character/number conversions to be Base-10.
\ Is equivalent to #10 BASE !
\ No input parameters
\ --
\ No output parameters

 help_pos source
\ (-- c-addr, u)
\ Return the character address and length of the string
\ containing the current input line. This is the PARSE area!
\ No input parameters
\ --
\ c-addr     Address of the input line.
\ u          Number of characters in the input line

\ (-- addr)
\ Leave behind the address of the file identity of the file that
\ provides the current input character stream
\ No input parameters
\ --
\ a-addr     Address containing the file identity of the current input line
\            source.

\   span
\ (-- a-addr)
\ The address of a cell containing  the number of characters
\ in the input line. Even if you change it, it will have no effect.
\ No input parameters
\ --
\ a-addr     Address containing the number of characters
\            in the input line.

 help_pos stream-name
\ (-- c-addr, u)
\ Leave  behind the character string at c-addr of length u that
\ gives the file name associated with the current input character stream
\ No input parameters
\ --
\ c-addr     Address of 0 terminated character string holding
\            the name of the current input stream
\ U          Length of character string

 help_pos >in
\ (-- a-addr)
\ Return the address of a cell containing the offset in CHARACTERS
\ from the start of the current PARSE area to the start of the
\ next character to be parsed
\ No input parameters
\ --
\ a-addr     Address containing the character offset

 help_pos tib
\ (-- c-addr)
\ Return the start address of the current PARSE area.
\ No input parameters
\ --
\ c-addr     Address of the current input line

 help_pos source-id
\ (-- 0|-1|file-id)
\ Identify which type of source is providing the current input line.
\ No input parameters (keyboard/Evaluate/file)
\ --
\            0 = user input device
\            -1 = input string via EVALUATE
\            ELSE  = the system allocated file-identity of an included file

 help_pos state
\ (-- a-addr)
\ Return the address of a internal variable containing a boolean
\ indicating whether the command line interpreter is in compile
\ or interactive mode. ( 0 = interactive mode, else compile mode)
\ No input parameters
\ --
\ a-addr     The address of the STATE variable

 help_pos here
\ (-- addr)
\ Return the address of the next free space in the dataspace.
\ No input parameters
\ --
\ a-addr     The address of the next free space in the dataspace

 help_pos bl
\ (-- char)
\ Return the value for a space character.
\ No input parameters
\ --
\ char       The value for a space character

 help_pos space
\ (--)
\ Display a single space character
\ No input parameters
\ --
\ No output parameters

 help_pos spaces
\ (u --)
\ Display U space characters
\ No input parameters
\ --
\ U          Number of spaces to be displayed

 help_pos cr
\ (--)
\ Advance the position for inserting the next character on the display
\ to the begining on the next display line.
\ No input parameters
\ --
\ No output parameters

 help_pos depth
\ (-- u)
\ Return the number of cells (excluding itself) on the stack
\ No input parameters
\ --
\ u          Number of cells (excluding itself) on the stack

 help_pos =
\ (x1, x2 -- bool)
\ Return bool = TRUE if and only if  x1 is equal to x2 , else bool = false.
\ x1         A cell size value
\ x2         A cell size value
\ --
\ bool      = TRUE if and only if  x1 is equal to x2
\           else = false

 help_pos 0=
\ (x -- bool)
\ Compare the  signed integer n with 0.
\ Return bool = TRUE if and only if  n is equal to 0 , else bool = false.
\ n          A signed integer
\ --
\ bool      = TRUE if and only if  n is equal to 0
\           else = false

 help_pos 0<
\ (n -- bool)
\ Compare the  signed integer n with 0.
\ Return bool = TRUE if and only if  n is less than 0 , else bool = false.
\ n          A signed integer
\ --
\ bool      = TRUE if and only if  n is less than 0
\           else = false

 help_pos <
\ (n1, n2 -- bool)
\ Compare the two signed integers n1 and n2.
\ Return bool = TRUE if and only if  n1 is less than n2 , else bool = false.
\ n1         A signed integer
\ n2         A signed integer
\ --
\ bool      = TRUE if and only if  n1 is less than n2
\           else = false

 help_pos >
\ (n1, n2 -- bool)
\ Compare the two signed integers n1 and n2.
\ Return bool = TRUE if and only if  n1 is greater than n2 , else bool = false.
\ n1         A signed integer
\ n2         A signed integer
\ --
\ bool      = TRUE if and only if  n1 is greater than n2
\           else = false

 help_pos '
\ (-- xt|0)
\ e.g.  '  FRED
\ Parse the current input area for a space delimited string.
\ Search the current search wordlist for a definition that matches
\ the delimited string.
\ Return the eXecution Token XT if the definition was found, else
\ return 0.
\ No input parameters
\ --
\ xt|0       The eXecution Token if the definition was found, else 0
\ See also  [']

 help_pos [']
\ (--)
\ e.g.  : test  ['] FRED
\ Compile time action:
\   Parse the current input area for a space delimited string.
\   Search the current search wordlist for a definition that matches
\   the delimited string.
\   Compile in the eXecution Token XT for the definition.
\   If the definition was not found, then a trap to an error handler occurs.
\   Compile in code to fullfill the following run time action:
\ Place XT on the stack.
\ No input parameters
\ --
\ xt         The eXecution Token
\ See also  '

 help_pos literal
\ (x --)
\ Used in the form    X   : fred  ...    literal  ... ;
\ Compile time action:
\   Compile the value X in to the current definition.
\   Compile in code to fullfill the following run time action:
\ Place X on the stack.
\ X         A cell sized value
\ --
\ No output parameters

 help_pos !DecimalChar
\ (character --)
\ Set the character to be used as the Decimal Point
\ X         A character value
\ --
\ No output parameters

 help_pos @DecimalChar
\ (-- character  )
\ Get the character used as the Decimal Point
\ No input parameters
\ --
\ X         A character value

 help_pos CommentStr
\ (   -- c-addr, u )
\

 help_pos ExecuteEditControl
\ ( hwnd --  )
\ Cause the Forth command line interpreter to take its input
\ from a RichText Edit control.
\ So it is logically similar to        include-file
\  HWND is the handle of the edit control
\

 help_pos refill
\ (-- bool)
\ Refill the input line with a new line from the input source.
\ Note: All keyboard input in RIPE is passed to the
\       command line interpreter via the evaluate command.
\ If the current input stream is the keyboard, then accept input.
\   Set the offset to the next character in the input line to
\   be parsed to be zero. See >IN
\   Return TRUE
\ ELSE
\   If the input stream was from EVALUATE
\      Return FALSE
\   Else
\     input stream is a file source
\     read input file
\     if read was successful and length > 0
\       return TRUE
\      else
\       FALSE
\ No input parameters
\ --
\ BOOL      = TRUE if operation successful, even for empty line
\           else = 0 = operation failed

\ Internal routine to do  WORD
\ (delim -- cs-addr)
\ Reads a delimited string from the input line.
\ DELIM     The delimiter character
\ --
\ CS-ADDR   is the address of a counted string in a transient area
\           CS-ADDR points at:
\              - string length in CHARACTERS
\              - character string
\              - a space character (required for compatibility
\              with an earlier standard)
\           If the parse area is empty, or only contains delimiters
\           then the string length is zero

 help_pos word
\ (char -- cs-addr)
\ Parse the input line for a string delimited by the character char or
\ the end of line character. The terminating character or the end of line
\ character is not included in the parsed string.
\ Copy the parsed string as a counted string to a temporary buffer.
\ Add a space to the end of the string, do not include this space
\ in the strings length.
\ Return the address the counted string.
\ CHAR      The delimiter character
\ --
\ CS-ADDR   is the address of a counted string in a transient area
\           CS-ADDR points at:
\              - string length
\              - character string
\              - a space character (required for compatibility
\              with an earlier standard)
\           If the parse area is empty, or only contains delimiters
\           then the string length is zero

 help_pos parse
\ (char -- c-addr, u)
\ Read a CHAR delimited string from the current input line.
\ If the parsed string is empty then u = 0.
\ CHAR      The delimiter character
\ --
\ C-ADDR    Address of the parsed string in the current input buffer
\ U         Size of the parsed string, = 0 if parsed area is empty

 help_pos [char]
\ (-- char)
\ Compile time action:
\   Parse over any consecutive space characters in the input line.
\   Parse the current input line for a space-delimited string.
\   Discard all parsed characters except the first character.
\   Compile this character in to the current definition.
\   Compile in code to fullfill the following run time action:
\ Place char on the stack.
\ No input parameters
\ --
\ CHAR      The found character

 help_pos char
\ (-- char)
\ Parse over any consecutive space characters in the input line.
\ Parse the current input line for a space-delimited string.
\ Discard all parsed characters except the first character.
\ Return this character on the stack.
\ No input parameters
\ --
\ CHAR      The found character

 help_pos then
\ (--)
\ Used as part of an IF THEN or IF ELSE THEN  or  AHEAD THEN   flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type IF or ELSE or AHEAD then resolve the link,
\   else trap to an error handler
\ No input parameters
\ --
\ No output parameters

 help_pos else
\ (--)
\ Used as part of an IF THEN or IF ELSE THEN flow control construct.
\ Compile time action:
\   Compile in an unconditional jump, and push a related ELSE link
\   request on to the control stack.
\   Swap the top two control stack link requests.
\   Pop a link request from the control stack.
\   If the request is of type IF then resolve the link,
\   else trap to an error handler.
\ No input parameters
\ --
\ No output parameters

 help_pos if
\ (x --)
\ Used as part of an IF THEN or IF ELSE THEN flow control construct.
\ Compile time action:
\   Push an IF link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ If x <> 0 then continue execution with the instruction after the if.
\ If x = 0 then continue execution with the instruction that will be
\ specified by the resolved IF link request.
\ x          A cell sized value
\ --
\ No output parameters

 help_pos ahead
\ (--)
\ Create an unconditional jump to a later point.
\ Used as part of an AHEAD THEN or AHEAD ELSE THEN flow control construct.
\ Think of AHEAD as being equal to the combination   0 IF
\ Compile time action:
\   Push an IF link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ Continue execution with the instruction that will be specified by the
\ resolved IF link request.
\ No input parameters
\ --
\ No output parameters

 help_pos [
\ (--)
\ Used as part of an [ ... ] construct within a : definition
\ Compile time action:
\   Push an [ link request on to the control stack.
\   Set the interpreter in interactive mode
\ No input parameters
\ --
\ No output parameters

 help_pos ]
\ (--)
\ Used as part of an [ ... ] construct within a : definition
\ Pop a link request from the control stack.
\ If the request is of type [ then discard the link and
\ Set the interpreter in compilation mode,
\ else trap to an error handler.
\ No input parameters
\ --
\ No output parameters

 help_pos embedded?
\ (-- boolean)
\ Indicates whether the interpreter has an embedded program.
\ No input parameters
\ --
\ BOOLEAN    = 0 if interpreter has no embedded program
\            else the interpreter has an embedded program

 help_pos i
\ (-- n|u)
\ Used with a  DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow
\ construction to obtain the loop index.
\ Compile time action:
\   If not called within a loop construct, then a trap
\   to an error handler occurs.
\   Else compile in code to fullfill the following run time action:
\ Obtain the u-index value for the loop the control stack.
\ No input parameters
\ --
\ n|u        The loop index value for the loop

 help_pos limit
\ (-- n|u)
\ Used within a  DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow
\ construction to obtain the maximum loop index.
\ Compile time action:
\   If not called within a loop construct, then a trap
\   to an error handler occurs.
\   Else compile in code to fullfill the following run time action:
\ Obtain the u-index value for the loop the control stack.
\ No input parameters
\ --
\ n|u        The loop index value for the loop

 help_pos j
\ (-- n|u)
\ Used with a nested a DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow
\ construction to obtain the loop index of the outer loop.
\ Compile time action:
\   If not called within a nested loop construct, then a trap
\   to an error handler occurs.
\   Else compile in code to fullfill the following run time action:
\ Obtain the u-index value for the outer loop from the control stack.
\ No input parameters
\ --
\ n|u        The loop index value from the outer DO LOOP

 help_pos exit
\ (--)
\ Force the currently running definition to return control to the
\ definition that called it.
\ If used within a DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow control
\ construct, then it will automatically de-nest such contructs.
\ i.e. you do not need to call   UNLOOP  once for each level!
\ No input parameters
\ --
\ No output parameters

 help_pos unloop
\ (--)
\ Used within a DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow control construct.
\ Compile time action:
\   If there is no unresolved do or ?do link request on the control stack,
\   then  trap to an error handler.
\   Else compile in code to fullfill the following run time action:
\ Discard the u-end and u-index values from the control stack.
\ No input parameters
\ --
\ No output parameters

 help_pos leave
\ (--)
\ Used within a DO LOOP, DO +LOOP, ?DO LOOP or ?DO +LOOP flow control construct.
\ Forces an immediate, and tidy exit from such a construct.
\ Compile time action:
\   If there is an unresolved DO or ?DO link request on the control stack,
\   then place a leave link request underneath the DO or ?DO link request,
\   else trap to an error handler.
\   Compile in code to fullfill the following run time action:
\ Discard the u-end and u-index values from the control stack and continue
\ execution with the instruction that will be specified by the resolved LEAVE
\ link request
\ No input parameters
\ --
\ No output parameters

 help_pos loop
\ (-- |(u-end, u-index))
\ Used as part of a DO LOOP or ?DO LOOP flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type DO or ?DO then resolve the link,
\   else trap to an error handler.
\   Pop and resolve all subsequent link requests on the control
\   stack if they are of type leave.
\   Compile in code to fullfill the following run time action:
\ Retrieve u-end and u-index from the control stack.
\ Increment u-index by 1.
\ If the u-index is less than u-end then jump back to the partner
\ DO or ?DO command.(-- u-end, u-index)
\ If the u-index is not less than u-end then discard u-end and
\ u-index and proceed by executing the instruction immediately
\ after the loop command.(--)
\ No input parameters
\ --
\ No output parameters if LOOP terminated
\                      else
\ u-end      The terminating value in the flow control construct
\ u-index    The loop index value in the flow control construct

 help_pos +loop
\ (u -- |(u-end, u-index))
\ Used as part of a DO +LOOP or ?DO +LOOP flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type DO or ?DO then resolve the link,
\   else trap to an error handler.
\   Pop and resolve all subsequent link requests on the control
\   stack if they are of type leave.
\   Compile in code to fullfill the following run time action:
\ Retrieve u-end and u-index from the control stack.
\ Increment u-index by u.
\ If u-index is less than u-end then jump back to the partner
\ DO or ?DO command.(-- u-end, u-index)
\ If u-index is not less than u-end then discard u-end and
\ u-index and proceed by executing the instruction immediately
\ after the +LOOP command.(--)
\ No input parameters
\ --
\ No output parameters if LOOP terminated
\                      else
\ u-end      The terminating value in the flow control construct
\ u-index    The loop index value in the flow control construct

 help_pos do
\ (u-end, u-index --)
\ Used as part of a DO LOOP or DO +LOOP flow control construct.
\ Compile time action:
\   Push a DO link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ Pop the values u-end and u-start from the stack,
\ and place them on the control stack
\ Used in the form
\   10 0 DO  ... LOOP
\   the code between DO and LOOP will be executed with indices 0..9
\ u-end      The terminating value in the flow control construct
\ u-index    The loop index value in the flow control construct
\ --
\ No output parameters

 help_pos ?do
\ (u-end, u-index --)
\ Used as part of a ?DO LOOP or ?DO +LOOP flow control construct.
\ Compile time action:
\   Push a ?DO link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ Pop the values u-end and u-start from the stack.
\ If the values are equal, then discarded them and continue
\ execution with the first instruction after the matching
\ LOOP or +LOOP.
\ If the values are not equal, place them on control stack and
\ continue execution with the instruction immediately after
\ the ?DO command
\ u-end      The terminating value in the flow control construct
\ u-index    The loop index value in the flow control construct
\ --
\ No output parameters

 help_pos until
\ (x --)
\ Used as part of a BEGIN UNTIL flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type BEGIN then resolve the link,
\   else trap to an error handler.
\   Compile in code to fullfill the following run time action:
\ If x <> 0 then continue by executing the instruction after the
\ UNTIL command, else continue execution with the instruction
\ immediately after the BEGIN command.
\ x          A cell sized value
\ --
\ No output parameters

 help_pos repeat
\ (--)
\ Used as part of a BEGIN WHILE REPEAT flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type BEGIN then resolve the link,
\   else trap to an error handler.
\   Pop a second link request from the control stack.
\   If the request is of type WHILE then resolve the link,
\   else trap to an error handler.
\   i.e.  BEGIN ... REPEAT   without a WHILE is illegal.
\   Compile in code to fullfill the following run time action:
\ Continue execution with the instruction immediately after the BEGIN command
\ No input parameters
\ --
\ No output parameters

 help_pos while
\ (x --)
\ Used as part of a BEGIN WHILE REPEAT
\ flow control construct.
\ Compile time action:
\   Push a WHILE link request on to the control stack.
\   Swap the top two control stack link requests.
\   Compile in code to fullfill the following run time action:
\ If x = 0 then continue by executing the first instruction after
\ the matching repeat command.
\ Else continue by executing the first instruction after the WHILE command.
\ x          A cell sized value
\ --
\ No output parameters

 help_pos begin
\ (--)
\ Used as part of an BEGIN WHILE REPEAT or BEGIN UNTIL flow control construct.
\ Compile time action:
\   Push a BEGIN link request on to the control stack.
\ No input parameters
\ --
\ No output parameters

 help_pos .(
\ (--)
\ Parse the current input line until either the character ) is met
\ or the end of line condition is encounted.
\ The parsed characters will be displayed.
\ If the input stream is a file, then refill the input buffer and continue
\ parsing until either the the character ) is meet or the end of file
\ condition is encounted.
\ Used in the form .( comment a definition )
\ No input parameters
\ --
\ No output parameters

 help_pos (
\ (--)
\ Parse the current input line until either the character ) is meet
\ or the end of line condition is encounted.
\ The parsed characters will be discarded.
\ If the input stream is a file, then refill the input buffer and continue
\ parsing until either the character ) is meet or the end of file condition
\ is encounted.
\ Used in the form ( comment a definition )
\ No input parameters
\ --
\ No output parameters

\ (delim -- cs-addr)
\ Reads a delimited string from the CURRENT input buffer .
\ If input buffer is empty it will read from the next input
\ line , until a non zero string is read .
\ If the input is non zero it will terminate reading on
\ either DELIM or END_OF_LINE .
\ If used in IMMED mode
\   address = address of a temporary buffer
\ If used in COMPILE mode
\   string will be COMPILED
\   address = address of counted string in vocabulary

\ (delim -- cs-addr)
\ Reads a delimited string from the CURRENT input buffer .
\ If used in IMMED mode
\   address = address of a temporary buffer
\ If used in COMPILE mode
\   string will be COMPILED
\   address = address of counted string in vocabulary

 help_pos ."
\ (--)
\ Used to cause a " delimited character string to be displayed.
\ When used in command definition mode:
\   Parse the input line until the character " is meet or the end
\   of line condition is encountered.
\   Compile the string in to the current definition so that at run
\   time the string will be displayed.
\ When used in interactive mode:
\   Parse the input line until the character " is meet or the end
\   of line condition is encountered.
\   Display the parsed string
\ No input parameters
\ --
\ No output parameters

 help_pos s"
\ (-- c-addr , u)
\ Parse the input line for a string delimited by the character " or
\ an end of line character.
\ The terminating " character or the end of line character is not included
\ in the parsed string.
\ When used in command definition mode:
\   Compile the parsed string and its length in to the current definition.
\   Compile in code to fullfill the following run time action:
\   Place the string address c-addr and the length u on the stack.
\ When used in interactive mode:
\   Copy the parsed characters to a buffer.
\   The address of this buffer c-addr and the length u are then
\   placed on the stack.
\ No input parameters
\ --
\ C-ADDR    Address of read in character string
\ U         Length of character string

 help_pos s^
\ (-- c-addr , u)
\ Parse the input line for a string delimited by the character  or
\ an end of line character.
\ The terminating  character or the end of line character is not included
\ in the parsed string.
\ When used in command definition mode:
\   Compile the parsed string and its length in to the current definition.
\   Compile in code to fullfill the following run time action:
\   Place the string address c-addr and the length u on the stack.
\ When used in interactive mode:
\   Copy the parsed characters to a buffer.
\   The address of this buffer c-addr and the length u are then
\   placed on the stack.
\ No input parameters
\ --
\ C-ADDR    Address of read in character string
\ U         Length of character string

 help_pos and
\ (x1, x2 -- x3)
\ X3 is the bit_wise AND of X1 with X2
\ x1        A cell sized value
\ x2        A cell sized value
\ --
\ x3        A cell sized value = bit_wise AND of X1 with X2

 help_pos or
\ (x1, x2 -- x3)
\ X3 is the bit_wise OR of X1 with X2
\ x1        A cell sized value
\ x2        A cell sized value
\ --
\ x3        A cell sized value = bit_wise OR of X1 with X2

 help_pos xor
\ (x1, x2 -- x3)
\ X3 is the bit_wise EXCLUSIVE OR of X1 with X2
\ x1        A cell sized value
\ x2        A cell sized value
\ --
\ x3        A cell sized value = bit_wise EXCLUSIVE OR of X1 with X2

 help_pos lshift
\ (x1, u -- x2)
\ The cell sized value x1 is shifted u bits to the left.
\ The U least significant bits are set to zero
\ x1         A cell sized value
\ u          Number of bit shifts to be done
\ --
\ x2         A cell sized value, = x1 shifted U bit to the right

 help_pos rshift
\ (x1, u -- x2)
\ The cell sized value x1 is shifted u bits to the right.
\ The U most significant bits are set to zero
\ x1         A cell sized value
\ u          Number of bit shifts to be done
\ --
\ x2         A cell sized value, = x1 shifted U bit to the right

 help_pos popcount
\ (x1 -- x2)
\ Count the bits set in X1 and return as x2 o
\ x1        A cell sized value
\ --
\ x2        A cell sized value, count of set bits in X1

 help_pos invert
\ (x1 -- x2)
\ All the bits of the cell sized value x1 are inverted.
\ x1        A cell sized value
\ --
\ x2        A cell sized value, = all bits of x1 inverted

 help_pos error.num
\ (  -- u)
\ Returns the current internal value  of USER_ERROR  set by some
\ double precision and floating point  operations.
\ THe internal value is automatically set to zero by this command.
\
\ no input parameters
\ --
\ U         current internal value  of USER_ERROR

 help_pos +
\ (n1|u1, n2|u2 -- n3|u3)
\ The number n1|u1 is added to the number n2|u2 to give the result n3|u3.
\ There is no detection of number /sign overflow.
\ n1|u1     A signed n or unsigned u integer value
\ n2|u2     A signed n or unsigned u integer value
\ --
\ n3|u3     A signed n or unsigned u integer value, the result
\           of the operation   n1|u1  +  n2|u2

 help_pos -
\ (n1|u1, n2|u2 -- n3|u3)
\ The number n2|u2 is subtracted from the number n1|u1 to give the result n3|u3.
\ There is no detection of number /sign underflow.
\ n1|u1     A signed n or unsigned u integer value
\ n2|u2     A signed n or unsigned u integer value
\ --
\ n3|u3     A signed n or unsigned u integer value, the result
\           of the operation   n1|u1  -  n2|u2

 help_pos /
\ (n1|u1, n2|u2 -- n3|u3)
\ The number n1|u1 is divided to the number n2|u2 to give the result n3|u3.
\ If n2|u2 = 0 then there is a trap to an error handler
\ n1|u1     A signed n or unsigned u integer value
\ n2|u2     A signed n or unsigned u integer value
\ --
\ n3|u3     A signed n or unsigned u integer value, the result
\           of the operation   n1|u1  /  n2|u2

 help_pos *
\ (n1|u1; n2|u2 -- n3|u3)
\ The number n1|u1 is multiplied to the number n2|u2 to give the result n3|u3.
\ There is no detection of number /sign overflow.
\ n1|u1     A signed n or unsigned u integer value
\ n2|u2     A signed n or unsigned u integer value
\ --
\ n3|u3     A signed n or unsigned u integer value, the result
\           of the operation   n1|u1  *  n2|u2

 help_pos negate
\ (n -- -n)
\ The signed integer n is negated to give the signed integer  -n
\ n         A signed integer value
\ --
\ -n        The negate of n.

 help_pos evaluate
\ (c-addr, u  --)
\ Passes the string given by c-addr,u to the command line interpreter
\ C-ADDR    Address of a character string
\ U         Length of character string
\ --
\ No output parameters

 help_pos emit
\ (char --)
\ Display the character value char
\ U         Length of character string
\ CHAR      Character value to be displayed
\ --
\ No output parameters

 help_pos .\0
\ (c-addr --)
\ The zero terminated character string found at c-addr
\ will be sent to the current output device
\ C-ADDR    Address of a zero terminated character string
\ --
\ No output parameters

 help_pos type
\ (c-addr ,u --)
\ Display the character string at the address c-addr of length u.
\ However: where is it "displayed"?
\   default: to a "terminal" like window
\   alternatively:
\   1) to a user defined definition
\      user definition must have the action   ( c-addr , -- )
\      If user definition is    say   myCode
\      Then the following will cause  the    c-addr ,u    passed to TYPE to be "passed" to   myCode
\        ' myCode   catch_on
\   use the following to return output to the   default
\         catch_off
\   Note: the characters string(s) passed to   TYPE   when in catch mode, are stored in a buffer
\   until a  CR or LF character is encountered, at which point the buffer (excluding the CR and LF)
\   will be "passed" to   myCode (and the buffer automatically emptied).
\   When if  catch  mode, the currently stored buffer can be accessed (and the buffer automatically emptied) by
\   using the built in definition      catch_it   ( c-addr , -- )
\   2) to a file
\   e.g. use something like (no error handling given in the example)
\       s" c:\myfile.txt"    w/o   open-files  drop pipe.to.file
\   from then on output goes to the file
\   use the following to return output to the   default
\      stdout   pipe.to.file
\   3) a Screen Object (SOB) that can process an EM_SETSEL message
\   e.g. use something like (no error handling given in the example)
\      1 sob@gui sob=show
\      4   s"           "  sob.edit.multi=new   sob@sys.id
\      output=hwnd
\   use the following to return output to the   default
\      0  output=hwnd
\ C-ADDR    Address of a character string
\ U         Length of character string
\ --
\ No output parameters

 help_pos flush
\ (--)
\ Ensures that all text output to the Command Line Interpreter has been displayed/handled.
\ No input parameters
\ --
\ No output parameters

 help_pos catch_on
\ (xt --)
\ Future output to the display will be stored in a buffer and not passed
\ to the display.
\ When the end of line character (carriage return) is sent to the
\ display then all characters in the buffer will be passed to the
\ command whose eXecution Token is XT, and whose stack effect
\ is (c-addr, u --) where c-addr is the start address of the buffer, and
\ u is the number of characters including the end of line character.
\ The character string will be zero terminated, this zero will not be
\ included in the string length u.
\ When CATCH_OFF is executed the eXecution Token XT will be called again
\ possible with U = 0, possibly with a buffer without a end of line character.
\ XT         An eXecution Token
\ --
\ No output parameters

 help_pos catch_off
\ (--)
\ If output was redirected by means of CATCH_ON, then pass the
\ stored character string to the eXecution Token used by CATCH_ON.
\ Reset the handling so that future character output is sent to the display.
\ No input parameters
\ --
\ No output parameters

 help_pos catch_it
\ (-- c-addr, u)
\ If output was redirected by means of CATCH_ON, then do not pass the
\ currently stored character string to the eXecution Token used by CATCH_ON, instead
\ return the currently stored character string to this definition.
\ Reset the handling so that future character output is sent to the display.
\ No input parameters
\ --
\ No output parameters

 help_pos pad
\ (-- c-addr)
\ Return the address of a general-purpose scratch pad area of 1024 bytes.
\ No input parameters
\ --
\ C-ADDR     Address of a general-purpose scratch pad area

 help_pos app.dataspace@free
\ (-- u)
\ Return the number of address units of the virtual machines dataspace that have not been
\ allocated to definitions.   U is the number of free address units in the dataspace
\ No input parameters
\ --
\ U          The number of free address units in the dataspace

 help_pos fill.char
\ (c-addr, u, char --)
\ Place u copies of the character char in consecutive character
\ aligned memory locations starting at c-addr.
\ C-ADDR    A character aligned memory address
\ U         Number of characters to be replicated
\ CHAR      Character value to be replicated
\ --
\ No output parameters

 help_pos fill.byte
\ (c-addr, u, Byte --)
\ Place u copies of the BYTE in consecutive BYTE
\ aligned memory locations starting at c-addr.
\ C-ADDR    A BYTE aligned memory address
\ U         Number of BYTES to be replicated
\ BYTE      Character value to be replicated
\ --
\ No output parameters

 help_pos \
\ (--)
\ Discard the current input line.
\ No input parameters
\ --
\ No output parameters

 help_pos //
\ (--)
\ Discard the input line.
\ Is included for compatibility with "C" header files
\ No input parameters
\ --
\ No output parameters

 help_pos nop
\ (--)
\ The No Operation command. Do nothing, a null command.
\ No input parameters
\ --
\ No output parameters

 help_pos rot
\ (x1, x2, x3 -- x2, x1, x3)
\ The top three cells on the stack are rotated.
\ x1         A cell value, the third cell on the stack
\ x2         A cell value, the second cell on the stack
\ x3         A cell value, the top cell on the stack
\ --
\ x2         A cell value, the second cell on the stack
\ x3         A cell value, the top cell on the stack
\ x1         A cell value, the third cell on the stack

 help_pos 2drop
\ (x1, x2 --)
\ Discard the top two cell on the stack
\ x1         A cell value
\ x2         A cell value
\ --
\ No output parameters

 help_pos 2swap
\ (x1,x2, x3,x4 -- x3,x4, x1,x2)
\ Exchange the top two cells-pairs on the stack.
\ x1         A cell value, lower cell second cell pair
\ x2         A cell value, upper cell second cell pair
\ x3         A cell value, lower cell first cell pair
\ x4         A cell value, upper cell first cell pair
\ --
\ x3         A cell value
\ x4         A cell value
\ x1         A cell value
\ x2         A cell value

 help_pos 2dup
\ (x1,x2 -- x1,x2, x1,x2)
\ The top cell-pair on the stack is duplicated
\ x1         A cell value
\ x2         A cell value
\ --
\ x1         A cell value
\ x2         A cell value
\ x1         A cell value
\ x2         A cell value

 help_pos /mod
\ (n1, n2 -- n-rem, n-quot)
\ The signed integer n1 is divided by the signed integer n2 to give
\ signed integer quotient and remainder result.
\ If n2 = 0 then a trap to an internal error handler occurs.
\ n1        A signed integer
\ n2        A signed integer
\ --
\ n-rem     A signed integer, the remainder of the operation n1 / n2
\ n-quot    A signed integer, the quotient of the operation n1 / n2

 help_pos align
\ (--)
\ If the dataspace pointer is not CELL aligned, then align it.
\ No input parameters
\ --
\ No output parameters

 help_pos aligned
\ (addr -- a-addr)
\ If the address addr is not CELL aligned then align it.
\ Return the aligned address as a-addr
\ addr      An address
\ --
\ a-addr    A cell aligned address

 help_pos b,
\ (char --)
\ Compile the character char into the next free character sized
\ location in the dataspace .
\ The free dataspace pointer incremented to the next character address.
\ The free dataspace pointer is NOT necessarily CELL aligned!
\ CHAR      Character to be stored in dataspace
\ --
\ No output parameters

 help_pos  c,
\ (char --)
\ Compile the character char into the next free character sized
\ location in the dataspace .
\ The free dataspace pointer incremented to the next character address.
\ The free dataspace pointer is NOT necessarily CELL aligned!
\ CHAR      Character to be stored in dataspace
\ --
\ No output parameters

 help_pos +!
\ (n|u, a-addr --)
\ Add the value n|u to the cell sized location at the cell
\ aligned memory address a-addr
\ n|u       A signed or unsigned single precision integer
\ a-addr    A cell aligned address
\ --
\ no return parameters

 help_pos >\0
\ (c-addr, u -- c-addr0 )
\ Convert the character string at c-addr and of length U characters
\ in to a zero terminated string
\ C-ADDR    Address of a character string
\ U         Number of characters in the string
\ --
\ C-ADDRO   Address of a zero terminated character string

 help_pos count
\ (cs-addrc -- c-addr, u)
\ Convert the counted character string at cs-addr in to a
\ character address  located at c-addr and a length U.
\ Return the address and length of the  CHARACTER string.
\ The string is not copied to a new location.
\ CS-ADDR   Address of a counted character string
\ --
\ C-ADDR    Address of a character string
\ U         Number of characters in the  string

 help_pos um*
\ (u1, u2 -- ud)
\ The number u1 is multiplied by the number u2 to give
\ the double precision integer result ud.
\ u1        A unsigned integer
\ u2        A unsigned integer
\ --
\ ud        A double precision unsigned integer created
\           by u1 * u2

 help_pos ul*
\ (ud1, ud2 -- ud)
\ The unsigned double precision integer u1 is multiplied
\ by unsigned double precision integer u2 to give
\ the unsigned double precision integer result ud.
\ If the result exceeds an unsigned double precision integer
\ then the value ERROR.NUM will return a non-zero value.
\
\ u1        A unsigned double precision integer
\ u2        A unsigned double precision integer
\ --
\ ud        A double precision unsigned integer created
\           by ud1 * ud2

 help_pos um/mod
\ (ud, u1 -- u-rem, u-quot)
\ The double precision unsigned integer ud is divided by the unsigned
\ integer u1 to give the unsigned resulting quotien and remainder.
\ If u1 = 0 then a trap to an internal error handler occurs.
\ ud        A double precision unsigned integer
\ u1        A unsigned integer
\ --
\ u-rem     A unsigned integer, the remainder of the operation ud / u1
\ u-quot    A unsigned integer, the quotient of the operation ud / u1

 help_pos? *?mod
\ (n1, n2, n3 -- n-rem , n-quot)
\ Multiply the signed integer n1 by the signed integer n2 to
\ create a temporary internal double precision value d.
\ Divide d by the signed integer n3
\ If n3 = 0 then a trap occurs to an internal error handler.
\ If the quotient is too large to fit a single precision signed integer
\ then a trap occurs to an internal error handler
\ n1        A signed integer
\ n2        A signed integer, create n1 * n2 to give DN
\ n3        A signed integer, create DN / n3
\ --
\ n-quot    A signed integer, the quotient of  DN / n3
\ n-rem     A signed integer, the remainder of  DN / n3

 help_pos? *?
\ (n1, n2, n3 -- n-quot)
\ Multiply the signed integer n1 by the signed integer n2 to
\ create a temporary internal double precision value d.
\ Divide d by the signed integer n3, the single precison signed
\ quotient of this division is n4.
\ If n3 = 0 then a trap occurs to an internal error handler.
\ If the quotient is too large to fit a single precision signed integer
\ then a  trap occurs to an internal error handler
\ n1        A signed integer
\ n2        A signed integer, create n1 * n2 to give DN
\ n3        A signed integer, create DN / n3
\ --
\ n-quot    A signed integer, the quotient of  DN / n3

 help_pos u<
\ (u1, u2 -- bool)
\ Returns bool = TRUE if and only if u1 is less than u2, else bool = FALSE
\ u1        A unsigned integer
\ u2        A unsigned integer
\ --
\ bool      = TRUE if and only if u1 is less than u2, else bool = FALSE

 help_pos u.
\ (u --)
\ The unsigned integer u is displayed in free field format with a
\ trailing space character
\ U         A single precision unsigned integer
\ --
\ No output parameters

 help_pos .
\ (n --)
\ The signed integer n is displayed in free field format with a
\ trailing space character
\ n         A single precision signed integer
\ --
\ No output parameters

 help_pos #
\ (ud1 -- ud2)
\ Divide ud1 by the value in BASE. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ ud1       A double precision unsigned integer, the number to be divided by
\           the contents of BASE
\ --
\ ud2       A double precision unsigned integer, the quotient after ud1 has been
\           divided by the contents of BASE.

 help_pos #t
\ (ud1 -- ud2)
\ Divide ud1 by the value in 10t. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ ud1       A double precision unsigned integer, the number to be divided by 1t
\ --
\ ud2       A double precision unsigned integer, the quotient after ud1 has been
\           divided by the 10t

 help_pos #h
\ (ud1 -- ud2)
\ Divide ud1 by the value in 16t. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ ud1       A double precision unsigned integer, the number to be divided by 1t
\ --
\ ud2       A double precision unsigned integer, the quotient after ud1 has been
\           divided by the 16t

 help_pos #s
\ (ud1 -- ud2)
\ Divide ud1 by the value in BASE. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ Repeat until UD2 = 0
\ ud1       A double precision unsigned integer, the number to be divided by
\           the contents of BASE
\ --
\ ud2       = 0 A double precision unsigned integer, the quotient after ud1 has been
\           repeatedly divided by the contents of BASE.

 help_pos #st
\ (ud1 -- ud2)
\ Divide ud1 by the value 10t. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ Repeat until UD2 = 0
\ ud1       A double precision unsigned integer, the number to be divided by 10t
\           the contents of BASE
\ --
\ ud2       = 0 A double precision unsigned integer, the quotient after ud1 has been
\           repeatedly divided by the 16t.

 help_pos #sh
\ (ud1 -- ud2)
\ Divide ud1 by the value 16t. Place the remainder in the PICTURED
\ NUMERIC OUTPUT STRING, and leave the unsigned double quotient UD2.
\ Repeat until UD2 = 0
\ ud1       A double precision unsigned integer, the number to be divided by 16t
\           the contents of BASE
\ --
\ ud2       = 0 A double precision unsigned integer, the quotient after ud1 has been
\           repeatedly divided by the 16t.

 help_pos <#
\ (--)
\ The PICTURED NUMERIC OUTPUT STRING is prepared for use with a double
\ precision unsigned integer.
\ Any PICTURED NUMERIC OUTPUT that was not previously completed will be discarded.
\ No input parameters
\ --
\ No output parameters

 help_pos #>
\ (ud -- c-addr, u)
\ The unsigned double UD is dropped and the address of the PICTURED
\ NUMERIC OUTPUT STRING and its length are left on the stack.
\ ud        A double precision signed integer
\ --
\ c-addr    Address of the Picture Numeric Output string
\ u         Length of the Picture Numeric Output string

 help_pos sign
\ (n --)
\ IF  N is negative then a minus sign will be added to the begining of the
\ next PICTURED NUMERIC OUTPUT STRING unless overwritten by other
\ other words that use the PICTURED NUMERIC OUTPUT STRING
\ N          A signed integer
\ --
\ No output parameters

 help_pos hold
\ (char --)
\ Insert the character CHAR to the front of the PICTURED
\ NUMERIC OUTPUT STRING
\ char       A character value
\ --
\ No output parameters

 help_pos abs
\ (n -- u)
\ Converts n to its absolute unsigned value u.
\ n          A signed integer
\ --
\ u          A unsigned integer = to the absolute value of n

 help_pos >number
\ (ud1, c-addr1, u1 -- ud2, c-addr2, u2)
\ Read in the first character of the string (c-addr1, u1).
\ If the character is convertible to a digit using the radix in
\ BASE then: convert the character, multiple ud1 by the radix and
\ add the converted digit, increment c-addr1 to next character,
\ decrement u1.
\ Repeat this sequence until the string is exhausted or a
\ non-convertable character is encounted.
\ Note: + and - are not valid digits!
\ UD1        A unsigned double precision integer
\ C-ADDR1    Character address of the string to be converted
\ U1         Number of characters in string
\ --
\ C-ADDR2    Character address of the first non convertable character in
\            the string c-addr1, u1
\ U2         Number of characters in string c-addr1, u1 that were not convertable
\ UD2        A unsigned double precision integer

 help_pos ud+
\ (ud1, ud2 -- ud)
\ unsigned double UD = unsigned double  UD1 + unsigned double UD2
\ UD1         Unsigned double integer
\ UD2         Unsigned double integer
\ --
\ UD3         Unsigned double integer = UD1 + UD2

 help_pos ud*
\ (ud1, ud2 -- ud)
\ unsigned double UD = unsigned double  UD1 * unsigned double UD2
\ UD1         Unsigned double integer
\ UD2         Unsigned double integer
\ --
\ UD3         Unsigned double integer = UD1 * UD2

 help_pos m*
\ (u1, u2 -- ud)
\ unsigned double UD = unsigned single  U2 * unsigned single U1
\ U1          Unsigned single integer
\ U2          Unsigned single integer
\ --
\ UD          Unsigned double integer = U1 * U2

 help_pos fm/mod
\ (dtop, bottom   -- frem, fquot)
\ Divide the double precision integer value   dtop
\ by  the single precision value              bottom
\ and return as single precision values
\    the floored    remainder
\    the floored    quotient
\ DTOP       double precision integer
\ BOTTOM     single precision integer
\ --
\ FREM       single precision integer
\ FQUOT      single precision integer

 help_pos min
\ (n1, n2 -- n3)
\ Returns n3, the smaller of the two signed integers n1 and n2.
\ n1         A signed integer
\ n2         A signed integer
\ --
\ n3         A signed integer = the smaller of the two signed integers n1 and n2

 help_pos max
\ (n1, n2 -- n3)
\ Returns n3, the larger of the two signed integers n1 and n2.
\ n1         A signed integer
\ n2         A signed integer
\ --
\ n3         A signed integer = the larger of the two signed integers n1 and n2

 help_pos mod
\ (n1, n2 -- n3)
\ The signed integer n1 is divided to the signed integer n2.
\ The remainder of the division is left as n3.
\ If n2 = 0 then a trap occurs to an internal error handler.
\ The sign of the result is always the same as the sign of n1.
\ n1         A signed integer
\ n2         A signed integer
\ --
\ n3         A signed integer

 help_pos d/
\ (ud1, ud2 --  udrem, udquot)
\  Divide the unsigned double integer values   ud1 by ud2
\  returning
\        udremainder  the unsigned double integer remainder
\        udquotient   the unsigned double integer quotient
\ UD1        unsigned double precision integer
\ UD2        unsigned single precision integer
\ --
\ UDREM      unsigned double precision integer
\ UDQUOT     unsigned double precision integer

 help_pos l/
\ (ud1, ud2 --  udrem, udquot)
\  Divide the unsigned double integer values   ud1 by ud2
\  returning
\        udremainder  the unsigned double integer remainder
\        udquotient   the unsigned double integer quotient
\ UD1        unsigned double precision integer
\ UD2        unsigned single precision integer
\ --
\ UDREM      unsigned double precision integer
\ UDQUOT     unsigned double precision integer

 help_pos 2@
\ (a-addr -- x1, x2)
\ Read the two cell-sized values x1 and x2 from the cell aligned address a-addr
\ x2 is read from the address a-addr, x1 is read from the next cell after a-addr
\ If a-addr is not cell aligned then a trap to an internal error handle occurs.
\ a-addr     A cell aligned memory address
\ --
\ x1         A cell sized value
\ x2         A cell sized value

 help_pos 2!
\ (x1 ,x2 ,a-addr --)
\ Write the two cell-sized values x1 x2, to the cell aligned address a-addr.
\ x2 is written to the address a-addr, x1 is written to the next cell after a-addr
\ If a-addr is not cell aligned then a trap to an internal error handle occurs.
\ x1         A cell sized value
\ x2         A cell sized value
\ a-addr     A cell aligned memory address
\ --
\ No output parameters

 help_pos s>d
\ (n -- dn)
\ Convert a single precision signed integer to a double precision signed integer
\ n          A single precision signed integer
\ --
\ dn         The double precision signed integer equal in value to n

 help_pos 2over
\ (x1 ,x2 ,x3 ,x4 -- x1, x2, x3, x4, x1, x2)
\ The second cell-pair on the stack is copied to the top
\ x1         A cell value
\ x2         A cell value
\ x3         A cell value
\ x4         A cell value
\ --
\ x1         A cell value
\ x2         A cell value
\ x3         A cell value
\ x4         A cell value
\ x1         A cell value
\ x2         A cell value

\ (x1, x2 --)
\ The two cell-sized values x1 and x2 are complied in to
\ the dataspace. First X2, then X1
\ x1        A cell sized value
\ x2        A cell sized value
\ --
\ No output parameters

 help_pos 2*
\ (x1 -- x2)
\ The cell sized value x1 is shifted 1 bit to the left.
\ The new least significant bit is cleared.
\ x1         A cell sized value
\ --
\ x2         A cell sized value, = x1 shifted 1 bit to the left

 help_pos 2/
\ (x1 --  x2)
\ The cell sized value x1 is shifted 1 bit to the right.
\ The most significant bit retains its value
\ x1         A cell sized value
\ --
\ x2         A cell sized value, = x1 shifted 1 bit to the right

\ Find the definition with the name given by the counted string
\ c-addr , u   in the word list identified by WID
\ If not found  return 0
\ else return the eXecution Token associated with the WORD
\       and the value  1 if the definition is immediate
\       else          -1
\ C-ADDR     Character string address
\ U          Length of character string
\ WID        Identity of a word-list
\ --
\   Return parameters are one of:
\ 0          if not found
\   OR
\ XT         eXecution Token of definition
\ 1          if definition is immediate
\   OR
\ XT         eXecution Token of definition
\ -1         if definition is not immediate

\ Find the definition with the name given by the counted string
\ c-addr , u   in the word list identified by WID
\ If not found  return 0
\ else return the eXecution Token associated with the WORD
\       and the value  1 if the definition is immediate
\       else          -1
\ C-ADDR     Character string address
\ U          Length of character string
\ WID        Identity of a word-list
\ --
\   Return parameters are one of:
\ 0          if not found
\   OR
\ XT         eXecution Token of definition
\ 1          if definition is immediate
\   OR
\ XT         eXecution Token of definition
\ -1         if definition is not immediate

\ (c-addr, u, wid -- 0|(xt, 1)|(xt, -1))
\ Find the definition with the name given by the counted string
\ c-addr , u   in the word list identified by WID
\ If not found  return 0
\ else return the eXecution Token associated with the WORD
\       and the value  1 if the definition is immediate
\       else          -1
\ C-ADDR     Character string address
\ U          Length of character string
\ WID        Identity of a word-list
\ --
\   Return parameters are one of:
\ 0          if not found
\   OR
\ XT         eXecution Token of definition
\ 1          if definition is immediate
\   OR
\ XT         eXecution Token of definition
\ -1         if definition is not immediate

\ (cs-addr -- cs-addr, 0 | (xt, 1) | (xt, -1)  )
\  Find the definition with the name given by the counted string at address
\  cs-addr.
\  If not found  return  cs-addr  and 0
\  else return the eXecution Token associated with the WORD
\       and the value  1 if the definition is immediate
\       else          -1
\ CS-ADDR    a counted character string address
\ --
\   Return parameters are one of:
\ 0          if not found
\   OR
\ XT         eXecution Token of definition
\ 1          if definition is immediate
\   OR
\ XT         eXecution Token of definition
\ -1         if definition is not immediate

 help_pos max-length
\ (value  -- )
\ if value >  9  then this value will be used as the maximum length of a
\ line created by WORDS

 help_pos true
\ (-- TRUE)
\ Return the value associated with TRUE.
\ Be warned! In reality only the value FALSE is defined ( = 0 )
\ so TRUE is every thing that is NOT FALSE.
\ No input parameters
\ --
\ TRUE       Value associated with TRUE (sort of ! )

 help_pos false
\ (-- FALSE)
\ Return the value associated with FALSE. Always = 0.
\ No input parameters
\ --
\ FALSE      Value associated with FALSE

 help_pos bye
\ (--)
\ Causes the interpreter to terminate and return to the operating system
\ No input parameters
\ --
\ No output parameters

 help_pos restart
\ (--)
\ Causes the interpreter to execute any internal restart.
\ No input parameters
\ --
\ No output parameters

\ (x -- x, flag)
\ Return   FALSE  if X  is = or >0
\                 else returns TRUE
\ X        A single precision signed integer
\ --
\ X        A single precision signed integer
\ FLAG     = TRUE if X is negative
\          = else FALSE

 help_pos "ToUpper.in.situ
\ ( c-addrIN , uIN  -- c-addrIN , uIN )
\ Converts the character string at C_ADDR of length U characters in to
\ all upper case characters  --in situ--
\ C-ADDR     Character string address
\ U          Length of character string
\ --
\ C-ADDR     Character string address
\ U          Length of character string

 help_pos "ToUpper
\ ( c-addrIN , uIN  -- c-addrOUT , uOUT )
\ Converts the character string at C-ADDR of length U characters in to
\ all upper case characters.
\ Output is to a new memory area!
\ C-ADDRIN     Character string address
\ UIN          Length of character string
\ --
\ C-ADDROUT     Character string address
\ UOUT          Length of character string

 help_pos "ToLower
\ ( c-addrIN , uIN  -- c-addrOUT , uOUT )
\ Converts the character string at C-ADDR of length U characters in to
\ all lower case characters.
\ Output is to a new memory area!
\ C-ADDRIN     Character string address
\ UIN          Length of character string
\ --
\ C-ADDROUT     Character string address
\ UOUT          Length of character string

 help_pos "ToLower.in.situ
\ ( c-addrIN , uIN  -- c-addrIN , uIN )
\ Converts the character string at C-ADDR of length U characters in to
\ all lower case characters,  --in situ--
\ Output is to a new memory area!
\ C-ADDRIN     Character string address
\ UIN          Length of character string
\ --
\ C-ADDRIN     Character string address
\ UIN          Length of character string

 help_pos ToUpper
\ (char -- CHAR)
\ If  char   is a number with the ASCI value of a lower case letter (a..z)
\ then convert it to UPPER case.
\ X         Integer
\ --
\ X         Converted to UPPER case if relevant.

 help_pos ToLower
\ (CHAR -- char)
\ If  char   is a number with the ASCI value of an upper case letter (A..Z)
\ then convert it to lower case.
\ X         Integer
\ --
\ X         Converted to lower case if relevant.

 help_pos strlen
\ (c-addr -- c-addr , count)
\ Returns the number of characters found at the address c-addr
\ until a character with the value of zero is found.
\ The zero character is not included in the count.
\ C-ADDR    Address of the character string
\ --
\ C-ADDR    Address of the character string
\ COUNT     Number of characters remaining in the string

 help_pos bytelen
\ (c-addr -- c-addr , count)
\ Returns the number of BYTES found at the address c-addr
\ until a BYTE with the value of zero is found.
\ The zero BYTE is not included in the count.
\ C-ADDR    Address of the BYTE string
\ --
\ C-ADDR    Address of the BYTE string
\ COUNT     Number of BYTE remaining in the string

 help_pos on-error=xt
\ (-1|0|xt --)
\ Define how the program is to respond to internally detected errors.
\ If the stream is a file, then the file will be closed.
\ -1        Terminate the program, return to the operating system
\ 0         Run the internal error handler and enter interactive mode
\ XT        After running the internal error handler execute the
\           user defined routine with the eXecution Token xt.
\ --
\ No output parameters

 help_pos \\
\ (--)
\ Terminate the current input stream.
\ If the stream is a file, then the file will be closed.
\ No input parameters
\ --
\ No output parameters

    [then]
 help_pos sizeof(chars)
\ (u1 -- u2)
\ Return U2 the number of address units in U1 chars
\ U1         The number of characters
\ --
\ U2         =  number of address units in U1 chars

 help_pos sizeof(char)
\ (  -- u)
\ Return the number of address units in a char
\ No inputs
\ --
\ U1         =  number of address units in a char

 help_pos sizeof(byte)
\ (  -- u)
\ Return the number of address units in a BYTE
\ No inputs
\ --
\ U1         =  number of address units in a BYTE

 help_pos sizeof(cell)
\ (  -- u)
\ Return the number of address units in a CELL
\ No inputs
\ --
\ U          =  number of address units in a CELL

 help_pos value
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A cell sized value
\ --
\ No output parameters

 help_pos value(ptr)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A POINTER sized value
\ --
\ No output parameters

 help_pos value(float)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A FLOAT sized value
\ --
\ No output parameters

 help_pos value(2cell)
\ (x , y --)
\ Used in the form 12 34 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   45 67 TO FRED
\ X , Y         A DOUBLE sized value
\ --
\ No output parameters

 help_pos value(char)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the CHARACTER value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A CHARACTER sized value
\ --
\ No output parameters

 help_pos value(byte)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the CHARACTER value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A BYTE sized value
\ --
\ No output parameters

 help_pos value(word)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the CHARACTER value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A WORD sized value
\ --
\ No output parameters

 help_pos value(dword)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the CHARACTER value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A DWORD sized value
\ --
\ No output parameters

 help_pos value(int)
\ (x --)
\ Used in the form 12 VALUE FRED
\ Parse the input line for a space delimited string.
\ Create a new definition with the parsed string as its name.
\ Assign the value x to this definition such that when the
\ definition is called it returns the value x.
\ The value associated with FRED can be altered by use of
\ the TO command e.g.   123 TO FRED
\ X         A INT sized value
\ --
\ No output parameters

 help_pos to
\ (--)
\ Used in the form 12 TO FRED where FRED was created as a VALUE
\ Sets an internal value to permit the changing of a VALUE
\ No input parameters
\ --
\ No output parameters

 help_pos to+
\ (--)
\ Used in the form 12 TO+ FRED where FRED was created as a VALUE
\ Sets an internal value to permit the changing of a VALUE such that the (in this case) 12 is added to it
\ No input parameters
\ --
\ No output parameters

 help_pos byref
\ (-- addr)
\ Used in the form BYREF FRED where FRED was created as a VALUE
\ Returns the memory addres where FRED is stored
\ No input parameters
\ --
\ ADDR     memory address where value is stored

 help_pos to?
\ (-- bool)
\ Returns the current state of an internal variable controlling whether the
\ next use of a VALUE defined word is read or write
\ AND it resets the value to 0 = READ
\ No input parameters
\ --
\ BOOLEAN    FALSE = 0 = read
\            esle = write

 help_pos sizeof(ptr)
\ (-- u)
\ Returns the size in address units of a C language POINTER, this is the same as the size of
\ the data that the interpreter pops and pushes.
\ This value is dependant on how the interpreter was compiled.
\ No input parameters
\ --
\ U          The size of a POINTER in address units (bytes)

 help_pos sizeof(int)
\ (-- u)
\ Returns the size in address units of a C language INTEGER  (is same size as an UNSIGNED INTEGER).
\ This value is dependant on how the interpreter was compiled.
\ No input parameters
\ --
\ U          The size of a UNSIGNED INTEGER in address units (bytes)

 help_pos sizeof(word)
\ (-- u)
\ Returns the size in address units of a  C language WORD.
\ No input parameters
\ --
\ U          The size of a WORD in address units (bytes)

 help_pos sizeof(long)
\ (-- u)
\ Returns the size in address units of a  C language LONG.
\ No input parameters
\ --
\ U          The size of a LONG in address units (bytes)

 help_pos sizeof(longlong)
\ (-- u)
\ Returns the size in address units of a  C language LONG LONG.
\ No input parameters
\ --
\ U          The size of a LONG LONG in address units (bytes)

 help_pos sizeof(double)
\ (-- u)
\ Returns the size in address units of a C language DOUBLE precision floating point.
\ This value is dependant on how the interpreter was compiled.
\ No input parameters
\ --
\ U          The size of a DOUBLE in address units (bytes)

 help_pos sizeof(float)
\ (-- u)
\ Returns the size in address units of the interpreters  FLOAT representation.
\ This is NOT necessarily the same as a C language FLOAT variable.
\ No input parameters
\ --
\ U          The size of a FLOAT in address units (bytes)

 help_pos sizeof(dword)
\ (-- u)
\ Returns the size in address units of a Microsoft C language  DWORD.
\ This value is dependant on how the interpreter was compiled.
\ No input parameters
\ --
\ U          The size of a DOUBLE WORD in address units (bytes)

 help_pos @char
\ (c-addr -- x)
\ Read the CHARACTER value X from the CHARACTER aligned address c-addr
\ If c-addr is not CHARACTER aligned then a trap to an internal error handle occurs.
\ c-addr     CHARACTER aligned address
\ --
\ X          CHARACTER value located at the memory address c-addr

 help_pos @
\ (a-addr -- x)
\ Read the value x from the cell aligned address a-addr
\ If a-addr is not cell aligned then a trap to an internal error handle occurs.
\ a-addr     Cell aligned memory address
\ --
\ x          Cell sized value located at the cell aligned memory address a-addr

 help_pos @byte
\ (c-addr -- x)
\ Read the BYTE value X from the BYTE aligned address c-addr
\ If c-addr is not BYTE aligned then a trap to an internal error handle occurs.
\ c-addr     BYTE aligned address
\ --
\ b          BYTE value located at the memory address c-addr

 help_pos @word
\ (c-addr -- x)
\ Read the WORD value X from the WORD aligned address c-addr
\ If c-addr is not WORD aligned then a trap to an internal error handle occurs.
\ c-addr     WORD aligned address
\ --
\ X          WORD value located at the memory address c-addr

 help_pos @32
\ (c-addr -- x)
\ Read the 32 bit value X from the double word aligned address c-addr
\ If c-addr is not double word  aligned then a trap to an internal error handle occurs.
\ c-addr     double word  aligned address
\ --
\ X          32 bit value value located at the memory address c-addr

 help_pos @64
\ (c-addr -- x)
\ Read the 64 bit value X from the quad word aligned address c-addr
\ If c-addr is not quad word  aligned then a trap to an internal error handle occurs.
\ c-addr     quad word  aligned address
\ --
\ X          64 bit value value located at the memory address c-addr

 help_pos !
\ (x, a-addr --)
\ Store the value x at the cell aligned address a-addr
\ If a-addr is not cell aligned then a trap to an internal error handle occurs.
\ x          Cell sized value
\ a-addr     Cell aligned memory address
\ --
\ No output parameters

 help_pos !char
\ (x, u-addr --)
\ Store the CHARACTER value X at the CHARACTER value aligned address c-addr
\ If u-addr is not CHARACTER aligned then a trap to an internal error handle occurs.
\ X          CHARACTER value
\ U-addr     CHARACTER aligned memory address
\ --
\ No output parameters

 help_pos !8
\ (x, u-addr --)
\ Store the 8 bit value X at the 8 bit value aligned address c-addr
\ If u-addr is not 8 bit value aligned then a trap to an internal error handle occurs.
\ X          8 bit value value
\ U-addr     8 bit value aligned memory address
\ --
\ No output parameters

 help_pos !16
\ (x, u-addr --)
\ Store the 16 bit value X at the 16 bit aligned address c-addr
\ If u-addr is not 16 bit aligned then a trap to an internal error handle occurs.
\ X          16 bit value
\ U-addr     16 bit aligned memory address
\ --
\ No output parameters

 help_pos !32
\ (x, u-addr --)
\ Store the 32 bit value X at the 32 bit aligned address c-addr
\ If u-addr is not 32 bit aligned then a trap to an internal error handle occurs.
\ X          32 bit value
\ U-addr     32 bit aligned memory address
\ --
\ No output parameters

 help_pos !64
\ (x, u-addr --)
\ Store the 64 bit value X at the  64 bit aligned address c-addr
\ If u-addr is not  64 bit aligned then a trap to an internal error handle occurs.
\ X           64 bit value
\ U-addr      64 bit aligned memory address
\ --
\ No output parameters

 help_pos  [!]
\ ( value , index , cellPtr  --    )
\ Treats CELLPTR as the start of an array of cell sized objects
\ and places VALUE in the cell at array position   INDEX  (zero based index)
\ WARNING: no range checking !
\
\ VALUE   content of the cell at array position 0 relative to  CELLPTR
\ INDEX
\ CELLPTR  address of a cell
\ --
\ No output parameters

 help_pos  [@]
\ (  index , cellPtr  --  value   )
\ Treats CELLPTR as the start of an array of cell sized objects
\ and returns VALUE the content of the cell at array position   INDEX  (zero based index)
\ WARNING: no range checking !
\
\ INDEX
\ CELLPTR  address of a cell
\ --
\ VALUE   content of the cell at array position 0 relative to  CELLPTR

   [THEN]
 help_pos core-ext
\ (-- bool)
\ BOOLEAN is true if and only if the entire CORE-EXT WORD SET
\ is present
\ No input parameters
\ --
\ BOOL      = FALSE because only a subset of CORE-EXT WORD SET available

 help_pos .r
\ (n, u --)
\ Display the single precison signed integer n in a right aligned
\ field of at least u characters.
\ If n is too big for the field, then do not display any leading zeros,
\ and make the field as big as necessary to hold n.
\ n         Single precision signed integer, the number to be displayed
\ u         Single precision unsigned integer, the minimum width of the display
\ --
\ No output parameters

 help_pos 0<>
\ (x -- bool)
\ Compare the cell sized value x with 0.
\ Return bool = TRUE if and only if x is not equal to 0, else bool = false.
\ x         A cell sized value
\ --
\ bool      = TRUE if and only if x is not equal to 0
\           else = false

 help_pos 0>
\ (n-- bool)
\ Compare the signed integer n with 0.
\ Return bool = TRUE if and only if n is greater than 0 , else bool = false.
\ n         A signed integer
\ --
\ bool      = TRUE if and only if  n is greater than 0
\           else = false

 help_pos 2r@
\ (-- x1, x2)
\ The top cell-pair on the return stack will be copied to the stack.
\ Note: equivalent to  R> R> 2DUP  >R >R SWAP
\ No input parameters
\ --
\ x1         A cell sized value
\ x2         A cell sized value

 help_pos 2r>
\ (-- x1, x2)
\ The top cell-pair on the return stack will be transfered to the stack.
\ Note: equivalent to >R >R SWAP
\ No input parameters
\ --
\ x1         A cell sized value
\ x2         A cell sized value

 help_pos 2>r
\ (x1, x2 --)
\ The top cell-pair on the stack will be transfered to the return stack.
\ Note: equivalent to  SWAP >R  >R
\ x1         A cell sized value
\ x2         A cell sized value
\ --
\ No output parameters

 help_pos :noname
\ (-- xt)
\ Used in the form  :noname   ...words... ;
\ Places the compiler in the execution state and leaves
\ behind an eXecution Token for the nameless definition.
\ The definition has NONE of the following
\  LFA    Link Field Address        ptr to previous WORD'S header
\  FFA    Flag Field Address        boolean flags
\  NCFA   Name Count Field Address  length of WORDs name in characters
\  NFA    Name Field Address        ASCII name of WORD , zero terminated
\  HFA    Help Field Address        file-offset into a help file
\ No input parameters
\ --
\ XT       eXecution Token of the no name definition

 help_pos <>
\ (n1, n2 -- bool)
\ Compare the two signed integer n1 and n2
\ Return bool = TRUE if and only if n1 does not equal n2 , else bool = false.
\ n1        A signed integer
\ n2        A signed integer
\ --
\ bool      = TRUE if and only if  n1 does not equal n2
\           else = false

 help_pos of
\ (x1, x2 -- |x1)
\ Used as part of an OF ENDOF inside a CASE ENDCASE flow control construct.
\ Compile time action:
\   Push an OF link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ If x1 = x2, then discard both values and execute the code immediately
\ following the OF,
\ Else discard x2, leave x1 on the stack and continue execution with
\ the instruction that will be specified by the resolved of link request.
\ x1         A cell sized value
\ x2         A cell sized value
\ --
\  | x1   Either the OF to ENDOF is not executed, then X1
\         or the OF to ENDOF is executed then no value left on the stack
\

 help_pos endof
\ (--)
\ Used as part of an OF ENDOF inside a CASE ENDCASE flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type OF then resolve the link,
\   else trap to an error handler.
\   Push an ENDOF link request on to the control stack.
\   Compile in code to fullfill the following run time action:
\ Continue execution with the instruction that will be specified by the
\ resolved ENDOF link request
\ No input parameters
\ --
\ No output parameters

 help_pos case
\ (--)
\ Used as part of a CASE ENDCASE flow control construct.
\ Compile time action:
\   Push a CASE link request on to the control stack.
\ No input parameters
\ --
\ No output parameters

 help_pos endcase
\ (x --)
\ Used as part of a CASE ENDCASE flow control construct.
\ Compile time action:
\   Pop and resolve link requests on the control stack if
\   and as long as they are of type ENDOF.
\   Pop a link request from the control stack.
\   If the request is of type case then resolve the link,
\   else trap to an error handler.
\   Compile in code to fullfill the following run time action:
\ Discard the value x.
\ X         A cell sized value
\ --
\ No output parameters

 help_pos default
\ (-- x)
\ Used within a CASE ENDCASE flow control construct.
\ It returns the value of the CASE switch.
\ Can be called more than once.
\ Does not function inside an OF   ENDOF
\ No input parameters
\ --
\ X         The value being tested by a CASE flow control construct

 help_pos c"
\ (-- cs-addr)
\ Parse the input line for a string delimited by the character ".
\ Return the parsed string as counted address cs-addr.
\ If used within a : definition , the string is COMPILED-IN
\ Else the string is held in a temporary buffer
\ No input parameters
\ --
\ CS-ADDR   A counted string address

 help_pos again
\ (--)
\ Used as part of an BEGIN AGAIN flow control construct.
\ Compile time action:
\   Pop a link request from the control stack.
\   If the request is of type BEGIN then resolve the link,
\   else trap to an error handler.
\   Compile in code to fullfill the following run time action:
\ Continue by executing the next instruction after the BEGIN
\ i.e. jump unconditionally to the start of the BEGIN construct.
\ No input parameters
\ --
\ No output parameters

 help_pos compile,
\ (xt --)
\ Append the eXecution Token XT to the definition currently
\ being created, so that at run time XT will be executed
\ XT        An eXecution Token
\ --
\ No output parameters

 help_pos erase
\ (addr, u --)
\ If u > 0, then clear the memory contents of U consecutive address
\ locations
\ addr      A memory address
\ U         Number of address unit locations to be cleared
\ --
\ No output parameters

 help_pos hex
\ (--)
\ Set the current base for character/number conversions to be Base-16
\ Is equivalent to #16 BASE !
\ No input parameters
\ --
\ No output parameters

 help_pos [compile]
\ (--)
\ Used in the form   :  FRED  ...  [compile] <name>  ... ;
\ Parse the input line for a space delimited string. Find the parsed
\ string in the current search order. Compile the found command in to the
\ definition current being created.
\ Is useful for compiling IMMEDIATE words
\ No input parameters
\ --
\ No output parameters

 help_pos u.r
\ (u1, u2 --)
\ Display the single precison unsigned integer u1 in a right aligned
\ field of at least u2 characters.
\ If u1 is too big for the field, then do not display any leading zeros,
\ and make the field as big as necessary to hold u1.
\ u1        Single precision unsigned integer, the number to be displayed
\ u2        Single precision unsigned integer, the minimum width of the display
\ --
\ No output parameters

 help_pos u>
\ (u1, u2-- bool)
\ Compare the 2 unsigned integers u1 and u2.
\ Return bool = TRUE if and only if U1 > U2 , else bool = false.
\ n          A signed integer
\ --
\ bool      = TRUE if and only if U1 > U2
\           else = false

 help_pos unused
\ (-- x)
\ Leave behind the amount of free space in the dataspace area
\ No input parameters
\ --
\ u          The number of free address units in the  dataspace

 help_pos tuck
\ (x1, x2 -- x2, x1, x2)
\ Copy the top cell on the stack, underneath the second cell
\ X1         A cell sized value
\ X2         A cell sized value
\ --
\ X1         A cell sized value
\ X2         A cell sized value
\ X1         A cell sized value

 help_pos pick
\ (xn...x1, x0, n -- xn...x1, x0, xn)
\ The value n is removed from the stack. Then the n'th cell
\ on the stack is copied, the stack is pushed down, and
\ the copied value is placed on the top of the stack.
\    0 pick is equivalent to dup
\    1 pick is equivalent to over
\ xn         A cell value, the n'th cell on the stack
\ ..
\ x1         A cell value, the second cell on the stack
\ x0         A cell value, the top cell on the stack
\ n          The index (0..) of the cell to be copied
\ --
\ xn         A cell value, the n'th cell on the stack
\ ..
\ x1         A cell value, the second cell on the stack
\ x0         A cell value, the top cell on the stack
\ xn         A cell value, the n'th cell on the stack

 help_pos roll
\ (xn...x1, x0, n -- xn-1...x1, x0, xn)
\ The value n is removed from the stack. Then the top n cells
\ on the stack are rolled
\ xn         A cell value, the n'th cell on the stack
\ ..
\ x1         A cell value, the second cell on the stack
\ x0         A cell value, the top cell on the stack
\ n          The index (0..) of the cell to be copied
\ --
\ xn-1       A cell value, the n'th cell on the stack
\ ..
\ x1         A cell value, the third cell on the stack
\ x0         A cell value, the second cell on the stack
\ xn         A cell value, the top cell on the stack

 help_pos nip
\ (x1, x2 -- x2)
\ The second cell on the top of the stack will be removed
\ x1         A cell value, the second cell on the stack
\ x2         A cell value, the top cell on the stack
\ --
\ x2         A cell value

 help_pos marker
\ (--)
\ Compile time action:
\   Parse the input line for a space delimited character string.
\   Create a new command with this name.
\   Store in the dataspace associated with this command, the
\   current state of the search order, compilation wordlist, and
\   all existing wordlists.
\ Run time action:
\   Delete itself and all subsequent definitions
\   Restore the search order and compilation wordlists to the
\   state they had when MARKER was executed.
\   Recover the dataspace that was used by this and subsequent definitions.
\   Restore all wordlists to the state that they were when MARKER was called.
\ No input parameters
\ --
\ No output parameters

 help_pos help=no
\ (--)
\ Set an internal flag that will prevent the help file being loaded during the
\ start-up process of this executable.
\ No input parameters
\ --
\ No output parameters

 help_pos user=no
\ (--)
\ Set an internal flag that will prevent a users initialisation file from being
\ loaded during the start-up process of this executable.
\ If a users initialisation file exists then:
\   Its pathname must be that of the users working directory when the program
\     was executed. See  app.path@invocation
\   Its filename is   ripe_uinit.txt
\ No input parameters
\ --
\ No output parameters

  ' .bin [if]
 help_pos mk-dir.path
\ (c-addr , count -- ErrorCode)
\ Create the Directory specified by  C-ADDR, U
\ If one or more intermediatory Directories do not exist they will be created.
\ C-ADDR    Address of text string
\ COUNT     Size of list area in BYTES
\ --
\ ErrorCode   = 0 = no error

 help_pos list=open
\ (-- index)
\ Returns the index of a  free list
\ It does NOT automatically select that list !
\ No input parameters
\ --
\ INDEX     0..63
\           = -1 = no free list

 help_pos list=empty
\ (--)
\ Release the current LIST resource
\ No input parameters
\ --
\ No output parameters

 help_pos list=close
\ (--)
\ Release the current LIST resource
\ No input parameters
\ --
\ No output parameters

 help_pos list=unique
\ ( bool --)
\ defines whether the current LIST allows duplicate byte/char arrays
\ BOOL   = 0  duplicate lines are permitted (default)
\        else duplicate lines are dropped
\ --
\ No output parameters

 help_pos list=binary
\ ( bool --)
\ defines how the list functions compare input
\ BOOL   = 0  use a caseless comparision when adding/finding entries (default)
\        else use a binary comparision when adding/finding entries
\ --
\ No output parameters

 help_pos list=select
\ ( index --)
\ Set the list for future list operations.
\ INDEX = 0 .. 63
\ --
\ No output parameters

 help_pos list@select
\ ( -- index)
\ Get the zero based index of the current LIST
\ No input parameters
\ --
\ INDEX = 0 .. 63

 help_pos list@base
\ ( -- u )
\ Get the base memory address of the current LIST
\ No input parameters
\ --
\ U         Memory address of first byte of the current LIST

 help_pos list.bytes=find
\ (c-addr , count -- u)
\ If the BYTE array identified by C-ADDR, COUNT is
\ a member of the LIST then return U the zero based index of the
\ array/string.
\ Search the LIST from the oldest entry to the newest.
\ C-ADDR    Address of BYTE   array/string
\ COUNT     Size of list area in BYTES
\ --
\ U         The zero based index of this array/string
\           -1 if not found

 help_pos list.bytes=dnif
\ (c-addr , count -- u)
\ If the BYTE array identified by C-ADDR, COUNT is a member of the LIST then return U the zero based index of the array.
\ Search the LIST from the newest entry to the oldest.
\ C-ADDR    Address of BYTE   array/string
\ COUNT     Size of list area in BYTES
\ --
\ U         The zero based index of this array/string
\           -1 if not found

 help_pos list@size
\ ( -- u)
\ Returns the number of elements in the current list.
\ No input parameters
\ --
\ U         The number of elements in the current list.
\           -1 if LIST not OPENED

 help_pos list.chars.data=add
\ ( xA , xB , c-addr , count , ListId -- u)
\ If the   CHARACTER string identified by C-ADDR, COUNT is NOT
\ already a member of the LIST then add it to the LIST.
\ Return U the zero based index of the array/string.
\
\ ValueA    data value associated with CHARACTER string
\ Valueb    data value associated with CHARACTER string
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of  string  in bytes
\ LISTID    Identity of list to be added to
\ --
\ U         The zero based index of this string
\           -1 if not found

 help_pos list.chars@data
\ (c-addr , count , ListId  --   ( ( xA , xB , index , true ) | false ))
\ If the CHARACTER string identified by C-ADDR, COUNT is a member of the LIST then
\ return U the zero based index of the array.
\ Search the LIST from the oldest entry to the newest.
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of list area in CHARACTERs
\ LISTID    Identity of list to be searched
\ --
\ (
\ ValueA    data value associated with CHARACTER string
\ Valueb    data value associated with CHARACTER string
\ U         The zero based index of this array/string
\ TRUE      a non-zero value
\ )
\ or
\ FALSE     = value zero

 help_pos list.chars=find
\ (c-addr , count -- u)
\ If the CHARACTER string identified by C-ADDR, COUNT is a member of the LIST then return U the zero based index of the array.
\ Search the LIST from the oldest entry to the newest.
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of list area in CHARACTERs
\ --
\ U         The zero based index of this array/string
\           -1 if not found

 help_pos list.chars=dnif
\ (c-addr , count -- u)
\ If the CHARACTER string identified by C-ADDR, COUNT is a member of the LIST then return U the zero based index of the array.
\ Search the LIST from the newest entry to the oldest.
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of list area in CHARACTERs
\ --
\ U         The zero based index of this array/string
\           -1 if not found

 help_pos list.named.blob=add
\ ( blobSize , c-addr , count -- b-addr , u)
\ EXPERIMENTAL
\ If the   CHARACTER string identified by C-ADDR, COUNT is NOT
\ already a member of the LIST then add it to the LIST.
\ Add enough space to hold BLOBSIZE bytes.
\ Return U the zero based index of the array/string.
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of  string  in bytes
\ --
\ U         The zero based index of this string
\           -1 if not found

 help_pos list.chars=add
\ (c-addr , count -- u)
\ If the   CHARACTER string identified by C-ADDR, COUNT is NOT
\ already a member of the LIST then add it to the LIST.
\ Return U the zero based index of the array/string.
\ C-ADDR    Address of CHARACTER    array/string
\ COUNT     Size of  string  in bytes
\ --
\ U         The zero based index of this string
\           -1 if not found

 help_pos list.bytes=add
\ (c-addr , count -- u)
\ If the byte array (or character string)identified by C-ADDR, COUNT is NOT
\ already a member of the LIST then add it to the LIST.
\ Return U the zero based index of the array/string.
\ C-ADDR    Address of byte/character    array/string
\ COUNT     Size of array/string  in bytes
\ --
\ U         The zero based index of this array/string
\           -1 if not found

 help_pos list@chars
\ ( u -- c-addr , count)
\ Return the CHARACTER array associated with the zero based index of the currently active LIST
\ U         The zero based index of this array/string
\ --
\ C-ADDR    Address of CHARACTER    array
\ COUNT     Size of string in CHARACTER
\           If  U  is out of range, then return   COUNT = -1
\           If  U  in range, but there is no CHAR string  COUNT = 0
 help_pos list@bytes
\ ( u -- c-addr , count)
\ Return the BYTE array associated with the zero based index of the currently active LIST
\ U         The zero based index of this array/string
\ --
\ C-ADDR    Address of BYTE    array
\ COUNT     Size of array in BYTES
\           If  U  is out of range, then return   COUNT = -1
\           If U in range, but there is no BYTE array  COUNT = 0
 help_pos list@value
\ ( u -- val0 , val1 , BOOLEAN)
\ Return the user data associated with the zero based index of the currently active LIST
\ U         The zero based index of this array/string
\ --
\ VAL0      user defined value
\ VAL1      user defined value
\ BOOLEAN   = 0 if okay
\           = -1 if U not in range
 help_pos list=value
\ ( val0 , val1 , u --  -1 | 0)
\ Set the user defined values val0, val1  associated with  U the zero based index of the currently active LIST
\ VAL0      User data
\ VAL1      User data
\ U         The zero based index of the target cell 
\ --
\ -1 | 0    Returns 0 if okay, else ERROR
 help_pos getspecial
\ ( X -- c-addrF , uF)
\ Gets the full path of a "known" folder.
\ THe "known" folder is identified by the value  X
\ Is a wrapper around the operating system's    SHGetKnownFolderPath  function.
\ e.g.   5  getspecial  type
\        \ gets the users default Documents folder
\        \ returns on my development system
\        \ DriverData=C:\Users\george\Documents
\
\ X         Index of wanted "known" folder
\ --
\ C-ADDRF   Address of a character string holding the wanted "known" folder string
\ UF        Length of "known" folder in characters

 help_pos getenvById
\ ( X -- c-addrV , uV)
\ Gets the x'th environmental string.
\ Is a wrapper around the operating system's    GetEnvironmentStrings function.
\ e.g.   79 getenvById  type
\        \ returns on my development system
\        \ DriverData=C:\Windows\System32\Drivers\DriverData
\
\ X         Index of wanted environmental string
\ --
\ C-ADDRV   Address of a character string holding the wanted environmental string
\ UV        Length of NAME environmental in characters

 help_pos getenv
\ (c-addrN , uN -- c-addrV , uV)
\ Is a wrapper aruond the operating systems    environ function.
\ e.g.   s" SYSTEMROOT"  getenv  type
\        \ returns on my development system    c:\windows
\ C-ADDRN   Address of a character string holding the NAME of the wanted environmental string
\ UN        Length of NAME string in characters
\ --
\ C-ADDRV   Address of a character string holding the wanted environmental string
\ UV        Length of NAME environmental in characters
\

 help_pos debug
\ (--)
\ IF    the debug flag is TRUE then this DEFN acts exactly as the DEFN   \
\ ELSE  this DEFN has no effect
\ note that this DEFN is IMMEDIATE.
\ See   DEBUG=ON and DEBUG=OFF to set the debug flag state.
\ Can be used to "comment out" code that is not for normal execution
\ No input parameters
\ --
\ No output parameters

 help_pos debug=on
\ (--)
\ Set the debug flag to be TRUE
\ see   DEBUG
\
\ No input parameters
\ --
\ No output parameters

 help_pos debug=off
\ (--)
\ Set the debug flag to be FALSE
\ see   DEBUG
\
\ No input parameters
\ --
\ No output parameters

 help_pos land
\ (x1, x2 -- bool)
\ Test the value x1 and x2.
\ Return bool = TRUE if and only if  x1 and x2 <> 0
\ x1         A value
\ x2         A value
\ --
\ bool      = TRUE if and only if  x1 and x2 <> 0
\           else = false

 help_pos lor
\ (x1, x2 -- bool)
\ Test the value x1 and x2.
\ Return bool = TRUE if and only if  x1 or x2 <> 0
\ x1         A value
\ x2         A value
\ --
\ bool      = TRUE if and only if  x1 or x2 <> 0
\           else = false

 help_pos .hex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .2hex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .dec
\ (x --)
\ Convert the value X to an ascii string in decimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .bin
\ (u --)
\ Convert the value X to an ascii string in binary format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos msb
\ (-- x)
\ Return the bit pattern in which only the Most Significant Bit
\ is set to ONE all other bits are set to zero.
\ No input parameters
\ --
\ X         Single cell

 help_pos %
\ (-- c-addr , count)
\ Read a space delimited string from the current input buffer , and
\ leave the address of the string on the stack
\ If used within a : definition , the string is COMPILED-IN
\ Else the string is held in a temporary buffer

 help_pos 'link
\ (-- link)
\ e.g.  'link  FRED
\ Parse the input area for a space delimited character string.
\ Search for a definition in the current search wordlists with this
\ string as its name.
\ If found 'link returns the Link Field Address of   FRED
\ If not found,  link = 0
\ No input parameters
\ --
\ LINK        = Link Field Address if definition found
\             else = 0

 help_pos .\
\ (--)
\ The rest of the current input buffer will be displayed
\ on the current output device
\ No input parameters
\ --
\ No output parameters

 help_pos key
\ (-- char)
\ Receive one character from the keyboard.
\ Ignore all characters less than  0x020 and greater than 0x06f
\ No input parameters
\ --
\ CHAR       Character value

 help_pos at-xy
\ (x, y --)
\ Define the co-ordinate (x, y) where the next displayed character should
\ be placed on the screen.
\ X          Horizonatal co-ordinate
\ X          Veritical co-ordinate
\ --
\ No output parameters

 help_pos %create
\ (c-addr , u --)
\ CREATEs a WORD with the name pointed to by the counted string C-ADDR,U
\ e.g.   s" fred"   %create
\  is equivalent to
\        create  fred
\ C-ADDR   Character string address
\ U        Length of character string
\ --
\ No output parameters


 help_pos w@
\ (w-addr -- w )
\ Return the value W ( 16 bits ) stored at the word aligned
\ memory address W-ADDR.
\ W-ADDR    Word aligned memory address
\ --
\ W         Word sized content at addres W-ADDR

 help_pos w!
\ (w, w-addr --)
\ Write the word sized value w (16 bits) to the word aligned memory
\ at address W-ADDR
\ W         Word sized value
\ W-ADDR    Word aligned memory address
\ --
\ No output parameters

 help_pos integer
\ (c-addr , u  -- [FALSE | x , TRUE])
\ Convert the entire character string pointed at by C_ADDR,U to a single
\ precision integer.
\ C-ADDR    Character aligned memory address = address of first character in string
\ U         Length of string in characters
\ --
\ either
\ FALSE     If string is not an integer representation
\ or
\ X         Integer value
\ TRUE

 help_pos Dinteger
\ (c-addr , u  -- [FALSE | x , TRUE])
\ Convert the entire character string pointed at by C_ADDR,U to a DOUBLE
\ precision integer.
\ C-ADDR    Character aligned memory address = address of first character in string
\ U         Length of string in characters
\ --
\ either
\ FALSE     If string is not an integer representation
\ or
\ X         Integer value
\ TRUE

 help_pos sizeof(UTF8">s")
\ ( UC-ADDR , uU --   wU)
\ Calculates the number of bytes needed when
\ converting a UTF8 CHARACTER text string to a WIDE CHARACTER text string
\
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string
\ --
\ WU         Length of the wide character string

 help_pos UTF8">WBuffer
\ ( UC-ADDR , uU , WC-ADDR , wU  -- WC-ADDR , wU)
\ Convert a UTF8 CHARACTER text string into a WIDE CHARACTER strin held in
\ a user provided buffer
\
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string
\ --
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string

 help_pos sizeof(s">UTF8")
\ ( WC-ADDR , WU --   UU)
\ Calculates the number of bytes needed when
\ converting a WIDE CHARACTER text string to a  UTF8 CHARACTER text string
\ WC-ADDR    Address of a WIDE character string
\ WU         Length of the WIDE character string
\ --
\ UU         Length of the UTF8 character string

 help_pos UTF8">WCHAR"
\ ( UC-ADDR , uU -- WC-ADDR , wU)
\ Convert a UTF8 CHARACTER text string to a WIDE CHARACTER text string
\
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string
\ --
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string

 help_pos ACHAR">WCHAR"
\ ( AC-ADDR , aU -- WC-ADDR , wU)
\ Convert an ANSI CHARACTER text string to a WIDE CHARACTER text string
\
\ AC-ADDR    Address of an ASNI character string
\ AU         Length of the ASNI character string
\ --
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string

 help_pos WCHAR">ACHAR"
\ ( WC-ADDR , wU -- AC-ADDR , aU )
\ Convert a WIDE CHARACTER text string to a ANSI CHARACTER text string
\
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string
\ --
\ AC-ADDR    Address of an ASNI character string
\ AU         Length of the ASNI character string

 help_pos s">sys(UTF8)str
\ ( WC-ADDR , wU -- UC-ADDR , uU)
\ Convert a wide CHARACTER text string to a zero terminated , UTF8 CHARACTER text string
\ N
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string
\ --
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string  ***without*** the terminating 0
\   This string should be returned by passing  UC-ADDR  to  bstr.free

 help_pos WCHAR">UTF8"
\ ( WC-ADDR , wU -- UC-ADDR , uU)
\ Convert a wide CHARACTER text string to a UTF8 CHARACTER text string
\
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string
\ --
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string

 help_pos ACHAR">UTF8"
\ ( AC-ADDR , aU -- uC-ADDR , uU)
\ Convert an ANSI CHARACTER text string to a UTF8 CHARACTER text string
\ No input parameters
\ AC-ADDR    Address of an ASNI character string
\ AU         Length of the ASNI character string
\ --
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string

 help_pos UTF8">ACHAR"
\ ( uC-ADDR , uU -- AC-ADDR , aU)
\ Convert an UTF8 CHARACTER text string to a ANSI CHARACTER text string
\ UC-ADDR    Address of a UTF8 character string
\ UU         Length of the UTF8 character string
\ --
\ AC-ADDR    Address of an ASNI character string
\ AU         Length of the ASNI character string

 help_pos ACHAR">S"
\ ( AC-ADDR , AU -- C-ADDR , U)
\ Convert an ANSI CHARACTER text string  to a standard  CHARACTER text string
\ AC-ADDR    Address of a ANSI character string
\ AU         Length of the ANSI character string
\ --
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string

 help_pos UTF8">S"
\ ( AC-ADDR , AU -- C-ADDR , U)
\ Convert an UTF8 CHARACTER text string  to a standard  CHARACTER text string
\ AC-ADDR    Address of an UTF8 character string
\ AU         Length of the UTF8 character string
\ --
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string

 help_pos WCHAR">s"
\ ( WC-ADDR , WU -- C-ADDR , U)
\ Convert a WIDE CHARACTER text string  to a standard  CHARACTER text string
\ Actually it does nothing since standard characters, in this version executable, are wide characters.
\ WC-ADDR    Address of a WIDE character string
\ WU         Length of the WIDE character string
\ --
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string

 help_pos S">ACHAR"
\ ( C-ADDR , U -- AC-ADDR , AU)
\ Convert a standard  CHARACTER text string to a ANSI CHARACTER text string
\
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string
\ --
\ AC-ADDR    Address of a ANSI character string
\ AU         Length of the ANSI character string

 help_pos s">UTF8"
\ ( C-ADDR , U -- UC-ADDR , uU)
\ Convert a standard  CHARACTER text string to a UTF8 CHARACTER text string
\
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string
\ --
\ uC-ADDR    Address of a UTF8 character string
\ uU         Length of the UTF8 character string

 help_pos s">WCHAR"
\ ( C-ADDR , U -- UC-ADDR , uU)
\ Convert a standard  CHARACTER text string to a WIDE CHARACTER text string
\ Actually it does nothing since standard characters, in this version executable, are wide characters.
\ C-ADDR     Address of a standard character string  e.g  s" Hello"
\ U          Length of the standard character string
\ --
\ WC-ADDR    Address of a wide character string
\ WU         Length of the wide character string

 help_pos sprintf
\ ( val ,  FC-ADDR , FU -- UC-ADDR , uU)
\ VAL         Value to be formatted
\ FC-ADDR     Address of the format character string
\ FU          Length of the format character string
\ --
\ C-ADDR     Address of the formatted character string
\ U          Length of the formatted character string  = 0  on ERROR

 help_pos setlocale
\ ( category, LC-ADDR , LU -- UC-ADDR , uU)
\ Please refer to online documentation for the "C" language  setlocale function
\ CATERGORY:
\      LC_COLLATE = 1
\      LC_ALL = 0
\      LC_CTYPE=2
\      LC_MONETARY = 3
\      LC_NUMERIC = 4
\      LC_TIME= 5
\ LC-ADDR     Address of a string holding the target  locale
\ LU          Length of the ftarget  locale
\ --
\ RC-ADDR     Address of the formatted character string
\ R U          Length of the formatted character string  = 0  on ERROR

 help_pos .dwordHex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .qwordHex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .wordhex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string willl be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

 help_pos .byteHex
\ (x --)
\ Convert the value X to an ascii string in hexadecimal format
\ which is then displayed on the current output device .
\ The ascii string will be followed by a single space
\ X         Single precision signed integer
\ --
\ No output parameters

  [then]
  ' cng:open [if]
 help_pos cng:open
\ ( c-addr, u -- boolean)
\ Any previously unclosed CNG hash operation will be closed and its results deleted
\ Initialise a CNG hash operation for the hash algorithm defined by the
\ string  C-ADDR and length U characters.
\ e.g.      MD4   MD5   SHA1  SHA256   SHA384   SHA512
\
\ C-ADDR    text name of algorithm to be used by handler
\ U         length of text name
\ --
\ BOOL      0 = error
\           else Okay

 help_pos cng:add.buffer
\ ( c-addr, u -- result)
\ Add to the current HASH the hash value of a block of data
\
\ NOTE: this command should be part of a wider sequence:
\       You must already have run   cng.hash=open
\       Optionally run 0 or more   cng.hash=add.buffer    OR  cng.hash=add.file
\       Then this   cng.hash=add.buffer
\       Optionally run 0 or more   cng.hash=add.buffer    OR  cng.hash=add.file
\      Then   cng.hash=close
\
\ B-ADDR    Byte address of data to be added to the hash
\ U         length of byte data
\ --
\ RESULT    0 on error , else okay

 help_0pos cng:close.b64
\ (-- c-addr, u|0)
\ Return the HASH value created by the current CNG HASH operation
\ and terminate the CNG HASH operation.
\ The returned value is the hash converted to -> b64
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the B64 version of the HASH value
\ u         Length of the B64 data in bytes
\           0 if error

 help_pos cng:close.str
\ (-- c-addr, u|0)
\ Return the HASH value created by the current CNG HASH operation
\ and terminate the CNG HASH operation.
\ The returned value is the hash converted to -> b64- > converted to character sting
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the HASH value
\ u         Length of the HASH data in characters
\           0 if error

 help_0pos cng:read
\ (c-addrI, uI, -- boolean)
\ IS NOT REALLY A CRYPTO FUNCTION
\ Read the entire file identifed by the filename.
\ Do NOTHING with the data.
\ Close the file
\ Is used to simply time how long it takes to read the file to a buffer!
\
\ c-addr    Start address of byte array in memory holding the file name
\ u1        Length of file name
\ --
\ boolean    0 if error
\           else okay

 help_pos cng:add.file
\ (c-addrI, uI, -- boolean)
\ Add to the current HASH the hash value of a file!
\ NOTE: this command should be part of a wider sequence:
\       You must already have run   cng.hash=open
\       Optionally run 0 or more   cng.hash=add.buffer    OR  cng.hash=add.file
\       Then this   cng.hash=add.file
\       Optionally run 0 or more   cng.hash=add.buffer    OR  cng.hash=add.file
\      Then   cng.hash=close
\ c-addr    Start address of byte array in memory holding the file name
\ u1        Length of file name
\ --
\ boolean    0 if error
\           else okay

 help_pos cng:close
\ (-- c-addr, u|0)
\ Return the HASH value created by the current CNG HASH operation
\ and terminate the CNG HASH operation.
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the HASH value
\ u         Length of the HASH data in bytes
\           0 if error

 help_pos cng:peek
\ (-- c-addr, u|0)
\ Return the HASH value created by the current CNG HASH operation
\ and terminate the CNG HASH operation.
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the HASH value
\ u         Length of the HASH data in bytes
\           0 if error

 help_pos cng.hash@name
\ (-- c-addr, u )
\ Return the name of the last HASH algorithm
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the HASH algorithm name
\ u         Length of the name

 help_pos cng:help
\ ( -- c-addr, u  )
\ General info about the namespace  CNG:
\ --
\ no output parameters

    [then]
    [then]
  ' dll:open [if]
 help_pos dll:call.0
\ (xn ,  .. , x1 , n , c-xt -- )
\ Cause the machine code routine at C-XT in memory to be called.
\ The routine will be given N parameters and return NONE.
\ The parameters are pased in the "C" language  calling convention.
\ N can be any value from 0  to  16 inclusive
\ xn,.. x1  Potential input parameters
\ N         Number of input parameters
\ C-XT      Start address of a machine code routine
\ --
\ No output parameters

 help_pos dll:call.1
\ (xn ,  .. , x1 , n , c-xt -- x0)
\ Cause the machine code routine at C-XT in memory to be called.
\ The routine will be given N parameters and return one parameter.
\ N can be any value from 0  to  16 inclusive
\ xn,.. x1  Potential input parameters
\ N         Number of input parameters
\ C-XT      Start address of a machine code routine
\ --
\ X0        Single cell return parameter

 help_pos dll:call.2
\ (xn ,  .. , x1 , n , c-xt -- xd)
\ Cause the machine code routine at C-XT in memory to be called.
\ The routine will be given N parameters and return a double sized parameter.
\ The parameters are passed in the "C" language  calling convention.
\ N can be any value from 0  to  16 inclusive
\ xn,.. x1  Potential input parameters
\ N         Number of input parameters
\ C-XT      Start address of a machine code routine
\ --
\ XD        Double (float) return parameter

 help_pos dll:open
\ (c-addr, u -- 0 | fileid)
\ Return the file identity of the shared/dynamic link library file given by
\ the character string  C-ADDR and length U.
\ Do NOT use  forward  slashes  /  in the file name.
\ Only use    backward slashes  \  in the file name.
\ C-ADDR     Character string address of file name
\ U          Length of character string
\ --
\ 0          on error
\  else
\ FILEID     System identity of opened shared/dynamic link library file

 help_pos dll:close
\ (fileid -- res)
\ Close the shared/dynamic link library file identified by fileid.
\ FILEID     System identity of opened shared/dynamic link library file
\ --
\ RES        = 0 if okay
\            else = error

 help_pos  dll:sym
\ (fileid, c-addr, u -- ext)
\ Get the execution address of the procedure with the name given by the
\ character string c-addr and length u, in the shared/dynamic link library
\ identified by fileid.
\ FILEID    File identity of shared/dynamic link library opened by lib.open
\ C-ADDR    Character string address of procedure name
\ U         Length of character string
\ --
\ EXT       = 0 on error
\           else = execution address of procedure

  [then]
  ' dos [if]
 help_pos app=cwd
\ (c-addr , u -- -1|0)
\ Assigns the given path name to be the default/working directory
\ C-ADDR    Address of a character string - giving path name of directory to be
\           used as the current directory.
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos mk-dir
\ (c-addr , u -- -1|0)
\ Creates the named directory.
\ C-ADDR    Address of a character string - giving path name of directory to be
\           created
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos rm-dir
\ (c-addr , u -- -1|0)
\ Deletes the named directory.
\ C-ADDR    Address of a character string - giving path name of directory to be
\           deleted
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos app@cwd
\ (-- c-addr , u)
\ Obtains the path name of the default/working directory
\ No input parameters
\ --
\ C-ADDR    Address of a character string - giving path name of current directory
\ U         length of character string

 help_pos save=cwd
\ (--)
\ Save the current working directory name in an internal buffer,
\ See  saved-cwd  to gain access to the path as a character string
\ No input parameters
\ --
\ No output parameters

 help_pos save@cwd
\ (-- c-addr , u)
\ Return the string containing the Saved  current working directory
\ No input parameters
\ --
\ C-ADDR    Address of character string giving path name of saved CWD
\ U         length of character string

 help_pos inp
\ (port_addr -- u)
\ Read u, the 8 bit value from the IO port at address  port_addr.
\ PORT_ADDR Address of I/O port to be read from
\ --
\ U         8 bit value read from PORT_ADDR

 help_pos outp
\ (u, port_addr --)
\ Write u, the 8 bit value to the IO port at address  port_addr.
\ U         8 bit value to be written
\ PORT_ADDR Address of I/O port to be written to
\ --
\ No output parameters
 help_pos accept
\ (c-addr, u1 -- u2)
\ Receive a string of at most U1 characters from the current input device
\ Stop accepting input on receiving a new-line character, or
\ when U1 characters have been received.
\ Return U2, the actual number of received characters (not
\ including any newline characters )
\ CS-ADDR   Address to which characters should be placed
\ U1        Maximum number of wanted characters
\ --
\ U2        Actual number of characters received

 help_pos app@name
\ (-- c-addr, u)
\ Return a character string giving the filename of the
\ interpreters executable without an extension
\ No input parameters
\ --
\ C-ADDR    The character string address of file name
\ U         The length of the character string.

 help_pos system
\ (caddr, count -- return code)
\ Pass the text string to the system command interpreter
\ If  caddr  = NULL
\     return code = non-zero if command interpreter exists
\ else
\     return code is system dependant

 help_pos path@invocation
\ (-- c-addr, u)
\ Returns a character string giving the pathname of the directory in which
\ the user was, when the executable file was activated
\ No input parameters
\ --
\ C-ADDR    The character string address of directory
\ U         The length of the character string.

 help_pos path@execution
\ (-- c-addr, u)
\ Returns a character string giving the pathname of the directory from which
\ the executable file was loaded
\ No input parameters
\ --
\ C-ADDR    The character string address of directory
\ U         The length of the character string.

   [THEN]
  ' d. [if]
 help_pos d.
\ (d --)
\ The number d will be displayed in free field format
\ with a trailing space.
\ d        A double precision signed or unsigned integer
\ --
\ No output parameters

 help_pos m+
\ (d1|u1, n1 -- d2|du2)
\ Add the single precision signed integer n1 to the double
\ precision signed integer d1|du1 to give the result d2|du2
\ d1|du1    A double precision value, either signed or unsigned
\ n         A single precision signed integer
\ --
\ d2|du2    A double precision value, either signed or unsigned

 help_pos? m*?
\ (d1, n1, n2 -- d2)
\ Multiply the double precision signed integer d1 by the single
\ precision signed integer n1 to create a temporary internal triple
\ precision value t.
\ Divide t by the signed integer n2, the double precison signed
\ quotient of this division is d2.
\ If n2 = 0 then a trap occurs to an internal error handler.
\ If the quotient is too large to fit a double precision signed
\ integer then a trap occurs to an internal error handler.
\ d1        A double precision signed value
\ n1        A single precision signed integer
\ n2        A single precision signed integer
\ --
\ d2        A double precision signed value

 help_pos d2/
\ (xd1 -- xd2)
\ The double cell sized value dx1 is shifted 1 bit to the right.
\ The most significant bit retains its value.
\ xd1       A double precision value
\ --
\ xd2       A double precision value

 help_pos d2*
\ (xd1 -- xd2)
\ The double cell sized value dx1 is shifted 1 bit to the left.
\ The new least significant bit is cleared.
\ xd1       A double precision value
\ --
\ xd2       A double precision value

 help_pos dmin
\ (d1, d2 -- d3)
\ Returns d3, the smaller of the two double precision signed integers d1 and d2.
\ d1       A double precision signed integer
\ d2       A double precision signed integer
\ --
\ d3       A double precision signed integer, the smaller of xd1 and xd2

 help_pos dmax
\ (d1, d2 -- d3)
\ Returns d3, the larger of the two double precision signed integers d1 and d2.
\ d1        A double precision signed integer
\ d2        A double precision signed integer
\ --
\ d3        A double precision value, the larger of xd1 and xd2

 help_pos d<
\ (d1, d2 -- bool)
\ Returns bool = TRUE if and only if d1 is less than d2, else bool = FALSE
\ d1        A double precision signed integer
\ d2        A double precision signed integer
\ --
\ bool      = TRUE if and only if d1 is less than d2, else bool = FALSE

 help_pos du<
\ (du1, du2 -- bool)
\ Returns bool = TRUE if and only if du1 is less than du2, else bool = FALSE
\ du1       A double precision unsigned integer
\ du2       A double precision unsigned integer
\ --
\ bool      = TRUE if and only if du1 is less than du2, else bool = FALSE

 help_pos 2rot
\ (x1, x2, x3, x4, x5, x6 -- x3, x4, x5, x6, x1, x2)
\ The top three cells-pairs on the stack are rotated.
\ x1         A cell value, lower cell third cell pair
\ x2         A cell value, upper cell third cell pair
\ x3         A cell value, lower cell second cell pair
\ x4         A cell value, upper cell second cell pair
\ x5         A cell value, lower cell top cell pair
\ x6         A cell value, upper cell top cell pair
\ --
\ x3         A cell value
\ x4         A cell value
\ x5         A cell value
\ x6         A cell value
\ x1         A cell value
\ x2         A cell value

 help_pos d=
\ (d1, d2 -- bool)
\ Returns bool = TRUE if and only if d1 is equal to d2, else bool = FALSE
\ d1        A double precision signed integer
\ d2        A double precision signed integer
\ --
\ bool      = TRUE if and only if d1 is equal to d2, else bool = FALSE

 help_pos d0<
\ (d -- bool)
\ Returns bool = TRUE if and only if d1 is less than zero, else bool = FALSE
\ d         A double precision signed integer
\ --
\ bool      = TRUE if and only if d is less than zero, else bool = FALSE

 help_pos d0=
\ (xd -- bool)
\ Returns bool = TRUE if and only if d is equal to zero, else bool = FALSE
\ xd        A double precision value
\ --
\ bool      = TRUE if and only if d1 is equal to d2, else bool = FALSE

 help_pos d-
\ (d1|du1, d2|du2 -- d3|du3)
\ The number d2|du2 is subtracted from the number d1|du1 to give the
\ result d3|du3. There is no detection of number /sign underflow.
\ d1|du1   A double precision signed or unsigned integer
\ d2|du2   A double precision signed or unsigned integer
\ --
\ d3|du3   A double precision signed or unsigned integer

 help_pos d+
\ (d1|du1, d2|du2 -- d3|du3)
\ The number d2|du2 is added from the number d1|du1 to give the
\ result d3|du3. There is no detection of number /sign overflow.
\ d1|du1   A double precision signed or unsigned integer
\ d2|du2   A double precision signed or unsigned integer
\ --
\ d3|du3   A double precision signed or unsigned integer

 help_pos d>s
\ (d -- n )
\  n is the single precision signed equivalent of the double precision signed integer d
\ D         Double precision signed integer
\ --
\ N         Single precision signed integer

 help_pos dabs
\ (d -- du)
\ Convert d to its absolute unsigned value du
\ Note: negation means that d1 added to its negate will = zero.
\ d        A double precision signed integer
\ --
\ du       A double precision unsigned integer

 help_pos dnegate
\ (d1 -- d2)
\ The double precision signed integer d1 is negated to give the double
\ precision signed integer d2.
\ Note: negation means that d1 added to its negate will = zero.
\ d1       A double precision signed integer
\ --
\ d2       A double precision signed integer

 help_pos 2variable
\ (--)
\ Used in the form  2VARIABLE <name>
\ Creates a new word with name  <name> that when used gives
\ the address of a memory space big enough for a double value
\ No input parameters
\ --
\ No output parameters

 help_pos 2constant
\ (--)
\ Used in the form  two_value DCONSTANT <name>
\ Creates a new word with name  <name> that when used returns
\ two_value
\ No input parameters
\ --
\ No output parameters

 help_pos 2literal
\ (--)
\ Used in the form  two_value DCONSTANT <name>
\ Creates a new word with name  <name> that when used returns
\ two_value
\ No input parameters
\ --
\ No output parameters

 help_pos d.r
\ (d, u --)
\ The double precison signed integer d will be displayed in a right aligned
\ field of at least u characters. If d is too big for the field, then do not
\ display any leading zeros, and make the field as big as necessary to hold d.
\ d         A double precision signed integer, the number to be displayed
\ u         A single precision unsigned integer, the minimal width of the display
\ --
\ No output parameters

  [then]
  ' environment? [if]
 help_pos environment-wordlist
\ (-- wid)
\ Return the identity assigned to the Environment wordlist.
\ No input parameters
\ --
\ WID       Identity of the Environment wordlist.

 help_pos environment?
\ (-- false|(i*x,true) )
\ Used in the form  environment?   text
\ Looks for the space delimited TEXT string in the ENVIRONMENT space,
\ if not found it returns FALSE
\ else it returns the parameters belonging to the TEXT
\ No input parameters
\ --
\ Either
\   FALSE       If TEXT not found
\ Else
\   i*x         Text dependent parameter sequence
\   TRUE
\
\ No help needed since this is a environment? string
\ (-- x)
\ X is the maximum number of characters in a counted string

\ No help needed since this is an environment? string
\ (-- x)
\ X is the size of the pictured numeric output string
\ buffer in characters

\ No help needed since this is an environment? string
\ (-- x)
\ X is the size of the scratch pad area in characters

\ No help needed since this is an environment? string
\ (-- x)
\ X is the size of an address unit in bits

\ No help needed since this is an environment? string
\ (-- boolean)
\ BOOLEAN is true if and only if the entire CORE WORD SET
\ is present

\ No help needed since this is an environment? string
\ (-- boolean)
\ BOOLEAN is true if and only if floored division is the default

\ No help needed since this is an environment? string
\ (-- x)
\ X is the maximum value of any character permitted by this
\ implementation

\ No help needed since this is an environment? string
\ (-- d)
\ D is the maximum value of signed double precision integer

\ No help needed since this is an environment? string
\ (-- n)
\ N is the maximum value of signed single precision integer

\ No help needed since this is an environment? string
\ (-- u)
\ U is the maximum value of unsigned single precision integer

\ No help needed since this is an environment? string
\ (-- d)
\ D is the maximum value of unsigned double precision integer

\ No help needed since this is an environment? string
\ (-- n)
\ N is the size ofthe return stack in cells

\ No help needed since this is an environment? string
\ (-- n)
\ N is the size ofthe data stack in cells

  [then]
  ' catch [if]
 help_pos abort
\ (x?, ..x1 --)
\ Discard all cells on the stack then execute QUIT
\ x?, ..x1   All cells on the stack
\ --
\ No output parameters

 help_pos catch
\ (i*x, xt -- (j*x,0)|(i*x,n) )
\  Execute the eXecution Token  XT
\  IF the definition THROW is executed prior to the XT returning control
\  to  CATCH, then:
\    execution will return to CATCH
\    CATCH will reset the return and data stack pointers to their
\    depth as of entry to CATCH.
\    CATCH will de-nest any nested input streams back to the stream
\    that was active when CATCH was entered
\ I*X       Unknown stack content on entry to  XT
\ XT        eXecution Token of definition to be executed
\ --
\ Either
\ J*X       Unknown stack content
\ 0         means THROW was NOT executed
\ OR
\ I*X       Recovered stack content
\ N         <> 0 means THROW was executed
\           and N = value returned by THROW

 help_pos throw
\ (l*x, n -- k*x|(i*x, n) )
\ If N <>0
\   recover data & return stack depths
\   recover input stream nesting level
\   return to the last CATCH command
\ ELSE
\   continue execution with the next command
\
\ L*X       Unknown stack content on return to CATCH
\ N         Cell sized value
\ --
\ Either
\
\   K*X    Unknown stack content for passing to next command
\ OR
\   I*X    Recovered stack depth for return to CATCH
\   N      The input N value

   [THEN]
  ' open-file [if]
 help_pos file@ext
\ ( -- c-addr, u   )
\ Return the file extension part of a path/file name that
\ was decomposed by the command  file>components,
\ a character string at c-addr and of length u characters
\
\ No input parameters
\ --
\ c-addr    Start address of extension name (after the period ".")
\ u         Length of extension name

 help_pos file@name
\ ( -- c-addr, u)
\ Return the file name part of a path/file name that
\ was decomposed by the command  file>components,
\ a character string at c-addr and of length u characters
\
\ No input parameters
\ --
\ c-addr    Start address of file name (after the last "\" and before the first period ".")
\ u         Length of file name

 help_pos file@path
\ ( -- c-addr, u)
\ Return the path name part of a path/file name that
\ was decomposed by the command  file>components,
\ a character string at c-addr and of length u characters
\
\ No input parameters
\ --
\ c-addr    Start address of path name (up to and including the last "\")
\ u         Length of path name

 help_pos file@volume
\ ( -- c-addr, u)
\ Return the volume name part of a path/file name that
\ was decomposed by the command  file>components,
\ a character string at c-addr and of length u characters
\
\ No input parameters
\ --
\ c-addr    Start address of volume name
\ u         Length of volume name

 help_pos file>components
\ (c-addr, u --  )
\ Decompose the path/file specified by the character string
\ at C_ADDR and of length U characters, into its
\ component parts strings: volume, path, file, extension
\
\ c-addr    Start address of path/file name
\ u         Length of volume name
\ --
\ No output parameters

 help_pos fam=ro
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "read only" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character r

 help_pos fam=rw
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "read write" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            two characters r+

 help_pos fam=wo
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "write only" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character w

 help_pos fam=wa
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "append" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character a

 help_pos fam>bin
\ ( OAc-addr , OAu-- EAc-addr , EAu )
\ Extend the file access method fam1 to include "binary" access
\ OAc-addr    Address of a character string holding the original access method
\ OAu         Length of character string
\ --
\ OAc-addr    Address of a character string holding the extended access method
\ OAu         Length of character string

 help_pos file=open
\ (Nc-addr, Nu, Ac-addr, Au, -- file-id, ior)
\ Open a file with the name given by the text string Nc-addr and length Nu for
\ the access given by  the text string Ac-addr and length Au.
\ If the operation was successful
\ then return file-id = file identifier allocated by the
\      system and IOR = 0
\ else return file-id = undefined and IOR = -1
\ Nc-addr    Address of a character string holding the file name
\ Nu         Length of character string
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string( see R/O  R/W  W/O )
\ --
\ file-id   system allocated file identity
\ ior       = 0 if okay, else -1 on error

 help_pos file@buffer
\ (c-addr, u1, file-id -- u2, ior)
\ Read u1 characters from the file identified by file-id, to
\ the byte buffer starting at c-addr. Stop the read operation on
\ encountering an end of line or end of file condition.
\ If the operation does not cause an error condition, then
\   return u2 = number of bytes read in, ior = 0
\   else u2 = indeterminate, ior = -1
\ c-addr    Start address of buffer to receive data
\ u1        Maximum length of data to be read
\ file-id   System assigned file identity of file to be read
\ --
\ u2        Number of bytes read
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos file=buffer
\ (c-addr, u1, file-id -- ior)
\ Write the u1 characters from the byte buffer starting at
\ c-addr, to the open file with the system identity file-id.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ c-addr    Start address of bytes sequence to be written to file
\ u1        Length of data to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos file@cline
\ (c-addr, u1, file-id -- u2, flag, ior)
\ Read at most u1 CHARACTERS from the file identified by file-id, to
\ the CHARACTERS buffer starting at c-addr. Stop the read operation on
\ encountering an end of line or end of file condition.
\ If the operation does not cause an error condition, then
\   return u2 = number of CHARACTERS read in, flag = TRUE, ior = 0
\   else u2 = indeterminate, ior = system defined error code
\ c-addr    Start address of buffer to receive the CHARACTERS
\ u1        Maximum length of data to be read
\ file-id   System assigned file identity of file to be read
\ --
\ u2        Number of CHARACTERS read
\ flag      = TRUE if no errors occurred, else FALSE
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos file=cline
\ (c-addr, u1, file-id -- ior)
\ Write the u1 CHARACTERS from the CHARACTERS buffer starting at
\ c-addr, to the open file with the system identity file-id. Append
\ a new line CHARACTERS to the file.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ c-addr    Start address of CHARACTERS sequence to be written to file
\ u1        Length of data to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos file=close
\ (file-id -- ior)
\ If file-id is the system identity of an open file, then
\ close the file.
\ file-id    File identity of file to be closed
\ --
\ ior        = 0 if okay, else -1 on erro

 help_pos file=delete
\ (c-addr, u, -- ior)
\ Delete the file with the name given by c-addr and length u.
\ If the operation was successful
\ then return ior = 0, else return ior = -1
\ c-addr    Address of file name as a character string
\ u         Length of character string
\ --
\ ior       = 0 if okay, else -1 on error

 help_pos file=create
\ (c-addr, u, fam -- file-id, ior)
\ Create a file with the name given by c-addr and length u.
\ If a file with the same name already exists, then delete it.
\ The open the file for the access defined by FAM.
\ If the file create and open operation was successful
\ then return file-id = file identifier allocated by the
\      system and IOR = 0
\ else return file-id = undefined and IOR = -1
\ c-addr    Address of file name as a character string
\ u         Length of character string
\ fam       file access method ( see R/O  R/W  W/O )
\ --
\ file-id   system allocated file identity
\ ior       = 0 if okay, else -1 on error

 help_pos file@ptr
\ (file-id -- ud, ior)
\ Obtain the current position of the system file pointer
\ associated with the open file file-id.
\ If the operation was successful
\ then return ud = file position and ior = 0,
\ else return ud = undefined and ior = -1
\ file-id   system allocated identity of file
\ --
\ ud        file position as an unsigned DOUBLE precision integer
\ ior       = 0 if okay, else -1 on error

 help_pos file=ptr
\ (ud, file-id -- ior)
\ Set the position of the system file pointer associated with the
\ open file file-id to be ud
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ ud       new position of file pointer as an unsigned DOUBLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos file@size
\ (file-id -- ud, ior)
\ Obtain the size of the open file with the system identity file-id.
\ If the operation was successful
\ then return ud = file size and ior = 0,
\ else return ud = undefined and ior = -1
\ file-id   system allocated identity of file
\ --
\ ud        file size as an unsigned DOUBLE precision integer
\ ior       = 0 if okay, else -1 on error

 help_pos file=copy
\ (c-addrS, uS , c-addrD , uD -- boolean )
\ Copy the path/file specified by the string c-addrS, uS  to the c-addrS, uS , c-addrD , uD  specified by  c-addrD , uD
\ C-ADDRS   Address of a character string holding the SOURCE file name
\ US        Length of character string
\ C-ADDRD   Address of a character string holding the DESTINATION file name
\ UD        Length of character string
\ --
\ BOOLEAN    = 0 on error

 help_pos file=move
\ (c-addrS, uS , c-addrD , uD -- boolean )
\ Move the path/file specified by the string c-addrS, uS  to the c-addrS, uS , c-addrD , uD  specified by  c-addrD , uD
\ C-ADDRS   Address of a character string holding the SOURCE file name
\ US        Length of character string
\ C-ADDRD   Address of a character string holding the DESTINATION file name
\ UD        Length of character string
\ --
\ BOOLEAN    = 0 on error
\ STDOUT     The file_stream_ptr value for the standard output file

 help_pos stdout
\ (-- file_stream_ptr)
\ Return the file_stream_ptr  STDOUT assigned by the system to the default output file stream
\ No input parameters
\ --
\ STDOUT     The file_stream_ptr value for the standard output file

 help_pos stdin
\ (-- file_stream_ptr)
\ Return the file_stream_ptr  STDIN assigned by the system to the default input file stream
\ No input parameters
\ --
\ STDIN      The file_stream_ptr value for the standard input file

 help_pos open-file
\ (Nc-addr, Nu, Ac-addr, Au, -- file-id, ior)
\ Open a file with the name given by the text string Nc-addr and length Nu for
\ the access given by  the text string Ac-addr and length Au.
\ If the operation was successful
\ then return file-id = file identifier allocated by the
\      system and IOR = 0
\ else return file-id = undefined and IOR = -1
\ Nc-addr    Address of a character string holding the file name
\ Nu         Length of character string
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string( see R/O  R/W  W/O )
\ --
\ file-id   system allocated file identity
\ ior       = 0 if okay, else -1 on error

 help_pos read-file
\ (c-addr, u1, file-id -- u2, ior)
\ Read u1 characters from the file identified by file-id, to
\ the character buffer starting at c-addr. Stop the read operation on
\ encountering an END OF LINE or END OF FILE condition.
\ Bewarned: if you want to read all characters then you need to set the BIN condition.
\ If the operation does not cause an error condition, then
\   return u2 = number of characters read in, ior = 0
\   else u2 = indeterminate, ior = -1
\ c-addr    Start address of buffer to receive data
\ u1        Maximum length of data to be read
\ file-id   System assigned file identity of file to be read
\ --
\ u2        Number of characters read
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos file@byte
\ (file-id -- byte, ior)
\ Reads 1 byte  from the file identified by file-id.
\ If the operation does not cause an error condition, then
\   return the read byte
\   else byte = indeterminate, ior = -1
\ file-id   System assigned file identity of file to be read
\ --
\ Byte      Read byte
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos write-file
\ (c-addr, u1, file-id -- ior)
\ Write the u1 BYTES from the BYTE buffer starting at
\ c-addr, to the open file with the system identity file-id.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ c-addr    Start address of BYTE sequence to be written to file
\ u1        Length of data, in BYTES, to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos close-file
\ (file-id -- ior)
\ If file-id is the system identity of an open file, then
\ close the file.
\ file-id    File identity of file to be closed
\ --
\ ior        = 0 if okay, else -1 on erro

 help_pos r/o
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "read only" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character r

 help_pos r/w
\ ( -- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "read write" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            two characters r+

 help_pos w/a
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "append" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character a

 help_pos w/o
\ (-- Ac-addr , Au )
\ Return the system dependant expression for opening a file
\ with the "write only" access method.
\ No input parameters
\ --
\ Ac-addr    Address of a character string holding the access method
\ Au         Length of character string
\            A zero terminated character string containing the
\            single character w

 help_pos fam>utf8
\ ( OAc-addr , OAu-- EAc-addr , EAu )
\ EXTEND the file access method  to   open the target file in  UTF-8
\ OAc-addr    Address of a character string holding the original access method
\ OAu         Length of character string
\ --
\ OAc-addr    Address of a character string holding the extended access method
\ OAu         Length of character string

 help_pos fam>wchar
\ ( OAc-addr , OAu-- EAc-addr , EAu )
\ EXTEND the file access method  to   open the target file in  wide characater = UNICODE mode
\ OAc-addr    Address of a character string holding the original access method
\ OAu         Length of character string
\ --
\ OAc-addr    Address of a character string holding the extended access method
\ OAu         Length of character string

 help_pos fam>cli
\ ( OAc-addr , OAu-- EAc-addr , EAu )
\ EXTEND the file access method  to include open the target file in the same character encoding scheme
\ as this interpreter uses for it command line input
\ OAc-addr    Address of a character string holding the original access method
\ OAu         Length of character string
\ --
\ OAc-addr    Address of a character string holding the extended access method
\ OAu         Length of character string

 help_pos bin
\ ( OAc-addr , OAu-- EAc-addr , EAu )
\ EXTEND the file access method fam1 to include "binary" access
\ OAc-addr    Address of a character string holding the original access method
\ OAu         Length of character string
\ --
\ OAc-addr    Address of a character string holding the extended access method
\ OAu         Length of character string

 help_pos file-position
\ (file-id -- u, ior)
\ Obtain the current position of the system file pointer
\ associated with the open file file-id.
\ If the operation was successful
\ then return ud = file position and ior = 0,
\ else return ud = undefined and ior = -1
\ file-id   system allocated identity of file
\ --
\ ud        file position as an unsigned SINGLE precision integer
\ ior       = 0 if okay, else -1 on error

 help_pos file.seek=begin
\ (ud, file-id -- ior)
\ Set the position of the system file pointer associated with the
\ open file file-id to be at the beginning of the file
\ Then move the file ptr forwards   UD bytes
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ ud         new position of file pointer as an unsigned SINGLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos file.seek=end
\ (ud, file-id -- ior)
\ Set the position of the system file pointer associated with the
\ open file file-id to be at the end of the file
\ Then move the file ptr backwards   UD bytes
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ ud        new position of file pointer as an unsigned DOUBLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos file.seek=offset
\ (D, file-id -- ior)
\ Move the position of the system file pointer associated with the
\ open file file-id to be  D bytes  from its current position
\ Note that D can be negative !
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ d          new position of file pointer as a signed SINGLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos dfile-position
\ (file-id -- ud, ior)
\ Obtain the current position of the system file pointer
\ associated with the open file file-id.
\ If the operation was successful
\ then return ud = file position and ior = 0,
\ else return ud = undefined and ior = -1
\ file-id   system allocated identity of file
\ --
\ ud        file position as an unsigned SINGLE precision integer
\ ior       = 0 if okay, else -1 on error

 help_pos reposition-file
\ (u, file-id -- ior)
\ Set the position of the system file pointer associated with the
\ open file file-id to be ud
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ u        new position of file pointer as an unsigned SINGLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos dreposition-file
\ (ud, file-id -- ior)
\ Set the position of the system file pointer associated with the
\ open file file-id to be ud
\ If the operation was successful, return ior = 0
\ else return ior <> 0
\ ud       new position of file pointer as an unsigned DOUBLE precision integer
\ file-id   system allocated identity of file
\ --
\ ior       = 0 if okay
\           <> 0 if an error occured

 help_pos read-bline
\ (c-addr, u1, file-id -- u2, flag, ior)
\ Read at most u1  BYTES from the file identified by file-id, to
\ the BYTES buffer starting at c-addr. Stop the read operation on
\ encountering an end of line or end of file condition.
\ If the operation does not cause an error condition, then
\   return u2 = number of BYTES read in, flag = TRUE, ior = 0
\   else u2 = indeterminate, ior = system defined error code
\ c-addr    Start address of buffer to receive data
\ u1        Maximum length of data to be read
\ file-id   System assigned file identity of file to be read
\ --
\ u2        Number of BYTES read
\ flag      = TRUE if no errors occurred, else FALSE
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos write-bline
\ (c-addr, u1, file-id -- ior)
\ Write the u1 BYTES from the BYTE buffer starting at
\ c-addr, to the open file with the system identity file-id. Append
\ a new line BYTE to the file.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ c-addr    Start address of BYTE sequence to be written to file
\ u1        Length of data to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos write-byte
\ ( x, file-id -- ior)
\ Write the   BYTE x  to the open file with the system identity file-id.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ x         Byte to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos write-char
\ ( x, file-id -- ior)
\ Write the   CHAR x  to the open file with the system identity file-id.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ x         CHAR to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos read-cline
\ (c-addr, u1, file-id -- u2, flag, ior)
\ Read at most u1 CHARACTERS  from the file identified by file-id, to
\ the CHARACTER buffer starting at c-addr. Stop the read operation on
\ encountering an end of line or end of file condition.
\ If the operation does not cause an error condition, then
\   return u2 = number of characters read in, flag = TRUE, ior = 0
\   else u2 = indeterminate, ior = system defined error code
\ c-addr    Start address of buffer to receive data
\ u1        Maximum length of data to be read
\ file-id   System assigned file identity of file to be read
\ --
\ u2        Number of characters read
\ flag      = TRUE if no errors occurred, else FALSE
\ ior       = 0 if okay, else system defined error code
\ Note:     u2 can be less than u1 if at end of file

 help_pos write-cline
\ (c-addr, u1, file-id -- ior)
\ Write the u1 CHARACTERS from the CHARACTER buffer starting at
\ c-addr, to the open file with the system identity file-id. Append
\ a new line character to the file.
\ If the operation does not cause an error condition, then
\   return ior = 0
\   else ior = system defined error code
\ c-addr    Start address of CHARACTER sequence to be written to file
\ u1        Length of data to be written
\ file-id   System assigned file identity of file to be read
\ --
\ ior       = 0 if okay, else = system defined error code

 help_pos included
\ (c-addr, u -- )
\ The current input stream specification will be saved (nested).
\ The file identified by the character string at c-addr and of length u
\ will be opened and its contents passed to the command line interpreter.
\ On End Of File condition, the file will be closed. The previous input
\ stream specification will be recovered (de-nested) and execution will
\ continue with the next instruction of the input stream.
\ C-ADDR    Address of a character string - name of file to be included
\ U         Length of the character string
\ --
\ No output parameters

 help_pos include-file
\ (file-id --)
\ The current input stream specification will be saved (nested).
\ The file identified by the system identity file-id will be passed line by
\ line to the command line interpreter.
\ On End Of File condition, the file will be closed. The previous input
\ stream specification will be recovered (de-nested) and execution will
\ continue with the next instruction of the input stream.
\ file-id   System identity of an open file
\ --
\ No output parameters

 help_pos file=recycle
\ (c-addr, u, -- ior)
\ Delete the file with the name given by c-addr and length u, by
\ sending the file to the Recycle Bin.
\ If the operation was successful
\ then return ior = 0, else return ior = -1
\ c-addr    Address of file name as a character string
\ u         Length of character string
\ --
\ ior       = 0 if okay, else -1 on error

 help_pos delete-file
\ (c-addr, u, -- ior)
\ Delete the file with the name given by c-addr and length u.
\ If the operation was successful
\ then return ior = 0, else return ior = -1
\ c-addr    Address of file name as a character string
\ u         Length of character string
\ --
\ ior       = 0 if okay, else -1 on error

 help_pos create-file
\ (Nc - addr, Nu, Ac - addr, Au, -- file-id, ior)
\ Create a file with the name given by the text string Nc - addr and length Nu
\ If a file with the same name already exists, then delete it.
\ The open the file for the access given by  the text string Ac - addr and length Au.
\ If the file create and open operation was successful
\ then return file-id = file identifier allocated by the
\      system and IOR = 0
\ else return file-id = undefined and IOR = -1
\ Nc - addr    Address of a character string holding the file name
\ Nu         Length of character string
\ Ac - addr    Address of a character string holding the access method
\ Au         Length of character string
\ --
\ file-id   system allocated file identity
\ ior       = 0 if okay, else -1 on error

 help_pos file-size
\ (file-id -- u, ior)
\ Obtain the size of the open file with the system identity file-id.
\ If the operation was successful
\ then return u = file size and ior = 0,
\ else return u = undefined and ior = -1
\ file-id   system allocated identity of file
\ --
\ u         file size as an unsigned SINGLE precision integer
\ ior       = 0 if okay, else -1 on error

\ help_pos \\
\ ( -- )
\ If the current input source is a file , then this
\ forces the EOF condition

    [then]
  ' flush-file [if]
 help_pos file>name
\ (c-addrO, uO, c-addrN, uN -- ior)
\ Rename the file with the name given by the character string
\ at c-addrO and length uO, to the name the name given by the
\ character string at c-addrN and length uN.
\ c-addrO   Address of a character string holding the original file name
\ uO        Length of character string
\ c-addrN   Address of a character string holding the new file name
\ uN        Length of character string
\ --
\ ior       = 0 if okay, else -1 on error

 help_pos file-status
\ (c-addr, u1 -- u, ior)
\ Check whether the file with the name given by the character string
\ at c-addr and length u1 exists.
\ c-addr    Address of a character string holding the  file name
\ u1        Length of character string
\ --
\ u2        = 0 if okay, else -1 on error
\ ior       = 0 if okay, else -1 on error

 help_pos flush-file
\ (file-id -- ior)
\ Any buffered output that has not yet been transfered to the file on the
\ file strorage medium should now be transfered, and the buffer cleared.
\ If the operation was successful
\ then return ior = 0
\ else ior = system defined error code
\ No input parameters
\ --
\ ior       = 0 if operation okay, else  error

 help_pos rename-file
\ (c-addrO, uO, c-addrN, uN -- ior)
\ Rename the file with the name given by the character string
\ at c-addrO and length uO, to the name the name given by the
\ character string at c-addrN and length uN.
\ c-addrO   Address of a character string holding the original file name
\ uO        Length of character string
\ c-addrN   Address of a character string holding the new file name
\ uN        Length of character string
\ --
\ ior       = 0 if okay, else -1 on error

    [then]
 help_pos verify
\ (--)
\ Toggles an internal flag used to control whether input lines
\ from an INCLUDED file should be displayed as they are being read in
\ No input parameters
\ --
\ No output parameters

 help_pos pipe.to.file
\ (stream_id --)
\ Send future character output to the specified output stream
\ STREAM-ID   File identity of destination file
\ --
\ No output parameters

 help_pos log.to.file
\ (stream_id --)
\ Send future character output to the specified output stream
\ STREAM-ID   File identity of destination file
\ --
\ No output parameters

 help_pos help-file
\ (-- c-addr , count)
\ Returns the string containing the default help path&file name
\ C-ADDR    address of a text string -  path&file name of default help file
\ COUNT     length of text string
\ --
\ No output parameters

    [then]
  ' file.find=open [if]
 help_pos file@exists
\ (c-addr, u1 -- flag)
\ Check whether the file with the name given by the character string
\ at c-addr and length u1 exists.
\ Also works with FOLDERS  do not terminate folder name with a \    !
\ c-addr    Address of a character string holding the  file name
\ u1        Length of character string
\ --
\ flag      = 0 if fail, else okay
\           = 1 is FILE
\           = -1 is FOLDER

 help_pos file.find=close.all
\ (--)
\ Terminates all open file searches.
\ Returns any related temporary memory to the system.
\ No input parameters
\ --
\ No output parameters

 help_pos file.find=close
\ (search-id --)
\ Terminates a file search, started using the file.find=open command
\ or a subsequent findfile=next, that returned the identity  search-id.
\ Returns any related temporary memory to the system.
\ SEARCH-ID  The value returned by findfile and/or findfile=next
\ --
\ no return parameters

 help_pos file.find=open
\ (c-addr , u -- search-id|-1)
\ Starts a new file search
\ C-ADDR    address of a character string - giving name of file to be searched for.
\           The wildcard characters * and ? are permitted in the name
\           The name may start with a path name if required.
\ U         length of character string
\ --
\ SEARCH-ID|-1  If the search was successful then this command returns the SEARCH-ID
\               else it returns -1
\               The SEARCH-ID can be used to obtain information about the found file
\               See also  file.found@name , file.found@size ,...

 help_pos file.find=next
\ (search-id -- search-id|-1)
\ Searches for the next matching file
\ SEARCH-ID  The value returned by file.find=open and/or findfile=next
\ --
\ SEARCH-ID|-1  If the search was successful then this command returns the SEARCH-ID
\               else it returns -1
\               The SEARCH-ID can be used to obtain information about the found file
\               See also  file.found@name , file.found@size ,...

 help_pos file.found@name
\ (search-id -- c-addr , u)
\ Obtains the name of the found file
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ C-ADDR    address of a character string - giving name of file found by a
\           file.find=open or file.find=next command
\ U         length of character string

 help_pos file.found@name.short
\ (search-id -- c-addr , u )
\ Obtains the short version of the name of the found file
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ C-ADDR    address of a character string - giving name of file found by a
\           file.find=open or file.find=next command
\ U         length of character string ( will not exceed 14 characters!)

 help_pos file.found@attributes
\ (search-id -- u)
\ Obtains the attributes of the found file
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ U         An unsigned integer containing the attributes of the file found by a
\           findfile or findfile=next command
\           0x01 = read only
\           0x02 = hidden
\           0x04 = system
\           0x10 = directory
\           0x80 = normal

 help_pos file.found@size
\ (search-id -- u-low , u-high)
\ Obtains the size in bytes of the found file
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ U-LOW     An unsigned integer containing lower 32 bits of the size of the file
\           found by a file.find=open or file.find=next command
\ U-HIGH    An unsigned integer containing upper 32 bits of the size of the file.

 help_pos file.found@last.write
\ (search-id -- u-low , u-high)
\ Obtains the last write to time for the found file.
\ See    file.time=text
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ U-LOW     An unsigned integer containing the lower part of the time
\           found by a file.find=open or file.find=next command
\ U-HIGH    An unsigned integer containing the upper part of the time

 help_pos file.found@create
\ (search-id -- u-low , u-high)
\ Obtains the creation time for the found file.
\ See    file.time=text
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ U-LOW     An unsigned integer containing the lower part of the time
\           found by a file.find=open or file.find=next command
\ U-HIGH    An unsigned integer containing the upper part of the time

 help_pos file.found@last.access
\ (search-id -- u-low , u-high)
\ Obtains the last access time for the found file.
\ See    file.time=text
\ SEARCH-ID  The value returned by file.find=open and/or file.find=next
\ --
\ U-LOW     An unsigned integer containing the lower part of the time
\           found by a file.find=open or file.find=next command
\ U-HIGH    An unsigned integer containing the upper part of the time

 help_pos date>fileTime
\ (year, month, day , DayOfWeek -- LowValue, HighValue)
\ Year       As an integer expressed in Common Era
\ Month      As an integer 1-12   1= January
\ Day        As an integer 1-31
\ DayOfWeek  As an integer 0-06   0 = Sunday
\ --
\ FILETIME

 help_pos time"
\ (-- c-addr , u )
\ Create a character string containg the date in the format "hh:mm:ss"
\ Hours in 24 hour format
\ No input parameters
\ --
\ C-ADDR     Address of character string
\ u          Length of string in characters

 help_pos date"
\ (-- c-addr , u )
\ Create a character string containg the date in the format "yyyy-mm-dd"
\ Date is based on the "Common Era".
\ No input parameters
\ --
\ C-ADDR     Address of character string
\ u          Length of string in characters

 help_pos time@
\ (-- hour, minute, second, millisecond)
\ No input parameters
\ --
\ Hour      As an integer 0-23
\ Minute    As an integer 0-59
\ Second    As an integer 0-59
\ Millisec  As an integer 0-999

 help_pos date@
\ (-- year, month, day, dayOfWeek)
\ No input parameters
\ --
\ Year       As an integer expressed in Common Era
\ Month      As an integer 1-12   1= January
\ Day        As an integer 1-31
\ DayOfWeek  As an integer 0-06   0 = Sunday

 help_pos file.time=text
\ (u-low , u-high -- c-addr, u)
\ Take the 2 unsigned integers returned by one of:
\    file.found@last.access
\    file.found@create
\    file.found@last.write
\ and convert them in to a date / time in text format.
\ U-LOW     An unsigned integer containing lower 32 bits of the size of the file
\           found by a file.find=open or file.find=next command
\ U-HIGH    An unsigned integer containing upper 32 bits of the size of the file.
\ --
\ C-ADDR    address of a character string - giving   file  modification date
\ U         length of character string

 help_pos app=cwd
\ (c-addr , u -- -1|0)
\ Assigns the given path name to be the default/working directory
\ C-ADDR    Address of a character string - giving path name of directory to be
\           used as the current directory.
\           WARNING:      C:\FRED   will set the CWD to be FRED
\           a subsequent  C:   will only change the DRIVE
\           so if you meant the root dir of C  use  C:\
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos mk-dir
\ (c-addr , u -- -1|0)
\ Creates the named directory.
\ C-ADDR    Address of a character string - giving path name of directory to be
\           created
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos rm-dir
\ (c-addr , u -- -1|0)
\ Deletes the named directory.
\ C-ADDR    Address of a character string - giving path name of directory to be
\           deleted
\ U         length of character string
\ --
\ -1|0      Returns 0 if successful, else returns -1

 help_pos app@cwd
\ (-- c-addr , u)
\ Obtains the path name of the default/working directory
\ No input parameters
\ --
\ C-ADDR    Address of a character string - giving path name of current directory
\ U         length of character string

 help_pos save=cwd
\ (--)
\ Save the current working directory name in an internal buffer,
\ See  saved-cwd  to gain access to the path as a character string
\ No input parameters
\ --
\ No output parameters

 help_pos save@cwd
\ (-- c-addr , u)
\ Return the string containing the Saved  current working directory
\ No input parameters
\ --
\ C-ADDR    Address of character string giving path name of saved CWD
\ U         length of character string

 help_pos app=drv
\ (u -- 0|-1)
\ Changes the default drive device
\ U        Number representing the drive that is to be the default drive
\          In Microsoft Windows  1..26   0=A  26=Z
\ --
\ -1|0     Returns 0 if successful, else returns -1

 help_pos app@drv
\ (-- u)
\ Obtains the number representing the default drive device
\ --
\ U        Number representing the drive that is the default drive
\          In Microsoft Windows  1..26   0=A  26=Z

   [then]
  ' dfloats [if]
 help_pos numeric?
\ (c-addr , u  -- [0 | xValue , TRUE])
\ Convert the entire character string pointed at by C_ADDR,U to a numerical value.
\ If the entire string is an INTEGER                  then return   iValue , 1
\ If the entire string is an Double Precision INTEGER then return   dValue , 2
\ If the entire string is an Floating number          then return   fValue , 3
\ C-ADDR    Character aligned memory address = address of first character in string
\ U         Length of string in characters
\ --
\ either
\ 0          If string is not a numercial representation
\ OR
\ X         Single  Precision Integer value
\ 1
\ OR
\ D         Double Precision Integer value
\ 2
\ OR
\ F         Floating number
\ 3

\ (-- flag)
\  Indicates whether there is a separate stack
\  for  floating numbers

\ (-- Fmax)
\  Returns    The maximum float number

 help_pos falign
\ (--)
\ If the data-space pointer is not float aligned then align it
\ No input parameters
\ --
\ No output parameters

 help_pos faligned
\ (addr -- f-addr)
\ If the addres addr is not float aligned then align it and return
\ the aligned address f-addr.
\ addr       A memory address
\ --
\ f-addr     A floating point aligned memory address

 help_pos floats
\ (n1 -- n2)
\ Returns n2 the number of address units in n1 floating point numbers
\ n1         Number of floating point values
\ --
\ n2         Number of address unit in n1 floating point numbers

 help_pos float+
\ (f-addr1 -- f-addr2)
\ Adds the size in address units of a single floating point
\ number to the address   f-addr1  to give  f-addr2
\ f-addr1    A floating point aligned address
\ --
\ f-addr2    The next floating point aligned address after f-addr1

 help_pos f+
\ (f1 , f2 -- f3)
\ The floating point number f2 is added to the floating point number f1
\ to give the resulting floating point number f3
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The floating point result of  f1 + f2

 help_pos f-
\ (f1 , f2 -- f3)
\ The floating point number f2 is subtracted from the floating point number f1
\ to give the resulting floating point number f3
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The floating point result of  f1 - f2

 help_pos f/
\ (f1 , f2 -- f3)
\ The floating point number f1 is divided by the floating point number f2
\ to give the resulting floating point number f3.
\ If f2 = 0 then a trap to an internal error handler occurs.
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The floating point result of  f1 / f2

 help_pos f*
\ (f1 , f2 -- f3)
\ The floating point number f1 is multiplied by the floating point number f2
\ to give the resulting floating point number f3.
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The floating point result of  f1 * f2

 help_pos fvariable
\ (--)
\ Used in the form  FVARIABLE fred
\ Creates a new word with name  fred that when used gives
\ the address of a memory space big enough for a FLOAT_TYPE value.
\ Is initialised to hold   0.0
\ No input parameters
\ --
\ No output parameters

 help_pos f<
\ (f1 f2 -- bool)
\ Compares the two floating point numbers f1 and f2.
\ Returns bool = TRUE if and only if  f1 is less than f2 , else bool = false.
\ f1         A floating point number
\ f2         A floating point number
\ --
\ bool      = TRUE if and only if  f1 is less than f2
\           else = false

 help_pos f>
\ (f1 f2 -- bool)
\ Compares the two floating point numbers f1 and f2.
\ Returns bool = TRUE if and only if  f1 is greater than f2 , else bool = false.
\ f1         A floating point number
\ f2         A floating point number
\ --
\ bool      = TRUE if and only if  f1 is greater than f2
\           else = false

 help_pos fover
\ (f1 , f2 -- f1 , f2 , f1)
\ The second floating point number on the stack is copied to the top.
\ f1         A floating number
\ f2         A floating number
\ --
\ f1         A floating number
\ f2         A floating number
\ f1         A floating number

 help_pos frot
\ (f1 , f2 , f3 -- f2 , f3 , f1)
\ The top three  flaoting point numbers on the stack are rotated
\ f1         A floating number
\ f2         A floating number
\ f3         A floating number
\ --
\ f2         A floating number
\ f3         A floating number
\ f1         A floating number

 help_pos fswap
\ (f1 , f2 -- f2 , f1)
\ The top two  floating point numbers on the stack are exchanged
\ f1         A floating number
\ f2         A floating number
\ --
\ f2         A floating number
\ f1         A floating number

 help_pos fdrop
\ (f --)
\ The top floating point number on the stack is discarded
\ f          A floating number
\ --
\ No output parameters

 help_pos f=
\ (f1, f2 -- bool)
\ Compares the floating point number f1 with f2.
\ Returns bool = TRUE if and only if f1 is equal to f2 , else bool = false.
\ f1         A floating point number
\ f2         A floating point number
\ --
\ bool      = TRUE if and only if f1 is equal to f2
\           else = false

 help_pos fdup
\ (f -- f , f)
\ The top floating point number on the stack is duplicated
\ f          A floating number
\ f2         A floating number
\ --
\ f          A floating number
\ f          A floating number

 help_pos fconstant
\ (Fx --)
\ Used in the form  Fx FCONSTANT fred
\ Create a new definition with the name  fred that when used returns Fx
\ FX       Floating point number
\ --
\ No output parameters

\ help_pos f,
\ (f --)
\ The floating point number f will be written to the next floating point sized
\ location of the free dataspace.
\ f          A floating point number
\ --
\ No output parameters

 help_pos fdepth
\ (-- x)
\ Returns the number of floating point numbers that could be on the stack if
\ all currently occupied cells were used by floating point numbers
\ No input parameters
\ --
\ n          Number of floating point numbers that could be on the stack

 help_pos fmax
\ (f1 f2 -- f3)
\ Compares the two floating point numbers f1 and f2 and returns the larger as f3
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The larger of the two floating point numbers f1 and f2

 help_pos fmin
\ (f1 f2 -- f3)
\ Compares the two floating point numbers f1 and f2 and returns the smaller as f3
\ f1         A floating point number
\ f2         A floating point number
\ --
\ f3         The smaller of the two floating point numbers f1 and f2

 help_pos fnegate
\ (f -- -f)
\ The sign of the floating point number f1 is negated.
\ f         A floating point numbe
\ --
\ -f        The negate of f

 help_pos f@
\ (f-addr -- f)
\ Read the floating point value f, from the floating point address f-addr
\ If f-addr is not floating point aligned then a trap to an internal error handle occurs.
\ f-addr     A floating point aligned memory address
\ --
\ f          The floating point value located at the address f-addr

 help_pos f!
\ (f , f-addr --)
\ Writes the floating point value f, to the floating point address f-addr
\ If f-addr is not floating point aligned then a trap to an internal error handle occurs.
\ f          A floating point value
\ f-addr     A floating point aligned memory address
\ --
\ No output parameters

 help_pos f0=
\ (f -- bool)
\ Compares the floating point number f with 0.
\ Returns bool = TRUE if and only if f is equal to 0 , else bool = false.
\ f1         A floating point number
\ --
\ bool      = TRUE if and only if f is equal to 0
\           else = false

 help_pos f0<
\ (f -- bool)
\ Compares the floating point number f with 0.
\ Returns bool = TRUE if and only if f is equal to 0 , else bool = false.
\ f1         A floating point number
\ --
\ bool      = TRUE if and only if f is equal to 0
\           else = false

 help_pos d>f
\ (d -- f)
\ Convert the double precision integer to a floating point representation
\ d         A double precision signed integer
\ --
\ f         f is the floating-point representation of d

 help_pos f>d
\ (f -- d)
\ Convert the integer part of the floating point number f to a double precision integer
\ f         A floating-point number
\ --
\ d         A double precision signed integer equal to the integer part of f

 help_pos f>s
\ (s -- f)
\ Convert a floating point representation to a signed integer
\ f         f is the floating-point representation of d
\ --
\ s         A single precision signed integer

 help_pos s>f
\ (s -- f)
\ Convert the single precision signed integer to a floating point representation
\ s         A single precision signed integer
\ --
\ f         f is the floating-point representation of d

 help_pos >float
\ (c-addr , count -- (f,true)|false)
\ Convert the character string c-addr, count to a number in floating
\ point representation. If the conversion was succesful then
\ return f the floating point number and a TRUE flag.
\ If the conversion was unsuccesful return only FALSE.
\ Special case: a string of spaces shall be considered to
\ be the floating point zero number
\ C-ADDR    address of a character string
\ COUNT     length of character string
\ --
\ either the conversion was successful:
\ F         the floating point number
\ BOOL      = TRUE
\ or the conversion was unsuccessful:
\ BOOL      = zero

 help_pos fsplit
\ (f1 -- fint, fdec ) (F: r1 -- rInt, rdec)
\ The floating point value f1 is split into its integral and decimal  values
\ f1        A floating-point number
\ --
\ fInt        The floating-point number equal to f1 rounded to the nearest integer
\ fdec        The floating-point number equal to f1 rounded to the nearest integer

 help_pos fround
\ (f1 -- f2) (F: r1 -- r2)
\ The floating point value f1 is rounded to the nearest integer value
\ f1        A floating-point number
\ --
\ f2        The floating-point number equal to f1 rounded to the nearest integer

 help_pos floor
\ (f1 -- f2)
\ The floating point value f1 is rounded to the nearest integer value towards
\ negative infinity
\ f1        A floating-point number
\ --
\ f2        The floating-point number equal to f1 rounded to the nearest integer
\           towards negative infinity

 help_pos pi
\ (-- fpi)
\ The floating point value for PI  3.14159265358979323846 is returned
\ No input parameters
\ --
\ fpi       The floating-point number equal to PI 3.14159265358979323846

 help_pos fliteral
\ (Fx --)
\ Used in the form : cmd ..  [ 12.34 ]  fliteral  .. ;
\ Compile the floating number FX in to the current definition such
\ that at run time the value FX is placed on the stack.
\ FX       Floating point number
\ --
\ No output parameters

  [then]
  ' df@ [if]
 help_pos set-precision
\ (x -- )
\ Set the number of significant digits displayed by
\  F.   FE.  and  FS.    to be   x
\ X         Integer, number of significant digits to be displayed
\ --
\ No output parameters

 help_pos precision
\ (-- x)
\ Return the number of significant digits displayed by
\ F.   FE.  and  FS.
\ No input parameters
\ --
\ X         Integer, number of significant digits displayed

 help_pos sfloats
\ (n -- x)
\ Return the number of address units in N 32-bit floating point numbers
\ N         Number of 32-bit floating point numbers
\ --
\ X         Number of address units.

 help_pos sfloat+
\  (sf-addrX -- sf-addrY)
\  Add the size in address units of a 32-bit floating point
\  number to the address   sf-addrX  to give  sf-addrY
\ SF-ADDRX    Memory address of first 32-bit floating point number in memory
\ --
\ SF-ADDRX    Memory address of next 32-bit floating point number in memory

 help_pos sfalign
\  (--)
\ If the free dataspace pointer is not 32-bit float aligned then align it
\ No input parameters
\ --
\ No output parameters

 help_pos sfaligned
\  (sf-addrX -- sf-addrY)
\ If the address  sf-addrX is not 32-bit float aligned, then align it.
\ SF-ADDRX    Memory address of first 32-bit floating point number
\ --
\ SF-ADDRX    Memory address of next 32-bit  floating point number

 help_pos sf@
\ (sf-addr -- sfx)
\  Fetch  sfx the 32 bit single floating value fx
\  from the memory at  sf-addr.
\ SF-ADDR    Memory address of 32-bit floating point number
\ --
\ Sfx         32-bit  floating point number

 help_pos sf!
\ (Sfx, sf-addr --)
\ Store the 32 bit single floating value fx  to the memory at  sf-addr.
\ Sfx         32-bit  floating point number
\ SF-ADDR    Memory address of 32-bit floating point number
\ --
\ No output parameters

 help_pos fsincos
\ (fx -- sin , cos)
\ Return  as double precision floating point values
\ the sine and cosine of the radian angle
\     given by the double precision floating point value dfx
\ FX         Double precision floating point number
\ --
\ SIN        Sine value of the radian DFX
\ COS        Cosine value of the radian DFX

 help_pos fsqrt
\ (fx -- fz )
\ returns  fz  a double precision floating point value
\  = the square root of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point square root of FX

 help_pos flog
\ (fx -- fz)
\ returns  fz  a double precision floating point value
\  = the base 10 logarithm of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point logarithm(10) of FX

 help_pos fln
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the natural logarithm
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point logarithm(e) of FX

 help_pos fexp
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the value  e   raised to the power  of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point =  e to the power of FX

 help_pos ftanh
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the hyberbolic tangent of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point =  hyberbolic tangent FX

 help_pos fatan2
\ (x , y  --- z )
\ Return fz a double precision floating point value
\  = angle in radians whose tangent is
\    the double precision floating point values  x / y

 help_pos fatan
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = angle in radians whose tangent is
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = angle in radian whose tangent = FX

 help_pos ftan
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = tangent of the angle in radians =  fx
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = tangent of angle in radians = FX

 help_pos falog
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the  value of 10 raised to the power of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point =  10 to the power of FX

 help_pos fsinh
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the hyberbolic sine of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = hyberbolic sine of angle in radians = FX

 help_pos fcosh
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = the hyberbolic cosine of
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = hyberbolic cosine of angle in radians = FX

 help_pos fasin
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = angle in radians whose sine is
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = angle in radian whose sine = FX

 help_pos facos
\ (fx -- fz)
\ Return fz a double precision floating point value
\  = angle in radians whose cosine is
\    the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = angle in radian whose cosine = FX

 help_pos fsin
\ (fx -- fz)
\ Return fz a double precision floating point value
\   = the sine of the angle in radians of
\     the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = sine of angle in radians = FX

 help_pos fcos
\ (fx -- fz)
\ Return fz a double precision floating point value
\   = the cosine of the angle in radians of
\     the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = cosine of angle in radians = FX

 help_pos fabs
\ (fx -- fz)
\ Return fz a double precision floating point value
\   = the absolute value of the double precision floating point value fx
\ FX         Double precision floating point number
\ --
\ FZ         Double precision floating point = absolue value of FX

 help_pos f**
\ (fx, fy -- fz)
\ Return fz a double precision floating point value
\  =  double precision floating point value fx
\    raised to the power fy also a double precision floating point value
\ FX         Double precision floating point number
\ FY         Double precision floating point number
\ --
\ FZ         Double precision floating point number ABS(fx to power of fy)

 help_pos dfloats
\ (n -- x)
\ Return the number of address units in
\ N  double precision floating point numbers
\ Return the number of address units in N Double precision floating point numbers
\ N         Number of Double precision floating point numbers
\ --
\ X         Number of address units.

 help_pos dfloat+
\  (df-addrX -- df-addrY)
\  Add the size in address units of a double floating point
\  number to the address   df-addrX  to give  df-addrY
\ DF-ADDRX    Memory address of first Double precision floating point number in memory
\ --
\ DF-ADDRX    Memory address of next Double precision floating point number in memory

 help_pos dfalign
\  (--)
\ If the free dataspace pointer is not Double precision float aligned then align it
\ No input parameters
\ --
\ No output parameters

 help_pos dfaligned
\ (addr --- df-addrY)
\ Converts the address  addr to double precision floating point aligned  df-addrY
\ ADDR        Memory address
\ --
\ DF-ADDRY    Memory address of  double precision  floating point number


 help_pos df@
\ (df-addr -- dfx)
\ Fetch the double precision float value dfx from the memory at  df-addr.
\ DF-ADDR     Memory address of  double precision  floating point number
\ --
\ DFX         double precision  floating point number from memory

 help_pos df!
\ (dfx, df-addr --)
\  Store the double precision float value fx at the memory df-addr.
\ DFX         double precision  floating point number
\ DF-ADDR     Memory address of  double precision  floating point number
\ --
\ No output parameters

 help_pos f.
\ (dfx --)
\ Display the double precision floating value dfx as an ascii string with a
\ trailing space, on the current output device.
\ DFX         double precision  floating point number
\ --
\ No output parameters

 help_pos fe.
\ (Fx --)
\ Display the double precision floating value dfx as an ascii string with a
\ trailing space, on the current output device.(Engineering format)
\ DFX         double precision  floating point number
\ --
\ No output parameters

 help_pos fs.
\ (dfx --)
\ Display the double precision floating value dfx as an ascii string with a
\ trailing space, on the current output device.(Scientific format)
\ DFX         double precision  floating point number
\ --
\ No output parameters

 help_pos f=format
\ (c-addr, u --)
\ Set the print format for the   f.   command
\ e.g   s" %f"  f=format
\ C-ADDR      Address of character string
\ U           Length of string
\ --
\ No input parameters

 help_pos f.custom
\ (dfx -- c-addr, u)
\ Convert the double precision floating value dfx to an ascii string
\ using the conversion defined by f=format
\ Default =   s" %f" f=format
\ DFX         Double precision floating point number
\ --
\ C-ADDR      Address of character string
\ U           Length of character string

 help_pos sf>df
\ (fx -- fz)
\ Convert a single precision floating point value to a double precision floating point value
\ SFX        Single precision floating point number
\ --
\ DFZ        Double precision floating point logarithm(e) of FX

  ' font: [if]
 help_pos font:default
\ (--)
\ Initialise the FONT parameters for the next   FONT>MAKE
\ These parameters can be overridden by         FONT>PARAM
\ See also help for    FONT
\
\ No input parameters
\ --
\ No output parameters

 help_pos font:param=
\ (value, index -- )
\ Set the future value of a parameter for a FONT
\ See also help for    FONT
\
\ VALUE      New Value for the parameter
\ INDEX      Selects the font parameter
\    00 : font Height
\    01 : font Width
\    02 : font Escapement
\    03 : font Orientation
\    04 : font Weight
\    05 : font Italic
\    06 : font Underline
\    07 : font StrikeOut
\    08 : font CharSet
\    09 : font OutPrecision
\    10 : font ClipPrecision
\    11 : font Quality
\    12 : font PitchAndFamily
\    13 : font FaceName (zero terminated string)
\ --
\ No output parameters

 help_pos font:defaults.from.handle
\ ( FontHandle -- )
\ Populate the internal FONT default with the values from the FONT with the handle  FontHandle
\ --
\ no output parameters

 help_pos font:param
\ (  index -- value )
\ Get the future value of a parameter for a FONT
\ See also help for    FONT
\
\ INDEX      Selects the font parameter
\    00 : font Height
\    01 : font Width
\    02 : font Escapement
\    03 : font Orientation
\    04 : font Weight
\    05 : font Italic
\    06 : font Underline
\    07 : font StrikeOut
\    08 : font CharSet
\    09 : font OutPrecision
\    10 : font ClipPrecision
\    11 : font Quality
\    12 : font PitchAndFamily
\    13 : font FaceName ( zero terminated string)
\    else returns VALUE = -1
\ --
\ VALUE      Value of the parameter

 help_pos font:new
\ (-- handle)
\ Creates a FONT
\ Internally there is a data structure (WIN32 API LOGFONT) which is given default values
\ on program startup.
\ Use command   font@param   to get the current value of a FONT field.
\ Use command   font0param   to set the current value of a FONT field.
\ The FONT command passes this data structure to the WIN32 API CreateFontIndirect function
\ which returns the HANDLE of the new FONT
\ This NEW FONT can be assigned to a Screen OBject using the   sob=FONT  command.
\ No input parameters
\ --
\ HANDLE    the system HANDLE assigned to the required FONT

 help_pos font:help
\ ( -- c-addr, u  )
\ General info about the namespace  FONT:
\ --
\ no output parameters

    [then]
  ' random [if]
 help_pos hash>MD5
\ (--)
\ The next   hash=open    will be done using MD5
\ No input parameters
\ --
\ No output parameters

 help_pos hash>sha1
\ (--)
\ The next   hash=open    will be done using SHA1
\ No input parameters
\ --
\ No output parameters

 help_pos hash@file.Buffered
\ (c-addrI, uI, bSize -- c-addrO, uO)
\ Read the file identifed by the filename, contained in the
\ the character buffer starting at c-addrI of length uI character,
\ into a internal buffer of length bSIZE bytes. Execute the HASH function on this buffer.
\ Repeat the read / HASH until the file is exhausted or an error occurs.
\ Close the file.
\ c-addr    Start address of buffer to receive data
\ u1        Maximum length of data to be read
\ --
\ c-addrO   Start address of byte array holding the HASH result
\ uO        Number of bytes in array
\            0 IF    FILE    could not be accessed
\           -1 IF internal error e.g. file too big

 help_pos hash@file
\ (c-addrI, uI, -- c-addrO, uO)
\ Read the entire file identifed by the filename, contained in the
\ the character buffer starting at c-addrI of length uI character,
\ into a SINGLE internal memory buffer and derive a HASH on that buffer.
\ Should be faster that the buffered version!
\ c-addr    Start address of byte array in memory holding the file name
\ u1        Length of file name
\ --
\ c-addrO   Start address of byte array holding the HASH result
\ uO        Number of bytes in array
\            0 IF    FILE    could not be accessed
\           -1 IF internal error e.g. file too big
\
\ Example:
\ : show   0 do dup @byte  0 <# #h #sh #>  type      1 + loop drop cr ;  \ formatting routine
\ hash>MD5    \ set HASH type to be   MDA5
\ s" C:\Users\george\Desktop\android\Yes Album\02 The Clap.mp3"      \ name of file to be hashed
\ hash@file
\ 2dup  show  \ display the hash as hex characters
\ str>b64     \ convert the binary hash to binary 64 format (a UTF8 text format)
\ utf8">s"    \ convert UTF8 to the default character format for this program
\ type cr     \ display the   b64 hash

 help_pos hash@string
\ (c-addrI, uI, -- c-addrO, uO)
\ Read the  character buffer starting at c-addrI of length uI character,
\ and derive a HASH on that buffer.
\ c-addr    Start address of byte array in memory
\ u1        Length of file name
\ --
\ c-addrO   Start address of byte array holding the HASH result
\ uO        Number of bytes in array
\            0 IF    FILE    could not be accessed
\           -1 IF internal error e.g. file too big

 help_pos mpeg
\ (c-addrI, uI, hashFlag -- MPEGres, c-addrH, uH )
\ Check a MP3 / MPEG encoded file for consistency.
\ i.e. IF ID3v2 tag(s)of file are correctly followed by a MPEG frame
\      IF each MPEG frame if correctly followed by other MPEG frames.
\      IF the end of file exactly coincides with
\           either the expected start of the next MPEG frame
\           or the "last" MPEG frame is followed by an ID3v1 tag(s)
\
\ The M3/MPEG file name is specified by   c-ADDRI, uI
\
\ c-addrI     Start address of filename
\ uI          length in characters of filename
\ hashFlag    0 = no hash check
\             else HASH check will be done
\                 = 1   SHA1
\                 = 5   MD5
\             IF the MPEG check was okay, then the HASH check does not include the ID3v2 or ID3v1 tag fields!
\ --
\
\ MPEGres    The result of the consistency check is either
\            0 = error
\            else = number of MPEG frames
\ c-addrH    Start address of the HASH checksum
\ uH         Length of HASH checksum in bytes
\            c-addrH , uH  =  -1 , 0   if FILE could not be opened
\                          =   0 , 0   if HASH not requested

 help_pos hash=open
\ (-- bool)
\ Any previously unclosed hash operation will be closed and its results deleted
\ No input parameters
\ --
\ BOOL      0 = error
\           else Okay


 help_pos hash=close
\ (-- c-addr, u|0)
\ Return the HASH value created by the current HASH operation
\ and terminate the HASH operation.
\ No input parameters
\ --
\ c-addr    Start address of buffer holding the HASH value
\ u         Length of the HASH data in bytes
\           0 if error

 help_pos hash=add
\ (c-addr, u1, -- bool)
\ Add the     U1  bytes starting at address C-ADDR to the current HASH operation.
\ --
\ BOOL      0 = error
\           else Okay

    [then]
  ' open-file [if]
    [then]
  ' heapInit [if]
 help_pos heapInit
\ (--)
\ Initialises an internal pointer that effectively empties the internal HEAP memory
\ No input parameters
\ --
\ No output parameters

 help_pos heapOn
\ (caddrIN, uIN -- caddrOUT, uOUT)
\ Copies the byte string of length UIN at location CADDRIN to the
\ local heap at location CADDROUT and length UOUT (= UIN)
\ Used to copy data from a temporary location to a "less" temporary one
\ C-ADDRIN     Address of a byte string  containing the data to be placed on the heap
\ UIN          Number of bytes in the string
\ No input parameters
\ --
\ C-ADDROUT    Address of the byte string on the heap
\ UOUT         Number of bytes in the string

 help_pos heapOff
\ (-- caddrOUT, uOUT)
\ Remove the last entry on the heap, and return the address and length of that entry
\ WARNING: the next HEAPON operation will overwrite the returned data
\ No input parameters
\ --
\ C-ADDROUT    Address of the byte string on the heap
\ UOUT         Number of characters in the string

 help_pos heapDrop
\ (--)
\ Remove the last entry on the heap
\ No input parameters
\ --
\ No output parameters

    [then]
  ' {: [if]
 help_pos {:
\ (--)
\ Used inside a DEFINITION to create Named Arguments and/or Local Values (both types are temporarily stored on the heap)
\ Used in the form
\
\    : test  {: width height  |   area  circumference :}
\            width height *  to  area
\            width area + 2 *  to circumference
\            ." area = " area .dec
\            ." circumference = "  circumference .dec cr  ;
\
\  This definition is identical to  (note reversal of the Named Argument sequence!
\
\    : test  na: height     na: width      lv: area     lv: circumference
\            width height *  to  area
\            width area + 2 *  to circumference
\            ." area = " area .dec
\            ." circumference = "  circumference .dec cr  ;
\
\
\  Words between the  {:    and   |      will be Named Arguments
\  Words between the   |    and   :}     will be Local Values
\  NOTE: to change either Named Arguments, or Local Values you must use the   TO   definition
\  NOTE: if this example is called by  3  9  TEST
\        then   WIDTH  takes the value 3
\        and    HEIGHT takes the value 9
\  Number of Named Arguments = 0 or more (depends on length of line)
\  Number of Local Values    = 0 or more (depends on length of line)
\
\  NOTE: Local Values are always automatically initialised to 0
\  NOTE: on exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos BA:
\ (caddr, u -- )
\ Used inside a DEFINITION to create named, temporary storage (on the heap), for a BYTE array
\ of length U BYTE starting at the address CADDR.
\ Used in the form
\
\    : test  BA: UserString
\           ." The user supplied BYTE string has been copied to:- "  UserString drop   .hex
\           ."  and has a length in BYTES of:- "   UserString nip    .dec cr
\           ." The user supplied string is:- "   USerString type   cr     ;
\      0 pad !byte
\      2  1 pad + !byte
\      4  2 pad + !byte
\      pad  3     test
\ NOTE:  You cannot change the string. (Well you can change the content, but not the location or length values!)
\        On exiting the definition the temporary storage will be automatically released.
\
\ C-ADDR    Address of the BYTE string to be temporarily stored on the heap
\ U         Number of BYTES in the array
\ --
\ No output parameters

 help_pos CA:
\ (caddr, u -- )
\ Used inside a DEFINITION to create named, temporary storage (on the heap), for a CHARACTER array
\ of length U CHARACTERS starting at the address CADDR.
\ Used in the form
\
\    : test  CA: UserString
\           ." The user supplied CHARACTER string has been copied to:- "  UserString drop   .hex
\           ."  and has a length in CHARACTERS of:- "   UserString nip    .dec cr
\           ." The user supplied string is:- "   USerString type   cr     ;
\ NOTE:  You cannot change the string. (Well you can change the content, but not the location or length values!)
\        On exiting the definition the temporary storage will be automatically released.
\
\ C-ADDR    Address of the CHARACTER string to be temporarily stored on the heap
\ U         Number of CHARACTERS in the array
\ --
\ No output parameters

 help_pos 2NA:
\ (--)
\ Used inside a DEFINITION to create a LOCAL Double Value (temporarily stored on the heap)
\ e.g.     2lv: my2Values
\ initially  my2Values  =  0, 0
\ to set  my2Values use a    to   command
\ e.g.   0x0123 0x0456  to my2values
\
\    : test  2na: HxW
\            ." area = " HxW  * .dec cr
\            ." circumference = "  H*W + dup +   .dec cr
\     ;
\      5 7 test
\  NOTE:
\        Local Values are always automatically initialised to 0
\        To change a Local Values you must use the   TO   definition
\        On exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos na:
\ (--)
\ Used inside a DEFINITION to create a Local Value (temporarily stored on the heap)
\ Used in the form
\
\    : test  na: height     na: width      lv: area     lv: circumference
\            width height *  to  area
\            width area + 2 *  to circumference
\            ." area = " area .dec
\            ." circumference = "  circumference .dec cr  ;
\     3   5    test
\  NOTE:
\        Local Values are always automatically initialised to 0
\        To change a Local Values you must use the   TO   definition
\        On exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos 2LV:
\ (--)
\ Used inside a DEFINITION to create a LOCAL Double Value (temporarily stored on the heap)
\ e.g.     2lv: my2Values
\ initially  my2Values  =  0, 0
\ to set  my2Values use a    to   command
\ e.g.   0x0123 0x0456  to my2values
\ NOTE: on exiting the definition the temporary storage will be automatically released.
\
\    : test    2lv: rect
\             2 3  to    rect
\
\            ." area of rect = " rect * .dec  cr  ;
\
\  NOTE:
\        Local Values are always automatically initialised to 0
\        To change a Local Values you must use the   TO   definition
\        On exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos lv:
\ (--)
\ Used inside a DEFINITION to create a Local Value (temporarily stored on the heap)
\ Used in the form
\
\    : test  na: height     na: width      lv: area     lv: circumference
\            width height *  to  area
\            width area + 2 *  to circumference
\            ." area = " area .dec
\            ." circumference = "  circumference .dec cr  ;
\
\  NOTE:
\        Local Values are always automatically initialised to 0
\        To change a Local Values you must use the   TO   definition
\        On exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos BYTES:
\ ( u -- )
\ Used inside a DEFINITION to create a named temporary storage (on the heap) for a BYTE array
\ of length U BYTES.
\ NOTE:   u   is a runtime value  NOT a compile time value
\ Hence in the follwing example we have used [ ]  to provide a fixed value at compile time!
\ Used in the form
\
\    : test  [ 42 ]  bytes: myByteSpace
\            0   0 myByteSpace !byte
\            2   1 myByteSpace !byte
\            6   3 myByteSpace !byte
\           ." value at   myByteSpace[1] is "   1 myByteSpace @byte  .hex cr
\      ;
\
\  NOTE:
\        Local Values are always automatically initialised to 0
\        To change a Local Values you must use the   TO   definition
\        On exiting the definition the temporary storage will be automatically released.
\
\ C-ADDR    Address of the first  BYTE on the temporarily storage
\ --
\ No output parameters

 help_pos NA:f
\ (--)
\ Used inside a DEFINITION to create temporary storage for a named FLOATING point argument
\ The array is not stored, only its C-ADDR (start address) and U (length)
\
\    : test  NA:f UserFloat
\           ." The user supplied float:- "  UserFloat  f. cr     ;
\
\
\  NOTE: to change a    Named Float Argument   you must use the   TO   definition
\        Named Argument are always initialised from the stack
\        On exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

 help_pos LV:F
\ (--)
\ Used inside a DEFINITION to create a LOCAL Float Value (temporarily stored on the heap)
\
\ NOTE: on exiting the definition the temporary storage will be automatically released.
\
\ No input parameters
\ --
\ No output parameters

    [then]
  ' free [if]
 help_pos   sys.mem.open
\ (u -- a-addr, ior)
\ Obtain an area of system memory from the operating sufficient to
\ contain  u  address units.
\ If succesful,  ior = 0 and a-addr is the address of allocated memory
\ else  ior !=0 and a-addr is invalid
\
\ PLEASE, TO AVOID PROBLEMS (NOT IN RIPETECH!), ALWAYS RETURN MEMORY
\
\ U      Size of required memory area in address units
\ --
\ A-ADDR  Address of allocated memory
\ IOR     = 0 if okay, then A-ADDR is valid
\         else error, then  A-ADDR is invalid

 help_pos allocate
\ (u -- a-addr, ior)
\ Obtain an area of system memory from the operating sufficient to
\ contain  u  address units.
\ If succesful,  ior = 0 and a-addr is the address of allocated memory
\ else  ior !=0 and a-addr is invalid
\
\ PLEASE, TO AVOID PROBLEMS (NOT IN RIPETECH!), ALWAYS RETURN MEMORY
\
\ U      Size of required memory area in address units
\ --
\ A-ADDR  Address of allocated memory
\ IOR     = 0 if okay, then A-ADDR is valid
\         else error, then  A-ADDR is invalid

 help_pos free
\ (a-addr -- ior)
\ Return an area of system memory to the operating system.
\ This area MUST have been obtained by the command ALLOCATE or
\ SYS.MEM.OPEN
\
\ PLEASE, TO AVOID PROBLEMS (NOT IN RIPETECH!), ALWAYS RETURN MEMORY
\ IN THE SEQUENCE NEWEST FIRST (I.E. REVERSE TO THE GET MEMORY).
\
\ A-ADDR  Address of allocated memory
\ --
\ IOR     = 0 if successful

 help_pos  sys.mem=close
\ (a-addr -- ior)
\ Return an area of system memory to the operating system.
\ This area MUST have been obtained by the command ALLOCATE or
\ SYS.MEM.OPEN
\
\ PLEASE, TO AVOID PROBLEMS (NOT IN RIPETECH!), ALWAYS RETURN MEMORY
\ IN THE SEQUENCE NEWEST FIRST (I.E. REVERSE TO THE GET MEMORY).
\
\ A-ADDR  Address of allocated memory
\ --
\ IOR     = 0 if successful

 help_pos resize
\ (a-addr1 , u1 -- a-addr2 , ior)
\ Change the size of the system memory area starting at a-addr1, by
\ u1 address units.
\ This area MUST have been obtained by the command ALLOCATE or
\ SYS.MEM.OPEN
\ This may make   a-addr1 larger or smaller than its previous value
\ Memory contents up to the minimum of u1 and the original size are
\ maintained. New memory is not initialised.
\ NOTE: the new memory can be at a different address to original!
\ If the resizing is successfull  ior = zero
\ A-ADDR1  Address of original allocated memory
\ U1       Size of area to be changed (can be negative!)
\ --
\ A-ADDR2  Address of modified  memory
\ IOR      = 0 if okay, on error

 help_pos  sys.mem=resize
\ (a-addr1 , u1 -- a-addr2 , ior)
\ Change the size of the system memory area starting at a-addr1, by
\ u1 address units.
\ This area MUST have been obtained by the command ALLOCATE or
\ SYS.MEM.OPEN
\ This may make   a-addr1 larger or smaller than its previous value
\ Memory contents up to the minimum of u1 and the original size are
\ maintained. New memory is not initialised.
\ NOTE: the new memory can be at a different address to original!
\ If the resizing is successfull  ior = zero
\ A-ADDR1  Address of original allocated memory
\ U1       Size of area to be changed (can be negative!)
\ --
\ A-ADDR2  Address of modified  memory
\ IOR      = 0 if okay, on error

   [THEN]
  ' app.dataspace=add [if]
 help_pos app.dataspace=add
\  (u -- a-addr|0, ior)
\  Allocate memory space sufficient to contain u address units.
\  If succesful it returns the start address of the allocated memory
\  else 0 is returned

   [THEN]
  ' free [if]
   [THEN]
  ' msg.box.ok [if]
 help_pos msg.box.icon>default
\ (--)
\ Until overridden, by one of the msg.box.icon>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that there
\ is NO ICON displayed in the BOX
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.icon>exclamation
\ (--)
\ Until overridden, by one of the msg.box.icon>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that there
\ is an EXCLAMATION ICON displayed in the BOX
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.icon>asterix
\ (--)
\ Until overridden, by one of the msg.box.icon>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that there
\ is an ASTERISK ICON displayed in the BOX
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.icon>question
\ (--)
\ Until overridden, by one of the msg.box.icon>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that there
\ is a QUESTION ICON displayed in the BOX
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.icon>hand
\ (--)
\ Until overridden, by one of the msg.box.icon>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that there
\ is a HAND ICON displayed in the BOX
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.modal>default
\ (--)
\ Until overridden, by one of the msg.box.modal>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that the
\ BOX can be covered by other applications windows !
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.modal>app
\ (--)
\ Until overridden, by one of the msg.box.modal>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that the
\ BOX can be covered by other applications windows!
\ no input  parameters
\ --
\ No output parameters

 help_pos msg.box.modal>system
\ (--)
\ Until overridden, by one of the msg.box.modal>xxxx commands,
\ future MESSAGE BOX Screen OBjects will be created so that the
\ BOX can NOT be covered by other applications windows!
\ no input  parameters
\ --
\ No output parameters

\ help_pos msg.box
\ (c-addrT, uT, c-addrC, uC, style -- button-id)
\ Creates a general purpose MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ STYLE     see online documentation for the   Windows MessageBox function
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = left most button
\            = 1 = middle button
\            = 2 = right most button

 help_pos msg.box.yn
\ (c-addrT, uT, c-addrC, uC -- button-id)
\ Creates a Yes/No MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = Yes = left most button
\            = 1 = No  = middle button

 help_pos msg.box.ync
\ (c-addrT, uT, c-addrC, uC -- button-id)
\ Creates a Yes/No/Cancel MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = Yes = left most button
\            = 1 = No  = middle button
\            = 2 = Cancel = right most button

 help_pos msg.box.ok
\ (c-addrT, uT, c-addrC, uC -- button-id)
\ Creates a OK MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = OK = left most button

 help_pos msg.box.okc
\ (c-addrT, uT, c-addrC, uC -- button-id)
\ Creates a YOK/Cancel MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = OK = left most button
\            = 1 = Cancel = middle button

 help_pos msg.box.ari
\ Creates a Abort/Retry/Ignore MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = Abort = left most button
\            = 1 = Retry = middle button
\            = 2 = Ignore = right most button

 help_pos msg.box.rc
\ (c-addrT, uT, c-addrC, uC -- button-id)
\ Creates a Retry/Cancel MessageBox
\ C-ADDRT   address of a character string - message text
\ UT        length of character string
\ C-ADDRC   address of a character string - caption text
\ UC        length of character string
\ --
\ BUTTON-ID Identity of the button that was used to close the box
\            = 0 = Retry = left most button
\            = 1 = Cancel = middle button

 help_pos about
\ (--)
\ Displays a Message Box containing information about the version number
\ of this interpreter and the data of the executable image compilation.
\ no input  parameters
\ --
\ No output parameters

  [then]
  ' timer.open [if]
 help_pos cli.input=state
\ ( boolean -- )
\ Controls whether the standard input window, the CLI, will accept keyboard input.
\ BOOLEAN           0 = keyboard input not allowed
\                   else = allowed
\ --
\ No output parameters

 help_pos char2cli
\ ( character -- )
\ Passes a single character to the Forth command line handler
\ Is similar to the keyboard passing a character to the Forth command line handler
\ CHARACTER
\ --
\ No output parameters

 help_pos sys.foldersel
\ (-- c-addr, u)
\ Display the system defined Browser Folder Selection dialogue.
\ When the dialog is closed, return the c-addr and u of the selected
\ folder
\ No input parameters
\ --
\ C-ADDR    Character string address of selected file
\ U         Length of character string

 help_pos cancel=new
\ ( -- X )
\ Creates a MODELESS dialogue with a title, label field and a cancel button
\     See  CANCEL=TITLE   and   CANCEL=TEXT   to set the title and the label
\ Also sets a internal boolean to    FALSE
\ If the CANCEL button is pressed the the internal flag is reset to TRUE
\ You can query the state of the boolean using   CANCEL@STATE
\      Beware:     CANCEL@STATE    will interrupt normal processing and allow outstanding event / message to be handled
\      This is a trick so that when processing a piece of work
\      you call    CANCEL=NEW
\      start the long work, then call  CANCEL@STATE   in the work
\      if CANCEL@STATE  returns TRUE then you know the user has CANCELLED the work
\      so steer the code to exit the work
\      IF the work finishes and  CANCEL@STATE  never returned TRUE then
\      you must stop the MODELESS dialogue with  CANCEL=STOP
\      Whilst working you can change the TITLE or the TEXT fields to reflect progress
\
\ No input parameters
\ --
\ No output parameters
\ X         Number of "active" cancels

 help_pos cancel=disable
\ (  -- )
\ Prevents the  CANCEL button from responding to a press
\ No input parameters
\ --
\ No output parameters

 help_pos cancel=enable
\ (  -- )
\ Allows the  CANCEL button to respond to a press
\ No input parameters
\ --
\ No output parameters

 help_pos cancel@show
\ (-- Boolean)
\ Gets the visibility state of the  CANCEL dialogue  .
\ No input parameters
\ --
\ BOOLEAN  =TRUE if visible

 help_pos cancel=show
\ (--)
\ Set the visiblity state of the CANCEL dialogue
\ No input parameters
\ --
\ No output parameters

 help_pos cancel=stop
\ (--)
\ Unconditionally terminates the CANCEL dialogue
\ No input parameters
\ --
\ No output parameters

 help_pos cancel=release
\ (--)
\ Terminates the CANCEL dialogue   but ONLY if the
\ number of  cancel=release   requests = the number of cancel=new  requests
\ No input parameters
\ --
\ No output parameters

 help_pos cancel@state
\ (-- boolean)
\ Returns the state (boolean) of the CANCEL=NEW window's  CANCEL button
\ No input parameters
\ --
\ BOOLEAN    TRUE = cancelled

 help_pos cancel=title
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's TITLE
\ On calling CANCEL=NEW the title takes a default message
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=text1
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  1st text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel.post=text1
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  1st text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel.post=text2
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  2nd text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel.post=text3
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  3rd text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel.post=text4
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  4th text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=text2
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  2nd text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=text3
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  3rd text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=toggle
\ Toggles the appearance of an  X  character on the Cancel dialogue
\  ( -- )
\
\ No input parameters
\ --
\ No output parameters

 help_pos cancel=tick.set
\ ( value -- )
\ Sets the value of an internal variable
\ Each time that   CANCEL=TICK   is called this value will be displayed
\ in the window's  3rd  text field.
\ I use this as a progress count in loops.
\ e.g. The loop index is written say ever 16 loops in to    cancel=tick.set
\  and the it calls   CANCEL=TICK
\ Should probably have combined them to one function
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=tick
\ (  -- )
\ Sets the text displayed as the CANCEL=NEW window's  3rd  text field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel=text4
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window   button's text field
\ On calling CANCEL=NEW the button text field is   Cancel
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

 help_pos cancel.post=text0
\ (c-addr, u --)
\ Sets the text displayed as the CANCEL=NEW window's  title field
\ On calling CANCEL=NEW the text field is empty
\ C-ADDR    Character string address of text
\ U         Length of character string
\ --
\ No output parameters

\  help_pos cancel=focus
\ ( -- )
\ Keyboard and mouse button events will be focused on the  CANCEL dialogue
\ No input parameters
\ --
\ No output parameters

 help_pos sleep
\ ( ms  --)
\ This thread will sleep for the defined period of milliseconds
\ MS      period in milliseconds
\ --
\ No output parameters

 help_pos sys.filesel=filter
\ (c-addr, u -- )
\ Define the name and extension filter to be used in the next
\ use of sys.filesel
\ The character string c-addr and length u, must define a set of
\ double line entries. All entries are 0 character terminated.
\ The last entry must be terminated by a double 0.
\ These 0 terminators are counted as members of the string.
\ The first entry of a pair is a comment. The second entry is used
\ to define a file/ext filter.
\ IF  U = 0  then the default file spec will be installed.
\ In "C" language notation "All Files(*.*)\0*.*\0\0" is the default.
\ C-ADDR    Character string address of file/ext filter specification
\ U         Length of character string (including all \0 characters)
\ --
\ No output parameters

 help_pos sys.filesel=dir
\ (c-addr, u -- )
\ Sets the initial directory for  sys.filesel and sys.opensel definitions
\ C-ADDR    Character string address of initial directory
\ U         Length of character string
\ --
\ No otput parameters

 help_pos sys.filesel
\ (-- c-addr, u)
\ Display the system defined Get Open File Selection dialogue.
\ When the dialog is closed, return the c-addr and u of the selected
\ file
\ No input parameters
\ --
\ C-ADDR    Character string address of selected file
\ U         Length of character string

 help_pos sys.savesel
\ (-- c-addr, u)
\ Display the system defined Get Open File Selection dialogue.
\ When the dialog is closed, return the c-addr and u of the selected
\ file
\ No input parameters
\ --
\ C-ADDR    Character string address of selected file
\ U         Length of character string

 help_pos InstanceId
\ ( -- c-addr , u )
\ Returns a character string of the form "12345" where the
\ integer unique to this INSTANCE of the RipeTech executable.
\ Useful when you need a temporary name that no other running RipeTech
\ executables will use!
\ No input parameters
\ --
\ C-ADDR    Character string address
\ U         Length of character string

 help_pos InstanceName
\ ( -- c-addr , u )
\ Returns a character string of the form "RipeTech12345" where the
\ integer part is unique to this INSTANCE of the RipeTech executable.
\ Useful when you need a temporary name that no other running RipeTech
\ executables will use!
\ No input parameters
\ --
\ C-ADDR    Character string address
\ U         Length of character string

 help_pos sys.filepath=short
\ (c-addrL, uL -- c-addrS, uS)
\ Convert the file name given by the character string
\ at c-addrL and length uL from using long file and path names
\ to the character string at c-addrS and length uS  using
\ short file and path names
\ C-ADDRL   Character string address of long file name
\ UL        Length of character string
\ --
\ C-ADDRS   Character string address of short file name
\ US        Length of character string

 help_pos accept>prompt
\ (c-addr, u1 --)
\ Define a character string to be used as the prompt for
\ use by future calls to the accept command.
\ CS-ADDR   Address of character string
\ U         length of string
\ --
\ No output parameters

 help_pos accept
\ (c-addr, u1 -- u2)
\ Receive a string of at most U1 characters from the current input device
\ Stop accepting input on receiving a new-line character, or
\ when U1 characters have been received.
\ Return U2, the actual number of received characters (not
\ including any newline characters )
\ CS-ADDR   Address to which characters should be placed
\ U1        Maximum number of wanted characters
\ --
\ U2        Actual number of characters received

 help_pos naccept
\ (c-addr, u1 -- u2)
\ Receive a string of at most U1 numeric only characters from the current
\ input device.
\ Stop accepting input on receiving a new-line character, or
\ when U1 characters have been received.
\ Return U2, the actual number of received characters (not
\ including any newline characters )
\ CS-ADDR   Address to which characters should be placed
\ U1        Maximum number of wanted characters
\ --
\ U2        Actual number of characters received

 help_pos sys@error.int
\ (ecode -- c-addr, u1)
\ Return the address of the character string and length, associated with
\ the SYSTEM error code ecode .
\ Uses    FormatMessage   from Win32 API
\ ECODE     Error code
\ --
\ C-ADDR    Address of a charcter string
\ U         Length of character string

 help_pos evaluate.async
\ (xt, c-addr, u  --)
\ Passes the string given by c-addr,u to the command line interpreter.
\ The standard   evaluate    is implemented in this program as a sysnchronous command.
\  ie       1 .          s" 2 . "  evaluate         3 .   cr
\  results in the output  1 2 3
\
\ However       1 .          s" 2 . "  evaluate.async          3 .   cr
\ results in the output   1 3 on the first lines   and  2 on the next line
\ XT        Execution Toekn to be called when the  string has been evaluated
\ C-ADDR    Address of a character string
\ U         Length of character string
\ --
\ No output parameters

 help_pos timer.create
\ (time, xt , periodic , timer-id -- timer-id )
\ Arrange for an XT to be executed after a predetermined time interval has elapsed.
\ This does NOT block program execution !
\ TIME      Delay in milli-seconds before XT will be executed
\ XT        eXecution Token of routine to be called on timer expiry
\           XT must have the stack behaviour (--)
\ PERIODIC  0 = single shot, else automatically repeated
\ TIMER-ID  User defined identifer for this timer must be in range 0 - 15
\ --
\ TIMER-ID  System defined identifer for this timer action

 help_pos timer.open
\ (time, xt -- timer-id)
\ Arrange for an XT to be executed after a predetermined time interval has elapsed.
\ This does NOT block program execution !
\ TIME      Delay in milli-seconds before XT will be executed
\ XT        eXecution Token of routine to be called on timer expiry
\           XT must have the stack behaviour (--)
\ --
\ TIMER-ID  System defined identifer for this timer action

 help_pos timer=close
\ (timer-id -- imer-id)
\ Delete a timer created via  TIMER.OPEN
\ TIMER-ID  An identifer returned by  TIMER.OPEN
\ --
\ No output parameters

    [then]
   ' ll=xt [if]
 help_pos ll=message.send
\ ( hwnd, umsg, wParam, lParam -- ret )
\ Send a message with the goven parameters
\ HWND      The HWND handle  of the window
\ UMSG      The Windows assigned message identity
\ WPARAM    The first parameter
\ LPARAM    The second parameter
\ --
\ RET       Value returned by the message, is message specific.

 help_pos ll=message.post
\ ( hwnd, umsg, wParam, lParam -- retCode )
\ Post a message with the given parameters
\
\ HWND      The HWND handle  of the window
\ UMSG      The Windows assigned message identity
\ WPARAM    The first parameter
\ LPARAM    The second parameter
\ --
\ RETCODE   The value returned by the PostMessage

 help_pos ll=message.post.descendants
\ ( hwnd, umsg, wParam, lParam --   )
\ Post a message with the given parameters to all of the children of the specified parent HWND
\
\ HWND      The HWND handle  of the window
\ UMSG      The Windows assigned message identity
\ WPARAM    The first parameter
\ LPARAM    The second parameter
\ --
\ no return parameters

 help_pos ll@message
\ (ll-id -- hwnd, umsg, wParam, lParam)
\ Return the message parameters belonging to the last message that
\ was received by the user controlled low level Message handler
\ LL-ID     The identity of the low level Message handler 0..3
\ --
\ HWND      The HWND handle  of the window
\ UMSG      The Windows assigned message identity
\ WPARAM    The first parameter
\ LPARAM    The second parameter

 help_pos ll=return
\ (ll-id, boolean --)
\ Define the value to be returned  by the low level Message handler
\ LL-ID     The identity of the low level Message handler 0..3
\ BOOLEAN   If = TRUE, the Message Handler will call the default
\           handler   DefWindowProc(hWnd, message, wParam, lParam)
\           else it executes        return 0
\ --
\ no return parameters

 help_pos ll=xt
\ (ll-id, xt --)
\ Define the eXecution Token of a user defined command to be executed whenever
\ the low level Message handler receives a message
\ LL-ID     The identity of the low level Message handler 0..3
\ XT        eXecution Token of user defined command,
\           xt must have the stack behaviour (--)
\ --
\ no return parameters

 help_pos ll@address
\ (ll-id -- p-addr)
\ Return the procedure address to be called whenever a message is sent
\ to the low level Message handler 0..3
\ LL-ID     The identity of the low level Message handler 0..3
\ --
\ P-ADDR    The address of the relevant low level Message handler

    [then]
   ' sob=delete [if]
 help_pos msg.intercept@details
\ (-- wParam, lParam , hwnd, msg )
\ Get the message parameters for the last intercepted message that
\ was passed to a DEFN
\ No input parameters
\ --
\ WPARAM
\ LPARAM
\ HWND     The HWND handle of the window
\ MESSAGE

 help_pos msg=post
\ (wParam, lParam , hwnd, msg --)
\ Create a message and post it.
\ WPARAM
\ LPARAM
\ HWND     The HWND handle of the target window
\ MESSAGE
\ --
\ No output parameters

 help_pos msg.intercept=xt
\ (xt , msgNbr -- boolean )
\ If the Windows message number  MSGNBR  is received and not handled
\ by default, then cause a DEFN to be called.
\ XT         eXecution Token  of DEFN to be called, or 0 to stop interception
\ MSGNBR     message number to be intercepted
\ --
\ BOOLEAN    on error = 0 = False
\            else = TRUE

 help_pos msg.intercept=reset
\ ( --  )
\ Stop all message intercepting
\ No input parameters
\ --
\ No output parameters

 help_pos sob=show.child
\  ( sob-id -- )
\ If this SOB-ID is a direct CHILD of a OVERLAY SOB,
\ then this SOB_ID will be made visible, and the other direct children of
\ the OVERLAY SOB will be made invisible.
\ SOB-ID    internally allocated identity of a child (of an OVERLAY) Screen OBject
\ --
\ No output parameters

 help_pos sob.msg>anchor
\ Used to influence where user generated messages are displayed
\ e.g. s" Hello"   s" World"   msg.box.ok drop
\ By default such messages are displayed in the center of the primary display screen.
\ If you provide this function with a SOBID, then it will TRY to position future messages
\ over the top/left corner of the SOBID's window!
\
\ ( sobId --  )
\ Sob Id     ASceen OBject over whose window future messages should be positioned
\ --
\ No output parameters

 help_pos sob@check
\ (sob-id -- bool)
\ Indicates whether a Screen OBject item is checked or not.
\ Works with: menu items, radio buttons and check buttons
\ SOB-ID    identity of Screen OBject item
\ --
\ BOOL      = 0 =   CHECK STATE is NOT CHECKED
\           else set CHECK STATE
\           = -1 if SOB-ID is not a "checkable" SOB

 help_pos sob=check
\ (bool , sob-id -- )
\ Sets whether a Screen OBject item is checked or not
\ If Screen OBject is not a "checkable" SOB then both parameters are discarded
\
\ BOOL      = 0 =   CHECK STATE is NOT CHECKED
\           else set CHECK STATE
\ SOB-ID    identity of Screen OBject item
\ --
\ No output parameters

 help_pos sob@cursor
\ (sob-id -- nX, nY)
\ Return the (x, y) co-ordinate of the cursor relative to the
\ current Screen OBjects's client area
\ No input parameters
\ --
\ NX         X co-ordinate of cursor relative to current DISPLAY WINDOW's client area
\ NY         Y co-ordinate of cursor relative to current DISPLAY WINDOW's client area

 help_pos sob.mouse@xy
\ (  -- nX, nY)
\ Return the (x, y) co-ordinate of the cursor relative to the
\ current DISPLAY WINDOW's client area
\ No input parameters
\ --
\ NX         X co-ordinate of cursor relative to current DISPLAY WINDOW's client area
\ NY         Y co-ordinate of cursor relative to current DISPLAY WINDOW's client area

 help_pos sob=display
\ (value --)
\ Sets the internal boolean that disables display updates
\ displayed when SOBs are redrawn.
\ FLAG      TRUE = no display
\           else = display allowed
\ --
\ No output parameters
 help_pos sob@display
\ (value --)
\ Gets the internal boolean that inhibits/allows display updates
\ No input parameters
\ --
\ FLAG      TRUE = no display
\           else = display allowed
 help_pos sob=debug
\ (flag --)
\ Sets the internal debug flag that controls whether SOB positioning information is
\ displayed when SOBs are redrawn.
\ FLAG      = 0 = no display
\           else = display info
\ --
\ No output parameters
 help_pos sob@ownerdrawn
\ (u -- value)
\ When handling a user drawn operation, the WM_DRAWITEM message's parameters are saved, and
\ if available a SOB eXecution Token is called.
\ If this is called outside of the handler of a SOB.CALLBACK=XT.OWNERDRAW then it unconditionally returns -1
\ The message's parameters are available:
\ U           Index in to the stored WM_DRAWITEM message's parameters
\             00  =    WINDOWS parameter CtlType
\             01  =    WINDOWS parameter CtlID
\             02  =    WINDOWS parameter itemId
\             03  =    WINDOWS parameter itemAction
\             04  =    WINDOWS parameter itemState
\             05  =    WINDOWS parameter itemState
\             06  =    WINDOWS parameter hwndItem = item id within SOB
\             07  =    WINDOWS parameter hDC
\             08  =    WINDOWS parameter rcItem
\             09  =    rcItem.bottom
\             10  =    rcItem.left = X
\             11  =    rcItem.right
\             12  =    rcItem.top = Y
\             13  =    WINDOWS parameter itemData = user data associate with this item
\             14  =    identity of the user drawn SOB
\             else = return -1
\ --
\ VALUE       stored value

 help_pos app@instance
\ (-- instance)
\ Obtain the INSTANCE handle used by this program, that was provided by the call to WinMain
\ No input parameters
\ --
\ INSTANCE     The INSTANCE handle used by this program.

 help_pos sob.class>bkgd
\ (bkgd --)
\ Sets the background colour to be used for future created sob.windows
\ Technical note: sets the HBRUSH hbrBackground field of the WNDCLASS
\ structure used in a RegisterClass call !
\ BKGD      a system value defining a background colour handle
\ --
\ No output parameters

 help_pos sob@cli
\ (-- sob-id)
\ Returns the  Screen OBject identity associated with the Command Line Interpreter display
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob@gui
\ (-- sob-id)
\ Returns the  Screen OBject identity associated with the Graphical User Interface display.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob@gindex
\ (-- sob-id)
\ Returns the  Screen OBject
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.class
\ (c-addr, u --)
\ Creates a new, windows class
\ C-ADDR    address of a character string - name of new class
\ U         length of character string
\ --
\ No output parameters

 help_pos sob.class>style
\ (wstyle --)
\ Defien the window class style to be used when the next
\ window is created.
\ WSTYLE    Style to be used.
\ --
\ No output parameters

 help_pos sob.class>name
\ (c-addr, u --)
\ Creates a new, windows class
\ C-ADDR    address of a character string - name to be displayed with Screen OBject
\ U         length of character string
\ --
\ No output parameters

 help_pos sob.class=default
\ (--)
\ Use the default class for future window types SOBs
\ --
\ No output parameters

 help_pos sob.window=new
\ (c-addr, u -- sob-id)
\ Creates a new, empty window on the display device
\ C-ADDR    address of a character string - name to be displayed with Screen OBject
\ U         length of character string
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.window.child=new
\ (c-addr, u -- sob-id)
\ Creates a child window, on the current display, to hold other display elements
\ e.g. buttons, scrolls  ...
\ C-ADDR    address of a character string - not used
\ U         length of character string    - not used
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.box
\ (xt -- sob-id)
\ Creates a box on the current display, to hold other display elements
\ e.g. buttons, scrolls  ...
\ It will be large enough to hold its children.
\ XT        eXecution Token of routine to be called when the Screen OBject is SIZED
\           by the user dragging the SOB on the screen
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.box.scrolled
\ ( rows, c-addr, u -- sob-id)
\ Creates a box whose size can NOT be changed , on the current display, to hold other display elements
\ e.g. buttons, scrolls  ...
\ at creation time you specify the box size  via  ROWS  (vertical)
\ and C_ADDR , U  (horizontal).
\ If the content of the container exceeds the size, then scrollbars will be visible.
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob>style.extend
\ (style --)
\ Used to control whether the next Screen OBject to be created is done
\ using the default STYLE characteristics, or is to be EXTENDED ( Bitwise ORed) with the
\ value provided by this definition.
\ NOTE: this is only valid until the next Screen OBject is created, or until another
\       use of SOB>STYLE, which-ever occurs first.
\ STYLE    Style to be used in creating the next Screen OBject if default is over-ridden
\ --
\ No output parameters

 help_pos sob>style
\ (style --)
\ Used to control whether the next Screen OBject to be created is done so
\ using the default STYLE characteristics, or is to be REPLACED by the
\ value provided by this definition.
\ NOTE: this is only valid until the next Screen OBject is created, or until another
\       use of SOB>STYLE, which-ever occurs first.
\ STYLE    Style to be used in creating the next Screen OBject if default is over-ridden
\ --
\ No output parameters

 help_pos sob@style
\ (sob-id -- style)
\ Return the STYLE of the specified Screen OBject
\ In Techie-Talk: GetWindowLong (  Screen OBJect's HWND , GWL_STYLE )
\ SOB-ID    identity of the target Screen OBject
\ --
\ STYLE     The internal STYLE for the specified Screen OBject

 help_pos sob=style
\ (value, sob-id --)
\ Set the STYLE of the specified Screen OBject
\ VALUE     New extended style value (see Microsoft Windows documentation)
\ SOB-ID    identity of the target Screen OBject
\ --
\ no output parameter

 help_pos sob=exstyle
\ (value, sob-id --)
\ Set the EXTENDED STYLE of the specified Screen OBject
\ VALUE     New extended style value (see Microsoft Windows documentation)
\ SOB-ID    identity of the target Screen OBject
\ --
\ no output parameter

 help_pos sob@exstyle
\ (sob-id -- style)
\ Return the EXTENDED STYLE of the specified Screen OBject
\ In Techie-Talk: GetWindowLong (  Screen OBJect's HWND , GWL_EXSTYLE )
\ SOB-ID    identity of the target Screen OBject
\ --
\ STYLE     The internal EXTENDED STYLE for the specified Screen OBject

 help_pos sob@type
\ ( sob-id -- subType, type)
\ Gets the internal type and subtype of the Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject SLIDER
\ --
\ VALUE     Subtype
\ VALUE     Type

  ' sys.icon=add [if]
 help_pos file@icon
\ (c-addr, u , i ,LorS-- handle, res )
\ Returns a HANDLE to the i'th ICON in the file identified by C-ADDR, U
\ Often used example:       s" shell32.dll"  3 file@icon
\ YOU MUST RELEASE THE HANDLE USING     ICON=RELEASE
\ C-ADDR    Address of a character string
\ U         Number of characters in the string
\ i         Index to target ICON
\           if -1 then RES = number of icons in file
\ LorS      Boolean Large or Small   Large = positive, small = negative
\ --
\ HANDLE    HANDLE of the ICON
\ RES       RESULT      -1 = FAILED

 help_pos sob=imagelist
\ (sob-id , b --)
\ Associate the system internal image list identified by B with
\ the LISTVIEW identified by SOB-ID.
\ C-ADDR    Address of a character string
\ U         Number of characters in the string
\ B         Boolean to select icon size
\              TRUE = small
\              FALSE = large
\ --
\ No output parameters

 help_pos  icon=release
\ (Handle --)
\ Release the resources associated with an ICON HANDLE
\ HANDLE    HANDLE of the ICON
\ --
\ No output parameters

 help_pos ext@icon
\ (c-addr, u -- iHandle)
\ Find the system ICON associated with the filename identified by C-ADDR, U
\
\ C-ADDR    Address of a character string
\ U         Number of characters in the string
\ --
\ iHandle   Handle of the ICON
\           0 on error

 help_pos sys.sys@icon
\ (flag , b --i)
\ Find the system ICON associated with the values defined by FLAG
\ Add that ICON  to the internal image list identified by B.
\ FLAG      Number of characters in the string
\           0x0100 = ICON
\           0x0001 = SMALLICON
\           0x0002 = OPENICON
\ B         Boolean to select icon size
\              TRUE = small
\              FALSE = large
\ --
\ I         The index of the ICON in the image list (zero based)

 help_pos sys.file@icon
\ (c-addr, u , b -- i)
\ Find the system ICON associated with the file extension belonging to the filename identified by C-ADDR, U
\ Add that ICON  to the internal image list identified by B.
\ C-ADDR    Address of a character string
\ U         Number of characters in the string
\ B         Boolean to select icon size
\              TRUE = small
\              FALSE = large
\ --
\ I         The index of the ICON in the image list (zero based)

 help_pos sys.icon=add
\ (handle, b -- index)
\ Add the ICON identified by HANDLE to the internal image list identified by B.
\ HANDLE    HANDLE of the ICON
\ B         Boolean to select icon size
\              TRUE = small
\              FALSE = large
\ --
\ No output parameters

 help_pos sys.imagelist@handle
\ (b -- handle)
\ Get the HANDLE to the internal image list identified by B.
\ B         Boolean to select icon size
\              TRUE = small
\              FALSE = large
\ --
\ HANDLE    HANDLE of the built-in IMAGE list

    [then]
 help_pos trouble
\  ( -- val )

 help_pos device.callback=add
\ (xt --)
\ Causes a user defined command to be called when a device such as
\ a media storage USB device is added to the system.
\ Does NOT work for USB devices such as headphones
\ XT        eXecution Token of routine to be called
\           XT must have the stack behaviour ( char --)
\           where CHAR is the ASCII character letter of the changed DRIVE
\ --
\ No output parameters

 help_pos device.callback=remove
\ (xt --)
\ Causes a user defined command to be called when a device such as
\ a media storage USB device is REMOVED from the system.
\ Does NOT work for USB devices such as headphones
\ XT        eXecution Token of routine to be called
\           XT must have the stack behaviour ( char --)
\           where CHAR is the ASCII character letter of the changed DRIVE
\ --
\ No output parameters

 help_pos mm.wim=xt
\ (xt --)
\ Causes a user defined command to be called when the Sound Card has filled
\ a user supplied buffer with sound samples.
\ XT        eXecution Token of routine to be called
\           XT must have the stack behaviour (--)
\ --
\ No output parameters

 help_pos mm.wom=xt
\ (xt --)
\ Causes a user defined command to be called when the Sound Card has played
\ a user supplied buffer with sound samples.
\ XT        eXecution Token of routine to be called
\           XT must have the stack behaviour (--)
\ --
\ No output parameters

 help_pos sob.callback@xy
\ (-- intX, intY)
\ Return the (x, y) co-ordinate of the cursor relative to the
\ current Screen OBject
\ No input parameters
\ --
\ INTX      X co-ordinate of cursor relative to current SOB
\ INTY      Y co-ordinate of cursor relative to current SOB

 help_pos mouse=xt
\ (xt, action --)
\ Causes a user defined command to be called when a given mouse action occurs.
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ ACTION    A number identifing which MOUSE ACTION is being defined:
\           0 left button double click
\           1 left button down
\           2 left button up
\           3 middle button double click
\           4 middle button down click
\           5 middle button up
\           6 right button double click
\           7 right button down click
\           8 right button up
\           9 mouse move
\          10 right button down click on a listview header
\ --
\ No output parameters

 help_pos sob.menu.popup=pos
\ (xpos , ypos --)
\ IF xpos = ypos = -1
\   The position of the mouse at the next Left Button Double Click
\   will be recorded.
\ ELSE
\   The co-ordinates (xpos, ypos) will be used as the position of
\   the next displayed POPUP menu
\
\ Note: These co-oddinates are used as the position of the top left corner
\       of the the next POPUP menu
\ POSX      X Co-ordinate
\ POSY      Y Co-ordinate
\ --
\ No output parameters

 help_pos sob.menu.popup@pos
\ (-- posX , posY)
\ The position of the mouse that was last recorded by the  SOB.MENU.POPUP=POS
\ will be returned as (X,Y) co-ordinates.
\
\ Note: These co-oddinates are used as the position of the top left corner
\       of the the next POPUP menu
\ No input parameters
\ --
\ POSX      X Co-ordinate of mouse
\ POSY      Y Co-ordinate of mouse

 help_pos mouse@data
\ (-- x , y , keys, event)
\ Returns information about the last received mouse event
\ includes mouse move events
\
\ No input parameters
\ --
\ X         The X co-ordinate of the mouse when the user mouse routine was called
\ Y         The X co-ordinate of the mouse when the user mouse routine was called
\ KEYS      A bitmap indicating which buttons are active
\           Bit position
\           0 left button down
\           1 right button up
\           2 keyboard shift key
\           3 keyboard control key
\           4 middle button down
\
\ EVENT     A number identifing which MOUSE ACTION was last passed to the user:
\           0 left button double click
\           1 left button down
\           2 left button up
\           3 middle button double click
\           4 middle button down click
\           5 middle button up
\           6 right button double click
\           7 right button down click
\           8 right button up
\           9 mouse move
\          10 right button down click on a listview header

 help_pos click@data
\ (-- x , y , keys, event)
\ Returns information about the last received mouse click
\ does not register mouse move events
\
\ no input parameters
\ --
\ X         The X co-ordinate of the mouse when the user mouse routine was called
\ Y         The X co-ordinate of the mouse when the user mouse routine was called
\ KEYS      A bitmap indicating which buttons are active
\           Bit position
\           0 left button down
\           1 right button down
\           2 keyboard shift key
\           3 keyboard control key
\           4 middle button down
\
\ EVENT     A number identifing which MOUSE ACTION was last passed to the user:
\           0 left button double click
\           1 left button down
\           2 left button up
\           3 middle button double click
\           4 middle button down click
\           5 middle button up
\           6 right button double click
\           7 right button down click
\           8 right button up
\           9 mouse move
\          10 right button down click on a listview header

 help_pos sob=shrink
\ (sob-id --)
\ The parent window of the Screen OBject identified by sob-id
\ will be made just big enough to hold its children Screen OBjects.
\ SOB-ID    identity of the parent WINDOW type Screen OBject belong
\           to the Screen OBject sob-id.  sob-id can itself be the
\           target WINDOW.
\ --
\ No output parameters

 help_pos GetSystemMetrics
\ (metric id  -- metrix value)
\ Calls the operating system    API   GetSystemMetrics
\ inP is the numerical value of the metric to be obtained
\ outP is the result of calling    GetSystemMetrics(inP)
\
\ INP      numerical value of the metric to be obtained
\ --
\ OUT      result of calling    GetSystemMetrics(inP)

 help_pos deleteObjectHandle
\ (handle  -- BOOLEAN)
\ Sets the font to be used for a given Screen OBject
\ HANDLE    the system HANDLE to rbe deleted
\ --
\ BOOLEAN   = 0 if invalid
\          else okay

 help_pos sob=font
\ (handle, sob-id -- pHandle|0)
\ Sets the font to be used for a given Screen OBject
\ HANDLE    the system HANDLE assigned to the required FONT
\ SOB-ID    Identity of Screen OBject to use new font
\           IF SOB-ID = -1 then font will be the new system font
\ --
\ PHANDLE   If the previous FONT of SOB-ID is NOT used by any other
\           Screen OBject then the previous FONT handle will be returned to the
\           caller for THEM to delete it if appropriate.
\           = 0 if previous FONT is still in use!

 help_pos sob@font
\ (sob-id -- handle)
\ Returns the font used by a given Screen OBject
\ SOB-ID    Identity of Screen OBject to use new font
\           IF SOB-ID = -1 then font will be the new system font
\ --
\ HANDLE    the system HANDLE assigned to the FONT

 help_pos sob.grow=w
\ (mult, sob-id --)
\ The Screen OBject sob-id will appear on the screen at
\ its default width * MULT where MULT is a percentage
\ MULT      The multiplication factor
\ SOB-ID    Identity of Screen OBject to be grown
\ --
\ No output parameters

 help_pos sob.grow=h
\ (mult, sob-id --)
\ The Screen OBject sob-id will appear on the screen at
\ its default height * MULT where MULT is a percentage
\ MULT      The multiplication factor
\ SOB-ID    Identity of Screen OBject to be grown
\ --
\ No output parameters

 help_pos sob=delete.children
\ (sob-id --)
\ Deletes the children of the specified Screen OBject
\ SOB-ID    Identity of Screen OBject
\ --
\ No output parameters

 help_pos sob=delete
\ (sob-id --)
\ Deletes the specified Screen OBject and all of its children
\ SOB-ID    Identity of Screen OBject to be deleted
\ --
\ No output parameters

 help_pos sob.usera=delete
\ ( -- )
\ Deletes all  Screen OBjects  that are part of a user group
\ Use  sob=usera  to create a user group
\ SOB-ID    Identity of Screen OBject to be deleted
\ --
\ No output parameters

 help_pos sob=focus
\ (sob-id --)
\ Keyboard and mouse button events will be focused on the
\ specified Screen OBject
\ SOB-ID    Identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=redraw
\ ( sob-id --)
\ Redraw all of the Screen Objects in the specified SOB's window
\ No input parameters
\ --
\ No output parameters

 help_pos sob=update
\ ( bool , sob-id -- )
\ Redraw all of the Screen Objects
\ BOOL      false, 0    = do not update Screen Object
\           else = update
\ SOB-ID    Identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=top
\ ( sob-id --)
\ Brings the target SOBID's window to the front of the display
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ No output parameters

 help_pos sob=show
\ (ONorOFF,  sob-id --)
\ Controls the visibility of the specified Screen OBject
\ ONorOFF   flag indicating whether Screen OBject is visible or not
\           0 = INVISIBLE   else VISIBLE
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ No output parameters

 help_pos sob@size
\ (sob-id -- width, height )
\ Gets the  height and width for a given Screen OBject.
\ SOB-ID    Identity of target Screen OBject
\ --
\ WIDTH     new width of the SOB
\ HEIGHT    new height of the SOB

 help_pos sob=enable
\ (bool, sob-id --  )
\ Find the window that owns the Screen Object given by SOB-ID
\ and sets whether that window will accept GUI input from the user or not.
\ BOOL      = 0 = input blocked
\           else input allowed
\ SOB-ID    Identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=size
\ (width, height, sob-id --)
\ Sets the default height and width for a given Screen OBject.
\ WIDTH     new width of the SOB
\ HEIGHT    new height of the SOB
\ --
\ No output parameters

 help_pos sob=move
\ (x-pos, y-pos, sob-id --)
\ Sets the position of a given Screen OBject in terms of (x,y) co-ordinates
\ based on its parent window.
\ (x,y) = (0,0) = return SOB to its default position
\ XPOS      new X co-ord of the SOB
\ YPOS      new Y co-ord of the SOB
\ --
\ No output parameters

 help_pos sob@last.id
\ (-- sob-id)
\ Return the identity of the last created Screen OBject
\ No input parameters
\ --
\ SOB-ID    internally identity of last created Screen OBject

 help_pos sob=title
\ (c-addr, u, sob-id --)
\ Changes the TITLE associated with the specified Screen OBject, even with menu items
\ C-ADDR    address of a character string - to be associated with Screen OBject
\ U         length of character string
\ SOB-ID    identity of targeted Screen OBject
\ --
\ No output parameters

 help_pos sob@title
\ (sob-id -- c-addr, u)
\ Gets the TITLE associated with the specified Screen OBject
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U         length of character string

 help_pos sob@text
\ (sob-id -- c-addr, u)
\ Get the text associated with the specified Screen OBject
\    TYPE                  TEXT
\   window                 title
\   button                 title
\   label                  title
\   edit                   edit field
\   list              current selected line
\   combo             current selected line
\   menu iterm              title
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U         length of character string
\           Note: = 0 if the text is to big for an internal buffer (256 bytes)

 help_pos sob@text.length
\ (sob-id -- c-addr, u)
\ Get the length of the text associated with the specified Screen OBject
\ in characters,
\    TYPE                  TEXT
\   window                 title
\   button                 title
\   label                  title
\   edit                   edit field
\   list              current selected line
\   combo             current selected line
\   menu iterm              title
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ U         length of character string in characters
\

 help_pos sob@text.to.blob
\ (c-addr , ui , sob-id -- c-addr, uo)
\ Get the text associated with the specified Screen OBject and place it in
\ the user supplied memory area starting a C-ADDR and of a maximum of UI characters.
\    TYPE                  TEXT
\   window                 title
\   button                 title
\   label                  title
\   edit                   edit field
\   list              current selected line
\   combo             current selected line
\   menu iterm              title
\
\ C-ADDR    address of a memory area to receive the text
\ UO        size of memory area in characters
\ SOB-ID    identity of targeted Screen OBject
\ --
\ UO        length of character string
\           C_ADDR = U0 = 0 if user supplied area is too small

 help_pos sob.edit@find
\ (c-addr, u , sob-id -- POS )
\ Search for the specified text in the edit SOB  given by SOB-ID
\ Start the search at the top of the edit area.
\ Search is case INSENSITIVE
\ If found return the 0-based index of the start of the text in the edit SOB.
\
\ C-ADDR    address of a character string to be searched for
\ U         length of character string
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ POS       0-based index of the start of the text in the edit SOB.
\           = -1 if not found

 help_pos sob@line.nbr
\ (sob-id --  n)
\ Get the line number where the cursor is.
\ Only works for multi-line Scren Objects
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ N        0based index line number

 help_pos sob.edit@sel
\ (sob-id -- c-addr, u)
\ Get the selection text associated with the specified Screen OBject
\    TYPE                  TEXT
\   edit                   edit field
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U         length of character string
\           Note: = 0 if the text is to big for an internal buffer (256 bytes)

 help_pos sob.edit@to.end
\ (sob-id -- c-addr, u)
\ Get the selection text associated with the specified Screen OBject
\    TYPE                  TEXT
\   edit                   edit field
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U         length of character string
\           Note: = 0 if the text is to big for an internal buffer (256 bytes)

 help_pos sob.edit@line
\ (sob-id -- line Nr)
\ Get the selection text associated with the specified Screen OBject
\    TYPE                  TEXT
\   edit                   edit field
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U         length of character string
\           Note: = 0 if the text is to big for an internal buffer (256 bytes)

 help_pos sob@sys.id
\ (sob-id -- hwnd)
\ Return the window HANDLE/HWND associated with the specified Screen OBject
\ SOB-ID    identity of targeted Screen OBject
\ --
\ HWND      the handle associated with the targeted Screen OBject

 help_pos sob@child.by.index
\ (index , sob-parent -- sob-child)
\ Return the Screen OBject identity SOB-IDP of the parent SOB
\ of the Screen OBject specified by SOB-IDC
\ SOB-IDC   identity of child Screen OBject
\ --
\ SOB-IDP   identity of parent Screen OBject

 help_pos sob@parent.id
\ (sob-idC -- sob-idP)
\ Return the Screen OBject identity SOB-IDP of the parent SOB
\ of the Screen OBject specified by SOB-IDC
\ SOB-IDC   identity of child Screen OBject
\ --
\ SOB-IDP   identity of parent Screen OBject

 help_pos sob@window.id
\ (sob-idC -- sob-idW)
\ Return the SOB identity of the parent window of the child SOB-IDC
\ SOB-IDC   identity of child Screen OBject
\ --
\ SOB-IDP   identity of parent Screen OBject

 help_pos sob.user@find
\ (u -- sob-id|-1)
\ Obtain the identity of the Screen OBject which was allocated the
\ user defined data value  U
\ U         User allocated value to be searched for
\ --
\ SOB-ID    Identity of Screen OBject that has the user allocated value U
\           or -1 if not found

 help_pos sob=rgb
\ (rgb, sob-id --)
\ Changes the COLOUR associated with a given Screen OBject
\ RGB       the required colour (see defn RGB )
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.font=rgb
\ (rgb, sob-id --)
\ Changes the COLOUR associated with a given Screen OBject text font
\ RGB       the required colour (see defn RGB )
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.font@rgb
\ (  sob-id -- rgb)
\ Get the COLOUR associated with a given Screen OBject' text font
\ RGB       the required colour (see defn RGB )
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob@rgb
\ (sob-id -- rgb)
\ Return the COLOUR associated with a given Screen OBject
\ SOB-ID    identity of target Screen OBject
\ --
\ RGB       the  colour (see defn RGB )

 help_pos sob.user=data
\ (u, sob-id --)
\ Assigns the user defined value U to the Screen OBject sob-id
\ U         Value to be assigned to target Screen OBject
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.user@data
\ (sob-id -- u)
\ Obtains the value U assigned by the user to the Screen OBject sob-id
\ SOB-ID    identity of target Screen OBject
\ --
\ U         Value that was assigned by user to target Screen OBject

 help_pos sob.user=unk
\ (u, sob-id --)
\ Assigns the user defined value U to the Screen OBject sob-id
\ U         Value to be assigned to target Screen OBject
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.user@unk
\ (sob-id -- u)
\ Obtains the value U assigned by the user to the Screen OBject sob-id
\ SOB-ID    identity of target Screen OBject
\ --
\ U         Value that was assigned by user to target Screen OBject

 help_pos sob.callback=value
\ ( value --)
\ Assign VALUE to the internal variable used for a callback handler to
\ pass a value to the callback's caller.
\ e.g.
\    If the    sob.callback=xt2   , used by Listviews to control whether an item is editable,
\    sets this to non-zero, then the field is editable
\    Note: in this case the  zero indexed ROW is held insob.callback@data
\                   and the  zero indexed COL is held in   sob.callback@data2
\
\ VALUE     a value
\ --
\ No output parameters

 help_pos sob.callback=xt1
\ (xt, sob-id --)
\ Assign the callback value xt to the Screen OBject sob-id
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt2
\ (xt, sob-id --)
\ Assigns the callback value xt to the Screen OBject sob-id
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt3
\ (xt, sob-id --)
\ Assigns the callback value xt to the Screen OBject sob-id
\ For   all button type SOBS, as well as  SOB.IMAGEs and SOB.CANVAS'
\ a callback=xt3  is used to draw  rubber bands
\ i.e.  if Left button down, and mouse is dragged, then callback is triggered.
\       callback.userdata2   = 1 on first and subsequent calls
\                            = 0 when left button is released
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.mouse
\ (xt, sob-id --)
\ Assigns the callback value xt to the Screen OBject sob-id
\ Whenever a mouse button is clicked whilst over this SOB = SOB_ID, then
\ the  definition identified by XT will be called.
\ ONLY WORKS FOR A WINDOW SOB
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.over
\ (xt, sob-id --)
\ Assigns the callback value xt to the Screen OBject sob-id
\ Triggered whenever the cursor enters this SOB's client area
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.mouse.release
\ ( --)
\ If the application currently has CAPTURED the mouse, then the CAPTURE is released.
\ No input parameters
\ --
\ No output parameters

 help_pos sob.mouse.capture
\ ( sob-id --)
\ Captures the MOUSE activity until      sob.mouse.release    Assigns the callback value xt to the Screen OBject sob-id
\ Whenever a mouse button is clicked whilst over this SOB = SOB_ID, then
\ the  definition identified by XT will be called.
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.drop
\ (xt, fmt , sob-id --)
\ Assigns the callback value xt to the Screen OBject sob-id
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ FMT       An indicator as to whether the DROP target will accept TEXT or a FILE
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.drag
\ (xt, sob-id --)
\ Assign the callback value xt to the Screen OBject sob-id
\ This will be activated at the start of a Mouse Click & Mouse Move (= Drag) on this SOB
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.ownnerdrawn
\ (xt, sob-id --)
\ Assign the callback value xt to the Screen OBject sob-id
\ This will be activated at the start of an OWNER DRAW operation on this SOB
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback@id
\ (-- sob-id)
\ Returns the identity of the Screen OBject that was involved in the last callback operation.
\ No input parameters
\ --
\ SOB-ID    identity of the Screen OBject that handle the last command message

 help_pos sob.callback@data
\ (-- value)
\ Obtains a value, that is associated with the last callback operation.
\ This value is dependant on the type of callback and the involved SOB.
\ No input parameters
\ --
\ VALUE      For Combo-box, index of selected item
\                List-box,  index of selected item

 help_pos sob.callback@msg
\ (-- value)
\ Obtains the Windows message number, that is associated with the last callback operation.
\ No input parameters
\ --
\ VALUE      Windows message number

 help_pos sob.callback@data2
\ (-- value)
\ Obtains a value, that is associated with the last callback operation.
\ This value is dependant on the type of callback and the involved SOB.
\ No input parameters
\ --
\ VALUE      For Combo-box, index of selected item
\                List-box,  index of selected item

 help_pos sob.callback@data3
\ (-- value)
\ Obtains a value, that is associated with the last callback operation.
\ This value is dependant on the type of callback and the involved SOB.
\ No input parameters
\ --
\ VALUE      For Combo-box, index of selected item
\                List-box,  index of selected item

 help_pos sob@xy
\ (sob-id -- intX, intY)
\ Return the (x, y) co-ordinate (=start location) of the screen area occupied by
\ the Screen OBject given by SOB-ID.
\ Co-ords are with respect to the the SOB's parent.
\ SOB-ID    identity of target Screen OBject
\ --
\ INTX      X co-ordinate of screen area
\ INTY      Y co-ordinate of screen area

 help_pos sob@cli.xy
\ (sob-id -- x, y )
\ Return the x y position of the client area of the
\ Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject
\ --
\ W         Width of client area in pixels
\ H         Height of client area in pixels

 help_pos sob@cli.wh
\ (sob-id -- w, h )
\ Return the width W and height H of the client area of the
\ Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject
\ --
\ W         Width of client area in pixels
\ H         Height of client area in pixels

 help_pos sob@scr.xy
\ (sob-id -- X,Y)
\ Return the X and Y coordinates of the screen area of the
\ Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject
\ --
\ X         -
\ Y         -

 help_pos sob@image.file.wh
\ (sob-id -- W,H)
\ Return the width W and height H of the IMAGE in the Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject, must hold an IMAGE
\ --
\ W         Width  of screen area in pixels
\ H         Height of screen area in pixels

 help_pos sob@image.wh
\ (sob-id -- W,H)
\ Return the width W and height H of the screen area occupied by
\ the IMAGE Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject, must hold an IMAGE
\ --
\ W         Width  of screen area in pixels
\ H         Height of screen area in pixels

 help_pos sob@scr.wh
\ (sob-id -- W,H)
\ Return the width W and height H of the screen area of the
\ Screen OBject identified by SOB-ID
\ SOB-ID    identity of target Screen OBject
\ --
\ W         Width  of screen area in pixels
\ H         Height of screen area in pixels

 help_pos sob=flag
\ (bool, flag-id, sob-id --)
\ Sets/clears the value of a flag associated with a Screen OBject
\ BOOL      Boolean indicating whether the FLAG is to be set or cleared
\           0 = CLEAR , else SET
\ FLAG_ID   Identity of the FLAG to be set
\           0 = invalid
\           1 = SIZE
\           2 = MOVE
\           4 = SCALE X
\           8 = SCALE Y
\        0x10 = FILL
\        0x20 = SIZE X
\        0x40 = SIZE Y
\        0x80 = SCROLL
\       0x100 = RESIZEABLE
\       0x200 = MOVEABLE
\       0x400 = MULTISEL
\       0x800 = FILL
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob@flag
\ (  sob-id -- flags)
\ Sets/clears the value of a flag associated with a Screen OBject
\ BOOL      Boolean indicating whether the FLAG is to be set or cleared
\           0 = CLEAR , else SET
\ FLAG_ID   Identity of the FLAG to be set
\           0 = invalid
\           1 = SIZE
\           2 = MOVE
\           4 = SCALE X
\           8 = SCALE Y
\        0x10 = FILL
\        0x20 = SIZE X
\        0x40 = SIZE Y
\        0x80 = SCROLL
\       0x100 = RESIZEABLE
\       0x200 = MOVEABLE
\       0x400 = MULTISEL
\       0x800 = FILL
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=stretch.on
\ (sob-id --)
\ Makes this Screen OBject stretch.
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=stretch.off
\ ( sobId --)
\ If the Screen OBject identified by SOB-ID is a CONTAINER ,
\ then this command will disable stretching for this container.
\ Else if its parent SOB is a CONTAINER, then this command will
\       disable stretching for the parent container.
\ No input parameters
\ --
\ No output parameters

 help_pos sob.hscroll=off
\ ( bool  , sobId --)
\ Set the flag that controls if Horizontal Scrolling  of the Screen OBject identified by SOBID is to be disabled
\ BOOL      Boolean
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.fthcli=state
\ ( bool  , sobId --)
\ Set the flag that controls whether this control is the source of FORTH CLI input
\ BOOL      Boolean
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.hover=state
\ ( bool  , sobId --)
\ Set the flag that controls whether this control changes colour on mouse hover
\ Only implemented for LABELs !
\ BOOL      Boolean
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.vscroll=off
\ ( bool  , sobId --)
\ Set the flag that controls if Vertical Scrolling  of the Screen OBject identified by SOBID is to be disabled
\ BOOL      Boolean
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=usera
\ ( bool  , sobId --)
\ Set the USER A flag of the Screen OBject identified by SOBID
\ BOOL      Boolean
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob@usera
\ (    sobId --  bool)
\ Get the USER A flag of the Screen OBject identified by SOBID
\ SOB-ID    identity of target Screen OBject
\ --
\ BOOL      Boolean

 help_pos sob=sizeable
\ (bool, sob-id --)
\ Set whether this SOB can be resized by the user with the mouse
\ Only has effect on WINDOW type SOBS
\ BOOL      0 = no resizing
\           else = resizing allowed
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob=moveable
\ (bool, sob-id --)
\ Set whether this SOB can be moved by the user with the mouse
\ Only has effect on WINDOW type SOBS
\ BOOL      0 = no moving
\           else = moving allowed
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_0pos sob.listview.rgb@headers
\ ( sob-id -- FilterText, FilterBack , Text, Back  )
\  If the target SOB-ID is a LISTVIEW then
\  return the RGB colour codes used for the HEADER ROW.
\  RGB codes are -1 if the internal default RGB code is to be applied.
\ SOB-ID    identity of target Screen OBject
\ --
\ FilterTextCol    RGB code for the TEXT of a header when there is a FILTER on a column
\ FilterBackCol    RGB code for the BACKground of a header when there is a FILTER on a column
\ TextCol          RGB code for the TEXT of a header when there is no FILTER on a column
\ BackCol          RGB code for the BACKground of a header when there is no FILTER on a column

 help_0pos sob.listview.header=default
\ ( boolean, col-id , sob-id --   )
\  If the target SOB-ID is a LISTVIEW then
\  define whether the column header for column COL-ID
\  is displayed in the default ot alternative color/background combination
\  A vaue of  -1  causes the system to use the internal default RGB code
\
\ FilterTextCol    RGB code for the TEXT of a header when there is a FILTER on a column
\ FilterBackCol    RGB code for the BACKground of a header when there is a FILTER on a column
\ TextCol          RGB code for the TEXT of a header when there is no FILTER on a column
\ BackCol          RGB code for the BACKground of a header when there is no FILTER on a column
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.listview.rgb=headers
\ ( FilterText, FilterBack , Text, Back , sob-id --   )
\  If the target SOB-ID is a LISTVIEW then
\  set the RGB colour codes used for the HEADER ROW.
\
\  A vaue of  -1  causes the system to use the internal default RGB code
\
\ FilterTextCol    RGB code for the TEXT of a header when there is a FILTER on a column
\ FilterBackCol    RGB code for the BACKground of a header when there is a FILTER on a column
\ TextCol          RGB code for the TEXT of a header when there is no FILTER on a column
\ BackCol          RGB code for the BACKground of a header when there is no FILTER on a column
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.listview.rgb@rows
\ ( sob-id -- OddText , OddBack  , EvenText , EvenBack   )
\  If the target SOB-ID is a LISTVIEW then
\  return the RGB colour codes used for the rows (odd, even).
\  RGB codes are -1 if the internal default RGB code is to be applied.
\ SOB-ID    identity of target Screen OBject
\ --
\ OddTextCol    RGB code for the TEXT of an even numbered row
\ OddBackCol    RGB code for the BACKground of an even numbered row
\ EvenTextCol   RGB code for the TEXT of an odd numbered row
\ EvenBackCol   RGB code for the BACKground of an odd numbered row

 help_pos sob.listview.rgb=rows
\ ( FilterText, FilterBack , Text, Back , sob-id --   )
\  If the target SOB-ID is a LISTVIEW then
\  set the RGB colour codes used for the rows (odd, even).
\
\  A vaue of  -1  causes the system to use the internal default RGB code
\
\ OddTextCol    RGB code for the TEXT of an even numbered row
\ OddBackCol    RGB code for the BACKground of an even numbered row
\ EvenTextCol   RGB code for the TEXT of an odd numbered row
\ EvenBackCol   RGB code for the BACKground of an odd numbered row
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.listview=editable
\ (bool, sob-id --)
\ Set whether this SOB can be edited by the user
\ Only has effect on LISTVIEW type SOBS
\ BOOL      0 = no moving
\           else = moving allowed
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos sob.callback=xt.delete
\ (xt, sob-id --)
\ Assign the callback value xt to the Screen OBject sob-id
\ This will be activated when this Screen OBject is being delete
\ XT        eXecution Token of routine to be called on Screen OBject deletion
\           XT must have the stack behaviour (--)
\ SOB-ID    identity of target Screen OBject
\ --
\ No output parameters

 help_pos app@arg
\ (argIdChar -- value)
\ For each letter A..Z there is an internal variable, default =0
\ On invocation this application reads the text after the application path/name/extension
\ if, for example, the application reads a  F then the 'F' variable will be incremented
\                                           f then the 'F' variable will be decremented
\ ( 'F' is used internally to let the use increase/decrease the default Font size.
\ If argIdChar is invalid then a value 0   0   will be returned
\ ARGIDCHAR  identifies the wanted internal variable
\ --
\ VALUE    the value of the specified internal variable

 help_pos rgb
\ (red, green, blue -- rgb)
\ Mixes the three colours to give the internal representation
\ of the resulting colour
\ RED    an 8 bit value representing the intensity of this colour component
\ GREEN  an 8 bit value representing the intensity of this colour component
\ BLUE   an 8 bit value representing the intensity of this colour component
\ --
\ RGB    the resulting, mixed , colour code

 help_pos sob=empty
\ (sob-id --)
\ Removes all items associated with a SOB
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\ --
\ No output parameters

 help_pos sob.item@user.find
\ Find the ITEM associated with the user data  UDATA  in a given SOB
\ (ud,  sob-id -- item-id)
\ UD        The user data to looked for
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\ --
\ ITEM-ID   The identity of the target line in the SOB

 help_pos sob.item@user
\ Get the user data associated with an ITEM in the given SOB
\ (item-id,  sob-id -- ud)
\ ITEM-ID   The identity of the target line in the SOB
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\              MENUs (horizontal and vertical) note: ITEM-ID will be ignored
\ --
\ UD        The user data to be associated with the item

 help_pos sob.item=user
\ Sets the user data associated with an ITEM  in a given SOB
\ (ud , item-id,  sob-id --)
\ UD        The user data to be associated with the item
\ ITEM-ID   The identity of the target line in the SOB
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\              MENUs (horizontal and vertical) note: ITEM-ID will be ignored
\ --
\ No output parameters

 help_pos sob.item@count
\ Gets the number of entries in a given SOB
\ (sob-id -- u)
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\
\ --
\ U         Number of items in the SOB

 help_pos sob.listview.col@name
\ Gets the text displayed by a listview column header
\ (col-id, sob-id -- c-addr, u)
\ COL-ID    Identity of column
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ C-ADDR    address of a character string
\ U         length of character string
\           0 if error

 help_pos sob.listview.col=name
\ Sets the text displayed by a listview column header
\ (c-addr, u, col-id, sob-id --)
\ C-ADDR    address of a character string - text to go in the column header
\ U         length of character string
\ COL-ID    Identity of column
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview.col=add
\ Add a new column to the SOB
\ Give the column header the text specified by   c-addr / u
\ (c-addr, u, sob-id -- u)
\ C-ADDR    address of a character string - text to go in the column header
\ U         length of character string
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ U         number of columns
\           -1 if error

 help_pos sob.listview.col=delete
\ Delete the specified column of the SOB
\ (col-id, sob-id -- )
\ COL-ID    Identity of column to be deleted, zero based index
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview.col=width
\ Set the width of the specified LISTVIEW column
\ (width, col-id, sob-id -- )
\ WIDTH     Width of column
\           = -1   imples autosize to column text
\           = -2   imples autosize to column header
\           else = width in pixels
\ COL-ID    Identity of target column
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview@xywh
\ Get the  number of rows that fit in the display area of a listview
\ ( sob-id -- nbr rows )
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ ROWS     Number of rows displayable
\         = -1 on error

 help_pos sob.listview.hscroll=col
\ Scroll the display area of a listview so that the column COL-ID is visible
\ ( col-id, sob-id -- nbr rows )
\ COL-ID
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ ROWS     Number of rows displayable
\         = -1 on error

 help_pos sob.listview@rows
\ Get the  number of rows that fit in the display area of a listview
\ ( sob-id -- nbr rows )
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ ROWS     Number of rows displayable
\         = -1 on error

 help_pos sob.listview.cols=delete
\ (sob-id --)
\ Delete all columns of the specified SOB except for the FIRST column
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview.cols@count
\ (sob-id -- u|0)
\ Return the number of columns in the SOB
\ SOB-ID    Identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ U         Number of columns in the identified SOB
\           0  if SOB-ID does not specifiy a Listview SOB

 help_pos sob.listview=rowselect
\ (flag, sob-id --)
\ Set whether the specified SOB (a LISTVIEW) has full row select or not.
\ FLAG      boolean value defining whether LISTVIEW supports full row select
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

\  LVS_ICON  0000H
\  LVS_REPORT   0001H
\  LVS_SMALLICON  0002H
\  LVS_SMALLICON  0002H
\  LVS_LIST  0003H
\  LVS_TYPEMASK  0003H
\  LVS_SINGLESEL  0004H
\  LVS_SHOWSELALWAYS  0008H
\  LVS_SORTASCENDING  0010H
\  LVS_SORTDESCENDING  0020H
\  LVS_SHAREIMAGELISTS 0040H
\  LVS_NOLABELWRAP  0080H
\  LVS_AUTOARRANGE  0100H
\  LVS_EDITLABELS  0200H
\  LVS_OWNERDATA  1000H
\  LVS_NOSCROLL  2000H
\  LVS_TYPESTYLEMASK   0fc00H
\  LVS_ALIGNTOP  0000H
\  LVS_ALIGNLEFT  0800H
\  LVS_ALIGNMASK  0c00H
\  LVS_OWNERDRAWFIXED  0400H
\  LVS_NOCOLUMNHEADER  4000H
\  LVS_NOSORTHEADER  8000H
 help_pos sob.listview=extendedStyle
\ (bool, element, sob-id --)
\ Set the EXTENDEDLISTVIEWSTYLE to the state given by BOOL for the LISTVIEW Screen OBject
\ identified by SOB-ID
\
\ BOOL      boolean value
\ ELEMENT   Bit mask identifing the Extended Style to be set/reset
\ LVS_EX_GRIDLINES        000001H
\ LVS_EX_SUBITEMIMAGES    000002H
\ LVS_EX_CHECKBOXES       000004H
\ LVS_EX_TRACKSELECT      000008H
\ LVS_EX_HEADERDRAGDROP   000010H
\ LVS_EX_FULLROWSELECT    000020H
\ LVS_EX_ONECLICKACTIVATE 000040H
\ LVS_EX_TWOCLICKACTIVATE 000080H
\ LVS_EX_FLATSB           000100H
\ LVS_EX_REGIONAL         000200H
\ LVS_EX_INFOTIP          000400H
\ LVS_EX_UNDERLINEHOT     000800H
\ LVS_EX_UNDERLINECOLD    001000H
\ LVS_EX_MULTIWORKAREAS   002000H
\ LVS_EX_LABELTIP         004000H
\ LVS_EX_BORDERSELECT     008000H
\ LVS_EX_DOUBLEBUFFER     010000H
\ LVS_EX_HIDELABELS       020000H
\ LVS_EX_SINGLEROW        040000H   - has no effect
\ LVS_EX_SNAPTOGRID       080000H
\ LVS_EX_SIMPLESELECT     100000H
\
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_0pos sob.listview.sel=multi

 help_0pos sob.listview.sel=single

 help_0pos sob.listview.gridline=state

 help_pos sob.listview@rowcol
\ (row-id, col-id, sob-id -- c-addr, u)
\ Return the character string currently associated with the specified ROW and COL
\ of the  Screen OBject identified by sob-id
\ ROW-ID    Identity of line to be obtained, zero based index
\ COL-ID    Identity of line to be obtained, zero based index
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ C-ADDR    address of a character string - text displayed in edit box
\ U         length of character string

 help_pos sob.listview=rowcol
\ (c-addr, u, row-id, col-id, sob-id -- )
\ Set the character string currently associated with the specified line
\ of the  Screen OBject identified by sob-id
\ C-ADDR    address of a character string - text displayed in edit box
\ U         length of character string
\ ROW-ID    Identity of line to be set, zero based index
\ COL-ID    Identity of line to be set, zero based index
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_0pos sob.listview.row=canvas
\ (im-id, row-id, sob-id -- )
\ Associate the IMAGE identified by IM-ID with the row ROW-ID of the SOB SOB-ID
\ IM-ID     Index of image to be used for this row
\ ROW-ID    Identity of line to be obtained, zero based index
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview=details
\ (sob-id --)
\ Sets the display style of a LISTVIEW object to be "DETAILS"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview=icon
\ (sob-id --)
\ Sets the display style of a Listview object to be "ICON"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview=list
\ (sob-id --)
\ Sets the display style of a Listview object to be "LIST"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview=smallicon
\ (sob-id --)
\ Sets the display style of a Listview object to be "SMALLICON"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_pos sob.listview=tile
\ (sob-id --)
\ Sets the display style of a Listview object to be "TILE"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_0pos sob.list=drag
\ (sob-id --)
\ Sets the display style of a Listview object to be "TILE"
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LISTVIEW
\ --
\ No output parameters

 help_0pos sob.listview=checkbox
\ (lines, c-addr, u, xt --)

 help_0pos sob.listview@width
\ (   sob-id -- x)

 help_0pos sob.listview.checkbox@state
\ ( row-id , sob-id -- state)

 help_0pos sob.listview.checkbox=state
\ (state,  row-id , sob-id --  )

 help_pos sob.imageList=new
\ ( u , sob-id -- )
\ Create an ImageList that can be loaded with images that can be displayed in a ListView control.
\ The ImageList is owned by / assigned to the Screen OBject identified by SOB-ID.
\ The images placed in the ImageList are to be of size   U * U pixels.  U seems to be limited to 120!
\ U         Size ( height and width ) of the images to be held in the ImageList
\ SOB-ID    Identity of the Screen OBject (a ListView) that is to be the owner of the ImageList.
\ --
\ No output parameters
\

 help_pos sob.listview=new
\ (lines, c-addr, u, xt -- sob-id)
\ Creates a LIST VIEW  on the current display
\ TIPS n TRICKS
\     use SOB>STYLE.EXTEND   immediately before creating the new LISTVIEW
\     if you want to add additional STYLEs to the default creation parameters.
\     e.g.
\          0x04   to allow a single line to be selected
\          0x08   to highlight the selected lines
\          0x0800000 to display a border
\     so a border &  single line selection would be
\     0x800000   0x04   OR    SOB>STYLE.EXTEND
\
\     SOB.CALLBACK=XT1  is used internally, it triggers on ROW selection
\
\     To create editable fields
\         set a callback for SOB.CALLBACK=XT2
\         Callback handler must have the stack behaviour ( VAL -- )
\
\         VAL =  0 implies START of edit
\         Decide if the specific ROW / COL is editable
\             the  zero indexed ROW is held in  SOB.CALLBACK@DATA
\             the  zero indexed COL is held in   SOB.CALLBACK@DATA2
\         To enable EDITING of this specific ROW/COL:
\            call within the callback handler     1 SOB.CALLBACK=VALUE
\            if not specifically enabled, then it is disabled by default.
\
\         VAL =  1 implies END of edit
\         Decide if the edit is to be discarded
\             the  zero indexed ROW is held in   SOB.CALLBACK@DATA
\             the  zero indexed COL is held in   SOB.CALLBACK@DATA2
\             the  ORIGINAL TEXT is a 0 terminated string starting at PAD
\                e.g.   PAD .\0   cr
\             the  NEW TEXT is a 0 terminated string starting at
\                      SOB.CALLBACK@DATA
\               e.g.   SOB.CALLBACK@DATA .\0   cr
\         To discard EDITING of this specific ROW/COL:
\            call within the callback handler     0 SOB.CALLBACK=VALUE
\            if not specifically discarded, then it is accepted by default.
\
\     To react to mouse clicks
\         set a callback for SOB.CALLBACK=XT2
\         Callback handler must have the stack behaviour ( VAL -- )
\
\         VAL =  3 implies one of the following occurred, identified by    SOB.CALLBACK@DATA3
\             01 =  Mouse Left  Button Single Click
\             06 =  Mouse Right Button Double Click
\             07 =  Mouse Right Button Single Click
\
\     To sort columns
\         set a callback for SOB.CALLBACK=XT2
\         Callback handler must have the stack behaviour ( VAL -- )
\
\         VAL =  2 implies a column header was clicked
\         SOB.CALLBACK@DATA will return the zero indexed of the current COLUMN
\         1) simply return from the Callback handler, and sorting is based on the current COL
\         2) to select a different COLUMN for sorting
\            call         x SOB.CALLBACK=VALUE
\            where  X is the  zero indexed of the COLUMN that you want to use for the sorting
\            if X = -1 then sorting is not done.
\
\ LINES     Number of lines to be supported
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the list box
\           is really SOB.CALLBACK=XT1
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.list=new
\ (lines, c-addr, u, xt -- sob-id )
\ Creates a LIST BOX  on the current display
\ LINES     Number of lines to be supported
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the list box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.listv=new
\ (lines, c-addr, u, xt -- sob-id)
\ Creates a LIST BOX  on the current display
\ LINES     Number of lines to be supported
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the list box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_0pos sob.list=Hscroll
\ (lines, c-addr, u, xt --)
\ Creates a LIST BOX  on the current display
\ LINES     Number of lines to be supported
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the list box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.list>default
\ (--)
\ Unless overridden, causes the next LIST Screen OBject to be created with the
\ default characteristics:
\    no sorting
\    no vertical scroll bar
\    no horizontal scroll bar
\    visible space is an integral number of lines
\    no border displayed
\ --
\ No output parameters

 help_pos sob.list>sorted
\ (--)
\ Unless overridden by SOB.LIST>DEFAULT , causes the next LIST Screen OBject
\ to be created with the characteristic:
\    sorting
\ --
\ No output parameters

 help_pos sob.list>scroll.v
\ (--)
\ Unless overridden by SOB.LIST>DEFAULT , causes the next LIST Screen OBject
\ to be created with the characteristic:
\    vertical scroll bar
\ --
\ No output parameters

 help_pos sob.list>scroll.h
\ (--)
\ Unless overridden by SOB.LIST>DEFAULT , causes the next LIST Screen OBject
\ to be created with the characteristic:
\    horizontal scroll bar
\ --
\ No output parameters

 help_pos sob.list>height
\ (--)
\ Unless overridden, by sob.list>DEFAULT causes the next LIST Screen OBject
\ to be created with the characteristic:
\    visible space is NOT an integral number of lines
\ --
\ No output parameters

 help_pos sob.list>border
\ (--)
\ Unless overridden, by sob.list>DEFAULT causes the next LIST Screen OBject
\ to be created with the characteristic:
\    border displayed
\ --
\ No output parameters

 help_pos sob.list>multi
\ (--)
\ Unless overridden, by sob.list>DEFAULT causes the next LIST Screen OBject
\ to be created with the characteristic:
\    multiple selection
\ --
\ No output parameters

 help_pos sob.list>user
\ (u--)
\ List-View Window Styles
\ Unless overridden, by sob.list>DEFAULT causes the next LIST Screen OBject
\ to be created with the characteristic defined by the value U
\ U        Value to be used
\ --
\ No output parameters

 help_pos sob.list=sort
\ (sob-id --)
\ If the Screen OBject identified by SOB-ID is a LISTBOX, then the
\ LIST BOX will be displayed as a SORTED list
\ SOB-ID    identity of targeted Screen OBject
\ --
\ No output parameters

 help_pos sob.list=unsort
\ (sob-id --)
\ If the Screen OBject identified by SOB-ID is a LISTBOX, then the
\ LIST BOX will be displayed as an UNSORTED list
\ SOB-ID    identity of targeted Screen OBject
\ --
\ No output parameters

 help_pos sob.list=reverse
\ (sob-id --)
\ If the Screen OBject identified by SOB-ID is a LISTBOX, then the
\ LIST BOX will be displayed in reverse order
\ SOB-ID    identity of targeted Screen OBject
\ --
\ No output parameters

 help_pos sob.item=find
\ (line-id, c-addr, u , sob-id -- index)
\ Search the ITEMS of the Screen OBject given by SOB-ID for the entry that exactly matches
\ the given by c-addr,u  Start the search at the line AFTER that given by index.
\ The Screen OBject given by SOB-ID should be one of:
\             COMBO
\             LIST
\             LISTVIEW
\
\ LINE-ID   Identity of line to be obtained, ignored for a simple edit box
\           = -1 = search all. Remember list box indices are (0..n)
\ C-ADDR    address of a character string to be matched
\ U         length of character string
\ SOB-ID    identity of target Screen OBject
\ --
\ INDEX     Index of matched entry
\           = -1 if not found

 help_pos sob.item=find.pre
\ (line-id, c-addr, u , sob-id -- index)
\ Search the ITEMS of the Screen OBject given by SOB-ID for the entry that begins with the
\ text given by c-addr,u  Start the search at the line AFTER that given by index.
\ The Screen OBject given by SOB-ID should be one of:
\             COMBO
\             LIST
\             LISTVIEW
\ LINE-ID   Identity of line to be obtained, ignored for a simple edit box
\           = -1 = search all. Remember list box indices are (0..n)
\ C-ADDR    address of a character string to be matched
\ U         length of character string
\ SOB-ID    identity of target Screen OBject
\ --
\ INDEX     Index of matched entry
\           = -1 if not found

 help_pos sob.edit=new
\ (c-addr, u, xt -- sob-id)
\ Creates a simple box with text, on the current display
\ Hints:
\                        These intercept the input BEFORE a change to the content
\     sob.key.any=xt     to intercept any input
\     sob.key.cr=xt      to intercept only the ENTER key
\     sob.key.tab=xt  to intercept only the TAB key
\
\                        Post change intercepts:
\     sob.callback=xt2   to be informed AFTER a change to the content
\
\ C-ADDR    address of a character string - text to be displayed in edit box
\ U         length of character string
\ XT        eXecution Token of routine to be called on editing in the edit box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.combo=new
\ (c-addr, u, xt -- sob-id)
\ Creates a COMBO BOX with text, on the current display
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the combo box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.combo.edit=new
\ (c-addr, u, xt -- sob-id)
\ Creates a COMBO BOX with text, on the current display
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the combo box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.combo.drop=new
\ (c-addr, u, xt -- sob-id)
\ Creates a COMBO BOX with text, on the current display
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ XT        eXecution Token of routine to be called on selection in the combo box
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob@line.size
\ (line-id, sob-id -- u)
\ Return the size of the text line associated with the specified Screen OBject
\ LINE-ID   identity of the text part
\           IF = -1
\           THEN
\              COMBO-BOX    identity of current selected line
\              LIST-BOX     identity of current selected line
\              other        all text associated with Screen OBject
\
\           ELSE if SOB-ID is a:
\              COMBO-BOX    identity of line
\              LIST-BOX     identity of line
\              EDIT-BOX     line-id will be ignored
\              Multi-Line EDIT-BOX  identity of line
\              other        line-id will be ignored
\
\ SOB-ID    identity of target Screen OBject
\ --
\ U         length of text in characters, excluding a 0 terminating character

 help_pos sob@line2buf
\ (c-addr, u-in, line-id, sob-id -- c-addr, u-out)
\ Return the  text line associated with the specified Screen OBject
\ WARNING: the max retrieved text length is 0xffff characters!
\ C-ADDR    address of a character  buffer to receive the text
\ U-IN      size of buffer in characters
\ LINE-ID   identity of the text part
\           IF = -1
\           THEN
\              COMBO-BOX    identity of current selected line
\              LIST-BOX     identity of current selected line
\              other        all text associated with Screen OBject
\
\           ELSE if SOB-ID is a:
\              COMBO-BOX    identity of line
\              LIST-BOX     identity of line
\              EDIT-BOX     line-id will be ignored
\              Multi-Line EDIT-BOX  identity of line
\              other        line-id will be ignored
\
\ SOB-ID    identity of targeted Screen OBject
\ --
\ C-ADDR    address of a character string - associated with Screen OBject
\ U-OUT     length of returned character string
\           Note: = -1 if the text is to big for the buffer

 help_pos sob.item@text
\ (line-id, sob-id -- c-addr, u)
\ Return the character string currently associated with the specified line
\ of the  Screen OBject identified by sob-id
\ WARNING: the max retrieved text length is 0xffff characters!
\ LINE-ID   Identity of line to be obtained, ignored for a simple edit box
\           top line = 0
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              COMBO-BOX
\              LIST-BOX
\              EDIT-BOX     line-id will be ignored
\              Multi-Line EDIT-BOX
\ --
\ C-ADDR    address of a character string - text displayed in edit box
\ U         length of character string

 help_pos sob@line
\ (line-id, sob-id -- c-addr, u)
\ Return the character string currently associated with the specified line
\ of the  Screen OBject identified by sob-id
\ WARNING: the max retrieved text length is 0xffff characters!
\ LINE-ID   Identity of line to be obtained, ignored for a simple edit box
\           top line = 0
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              COMBO-BOX
\              LIST-BOX
\              EDIT-BOX     line-id will be ignored
\              Multi-Line EDIT-BOX
\ --
\ C-ADDR    address of a character string - text displayed in edit box
\ U         length of character string

 help_pos sob.item=add
\ (c-addr, u, sob-id -- index)
\ Adds a character string to a SOB
\ C-ADDR    address of a character string
\ U         length of character string
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              COMBO-BOX        text added to list
\              LIST-BOX         text added to list
\              LISTVIEW         text added to list
\              EDIT-BOX         text used as basis of edit
\           to add an item to a POPUP-MENU use SOB.POPUP=ADD (needs different parameters!)
\ --
\ INDEX     the zero-based index of added string
\           or a negative number on error.

 help_pos sob.edit=undo
\ (sob-id -- )
\ Undo the last edit command
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              EDIT-BOX         text used as basis of edit
\ --
\ No output parameters

 help_pos sob=ro
\ (bool, sob-id -- )
\ Sets the read-only/read-write state of an EDIT SOB
\ BOOL      boolean value defining whether EDIT box is Read-Only
\           0 = read and write
\           else = read only
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              EDIT-BOX         text used as basis of edit
\ --
\ No output parameters

 help_pos sob@ro
\ (sob-id -- bool)
\ Gets the read-only/read-write state of an EDIT SOB
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              EDIT-BOX         text used as basis of edit
\ --
\ BOOL      boolean value defining whether EDIT box is Read-Only
\           0 = read and write
\           else = read only

 help_pos sob.item@state
\ (index , sob-id -- state)
\ Obtains the selection state of an entry  in SOB
\ INDEX     Entry in SOB
\ SOB-ID    identity of target Screen OBject
\           SOB must be one of:
\              LIST-BOX         text on line number INDEX
\              LISTVIEW         text on line number INDEX
\ --
\ STATE    Boolean showing if item is selected
\           0 = not selected
\           else = selected

 help_pos sob.item.sel@id
\ (sel-id , sob-id -- u)
\ gets the identity of the SEL-ID'th selected item in a LIST or COMBO box
\ SOB-ID    identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO-BOX
\              LIST-BOX
\              LISTVIEW
\ --
\ SEL-CNT    the number of items selected in the specified SOB

 help_pos sob.sel@count
\ (sob-id -- sel-cnt)
\ gets the number of items selected in a LIST or COMBO box
\ SOB-ID    identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO-BOX
\              LIST-BOX
\              LISTVIEW
\ --
\ SEL-CNT    the number of items selected in the specified SOB

 help_pos sob.item@sel
\ (sob-id -- sel-id)
\ gets the identity of the current selection in a LIST or COMBO box
\
\ SOB-ID    identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO-BOX
\              LIST-BOX
\              LISTVIEW
\ --
\ SEL-ID    the identity of the current selected object with this SOB

 help_pos sob.item=delete
\ (item-id, sob-id --)
\ Deletes the specified item of a Screen OBject
\ ITEM-ID   The identity of the target line in the SOB
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\ --
\ No output parameters

 help_pos sob.items=delete
\ (nbr, sob-id --)
\ Deletes the first  NBR lines   of a Screen OBject
\ NBR       The identity of the target line in the SOB
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\ --
\ No output parameters

 help_pos sob=unsel
\ ( sob-id -- )
\ Unselect ALL the  items  of the Screen OBject SOB-ID
\
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW   only this one works!
\              RICH EDIT
\ --
\ No output parameters

 help_pos sob.item=sel
\ (item-id, sob-id --)
\ Sets the selection state of the item ITEM-ID of the Screen OBject SOB-ID
\ ITEM-ID   The identity of the current selected object with this SOB
\ SOB-ID    Identity of targeted Screen OBject
\           SOB must be one of:
\              COMBO
\              EDIT
\              LISTBOX
\              LISTVIEW
\              RICH EDIT
\ --
\ No output parameters

 help_pos sob.items@screen
\ (sob-id -- u)
\ Returns the number of lines displayable on the Screen OBject identified by SOB-ID
\ SOB-ID    identity of targeted Screen OBject
\           Only valid for LIST, COMBO or EDIT box
\ --
\ U         Number of lines

 help_pos sob=show.top
\ (item-id, sob-id --)
\ Sets the display of the Screen OBject specified by SOB-ID, to display the
\ item  ITEM-ID   at the top of the SOB's display area
\ SOB-ID    identity of targeted Screen OBject
\           Only valid for LIST, COMBO or EDIT box
\ --
\ No output parameters

 help_pos sob=show.end
\ (sob-id --)
\ Sets the display of the specified LIST, COMBO or EDIT box to show the last lines.
\ SOB-ID    identity of targeted Screen OBject
\           Only valid for LIST, COMBO or EDIT box
\ --
\ No output parameters

 help_pos sob.edit.multi=new
\ (lines, c-addr, u -- sob-id)
\ Create a multi line edit box, on the current display
\ LINES     Number of lines to be supported
\ C-ADDR    address of a character string - used to define width of SOB
\ U         length of character string
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.label=new
\ (c-addr, u, xt -- sob-id)
\ Creates a simple label with text on the current display
\ C-ADDR    address of a character string - name to be displayed in LABEL
\ U         length of character string
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.slider=new
\ (HorV, max-val, c-addr, u, xt -- sob-id)
\ Creates a SLIDER, on the current display
\ HorV      flag indicating whether the SLIDER is Horizonal or Vertical
\           0 = VERTICAL   else HORIZONAL
\ MAX-VAL   a number indicating the maximum value the SLIDER can have.
\ C-ADDR    address of a character string - giving name to be displayed with Screen OBject
\ U         length of character string
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (pos --) where POS = scroll position
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.slider=pos
\ (value, sob-id --)
\ Sets the SLIDER position associated with a given Screen OBject SLIDER
\ SOB-ID    identity of target Screen OBject SLIDER
\ VALUE     the new position of the slider
\ --
\ No output parameters

 help_pos sob.slider@pos
\ (sob-id -- value)
\ Gets the SLIDER position associated with a given Screen OBject SLIDER
\ SOB-ID    identity of target Screen OBject SLIDER
\ --
\ VALUE     the  position of the slider

 help_pos sob.slider>values
\ (range, page,  sob-id -- )
\ Sets the total "lines" in the RANGE, and the "lines" in a PAGE
\ for the SLIDER associated with a given Screen OBject SLIDER
\ RANGE     Number of lines
\ PAGE      Number of lines
\ SOB-ID    Identity of target Screen OBject SLIDER
\ --
\ No output parameters

 help_pos sob>trigger.async
\ (sob-id --)
\ Invoke the Critical Event for the Screen OBject identified by SOB-ID
\ The trigger, sent via a PostMessage, will be queued.
\ SOB-ID    identity of target Screen OBject BUTTON
\ --
\ No output parameters

 help_pos sob>trigger.sync
\ (sob-id --)
\ Invoke the Critical Event for the Screen OBject identified by SOB-ID
\ The trigger, sent via a SendMessage, will be executed immediately!
\ SOB-ID    identity of target Screen OBject BUTTON
\ --
\ No output parameters

 help_pos sob.key.tab=xt
\ (xt, sob-id --)
\ Provide an eXecution Token that will be executed whenever the TAB key
\ is pressed whilst this Screen OBject has the keyboard focus
\ SOB-ID    identity of target Screen OBject BUTTON
\ XT        eXecution Token of routine to be called on TAB key being entered
\           XT must have the stack behaviour ( TAB char --)
\           Use sob.callback@id to get triggering sob-id
\           and sob.callback@data to get the key code
\ --
\ No output parameters

 help_pos sob.key.cr=xt
\ (xt , sob-id --)
\ Provide an eXecution Token that will be executed whenever the CR (carriage return) key
\ is pressed whilst this Screen OBject has the keyboard focus
\ SOB-ID    identity of target Screen OBject BUTTON
\ XT        eXecution Token of routine to be called on CR key being entered
\           XT must have the stack behaviour ( CR char --)
\           Use sob.callback@id to get triggering sob-id
\           and sob.callback@data to get the key code
\ --
\ No output parameters

 help_pos sob.key.any=xt
\ (xt, sob-id --)
\ Provide an eXecution Token that will be executed whenever any key
\ is pressed whilst this Screen OBject has the keyboard focus
\ SOB-ID    identity of target Screen OBject BUTTON
\ XT        eXecution Token of routine to be called on any key being entered
\           XT must have the stack behaviour ( KEY char --)
\           Use sob.callback@id to get triggering sob-id
\           and sob.callback@data to get the key code
\ --
\ No output parameters

 help_pos sob=key
\ (new-char --)
\ Only usable from with a callback routine belonging to
\ sob.key.any=xt , sob.key.tab=xt or sob.key.cr=xt
\ If this command is called then the  key character that triggered
\ the callback will be deleted i.e. NOT returned to the triggering Screen OBject!
\ If new-char = -1 then nothing else happens
\ ELSE the character value of new-char will be sent to the
\ target Screen OBject.
\ NEW-CHAR  If <> -1 the character to be sent
\ --
\ No output parameters

 help_pos sob.panel.v=new
\ ( lines, caddr, u -- sob-child1, sob-child1, sob-Parent)
\ Creates a SPLIT WINDOW with a VERTICAL divider.
\ LINES     HEIGHT of the SPLIT WINDOW expressed in "lines"
\ CADDR     Total WIDTH of SPLIT WINDOW expressed in characters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.panel.h=new
\ ( lines, caddr, u -- sob-child1, sob-child1, sob-Parent)
\ Creates a SPLIT WINDOW with a HORIZONTAL divider.
\ LINES     Total HEIGHT of the SPLIT WINDOW expressed in "lines"
\ CADDR     WIDTH of SPLIT WINDOW expressed in characters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.void=new
\ ( w , h -- sob-child )
\ Creates an empty Screen OBject of width W and height H
\ W          WIDTH of empty area in pixels
\ H          HEIGHT of empty area in pixels
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.overlay
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ All child Screen OBjects of this container will be subject to
\ management of their size and positioning. The children will be placed
\ on top of one another and will have the size and width of the largest
\ size and width.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob@sibling.by.offset
\ ( offset , sob-id  --  sob-idS)
\ Return the SOBID of a SIBLING of the Target Screen OBject.
\ eg OFFSET =  2  would return the 2nd SOB defined AFTER the Target
\    OFFSET = -1  would return the 1st SOB defined BEFORE the Target
\
\ OFFSET
\ SOB-ID    internally of reference Screen OBject
\ --
\ SOB-IDC  Screen OBject id of found Child

 help_pos sob.con.matrix
\ (RorC, dim -- sob-id)
\ Creates a container for other Screen OBjects.
\ All child Screen OBjects of this container will be subject to
\ management of their size and positioning. The children will be placed
\ in a 2 dimensional matrix.
\ RORC      flag indicating whether CHILDREN are displayed in ROWS or COLS
\           0 = COLUMNS   else ROWS
\ DIM       dimension, number of Rows or Cols to be displayed
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob=redim
\ (dim , sob-id -- )
\ Resize the dimension of a MATRIX type Screen OBject
\ DIM       new dimension of the matrix
\ SOB-ID    internally of target Screen OBject
\ --
\ ROW      0-based index
\ COL      0-based index

 help_pos sob@rc
\ (sob-id --  row , col )
\ Return the row / column values for this SOB. a container for other Screen OBjects.
\ Only non-zero for the CHILD of a  matrix Screen Object
\ SOB-ID    internally id if  target Screen OBject
\ --
\ ROW      0-based index
\ COL      0-based index

 help_pos sob@dim
\ (  sob-id  --  dim )
\ Identifies if the specified matrix Screen OBject is orientated by row or column
\ SOB-ID    internally id of  Matrix Screen OBject
\ --
\ DIM      = 0        if not a Matrix
\          = positive value if matrix is a column matrix
\          = negative value if matrix is a row matrix

 help_pos sob@rc.id
\ ( row , col , sob-idM --  sob-idC)
\ Return the SOBID of the row / column values for this SOB. a container for other Screen OBjects.
\ Only non-zero for the CHILD of a  matrix Screen Object
\ ROW      0-based index
\ COL      0-based index
\ SOB-ID   Screen OBject id of a Matrix Screen OBject
\ --
\ SOB-IDC  Screen OBject id of found Child
\          = 0 if row/col invalid, or sob-idM nt a matrix

 help_pos sob.child@count
\ ( sob-id  --  Nbr)
\ Return the number of CHILDREN that the target Screen OBject has.
\ Only non-zero for a CONTAINER type Screen OBject
\ SOB-ID    internally of Matric Screen OBject
\ --
\ NBR      Number of Children

 help_pos sob.child@handle
\ ( Nbr , sob-id  --  SOB-IDC )
\ Return the HANDLE of the Nbr'th child of the target Screen OBject.
\ Only non-zero for a CONTAINER type Screen OBject
\ NBR      Number of Child ( 1.. Nbr of Children)
\ SOB-ID   handle of parent  Screen OBject
\ --
\ SOB-IDC   handle of child  Screen OBject
\           = 0 on Nbr out-of-range, or SOB-ID  invalid

 help_pos sob.con.col.hw
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple column.
\ The direct children of this container are forced to have the same WIDTH
\ and height
\ no input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.row.hw
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple row.
\ The direct children of this container are forced to have the same WIDTH
\ and height
\ no input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.col.w
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple column.
\ The direct children of this container are forced to have the same WIDTH
\ The WIDTH is that of the widest child.
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.col.h
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple column.
\ The direct children of this container are forced to have the same HEIGHT
\ The HEIGHT is that of the tallest child.
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.row.h
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple row.
\ The direct children of this container are forced to have the same HEIGHT
\ The HEIGHT is that of the tallest child.
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.row.w
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple row.
\ The direct children of this container are forced to have the same WIDTH
\ The WIDTH is that of the widest child.
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con.frame
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ Its children an placed in a simple column.
\ Its children are not subject to size control.
\ This container surrounds its children with a black lined box.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.row
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ Its children an placed in a simple row.
\ Its children are not subject to size control.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.splitter.v
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ Its children an placed in a simple row.
\ Its children are not subject to size control.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.vertical
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ Its children an placed in a simple row.
\ Its children are not subject to size control.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.con.col
\ (-- sob-id)
\ Creates a container for other Screen OBjects.
\ This container positions all of its direct children in a simple column.
\ This is the default container.
\ This container imposes no management on the childrens width or height.
\ No input parameters
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\
\ See also    help* sob.con.

 help_pos sob.con=open
\ (sob-id --)
\ Re-opens a container Screen OBject so that more child Screen OBjects
\ can be placed within it.
\ SOB-ID   identity of container Screen OBject to be re-opened
\ --
\ No output parameters

 help_pos sob.con=close
\ (--)
\ Terminates the currently active size and positioning management of
\ Screen OBjetcs

 help_pos sob.button.dummy=new
\ (c-addr, u, xt -- sob-id)
\ Creates a PUSH BUTTON on the current display
\ C-ADDR    address of a character string - name to be displayed in BUTTON
\ U         length of character string
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\           See ALSO SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.button.push=new
\ (c-addr, u, xt -- sob-id)
\ Creates a PUSH BUTTON on the current display
\ C-ADDR    address of a character string - name to be displayed in BUTTON
\ U         length of character string
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\           See ALSO SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.button.radio=new
\ (c-addr, u, xt -- sob-id)
\ Creates a RADIO BUTTON on the current display
\ C-ADDR    address of a character string - name to be displayed in BUTTON
\ U         length of character string
\ XT        eXecution Token of routine to be called on Screen OBject selection
\           XT must have the stack behaviour (--)
\           See ALSO SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob>size
\ ( height , width   --   )
\ Overrides the default PIXEL size for the next call to
\   sob.graphics=new
\ or
\  sob.graphics.holder=new
\ HEIGHT    of image ares in PIXELS
\ WIDTH     of image ares in PIXELS
\ --
\ no output parameters

 help_pos sob.graphics.holder=new
\ (   height , width , tri-value, xt -- sob-id)
\ Create an empty SOB to which can (later) be added an IMAGE or CANVAS, as well
\ as a OVERLAY CANVAS
\ HEIGHT    minimum height of image area in PIXELS
\ WIDTH     minimum width  of image area in PIXELS
\ TRI-VALUE      indicates   the image     size rule
\           Defines the SOB size management
\           0 = image is zoomed (in/out) to fit SOB
\           2 = image stays full size, aligned at (0,0)
\           3 = is stretched/shrunk to fit SOB
\           1 = SOB minimum size = image size. Image size constant
\           else =  SOB minimum size = image size. Image zooms with SOB
\                  or takes the size of the SOB if SOB is bigger
\ XT        eXecution Token of routine to be called on SOB  selection
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\           = 0 = ERROR

 help_pos sob.imagelist=add
\ (c-addr, u, sob-id  -- retVal )
\ Create an image from a BITMAP file or JPG file, then add it to the ImageList assigned to the ListView
\ identified by SOB-ID.
\ C-ADDR    address of a character string - file or path&file name of bitmap
\ U         length of character string
\ SOB-ID    Identity of target Screen OBject, must be a ListView
\ --
\ RetVal    = -1 on error
\           else 0 based index of created Image

 help_pos sob@malloc
\ ( sob-id -- memPtr )
\ Get the MEMPTR associated with the specified Screen OBject
\
\ SOB-ID    identity of target Screen OBject
\ --
\ MEMPTR    ptr to memory
\           = 0 = ERROR

 help_pos sob=malloc
\ ( memPtr , sob-id -- memPtr )
\ Set the MEMPTR associated with the specified Screen OBject
\
\ MEMPTR    ptr to memory
\ SOB-ID    identity of target Screen OBject
\ --
\ MEMPTR    ptr to memory
\           = 0 = ERROR

 help_pos sob@canvas.upper
\ ( sob-id -- u-canvas )
\ Get the CANVAS associated with the  upper element of a SOB_GRAPHICS Screen OBject
\
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ U-CANVAS  handle of the canvas
\           = 0 = ERROR

 help_pos sob@canvas.lower
\ ( sob-id -- u-canvas )
\ Get the CANVAS associated with the  lower element of a SOB_GRAPHICS Screen OBject
\
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ U-CANVAS  handle of the canvas
\           = 0 = ERROR

 help_pos sob.graphics.lower=canvas
\ (canvasId,  sob-id -- P-CANVAS )
\ Assigns the  canvas   CANVASID to be the lower element of a SOB_GRAPHICS object.
\ It does NOT release the previous object
\ CANVASID   the canvas to be assigned to the lower element
\ SOB-ID     internally allocated identity of a GRAPHICS   Screen OBject
\ --
\ P-CANVAS   identity of previous canvas
\            =   0 on error

 help_pos sob.graphics=new
\ (c-addr, u, tri-value, xt -- sob-id)
\ Create a Screen OBJect that can hold a GRAPHICS and insert the image from a:
\     BMP (bitmap), JPEG, WMF (metafile), ICO (icon), or GIF format file, on the current display
\ The image is converted to a CANVAS and the CANVAS is inserted as the lower element
\ of the SOB-GRAPHICS object
\ C-ADDR    address of a character string - file or path&file name of bitmap
\ U         length of character string
\ TRI-VALUE      indicates   the GRAPHICS     size rule
\           Basically who defines the SOB size
\           0 = SOB management, GRAPHIC is zoomed (in/out) to fit SOB
\           2 = SOB management, GRAPHIC stays full size, aligned at (0,0)
\           3 = SOB management, is stretched/shrunk to fit SOB
\           1 = SOB minimum size = GRAPHIC size. GRAPHIC size constant
\           else =  SOB minimum size = GRAPHIC size. GRAPHIC zooms with SOB
\ XT        eXecution Token of routine to be called on GRAPHICS selection
\           XT must have the stack behaviour (--)
\ --
\ SOB-ID    internally allocated identity of created Screen OBject
\           = 0 = ERROR

 help_pos sob.image@state
\ (sob-id -- canvasId)
\ Canvas identity of the lower graphic associated with the GRAPHICS SOB
\ identified by SOB-ID
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ CANVASID  = 0 on error
\           else = okay

 help_pos sob.graphics.lower=file
\ (c-addr, u,  sob-id -- bool)
\ Sets the BITMAP, JPG or GIF image source file associated with a given sob.graphics.
\ The previous image will be released.
\ The size of the Screen OBject is unchanged.
\ C-ADDR    address of a character string - file or path&file name of bitmap
\ U         length of character string
\ SOB-ID    internally allocated identity of target Screen OBject
\ --
\ BOOL      Boolean = 0 if okay
\           else =   -2  if Screen OBject does not support an image
\                    -3  if the specified file does not represent a valid image

 help_0pos sob.image=sizing
\ ( bool, sob-id --  )
\  WARNING: I think that this follows bad logic!
\ Changes the size of the BITMAP, JPG or GIF image source file associated with a given sob.image
\ The size of the Screen OBject is unchanged.
\ (change it using sob=size).
\ BOOL      indicates whether the image takes the size of the bitmap
\ SOB-ID    internally allocated identity of created Screen OBject
\ --
\ no otput parameters

 help_pos sob.button.check=new
\ (c-addr, u, xt -- sob-id)
\ Creates an OWNER DRAWN BUTTON on the current display
\ C-ADDR    address of a character string - file or path&file name of bitmap
\ U         length of character string
\ XT        eXecution Token of routine to be called on BUTTON selection
\           XT must have the stack behaviour (--)
\           See ALSO SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS
\ --
\ SOB-ID    internally allocated identity of created Screen OBject

 help_pos sob.button=state
\ (bool, sob-id --)
\ button-state shows visibly whether the button is pressed or not
\ BOOL      0 means clear the STATE, else set STATE
\ SOB-ID    identity of target Screen OBject BUTTON
\ --
\ No output parameters

 help_pos sob.button@state
\ (sob-id -- state)
\ Return the check/push state of the specified button.
\ SOB-ID    identity of target Screen OBject BUTTON
\ --
\ STATE     = 1 if button is checked
\           = 0 if button in not-checked
\            = -1 if not a checkable Screen OBject

 help_pos sob.button>lmr.default
\ (--)
\ Until overridden, by one of the sob.button>lmr.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed in the default horizontal position.
\ --
\ No output parameters

 help_pos sob.button>lmr.left
\ (--)
\ Until overridden, by one of the sob.button>lmr.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed to the LEFT of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button>lmr.middle
\ (--)
\ Until overridden, by one of the sob.button>lmr.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed to the Vertical MIDDLE of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button>lmr.right
\ (--)
\ Until overridden, by one of the sob.button>lmr.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed to the RIGHT of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button>tmb.default
\ (--)
\ Until overridden, by one of the sob.button>tmb.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed in the default vertical position
\ --
\ No output parameters

 help_pos sob.button>tmb.top
\ (--)
\ Until overridden, by one of the sob.button>tmb.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed in the TOP of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button>tmb.middle
\ (--)
\ Until overridden, by one of the sob.button>tmb.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed in the horizontally MIDDLE of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button>tmb.bottom
\ (--)
\ Until overridden, by one of the sob.button>tmb.xxxx commands, future BUTTON Screen OBjects
\ will be created so that any text will be placed in the BOTTOM of the BUTTONS area
\ --
\ No output parameters

 help_pos sob.button=style
\ (style, sob-id --)
\ Use this set a STYLE for an existing Screen OBject button.
\ Internally it sends a BM_SETSTYLE message to the target button.
\ STYLE
\    00  = push button
\    01  = auto radio button
\    02  = auto check box
\    03  = check box
\    04  = def push button
\    05  = group box
\    06  = auto 3 state button
\    07  = left text
\    08  = owner drawn
\    09  = 3 state
\    10  = user button
\    11  = bitmap
\    12  = bottom
\    13  = center
\    14  = icon
\    15  = flat
\    16  = left
\    17  = multi line
\    18  = notify
\    19  = push like
\    20  = right
\    21  = right button
\    22  = text
\    23  = top
\    24  = vertical center
\ SOB-ID    identity of target Screen OBject BUTTON
\ --
\ No output parameters

 help_pos TYPE.XXXX
\ Returns the value assigned to    TYPE.XXXX
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.DISPLAY
\ Returns the value assigned to    TYPE.DISPLAY
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.MENUBAR
\ Returns the value assigned to    TYPE.MENUBAR
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.MENUH
\ Returns the value assigned to    TYPE.MENUH
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.MENUV
\ Returns the value assigned to    TYPE.MENUV
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER
\ Returns the value assigned to    TYPE.CONTAINER
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.BUTTON.PUSH
\ Returns the value assigned to    TYPE.BUTTON.PUSH
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.BUTTON.RADIO
\ Returns the value assigned to    TYPE.BUTTON.RADIO
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.BUTTON.CHECK
\ Returns the value assigned to    TYPE.BUTTON.CHECK
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.HSCROLL
\ Returns the value assigned to    TYPE.HSCROLL
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.BUTTON.COL
\ Returns the value assigned to    TYPE.BUTTON_COL
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.VSCROLL
\ Returns the value assigned to    TYPE.VSCROLL
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.BUTTON.GRAPHICS
\ Returns the value assigned to    TYPE.BUTTON_GRAPICS
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.STATIC.TEXT
\ Returns the value assigned to    TYPE.STATIC_TEXT
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.EDIT.TEXT
\ Returns the value assigned to    TYPE.EDIT.TEXT
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.COMBO
\ Returns the value assigned to    TYPE.COMBO
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.IMAGE
\ Returns the value assigned to    TYPE.IMAGE
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.LIST
\ Returns the value assigned to    TYPE.LIST
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.LISTV
\ Returns the value assigned to    TYPE.LISTV
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.LISTVIEW
\ Returns the value assigned to    TYPE.LISTVIEW
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.RICH.EDIT
\ Returns the value assigned to    TYPE.RICH.EDIT
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.MENU.POPUP
\ Returns the value assigned to    TYPE.MENU.POPUP
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.WEB.BROWSER
\ Returns the value assigned to    TYPE.WEB.BROWSER
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.XXXX
\ Returns the value assigned to    TYPE.CONTAINER.XXXX
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.WINDOW
\ Returns the value assigned to    TYPE.CONTAINER.WINDOW
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.WINDOW.CHILD
\ Returns the value assigned to    TYPE.CONTAINER.WINDOW.CHILD
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.BOX
\ Returns the value assigned to    TYPE.CONTAINER.BOX
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.BOX.SCROLLED
\ Returns the value assigned to    TYPE.CONTAINER.BOX.SCROLLED
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.SPLIT.V
\ Returns the value assigned to    TYPE.CONTAINER.SPLIT.V
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.SPLIT.H
\ Returns the value assigned to    TYPE.CONTAINER.SPLIT.H
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.PANEL
\ Returns the value assigned to    TYPE.CONTAINER.PANEL
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.OVERLAY
\ Returns the value assigned to    TYPE.CONTAINER.OVERLAY
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.MATRIX
\ Returns the value assigned to    TYPE.CONTAINER.MATRIX
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.COL
\ Returns the value assigned to    TYPE.CONTAINER.COL
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.COL.W
\ Returns the value assigned to    TYPE.CONTAINER.COL.W
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.COL.HW
\ Returns the value assigned to    TYPE.CONTAINER.COL.HW
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.COL.H
\ Returns the value assigned to    TYPE.CONTAINER.COL.H
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.frame
\ Returns the value assigned to    TYPE.CONTAINER.FRAME
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.row
\ Returns the value assigned to    TYPE.CONTAINER.ROW
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.row.H
\ Returns the value assigned to    TYPE.CONTAINER.ROW.H
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.row.w
\ Returns the value assigned to    TYPE.CONTAINER.ROW.W
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos TYPE.CONTAINER.row.hw
\ Returns the value assigned to    TYPE.CONTAINER.ROW.HW
\ ( -- value )
\ no input parameters
\ --
\ VALUE    Value assigned

 help_pos sob@validate
\ Check whether SOB-ID represents an assigned/active Screen OBject.
\ ( sob-id -- boolean )
\ SOB-ID     Identity of target Screen OBject
\ --
\ BOOLEAN    SOB-ID is valid
\            else  0

 help_pos sob.menu>owner.drawn
\ (X -- )
\ Set an internal flag that if TRUE causes future menu items
\ to be ownerdrawn
\ X         BOOLEAN
\ --
\ No output parameters

 help_pos sob.menu>style
\ (flags -- )
\ The bit flags specified by FLAGS will be logically OR'D with
\ the default flags used in creating the next menu item
\ See Microsfoft documentation on:
\    function  = AppendMenu
\    parameter = uFlags
\ FLAGS     Bit flags
\           0x000 = default
\           0x100 = owner drawn
\ --
\ No output parameters

 help_pos sob.menu=grey.all
\ (bool, sob-id --)
\ Defines whether an entire vertical menu has ALL of its items  greyed-out or not
\ Grey menu items are not actionable
\ BOOL      = 0   menu item is NOT grey
\           else menu is grey
\ SOB-ID    identity of vertical Screen OBject menu item
\ --
\ No output parameters

 help_pos sob.menu=checks.off
\ (sob-id --)
\ Clears all the checked states in a given vertical menu.
\
\ SOB-ID    identity of Screen OBject menu item either the vertical menu owner, or
\           any of its sub-menus
\ --
\ No output parameters

 help_pos sob.menu=grey
\ (bool, sob-id --)
\ Defines whether a menu item is greyed-out or not
\ Grey menu items are not actionable
\ BOOL      = 0   menu item is NOT grey
\           else menu is grey
\ SOB-ID    identity of Screen OBject menu item
\ --
\ No output parameters

 help_pos sob.menu.bar=new
\ (sob-id -- id)
\ Creates a menubar for the display  ID
\ SOB-ID    identity of parent Screen OBject, typically a Window
\ --
\ ID        is the identity of the created horizontal menu,

 help_pos sob.menu.h=new
\ (P-ID, c-addr, u -- id)
\ SOB-ID    identity of parent Screen OBject, typically a SOB.MENU.BAR=NEW
\ C-ADDR    address of a character string holding the menu name
\ U         length of character string
\ --
\ ID        is the identity of the created horizontal menu,
\           typically passed to  sob.menu.V

 help_pos sob.popup=add
\  alias for    sob.menu.v=new

 help_pos sob.menu.v=new
\ (sob-idP, c-addr, u, xt -- sob-idV)
\ Adds a "vertical" menu item to a "horizontal" menu item
\ OR to a popup menu
\ SOB-IDP   identity of parent Screen OBject, typically a sob.menu.H
\ C-ADDR    address of a character string holding the menu name
\ U         length of character string
\ XT        eXecution Token of routine to be called on menu selection
\ --
\ SOB-IDV   identity of the created Screen OBject sob.menu.V

 help_pos sob.menu.v=bar
\ (sob-idP  -- )
\ Adds a horizontal line to a  menu
\ SOB-IDP   identity of parent Screen OBject, typically a sob.menu.H
\ --
\ no output parameters

 help_pos sob.menu=owner.drawn
\ (sob-idP  -- )
\ Set / unset the ownerdrawn state of a menu item
\ SOB-IDP   identity of target Screen OBject
\ --
\ no output parameters

 help_pos sob.menu@bar.id
\ (sob-idW -- sob-idB)
\ Returns the identity of the menu bar Screen OBject associated with a
\ given Window container,
\ SOB-IDP   identity of parent Screen OBject Window container
\ --
\ SOB-IDB   identity of the Screen OBject sob.menu.bar
\           = -1 if parent SOB has no menu bar

 help_pos sob.popup=new
\ (sob-idW -- sob-idP)
\ Create a "parent" pop up menu
\ SOB-IDW   identity of parent Screen OBject
\ --
\  SOB-IDP   is the identity of the created popup menu,

 help_pos sob.focus.on=xt
\ (xt --)
\ Set the eXecution Token of a user defined command to be executed whenever
\ the Windows Message handler receives a WM_SETFOCUS that it can not handle
\ XT       eXecution Token of user defined command, must have the stack
\          behaviour (--)
\ --
\ No output parameters

 help_pos sob.focus.off=xt
\ (xt --)
\ Set the eXecution Token of a user defined command to be executed whenever
\ the Windows Message handler receives a WM_KILLFOCUS that it can not handle
\ XT       eXecution Token of user defined command, must have the stack
\          behaviour (--)
\ --
\ No output parameters

 help_pos sob.msg=cmd.xt
\ (xt --)
\ Set the eXecution Token of a user defined command to be executed whenever
\ the Windows Message handler receives a WM_COMMAND that it can not handle
\ XT       eXecution Token of user defined command, must have the stack
\          behaviour (--)
\ --
\ No output parameters
\
\ See also   sob.msg@cmd   to obtain the message parameters

  ' dnd=add [if]
 help_pos dnd=return
\ (u -- )
\ Set the return type for a successful DROP operation
\ After handling a DROP the code must indicate whether the action was
\
\ U        Drop data type
\            1 = Copied
\            2 = Moved
\            else =  Cancelled
\ If not explicitly called, a DROP action handled via   sob.callback=xt.drop   defaults to COPIED
\ --
\ No output parameters

 help_pos dnd@type
\ (-- u )
\ Returns U that specifies the type of data being dropped
\ No input parameters
\ --
\ U        Drop data type
\          01 = simple ANSI text
\          13 = Wide character text
\          15 = a file or folder name

 help_pos dnd@pos
\ ( -- x , y )
\ Returns the position of the mouse at the time of the drop relevant to the display!
\ No input parameters
\ --
\ X           X
\ Y           Y

 help_pos dnd.drop@data
\ (i -- c-addr, u )
\ Returns the Ith element (zero based) of the DROPPED data
\ I           Drop data type
\ --
\ C-ADDR      Address of a byte array
\ U           Size of array

 help_pos dnd.drop@type
\ ( -- Boolean )
\ Returns whether the user requested a Copy or a Move
\ No input parameters
\ --
\ Boolean    0 = copy, else move

 help_pos dnd.drop@count
\ ( -- x )
\ Returns the number of elements being offered to the DROP target.
\ No input parameters
\ --
\ X          count of items being dropped

 help_pos dnd=add
\ (c-addr, u , fmt -- )
\ Adds the specified CHARACTER array to the data to be provided by a subsequent Drag and Drop operation
\ C-ADDR      Address of a CHARACTER array
\ U           Size of array in CHARACTERs
\ FMT         =1  = text,    =15 = files/folder
\ --
\ No output parameters

 help_pos dnd=drag
\ (effect -- result )
\ Triggers a  DRAG  operation
\ Only returns when the operation is terminated!
\
\ EFFECT     Indicates the type of DRAG operation allowed
\            1 = Copy
\            2 = Move
\            3 = either Copy or Move depending on state of the STRG key
\ --
\ RESULT    Indicates the type of DRAG operation executed
\            0 = Cancelled
\            1 = Copy
\            2 = Move

    [then]
   [THEN]
  ' ip=rxt [if]
 help_pos WSAStartup=open
\ (--)
\ Initialise the windows sockets code
\ No input parameters
\ --
\ No output parameters

 help_pos WSAStartup=close
\ (--)
\ Release the windows sockets code
\ No input parameters
\ --
\ No output parameters

 help_pos ip@UorT
\ (bool --)
\ Gets the current IP protocol.
\ --
\ No input parameters
\ --
\ BOOL      = 0 = False = TCP
\           else = true = UDP

 help_pos ip=UorT
\ (bool --)
\ Set the IP protocol to be used for future opened IP communications.
\ BOOL      = 0 = False = TCP
\           else = true = UDP
\ --
\ No output parameters

 help_pos ip.address=family
\ Set the protocol family to be used for network communications.
\ This command supports bypassing of the program supplied
\ communications parameters.
\ Use with care !
\ The default is AF_INET, as used for IP communications.
\ U         = -1 = AF_INET
\           else the value U will be used.
\           in MicroSoft Windows, IPv6 AF_INET6 = 23t
\ --
\ No output parameters

 help_pos ip@sys.id
\ (ip-id -- socket)
\ Return the system identity associated with IP port given by IP-ID.
\ For IP ports the system identity is a SOCKET.
\ IP-ID     Identity of target IP port
\ --
\ SOCKET    System identity associated with an opened IP port

 help_pos ip@address
\ (ip-id -- socket)
\ Return the system identity associated with IP port given by IP-ID.
\ For IP ports the system identity is a SOCKET.
\ IP-ID     Identity of target IP port
\ --
\ SOCKET    System identity associated with an opened IP port

 help_pos ip=connect
\ (ip-id -- res)
\ Request from a IP TCP client to be connected to the
\ server given by the default IP-address/port combination.
\ (Defined at ip.client.open  or overridden by ip=via)
\ If the link is synchronous then wait on a response.
\ If asynchronous then the completion will be passed
\ to the appropriate callback.
\ IP-ID      Identity of IP link
\ --
\ RES        -1 on error

 help_pos ip.open
\ (port, xt -- ip-id)
\ This is a command that supports by-passing of the interpreter.
\ Open a SOCKET to the IP PORT specified by port.
\ Use XT to define whether the link is synchronous (xt = 0 ) or
\ asynchronous ( XT = eXecution Token of a callback).
\ Return the identity of the created link.
\ PORT      The IP port address of the opened link
\ XT        = 0 = synchronous communications
\           else = asynchronous communications
\                = eXecution Token of a callback routine for error/event reports
\           XT must have the stack behaviour (ip_id--) where IP_ID is the internally
\           allocated identity of the IP link
\ --
\ IP-ID     A system allocated identity for the opened IP link.
\            = -1 = link could not be created
\                  use  LAST-ERROR for more details

 help_pos gethostaddr
\ (-- c-addr, u)
\ Return the IP address of the host machine as a character string c-addr of
\ length u characters, in IPv4       127.0.0.1  type format
\ No input parameters
\ --
\ C-ADDR    Character string identifing the destination machines IP address
\ U         Length of character string
\           = 0 on error

 help_pos gethostname
\ (-- c-addr, u)
\ Return the name of the host machine as a character string c-addr of
\ length u characters.
\ No input parameters
\ --
\ C-ADDR    Character string identifing the destination machines IP address
\ U         Length of character string
\           = 0 on error

 help_pos ip.client.open
\ (c-addr, u, port, xt -- ip-id)
\ Open the client side of a network IP link to the specified PORT, on the
\ machine with the IP address specified by the character string c-addr of
\ length u characters.
\ Use XT to define whether the link is synchronous (xt = 0 ) or
\ asynchronous ( XT = eXecution Token of a callback).
\ E.g. to open a synchronous client link to the Telnet server on machine 192.168.0.3
\       s" 192.168.0.3"   23t   0   ip.client.open
\
\ Note: Synchronous  => XT = 0
\       Synchronous means that a communications operation such as read or write
\       must be completed before control returns to the user's program.
\       Asynchronous => XT <> 0
\       Asynchronous means that such operations will (probably) return before
\       completed, and that operation completion can be signalled to a user
\       defined callback routine.
\       For UDP , XT called when a read packet is waiting, or a close occurs
\       For TCP , XT called when CONNECT request is completed
\ C-ADDR    Character string identifing the destination machines IP address
\ U         Length of character string
\ PORT      The destination port number to be accessed.
\ XT        = 0 = synchronous communications
\           else = asynchronous communications
\                = eXecution Token of a callback routine for error/event reports
\           XT must have the stack behaviour (ip_id--) where IP_ID is the internally
\           allocated identity of the client-server IP link
\ --
\ IP-ID     A system allocated identity for the opened IP link.
\            = -1 = link could not be created
\                  use  LAST-ERROR for more details

 help_pos ip=bind
\ (ip-id -- ip_id|-1)
\ Bind the IP communications port identified by the value ip-id to the
\ IP address/port supplied at the opening of the link, or by a subsequent
\ IP=VIA command.
\ Return ip-id on success, and -1 on error.
\ IP-ID     The system allocated identity for the target IP communications port.
\ --
\ Return ip-id on success, and -1 on error.

 help_pos ip=listen
\ (ip-id -- )
\ Place the IP  port identified by the value ip-id in to the
\ listening mode for client initiated communications.
\ This commmand is intended for TCP based communications.
\ IP-ID     The system allocated identity for the target IP communications port.
\ --
\ Return ip-id on success, and -1 on error.

 help_pos ip.server.open
\ (port, xt -- ip-id)
\ Open a server that handles communication that is directed to the specified PORT on
\ the current machine.
\ E.g. to open a synchronous server that handles the port 4000t
\       4000t   0   ip.server.open
\ Use XT to define whether the link is synchronous (xt = 0 ) or
\ asynchronous ( XT = eXecution Token of a callback).
\ Note: Synchronous means that a communications operation such as read or write
\       must be completed before control returns to the user's program.
\       Asynchronous means that such operations will (probably) return before
\       completed, and that operation completion can be signalled to a user
\       defined callback routine.
\ PORT      The port number to be opened.
\ XT        = 0 = synchronous communications
\           else = asynchronous communications
\                = eXecution Token of a callback routine for error/event reports
\                XT will be called when a client tries to opwn communications
\                with the server port.
\           XT must have the stack behaviour (ip_id--) where IP_ID is the internally
\           allocated identity of the client-server IP link
\ --
\ IP-ID     A system allocated identity for the opened IP link.
\           = -1 = link could not be created
\                  use command last-error to find out more details

 help_pos ip=accept
\ (port, xt -- ip-id)
\ Open a  server that handles communication that is directed to the specified PORT.
\ E.g. to open a synchronous server that handle the port 4000t
\       4000t   0   ip.server.open
\
\ Note: Synchronous means that a communications operation such as read or write
\       must be completed before control returns to the user's program.
\       Asynchronous means that such operations will (probably) return before
\       completed, and that the completion event can be signalled to a user
\       defined callback routine.
\ PORT      The port number to be opened.
\ XT        = 0 = synchronous communications
\           else = asynchronous communications
\                = eXecutution Token of a callback routine for error/event reports
\                XT will be called when a client tries to opwn communications
\                with the server port.
\           XT must have the stack behaviour (ip_id--) where IP_ID is the internally
\           allocated identity of the client-server communications link
\ --
\ IP-ID     A system allocated identity for the opened communications link.
\           = -1 = link could not be created
\                  use command last-error to find out more details

 help_pos ip=rxt
\ (xt, ip-id --)
\ Set the eXecution Token/callback to be called when the target network
\ communications port has completed an asynchronous read request.
\ XT        The eXecution Token of the callback
\           XT has the stack effect ( res -- 0 )
\           Where res = 0 is okay
\           else res = an error code.
\ IP-ID    Identity of target network communications port
\ --
\ No output parameters

 help_pos ip=wxt
\ (xt, ip-id --)
\ Set the eXecution Token/callback to be called when the target network
\ communications port has completed an asynchronous write request.
\ XT        The eXecution Token of the callback
\           XT has the stack effect ( res -- 0 )
\           Where res = 0 is okay
\           else res = an error code.
\ IP-ID    Identity of target network communications port
\ --
\ No output parameters

 help_pos ip=ext
\ (xt, ip-id --)
\ Set the eXecution Token/callback to be called when the target network
\ communications port is to report an error condition
\ XT        The eXecution Token of the callback
\           XT has the stack effect ( res -- 0 )
\           Where res = 0 is okay
\           else res = an error code.
\ IP-ID    Identity of target network communications port
\ --
\ No output parameters

 help_pos ip=close
\ (ip-id --)
\ Terminate any outstanding read and/or write operation for this
\ communications port.
\ Release any associated resources.
\ Close the communications port.
\ COM-ID    Identity of target communications port
\ --
\ No output parameters

 help_pos ip=write
\ (c-addr, u, ip-id -- -1|len)
\ Write the U bytes fron the buffer starting at address c-addr,
\ to the IP link identified by ip-id.
\ C-ADDR     Address of a buffer of data
\ U          Length of buffer
\ IP-ID      Identity of IP link
\ --
\ RES        = -1 on error
\            else = number of bytes written

 help_pos ip@via
\ (ip-id -- c-addr, u, IP-port)
\ Return the IP port and IP address from which the IP link
\ identified by ip-id last received a packet.
\ IP-ID      Identity of IP link
\ --
\ C-ADDR    Character string identifing the IP address in abc.def.ghk.lmn format
\ U         Length of character string
\ IP-port

 help_pos ip=via
\ (c-addr, u, IP-port, ip-id -- )
\ Set the IP port and IP address to which the next send packet
\ will be sent over the  IP link identified by ip-id.
\ This command only functions on UDP links
\ C-ADDR    Character string identifing the destination machines IP address
\ U         Length of character string
\ IP-port
\ IP-ID     Identity of IP link
\ --
\ No output parameters

 help_pos ip@read
\ (c-addr, u, ip-id -- -1|len)
\ Read  U bytes from the IP link identified by ip-id to
\ the buffer starting at address c-addr.
\ C-ADDR     Address of a buffer of data
\ U          Length of buffer
\ IP-ID      Identity of IP link
\ --
\ RES        = -1 on error
\            else = number of bytes read

 help_pos ip@status
\ (ip-id -- res)
\ Return a bit map showing the status of the
\ read/write and error indicators for the IP link identified by ip-id
\ IP-ID      Identity of IP link
\ --
\ RES         1 = read data read
\             2 = ready to write
\             4 = error

 help_pos gethostbyaddr
\ (ip-id -- res)
\ Return a bit map showing the status of the
\ read/write and error indicators for the IP link identified by ip-id
\ IP-ID      Identity of IP link
\ --
\ RES         1 = read data read
\             2 = ready to write
\             4 = error

  [then]
  ' app@name [if]
 help_pos app@font
\ (--   u)
\ Return the handle of the FONT used by this application
\ --
\ U         The length of the character string.

 help_pos app@name
\ (-- c-addr, u)
\ Return a character string giving the name of this application
\ No input parameters
\ --
\ C-ADDR    The character string address of file name
\ U         The length of the character string.

 help_pos exe@name
\ (-- c-addr, u)
\ Return a character string giving the filename of the
\ interpreters executable without an extension
\ No input parameters
\ --
\ C-ADDR    The character string address of file name
\ U         The length of the character string.

 help_pos invLine
\ (-- c-addr, u)
\ Return a character string giving the parameters passed to this instance
\ at invocation time.
\ No input parameters
\ --
\ C-ADDR    The character string address of file name
\ U         The length of the character string.

 help_pos system
\ (caddr, count -- return code)
\ Pass the text string to the system command interpreter
\ If  caddr  = NULL
\     return code = -1 on error
\ else
\     return code is system dependant
\ Does NOT retun until the created process has terminated
\
\ C-ADDR        The character string address of file name
\ U             The length of the character string.
\ --
\ RETURN CODE   -1 on error

 help_pos system2
\ (caddr, count -- )
\ Pass the text string to the system command interpreter
\ Does not wait for created process to terminate!
\
\ C-ADDR    The character string address of file name
\ U         The length of the character string.
\ --
\ No input parameters

 help_pos system2params
\ (paddr, pu , caddr, count -- )
\ Pass the text string to the system command interpreter
\ Does not wait for created process to terminate!
\
\ C-ADDR    The character string address of file name
\ U         The length of the character string.
\ --
\ No input parameters

 help_pos ShellExecute
\ (hwnd , c-addrOP, uOP , c-addrF, uF ,  c-addrP, uP , c-addrD, uD , U -- RetCode )
\ In a wrapper around the operating system   ShellExecute
\ Does not wait for created process to terminate!
\
\ HWND      WINDOW to be used, or 0
\ C-ADDROP  The character string address of the OPERATION to be performed
\ UOP       The length of the OPERATION character string.
\ C-ADDRF   The character string address of the FILE to be used
\ UF        The length of the FILE character string.
\ C-ADDRP   The character string address of the PARAMETERS to be used
\ UP        The length of the PARAMETERS character string.
\ C-ADDRD   The character string address of the DIRECTORY to be used
\ UD        The length of the DIRECTORY character string.
\ U         The nShowCmd value, typically 1
\ --
\ RETCODE   Return value of the   ShellExecute function

 help_pos spawn
\ (caddr, count -- bool)
\ Pass the text string to a spawned copy of this interpreter
\ C-ADDR    The character string address of file name
\ count     The length of the character string.
\ --
\ BOOLEAN   TRUE = okay
\           FALSE = error occurred

 help_pos path@invocation
\ (-- c-addr, u)
\ Returns a character string giving the pathname of the directory in which
\ the user was, when the executable file was activated
\ No input parameters
\ --
\ C-ADDR    The character string address of directory
\ U         The length of the character string.

 help_pos path@execution
\ (-- c-addr, u)
\ Returns a character string giving the pathname of the directory from which
\ the executable file was loaded
\ No input parameters
\ --
\ C-ADDR    The character string address of directory
\ U         The length of the character string.

   [THEN]
  ' cng.hash=open [if]
 help_pos murmur=file
\ (seedHigh , seedLow, c-addrI, uI, --  u32 | -1 )
\ Calculate the Murmur3_32 hash of the target file using 2 seeds.
\ The results are packed together as the HIGH LOW vaues of a single 64 bit value.
\
\ c-addr    Start address of byte array in memory holding the file name
\ u1        Length of file name
\ --
\ boolean    -1 if error
\            else a 64 bit value = HIGH LOW results packed as a single 64 bit value

    [then]
  ' random [if]
 help_pos random
\ (-- U)
\ Generate a psuedo random value between 0 and 511
\ No input parameters
\ --
\ U         value between 0 and 511

 help_pos qpc
\ (-- U)
\ The value returned by calling the operating system's QueryPerformanceCounter
\ this is a high resolution time stamp
\ To get the time difference in milli seconds between 2 calls to QPC    QPCStart and QPStop:
\      QPStop     QPCStart   -     1000t *  qpf  /
\ No input parameters
\ --
\ U         a 64 bit value

 help_pos qpF
\ (-- U)
\ The value returned by calling the operating system's QueryPerformanceFrequency.
\ To get the time difference in milli seconds between 2 calls to QPC    QPCStart and QPStop:
\      QPStop     QPCStart   -     1000t *  qpf  /
\ No input parameters
\ --
\ U         a 64 bit value

    [then]
  ' regexp [if]
 help_pos regexp
\ (-- u-wid)
\ Returns the identifier of the Forth core wordset wordlist.
\ No input parameters
\ --
\ u-wid     The identifier of the Forth core wordset wordlist
\ -1        The value -1

 help_pos regexp.replace
\ (c-addr By , u len by , c-addr Regexp , u len Regexp , c-addr Text , u len Text  -- result  )
\ Executes a REGEXP match operation on a text string.
\ C-ADDR    Address of REGEXP expression
\ U         Number of characters in REGEXP expression
\ C-ADDR    Address of text string to be examined
\ U         Number of characters in text string to be examined
\ --
\ result    The identifier of the Forth core wordset wordlist
\           on error   -11

 help_pos regexp.instr
\ (c-addr Regexp , u len Regexp , c-addr Text , u len Text  -- result  )
\ Executes a REGEXP match operation on a text string.
\ C-ADDR    Address of REGEXP expression
\ U         Number of characters in REGEXP expression
\ C-ADDR    Address of text string to be examined
\ U         Number of characters in text string to be examined
\ --
\ result
\           on error   -1

 help_pos regexp.instr.after
\ (c-addr Regexp , u len Regexp , c-addr Text , u len Text  -- result  )
\ Executes a REGEXP match operation on a text string.
\ C-ADDR    Address of REGEXP expression
\ U         Number of characters in REGEXP expression
\ C-ADDR    Address of text string to be examined
\ U         Number of characters in text string to be examined
\ --
\ result    1 based index of the first character AFTER the matched expression
\           on error   -1

  [then]
\ (-- wid )
\  create a new empty WORDLIST

 help_pos core-wordlist
\ (-- u-wid)
\ Returns the identifier of the Forth core wordset wordlist.
\ No input parameters
\ --
\ u-wid     The identifier of the Forth core wordset wordlist
\ -1        The value -1

  ' wordlist [if]
 help_pos find
\ (cs-addr -- (cs-addr, 0)|(xt, 1)|(xt, -1))
\ Search the wordlists in the current search order for the
\ definition named by the counted string CS-ADDR.
\
\ -----------------------------------------------------------------------
\ if the name starts with  "THIS."   then
\    Reduce name to the  post 'THIS." text
\    Look for the reduced name in  the compilation wordlist
\    RETURN the search results. Do not search any further!
\ continue:
\     (  Why this capability is provided:
\       It makes sense if the target defn  is in the compilation wordlist
\       AND  that wordlist is not in the search order
\       OR   target wordlist is deeper in the  search order than another wordlist with the same name
\       OR !! you want to make it visible that the target is in the NAMESPACE
\       OR !!!! inside a definition where you might want a local value with a
\               name that clashes with the NAMESPACE
\               precedence goes to the LOCAL name !
\     )
\ -----------------------------------------------------------------------
\ If in compliation mode then
\   search FIRST in the internal LOCALs wordlist
\   If found RETURN the found details
\ continue:
\ -----------------------------------------------------------------------
\ If there are one or more NAMESPACEs then
\ temporarily reduce NAME  upto the first DOT character or end of name, which ever comes first
\ Look for the reduced NAME in the internal NAMESPACES wordlist
\ RECURSIVELY
\   If found then
\      if the name is exhausted then RETURN the details of the NAME
\      make that NAMESPACE the only wordlist in the temporary search wordlist
\      extract   the next DOT delimited name part
\      find the  next dot delimited name part in the search wordlist
\ END
\ Look for the remainder of the name in the temporary search wordlist
\ if the name is exhausted then RETURN the details of the NAME
\ continue:
\ -----------------------------------------------------------------------
\ Look for the (entire) NAME in the default  search worldlist(s)
\
\ If the name is not found then return (cs-addr, 0)
\ Else
\   if the command is immediate then return (xt, 1)
\   else
\     return (xt, -1)
\ CS-ADDR   The counted string address of the name to be searched for.
\ --
\ either
\    if name not found
\ CS-ADDR   The counted string address of the name.
\ 0         The value 0
\    if found, and command is immediate
\ XT        The eXecution Token of the found command
\ 1         The value 1
\    else name found but not immediate
\ XT        The eXecution Token of the found command
\ -1        The value -1

 help_pos get-current
\ (-- u-wid)
\ Returns the identifier assigned to the wordlist that is currently
\ used to hold new definitions i.e. the compilation wordlist
\ No input parameters
\ --
\ u-wid     Identity of the compilation wordlist

 help_pos set-current
\ (u-wid --)
\ Sets the compilation wordlist, the wordlist in which new definitions
\ are to be placed, to be the wordlist with the identity u-wid
\ u-wid     Identity of the compilation wordlist
\ --
\ No output parameters

 help_pos get-order
\ (-- u-widn...u-wid1, u)
\ Returns the identifiers of all wordlists in the current search order,
\ and the number U of wordlists in the search order.
\ No input parameters
\ --
\ u-widn    Identity of the n'th wordlist in the search order
\ ...
\ u-wid1    Identity of the top wordlist in the search order
\ U         Number of wordlists in the search order

 help_pos set-order
\ (u-widn...u-wid1, n --)
\ The search order will be replaced by the wordlists with  the
\ identifiers u-widn...u-wid1. U is the number of wordlists in
\ the new search order.
\ If N = 0 then empty the search order.
\ If N = -1 the search order will be set to a system defined default.
\ u-widn    Identity of the n'th wordlist in the search order
\ ...
\ u-wid1    Identity of the top wordlist in the search order
\ N         Number of wordlists in the new search order
\ --
\ No input parameters

 help_pos search-wordlist
\ (c-addr, u, u-wid -- 0|(xt, 1)|(xt, -1))
\ Search in the wordlist identified by U-WID for the
\ definition named by the character string C-ADDR of length U
\ If the name is not found then return 0
\ Else
\   if the command is immediate then return (xt, 1)
\   else
\     return (xt, -1)
\ C-ADDR    The character string address of the name to be searched for.
\ U         The length of the character string.
\ U-WID     The identity of the wordlist to be searched
\ --
\ either
\    if name not found
\ 0         The value 0
\    if found, and command is immediate
\ XT        The eXecution Token of the found command
\ 1         The value 1
\    else name found but not immediate
\ XT        The eXecution Token of the found command
\ -1        The value -1

 help_pos wordlist
\ (-- u-wid)
\ Return the identifier assigned to a new empty wordlist
\ No input parameters
\ --
\ u-wid     Identity of the new wordlist

 help_pos %namespace
\ ( c-addr , u --)
\ Used in the form     s" space-name"   %NAMESPACE
\ Create a command header with the input string given
\ by  C-ADDR and U  as the command name.
\ Compile in code to fullfill the following RUN TIME action:
\ When SPACE-NAME is executed the current compilation worldlist
\ is added to the search wordlist.
\ SPACE-NAME is made the current compilation worldlist.
\ C-ADDR   memory address of text string
\ U        length of text string in characters
\ --
\ No output parameters

 help_pos namespace
\ (--)
\ Used in the form   NAMESPACE    SPACE-NAME
\ Parse the input line for a space  delimited string.
\ If the string is empty, then a trap to an error occurs.
\ Else
\   Create a command header with this string as the command name.
\   Add SPACE-NAME to the internal NAMESPACES wordlist.
\   Compile in code to fullfill the following RUN TIME action:
\ When SPACE-NAME is executed the current compilation wordlist
\ is added to the search wordlist.
\  SPACE-NAME is made the current compilation worldlist.
\ No input parameters
\ --
\ No output parameters

 help_pos %subspace
\ ( c-addr , u --)
\ Used in the form     s" subspace-name"   %SUBSPACE
\ Create a command header with the input string given
\ by  C-ADDR and U  as the command name.
\ Compile in code to fullfill the following RUN TIME action:
\ When SUBSPACE-NAME is executed the current compilation worldlist
\ is added to the search wordlist.
\ SUBSPACE-NAME is made the current compilation worldlist.
\ C-ADDR   memory address of text string
\ U        length of text string in characters
\ --
\ No output parameters

 help_pos subspace
\ (--)
\ Used in the form   SUBSPACE   SUBSPACE-NAME
\ Parse the input line for a space  delimited string.
\ If the string is empty, then a trap to an error occurs.
\ Else
\   Create a command header with this string as the command name.
\   Compile in code to fullfill the following RUN TIME action:
\ When SUBSPACE-NAME is executed the current compilation worldlist
\ is added to the search wordlist.
\ SUBSPACE-NAME is made the current compilation worldlist.
\ No input parameters
\ --
\ No output parameters

 help_pos closeSpace
\ (--)
\ if there is an active NameSpace or SubSpace then undo it.
\ i.e. pop the previous NameSpace/SubSpace IF there was one
\      then MOVE the current TOP of the search order to compilation wordlist
\ No input parameters
\ --
\ No output parameters

 help_pos closeSpaceS
\ (--)
\ close all NameSpaces, do the following once per active namespace
\ if there is an active NameSpace or SubSpace then undo it.
\ i.e. pop the previous NameSpace/SubSpace if there was one
\      MOVE the current TOP of the search order to compilation wordlist
\ No input parameters
\ --
\ No output parameters

 help_pos nameSpaces.wid
\ (-- wid)
\ No input parameters
\ --
\ WID     Wordlist identity of the NAMESPACES worllist

 help_pos nameSpace.wid
\ (-- wid)
\ No input parameters
\ --
\ WID     Wordlist identity of the current NAMESPACE worllist

 help_pos definitions
\ (--)
\ Make the compilation word list the same as the first wordlist
\ in the search order
\ No input parameters
\ --
\ No output parameters

  [else]
\ NO help for this definition, it is internal only if WORD  SET not included
\ (-- widn , .. , wid1  , n )
\  returns the WIDs of current search wordlists
\  and the number N of such search lists
\  wid1 is searched before wid2..widn
\ NO help for this definition, it is internal only if WORD  SET not included
\ (widn , .. , wid1  , n -- )
\  set the WIDs of current search wordlists
\  and the number N of such search lists
\  wid1 is searched before wid2..widn

\ NO help for this definition, it is internal only if WORD  SET not included
\ (-- wid )
\  returns the WID of current compilation wordlist

\ NO help for this definition, it is internal only if WORD  SET not included
\ (wid -- )
\  sets WID to be the current compilation wordlist

  [then]
  ' also [if]
 help_pos only
\ (--)
\ Set the wordlist search order and the compilation wordlist to
\ the system defaults
\ No input parameters
\ --
\ No output parameters

 help_pos also
\ (--)
\ Duplicate the top wordlist of the current search order.
\ Extends the wordlist search order from u-widn...u-wid1
\ to u-widn...u-wid1, u-wid1
\ No input parameters
\ --
\ No output parameters

 help_pos core
\ (--)
\ Add the core wordset wordlist to the top of the
\ current search order.
\ Convert the wordlist search order from u-widn...u-wid1
\ to u-widn...u-wid2, u-core-wid
\ Where u-core-wid is the wordlist identifier of the core wordset.
\ No input parameters
\ --
\ No output parameters

 help_pos previous
\ (--)
\ Discard the top wordlist of the current search order.
\ Convert the wordlist search order from u-widn...u-wid2, u-wid1
\ to u-widn...u-wid2
\ No input parameters
\ --
\ No output parameters

 help_pos order
\ (--)
\ Display the wordlist identifiers for the current search order
\ starting with the top wordlist.
\ No input parameters
\ --
\ No output parameters

  [then]
  ' wid-words  [if]
 help_pos wid-words
\  (wid --)
\  Display the definitions in the wordlist identified by  WID.
\  Used as :  wid WORDS
\              will display all definitions in the  WID  wordlist
\ WID       Identified of the target worldlist.(Obtained when wordlist was created)
\ --
\ No output parameters

 help_pos words**
\ (--)
\ Used to display the names of the definitions that are in the
\ top wordlist of the current search order wordlist.
\ Parse the current input area for a space delimited string. Search all
\ the wordlists in the search order for names thatinclude the parsed
\ string, and display those names.
\ If the parsed string is empty then display all the names in all the
\ top wordlist of the current search order wordlist
\ Used in the form WORDS* <enter>
\   The command will display all the names.
\ Use in the form WORDS*  xyz
\   The command will only display names that, in this example,
\   include the character string xyz
\ No input parameters
\ --
\ No output parameters

 help_pos xt-wid-words*
\ (xt, wid  --)
\ Used in the form    ' cmd  core-wordlist  xt-wid-words* xyz
\ The command CMD must have the the stack effect (lfa --)
\ Parse the current input area for a space delimited string.
\ Search the wordlist WID for definition names that include the parsed
\ string, pass their Link Field Address to the command with the
\ eXecution Token XT.
\ If the parsed string is empty then pass all the Link Field Addresses
\ found in the wordlist, to the command with the eXecution Token XT.
\ XT        The eXecution Token of a command with the stack effect (lfa --)
\ WID       The identity of the target wordlist
\ --
\ No output parameters

 help_pos wid-words*
\ (wid--)
\ Used to display the names of the definitions that are in the
\ wordlist identified by wid.
\ Parse the current input area for a space delimited string. Search all
\ the wordlists in the search order for names thatinclude the parsed
\ string, and display those names.
\ If the parsed string is empty then display all the names in all the
\ wordlists in the wordlist wid.
\ Used in the form WID-WORDS* <enter>
\   The command will display all the names.
\ Use in the form WID-WORDS*  xyz
\   The command will only display names that, in this example,
\   include the character string xyz
\ No input parameters
\ --
\ No output parameters

 help_pos words*
\ (--)
\ Used to display the names of the definitions that are in the
\ top wordlist of the current search order wordlist.
\ Parse the current input area for a space delimited string. Search all
\ the wordlists in the search order for names thatinclude the parsed
\ string, and display those names.
\ If the parsed string is empty then display all the names in all the
\ top wordlist of the current search order wordlist
\ Used in the form WORDS* <enter>
\   The command will display all the names.
\ Use in the form WORDS*  xyz
\   The command will only display names that, in this example,
\   include the character string xyz
\ No input parameters
\ --
\ No output parameters

  [then]
  ' SQL [if]
 help_pos sql>SafeArray
\ ( asTextFlag , useRows,  RESPTR , pSA -- ERROR Code  )
\ Assuming:
\   that RESPTR is the response from a DB query
\   and that  pSA is a 2 dimensional Safearray of VARIANTS , big enough to hold the DB query results
\ then copy  the DB query results to the Safarray.
\ You can force ALL the results to be copied as TEX
\
\ asTextFlag    = True forces all Safearray VALUES to be converted to text
\ useRows       NBR ROWS to be handled
\ pSA           ptr to SAFEARRAY
\ RESPTR        Pointer to the  DB  query response
\ --
\ ERROR Code    0 if no error
\               else an error occurred
\

 help_pos  SafeArray>SQL
\ ( R8XT,  c-addr, u , dbConPtr , pSA  -- ROWCNT , ERROR Code  )
\ Sends the content of a SAFEARRAY, holding a 2 dim array of VARIANTS, to an SQL table.
\ Difficult to explain!
\ 1) Assume you have a SAFEARRAY holding a 2 dim array of VARIANTS.
\    (e.g. data read from  some rows/cols of an Excel sheet)
\ 2) For each ROW this command will , format the appropriate data in to an SQLite INSERT INTO command
\    and execute it (assumes a DB table already exists with the appropriate columns)
\ 3) The target table must already exist
\ 4) You must provide a non-terminated INSERT  template as a string
\    e.g.   " Insert into main.mytable (column list)  values ("
\    The  (column list)   can be omitted if the table and SafeArry have the same number of columns
\    in the same sequence.
\ 5) for each row in the Safearray the Insert template will be filled/terminated and sent to the SQL engine
\ 6) IF wanted, a R8 floating value in a  Safearray cell can be passed to a user defined command
\    to handle custom formating. Command must have the stack behaviour ( floatingValue -- c-addr, u )
\
\ Do this for not more than    NBR ROWS.
\ The SAFEARRAY must have been dimensioned to be large enough to contain
\      NBR ROWS  *   number of columns in the SQL Query response.
\
\ R8XT          eXecuTion token for a Callback for a R8 to text conversion
\ C-ADDR        address of character string for the INSERT template
\ U             number of characters in INSERT template
\ PSA           ptr to SAFEARRAY
\ DBCONPTR      Connection pointer for the traget table's  DB
\ --
\ ROWCNT        Number of handled rows
\ ERROR Code    0 if no error
\               else an error occurred
\

 help_pos listview>csv
\ ( QuoteFlag , ExportMask , HWND ,  delimchar , fileId  -- boolean  )
\ Send the contents of the LISTVIEW   given by HWND
\ to the UTF8 file identified by FILEID
\ Used in the form:
\  \ create an empty  memory   database
\  s" :memory:"  sql.db=open  value dbConPtr
\
\  \ create and populate a table
\  s" create table family   ( Role text , Age int, Id TEXT , Pic BLOB )"   dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Father', 42,  0123  , NULL)"     dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Mother', 41, 4.5  , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Daughter', 4, 000 , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Son', 14, -1 , NULL)"            dbConPtr  sql.db=command   drop
\  s" insert into family (role, age) values ( 'Grandfather', 70)"   dbConPtr  sql.db=command   drop
\
\  s" select * from family"   dbConPtr  sql.db=query  value myStmtRepPtr
\  \  create a WINDOW
\  s" Test SQL>Listview command"  sob.window=new  VALUE testWindow
\  \ add a LISTVIEW
\  10  s"                                      "   0   sob.listview=new  value si-listview
\
\  1  \ TopRowColsFlag
\  1  \ ColNbrsFlag
\  1  \ RowNbrsFlag
\  1  \ HeaderFlag
\  si-listview sob@sys.id   \  HWND of LISTVIEW
\  myStmtRepPtr
\  sql>listview   \ display the QUERY result to the LISTVIEW
\  ." Nbr columns " dup  value  nbrCOls .dec cr
\  ." Nbr rows    " .dec cr
\  value ColTypePtr
\
\    myStmtRepPtr  sql.finalize  ." sqlite3_finalize result code " .hex cr
\
\   \  create an empty file to hold the query result as  CSV
\   s" family.csv"
\   w/o
\   file=open  drop value  fileId    \ have ignored error handling !
\
\ 1      \ QuoteFlag    a BOOLEAN value, IF non-zero then text will be enclosed inside a pair of double quotes
\ 3      \ ExportMask   defines what type of information is to be exported
\        \      0x01   Header
\        \      0x02   Data
\        \      0x03   header + data
\ si-listview sob@sys.id \         System identity of the source LISTVIEW ( if a Screen OBject use: sobId sob@sys.id )
\ char :   \  DELIMCHAR Character value to be used the CSV delimiter
\ fileId
\   LISTVIEW>CSV
\ ." written row count " .dec cr
\   fileId  file=close  drop

 help_pos LISTVIEW.SELECTION>CSV
\ ( QuoteFlag , ExportMask , HWND ,  delimchar , fileId  -- boolean  )
\ Send the contents of the LISTVIEW   given by HWND
\ to the UTF8 formated CSV file identified by FILEID
\ Used in the form:
\  \ create an empty  memory   database
\  s" :memory:"  sql.db=open  value dbConPtr
\
\  \ create and populate a table
\  s" create table family   ( Role text , Age int, Id TEXT , Pic BLOB )"   dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Father', 42,  0123  , NULL)"     dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Mother', 41, 4.5  , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Daughter', 4, 000 , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Son', 14, -1 , NULL)"            dbConPtr  sql.db=command   drop
\  s" insert into family (role, age) values ( 'Grandfather', 70)"   dbConPtr  sql.db=command   drop
\
\  s" select * from family"   dbConPtr  sql.db=query  value myStmtRepPtr
\  \  create a WINDOW
\  s" Test SQL>Listview command"  sob.window=new  VALUE testWindow
\  \ add a LISTVIEW
\  10  s"                                      "   0   sob.listview=new  value si-listview
\
\  1  \ TopRowColsFlag
\  1  \ ColNbrsFlag
\  1  \ RowNbrsFlag
\  1  \ HeaderFlag
\  si-listview sob@sys.id   \  HWND of LISTVIEW
\  myStmtRepPtr
\  sql>listview   \ display the QUERY result to the LISTVIEW
\  ." Nbr columns " dup  value  nbrCOls .dec cr
\  ." Nbr rows    " .dec cr
\  value ColTypePtr
\
\    myStmtRepPtr  sql.finalize  ." sqlite3_finalize result code " .hex cr
\
\   \ Following are only relevant if testing a
\    \  LISTVIEW.SELECTION >CSV  and not   LISTVIEW>CSV
\     1   si-listview   sob.item=sel
\     3   si-listview   sob.item=sel
\
\   \  create an empty file to hold the query result as  CSV
\   s" family.csv"
\   w/o
\   file=open  drop value  fileId    \ have ignored error handling !
\
\ 1      \ QuoteFlag    a BOOLEAN value, IF non-zero then text will be enclosed inside a pair of double quotes
\ 3      \ ExportMask   defines what type of information is to be exported
\        \      0x01   Header
\        \      0x02   Data
\        \      0x03   header + data
\ si-listview sob@sys.id \         System identity of the source LISTVIEW ( if a Screen OBject use: sobId sob@sys.id )
\ char :   \  DELIMCHAR Character value to be used the CSV delimiter
\ fileId
\   LISTVIEW.SELECTION>CSV
\ ." written row count " .dec cr
\   fileId  file=close  drop
\

 help_pos sql>csv
\ ( QuoteFlag , ExportMask , ptr to colTypeBuffer , delimchar , fileId , RESPTR -- nbr rows, nbr columns  )
\ Send the results of a database query to a (already opened) file (in UTF format).
\ Used in the form:
\   \ create an empty  memory   database
\   s" :memory:"  sql.db=open  value dbConPtr
\
\   \ create and populate a table
\   s" create table family   ( Role text , Age int, Id TEXT , Pic BLOB )"   dbConPtr  sql.db=command   drop
\   s" insert into family values ( 'Father', 42,  0123  , NULL)"     dbConPtr  sql.db=command   drop
\   s" insert into family values ( 'Mother', 41, 4.5  , NULL)"       dbConPtr  sql.db=command   drop
\   s" insert into family values ( 'Daughter', 4, 000 , NULL)"       dbConPtr  sql.db=command   drop
\   s" insert into family values ( 'Son', 14, -1 , NULL)"            dbConPtr  sql.db=command   drop
\   s" insert into family (role, age) values ( 'Grandfather', 70)"   dbConPtr  sql.db=command   drop
\
\   \ prepare a query on the table
\   s" select * from family"   dbConPtr  sql.db=query  value myStmtRepPtr
\
\   \  create an empty file to hold the query result as  CSV
\   s" family.csv"
\   w/o
\   file=open  drop value  fileId    \ have ignored error handling !
\
\   1  \ QuoteFlag
\   3  \ ExportMask
\   pad \ a BYTE array that will be filled in with the QUERY rersponse column types
\   char "   \  delimiter to be used in the CSV
\   fileId
\   myStmtRepPtr
\   sql>csv       \ send  QUERY results to the file
\   ." Nbr columns " dup value  nbrCOls    .dec cr
\   ." Nbr rows    " .dec cr
\
\     myStmtRepPtr  sql.finalize  ." sqlite3_finalize result code " .hex cr
\
\   fileId  file=close  drop
\
\ : show-col-types
\   pad
\    ." Column types:" cr
\    BEGIN
\     nbrCOls
\     WHILE
\       dup @byte
\       CASE
\         1 OF ." Integer "   ENDOF
\         2 OF ." Float "   ENDOF
\         3 OF ." Text "   ENDOF
\         4 OF ." Blob "   ENDOF
\         5 OF ." NULL "   ENDOF
\         ." Unknown " default .dec
\       ENDCASE
\       cr
\       1 +
\       nbrCOls 1 - to nbrCOls
\  repeat
\  drop
\  ;
\  show-col-types
\
\ QuoteFlag    a BOOLEAN value, IF non-zero then text will be enclosed inside a pair of double quotes
\ ExportMask   defines what type of information is to be exported
\              0x01   Header
\              0x02   Data
\              0x03   header + data
\ colTypeBuffer  ptr to a byte array [2048] that WILL BE filled by   sql>csv to
\           identify the query response's COLUMN types.
\ DELIMCHAR Character value to be used the delimiter
\ FILEID    File Id of the already opened CSV file
\ RESPTR    Pointer to the already obtained query response
\ --
\ RESPTR    Pointer to the query response
\

 help_pos sql>listview
\ ( TopRowColsFlag, ColNbrsFlag, RowNbrsFlag , HeaderFlag , hwnd , RESPTR -- ptr to col type array, nbr rows, nbr columns  )
\ Send the results of a SQLite database query to a user specified LISTVIEW Screen OBject
\ Used in the form:
\  \ create an empty  memory   database
\  s" :memory:"  sql.db=open  value dbConPtr
\
\  \ create and populate a table
\  s" create table family   ( Role text , Age int, Id TEXT , Pic BLOB )"   dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Father', 42,  0123  , NULL)"     dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Mother', 41, 4.5  , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Daughter', 4, 000 , NULL)"       dbConPtr  sql.db=command   drop
\  s" insert into family values ( 'Son', 14, -1 , NULL)"            dbConPtr  sql.db=command   drop
\  s" insert into family (role, age) values ( 'Grandfather', 70)"   dbConPtr  sql.db=command   drop
\
\  s" select * from family"   dbConPtr  sql.db=query  value myStmtRepPtr
\  \  create a WINDOW
\  s" Test SQL>Listview command"  sob.window=new  VALUE testWindow
\  \ add a LISTVIEW
\  10  s"                                      "   0   sob.listview=new  value si-listview
\
\  1  \ TopRowColsFlag
\  1  \ ColNbrsFlag
\  1  \ RowNbrsFlag
\  1  \ HeaderFlag
\  si-listview sob@sys.id   \  HWND of LISTVIEW
\  myStmtRepPtr
\  sql>listview   \ display the QUERY result to the LISTVIEW
\  ." Nbr columns " dup  value  nbrCOls .dec cr
\  ." Nbr rows    " .dec cr
\  value ColTypePtr
\
\    myStmtRepPtr  sql.finalize  ." sqlite3_finalize result code " .hex cr
\
\   : show-col-types
\    ." Column types:" cr
\   ColTypePtr
\    BEGIN
\     nbrCOls
\     WHILE
\       dup @byte
\       CASE
\        1 OF ." Integer "   ENDOF
\         2 OF ." Float "   ENDOF
\         3 OF ." Text "   ENDOF
\         4 OF ." Blob "   ENDOF
\         5 OF ." NULL "   ENDOF
\         ." Unknown " default .dec
\       ENDCASE
\       cr
\       1 +
\       nbrCOls 1 - to nbrCOls
\  repeat
\  drop
\  ;
\  show-col-types
\
\ TopRowColsFlag   if TRUE then first ROW of the LISTVIEW is a duplicate of the HEADERS row
\ ColNbrsFlag      if TRUE then the HEADER of the LISTVIEW includes a 0-based column index
\ RowNbrsFlag      if TRUE then the first COLUMN of the LISTVIEW is a 0-based row index
\ HeaderFlag       if TRUE then the LISTVIEW has a HEADER row (of DB column names)
\ hwnd             HWND handle of the target LISTVIEW
\ RESPTR    Pointer to the query response
\ --
\ RESPTR    Pointer to the query response
\

 help_pos CSV(UTF)>sql
\ ( CreateOrAppendFlag ,PassOverLeadingLines, DefaultDelimChar ,  max rows ,ptr to Table name (UTF) , length Table name in characters FileId,  SQL-Connection ,   XT (CHAR) reporter , XT (UTF) reporter ---  read lines, columns per line , errorCode  )
\ Read an UTF encoded CVS text file to a SQLite table.
\ The destination SQLite table is user defined, and can either be created, or appended to (must have same number of columns as CSF file)
\     \ create an empty  memory   database
\     s" :memory:"  sql.db=open  value dbConPtr
\
\     s" family.csv"
\     r/o
\     file=open  drop value  fileId
\
\  1     \     CreateOrAppendFlag    0= append to EXISTING DB taable, else create DB table
\  0     \      PassOverLeadingLines  0=  all lines will be read, else specified number of leading lines are ignored
\  0     \      DefaultDelimChar      0=  attempt to discover the delimiter character, else use the specified  UTF value
\ -1     \      max rows             -1=  all
\ s" family" s">utf8"   \     Table name  (c-addr, u )        UTF character string = name of table to be created
\ fileId     \  FileId               of already opend input CSV file
\ 0
\ 0
\  CSV(UTF)>sql
\  ." error code " .hex cr
\  ." Colums per line "  .dec cr
\  ." lines read in " .dec cr
\
\  \ check results
\     s" select * from family"   dbConPtr  sql.db=query  value myStmtRepPtr
\
\    \  create a WINDOW
\    s" Test SQL>Listview command"  sob.window=new  VALUE testWindow
\   '  bye   testWindow  sob.callback=xt1
\
\    \ add a LISTVIEW
\    10  s"                                      "   0   sob.listview=new  value si-listview
\
\    1  \ TopRowColsFlag
\    1  \ ColNbrsFlag
\    1  \ RowNbrsFlag
\    1  \ HeaderFlag
\    si-listview sob@sys.id   \  HWND of LISTVIEW
\    myStmtRepPtr
\    sql>listview   \ display the QUERY result to the LISTVIEW
\    ." Nbr columns " dup  value  nbrCOls .dec cr
\    ." Nbr rows    " .dec cr
\    value ColTypePtr
\
\ CreateOrAppendFlag    0= append to EXISTING DB table, else create DB table
\ PassOverLeadingLines  0=  all lines will be read, else specified number of leading lines are ignored. Usefull to pass-over HEADER line if APPENDING to a table
\ DefaultDelimChar      0=  attempt to discover the delimiter character, else use the specified  UTF value
\ max rows             depreceated, any numerical value
\ ptr to Table name as a UTF character string = name of table to be created
\ length Table name in characters
\ FileId               of already opend input CSV file
\ RESPTR               Pointer to the already obtained query response
\  XT (CHAR) reporter  0= nothing, else an eXecuTion address to be called   if an error occurs  ( wc-addr, u --  )
\  XT (UTF) reporter   0= nothing, else an eXecuTion address to be called   if an error occurs  ( wutf8-addr, u --  )
\ RESPTR    Pointer to the query response
\ --
\ RESPTR    Pointer to the query response
\

 help_pos FILELIST>SQL
\ (  recurseLevel, f-addr, fu , s-addr, su, dbConPtr --   )
\ Scans a section of a  file-system and writes related data to a database table.
\ recurseLevel     -1=all, 0=none, else      = max nbr of folder levels
\ f-addr, fu       Character address & length: filter specification:
\                  e.g.   s" *jpg" = jpg files only
\                         s" s*" = filename must start with a "s"
\ s-addr, su       Character address & length: starting point for the file system scan
\                  e.g.   s" C:\Users\me\Desktop"
\                  IF this is a FOLDER name  AND is terminated by a \  then recursion is POSSIBLE
\ dbConPtr         identifies the DB to be used
\ --
\ no output parameters
\
\ Used in the form:
\
\   \ create an empty  memory   database
\    s" :memory:"  sql.db = open  value dbConPtr
\
\ -1                   \ recurse level: -1=all, 0=none, else  X= max nbr of folder levels
\ s" *"                \ filter specification:e.g.   s" *jpg" = jpg files only,  s" s*" = filename must start with a "s"
\
\ app@cwd              \ starting point in file system
\                      \ IF is a FOLDER name  AND is terminated by a \  then recursion is POSSIBLE
\ s" main.myFileList"  \ name of table, will be deleted if already exists!
\ dbConPtr             \ identifies the DB to be used
\ FILELIST > SQL
\
\ \ following is to make the results visible in this "demo"
\
\ s" select * from main.myFileList" dbConPtr  sql.db = query  value myStmtRepPtr
\
\    \  create a WINDOW
\    s" Test SQL>Listview command"  sob.window = new  VALUE testWindow
\    \ add a LISTVIEW
\    10  s"                                      "   0   sob.listview = new  value si - listview
\    1  \ TopRowColsFlag
\    1  \ ColNbrsFlag
\    1  \ RowNbrsFlag
\    1  \ HeaderFlag
\    si - listview sob@sys.id   \  HWND of LISTVIEW
\    myStmtRepPtr
\    sql > listview   \ display the QUERY result to the LISTVIEW
\    ." Nbr columns " dup  value  nbrCOls.dec cr
\    ." Nbr rows    ".dec cr
\    value ColTypePtr
\
\      myStmtRepPtr  sql.finalize  ." sqlite3_finalize result code ".hex cr
\ --
\ No output parameters

  [then]
  ' SQL [IF]
 help_pos sql.db@hash.schema
\ (c-addrH, uH, c-addrS, uS  , conPtr --  c-addrH, uH)
\ If the DB schema given by  C-ADDRS, US  exists in the specified database connection,
\ then do a checksum over that schema and it's user tables
\ Additionally a user specified HASH SEED is applied!
\
\ C-ADDRH   address of a text string containing a hash seed
\ UH        length of text string in bytes
\ C-ADDRS   address of a text string containing target database schema to be  hashed
\ US        length of text string in bytes
\ CONPTR    connection ptr of database
\ --
\ C-ADDRH   address of a text string containing HASH result
\ UH        length of text string in bytes
\           = 0 on error, in which case C-ADDRH = ptr to \0 terminated error text

 help_pos sql.db@hash
\ ( conptr  --  c-addrH, uH)
\ Do a checksum over   ALL the   schema and  user tables in the specified database connection.
\ This does NOT apply a HASH SEED.
\ Only if ALL checks are passed, then return   0, else a failure code RES
\ C-ADDRF   address of a text string containing target database file to be  hashed
\ UF        length of text string in bytes
\ --
\ C-ADDRH   address of a text string containing HASH of target database file
\ UH        length of text string in bytes  = 0 on error

 help_pos sql.file.changed
\ (c-addr, u  --  boolean)
\ If the file name given by  C-ADDR, U  contains a SQL database, possible appended,
\ then run checks to determine if the file has been altered since it was created.
\ Only if ALL checks are passed, then return  0 , else a failure code RES
\ C-ADDR    address of a text string
\ U         length of text string in bytes
\ --
\ RES       0 ALL checks passed
\           -1 not a DB
\           -2 could not open an memory DB
\           -3 could not copy the target DB to memory DB
\           -4 could not find the DB magic checksum.
\           -5 invalid magic checksum length
\           -6 could not prepare DB for a checksum recalculation
\           -7   ditto
\           -8 recalculated checksum has incorrect length
\           -9 recalculated checksum not same as original checksum
\           -10 could not reset DB after checking
\           -11  ditto

  [then]
  ' SQL [if]
 help_pos sql:extension:eval
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension EVAL   from
\    https://sqlite.org/src/file?name=ext/misc/eval.c&ci=tip
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:fileio
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension FILEIO   from
\    https://sqlite.org/src/file?name=ext/misc/fileio.c&ci=tip
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:fileutilities
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension FILEIUTILITIES  from
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:define
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension DEFINE part from the
\    https://github.com/nalgeon/sqlean SQLITE loadable extension package.
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:regexp
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension REGEXP   from
\    https://sqlite.org/src/file?name=ext/misc/regexp.c&ci=tip
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:popcount
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension POPCOUNT
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:csv
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension CSV   from
\    https://sqlite.org/src/file?name=ext/misc/csv.c&ci=tip
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:extension:bk64tree
\ ( bool , sqlConnection --  )
\ Enable (true) or disable (false) the SQLITE loadable extension bk64tree
\ Takes effect when the NEXT database is created.
\ BOOLEAN   0 = disable, else = enable
\ SQL-CONNECTION  if  NEQU 0  AND if BOOLEAN = TRUE, load extension immediately
\ --
\ no output parameter

 help_pos sql:file.check
\ (c-addr, u  --  -1 | 0 | 1 | 2)
\ Checks if the file name given by  C-ADDR, U  appears to contain a SQL database
\ C-ADDR    address of a text string
\ U         length of text string in bytes
\ --
\ RES       0 file does not exist
\           -1 not a database
\           1  "normal" database
\           2  database is "appended" to some other leading file content

 help_pos sql:bind.double
\ ( Float , index ,  stmtPtr -- resptr|0)
\ Provide an 8 Byte floating point value  R8  to replace the literal INDEX ( 1-based)
\ in the prepared SQL statement pointed at by   STMTPTR
\ FLOAT     8 byte floating point value
\ INDEX     1-based index of the target literal
\ STMTPTR   Pointer to a prepared SQL statement
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:bind.int
\ ( int , index ,  stmtPtr -- resptr|0)
\ Provide an INTEGER  INT  to replace the literal number INDEX ( 1-based)
\ in the prepared SQL statement pointed at by   STMTPTR
\ INT       integer value
\ INDEX     1-based index of the target literal
\ STMTPTR   Pointer to a prepared SQL statement
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:bind.utf16
\ (c-addr, u , index ,  stmtPtr -- resptr|0)
\ Provide a text string C-ADDR, U  to replace the literal number INDEX ( 1-based)
\ in the prepared SQL statement pointed at by   STMTPTR
\ C-ADDR    address of a text string
\ U         length of text string in bytes
\ INDEX     1-based index of the target literal
\ STMTPTR   Pointer to a prepared SQL statement
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql@version
\  (  --  caddr, u)
\ Returns a character string giving the version of the embedded SQLite database engine.
\ No input parameters
\ --
\ C-ADDR    address of a character string
\ U         length of character string

 help_pos sql:query@columns
\  (  -- u )
\ Returns the number of columns in the last query.
\ Even if the query had no rows, this value will be set.
\ no input paramater
\ --
\ U         number of columns

 help_pos sql:step
\  (resptr -- int)
\ A wrapper around the SQLite    sqlite3_step   function
\ RESPTR        Pointer to the query response
\ --
\ INT           Response from the function

 help_pos sql:column_count
\  (stmtPtr -- int)
\ Number of columns in the result set returned by the prepared statement  pointed at by stmtPtr
\ STMTPTR   Pointer to a prepared SQL statement
\ --
\ INT    number of COLUMNS in statment response

 help_pos sql:interrupt
\  ( -- )
\  If the SQLite database engine is running a query that takes too long
\  you can try to terminate that query with this command.
\
\ No input parameters
\ --
\ No output parameters

 help_pos sql:blob=mem
\ ( resptr  ,c-addrD, uD,c-addrT, uT,c-addrC, uC,  Rowid,  c-addrM  uM, --     (c-addrE , uE) |  0  )
\ Associate the memory area of length U bytes, with the parameter
\ specified by ID in the  row ROWID of the query result identified by RESPTR.
\ RESPTR        Pointer to the query response
\ C-ADDRD       address of a character string containing the name of the target database/schema
\ UD            length of character string
\ C-ADDRT       address of a character string containing the name of the target table
\ UT            length of character string
\ C-ADDRC       address of a character string containing the name of the target column
\ UC            length of character string
\ ROWID         RowId of the target row
\ C-ADDRM       address of a BLOB in memory
\ UM            length of BLOB in bytes
\ --
\ C-ADDRE       address of a character string containing the error description text
\ UE            length of character string
\    OR
\ 0             = 0 if no error

 help_pos sql:extension:load.state=
\  (conptr,state  -- boolean)
\ Enables/Disables the SQLite load extension functionality
\ CONPTR    Pointer to a Connection data structure.
\ STATE     boolean
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql:db:copy.schema.to.schema
\  (conptr , c-addrF, uF , c-addrA, uA   -- boolean)
\ Saves an in-memory database to a disk file
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDRS   address of a character string - schema name of SOURCE database
\ US        length of character string
\ C-ADDRD   address of a character string - schema name of DESTINATION database
\ UD        length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql:db:copy.file.to.schema
\  (conptr , c-addrF, uF , c-addrA, uA   -- boolean)
\ Loads a disk based database given by c-addrF, uF
\ to the schema given by c-addrA, uA
\ of the database(s) in the connection given by CONPTR
\ If disk file does not exist then an errror occurs.
\ Works with normal  and APPENDED  database files
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDRF   address of a character string - file name of disk database
\ UF        length of character string
\ C-ADDRA   address of a character string - schema name of DESTINATION database
\ UA        length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql:db:copy.main.to.file
\  (conptr , c-addrF, uF -- boolean)
\ Saves the database with the schema  "main"
\ of the database(s) in the connection given by CONPTR
\ to the disk file given by c-addrF, uF
\ If disk file does not exist then an errror occurs.
\ Works with normal  and APPENDED  database files
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDRF   address of a character string - Name of DB disk file to be created
\ UF        length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

\ help_pos sql:db:copy.file.to.main
\  (CONPTR , c-addr, u -- boolean)
\ Loads an disk based Database to the schema "main" in the specified CONPTR
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDR    address of a character string - Name of DB disk file to be copied to memory
\ U         length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql:memory=save.append
\  (conptr , c-addr, u -- boolean)
\ Saves an in-memory database to a Database that is appended to the disk file
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDR    address of a character string - Name of DB disk file to be created
\ U         length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql:memory=load.append
\  (CONPTR , c-addr, u -- boolean)
\ Loads a Database that is appended to a disk based file to in-memory
\ CONPTR    Pointer to a Connection data structure.
\ C-ADDR    address of a character string - Name of DB disk file to be copied to memory
\ U         length of character string
\ --
\ BOOLEAN   Success = true, else FALSE

 help_pos sql@error
\  ( conptr -- c-addr, u)
\ Returns a text description of the last SQL error
\ No input parameters
\ --
\ C-ADDR    address of a character string
\ U         length of character string

 help_pos sql@error.utf
\  ( conptr -- c-addr, u)
\ Returns a text description of the last SQL error
\ No input parameters
\ --
\ C-ADDR    address of a character string
\ U         length of character string

 help_pos sql:text>identifier
\  (c-addri, ui -- c-addro, uo )
\ Ensures that each char "  in the text is converted to ""
\ It also ENCAPSULATES the identifier between 2  "
\ This is because the single " has a special meaning in SQL
\ C-ADDRI   address of a character string
\ UI        length of character string
\ --
\ C-ADDRO   address of a character string
\ UO        length of character string

 help_pos sql:text>string
\  (c-addri, ui -- c-addro, uo )
\ Ensures that each char '  in the text is converted to ''
\ It also ENCAPSULATES the string between 2  '
\ This is because the single ' has a special meaning in SQL
\ C-ADDRI   address of a character string
\ UI        length of character string
\ --
\ C-ADDRO   address of a character string
\ UO        length of character string

 help_pos sql:text=correct
\  (c-addri, ui -- c-addro, uo )
\ Ensures that each char '  in the text is converted to ''
\ This is because the single ' has a special meaning in SQL
\ C-ADDRI   address of a character string
\ UI        length of character string
\ --
\ C-ADDRO   address of a character string
\ UO        length of character string

 help_pos SQL
\ (--)
\ Simply a DEFN to check that the SQL words are available
\ No input parameters
\ --
\ No output parameters

\ help_pos sql:db:open
\ (c-addr, u  -- conptr|0)
\ Open a connection to the SQLITE database file identified by the character string
\ If the SQLITE database file does not exist it will be created.
\
\ C-ADDR    address of a character string - Name of DB file to be opened
\ U         length of character string
\ --
\ CONPTR    Pointer to a Connection data structure.
\           Always return the pointer using    sql.db=close
\           0  on error

 help_pos sql:db:open
\ (c-addr, u  -- conptr|0)
\ Open a connection to the SQLITE database file identified by the character string
\ If the SQLITE database file does not exist it will be created.
\
\ C-ADDR    address of a character string - Name of DB file to be opened
\ U         length of character string
\ --
\ CONPTR    Pointer to a Connection data structure.
\           Always return the pointer using    sql.db=close
\           0  on error

 help_pos sql:db:close
\ (conptr  -- )
\ Close the connection to a SQLITE database
\ CONPTR Pointer to a Connection data structure.
\ --
\ No output parameters

 help_pos sql:db:query.utf
\ (c-addr, u , conptr -- resptr|0)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ B-ADDR    address of a UTF string - the QUERY text
\ U         length of UTF string in bytes
\ CONPTR    Pointer to a Connection data structure.
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:db:query
\ (c-addr, u , conptr -- resptr|0)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ C-ADDR    address of a character string - the QUERY text
\ U         length of character string
\ CONPTR    Pointer to a Connection data structure.
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:db:query.bstr
\ ( bstrV  , conptr -- resptr|0)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ bstrVAR   the  QUERY text held as a BSTR
\ CONPTR    Pointer to a Connection data structure.
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:db:query.variant
\ ( bstrVAR , conptr -- resptr|0)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ bstrVAR   the  QUERY text held as a BSTR inside a VARIANT
\ CONPTR    Pointer to a Connection data structure.
\ --
\ RESPTR    Pointer to the query response
\           0 if failure

 help_pos sql:transaction=begin
\ (conptr -- boo)
\ Start a database transaction.
\ CONPTR    Pointer to a Connection data structure.
\ --
\ BOOLEAN   TRUE if okay, else FALSE

 help_pos sql:transaction=end
\ (conptr -- boo)
\ Stop a database transaction.
\ CONPTR    Pointer to a Connection data structure.
\ --
\ BOOLEAN   TRUE if okay, else FALSE

 help_pos sql:prepare.utf8
\ (c-addr, u , conptr -- ptr SQL statement)
\ Prepare a query string for the database identified by the Connection Pointer CONPTR.
\ C-ADDR    address of a UTF string - the QUERY string
\ U         length of UTF string in bytes
\ CONPTR    Pointer to a Connection data structure.
\ --
\ PTR SQL statement      = 0 if failure
\           else is a pointer to the prepared SQL statement

 help_pos sql:prepare.utf16
\ (c-addr, u , conptr -- ptr SQL statement)
\ Prepare a query string for the database identified by the Connection Pointer CONPTR.
\ C-ADDR    address of a text string - the QUERY string
\ U         length of text string in bytes
\ CONPTR    Pointer to a Connection data structure.
\ --
\ PTR SQL statement      = 0 if failure
\           else is a pointer to the prepared SQL statement

 help_pos sql:db:command.utf
\ (c-addr, u , conptr -- bool)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ C-ADDR    address of a UTF string - the QUERY text
\ U         length of UTF string in bytes
\ CONPTR    Pointer to a Connection data structure.
\ --
\ BOOL      = 0 if failure
\           else successful

 help_pos sql:db:command
\ (c-addr, u , conptr -- bool)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ C-ADDR    address of a character string - the QUERY text
\ U         length of character string
\ CONPTR    Pointer to a Connection data structure.
\ --
\ BOOL      = 0 if failure
\           else successful

 help_pos sql:db:command.variant
\ (VARIANT , conptr -- bool)
\ Submit a query string to the database identified by the Connection Pointer CONPTR.
\ VARIANT   address of a VARIANT with  BSTR conatining the SQL command to be executed
\ CONPTR    Pointer to a Connection data structure.
\ --
\ BOOL      = 0 if failure
\           else successful

 help_pos sql:query@row
\ (resptr -- cols|0|-1)
\ If the database query that generated the response identified by RESPTR has one of more
\ unread rows, then move an internal pointer to point at the next unread row.
\ RESPTR  A pointer to the query response
\ --
\ COLs      The number of columns in the response
\           0 if no more rows are available
\           -1 if failure

 help_pos sql:finalize
\ (resptr -- ResCode )
\ Terminate the handling of a query response (releases internal resources).
\ RESPTR  Pointer to the query response
\ --
\ RESCODE  see SQLITE documentation  ( SQLITE_OK = 0)

 help_pos sql:Reset
\ (resptr -- ResCode )
\ Reset the internal pointers associated with the query response RESPTR to
\ indicate that no rows of the response have yet been read.
\ RESPTR  Pointer to the query response
\ --
\ RESCODE  see SQLITE documentation

 help_pos sql:bind.Reset
\ (resptr -- ResCode )
\ Reset the internal bindings associated with the query response RESPTR
\ RESPTR  Pointer to the query response
\ --
\ RESCODE  see SQLITE documentation

 help_pos sql:col@txt.UTF
\ (col-id, resptr -- b-addr, u)
\ Get the UTF string associated with the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ B-ADDR        address of a UTF string - Text contained in specified column
\ U             length of UTF string in bytes

 help_pos sql:col@txt
\ (col-id, resptr -- c-addr, u)
\ Get the character string associated with the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ C-ADDR        address of a character string - Text contained in specified column
\ U             length of character string

 help_pos sql:col@size
\ (col-id, resptr --   u)
\ Get the size in BYTES of the response held in the current row of the COL-ID'th colums (0-based)
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ U             Size of column in bytes

 help_pos sql:col@Int
\ (col-id, resptr -- i)
\ Get the INTEGER value associated with the specified column in
\ the database query reponse identified by RESPTR
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ I             Integer value associated with the specified column

 help_pos sql:col@DInt
\ (col-id, resptr -- di)
\ Get the DOUBLE precision (64 bit) Floating value associated with the specified column in
\ the database query reponse identified by RESPTR
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ DI            Double precision Floating value associated with the specified column

 help_pos sql:col@type
\ (col-id, resptr -- val)
\ Get the INTEGER value associated with the specified column TYPE in
\ the database query reponse identified by RESPTR
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ Val           Integer value associated with the specified column
\               1 = integer
\               2 = float
\               3 = text
\               4 = blob
\               5 = NULL

 help_pos sql:col@name.utf
\ (col-id, resptr -- b-addr, u)
\ Get the UTF string associated with the NAME of the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ B-ADDR        address of a UTF string
\ U             length of UTF string in bytes

 help_pos sql:col@name
\ (col-id, resptr -- c-addr, u)
\ Get the character string associated with the NAME of the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ C-ADDR        address of a character string
\ U             length of character string

 help_pos sql:col@decl.utf
\ (col-id, resptr -- b-addr, u)
\ Get, as a  UTF string, the DATA TYPE assigned  to the column specified by  COL-ID in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ B-ADDR        address of a UTF string
\ U             length of UTF string in bytes

 help_pos sql:col@decl
\ (col-id, resptr -- c-addr, u)
\ Get, as a text string, the DATA TYPE assigned  to the column specified by  COL-ID in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ C-ADDR        address of a character string
\ U             length of character string

 help_pos sql:col@as
\ (col-id, resptr -- c-addr, u)
\ Get the character string associated with the schema of the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ C-ADDR        address of a character string
\ U             length of character string

 help_pos sql:bind=text16
\ (c-addr, u,  id, resptr -- boolean)
\ Associate the character string C-ADDR of length U characters, with the parameter
\ specified by ID in the currently selected row of the query result identified by RESPTR.
\ C-ADDR        address of a character string to be bound to the parameter
\ U             length of character string
\ ID            "One" based index of the parameter that the text (CA_DDR, U) is to be bound to
\ RESPTR        Pointer to the query response
\ --
\ BOOLEAN       = 0 on error
\               else = okay

 help_pos sql:bind=text
\ (c-addr, u,  id, resptr -- boolean)
\ Associate the character string C-ADDR of length U characters, with the parameter
\ specified by ID in the currently selected row of the query result identified by RESPTR.
\ C-ADDR        address of a character string to be bound to the parameter
\ U             length of character string
\ ID            "One" based index of the parameter that the text (CA_DDR, U) is to be bound to
\ RESPTR        Pointer to the query response
\ --
\ BOOLEAN       = 0 on error
\               else = okay

 help_pos sql:col@blob
\ (col-id, resptr -- c-addr, u)
\ Get the byte array associated with the BLOB in the specified column in
\ the database query reponse identified by RESPTR
\ BE WARNED: the returned  C-ADDR,U  loses its validity when the owning
\ query reponse is finalised !
\ COL-ID        Zero based index of column to be read from the current row in the query response
\ RESPTR        Pointer to the query response
\ --
\ C-ADDR        address of a memory area that holds the BLOB
\ U             size of the BLOB in bytes

  [then]
  ' SQL [if]
 help_pos arg@text
\ (c-addr, u  -- c-addr, u)
\ Submit a query string to the database that is embedded (appended) in
\ this executable.
\ The query should return a single TEXT string
\ C-ADDR    address of a character string - the QUERY text
\ U         length of character string
\ --
\ C-ADDR    address of a character string - the QUERY RESULT text
\           address = 0 on error, or if there is no embedded database
\ U         length of character string
\           length = 0 on error, or if there is no embedded database

 help_pos arg@int
\ (c-addr, u  -- (x,1) |0 )
\ Submit a query string to the database that is embedded (appended) in
\ this executable.
\ The query should return a single INTEGER
\ C-ADDR    address of a character string - the QUERY text
\ U         length of character string
\ --
\ Boolean    = 0 on error, or if there is no embedded database
\ (X)           if Boolean <> 0 then  the result  X    is provided = INTEGER

 help_pos arg@float
\ (c-addr, u  -- (x,1) |0 )
\ Submit a query string to the database that is embedded (appended) in
\ this executable.
\ The query should return a single FLOAT  (R8) value
\ C-ADDR    address of a character string - the QUERY text
\ U         length of character string
\ --
\ Boolean    = 0 on error, or if there is no embedded database
\ (X)           if Boolean <> 0 then  the result  X    is provided = FLOAT

 help_pos arg@Connection
\ ( --  DBconPtr )
\ Returns a pointer to the DB Connection belong to the database that is embedded (appended) in
\ this executable.
\ no input parameters
\ --
\ DBCONPTR  Pointer to the DB Connection belong to the database that is embedded (appended) in
\           this executable.
\           = 0 if there is no embedded database

  [then]
  ' -trailing [if]
 help_pos -trailing
\ (c-addrI, uI -- c-addrO, uO)
\ Remove any trailing space characters from the input character string and
\ return the address of the input character string and the length
\ of the remaining character string
\ C-ADDRI   Address of the input character string
\ UI        Number of characters in the input string
\ --
\ C-ADDRO   Address of the output character string
\ UO        Number of characters in the output string

 help_pos /string
\ (c-addrI, uI, n -- c-addrO, uO)
\ Remove the leading N characters from the input character string and
\ return the address and length of the new character string.
\ C-ADDRI   Address of the input character string
\ UI        Length of input character string
\ N         Number of characters to be removed from the front of the
\           input character string.  N must be less than COUNTI
\ --
\ C-ADDRO   Address of the output character string
\ UO        Number of characters in the output string

 help_pos blank
\ (c-addr, u --)
\ Fill the memory area at C-ADDR with U space characters.
\ C-ADDR    Address of a memory area to be filled with space characters
\ U         Number of spaces characters to be placed in the memory area,
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos cmove
\ (c-addrS, c-addrD, u --)
\ Copy U CHARACTERS starting from the address C-ADDRS
\ to the memory starting at the address C-ADDRD
\ C-ADDRS   Address of the source memory area
\ C-ADDRD   Address of the destination memory area
\ U         Number of  CHARACTERS to be copied
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos cell.move
\ (c-addrS, c-addrD, u --)
\ Copy U CELL starting from the address C-ADDRS
\ to the memory starting at the address C-ADDRD
\ C-ADDRS   Address of the source memory area
\ C-ADDRD   Address of the destination memory area
\ U         Number of  CELLS to be copied
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos bmove
\ (c-addrS, c-addrD, u --)
\ Copy U BYTES starting from the address C-ADDRS
\ to the memory starting at the address C-ADDRD
\ C-ADDRS   Address of the source memory area
\ C-ADDRD   Address of the destination memory area
\ U         Number of  BYTES to be copied
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos cmove>
\ (c-addrS, c-addrD, u --)
\ Copy U CHARACTERS starting from the address C-ADDRS
\ to the memory starting at the address C-ADDRD.
\ Start the copy from the higher address and move downwards.
\ C-ADDRS   Address of the source memory area
\ C-ADDRD   Address of the destination memory area
\ U         Number of CHARACTERS to be copied
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos bmove>
\ (c-addrS, c-addrD, u --)
\ Copy U BYTES starting from the address C-ADDRS
\ to the memory starting at the address C-ADDRD.
\ Start the copy from the higher address and move downwards.
\ C-ADDRS   Address of the source memory area
\ C-ADDRD   Address of the destination memory area
\ U         Number of BYTES to be copied
\           if U is zero then do nothing!
\ --
\ No output parameters

 help_pos compare
\ (c-addr1, u1, c-addr2, u2 -- rcode)
\ Compare two character strings, note that this comparision IS case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ RCODE     = 0 = identical
\           IF identical up to length of shorted string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos compare(bytes)
\ (c-addr1, u1, c-addr2, u2 -- rcode)
\ Compare two BYTE strings, note that this comparision IS case sensitive
\ C-ADDR1   Address of the first BYTE string
\ U1        Number of BYTEs in the first string
\ C-ADDR2   Address of the second BYTE string
\ U2        Number of BYTEs in the second string
\ --
\ RCODE     = 0 = identical
\           IF identical up to length of shorted string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos search
\ (c-addr1, u1, c-addr2, u2 -- c-addr3, u3, rcode)
\ Search the CHARACTER string   caddr , count
\ For the first appearance of the CHARACTER string caddr2 , count2
\ C-ADDR1   Address of the first CHARACTER string
\ U1        Number of CHARACTERS in the first string
\ C-ADDR2   Address of the second CHARACTER string
\ U2        Number of CHARACTERS in the second string
\ --
\ C-ADDR3   Address of the first match in first string
\ U3        Number of CHARACTERS remaining in the first string
\ RCODE     = TRUE then a match was found
\           = FALSE no match found and c-addr3 , count3  = c-addr1 , count1

 help_pos sliteral
\ (c-addr, u --)
\ Causes the character string defined by c-addr u to be compiled
\ in to the current definition so that at run time the
\ an address and length of string containing the same characters shall be
\ placed on the stack
\ C-ADDR    Address of the character string
\ U         Number of characters in the string
\ --
\ No output parameters

   [THEN]
  ' join" [if]
 help_pos trim-trailing-whitespace
\ (c-addrI, uI -- c-addrO, uO)
\ Remove any trailing SPACE or TAB  characters from the input character string and
\ return the address of the first non-CHAR character and the length
\ of the remaining character string.
\ Note: It does this by moving the start address and string length.
\       It does not copy the data to a new buffer
\ C-ADDRI   Address of the input character string
\ UI        Length of input character string
\ --
\ C-ADDRO   Address of the output character string
\ UO        Length of output character string

 help_pos trim-leading-whitespace
\ (c-addrI, uI -- c-addrO, uO)
\ Remove any leading SPACE or TAB  characters from the input character string and
\ return the address of the first non-CHAR character and the length
\ of the remaining character string
\ Note: It does this by moving the end address and string length.
\       It does not copy the data to a new buffer
\ C-ADDRI   Address of the input character string
\ UI        Length of input character string
\ --
\ C-ADDRO   Address of the output character string
\ UO        Length of output character string

 help_pos trim-leading
\ (c-addrI, uI, char -- c-addrO, uO)
\ Remove any leading CHAR characters from the input character string and
\ return the address of the first non-CHAR character and the length
\ of the remaining character string
\ C-ADDRI   Address of the input character string
\ UI        Length of input character string
\ CHAR      A character sized value
\ --
\ C-ADDRO   Address of the output character string
\ UO        Length of output character string

 help_pos trim-trailing
\ (c-addrI, uI, char -- c-addrO, uO)
\ Remove any trailing CHAR characters from the input character string and
\ return the address of the input character string and the length
\ of the remaining character string
\ C-ADDRI   Address of the input character string
\ UI        Length of input character string
\ CHAR      A character sized value
\ --
\ C-ADDRO   Address of the output character string
\ UO        Length of output character string

 help_pos char>"
\ (char -- c-addr, u)
\ Convert a single character to a character string
\ CHAR      A character sized value
\ --
\ C-ADDR    Address of the created character string
\ U         Length of created string ( = 1 )

 help_pos join"
\ (c-addr1, u1, c-addr2, u2 -- c-addrO, uO)
\ Copy the character string given by c-addr1 count1 to a new internal
\ string buffer at c-addr3.
\ Concatenate the character string given by c-addr2 count2
\ to the end of the character string given by c-addr3 count1.
\ Note: that the length of the combined strings must not exceed 64 k characters
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ C-ADDRO   Address of the resulting character string
\ UO        Number of characters in the resulting string

 help_pos join-memory
\ (c-addr1, u1, c-addr2, u2 -- c-addr1, uO)
\ Concatenate the character string given by c-addr2 count2
\ to the end of the character string given by c-addr1 count1.
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ C-ADDR1   Address of the first character string
\ UO        Number of characters in the resulting string

 help_pos compare.chars.caseless
\ (c-addr1, u1, c-addr2, u2 -- rcode)
\ Compare two CHARACTER strings, note that this comparision is
\ NOT case sensitive
\ C-ADDR1   Address of the first CHARACTER string
\ U1        Number of CHARACTERS in the first string
\ C-ADDR2   Address of the second CHARACTER string
\ U2        Number of CHARACTERS in the second string
\ --
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos compare.bytes.caseless
\ (c-addr1, u1, c-addr2, u2 -- rcode)
\ Compare two BYTE strings, note that this comparision is
\ NOT case sensitive
\ C-ADDR1   Address of the first BYTE string
\ U1        Number of BYTES in the first string
\ C-ADDR2   Address of the second BYTE string
\ U2        Number of BYTES in the second string
\ --
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos equal.chars.caseless
\ (c-addr1, u1, c-addr2, u2 -- bool)
\ Compare two CHARACTER strings, note that this comparision is
\ NOT case sensitive
\ C-ADDR1   Address of the first CHARACTER string
\ U1        Number of CHARACTERS in the first string
\ C-ADDR2   Address of the second CHARACTER string
\ U2        Number of CHARACTERS in the second string
\ --
\ BOOL     = TRUE = identical
\           else 0

 help_pos equal.chars
\ (c-addr1, u1, c-addr2, u2 -- bool)
\ Compare two CHARACTER strings, note that this comparision IS
\  case sensitive
\ C-ADDR1   Address of the first CHARACTER string
\ U1        Number of CHARACTERS in the first string
\ C-ADDR2   Address of the second CHARACTER string
\ U2        Number of CHARACTERS in the second string
\ --
\ BOOL     = TRUE = identical
\           else 0

 help_pos equal.bytes.caseless
\ (c-addr1, u1, c-addr2, u2 -- BOOL)
\ Compare two BYTE strings, note that this comparision is
\ NOT case sensitive
\ C-ADDR1   Address of the first BYTE string
\ U1        Number of BYTES in the first string
\ C-ADDR2   Address of the second BYTE string
\ U2        Number of BYTES in the second string
\ --
\ BOOL     = TRUE = identical
\           else 0

 help_pos search.chars
\ (c-addr1, u1, c-addr2, u2 -- c-addr3, u3, rcode)
\ Search in string 1 for the first appearance of string 2
\ this IS  case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ C-ADDR3   Address of the first match in first string
\ U3        Number of characters remaining in the first string
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos search.bytes
\ (c-addr1, u1, c-addr2, u2 -- c-addr3, u3, rcode)
\ Search in string 1 for the first appearance of string 2
\ this IS  case sensitive
\ C-ADDR1   Address of the first byte string
\ U1        Number of byte in the first string
\ C-ADDR2   Address of the second byte string
\ U2        Number of byte in the second string
\ --
\ C-ADDR3   Address of the first match in first string
\ U3        Number of byte remaining in the first string
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 byte at X is than string2 byte position X
\                1 else

 help_pos search.chars.caseless
\ (c-addr1, u1, c-addr2, u2 -- c-addr3, u3, rcode)
\ Search in string 1 for the first appearance of string 2
\ NOT case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ C-ADDR3   Address of the first match in first string
\ U3        Number of characters remaining in the first string
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 char at X is than string2 char position X
\                1 else

 help_pos search.bytes.caseless
\ (c-addr1, u1, c-addr2, u2 -- c-addr3, u3, rcode)
\ Search in string 1 for the first appearance of string 2
\ NOT case sensitive
\ C-ADDR1   Address of the first byte string
\ U1        Number of byte in the first string
\ C-ADDR2   Address of the second byte string
\ U2        Number of byte in the second string
\ --
\ C-ADDR3   Address of the first match in first string
\ U3        Number of byte remaining in the first string
\ RCODE     = 0 = identical
\           IF identical up to length of shorter string
\               -1  if string1 is shorter than string2
\                1  else
\           IF identical up to position X
\               -1 if string1 byte at X is than string2 byte position X
\                1 else

 help_pos instr.chars
\ (c-addr1, u1, c-addr2, u2 --  rcode)
\ Search in string 1 for the first appearance of string 2
\ this IS  case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos instr.bytes
\ (c-addr1, u1, c-addr2, u2 -- rcode)
\ Search in string 1 for the first appearance of string 2
\ this IS  case sensitive
\ C-ADDR1   Address of the first byte string
\ U1        Number of byte in the first string
\ C-ADDR2   Address of the second byte string
\ U2        Number of byte in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos instrRev.chars.caseless
\ (c-addr1, u1, c-addr2, u2 --  rcode)
\ Search in string 1 for the last appearance of string 2
\ NOT case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos instrRev.chars
\ (c-addr1, u1, c-addr2, u2 --  rcode)
\ Search in string 1 for the last appearance of string 2
\    case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos instr.chars.caseless
\ (c-addr1, u1, c-addr2, u2 --  rcode)
\ Search in string 1 for the first appearance of string 2
\ NOT case sensitive
\ C-ADDR1   Address of the first character string
\ U1        Number of characters in the first string
\ C-ADDR2   Address of the second character string
\ U2        Number of characters in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos instr.bytes.caseless
\ (c-addr1, u1, c-addr2, u2 --  rcode)
\ Search in string 1 for the first appearance of string 2
\ NOT case sensitive
\ C-ADDR1   Address of the first byte string
\ U1        Number of byte in the first string
\ C-ADDR2   Address of the second byte string
\ U2        Number of byte in the second string
\ --
\ RCODE     = 0 = not found
\           else = 1 based index of first match

 help_pos substr.chars
\ (c-addr, u, offset, length  -- c-addrS, uS )
\ Split a input string into 3 components
\   text before the split string
\   the split string
\   text after the split string
\
\ C-ADDR    Address of the character string to converted to a substr
\ U         length of string
\ OFFSET    Number of leading characater to be passed over
\ LENGTH    Number of characters to be retained
\ --
\ C-ADDRS   Address of the character string appearing BEFORE the SPLIT string
\ US        length of string defining the SPLIT  ( S for  start )

 help_pos strsplit
\ (c-addr, u, c-addrD, uD, bool -- c-addrE, uE, c-addrS, uS, c-addrM, uM)
\ Split a input string into 3 components
\   text before the split string
\   the split string
\   text after the split string
\
\ C-ADDR    Address of the character string to be SPLIT
\ U         length of string to be SPLIT
\ C-ADDRD   Address of the character string defining the SPLIT
\ UD        length of string defining the SPLIT
\ BOOL      = 0 case insensitive
\           else case sensitive
\ --
\ C-ADDRE   Address of the character string appearing AFTER the SPLIT string
\ UE        length of string to be SPLIT    ( E for  end )
\           0 if SPLIT not found   or   if SPLIT string is at the end of the string to be SPLIT
\ C-ADDRS   Address of the character string appearing BEFORE the SPLIT string
\ US        length of string defining the SPLIT  ( S for  start )
\ C-ADDRM   Address of the character string defining the SPLIT
\ UM        length of string defining the SPLIT  ( M for  middle )
\           0 if SPLIT not found

 help_pos strsplit.end
\ (c-addr, u, c-addrD, uD, bool -- c-addrE, uE, c-addrS, uS, c-addrM, uM)
\ Split a input string into 3 components
\   text before the split string
\   the split string
\   text after the split string
\
\ C-ADDRS   Address of the character string to be SPLIT
\ US        length of string to be SPLIT
\ C-ADDRD   Address of the character string defining the SPLIT
\ UD        length of string defining the SPLIT
\ BOOL      = 0 case insensitive
\           else case sensitive
\ --
\ C-ADDRE   Address of the character string appearing AFTER the SPLIT string
\ UE        length of string to be SPLIT    ( E for  end )
\           0 if SPLIT not found   or   if SPLIT string is at the end of the string to be SPLIT
\ C-ADDRS   Address of the character string appearing BEFORE the SPLIT string
\ US        length of string defining the SPLIT  ( S for  start )
\ C-ADDRM   Address of the character string defining the SPLIT
\ UM        length of string defining the SPLIT  ( M for  middle )
\           0 if SPLIT not found

 help_pos strreplace-all
\ (c-addrm, um, c-addrO, uO, c-addrN, uN, bool -- c-addr, u , bool)
\ Replace all occurrences of OLD string in the master string by the NEW string
\
\ C-ADDRM   Address of the master character string
\ UM        length of master string
\ C-ADDRO   Address of the character string to be replaced (OLD)
\ UO        length of string defining the old string
\ C-ADDRN   Address of the character string to be inserted (NEW)
\ UN        length of string defining the new string
\ BOOL      = 0 case insensitive
\           else case sensitive
\ --
\ C-ADDR    Address of the resulting character string
\ U         length of resulting string
\ BOOL      = 0 not replaced
\           else   replaced

 help_pos strreplace
\ (c-addrm, um, c-addrO, uO, c-addrN, uN, bool -- c-addr, u , bool)
\ Replace the FIRST occurrence of OLD string in the master string by the NEW string
\
\ C-ADDRM   Address of the master character string
\ UM        length of master string
\ C-ADDRO   Address of the character string to be replaced (OLD)
\ UO        length of string defining the old string
\ C-ADDRN   Address of the character string to be inserted (NEW)
\ UN        length of string defining the new string
\ BOOL      = 0 case insensitive
\           else case sensitive
\ --
\ C-ADDR    Address of the resulting character string
\ U         length of resulting string
\ BOOL      = 0 not replaced
\           else   replaced

 help_pos byte:append
\ (c-addrL, uL,  c-addrR, uR,    c-addrD, uDmax -- c-addrD, uDis  )
\ Append the RIGHT byte array to the end of the LEFT byte array to create DST byte array
\
\ C-ADDRL   Address of the LEFT byte array
\ UL        length of LEFT byte array
\ C-ADDRR   Address of the right byte array
\ UR        length of right byte array
\ C-ADDRD   Address of the destination byte array
\ UDMAX     Maximum length of byte array
\ --
\ C-ADDRD   Address of the destination byte array
\ UIS       Used length of destination byte array

 help_pos char.append
\ (c-addrL, uL,  c-addrR, uR,    c-addrD, uDmax -- c-addrD, uDis  )
\ Append the RIGHT string to the end of the LEFT string to create DST string
\
\ C-ADDRL   Address of the LEFT character string
\ UL        length of LEFT string
\ C-ADDRR   Address of the right character string
\ UR        length of right string
\ C-ADDRD   Address of the destination character string
\ UDMAX     Maximum length of destination string
\ --
\ C-ADDRD   Address of the destination character string
\ UIS       Used length of destination string

   [THEN]
 help_pos ecode@fiop
\ (-- a-addr)
\ Return the address of an internal variable used to hold the
\ file-id of the opened file that provides user defined modifications
\ to the ecode table.
\ No input parameters
\ --
\ A-ADDR    Address of an internal variable

 help_pos ecode@size
\ (-- u)
\ Return the number of entries in the ECODE table.
\ No input parameters
\ --
\ U        Number of entries in the error/text table.

 help_pos ecode@offset
\ (uecode -- u-ptr)
\ Return the address of the file-offset for this uecode.
\ If uecode is invalid then return -1.
\ If the text for uecode is the default(in the ECODE table) then return 0.
\ UECODE    Error code
\ --
\ U-PTR     -1 IF   uecode is invalid
\            0 IF   text is in ECODE table not in a file
\              ELSE address of file offset

 help_pos ecode@text
\ (uecode -- c-addr, u)
\ Return the address c-addr , of the character string and length u, associated with
\ the INTERPRETER's error code uecode.
\ If the text is held in a user defined file, it will be copied in to
\ a temporary buffer.
\ UECODE    Error code
\ --
\ C-ADDR    Address of a charcter string
\ U         Length of character string


\ (ecode -- u-ptr)
\ Return the address of 0 terminated character string associated with
\ the error code ecode .
\ ECODE     Error code
\ --
\ U-PTR     -1 IF   no such error code
\              ELSE address of a zero terminated character string

 help_pos ecode@index
\ (index -- uecode)
\ Return the error code uecode associated with the index position
\ INDEX     Index in to an internal array with  ecode@size  elements
\ --
\ UECODE    Error code if index valid
\           ELSE  -1

 help_pos Trigger.error
\ (c-addr, u  --  )
\ Return the error code uecode associated with the index position
\ C-ADDR    Address of character string holding user defined error text
\ U         Length of character string in characters
\ --
\ no output parameters

  ' dump [if]
 help_pos see
\ (--)
\ Used to display the header and some of the compiled in code of
\ a specified definition. This command is primitive!
\ Used in the form  SEE COMMAND-NAME
\ Parse the current input area for a space delimited string.
\ Search the current search order wordlists for the delimited string.
\ If found, then display the definitions header and code area.
\ No input parameters
\ --
\ No output parameters

 help_pos dump
\ (a-addr, u --)
\ Displays the U cells starting at address a-addr
\ This is a sort of memory display function.
\ This uses the standard display format for unsigned integers.
\ a-addr    Address of first cell in memory to be displayed
\ u         The number of cells to be displayed
\ --
\ No output parameters

 help_pos ?
\ (a-addr --)
\ Display the cell stored at the address a-addr.
\ This uses the standard display format for unsigned integers.
\ a-addr    Address of cell in memory to be displayed
\ --
\ No output parameters

 help_pos .s
\ (--)
\ Display all the cells on the stack. The stack will not be corrupted or changed.
\ No input parameters
\ --
\ No output parameters

 help_pos words
\ (--)
\ Used to display the names of the definitions that are in the top
\ wordlist of the current search order wordlist.
\ No input parameters
\ --
\ No output parameters

   [THEN]
  ' [then] [if]
 help_pos [if]
\ (x --)
\ Used as part of an [IF] [THEN] or [IF] [ELSE] [THEN]
\ flow control construct. Note these constructs can be nested!
\ If x <> 0 then continue execution with the instruction after
\ the [if].
\ If x = 0 then parse the input stream, refilling when
\ necessary, until the next matched, space delimited string [ELSE]
\ or [THEN] is encountered.
\ Discard the matched string and continue with normal command line
\ interpretation from that point onwards.
\ Used in the form
\   value  [IF]   words to do if value is true
\          [ELSE] words to do if value is false
\          [THEN] normal processing
\  [IF]  [ELSE]  [THEN] can be nested
\  [IF]  [THEN] is allowed
\  Input will be scanned across multiple input lines until
\  the appropriate (in case of nesting) [ELSE] or [THEN] is found
\ x          A cell sized value
\ --
\ No output parameters

 help_pos [else]
\ (--)
\ Used as part of an [IF] [THEN] or [IF] [ELSE] [THEN]
\ flow control construct. Note these constructs can be nested!
\ Parse the input stream, refilling when
\ necessary, until the next matched, space delimited string [THEN]
\ is encountered.
\ Discard the matched string and continue with normal command line
\ interpretation from that point onwards.
\ Used in the form
\   value  [IF]   words to do if value is true
\          [ELSE] words to do if value is false
\          [THEN] normal processing
\  [IF]  [ELSE]  [THEN] can be nested
\  [IF]  [THEN] is allowed
\  Input will be scanned across multiple input lines until
\  the appropriate (in case of nesting) [THEN] is found
\ No input parameters
\ --
\ No output parameters

 help_pos [then]
\ (--)
\ Used as part of an [IF] [THEN] or [IF] [ELSE] [THEN]
\ flow control construct. Note these constructs can be nested!
\ This command has no action, it is simply a character string
\ that is used by [IF] and [ELSE] as a marker in the input stream.
\ Used in the form
\   value  [IF]   words to do if value is true
\          [ELSE] words to do if value is false
\          [THEN] normal processing
\  [IF]  [ELSE]  [THEN] can be nested
\  [IF]  [THEN] is allowed
\ No input parameters
\ --
\ No output parameters

   [THEN]
 help_pos list.media.subtypes
\ ( c-addr, u -- listId)
\ Return the ListId of an internal list containing the names (character strings)
\ of the Directshow media subtypes that the device supports.
\ If a media subtype is not known it will be represented by a character representation
\ of the subtype's GUID.
\ C-ADDR    Address of memory holding the target DEVICE's NAME
\ U         Number of characters in the target DEVICE's NAME
\ --
\ LISTID   on error = -1
\          else internal list identity

 help_pos list.video.sources
\ (--lisId)
\ Release the current LIST resource
\ No input parameters
\ --
\ No output parameters

 help_pos list.video.sources
\ ( -- listId)
\ Release the current LIST resource
\ No input parameters
\ --
\ LISTID   on error = -1
\          else internal list identity

