Ticol TCL - HowTo

Howto - Introductory Notes

• While it may work with certain emulators or with WINE on Linux, Ticol is solely a Windows-based language.
• Ticol is also, by design, non-Unicode and ANSI only.  There was no requirement when the design was mooted for Unicode or multi-national support
• The interface prototypes for ticol.dll are under development and are subject to change
• All exported functions are declared as __stdcall unless otherwise stated
• Not all exports are active/valid or safe. Those marked 'do not use' should not be used
• The caller should not free returned strings unless otherwise stated. Strings are set up to work in the VB5/6 environment
• The interpreter is designed to, as far as possible, support Windows from NT4/SP6a to Windows 10/Server 2016
• Never use ordinal numbers as these will change in future versions

How to View Ticol's DLL Exports

The following functions are exported from ticol.dll. This includes a number of useful ancillary functions for addressing the console.
The NirSoft DLL Export Viewer can be used to view the exports

Exported functions behave as follows. Some of the function names retain the same name as the original Picol source from which Ticol was originally based. There has been no reason to change these names. Some functions are retained for development debugging only

Top

DLL Function Prototypes

The following prototypes apply to exported functions. These are subject to change

Top

How To Call Ticol DLL from Visual BASIC

Calling Ticol from Visual BASIC via the ticol.dll version of the interpreter is reasonably straightforward as long as the correct Declare statements are included with the project. The main recommended interface is ticol_command(). Other exports should be avoided as these are experimental/deprecated.

Note that return values, where specified, MUST be taken, and exported Ticol functions called as a function rather than as a VB command

Simple calling example. Load ticol_wordcount.dll and count words in $qbf

Dim r As Long
Dim Breakpoints As Long
Dim StackTrace As Long
Dim RunAutoexec As Long
Dim DebugMode As Long
Dim Q As String
Q = Chr$(34)
ticol_set_app_path "c:\\tcl"

' Load ticol_wordcount.dll plugin
Debug.Print ticol_command("cls;lib ticol_wordcount.dll", Breakpoints, StackTrace, RunAutoexec, DebugMode, VarPtr(r))
' Call it...
Debug.Print ticol_command("puts " & Q & "[wordcount $qbf] word(s) [wordcount $qbf -chars] char(s)" & Q);
End

Result:

Top

How To Call Ticol DLL from C/C++

• ticol.dll is a fully-independent DLL with no LIB requirement. Prototypes are best declared for dynamic loading via LoadLibrary and GetProcAddress
• Calling Ticol is straightforward using the ticol.dll version of the interpreter. A small example calling program including compiled EXE binary is available here
• The C/C++ prototypes are defined in the table above.  Do not use the deprecated/reserved command
• ticol_command() is self-initialising and also cleans up as necessary. You can use ticol_ver() to check the release version if required. You may also call ticol_exit() but this shold not be necessary when using ticol_command(). It is currently not possible to disable Macro Preprocessing (MPP)
• The Ticol macro preprocessor (MPP) will be called automatically. This may be configurable on later versions to enable it to be disabled.
  There is no ability to load encrypted TCX files via ticol_command(), you must load into the interpreter space using ticol_load_script()
• It is anticipated that these commands will be called from C/C++ console programs rather than non-console ones
• Be sure to set sufficient stack as indicated in the example code below

Sample code:

// Example C++ calling ticol.dll (A __stdcall DLL)
// Ensure stack is sufficient for recursion (try 30,000-100,000)
// Loading the DLL dynamically is straightforward

#pragma comment(linker, "/stack:0x300000") 
#include <windows.h>
#include <stdio.h> 

int main(int argc, char** argv)
{
	LPSTR ptr=NULL;
	long breakpoint=0;
	long stacktrace=0;
	long autoexec=0;
	long debug=0;
	long errnum=0;

	// Embedded Tcl source code:
	// DO NOT indent this multi-line literal!
	// Some compilers may also restrict the size of string literals
	// e.g. MSVC 5.0

LPSTR script="\
textcolor magenta\r\n\
puts \"Hello world\"\r\n\
textcolor\r\n\
";

	// Declare funct*
	LPSTR (__stdcall* ticol_command)(LPSTR s,long,long,long,long,long*);

	HINSTANCE hAPI=LoadLibraryA("ticol.dll"); // Load the DLL
	if(hAPI) // Check handle
	{
		ticol_command=(LPSTR (__stdcall*)(LPSTR,long,long,long,long,long*)) \
		GetProcAddress(hAPI,"ticol_command"); // Load the export
		if(ticol_command) // If successful
		{
			printf("test: Loaded DLL ticol.dll->ticol_command()\r\n");
			// Call Tcl ...
			ptr=ticol_command(script,breakpoint,stacktrace,autoexec,debug,&errnum);
			printf("test: ticol_command: Returned result:'%s' errorcode:%li\r\n"\,(ptr?ptr:"NULL"),errnum);
		}
		else
		{
			printf("test: Failed to ticol_command in ticol.dll\r\n");
			return 1;
		}
	}
	else
	{
		printf("test: Failed to load ticol.dll\r\n");
		return 2;
	}
	return 0;
}

How to Test ticol.dll via The Windows Test Interface

The test interface allows basic scripts or commands to be run. The image below shows a pop-up console operating and which is spawned from the VB5 test app.  The autoexec.tcl file has run and a simple, 3-line script has been run. Some commands can't be run from VB such as [spawn],  [exec] must be used instead. Encrypted TCX files are handled in all encryption formats.

More recent versions allow the CLI to be launched and which then permits normal CLI operation

Showing unit tests running successfully on the DLL version of Ticol

Back | Top

Last updated on 15 May 2023 - This page is designed for 1024 x760 and higher resolution displays