TECHNICAL BULLETIN #103 - Rev 1.01 (3/30/98) ============================================================================== TITLE : ASPECT Top 10 Scripting Questions and Answers for Procomm Plus. PRODUCT : Procomm Plus 4.x, 3.x ============================================================================== ----------------------------------------------------------------------------- #1. How do I check if a file is successfully sent or received in ASPECT? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 3.0 & 4.x for Windows. $XFERSTATUS is a system variable that returns the current status of a file transfer. It is commonly used with the SENDFILE and GETFILE commands. The values for $XFERSTATUS are: 0 No file transfer is in progress. (default) 1 File transfer is in progress. 2 File transfer completed successfully. 3 File transfer failed. The values of 2 and 3 are reset to 0 after $XFERSTATUS has been accessed. Example: proc main integer iTemp ;Will store the $XFERSTATUS value. transmit "test.txt^M" ;Transmit the file name to send. waitfor "Start transfer" ;Wait for signal to start transfer. iTemp = 1 ;Set iTemp value to 1 (for loop.) sendfile ZMODEM "test.txt" ;Upload file using ZMODEM. while iTemp == 1 ;While file transfer is going on. iTemp = $XFERSTATUS ;Store value in $XFERSTATUS in iTemp yield ;Yield processor time. endwhile if iTemp == 2 ;Test value of iTemp for success. usermsg "File successfully sent." else ;or failure of file transfer. errormsg "File transfer failed!." endif endproc Note: In the line [if iTemp == 2], if this line were [if iTemp = 2] then the file transfer would always report success. Only one "=" will assign the value of 2 to iTemp. Beware of the following mistake: sendfile ZMODEM "test.txt" ;Upload file using ZMODEM. while $XFERSTATUS ;While file transfer is going on. yield ;Yield processor time. endwhile if $XFERSTATUS == 2 ;Test the value of $XFERSTATUS usermsg "File successfully sent." else errormsg "File transfer failed!." endif The reason the above example will NOT WORK is because the value 2 or 3 in $XFERSTATUS is cleared when accessed. When $XFERSTATUS is 2 the ' while $XFERSTATUS' line will reset the value back to 0. So when the ' if $XFERSTATUS == 2' statement is executed the value in $XFERSTATUS is 0 and will report failure. ----------------------------------------------------------------------------- #2. How do I use the FTP command in ASPECT? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 4.x for Windows. The following example covers just about everything you can do with the FTP command. Unfortunately the ASPECT on-line help system does not have examples of the FTP commands. However, the following should do the trick. Note: Keep an eye out for filenames. In FTP commands they are case-sensitive. ;FTP.WAS ASPECT Script for Procomm Plus 4.x ;Example script with FTP commands. proc main FTP LOCAL CHDIR "C:\test\" ;Set the local dir. to C:\test\. Connect FTP "Quarterdeck" ;Connect to Quarterdecks FTP site. while $ftpstatus ;Loop while connecting to FTP site. yield endwhile pause 1 ;Let Procomm update its screen. FTP REMOTE CHDIR "/pub/procomm-windows/us/ver-4/" ;Change dir on FTP site. pause 1 FTP REMOTE COPYFILE "pw4mdm.lst" ;Copy (download) pw4mdm.lst from FTP ;site to local machine. Filenames ;are case-sensitive! while $ftpstatus ;Yield while transferring file. yield endwhile FTP LOCAL RENAME "pw4mdm.lst" "new.lst" ;Rename the local filename. pause 1 ;Let Procomm update its screen. FTP REMOTE CHDIR "/upload/" ;Change dir on FTP site to /upload/. pause 1 ;Let Procomm update its screen. FTP LOCAL COPYFILE "new.lst" ;Copy (upload) file to FTP site. while $ftpstatus ;Yield while transferring file. yield endwhile disconnect endproc ----------------------------------------------------------------------------- #3. How do I to print the ASPECT on-line help manual. ----------------------------------------------------------------------------- This tip applies to Procomm Plus 3.0 & 4.x for Windows. Previously for printing the ASPECT on-line help system we have recommended downloading the following files (which are still available): PRINTHLP.EXE - For printing PROCOMM PLUS 3.0 ASPECT manual. PRNTHLP4.EXE - For printing Procomm Plus for Windows 95 ASPECT manual. These script files are no longer needed with Windows 95 and Windows NT 4.x operating systems. These operating systems will allow us the ability to print "books" or subjects. To print the ASPECT on-line help in Windows 95: Start Procomm Plus and select the Help menu option. Then select Script Reference. The ASPECT help system will be loaded. Choose the Contents button in the upper left corner. The help system will now list about 11 books. Simply choose a book and press the print button. It will now print the entire subject. To print the ASPECT on-line help in Windows NT4: Start Procomm Plus and select the Help menu option. Then select Script Reference. The help system will now list about 11 books. Simply choose a book and press the print button. It will now print the entire subject. And as reminder, printing the entire ASPECT help system is over 600 pages! ----------------------------------------------------------------------------- #4. How do I pass arguments to an ASPECT script from the command line? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 2.11, 3.0 & 4.x for Windows. ASPECT has the ability to accept arguments passed to it from a command line through its predefined global variables. There are 40 predefined global variables. They are string variables S0 through S9, integer variables I0 through I9, long integer variables L0 through L9 and float variables F0 through F9. This means that ASPECT will only handle 10 string arguments passed at one time. The following script is an example. ;ARGUMENT.WAS ASPECT Script example for passing arguments to scripts. proc main usermsg "Hello my name is %s." S0 ;Display a message with string s0 usermsg "My company is %s." S1 ;Display a message with string s1 endproc The above script called with the command line: "D:\Program Files\Procomm\programs\PW4.EXE" argument.wax Fred Quarterdeck would produce the following output: Hello my name is Fred. My company is Quarterdeck. More information about command line options is available in: Tech Bulletin 186: Command Line Options ----------------------------------------------------------------------------- #5. How do I send keystrokes out the port with ASPECT. ----------------------------------------------------------------------------- This tip applies to Procomm Plus 2.11, 3.x & 4.x for Windows. Have you ever needed to send an or other special sequence to a remote system. If you try in Procomm Plus it will bring up our Meta Key Editor, and not send it to the remote system. One way to work around this is by using an ASPECT script with the COMWRITE command. The following script will demonstrate. ;COMWRITE.WAS ASPECT example script for COMWRITE command. proc main integer ALT_M = 0x044D ;Key code for . comwrite ALT_M ;Write to the current port. endproc You can assign the above script to a Meta Key and now you can send whenever you need to. Remember to get a key value use the Virtual Key Codes Table and the following rules for the modifier keys. SHIFT : 0x01, meaning the key is also pressed. CTRL : 0x02, meaning the key is also pressed. ALT : 0x04, meaning the key is also pressed. EXTENDED : 0x08, meaning the value is also an extended key. CAPS LOCK : 0x10, meaning that is toggled on. For example, ALTSHIFT is 4 + 1 or 5, so the key press <3> is identified as 0x0533 because the virtual key code for 3 is 0x33. The letter 'A' is identified as or 0x0141, whereas 'a' is 0x0041. The EXTENDED value does not represent an actual key being pressed, but rather identifies the virtual key value as a special type of key such as a function key or a key on the numeric keypad. ----------------------------------------------------------------------------- #6. How do I Send Keystrokes to Procomm Plus or other applications? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 4.x for Windows. The following script will demonstrate the use of the sendkey commands in Procomm Plus. This script will send an email message to every person listed in the Mail section of the Connection Directory. Since we don't have an ASPECT internet mail command we will do it the hard way. ;SENDKEYS.WAS Example script for Procomm Plus 4.5 ;Uses keystrokes to send an email message to every entry in the Connection Dir. ;************************************************************************** ; Define * ;************************************************************************** #define szSUBJECT "Hello" ;Message Subject Line. #define fMSGFILE "C:\test\message.txt" ;The text file containing the ; mail message itself. ;************************************************************************** ; Main * ;************************************************************************** proc main string szName integer iCount, iNumber filetoclip TEXT fMSGFILE ;Take text file and copy it to ; the windows clipboard. dialcount MAIL iNumber for iCount = 1 upto iNumber if dialname MAIL iCount szName ;Get the name of the entry number. if dial MAIL szName ;Open the mail message window. sendkeystr szSUBJECT ;Send keystrokes to status message ; field of email window. mspause 250 sendvkey 0x09 ;Send a Tab key. mspause 250 sendvkey 0x09 ;Send a Tab key. mspause 250 sendkey CTRL 'V' ;Send a CTRL-V to paste file into ; mail message. pause 1 sendkey ALT 'M' ;Send a keystroke to Mail message. mspause 250 sendkey 'M' ;Send the message. yield pause 1 else errormsg "Error Sending Mail Message to: %s" szName endif endif endfor endproc Note: Always remember when using the sendkey commands that the keystrokes will go to the active window. If the user changes the focus from one application to another the keystrokes will go to the current window. Just as if the user typed them from the keyboard. ----------------------------------------------------------------------------- #7. How do I Convert ASPECT Scripts from Previous Version of Procomm Plus for Windows? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 3.x & 4.x for Windows. A good thing to try first is compiling the script in the new version of Procomm Plus and make any changes to the script the compiler points out. However, Procomm for Windows products all come with a Directory and ASPECT Conversion Utility. This utility is located in your new version's Utilities group. This utility converts previous Procomm for Windows ASPECT scripts, extension .was files. This utility will also convert previous Dialing Directories, extension .dir. (The old files should not be in the Procomm Plus directory) If your new version is Procomm Plus for Windows version 4.x 1. Select the BROWSE button next to the File(s) To Convert: 2. Navigate to the directory where the old files are located. 3. Highlight each file you wish to convert and select open. 4. Click on the Convert Button and the file will be processed. When processing is complete, converted copies of your ASPECT and Connection Directory files will be found in the new version's appropriate directory. If your new version is prior to Procomm Plus for Windows version 4.x, the process is the same except the first Button you must press is CONVERT, not BROWSE. For further information concerning the specifics of your Conversion Utility, press F1 for case sensitive help. ----------------------------------------------------------------------------- #8. Why do I always get an ASPECT Error 111, 107 or 106 when compiling Procomm Plus for DOS scripts? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 2.01 for DOS. There is a little known bug (which has been confirmed) in ASPCOMP.EXE which will cause runtime errors 111, 107, 106, or a variety of other erratic behaviors. The bug listing states, "Logical operators in unreferenced procedures generate invalid offsets. To work around this problem compile the script with the /O option, which PREVENTS optimization of the code. In other words, /O forces the compiler to include all unreferenced procedures and variables. To make your script run more efficiently, remove all unreferenced variables and procedures and compile the script again. ----------------------------------------------------------------------------- #9. The RUN command in ASPECT is not giving me the correct Task ID. How do I communicate between two instances of Procomm Plus 4.5x? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 4.x for Windows. When using the RUN command, you can obtain the Task ID and you have noticed that it is the same for both instances of Procomm that are running. In fact, the ID obtained is not the Task ID, but the Process ID. No matter how many instances of Procomm Plus you have running, they all have the same Process ID. So you cannot use the Task ID (or Process ID here) to access the other instances of Procomm. The book states that you should be able to manipulate a second instance of PW4 by using a specific instance handle: "use PW4xxxxx, where the digits xxxxx correspond to the unsigned integer value of Procomm Plus's instance handle. You can obtain this handle value from within the ASPECT script by using the run command to launch another instance of Procomm Plus. " Of course, using the RUN command gets the wrong ID. Additionally, the documentation here is incorrect - the xxxxx has to be replaced by the Thread ID instead of the Task ID (or Process ID). Unfortunately, the Thread ID is not obtainable by ASPECT. Therefore, you find that you cannot manipulate separate instances through their Task ID and you cannot manipulate more than two instances through DDE. RESOLUTION: 1) The DDE can be used to access the second instance by using "PW4" as the handle. This seems to work as long as no more instances of Procomm are executed. 2) Write a DLL that makes a Win32 API call to obtain the Thread ID, thereby allowing ASPECT to directly access the multiple instances. The following example demonstrates how to setup a DDE link with a second instance of Procomm Plus. proc main string pathname integer pwhwnd long pwchanid pathname = $pwtaskpath ;Get PW's path. addfilename pathname "PW4.EXE" ;Add Procomm's EXE. if run pathname ;Run the program. pause 2 pwhwnd = $mainwin ;Get the active window ID. if ddeinit pwchanid "PW4" "System" pwhwnd ;Establish DDE connection. usermsg "DDE channel successfully established!" else errormsg "Error initializing DDE channel" endif else ;Problems running program. errormsg "Error running %s" pathname endif endproc Note: This example requires that new instances of Procomm Plus must receive focus, at least long enough to grab the window ID of the new instance. ----------------------------------------------------------------------------- #10. How do I use ASPECT to send a fax? ----------------------------------------------------------------------------- This tip applies to Procomm Plus 4.x for Windows. The following is a simple example of how to use the SENDFAX command in ASPECT. proc main faxsend DIALDIR "Quarterdeck" SINGLE "C:\FILE.TXT" pause 2 while $faxstatus yield endwhile endproc This example will generate the fax from file "FILE.TXT" assuming that Windows has the ".TXT" registered to an application that will print. The example will then wait until the fax has been sent. $FAXSTATUS can be tested the same way $XFERSTATUS is tested for file transfers. Note: For the $FAXSTATUS command to work properly the modem used to send the fax also must be the current modem listed in the Data Terminal Window.