Windows Scripting in AnzioWin

Introduction

Both AnzioWin and Anzio Lite have the capabilities of being controlled to some extent from the host by sending commands. 

Likewise, AnzioWin includes a basic macro language that allows you to define a certain key or key combination, to run a small one-line macro. This works very similar to host-end scripting and encompasses both macros and keyboard remapping.

Two other issues to be covered in the scripting field are  a) can a script control Anzio and b) can Anzio do more sophisticated scripting (end-user programming if you will)?

Both of these are to be answered in our current release of AnzioWin, using Microsoft's Script Control. Script Control is an ActiveX control from Microsoft that provides a way of adding scripting to an application. Script Control is an easy to install set of script utilities that allow extensive user programming capabilities to AnzioWin.

What you need

There are various components that must be in place for this to all work smoothly, but the functionality is well worth the little effort to install these. At this time, all of these components are free, most are installed by Internet Explorer (version 4 or later), and Windows 2000 ships with some of them in place. However, we recommend you download the latest versions from Microsoft.

All of the needed components can be downloaded from the Microsoft Script Technologies web pages at the Microsoft web site The packages are:

Windows Script 5.5 or later        
This is the script engine and script component available from Microsoft. Included in the package is support for WSH (Windows Script Host), VBScript (Visual Basic Script) and JavaScript.

Additional third party script engines are available, i.e. PerlScript.

Microsoft Script Debugger         
Debugging scripts can be painful, since they are edited in something like NotePad and run without a user interface. Microsoft has developed a free-standing script debugger that you can use with the Microsoft provided script engines from above (I have not tested it with 3rd party script engines).

Microsoft Script Control   
This is the ActiveX Control component required to make scripting available to other applications.
You may have to register with Microsoft to download some of these components, but so far they are all free. 

At the Microsoft web site are numerous documents and support pages for the Scripting Technologies Microsoft is providing. We also recommend a couple of books that are quite useful when doing non-browser related scripting. These are worth having around if you are to do any scripting for automating Anzio functions.

How it works

First off, AnzioWin interacts with the Script Control engine to start a script (using one of the Windows registered script engines) and runs a single routine at a time. A string argument can be sent to the script module and a command string returned from the script module. It is then up to the script module as to what the returned string does. AnzioWin runs it as if it were a command for it to take action on, either to send it to the host, run it as a command or perform a required function.

Second, AnzioWin will respond to an external script controlling it in a basic way, by responding to keystrokes pushed at it. In fact if you have loaded the Microsoft script engine, you will be able to make this work on your current AnzioWin or Anzio Lite. See below for more information.

Scripting Within Anzio

Within AnzioWin

A new command has been added to AnzioWin to allow a script to run. This script can be built as part of an AnzioWin macro for startup or user initiation, or it can be a command either issued from a host script or ran manually from within AnzioWin.

The command is "script" and is done as an AnzioWin function right now (this may change in the future). You initiate this from the Function line or from within a macro (do a Ctrl-Shift-f to bring up the Function line).

The general format is:

script <filename> [E:<lang>] [M:<module>] [T:<timeout>] [<args>]

with defaults being "E:vbscript", "M:Main" (main), "T:0" (no timeout). Some examples:

script
script c:\anzio123\script\demo.vbs
script c:\anzio123\script\demo.vbs m:AnzioReturn
script c:\anzio123\script\demo.vbs m:HostReturn test argument

"script" by itself is a debugging option (see notes below).

You can pass arguments to a particular module by including the argument as part of the string. This can be anything you wish and continues from the last option till the end of the line (or to a carriage return inside a macro).

The returned value is nothing more than a string for Anzio to process as if you were giving it a command. If you need to send something from the script to the host you can, if you need to capture a screen (screen scrape) you can, if you need to shutdown AnzioWin you can. Again, any command that can be embedded in an AnzioWin macro, can be returned back to AnzioWin from the script module.

A list of available commands to issue back to AnzioWin can be found in the Anzio manual.

Within the Script

There are basically two types of modules (chunks of code) within a script, a Function or a Procedure. Either of these two optionally can be passed a string containing some argument. The difference between the two is that a Function will return some value to AnzioWin, while a Procedure will not. What AnzioWin does with a returned value is totally dependent on the content of the returned string. It comes in to AnzioWin as a command.

Since Visual Basic is easy to read and understand, these examples will focus on VBScript. You do need to watch your character case, some script engines are very case sensitive, as an example when giving the script module name in the script command, be sure to have the correct upper and lower case.

The following script is a small, one Procedure script you can type in via Notepad. Save it as demo1.vbs. In this example, the script simply displays the PC date:

Sub Main()
   Const TITLE = "AnzioWin Test"
   Dim MyDate
   GetDate MyDate
   Msgbox("Today is " & MyDate, vbInformation, TITLE
End Sub
Sub GetDate(X)
   X = CStr(Date())
End Sub

Within AnzioWin do the following command from the Function line (either example should work as the default procedure is "Main"):

Ctrl-Shift-f
script c:\anzio\demo1.vbs m:Main     OR
script c:\anzio\demo1.vbs

A one Function script example is below. This one accepts an argument from AnzioWin as well as returns a  command to AnzioWin to change its Window Title.

Function AnzioReturn(X)
   Call Msgbox("I received " & X & " from Anzio, thanks.",       vbInformation, TITLE)
   X = "title This Is The Test Title"
   AnzioReturn = X 
End Function

Within AnzioWin do the following command:

Ctrl-Shift-f
script c:\anzio\demo1.vbs m:AnzioReturn HI THERE!!!

See further examples below.

Scripting To Control Anzio

While AnzioWin does not directly interact with a script running it, the Microsoft scripting technologies can be used to control the basic features of AnzioWin or Anzio Lite. By responding to typical keystrokes pushed at it over a timed interval, AnzioWin and Anzio Lite will respond and can be controlled by simply passing it keystrokes.

The sample below is a simple script that starts AnzioWin, logs in using a the current PC's logged in username, passes the password from the command-line to the host, does a file transfer and then exits without any user intervention. It could then manipulate the file as necessary, etc. To start this macro, do the following (or set up a batch file to start the script):

wscript //e:vbscript anziocontrol.ws <password>

The script is a basic Windows Script Host script (see reference material on Windows Script Host mentioned above):

Set WshShell = WScript.CreateObject("WScript.Shell")
Set WshNetwork = WScript.CreateObject("WScript.Network")
Set WshFs = WScript.CreateObject("Scripting.FileSystemObject")
Set ObjArgs = WScript.Arguments

strAnzio = "anzio32"
strArg = " c:\anzio\host1.def"
strFile = "testfile"
strPath = "c:\temp\"

if ObjArgs.Count > 0 then
   strPasswd = objArgs.Item(0)

   if WshFs.FileExists(strPath + strFile) then
      WshFs.DeleteFile(strPath + strFile)
   end if
   WshShell.Run strAnzio + strArg 
   WshShell.AppActivate("Anzio32") 

   WScript.Sleep 1000 
   WshShell.SendKeys WshNetwork.UserName + vbLf
   WScript.Sleep 1000

   WshShell.SendKeys strPasswd + vbLf
   WScript.Sleep 500

   WshShell.SendKeys "%TD" + strPath + "{enter}"
   WScript.Sleep 500

   WshShell.SendKeys vbLf + "sz " + strFile + "{enter}"
   WScript.Sleep 5000

   if WshFs.FileExists(strPath + strFile) then
      WshShell.SendKeys vbLf + "exit" + vbLf
   else 
      MsgBox "File " + strPath + strFile + " did not transfer"
   end if
else
   MsgBox "No Password given"
end if

Sleep timers may have to be adjusted to make sure they are long enough.

Debugging Notes

"script"

"script" by itself is a debugging option where you can take a look at valid modules in your script,  and you can run some simple testing. However, this does not replace the Microsoft debugger which works great as a standalone utility for testing your script.

When you first do a Ctrl-shift-f in AnzioWin and enter "script" it will bring up the following dialog. You can choose the script file to debug and then it will reflect the number of modules and whether they have arguments.

With the second dialog, you can select one of the module names and Anzio will attempt to run it, asking for argument parameters where required.

Microsoft Script Debugger

With Microsoft's debugger you have to take a slightly different approach. It is designed to work with the script engine directly, not through AnzioWin. The simplest method of utilizing this is to set up your vbscript file to be a normal script file (a main section that calls your various procedures to test). The main section of code can call your Main procedure, which in turn calls the other modules, etc.
To start a script manually, you go to an MS-DOS Prompt Window and use cscript or wscript:

cscript <script file name>

To turn on debugging, do

cscript //X <script file name>

The Microsoft Script Debugger will come up and allow you to step through your script one line at a time. For more information on the Script Debugger and cscript, see the Microsoft web site.

Examples

Example 1

The one script below, demo.vbs, contains several Functions and Procedures that can be called at different times by AnzioWin.

'***********************************
' VB Script Demo for Script Runner *
'***********************************
Const TITLE = "Script Runner Demo"

Sub Main()
   Dim MyDate
   Select Case Msgbox("Hello! Do you want to know the Date ?", _
        vbYesNo + vbQuestion, TITLE)

   Case vbYes 
      GetDate MyDate
      If Msgbox("Today is " & MyDate & vbCrLf & "And also want to know the time ?" & _
             vbCrLf & "Dont say no or I will Raise an Exception !!!", _
             vbYesNo + vbExclamation + vbDefaultButton2, TITLE) = vbYes then
         Msgbox "The time is " & GetTime(), vbInformation, TITLE 
         Msgbox "See ya!!" 
      Else
         Err.Raise 1000, "Script Runner Demo", "Refuse to get time error :)"
      End If
   Case vbNo
      Call Msgbox("Bye!!", vbInformation, TITLE) 

   End Select
End Sub

Sub GetDate(X)
   X = CStr(Date())
End Sub

Function GetTime()
   GetTime = CStr(Time())
End Function

Function MyGetDate(X)
   X = CStr(Date())
   Call Msgbox("Here is myGetDate Routine, Bye!!", vbInformation, TITLE)
   MyGetDate = X ' return the X string
End Function

Function AnzioReturn(X)
   Call Msgbox("I received " & X & " from Anzio, thanks.", vbInformation, TITLE)
   X = InputBox("Please enter command to return to Anzio")
   AnzioReturn = X ' return the X string
End Function

Function HostReturn()
   HostReturn = "send """ & Cstr(Time()) & """"
End Function

Function HostReturn2()
   HostReturn2 = "send " & chr(34) & Cstr(Time()) & chr(34)
End Function

Note that the above example contains several modules. These modules can call each other or be standalone. When called from AnzioWin, a single module is accessed at a time, but any one of them can be called. As an example, to call the Function routine AnzioReturn, you would do

Ctrl-shift-f
script c:\anzio\demo.vbs m:AnzioReturn Test Argument #1

and this would return whatever command the user puts in the vbscript input box, i.e. if they entered "title AnzioWin Test Title", then AnzioWin would change its default window title.

Example 2

A real world scenario: One of our clients in Australia has a need to scrape the screen, parse the data and depending on the screen they are on, do a custom address label comprised of data from the screen. The script to do this and the macro for AnzioWin are included below.

What the script does is to open a file, capture the screen, close the file and then scrape the captured screen to produce a label for a library circulation desk:

Const TITLE = "Innopac Patron Screen Parser Script Demo"
Const strFilename = "c:\anzio\adrtemp.txt"

Sub Main
   ' Setup procedure for debugging
   Select Case Msgbox("Hello! Do you want to continue? ", vbYesNo + vbQuestion,$
   Case vbYes
       DoLabel
   Case vbNo
       Call Msgbox("Bye!!", vbInformation, TITLE)
   End Select
End Sub

Sub DoLabel
   Const ForReading = 1, ForWriting = 2, LabelLength = 8
   Dim arLbl(8)
   Dim strSearchFor
   Dim strAddr, strName, intIsScreen
   Dim intIndex1, intIndex2, intA
   Dim intULines, intUFile, intLblOffset, intLblTemp
   Dim fso, ts, ps
   Set fso = CreateObject("Scripting.FileSystemObject")
   Set ts = fso.OpenTextFile(strFilename, ForReading)
   arLines = Split(ts.ReadAll, vbCrLf)

   ' Note: Arrays start at 0

   ' Search for "PATRN NAME" first, on line 7 (7 - 1) (Alternate Page 1st)
   strSearchFor = "PATRN NAME"
   strTemp = arLines(6)
   intIndex1 = InStr(1, strTemp, strSearchFor)
   intUFile = UBound(arLines)

   ' If it is the Alt Page, assume we need to parse line 8 into addresses
   if intIndex1 > 0 Then
     ' set the intIsScreen to true
      intIsScreen = 1
      strName = Mid(arLines(6), 18, 38) 'Name
      strAddr = Mid(arLines(7), 18, len(arLines(7)))
      arAddr = Split(strAddr, "$")
      intULines = UBound(arAddr)
      ' Call MsgBox("Number of lines in file: " & intULines+1, vbInformation, TI$
      'we need to center the label in the 8 lines we have to print on
      intLblTemp = (LabelLength) - (intULines+3)
      If intLblTemp > 0 Then
         ' if we're going to run tinto computational problems (not likely thoug$
         intLblOffset = Int(intLblTemp/2)
      Else
         ' then brute force this instead of trying to compute it
         intLblOffset = 0
      End If
      'now we copy the data across
      arLbl(intLblOffset) = strName
      for intA = 0 to intULines
      arLbl(intA + 1 + intLblOffset) = arAddr(intA)
      Next
   Else
      ' We need to check its the more screen
      strTemp = arLines(1)
      intIndex2 = InStr(1, strTemp, strSearchFor)
      If intIndex2 > 0 Then
         ' otherwise assume we assume main page and we need
         ' lines 3 thru 5 and name 
         ' set the intIsScreen to true
         intIsScreen = 1
         arLbl(2) = Mid(arLines(1), 13, 38) 'Name
         arLbl(3) = Left(arLines(2), 38)
         arLbl(4) = Left(arLines(3), 38)
         arLbl(5) = Left(arLines(4), 38)
      end If
   End If

   ts.Close

   ' Now print label according to number of address lines
   if intIsScreen = 1 then
      intULines = UBound(arLbl)
   ' Print label for alt page
   Set ps = fso.OpenTextFile("LPT1:", ForWriting, True)
   for intIndex2 = 0 to intULines
      ps.Write(arLbl(intIndex2) & vbNewLine)
   Next
   ' Do a FormFeed just for test to print page on my printer
   'ps.Write(vbFormFeed)
   ps.Close
   end if

End Sub

Function OpenFile()
   ' Open a temp file for screen scrape
   OpenFile = "openo/n " & strFilename
End Function

Function ScrapeScreen()
   ' Scrape screen in to a file
   ScrapeScreen = "keep"
End Function

Function CloseFile()
   ' Close temp file
   CloseFile = "closeo"
End Function

From within Anzio, create a macro (all on one line):

F6script c:\anzio\adrlabel.vbs m:OpenFile |
F6script c:\anzio\adrlabel.vbs m:ScrapeScreen |
F6script c:\anzio\adrlabel.vbs m:CloseFile |
F6script c:\anzio\adrlabel.vbs m:DoLabel

Example 3

Script Engines are typically not full implementations of the particular language, but only partial. They are also limited by the form/dialog handling that is available. Various vendors and some freeware modules add forms capabilties to the script hosts, by allowing you to create Visual Basic forms that can then be called from within a vbscript. This provides the simple user a high-level way of creating user interfaces for your script, and hence adding even further functionality to AnzioWin.

Now the big question, how? Most approaches use ActiveX Controls. Set up a Visual Basic ActiveX component and you can call the component from your script engine. There are several such interface modules currently available over the web. We are working with a couple to provide you some recommended flexibility. However at this time, we are not familiar enough with them to recommend one or to provide an example. 

Conclusion

Microsoft's Script Control and Script Engines are very flexible and add a great deal to AnzioWin.
The limitations:

• No custom dialogs, they usually only support basic message boxes. However, you can write your own applications to interface to AnzioWin and the host.
   
• Issues due to security levels. Scripting was originally designed to be ran from within web pages and hence is limited in overall access. Depending on security issues for various browsers and various versions of Windows, you may run into problems reading and writing from certain files.
   
• Debugging is sometimes difficult.
   
• No concept of global variables. No variables can be kept and passed from routine to routine.

The advantages:

• Adds if-then-else and case statement capabilities to AnzioWin.
   
• Adds string and file manipulation to AnzioWin.
   
• Provides a well-documented set of rules (there are numerous books out there on VBScript, JavaScript and WSH support from web browsers, and the approach in AnzioWIn is similar).
   
• Adds object oriented calls to AnzioWin through the script engines (design of your own objects and user interfaces is possible).

So, while a little cumbersome at present, Microsoft's Script Control is worth the effort if you have specific programming needs.