Creating the object and connecting to PixieEngine

In IIS Webserver .ASP scripts:

Dim Pixie
Set Pixie = CreateObject("PxEngWeb.clsAgent")
Pixie.TimeOut = 2 
Call Pixie.Connect(Session.SessionID)

In VB apps and VBA modules etc,
start with "Project References"
and select "PixieEngine web etc interface"

Dim|Private|Public Pixie As PxEngWeb.clsAgent
....
Set Pixie = New PxEngWeb.clsAgent
Pixie.Timeout = 2
Call Pixie.Connect(MyCustomID)

We use "Pixie" as our object name, but you can call it anything you like as long as you are consistent in your use.

"Pixie" can also be stored as a "Session Object", which gives it a continuous PixieEngine user session matching the IIS WebServer User session.  This is especially useful with field-by-field interactive web apps. 

TimeOut	 Single (ie decimals allowed) eg 4, 8, 2.5 
         Default = 3 sec
	 Time in seconds allowed to wait for PICK responses.
         NOTE, in a significant change for ver 3.2 December 2000,
         the TimeOut starts counting from the most recent chunk
         of data received from PixieEngine.
         IF for example, a long report takes 12 sec to output, 
         AND the TimeOut = 4, 
         THEN the TimeOut error fires at 12+4=16 seconds.
         ie 4 seconds after PixieEngine stops feeding out chunks.
         You can choose to ignore the error and use the value Pixie.Response, 
         and this can be a good technique in "screen-scraping" situations.

State    Returns a string to let you check the state of 
         the object, possible returned values are: 
	 "STARTUP" = not connected to PICK etc 
	 "TCL"     = connected and last execution was successful
	 "ERROR"   = error on last execution

	 PxEngWeb does NOT stop when in a state of "ERROR",
	 rather it will happily allow you to try to execute
         something else.

Call Pixie.Connect( session_identifier)
          The "session identifier" is a string to write
         into PixieEngine's "description" property to identify the
         client or client session.  We recommend that web apps use
         Session.SessionID for this.  With other apps you can give
         any custom id, good ones are descriptions of the client
         eg for VBA macros in MS Office I would use "Word", "Excel"
         "Outlook", "Access" etc.  If not required, use         "" as argument.

Call Pixie.ExecuteET(request_to_PixieEngine, expected_response)
   Or
sResponse = Pixie.ExecuteET(request_to_PixieEngine, expected_response)
	 Both arguments are strings.



         " expected_response" is any text which you would
         expect to find at or near the end of a successful
         response.  We suggest "</TX>" within VAR apps as a 
         standard end-of-transmission tag.  In TCL you would
         often use ":"          
         NOTE that PxEngWeb will add a carriage return
         CHAR(13) to the end of any request.

         The new function syntax "sResponse = ..." gives a 
         result in one process call instead of the old 2-step.
         The old "Call ..." syntax with a follow up reading
         of "Pixie.Response" is retained for PixieWeb compatibility.

Call Pixie.ExecuteTX(request_to_PixieEngine)
Or 
sResponse = Pixie.ExecuteTX(request_to_PixieEngine)
         Similar to Execute, but automatically buffers until
         it detects "</TX>".
         AND it then returns a string processed for ending 
         before "</TX>" and starting after any "<TX>"
         eg
         raw string = "Debug: ItemID=NN8088<TX>Michael</TX>"
         ExecuteTX returns "Michael"
         eg
         raw string = "John Calder</TX>"
         ExecuteTX returns "John Calder"

Call Pixie.ExecutePM(request, expected1 [, expected2 [, ...]])
Or
sResponse = Pixie.ExecutePM(request, expected1 [, expected2 [, ...]])
         Similar to Execute, but you can give a number of 
         alternative expected responses.  This is useful for
         "quick and dirty" screen scraping from raw-converted
         legacy apps.
         sResponse = Pixie.ExecutePM(sRequest, "(Y/N)", "F9=Find", Chr(27) & "=            ")

Call Pixie.ExecuteRaw(request)
	 "Request" is a string
	 With ExecuteRaw,PixieWeb does NOT check that a 
	 response from PixieEngine is complete.
         Provided only for compatibility with PixieWeb.
         New coding should use Pixie.Execute("")

Response Returns a string giving the PixieEngine response 
	 returned by ExecuteET, ExecuteTX, or ExecutePM

ResponseRaw
         Same as Response.  Provided only for compatibility
         with VARs' existing PixieWeb code.

ExecuteCompareMethod
         Sets whether end-of-transmission is to be recognised by
         a case-sensitive comparison, eg that "</tx>" is
         recognised as         a valid alternative to "</TX>".
         Default value is 0, giving case-sensitive comparisons.
         The alternative value         is 1
         eg, to allow upper or lower case end-of-transmission
         marks:
         Pixie.ExecuteCompareMethod = 1
  

WebServer file Functions: 
FileGetText, FileGetStream, LogBook

byteArray = Pixie.FileGetStream(filename_with_full_path)
         Get disk file as an array of bytes.  Useful for
         detailed manipulation and control of binary files
         such as page image and sounds, or executable downloads.

s = Pixie.FileGetText(filename_with_full_path)
         Get disk file contents as a string.  
         Especially useful for keeping control of the 
         issuing of .htm pages-as-templates by feeding them out 
         through a controlling .asp script.
         The <% = myVariable %> facility in IIS does much the
         same thing, but FileGetText gives flexibility like:
         *  Select from several templates depending on
            the situation.
         *  Enables use of the nice Response.End statement
            which does not work with the <% = myVariable %>
            technique.
         *  Use this within your compiled ActiveX .dll
            web app to get a "webclass" effect without
            the ugly "webclass" baggage. 

Call Pixie.LogBook(log_stub_name, log_message)
         Keep logs of your site visitors and their activities.
         The "log stub name" is a path plus the generic log file name.
         PixieWeb adds suffixes .. "book.txt", "bak1.txt", 
         "bak2.txt", "bak3.txt"
         eg with a "stub" of "C:\InetPub\wwwRoot\Log", you will get
         files "Logbook.txt", "Logbak1.txt", "Logbak2.txt", "Logbak3.txt"
         Logbooks are allowed to reach a max size of 32K, the limit for 
         easy reading with "Notepad", before they are moved to bak1, with 
         bak1 moving to bak2, bak 2 moving to bak3, and the former contents
         of bak3 being discarded.

eg Use of LogBook for privilege-controlled file download.

sUserID = Session("UserID")
If Vartype(sUserID) <> vbString Then sUserID = ""
If sUserID > "" Then
  Call Pixie.LogBook(Session("LogStub"), sUserID & " download Maestro") 
  Response.Redirect "http://www.mysite.com/downloads/Maestro.zip"       
Else
  'Enforce login before allowing download
  s = Pixie.FileGetText(Session("Folder") & "login.htm")
  Response.Write s
End If