ASPECT tips and tricks

As always, if you have information to share with other ASPECT users, please email me and I will add your tip!

Click here for instructions on performing a debug compile of your ASPECT script and the assistance this can provide when troubleshooting an irritating problem.

This ZIP file (provided by the developer of ASPECT) contains a framework to create your own ASPECT-callable DLLs that can be accessed by your script.

Be sure to browse the SAMPLES directory on your Procomm Plus 4.8 CD for sample scripts, as well as the two tutorial PDF files in the SAMPLES\ASPECT directory. Also be sure to read ASPECT.PDF in the DOCS directory on the CD. This file is a high-level overview of ASPECT that serves as a very good introduction to the language, and also includes many sample scripts toward the end of the document. One final source of sample scripts is the ASPECT help file discussions of the various commands as they include many examples illustrating how the commands are used.

If you right click on an ASPECT keyword in the ASPECT Editor, the discussion of that command in the ASPECT help file will be displayed.

Procomm Plus comes with several scripts, but the one of most interest is the host script. This is a mini-BBS with mail and file transfer capabilities. The source code for this script is included and makes for a good reference. This also enables you to modify the host script for your own purposes. Be sure to backup the original files before undertaking any modifications, just in case! I have a page with useful modifications to the host script here.

Another script that may prove useful is the WinLink script. This script can be used to transfer files between two instances of Procomm Plus, either via a modem or direct connection, by using an interface similar to the Windows 3.x File Manager.

Always be sure to check for the success or failure of a command before continuing execution of your script. For example, if you do not check that the fopen command successfully opened the target file, further commands on that file id will result in "Error 5: Invalid identifier." Read this page for more information on how to check for success or failure.

You can pass variables to Procomm Plus via the command line used to start the application. For example, the command line "C:\Program Files\Symantec\Procomm Plus\Programs\PW5.exe myscript.wax test" will launch Procomm Plus, execute the script myscript.wax and place the word test in the predefined global string variable s0. Up to 10 values may be passed in. The values will be placed in the global strings s0 through s9, and the number of passed variables will be placed in the predefined global integer i0. Your script can then use the atoi, atol, or atof commands to convert the string values to integers, longs, or floats, if necessary.

Some commands may behave differently depending on what operating system you are running. If you experience odd results with a particular command, be sure to read the discussion of that command in the ASPECT help file.

Trying to convert a DOS ASPECT script using the conversion utility, but you receive an error message of Load Library Failed 126 c:\procomm\0_3.dll? This is due to the functionality to convert DOS scripts never being added to the conversion utility. If you need to convert a DOS script to the Windows format, you will need to rewrite your script. You can view this Symantec knowledge base article for a list of equivalent commands between the DOS and Windows versions of Procomm Plus. You may also wish to download this file , run it to expand the enclosed files, run apwp06.exe to expand the files in that archive, and use the resulting file to convert DOS version 2.x ASPECT scripts to the Windows version 1.x format. You could then use Procomm's conversion utility to convert that file to the current version's format. Please note that I have not used this utility myself, I only offer it as possible avenue of identifying changes that must be made to transition a DOS script to the Windows format.

I'm occasionally asked if it is possible to decompile a compiled ASPECT script. There is no such tool to perform this function, so be careful and don't lose your original source files!

One common question I see is how to change the active com port via an ASPECT script. Starting with version 4.0 of Procomm Plus, the application used TAPI to talk to the modem instead of communicating with it directly. This change required Procomm Plus to address a connection (a modem or direct connection, plus its associated com port) rather than setting the current modem with one command and the current com port with a second command. To specify a particular connection within your script, use the set modem connection command. The format is set modem connection "connection_name", where connection_name is replaced by the connection as it appears in the Quick Select Line at the bottom of the Procomm Plus window. The double quotes around the connection name are required.

Another common question is if there is an ASPECT reference manual available. Until version 3.0, Procomm Plus shipped with a separate ASPECT manual that had mostly the same content as the ASPECT help file. At one point, Quarterdeck did make available an ASPECT Script User's Guide that could be purchased separately, but this was once again mostly identical to the help file. Symantec sold this manual for a short time after purchasing Quarterdeck, but it is no longer available. I have never seen this manual for sale elsewhere, and the copy I have does not include an ISBN number. There is a part number of 51PCW451X899US on the back of the manual, which probably indicates it was released around the time of version 4.51 of Procomm Plus.

The Windows Media Player will register the .WAX filetype that Procomm Plus uses for compiled scripts. If you need to configure Windows to open that filetype in Procomm Plus instead, right click on a .WAX file, select Open With from the context menu, and click Choose Program. On Windows 2000, select Procomm Plus Connection Manager, check the Always use this program to open these files checkbox, and click OK. On Windows XP, click the Browse button, navigate to the Programs folder under your Procomm Plus install, select PW5.EXE (or the appropiate file if you are using an earlier version), click the Open button, check the Always use the selected program to open this kind of file checkbox, and click OK.

When using the waitfor command, keep in mind that it has a default timeout value of 30 seconds. If the string you are waiting on does not appear in the specified timeframe, the script will continue execution. You can increase the amount of time the waitfor command looks for the string by appending a value (in seconds) at the end of the waitfor command, or use the FOREVER keyword to have the waitfor command complete only when the specified string is received.

One question I see occasionally is how to send certain (usually non-printable) characters via ASPECT. View these help topics in the ASPECT help file for more information: Escape Sequences, Caret Translation, and Virtual Key Codes Table.

If you try to transmit a tilde (~) in an ASPECT script, you will notice that the character is not sent to the remote computer. This is due to the tilde being used as a pause character (half-second delay) by Procomm Plus. You can change the value of the pause character by selecting the Options | System Options | System Options menu item and choosing a new value for the Pause character field. You can also add the RAW keyword at the end of the transmit command and the tilde will be transmitted instead of acting as the pause character.

Kevin Smith from the Tek-Tips forum has made available a snippet of Visual Basic code that can take input from a text file or Excel spreadsheet, and then create an ASPECT script to automate the sending of that data. You can view his document here.

Click here for more information if you compile your script and receive a "Far Calls required (use /F command line option)" warning.

If you receive runtime errors 106, 107, or 111 when running a script in the DOS version of Procomm Plus, try recompiling your script with the /O flag. This turns off compiler optimizations and has been known to solve some erratic problems with the DOS release. If this works for you, you can try removing any unreferenced variables and procedures from your script and then recompile without the /O flag.

If your script requires the use of dialogs or a graphical display of some sort, save yourself time and frustration by using the Dialog Editor or User Window Editor to visually create the user interface. When you are done, you can save your work to a file that your script can import using the #include command, or you can just copy and paste the ASPECT code directly into your script.

If you are running Procomm Plus on Windows 2000 or XP, you should be aware that some ASPECT commands do not operate properly on that platform. These various commands do not correctly process the directory that is used as an argument with the command; instead the current working directory in Windows is used. The first time you use one of these commands it will execute correctly, but subsequent attempts will show the previous argument value instead of the path you have currently defined in your script, even if you restart Windows. The commands I have seen this problem with are sdlgsaveas, sdlgfopen, and dir.

Another oddity I recently saw on Windows 2000 and XP is new Procomm Plus windows created via the Window | New Window menu item are not maximized, even if the original Procomm Plus window was. To work around this problem, modify your STARTUP.WAS script by adding these two lines at the bottom, just before the endproc command:

pause 1
winmaximize $PWMAINWIN

One ASPECT command that is hardly documented in the ASPECT help file is the sizeof operator. This command can be used to place the size of a variable or structure (in bytes) into another variable. This would be handy if you were using ASPECT's various memory-related commands and needed to know how much memory was required. The format of the operator is as such: iSize=sizeof i0. When run, iSize will be set to 4, the number of bytes that represents an integer value in ASPECT. This command is more useful when you are dealing with data structures such as arrays. If an array called iArray[10] was defined, iSize=sizeof iArray would return 40, the number of bytes that is required to store the entire array.

If you receive Error C034: Maximum stack displacement exceeded when compiling your script, this is probably due to declaring an array that is larger than 64K in size. To solve this problem, define it as a global array by declaring it prior to the proc main statement.

If you use the set capture file command to define the name of a capture file in your script, make sure you do not include a path in the command. Doing so will cause the command to fail. To set the location for the capture file to be placed in, use the set capture path command instead.

If you are trying to create a script that automates communications with a remote system and the text is relatively constant, you can make the task easier by using the Script Recorder to create your script. To enable the Script Recorder, select the Tools | Scripts | Start Recorder menu item. Procomm Plus will now monitor all incoming data and your outgoing responses to that data. Start performing the tasks (keyboard-based only!) that you want Procomm Plus to record. Once done, select the Tools | Scripts | Stop Recorder menu item. You will be prompted to save your recorded script; some editing of the script may be necessary. Be aware that if you dialed an entry from the Connection Directory, then your recorded script will be attached to that entry unless you change the value at the bottom of the Save As dialog. When you view your script, you will see that it is composed of waitfor/transmit commands. If all looks well, compile your script and see if it executes as expected. To make a recorded script more extensible, you can take a recorded script and replace some of the recorded strings with variables so that a more general script can be created.

If you would like certain ASPECT commands to be run each time you launch Procomm Plus, you can add them to STARTUP.WAS. This script is executed each time Procomm Plus is run (unless Procomm Plus is started with the /nostartup command line option).

You can find an Excel 97 help file at this Microsoft knowledge base article. It contains some information that may be useful when performing DDE operations with Excel. Thanks to Hank Campbell of the Tek-Tips forum for locating this! Another Tek-Tips members recommends viewing this site for more information on using DDE.

When retrieving a string from an Excel spreadsheet via DDE, be aware that the string will have a carriage return and linefeed at the end of it. You can use the commands strreplace szText "`n" "" and strreplace szText "`r" "" to strip these extra characters out.

If you (or another process) tries to close Procomm Plus while a script is running, you will see a message box that asks if you want to exit all active scripts or not. As you can probably surmise, this behavior would prevent the unattended shutdown of a Procomm Plus instance that is running a script. This could cause problems if a machine needed to be restarted remotely, for instance. To alleviate this situation, you can add the line set aspect exitaction halt to your script, which will prevent the above message box from being displayed. Another useful set command is set aspect control on, which will prevent a user from stopping a script via the program's UI.

One troubleshooting trick I use when I want to check for non-printable characters in a string is to add usermsg "X%sX" strvar to my script. If the strvar string does not contain any non-printable characters, then I should see just the string displayed with an X immediately at the front and another X right at the end. However, if I see a graphical block character or all of the string is not on the same line, then I know I have some characters that need to be filtered.

Procomm Plus comes with an ASPECT-callable DLL called ASPTIME.DLL. This DLL allows your script to display handy controls for users to input time and/or date values. ASPTIME.TXT, located in the ASPECT directory of your Procomm Plus installation, documents the functionality of this DLL. Be aware that ASPTIME.TXT incorrectly reports 0 being returned if the user did not select the OK button in the various controls available through ASPTIME.DLL - the correct value to check for is 2.

The ASPECT compiler can be run from a DOS window, if necessary. The compiler name is ASPCOMPW.EXE and it does support several command line options. View the Command-Line Syntax topic in the ASPECT Compiler section of the ASPECT help file for further information on the available flags.

You can also modify Windows so that you can right click on a .WAS file in Explorer, and compile your script without the file being loaded in an editor. To do so, open Windows Explorer and select the Tools | Folder Options menu item. Select the File Types tab in the resulting dialog, scroll down to Procomm Plus ASPECT Source, select it, then click on the Edit button. Click the New button to bring up the New Action dialog. Enter a name in the Action field, such as Compile, then click on the Browse button and locate ASPCOMPW.EXE (located in the Programs directory under your Procomm install directory). Put your cursor at the end of the Application used to perform action field, add a space, then "%1" (quotes included). Click on the OK button twice to get back to the Folder Options dialog, then click the Close button. You should now be able to right click on a .WAS file in Explorer and select the Compile item from the context menu to compile your scripts. Please note that the steps above were for Windows 98, and may be slightly different on other platforms.

If you would like your script to call or disconnect a dial-up networking connection, the program you will want to run is rasphone.exe, located in the system32 directory under your Windows NT, 2000, or XP installation. Run rasphone.exe -? from a cmd prompt to see the available parameters this program takes. On Windows 95, 98, or ME, the proper command line is rundll rnaui.dll,RnaDial <ConnectionName>, where <ConnectionName> is replaced with the Dial-Up Networking connection exactly as it appears within Windows. This sample script shows how to dial and wait for the connection process to end on Win95, Win98, ME, Win2K, and XP.

I recently discovered a situation where $XFERSTATUS does not report the correct value for a file transfer. If you are sending a file and the connection drops for whatever reason, $XFERSTATUS will report 2 (transfer successful) instead of 3 (transfer failed). To workaround this issue, you could monitor the $CARRIER system variable with a when command, then call a cleanup procedure that can handle the error, or you could check the current value of $CARRIER after a file transfer has completed and have your script branch appropriately.

With version 4.8 of Procomm Plus, it is not possible to switch to FTP, terminal, or telnet mode using the pwmode command. As a workaround for this issue, you can use menuselect PWMENU 500 to switch to terminal mode, menuselect PWMENU 321 to switch to telnet mode, and menuselect PWMENU 322 to switch to FTP mode.

The developer of ASPECT recently alerted me to a problem that some people may be running into if they are dialing data Connection Directory entries from a script. The issue occurs if the entry you are dialing references a specific modem instead of the generic Current Connection value, and the Connection Directory entry's modem value is retrieved via the fetch modem connection command. When this occurs, the value of the modem index is decremented, which can cause a different modem or connection on your system to be accessed instead of the intended device. To prevent this problem, reload the Connection Directory using the dialload command after the fetch command. I have also included a sample script to illustrate the problem.

There is not a direct way to declare an array with an arbitrary number of rows and columns, i.e. they must be assigned before compile-time. However, one way around this limitation is to declare the rows and columns using values that are then substituted by being #defined in an include file. For example, the .inc file could contains the lines #define x 5 and #define y 5, while your .was file had this line at some point after the #include statement: integer FiveByFive[x][y].

Be aware that the set ftp xfermode command sets the transfer mode (binary, ASCII, or L8) within Procomm's Setup dialog, but does not apply this change to the currently-open window. If you wish to change the transfer mode while Procomm Plus is in FTP mode, you need to select the appropriate menu item using the menuselect PWMENU <menuid> command, where <menuid> is replaced by the menu ID of the transfer mode you desire. 18119 is the value for binary, 18120 is the value for ASCII, and 18121 is the value for L8.

If you are using the strtonum command to convert a string with leading zeroes to an integer, keep in mind that the conversion will assume the string is not base 10. This is due to the strtonum command assuming a string with a leading zero is either an octal or hexadecimal value. To force the conversion to assume a decimal value, add "10" (without quotes) to the end of the strtonum command. Failure to do so will cause conversions including 8 or 9 in the string, which are invalid octal values, to produce incorrect results.

If you would like to perform audio feedback of some sort in your script, you can use the mciexec command to play a .WAV file. The format of the command is mciexec "SOUND wavefile", where wavefile is the fully-qualified path and filename of the .WAV file you wish to play. If there are any spaces in the path, then the entire path must be enclosed between a pair of `" characters (this is a backtick, the character to the left of the 1 key, and a double quote).

A recent problem I experienced had to do with a capture file not containing all of the expected data if Procomm Plus was started in a minimized state. The workaround for this problem was to start Procomm as a regular window, but include the line "winminimize $PWMAINWIN" at the end of the STARTUP.WAS script. This still causes the Procomm Plus splash screen to appear for a short time, but at least no data will be lost.

I recently encountered a problem when VK_UP (the up arrow as defined in VKEYS.INC) was used with the sendkey command in a Procomm Plus window. This command was actually sending an 8 (the numeric value of the keypad's up arrow) instead of the expected result. To work around this problem, use sendvkey 2086 instead. A similar problem exists for VK_DOWN, VK_LEFT, and VK_RIGHT. The corresponding sendvkey arguments are 2088, 2085, and 2087.

Here is another problem that I was able to resolve by using the information in VKEYS.INC. The command sendkey ALT '.' does not send an Alt-. keystroke to a window, but sendkey ALT 0x6E can be used to workaround this issue.

Speaking of VKEYS.INC, you can include this file (located in your ASPECT directory) in your script using the #include command. You can then reference a key by a macro definition instead of the virtual key code. This file is also a good reference if you ever need to find out the virtual key code of a particular key.

If you are looking for the value of a certain key in VKEYS.INC but cannot find it, such as the value of the Page Down key that is not on the numeric keypad, here is a script to determine the hexadecimal value to use with the sendvkey command:

proc main
   keyget i0
   usermsg "%x" i0
endproc

Another include file that is good to know is PW5MENU.INC (also located in your ASPECT directory). This file contains the mapping between Procomm's various menus and their menu IDs, as well as macro definitions that you can use instead of the menu ID. This information can be useful if your script needs to perform some operation with Procomm's menu items, such as disabling or enabling a menu item in Procomm Plus by using the disable or enable ASPECT commands, or if you would like your script to automatically access some functionality by using the menuselect PWMENU command. It may also be worthwhile to view PW4MENU.INC as it includes several menu items that are still present in version 4.8, but whose menu IDs were not included in PW5MENU.INC. These omissions affect the news and mail portions of Procomm Plus. Additionally, the menu IDs for the FTP client are incorrect. The table below contains the correct mapping for those menu items:

Menu Item	Menu ID
File \| Open	18100
File \| Send	18101
File \| Delete	18102
File \| Rename	18103
File \| New Folder	18104
File \| Change Folder \| Local	18105
File \| Change Folder \| Remote	18106
File \| Properties	18107
Edit \| Cut	18108
Edit \| Copy	18109
Edit \| Paste	18110
Edit \| Select All	18111
Edit \| Invert Selection	18112
View \| Large Icons	18113
View \| Small Icons	18114
View \| List	18115
View \| Progress Window	18116
View \| Progress Window Font	18117
Options \| Filters	18118
Options \| File Transfer Mode \| Binary	18119
Options \| File Transfer Mode \| ASCII	18120
Options \| File Transfer Mode \| L8	18121
FTP \| Connect	18122
FTP \| Manual Connect	18123
FTP \| Refresh Current Folders	18124
FTP \| Expand Remote Folder	18125
FTP \| Display Progress Text	18126
Help \| Using the FTP Client	18127

If you are experiencing odd behavior with a when command, make sure you are not continually redefining the when statement, such as including it in a while loop. I've seen two cases recently where moving a when statement outside of the while loop cleared up unexpected results.

Although the help file does not make it clear (in my opinion), your script can modify values of a Connection Directory entry after it has been specified via the set dialentry access command. You can modify any setting's value, not just the few options under the set dialentry family of commands. Make sure your script includes a dialsave command so that your changes are saved.

If you are using the mapisend command to send an email through Outlook, you will need to use the name of the current mail profile as the logon name argument. To check this value, select the Tools | Options menu item within Outlook. then click on the Mail Services tab. If the Always use this profile radiobutton is selected, then the profile you need to use will be in the associated edit field.

If your version of Outlook has a security patch applied that displays a message box when your script tries to send an email, this utility can be used to automatically press the Yes button.

If you wish to change the named option set for the Data tab in Procomm's Setup dialog, the proper command is set data options "name" where name is the option set exactly as it appears in the dialog.

Another ASPECT user ran into a problem where Procomm Plus did not immediately process the character 0x01 (SOH) and only processed it when two additional characters were received. He verified this by monitoring the value of $RXDATA. He was able to resolve the problem by turning off the "Enable automatic download start for Zmodem and Kermit" checkbox in Procomm's Setup dialog.

If you would like to perform some operations on a file after you have downloaded it but don't know the name of the file, you can query the $XFERFILE system variable during the download. Using a command such as "when $XFERFILE call proc_name" will call the procedure proc_name each time $XFERFILE changes (even during a batch transfer). This procedure can then queue up the name(s) of the transferred file(s) for processing after the downloaded is complete.

One poster on the Tek-Tips forum reported that the fetch print device command was returning a null string instead of his default printer in Windows. After investigating this issue, it appears that you must select the File | Print Setup menu item in Procomm Plus, then click OK in the resulting dialog (and select the correct printer, if necessary) to set the printer. After doing the above steps, the fetch print device command will return the expected result.

If you are using one copy of Procomm Plus to connect with another computer also running Procomm Plus, you can issue remote ASPECT commands to that computer. For more information, view the Using Remote ASPECT Commands topic in the ASPECT help file. Another option is using the REMCMD script that ships with the later versions of Procomm Plus. For more information about this script, read the file REMCMD.TXT located in your ASPECT directory.

After seeing a post from J Dan Skinner on the Symantec support forum, I did a little more research into remote script commands in the context of a Unix shell script echoing the necessary commands to Procomm Plus. First, here is a sample to look at:

#!/bin/sh
echo "\004test"
echo "string dl"
echo "fetch dnldpath dl"
echo "usermsg dl"
echo "usermsg \$ASPECTPATH"
echo "run \c"
echo "\"C:\\Program Files\\Symantec\\Procomm Plus\\Programs\c"
echo "\\pwedit.exe\""
echo "\004"

\004 indicates the beginning or end of the remote script commands. \004test tells Procomm Plus to begin the remote script process, with test being the corresponding remote script password (select the Options | System Options | System Options menu item to set this). The remainder of the shell script is mostly self-explanatory, but there are a couple things to keep in mind when operating in a Unix environment. First, some characters need to be escaped with a backslash, such as the $ in the $ASPECTPATH environment variable or a double-quote in a string (such as in line 8). This also means you need to use two backslashes to echo one backslash, as seen in lines 8 and 9. Finally, you can use \c to have the shell script not send the newline character that usually follows an echo command. This can allow you to concatenate the output of several echo commands in the shell script into one ASPECT command line.

If you would like your script to display high-bit characters in the terminal window, you need to use the ansitooem command to convert the characters so they will display properly. This command is not needed to display high-bit characters in dialogs. You will also likely need to uncheck the Strip bit 8 checkbox associated with your current terminal emulation. To do so, select the Options | Data Options | Terminal Options menu item in Procomm Plus.