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 <ALT><M> or other special
sequence to a remote system. If you try <ALT><M> 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 <ALT><M>.

   comwrite ALT_M                        ;Write <ALT><M> to the current port.
endproc

You can assign the above script to a Meta Key and now you can send
<ALT><M> 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 <Shift> key is also pressed.
CTRL : 0x02, meaning the <Ctrl> key is also pressed.
ALT : 0x04, meaning the <Alt> key is also pressed.
EXTENDED : 0x08, meaning the value is also an extended key.
CAPS LOCK : 0x10, meaning that <Caps Lock> is toggled on.

For example, ALTSHIFT is 4 + 1 or 5, so the key press <Alt><Shift><3> is
identified as 0x0533 because the virtual key code for 3 is 0x33. The letter
'A' is identified as <Shift><A> 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.
