Novell is now a part of Micro Focus

Using AppWare To Automate PerfectOffice Applications

Articles and Tips: article

STEVE BOWEN
Software Engineer
AppWare Systems Group

01 Sep 1995


Novell AppWare can be used to automate PerfectOffice applications. This automation includes playing macros, as well as activating one or more features of a PerfectOffice application. PerfectLinks is the general term for a set of ALMs used to access the various applications in PerfectOffice. The PerfectScript ALM is used to establish the automation link with an application. With this ALM you can use AppWare to play a file or template "script" (macro), check for the existence of persistent variables, play macro product commands, or query the state of an application using system variables.Whether you are automating WordPerfect, GroupWise, or Presentations, the syntax and construction of your PerfectScript application is the same. You need only identify the target application you wish to send commands to.

Introduction

Novell AppWare can be used to automate the applications - WordPerfect, GroupWise, Quattro Pro, and Presentations - in PerfectOffice. This automation includes playing macros, as well as activating one or more features of a PerfectOffice application, such as entering text or saving files.

A common use of AppWare is as a "front-end" to automate other Windows programs. Various techniques are used to accomplish this automation, including DDE, SendKeys, and in some instances, OLE 2.0 Automation. In other words, the "front-end" application controlling the automation sequence is the client; the program being automated - such as WordPerfect or GroupWise - is the server.

The AppWare automation scheme currently used by the applications in PerfectOffice is based on "PerfectLinks". Unlike some other automation schemes, PerfectLinks does not use Windows DDE or OLE services, and therefore does not need the extra resources these features require. Rather, PerfectLinks is an integration technique that taps directly into the automation capabilities of the server program. It accomplishes this with an AppWare ALM. Once the appropriate ALMs have been added to an AppWare project, the automation features are available for use.

Note: PerfectLinks is compatible with PerfectOffice 3.0 and the applications programs that come with it (e.g., WordPerfect 6.1, Quattro Pro 6.0, and Presentations 3.0). PerfectLinks cannot be used with earlier versions of these products.

While PerfectLinks makes it easy to remotely control a PerfectOffice application, it's not the only method that can be used for automation. The PerfectOffice applications also support automation using SendKeys and DDE "execute" commands (the PerfectOffice applications currently do not support OLE 2.0 automation).

About PerfectLinks

PerfectLinks is the general term for a set of ALMs used to access the various applications in PerfectOffice. You use only those ALMs that pertain to the type of automation you wish to do. The ALMs are independent of one another and perform separate tasks.

  • Lotus 123 Functions (ALM_123) -Use this ALM to automate Lotus 123 functionality. These function scan send and retrieve data from a Lotus 123 spreadsheet as well as execute a spreadsheet macro.

  • Excel Functions (ALM_PFXL) - Use this ALM to automate Excel functionality. These functions can send and retrieve data from an Excel spreadsheet as well asexecute a spreadsheet macro.

  • Quattro Pro Functions (QPW_USR) - Use this ALM to automate Quattro Pro functionality. These functions can send and retrieve data from a Quattro Pro spreadsheet as well as execute a spreadsheet macro. Use these ALM functions when PerfectOffice "shared files" are unavailable on the computer.

  • PerfectFit File Dialogs (ALM_WPPF) - Use this ALM to add the standard Open, Save and Select Directory dialog boxes used by PerfectOffice applications.

  • PerfectScript (ALM_WPCI) - Use this ALM to automate the execution of WordPerfect macro scripts or commands.

  • PerfectLinks Detect (ALM_WPSS) - Use this ALM to detect the presence of a spreadsheet.

  • WPInfoCentral (WPICALM) - Use this ALM to automate tasks within InfoCentral.

Before you design an AppWare application, place one or all of the CFG files in your APPWARE\CONFIG directory and the corresponding DLL files in the APPWARE\BIN directory and re-start AppWare. This will register the ALMs with AppWare and make them available for use.

Using PerfectLinks to Automate WordPerfect

WordPerfect for Windows is the most common PerfectOffice application used for AppWare automation. The following section explains how to use AppWare to automate WordPerfect for Windows. Much of this information also applies to automating GroupWise, Presentations and Quattro Pro. Automating these other applications is explained in detail later in the document.

The PerfectScript ALM is used to establish the automation link with WordPerfect. With this ALM you can use AppWare to:

  • Play a file or template "script" (macro).

  • Set, read, delete or check for the existence of persistent variables.

  • Play most macro product commands available to WordPerfect.

  • Query the state of WordPerfect using system variables.

Adding a PerfectScript Object to a Project

Before you can use AppWare to automate WordPerfect you must add a PerfectScript object to your AppWare project. To do so, locate and select the PerfectScript object on the Object & Function Palette and drag it onto your current subject of your project. A PerfectScript object will be instantiated and will be ready for configuration.

Note: The PerfectScript ALM requires the "shared code" files that are an integral part of PerfectOffice. If your computer does not have these shared code files, you cannot use the PerfectScript ALM.

Setting the Target Application

Like all AppWare objects, the PerfectScript object can be configured to define how the object behaves. To configure the object, double-click the PerfectScript object icon and select which application you would like to control from AppWare, as shown in Figure 1.

Figure 1: Selecting an application to configure.

Playing a File Script

Playing a "script" is the most straightforward task that PerfectScript can automate. The script can be contained in a WordPerfect template or a separate file. To play a file script (a macro contained in its own file) you merely call the Play File Script function passing in the path to the script file as the input parameter to the function.

Figure 2: The script can be contained in a template or a separate file.

Playing a Template Script

PerfectScript can also play a script contained in a WordPerfect template (the template does not need to be active). In a working AppWare program, you will need to provide the actual name of the template as the first input parameter and the name of the script to play as the second input parameter to the Play WP Template Script function.

Figure 3: Template name and script name are required parameters.

Sending Commands to WordPerfect with PerfectScript

PerfectScript enables you to send most macro product commands to WordPerfect. The command may insert text, add a blank line, open a document or save a document. While there is virtually no limit to the complexity of automation you can achieve using PerfectScript inside AppWare, you should reserve using PerfectScript to sending only a handful of commands. If you require WordPerfect to follow a long series of steps, you will need to create a file or template script that you will play from within AppWare (explained earlier in this document).

Specifying the Command. To send a command to WordPerfect you must first specify the command you wish to use and include any required parameters. In most cases, your AppWare program will send a command to WordPerfect in response to the user choosing some command button or other control.

For example, you might have a command button on the form of your AppWare program which tells WordPerfect that you wish to insert a hard return. To do this, you would double-click the PerfectScript object and select WordPerfect as the target product. Once the target product is selected, you would then select the HardReturn command.

Figure 4: Selecting the Hard Return command.

To execute the command, you would call the Send PerfectScript Command function passing as the input parameter the PerfectScript object, which in this case is named HardReturn.

Figure 5: Executing the command.

The command string to send to WordPerfect is HardReturn(). When the command button is pressed, PerfectScript passes the HardReturn command to WordPerfect, which responds by inserting a hard return at the current insertion point.

In addition to HardReturn, a second command string (Quit) should also be sent to WordPerfect. This tells WordPerfect that no more command strings are forthcoming and that it should revert to normal operating mode. It is important that you include the Quit command string after sending each set of commands to WordPerfect. Otherwise, WordPerfect will expect additional command strings and will not allow you to exit the program. If you accidentally forget to provide the Quit command string, you must close your AppWare application, releasing WordPerfect and allowing it to be used normally.

Commands You Can Use in a PerfectScript Application

Macro product commands for WordPerfect are listed in the Commands Inserter dialog box, which is available in WordPerfect when you edit a macro. You can access a special version of this macro commands inserter dialog box directly in AppWare.

  1. Double-click a PerfectScript object in the AppWare application.

  2. Select WordPerfect as the target application.

  3. The PerfectScript Commands dialog box appears, listing more than 1,800 macro product commands you can use.

Note: For those familiar with writing macros in WordPerfect for Windows, programming commands such as If, While and Assign are unavailable in an AppWare PerfectScript application. The programming methods of AppWare must be used instead.

Figure 6: Values are specified in the Parameter Value box.

You can build a command using literal text, variable names and enumerated values (parameters that end with an exclamation point [!]). Find the command you want in the list and click it. If the command uses parameters, one or two additional list boxes will appear. You can specify the values of the parameter(s) to use in the Parameter Values box, and then click Update to insert the parameter into the command string preview window.

Because the PerfectScript Commands dialog box is modeless you can go back to working with AppWare without closing the dialog box. You can drag the PerfectScript Commands dialog box out of the way while you're working in AppWare. Choose OK or Cancel in the PerfectScript Commands dialog box to close it.

Setting and Getting Variables from within AppWare

PerfectScript enables you to set and get persistent variables used in WordPerfect macros and merges. A persistent variable is one that is not cleared when a macro ends. Normally, variables defined in a macro are cleared as soon as the macro finishes to preserve memory space. Conversely, the contents of a persistent variable are lost when you exit WordPerfect or specifically remove the variable from memory.

Setting and getting variables from within AppWare is handy if your AppWare program must interact with WordPerfect macros or merges. For example, suppose you have devised a macro that inserts the contents of a Name variable into the document. You set the contents of this variable in AppWare. When AppWare runs the macro, the Name variable is already filled with text, so the macro simply inserts this text into the document. Variables created in AppWare can be used in WordPerfect like any other variable created by WordPerfect itself.

Setting a Persistent Variable. To set a persistent variable, define the name, value and type of variable. Then instruct PerfectScript to create the variable. You can define the variable name, value and type in the PerfectScript dialog box or within code. The code method is much more flexible because you can dynamically alter the variable name, value and type as your AppWare program runs. To create a persistent variable, use the Set Script Variable function passing in the variable name, type and value as input parameters. Valid variable types are String, Integer and Float.

Figure 7: Variable name, value, and type can be defined.

Getting the Contents of a Persistent Variable. Your AppWare program or WordPerfect can create persistent variables (in WordPerfect, a persistent variable is created by defining it in a merge or by using the PERSIST command in a macro). With a persistent variable available in memory, you can have PerfectScript fetch the value for you to use in your AppWare program.

To get the contents of a persistent variable, use the Get Script Variable function passing in the name of the variable as its only input parameter. The returned value from the function is placed in the output parameter of the function.

Figure 8: Getting the variable.

Deleting a Persistent Variable. A persistent variable should be cleared from memory if it is no longer needed, freeing the memory for other tasks. To delete the persistent variable, use the Delete Script Variable function passing in the name of the variable as its only input parameter, as shown in Figure 9.

Figure 9: Deleting the variable.

Testing for the Existence of a Persistent Variable. PerfectScript enables you to test if a persistent variable exists in cases where you need to determine ahead of time if a given variable is available. To determine if a persistent variable exists, call the Script Variable Exists function. The resulting function signal flow will be either Variable Exists or Variable Does Not Exist.

Figure 10: The Variable Exists function tests for the availability of a given variable.

Retrieving System Variables

System variables, which are read-only, are used to "query" the current state of WordPerfect. For example, a system variable can return the current page number (the page number contains the insertion point), the current font, the paper size and so on. System variable are identified in the PerfectScript Commands dialog box (discussed earlier in this article) with a question mark as the beginning of their name. For example, the ?Page system variable returns the current page number and ?CurrentFont returns the current font.

The process to retrieve the value of any WordPerfect system variable with PerfectScript is straightforward:

  • Configure a PerfectScript object to call any ?Variable command.

  • Execute the Send PerfectScript Command function. The resultant value is stored in the output parameter of the function.

For example, suppose you want to determine the path that contains the WPWIN.EXE executable program for WordPerfect. You can call the ?PathProgram command via the Send PerfectScript Command and the result will be placed in the output parameter of the function.

Figure 11: Determing a path.

Dealing with Errors

With few exceptions, PerfectScript does not display messages when it encounters an error in processing commands for WordPerfect. Nor does it generate a run-time error in AppWare. Rather, PerfectScript functions generate function flows which indicate if an error occured. For example, the Send PerfectScript Command generates two signal flows - Success and Fail.

Note: PerfectScript displays its own run-time error message if a required parameter - such as the name of a macro script to play - is blank. These messages are not trappable. You will want to build into your code a test to ensure that all required properties contain a valid value. The test can be simple.

Starting and Ending WordPerfect with PerfectScript

AppWare as an automation front end is commonly used to remotely start WordPerfect if it is not already running, and to exit the program after the automation steps are done. For example, your AppWare program might instruct WordPerfect to print a file and then exit the program after printing is complete.

PerfectScript makes it easy to start and end WordPerfect. The starting process is automatic if the program is not already running. PerfectScript will start WordPerfect prior to sending it the instructions to play a script or execute a command. You do not need to determine ahead of time if WordPerfect is currently running.

To end WordPerfect include the ExitWordPerfect command which forces WordPerfect to shut down. Like other commands sent to WordPerfect, a Quit instruction needs to be included as the last command.

Using PerfectScript with PerfectOffice Applications

So far this article has concentrated on using PerfectScript to automate WordPerfect. The same techniques can also be used to automate other selected applications in the PerfectOffice suite, namely GroupWise, Presentations, and Quattro Pro.

Whether you are automating WordPerfect, GroupWise or Presentations, the syntax and construction of your PerfectScript application is the same. You need only to identify the target application you wish to send commands to.


Tosend commands to
Use as target application name

WordPerfect

WordPerfect

GroupWise

WPOffice

Presentations

WPPrWin

Quattro Pro

QuattroPro

Note: You can control Quattro Pro with the PerfectScript ALM or a separate ALM. The ALM is Quattro Pro Functions (QPR_USR) which is discussed in detail later in this article. This is the custom function ALM to use if you are using Quattro Pro without "shared code" files that are an integral part of PerfectOffice.

Displaying Open, Save, and Directory Dialogs

The PerfectFit File Dialogs ALM enables you to access the standard File Open, Save and Select dialog boxes in used in all PerfectOffice applications. These dialog boxes are easier to use and allow far greater flexibility than the standard Windows common dialog boxes. The standard PerfectOffice Open and Save dialog box styles allow you to provide a unique caption for the box and the OK "action" button, the OK button can be labeled Save, Open, or another action. You can also provide default paths and extensions.

The PerfectFit File Dialog functions provide input parameters that customize the appearance of the file dialog. You can specify values for these input parameters. The functions for the File Open, Save As, and Select Directory dialog functions are displayed in Figure 12.

Figure 12: Functions for Open, Save As, and Select Directory.

Setting Function Input Parameters

The unique properties included with the PerfectFit File Dialog functions are listed below:


Parameter
Function

Default Directory

The initialdirectory shown when the dialog box is firstdisplayed. If the directory does not exist,an errorwill occur. If no directory is specified,the Windows default is used.

File Mask

The file mask(*.txt or *.doc for example)that is used when the dialog box is opened.The extensionis also used to append the extensionto any file name that is enteredwithout anextension. For example, if *.txt isthe default extension, typing test resultsin a file name of test.txt.

Note: This parameter is ignored when the SelectDirectorydialog style is used.

Dialog Title

The title todisplay on the title bar (caption)of thedialog box.

Note: This property is ignored when the Select Directory dialog style is used.

OK Button Text

The text ofthe "action" button in the topright of thedialog box. If this is omitted, the standard"OK" button textis used.

Note: This property is ignored when the SelectDirectory dialog style is used.

Returned FileName

Contains thefull path and filenameof the file selectedfor the Open dialog; contains the full pathandfilename of the file specified, for theSave dialog; contains the directoryselected,for the Select Directory dialog. This isalways an output parameter.

Not all parameters are available in each of the three dialog box styles. The following table lists the dialog box styles and the properties that can be defined for them. The table also lists the type of value expected for each of the properties.


Property
Default
Type
Used In

Default Directory

Windows Default

String

All

File Mask

*.*

String

Open, Save

Dialog Title

String

Open, Save

OK Button Text

OK

String

Open, Save

Returned File Name

N/A

String

All

Displaying and Returning Values from the Dialog

Once the dialog is displayed by calling one of the three AppWare functions, each function generates one of two possible function signal flows - OK Selected and Cancel Selected. If any outputs were possible, they will be available via the output parameter of the function.

Using PerfectLinks to Automate Quattro Pro

The Quattro Pro ALM function (QPW_USR) for Windows lets you perform the following actions remotely:

  • Play a spreadsheet macro by either range name or cell reference

  • Get the contents of a cell

  • Set the contents of a cell

Playing a Spreadsheet Macro

To play a spreadsheet macro you must define the cell reference or range name and the name of the spreadsheet that contains the macro. To do so, pass in the name of the macro as an input parameter to the Play Quattro Macro function. If the macro is contained within a file, you may optionally pass in the file name of the spreadsheet as the second input parameter.

Figure 13: Playing a Quattro macro.

Setting a Cell Value in Quattro Pro

To set the value of a cell in Quattro Pro you need to specify the cell reference and the value you wish to use when calling the Put Quattro Data function.

Figure 14: Setting a cell value.

Getting a Cell Value in Quattro Pro

To get the value of a cell in Quattro Pro you need to specify the cell reference as in input parameters when calling the Get Quattro Data function. The resultant data is returned as an output parameter.

Figure 15: Getting a cell value.

Accessing Quattro Pro from the PerfectScript Object

The Quattro Pro Functions is designed for easy interfacing of AppWare and QuattroPro. The functions do not require the shared code used by PerfectOffice and many of its components.

The same functionality for playing a spreadsheet macro and setting or getting cell values is also available via the PerfectScript object (discussed earlier in this document). Unlike the Quattro Pro Functions ALM, the PerfectScript object requires the shared code files that are an integral part of PerfectOffice. If your computer lacks these shared code files, you cannot use the PerfectScript ALM.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates