PixieEditor Documentation

PixieEngine(TM) 2.1 - a PICK etc emulator

Chapter 1 - Overview (this document)

• Introduction
• VAR-programming overview.
• WebServer / VBA/ COM Programming
• DataStore overview.

Chapter 2 - To install, configure and test-run

• To Install
• After Setup - guide to your resulting PixieEngine folder.
• Terminal emulator setup.
• Suggested testing activities and guide to the example programs.

Chapter 3 - VAR programming

• A tale of 2 servers: Socket or COM.
• VB/PixieEngine Project organisation and Language notes.
• How to emulate some common MV and DATABASIC practices.

Chapter 4 - Batch-Submit web apps and Example PX2

• Setup and Running of Example PX2
• Commentary on PX2 and PixieEngine's batch methods.
• Other batch-submit issues: Item/Record Locks, User tracking.

Appendix 1 - Technical Reference: PixieEngine Functions and Data Transfer

• System Variables and Conventions
• Classical Terminal/Printer I/O, "IInput", "PPrint", "Crt"
• File I/O "RRead", "WWrite" etc and the new "RReadTR"
• ExecutePS
• String and other utility functions eg "DCount", "Field", "OConv", "Locate"
• Data transfer with "admin".

Appendix 2 - PxEngWeb interface for some Web Apps and COM Clients

• Use PxEngWeb, the "PixieEngine Process Buffering Agent", when you have hosted
  VAR programs in the PixieEngine environment which "talk with the user" in the classical
  way with IInput and Crt/PPrint statements.

PixieEngine configures various database engines, eg 'MySQL', 'MS SQL SERVER', 'ORACLE', 'MS JET/ACCESS'  to act in a "PICK-like" way, including working with existing PICK-etc data copied into them. PixieEngine also provides a host programming environment in Visual Basic with a PICKBASIC-like flavour. Other languages are also possible.
PixieEngine also works with these MV Datastores:  'PICK', 'MVBASE', 'ULTPLUS', 'UNIDATA', 'UNIVERSE'.
What it does for them is provide programming in server-side Visual Basic with our Web App and Gui libraries, and close integration with modern Windows practice.  Our "Field-by-Field" Web App framework is especially suitable for modernising existing PICKBASIC apps. 
PixieEngine is Windows software at present.  Datastores can however be on other machines which can be any suitable OS. 

We use MS Access/Jet .mdb files. as a lightweight prototyping demo and test alternative.  Access/Jet also makes for an easy-to-setup download package. You can try Access/Jet immediately whereas it takes additional steps to get a Server Engine going.  However MS Access is less effective at emulating MV than the true server engines.  So please use one of them for any serious performance assessment.

What "Microsoft Access" does make possible is the wrapping of some of the PixieEngine functions into file "testpxe1.mdb" as VBA code. This means that "testpxe1.mdb" acts as a self-contained "quickie" demo of some of PixieEngine. You need "Access 97" or newer to open it. If reading this with internet access, click here to download testpxe1.zip (only 100K) .

Note sample data is fictional, especially the randomly generated prices.

The PixieEngine package includes:

• PixieMassage, for converting legacy DATABASIC programs
• PixieEditor, which can convert data from some classic MV engines.
• PxEngLink (based on our PixieLink), a GUI-capable front end which can also handle classical terminal emulation.  

There are 3 licensing levels for PixieEngine:

1. PixieEngine Personal Edition - developer/personal licence is free of charge.
   Restricted to JET/ACCESS datastore only and 2 users max.
2. PixieEngine Special Licence - economically-priced light-duty system.
   Restricted to JET/ACCESS datastore only, but we impose no limit on the number
   of users.  We rely on the JET/ACCESS limitations.  In practical terms this
   means a max of 5 simultanous heavy-demand users up to about 20 light-demand.
3. PixieEngine Full Industrial-Strength Edition.  Any datastore, no user-number limits
   (apart from those imposed by some datastores).

Pricing of 2 and 3 is by negotiable quote for each situation and is usually a single price for unlimited use within a site or organisation with a support package built in..

PixieEngine's equivalent to PICKBASIC is to program with Microsoft VB5 or VB6 by creating your app as an ActiveX .dll, instances of which get hosted inside PixieEngine's "UserPort" objects. We provide a template app to copy and adapt. In theory any Windows development environment that can talk to ActiveX objects should work as a VAR-Programming method, but VB is close enough to PICKBASIC that a high degree of automatic conversion is possible.

VB5/6 has a very attractive editing and debugging environment. The obvious question is "big change from DATABASIC ?" but VB is a very "extensible" system and we have done 2 things to bring it close to DATABASIC:

1. Provided the option of retaining the DATABASIC procedural model, ie Input and Output can still be achieved within programs by IInput, Crt and PPrint, and you do NOT need to follow the usual VB client-side "event-driven model" of 1-user-action = 1-complete-routine-run.
2. Provided a library of DATABASIC-emulating functions
   eg EXTRACT, RREPLACE, OOPEN, CCLOSE, RREAD, WWRITE
   TTAG (equivalent of @), FIELD, DCOUNT, LOCATE, INDEX,
   MATCHES and growing ...

eg DATABASIC

OPEN "cust" TO File.Cust ELSE
  CRT 'Cannot open file "Cust".' 
  STOP
END
** dynamic variables
A<3,4> = B
C = D<1,2,3>

translates to VB

If Not OOpen("cust", File_Cust) Then 
  Crt "Cannot open file ""Cust""." 
  Exit Sub 
End If 
'* dynamic variables
A = RReplace(A, 3, 4, B)
C = Extract(D, 1, 2, 3)

We have written a utility "PixieMassage" which does such conversions automatically. Note that VB and the DataStores have their own reserved purposes for "dot" and "hyphen" operators. So in most cases, DATABASIC and TCL file, variable and routine names like "File.Cust" and "BP.WEB"  get changed eg to "File_Cust" and "BP_WEB".

"PixieEngine" handles most required PICK emulation.  With version 2.1 we offer some major advances in automatic conversion, the main one being handling of PICK-etc LIST, SORT, SELECT, SSELECT, and QSELECT queries.
An example remaining challenge is handling GOTO into and out of INCLUDEd code. At present, setting common variables and values in INCLUDEs is no problem, the Visual Basic "Procedure Header" with Public variables does much the same thing. But you do need to convert INCLUDEs which are coded processes, to subroutines.

There are 2 approaches:

1. "The Non-Persistent Microsoft Way" where all programs involved are
   subroutines running to completion when the user takes some action on the web page
   or other client.  In-between calls, you need to store variable values and "states" in the
   database, or on the client, or in a Webserver "Session Object".  Clients and middleware
   objects use PixieEngine as a PICK-style data provider.  User Interface programming is
   quite different to PICK-style terminal programming, but you can convert and re-use
   non-interface PICKBASIC routines.
   Such Apps are commonly VB clients making use of VB's built-in form-drawing capability
   with event-driven input fields.  This approach also includes custom programming
   of ready-made front ends eg  Microsoft Excel, Microsoft Word.
   
2. "PICKBASIC-style, Persistent-allowed", where server programs can keep talking to clients
   eg with "IInput" and "Crt"/"PPrint" statements.  We have solved the problem of
   a almost philosophical incompatibility between PICK and Windows practice by
   placing a "process buffer" between the Webserver etc and PixieEngine.
   To work this way, and have the full use of both Windows and PICK-style programming,
   you work with object "PxEngWeb.clsAgent ", the "PixieEngine Agent" rather than directly
   with "PixieEngine.Port ".  Such Apps are mostly web-apps which support
   field-by-field validation, or which emulate the PICK-etc web interfaces like "Flashconnect"(TM)
   "RedBack"(TM) or "Coyote"(TM).

Example 1: ASP SCRIPT fragment for the "Non-Persistent Microsoft Way"

Set P = Server.CreateObject("PixieEngine.Port")
Set F = Server.CreateObject("PixieEngine.Functions")
'** Login user "jeffrey" with a password of "biscuit"
Call P.ExecutePS("LOGIN jeffrey biscuit")
If P.OOpen(Cust, File_Cust) = False  Then
  Response.Write "Cannot open file 'Cust'."
  Response.End
End If
'** PixieEngine supports dynamic variables"
A = F.RReplace(A, 3, 4, B) 'was A<3,4> = B
C = F.Extract(D, 1, 2, 3) 'was C = D<1,2,3>
…

Example 2: Similar ASP scripting but supporting a mostly PICK-style app.
All data handling and processing happens in a PICK-like way in the
separate PixieEngine environment.  Pixie.Execute represents a conversational
step where this script talks to INPUT statements in your app and gets its
responses back via CRT.

Set Pixie = Server.CreateObject("PxEngWeb.clsAgent")
Pixie.TimeOut = 30 
Call Pixie.Connect(Session.SessionID) 
Call Pixie.ExecuteET("jeffrey", ":")
Call Pixie.ExecuteET("biscuit", ":")
If Pixie.State = "ERROR" Then Call AppExit
Call Pixie.ExecuteET("logto myaccount", ":")
sResponse = Pixie.ExecuteTX("RUN MYAPP.BP MAINPROCESS " & Request.Querystring)
If Pixie.State <> "ERROR" Then
  Response.Write sResponse
Else
  Call ErrorHandler("ERROR: in App 'MyApp' ", sResponse)
End If

Click Here , for a full-length example

"Accounts" are emulated by "databases".

• In MySQL these are separate subfolders off MySQL folder "data". 
• In MS_SQL Server each "database" is a Windows file.
• In "Access/Jet" they are separate .mdb files in folder C:\Program Files\PixieEngine\JetMDB\
• In "ORACLE" they are "schemas" within one "data source" or "instance" for PixieEngine work

"Files"( aka "Tables") feature:

• Two types of files/tables are offered:
  Type C (Columns type) is the default.  Each "attribute" becomes a defined field in
  the new datastore.  Field Names are  A0, A1, A2, A3,...
  Type N (no-columns) is to cover the limitations of MS-Access (255 columns max)
  and MS-SQLServer (1024 columns max and reduced performance with more than
  about 600 columns).  A Type N table/file has only 2 fields: A0, and ITEM.
  ITEM is a LONG VARCHAR, TEXT, MEMO or CLOB field which can contain
  items as long strings with CHAR(254) characters separating the attribute values.
  A Type N table/file is therefore close to classical PICKetc data storage.
  Type N is fast for straight reading of items, but has disadvantages when doing
  searches and queries based on attributes other than A0.
  
• For both Type C and Type N, A0 is defined by default as a 25-character
  indexed "Primary Key" so it simulates the MV "ItemID"
  
• "CREATE-FILE " and other table/file building methods, eg PxAdmin, PixieEditor, start with columns
  other than A0 as long-text capable by default.  You can choose to "tune" for indexing and/or
  performance by re-defining columns as numeric, date etc, or shorter VARCHAR lengths.
  Our Pixie utilities automatically scan all data in an MV file first, then depending on the datastore
  and the sample size will optimise column widths.  EG if PixieEditor finds the length of the longest
  Attribute-5 to be 20 characters, and there are more than 500 items to base an automatic
  decision on, then it will define A5 as a VARCHAR(30) giving 50% of "headroom".
  
• Type C tables/files do NOT share the PICKetc capability of increasing the
  number of attributes in an Item at any time. The expected number of attributes must be
  declared when creating the file/table and if you need more later, you need to do
  "ALTER TABLE ...MODIFY ..." or similar.
  NOTE our TCL function "CREATE FILE" where the number argument
  may look like an MV "modulus" but is really the number of attributes
  allowed for: eg " CREATE-FILE PORD 55 D"
  
• Most DataStores work with Microsoft Access as the front end program, so much so that we have provided only a limited TCL environment.  We intend that most TCL-admin-like tasks eg queries, editing, would be done via the Access front end. (NOTE that the "Access" visible front end program is a separate component to its associated "Access/Jet" data storage method. The visible front end is applicable to and useful for MySQL
  and MS_SQL_SERVER)
  
• Dictionaries are optional. Where used they are identified by "_dict"
  added to the file name eg "prod" has a dictionary "prod_dict".
  
• "md" files currently support their "pointer to compiled program" function with more emulation planned.
  
• Database/account/schema "dm" currently provides the "users" file with similar behaviour to MV equivalents.
  "dm" also provides a "locks" file used by RREADU etc, as well as stored procedures (programs inside the database in its own programming language).  In Datastores with user permission issues, eg MS SQL Server, Oracle, you need to give all PixieEngine users read/write access to "dm" as well as their usual working database/account/schema.

Description of Data Stores:  D3, UV and other MultiValue

New in PixieEngine 2.1 is its ability to provide VB or other modern programming environments for MV datastores.
To run in these modes you need to:

• Load PX.BACKSRV, supplied as PICKBASIC source code, into your datastore; compile and catalog it.
• Study carefully the conversation you use to get into TCL, and write all the steps into the config window provided in the console app. (PxEngConsole.exe)

CREATE-ACCOUNT, CREATE-FILE and other such admin tasks retain their classic syntax.  Such operations are best done through a traditional terminal interface.

QUERIES work differently. 

To get query results in with each cell as a separate value, use the PICK-like syntax:
  Call ExecutePS("SELECT ...")  or  Call ExecutePS("SSELECT .. ")
followed by coded READNEXT loops.

You can also run: 
  sQuery = ExecutePS("LIST ...") 
  sQuery = ExecutePS("SORT ...")
It is a good idea to include limiting options in your queries, eg D3's SAMPLING 500

Top      Next = Chapter 2: Installation...      Appendix - keyword reference