XbToolsIII Reference:xbt
Installation and usage Foundation
Since Xbase++ 2.0 XbToolsIII is part of the Xbase++ installation. No separate installation package is delivered anymore.
How to compile, link and debug (Windows)
A program that uses functions from XbToolsIII is basically compiled, linked and debugged just as any other program written with Xbase++ (refer to the Xbase++ documentation for a comprehensive description of the general Compile, Link and Debug cycle). Differences arise from the fact that XbToolsIII is not comprised of default libraries for the Xbase++ compiler. Hence the import libraries must be specified for the linker ALINK.EXE in order to resolve symbolic references to the XbToolsIII DLLs.
Import libraries
Four import libraries are available: XBTNETW.LIB (Novell NetWare functions), XBTNETB.LIB (NetBIOS functions) and XBTBASE1.LIB and XBTBASE2.LIB (none network functions).
When using NetWare functions from XBTNETW.LIB you must have installed the Novell Netware Intranetware Client 32 which is not part of the MS Windows IPX/SPX support. XbToolsIII NetWare functions do not work without this Novell Intranetware Client.
If a program does not use NetWare or NetBIOS functions XBTNETW.LIB and XBTNETB.LIB need not be specified for the linker. The following table shows the function groups which are part of the import libraries:
Function groups in XbToolsIII (Windows)
| Import Lib | Group |
|---|---|
| XBTBASE1.LIB + | Window Functions |
| XBTBASE2.LIB | Extended Text Mode |
| Serial Port | |
| String Functions | |
| Numbers and Bits | |
| Video Functions | |
| Disks and Drives | |
| Printer Functions | |
| Date and Time Functions | |
| Database Functions | |
| Settings and Status | |
| System Info Functions | |
| Miscellaneous Functions | |
| Mathematical Functions | |
| Get System | |
| XBTNETW.LIB | Low level Bindery |
| User and Group Administration | |
| Connection Services | |
| Capture Processes | |
| Drive Administration | |
| Server Administration | |
| Print Queue | |
| Print Job Configuration | |
| Print Server | |
| Semaphores | |
| Novell TTS | |
| Miscellaneous Network Functions | |
| Printer and Forms | |
| XBTNETB.LIB | Point to Point Communication |
Linking under Windows
Depending on which function is used, up to four import libraries must be specified for the linker.
Alink /PM:VIO Program1 XBTBASE1.LIB XBTBASE2.LIB
Alink /PM:VIO Program2 XBTNETW.LIB
Alink /PM:VIO Program3 XBTBASE1.LIB XBTBASE2.LIB XBTNETB.LIB XBTNETW.LIB
Using #pragma library()
The Xbase++ compiler introduced the #pragma directive in version 1.1. This directive can be used to specifiy necessary import libraries already in a PRG source file. For example:
// File: TEST.PRG
#pragma library( "XBTBASE1.LIB" )
#pragma library( "XBTBASE2.LIB" )
PROCEDURE Main
WInit()
nWin := WOpen( 10, 10, 20, 40, .T., "W+/B" )
WSelect( nWin )
? "Hello World"
WAIT
RETURN
This file can be compiled and linked by entering on the command line:
xpp test /link
In this case, the linker is invoked by the compiler and the two pragmas at the beginning of the file instruct the linker to search two import libraries for resolving external references.
Using the ProjectBuilder
The most convenient way of compiling and linking XbToolsIII libraries is by using the Xbase++ ProjectBuilder. A project file is created as described in the Xbase++ documentation and the import libraries are added to the AUTODEPEND section of the project file following the list of PRG files. An example for a PROJECT.XPJ file is this:
[PROJECT]
COMPILE = xpp
COMPILE_FLAGS = /q
DEBUG = yes
GUI = no
LINKER = alink
LINK_FLAGS =
RC_COMPILE = arc
RC_FLAGS = /v
ROOT
[ROOT]
TEST.EXE
[TEST.EXE]
// $START-AUTODEPEND
COLLAT.CH
GET.CH
MEMVAR.CH
PROMPT.CH
SET.CH
STD.CH
TEST.OBJ
// $STOP-AUTODEPEND
TEST.PRG
XBTBASE1.LIB // <-- import libraries added
XBTBASE2.LIB
Detecting unsupported functions
There are three include files in the ..\INCLUDE directory which exist for debugging purposes only. The files _CHKBASE.CH, _CHKNETW.CH and _CHKNETB.CH are useful for compiling CA-Clipper code that calls functions of the CA-Tools III library. If these files are included, all functions will be detected which are not supported in XbToolsIII.
Restricted functions
There is a set of about hundred functions in XBTBASE1.DLL and XBTBASE2.DLL which cannot be used in XbpDialog windows. These are functions performing screen output or managing the keyboard. They can be executed either in full screen sessions or hybrid mode using an XbpCrt window. The following tables list functions restricted to text mode programs and/or XbpCrt windows:
Functions restricted to XbpCrt windows and/or full screen
| Mainly screen output functions | |||
|---|---|---|---|
| Cga40() | KbdType() | SetLines() | WfLastRow() |
| Cga80() | KeyRead() | SetPage() | WFormat() |
| CharWin() | KeySend() | SetRC() | WfRow() |
| ClearEol() | MaxPage() | SetScrMode() | WGetClearB() |
| ClearSlow() | NumCol() | SetScrStr() | WInit() |
| ClearWin() | NumColors() | SetTab() | WLastCol() |
| ClWin() | PageCopy() | Standard() | WLastRow() |
| ColorRepl() | RestCursor() | StrScreen() | WMode() |
| ColorWin() | SaveCursor() | UnSelected() | WMouseSelect() |
| Ega43() | SayDown() | UntextWin() | WMove() |
| FileScreen() | SayMoveIn() | Vga28() | WNum() |
| GetCursor() | SayScreen() | Vga50() | WOpen() |
| GetKxlat() | SaySpread() | VideoInit() | WRestScreen() |
| GetKxtab() | ScanKey() | VideoSetup() | WRow() |
| GetMode() | ScreenAttr() | VideoType() | WSaveScreen() |
| GetPage() | ScreenFile() | WaClose() | WSay() |
| GetScrMode() | ScreenMark() | WBoard() | WSelect() |
| GetScrStr() | ScreenMix() | WBox() | WSetClearB() |
| GetTab() | ScreenSize() | WCenter() | WSetColor() |
| GetWBoard() | ScreenStr() | WClose() | WSetCursor() |
| InvertAttr() | SetBoxGrow() | WCol() | WSetMove() |
| InvertWin() | SetCursor() | WColor() | WSetShadow() |
| IsHercules() | SetKxlat() | WfCol() | WSetTitle() |
| KbdStat() | SetKxtab() | WfLastCol() | WStep() |
Most of these functions do not work in a XbpDialog window. Any function performing screen output will raise a runtime error when the current window is a XbpDialog window. Functions dealing with keyboard input are not guaranteed to work as expected. Thus, we strongly recommend to use PostAppEvent() and related functions from Xbase++ when you intend to manipulate keyboard events in a XbpDialog window.
Deployment of Windows applications
When you have developed an application using XbToolsIII and it is ready to be installed at your customer's site, you must install the following DLLs together with your EXE.
Install the runtime DLLs shipped with Xbase++ together with the DatabaseEngines required by the application in a directory which is part of PATH.
If you use neither 'Novell NetWare' functions nor NetBIOS functions:
Install XBTBASE1.DLL and XBTBASE2.DLL in a directory which is part of PATH.
If you use NetBIOS functions (Point to Point Communication):
Install XBTNETB.DLL in a directory which is part of PATH.
If you use Novell NetWare functions:
Install XBTNETW.DLL in a directory which is part of PATH.
Feedback
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.