Supported shared libraries

This chapter documents interfaces to shared libraries that can be used on all VFX Forth versions with the Extern: shared library interface - all except DOS. We will add more library interfaces as time goes by. Supported libraries can be found in <Vfx>/Lib/SharedLibs/.

We will support the interface code here, but our technical support cannot include teaching you how to use these libraries. Generous we may be, a charity we are not.

Open Source libraries can be found using Google, and may already be installed on your machine. For example, the SQLite database engine is used by FireFox and many other projects.

A reliable source of binaries for Windows is the MinGW distribution from:

 http://sourceforge.net/projects/mingw/
 http://www.mingw.org/

We will periodically put the Windows versions (and perhaps others) of the libraries on our FTP site at:

 ftp://soton.mpeforth.com/

You can use most browsers to access this. Login as "public" with a blank password and switch to the SharedLibs directory.

LibCurl

The libcurl library/DLL provides high-level functions for transferring data across networks to and from servers. be found at:

  http://curl.haxx.se/libcurl/

Additional help may be found at the curl-library mailing list subscription and unsubscription web interface:

  http://cool.haxx.se/mailman/listinfo/curl-library/

struct /curl_httppost   \ -- len
The Forth version of the curl_httppost structure.

0x10000001 constant CURL_WRITEFUNC_PAUSE
This is a magic return code for the write callback that, when returned, will signal libcurl to pause receiving on the current transfer.

Note that all Curl callbacks must be defined with FromC.

struct /curl_fileinfo   \ -- len
Content of this structure depends on information which is known and is achievable (e.g. by FTP LIST parsing). Please see the url_easy_setopt(3) man page for callbacks returning this structure -- some fields are mandatory, some others are optional. The FLAG field has special meaning.

LibIconv

LibIconv converts from one character encoding to another through Unicode conversion (see Web page for full list of supported encodings). It has also limited support for transliteration, i.e. when a character cannot be represented in the target character set, it is approximated through one or several similar looking characters. It is useful if your application needs to support multiple character encodings, but that support lacks from your system.

The latest version of the library can be obtained from

 http://gnuwin32.sourceforge.net/packages/libiconv.htm

The required files are:

To obtain a full list of the supported encodings, go to a operating system command line and type:

  iconv -l

: iconv_t  void *  ;
Define the iconv_t type as is done by the C header file.

: size_t        uint32  ;
Type for unsigned INT.

Extern: iconv_t "C" libiconv_open( const char * tocode, const char * fromcode );
Allocates descriptor for code conversion from encoding fromcode to encoding tocode.

Extern: size_t "C" libiconv(
Converts, using conversion descriptor cd, at most *inbytesleft bytes starting at *inbuf, writing at most *outbytesleft bytes starting at *outbuf.
Decrements *inbytesleft and increments *inbuf by the same amount.
Decrements *outbytesleft and increments *outbuf by the same amount.

  iconv_t cd,
  const char * * inbuf, size_t * inbytesleft,
  char * * outbuf, size_t * outbytesleft
);

Extern: int "C" libiconv_close( iconv_t cd );
Frees resources allocated for conversion descriptor cd.

SQLite

The most recent version of SQLite can be found at:

 http://www.sqlite.org/

This is a very compact and fast Open Source SQL database system that is ideal for managing data in a single application.

The VFX Forth interface can be found in the direcory:

 <Vfx>/Lib/SharedLibs/SQLite3

: pFunc  void *  ;
Pointer to a function.

: sqlite3  void  ;
This should always appear as sqlite3 *. Since this is an opaque type, translating it to void * is valid.

: sqlite3_stmt  void *  ;
Essentially a string pointer.

: sqlite3_value void *  ;
Can be anything!

: sqlite3_context void *  ;
Can hold anything!

: sqlite3_blob void *  ;
Pointer to an object.

: sqlite3_vfs  void *  ;
Essentially a pointer.

: sqlite3_mutex  void *  ;
Essentially a pointer.

zlib

The zlib library/DLL provides high-level functions for compression and decompression. The current version of the library is at

  www.zlib.net

The file zlib.fth is a conversion of zlib.h for VFX Forth. The zlib version is 1.2.5. If you are using this code with a different version of zlib, use

  zlibCompileflags ( -- x )

to check that the types and fields zLong and zInt defined here are correct.

Windows specifics

The most reliable source of binaries for Windows is the MinGW distribution from:

 http://sourceforge.net/projects/mingw/
 http://www.mingw.org/
[defined] Target_386_Windows [if]
library: zlib1.dll
also types definitions
: zexport   "C"  ;
: zlong     uint32  ;   \ uLong type
: zInt      uint32  ;   \ uInt type
: z_off_t   uint32  ;
previous definitions
: zlong     4 field  ;
: zInt      4 field  ;
[then]

Mac OS X specifics

[defined] Target_386_OSX [if]
\ library: libcurl.2.dylib
also types definitions
: zexport   "C"  ;
: z_off_t  LongLong  ;
: zlong     uint32  ;   \ uLong type
: zInt      uint32  ;   \ uInt type
previous definitions
: zlong     4 field  ;
: zInt      4 field  ;
[then]

Linux specifics

[defined] Target_386_Linux [if]
\ library: libcurl.so.3
\ library: libcurl.so.4
also types definitions
: zexport   "C"  ;
: z_off_t  LongLong  ;
: zlong     uint32  ;   \ uLong type
: zInt      uint32  ;   \ uInt type
previous definitions
: zlong     4 field  ;
: zInt      4 field  ;
[then]

Generic code

struct /z_stream_s      \ -- len
z_stream_s structure.

LibXL - Excel interface

LibXL is a library that can read and write Excel files. It doesn't require Microsoft Excel or the .NET framework, and combines a set of easy to use and powerful features. The library can be used to:

LibXL is proprietary code, but the price is very reasonable. Versions exist for Windows, OS X, iOS and Linux. LibXL can be obtained from:

  www.libxl.com

This code is built as 32 bit code using the ASCII interface. Consequently, strings shown with L" in the C examples are ASCII zero-terminated strings and the Forth word z" can be used for them. The DLL interface uses the "C" calling convention for all operating systems. The Windows version should use libXL.dll from the bin directory of LibXL distribution.

: enum          \ --
Process an enum of the form:

  enum <name> { a, b, c=10, d };

<name> is ignored. The elements appear as Forth constants. The definition may extend over many lines. C comments may occur after the ',' separator, e.g.

 JIM = 25, // comment about this line

: enum{         \ --
Process an enum of the form:

  enum{ a, b, c=10, d };

Test code

: UniPlace      \ addr len destaddr --
Store a Unicode string to an address. The string is stored as a cell counted string with a 16 bit zero terminator. The terminator is not included in the count.

: UniAppend ( addr len destaddr -- )
Append a string to the end of an address

: Ascii>Uni,    \ addr len --
Store an ASCII string as a Unicode string in the dictionary. The string is stored as a cell counted string with a 16 bit zero terminator. The terminator is not included in the count.

: Ascii>Uni     \ addr len dest --
Store an ASCII string as a Unicode string at an address. The string is stored as a cell counted string with a 16 bit zero terminator. The terminator is not included in the count.

: UniCount ( addr -- addr len )
Fetch a unicode string from an address.

: LZ"           \ "text" -- zaddr
Unicode string - should behave the same way as z"

: xlTest        \ --
libXL example 1