A tale of 2 servers: Socket or COM.
Programming  tools: Scripting, VB6 or VB5, Other toolkits.
Scripting
VB HOWTO notes.
 - VB/ActiveX - as PICKBASIC-like environment.
 - Variables in DATABASIC and VB.
 - Driving and debugging PixieEngine Apps in the VB IDE.
How to emulate some common MV and DATABASIC practices.
 - Select Lists and "READNEXT"
 - PROCs

A tale of 2 servers: Socket or COM.

The core of PixieEngine is an "ActiveX/COM" server. To service "classic" terminal-style operation, we provide a "Socket Server" add-on with its configuration and operation built into  PxEngConsole.exe

Our recommended setup for non-web-apps is "rich client" where your VAR-App along with the PixieEngine Package is installed on every client machine and can therefore use the supplied PixieLink.exe front end or your custom front end, eg customised MS Excel, connecting via ActiveX.  We have found maintenance of such networks to be quite OK.  It is possible to script installation of new VAR-apps with such methods as .bat files triggered by desktop icons labelled "Upgrade".  There is also a  maintenance advantage of not needing to get all users off to do an upgrade or even minor adjustment to the central server. Printing is simplified, especially on a WAN.  All the Windows components are on Windows clients so you can use a Linux MySQL server as the central datastore.   And  PixieLink.exe gives you no additional charge for client front ends like terminal emulators. 
BUT client machines do need to have sufficient power: CPU 200 MHZ or better with RAM of 32 MEG or better. 

A "thin client" approach using the "Socket Server" has the advantage of staying close to the known environment of a classical MV setup.  It can service less powerful client hardware, and keeps all setup and maintenance issues concentrated on 1 or 2 servers.

Approaches can be mixed, we have set up an office where most users are "rich client", but some lower powered computers are serviced by a PixieEngine socket server.

With Web Apps, PixieEngine is installed on the webserver only. 

• Windows scripting is a quick way to get started with PixieEngine programming, do new development and try out new ideas.  Scripts can also form those parts of an app that you want to be easily configurable for each site or allow expert users to change. But note that the Visual BASIC scripting engine does not support "GOTO" or "GOSUB" so it is NOT possible to easily adapt existing DATABASIC code to script.
• ActiveX programming with the full Visual Basic Programming Language gives the closest match to PICKBASIC and therefore the best support of Legacy code.  It also provides an excellent debugging and code editing environment.  Any other programming language supporting Windows ActiveX should also be possible, although we have focussed on VB so far and not tested any others.  We believe VB6 gives only a small advantage over VB5.
  Our testing of VB7 (also known as "dot-Net") suggests that it can be useful for new PixieEngine projects,
  but some of its changes, eg the lack of support for "GOSUB", make it less useful than VB6 as a PICKBASIC
  replacement.  This may change in future, but for this release, HTML, Oracle driver and MV drivers have been
  our higher priority.

Scripting
Script support is new in PixieEngine 1.1, August 2000.
It requires only that the Windows scripting engine is available, which it will be if you have IE4 or above.  The latest VBSCRIPT and JSCRIPT package is available as a separate free download of about 0.5 MEG from http://msdn.microsoft.com/scripting
PERL should work in theory but is untested at the time of writing.
Scripts take the form of Windows text files.  See subfolder "script1" for examples. The technology and usage is very like the way .asp scripting is done in webservers.  2 main differences: 
(1) We have provided the XRun function which allows you to call Subs and Functions in other scripts, thus getting scripts to better emulate PICKBASIC Program behaviour.
(2) The PICKBASIC-like functions eg DCOUNT, FIELD, MATCHES, RREAD, WWRITE are built in to our scripting environment and so there is no need to use a dot operator.
eg .asp webserver vbscripting:  
n = Pixie.DCount(sCust, "*") 
..becomes in PixieEngine vbscripting a more familiar 
n = DCount(sCust, "*")

VB/ActiveX - as PICKBASIC-like environment

Start a project by copying our ready-made project example folder, "PxAppTemplate".  It already contains object references, the interface class "BP" and the modules "basPxLibrary" and "basPxLibAdd1 ".

Begin the VB environment by double-clicking on "PxAppTemplate.vbp"

Under project "properties":

• Change the project name from our example "PxAppTemplate" to your own project name
• Check for the "project type" of "ActiveX dll".
• Check that "Apartment Threaded" and "Unattended Execution" are checked and that they remain checked as you program and compile. You are doing server-side programming for multi-users and the "Visual" tricks and treats of "Visual Basic" are not welcome here. No message boxes or forms allowed. Stick with modules and maybe classes if you are feeling adventurous. Losing the "Unattended Execution" status is a sure sign that you have broken the server-side rules.
• Change the title name (2nd tab page headed "Make") from our "PxAppTemplate" to your own project name
• When you compile for the first time, name the target file after your project name, eg "MyProject.dll"
  THEN change the "Version Compatibility" from "No Compatibility" to "Project Compatibility".
  You can find these settings on the 4th tab page headed "Component".
• As you get near production = you have your "bp" interface class worked out, change the
  "Version Compatibility" from "Project Compatibility" to "Binary Compatibility".
  You may find it displaying your .dll here by its full path name eg  C:\MyProjects\MyApp\MyApp.dll
  Warning: this can make it difficult to transfer the project around different machines
  eg for teamwork or for taking it home to work on.  So we recommend you cut out the path identifiers
  and simplify it down to something like  MyApp.dll
• If you get warning messages about "breaking binary compatibility", take the "preserve compatibility"
  option if available, but do not be too concerned.  PixieEngine "owns" these .dlls when they run, in
  a way that overcomes most of the "dll hell" concerns which VB6 programmers can have.
  At the worst, you may need to re-register your "dll" on client machines if you drastically change
  version, but that will only apply to the one .dll and the effect does not spread to other "dlls" in the
  PixieEngine system.  Like all VB dll projects, it is a good idea to work out your interface early on
  and stick to it, even though PixieEngine does give you more freedom to change than is commonly
  the case with VB.   Do ask us if you need to know more.
  

All "programs" in your App will be "Sub"s or "Functions". Any program that you will want to be runnable as a "verb" from TCL will be a Sub with no arguments, and it will need a simple interface routine in class BP.
Eg the "buddying" interface routine for "test2" :
Public Sub test2()
Call basExamples.test2
End Sub

Look through our supplied and commented example code to get the idea.
To keep the interface small and efficient, we at PixieWare have a convention for non-web-apps
of running our programs from a standard starting point "Sub UMenu ", source code provided.
For web apps, we call our interface "Sub MainProcess "
It also makes sense to have a  "Sub Test" in  BP  and rewrite it to point to whatever you want to test. 
This lets you can run a variety of tests with no interface change issues.
eg, to test a program called "X500" which is in code module "basMyApp1"
Sub Test
Call basMyApp1.X500
End Sub

PICKBASIC-like library functions are provided by classes "PixieEngine.Port" and "PixieEngine.Functions" .
We supply source code modules "basPxLibrary" and "basPxFunctions" which give you direct use of  "RRead", "Field", "Extract " etc in your code in a PICKBASIC-like way. With VB5 or VB6, an "intellisense" feature causes a help guide to the function syntax to popup when you type in the function name plus a space or a "(". This popup is a nice confirmation that you have typed a valid library function. Eg

Note the use of "[…]" to show optional arguments.
Note a peculiarity of this intellisense, it always shows the "( …)" that go with the Call syntax, even when you are using the alternative Keyword+Spaces syntax.
Eg IInput s is equivalent to Call IInput(s)

You write your app in "bas" modules.

• You can have as many of these as you like, to organise your work into sections or to divide work among a team of programmers.
• All routines are callable from anywhere in your app unless you declare them with the "Private" keyword.
• All variables declared as "Public" at the start of a module have global scope throughout your app. This becomes the PixieEngine equivalent to "COMMON"

Variables in DATABASIC and VB.

• Our examples follow the "Implicit Variant" approach which is also the VB default. "Implicit Variant" variables are created as you use them, and they assume "type"s eg "String" or "Integer" according to how they are used. This is very like PICKBASIC and it is the easiest approach when adapting legacy PICKBASIC code.
  
  VB convention, almost religion amongst the VB community, is to start all modules, forms and classes with "Option Explicit". If you are sharing a VB system normally used by avid VB-ers and you prefer to work in a PICKBASIC-like manner, then you will need to erase these, and even get into Menu: Tools --> Options to switch this behaviour off. With "Option Explicit", all variables must be declared, usually with a "Dim" statement. The benefit of this is that keeping track of your variable names can be easier. With "Option Explicit" goes the "type"-ing of all variables with "Dim" and similar statements. Eg
  
  Dim s as String, i as Long, n as Long
  Dim sCust as String, sFieldPosn as String
  
  The VB documentation claims that "Type"-ing variables makes apps run slightly faster, but our time trials find no measurable difference.
  
  Strict type-ing is recommended for creating new apps when you are already familiar with working in this style with VB. 
  
  Classical MV-focussed programmers, or ANYONE working with large quantities of code converted with "PixieMassage",  should stick with "Implicit Variants".  It is especially important NOT to try to Explicitly type arrays.  Arrays must remain all-variant in order to work reliably when passed as arguments to subroutines.
  

• NOTE a difference between PICKBASIC and VB in this code:
  
  a = 5
  b = "5"
  If a = b Then Crt "Cross-type equality checks out OK"
  
  Most PICKBASICs we have encountered will output the message. VB won't because it encounters a "type mismatch". In such situations you need our multivalue-style boolean functions   MVBool  and   MCBool  :
  
  If MVBool(a, "= ", b) Then Crt "Cross-type equality checks out OK"
  
  The supplied automatic PICKBASIC-to-VB converter  PixieMassage.exe
  adds  MVBool, and its single-argument sister  MCBool  as needed into all IF statements.
  
  
• Visual Basic treats "", the zero-length-string, as a very different entity to numerical zero.
  Legacy PICKBASIC often uses "" as zero which can result in "type mismatch errors"
  in Visual Basic.  So we have programmed our PixieMassage.exe converter to wrap
  all arithmetic arguments in the VB Val() function which converts "" to numerical zero.
  eg
  A = B + C
  converts to
  A = Val(B) + Val(C)

For more variables examples: Start PixieMassage.exe and convert the supplied raw PICKBASIC file hardlines.txt

Driving PixieEngine Apps in the VB6 IDE (Integrated Development Environment, ie the code editor)

Start by double-clicking on your project file, eg "Px1.vbp".  That way the IDE settles on the app's home folder as default rather than its own.  We recommend this as a general rule for all VB programming, because if you start VB6 first, then open your project from Menu:File, you get the unwelcome side effect that the default or home folder becomes whatever folder contains VB6.exe, and this is not good.

A new VB6 environment will often have a small window in the centre with code, and "docked" boxes around the edge with titles like "Toolbox", "Properties".  Apart from "Immediate", these are irrelevant to the "server-side" style of programming we are doing here and it is good to get rid of them.  Right click on their title bars, and you should see a popup menu with "Dockable" with a tick.  Untick that tick with a click, then close the box.

Some good hotkeys to know:
Ctrl+R = view the "Project Explorer", Ctrl+G = view the "Immediate Window"(good for debugging)
F5 = Run, F8 = debug-step, Shift+F8 = debug-step with skip debugging of child subroutines.

Run (F5) before starting a PixieEngine session, or while still in TCL.
The F5=Run of such server code appears to do almost nothing,
but the action comes when a TCL verb sparks an entry call to class BP

To get a debug happening, you need to set a "breakpoint" to interrupt what are transient events by nature.
To do this, click in the IDE left hand margin, gives red dot marker and a red highlighting of your code line.

Never try to breakpoint on IINPUT or similar eg IIN.  These are quite tricky: it is best to test them with breakpoints
just before and after.  On reaching the line before, do F5, go to the PixieLink interface to do your input, then return
 to the IDE to continue.

When a breakpoint activates, SHIFT + F8 is the usual line step forward, with F8 if coming up to a subroutine call where you want to go along for the ride.  While in debug mode, try hovering your mouse over variable names to see their values.  You can evaluate compound expressions by highlighting them, then pressing SHIFT+F9.

While in debug mode, you can press CTRL+G to get the "Immediate Window" if not already there.
You can evaluate expressions by typing them in, starting with a question mark, then press Enter: eg

? FIELD(MYVARIABLE, " ", 1)

And you can change the names of variables on the fly ..eg

MYVARIABLE = 7

If you don't like how the code is running, you can mouse-drag the yellow place marker BACK UP the routine,
re-write code and run lines or blocks again.  We believe VB5 and VB6 are still the only IDEs that can do this.
At the time of writing, Microsoft have lost this capability from VB7 although they do say they are working on 
a comeback in a future version.
You can save those rewrites after your next stop, providing you don't crash in the meantime, so if you are rewriting on the fly, it pays not to stretch out such debugging sessions for too long.

While in debug mode, press F5 to resume normal running.

Hint: To get to know the VB IDE, run the source code supplied with our Example PxApp1.

ONE-STEP method with the new ExecutePS function
This new method sets up a 2-dimensional "SelectResult" property directly from an SQL SELECT statement. For resource-safety reasons, we currently have it limited to reading of 1 Million string characters of data.

sRet = ExecutePS("SELECT * FROM PROD WHERE A1 LIKE '%CARD%';")
nColumns = Extract(sRet, 1)
nRows = Extract(sRet, 2)
For i = 1 to nRows
  sTemp = SelectResult(0, i)
  For j = 1 to nColumns
    sTemp = sTemp & ", " & SelectResult(j, i) 
  Next j
  Crt sTemp 
Next i  

Or, getting more real and reporting on attributes of interest ..

sRet = ExecutePS("SELECT A0, A1, A2, A34 FROM PROD WHERE A1 LIKE '%CARD%';")
nRows = Extract(sRet,2)
For i = 1 to nRows
  sTemp = SelectResult(0, i) & ", " _
  & SelectResult(1, i) & ", " _
  & SelectResult(2, i) & ", " _
  & OConv(SelectResult(3, i), "MR2")
  Crt sTemp
Next i

Select Lists and "READNEXT": Classic-BASIC-compatible approach with PixieEngine READNEXT

A PixieEngine SelectResult with only one column dimension is effectively a Select List in the form of an array.  If you issue a query, you can then move through that array with PixieEngine's ReadNext statement.  This approach is designed to closely match classic BASIC and is the result PixieMassage.exe gives on automatic conversions.  It can also handle large queries better than the one-step method from above.

DataBASIC / PICKBASIC
OPEN "PROD" TO PROD.FILE
EXECUTE 'SELECT PROD WITH DESCR = "[CARD]"'
LOOP
  READNEXT ItemID ELSE EXIT
  READ S FROM PROD.FILE, ITEM.ID
  CRT S
REPEAT

Visual Basic/PixieEngine
OOpen "PROD", PROD_FILE
ExecutePS "SELECT PROD WITH DESCR = ""[CARD]"""
Do 
  If Not ReadNext(ItemID) Then Exit Do
  RRead S, PROD_FILE, ITEM_ID
  CRT S
Loop

Note: New in PixieEngine 2.1 is the ability to interpret PICK-like query syntax for all datastores.
Note: That VB does not have PICKBASIC's feature of alternative quote marks,
so a quote within a quote needs to be represented as a doubling-up like ""[CARD]"".
PixieMassage handles this automatically for you.

Select Lists and "READNEXT": Recordset and MoveNext

Programmers with a VB background, may like to work with "Recordsets" which are the nearest
VB equivalent to "Select List"s. Looking here at a direct comparison.

DATABASIC
OPEN "PROD" TO PROD.FILE
EXECUTE 'SELECT PROD WITH DESCR = "[CARD]"'
LOOP
  READNEXT ItemID ELSE EXIT
  READ S FROM PROD.FILE, ItemID
  CRT S
REPEAT

Visual Basic/PixieEngine
Dim rstProd As ADODB.Recordset
...
Call RsOOpen("SELECT A0 FROM PROD WHERE A1 LIKE '%CARD%'", rstProd)
Do
  ItemID = rstProd.Fields(0)
  RRead s, "testpxe1.prod", ItemID
  Crt s
  rstProd.MoveNext
  If rstProd.EOF Then Exit Do
Loop

The advantage of this method is that this object, a "Static Recordset", has more methods available than "MoveNext".  eg "MovePrevious","MoveLast", "MoveFirst" and "Find". 

Emulating common practices continued .... PROCs

Our thanks to PixieEngine VAR John Probst for his contribution of a PROC interpreter.
This appears inside your apps as "Sub PXPQPROC" in "basLibAdd", but shows its face to TCL as stub interface routine "Sub ProcProcess" in class module "BP".

Note that unlike PICK-etc, this PROC handler is part of your app, rather than part of the global environment.  This mainly affects PROCs in file/table MD, (or VOC).  You need to tell PixieEngine the name of your app as the master handler of PROC VERBS.  You do this with a line in file "PixieEngine.ini".  eg if your app is called "pxappmx " :

[ProcProcess]
ProcProcess=run pxappmx.bp procprocess

Inside your app, you can run PROCs by calling PXPQPROC with the proc-table/filename,space,item-identifier as a string argument. 
eg  Call PXPQPROC("PROCS MEMBERS")
An argument without spaces causes PXPQPROC to look for that argument as an item identifier within "MD" and "VOC"
eg Call PXPQPROC("MEMBERS")

At this time of writing, 09 Aug 2002, PXPQPROC handles a subset of the PROC scripting language.  Areas on the TODO list include branching commands like IF and G (goto).  Any procs going to that level of programming are presently best hand-translated into VB subroutines.

Top      Next = Chapter 4: Web App Example PX2      Contents