Package Handling

Z88 CamelForth v3.00 now provides facilities for accessing the new Packages facilities introduced with Installer v2.00.

Basic Package Information

The following words allow you to determine whether the packages system is available on the Z88, which packages are available and details of their versions and resource usage. You should read and understand the full Packages documentation on the technical information page before attempting to use these words.

PKGS? ( -- flag )

Returns true if the packages system is available on this Z88. If not, no further package words should be executed.

AYT? ( pkgid -- ver | 0 )

Returns the version number of the package if available, or zero if not.

PKGINF ( pkgid -- 0-addr Dmem hdls res )

Returns the name, memory, handle and other resource usage of the package (invalid if package not installed).

PID ( -- pid )

Returns the process ID of the currently running application.

Package Calls

These words are provided to allow C-style package calls (as exported by z88dk packages, and soon by CamelForth packages) to be easily used. Examples of the use of PKGCALL can be seen in the support files for currently available packages, detailed below.

PKGCALL ( ressize nparams minver reason callid "name" -- )

Defines a word called name that will, when executed, make the specified package call. Reason is a reason code passed in A (required for TCP/IP calls, but otherwise rarely used), minver is the minimum version number of the package providing the call, nparams is the number of arguments provided on the data stack (in cells), and ressize is the size of the result provided, in bytes (returned in DEHL). Double-sized arguments should be presented with the low-order cell above the high-order cell on the stack (this is the other way around to Forth's usage). Results are automatically placed in the correct order on the stack.

(RC_PNF) ( callid -- )

This is a deferred word, executed whenever a package call fails because the required package (of the desired version number) cannot be located. You can either request the user to restore access to the package and continue (the call will then be retried and execution continues as normal) or throw an exception.

PKGMIA ( callid -- )

The default action for (RC_PNF). This adds 512 to the package ID, negates the result and THROWs it as an exception.

(PKGERR) ( rc -- )

Another deferred word, executed if a C-style package returns an error other than RC_PNF (this is unlikely; most C-style packages report errors in their result codes).

PKGERR ( rc -- )

The default action for (PKGERR). This adds 256 to the error code, negates the result and THROWs it as an exception (as for any normal OZ error).

Supported Packages

Support is already provided for two packages; the TCP/IP package provided with the ZSock application, and the MIMEtools package that comes with the UUtools popdown.

• TCP/IP package support
• MIMEtools package support

More about CamelForth

Back to the Z88 home page