Copyright: Copyright© 1999 Symantec Corporation.  All rights reserved.


#comment

#comment

Denotes the start of a comment block. Any commands or remarks following this command are ignored by the compiler until an #endcomment is encountered.

Example

proc main

   #comment

   The compiler does not process this block of

   information. Every line between the #COMMENT

   and #ENDCOMMENT keywords is ignored.

   #endcomment

   ; The following script command lies outside of the

   ; #COMMENT and #ENDCOMMENT block and is processed

   ; by the compiler.

   usermsg "Hello World!"

endproc

Comments

#comment blocks cannot be nested. Single-line comments are marked by a semicolon(;), and can be embedded within a #comment/#endcomment block.

See also

#endcomment; Preprocessor Commands.


#define

#define name text

(or) #define name([name[,name]...]) text

Defines a macro name and the text to substitute for it during compilation. There are two forms of macros in ASPECT.

Simple text substitution:

#define name text

name	The macro name to be defined.

text	The text to be substituted for the macro name when processed by the ASPECT Compiler.

Argument/text substitution:

#define name([name[,name]...]) text

name	The macro name to be defined.

([name[,name]...])	Zero or more arguments to be processed by the compiler with the substitution text.

text	The text to be substituted for the macro name when processed by the ASPECT Compiler.

Example

#define TRUE 1             ; Constant to use in place of TRUE.

#define FALSE 0            ; Constant to use in place of FALSE.

proc main

   integer Error           ; Integer to contain Error.

   Error = TRUE            ; Set error to true, or 1.

   if Error == TRUE        ; Check to see if error is true

      usermsg "True"       ; or false and display message.

   elseif Error == FALSE

      usermsg "False"

   endif

endproc

; #define macro(arglist)

; The statement below declares a macro that calls the internal

; SDLGMSGBOX function to display the specified message.

; Each operand, "a", "b", "c" corresponds to a parameter in the

; SDLGMSGBOX function.

#define PutMsg( a,b,c ) sdlgmsgbox a b STOP OK c 1

proc main

   string Title, BoxText      ; Strings for title and text.

   integer Choice             ; Integer for button selection.

   Title = "Macro Example"    ; Assign value to title and text.

   BoxText = "This is an example of Macro Expansion."

   ; Call internal SDLGMSGBOX function using macro.

   PutMsg( Title, BoxText, Choice )

endproc

Comments

Similar to macros in the "C" programming language, #define allows for textual substitution within a source program.

If the argument/text substitution macro form is used, any arguments specified must follow the standard ASPECT naming convention in the #define statement.

Arguments must be comma-separated. No whitespace can appear between the last macro name and the opening parentheses, or it will be treated as part of the substitution text. For more information, refer to Macros.

See also

#elifdef, #elifndef, #else, #ifdef, #ifndef, #endif, and #undef; Preprocessor Commands.


#elif

#elif expression

Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated.

expression	A constant value expression; that is, an expression that results in a constant value throughout the script.

Example

#define DEBUG 3                     ; Define DEBUG to have the value three

proc main

#if DEBUG == 2                      ; evaluates to 0 (false)

   usermsg s0                       ; not included

#elif DEBUG == 3                    ; evaluates to 1 (true)

   statmsg "String Zero: %s" s0     ; included

#endif                              ; terminates #if/#elif block

endproc

Comments

For more information, see the #define command.

See also

#define, #endif, #if. Preprocessor Commands.


#elifdef

#elifdef name

Allows conditional compilation by testing for the existence of a defined macro name after an #ifdef, #ifndef, #elifndef or another #elifdef statement has failed. For more information, see the #define command.

name	Macro name to test for existence.

Example

#define _DEBUG             ; Define _DEBUG as macro.

proc main

#ifndef _DEBUG             ; See if _DEBUG is undefined.

   usermsg "No Debug"      ; If so, display "No Debug".

#elifdef _DEBUG            ; If _DEBUG defined, display

   usermsg "Debug"         ; "Debug" message.

#endif

endproc

See also

#define, #ifdef, #ifndef, #else, #elifndef and #undef; Preprocessor Commands.


#elifndef

#elifndef name

Allows conditional compilation by testing for the non-existence of a defined macro name after an #ifdef, #ifndef, #elifdef or another #elinfdef statement has failed. For more information, see the #define command.

name	Macro name to test for non-existence.

Example

#define _DEBUG             ; Define _DEBUG as a macro.

proc main

#ifdef _DEBUG              ; See if _DEBUG is defined and

   usermsg "Debug"         ; if so, display debug message.

#elifndef _DEBUG           ; If _DEBUG not defined, display a

   usermsg "No Debug"      ; "No Debug" message.

#endif

endproc

See also

#ifdef, #ifndef, #elifdef, #else and #define; Preprocessor Commands.


#else

#else

Causes the ASPECT Compiler to process an alternate set of commands when the macro tested by an associated #ifdef, #ifndef, #elifdef or #elifndef is undefined. For more information, see the #define command.

Example

#define _LOCAL                       ; Define _LOCAL as a macro.

proc main

#ifdef _LOCAL                        ; See if _LOCAL is defined and

   usermsg "_LOCAL is defined!"      ; if so, display user message.

#else                   ; If _LOCAL is not defined, display

   errormsg "_LOCAL is not defined!" ; an error message.

#endif

endproc

See also

#define, #ifdef, #ifndef, #elifdef, #elifndef and #undef; Preprocessor Commands.


#endcomment

#endcomment

Marks the end of a comment block. Commands and text which follow #endcomment are processed normally.

Example

See the example for #comment.

See also

#comment; Preprocessor Commands.


#endif

#endif

Concludes the #if statement group. The ASPECT Compiler will process statements following the #endif command normally.

Example

proc main

#ifdef ASPDEBUG                          ; test if ASPDEBUG is defined

   usermsg "Debug compile is enabled"    ; issue debug compile message

#endif                                   ; terminate #ifdef block

endproc

See also

#define, #elifdef, #elifndef, #else, #ifdef, #ifndef and #undef; Preprocessor Commands.


#if

#if expression

Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

expression	A constant value expression; that is an expression that results in a constant value throughout the script.

Example

#define DEBUG 2            ; Define DEBUG to have a value of two

proc main

#if DEBUG == 2             ; evaluates to 1 because DEBUG == 2 is true

   usermsg s0              ; included only if DEBUG equals 2

#endif                     ; terminate #if block

endproc

Comments

For more information, see the #define command.

See Also

#define, #elif, and #endif; Preprocessor Commands.


#ifdef

#ifdef name

Allows conditional compilation by testing for the existence of a defined macro name.

Example

#define _NODISPLAY         ; Define _NODISPLAY as a macro.

proc main

#ifdef _NODISPLAY          ; See if _NODISPLAY is defined.

   set aspect display off  ; If so, turn off the display.

#endif

   transmit "Hello^M"      ; Interact with host system.

   transmit "GoodBye!^M"

   pause 5

endproc

Comments

For more information , see the #define command.

See also

#endif, #ifndef, #elifdef, #elifndef, #else and #define; Preprocessor Commands.


#ifndef

#ifndef name

Provides for conditional compilation by testing for the non-existence of a defined macro name.

Example

#undef _DIRECT             ; Make sure _DIRECT is undefined.

proc main

   ; Define _DIRECT to exclude the following modem initialization.

#ifndef _DIRECT            ; See if _DIRECT is undefined.

   InitModem()             ; Call proc to send commands to

#endif                     ; the modem.

endproc

proc InitModem

   transmit "AT&C1&D2^M"   ; Send commands to modem.

endproc

Comments

For more information, see the #define command.

See also

#ifdef, #elifdef, #elifndef, #else, #endif and #define; Preprocessor Commands.


#include

#include "filespec"

Merges commands from ASPECT source files during compilation.

"filespec"	The filespec must be a quoted string, but the described filename may have any valid extension. Typically, source files written for inclusion in other scripts are given extensions such as .inc or .h, however.

Example

#include "common.inc"      ; Include file containing common

                           ; procs and funcs.

proc main

   DispMsg("Hello World!") ; Display message using procedure

                           ; in an included file.

endproc

; common.inc - Common funcs and procs used in many scripts.

proc DispMsg

param string Message       ; Passed message string.

   usermsg Message         ; Display message in USERMSG box.

endproc

Comments

A #included file may contain other #include commands. There is no limit to the number of nested levels. #include commands can be placed within or outside of a procedure block. However, if it is to be used within a procedure or function block, the #included file cannot contain other procedures or functions.

#include can be used to set up source "header" files containing a set of #define commands, much like those used in the "C" programming language. Such files allow you to share macros and definitions between several scripts simply by #include-ing the appropriate file.

You can also use #included files to create a library of procedures and functions. For example, if your scripts often require a set of particular functions or procedures, you can place them in an #include file, then reference that file in any script that needs them.

Library files also offer an advantage if the procedures or functions need to be updated. If the source files reference the #include file for a particular function or procedure, you can update all references to the function or procedure simply by re-compiling them.

The ASPECT Compiler will not generate output for procedures and functions that aren’t called. Your libraries can be as large as you like without adding unnecessary code to the compiled .wax script!

Two useful files are provided with Procomm Plus that can be #included into your scripts. These files are pw4menu.inc, which defines all of Procomm Plus’s menu values, and vkeys.inc, which defines the virtual key codes as shown in Virtual Key Codes. Both of these files are installed to the default ASPECT directory.

See Also

Preprocessor Commands.


#undef

#undef name

Removes the current definition of a previously-defined macro.

Example

#define _DEBUG             ; Define _DEBUG as macro.

proc main

#ifdef _DEBUG              ; Check to see if _DEBUG macro is

   usermsg "DEBUG"         ; defined and if so, display a

#endif                     ; message.

#undef _DEBUG              ; Undefine _DEBUG

#ifndef _DEBUG             ; Check to see if _DEBUG is not

   usermsg "UNDEBUG"       ; defined and if not, display a

#endif                     ; message.

endproc

Comments

#undef is often paired with a #define command to create a "region" in a script where an identifier has a special meaning. #undef must also be used prior to redefining a macro that was previously #defined.

See also

#define and #ifdef; Preprocessor Commands.


$ACTIONBAR

An integer value reflecting an event from an Action Bar configured with a script notification code. $ACTIONBAR resets to 0 after it is accessed.


$ACTIONBARS

Returns a set of bit flags, indicating which Action Bars are currently displayed. Values are 0x01 (top), 0x02 (bottom), 0x04 (left), 0x08 (right) and 0x10 (floating).


$ACTIVEWIN

An integer value which is the window id of the currently-active window. Usually, this window has the current input focus. This value can be used in any command accepting a window id.


$ASPECTPATH

A string value containing the currently-defined Aspect Path. This value may be altered by a set aspect path command. When a script is launched, $ASPECTPATH is initialized to the drive and directory that contains the script’s .wax file, unless the script inherited its environment from another script. For more information, see "The ASPECT Script Environment".


$ASPMENU

An integer value, identifying the last command selected by the user from a custom menu created with menuitem. $ASPMENU is set to 0 after it’s accessed.

when $ASPMENU will "fire" whenever $ASPMENU’s value is non-zero. The procedure handling the when event should access the available menu value. Otherwise, the value will be automatically cleared when the procedure returns and the script will lose the value.


$CALLERID

A string containing the number when a caller id is recognized. $CALLERID is reset to null after it is read.


$CAPTURE

An integer value that returns non-zero when capturing incoming data to a file and 0 otherwise.


$CARRIER

An integer value reflecting the current status of the RS-232 Carrier Detect (CD) signal. $CARRIER is 0 if no carrier is detected (CD is low), or 1 if a carrier is present (CD is high). If used as a when variable, the when will "fire" whenever CD changes. $CARRIER is only available in Terminal and Telnet modes.


$CHAINEDFILE

If the current script was launched from another script using the chain command, this string variable will contain the name of the calling script. If the current script was not chained, this string will be null.

The $CHAINEDFILE variable could be used to restart the original script, or to branch based on the calling scriptname. The $SCRIPTMODE variable can be tested to determine how the current script was launched.


$CHATWIN

An integer value, equal to the window id of the Chat window or to 0 if the Chat window does not exist. This value can be used in any command accepting a window id.


$CNCTMSG

A string containing the modem result message matched upon a successful connection. The message should contain the baudrate for the connection or a connection error message - these are the same messages you would see when a connection is established in the Dialing Progress dialog.

$CNCTMSG is reset to null after it has been accessed.

If used as a when variable, the procedure handling the when event should access the available $CNCTMSG value. Otherwise, it will be automatically reset when the procedure returns and the script will lose the value.


$COL

An integer value equal to the current column cursor position in the Terminal display.


$COMPANY

A string variable containing the company name entered during the installation of Procomm Plus.


$CONNECTOPEN

This integer variable returns 1 if a connection is open and 0 otherwise. When a connection is open, you can read and write to the communications port provided no other activity (such as a file transfer) prevents it.


$CTS

An integer value reflecting the state of the RS-232 Clear to Send (CTS) line. $CTS equals 1 if CTS is high or 0 if CTS is low. $CTS is only available in Terminal and Telnet modes.  0 is also returned if the port is closed or invalid.


$DATAOPTIONS

A string value representing the name of the current option selected in the Current Data Options field in the Setup, Data, Data Options dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$DATE

A string value containing the current system date in the format specified for Short date style in the Date tab of the Regional Settings Properties dialog. (This dialog is available from the Control Panel.)


$DDEADVISE

The id number identifying the last ddeadvise statement whose gdatavar received a new value. If an id value was not specified for the ddeadvise statement, $DDEADVISE has a value of (-1).


$DDIRFNAME

A string containing the full path and filename of the current Connection Directory.


$DIALCHANGED

An integer value which returns the number of changes which have occurred in the Connection Directory that have not been saved to disk.  A successful dialadd, dialinsert and dialdelete will increment the count, as will any set command that alters Connection Directory data.

$DIALCHANGED is reset to 0 when a dialsave, dialload or dialcreate command is executed, or if the user opens a Connection Directory or creates a new one.


$DIALCONNECT

Identifies the name of the Connection Directory entry that established the current connection. $DIALCONNECT is set to null if the connection was made via manual dialing, or if no connection exists, or if a Connection Directory entry using a direct connection was selected and carrier is not detected.

$DIALCONNECT can be used in the dialclass command to determine which class the Connection Directory entry came from. A single class will be returned, unlike the general case where dialclass returns a value indicating all classes supported by the entry.


$DIALDIR

Returns the window id of the Connection Directory display. It returns 0 if the Connection Directory window does not exist. $DIALDIR can be used in any command accepting a window id.


$DIALENTRY

A string containing the name of the Connection Directory entry that launched the currently-executing script. $DIALENTRY is null if the script was not launched by a Connection Directory entry.

$DIALENTRY can be used in the dialclass command to determine which class (DATA, TELNET, or FTP) the Connection Directory entry came from. A single class will be returned, unlike the general case where dialclass returns a value indicating all classes supported by the entry.

The $SCRIPTMODE variable can also be tested to determine how the current script was launched.


$DIALING

Returns the type of the Connection Directory entry currently being dialed. Its value can be 0 for not dialing, 1 for DATA, 2 for FAX, or 4 for VOICE. $FAXSTATUS can be used to determine whether fax processes are on-going.


$DIALQUEUE

An integer value equal to the number of entries remaining in the dialing queue. This value is typically non-zero whenever $DIALING is non-zero.


$DIALSELECT

A string containing the name of the last Connection Directory entry dialed. It is null after a manual connect, or when no dial attempt has been made in the current Procomm Plus session.

$DIALSELECT can be used to determine which entry is being dialed when $DIALING returns a non-zero value, or to determine which entry is responsible for the current Procomm Plus settings since these settings change whenever a Connection Directory entry is dialed. $FAXSTATUS can be used to determine whether fax processes are active, since $DIALING will not reflect fax operations.

$DIALSELECT can also be used in the dialclass command to determine which class the Connection Directory entry came from. A single class will be returned, unlike the general case where dialclass returns a value indicating all classes supported by the entry.


$DTR

An integer value reflecting the state of the RS-232 Data Terminal Ready (DTR) line. $DTR equals 1 if DTR is high or 0 if DTR is low. $DTR is only available in Terminal and Telnet modes.  0 is also returned if the port is closed or invalid.


$ERRORNUM

An integer value, reflecting the last ASPECT run-time error.

when $ERRORNUM will "fire" whenever $ERRORNUM’s value is non-zero. The procedure handling the when event should read $ERRORNUM to reset it to 0. Otherwise, it will be automatically cleared when the procedure returns and the script will lose the value.

$ERRORNUM, when used with a when condition, can specify a procedure to handle non-critical run-time ASPECT errors. For example, the script could perform clean-up tasks before exiting, or choose to ignore the error altogether!

To prevent the display of error messages, use the set aspect errormsg command.


$EXITCODE

Contains the return value from a child script’s exit command. If no value was specified in the child script, this will equal 0.


$FATTR

A string containing the attributes of the last file found by a findfirst or findnext command.  It returns an 'N' to indicate a normal file with no attributes set.


$FAXFILE

A string containing the name of the .fax or .bft file currently being sent or received.


$FAXMESSAGE

A string value containing the last fax activity message. This is the message that appears in the Activity field in Fax Status.


$FAXOPTIONS

An string value representing the name of the current fax option set as it appears in the Current User Info list in Setup, Fax, User Info. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$FAXRECVCNT

An integer, indicating the number of faxes in the received-fax log.


$FAXSENDCNT

An integer, indicating the number of faxes remaining to be sent.


$FAXSTATUS

An integer, reflecting the state of the current modem/connection within Setup. Possible values are:

0	Not busy
1	Busy, sending
2	Busy, receiving
3	Successfully sent or received
4	Unsuccessfully sent or received
$FAXSTATUS will be set to 3 (Successfully sent or received) or 4 (Unsuccessfully sent or received) after an entire send or receive operation has been completed, even if the operation sent or received multiple faxes. $FAXFILE will update as necessary throughout the operation.

Similar to $XFERSTATUS, $FAXSTATUS will be reset to 0 after a value of either 3 or 4 has been read.

$FAXSTATUS behaves differently when a faxpoll command is executed. $FAXSTATUS will be set to 1 (Busy, sending), when a faxpoll command is being executed, but $FAXFILE will return null, since no file is being sent. $FAXSTATUS can then change from 1 to 2 (Busy, receiving), at which time $FAXFILE has the name of the file being received.


$FDATE

A string containing the creation date of the last file found by a findfirst or findnext command in the format specified for Short date style in the Date tab of the Regional Settings Properties dialog. (This dialog is available from the Control Panel.)


$FEXT

A string containing the extension, up to three characters following the period in a filename, of the last file found by a findfirst or findnext command.


$FILENAME

A string containing the full filename, with its extension, of the last file found by a findfirst or findnext command.  It contains the full filename, but no path or drive information.


$FILESPEC

A string containing the fully-qualified filespec of the last file found with a findfirst or findnext command.  The pathname portion of the string will be either the short or long path format specified in the findfirst command.  Note that findfirst does not expand the pathname portion to its long pathname equivalent.


$FLOWSTATE

An integer indicating the current state of software or hardware flow control. $FLOWSTATE equals 1 if either form of flow control has paused the flow of data. Otherwise, it is 0.   0 is also returned if the port is closed or invalid.


$FLTIME

A long value of the type timeval, indicating the time and date stamp of the last file found by a findfirst or findnext command. For more information, see "ASPECT Conventions".


$FNAME

A string containing the base filename, excluding its extension, of the last file found by a findfirst or findnext command.


$FOCUSWIN

An integer  value, equal to the window id of the window which currently has the input focus. The window with the input focus will receive data typed at the keyboard. This value can be used in any command accepting a window id.


$FSIZE

A long value equal to the size, in bytes, of the last file returned by a findfirst or findnext command.


$FTIME

A string containing the creation time for the last file found by a findfirst or findnext command. This string uses the format specified for Time style in the Time tab of the Regional Settings Properties dialog. (This dialog is available from the Control Panel.)


$FTPCONNECT

An integer, reflecting the state of the current FTP connection. Possible values are:

0	Idle.

1	Connecting.

2	Connected.

3	Connection failed or shutdown.

If $FTPCONNECT equals 3, it resets to 0 after it is accessed.


$FTPOPTIONS

A string value representing the name of the current FTP option set as it appears in the Current FTP Options list in Setup, Internet, FTP Options. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$FTPSTATUS

An integer value reporting the status of remote FTP operations. Possible values are 0 for idle, 1 for busy, 2 for success, and 3 for failure. If the variable is read when its value is 2 or 3, it is automatically reset to 0.


$IPADDRESS

A string value.

In FTP mode, it contains the host IP address.

In News or Mail modes, it contains the IP address of the news or email server to which Procomm Plus is connected.

In Telnet mode, it contains the host IP address.

$IPADDRESS is reset whenever Procomm Plus switches communication modes; it will always be null when Procomm Plus is not using an active Internet connection.


$KEYHIT

An integer value equal to the number of keyhits available in the keyboard buffer. If no keyhit is available, $KEYHIT will return 0. $KEYHIT will always return 0 when set aspect keys OFF has been issued.

when $KEYHIT will "fire" whenever $KEYHIT’s value is non-zero. The procedure handling the when event should read the available key value using the keyget command to reset $KEYHIT. Otherwise, the when $KEYHIT will process repeatedly for the same value.


$LMOUSEEVENT

An integer value equal to 1 whenever the left mouse button is pressed down while the mouse pointer is within the boundaries of the client area of Procomm Plus in Data mode. For more information, see the uwincreate command.


$LMOUSESTATE

An integer value, reflecting the state of the left mouse button. Equal to 1 if the button is depressed, 0 otherwise.


$LMOUSEWIN

An integer value reflecting the window ID over which the mouse event occured.


$LMOUSEX

An integer value, set to the X-coordinate of the mouse pointer whenever the left mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the left mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command.


$LMOUSEY

An integer value, set to the Y-coordinate of the mouse pointer whenever the left mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the left mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command.


$LTIME

A long value of type timeval representing the number of seconds between midnight of January 1, 1970 and the current system time and date. For more information on timevals, see "ASPECT Conventions".


$MAILOPTIONS

A string containing the name of the currently selected option set in the Current Mail Options field of the Setup, Internet, Internet Mail dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$MAINWIN

An integer value equal to the window id of the active application’s main (top level) window. This value can be used in any command accepting a window id.


$MAPIENABLED

An integer value representing the status of MAPI mail services: a 1 is returned if MAPI services are available, a 0 otherwise.


$MCIDEVICEID

An integer value that reports the device ID of the last device to send a notification. This information can be used along with the string returned by a mcisend command.


$MCINOTIFY

An integer value that will be set to the result of a mciexec or mcisend command if the notify parameter was specified. Possible values are:

1	Operation succeeded
2	Operation superceded (by another command notification request)
4	Operation aborted
8	Operation failed
After this variable is accessed, $MCINOTIFY is reset to 0.


$METAKEYS

An integer value, indicating the status of the Meta Keys display. The value is 1 if the keys are displayed or 0 if they are hidden.


$MISC

A string equal to the contents of the Miscellaneous field in the last Connection Directory entry dialed. This string is initialized to the corresponding string in a Connection Directory entry whenever that entry is dialed. It is null when a dialing attempt has not been made in the current Procomm Plus session.


$MMOUSEEVENT

An integer value equal to 1 whenever the middle mouse button is pressed down while the mouse pointer is within the boundaries of the client area of Procomm Plus in Data mode. For more information, see the uwincreate command.


$MMOUSESTATE

An integer value, reflecting the state of the middle mouse button. Equal to 1 if the button is depressed, 0 otherwise.


$MMOUSEWIN

An integer value reflecting the window ID over which the middle mouse button event occurred.


$MMOUSEX

An integer value, set to the X-coordinate of the mouse pointer whenever the middle mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the middle mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command.


$MMOUSEY

An integer value, set to the Y-coordinate of the mouse pointer whenever the middle mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the middle mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command.


$MODEMCONNECT

An string value representing the name of the current system connection as it appears in the Current Modem/Connection list in the Setup, System, Modem Connection dialog.


$MONITORWIN

Returns the window id of the Monitor Mode window. It is 0 if the Monitor Mode window does not exist. This value can be used in any command accepting a window id.


$NEWSOPTIONS

A string containing the name of the currently selected options set in the Current News Options field of the Setup, Internet, News Reader dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$NEWSSTATUS

A integer that returns 1 when news is being retrieved and 0 when the News Client is idle.


$NULLSTR

Returns a null or empty string. $NULLSTR can be used to test a string variable for the null condition.


$NUMCOLORS

An long value equal to the number of colors supported by the current Windows display driver. Typical values are 2, 16 and 256.


$NUMTASKS

Returns the number of tasks currently running in Windows. Note that this number may be greater than the number of "standard" Windows tasks returned with the firsttask and nexttask commands. An integer value.


$OBJECT

Contains the id value for the last User window object selected by the user. Selectable objects include bitmaps, icon buttons, pushbuttons and hotspots. $OBJECT is reset to 0 after it is accessed.

when $OBJECT will "fire" whenever $OBJECT’s value is non-zero. The procedure handling the when event should access the available $OBJECT value. Otherwise, it will be automatically cleared when the procedure returns and the script will lose the value.


$OS

Identifies the operating system running the current session. A string value.


$OSVER

Identifies the version of the operating system. A string value.


$PARENTFILE

A string value, $PARENTFILE contains the name of the script that will resume execution when the current script terminates. If the script was spawned from another script, this variable identifies the script that spawned it. The $SCRIPTMODE variable can be tested to determine how the current script was launched.

A chained script can also have a parent script.


$PASSWORD

The contents of the Password field in the last Connection Directory entry dialed. This string is initialized to the corresponding string in a Connection Directory entry whenever that entry is dialed. It is null when no dial attempt has been made in the current Procomm Plus session.


$PKRECV

An integer, reflecting the status of a pkrecv command. Possible values are:

0	Packet not received or idle (default state)
1	Packet received successfully
2	Timeout occurred, packet not received
3	Errors occurred, packet not received
$PKRECV is reset to 0 after it’s accessed.

when $PKRECV will "fire" whenever $PKRECV’s value is non-zero. The procedure handling the when event should access the available $PKRECV value. Otherwise, it will be automatically cleared when the procedure returns and the script will lose the value.


$PKSEND

An integer, reflecting the status of a pksend command. Possible values are:

0	Packet send in progress or idle
1	Packet sent successfully
2	Timeout occurred, packet not sent
3	Errors occurred, packet not sent
4	Packet send canceled by receiver, packet not sent
$PKSEND is reset to 0 after it’s accessed.

when $PKSEND will "fire" whenever $PKSEND’s value is non-zero. The procedure handling the when event should access the available $PKSEND value. Otherwise, it will be automatically cleared when the procedure returns and the script will lose the value.


$PLAYBACK

An integer value, equal to 1 if a file is currently being played back. Otherwise, it is 0.


$POINTERTASK

An integer value, equal to the id of the task over which the mouse pointer is currently positioned. This value can be used in any command which accepts a task id.


$POINTERWIN

An integer, equal to the id of the window over which the mouse pointer is currently positioned. This value can be used in any command accepting a window id.


$POINTERX

An integer, containing the absolute X screen coordinate of the current mouse pointer position.


$POINTERY

An integer, containing the absolute Y screen coordinate of the current mouse pointer position.


$PROTOCOL

A string value representing the name of the current protocol option set as it appears in the Current Transfer Protocol list in Setup, Data, Transfer Protocol. The itemfind and itemname commands can obtain the indices and name strings for all available protocols.


$PWACTIVE

An integer value, equal to 1 if the Procomm Plus session that launched the script is currently the active application. Equal to 0 otherwise.


$PWLOCALPATH

A string, containing the path where Procomm Plus files are stored. The dialload, dialsave and dialcreate commands all use the local task path. Meta Key, Translate Table, Action Bar and keyboard files are also stored there. Also see $PWTASKPATH.

In a network installation, certain files are installed local to the user such as Connection Directories and saved setup values. Others, such as executable files, are not.


$PWMAINWIN

An integer value, equal to the window id of the Procomm Plus main or top-level application window. This value can be used in any command accepting a window id.


$PWMENUBAR

Contains the integer id value of the current Procomm Plus menu bar. This value is used with the menupopup, menuitem and menushow commands. This value may be 0 if there is no menu displayed.


$PWMENUDEF

An integer value that returns the id of the default menu bar for Procomm Plus's current mode of operation.


$PWMODE

An integer value that contains the current execution mode of Procomm Plus. Possible values are:

0	Procomm Plus is in Terminal mode.

1	Procomm Plus is in FTP mode.

2	Not used anymore.

3	Procomm Plus is in MAIL mode.

4	Procomm Plus is in NEWS mode.

5	Procomm Plus is in TELNET mode.


$PWTASK

An integer value, equal to the Procomm Plus task id. This value can be used in any command which accepts a task id.


$PWTASKPATH

Returns Procomm Plus’s executable directory path. A string value. Also, see $PWLOCALPATH.


$PWTITLEBAR

The current contents of the Procomm Plus application title bar. A string value.


$PWVER

A string value containing the version number of Procomm Plus.


$PWWINSTATE

An integer value, reflecting the current status of Procomm Plus. Possible values are:

0	Procomm Plus is minimized
1	Procomm Plus is restored
2	Procomm Plus is maximized


$QUICKSELECT

An integer value, reflecting the state of the Procomm Plus Quick Selection Line. Equals 1 if it is displayed, 0 otherwise.


$RMOUSEEVENT

An integer value equal to 1 whenever the right mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. For more information, see the uwincreate command.


$RMOUSESTATE

An integer value, reflecting the state of the right mouse button. Equal to 1 if the button is depressed, 0 otherwise.


$RMOUSEWIN

An integer value reflecting the window ID over which the mouse event occurred.


$RMOUSEX

An integer value, set to the X-coordinate of the mouse pointer whenever the right mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the right mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command.


$RMOUSEY

An integer value, set to the Y-coordinate of the mouse pointer whenever the right mouse button is pressed down within the boundaries of the client area of Procomm Plus in Data mode. The value is updated again when the right mouse button is released. Coordinate values are relative to the window specified with the set aspect mousecoord command..


$ROW

The current row cursor position within the Terminal display. An integer value.


$RTS

An integer value reflecting the state of the RS-232 Ready to Send (RTS) line. Will equal 1 if RTS is high or 0 if RTS is low. $RTS is only available in Terminal and Telnet modes.  0 is also returned if the port is closed or invalid.


$RXCOUNT

An integer value, equal to the number of characters remaining in the receive data buffer. These characters may or may not be available to ASPECT depending on which process currently "owns" the buffer. $RXCOUNT is only available in Terminal and Telnet modes.

when $RXCOUNT will "fire" whenever $RXCOUNT’s value is non-zero. The procedure handling the when event should perform some action to clear the buffer and reset $RXCOUNT. Otherwise, the when $RXCOUNT will process repeatedly for the same data.


$RXDATA

An integer value, equal to the number of characters the script can retrieve in the received data buffer. $RXDATA is only available in Terminal and Telnet modes.

when $RXDATA will "fire" whenever $RXDATA’s value is non-zero. The procedure handling the when event should perform some action to clear the buffer and reset $RXDATA. Otherwise, the when $RXDATA will process repeatedly for the same data.


$SCRIPTENV

An integer value, equal to 1 if the ASPECT environment the current script has is being shared with the script that launched it; otherwise 0. For further information, see the execute command, and "Script Spawning and Chaining".


$SCRIPTFILE

A string, containing the fully-qualified path and filename of the currently-executing script file.


$SCRIPTMODE

An integer value reflecting how the currently-executing script was launched. Possible values are:

0	Normal execution.
1	Spawned script (execute issued by another script). Note that $PARENTFILE contains the name of the script which spawned the currently-executing script.
2	Chained script (chain command issued by another script). Note that $CHAINEDFILE contains the name of the script which chained the currently-executing script.
3	Executed from the command line at the startup of Procomm Plus. Note that the pre-defined global variable I0 contains the number of arguments passed to the script from the command line, and S0 through S9 contain the values of those arguments. For more information about these variables, please see Pre-defined Global Variables.
4	Remote script command.
5	Executed from a Connection Directory entry. Note that $DIALENTRY contains the name of the Connection Directory entry.
6	Executed from distinctive ring.
7	Executed from DDE execute.
8	Executed from DDE aspectcmd command.
9	Executed from a Caller ID Directory match. Note that $CALLERID contains the caller ID number associated with the matching Caller ID Directory entry.


$SCROLLBACK

An integer value representing the status of scrollback mode: 0 is returned if it is inactive, 1 if it is active.


$SERIALNUM

The serial number of this copy of Procomm Plus. A string variable.


$SETUP

Returns the window id of the Setup window, or 0 if the Setup window does not exist. This value can be used in any command accepting a window id.


$SFILENAME

A string containing the full filename, with its extension, of the last file found by a findfirst or findnext command.  The filename is in the MS-DOS standard 8.3 format, containing the filename and extension, but no path.


$STATIONID

A string value representing the station id of the remote side of the current fax connection. The value will be null if the current fax connection is not sending or receiving.


$STATMSG

A string value containing the current status line message, if any.


$STATUSLINE

An integer value, equal to 1 if the Procomm Plus status line is displayed; 0 otherwise.


$TASK

An integer value, equal to the task id of the active Windows application. This value can be used in any command which accepts a task id.


$TELNETOPTIONS

A string value representing the name of the current telnet option set as it appears in the Current Telnet Options list in the Setup, Internet, Telnet dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$TERMCOLORS

An string value representing the name of the current terminal colors option set as it appears in the Current Terminal Colors list in the Setup, Data, Terminal Colors dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$TERMCOLS

An integer value, equal to the number of columns supported by the current emulation. Note that this value does not change if the Terminal window is resized.


$TERMFONT

An string value representing the name of the current terminal font option set as it appears in the Current Terminal Font list in the Setup, Data, Terminal Fonts dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$TERMINAL

A string value equal to the name of the current emulation option set as it appears in the Current Terminal list in the Setup, Data, Terminal Options dialog. The itemfind and  itemname commands can obtain the indices and name strings for all available emulations.


$TERMROWS

An integer value equal to the number of rows supported by the current emulation. Note that this value does not change if the Terminal window is resized.


$TIME

The current system time in a string in the format specified for Time style in the Time tab of the Regional Settings Properties dialog. (This dialog is available from the Control Panel.)


$TIME24

The current system time in 24-hour format. A string, with the time formatted using information from the Time style field in the Time tab of the Regional Settings Properties dialog. (This dialog is available from the Control Panel.) A leading 0 is prefixed to an hour less than 10, and the AM/PM/24-hour string is omitted.


$TITLEBAR

A string value, containing the caption or title text of the active application.


$TXCOUNT

An integer value, equal to the number of characters remaining to be transmitted. $TXCOUNT is only available in Terminal and Telnet modes.


$TXDATA

An integer value, equal to the number of characters that ASPECT can send to the transmit data buffer without causing an overflow. This value is set to 0 when further data cannot be transmitted. $TXDATA is only available in Terminal and Telnet modes.

The value returned is not necessarily the limit of available space that ASPECT has to transmit data. Provided that the additional memory is available, Procomm Plus will dynamically allocate more space to accomodate the transmitted data.


$USERDISK

An integer value, reflecting the disk drive specified in the current User Path. $USERDISK equals 1 for drive A, 2 for drive B, up to 26 for drive Z.


$USERDISKSTR

A string value, containing the "name" of the currently active drive. For example, "C:".


$USERID

A string containing the User ID field in the last Connection Directory entry dialed. This string is initialized to the corresponding string in a Connection Directory entry whenever that entry is dialed. It is null when no dial attempt has been made in the current Procomm Plus session.


$USERNAME

A string containing the name of the registered user of this copy of Procomm Plus.


$USERPATH

Contains the script’s current working directory path (for example, "c:windows"). When a script is launched, $USERPATH is initialized to the drive and directory that contains the script’s .wax file, unless the script inherited its environment from another script. For more information, see "The ASPECT Script Environment".

The string does not end with a trailing backslash unless the path is the root directory of the current drive. $USERPATH can be changed using the chdir command.


$USERWIN

An integer value, equal to the window id of a User window. This value can be used in any command accepting a window id.


$UWINACTIVE

An integer value that returns the status of the User window. 0 for inactive, 1 for active.


$VOLUME

A string containing the disk volume label of the current drive specified in the ASPECT User Path. For example, "COMPRESSED".


$WINCOLORS

An string value representing the name of the current window colors option set as it appears in the Current Window Colors list in the Setup, Data, Window Colors dialog. The itemname and itemfind commands can obtain the indices and name strings for all option entries.


$WINPATH

A string value containing the pathname of the Windows directory, which usually contains applications, initialization files and help files.


$XFERFILE

A string, reflecting the name of the file currently being transferred.


$XFERSTATUS

Indicates the status of the current file transfer. If no file transfer is in progress, $XFERSTATUS is set to 0, but it can also be 1 for file transfer in progress, 2 for file transfer completed successfully, or 3 for file transfer aborted.

The when $XFERSTATUS command will "fire" when the value of $XFERSTATUS changes to a value other than 0. Values of 2 or 3 are reset to 0 after $XFERSTATUS has been accessed.

The procedure handling the when event should access the available $XFERSTATUS value. Otherwise, it will be automatically cleared when the procedure returns and the script will lose the value.


$XOFFRECV

An integer value, equal to 1 if an XOFF (ASCII 17 or <Ctrl><Q>), has been received by Procomm Plus. 0 is also returned if the port is closed or invalid.


$XOFFSENT

An integer value, equal to 1 if an XOFF(ASCII 17 or <Ctrl><Q>) has been sent by the Windows communication driver to halt the flow of incoming data. It cannot be set true by pressing <Ctrl><Q> at the keyboard. 0 is also returned if the port is closed or invalid.


$XPIXELS

An integer equal to the horizontal resolution of the current display screen in pixels.


$YPIXELS

An integer equal to the vertical resolution of the current display screen in pixels.


A Dialog Box Example

  Related Topics

In the example for Getting User Input, we created a very simple dialog box for string input using the sdlginput command. You can also create more complex dialog boxes that allow you to input information by means of edit boxes, buttons, check boxes, option buttons and other controls. If you’ve used many Windows programs, including Procomm Plus, you’ve entered information by using several kinds of dialog boxes and controls.

The easiest way to create complex dialog boxes in ASPECT is to use the Dialog Editor, which you can access either from the Procomm Plus program group or from the Tools | Scripts menu. The Dialog Editor covers this utility in detail. Of course, you can also "hand code" dialog boxes and achieve the same results but that makes the process much more tedious!

In this example, you create a dialog that contains three option buttons, labeled First, Second and Third, and a button labeled OK. After compiling the script, you select one of the option buttons and the OK button. The script displays a message box reporting the radio button you selected. Of course, this script is not very useful but it’s a good building block that you can use to perform a variety of tasks.

Use the Dialog Editor to create a dialog box, giving it the caption "Dialog Example". Put several option buttons on the dialog using the Controls menu, and change their labels to First, Second, and Third respectively. Next, change the variable name associated with the option button group to "WhichButton".

Now add a button. Change its label to "OK".

Choose Save As... from the Dialog Editor’s File menu and save your dialog box as TEST1.WAS. Go back to Procomm Plus and choose Compile/Edit from the Scripts menu, or select the Compile/Edit icon on the Action Bar. Edit TEST1.WAS by selecting it from the list of files, then clicking on Edit in the dialog. Depending on your exact placement of the dialog controls, the code generated by the Dialog Editor looks something like this:

dialogbox 0 0 0 200 100 11 "Dialog Example"

   radiogroup 1 WhichButton

      radiobutton 2 50 20 35 10 "&First"

      radiobutton 3 50 38 35 10 "&Second"

      radiobutton 4 50 56 35 10 "&Third"

   endgroup

   groupbox 5 21 8 51 65 "Button Choices"

   pushbutton 6 27 80 40 14 "&Exit" default

   pushbutton 7 130 59 40 14 "OK"

enddialog

This fragment of code will paint your dialog box on the screen. The various numeric parameters control the sizing and placement of their corresponding objects. They can be adjusted by hand, if you like, to correct any alignment problems.

Now that you have the code for a dialog box, let’s create a procedure for it:

proc main                         ; Beginning of main procedure

   MakeDialog( )                  ; Call dialog procedure and when

   pause 5                        ; execution returns pause for 5 seconds

endproc                           ; and exit the script file.

proc MakeDialog

   integer WhichButton            ; This variable takes on a particular value based

                                  ; on the radio button selected.

   dialogbox 0 0 0 200 100 11 "Test"

      radiogroup 1 WhichButton

         radiobutton 2 50 20 28 10 "&First"

         radiobutton 3 50 38 28 10 "&Second"

         radiobutton 4 50 56 28 10 "&Third"

      endgroup

      groupbox 5 21 8 51 65 "Button Choices"

      pushbutton 6 27 80 40 14 "&Exit" default

   enddialog

endproc                           ; Return to proc main.

The call to MakeDialog causes script execution to jump to that procedure. MakeDialog paints the dialog you designed, then returns control to the main procedure.

Currently, your program does nothing except briefly put the dialog box on the screen. In order to be of any use, the script needs to wait for the user to press the button, and then determine which option button was selected.

Each dialog control has its own unique id that is returned by the dlgevent command when you select that control. If you click on the button in the example above and read the result with the dlgevent command, ASPECT returns the id of the OK button, which is 5. Let’s take a look at our script file and add some commands to handle the dialog events and display.

#define TRUE    1

integer WhichButton                ; Global variable used for radio’s.

;********************************************************************

; MAIN

; The main procedure calls MakeDialog to construct and display a dialog.

; It waits in an endless loop for a dialog event. When a dialog event occurs

; that is, when the user chooses a option button or presses the button,

; the procedure CheckIt is called.

; Calls: MakeDialog, CheckIt, ShowIt

; Modifies global variables: None

;*********************************************************************

proc main                          ; Start of main procedure.

   integer Event                   ; Variable used for dialog events.

   MakeDialog()                    ; Show the dialog box.

   while TRUE                      ; Sit and wait for an event.

      dlgevent 0 Event             ; Get any event for our dialog box.

      switch Event                 ; Evaluate the dialog event.

         case 0                    ; 0 indicates no dialog event.

         endcase

         case 2                    ; These case statements indicate

         case 3                    ; that one the radio buttons was

         case 4                    ; selected.

         endcase

         default                   ; This case corresponds to either an

            exitwhile              ; exit case or the OK button.

         endcase

      endswitch

   endwhile

   ShowIt()                        ; Call routine to display radio selection.

endproc                            ; End of main procedure.

;********************************************************************

; MAKEDIALOG

; MakeDialog constructs and displays the dialog box and returns to main.

; Calls:

; Called by: main

; Modifies global variables: WhichButton (initializes it to 0)

;*********************************************************************

proc MakeDialog

   WhichButton = 0                 ; Initialize WhichButton variable.

   dialogbox 0 0 0 200 100 11 "Test"

      radiogroup 1 WhichButton

         radiobutton 2 50 20 28 10 "&First"

         radiobutton 3 50 38 28 10 "&Second"

         radiobutton 4 50 56 28 10 "&Third"

      endgroup

      groupbox 5 21 8 51 65 "Button Choices"

      pushbutton 6 27 80 40 14 "&Exit" default

   enddialog

endproc                            ; Return to proc main.

;********************************************************************

; SHOWIT

; ShowIt checks the value of the global variable WhichButton

; after the button is pushed. WhichButton is 1 if the first radio button

; was selected, 2 if the second was selected, 3 if the third was selected.

; A different message is displayed based on this value.

; Calls:

; Called by: main

; Modifies global variables:

;*********************************************************************

proc ShowIt

   string DisplayString            ; Local variable for display in message box.

   switch WhichButton              ; Evaluate the WhichButton variable.

      case 2

         DisplayString = "The First option button"

      endcase

      case 3

         DisplayString = "The Second option button"

      endcase

      case 4

         DisplayString = "The Third option button"

      endcase

   endswitch

   usermsg " %s was selected." DisplayString

endproc

Notice the use of a format string in the usermsg command above. The format specifier "%s" is replaced in the sentence by the value of the variable DisplayString. For more information on the format string, see Formatting Text and Data.

Exercises

Write a script that paints a dialog box with at least three different controls and displays the value returned by the dlgevent command when the controls are selected.

Write a procedure similar to the sdlginput ASPECT command that displays a dialog box with an edit box, title, and button. To make the job easy, use the Dialog Editor to create your dialog box.


A User Window Example

  Related Topics

The graphical capability of Procomm Plus isn’t limited to dialog boxes! You can create User windows within the Terminal workspace. User windows may contain metafiles, bitmaps, icons, icon buttons, pushbuttons, hotspots and various other graphical elements. Some of these objects may be created interactively in the User Window Editor utility, which operates similar to the Dialog Editor. Others may already exist in other graphic or executable files, and only their source and placement needs to be specified in the script. Please see The User Window Editor for a discussion of the User Window Editor.

By positioning graphic objects in a User window you define, you can create custom applications that use the Procomm Plus communications engine, yet have your own look and feel. Since you’re now a master at reading and writing ASPECT scripts, let’s use what we’ve learned and the various User window commands to create an icon bar similar to the Procomm Plus Action Bar but located at the left side of the Terminal window rather than on top!

#define TRUE    1

string ABARLeft                      ; Name of the left icon bar.

proc main

   fetch actionbar left ABARLeft     ; Get the current left Action Bar.

   set actionbar left ""             ; Turn off the left Action Bar.

   when USEREXIT call ResetAbar      ; Wait for a user exit event.

   set aspect path $PWTASKPATH

   ; Create a user window on which to display our icons for our left

   ; icon bar. Procomm Plus stores it icons in pw4icons.dll.

   uwincreate LEFT PIXELS 42 128 128 128 BITMAP

      iconbutton 1 0 0 "" "pw4icons.dll" 5 BACKGROUND

      iconbutton 2 0 390 "" "pw4icons.dll" 26 BACKGROUND

      iconbutton 3 0 780 "" "pw4icons.dll" 25 BACKGROUND

      iconbutton 4 0 1170 "" "pw4icons.dll" 107 BACKGROUND

      iconbutton 5 0 1560 "" "pw4icons.dll" 90 BACKGROUND

      iconbutton 6 0 1950 "" "pw4icons.dll" 91 BACKGROUND

   uwinpaint                         ; Draw the new user window.

   while TRUE                        ; Loop forever.

      switch $OBJECT                 ; Evaluate the uwin event.

         case 1                      ; Dialing Directory selected.

            sendkey ALT 'D'

         endcase

         case 2                      ; Setup selected.

            sendkey ALT 'S'

         endcase

         case 3                      ; Scrollback selected.

            sendvkey 0x0C26

         endcase

         case 4                      ; Hangup selected.

            hangup

         endcase

         case 5                      ; Send file selected.

            sendkey ALT 'O'

            sendkey 'S'

         endcase

         case 6                      ; Receive file selected.

            sendkey ALT 'O'

            sendkey 'R'

         endcase

      endswitch

      endwhile                       ; Bottom of loop.

endproc                              ; End of proc main.

proc ResetAbar

        set actionbar left ABARLeft  ; Restore the left Action Bar.

        exit

endproc                              ; End of ResetAbar procedure.

In our example, we use the uwincreate command to define our User window. This command tells Procomm Plus what the User window is to look like on the Terminal workspace. In this case, we’re telling ASPECT that we want a User window that’s 42 pixels wide and gray.

Take a look at the iconbutton commands following uwincreate. Unlike dialog box commands, User window commands are not restricted to code structures or clauses, and can appear anywhere after the uwincreate declaration.

$OBJECT is a system variable that contains the id of the last User window object selected. If no User window object has been selected, the value of $OBJECT is false or zero. We use a switch ... case construct to evaluate the state of $OBJECT and the sendkey and sendvkey commands to emulate what happens when an icon is selected from a real Action Bar.

Read the descriptions for bitmap, hotspot, icon, iconbutton, metafile, pushbutton, uwincreate and uwinpaint for more information about User windows and their objects.

Exercise

Modify the sample above so that it displays an icon bar on the bottom of the screen instead of the left side. Use the User Window Editor if you like.

Advanced exercise

Write a script that puts a Windows .BMP file in the User window along with a hotspot that, when selected, exits the script.


A simple logon script

  Related Topics

The most common use of ASPECT is the automation of routine communication tasks such as signing on to a BBS or an information service like CompuServe, Delphi, or MCI. You can easily create logon scripts using the Procomm Plus Script Recorder.

The following topics discuss creating and compiling a simple logon script with the Script Recorder:

Using the Script Recorder

Compiling a Script

Using the Script Recorder

To start the Script Recorder, choose Start Recorder from the Tools | Scripts menu, or choose the Record icon on the Action Bar before going on-line. While the Script Recorder is running, Procomm Plus builds a script file based on prompts sent to you by the system you’re calling and the characters you type in response.

Select Stop Recorder or click the Record icon button again to stop the recording process. Procomm Plus displays a dialog asking you for the name of your script file. Choose a file name that describes the file you’re creating. For this example, let’s say that the name of our script file is called "BBS.WAS". The script created by the Script Recorder looks something like this:

; Recorded script. Editing may be required.

proc main

   waitfor "Name: "

   transmit "Jane^M"

   waitfor "Password: "

   transmit "1234^M"

endproc

The transmit statements represent what you normally type when logging on. The waitfor statements represent prompts sent to you by the remote system. Notice the "^M" characters at the end of the transmit statements. "^M" represents a carriage return. It appears in the script file at any point you press the <Enter> key.

ASPECT scripts are organized or structured by procedure and function blocks. Every script file requires at least one procedure called main. A proc main and an endproc statement pair represent the beginning and end of the main procedure, respectively.

Compiling a Script

After you create a logon script you must compile it. Choose Compile/Edit from the Tools | Scripts menu or the Action Bar. This opens the Compile/Edit ASPECT File dialog.  The name of the file you created appears in the list box. Select it, either by clicking on it, or by tabbing into the list and moving the focus with the cursor keys. After the filename is selected, notice that the "Notes" field in the dialog displays the first line of your recorded script.

If the first line of your script is a comment, marked with a semicolon in the first character on the first line, it will be displayed in the Notes field. If you have a variety of scripts, you can use the Notes field to help you distinquish between them!

To compile your script, click on the Compile... button. The ASPECT Script Compiler dialog appears.  The ASPECT Script Compiler automatically processes your script when you click on Compile... or Compile and Run... with a file selected. It reports its progress, and any errors or warnings in the Message List window.

If the compile is successful, the ASPECT Script Compiler creates a file with a .wax extension that Procomm Plus can run.

Notice the Edit source file button in the compiler window. If the compiler detects a syntax error in your source file, you can click on this button to load the source file into your editor to resolve the problem.

Click on OK to close the ASPECT Script Compiler.

To use your new script file with a Connection Directory entry, select it from the Script list box when editing the entry. Then, whenever you connect to the host system listed in the entry, Procomm Plus automatically launches the new script. You won’t have to enter your name and password anymore!

Remember, if you make any changes to the script source .was file, you must recompile it to make Procomm Plus aware of those changes. Compiled scripts cannot be uncompiled.

Exercise

Write and compile a logon script for a BBS or information service you call.

Try using the Script Recorder.


ADM31, ESPRIT3, IBM3270, TVI910, TVI912, TVI920, TVI925, TVI950, TVI955, WYSE50, WYSE60, WYSE100
ADM31, ESPRIT3, IBM3270, TVI910, TVI912, TVI920, TVI925, TVI950, TVI955, WYSE50, WYSE60, and WYSE100  Set/Fetch Statements

emulation protectattr DIM | REVERSE | UNDERLINE OFF | ON

Determines how protected text is displayed in the Terminal window for the specified emulation. This command corresponds to the Protected Attribute options in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.


ADM31, IBM3101, IBM3161, WYSE50, WYSE60
ADM31, IBM3101, IBM3161, WYSE50, and WYSE60  Set/Fetch Statements

emulation blockmode OFF | ON

Enables or disables block mode for the specified emulation. This command corresponds to the Block mode check box in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.


ADM31, IBM3270, TVI950, TVI955, WYSE50, WYSE60, and WYSE100 Set/Fetch Statements

emulation statusattr NORMAL | REVERSE | UNDERLINE

Determines how the terminal status line is displayed for the specified emulation. This command corresponds to the Terminal Status Line options in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for NORMAL, 1 for REVERSE or 2 for UNDERLINE.

emulation statusline OFF | ON

Enables or disables the terminal status line for the specified emulation. This command corresponds to the Terminal Status Line Display check box in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.


ADM31, WYSE50, and WYSE60 Set/Fetch Statements

emulation endsequence CRLF_ETX | US_CR

Determines the characters which signify the end of a line or block for the specified emulation. If CRLF_ETX is specified, Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs and end transmission characters, ASCII 3, mark the end of a line or block. If US_CR is used, US characters, ASCII 31 and Carriage Returns mark the end of a line or block. This command corresponds to the End of line/block sequence field in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for CRLF_ETX or 1 for US_CR.


ANSIBBS and IBMPC Set/Fetch Statements

emulation declinewrap OFF | ON

Determines how the ANSI and IBMPC emulations wrap lines that extend beyond the end of an emulation row. If ON, the emulations use the DEC Terminal method, which means Carriage Returns and the first Linefeed received are ignored when incoming data is wrapped to the following line. This command corresponds to the Use DEC linewrap mode check box in the Setup, Data, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.

emulation escapem MUSIC | DELLINE

Determines how the ANSI and IBMPC emulations respond to the ANSI Escape-M (^[M) sequence. If DELLINE is specified, the sequence is treated as a line delete command. If MUSIC is specified, the emulation "eats" or ignores ANSI music sequences. This command corresponds to the Treat Music sequences as Delete Line check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for MUSIC or 1 for DELLINE.


ASCII Protocol Set/Fetch Statements

The following set/fetch statements apply to only the ASCII transfer protocol. These commands correspond to the options in Setup, Data, Transfer Protocol, with the Current Protocol field set to ASCII.

ascii abortdnld KEEP | DELETE

Determines whether files aborted during an ASCII file download are kept or deleted. This command corresponds to the Delete aborted downloads check box. fetch returns 0 for KEEP or 1 for DELETE.

ascii blankexpand OFF | ON

Determines whether blank lines are expanded to spaces during ASCII file uploads. This command corresponds to the Expand blank lines check box. fetch returns 0 for OFF or 1 for ON.

ascii charpace integer

Specifies the length of a pause after a character is transmitted from a file during an ASCII file upload. This command corresponds to the Millisecond delay between characters field. fetch returns the current character pacing value, in the range of 0 to 9999.

ascii dnld cr STRIP | CR_LF | CR

Determines how a Carriage Return, ASCII 13, is interpreted in an ASCII file download. If STRIP is specified, incoming Carriage Returns are removed before the data is saved. If CR_LF is specified, incoming Carriage Returns are translated into Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs before the data is saved. If CR is specified, no translation is performed. This command corresponds to the CR options - download list. fetch returns 0 for STRIP, 1 for CR_LF or 2 for CR.

ascii dnld display OFF | ON

Determines whether incoming data is displayed as it is received during an ASCII file download. This command corresponds to the Display text check box. fetch returns 0 for OFF or 1 for ON.

ascii dnld lf STRIP | CR_LF | LF

Determines how a Linefeed, ASCII 10, is interpreted during an ASCII file download. If STRIP is specified, incoming Linefeeds are removed before the data is saved. If CR_LF is specified, incoming Linefeeds are translated into Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs before the data is saved. If LF is specified, no translation is performed. This command corresponds to the LF options - download field. fetch returns 0 for STRIP, 1 for CR_LF or 2 for LF.

ascii linepace integer

Specifies length of a pause after a line is sent during an ASCII file upload. This command corresponds to the Millisecond delay between lines field. fetch returns the current line pacing, in the range of 0 to 9999.

ascii overwrite OFF | ON

Determines whether a file is overwritten when another file using the same name is received with the ASCII file transfer protocol. This command corresponds to the Overwrite existing file check box. fetch returns 0 for OFF or 1 for ON.

ascii pacechar character

Specifies the character used to pace ASCII file uploads. This command corresponds to the Use x for Line pace character field. fetch returns the ASCII value of the upload pacing character, ranging from 0 to 255.

ascii stripbit8 OFF | ON

Determines whether the 8th or high bit is stripped from received data before it is saved to a file during an ASCII file download. This command corresponds to the Strip bit 8 check box. fetch returns 0 for OFF or 1 for ON.

ascii tabexpand OFF | ON

Determines whether Tab characters, ASCII 9, are expanded into spaces as they are transmitted during an ASCII file upload. This command corresponds to the Expand tabs check box. fetch returns 0 for OFF or 1 for ON.

ascii tabstops integer

Determines the number of spaces that Tab characters are expanded to during an ASCII file upload. This command corresponds to the Expand tabs x spaces field. fetch returns the integer value of this field, ranging from 0 to 255.

ascii timeout integer

Specifies the number of seconds that Procomm Plus waits for incoming information during an ASCII file download before closing the transfer as completed. This command corresponds to the Seconds until download time-out field. fetch returns the current download time-out value.

ascii upld cr STRIP | CR_LF | CR

Determines how Carriage Returns, ASCII 13, are handled during an ASCII file upload. If STRIP is specified, Carriage Returns are not transmitted. CR_LF causes Carriage Returns to be translated into Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs as they are sent. If CR is specified, Carriage Returns are transmitted without translation. This command corresponds to the CR options - upload field. fetch returns 0 for STRIP, 1 for CR_LF or 2 for CR.

ascii upld display OFF | ON

Determines whether a file is displayed as it is sent during an ASCII file upload. This command corresponds to the Display text check box. fetch returns 0 for OFF or 1 for ON.

ascii upld lf STRIP | CR_LF | LF

Determines how a Linefeed, ASCII 10, is transmitted in an ASCII file upload. If STRIP is specified, Linefeeds are not sent. CR_LF causes Linefeeds to be translated as Carriage Return, ASCII 13, and Linefeed pairs as they are transmitted. If LF is specified, no translation is performed. This command corresponds to the LF options - upload field. fetch returns 0 for STRIP, 1 for CR_LF or 2 for CR.

ascii usepacechar OFF | ON

Determines whether ASCII file uploads are paced using the pace character specified by set ascii pacechar. This command corresponds to the Use X for Line pace character check box. fetch returns 0 for NO or 1 for YES.


ASPECT Building Blocks

  Related Topics

The basic building blocks of ASPECT are commands, parameters and expressions. Each line in a source or .was file begins with one of the following:

A command word

An ASPECT command is usually followed by one or more parameters, which control the function of the command in some manner, or provide constants or variables for the command to act upon. For more information, see ASPECT Command Form.

An expression

An expression consists of one or more operands acted upon by one or more operators. For example, in the expression:

a = b + c

a, b and c are operands, while "=" and "+" are operators. Operands usually occur as numeric constants or variables, but they can also be the result of a sub-expression within the expression, like the "=" sign in our example above, which uses the result of the sub-expression b + c.

A label

A label denotes a target location within a local procedure which the script can jump to with the goto command word. A label marks the location of a particular script command for later reference. The label may appear on the line preceding a command or on the same line as the command. Labels in ASPECT are not case-sensitive; they take the form:

LABEL:

Labels are discussed in more detail in Labels.

A comment

A script source comment is denoted with a semicolon (;) or with the #comment command. Any characters to the right of a semicolon, or within a #comment block are ignored by the compiler and are not part of the compiled script. Comments allow you to document your source file in detail without losing speed or efficiency within the executing script.

Commands, parameters and expressions conform to rules called syntax. Like the syntax of written languages, programming syntax ensures that the function of each ASPECT command is clear and precise.


ASPECT Command Form

  Related Topics

An ASPECT command is formed by listing the command name followed by a specific number of keywords and/or arguments of the appropriate data type. An argument can be the result of an expression or function call. Each keyword or argument must be separated by a comma or at least one space or tab character.

If an expression is used to represent a single argument, it is generally easier to read if the entire expression is enclosed in parentheses. In cases where an argument is an expression or constant value that is negated using a minus sign, a comma or parentheses must be used so that the negated value is not combined with any preceding arguments by the compiler. For example, the command fseek 0 1 2 is intended to position the file pointer one character before the end of the file. However, the 0 and -1 arguments are seen by the compiler as a single expression, 0-1, with a value of -1, and the compiler reports syntax errors. To be evaluated correctly,

fseek 0 (-1) 2

(or)

fseek 0, -1, 2

should be used. Similar problems can occur when using the increment and decrement operators, ++ and - -.

The use of commas to separate adjacent arguments is encouraged. ASPECT is a maturing language, and future versions may require a stricter syntax to provide enhanced features.


ASPECT Conventions

  Related Topics

The following conventions are used to describe ASPECT commands and their parameters

[ ]	Any parameter enclosed in square brackets ([ ]) is optional.

{ }	Curly braces indicate two or more parameters which are required when several choices are available.

|	If multiple parameters are separated from each other by a vertical bar (|), choose only a single parameter. The vertical bar indicates "or".

" "	Quotation marks should be entered wherever shown.

...	You may insert any number of parameters, usually up to 12, in the location marked by an ellipsis (...).

.

.

.	Three vertical dots indicate any number of command statements in a command block. Examples of commands that use command blocks are the proc and while statements.

arglist	A series of up to 12 variables, numbers or strings separated by commas.

argument	A data item which is passed as input to an ASPECT command or a user-defined procedure or function.

baudrate	A long representing a valid communications baud rate.

character	An integer representing an ASCII character value between 0 and 127 or 255, if 8-bit values are included. Control characters range from 0 and 31, while displayable characters are usually considered to range from 32 to 126.

column	A vertical column on the Terminal display, specified either as an integer constant or variable. The maximum value of column is equal to the number of columns on the terminal display minus 1. Column 0 is always the leftmost column of the terminal display.

condition	An expression with a numeric result, or any single ASPECT command which sets the system variables SUCCESS and FAILURE. The NOT keyword may precede an ASPECT command to perform a logical negation of the command result. The NOT keyword may not precede a user-defined function call, a variable or a numeric expression. Instead, the "!" ASPECT operator is used to logically negate the result of a user-defined function call or a numeric expression. A condition evaluates true for any non-zero result, and false if the result is zero.

data	A variable or constant of any data type.

datatype	A data type keyword. Either string, integer, long or float may be specified.

datavar	A variable of any data type.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, FAX, FTP, MAIL, NEWS, TELNET, and VOICE.

disk	An integer specifying a disk drive within the current command. A value of 0 represents the current or default drive in the ASPECT User Path, 1 represents drive A, 2 represents drive B, up to 26 for drive Z.

expression	A list of one or more operands, each separated by an operator. The result of an expression is a single operand of either string or one of the numeric types. Expressions resulting in a string cannot be used within commands such as if or while.

filelength	A long value, representing the length of a file, or the length of some portion of a file.

filename	A string containing a single valid DOS filename. The pathname is omitted.

fileoffset	A long value representing a location within a file.

filespec	A string containing a valid DOS filename. The pathname is optional.

float	A floating point variable or constant.

floatcon	Any float constant.

floatvar	Any float variable.

formatstr	A string containing text and/or data format specifiers. For more information on the formatstr structure, please see Formatting Text and Data.

gdatavar	A global variable of any data type.

gfloatvar	A global float variable.

gintvar	A global integer variable.

glongvar	A global long variable.

gstrvar	A global string variable.

id	A user-specified integer representing a unique identification value.

index	An integer representing a value from a pre-defined range, or a selection from an ordered list.

intcon	An integer constant, not a variable.

integer	An integer variable or constant.

intvar	Any integer variable.

itemlist	A string containing a comma-separated list of items.

itemtype	A keyword or keyword combination that represents an option set item type. Valid keywords are: PROTOCOL, TERMCOLORS, TERMFONT, TERMINAL, WINCOLORS, MODEM CONNECTION, DATA OPTIONS,  FAX OPTIONS, FTP OPTIONS, MAIL OPTIONS, NEWS OPTIONS, and TELNET OPTIONS.

keyval	An integer value representing both a key and the current keyboard state. It uses the format 0xAABB, where AA is a two-digit hexadecimal number identifying the keyboard state, and BB is a virtual key value. The keyboard state is encoded by adding any combination of state values:

NONE : 0x00, meaning no additional keys are pressed.

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.

keyword	A predefined name used by ASPECT to identify a command or characteristic of a command’s operation. For a full list of keywords, see ASPECT Reserved Words.

long	Any long constant or variable.

longcon	Any long constant.

longvar	Any long variable.

memindex	An integer representing a location within a memory block allocated by an ASPECT script.

memlength	An integer representing the number of characters to process in a memory block command such as memread.

name	An unquoted character string containing the name of a procedure, function macro, label or variable. For more information, see Naming Elements in ASPECT.

number	Any integer, long or floating point constant or variable. No spaces are allowed between the characters in a numeric constant.

numvar	Any integer, long or float variable.

operand	A data item which an operator can act upon, or which is the result of another operation.

operator	A symbol for an operation which is performed on one or more operands. For a complete list, see ASPECT Operators.

pathname	A string containing a full or partial path name. All file and pathnames returned by ASPECT are in lowercase.

protocol	A valid protocol name, for example, as used by the sendfile and getfile commands. A complete list of valid protocol names appears in Protocol Names and Indices.

row	A horizontal row on the Terminal display, specified as an integer constant or variable. The maximum value of row is equal to the number of rows on the terminal display minus 1. Row 0 is always the top row of the Terminal display.

strcon	A string constant; a group of characters surrounded by double quotes.

strindex	A zero-based integer specifying a character position in a string. Possible values for strindex range from 0 to 255.

string	Any quoted string constant or variable. A quoted string constant can be up to 256 characters in length, and is surrounded by quotation marks, as in "Hello".

strlength	An integer specifying a maximum string length. Possible values for strlength range from 0 to 256.

strvar	Any string variable.

sysvar	Any system variable. For a complete list of system variables, see The System Variables.

task	An integer value representing an application’s task id.

terminal	A valid terminal emulation name. A complete list of emulation names appears in Emulation Names and Indices.

text	Any valid source line text composed of zero or more tokens.

timeval	A long value containing the date and time stamp in system format - the number of seconds elapsed since midnight (00:00) on January 1, 1970. The time value is already adjusted for the local time zone and daylight savings time if used within that zone. A long value, it can be used in arithmetic operations to determine periods of time between events. For example, you could add or subtract two time values to determine elapsed time between events.

The maximum time value, 0xFFFFFFFF, represents the date Sunday, February 7, 2106 06:28:15. Valid time values for file dates and times range from 0x12CEA600 to 0xF48656FF, representing dates from January 1, 1980 00:00:00 through December 31, 2099 23:59:59. Any values outside of the valid range will generate out-of-range errors.

vkey	A virtual key value. For a listing of virtual keys, see Virtual Key Codes.

window	An integer value representing a window id.


ASPECT Include File Path

  Related Topics

This edit field allows you to specify directories that the ASPECT Compiler will search for #include files that are not found in the main script file’s directory. You can enter multiple paths by separating them with a semi-colon. For example:

c:\aspect;c:\aspect\shared;d:\aspmisc


ASPECT Operator Table

  Related Topics

Precedence level is indicated by bold horizontal lines. Operators that appear within the same pair of bold lines have the same level of precedence. For example, the multiplication (*), division (/) and modulus (%) operators all have the same level of precedence, and they are grouped to indicate this.

The table is also arranged by order of precedence. A group of operators has a higher precedence than those following it in the table. For example, the muliplication (*), division (/) and modulus (%) operators have a higher precedence than addition (+) and subtraction (-).

ASPECT OPERATOR TABLE

Operator	Description	Associativity
( )	Procedure or function call	Left to right
[ ]	Array subscript
+ +	Postfix-increment
- -	Postfix-decrement
+ +	Prefix-increment	Right to left
- -	Prefix-decrement
-	Arithmetic-negation
!	Logical-negation (logical-NOT)
~	Bitwise-negation (bitwise-NOT)
sizeof	Storage amount (bytes) of datatype
*	Multiplication	Left to right
/	Division
%	Remainder (modulus)
+	Addition	Left to right
-	Subtraction
<<	Bitwise-leftward-shift	Left to right
>>	Bitwise-rightward-shift
<	Less than	Left to right
<=	Less than or equal to
>	Greater than
>=	Greater than or equal to
==	Equal to
!=	Not equal to
&	Bitwise-AND	Left to right
^	Bitwise-exclusive -OR	Left to right
|	Bitwise-inclusive-OR	Left to right
&&	Logical-AND	Left to right
||	Logical-inclusive-OR	Left to right
? :	Conditional (ternary)	Right to left
=	Simple-assignment (versus compound)	Right to left
*=	Multiplication assignment
/=	Division assignment
%=	Remainder assignment
+=	Addition assignment
- =	Subtraction assignment
<<=	Bitwise-leftward-shift assignment
>>=	Bitwise-rightward-shift assignment
&=	Bitwise-AND assignment
^=	Bitwise-exclusive-OR assignment
|=	Bitwise-inclusive-OR assignment
,	sequential evaluation	Left to right
It is important to note that you may not use bit-wise operators on float type variables.


ASPECT Operators

  Related Topics

Operators are used in mathematical expressions and string variable assignments in the ASPECT programming language. Each operator has a precedence level and associativity.

Precedence

Precedence defines the order of operator evaluation in the absence of parentheses. Operators of higher precedence are evaluated before those with lower precedence. Parentheses are used to override the default precedence. For example, the expression A + B * C would be evaluated by multiplying B and C together and then adding A because * has a higher precedence level than +. The expression (A + B) * C, however, would first evaluate A + B, and then would multiply the result by C.

Associativity.

Associativity determines the order of evaluation when examining two operators with equal precedence. All operators having the same precedence level always have the same associativity. Left to right associativity means that an operand is grouped with the operator on its left, whereas right to left associativity means that an operand is grouped with the operator on its right. For example, the expression A * B / C would be evaluated by multiplying A and B, and then dividing that result by C. Operand B groups with * rather than / because * and / are left to right associative. The expression A = B = C, however, is evaluated by assigning the value of C to B and then to A. B is assigned a value before A because = is right to left associative.

Two special unary operators, ++ and - -, may be applied to either side of an operand. In either case, the effect is to increment or decrement the operand. However, when the unary operator ++ or - - is applied to the right side of an operand, the value of the operand is used in the context of the expression before it is incremented or decremented. When applied to the left side of an operand, the value used in an expression is the result after the operand is incremented or decremented. For example, in the expression A + B- -, A is added to B, and then B is decremented. In the expression A + - -B, first B is decremented, and then it is added to A.

For clarity, spaces have been inserted between the character pairs in the post-fix decrement (- -) and prefix decrement (- -) entries. Do not separate these character pairs in your script source, or errors will be reported during compilation!

The compound assignment operators can both transform and assign values in a single step. For example, the expression A += B is equivalent to the expression A = A + B.

Except for the left and right parentheses, the unary operators and the ternary operator, all operators listed in the operator table are binary and act upon two operands.

The ternary or conditional operator uses the syntax:

expression ? expression : expression

During execution, the first expression is evaluated. If its value is true, then the expression following the ? character is evaluated. Otherwise, the expression following the : character is evaluated. Ternary operators are often used in assignment statements. For example, in the statement:

x = (y < 3) ? 100 : 500

x is assigned the value of 100 if y is less than 3. If y is not less than 3, x is assigned the value 500.

The comma has different meanings depending upon its context. For instance, it can be used to separate items in a variable definition list. In such a list, the comma doesn’t behave like an operator, but simply separates the items from one another.

The comma or sequential evaluation operator has left and right operands when used in an expression. Each operand can also be an expression itself. The operator causes the left operand to be fully evaluated first. The left operand’s resulting value, if any, is discarded, and the right operand is fully evaluated. The result of the expression is the result of the right operand.

The comma operator occurs most often in for loops, where it allows several assignment expressions to be combined into a single expression. For example:

for x=0, y=1, z=2 upto 10

;  .

;  .

endfor

Note the "step" variable is the first variable encountered. In this example, the step variable is x.

The sizeof operator can be used on any type of operand. It returns the storage amount in bytes required for the operand's datatype. The operand can be a single value, the result of an expression, or it can be a datatype keyword enclosed within parentheses:

sizeof expression

sizeof(datatype)

memalloc 1 (100*sizeof(integer))

The sizeof operator can also be applied to an array identifier without its subscript expression. In this case, the result is the size of the entire array, which is the number of elements multiplied by the size of an individual element.

The simple assignment operator "=" is the only operator which can be used with string operands. For example,

S1 = "Hello, world!"

is a legal ASPECT expression, assigning the value "Hello, world!" to the predefined string variable S1.

In the Operator Table, precedence level is indicated by bold horizontal lines. Operators that appear within the same pair of bold lines have the same level of precedence. For example, the multiplication (*), division (/) and modulus (%) operators all have the same level of precedence, and they are grouped to indicate this.

The table is also arranged by order of precedence. A group of operators has a higher precedence than those following it in the table. For example, the muliplication (*), division (/) and modulus (%) operators have a higher precedence than addition (+) and subtraction (-).

View ASPECT OPERATOR TABLE


ASPECT Primary Commands

call	Causes script execution to branch to a specified procedure or function and permits a return.

case | endcase	Declares a string or integer to be tested against a switch statement’s target variable.

default	Provides for processing when no match is found among the case statements in a switch statement group.

else	Executes an alternate set of commands when the expressions specified in the associated if or elseif commands evaluate as false.

elseif	Enables multiple tests within an if/endif block.

exitfor	Transfers control from a for statement group to the line following the endfor command.

exitswitch	Transfers control from a case or default statement group to the line following the endswitch command.

exitwhile	Transfers control from a while statement group to the line following the endwhile command.

float	Defines a global or local float variable, or an array of float variables.

for | endfor	Repeats a command or series of commands a specified number of times.

func | endfunc	Denotes a function block.

goto	Performs an unconditional branch to the specified label within the current procedure or function block.

if | endif	Denotes a block of commands which are executed if the condition associated with the if command is true.

integer	Defines a global or local integer variable, or an array of integer variables.

long	Defines a global or local long variable, or an array of long variables.

loopfor	Skips the remaining commands in a for loop and branches to the top of the loop.

loopwhile	Skips the remaining commands in a while loop and branches to the top of the loop.

param	Defines a parameter variable in a procedure or function.

proc | endproc	Denotes a procedure block.

return	Exits the current procedure or function and resumes processing at the statement following the function or procedure call.

string	Defines a global or local string variable, or an array of string variables.

switch | endswitch	Denotes a block of multiple decision points.

while | endwhile	Denotes a block of repeated commands.

 Return to category list


ASPECT Program Flow

  Related Topics

Every ASPECT script requires a special procedure that identifies the starting point for script execution. This procedure is always named proc main.

When a script is run, the first command line it executes is the first command line listed in the procedure named proc main. Execution flow continues until the end of the proc main procedure, at which time the script is terminated.

Generally, however, the proc main procedure directs execution to other parts of the script, using procedure or function calls. When a call is made, execution flow transfers to the start of that procedure or function and continues until that procedure or function block ends, or until a return command is encountered within the called procedure or function.

When a return command is encountered, or the end of the procedure or function is reached, execution returns to the point from which the procedure or function was originally called. Execution then proceeds with the command following the procedure or function call.

Any called function or procedure may in turn call any other function or procedure, even itself. In this way the program execution flow can branch out into all areas of the script.

The proc main procedure cannot define any parameters, since there is no initial call made where arguments would typically be passed. There are a number of ways to pass information to a script, however. Usually, this involves the pre-defined variables that are available to all scripts.


ASPECT Reserved Words

  Related Topics

See the following topics for reserved ASPECT symbols and words:

Reserved Symbols

Reserved Words


ASPECT Run-Time Error Messages

  Related Topics

Listed below are the messages displayed by Procomm Plus if an ASPECT error occurs while a script is executing. They are divided into non-critical and critical errors:

Non-critical Run-Time Errors

Critical Run-Time Errors


ASPECT Script Reference

The ASPECT commands can be referenced by the following methods:

1.	Use the Help system's Search function to search for the name of the command.

2.	Select the command from the list of Commands Listed Alphabetically.

2.	Select the command from the list of Commands Listed by Function.

3.	Browse the alphabetical sequence of The ASPECT Commands. with the Help "browse" buttons.

See Using Command Descriptions for more information about the ASPECT command descriptions.


ASPECT Scripts: A Brief Tutorial

  Related Topics

The following topics will help you begin scripting with ASPECT:

A simple logon script

Dialing without the Connection Directory

Variables: the basics

Procedures: the basics

Predefined Global Variables

Storing Information in Array Variables

Controlling Program Flow

Functions

Calling Conventions

Passing Parameters by Reference

SUCCESS and FAILURE System Variables

Getting User Input

A Dialog Box Example

A User Window Example

The when ... call Command

System Variables and the when Command

Sending Keys with Windows ASPECT

Spawning and Chaining ASPECT scripts

Some Notes on Design

Advanced Topics

What’s been covered?


ASPECT Set/Fetch Statements

  Related Topics

The following set aspect statements control how Procomm Plus operates when running a script. Each setting has a default value, which is assigned when a script is launched.

Scripts that are launched using the chain or execute command only receive default values for the scriptpath and remotecmd settings. All other settings are inherited from the script which launched them.

aspect codepage integer

Specifies the information used to convert characters between character sets to aid in internationalization. This information is used by the keytoansi, ansitooem and oemtoansi commands to perform proper character set conversions. By default, this option is set to the code page used by Windows. Acceptable settings are shown below:

0	ANSI - no conversions applied
255	Windows currently-loaded code page
437	Default - North American.
850	International
860	Portugal
861	Iceland
863	French Canadian
865	Norway / Denmark
fetch returns the code page currently used by Procomm Plus in an integer.

aspect control OFF | ON

Enables and disables the Tools | Scripts | Start Script/Stop Script menu item, as well as the Action Bar Run Script icon. If OFF, these controls operate normally. If ON, they are disabled, effectively preventing a user from interrupting a script. fetch returns 0 for OFF or 1 for ON.

Use this command in cases where you wish to guarantee that the script completes its actions without user intervention. Because this command prevents the user from shutting down Procomm Plus specifically, the only way to shut it down is by exiting Windows.  In this case, Procomm Plus will prompt the user for permission to shut down all active scripts - this prompt occurs independent of the aspect exitaction setting. Also, a script that sets aspect control ON may lose that control if it allows scripts to spawn on top of it, or if it executes a child script without sharing the environment. The default for this setting is OFF.

aspect ctrlbreak OFF | ON

Allows a user in Terminal or Telnet mode to abort a dead-end command like pause or waitfor with the <Ctrl><Break> key sequence. The default is ON. fetch returns 0 for OFF or 1 for ON.

aspect datakey integer

Specifies the integer key used in the encrypt and decrypt commands. fetch returns the value of the current integer key.

For more information on the use of the datakey in encryption, see the encrypt command and the decrypt command.

aspect decimal integer

Determines the default number of digits to the right of the decimal point to display for floating point numbers. This command affects the floating point precision used in ftoa and all commands that accept a format string. fetch returns an integer equal to the current decimal precision.

The default value for this setting is 2, but any value from 0 to 255 can be used. Any precision specifiers occurring in a format string override the default precision. The last digit in the displayed value is rounded as needed. For example, if the default precision is 2, a value of 123.456789 would become 123.46.

aspect dialingbox OFF | ON

Determines whether the Dialing Progress dialog is displayed after a dial or dialnumber command is processed. If the script stops running while this command is in effect, the Dialing Progress dialog is displayed immediately. fetch returns 0 for OFF or 1 for ON.

If the Dialing Progress dialog display has been turned off, the Procomm Plus main window remains disabled, preventing any interaction with menus or Action Bars.  Press the <Escape> key to cancel the dialing operation if you wish to reenable the main window.

If the Dialing Progress dialog is disabled, the user will not be able to select a new timeout value, or to cancel the dialing activity manually. This setting only affects dialing operations that follow it. It has no effect upon dialing operations underway when the command is executed.

aspect display OFF | ON

Determines whether characters received from a remote system are displayed on the Terminal window. fetch returns 0 for OFF or 1 for ON.

No characters are written to a Capture file or to the Scrollback Buffer when set aspect display OFF is used, nor are they printed if print capture is enabled. To display or capture data with set aspect display OFF, use set aspect rxdata ON and issue termwritec or termwrites commands as data is received.

aspect errormsg OFF | ON

Prevents ASPECT from displaying error messages that are not considered critical errors. fetch returns 0 for OFF or 1 for ON.

The $ERRORNUM system variable will contain a non-zero value when an error has occurred. It can be used in conjunction with the when command to build an error handling routine when the errormsg setting is OFF.

aspect exitaction PROMPT | HALT

Determines whether or not the user is prompted to exit all parent scripts, if any, when the current script is stopped.  This can occur when the user presses the Run Script Action Bar button or selects Script Stop from the Tools | Scripts menu.  exitaction also determines whether the user is prompted to exit all active scripts when Procomm Plus is shut down.  The default action is PROMPT, which displays a message box prompt to the user.  HALT stops all running scripts without prompting the user.  This setting is ignored when aspect control is set ON.  fetch returns 0 for PROMPT or 1 for HALT.

aspect filexferbox OFF | ON

Determines whether Procomm Plus displays the file transfer progress dialog during a sendfile or getfile operation. fetch returns 0 for OFF or 1 for ON.

With set aspect filexferbox OFF, file transfers can only be canceled with the xfercancel command. The set aspect filexferbox setting only controls file transfer operations which follow it. File transfers already underway when the command is executed will not be affected.

aspect helpfile filespec

Specifies the name of the help file to use with on-line help. Typically, this is a custom help file written especially for a script. The help command can be used to open help and display the help file specified by this command. fetch returns the name of the current help file in a string.

The ASPECT Path is the default path assumed for the ASPECT help file, and if no extension is specified .hlp is assumed.

aspect keys OFF | ON

Determines how keystrokes are processed when a script is executed. With set aspect keys OFF, Procomm Plus processes all keystrokes normally. With set aspect keys ON, the script must process all keystrokes. fetch returns 0 for OFF or 1 for ON.

The $KEYHIT system variable will contain a non-zero value when a key is pressed. It can be read with the keyget command and processed normally by Procomm Plus with the termvkey command.

aspect mousecoord window | SCREEN

Specifies which window ID that the mouse coordinates will be relative to. SCREEN is the default.

aspect path pathname

Specifies the path, called the Aspect Path, referenced by the dialog box and user-window commands. When a filename without a path component is specified within a filespec argument for one of these commands, ASPECT will look for that file within the Aspect Path. fetch returns the current default path value in a string. The $ASPECTPATH system variable can also be referenced for the the current Aspect Path.

The Aspect Path is also assumed for the chain, execute, compile, dllobjfile, and dllload commands. The Aspect Path can be changed with the set aspect path command, or as an optional action in the chdir command.

For more information, see The ASPECT Script Environment.

aspect rgetchar character [STRIP]

Specifies the character which terminates an rget command. The default character is a Carriage Return, ASCII 13. If STRIP is specified, the terminating character is removed from the string returned by rget. fetch returns the current rget termination character as an integer.

aspect rxdata {OFF [UNTIL WHENTARGET index]} | ON

Specifies whether Procomm Plus or a script processes characters received from the communication port. The default, OFF, indicates that Procomm Plus processes received characters. With set aspect rxdata ON, the script must handle incoming data with commands like comgetc. With set aspect rxdata ON, commands dependent upon received data, such as waitfor and when target are only checked when characters are retrieved from the receive data buffer. fetch returns 0 for OFF or 1 for ON.

Setting set aspect rxdata ON does not prevent autodownload sequences from being recognized. You must explicitly set autodnld OFF to prevent Kermit and Zmodem transfers from starting, and set terminal enquiry OFF to prevent CISB+ transfers from starting.

The optional UNTIL WHENTARGET forces Procomm Plus to process characters normally until the when target specified by the index is triggered. At that time, the script is expected to process any characters received after the target string.

aspect spawn OFF | ON

Determines whether a script may be executed while another script is running. If ON, scripts can be spawned from a Connection Directory entry, in response to a Meta Key press, via a ddeexecute command or by other methods. By default, this setting is OFF when a script is initially executed. fetch returns 0 for OFF or 1 for ON.

This command has no effect on the execute and chain commands.

aspect whensuspend OFF | ON

Determines whether events specified by when statements are acted upon while a procedure called by another when statement is executing. If this setting is ON, all other when events are suspended until the procedure called by the currently-executing when event returns. fetch returns 0 for OFF and 1 for ON.

Suspending when conditions does not eliminate ASPECT’s response to those conditions. Instead, the suspended whens are saved in a queue until the currently-executing when command has completed. This may result in unexpected when firings if the script is not configured to account for when events that occur during the suspended period. This is true of when ELAPSED, when ISKEY, when QUIET, when TARGET and the when USEREXIT commands. It is not true of when variable commands, meaning that changes to a variable which occur during a suspended period will not cause a when variable to fire.


Additional Options and Macro Definitions

  Related Topics

These edit fields allow you to specify options and macro definitions to be passed to the compiler as command-line arguments.

Additional Options and Macro Definitions (saved).

Options specified in this field will be saved whenever the dialog is closed via the OK button. They are stored in the pw4.ini file in the [ASPCOMPW] section, under the Options= entry, and used for future script compilations.

Additional Options and Macro Definitions (not saved).

Options in this field will be referenced only in the current compile session, allowing you to easily add or remove compile options temporarily, without affecting the .ini compiler settings.

The options that can be specified in these fields are discussed in Command-Line Syntax.


Advanced Emulation Set/Fetch Statements

  Related Topics

The following  advanced set/fetch emulation statements are not available for all Terminal types, thus a base type must be specified. For example, to disable the status line for the TVI950 emulation, use set TVI950 statusline OFF. To turn on block mode for the WYSE50 emulation, use set wyse50 blockmode ON.

Each group of set/fetch emulation statements is preceded by a list of Terminal emulations for which the command group is valid.

For all of the advanced terminal emulation set/fetch commands, the specified emulation argument is a base type and is required to validate the syntax at compile time. At run-time, however, if Setup’s currently selected emulation has the same base type, the set/fetch statement will only affect the currently selected terminal. If not, the base terminal definition will be affected.

ADM31, IBM3270, TVI950, TVI955, WYSE50, WYSE60, WYSE100

ADM31, ESPRIT3, IBM3270, TVI910, TVI912, TVI920, TVI925, TVI950, TVI955, WYSE50, WYSE60, WYSE100

ADM31, IBM3101, IBM3161, WYSE50, WYSE60

ADM31, WYSE50, WYSE60

ANSIBBS, IBMPC

TVI922, VT220, VT320

IBM3101, IBM 3161

RIP


Advanced Topics

  Related Topics

The following discussions will help you get the most out of ASPECT scripting:

Using macro definitions

Macros are meaningful phrases or constants that make your ASPECT script source code easier to read and maintain. In addition, macros may also represent calls to functions, procedures, or internal commands. They are typically declared at the top of script files, before the main procedure, but may appear anywhere in scripts. First, let’s talk about simple macro definitions that give loops, switch ... case, and boolean operations more meaning.

A macro definition, sometimes called a manifest constant, is made up of a reference name and constant value. Reference names are used in your script files in place of the values they represent. During compilation, Procomm Plus replaces the reference names with their corresponding values. Macro definitions take on the following form:

#define Name Value

As with variables, try to make your macro names describe the values they represent. For example, we may call a macro that represents the maximum length of a name _MAX_NAME_LEN. Use underscores to clarify the meaning of macros or to resolve naming conflicts with reserved words. The following script example shows how to use macro definitions to make a script easier to read:

#define _MAX_ROWS   $TERMROWS       ; Declare a macro representing the

                                    ; max. number of rows on screen.

proc main

   integer CurrentRow               ; Declare an integer variable we can

                                    ; use to count through each row

                                    ; on the screen.

   for CurrentRow = 0 upto _MAX_ROWS - 1

                                    ; Loop through all rows on

      termputs CurrentRow 0 "Hello!"

                                    ; screen and display a string

   endfor

endproc

When Procomm Plus compiles the script shown above, all references to _MAX_ROWS are replaced with the system variable $TERMROWS. In this case, we’re using a macro to make the operation of the for ... endfor loop clearer. Let’s say that we want the script to treat row 5 as the maximum row on the screen. Instead of changing all references to the system variable $TERMROWS to 5, we can simply change the reference in our _MAX_ROWS macro.

ASPECT also allows you to define macros that represent functions, procedures, or internal ASPECT commands. This feature not only makes a script easier to read, it can save you some programming time. For example, imagine that we want a function that displays a message box with a stop sign icon and an OK button and we’re going to call this function many times within our script file. Instead of using the internal sdlgmsgbox command with all of its required parameters, let’s create a macro that calls sdlgmsgbox with the parameters we want. The resulting macro definition could look something like this:

#define _DO_MSG( a ) sdlgmsgbox "Script Message" a STOP OK I9

The parameter called "a" in the macro name corresponds to parameter "a" in the macro definition. "a" is a token, representing the information that’s displayed using the sdlgmsgbox command. When a script is compiled with the above macro definition, _DO_MSG(string) references are replaced with ASPECT’s sdlgmsgbox command. In addition, the string used in the _DO_MSG reference replaces the "a" token in the macro definition. This process is referred to as Macro Expansion. Here is a script example that uses the macro definition above:

#define _DO_MSG( a ) sdlgmsgbox "Script Message" a STOP OK I9

proc main

_DO_MSG( "Display me!" )	; Use our macro to display a message

; using the sdlgmsgbox command.

endproc

When the script is compiled, the _DO_MSG macro is replaced with:

sdlgmsgbox "Script Message" "Display me!" STOP OK I9

As with the simple macro definitions, using macro expansion provides you with an easy way to make changes. All we need to do to change the icon displayed in all of our message boxes is replace STOP with the icon we want to use: INFORMATION, EXCLAMATION, QUESTION, or NONE.

You can use other tokens to expand more than one parameter in a macro definition. To create a macro called _PUTCURSOR that locates the mouse pointer at a specific location, we may use the following definition:

#define _PUTCURSOR( a, b ) setpointer a b

"a" and "b" in the macro definition are replaced with "a" and "b" in the macro name when the macro is expanded. We’ve replaced references to the setpointer command with a more descriptive macro!

Exercises

Write a script that uses simple macros to reference all text strings used for displaying messages. #define these text macros in a separate file called "STRINGS.INC". Use the #include command to include the text macros in your script file.

Imagine you’re writing a large ASPECT script application and your script is going to be used in many other countries. Describe how macros can make translation of text strings displayed by your script file into other languages easier.

DDE server operation

Procomm Plus supports Dynamic Data Exchange (DDE) both as a server and as a client. Using the program as a DDE server is not directly related to the construction of ASPECT script files, but it helps you understand client scripts if you have a good grasp of server operations as well.

Procomm Plus functions automatically as a DDE server. When it receives a DDE request from another Windows application, it processes it automatically. Typically, another program requests that Procomm Plus run a script file and return the value of a predefined global variable. For example, in Microsoft Excel version 5.0 the formula:

=PW4|test.wax!i0

instructs Excel to establish a DDE link with Procomm Plus (pw4), run test.wax, and display the value of the predefined global integer variable i0 in the cell where the formula is entered. Since this formula sets up a ddeadvise link to the variable i0, any change made by a script file to the value of i0 is automatically displayed in the cell.

As an example, suppose that you have written an ASPECT script called dow.wax that calls a financial service, downloads a particular stock quote and assigns the value to the float variable f0. You enter the formula =PW4|dow.wax!f0 in an Excel cell. Now each time dow.wax changes the value of F0, the spreadsheet is updated with the latest information!

In addition to running script files and determining the current value of the predefined global variables, a client Windows application may request Procomm Plus to execute a command. Procomm Plus, when acting as a DDE server, acts on the following commands received from a DDE client:

ASPECTCMD string

CAPTURE OFF | ON

DIAL {DATA | FAX | VOICE | FTP | TELNET} [GROUP] name [DIALINGBOX OFF]

DIALLOAD filespec

EXECUTE filespec

GETFILE string [filespec] [FILEXFERBOX OFF]

HALT

HANGUP

PWEXIT

SENDFILE string [filespec] [FILEXFERBOX OFF]

TRANSMIT string

Normally only applications that include some sort of macro or scripting language are able to send DDE "executes" like those listed above to a DDE server. Read the client application’s documentation for information about its client DDE support.

As a server, Procomm Plus responds to two topics, "System" and the name of a script file.

DDE client commands

Many DDE requests and "executes" can be sent only by client programs that support a macro or scripting language. ASPECT is a powerful scripting language, and you can use it to send a variety of DDE requests to other Windows programs that are able to act as DDE servers.

The process of setting up a DDE link with a server program begins with the ddeinit command, where you specify an application name and a topic. You will need to read the server application’s documentation to see what topics it supports. The ddeinit command returns a unique DDE channel identifier into a long variable. It’s a good idea to test this variable to make sure the connection is successful:

long DDEChan = 0

   ddeinit DDEChan "excel" "sheet1"        ; Try to initiate DDE link with Excel

   if FAILURE                              ; If no link established,

      usermsg "Unable to establish link"   ; warn the user.

   endif

Let’s say you want to send some DDE commands or "executes" to Excel. To do this you initiate a link using the "system" topic:

long SysChan = 0

   ddeinit SysChan "excel" "system"

The long variable Syschan assumes the value of a unique link identifier that you can use in ddeexecute commands:

proc SendCommands

   long SysChan                                ; Var. for link handle.

   ddeinit SysChan "excel" "system"            ; Set up a link to Excel.

   ddeexecute SysChan "[APP.RESTORE()]"        ; Commands that

   ddeexecute SysChan "[APP.MOVE(0,0)]"        ; Excel accepts to size

   ddeexecute SysChan "[APP.SIZE(530,180)]"    ; its window, format

   ddeexecute SysChan "[FULL(TRUE)]"           ; columns, etc.

   ddeexecute SysChan "[COLUMN.WIDTH(75)]"

endproc

Once again, the syntax of DDE server commands is specified in the documentation for the server application.

Now suppose you want to change the value of one of the cells in an Excel spreadsheet. For this, use the ddepoke command. To poke values to a spreadsheet cell, Excel requires that you use a DDE channel established using a topic that is the name of the spreadsheet. Examine the following script fragment:

   long SysChan = 0                                ; Identifier to Excel system.

   long DDEChan = 0                                ; Identifier to DDE channel.

   ddeinit DDEChan "excel" "test.xls"              ; Initiate DDE link with

   if FAILURE                                      ; spreadsheet. If no link

      usermsg "Unable to establish link"           ; established, tell user and

      exit                                         ; leave.

   endif

   ddeinit SysChan "excel" "system"                ; Establish execute channel.

   ddeexecute SysChan "[SELECT(`"R1C1`")]"         ; Move active cell to A1.

                                                   ; Notice the backticks (`)

                                                   ; for literal quote marks.

   ddepoke DDEChan "R1C1" "Test"                   ; A1 now contains "Test".

At this point, you can send commands, referencing the SysChan handle, and poke values into the spreadsheet using the DDEChan handle.

Use the ddeadvise command to request information from the client. The channel for this information in our example is the one established using the spreadsheet. In the line:

ddeadvise DDEChan "R1C1" s0

The value of the A1 cell is put into the variable s0. When the value of the R1C1 cell is changed, the new value is placed in s0 and the system variable $DDEADVISE takes on the value 1 to indicate that a change has occurred. In addition, the when command can trigger when the server reports a change. This is usually referred to as a DDE hot link:

#define TRUE    1

long DDEChan                               ; Handle to the DDE channel.

proc main

   ;     .

   ;     .

   ddeinit DDEChan "excel" "sheet1"        ; Establish DDE link.

   If FAILURE                              ; If no link established, tell user

      usermsg "Unable to establish link"

      exit                                 ; and leave.

   endif

   ddeadvise DDEChan "R1C1" s0             ; Set up hot link to R1, C1.

   when $DDEADVISE call ShowMessage

   ; Call ShowMessage when the

   ; cell is updated in Excel.

   while TRUE                              ; Loop forever.

      ;  .

      ;  .

      ;  .

   endwhile

endproc

proc ShowMessage

   usermsg "The value of cell A1 has changed."

endproc

Optionally, you can specify an integer at the end of the ddeadvise command. When the server informs the client that the information associated with a ddeadvise has changed, the system variable $DDEADVISE returns the value of this integer. If you have several outstanding ddeadvise events, you can determine very easily which changes occurred.

When you no longer need to be advised of changes to server data, issue a ddeunadvise command. Likewise, when you have completed your DDE session issue a ddeterminate for each open channel:

ddeunadvise DDEChan "R1C1"

ddeterminate DDEChan

ddeterminate SysChan

Packet Send and Receive

Another interesting set of commands is the packet send and receive commands. These commands provide you with the ability to exchange data and commands using an error free packet protocol that you define. You can, for example, develop a custom BBS that sends and receives packetized mail messages, commands and responses for on-line games or "doors" and a file transfer protocol to send and receive files simultaneously! Since this protocol is unique to Procomm Plus, both sides of the connection must be running Procomm Plus, typically with two different script files that interact with each other.

In order to use the packet send and receive commands, you must first put both machines in packet mode with the command:

pkmode ON txtimeout rxtimeout

where txtimeout and rxtimeout specify the timeout in seconds for transmitted and received packets, respectively. Setting the timeouts with the pkmode command sets the defaults for each transmitted or received packet, although it’s still possible to override these defaults by including an optional timeout parameter with packet sends and receives. A typical packet send looks like this:

   integer UserCommand = 1                 ; Command to pass to receiver.

   string szText = "This is the first command."    ; Text to send to receiver.

   integer Len = 26                        ; Length of string to send.

   pkmode ON 30 60                         ; Turn on packet mode.

   pksend UserCommand szText Len           ; Send packet to receiver.

Now you check to see if the packet is properly transmitted. If the packet is successfully transmitted, you can send another. If not, you can resend the packet or perform some other task:

   when $PKSEND call ProcessSend

 ; When the status of the $PKSEND

 ; system variable changes, letting

 ; you know the status of the send,

 ; call a proc to see what happened.

proc ProcessSend                   ; Determines the packet status

   switch $PKSEND                  ; by checking $PKSEND

      case 0                       ; If $PKSEND is 0, send is in progress

      endcase                      ; or idle.

      case 1                       ; If $PKSEND == 1, packet sent,

         SendNext()                ; the receiver has the packet.

      endcase

      case 2                       ; Timeout has occurred so warn user.

         DoTimeout()               ; (The receiver is dead or lost)

      endcase

      case 3                       ; Errors during transmission.

         Notify(_COMERROR)         ; Tell us about the error.

      endcase

      case 4                       ; Send cancelled by receiver.

         Notify(_CANCEL)           ; Tell us about the cancel request.

      endcase

   endswitch

endproc

$PKSEND is assigned a value of 3 when there are UART errors, buffer over-runs or the ASPECT packet protocol is in an indeterminate state. These errors are usually an indication of a poor communications link. $PKSEND is assigned a value of 4 when a cancel sequence is received.

At the receive end, your script processes the incoming packet when it arrives. Take a look at this script fragment:

   pkmode ON 30 120                ; Turn on packet mode.

   when $PKRECV call ProcessRecv   ; Watch for incoming packets!

   while TRUE

      ;     .

      ;     .

      yield                        ; Yield processing time

   endwhile

      ;     .

      ;     .

      ;     .

proc ProcessRecv                   ; Determines the status of the packet

   switch $PKRECV                  ; by checking system variable $PKSEND.

      case 0                       ; If $PKRECV == 0, packet not received.

      endcase

      case 1                       ; If $PKRECV == 1, packet received OK,

         ReadPacket()              ; extract the information from it.

      endcase

      case 2                       ; Timeout has occurred.

         Notify(_TIMEOUT)          ; Warn user about the error.

      endcase

      case 3                       ; Errors occurred during the receive.

         Notify(_COMERROR)         ; Warn user about the problem.

      endcase

   endswitch

endproc

In this example, if the packet is received error free, $PKRECV = 1, ASPECT automatically sends an acknowledgment to the sender, setting the sender’s $PKSEND variable to 1. Typically, this prompts the other end to send another packet. Meanwhile, the information in the received packet can be processed in the ReadPacket procedure. The variable parameters to the pkrecv command contain the information sent by the other end. A ReadPacket routine may look something like the following:

proc ReadPacket

   integer Command                 ; Command sent with packet.

   string RecvString               ; String sent with packet.

   integer PktLength               ; Length of the data in packet.

   switch Command                  ; Switch case to evaluate the

   ;    .                          ; command passed with the packet.

   ;    .

   endswitch

   ProcessData(RecvString)         ; Look at the string sent with packet.

   switch PktLength                ; Possibly evaluate the length of the

      ; .                          ; packet to perform some other actions.

      ; .

   endswitch

endproc

In this example, you can key on the value of the command variable to display a bitmap or metafile, write the received string to a file or perform some other type of processing on the received string. As you can see, this group of commands is very flexible. The packet send and receive support in ASPECT provides the tools necessary to develop your own error free protocol for a variety of uses. The exact specification of your protocol is determined by how you choose to react to errors, the timing of sends and receives and how integer and string data in the packets is interpreted.

Exercises

Write an #include file that contains macros representing each character in the ASCII chart. For example, _CR may stand for the carriage return character or ASCII 13.

It’s a good idea to use an extension other than .was for include files. .INC or .H are commonly used extensions for ASPECT’s #included files.

Write a script that captures a list of user names from a BBS and creates a report in a Windows word processor like Microsoft Word for Windows, WordPerfect for Windows or Lotus Ami Pro.

Write your own file transfer protocol in ASPECT.


Arrays

  Related Topics

You can define both global and local array variables. An array is a set of data storage areas of like type grouped together, and accessed using a common name. Each data storage area is called an element of the array; an array element is accessed by combining the array name with a subscript expression.

An array is defined using the syntax:

type name[size]...

where type can be either integer, long, float or string. The array name must follow the standard ASPECT naming conventions, and array definitions cannot include initialization values.

A left square bracket begins the definition of the first dimension in the array, and a right square bracket ends that dimension. An expression which evaluates as a constant whole-number value is used within the square brackets to define the size of the dimension. For example,

integer myarray[10]

defines an integer array called myarray which has one dimension of ten elements. In other words, myarray is a single-dimensional array with ten elements of type integer.

Arrays can be defined with up to twelve dimensions. The number of elements in an array definition is determined by the product of the sizes of each dimension. For example, an array declared as:

integer mybigarray[20][21][22]

contains 9240 elements, as 9240 == 20 * 21 * 22. ASPECT limits the overall number of elements in an array to the maximum positive value of a long data type, which is 2147483647. However, if the amount of memory required for an array is not available at run-time, an error message will be given.

To access an element of an array, the array name is combined with a subscript expression with the same number of dimensions as the array definition. For example, the statement:

i9 = mybigarray[3][4][5]

would assign the value stored in mybigarray[3][4][5] to the predefined integer variable i9.

Array indices are zero-based. This means that an array declared as:

integer myarray[10]

would be referenced using index values from 0 through 9. The statement:

i1 = myarray[3]

assigns the value of the fourth element of myarray to the system variable i1. While the array definition requires a constant subscript expression, the subscript expression used to access an array element can be any valid expression using operators, constants, variables, and even function calls. An expression is valid for array access if it evaluates to an integer or long value at run-time. This small ASPECT script:

proc main

integer index, myarray[10]

for index = 0 upto 9

myarray[index] = index

endfor

endproc

uses a simple for-loop to set each element in myarray equal to its index value.

If an array name is used in an expression, it must use the same number of dimensions or subscript expressions as there were in the definition of the array. An array name itself cannot be passed as an argument to a command, procedure, or function, but an element of an array can be passed.

ASPECT will detect out-of-bounds errors on array indices during run-time. However, an out-of-bounds condition will only occur if the overall resulting element offset into the array exceeds the number of elements in that array. For example, given the array:

integer mynextarray[4][3]

the statement:

mynextarray[2][5] = 1

would seem to be out of bounds. Instead, it accesses the 11th element of the array, as

11 == ((2 * 3) + 5)

It would not be reported as an error. To be readable and understandable, however, array accesses should conform to the definition of the array.


CAPTURE Set/Fetch Statements

  Related Topics

The set capture statements control the operation of the Procomm Plus Capture files. They correspond to the Capture File Options in the Setup, Data, Setup Files dialog. If set dialentry access is used to specify a Data- or Telnet-class Connection Directory entry, the autostart, file, overwrite, query and recordmode set statements only affect the Capture File Options of that entry. The Capture File Options dialog is accessed by clicking Setup within a Connection Directory entry’s Basic Options dialog, or Setup’s Data, Setup Files dialog.

capture autostart OFF | ON

If capture autostart is ON, Procomm Plus opens a Capture file when you connect using a Data- or Telnet-class Connection Directory entry, and closes it upon disconnect. This command corresponds to the Start capture on connection field in the Connection Directory Capture File Options dialog. fetch returns 0 for OFF or 1 for ON.

capture file filename | NONE | CURRENT

Specifies the default filename for capture files. If set to NONE, the Capture file is disabled. fetch returns the name of the current default capture file in a string.

The set dialentry access command may be used to target a Data- or Telnet-class Connection Directory entry for the set capture file command.If CURRENT is specified, Procomm Plus logs data to the file specified in Setup, Data, Setup Files. The CURRENT keyword is valid for Connection Directory entries only.

capture overwrite OFF | ON

Determines whether capture files are appended to or overwritten when capturing to existing files. fetch returns 0 for OFF or 1 for ON.

capture path pathname

Determines the default path for Capture files. This command corresponds to the Capture path field in Setup, Data, Data Options, Paths. fetch returns the current default path for capture files in a string.

This command pertains to Setup only, regardless of set dialentry access.

capture query OFF | ON

Determines whether Procomm Plus prompts for a filename when a capture is started. This command corresponds to the Query for file name... check box. fetch returns 0 for OFF or 1 for ON.

capture recordmode SCREEN | FILTERED | RAW

Determines whether Procomm Plus writes information to capture files just as the information appears on the Terminal display (SCREEN), writes information without emulation controls (FILTERED), or writes information just as it is received from the remote system (RAW). fetch returns 0 for SCREEN, 1 for FILTERED or 2 for RAW.

With set capture recordmode RAW, the capture file will contain any emulation sequences sent by the host. These may appear as high-bit characters in your Capture files.


CISB+ Protocol Set/Fetch Statements

The following set/fetch commands correspond to the options in Setup, Data, Transfer Protocol, with the Current Protocol field set to CIS-B+.

cisb abortdnld KEEP | DELETE

Determines whether files aborted during a CompuServe B+ file download are kept or deleted. This command corresponds to the Delete aborted downloads check box. fetch returns 0 for KEEP or 1 for DELETE.

cisb overwrite RESUME | ALWAYS | RENAME

Determines how filename collisions are handled in the CompuServe B+ file transfer protocol. If RESUME is specified, the download is treated as a resumption of a previous download, meaning that the remainder of the downloaded file downloaded is appended to the existing file. If ALWAYS is specified, the existing file is always overwritten by the file being downloaded. If RENAME is specified, the downloaded file is renamed, preserving the existing file. This command corresponds to the Existing File Action check box. fetch returns 0 for RESUME, 1 for ALWAYS or 2 for RENAME.


COM-Related Commands

break	Sends a break to a remote computer system.

clearxoff	Clears an XOFF state.

comgetc	Assigns the next character value in the receive data buffer to an integer variable.

computc	Sends the specified character value to the communications port.

comread	Retrieves data from the receive data buffer and stores it in the target variable.

comwrite	Sends the specified string value to the communications port.

disconnect	Disconnects the computer from the telephone line.

hangup	Disconnects your computer from the telephone line.

rget	Receives and stores a text string sent by a remote system.

rxflush	Clears the receive buffer.

transmit	Sends a character string to the active COM port.

txflush	Clears the transmit data buffer.

waitfor	Pauses script execution until a target string is received from a remote system.

waitquiet	Pauses script execution until the receive data line has been inactive for a specified number of seconds.

when quiet	Forces a procedure of function call when the receive data line has been inactive for a specified number of seconds.

when target	Forces a procedure or function call when a specified string is received from a remote system.

 Return to category list


Calling Conventions

  Related Topics

The previous section on functions may have given you the impression that functions are called differently from procedures. ASPECT supports two methods of calling procedures and functions that are interchangeable. You can use the call ... with syntax, or drop both keywords and include the parameter list in parentheses. For example, suppose we had a call to a procedure as:

call SomeProcedure with FirstVar, SecondVar, ThirdVar

We can use the shortened syntax and enhance the readability of our script with:

SomeProcedure(FirstVar, SecondVar, ThirdVar)

The shortened function call is similar. Instead of:

call SomeFunction with FirstVar, SecondVar, ThirdVar INTO Results

We can use:

Results = SomeFunction(FirstVar, SecondVar, ThirdVar)

You can use either calling form. However, we recommend the shortened form because it’s simpler and more readable. We’ll use it from this point on in the tutorial.


Caret Translation

  Related Topics

Certain special ASPECT commands perform caret "^" translation on the contents of their string arguments. Unlike the escape sequence processing, which is performed by the ASPECT Compiler when the .was file is compiled into a .wax file, caret translation occurs at run-time as the string argument is passed to the ASPECT command.

If a caret, ASCII 94, is followed by a character whose value is from ASCII 64 ("@") to 95 ("_"), a single character value is substituted within a value from 0 to 31. For example, ^@ is converted to a character value of 0, ^A is converted to value 1, and so forth up to ^_ (caret underscore) which is converted to value 31.

If a caret is followed by a character whose value is within the range 97 ("a") through 122 ("z"), a single character value is substituted with a value from 1 to 26. An ^a is converted to value 1, a ^b to value 2, and so forth up to ^z, which is converted to 26.

If a caret is followed by a vertical bar character, "|", or ASCII 124, then the two characters are converted to a single caret character, and the vertical bar is ignored.

If a caret is followed by any character other than those previously discussed, then no translation occurs, and the caret is treated like any other character.

ASPECT commands that perform caret translation are documented individually, but typically include those commands that write data to the terminal or provide strings to be tested against incoming data. For example, the transmit command writes the contents of a string to the currently active communication port. The command:

transmit "ATDT1-573-875-0503^M"

would write "ATDT1-573-875-0503" without quotes, to the active port, followed by a carriage return character, ASCII 13 or ^M.


Character Constants

  Related Topics

A character constant is an integer value representing an ASCII character within the range 0 through 255. It consists of a single quote, ASCII 39, followed by an ASCII character and a terminating single quote. An escape sequence may also be used to represent an ASCII character within a character constant. For example:

integer letter_a = ’a’     ; (integer constant 97)

integer escape = ’`033’    ; (integer constant 27)


Clipboard Commands

cliptofile	Copies data from the Windows Clipboard to a file.

cliptostr	Copies text from the Windows Clipboard to a string.

filetoclip	Retrieves the contents of a file and places the data in the Windows Clipboard.

pastetext	Sends text in the Windows Clipboard to the active COM port.

strtoclip	Copies information from a string to the Windows Clipboard.

 Return to category list


Command Line Options

You can launch Procomm Plus with the PW4 command line parameter. In addition, you can include command line arguments which control how Procomm Plus behaves once it is launched.

The PW4 command line parameter always follows this form:

PW4 [argument] [argument] ...

where each optional argument is separated by a space or tab character.

The optional arguments have the following forms:

[startup mode]	This optional argument specifies the type of Procomm Plus communication window that is launched. If it is included, it must occur as the first command line argument. Valid values include TERMINAL, FTP, MAIL, NEWS, or TELNET. Other arguments include PWFAXSTA32.DLL to launch Fax Status, and PWFAXM32.DLL to launch Fax Manager. Note that if you indicate PWFAXM32.DLL, the optional arguments shown below are not valid.

Another startup mode argument is /TRAY. This argument places a Procomm Plus "stub" icon in the System Tray on the Windows taskbar. Right-click on the icon and select from several menu items that launch Procomm Plus communication windows. Note that if you indicate /TRAY, the optional arguments shown below are not valid.

If a startup mode argument is not specified, the Terminal window is launched.

[file.dir]	This optional argument specifies a Connection Directory to load.

[CONNECT {MANUAL [class] number/address} | {[class] [GROUP] name}]
This optional argument specifies a manual connection or Connection Directory entry to connect to once Procomm Plus is launched.

If MANUAL is specified, a manual connection of the specified connection class is attempted with the specified number or address. If the connection class is not specified, the Connection Directory class associated with the current communication window is used.

If MANUAL is not specified, the name parameter must be included and enclosed in quotation marks, such as "Gargoyle BBS."  Procomm Plus searches the Connection Directory for a matching name and attempts a connection. If GROUP is specified before name, Procomm Plus interprets name as a group name and attempts to connect with the specified group. If class is specified, it overrides the Connection Directory entry class associated with the current communication window, and the Connection Directory is searched for a corresponding entry name or group name (if GROUP is also specified). Valid class values include DATA, FAX, VOICE, TELNET, FTP, MAIL, or NEWS.

[/nostartup]	If a startup.wax script exists in the path specified by Script path in the Data, Data Options, Paths panel within Setup, this optional argument prevents the script from executing when a script or connection operation has not been specified with the [file.wax...] or [CONNECT...] parameters.

[file.wax | file.was [argument list]]
This optional argument specifies an ASPECT script file for Procomm Plus to execute. If a .was file is specified, the ASPECT Compiler first compiles the script and upon successful compilation, the associated .wax file is executed. Any arguments following the script name are passed to the script in the predefined variables.

Please remember the following rules when you specify a command line option:

•	The Connection Directory, number/address, group name and script name must be enclosed in quotes.

•	Command line arguments are always delimited by spaces or tab markers.

•	Always enclose Connection Directory entry or group names in quotation marks, and be careful to include any spaces that exist in the name.

•	A quotation mark preceded by a backslash is interpreted as a quotation character. For example, the following command specifies an attempt to connect with a Connection Directory entry named This is "The Place".

PW4 CONNECT "This is /"The Place/""

•	Connection Directory names, numbers, and addresses are the only command line arguments that are case-sensitive.

•	If the [startup mode] argument is specified, it must be the first argument.

•	If a script file is specified, any arguments following the script name are passed to the script in the predefined variables.

Command Line Examples

PW4 FTP /nostartup

PW4 CONNECT DATA SYMANTEC

PW4 CONNECT MANUAL 1-123-456-7890

PW4 script.wax arg0 arg1 arg2 arg3

PW4 CONNECT FAX "Work Fax" /nostartup


Command Words and Parameters

  Related Topics

Each ASPECT command word begins on a separate line, and is always followed by any parameters it requires. The command and its parameters, if any, must be completed on a single line. However, exceptionally long source lines can be extended over several lines if a backslash (\) is used as the last character of each intermediate line. For example, both of these source lines are valid:

usermsg "Enter your name, please: "

waitfor "Enter your long message, \

please: " FOREVER

Note that if a quoted string constant is extended to two lines, any spaces occurring before the text on the second line will be included in the constant. No comments may follow the backslash.

The maximum length of a command line in a source file is unlimited.

Command words and parameters cannot be abbreviated.

Command words and parameters must be separated from each other by a space or a tab character. Commas may also be used to separate argument list items in most cases, and some special cases, they may be required.

Commands and their parameters are not case-sensitive, except for string information between quotes, as in "Hello," and format specifiers used in the strfmt command, as in "%d".

You must enter the parameters shown in a command’s syntax, unless the parameter is enclosed in brackets or otherwise identified as optional.


Command-Line Syntax

  Related Topics

The ASPECT Compiler executable, aspcompw.exe, resides in the programs directory under the Procomm Plus home directory. It is called using the following syntax:

ASPCOMPW [options] filespec

Where options may include:

/?	Display syntax screen
/Dx[=text]	Define macro x [and initialize to text]
/En	Set maximum allowable error count to n (default 20)
/ES	Save messages to an error file, with an .ERR extension
/F	Generate far calls to procedures and functions
/I path 1[;path 2][;...]	Specify the directories searched to find #include files.
/M[L]	Generate symbol map [with source line reference table]
/N	Ignore PW4.INI command line options
/O	Disable compiler optimizations
/Q	Quiet operation mode, with no screen output
/S	Compile with syntax check only
/Wn	Warning level n where n = 0, 1 (default), or 2
/X	Exit immediately after successful compile
/Z	Compile script with run-time debugging information
The ASPECT Compiler reports the following exit code values upon termination:

0	Normal termination, indicating a successful compile
-1	Error termination, indicating an unsuccessful compile
-2	Abort termination, indicating that the user closed the compiler window during compile
-3	Abort termination, indicating that the user ended the Windows session during compile

The ASPECT Compiler will accept a maximum of twenty command line options. Options, or arguments, are parsed according to the following rules:

•	Arguments are delimited by white space, meaning tab or space characters.

•	A string surrounded by double quotes is interpreted as a single argument, regardless of white space it may contain. The quotes surrounding the string will not be considered part of the argument after it is parsed.

•	A double quote preceded by a backslash (\) character is interpreted as a literal double quote (") character, and will be included in the argument with the backslash omitted.

Quotes would typically be used only when defining macros on the command line. Quotes are necessary if the macro text consists of more than one token. If the text itself should be enclosed in double quotes, such as when defining a macro as a literal string, then escape the quote characters with a backslash. For example:

/Dmac="1 2 3"	; is equivalent to #define mac 1 2 3

/Dmac="\"a b c\""	; is equivalent to #define mac "a b c"

/Dmac="\"a `\"b`\" c\""	; is equivalent to #define mac "a `"b`" c"

In the last example, back tick characters ( ` -ASCII 96) precede the innermost double quotes. A back tick character followed by a double quote is an ASPECT escape sequence, and is required when embedding quotes within literal strings. When the compiler parses this string, it will be equivalent to: a "b" c.


Commands Listed Alphabetically

  Related Topics

#

#comment	Denotes a comment block.

#endcomment	Marks the end of a comment block.

#define	Defines a macro name and the text to substitute during compilation.

#elif	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#elifdef	Allows conditional compilation by testing for the existence of a defined macro name after an associated #ifdef, #ifndef, #elifndef or another #elifdef has failed.

#elifndef	Allows conditional compilation by testing for the non-existence of a defined macro name after an associated #ifdef, #ifndef, #elifdef or another #elifndef has failed.

#else	Causes the ASPECT Compiler to process an alternate set of commands when the result of an associated #ifdef, #ifndef, #elifdef or #elifndef is false.

#endif	Concludes the #if statement group.

#if	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#ifdef	Allows conditional compilation by testing for the existence of a defined macro name.

#ifndef	Allows conditional compilation by testing for the non-existence of a defined macro name.

#include	Merges commands from another ASPECT source file during compilation.

#undef	Removes the current definition of a previously-defined macro.

A

addfilename	Adds a specified filename to a path.

alarm	Sounds an alarm to signal an event.

ansitokey	Converts an ANSI character to its corresponding virtual key code and shift state.

ansitooem	Converts an ANSI character or string to its OEM equivalent.

atof	Converts the contents of an ASCII string to a floating point value.

atoi	Converts the contents of an ASCII string to an integer value.

atol	Converts the contents of an ASCII string to a long value.

B

beep	Sounds a beep tone.

bitmap	Places a bitmap graphic in a dialog box.

bitmapbkg	Places a bitmap background in the User window.

break	Sends a break to a remote computer system.

breakpoint	Interrupts execution of a script file and displays the Debug window.

C

call	Causes script execution to branch to a specified procedure or function and permits a return.

capture	Controls session capture during script file execution.

capturestr	Writes a specified string to an open Capture file.

case	Declares a string or integer to be tested against a switch statement’s target variable.

ceil	Computes the smallest integral value greater than or equal to a floating point value.

chain	Executes another ASPECT script.

chdir	Changes the User Path to the specified drive and/or directory.

checkbox	Adds a "checkmark" selection control to a script dialog box.

clear	Clears the Terminal window and the status line.

clearxoff	Clears an XOFF state.

cliptofile	Copies data from the Windows Clipboard to a file.

cliptostr	Copies text from the Windows Clipboard to a string.

combobox	Adds a combination edit/selection or "drop down" selection control to a script dialog box.

comgetc	Assigns the next character value in the receive data buffer to an integer variable.

commandmode	Switches the modem on the current connection to command mode.

#comment	Denotes a comment block.

compile	Executes the ASPECT Compiler upon a target source file.

computc	Sends the specified character value to the communications port.

comread	Retrieves data from the receive data buffer and stores it in the target variable.

comwrite	Sends the specified string value to the communications port.

connect	Calls one or more entries in your Connection Directory.

connectmanual	Connects to the specified telephone number.

copyfile	Copies a file to another file or path.

crc16	Generates a CRC integer value for a specified string.

D

ddeadvise	Allows Procomm Plus to request the value of a variable from a Windows DDE server.

ddeexecute	Executes a command in a Windows DDE server application.

#define	Defines a macro name and the text to substitute during compilation.

ddeinit	Establishes a DDE data channel between Procomm Plus and a Windows DDE server application.

ddepoke	Assigns data from ASPECT to a Windows DDE server application.

dderequest	Receives the current value of a variable from a Windows DDE server application.

ddeterminate	Terminates an existing DDE data channel.

ddeunadvise	Terminates a current ddeadvise condition.

decrypt	Decodes an encrypted string.

default	Provides for processing when no match is found among the case statements in a switch statement group.

delfile	Deletes a specified file.

dial	Calls one or more entries in the Connection Directory.

dialadd	Adds a new entry or group to the Connection Directory.

dialcancel	Cancels a dialing operation.

dialclass	Returns a value indicating the entry class(es) for the specified entry.

dialcount	Returns the number of entries, groups or entries within a group for a particular dialing class.

dialcreate	Creates a new Connection Directory file.

dialdelete	Removes a Connection Directory entry, group or entry within a group.

dialfind	Finds the entry name and/or index associated with a specified name in the Connection Directory.

dialinsert	Inserts a Connection Directory entry into an existing group.

dialload	Loads a different Connection Directory.

dialname	Enumerates entries, groups or entries within groups.

dialnumber	Calls a specified telephone number.

dialogbox 	Denotes a dialog box statement group.

dialsave	Saves the current Connection Directory to disk.

dialstats	Retrieves information about a specified entry.

dir	Displays a standard file listing and optionally returns a selected filename.

dirlistbox	Adds a file selection list box to a script dialog.

dirpath	Displays the current disk drive and directory for a dirlistbox control in a dialog box.

disable	Disables controls, dialogs, menu selections or windows.

disconnect	Disconnects the computer from the telephone line.

diskfree	Returns the free disk space of the specified drive into a long variable.

dlgctrlwin	Returns the window id of a dialog box control.

dlgdestroy	Destroys a dialog box.

dlgevent	Returns the id of a user action within a dialog box, or flushes the event queue for the specified dialog box.

dlgexists	Sets SUCCESS to true if a dialog with the specified ID exists.

dlglist	Adds or removes an item from a list box, file list box, combo box or file combo box.

dlgsave	Updates variables associated with dialog box controls and forces changes in file combo boxes, edit boxes and list boxes to be written to disk.

dlgshow	Causes a hidden dialog box to be visible.

dlgupdate	Refreshes the display of a dialog box control.

dlgwin	Returns the window id of the specified dialog box.

dlgwinctrl	Converts a window id into the corresponding control id within a given dialog.

dllcall	Calls a routine or process within a DLL module that was created to interact with ASPECT.

dllfree	Frees unneeded DLL memory resources.

dllload	Loads the specified DLL module into memory.

dllobject	Identifies a graphic object within a User window to be updated by an associated DLL module.

dllobjfile	Specifies a file containing a graphic object to be accessedd or updated with the dllobject command.

dllobjupdt	Allows a DLL module linked to a DLL object to update that object.

dos	Executes a DOS command or another program within a separate DOS window.

E

editbox	Adds an editing box for text entry to a script dialog.

#elif	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#elifdef	Allows conditional compilation by testing for the existence of a defined macro name after an associated #ifdef, #ifndef, #elifndef or another #elifdef has failed.

#elifndef	Allows conditional compilation by testing for the non-existence of a defined macro name after an associated #ifdef, #ifndef, #elifdef or another #elifndef has failed.

else	Executes an alternate set of commands when the expressions specified in the associated if or elseif commands evaluate as false.

#else	Causes the ASPECT Compiler to process an alternate set of commands when the result of an associated #ifdef, #ifndef, #elifdef or #elifndef is false.

elseif	Enables multiple tests within an if/endif block.

enable	Enables controls, dialogs, menu selections or windows.

encrypt	Encodes a target string.

endcase	Concludes the case or default command within the switch command phrase, and transfers control to the line following the endswitch statement.

#endcomment	Marks the end of a comment block.

enddialog	Marks the end of a dialogbox statement group.

endfor	Concludes the for statement group.

endfunc	Terminates a function call block.

endgroup	Concludes a radiogroup block within a dialog box definition.

#endif	Concludes the #if statement group.

endif	Concludes the if statement group.

endproc	Terminates a procedure block.

endswitch	Terminates the switch statement group.

endwhile	Terminates the while statement group.

errormsg	Displays a message box with a graphic and specified text.

execute	Executes another ASPECT script.

exit	Terminates the executing script.

exitfor	Transfers control from a for statement group to the line following the endfor command.

exitswitch	Transfers control from a case or default statement group to the line following the endswitch command.

exitwhile	Transfers control from a while statement group to the line following the endwhile command.

exitwindows	Terminates all executing tasks and exits Windows.

F

faxcancel	Cancels the current fax operation.

faxlist	Enumerates the faxes displayed in the received or scheduled fax lists.

faxmodem	Determines if a modem is fax capable.

faxpoll	Dials a Connection Directory entry or group, or a specified number to receive faxes from a host.

faxprint	Prints a specified fax file.

faxremove	Removes a fax file from the received or scheduled fax list.

faxsend	Dials the specified number, Connection Directory entry or group and transmits a specified fax file.

faxstatus	Queries the status of a specific fax connection.

faxview	Displays a fax file.

fclear	Clears all end-of-file and error flags associated with the specified file id.

fclose	Closes the file corresponding to the specified file id.

fcombobox	Adds a combination edit/selection or "drop down" selection control to a script dialog box using a file as the list source.

fdelblock	Deletes a block of data from the specified file.

feditbox	Adds a text editing box with the contents of a disk file in a script dialog box.

feof	Tests for end-of-file condition on the specified file id.

ferror	Tests for any error condition of the specified file id.

fetch	Returns the current value(s) of any set command parameter.

fflush	Writes the current I/O buffer contents to the specified file id.

fgetc	Reads a character from the specified file id into a variable.

fgets	Reads a string from the specified file id into a variable.

fileget	Reports date, time, attributes and size for a given filespec.

fileset	Sets date, time, attributes and size for a given filespec.

filetoclip	Retrieves the contents of a file and places the data in the Windows Clipboard.

fileview	Displays a file in a modal dialog box.

findfirst	Locates a disk file using a specification you provide.

findnext	Locates additional disk files with the specification provided in a previously-executed findfirst command.

finsblock	Inserts a block of space into the specified file id.

firsttask	Returns the first task encountered in the Windows Task List.

flength	Returns the file size of an open file.

flistbox	Adds a list box to a script dialog, using the contents of a disk file for the list source.

float	Defines a global or local float variable, or an array of float variables.

floor	Computes the largest integral value less than or equal to a floating point number.

fopen	Opens a file in the indicated mode and assigns it to a file id.

for 	Repeats a command or series of commands a specified number of times.

fputc	Writes a character value to the specified file id.

fputs	Writes a string to the specified file id.

fread	Reads a block of data from a file into a variable and returns the number of bytes read.

fseek	Repositions the file pointer for the specified file id.

fstrfmt	Similar to strfmt, this command writes a formatted string to the specified file id.

ftell	Returns the current file pointer position for the specified file id.

ftext	Displays text from a file in a script dialog box.

ftoa	Converts a float to an ASCII string and stores it in a string variable.

ftp	Allows file manipulation on either host or local FTP machines.

ftruncate	Truncates or clips the file corresponding to the specified file id at the current file position.

fullpath	Returns the fully-qualified drive and path for a specified filespec.

func	Denotes a function block.

fwrite	Writes a block of data to a file.

G

getcur	Returns the current cursor location on the Terminal display.

getdir	Returns the current working directory and/or path of the specified drive into a string variable.

getenv	Returns the contents of a DOS environment variable definition.

getfile	Receives or downloads a file from a remote computer using the specified transfer protocol.

getfilename	Extracts a filename from a filespec.

getpathname	Extracts a path name from a filespec.

getvolume	Returns the volume label for the specified drive.

goto	Performs an unconditional branch to the specified label within the current procedure or function block.

groupbox	Displays a rectangle with an optional text label in a script dialog box.

H

halt	Terminates the executing script and any parent scripts unconditionally.

hangup	Disconnects your computer from the telephone line.

help	Displays on-line Help.

hotspot	Places a mouse-selectable rectangle in the User window.

I

icon	Displays an icon graphic in a script dialog box.

iconbutton	Displays an icon graphic as a clickable button in a script dialog box.

if	Denotes a block of commands which are executed if the condition associated with the if command is true.

#if	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#ifdef	Allows conditional compilation by testing for the existence of a defined macro name.

#ifndef	Allows conditional compilation by testing for the non-existence of a defined macro name.

#include	Merges commands from another ASPECT source file during compilation.

integer	Defines a global or local integer variable, or an array of integer variables.

intsltime	Converts integer date and time values into a long system time format.

isfile	Reports whether a file exists.

itemcount	Returns the number of items within a option set list.

itemcreate	Creates a new item in a option set list.

itemfind	Returns the index associated with a option set item.

itemname	Returns the name of a option set item in a string.

itemremove	Removes a script- or user-created entry from a option set list.

itoa	Converts an integer to an ASCII string and stores it in a string variable.

K

kermserve	Issues a Kermit server command.

keyflush	Clears accumulated keystrokes from the keyboard buffer.

keyget	Receives a user-keypress and stores it in a integer variable if specified.

keystate	Determines whether a key corresponding to a virtual key code is pressed.

keytoansi	Converts a key value to its ANSI character value.

keytooem	Converts a key value to its OEM character value.

L

listbox	Adds a list box to a script dialog box.

locate	Positions the terminal cursor to the location specified by row and column.

long	Defines a global or local long variable, or an array of long variables.

longjmp	Returns to a previously marked setjmp location.

loopfor	Skips the remaining commands in a for loop and branches to the top of the loop.

loopwhile	Skips the remaining commands in a while loop and branches to the top of the loop.

ltimeelapsed	Converts a timeval into a time string.

ltimeints	Converts a long time/date value in system time format into integer variables.

ltimemisc	Returns miscellaneous information about a given timeval.

ltimestring	Converts a long system time value into a string variable representing date and time.

ltimestrs	Converts a long system time value into a two string variables representing date and time.

ltoa	Converts a long to an ASCII string and stores it in a string variable.

M

makepath	Creates a path and/or filespec from individual components.

mapisend	Allows the user to send mail whenever the MAPI interface is loaded and accessible.

mciexec	Executes a high-level multimedia command.

mcisend	Allows you to issue an MCI command and retrieve the error message or the result of the command.

memaddress	Returns memory address associated with the specified memory ID.

memalloc	Allocates a block of contiguous memory for use by a script.

memavail	Returns a long value reflecting the amount of contiguous free memory available for allocation or executing other programs.

memchr	Searches for the first occurence of the specified character in an allocated memory block.

memcmp	Performs a byte-by-byte comparision of two memory locations.

memfree	Releases a block of memory previously reserved by memalloc or memrealloc.

memgetc	Retrieves a single character from a block of memory.

memicmp	Performs a byte-by-byte, case-insensitive comparision of two memory locations.

memmove	Copies characters from one location to another, either between different blocks or within the same block.

memputc	Writes a single character to a location within a block of memory.

memread	Reads a block of data from an allocated block of memory.

memrealloc	Changes the size of a block of memory previously reserved by memalloc.

memset	Initializes a block of memory to a specified value.

memsize	Reports the size of a block of memory allocated by memalloc.

memwrite	Writes a block of data to an allocated memory block.

menubar	Creates a new script menu bar.

menucheck	Places or removes a check mark on a menu item created by a script.

menuitem	Adds an item to a menu pop-up or menu bar.

menuitemcount	Returns the number of items on a menu bar or pop-up menu.

menupopup	Adds a pop-up menu to an existing pop-up menu or menu bar.

menupopupid	Returns the menu ID of a pop-up menu on a menu bar or other pop-up menu.

menuselect	Selects a PROCOMM P LUS or ASPECT menu item.

menushow	Displays the menu bar corresponding to the specified menu id.

menushowpopup	Displays a floating pop-up menu.

menustate	Reports the state of a Procomm Plus or ASPECT menu item.

metafile	Displays a metafile graphic in a script dialog box.

metafilebkg	Places a metafile background in the User window.

metakey	Executes the specified Meta Key.

mkdir	Creates a new directory using a path and/or directory name you provide.

monthstr	Returns the name of the specified month in a string.

mspause	Pauses script execution for the specified number of milliseconds.

N

nexttask	Returns the next task encountered in the Windows Task List after the execution of a firsttask command..

nullstr	Tests a string variable for the null condition.

numtostr	Converts a numeric value to a string.

O

objcoord	Returns the location coordinates of an object in the User window.

objhide	Hides an object, or a range of objects in the User window.

objmove	Moves an object identified by an id number to a new location in the User window.

objpaint	Updates the User window and some or all of the objects it contains.

objpointid	Returns the object id, if any, of an object located at a specific point.

objremove	Removes one or more objects from the User window.

objshow	Displays an object previously hidden with objhide.

oemtoansi	Converts an OEM character or string to its respective ANSI character equivalents.

oemtokey	Converts an OEM character to its key value.

P

param	Defines a parameter variable in a procedure or function.

pastetext	Sends text in the Windows Clipboard to the active COM port.

pause	Halts script execution for the specified number of seconds.

pkmode	Toggles error-free packet mode on and off.

pkrecv	Receives a packet from another computer that has issued an ASPECT pksend command.

pksend	Sends a packet to another computer that is running an ASPECT script.

playback	Plays back a Capture file or stops a playback currently in progress.

printalign	Specifies how text will be positioned when sent to the printer.

printattr	Specifies the character attributes for text sent to the printer.

printcapture	Routes characters received by Procomm Plus or entered from the keyboard to the printer.

printchar	Prints a character on the "open" printer at the current position.

printer	Opens the current printer in preparation for any of the print-command family.

printfit	Determines whether a string will print on the current page.

printfont	Selects a new printer font for subsequent print operations.

printmargin	Determines the page margins for data printed from Procomm Plus.

printstr	Sends a specified string to the open printer.

printtabs	Determines the tab positions for strings printed with the printtabstr command.

printtabstr	Prints a line of text, expanding tabs to the positions set with the printtabs command.

proc 	Denotes a procedure block.

profilerd	Reads a specified item value from any portion of a specified Windows .ini file.

profilewr	Writes a specified item value to any portion of a specified Windows .ini file.

pushbutton	Places a standard button control in a script dialog box.

putenv	Adds or changes a DOS environment variable definition.

pwexit	Terminates the executing script file, disconnects and then exits Procomm Plus.

pwmode	Places Procomm Plus into one of six execution modes.

pwtitlebar	Specifies the text to display in the Procomm Plus program title bar.

R

radiobutton	Creates or appends to a option button command group in a script dialog box.

radiogroup 	Denotes an option button command group.

rand	Returns a random value, ranging from 0 to 2147483647.

rename	Renames an existing file.

return	Exits the current procedure or function and resumes processing at the statement following the function or procedure call.

rewind	Repositions the file pointer of the specified file id to the beginning of the file.

rget	Receives and stores a text string sent by a remote system.

rmdir	Removes an existing directory using a specified path.

rstrcmp	Compares the contents of two strings up to the specified length.

run	Executes an external program in a separate window.

rxflush	Clears the receive buffer.

S

sbsave	Empties the Scrollback Buffer into a specified destination.

screentowin	Converts X/Y coordinates into coordinates relative to the specified window id.

sdlgfopen	Displays a standard file open dialog.

sdlginput	Displays a standard dialog box, allowing the user to enter a single line of text.

sdlgmsgbox	Displays a standard message box with a specified icon and button.

sdlgsaveas	Displays a standard file save as dialog box.

sendfile	Sends or uploads a file to a remote computer using the specified transfer protocol.

sendkey	Processes a keyboard shift state and a virtual key value and sends it to the focus window of the active application.

sendkeystr	Sends a specified string to the active window or dialog as if the user had sent it.

sendvkey	Processes an encoded key value and sends it to the focus window of the active application.

set	Changes system parameters which control various operations within Procomm Plus and ASPECT.

setjmp	Marks a location within a script that execution can immediately branch to using the longjmp command.

setpointer	Moves the mouse pointer to the specified X/Y screen coordinates.

setup	Manipulates the Procomm Plus Setup utility.

shell	Displays the DOS command prompt in a separate window or full screen.

shortpath	Sets a string variable to contain the short path name of the filespec.

snapshot	Copies the contents of the current logical terminal screen to a specified destination.

splitpath	Splits a file and path name.

statclear	Clears the status line in the Terminal window.

statmsg	Displays a formatted message on the status line in the Terminal window.

strcat	Concatenates one string to another string variable.

strchr	Searches for the first occurrence of a character in a given string.

strcmp	Compares two strings.

strcpy	Assigns a string to a string variable.

strcspn	Searches a string for a character contained in a second string.

strdelete	Removes characters from the contents of a string variable.

strextract	Returns a string from a list of elements.

strfind	Tests for the occurrence of the specified text within a variable.

strfmt	Creates a formatted string using a template and specified variables.

strgetc	Returns the ASCII value of a single character in a string.

stricmp	Performs a case-insensitive comparison of two strings.

string	Defines a global or local string variable, or an array of string variables.

strinsert	Inserts the contents of a string into another string.

strlen	Returns the length of a string or string variable’s contents.

strlwr	Converts the contents of a string variable to all lowercase.

strncmp	Performs a case-sensitive comparison of two strings for a specified length.

strnicmp	Performs a case-insensitive comparison of two strings for a specified length.

strputc	Modifies the value of a single character within a string.

strquote	Places the contents of a string within double quotes.

strrchr	Searches for the last occurrence of a character in a given string.

strread	Reads a block of data from a string.

strreplace	Searches a string for a specific pattern of characters and replaces that pattern with another string.

strrev	Reverses the contents of a string.

strright	Copies a string of characters from the end of a string.

strsearch	Searches a string for a specific character or pattern of characters.

strset	Sets the characters in a string variable to a specified ASCII value.

strsltime	Converts a date string and a time string into a long variable.

strspn	Searches a string for the first character that does not occur within a second string.

strtoclip	Copies information from a string to the Windows Clipboard.

strtok	Parses a delimited string into tokens.

strtonum	Converts a string to a numeric value.

strupdt	Overwrites a string with another string at a specified index.

strupr	Converts the contents of a string variable to all uppercase.

strwrite	Writes a block of data to a string.

substr	Copies the indicated number of characters from a string, beginning at a specified position.

switch 	Denotes a block of multiple decision points.

T

taskactivate	Activates the task with the specified task id.

taskexists	Tests a task id value and determines whether the task still exists.

taskexit	Terminates a Windows task.

taskname	Returns the executable name associated with a specified task id.

taskpath	Returns the executable directory used by a specified task id.

taskwin	Returns the main or top-level window id associated with a task id.

termgetc	Returns a character value from the Terminal window.

termgets	Returns a string from the Terminal window.

termkey	Processes a virtual key value and shift state and sends it to the Terminal window.

termmsg	Writes a formatted string to the Terminal window.

termputc	Writes a character value to a specified location in the Terminal window.

termputs	Writes a string to a specified location in the Terminal window.

termreadc	Reads a character value from the Terminal window at the current cursor location.

termreads	Reads a string from the Terminal window at the current cursor location.

termreset	Resets the Terminal window.

termvkey	Processes an endcoded key value and acts upon it as if it were typed in the Terminal window.

termwritec	Writes a character value to the Terminal window.

termwrites	Writes a string to the Terminal window.

text	Displays a text string in a script dialog box.

transmit	Sends a character string to the active COM port.

txflush	Clears the transmit data buffer.

U

#undef	Removes the current definition of a previously-defined macro.

usermsg	Displays a message string in a dialog.

uwincreate	Defines a User window which occupies all or part of the Terminal window.

uwinpaint	Paints the entire User window and all of its objects.

uwinremove	Removes the User window background or the entire User window.

uwutowin	Converts X/Y User Window Units to window coordinates.

W

waitfor	Pauses script execution until a target string is received from a remote system.

waitquiet	Pauses script execution until the receive data line has been inactive for a specified number of seconds.

waituntil	Pauses script processing until the specified date and/or time.

weekdaystr	Returns the name of the day of the week.

when	Forces a procedure or function call when a particular event occurs.

when quiet	Forces a procedure of function call when the receive data line has been inactive for a specified number of seconds.

when target	Forces a procedure or function call when a specified string is received from a remote system.

while	Denotes a block of repeated commands.

winactivate	Activates the specified window.

winclose	Sends a "close" message to a window.

wincoord	Returns the location and dimensions of the specified window.

winenabled	Tests the target window to determine its availability to the user or the script.

winexists	Tests for the existence of a window.

winfocus	Specifies the window to receive keyboard input.

winhide	Conceals the target window from view.

winmaximize	Maximizes an application window to fill the screen.

winminimize	Minimizes an application window to an icon.

winmove	Positions an application window.

winowner	Returns owner ID of a window ID.

winrestore	Restores an application window to its previous size from a minimized state.

winshow	Makes a hidden window visible.

winsize	Sizes the specified application window.

winstate	Returns an integer indicating the state of a window.

wintask	Returns the task id of a window.

wintext	Returns the caption or title bar text of a window.

wintoscreen	Converts X/Y coordinates into absolute screen coordinates.

wintouwu	Converts X/Y coordinates relative to a window into User Window Units.

winvisible	Tests whether a window is hidden or visible.

wizard	Activates a Procomm Plus wizard.

X

xfercancel	Cancels a current file transfer operation.

xlatin	Converts a character or string using the incoming Translate Table values.

xlatout	Converts a character or string using the outgoing Translate Table values.

xlatstr	Performs caret translation on a string.

Y

yield	Suspends script execution, allowing other tasks in Procomm Plus to continue execution until ASPECT is permitted to resume by the system.


Commands Listed by Function

  Related Topics

ASPECT Primary Commands

Clipboard Commands

COM-Related Commands

Date and Time Commands

Dialing Commands

Dialog Box Commands

DOS- or Disk-Related Commands

Dynamic Data Exchange Commands

Fax Commands

File I/O Commands

File Transfer Commands

General Procomm Plus Commands

General Windows Commands

Keyboard Commands

Internet Commands

Memory Commands

Menu Commands

Option Set Commands

Numeric, String Conversion Commands

OEM/ANSI Commands

Packet Mode Commands

Preprocessor Commands

Printer Commands

Script Control Commands

String Commands

Task/Window Manipulation Commands

Terminal Commands

User Window Commands


Compile-Time Error Messages

  Related Topics

These following error messages are generated at compile time by the ASPECT Compiler:

Syntactic Compile-Time Error Messages

Critical Compile-Time Error Messages


Compile-Time Errors

  Related Topics

Before your ASPECT script can be executed by Procomm Plus, it must be translated into symbols that Procomm Plus can understand. This translation is performed by the ASPECT Compiler.

The ASPECT Compiler reads your source file(s) line-by-line, encoding your commands, constants and variables into an executable .wax file. If the compiler encounters a line in a source file that it cannot interpret, it posts an error message in its Message List window. Hence the term "Compile-Time or syntax error."

For example, consider this simple script:

; Script to demonstrate compiler errors

proc main

string mystring = "Example."

usermsg s1 "Why won't this work? %s" mmystring

endproc

This script contains a simple mistake: the "mmystring" argument to the usermsg command is misspelled. The ASPECT Compiler is not allowed to "guess". Its only option is to report "mmystring" as invalid, with as much information as it can provide.

Let’s take a closer look at the message produced by the compiler. In only two lines, it reports four critical pieces of information:

1.	The source file which contains the error.

2.	The number of the line in which the error occurs.

3.	The kind of error encountered.

4.	The offending token involved in the error.

For step-by-step instructions on resolving compile-time errors, see Step-by-Step: Resolving Compile-Time Errors.


Compiler Options

  Related Topics

The ASPECT Compiler options allow you to control the kinds of warning messages reported to you as your script is processed by the compiler. They also allow you to enable the amount of debugging information generated by the compiler, and to specify additional options for the compiler command-line.

To configure the compiler options, open the Compile/Edit ASPECT File dialog, either by pressing <Alt><F3>or by clicking on the Compile/Edit button on the Action Bar. See "Compiling Scripts" for more information on opening the Compile/Edit ASPECT File dialog.

Once the Compile/Edit ASPECT File dialog is open, click on the Compile Options button to open the ASPECT Compiler Options dialog.  The ASPECT Compiler options are divided into three groups:

Warning Level

Other Options

ASPECT Include File Path

Additional Options and Macro Definitions


Compiler Warning Messages

  Related Topics

Warnings are non-fatal messages generated at compile time by the ASPECT Compiler. They are intended to provide information about potential oversights in the script. A target script can still be successfully created if one or more of these messages occur. When displayed in the ASPECT Compiler window, they will have a line number indicating the location of the possible problem in the source file.

Warning Level 1 Messages

Warning Level 2 Messages


Compiling Scripts

  Related Topics

Before an ASPECT script can be executed, it must be compiled. The ASPECT Compiler converts the commands and statements within an ASPECT source .was file into symbols that Procomm Plus can interpret and execute from a .wax file. Compiled scripts offer several advantages:

•	Compiled scripts are smaller, and generally run faster than interpreted text scripts.

•	Compiled scripts are more secure. The ASPECT Compiler automatically encrypts all string data, allowing you to share your compiled scripts with other users without revealing sensitive information.

•	Compiled scripts can easily support multiple-file projects. By using compiled scripts, ASPECT can support #include files and #define macro statements, allowing you to build powerful libraries of your own ASPECT functions.

ASPECT script files are usually compiled from within Procomm Plus. You can either select Tools | Scripts | Compile/Edit on the menu, or click on the Action Bar’s Compile/Edit button to open the Compile/Edit ASPECT File dialog.

For more detailed information, see The ASPECT Compiler.


Conditional Compilation

  Related Topics

You can include debugging code in your script with preprocessor and macro #define statements. For example, in the script fragment below:

#define DEBUG                   ; #Define this macro if debugging

proc main

   string today

   today = $DATE

   #ifdef DEBUG                 ; If debugging, display message

      usermsg "`"The returned date was %s`"" today

   #endif

endproc

the DEBUG macro would be defined, or active if this script were compiled now. Thus, the usermsg placed between the #ifdef DEBUG and the #endif commands would be processed and included in the compiled script. When the script executed, the usermsg dialog would be displayed. However, if a comment symbol (;) were placed in front of the #define statement:

; #define DEBUG                 ; #Define this macro if debugging

the DEBUG macro would be undefined, or inactive, and any commands placed between the #ifdef DEBUG and the #endif commands would be ignored by the compiler.


Contents
Procomm Plus Help: ASPECT Reference

Introduction to ASPECT

The Elements of ASPECT

ASPECT Command Reference

Set and Fetch Statements

System Variables

ASPECT Scripts: A Brief Tutorial

The ASPECT Utilities

Debugging Scripts

The ASPECT Compiler

ASPECT Reserved Words

Virtual Key Codes

Using Remote ASPECT Commands


Controlling Program Flow

  Related Topics

 A program in any structured programming language relies heavily on special keywords that control the flow of events. While many logon scripts are linear, more complex scripts perform activities based on conditions.

To understand conditionals that control program flow, it’s necessary to understand the meaning of the terms "true" and "false." For the purposes of ASPECT, "true" means "non-zero" while "false" represents a value of zero. The expression "5 == 4" is the same as zero, or false in ASPECT, while "5 == 5" is the same as a non-zero, or true value.

Simple Conditionals

The simplest type of conditional expression uses the if ... endif construct:

proc main

   integer Test             ; Declare variable named "Test" of integer type

        .       .           ; Some code that manipulates the value of Test.

                .

   if Test == 5             ; See if the variable now equals 5.

      call DoThis           ; If true, call a particular procedure.

   endif                    ; End of the conditional.

endproc

Although the if ... endif construct can be used in complex decision trees, at its basic level it is a simple question:

   if Test == 5             ; If Test equals value 5, THEN

      call DoThis           ; ... call our procedure.

   endif                    ; End of question

More complex variants on the if ... endif construct include if ... else ... endif and if ... elseif ... endif. A related command, the switch ... case, is fully documented. switch ... case constructs are also used in several examples later in this tutorial.

Loops

Many of the sample scripts in this tutorial include some variation of this script fragment:

#define TRUE    1

proc main

   ;       .

   ;       .        ;Other code here.

   ;       .

   while TRUE       ; Loop while true.

   endwhile

endproc

These lines cause the program to process indefinitely, until it is halted or until Procomm Plus is terminated. Why? while is a loop command. As long as the expression after the keyword while evaluates to non-zero, or true, everything between the while and endwhile executes over and over. When the expression after while evaluates to false, or 0, execution jumps to the line after the while ... endwhile construct. Since the expression "1" is true, the while TRUE / endwhile lines of code above loop endlessly. If you sandwich a transmit command between the lines, the script will transmit the same string over and over again:

while TRUE

   transmit "hi"    ; This would look like hihihihihihihihihi...

endwhile

Quite often the code in a while ... endwhile loop changes the value of the expression from true to false, causing the loop to execute a specific number of times:

proc main

   integer Counter = 0     ; Initialize the variable "Counter" to 0.

   while Counter != 5      ; This means "while counter does *not* equal 5".

      Counter++            ; Increment the value of counter (add 1 to it)

      transmit "hi"        ; and transmit "hi".

   endwhile

   transmit "^M"           ; Send a carriage return

   transmit "bye"          ; and then the word "bye".

endproc

In this example, the starting value of Counter is 0. The while expression evaluates to true, since Counter does not equal 5, and so the code inside the loop is executed. Counter is incremented to 1 and the word "hi" is transmitted. Execution loops back to the while statement. The variable Counter equals 1 now, which is still not 5, so the code inside the loop is executed again. This looping process continues until the value of Counter is 5. When the value of Counter is 5, the expression after the while keyword becomes false and execution jumps past the loop to the next line of the script. Thus, what gets transmitted by this fragment of code looks like this:

hihihihihi

bye

You can also nest loops, making loops within loops:

proc main

   integer Test1 = 1         ; Declare integer variable "Test1".

   integer Test2 = 1         ; Notice that we can initialize a variable here.

   while test1 != 5          ; Outer loop.

      while test2 < 10       ; Inner loop. Notice use of less than

         test2 ++            ; Increment test2

         ;         .         ; More code.

         ;         .

      endwhile               ; End of inner loop.

      test1 ++               ; Increment test1

   endwhile                  ; End of outer loop.

endproc

For more information on conditional expressions and looping, see the for command and the while command.

Exercise

Write a script that sends "AT^M" to your modem ten times, with a one second pause between each transmission. Try to make your script a maximum of eight lines, including the proc main and endproc statements.


Creating and Editing Scripts

  Related Topics

To write a new script "from scratch" or to change an existing source file, select Tools | Scripts | Compile/Edit..., or click on the Action Bar’s Compile/Edit icon. Procomm Plus displays the Compile/Edit ASPECT File dialog.

To create a new script, click on the New button. Procomm Plus invokes the script editor with an untitled window. Be sure to save your new file with a .was extension.

To modify an existing source file, select the .was filename from the drop-down list box and click on the Edit button. Procomm Plus invokes the script editor with the file you selected.

By default, Procomm Plus calls the ASPECT Editor. You can use your favorite Windows text editor by designating it in the Editor Name and Path field in Setup, System, System Options. For instance, if you wanted to use an editor in your c:\util directory with a filename of zedit.exe, you’d specify c:\util\zedit.exe in this field.


Critical Compile-Time Error Messages

  Related Topics

Compilation will terminate immediately if one of these error messages occurs.

C500	Internal compiler error
C501	Insufficient memory
C502	Unexpected end of file
C503	Stack under flow
C504	Stack overflow (nesting too deep)
C505	Procedure too large to compile
C520	Invalid command line option
C521	Missing script filespec
C522	Invalid script file name
C523	Error opening script file
C524	Error opening output file
C525	Error writing to output file
C600	Fatal exception


Critical Run-Time Errors

  Related Topics

101 Insufficient memory

There is not enough memory to run the script file.

102 Stack overflow in procedure call

A procedure or function call was made which required more stack space than was available at the time, either for passed parameters or local variables.

Usually this problem occurs if there are procedure or function calls nested very deeply, as might occur in a recursive call, or procedures or functions with large numbers of local string variables.

103 Unexpected end of file

An attempt to read the next script command from the compiled script failed. See error 106 for more details.

104 File I/O error

A critical error occurred while reading data from the target script file. The data being read was not valid. See error 106 for suggestions.

105 Unable to restore script task

Upon return from a child script an error occurred preventing the parent script from being completely restored.

106 Invalid command encountered

A command was encountered which is not recognized among ASPECT’s command set. This is a serious condition which indicates a corrupted file or an error within the compiler. First, attempt to re-compile the script file and execute it again. If the error still exists, contact technical support.

107 Invalid data type encountered

A data type was not recognized as valid. This is a serious condition which indicates a corrupted file or an error within the compiler. First, attempt to re-compile the script file and execute it again. If the error still exists, contact technical support.

108 Buffer overflow in string format

A string format operation such as strfmt exceeded the maximum length allowed for the output of formatted data. This error is critical in that it may have corrupted internal data within Procomm Plus.

109 Value out of range

This error occurs when a valid value was required for continued successful script execution, but because one was not provided, the run-time engine was in a state where it could not resume execution without the possibility of causing more serious problems.

120 Internal Windows ASPECT run-time error

This error indicates a serious problem within the ASPECT run-time processor. First, attempt to re-compile the script file and execute it again. If the error still exists, make a note of the full text of the message so that you can be report it to technical support.

121 Fatal exception during script execution

This error indicates a serious error within ASPECT or the instance of Procomm Plus that is running the script. Restart Procomm Plus and attempt to run the script again. If the error persists, please contact technical support.


Custom Interface Functions

  Related Topics

Windows ASPECT supports two important graphical interface formats: the User window and the dialog box.

The User window functions allow you to customize the appearance of Procomm Plus’s main window for the needs of your script. You can:

•	Display bitmaps, icons or metafiles.

•	Display clickable buttons or bitmaps.

•	Resize or even hide the Terminal window, using a bitmap or metafile background.

•	Create invisible "hotspots" in the User window that the user can click on.

•	Create custom objects that are controlled by a custom Dynamic Link Library (DLL).

For more information, see The User Window.

The dialog box functions allow you to create customized dialog boxes for any purpose. ASPECT dialog boxes support most of the standard Windows dialog controls, including:

•	Pushbuttons and icon buttons.

•	List Boxes and combo boxes, including a special dirlistbox control for lists of files within a directory.

•	Edit boxes for strings or text files.

•	Static and variable text for labels and information, including a special dirpath control for displaying the current drive and path.

•	Check Boxes and option buttons.

ASPECT also supports the use of graphical elements such as icons, bitmaps, metafiles and groupboxes within dialog boxes.

For more information, see Dialog Boxes.


DIAL Set/Fetch Statements

  Related Topics

The set dialentry commands are used to change the settings for specific Connection Directory entries.

When Connection Directory changes are complete, the dialsave command should be issued to save them.

dial location string

Specifies the location name appearing in the Current Location field in the Setup, System, Dialing Options dialog. fetch returns the current location in a string.

dial retries integer

Specifies the maximum number of times that Procomm Plus will attempt to connect with a Connection Directory entry. Valid values range from 0 to 999. This command corresponds to the Make x attempts and... field in the Setup, System, Dialing Options dialog. fetch returns the maximum number of dial attempts as an integer.

dial retrydelay integer

Specifies the number of seconds Procomm Plus pauses between dial attempts when redialing a number. Valid values range from 0 to 99. This command corresponds to the ... pause x seconds between attempts edit field in Setup, System, Dialing Options. fetch returns the current value in an integer.


DIALENTRY Set/Fetch Statements

  Related Topics

The set/fetch dialentry commands are used to retrieve and change the settings for specific Connection Directory entries. Other set/fetch commands that are common between the Connection Directory and Setup can also be used to retrieve and change the settings for Connection Directory entries. The set dialentry access command allows you to select the Connection Directory entry that these commands affect. When Connection Directory changes are complete, the dialsave command must be issued to save them.

Using set to change Connection Directory entry data will fail when the Connection Directory is displayed.

dialentry access OFF | {dialclass string}

Specifies the Connection Directory entry by name and class that subsequent set commands affect.

fetch dialentry access is shown separately for clarity.

dialentry access intvar strvar

fetch dialentry access returns an integer containing the type of Connection Directory entry and the name of the specified entry in a string. If set dialentry access is OFF, the intvar is assigned to 1 (DATA) and the strvar is a null string. The intvar can have any of the values that represent a single dialclass. For further information you may wish to see the dialclass command.

The dialname command can be used to get the name of a specific entry, based on its index within the Connection Directory. For more information, see the dialname command.

dialentry anonymouslogon OFF | ON

Specifies whether or not this entry uses anonymous logon or not. This command corresponds to the Anonymous logon check box in the FTP section of the Connection Directory.

In order for this command to be effective, the dialclass specified in the set/fetch dialentry access command must have been FTP.

dialentry areacode string

Specifies the area code for the selected Connection Directory entry. This command corresponds to the Area Code edit field in the selected Data-, Fax-, or Voice-class Connection Directory entry. fetch returns the entry’s area code in a string.

dialentry company string

Specifies the contents of the Company edit field for the selected Connection Directory entry. fetch returns the contents of the currently-selected Connection Directory entry’s Company edit field in a string.

dialentry country string [strvar]

Specifies the contents of the Country edit field for the selected Connection Directory entry. fetch allows the optional string variable which is assigned the dialing code for the current Country selection.  This command is valid only for Data-, Fax- and Voice-class entries.

dialentry dialnumberonly OFF | ON

Specifies whether Procomm Plus should dial only the Data number for the current entry.  fetch returns a zero for OFF and a 1 for ON.  This command is valid only for Data-, Fax-, and Voice-class entries.

dialentry hostdir string

Specifies the directory on the host system to view. This command corresponds to the Default Host Directory: field in the FTP, Basic Options dialog of the Connection Directory. fetch returns the current contents of the field in a string, or a null string if the field is blank.

In order for this command to be effective, the dialclass specified in the set/fetch dialentry access command must have been FTP.

dialentry hosttype index

Specifies what type of host is on the remote system. This command corresponds to the Host Type: list in the FTP, Basic Options dialog of the Connection Directory. fetch returns the current index value in an integer.

In order for this command to be effective, the dialclass specified in the set/fetch dialentry access command must have been FTP.

dialentry ipaddress string

Specifies the IP Address used to contact a host for a Telnet-, FTP-, Mail-,or News-class Connection Directory entry. This command corresponds to the Host/IP Address:, Address:, Mail Address: or News Group: field in the Connection Directory. fetch returns the current contents of the field.

dialentry ipport integer

Specifies which TCP/IP port to use when receiving data from the host. This command corresponds to the Telnet Port or FTP Port fields in the corresponding Options dialogs of a Telnet- or FTP-class Connection Directory entry. fetch returns the contents of the field in an integer.

dialentry logontimeout integer

Specifies how long Procomm Plus will wait for a response from the host while in FTP mode. This command corresponds to the Logon Timeout: field in the FTP, FTP Options dialog in the Connection Directory. fetch returns the value of the field in an integer.

dialentry longdistance OFF | ON

Specifies whether Procomm Plus should always dial the current entry as a long distance number. this command correspond to the Always dial as long distance check box in Data-, Fax-, or Voice-class entries. fetch returns a zero for OFF and a 1 for ON. This command is valid only for Data-, Fax- and Voice-class entries.

dialentry phonenumber string

Specifies the phone number to use for the selected Data-, Fax-, or Voice-class Connection Directory entry.

fetch dialentry phonenumber is shown separately for clarity.

fetch dialentry phonenumber strvar

fetch dialentry phonenumber returns a string containing the phone number for the selected Connection Directory entry. This command is valid if the dialclass specified in the set/fetch dialentry access command was either DATA, FAX, or VOICE.

dialentry scriptfile filename | NONE

Specifies the script file to be associated with the selected Data-, Telnet-, or FTP- class Connection Directory entry. This command corresponds to the Connection Directory entry’s Script edit field. fetch returns the name of the selected entry’s script filename in a string.

If the filename argument is specified, a filename extension is optional. However, if an extension is included, it must be .wax. set dialentry scriptstart may be used to determine when the script file should run.

dialentry scriptstart CONNECTED | DIALED

Specifies when the selected Data-, or FTP- class Connection Directory entry’s associated script file is run. This command corresponds to the settings in the Script Execution Options dialog, opened with the Script Setup... button in the Connection Directory entry. If DIALED is specified, the script is launched when the entry is dialed. If CONNECTED is used, the script is launched when a connection is established with the entry. fetch returns 0 for CONNECTED or 1 for DIALED.

dialentry terminalid string

Specifies the ID string to send when negotiating a Telnet connection. This command corresponds to the When negotiating... field in the Telnet Options dialog of the Connection Directory. fetch returns the contents of the field in a string or a null string if the field is empty.

In order for this command to be effective, the dialclass specified in the set/fetch dialentry access command must have been TELNET.


DOS- or Disk-Related Commands

addfilename	Adds a specified filename to a path.

chdir	Changes the User Path to the specified drive and/or directory.

copyfile	Copies a file to another file or path.

delfile	Deletes a specified file.

dir	Displays a standard file listing and optionally returns a selected filename.

diskfree	Returns the free disk space of the specified drive into a long variable.

dos	Executes a DOS command or another program within a separate DOS window.

fileget	Reports date, time, attributes and size for a given filespec.

fileset	Sets date, time, attributes and size for a given filespec.

fileview	Displays a file in a modal dialog box.

findfirst	Locates a disk file using a specification you provide.

findnext	Locates additional disk files with the specification provided in a previously-executed findfirst command.

fullpath	Returns the fully-qualified drive and path for a specified filespec.

getdir	Returns the current working directory and/or path of the specified drive into a string variable.

getenv	Returns the contents of a DOS environment variable definition.

getfilename	Extracts a filename from a filespec.

getpathname	Extracts a path name from a filespec.

getvolume	Returns the volume label for the specified drive.

isfile	Reports whether a file exists.

makepath	Creates a path and/or filespec from individual components.

mkdir	Creates a new directory using a path and/or directory name you provide.

putenv	Adds or changes a DOS environment variable definition.

rename	Renames an existing file.

rmdir	Removes an existing directory using a specified path.

run	Executes an external program in a separate window.

shell	Displays the DOS command prompt in a separate window or full screen.

shortpath	Sets a string variable to contain the short path name of the filespec.

splitpath	Splits a file and path name.

 Return to category list


Data Types

  Related Topics

ASPECT supports four data types:

integer	Values range from -2147483648 to 2147483647. An integer requires 4 bytes of storage.

float	Values range from a minimum positive value of 2.22507385072014e-308 to a maximum value of 1.7976931348623158e+308. Rounding is performed after 15 digits of decimal precision. A float requires 8 bytes of storage.

long	Values range from -2147483648 to 2147483647. A long requires 4 bytes of storage.  Long constants carry a long suffix.

string	May contain from 0 to 256 characters.

For an explanation of how numeric and string constants are interpreted by the ASPECT Compiler, see User-defined Constants.


Date and Time Commands

intsltime	Converts integer date and time values into a long system time format.

ltimeelapsed	Converts a timeval into a time string.

ltimeints	Converts a long time/date value in system time format into integer variables.

ltimemisc	Returns miscellaneous information about a given timeval.

ltimestring	Converts a long system time value into a string variable representing date and time.

ltimestrs	Converts a long system time value into a two string variables representing date and time.

monthstr	Returns the name of the specified month in a string.

strsltime	Converts a date string and a time string into a long variable.

weekdaystr	Returns the name of the day of the week.

 Return to category list


Debugging Options

  Related Topics

Other compiler options are of particular value when you’re tracking down logic or syntax errors in your source files. If you’re unsure of whether to change these settings, leave them at their defaults. For more detailed information, see Compiler Options.

Compile for debug

If you select this check box, the ASPECT Compiler will embed special information within the .wax file. This information can be used to display information about the script through the use of the ASPECT breakpoint command. By default, this check box is unselected.

Create map file

If you select this check box, Procomm Plus will create a symbol map for the compiled script. It will use the source’s filename with an extension of ".map". The map file provides complete details of each procedure and global variable, along with a summary of the resulting compiled script. If the compiler generates any warning messages in the Message List box for the script, they will also be included in the map file. By default, this check box is not selected.

Include line numbers

To include an additional source line number/offset reference table in the symbol map, check this box. If you compile a script with the Compile for debug option, the line number/offset table will allow you to cross-reference any run-time offset messages generated by Procomm Plus. By default, this check box is not selected; it can only be selected if the Create map file check box is selected.

ASPECT Include File Path

This edit field allows you to specify directories that the ASPECT Compiler will search for #include files that are not found in the main script file’s directory. You can enter multiple paths by separating them with a semi-colon. For example:

c:\aspect;c:\aspect\shared;d:\aspmisc

Additional Options and Macro Definitions (saved)

To specify additional macros or compiler options to be used each time you compile a script, enter them in this field. For a complete list of compiler options, refer to The ASPECT Compiler.

Additional Options and Macro Definitions (not saved)

To specify additional macros or compiler options to be used only for the current session of Procomm Plus, enter them in this field.


Debugging Scripts Overview

  Related Topics

It’s rare that a programmer in any language writes a program that compiles perfectly the first time! The process of tracking down logic, syntax and flow errors within a program is called debugging.

There are three kinds of errors that can commonly occur as you are developing a script. They are:

•	Compile-Time or syntax errors.

•	Logic errors.

•	Execution or Run-Time errors.

For more information, see the following topics:

Compile-Time Errors

Step-by-Step: Resolving Compile-Time Errors

Logic Errors

Conditional Compilation

Execution or Run-Time Errors

Step-by-Step: Resolving Run-Time Errors


Defining Variables

  Related Topics

Whether global or local, all variables must be defined before they are referenced in a script. Multiple variable definitions of the same data type may occur on a single line if each definition is separated with a comma.

Variables may also be initialized when they’re defined, as in:

integer number1, number2=13

Up to 256 global variables of each data type can be defined in a single script. In addition, a user can define up to 256 global variable arrays for each of the data types. This allows the user to define up to 2048 unique global variables in a single script!

The number of local variables allowed is limited by the run-time stack space available at the time the procedure or function is called. In general, this should not be considered a limitation; the stack can grow as large as 64K, which would allow for over 15,000 integer variables! If the run-time stack cannot accommodate the space required by a procedure’s or function’s local variables, a stack overflow error will occur, and the script will terminate.


Dialing Commands

connect	Calls one or more entries in your Connection Directory.

connectmanual	Connect to the specified telephone number.

dial	Calls one or more entries in the Connection Directory.

dialadd	Adds a new entry or group to the Connection Directory.

dialcancel	Cancels a dialing operation.

dialclass	Returns a value indicating the entry class(es) for the specified entry.

dialcount	Returns the number of entries, groups or entries within a group for a particular dialing class.

dialcreate	Creates a new Connection Directory file.

dialdelete	Removes a Connection Directory entry, group or entry within a group.

dialfind	Finds the entry name and/or index associated with a specified name in the Connection Directory.

dialinsert	Inserts a Connection Directory entry into an existing group.

dialload	Loads a different Connection Directory.

dialname	Enumerates entries, groups or entries within groups.

dialnumber	Calls a specified telephone number.

dialsave	Saves the current Connection Directory to disk.

dialstats	Retrieves information about a specified entry.

 Return to category list


Dialing without the Connection Directory

  Related Topics

The transmit command can be used to send commands to your modem, as well as to send text such as your name and password as shown in the previous section. Look at the following script file:

#define BBS_NUMBER "555-1234"; Define phone number macro

#define PASSWD "Rosebud^M"  ; Define password macro

proc Main                   ; Start of Main procedure.

   commandmode on           ; Enter command mode.

   transmit "ATDT"          ; The modem dial command

   transmit BBS_NUMBER      ; .. the number to dial.

   transmit "^M"            ; ... a carriage return.

   waitfor "Name: "         ; Wait for name prompt.

   transmit "Orson Welles^M"; Send your name.

   waitfor "Password:  "    ; Now the password prompt

   transmit PASSWD          ; Send password.

   waitfor "again: "        ; This system confirms passwords

   transmit PASSWD          ; So let’s send it again.

   alarm 2                  ; Wake up!

   usermsg "OK, you’re in"  ; You’re on.

   while $CARRIER           ; Loop as long as the modem is

      yield                 ; connected.

   endwhile                 ;

   commandmode OFF          ; release the modem to TAPI.

endproc                     ; End of Main procedure

Using Macros

In this script we use macros or #define statements to make our script easier to maintain. Wherever the word BBS_NUMBER appears it is replaced with the string "555-1234". Similarly, whenever PASSWD appears, it is replaced with the string "Rosebud" followed by a carriage return.

On first glance, it may seem as though our macros were a waste of time. After all, the phone number and password could just as easily been placed with the transmit statements. But what if the script were longer, or you needed to change the password? With the critical strings #defined at the top of the script, you’ll find them quickly and easily, and you’ll be able to change every instance of your password simply by editing the appropriate #define statement!

Learn more interesting uses for macros in Advanced Topics: Using Macro Definitions.

Notice the detailed comments for each line of the script file. Comments are optional notes that help you understand your programming later. They’re always preceded by a semi-colon and are therefore ignored by the compiler, so they don’t become part of the compiled script.

We also added two commands: a two-second alarm and a simple boxed message with the usermsg command to alert you when the connection is made.

Since this script actually dials the phone number, you run it by itself instead of from the Connection Directory. After you’ve compiled the script, you can execute it by choosing Run from the Scripts menu, or by selecting it from the Script File list box on the Action Bar.

There are other ways to automate calling without attching a script file to a Connection Directory. For example, the dialnumber command places a call just as though you had initieated a maunal dial from the Connection Directory.

Set and Fetch

ASPECT has a set and fetch command for almost every option available in the program. Set and Fetch Statements contains a complete list.

For instance, suppose that you have several Internet Mail accounts, including a separate mail account for your business. If you configure each account as an option set within Setup, you could specify a particular option set within the script. By creating an option set called “Business Mail” you could simply add this line to a script to switch your option set:

set internet mail options “Business Mail”

Switching option sets is as easy as using a set command along with the option set’s name included in quotes, or as a string.

As an alternative to using the option set’s name, you can reference it numerically using a zero based index. For example:

set internet mail options 1

would assign the second option set as the Current Mail Options.

Exercise

Write a script that dials a phone number without using the Connection Directory. Use one #define statement for the dialing command and another for the phone number.

Don’t forget to transmit a Carriage Return after the number! This is the modem's "execute" command, which causes it to process the commands you've sent.


Dialog Box Commands

bitmap	Places a bitmap graphic in a dialog box.

checkbox	Adds a "checkmark" selection control to a script dialog box.

combobox	Adds a combination edit/selection or "drop down" selection control to a script dialog box.

dialogbox 	Denotes a dialog box statement group.

/ enddialog

dirlistbox	Adds a file selection list box to a script dialog.

dirpath	Displays the current disk drive and directory for a dirlistbox control in a dialog box.

dlgctrlwin	Returns the window id of a dialog box control.

dlgdestroy	Destroys a dialog box.

dlgevent	Returns the id of a user action within a dialog box, or flushes the event queue for the specified dialog box.

dlgexists	Sets SUCCESS to true if a dialog with the specified ID exists.

dlglist	Adds or removes an item from a list box, file list box, combo box or file combo box.

dlgsave	Updates variables associated with dialog box controls and forces changes in file combo boxes, edit boxes and list boxes to be written to disk.

dlgshow	Causes a hidden dialog box to be visible.

dlgupdate	Refreshes the display of a dialog box control.

dlgwin	Returns the window id of the specified dialog box.

dlgwinctrl	Converts a window id into the corresponding control id within a given dialog.

editbox	Adds an editing box for text entry to a script dialog.

fcombobox	Adds a combination edit/selection or "drop down" selection control to a script dialog box using a file as the list source.

feditbox	Adds a text editing box with the contents of a disk file in a script dialog box.

flistbox	Adds a list box to a script dialog, using the contents of a disk file for the list source.

ftext	Displays text from a file in a script dialog box.

groupbox	Displays a rectangle with an optional text label in a script dialog box.

icon	Displays an icon graphic in a script dialog box.

iconbutton	Displays an icon graphic as a clickable button in a script dialog box.

listbox	Adds a list box to a script dialog box.

metafile	Displays a metafile graphic in a script dialog box.

pushbutton	Places a standard button control in a script dialog box.

radiobutton	Creates or appends to a radio button command group in a script dialog box.

radiogroup 	Denotes an option button command group.

/ endgroup

text	Displays a text string in a script dialog box.

 Return to category list


Dialog Boxes

  Related Topics

A dialog box is defined by the dialogbox command, which requires arguments and keywords specifying the size, placement and behavior of the dialog. Elements within the dialog are known as controls, and are created using the appropriate ASPECT commands within the dialogbox statement group.

Up to a total of 255 controls can be used within a single dialog box.

Dialog Box Control Id’s

Each dialog box control is assigned a unique id value. The dialog box control id must be an integer value from 1 up to 999. The ASPECT Compiler will detect duplicate control id’s and report them as errors.

Control id’s are used to manipulate their associated controls. They are also used to detect when those controls have been selected or modified by the user. For more information, see the description of the dialogbox command.

Dialog Box Units

When a dialog box is created, its overall size and the position and size of the controls within it are determined in Dialog Box Units, or DBUs. The DBU is based on the size of the current system font. A vertical DBU is 1/8 of the height of the system font. A horizontal DBU is 1/4 of the average width of the system font.

In most cases, you will not need to worry about calculating Dialog Box Units, as the Dialog Editor does this for you automatically!


Dynamic Data Exchange Commands

ddeadvise	Allows Procomm Plus to request the value of a variable from a Windows DDE server.

ddeexecute	Executes a command in a Windows DDE server application.

ddeinit	Establishes a DDE data channel between Procomm Plus and a Windows DDE server application.

ddepoke	Assigns data from ASPECT to a Windows DDE server application.

dderequest	Receives the current value of a variable from a Windows DDE server application.

ddeterminate	Terminates an existing DDE data channel.

ddeunadvise	Terminates a currente ddeadvise condition.

 Return to category list


Emulation Names and Indices

  Related Topics

The set and itemcreate commands use reserved names or indices to reference the emulations supported by Procomm Plus.

The emulation names and their corresponding indices are

EMULATION NAME AND INDEX TABLE

Name	Index	Name	Index
ADDS60	0	TTY	17
ADDS90	1	TVI910	18
ADM31	2	TVI912	19
ADM3A	3	TVI920	20
ADM5	4	TVI922	21
ANSIBBS	5	TVI925	22
ATT4410	6	TVI950	23
ATT605	7	TVI955	24
DGD100	8	VIDTEX	25
DGD200	9	VT52	26
DGD210	10	VT100	27
ESPRIT3	11	VT102	28
HEATH19	12	VT220	29
IBM3101	13	VT320	30
IBM3161	14	WYSE50	31
IBM3270	15	WYSE60	32
IBMPC	16	WYSE75	33
RIP	n/a (see below)	WYSE100	34
The RIPscrip emulation is shipped as a .dlt, meaning that it does not have an associated index value.

Emulations and protocols that are shipped with Procomm Plus as Dynamic Linked Libraries do not have associated index values. For convenience, ASPECT provides reserved keyword names for these .dlt (Dynamic Linked Terminal) and .dlp (Dynamic Linked Protocol) modules such as the RIPscrip terminal and the Ind$file file transfer protocol. For best results, you should use the module's keyword or string name whenever a protocol or emulation name is required.

For more information, see Set and Fetch Statements.


Error message no command
There are no commands that start with that letter. Please choose another letter.


Error message no reserved
There are no reserved words that start with that letter. Please choose another letter.


Error message no sysvar
There are no system variables that start with that letter. Please choose another letter.


Escape Sequences

  Related Topics

ASPECT uses escape  sequences in string and character constants to represent non-displayable characters and control codes which have special meanings to hardware devices. They consist of a backwards single quote character `, followed by an alphabetic character or series of digits. The "`" character is ASCII 96, available on the unshifted tilde key; it is sometimes called the "back tick". The following table details the escape sequences supported by ASPECT:

	Escape Sequences
Sequence	ASCII Value	Description
`a	7	Alert or Bell
`b	8	Backspace
`f	12	Form feed
`n	10	New line/line feed
`r	13	Carriage return
`t	9	Horizontal tab
`v	11	Vertical tab
``	39	Single quote
`"	34	Double quote
`'	96	Backwards single quote
`000	ASCII character	octal notation
`xhhh	ASCII character	hex notation
If a backwards single quote precedes a character not listed above, the backwards single quote will be ignored.

When a "000" or "xhhh" sequence is used, it may consist of one to three octal or hexadecimal digits ranging in decimal values from 0 to 255. Values greater than 255 will generate an error. It is usually best to use all three digits, as in `004, since a letter or digit immediately following an escape sequence may represent either an octal or hexadecimal character which would then be interpreted as part of the escape sequence.


Execution or Run-Time Errors

  Related Topics

The ASPECT Compiler translates or compiles your script file(s) into a .wax file that Procomm Plus can run. The compiler cannot anticipate some problems that may occur while the script is running, however. When ASPECT encounters a problem when it is running your script, it reports it as a run-time error.

Run-time errors can be either "critical" or "non-critical". While critical run-time errors are rare, they signal potentially dangerous conditions within the script execution routines. Procomm Plus will always terminate a script if a critical error occurs.

Non-critical errors are less serious. They are often the result of logic errors within the script. Procomm Plus prompts for confirmation before continuing script execution in response to a non-critical error, but it’s usually a good idea not to continue a script after a non-critical error, since the problem may cause unintended results.

For step-by-step instructions on resolving run-time errors, see Step-by-Step: Resolving Run-Time Errors.

For detailed explanations of run-time errors, see ASPECT Run-Time Error Messages.


FAX Set/Fetch Statements

  Related Topics

The set and fetch fax commands are used to retrieve and change Procomm Plus fax options. They correspond to options in Setup’s Fax dialogs.

set fax commands that correspond to the fields on the System, Modem Connection, Fax Settings dialog in Setup will fail for all "direct connect" and .dlc connections like Telnet.

All set fax commands will fail if Procomm Plus is currently dialing, if a file transfer is in progress or if another instance of Procomm Plus exists.

fax adaptive19200 OFF | ON

Specifies whether or not to change the baud rate to 19200 when performing Adaptive Answer. This command corresponds to the Automatically switch baud rate to 19,200... check box in the Setup, System, Modem Connection, Fax Settings, Adaptive Answer dialog. fetch returns a 0 if the check box is not enabled and a 1 if it is.

fax adaptiveans CLASS1 | CLASS2 string

Specifies the modem commands used to enable adaptive answer for Class 1 and Class 2 fax. This command corresponds to the Enable command: fields in the Class 1 Adaptive Answer and Class 2 Adaptive Answer groups of the Setup, System, Modem Connection, Fax Settings, Adaptive Answer dialog. fetch returns the contents of the specified adaptive answer command’s edit field in a string.

fax baudrate long

Specifies the DTE speed to use when faxing. This command corresponds to the Fax baud rate (DTE) field in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns the current value in a long. Possible values include 19200, 28800, 38400, 57600, or 115200.

fax class CLASS1 | CLASS2 | SIERRA

Specifies the standard used to transmit faxes. This command corresponds to the Fax class: list in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns 1 for CLASS1, 2 for CLASS2 or 4 for SIERRA.

fax cnctmsg CLASS1 | CLASS2 string

Specifies the connect message for fax adaptive answer connections. This command corresponds to the Fax connect message edit fields in the Class 1 Adaptive Answer and Class 2 Adaptive Answer groups of the Setup, System, Modem Connection, Fax Settings, Adaptive Answer dialog. fetch returns the contents of the Adaptive answer connect message field in a string.

fax company string

Specifies the contents of the Company: edit field in the Setup, Fax, User Info, User Info dialog. fetch returns contents of the Company field in a string.

fax coversheet filename | NONE

Specifies the default fax cover sheet used in transmitted faxes. This command corresponds to the Default cover sheet: list in the Setup, Fax, User Info, User Info dialog. fetch returns the contents of the Default cover sheet list in a string. If no default cover sheet is defined, fetch returns a null string.

fax delpages OFF | ON

Determines whether fax pages are deleted after a fax is sent. This command corresponds to the Delete pages after send check box in the Setup, Fax, Fax Options, dialog. fetch returns 0 for OFF or 1 for ON.

fax ecm receive NONE | SOFTWARE | HARDWARE

Specifies what type of error correcting method Procomm Plus uses when receiving faxes in Class 1 mode. This command corresponds to the Fax ECM during receive... list in the Setup, System, Modem Connection, Fax Settings, Advanced dialog. fetch returns a 0 for NONE, a 1 for SOFTWARE, and a 2 for HARDWARE.

fax ecm send NONE | SOFTWARE | HARDWARE

Specifies what type of error correcting method Procomm Plus uses when sending faxes in Class 1 mode. This command corresponds to the Fax ECM during send... list in the Setup, System, Modem Connection, Fax Settings, Advanced dialog. fetch returns a 0 for NONE, a 1 for SOFTWARE, and a 2 for HARDWARE.

fax faxnumber string

Specifies the fax number displayed on fax cover sheets and in the header at the top of fax documents. This command corresponds to the Fax number field in the Setup, Fax, User Info, User Info dialog. fetch returns the contents of the Fax number field in a string.

fax flowcontrol SOFTWARE | HARDWARE

Specifies the type of flow control used when sending faxes. This command corresponds to the Flow control list in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns 0 for SOFTWARE or 1 for HARDWARE.

fax header PAGENUMBERS | TIMESTAMP | {RECEIVER USERNAME | FAXNUMBER} | {SENDER USERNAME | COMPANY | FAXNUMBER | VOICENUMBER | STATIONID} OFF | ON

Specifies the user information included in the header of transmitted faxes. This corresponds to the check box options found in the Include in Fax Header groupbox in Setup, Fax, User Info, Fax Header. These include Page numbers, Date and time, Receiver’s fax number, Receiver’s name, Sender’s name, Sender’s company, Sender’s fax number, Sender’s voice number, and Sender’s station ID.

fetch returns 0 if the specified option is OFF or 1 if it is ON.

fax init string

Specifies the command string sent to the modem before a fax is transmitted. This command corresponds to the Fax initialization string edit field in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns the contents of the Fax initialization string field in a string.

fax linetype CONVENTIONAL | CELLULAR

Specifies what type of phone line the fax is being sent over. This command corresponds to the Telephone line type: list in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns 0 for CONVENTIONAL and 1 for CELLULAR.

fax manager OFF | ON

Specifies whether Fax Manager is run after a fax is received. This command corresponds to the Run Fax Manager check box in the Setup, Fax, Fax Options dialog. fetch returns 0 if the check box is not enabled, or 1 if it is enabled.

fax options index | string

Specifies the set of saved options used by Procomm Plus. A zero-based index value or a string specifying the name of the options set may be used. This command corresponds to the Current User Info list in the Setup, Fax, User Info dialog. fetch returns the name of the options set selected in a string.

fax path coversheet pathname

Specifies the path Procomm Plus will search for fax cover sheets. This command corresponds to the Fax cover sheet files: edit field in Setup, Fax, Fax Paths. fetch returns the contents of the Fax cover sheet files field in a string.

fax path inbox pathname

Specifies the path incoming fax documents are stored by Procomm Plus. This command corresponds to Received faxes: field in the Setup, Fax, Fax Paths dialog. fetch returns the contents of the Received faxes field in a string.

fax path sent pathname

Specifies the path where faxes are stored after they’ve been sent. This command corresponds to the Sent faxes directory: field in the Setup, Fax, Fax Paths dialog. fetch returns the contents of the Sent faxes directory: field in a string.

fax path outbox pathname

Specifies the path where faxes are stored before they’re transmitted. This command corresponds to the Scheduled faxes edit field in the Setup, Fax, Fax Paths dialog. fetch returns the contents of the Scheduled faxes field in a string.

fax recvbaud long

Specifies the maximum baud rate used when receiving faxes. This command corresponds to the Maximum receive rate field in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns a long value representing the current maximum receive rate. Possible values are 2400, 4800, 7200, 9600, 12000, or 14400.

fax recvprint OFF | ON

Determines whether faxes are printed upon receipt. This command corresponds to the Print fax check box in the Setup, Fax, Fax Options dialog. fetch returns 0 for OFF or 1 for ON.

fax recvview OFF | ON

Determines whether faxes are displayed upon receipt. This command corresponds to the View fax check box in the Setup, Fax, Fax Options dialog. fetch returns 0 for OFF or 1 for ON.

fax retries integer

Determines the number of send fax dialing attempts Procomm Plus will make before aborting; valid values range from 0 to 99. This command corresponds to Make up to x attempts field in the Setup, Fax, Fax Options dialog. fetch returns an integer reflecting the current number of dialing attempts.

fax retrydelay integer

Determines the number of seconds Procomm Plus pauses between send fax attempts. This command corresponds to the Retry every x minutes field in the Setup, Fax, Fax Options dialog. fetch returns an integer reflecting the current Retry interval value.

fax reversebit {PORT | FAX} {SEND | RECEIVE} {OFF | ON | DEFAULT}

Determines whether or not Procomm Plus uses a reverse bit order when sending or receiving faxes. This command corresponds to the four Reverse... check boxes on the Setup, System, Modem Connection, Fax Settings, Advanced dialog. Depending on the first two parameters, fetch will return a 0, 1, or 2, representing OFF, ON and DEFAULT respectively.

fax rmvpolled OFF | ON

Determines whether files set for polling are removed after they’re successfully transmitted. This command corresponds to the Remove from polling list once polled check box in the Files for Polling by a Fax Caller dialog, which is available from the Fax | Select Files for Polling... menu in Fax Status. fetch returns 0 for OFF or 1 for ON.

fax scheduled RESUME | HOLD

Determines whether Procomm Plus will send or hold all faxes. This command corresponds to the Hold/Resume all Scheduled faxes menu item on the Fax menu in Fax Status. fetch will return a 0 if all faxes are being sent or a 1 if faxes are on HOLD.

fax sendpolled OFF | ON | AUTO

Determines whether faxes in the polling list are sent when Procomm Plus is polled by a remote fax system. This command corresponds to the Send Faxes When Polled radio buttons in the Files for Polling by a Fax Caller dialog, available from the Fax | Files for Polling... menu in Fax Status. fetch returns 0 for OFF, 1 for ON or 2 for AUTO.

fax showfaxstatus {SEND | RECEIVE} {BEGIN | COMPLETE} {OFF | ON}

Determines when Fax Status should be brought to the foreground. This command corresponds to the Fax Receive begins, Fax Receive is complete, Fax Send begins, and Fax Send is complete check boxes available in the Setup, Fax, Fax Options dialog.

fax stationid string

Specifies the station id displayed on fax cover sheets and fax document headers. This command corresponds to the Station ID edit field in the Setup, Fax, User Info, User Info dialog. fetch returns the contents of the Station ID field in a string.

fax username string

Specifies the user name displayed on fax cover sheets and fax document headers. This command corresponds to the Name edit field in the Setup, Fax, User Info, User Info dialog. fetch returns the contents of the Name field in a string.

fax voicenumber string

Specifies the voice number displayed on fax cover sheets fax document headers. This command corresponds to the Voice number edit field in Setup, Fax, User Info, User Info. fetch returns the contents of the Voice number field in a string.

fax xmitbaud long

Specifies the maximum baud rate used to send faxes. This command corresponds to the Maximum transmit rate field in the Setup, System, Modem Connection, Fax Settings, General dialog. fetch returns a long value reflecting the current maximum transmit rate. Possible values are 2400, 4800, 7200, 9600, 12000, or 14400.


FTP Set/Fetch Statements

  Related Topics

The following set/fetch commands control FTP settings within Procomm Plus. They correspond to options in the Internet, FTP Options dialog in Setup.

ftp alarm OFF | ON

Determines whether or not Procomm Plus sounds the alarm when a transfer is complete. This command corresponds to the Sound alarm at end of transfer check box in the Setup, Internet, FTP Options, Transfer Options dialog. fetch will return a 0 if the check box is unchecked or a 1 if it is active.

ftp crashrecover OFF | ON

Determines whether or not to allow crash recovery on aborted downloads while in FTP mode. This command corresponds to the Allow file transfer crash recovery check box in the Setup, Internet, FTP Options, Transfer Options dialog. fetch returns a 0 if the check box is unchecked, or a 1 if it is active.

ftp dblclick fileview | filexfer

Determines the action Procomm Plus takes when you double click on a filename in FTP mode. This command corresponds to the Double Click on File Name radio group in the Setup, Internet, FTP Options, General Options dialog. fetch will return a 0 if To view file is selected or a 1 if To transfer file is selected.

ftp filter local | remote filename

Determines what file types appear in the directories on both the local and the remote machine. This command corresponds to the Default File Filters groupbox in the Setup, Internet, FTP Options, Folder Options dialog. fetch will return a string containing the filter for either the local or remote machine depending on which parameter you use.

ftp localdir pathname

Determines which directory is displayed by default when FTP mode is started. This command corresponds to the Initial local directory field in the Setup, Internet, FTP Options, Folder Options dialog. fetch will return a string containing the currently specified path.

ftp options index | string

Specifies the active FTP options set, corresponding to the Current FTP Options in Setup, Internet, FTP Options. Either the zero-based index or the name of an option set as it appears in the Current FTP Options list may be used. fetch returns the contents of the Current FTP Options field in a string.

If the set dialentry access command has been used to specify a FTP-class Connection Directory entry, set/fetch ftp options only affects that entry.

ftp passivemode OFF | ON | CURRENT

Specifies whether or not to use passive mode. This command corresponds to the Use passive mode (for local firewall) check box in the Setup, Internet, FTP Options, General Options dialog. fetch returns a 0 is the check box is unchecked, or a 1 if it is active.

If the set dialentry access command has been used to specify a FTP-class Connection Directory entry, set/fetch ftp passivemode only affects that entry. CURRENT specifies the current Setup setting, and is only valid for a Connection Directory entry.

ftp password string

Specifies the password to use with an anonymous logon. This command corresponds to the Anonymous logon password: field in the Setup, Internet, FTP Options, General Options dialog. fetch returns the contents of the password in a string.

ftp prompt overwrite | longfilename OFF | ON

Specifies whether or not Procomm Plus will prompt you before converting long filenames or overwriting existing files. This command corresponds to the Confirm overwriting existing files and Prompt for long file name conversion check boxes in the Setup, Internet, FTP Options, Folder Options dialog. For each of the check boxes, fetch will return a 0 if the check box is unchecked, or a 1 if it is active.

ftp retainfiles OFF | ON

Determines whether or not to save files that you have viewed in FTP mode. This command corresponds to the Retain viewed files check box in the Setup, Internet, FTP Options, Folder Options dialog. fetch returns a 0 if the check box is unchecked, or a 1 if it is active.

ftp viewgif OFF | ON

Determines if Procomm Plus will automatically display GIF images as they are downloaded while in FTP mode. This command corresponds to the View GIF file while receiving check box in the Setup, Internet, FTP Options, Transfer Options dialog. fetch returns a 0 if the check box is unchecked or a 1 if it is active.

ftp xfermode BINARY | ASCII | L8 | CURRENT

Specifies the file transfer mode used by Procomm Plus when in FTP mode. This command corresponds to the File transfer mode option button group in the Setup, Internet, FTP Options, Transfer Options dialog. fetch returns a 0 if Binary is selected, a 1 if ASCII is selected, or a 2 if L8 is selected.

If the set dialentry access command has been used to specify a FTP-class Connection Directory entry, set/fetch ftp xfermode only affects that entry. CURRENT specifies the current Setup setting, and is only valid for a Connection Directory entry.


Fax Commands

faxcancel	Cancels the current fax operation.

faxlist	Enumerates the faxes displayed in the received or scheduled fax lists.

faxmodem	Determines if a modem is fax capable.

faxpoll	Dials a Connection Directory entry or group, or a specified number to receive faxes from a host.

faxprint	Prints a specified fax file.

faxremove	Removes a fax file from the received or scheduled fax list.

faxsend	Dials the specified number, Connection Directory entry or group and transmits a specified fax file.

faxstatus	Queries the status of a specific fax connection.

faxview	Displays a fax file.

 Return to category list


File I/O Commands

fclear	Clears all end-of-file and error flags associated with the specified file id.

fclose	Closes the file corresponding to the specified file id.

fdelblock	Deletes a block of data from the specified file.

feof	Tests for end-of-file condition on the specified file id.

ferror	Tests for any error condition of the specified file id.

fflush	Writes the current I/O buffer contents to the specified file id.

fgetc	Reads a character from the specified file id into a variable.

fgets	Reads a string from the specified file id into a variable.

finsblock	Inserts a block of space into the specified file id.

flength	Returns the file size of an open file.

fopen	Opens a file in the indicated mode and assigns it to a file id.

fputc	Writes a character value to the specified file id.

fputs	Writes a string to the specified file id.

fread	Reads a block of data from a file into a variable and returns the number of bytes read.

fseek	Repositions the file pointer for the specified file id.

fstrfmt	Similar to strfmt, this command writes a formatted string to the specified file id.

ftell	Returns the current file pointer position for the specified file id.

ftruncate	Truncates or clips the file corresponding to the specified file id at the current file position.

fwrite	Writes a block of data to a file.

rewind	Repositions the file pointer of the specified file id to the beginning of the file.

 Return to category list


File Transfer Commands

ftp	Allows file manipulation on either host or local FTP machines.

getfile	Receives or downloads a file from a remote computer using the specified transfer protocol.

kermserve	Issues a Kermit server command.

sendfile	Sends or uploads a file to a remote computer using the specified transfer protocol.

xfercancel	Cancels a current file transfer operation.

 Return to category list


Formatting Text and Data

  Related Topics

The format string, formatstr, consists of zero or more characters of literal text with zero or more format specifiers. For example, in the statement:

strfmt s0 "This is literal text."

the formatstr "This is literal text." performs no special formatting at all. It merely assigns the quoted string, "This is literal text." to the predefinied global variable S0.

However, the formatstr may also contain an assortment of format specifiers that correspond with optional variables or constants (parameters) following the format string. Format specifiers and their corresponding parameters are processed from left to right. A format specifier is constructed as follows:

%[flags][width][precision]type

where:

%	Indicates that this is the beginning of a format specifier, rather than normal text. Characters following this special marker describe the format for displaying the corresponding param. If the % sign is followed by a character that has no special meaning as a format specifier, then that character and any subsequent characters until the next % are simply displayed as normal text. To display a percent sign, use "%%".

flags	Valid flags are "-", "+", " " (a space), and "#". These flags are optional.

"-"	Left-justifies the converted parameter within the number of places indicated in the width field. Without this optional flag, the displayed text is right justified.

"+"	Prefixes the converted parameter with a plus or minus sign, if it represents a signed type. Without this flag, the text will be displayed with a sign only if it represents a negative number.

" "	A space immediately after the % marker prefixes the converted parameter with a space if it represents a signed positive value; the space is ignored if both the blank and "+" flags appear.

"#"	Prefixes the converted parameter with the characters "0x" if it represents a hexadecimal value or with "0" if it represents an octal value. In addition, the # flag can be used to force a decimal point for all float conversions even if there is no fractional portion. This flag is ignored if used with any format types other than x, X, o, f, e, E, g, or G. For example:

integer nm1 = 16
float nm2 = 16
strfmt s0 "%+d" nm1	; formats as "+16"
strfmt s0 "% d" nm1	; formats as " 16"
strfmt s0 "%#x" nm1	; formats as "0x10"
strfmt s0 "%#f" nm2	; formats as "16."
width	This optional value specifies the minimum number of characters that will be generated for the conversion from the corresponding parameter. If the width value is greater than the number of characters in the converted text, it will be padded on the left with spaces, unless this has been altered by one of the flags. A 0 immediately preceding the width field pads the converted text with leading zeros after any sign or prefix, as long as no other padding has been specified. Note that since the width field specifies the minimum number of generated characters, it will never cause a value to be truncated. For example:

integer nm1 = 16
strfmt s0 "%d" nm1	; formats as "16"
strfmt s0 "%05d" nm1	; formats as "00016"
strfmt s0 "%-5d" nm1	; formats as "16   "
precision	This optional value must always be preceded by a period (.). It specifies the minimum number of digits to display when converting an integer param to displayed text, the number of decimal places to display on a float conversion using the e, E , or f types, the maximum number of significant digits to display on a g or G conversion or the maximum number of characters to display on a string conversion using the s type. The default precision for floating point values may be specified using the set aspect decimal statement.

Since precision specifies the maximum number of digits, it may cause truncation of strings or rounding of floats. For example:

string str1 = "This is a string"
float nm1 = 1234.567
strfmt s0 "%7.4s" str1	; formats as " This"
strfmt s0 "%-*.*f" 8 1 nm1	; formats as "1234.5 "
The width and/or precision fields may be an asterisk (*), which means that the value is supplied from the parameter list following the format string. In this case, the extra parameter would be an integer type preceding the parameter to be converted.

type	This specifier determines the data type required of the corresponding parameter, if any, and how the strfmt command will alter the parameter’s value before converting it to displayed text. Please note that the following type specifiers are case sensitive; lower case types must be entered in lower case and upper case specifiers must be entered in upper case!

d or i	The parameter is converted to signed decimal notation.

u	The parameter is output as an unsigned decimal number.

o	The parameter is output in octal notation.

x	The parameter is output in hexadecimal notation using the characters 0-9 and a-f.

X	The parameter is output in hexadecimal notation using the characters 0-9 and A-F.

l	A lower case "L" may be used before the d, i, o,x, or X format specifiers to specify that the corresponding argument is a long value.

f	The parameter is output in the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits displayed after the decimal point is determined by the precision specification. The default precision is 2. A minus sign is displayed if the value is less than zero, but a plus sign is displayed only if called for with the "+" flag.

e	The parameter is output in the form [-]d.dddd e sign ddd, where d is a decimal digit, dddd is one or more decimal digits, ddd is three decimal digits, and the sign is "+" or "-" (scientific notation).

E	Similar to "e", above, except that this type uses a capital E instead of lower case "e" to prefix the exponent.

g	The parameter is output in f or e format, as appropriate. If the e conversion would yield an exponent greater than -4 or less than the specified precision, the parameter value is output in f format instead. The generated text has no trailing zeros after the decimal point and includes a decimal point only if the result is not a whole number or if you specify the "#" flag.

G	Same as g above, except the E output format is used instead of the e format.

c	The integer parameter is output as a single ASCII character.

s	The string parameter is displayed up to the first null character or until the precision value is reached. For example:

integer num1 = 20, num2 = 30
string string1 = "This is a string"
float float1 = 1234.567
strfmt "Print %d and %d" num1 num2	; formats as "Print 20 and 30"
strfmt "To %d and %#X" num1 num2	; formats as "To 20 and 0X1E"
strfmt "%7.4s" string1	; formats as " This"
strfmt "%-8.1f" num1	; formats as "1234.5 "


Functions

  Related Topics

ASPECT supports user-defined functions as well as procedures. Functions and procedures are almost identical. They are isolated pieces of code that perform specific operations, sometimes changing the value of data that is passed to them. Unlike procedures however, functions return values. For instance, a function can return the square of a number:

integer Num = 2

Num = Square(Num)     ; Assuming the user-defined function

                      ; "Square" works to square an integer,

                      ; it returns the value 4, so Num now has

                      ; the value 4.

As you can see, you don’t need to explicitly call and pass parameters to a function using the call ... with statement. Instead, a list of parameters may be passed to a function inside of parentheses.

This is true of procedures as well, as we’ll see in the next section.

Functions not only behave differently, they also look different from procedures. They start with the keyword func rather than proc and, as you may suspect, they end with an endfunc rather than an endproc. Also, the first line of a function must declare the type of value it returns. Here’s the square function we referred to earlier:

func Square : integer      ; The function returns an integer value.

param integer Number       ; Variable for value passed to Square.

   return Number * Number  ; Return the new value of number.

endfunc                    ; End of function Square.

And here’s a script that includes a function to add a carriage return to a string:

;****************** MAIN PROCEDURE *******************

proc main

   string FirstName = "Ebenezer"   ; Declare string for first name.

   FirstName = AddCR(FirstName)    ; Get "Ebenezer^M" from AddCR.

   waitfor "Name: "                ; Now you can wait for prompt

   transmit FirstName              ; and send string out.

endproc

;****************** ADDCR FUNCTION ******************

func AddCR : string                ; Must include return type!

param string szText                ; Define variable "szText"

                                   ; for passed string.

   strcat szText "^M"              ; Add a CR to received string

   return szText                   ; and return it to calling proc.

endfunc

This AddCR function is general enough that you can use it in a variety of situations, so you may wish to add it to a "library" file of commonly-used procedures and functions that can be #included in your other scripts.

To create a library or #include file, simply open a new text file, and enter the functions, procedures, macros or declarations you want it to contain. Save the file to the directory containing the source files that will use the #include file. Any file name and extension can be used for an #include file; .inc is the most common extension, however.

Let’s say that you are working on a bulleten board logon script called callbbs.was. At the beginning of the script, before any procedures, insert the line:

#include "library.inc"

Now you can use the AddCR function in your callbbs.was file even though the function itself is in library.inc! You can include library.inc in any script you want to write.

There are two important considerations to keep in mind when working with functions:

•	Functions are always user-defined. There are no ASPECT commands that can be called in the manner that functions are called.

•	Functions may be used in command expressions anywhere that a constant value can be used, including arguments to other procedures and functions.

For example, the line:

Answer = Num + Square(Num)	; OK to use functions in expressions.

and

transmit AddCr(Name)	;OK to use function as argument

are perfectly acceptable, but the following line is not:

strcat AddCR(Name) "^L"	; WRONG!

The third line doesn’t work because the ASPECT strcat command expects a string variable as the first parameter, but functions can only be used where constants are allowed.

Exercises

Write a script that prompts you for an input string, adds an exclamation point to the string and displays it.

Use the sdlginput command to get the string, and the usermsg command to display it.

Write a script that prompts you for two numbers, adds them, and returns the result. Display the result using usermsg with the "%d" format string.

Advanced exercise

Write a function that prompts for a string and reverses the contents of the string.

You may find the strrev command helpful!


General Procomm Plus Commands

alarm	Sounds an alarm to signal an event.

beep	Sounds a beep tone.

capture	Controls session capture during script file execution.

capturestr	Writes a specified string to an open Capture file.

crc16	Generates a CRC integer value for a specified string.

decrypt	Decodes an encrypted string.

encrypt	Encodes a target string.

errormsg	Displays a message box with a graphic and specified text.

fetch	Returns the current value(s) of any set command parameter.

help	Displays on-line Help.

mapisend	Allows the user to send mail whenever the MAPI interface is loaded and accessible.

metakey	Executes the specified Meta Key.

mspause	Pauses script execution for the specified number of milliseconds.

pause	Halts script execution for the specified number of seconds.

playback	Plays back a Capture file or stops a playback currently in progress.

pwexit	Terminates the executing script file, disconnects and then exits Procomm Plus.

pwmode	Places Procomm Plus into one of six execution modes.

pwtitlebar	Specifies the text to display in the Procomm Plus program title bar.

sdlgfopen	Displays a standard file open dialog.

sdlginput	Displays a standard dialog box, allowing the user to enter a single line of text.

sdlgmsgbox	Displays a standard message box with a specified icon and button.

sdlgsaveas	Displays a standard file save as dialog box.

set	Changes system parameters which control various operations within Procomm Plus and ASPECT.

setpointer	Moves the mouse pointer to the specified X/Y screen coordinates.

setup	Manipulates the Procomm Plus Setup utility.

statclear	Clears the status line in the Terminal window.

statmsg	Displays a formatted message on the status line in the Terminal window.

usermsg	Displays a message string in a dialog.

waituntil	Pauses script processing until the specified date and/or time.

when	Forces a procedure or function call when a particular event occurs.

xlatin	Converts a character or string using the incoming Translate Table values.

xlatout	Converts a character or string using the outgoing Translate Table values.

xlatstr	Performs caret translation on a string.

wizard	Activates a Procomm Plus wizard.

 Return to category list


General Set/Fetch Statements

  Related Topics

actionbar {TOP | BOTTOM | LEFT | RIGHT | FLOAT} {filename | NONE | CURRENT} [PERMANENT [GLOBAL]]

Specifies the Action Bar file that’s displayed for top, bottom, left, right, and float Action Bars in the Terminal window.

The PERMANENT keyword sets the specified ActionBar as the default for the current mode. If the PERMANENT keyword is not used, the previously specified ActionBar will be loaded when you next switch to this mode. The GLOBAL keyword indicates that the specified ActionBar should be used for all modes.

fetch returns a string containing the specified Action Bar filename and an integer set to 1 if the ActionBar is global or 0 if it is not.

The CURRENT keyword is only valid when the script is modifying a Data- or Telnet-class Connection Directory entry targeted with the set dialentry access command.

alarm OFF | ON

Enables or disables the alarm sound. This command corresponds to the Sound Alarm... check box in the Setup, System, System Options dialog. It has no effect on the ASPECT alarm command. fetch returns 0 for OFF or 1 for ON.

alarmtime integer

Specifies the number of seconds Procomm Plus sounds an alarm to signal the end of file transfers and dialing connections. The default is 2 seconds, and valid values range from 0 to 99. This command corresponds to the Sound alarm for x seconds field in the Setup, System, System Options. fetch returns the current number of seconds that the alarm sounds.

ASPECT... -see ASPECT Set/Fetch Statements.

autodnld OFF | ON

Enables or disables auto-downloading for Zmodem and Kermit protocols. This command corresponds to the Enable automatic download start for Zmodem and Kermit check box in the Setup, Data, Data Options, Advanced dialog. fetch returns 0 for OFF or 1 for ON.

Control auto-downloading for the CIS-B+ protocol with the set terminal enquiry command.

breaklen integer

Specifies the amount of time that Procomm Plus issues a break signal when the break command is used. Values range from 0 to 9999 in tenths of a second. This command corresponds to the Break Length edit field in the Setup, Data, Data Options, Advanced dialog. fetch returns the break length for the current connection.

callerid OFF | ON

Enables or disables Caller ID use throughout Procomm Plus. This command corresponds to the Use Caller ID check box in Setup, System, System Options. fetch returns 0 for OFF or 1 for ON.

callerid addcallinfo OFF | ON

Enables or disables Procomm Plus’s ability to add caller information to the current database. This command corresponds to the Add incoming calls to Caller Information Directory: check box in Setup, System, System Options. fetch returns 0 for OFF or 1 for ON.

callerid database filename

Specifies the Caller ID database file to use for Caller Information logging, and Global Screening. This command corresponds to the Add incoming calls to Caller Information Directory: list box in the Setup, System, System Options dialog. Fetch returns a string containing the filename.

CAPTURE... see CAPTURE Set/Fetch Statements.

cdinxfer OFF| ON

Determines whether Procomm Plus aborts file transfers when carrier is lost. This command corresponds to the Abort transfer if Carrier Detect signal lost check box in the Setup, Data, Data Options, Advanced dialog. fetch returns 0 for OFF or 1 for ON.

chatmode BLOCK | CHARACTER [CR_LF]

Specifies BLOCK or CHARACTER transmission of data in the Terminal window’s Chat. This command corresponds to the Chat Mode transmit method: list in the Setup, Data, Data Options, General dialog. fetch chatmode requires two intvar arguments, returning 0 for BLOCK or 1 for CHARACTER in the first argument and 0 for no CR_LF or 1 for CR_LF in the second argument.

clipchar character

Specifies the separator character for filenames sent from the File Clipboard. The character value must be an integer (in octal, decimal, or hexadecimal notation) which corresponds to the ASCII value of one of the characters described in the File Clipboard separator list in the Setup, Data, Data Options, General dialog. fetch returns an integer equal to the ASCII value of the current separator character.

clipfilermv OFF | ON

Determines whether filenames are removed from the File Clipboard after they’re sent to a remote system. This command corresponds to the Remove when sent check box in the File Clipboard dialog. fetch returns 0 for OFF or 1 for ON.

connection logging OFF | ON

Determines whether Procomm Plus records data, fax, and voice connections. This command corresponds to the Connection logging check box in the Setup, System, System Options dialog. fetch returns 0 for OFF or 1 for ON.

connection statmsg OFF | ON

Determines whether status line messages related to the current connection are written to the connection log. This command corresponds to the Write status line messages to Connection Log check box in the Setup, System, System Options dialog. fetch returns 0 for OFF or 1 for ON.

This option only controls status line messages related to the current connection. If connection logging is off, this command has no effect.

DIAL... - see Dial Set/Fetch Statements

DIALENTRY... - see DIALENTRY Set/Fetch Statements

dnldpath pathname

Specifies the default path for received or downloaded files. This command corresponds to the Download path: field in the Setup, Data, Data Options, Paths dialog. fetch returns the contents of the field in a string.

dnldprompt OFF | ON

Enables or disables the display of the Change File Transfer Protocol dialog when a download is manually initiated. This command corresponds to the Prompt for download protocol before starting transfer check box in Setup, Data, Data Options, Advanced. fetch returns 0 for OFF or 1 for ON.

duplex FULL | HALF

Switches the duplex setting between full duplex and half duplex. In full duplex, data is not displayed to the screen as it is sent. In half duplex, Procomm Plus displays characters as they are sent. This command corresponds to the Duplex menu item on the Terminal window Data menu. fetch returns 0 for FULL or 1 for HALF.

editor filespec

Specifies the program to run when the Edit or New button is selected in the Compile/Edit ASPECT File dialog. The default is PWEDIT.EXE, the Aspect Editor. This command corresponds to the Editor name & path field in the Setup, System, System Options. fetch returns the contents of the field in a string.

EMULATION...

The basic terminal commands are listed in Terminal Set/Fetch Statements.Some terminal emulations have advanced command groups - advanced commands are listed in Advanced Emulation Commands Set/Fetch Statements.

FAX... - see FAX Set/Fetch Statements.

FTP... - see FTP Set/Fetch Statements

iconflash OFF | ON

Iconflash determines whether the Procomm Plus icon flashes when a file transfer is completed and Procomm Plus is minimized. This command corresponds to the Flash icon when transfer complete check box in the Setup, System, Data Options, Advanced dialog. fetch returns 0 for OFF or 1 for ON.

largeabars OFF | ON

Determines whether Procomm Plus will use large or small Action Bar icons. This command corresponds to the View | Large Action Bar menu item. fetch returns 0 for OFF or 1 for ON.

INTERNET... see INTERNET Set/Fetch Statements.

lmouse dblclick WORD | CHARACTER [CR]

Determines the action taken when the left mouse button is double clicked. This command corresponds to the Left button double click transmits: list in the Setup, Data, Data Options, Left Mouse dialog. fetch requires two intvar arguments, returning 0 for WORD or 1 for CHARACTER in the first argument and 1 in the second argument if the word or character is to be followed by a Carriage Return.

lmouse eolchar ENTERKEY | EOLSTR

Specifies whether an emulation Enter key press or a configurable string is sent after the word or character selected from the Terminal window by a Left mouse button double click, when the Left button double click field is set to send a Carriage Return. This command corresponds to the End of line character(s) option button in the Setup, Data, Data Options, Left Mouse dialog. fetch returns 0 for ENTERKEY or 1 for EOLSTR.

lmouse eolstr string

Specifies the text that is sent when End of line character(s) is not set to Enter key in the Setup, Data, Data Options, Left Mouse Options dialog. This command corresponds to the End of line character(s) edit field in the Setup, Data, Data Options, Left Mouse dialog. fetch returns a string containing the current value of the edit field.  The end of line string has a maximum length of 7 characters.

lmouse prefix string

Determines the text that precedes information selected from the Terminal window or the Scrollback Buffer when that information is pasted. This command corresponds to the Selection paste prefix edit field in the Setup, Data, Data Options, Left Mouse dialog. fetch returns the current value of the edit field in a string.  The prefix string has a maximum length of 7 characters.

longfilename OFF | ON

Determines whether the File Clipboard supports filenames that don’t adhere to the 12-character DOS file-naming standard. This command corresponds to the Long filename support for File Clipboard check box in the Setup, Data, Data Options, General dialog. fetch returns 0 for OFF or 1 for ON.

MAIL... - See Mail Set/Fetch Statements

metakeyfile filename | NONE | CURRENT

Loads the Meta Key file specified in the filename argument, which may or may not include a .key extension. This command can be tested with the if SUCCESS statement, returning false if the specified file cannot be loaded. This command corresponds to the Meta Keys list in the Setup, Data, Setup Files dialog. fetch returns the name of the currently-loaded Meta Key file in a string, or a null string if no file is currently loaded.

If the set dialentry access command has been used to specify a Data- or Telnet-class Connection Directory entry, set/fetch metakeyfile only affects that entry. Under this circumstance, set metakeyfile NONE selects the NONE value for that entry’s Meta Key field. Use the CURRENT keyword to use the Meta Key file specified in the current Setup.

metakeys OFF | ON

Enables or disables the Meta Key display on the Terminal window. This command corresponds to the Meta Keys item on the View menu. fetch returns 0 for OFF or 1 for ON.

misc string

Specifies the miscellaneous string for a Data-, Telnet-, or  FTP- class Connection Directory entry. This command corresponds to the Misc field in a Connection Directory entry’s Logon Info dialog. fetch returns a string containing the Misc field contents of the currently-selected Connection Directory entry. Use the set dialentry access command to set the current Connection Directory entry.

Misc fields may also be read using the $MISC system variable. The maximum length of the Misc field is 40 characters.

MODEM... - See MODEM Set/Fetch Statements.

NEWS... - See NEWS Set/Fetch Statements

notesfile filename | NONE | CURRENT

Specifies a default Notes file for Setup or for the current Connection Directory entry. If a current Connection Directory entry is selected with the set dialentry access command, this command affects that entry. If an entry is not targeted, this command affects the Notes File: list in the Setup, System, System Options dialog. fetch returns a string containing the name of the Notes file. The CURRENT keyword is valid only when setting the Notes file for a Connection Directory entry.

notespath pathname

Specifies the default path for Notes files. This command corresponds to the Notes path field in Setup, Data, Data Options, Paths. fetch returns the default path in a string.

password string

Specifies the password string for a Data-, Telnet-, or FTP- class Connection Directory entry. This command corresponds to the Password field in a Connection Directory entry’s Logon Info dialog. The current Connection Directory entry can be specified by using the set dialentry access command. fetch returns the contents of the Password field in the current Connection Directory entry in a string. Password fields can also be read with the $PASSWORD system variable.

pausechar character

Identifies the character Procomm Plus translates into a half-second pause within modem commands and strings sent to the modem with Aspect commands. The default character is a tilde (~), but any value from 32 to 126 is valid. This command corresponds to the Pause character field in the Setup, System, System Options dialog. fetch returns the numerical value of the current pause character as an integer.

playbackpace integer

Determines the speed at which information from a playback or capture file is displayed in the Terminal window. Valid values range from 0 to 6, 0 being slow and 6 being fast. This command corresponds to the File Playback Speed horizontal scroll bar in the Setup, Data, Data Options, General dialog. fetch returns the current playback speed as an integer.

PORT... - See PORT Set/Fetch Statements

PRINT... - See PRINT Set/Fetch Statements

protocol protocol | index | string

Specifies a default protocol for file transfers. You may either supply the name of the protocol as a keyword, give the zero-based index of the protocol within the Current Transfer Protocol list box in the Setup, Data, Transfer Protocol dialog, or provide a string containing the name of the protocol. fetch returns the name of the current default file transfer protocol in a string.

If you have used the set dialentry access command to a select a specific Data- or Telnet-class Connection Directory entry, the set protocol command affects that entry instead of Setup.

For a complete list of protocol names and indices, see Protocol Names and Indices.

PROTOCOL...

General commands regarding all of the protocols, in addition to each protocol's related command group, are listed in PROTOCOL-related Set/Fetch Statements.

quickoption index index

Specifies the information displayed in the selectable fields on the Quick Select Line. index is an integer value of 1, 2 or 3, corresponding to the first, second or third selectable field. Values of 1 to 7 are allowed for the second index. fetch returns values from 1 to 7, corresponding to Modem Lights, Terminal Row/Column, Download Disk Space, Free Memory, Rx and Tx Buffer graph, Real-Time Clock and Current Aspect script, respectively for the specified selectable field.

This command is only available in Data and Telnet modes.

quickselect OFF | ON

Determines whether the Quick Select Line is displayed on the Terminal window. This command corresponds to the View | Quick Select Line menu item. fetch returns 0 for OFF or 1 for ON.

This command is only available in Data mode.

remotecmd OFF | ON [password]

Determines whether Procomm Plus responds to Aspect commands sent from remote computers. password is an optional string constant or variable that you may use to configure the Remote command password, which restricts the use of remote script commands by users dialing in to your system. This command corresponds to the Remote script commands... check box in Setup, System, System Options. fetch returns 0 for OFF or 1 for ON.

For security reasons, fetch will not return the value of the Remote script commands Password.

rmouse action NONE | MENU | CURSORPOS

Determines the action of a right button click. This command corresponds to the Right mouse button action: list in the Setup, Data, Data Options, Right Mouse dialog. fetch returns 0 for NONE, 1 for MENU or 2 for CURSORPOS.

rmouse item index NONE | CURSORPOS | pw_menu_id

Determines the options that are available on the menu displayed when the right mouse button is clicked. Index is a number from 1 to 10 corresponding to each item in the right mouse button menu. Pw_menu_id is the id of the item in the Procomm Plus main menu that you want to add to the right mouse button menu. This command corresponds to the ‘1’ through ‘10’ lists in the Setup, Data, Data Options, Right Mouse dialog. fetch returns 0 for NONE, 1 for CURSORPOS or the id of the Procomm Plus main menu item corresponding to the specified index.

The Procomm Plus menu ids are defined in pw4menu.inc, which is installed by default in the ASPECT directory.

scriptpath pathname

Specifies the path Procomm Plus searches for Aspect script files. This command corresponds to the Script path: field in the Setup, Data, Data Options, Paths dialog. fetch returns the current Aspect script path in a string.

statusline OFF | ON

Determines whether the status line is displayed at the bottom of the Terminal window. This command corresponds to the Status Line item on the Setup menu. fetch returns 0 for OFF or 1 for ON.

This command is only available in Data mode.

TELNET... -see TELNET Set/Fetch Statements

TERMINAL... - see TERMINAL Set/Fetch Statements.

tooltips OFF | ON

Determines whether help labels appear below the Action Bar icons when the mouse pointer is positioned over them. This command corresponds to the View | ToolTips menu item. fetch returns 0 for OFF or 1 for ON.

translate filename | NONE | CURRENT

Specifies the default Translate Table in Setup or the Translate Table to use for a Data- or Telnet-class Connection Directory entry. If used in conjunction with the set dialentry access command, this command affects the Translate Table: list in the current Connection Directory entry’s Advanced Options dialog. The default extension is .xlt, but it need not be specified. The CURRENT keyword causes a Connection Directory entry to use the Translate Table specified in Setup.

If set dialentry access has not been specified, this command affects the Translate Table: list in the Setup, Data, Setup Files dialog. fetch returns a string containing the name of the current Translate Table.

txpace integer

Determines the length of pauses between transmitted characters. This command corresponds to the Transmit pacing (ms): field in the Setup, System, System Options dialog. Valid values range from 0 to 999, in milliseconds. fetch returns an integer equal to the current transmit pacing value.

upldpath pathname

Specifies the default path for upload files. This command corresponds to the Upload path: field in the Setup, Data, Data Options, Paths dialog. fetch returns the current default upload path in a string.

userid string

Specifies the contents of the User ID edit field in a Data-, Telnet-, or FTP- class Connection Directory entry. The maximum length for the User ID string is 40 characters. fetch returns the contents of the User ID field from the current Connection Directory entry's Logon Info dialog in a string. The $USERID system variable may also be used to read the contents of this field.

The set dialentry access command can be used to specify the desired Connection Directory entry.

viewgif OFF | ON

Determines .gif graphics are displayed as they are downloaded. This command corresponds to the View .GIF files during download check box in the Setup, Data, Data Options, Advanced dialog. fetch returns 0 for OFF or 1 for ON.

wavefile index filespec

Specifies the name of a wave file to play when a specific event occurs. Index is a number from 1 to 9, specifying the event wave file to set. fetch returns the name of the wave file corresponding to the specified index in a string. The indexes and their corresponding Setup fields include:

1	File transfer complete field in Setup, Data, Data Options, General dialog
2	File transfer abort field in Setup, Data, Data Options, General dialog
3	Connect field in Setup, Data, Data Options, General dialog
4	Disconnect field in Setup, Data, Data Options, General dialog
5	Fax receive complete field in Setup, Fax, Fax Options dialog
6	Fax send complete field in Setup, Fax, Fax Options dialog
7	Fax send/receive failure field in Setup, Fax, Fax Options dialog
8	Calling queue complete field in Setup, System, System Options dialog
9	Miscellaneus errors field in Setup, System, System Options dialog
wincolors index | string

Specifies the Current Window Colors options set. Index is a zero-based value, corresponding to the option set entry of the desired Current Window Colors options set. String is the name of the desired Current Window Colors options set. This command corresponds to the Current Window Colors: field in the Setup, Data, Window Colors dialog. fetch returns the name of the Current Window Colors options set in a string.

xferyield integer

Determines how much processor time Procomm Plus gives to other applications while a file transfer is in progress. Valid values range from 0 to 17, 0 meaning that Procomm Plus will yield very little and 17 meaning that it will yield generously. This command corresponds to the Yield During File Transfer horizontal scroll bar in the Setup, Data, Data Options, Advanced dialog. fetch returns the current setting in an integer.


General Windows Commands

disable	Disables controls, dialogs, menu selections or windows.

dllcall	Calls a routine or process within a DLL module that was created to interact with ASPECT.

dllfree	Frees unneeded DLL memory resources.

dllload	Loads the specified DLL module into memory.

enable	Enables controls, dialogs, menu selections or windows.

exitwindows	Terminates all executing tasks and exits Windows.

mciexec	Executes a high-level multimedia command.

mcisend	Allows you to issue an MCI command and retrieve the error message or the result of the command.

profilerd	Reads a specified item value from any portion of a specified Windows .ini file.

profilewr	Writes a specified item value to any portion of a specified Windows .ini file.

screentowin	Converts X/Y coordinates into coordinates relative to the specified window id.

sendkey	Processes a keyboard shift state and a virtual key value and sends it to the focus window of the active application.

sendkeystr	Sends a specified string to the active window or dialog as if the user had sent it.

sendvkey	Processes an encoded key value and sends it to the focus window of the active application.

wintoscreen	Converts X/Y coordinates into absolute screen coordinates.

 Return to category list


Getting User Input

  Related Topics

Suppose you want to automate your logins with ASPECT, but for security reasons you don’t want the script to transmit your password automatically. ASPECT has many ways to prompt you for input with a "dialog box", the simplest of which is an input dialog box created with the sdlginput command. A standard dialog box customized for the input of a user password looks like this:

;*********************************************************************

; Main procedure.

; Calls: SendData.

; Called by:

; Modifies the value of the following globals:

;*********************************************************************

proc main

   string szPassword            ; Local variable for string user enters in input

                                ; box. Its value will then be passed to the

                                ; SendData routine.

   ; The following line creates the box for user input. The first string

   ; appears in the title bar of the box; the second is the prompt

   ; string that appears right before the text entry field itself; the

   ; variable at the end assumes the value of the string the user enters.

   sdlginput "Password Entry" "Enter your password:" szPassword

   waitfor "Password: "         ; Wait for password prompt.

   SendData( szPassword )

   ; Call the SendData routine with the value of the local

   ; string variable "szPassword". SendData adds a carriage return and

   ; sends user’s password out the port.

endproc

;*********************************************************************

; SendData procedure. Adds a carriage return to passed string and

; then transmits it.

; Calls:

; Called by: main.

; Modifies the value of the following globals:

;*********************************************************************

proc SendData

param string szText             ; Local variable to receive

                                ; value passed from another procedure.

   strcat szText "^M"           ; Strcat appends a string onto the end of

                                ; another. In this case we stick "^M"

                                ; onto the end of the password string

   transmit szText              ; and send the concatenation.

endproc

Exercise

Write a script that prompts you for your first name, your last name, and concatenates the two strings with the strcat command and displays your full name in a single message box. Be careful to divide your script into sensible procedures.

You may end up with procedures named something like GetFirstName and GetLastName. Don’t forget to embed a space between the first and last names!


Global Variables

  Related Topics

Global variables can be defined anywhere within a source program, but outside of any procedure or function block. Typically, they are defined at the top of a source program, before any procedures or functions are declared.

A global variable can be referenced within any procedure or function throughout the script. If a procedure or function changes the value of a global variable, that value is maintained until the variable is acted upon by another command anywhere else in the script. User-defined globals cannot be passed to another script by chaining or spawning; only the predefined Ix, Lx, Fx and Sx variables can pass information to another script.

For more information on predefined variables, see Predefined Variables. and Predefined Global Variables.

Global variable names must be unique. Attempting to define a global variable with the same name as a previously-existing global variable will result in a compile-time error message.


Global and Local Variables

  Related Topics

ASPECT supports the use of both global and local user-defined variables. The terms "global" and "local" refer to the "scope" of a variable. That is, whether a variable is visible to the ASPECT Compiler throughout a script’s source code, or only visible within a particular function or procedure block.

For more information, select one of the following topics:

Global Variables

Local Variables

Defining Variables


IBM3101 and IBM 3161 Set/Fetch Statements

emulation entercrlf OFF | ON

Specifies whether an Enter keypress generates the characters mapped to the return key in the keyboard mapping utility or a Carriage Return and Linefeed, ASCII 13 and ASCII 10 pair. This command corresponds to the Enter key sends CR/LF check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.

emulation nullsuppress OFF | ON

Determines whether processing of the NULL character, ASCII 0, is suppressed for the specified emulation. This command corresponds to the Null suppression check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.

emulation turnchar CR | EOT | ETX | XOFF

Determines the end of a line or block character for the specified emulation. If set to CR, a Carriage Return, ASCII 13, is appended to the end of a line or block when the send key is pressed. If set to EOT, an end of text character, ASCII 4, is appended. If set to ETX, an end transmission character, ASCII 3, is appended. If set to XOFF, a pause transmission character, ASCII 19, is appended. This command corresponds to the Turn-around character field in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for CR, 1 for EOT, 2 for ETX or 3 for XOFF.


IND$FILE Protocol Set/Fetch Statements

The following set and fetch commands correspond to the options found in Setup, Data, Transfer Protocol, with the Current Protocol field set to IND$FILE.

ind$file abortdnld KEEP | DELETE

Determines whether aborted Ind$file downloads are kept or deleted. This command corresponds to the Delete aborted downloads check box. fetch returns 0 for KEEP or 1 for DELETE.

ind$file asciixlat OFF | ON

Determines whether EBCDIC characters are translated into ASCII characters when a text file is downloaded using the Ind$file protocol. This command corresponds to the ASCII translate check box. fetch returns 0 for OFF or 1 for ON.

ind$file converter index string

Specifies protocol converter options for the Ind$file transfer protocol. Index corresponds to edit fields listed in the Protocol Converter Setup dialog (available within Setup, Data, Transfer Protocol, by clicking on Protocol Converter...) ranging from 0 to 9 for Enter, Reset, Refresh, Clear, PF1, PF2, Erase input, Erase EOF, File transfer on and File Transfer off, respectively. fetch returns the contents of the field specified by index in a string.

For example, if you want to change the sequence that represents Enter, use set ind$file converter 0 string, where string is the desired value.

It is important to note that these settings are only available with certain Environment: settings.

ind$file crlfxlat OFF | ON

Determines whether end-of-line characters are translated based upon the capabilities of the receiving system in an Ind$file file transfer. This command corresponds to the CR-LF translate check box. fetch returns 0 for OFF or 1 for ON.

ind$file display OFF | ON

Determines whether a text file is displayed as it is uploaded with the Ind$file protocol. This command corresponds to the Display data during transfer check box. fetch returns 0 for OFF or 1 for ON.

ind$file environment index

Specifies the protocol converter and terminal emulation combination used when transferring files. Index is a zero-based integer corresponding to an item listed in the Environment: list. fetch returns an integer equal to the current item’s index value.

ind$file host VM_CMS | MVS_TSO | OTHER

Specifies the host’s operating system. This command corresponds to the Host OS: list. fetch returns 0 for VM_CMS, 1 for MVS_TSO or 2 for OTHER.

ind$file lrecl integer

Specifies the logical record length for a file uploaded with the Ind$file protocol. This command corresponds to the LRECL edit field. Valid values range from 1 to 65535, treated as an unsigned integer. fetch returns an unsigned integer equal to the current logical record length. This field has no effect if Use LRECL: is not enabled.

ind$file overwrite OFF | ON

Determines how filename collisions are handled by the the Ind$file protocol. This command corresponds to the Overwrite existing file check box. fetch returns 0 for OFF or 1 for ON.

ind$file pacelines integer

Specifies the number of lines Procomm Plus will receive before pausing during an Ind$file file upload. This command corresponds to the Pace uploads: X Lines edit field. fetch returns an integer equal to the current number of pace lines. If Pace uploads: is not enabled, this command will have no effect.

ind$file recfm FIXED | VARIABLE

Specifies the record format used for storing files uploaded with the Ind$file protocol. This command corresponds to the Use RECFM edit field. fetch returns 0 for FIXED or 1 for VARIABLE. This field has no effect if Use RECFM: is not enabled.

ind$file recvcmd string

Specifies the command sent to the host system to initiate an Ind$file download. This command corresponds to the Receive command edit field. fetch returns the contents of the field in a string.

ind$file sendcmd string

Specifies the command sent to the host system to initiate an Ind$file upload. This command corresponds to the Send command edit field. fetch returns the contents of the field in a string.

ind$file timing RELAXED | NORMAL | TIGHT

Determines the Ind$file protocol’s sensitivity to timing problems. This command corresponds to the Timing: list. fetch returns 0 for RELAXED, 1 for NORMAL or 2 for TIGHT.

ind$file upldpace OFF | ON

Determines whether the Ind$file protocol pauses after sending lines from a text file. If ON is used, the upload pauses after sending the number of lines specified in the Pace uploads: X Lines edit field before resuming the transfer. This command corresponds to the Pace uploads: X Lines check box. fetch returns 0 for OFF or 1 for ON.

ind$file uselrecl OFF | ON

Determines whether files uploaded with the Ind$file protocol are sent using the logical record length specified in the Use LRECL: edit field. This command corresponds to the Use LRECL: check box. fetch returns 0 for OFF or 1 for ON.

ind$file userecfm OFF | ON

Determines whether files uploaded with the Ind$file protocol are sent using a specific record format. If ON, Ind$file uses the record format specified in the Use RECFM: edit field. This command corresponds to the Use RECFM: check box. fetch returns 0 for OFF or 1 for ON.


INTERNET Set/Fetch Statements

  Related Topics

The following set/fetch commands control the Internet connection within Procomm Plus. They correspond to options in the Internet Connection dialog in Setup.

With the exception of Internet Connection, these commands only affect the current option set specified in the Current Internet Connection list in the Setup, Internet, Internet Connection dialog.

internet connection string

Specifies the active Internet connection. The name of a connection in the Current Internet Connection list in Setup, Internet, Internet Connection dialog must be used.

fetch returns the contents of the Current Internet Connection field in a string variable.

This command, unlike the user interface, does not automatically set the Mail Options and News Options to match what is specified for the Internet Connection. If desired, you must manually set these options with the set mail options and set news options commands.

internet mail options index | string | CURRENT

Specifies the active mail options set, corresponding to the Current Mail Options in Setup, Internet, Internet Connection. Either the zero-based index or the name of an option set as it appears in the Current Mail Options list, or the keyword CURRENT may be used. fetch returns the contents of the Current Mail Options field in a string.

internet news options index | string | CURRENT

Specifies the active news options set, corresponding to the Current News Options in Setup, Internet, Internet Connection. Either the zero-based index or the name of an option set as it appears in the Current News Options list, or the keyword CURRENT may be used. fetch returns the contents of the Current News Options field in a string.


Internet Commands

connect	Calls one or more entries in your Connection Directory.

connectmanual	Connect to the specified telephone number.

disconnect	Disconnects the computer from the telephone line.

ftp	Allows file manipulation on either host or local FTP machines.

 Return to category list


Introduction to ASPECT

  Related Topics

The following topics introduce you to ASPECT and its possible applications. These topics discuss the new features of ASPECT for Procomm Plus, and you’ll learn more about editing, compiling, debugging and running scripts.

What Are Scripts?

Script Record Mode

Step-by-Step: Recording a Script

Creating and Editing Scripts

Running Scripts

Compiling Scripts

Debugging Options


KERMIT Protocol Set/Fetch Statements

The following set/fetch statements control the operation of the Kermit protocol. They correspond to options in Setup, Data, Transfer Protocol, with the Current Protocol field set to KERMIT.

kermit abortdnld KEEP | DELETE

Determines whether files that are aborted during Kermit downloads are kept or deleted. This command corresponds to the Delete aborted downloads check box. fetch returns 0 for KEEP or 1 for DELETE.

kermit bit8quote character

Specifies the character used to "quote" highbit ASCII characters during a Kermit transfers. Valid values range from 33 to 126. This command corresponds to the 8th bit quote field. fetch returns the ASCII value of the current 8th bit quote character.

kermit blockcheck integer

Specifies the type of error-detection used during a Kermit transfer. Valid values for integer are 1, 2 and 3. This command corresponds to the Block Check Type option button. fetch returns 1, 2 or 3, corresponding to 1 byte checksum, 2 byte checksum or 3 byte CRC, respectively.

kermit blockstart character

Specifies the start block character for a Kermit transfer. Most systems expect this value to be 1, CTRL-A, but acceptable values range from 0 to 127. This command corresponds to the Block start edit field. fetch returns the ASCII value of the current block start character.

kermit ctrlquote character

Specifies the character used to "quote" control characters during a Kermit transfer. Valid values range from 32 to 127. This command corresponds to the Control quote field. fetch returns the value of the current control quote character.

kermit eolchar character

Specifies the end of line character used during a Kermit transfer. Valid values range from 0 to 127. This command corresponds to the End of line field. fetch returns the value of the current end of line character.

kermit filetype BINARY | TEXT

Specifies the type of files being transferred with the Kermit protocol. This command corresponds to the File type option button. fetch returns 0 for BINARY or 1 for TEXT.

kermit overwrite OFF | ON

Determines how filename collisions are handled during a Kermit file transfer. This command corresponds to the Overwrite existing file check box. fetch returns 0 for OFF and 1 for ON.

kermit packetsize integer

Specifies the maximum size of data packets used in Kermit file transfers. Valid values range from 20 to 1024. This command corresponds to the Maximum packet size edit field. fetch returns the current maximum packet size.

kermit padchar character

Specifies the character used to pad empty data packets in a Kermit file transfer. Valid values range from 0 to 127. This command corresponds to the Pad edit field. fetch returns the value of the current pad character.

kermit padnum integer

Specifies the number of pad characters used to fill empty data packets in a Kermit file transfer. Valid values range from 0 to 127. This command corresponds to the Number of pad chars field. fetch returns the current number of pad characters.


Keyboard Commands

ansitokey	Converts an ANSI character to its corresponding virtual key code and shift state.

keyflush	Clears accumulated keystrokes from the keyboard buffer.

keyget	Receives a user-keypress and stores it in a integer variable if specified.

keystate	Determines whether a key corresponding to a virtual key code is pressed.

keytoansi	Converts a key value to its ANSI character value.

keytooem	Converts a key value to its OEM character value.

oemtokey	Converts an OEM character to its key value.

 Return to category list


Labels

  Related Topics

Labels use a special name format - they must end in a colon. A label may occur in a separate line preceding the destination, or it may precede a command on the same line. Labels are used only with the goto command word. Each goto statement specifies a label as a destination. Labels operate locally to their procedure or function blocks, so you may use the same name for another label in another procedure. For example:

proc ask1

label1:

sdlgmsgbox "Message" "This is shown to the user." \

INFORMATION OK

endproc

proc ask2

label1: sdlgmsgbox "Message" "And so is this." \

INFORMATION OK

endproc

Certain ASPECT commands are invalid as label jump locations, and may not be used as targets for a goto command. These commands include integer, float, long, string, param, case and .default. Labels are also invalid within dialogbox command groups.


Local Variables

  Related Topics

Local variables are defined with the same commands as globals. Unlike global variables, they can only be referenced within the procedure or function in which they’re defined. The same local variable name can be used in more than one procedure or function, but each occurrence is a completely different case and has no effect on any other occurrences.

Unlike global variables, local variables are discarded by ASPECT when the function or procedure in which they’re defined returns or terminates. Thus, local variable values are not retained between calls to the procedure or function in which they are defined.


Logic Errors

  Related Topics

The hardest program errors to track down are those within a script that executes without reported errors, but does not produce the expected results. Typically, the problem is caused by a mistake in logic or by a variable being assigned an improper value.

One method of debugging such an error is to "watch" critical program variables as the script runs. The usermsg, errormsg, sdlgmsgbox and statmsg commands provide ways to monitor variables during script execution. For example:

proc main

   integer x = 256, y, z

   string msg = "This is a string"

   x -= 1

   y = x >> 4

   z = y % 2

   usermsg "x = %d y = %d z = %d msg = %s" x y x msg

   ; The usermsg dialog will not close until

   ; you press a button.

endproc

The statmsg command allows you to monitor variables while the script runs, without stopping the execution for user input. For example:

proc main

   integer x = 256, y, z

   string msg = "This is a string"

   x -= 1

   y = x >> 4

   z = y % 2

   statmsg "x = %d y = %d z = %d msg = %s" x y x msg

   ; Script execution is not paused by the

   ; statmsg command.

endproc

Even something as simple as the beep command can be used effectively during the debugging process. For instance, in debugging a when procedure that handles an asynchronous event, you may simply wish to know approximately how often that procedure is called. An audible debug signal is ideal for this purpose.

You can also  use the ASPECT Run-Time Debugger to watch a variable’s value as a script executes. For a step-by-step example, see Resolving Run-Time Errors.

For another debugging technique, see Conditional Compilation.


MAIL Set/Fetch Statements

  Related Topics

mail address string

Specifies the Internet mail address used in the header of outgoing mail. This command corresponds to the Email Address field in the User Info panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Email Address field in a string.

mail forwardaddress OFF | ON | string

Specifies the Internet mail address used to send mail. This entry is only used if outgoing mail must be sent through a different server than incoming incoming mail. This command corresponds to the Forward outgoing... field in the Mail Server panel of the Setup, Internet, Internet Mail dialog. fetch returns the OFF / ON setting in an integer or the server address in a string.

mail logonname string

Specifies the username to be used when connecting to the mail server. This command corresponds to the Logon Name field in the Mail Server panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Logon name field in a string.

mail options index | string

Specifies the active Mail Client options set, corresponding to the Current Mail Options in Setup, Internet, Internet Mail. Either the zero-based index or the name of an option set as it appears in the Current Mail Options list may be used. fetch returns the contents of the Current Mail Options field in a string.

mail password string

Specifies the password to be used when connecting to the mail server. This command corresponds to the Password field in the Mail Server panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Password field in a string.

mail replyaddress string

Specifies the Internet mail address on which you would like to receive replies. When the person you are sending mail to receives your message, this is the address they will see on the Reply to line of their mail reader. This command corresponds to the Reply Address field in the User Info panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Reply Address field in a string.

mail serveraddress string

Specifies the ip address of the mail server from which you receive mail. This command corresponds to the Incoming mail server address field in the User Info panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Incoming mail server address field in a string.

mail signaturefile filespec

Specifies a text file that contains text to be appended to the end of all mail messages you send. This command corresponds to the Signature file field in the User Info panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Signature file field in a string.

mail username string

Specifies the username to be used when sending Internet mail. This command corresponds to the Full name field in the User Info panel of the Setup, Internet, Internet Mail dialog. fetch returns the contents of the Full name field in a string.


MODEM Set/Fetch Statements

  Related Topics

The set modem statements affect the communication port connection and initialization, and the operation of your modem. They correspond to the options in the Setup, System, Modem Connection dialog. If you intend to change a setting associated with a connection other than the currently selected Current Modem/Connection, you must first select it.

All set modem commands will fail if a file transfer is in progress.

modem acceptcall data OFF | ON

Enables or disables auto-answer for data connections. This command will fail for all "direct connect" connections and .dlc connections like Telnet. This command corresponds to the Accept data terminal calls check box in Setup, System, Modem Connection. fetch returns 0 for OFF, 1 for ON.

modem acceptcall fax OFF | ON

Enables or disables auto-answer for fax connections. This command will fail for all "direct connect" connections and .dlc connections like Telnet. This command corresponds to the Accept fax calls check box in Setup, System, Modem Connection. fetch returns 0 for OFF, 1 for ON.

modem ansrings integer

Specifies the number of telephone rings after which Procomm Plus answers a data or fax call, with a valid range of 1 to 20. This command will fail for all "direct connect" connections and .dlc connections like Telnet. This command corresponds to the Procomm Plus should answer incoming calls after x rings field in Setup, System, Modem Connection. Using fetch returns the current number of rings as an integer.

Setting this value alone does not enable auto-answer. To enable auto-answer for data, fax, or both, you must use the set modem autoanswer command.

modem autoanswer OFF | PW | OTHER

Enables or disables auto-answer for data and fax connections.  This command will always return OFF for all "direct connect" connections and .dlc connections like Telnet. This command corresponds to the Incoming call handling for current modem connection option button group in Setup, System, Modem Connection, where OFF specifies the Do not accept... option, PW specifies the Procomm Plus should answer... option, and OTHER specifies the Another program will answer... option. fetch returns 0 for OFF, 1 for PW or 2 for OTHER.

modem connection index | string | CURRENT | FIRST

Specifies the active data modem connection. Either a zero-based index, or the name of a data modem connection in the Current Modem/Connection list in Setup, System, Modem Connection may be used.  This command will fail if an attempt is made to set a Connection Directory entry to "direct connect-none", "direct connect-Telnet", or a modem/connection that has incnctlist set to OFF. This command will also fail if you specify a modem/connection  that has incnctlist set to OFF. fetch returns the contents of the Current Modem/Connection field in a string.

Please note that the index value for TAPI connections begins at 10, even though TAPI connections may be displayed at the top of the Current Modem/Connection list. Other connections have zero-based indexes. For example, "direct connect-none" is always index 0, followed in order by the other connections in the list.

The CURRENT and FIRST keywords are valid only for a specified Connection Directory entry.  The FIRST keyword is valid only when accessing a Fax entry.

modem faxxmit OFF | ON

Specifies whether or not a modem can be used for sending faxes. This command corresponds to the Use this modem/connection to send faxes check box in the Setup, System, Modem Connection dialog. fetch returns 0 for OFF, 1 for ON.

This command will fail for all "direct connect" connections and .dlc connections like Telnet.

modem incnctlist index | string  OFF | ON

Displays or hides the connection name referred to by the index or string in the Quick Select connection list. This command fails when a set modem incntlist is attempted on the "direct connect-none" connection, and a fetch on that connection always returns the value ON. This command corresponds to the Make this connection available to Procomm Plus check box in Setup, System, Modem Connection. fetch returns 0 for OFF, 1 for ON.


Macros

  Related Topics

ASPECT supports macro definitions with or without parameters. When a macro is processed, the ASPECT Compiler, replaces it with the body of the macro definition. Any argument list is also replaced. This is called macro expansion. The ASPECT Compiler then continues with the first token found in the macro body.

The name of a macro must be specified using the same rules followed for all identifiers. However, macro names are handled differently by the ASPECT Compiler, and there is no restriction on using the name of a reserved word or user-defined name, except for other macro names.

When a macro is defined without parameters, the macro body begins immediately after the macro name:

#define MACRO_NO_ARGS "This is the macro body."

A macro with parameters is defined by following the macro name with a left parentheses:

#define MACRO_ARGS(x,y,z) x = y * z

A macro can have between 0 and 12 parameters in a comma-separated list. The parameters must follow the standard ASPECT naming conventions, and the list must terminate with a right parentheses. A parameter name appearing within the macro body will be replaced with the argument given in the ASPECT source line using the macro during expansion, but the macro body does not have to contain every parameter in the macro definition.

For example, with user-defined integer variables product, mult1 and mult2 declared either globally or locally, the statement:

MACRO_ARGS(product, mult1, mult2)

would become:

product = mult1 * mult2

when expanded by the ASPECT Compiler.

The body of a macro can be up to 254 characters in length, and a macro can expand into a multiple command line argument, using the "#" character as an end-of-line marker within a macro body. For example, a multi-line macro could be defined as:

#define XMIT(a,b,c) transmit a # transmit b # transmit c

or, using the line continuation character:

#define XMIT(a,b,c) \

transmit a	#\

transmit b	#\

transmit c

Either of these forms expand into three separate ASPECT command lines when processed by the ASPECT Compiler:

transmit a

transmit b

transmit c

The ASPECT Compiler issues a warning message if a macro is invoked with too many or too few arguments. If too few arguments are specified and the missing arguments occur within the macro body, no argument substitution will be done. If too many arguments are specified, the overflow will be ignored in the macro expansion. The argument list must be comma-separated. Parentheses may be used within the argument list if they are properly matched and nested, and commas may be used within parentheses defining a single variable. Each macro argument can be up to 258 characters long.

After the ASPECT Compiler has substituted all of the arguments within the macro, the macro is said to be fully-expanded. The total number of characters of a fully-expanded macro cannot exceed 1024.

If any token in the macro expansion matches the name of a defined macro, it will also be expanded. However, macros are not expanded recursively. Thus if the name of a macro is found within its own body, or through a set of macro expansions, it will not be expanded again and the name will be treated as a normal identifier.

Macros are very useful for making code easier to read. For example, most programmers would find using:

#define MIN(x,y) (( x > y ) ? y : x)

least = MIN(int1, int2)	; Least will equal lesser

; of int1,int2

easier to understand than:

least = ( int1 > int2 ) ? int2 : int1

when reading the script source. Macros can also simplify global changes for constant values. It is much easier to change the value once within a #define statement than to scan through several ASPECT files searching for many occurrences.


Memory Commands

memaddress	Returns memory address associated with the specified memory ID.

memalloc	Allocates a block of contiguous memory for use by a script.

memavail	Returns a long value reflecting the amount of contiguous free memory available for allocation or executing other programs.

memchr	Searches for the first occurence of the specified character in an allocated memory block.

memcmp	Performs a byte-by-byte comparision of two memory locations.

memfree	Releases a block of memory previously reserved by memalloc or memrealloc.

memgetc	Retrieves a single character from a block of memory.

memicmp	Performs a byte-by-byte, case-insensitive comparision of two memory locations.

memmove	Copies characters from one location to another, either between different blocks or within the same block.

memputc	Writes a single character to a location within a block of memory.

memread	Reads a block of data from an allocated block of memory.

memrealloc	Changes the size of a block of memory previously reserved by memalloc.

memset	Initializes a block of memory to a specified value.

memsize	Reports the size of a block of memory allocated by memalloc.

memwrite	Writes a block of data to an allocated memory block.

 Return to category list


Menu Commands

menubar	Creates a new script menu bar.

menucheck	Places or removes a check mark on a menu item created by a script.

menuitem	Adds an item to a menu pop-up or menu bar.

menuitemcount	Returns the number of items on a menu bar or pop-up menu.

menupopup	Adds a pop-up menu to an existing pop-up menu or menu bar.

menupopupid	Returns the menu ID of a pop-up menu on a menu bar or other pop-up menu.

menuselect	Selects a PROCOMM P LUS or ASPECT menu item.

menushow	Displays the menu bar corresponding to the specified menu id.

menushowpopup	Displays a floating pop-up menu.

menustate	Reports the state of a Procomm Plus or ASPECT menu item.

 Return to category list


NEWS Set/Fetch Statements

  Related Topics

news address string

Specifies the Internet mail address being used when posting messsage from News. When the message you are posting is read, this is the address that will appear on the From line. This command corresponds to the Email Address field in the User Info panel of the Setup, Internet, News dialog. fetch returns the contents of the Email Address field in a string.

news checkgroups OFF | ON

Specifies whether Procomm Plus will check the server for new newsgroups at startup. This command corresponds to the Check for new newsgroups at startup field in the Properties panel of the Setup, Internet, News dialog. fetch returns a zero for OFF and a 1 for ON.

news logonname string

Specifies the username to be used when posting messages. This command corresponds to the Logon Name field in the News Server panel of the Setup, Internet, News dialog. fetch returns the contents of the Logon name field in a string.

news organization string

Specifies the organization name being used when posting messages from News. When the message you are posting is read, this is the address that will appear on the Organization line. This command corresponds to the Organization field in the User Info panel of the Setup, Internet, News dialog. fetch returns the contents of the Organization field in a string.

news options index | string

Specifies the active News Reader options set, corresponding to the Current News Options in Setup, Internet, News. Either the zero-based index or the name of an option set as it appears in the Current News Options list may be used. fetch returns the contents of the Current News Options field in a string.

news password string

Specifies the password to be used when posting messages. This command corresponds to the Password field in the News Server panel of the Setup, Internet, News dialog. fetch returns the contents of the Password field in a string.

news promptheaders OFF | ON

Specifies whether Procomm Plus will prompt for header retrieval. This command corresponds to the Prompt if number of headers... field in the Properties panel of the Setup, Internet, News dialog. fetch returns a zero for OFF and a 1 for ON.

news serveraddress string

Specifies the address of your news server. This command corresponds to the News server address field in the News Server panel of the Setup, Internet, News dialog. fetch returns the contents of the News server address field in a string.

Changing the server address when Procomm Plus is not in News mode will result in a dialog being displayed on a subsequent switch to News mode. The dialog will not be displayed if Procomm Plus is already in News mode.

news signaturefile filespec

Specifies a text file that contains text to be appended to the end of all messages posted from News. This command corresponds to the Signature file field in the User Info panel of the Setup, Internet, News dialog. fetch returns the contents of the Signature file field in a string.

news username string

Specifies the name you wish to use when posting news messages. This command corresponds to the Name field in the User Info panel of the Setup, Internet, News dialog. fetch returns the contents of the Name field in a string.


Naming Elements in ASPECT

  Related Topics

All of the named elements in ASPECT, such as command word names, procedure and function names, labels, variable names and #define macros follow the same basic syntax rules:

Name Length

Names have a maximum length of 30 characters.The compiler treats all of these characters as unique, but they are not case sensitive. Therefore, the ASPECT Compiler would consider two separate variables with names identical for the first 29 characters to be different so long as the 30th character were different. For example, the two following variables would be considered unique by the ASPECT Compiler:

string NotAVeryOriginallyNamedStrng1

string NotAVeryOriginallyNamedStrng2

If two identical local variables are defined within the same procedure or function block, the second such variable would be flagged as an error by the ASPECT Compiler.

Allowed Characters

Names can begin with any alphabetic character, A-Z or a-z, or an underscore "_". Other characters in the name can be alphabetic, the underscore character or numeric, 0-9. Examples of valid names are "NUM", "_FINAL_", "Send_2_Where", "e" and "Term5".

Reserved Words

All pre-existing names, like command words and system variables, are considered reserved within ASPECT, and cannot be used as user-defined variable, function, or procedure names. Reserved words can be used in macro definitions, however.A complete list reserved words appears in ASPECT Reserved Words.


Non-critical Run-Time Errors

  Related Topics

001 Value out of range

A value was encountered which was not within the valid range of values accepted for a particular command parameter. For example, attempting to strputc a value that is outside of the range of valid characters, 0 to 255, into a string will generate this message. This is perhaps the most common error message, and does indicate a problem that should be resolved.

002 Divide by zero

A division (/) or modulus (%) operator attempted to divide a value by zero.

003 Insufficient memory

An ASPECT command could not be completed successfully due to insufficient memory.

004 String length limit exceeded

An operation which updates, concatenates, inserts or otherwise writes to a string variable has attempted to write data past the end of a string’s data area. The maximum length of a string in ASPECT is 256 characters.

005 Invalid identifier

An ASPECT command attempted to reference an id, such as a file I/ O, memory block, when, or setjmp/longjmp id, that was not valid at the time the command executed.

006 Child scripts nested too deeply

The limit of nested scripts launched with the execute command has been reached. This message probably indicates an execution problem with recursion, as the allowed number of nested scripts is 1000!

020 Error creating dialog box

Typically, this message indicates a memory or resource allocation problem.


Numeric, String Conversion Commands

atof	Converts the contents of an ASCII string to a floating point value.

atoi	Converts the contents of an ASCII string to an integer value.

atol	Converts the contents of an ASCII string to a long value.

ceil	Computes the smallest integral value greater than or equal to a floating point value.

floor	Computes the largest integral value less than or equal to a floating point number.

ftoa	Converts a float to an ASCII string and stores it in a string variable.

itoa	Converts an integer to an ASCII string and stores it in a string variable.

ltoa	Converts a long to an ASCII string and stores it in a string variable.

numtostr	Converts a numeric value to a string.

rand	Returns a random value, ranging from 0 to 2147483647.

strtonum	Converts a string to a numeric value.

 Return to category list


OEM/ANSI Commands

ansitokey	Converts an ANSI character to its corresponding virtual key code and shift state.

ansitooem	Converts an ANSI character or string to its OEM equivalent.

oemtoansi	Converts an OEM character or string to its respective ANSI character equivalents.

oemtokey	Converts an OEM character to its key value.

 Return to category list


Opening the Compile/Edit ASPECT File dialog

  Related Topics

Before an ASPECT script can be executed, it must be compiled. Select Tools | Scripts | Compile/Edit on the menu, or click on the Action Bar’s Compile/Edit button to open the Compile/Edit ASPECT File dialog:

Compile

When you click on the Compile button, Procomm Plus attempts to compile the source file you selected. If successful, the message "Script file successfully compiled!" is displayed in the compiler window, and a .wax file is generated.

Compile and Run

If you click the Compile and Run button, Procomm Plus will run the script immediately after a successful compilation.

If the compilation is unsuccessful, specific warning and error messages are displayed in the compiler Message List box. You can use these messages to help you "debug" your source file, then compile the script again.

These same messages can also be written to a file with the source filename and the extension ".err" if you specify the "/ES" compiler switch in the Additional Options and Macro Definitions field within the Compile Options dialog, or select Save Messages from the ASPECT Compiler window. For more information, see "Additional Options and Macro Definitions".

Delete

You can also delete script files you no longer need from this dialog. Select the name of the file to erase and click the Delete button. Procomm Plus will prompt you for confirmation before deleting the selected file.

Compile Options...

The Compile/Edit ASPECT File window also features a separate dialog where you can set the values for several compiler options. See Compiler Options... for more information.


Option Set Commands

itemcount	Returns the number of items within a option set list.

itemcreate	Creates a new item in a option set list.

itemfind	Returns the index associated with a option set item.

itemname	Returns the name of a option set item in a string.

itemremove	Removes a script- or user-created entry from a option set list.

 Return to category list


Other Options

  Related Topics

The Other Options settings group allow you to specify the kinds of debugging information generated by the compiler as your script is processed. It also includes a setting for the number of errors the compiler will process before terminating a compile attempt.

Compile for Debug.

If this box is checked, the ASPECT Compiler will embed special information in the compiled script. If the script contains breakpoint commands, selecting this option will cause them to "fire" during script execution.

Create map file.

If this box is checked, the ASPECT Compiler will generate a map file along with the compiled script. The map file, with an extension of .map, will be created in the same directory as the target source file. A .map file contains detailed information about the generated .wax file, including user-defined variables, procedures and functions, and global variable usage.

Include line numbers.

If this box is checked, the compiler will include source line numbers in the generated map file. This option is only available if Create map file is enabled.

The debugging options are discussed in more detail in Execution or Run-Time Errors

Maximum errors before terminating.

This field specifies the number of compile-time errors the ASPECT Compiler will allow before terminating the compile attempt. By default, this value is 20.


PORT Set/Fetch Statements

  Related Topics

The following set/fetch statements control the communication port for the current connection.

FAILURE is set if any set port command is used to set/fetch the settings of an unopened TAPI connection. Also, all set port commands fail with the "direct connect-none" connection and .dlc connections like Telnet.

For TAPI connections, the set port commands only affect the currently selected connection in System panel of Setup. They cannot change or access settings of a connection that is referenced by a Connection Directory entry. The settings will not be saved as new settings for a TAPI connection.

All set port commands will fail if a file transfer or a dialing attempt is in progress.

port baudrate baudrate

Specifies the baud rate at which Procomm Plus talks to the current data modem. If the DEFAULT keyword is specified, the string Modem Default is used. fetch returns the current baud rate as a long value.

port databits integer

Specifies the length of a byte sent or received through the current port, either 7 or 8 bits. fetch returns 7 for 7 data bits or 8 for 8 data bits.

port dropdtr OFF | ON

Determines whether Procomm Plus will drop the RS-232 DTR signal to disconnect. fetch returns 0 for OFF or 1 for ON. This command always fails for TAPI connections.

port hardflow OFF | ON

Enables or disables hardware flow control, which is sometimes referred to as RTS/CTS flow control.  fetch returns 0 for OFF or 1 for ON.

port parity NONE | ODD | EVEN | MARK | SPACE

Specifies the parity for the current communication port. fetch returns 0 for NONE, 1 for ODD, 2 for EVEN, 3 for MARK or 4 for SPACE.

port softflow OFF | ON

Enables or disables software flow control, which is sometimes referred to as XON/XOFF flow control.  fetch returns 0 for OFF or 1 for ON.

port stopbits integer

Specifies the number of bits used to signify the end of a byte sent or received through the current port. fetch returns 1 for 1 stop bit or 2 for 2 stop bits.


PRINT Set/Fetch Statements

  Related Topics

The following set/fetch statements control the operation of the printer.

Changes made using the set print command family will take effect upon the execution of the next printer open command. If the printer is already open, changes made using the set print command family will not alter the current printer output.

print device string

Specifies the print device used by Procomm Plus when the printer is enabled. Only the name of the device is required; port information should not be included in the device name even though the device name appears this way in many of the printer lists in Windows. fetch returns the name of the current print device in a string.

print fontname string

Specifies the font used by Procomm Plus when printing. String should specify the font name just as it appears in the Font list box in the Fonts dialog.  fetch returns the name of the current printer font in a string.

print fontsize integer

Specifies the size of the font used by Procomm Plus when printing.  fetch returns the size of the current printer font in an integer.

print footer string

Specifies the text to print at the bottom of printed pages. The maximum character length of this text is 65 characters. fetch returns the contents of the Footer field for the current print device in a string.

print header string

Specifies the text to print at the top of printed pages. The maximum character length of this text is 65 characters. fetch returns returns the contents of the Header field for the current print device in a string.

print margins left right top bottom

Specifies the margins for printed pages. All values are decimal point values or floats, measured in inches. fetch returns four float values, reflecting the values of the four margins.

print orientation PORTRAIT | LANDSCAPE

Determines the orientation of printed pages. When set to PORTRAIT, pages are taller than they are wide. When set to LANDSCAPE, pages are wider than they are tall. fetch returns 1 for PORTRAIT or 2 for LANDSCAPE.


PROCOMM PLUS: ASPECT Help Contents 2
Procomm Plus: ASPECT Help Contents

Introduction to ASPECT

The Elements of ASPECT

ASPECT Command Reference

Commands Listed Alphabetically

Commands Listed by Function

The ASPECT Commands

Set and Fetch Statements

System Variables

ASPECT Scripts: A Brief Tutorial

The ASPECT Utilities

Debugging Scripts

The ASPECT Compiler

ASPECT Reserved Words

Virtual Key Codes

Using Remote ASPECT Commands


PROCOMM PLUS: ASPECT Help Contents 3
Procomm Plus: ASPECT Help Contents

Introduction to ASPECT

The Elements of ASPECT

ASPECT Command Reference

Set and Fetch Statements

System Variables

System Variables Overview

The List of System Variables

ASPECT Scripts: A Brief Tutorial

The ASPECT Utilities

Debugging Scripts

The ASPECT Compiler

ASPECT Reserved Words

Virtual Key Codes

Using Remote ASPECT Commands


PROCOMM PLUS: ASPECT Help Contents 4
Procomm Plus: ASPECT Help Contents

Introduction to ASPECT

The Elements of ASPECT

ASPECT Command Reference

Set and Fetch Statements

System Variables

ASPECT Scripts: A Brief Tutorial

Debugging Scripts

The ASPECT Compiler

ASPECT Reserved Words

Virtual Key Codes

Using Remote ASPECT Commands


PROTOCOL-related Set/Fetch Statements

  Related Topics

For all of the protocol set/fetch commands, the specified protocol argument is a base type identifier required to validate the syntax at compile time. At run-time, if the currently specified protocol in Setup has the same base type, only the currently specified protocol is effected. If the currently specified protocol is of a different base type, the command will affect the base protocol definition.

Xmodem, 1K-Xmodem, 1K-Xmodem-G, Ymodem and Ymodem-G Protocol Set/Fetch Statements

ASCII Protocol Set/Fetch Statements

CISB+ Protocol Set/Fetch Statements

IND$FILE Protocol Set/Fetch Statements

KERMIT Protocol Set/Fetch Statements

RAWASCII Protocol Set/Fetch Statements

ZMODEM Protocol Set/Fetch Statements


Packet Mode Commands

pkmode	Toggles error-free packet mode on and off.

pkrecv	Receives a packet from another computer that has issued an ASPECT pksend command.

pksend	Sends a packet to another computer that is running an ASPECT script.

 Return to category list


Parameter Variables

  Related Topics

Any procedure except proc main can be defined with up to 12 parameter variables. Parameter variables are similar to local variables in that they may only be referenced within the procedure in which they’re defined. Unlike local variables, however, parameter variables are automatically initialized when the procedure or function is called, using the values supplied by the calling statement.

The call command allows values to be passed to the procedure or function being called. These values initialize the procedure’s or function’s parameters.

Parameter variables must be defined at the top of a procedure or function, before any commands or local variables. The order in which parameters are defined determines the order in which they’re passed by the calling procedure or function.

Changes made to parameter variables can be passed back to the calling procedure. For more information, see the description of the call command.

Additional checking on passed parameters is performed during compilation. Inconsistencies, such as mismatched data types, or too many or too few parameters will result in compiler error messages.

A parameter variable is defined much like a local or global variable, with the addition of the param keyword before the datatype statement. Several parameter variables of the same datatype may be defined on the same source line, if each definition is separated from the next by a comma. For more information on defining parameter variables, see the description of the param command.


Passing Parameters by Reference

  Related Topics

As we said earlier, a local variable can only change within the procedure that defines it. Globals are accessible to all procedures in a script file and may therefore be modified at any point in a script. It is possible to pass a local variable from one procedure to another, have the second procedure change its value and pass back the changed value. This is accomplished by prefixing the ampersand character (&) to the name of the passed variable, a process known as passing by reference:

proc main

   integer Number = 0                 ; Declare a number variable.

        OtherStuff( &Number )         ; Pass the variable Number "by reference".

        usermsg "%d" Number           ; Display new value. Should be 1 now.

endproc

proc OtherStuff

param integer Num                     ; Variable for passed value.

   ;             .

   ;             .                    ; More code...

   ;             .

   Num++                              ; But one command increments the value

                                      ; passed to it and automatically returns it to

                                      ; the variable used when calling this proc.

endproc

This is a trivial example. It is possible to achieve the same results with a function or a global variable. However, if you think of the above fragment in the context of a longer script with many procedures, a global variable may be risky. You might lose track of the various situations in which you’ve used a global variable, and have a procedure change its value in a way that adversely affects another part of the script. On the other hand, a function may not be appropriate if it performs more than one task, and any of its tasks inconveniently change the values of the passed parameters. In the case above, a variable passed by reference is the safest and most elegant choice.

Notice the use of "%d" in the usermsg command to display the value of an integer variable in the formatted string.

Exercise

Rewrite the "Carriage Return" script in the section on functions so that it uses a variable passed by reference, instead of a function.


Predefined Global Variables

  Related Topics

In addition to allowing you to define your own variables, ASPECT provides 40 predefined global variables that you can use "right out of the box". These are the string variables S0 through S9, the integer variables I0 through I9, the long integer variables L0 through L9 and the float variables F0 through F9. Like user-defined variables, you can assign these variables any values you want in the course of your script. For most purposes, it’s better to define your own variables. It’s very hard to tell from a variable name like I5, for example, what role it plays in a script. Variable names like "NumApples", "CostOfGoods" or "NameOfClient" are much more descriptive.

Although they can be used like any global user-defined variable, the predefined global variables can be used in very special ways in ASPECT, such as sharing values between different scripts.


Predefined Macro Definitions

  Related Topics

The ASPECT Compiler automatically defines several macro definitions that are accessible during compilation: ASPVERSION, ASPDEBUG, ASPFILE, and ASPLINE. Predefined macros cannot be undefined using #undef.

ASPVERSION is defined as the current ASPECT Compiler version ID. A single number is defined where the hundreds digit represents the major version number, and the tens and ones digits represent the minor version number. For instance, version 4.00 is stored as the value 400 in ASPVERSION. This macro is useful for ASPECT scripts that can be compiled and run on several different versions of Procomm Plus.

ASPDEBUG is defined with a value of 1 whenever a script is being compiled in debug mode (or with the /Z command line switch). This macro definition can assist users in writing blocks of code that should be executed only when debugging their scripts. ASPDEBUG is not defined when not compiling in debug mode, thus the preprocessor command #ifdef would typically be used to test for its existence.

ASPFILE is defined with the current source file name that is being compiled. Its definition will change with each included source file.

ASPLINE is defined with the current source file line that is being compiled. It uses a long data type.

The combination of ASPFILE and ASPLINE are useful when writing debugging code within a script. For instance, one could write code to test a condition upon entry to a particular procedure:

proc Example

param integer Value

#ifdef ASPDEBUG

if(value<0)||(value>100)

usermsg "File: %s Line %ld Value out of range."\

ASPFILE ASPLINE

endif

#endif

; Additional commands and processes

; can be placed here.

endproc


Predefined Variables

  Related Topics

For your convenience, ASPECT provides a total of 40 "predefined" global variables which you do not have to define at the beginning of a script. They are available for use by any command, procedure, or function within a script.

There are 10 predefined string variables, labeled S0 through S9. Each can contain a maximum of 256 characters. The predefined numeric variables are labeled I0 through I9 for integers, L0 through L9 for long values and F0 through F9 for float values.

Predefined variables are initialized to 0, or to null strings in the case of string variables when Procomm Plus is started. If a script uses these variables, their values will remain unchanged after the script terminates, so they can be used to pass values between separate scripts.

Predefined variables have several uses. If Procomm Plus is executed with a command-line in which the first parameter is a script file name, with either a .was or .wax extension, the information following the filename will be parsed into individual options. Each option will be loaded into a predefined string variable, beginning with S0. Up to 10 options can be passed to the requested script in this manner. The predefined integer variable I0 will contain a count of the parsed options. The script can use the system variable $SCRIPTMODE to determine whether it was run from the command-line, and reference I0 for the number of options provided.

As mentioned before, predefined variables can be used to pass information between executed scripts. If a script launches or spawns another script using either the chain or execute command, the launched script automatically inherits all values stored within the predefined variables. A script can determine whether it was executed by another script, but the convention for the information passed to the second script is left to the script author.

Information can be passed in both directions, as changes made to predefined variables by a spawned script are maintained in the parent script when it resumes execution.

Predefined variables can also be used in Dynamic Data Exchange (DDE). In DDE, an application can change or retrieve the values of Procomm Plus’s predefined variables, providing a mechanism for data transfer between the two applications. ASPECT can also be used to control the DDE communications channel.


Preprocessor Commands

  Related Topics

The ASPECT Compiler has a built-in preprocessor. A preprocessor command is an instruction to the compiler to carry out a change in the way the ASPECT source file is being compiled. It is normally used to make source files simpler to adjust for special conditions, for the inclusion of other source files in the compiled result, or to prevent compilation of certain sections of the source file.

Preprocessor commands begin with a pound sign (#) as the first non-whitespace character on a source line followed by the command word. Spaces or tabs are allowed between the pound sign and the command word. A pound sign appearing alone on an ASPECT source line is called a "null directive" and is treated as a blank line.

Preprocessor commands are recognized before macro expansion occurs. If a macro expands into something that appears as a preprocessor command, it will not be recognized as a preprocessor command, and it will generate a compile-time error.

The conditional compilation commands, #ifdef, #ifndef, #elifdef and #elifndef test for the existence of a defined macro name. The macro name should be specified without arguments, even if it was defined with a parameter list.

The #if and #elif preprocessor commands are conditional compilation commands as well. However, unlike the previous, these commands evaluate a constant expression (such as a numeric constant, or an expression composed solely of numeric constants) to determine whether or not the block of code which follows is compiled.

For more information on preprocessor commands, see the descriptions for the #define command and the #ifdef command.


Preprocessor Commands_1
Preprocessor Commands

#comment  |	Denotes a comment block.

#endcomment

#define	Defines a macro name and the text to substitute during compilation.

#else	Causes the ASPECT Compiler to process an alternate set of commands when the result of an associated #ifdef, #ifndef, #elifdef or #elifndef is false.

#elif	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#elifdef	Allows conditional compilation by testing for the existence of a defined macro name after an associated #ifdef, #ifndef, #elifndef or another #elifdef has failed.

#elifndef	Allows conditional compilation by testing for the non-existence of a defined macro name after an associated #ifdef, #ifndef, #elifdef or another #elifndef has failed.

#if	Allows the ASPECT Compiler to evaluate whether the block of code which follows is evaluated or not.

#ifdef  |	Allows conditional compilation by testing for the existence of a defined macro name.

#endif

#ifndef	Allows conditional compilation by testing for the non-existence of a defined macro name.

#include	Merges commands from another ASPECT source file during compilation.

#undef	Removes the current definition of a previously-defined macro.

 Return to category list


Printer Commands

printalign	Specifies how text will be positioned when sent to the printer.

printattr	Specifies the character attributes for text sent to the printer.

printcapture	Routes characters received by Procomm Plus or entered from the keyboard to the printer.

printchar	Prints a character on the "open" printer at the current position.

printer	Opens the current printer in preparation for any of the print-command family.

printfit	Determines whether a string will print on the current page.

printfont	Selects a new printer font for subsequent print operations.

printmargin	Determines the page margins for data printed from Procomm Plus.

printstr	Sends a specified string to the open printer.

printtabs	Determines the tab positions for strings printed with the printtabstr command.

printtabstr	Prints a line of text, expanding tabs to the positions set with the printtabs command.

 Return to category list


Procedures and Functions

  Related Topics

A procedure or function is a logical grouping of commands identified by a unique name. The name is provided as a parameter to a proc or func command, or as an argument to a call command. For example:

proc Update

defines the beginning of a procedure block named Update. Your script could later branch to that procedure with the statement:

call Update

Unless explicitly stated otherwise, a function can be substituted for a procedure in any command description. Procedures and functions are very closely related; essentially, a function is a procedure that can return a value.

When a function is defined, its return type must be specified. Additionally, a variable of the appropriate type must be declared when a function is called to receive the function’s return value. A numeric variable can receive a value from a function that returns a float, long or integer value; a string variable can receive a value from a function that returns a string.

Every ASPECT program requires at least one procedure called main, which identifies the entry point for command execution. For more information, see ASPECT Program Flow.

If a procedure or function requires arguments to be passed, the procedure or function name is followed by the with keyword, and then a list of arguments. When calling a function, the argument list, if any, can optionally be followed by the into keyword, and a variable to receive the function’s return value. For example:

call myfunc WITH arg0 arg1 arg2 INTO retval

calls the function myfunc with arguments whose names are arg0, arg1 and arg2, and receives the function’s return value into a variable called retval. If a function or procedure receives no arguments, its format could be:

call myproc

(or)	call myotherfunc

(or)	call myotherfunc INTO retval

A user-defined procedure or function can also be called using a shortened format, as in:

name ([arglist])

If an argument list is present, a comma must used to separate the arguments. If a function is called in this manner, its return value can be assigned to a variable using an assignment operator. A function call with the shortened format can also be used in an expression involving any number of operators and operands. Its return value is treated just like any other value in the expression.

With the shortened format, the examples above would read:

retval = myfunc(arg0, arg1, arg2)

myproc()

mySpecialFunc()

retval = myUniqueFunc()

This shortened form is thus more flexible, less verbose and certainly as clear as the longer version. We highly recommend the shortened form, as future enhancements of ASPECT may require it.

While the call format does not require commas to separate arguments within the argument list, commas are accepted if they appear there. In fact, in one special case a call actually requires a comma to separate arguments. This case is discussed below.

Passing by Value and Reference

When a procedure or function requires arguments, arguments that are constants are passed by value. Arguments that are variables are, by default, passed by value. This means that the called function or procedure receives a copy of the argument, and any changes made to that argument by the called procedure or function will not alter the value of the argument variable when the function or procedure returns.

If a procedure or function is intended to permanently alter the a variable argument’s value, however, the variable can be "passed by reference". This means that the variable will have whatever value its corresponding parameter last had in the called procedure or function when it returned.

To pass a variable by reference, an ampersand character (&) must be placed before the name of the variable. For example the statement:

myfunc(&arg0, arg1, &arg2)

calls the function myfunc with arguments arg0 and arg2 passed by reference. When myfunc returns, arg0 and arg2 may have new values assigned to them, but arg1 will have whatever value it had when the call was executed. The call format would look like this:

call myfunc with &arg0 arg1, &arg2

Note that a comma was placed between arg1 and arg2. Without this comma, the ASPECT Compiler would have interpreted the two arguments as a single argument resulting from the expression

arg1 & arg2

which performs a bitwise-AND operation on the two operands. This would be flagged as an error by the ASPECT Compiler. In general, if the call format is used at all, the use of commas to separate arguments is always recommended and sometimes required.

A Technical Note

Technically, ASPECT’s parameter passing convention is "call by value reference." This means that any variables passed by reference, as explained in "Passing by Value and Reference", will not be updated until after the called procedure or function returns. The variable’s value is passed to the called procedure, where the value is then used or modified by the procedure. Upon return, the value is copied back into the variable which was passed by reference.

"Call by value reference" has two important implications. First, if the longjmp command is executed within the called procedure, and the target is some other previously called procedure, variables that had been passed by reference after the setjmp command was processed in that target procedure will not be updated with the modified values. Second, if a global variable is passed by reference, its value will not change within the called procedure until it returns. Thus the value of the global itself, and the value of the variable argument corresponding to that global in the called procedure will not necessarily be the same!


Procedures: the basics

  Related Topics

In the example of Variables: the basics, you took your first look at using more than one procedure. When another procedure is called, script execution passes to it. When the called procedure is finished, execution automatically returns to the calling procedure at the line after the call statement.

The use of separate procedures may seem odd to you at first. Why not just put everything inside the main procedure? Breaking up your scripts into separate procedures gives you several advantages:

•	You can break up larger tasks into smaller, more easily-designed steps.

This is especially critical in large script projects.

•	You can call isolated procedures in other procedures in your script.

In the previous example, main is the only procedure calling SendData, but you could add other procedures that called the SendData routine. Since procedures are re-usable, you avoid redundant lines of code.

•	Modular or procedure-oriented code is more readable and therefore easier to maintain.

•	You can replace routines easily.

Changing the way SendData works is much easier than searching through dozens or even hundreds of lines of code to make selective changes.

•	You can re-use code.

If you have broken down a task into several logical procedures or functions, there’s a good chance that at least some of those functions may be useful in other scripts with minor adjustment.

The SendData procedure in the example above requires Name to be a global variable, accessible to any procedure in the program. Be careful when using global variables in this manner, as any procedure can modify a global variable’s value.

The call Command

For example, another procedure may set the value of the variable to your last name rather than your first, and the main procedure has no way of detecting it. Let’s rewrite the script so that it uses a local variable rather than a global variable:

proc main                           ; Beginning of main procedure.

   string Name = "Fred^M"           ; Define local string variable "Name"

   call SendData with Name          ; Call another procedure, passing it the value

                                    ; of name.

endproc                             ; End of main procedure.

proc SendData                       ; Procedure called by another proc.

param string szText

        ; Define a local variable to contain the value

        ; passed from another procedure. In this case

        ; it’s a string.

        transmit szText             ; Send the value of the local variable "szText",

                                    ; which is equal to the value of name

        usermsg "Done!"             ; Message box.

endproc                             ; End of SendData procedure, execution

                                    ; returns to calling procedure.

In this example we use the call command not only to invoke another procedure, but to pass it a value as well. This demonstrates a very powerful feature of ASPECT. The call...with construct only passes a variable’s value and not the variable itself. The called procedure accepts that value into its own local variable and can manipulate it in any way without changing the value of the original variable in the main procedure.

The ability to pass parameters greatly enhances the usefulness and modularity of called procedures. Now we can call SendData several times for different purposes:

;*********************************************************************

; Main procedure.

; Calls: SendData.

; Called by:

; Modifies the value of the following globals:

;*********************************************************************

proc main                        ; Beginning of main procedure.

   string FirstName = "Fred^M"   ; Define local string variable "FirstName".

   string LastName = "Smith^M"   ; Define local string variable "LastName".

   call SendData with FirstName  ; Call SendData procedure, passing it

                                 ; the value of FirstName.

   call SendData with LastName   ; After execution returns to main, call

                                 ; SendData again passing a new value.

endproc                          ; End of main procedure.

;*********************************************************************

; SendData procedure.

; Calls:

; Called by: main.

; Modifies the value of the following globals:

;*********************************************************************

proc SendData                    ; Procedure called by another proc.

param string szText              ; Define a local variable to contain the

                                 ; value passed from another procedure.

   transmit szText               ; Send the value of the local variable

                                 ; "szText", which is equal to the value

                                 ; passed in from calling procedure.

   usermsg "Done!"               ; Message box.

endproc                          ; End of SendData procedure, execution

                                 ; returns to caller.

Notice the command clause "param string", instead of "string" in SendData’s variable declaration. param tells ASPECT that a procedure requires the calling procedure to pass it a variable or constant of the specified type. In this case, SendData expects a string because the param command is followed by "string". Simarly, we can also pass integers, longs and floats by changing the type declaration that follows the param command.

As you can see, the comments at the head of each procedure make it clear "who is calling whom". They may also document global variables that are affected by a procedure or explain what a procedure does. This form of documentation, while not necessary, is excellent programming practice.

Exercise

Write a procedure called DelaySend that can be passed a string from any other procedure. DelaySend should use the command "pause 1" to delay a second before transmitting the string. You can test your procedure by creating a main procedure that calls DelaySend.


Protocol Names and Indices

  Related Topics

The set and commands, getfile, sendfile and the item-related commands use reserved names or indices to reference the protocols supported by Procomm Plus.

The protocol names and their corresponding indices are:

PROTOCOL NAME AND INDEX TABLE

Protocol Name	Index	Getfile Filespec	Sendfile Filespec
ZMODEM	0	Not required	Required
KERMIT	1	Not required	Required
XMODEM	2	Required	Required
1KXMODEM	3	Required	Required
1KXMODEMG	4	Required	Required
YMODEM	5	Not required	Required
YMODEMG	6	Not required	Required
CISB	7	Not required	Not required
ASCII	8	Required	Required
RAWASCII	9	Required	Required
IND$FILE	n/a  (see below)	Two required	Two required
The Ind$file protocol is shipped as a .dlp, meaning that it does not have an associated index value.

For further information on protocol use, please refer to the descriptions for the getfile command and the sendfile command.

Emulations and protocols that are shipped with Procomm Plus as Dynamic Linked Libraries do not have associated index values. For convenience, ASPECT provides reserved keyword names for these .dlt (Dynamic Linked Terminal) and .dlp (Dynamic Linked Protocol) modules such as the RIPscrip terminal and the Ind$file file transfer protocol. For best results, you should use the module's keyword or string name whenever a protocol or emulation name is required.


Protocol Set/Fetch Statements
Xmodem, 1K-Xmodem, 1K-Xmodem-G, Ymodem and Ymodem-G Protocol Set/Fetch Statements

The following set/fetch statements are general commands for the Xmodem, 1K-Xmodem, 1K-Xmodem-G, Ymodem and Ymodem-G protocols. They correspond to options in Setup, Transfer Protocol, with the Current Protocol set to the transfer protocol specified by the protocol parameter. For example, to enable the overwrite option for Xmodem, use set xmodem overwrite ON.

protocol abortdnld KEEP | DELETE

Determines whether aborted file transfers are kept or deleted. This command corresponds to the Delete aborted downloads check box for the listed protocols. fetch returns 0 for KEEP or 1 for DELETE.

protocol overwrite OFF | ON

Determines how filename collisions are handled for the specified protocol. This command corresponds to the Overwrite existing file check box for the listed protocols. fetch returns 0 for OFF or 1 for ON.

protocol relaxed OFF | ON

Enables or disables relaxed timing for the specified protocol. This command corresponds to the Use relaxed protocol timing check box for the listed protocols. fetch returns 0 for OFF or 1 for ON.


RAWASCII Protocol Set/Fetch Statements

The following set/fetch statements apply to the Raw ASCII transfer protocol. These commands correspond to options in Setup, Data, Transfer Protocol, with the Current Protocol set to RAWASCII.

rawascii abortdnld KEEP | DELETE

Determines whether files aborted during a Raw ASCII download are kept or deleted. This command corresponds to the Delete aborted downloads check box. fetch returns 0 for KEEP or 1 for DELETE.

rawascii charpace integer

Specifies the length of the pause between characters during a Raw ASCII upload. This command corresponds to the Millisecond delay between characters field. fetch returns the current character pacing.

rawascii dnld display OFF | ON

Determines whether data is displayed as it is received during a Raw ASCII download. This command corresponds to the Download Options Display text check box. fetch returns 0 for OFF or 1 for ON.

rawascii linepace integer

Specifies the length of the pause between lines during a Raw ASCII upload. This command corresponds to the Millisecond delay between lines field. fetch returns the current line pacing.

rawascii overwrite OFF | ON

Determines how filename collisions are handled during Raw ASCII file transfers. This command corresponds to the Overwrite existing file check box. fetch returns 0 for OFF or 1 for ON.

rawascii pacechar character

Specifies the pace character for Raw ASCII uploads. This command corresponds to the Use X for Line pace character edit field. fetch returns the value of the Raw ASCII upload pacing character.

rawascii timeout integer

Specifies the number of seconds that Procomm Plus waits for incoming information during a Raw ASCII file download before closing the transfer as completed. This command corresponds to the Seconds until download time-out edit field. fetch returns the current download time-out value.

rawascii upld display OFF | ON

Specifies whether data is displayed as it is sent during a Raw ASCII upload. This command corresponds to the Upload Options, Display text check box. fetch returns 0 for OFF or 1 for ON.

rawascii usepacechar OFF| ON

Specifies whether the Raw ASCII protocol uses the specified pace character to control a Raw ASCII upload. This command corresponds to the Use x for Line pace character check box. fetch returns 0 for NO or 1 for YES.


RIP Set/Fetch Statements

rip filetype BITMAP | TEXT

Controls the operation of Edit Screen to Clipboard and Edit Screen to File menu items. When set to BITMAP, the entire current terminal screen will be copied as a bitmap. If TEXT is selected, the text portions of the screen will be copied as text. This command corresponds to the Screen to File/Clipboard options radio group in the Ripscrip Advanced Setup dialog.

rip font index

Specifies which font Procomm Plus will display when using the RIP emulation. Index is an integer from 0 to 4 which corresponds to the option buttons in the Initial Text Window Font section of the Setup, Data, Terminal Options, RIPscrip Advanced Setup dialog. fetch will return the currently selected font.

rip hotkeys OFF | ON

Specifies the initial setting for button hotkeys. This command corresponds to the Enable button Hotkeys check box in the Ripscript Advanced Setup dialog. Button hotkeys must still be set by the host, and the host may enable or disable this item at any time. fetch will return a 0 if it is disabled, or a 1 if it is enabled.

rip iconpath pathname

Specifies the path Procomm Plus will use to locate the RIP icons. This command corresponds to the RIP Icons path field in the Setup, Data, Terminal Options, RIPscrip Advanced Setup dialog. fetch will return the current path.

rip print BITMAP | TEXT

Controls the printing method used in the RIP emulation. This command corresponds to the Screen to Printer printing options radio group in the RipScript Advanced Setup dialog. When set to BITMAP, the entire current terminal screen will be printed as a graphical image. If TEXT is selected, only the text portions of the screen will be sent to the printer.

rip security OFF | ON

Enables or disables Data Security for the RIP emulation. This command corresponds to the Enable Data Security check box in the Setup, Data, Terminal Options, RIPscrip Advanced Setup dialog. fetch will return a 0 if it is disabled, or a 1 if it is enabled.

rip tabkey OFF | ON

Specifies the action of the tabkey within the RIP emulation. This command corresponds to the Tab key controls button focus check box in the RipScript Advanced Setup dialog.When set to OFF, the tabkey sends a tab character (ASCII 0x09). When set to ON, the tab key moves the on-screen highlight from control to control. fetch will return a 0 if it is OFF, or a 1 if it is ON.

rip variable string string | DELETE

Specifies additional text variables for the Text Variable Database. The first string specifies the name for the Text Variable and the second string specifies the contents. This command corresponds to the Name: and Contents: fields in the Setup, Data, Terminal Options, RIPscrip Advanced Setup, Text Variable Database, Create Text Variable dialog. DELETE will remove a variable from the database. fetch will return the contents of the variable.


Remote Command Format

  Related Topics

Procomm Plus allows a remote user to execute ASPECT script commands. This makes it possible for you to control your PC from a distant location and perform a wide variety of tasks.

Remote commands are sent from another computer with the sequence:

Ctrl-D [password][command [Ctrl-J command] ...] Ctrl-D [command [Ctrl-J] ]

where Ctrl-D (or ^D) = decimal 4 and Ctrl-J (or ^J) = decimal 10, and "command" is a valid ASPECT command.

If you need to cancel a remote command, you can do so by entering a Ctrl-X (or ^X), decimal 24 at any time before the trailing Ctrl-D.

Multiple ASPECT commands may be sent in a single remote command, separated by the Ctrl-J character; a remote command terminates with the second Ctrl-D character.

Problems can occur if a remote command is sent to the receiving system before a previous remote command has completed. To avoid this complication, consider pairing remote commands with a set aspect rxdata on remote command. This allows the receiving system to hold in-coming data for processing after the remote command has completed rather than while the command is executing. This solution is effective as long as the remote script commands are not themselves retrieving incoming data.

The receiving system will wait up to 10 seconds between any two characters to allow ample time for a user who is entering the commands manually. The backspace character is acknowledged by the receiving system to correct errors, but only to the beginning of the current line (the last Ctrl-J). Also, the remote system will accept the carriage return (ASCII 13) and interpret it to mean a carriage return followed by a Ctrl-J. Therefore, a user can enter a command, press <Enter>, enter another command, press <Enter>, and so forth, until terminating the remote command with a Ctrl-D.

A remote command is compiled just as any other ASPECT script. The remote command processor automatically places the command list between the two required ASPECT syntax lines proc main and endproc. After the remote command is received, compiled and executed, any source and target script files that were generated will be removed from the remote system.

For example, to force your system to disconnect, a remote computer might send Ctrl-D hangup Ctrl-D.

To send this same command from a script file, the ^D must be translated. The command would be:

transmit "^Dhangup^D"

Entering remote commands manually can be tedious; you can use Meta Keys to send the same commands repeatedly. Another way to send many commands is to start the remote processor by hitting Ctrl-D, transmit an ASPECT script using an ASCII file transfer, and follow the transmission with the terminating Ctrl-D. If the script has procedures in it, however, the remote processor will still assume an initial proc main and endproc.

To accommodate this situation, the remote command processor will define a macro named REMOTEASP to be automatically passed to the ASPECT Compiler. The script's existing proc main and endproc can easily be handled with conditional compilation.

To modify an existing script for use as a remote command script, add the following lines to the top of the script:

#ifdef REMOTEASP        ; If compiling script as remote command

#define MAIN MYMAIN     ; Redefine MAIN procedure as MYMAIN

MYMAIN()             ; Call my renamed MAIN procedure

ENDPROC                 ; Terminate remote command file’s PROC MAIN

Then, add the following to the end of the script, outside of any existing function or procedure:

#ifdef REMOTEASP        ; If compiling script as remote command

proc REMOTEDUMMY        ; Begin definition of ‘dummy’ procedure

#endif

This remote capability will work with all terminal emulations, but to use them you must enable the Remote script commands check box in the System, System Options, Advanced Options panel in Setup. If you enable the check box, you can also specify a password.

For an easier way to send a complete script as a set of remote commands, see the remcmd.wax script, installed by default in the \procomm plus\aspect directory. It is self-documenting.

The optional password may be up to 8 characters long. It must match the receiving system’s password exactly, including case. If the password does not match, the remote command will be aborted immediately. After three such failures have occurred, remote commands will be disabled automatically.

For backwards compatibility to version 1.0x of Procomm Plus, where remote commands were terminated with the receipt of the first carriage return, a pw4.ini entry can be made forcing the remote command processor to revert to this less capable implementation. To use the older format of the remote commands, add the lines:

[Options]

RemoteCmdCR = 1

to the end of the pw4.ini file. If the [Options] section already exists in pw4.ini, just add the second line immediately after it. A value of 0 for this entry will re-enable the version 2- and 3-style remote command support.


Reserved Symbols

  Related Topics

The following symbols are reserved in ASPECT:

!	!=	#	$	%	%=	&
&&	&=	(	)	*	*=	+
++	+=	’	-	--	-=	/
/=	:	;	<	<<	<<=	<=
=	==	>	>=	>>	>>=	?
[	]	^	^=	|	|=	||
~	\


Reserved Words

  Related Topics

The following reserved words are organized alphabetically into groups. Select a character to view the section of reserved words which begin with that respective character.

#

#COMMENT

#DEFINE

#ELIFDEF

#ELIFNDEF

#ENDCOMMENT

#IFDEF

#IFNDEF

#INCLUDE

#UNDEF

$

$ACTIONBAR

$ACTIONBARS

$ACTIVEWIN

$ASPECTPATH

$ASPMENU

$CALLERID

$CAPTURE

$CARRIER

$CHAINEDFILE

$CHATWIN

$CNCTMSG

$COL

$CTS

$DATAOPTIONS

$DATE

$DDEADVISE

$DDIRFNAME

$DIALCHANGED

$DIALCONNECT

$DIALDIR

$DIALENTRY

$DIALING

$DIALQUEUE

$DIALSELECT

$DTR

$ERRORNUM

$EXITCODE

$FATTR

$FAXFILE

$FAXMESSAGE

$FAXOPTIONS

$FAXRECVCNT

$FAXSENDCNT

$FAXSTATUS

$FDATE

$FEXT

$FILENAME

$FILESPEC

$FLOWSTATE

$FLTIME

$FNAME

$FOCUSWIN

$FSIZE

$FTIME

$FTPCONNECT

$FTPOPTIONS

$FTPSTATUS

$IPADDRESS

$KEYHIT

$LMOUSEEVENT

$LMOUSESTATE

$LMOUSEWIN

$LMOUSEX

$LMOUSEY

$LTIME

$MAILOPTIONS

$MAINWIN

$MAPIENABLED

$MCIDEVICEID

$MCINOTIFY

$METAKEYS

$MISC

$MMOUSEEVENT

$MMOUSESTATE

$MMOUSEWIN

$MMOUSEX

$MMOUSEY

$MODEMCONNECT

$MONITORWIN

$NEWSOPTIONS

$NULLSTR

$NUMCOLORS

$NUMTASKS

$OBJECT

$OS

$OSVER

$PARENTFILE

$PASSWORD

$PKRECV

$PKSEND

$PLAYBACK

$POINTERTASK

$POINTERWIN

$POINTERX

$POINTERY

$PROTOCOL

$PWACTIVE

$PWLOCALPATH

$PWMAINWIN

$PWMENUBAR

$PWMENUDEF

$PWMODE

$PWTASK

$PWTASKPATH

$PWTITLEBAR

$PWVER

$PWWINSTATE

$QUICKSELECT

$RMOUSEEVENT

$RMOUSESTATE

$RMOUSEWIN

$RMOUSEX

$RMOUSEY

$ROW

$RTS

$RXCOUNT

$RXDATA

$SCRIPTENV

$SCRIPTFILE

$SCRIPTMODE

$SCROLLBACK

$SERIALNUM

$SETUP

$STATIONID

$STATMSG

$STATUSLINE

$TASK

$TELNETOPTIONS

$TERMCOLORS

$TERMCOLS

$TERMFONT

$TERMINAL

$TERMROWS

$TIME

$TIME24

$TITLEBAR

$TXCOUNT

$TXDATA

$USERDISK

$USERDISKSTR

$USERID

$USERNAME

$USERPATH

$USERWIN

$UWINACTIVE

$VOLUME

$WINCOLORS

$WINMODE

$WINPATH

$XFERFILE

$XFERSTATUS

$XOFFRECV

$XOFFSENT

$XPIXELS

$YPIXELS

1

1KXMODEM

1KXMODEMG

2

2KWINDOW

4

4KWINDOW

A

ABORTDNLD

ABORTRETRY

ACCESS

ACTION

ACTIONBAR

ADAPTIVE19200

ADAPTIVEANS

ADDCALLINFO

ADDFILENAME

ADDRESS

ADDS60

ADDS90

ADM31

ADM3A

ADM5

ALARM

ALARMTIME

ALT

ALTCTRL

ALTCTRLSHIFT

ALTERNATE

ALTSHIFT

ALWAYS

ANONYMOUSLOGON

ANSIBBS

ANSITOKEY

ANSITOOEM

ANSRINGS

APPEND

AREACODE

ASCII

ASCIIXLAT

ASPDEBUG

ASPECT

ASPECTPATH

ASPFILE

ASPLINE

ASPMENU

ASPVERSION

ATOF

ATOI

ATOL

ATT4410

ATT605

ATTRIBUTE

AUTO

AUTOANSOFF

AUTOANSWER

AUTOBAUD

AUTODNLD

AUTOLOGON

AUTORELIABLE

AUTOSIZE

AUTOSTART

B

BACKGROUND

BACKSPACE

BAUDRATE

BEEP

BEGIN

BETWEENCALLS

BINARY

BINARYMODE

BIT8MODE

BIT8QUOTE

BITMAP

BITMAPBKG

BLANKEXPAND

BLINKRATE

BLOCK

BLOCKCHECK

BLOCKCURSOR

BLOCKMODE

BLOCKSTART

BOLD

BOTTOM

BREAK

BREAKLEN

BREAKPOINT

BY

C

CALL

CALLERID

CALLERIDOFF

CALLTYPE

CALLWAITING

CALLWAITOFF

CANCEL

CAPTURE

CAPTURESTR

CARDNUM

CASE

CDINXFER

CEIL

CELLULAR

CENTER

CHAIN

CHARACTER

CHARPACE

CHARSET

CHATMODE

CHDIR

CHECKBOX

CISB

CLASS

CLASS1

CLASS2

CLEAR

CLEARXOFF

CLIPBOARD

CLIPCHAR

CLIPFILERMV

CLIPTOFILE

CLIPTOSTR

CLOSE

CLOSED

CMDSUFFIX

CNCTMSG

CODE

CODEPAGE

COLORS

COLUMNS

COM1

COM2

COM3

COM4

COM5

COM6

COM7

COM8

COM9

COMBOBOX

COMGETC

COMPANY

COMPILE

COMPLETE

COMPLETED

COMPUTC

COMREAD

COMWRITE

CONNECT

CONNECTALL

CONNECTED

CONNECTION

CONNECTMANUAL

CONTENTS

CONTROL

CONVENTIONAL

CONVERTER

COPYFILE

COUNTRYCODE

COVERSHEET

CR

CRASHRECOVER

CRC

CRC16

CRC32

CREATE

CRLFXLAT

CRLF_ETX

CR_LF

CSLIPCOMPRESS

CTRL

CTRLQUOTE

CTRLSHIFT

CURRENT

CURSORKEYAPP

CURSORPOS

D

DATA

DATABASE

DATABITS

DATAFAX

DATAKEY

DATE

DBLCLICK

DDEADVISE

DDEEXECUTE

DDEINIT

DDEPOKE

DDEREQUEST

DDETERMINATE

DDEUNADVISE

DEC

DECIMAL

DECLINEWRAP

DECRYPT

DEFAULT

DELAY

DELETE

DELFILE

DELLINE

DELPAGES

DEST

DEVICE

DGD100

DGD200

DGD210

DIAL

DIALACALWAYS

DIALACFORLD

DIALADD

DIALCANCEL

DIALCLASS

DIALCMD

DIALCOUNT

DIALCREATE

DIALDELETE

DIALDIR

DIALED

DIALENTRY

DIALFIND

DIALINGBOX

DIALINSERT

DIALLOAD

DIALNAME

DIALNUMBER

DIALOG

DIALOGBOX

DIALSAVE

DIALSPEED

DIALSTATS

DIM

DIR

DIRECT

DIRLISTBOX

DIRPATH

DISABLE

DISABLED

DISCONNECT

DISK

DISKFREE

DISPLAY

DISTINCTRING

DLGCTRL

DLGCTRLWIN

DLGDESTROY

DLGEVENT

DLGLIST

DLGSAVE

DLGSHOW

DLGUPDATE

DLGWIN

DLGWINCTRL

DLLCALL

DLLFREE

DLLLOAD

DLLOBJECT

DLLOBJFILE

DLLOBJUPDT

DNLD

DNLDPATH

DNLDPROMPT

DNSADDRESS

DOS

DOWNTO

DROPDOWN

DROPDOWNLIST

DROPDTR

DUPLEX

DYNAMIC

E

ECHO

ECM

EDITBOX

EDITOR

ELAPSED

ELSE

ELSEIF

ENABLE

ENCRYPT

ENDCASE

ENDDIALOG

ENDFOR

ENDFUNC

ENDGROUP

ENDIF

ENDPROC

ENDSEQUENCE

ENDSWITCH

ENDWHILE

ENQUIRY

ENQUIRYSTR

ENTERCRLF

ENTERKEY

ENTRY

ENTRYNUM

ENVIRONMENT

EOLCHAR

EOLCONVERT

EOLSTR

EOT

ERRORCORRECT

ERRORDETECT

ERRORMSG

ESCAPEM

ESPRIT3

ETX

EVEN

EXACT

EXCLAMATION

EXECUTE

EXIT

EXITFOR

EXITSWITCH

EXITWHILE

EXITWINDOWS

EXPAND

EXTENDED

F

F0

F1

F2

F3

F4

F5

F6

F7

F8

F9

FAILURE

FAST

FAX

FAXCANCEL

FAXLIST

FAXMODEM

FAXNUMBER

FAXPOLL

FAXPRINT

FAXREMOVE

FAXSEND

FAXSTATUS

FAXVIEW

FCLEAR

FCLOSE

FCOMBOBOX

FDELBLOCK

FEDITBOX

FEOF

FERROR

FETCH

FFLUSH

FGETC

FGETS

FILE

FILEGET

FILELIST

FILESET

FILETOCLIP

FILETYPE

FILEVIEW

FILEXFER

FILEXFERBOX

FILTER

FILTERED

FINDFIRST

FINDNEXT

FINISH

FINSBLOCK

FIRST

FIRSTTASK

FIXED

FLENGTH

FLISTBOX

FLOAT

FLOOR

FLOWCONTROL

FLUSH

FONT

FONTNAME

FONTSIZE

FOOTER

FOPEN

FOR

FOREVER

FPUTC

FPUTS

FRAME

FREAD

FSEEK

FSTRFMT

FTELL

FTEXT

FTOA

FTP

FTRUNCATE

FULL

FULLPATH

FUNC

FWRITE

G

GETCUR

GETDIR

GETENV

GETFILE

GETFILENAME

GETPATHNAME

GETVOLUME

GLOBAL

GOTO

GROUP

GROUPBOX

H

HALF

HALT

HANGUP

HARDFLOW

HARDWARE

HEADER

HEATH19

HELP

HELPFILE

HIDDEN

HIGH

HOLD

HOMEPAGE

HOST

HOSTDIR

HOSTPRINT

HOSTTYPE

HOTKEYS

HOTSPOT

HSCROLL

HTML

I

I0

I1

I2

I3

I4

I5

I6

I7

I8

I9

IBM3101

IBM3161

IBM3270

IBMPC

ICON

ICONBUTTON

ICONFLASH

ICONPATH

IF

INBOX

INCNCTLIST

INCREMENTAL

IND$FILE

INFORMATION

INIT

INSERT

INTEGER

INTERNAL

INTERNET

INTL

INTLPREFIX

INTO

INTSLTIME

IPADDRESS

IPADDRESSTYPE

IPPORT

ISFILE

ISKEY

ISO

ITALIC

ITEM

ITEMCOUNT

ITEMCREATE

ITEMFIND

ITEMNAME

ITEMREMOVE

ITOA

K

KEEP

KERMIT

KERMSERVE

KEYBOARDFILE

KEYFLUSH

KEYGET

KEYPADAPP

KEYS

KEYSTATE

KEYTOANSI

KEYTOOEM

L

L0

L1

L2

L3

L4

L5

L6

L7

L8

L9

LANDSCAPE

LDLINEOUT

LDPREFIX

LEFT

LENGTH

LF

LINEPACE

LINETYPE

LINEWRAP

LISTBOX

LMOUSE

LOCAL

LOCALDIR

LOCATE

LOCKED

LOCLINEOUT

LOGGING

LOGONNAME

LOGONTIMEOUT

LOGOUT

LONG

LONGDISTANCE

LONGFILENAME

LONGJMP

LOOPFOR

LOOPWHILE

LOW

LRECL

LTIME

LTIMEELAPSED

LTIMEINTS

LTIMEMISC

LTIMESTRING

LTIMESTRS

LTOA

M

MAIL

MAKEPATH

MANAGER

MAPISEND

MARGINS

MARK

MASKED

MATCHCASE

MAXIMIZED

MAXLENGTH

MCIEXEC

MCISEND

MEDIUM

MEMADDRESS

MEMALLOC

MEMAVAIL

MEMCHR

MEMCMP

MEMFREE

MEMGETC

MEMICMP

MEMLOAD

MEMMOVE

MEMO

MEMORY

MEMPUTC

MEMREAD

MEMREALLOC

MEMSET

MEMSIZE

MEMTOTAL

MEMWRITE

MENU

MENUBAR

MENUCHECK

MENUITEM

MENUITEMCOUNT

MENUPOPUP

MENUPOPUPID

MENUSELECT

MENUSHOW

MENUSHOWPOPUP

MENUSTATE

METAFILE

METAFILEBKG

METAKEY

METAKEYFILE

METAKEYS

METHOD

MINIMIZED

MISC

MISCNUM

MKDIR

MNP4

MNP5

MODE

MODEM

MONTHSTR

MOUSECOORD

MSPAUSE

MULTILINE

MULTIPLE

MULTIPLECONNECT

MUSIC

MVS_TSO

N

NAMEPREFIX

NEGOTIATE

NEGOTIATION

NEVER

NEWER

NEWS

NEXT

NEXTTASK

NO

NOCNCTMSG

NOERRORCORRECT

NONCONTIG

NONDEST

NONE

NOPAINT

NORMAL

NOT

NOTES

NOTESFILE

NOTESPATH

NULLSTR

NULLSUPPRESS

NUMBERPREFIX

NUMTOSTR

O

OBJCOORD

OBJHIDE

OBJMOVE

OBJPAINT

OBJPOINTID

OBJREMOVE

OBJSHOW

ODD

OEMTOANSI

OEMTOKEY

OFF

OFFDIAL

OFFSET

OK

OKCANCEL

ON

ONCE

ONUNTILCD

ONVERIFY

OPEN

OPTIONS

ORGANIZATION

ORIENTATION

ORIGTIME

OTHER

OUTBOX

OVERWRITE

P

PACECHAR

PACELINES

PACING

PACKETSIZE

PADCHAR

PADNUM

PAGENUMBERS

PAGEUPDATE

PAGING

PARAM

PARENT

PARITY

PASSIVEMODE

PASSWORD

PASTETEXT

PATH

PATTERN

PAUSE

PAUSECHAR

PERMANENT

PHONECARD

PHONENUMBER

PHYSICAL

PINNUM

PIXELS

PKMODE

PKRECV

PKSEND

PLAYBACK

PLAYBACKPACE

POPUP

PORT

PORTRAIT

PPP

PREFIX

PRINT

PRINTALIGN

PRINTATTR

PRINTCAPTURE

PRINTCHAR

PRINTER

PRINTFIT

PRINTFONT

PRINTMARGIN

PRINTSTR

PRINTTABS

PRINTTABSTR

PROC

PROFILERD

PROFILEWR

PROGRAM

PROMPT

PROPRIETARY

PROTECT

PROTECTATTR

PROTOCOL

PULSE

PUSHBUTTON

PUTENV

PWEXIT

PWMENU

PWMODE

PWTITLEBAR

Q

QUERY

QUESTION

QUICKOPTION

QUICKSELECT

QUIET

R

RADIOBUTTON

RADIOGROUP

RAND

RAW

RAWASCII

RAWPRINT

READ

READAPPEND

READWRITE

REBOOT

RECEIVE

RECEIVED

RECEIVER

RECFM

RECORDMODE

RECVBAUD

RECVCMD

RECVPRINT

RECVVIEW

RECYCLE

RELAXED

REMOTE

REMOTECMD

REMOVE

RENAME

REPAINT

REPLYADDRESS

RESET

RESTART

RESTORE

RESUME

RETAINFILES

RETRIES

RETRYCANCEL

RETRYDELAY

RETURN

REVERSE

REVERSEBIT

REWIND

RGET

RGETCHAR

RIGHT

RINGMSG

RIP

RMDIR

RMOUSE

RMVPOLLED

ROWS

RSTRCMP

RUN

RXCR

RXDATA

RXFLUSH

S

S0

S1

S2

S3

S4

S5

S6

S7

S7CMD

S8

S9

SAVE

SBBUFFER

SBPAGES

SBSAVE

SCALE

SCHEDULED

SCREEN

SCREENTOWIN

SCRIPTFILE

SCRIPTPATH

SCRIPTSTART

SCROLL

SCROLLMETHOD

SDLGFOPEN

SDLGINPUT

SDLGMSGBOX

SDLGSAVEAS

SEARCH

SECURITY

SELECT

SEND

SENDCMD

SENDCR

SENDER

SENDFILE

SENDKEY

SENDKEYSTR

SENDPOLLED

SENDVKEY

SENT

SEPARATOR

SERVERADDRESS

SERVICENUM

SET

SETJMP

SETPOINTER

SETUP

SHARED

SHELL

SHIFT

SHORT

SHOWFAXSTATUS

SIERRA

SIGNATUREFILE

SIMPLE

SINGLE

SIZE

SIZEOF

SKIP

SLIP

SLOW

SNAPSHOT

SOFTFLOW

SOFTWARE

SORT

SPACE

SPAWN

SPEAKER

SPLITPATH

STATCLEAR

STATIONID

STATMSG

STATUSATTR

STATUSLINE

STOP

STOPBITS

STRCAT

STRCHR

STRCMP

STRCPY

STRCSPN

STRDELETE

STREAMING

STREXTRACT

STRFIND

STRFMT

STRGETC

STRICMP

STRING

STRINSERT

STRIP

STRIPBIT8

STRLEN

STRLWR

STRNCMP

STRNICMP

STRPUTC

STRQUOTE

STRRCHR

STRREAD

STRREPLACE

STRREV

STRRIGHT

STRSEARCH

STRSET

STRSLTIME

STRSPN

STRTOCLIP

STRTOK

STRTONUM

STRUPDT

STRUPR

STRWRITE

STYLE

SUBNETMASK

SUBSTR

SUCCESS

SUFFIX

SUSPEND

SWITCH

T

TABEXPAND

TABKEY

TABSTOPS

TARGET

TASKACTIVATE

TASKEXISTS

TASKEXIT

TASKNAME

TASKPATH

TASKWIN

TELNET

TERMCOLORS

TERMFONT

TERMGETC

TERMGETS

TERMINAL

TERMINALID

TERMKEY

TERMMSG

TERMPUTC

TERMPUTS

TERMREADC

TERMREADS

TERMRESET

TERMVKEY

TERMWRITEC

TERMWRITES

TEXT

TIGHT

TILED

TIME

TIMEOUT

TIMESTAMP

TIMING

TONE

TOOLTIPS

TOP

TOPIC

TRANSLATE

TRANSMIT

TTY

TURNCHAR

TVI910

TVI912

TVI920

TVI922

TVI925

TVI950

TVI955

TXFLUSH

TXMETHOD

TXPACE

TYPE

U

UNDERLINE

UNSELECT

UNTIL

UPDATE

UPLD

UPLDPACE

UPLDPATH

UPTO

USELRECL

USEPACECHAR

USEPHONECARD

USERECFM

USEREXIT

USERID

USERMSG

USERNAME

USERWIN

US_CR

UWINCREATE

UWINPAINT

UWINREMOVE

UWUS

UWUTOWIN

V

V23

V42

VARIABLE

VIDTEX

VIEWCURSOR

VIEWGIF

VIEWGRAPHICS

VIRTUAL

VISUAL

VM_CMS

VOICE

VOICENUMBER

VOLUME

VT100

VT102

VT220

VT320

VT52

W

WAITCNCT

WAITFOR

WAITQUIET

WAITUNTIL

WAVEFILE

WEEKDAYSTR

WHEN

WHENSUSPEND

WHENTARGET

WHILE

WINACTIVATE

WINCLOSE

WINCOLORS

WINCOORD

WINDOW

WINENABLED

WINEXISTS

WINFOCUS

WINHIDE

WINMAXIMIZE

WINMINIMIZE

WINMOVE

WINOWNER

WINRESTORE

WINSHOW

WINSIZE

WINSTATE

WINTASK

WINTEXT

WINTOSCREEN

WINTOUWU

WINVISIBLE

WITH

WORD

WRITE

WYSE100

WYSE50

WYSE60

WYSE75

X

XFERCANCEL

XFERMODE

XFERYIELD

XLATIN

XLATOUT

XLATSTR

XMITBAUD

XMODEM

XOFF

XWINDOW

Y

YES

YESNO

YESNOCANCEL

YIELD

YMODEM

YMODEMG

Z

ZMODEM


Running Scripts

  Related Topics

You can run a script in many different ways:

•	By selecting it from the Action Bar’s Script File drop-down list box.

Click on the Action Bar’s Script File drop-down list box, which displays the compiled scripts found in the default script directory. Click on the script name you wish to run, and Procomm Plus will execute it.

If the script you want to run is already displayed in the Script File list box, you can run it by double-clicking on the list box, or by clicking the Action Bar’s Run Script icon.

•	By selecting it from the Run ASPECT File dialog.

Select Tools | Scripts | Run... to open the dialog, then select your script and click on OK. Note that only scripts that have successfully compiled will be available in this dialog.

•	By selecting it from the Compile/Edit ASPECT File dialog.

Select Tools | Scripts | Compile/Edit... to open the dialog, then select your script and click on Compile and Run. Procomm Plus will attempt to compile you’re selection, and run it automatically if the compilation succeeds.

•	By associating it with a Connection Directory entry.

If you specify a script in a Connection Directory entry’s Script field, it will be executed automatically each time you call that entry.

•	By clicking on a Run Script Action Bar button.

If you’ve configured a custom Action Bar button as a Run Script button, you can launch its associated script with a single click.

•	By pressing a Run Script Meta Key.

If you’ve configured a Meta Key as a Run Script button, you can launch its associated script with the touch of a key or a single mouse click.

•	By pressing a Run Script Terminal key.

If you’ve configured a mappable key as a Run Script key, you can launch its associated script with the press of a key.

•	By launching it from another script.

To run a script from within another script, you can use either the execute or chain command. The launched script can even share information with the called scripts using the pre-defined global variables, open files and allocated memory!

For more information, see Script Spawning and Chaining. You may also want to see the descriptions of the chain and execute commands.

•	By naming it startup.wax.

Each time it launches, Procomm Plus searches your script directory for a compiled script with this special name. If it finds the file, Procomm Plus executes it automatically.

•	By adding it to the Procomm Plus's command line in the Start menu group.

The script argument can be used alone, or with up to 10 arguments which will be passed to the script as values for the pre-defined string variables S0 through S9. You must specify either a .was or .wax extension.

After it has initialized, Procomm Plus executes the script immediately.

The script can determine how it was started by testing the value of the $SCRIPTMODE system variable. It can also determine the number of command-line arguments by testing the value of the pre-defined I0 integer variable. As an example, you could specify the compiled ASPECT script dialout.wax to run automatically, initializing S0 to "DIALFAST" with the command:

win PW4 dialout.wax "DIALFAST" <Enter>

•	By using a Dynamic Data Exchange (DDE) command from another application.

Procomm Plus can run a script automatically when it's acting as a DDE server. It can also return values through its pre-defined global variables via DDE. For more information, see Procomm Plus as a DDE Server.

•	By using a remote ASPECT command.

If you’re connected to a computer that is also running Procomm Plus, you can launch a script on that machine by transmitting a remote ASPECT command. The following sequence, received by Procomm Plus, will run the script remote.wax:

<Ctrl><D> execute "REMOTE.WAX" <Ctrl><D>

<Ctrl><D> in the example above represents the decimal 4 value ASCII character. For more information, see Using Remote ASPECT Commands.

•	By specifying it as a response to Caller ID.

Procomm Plus can launch a script in response to Caller ID.

•	By specifying it as a task in the Procomm Plus Scheduler.

Scripts can be scheduled to run as automatic tasks..

While a script is running, the Tools | Scripts | Run Script item changes to Stop Script. You can select the Stop Script command, or click on the Action Bar Run Run Script icon to end script execution.


SUCCESS and FAILURE

  Related Topics

ASPECT commands which set SUCCESS and FAILURE are indicated by an "S/F" bullet in their command description.

FAILURE

Indicates whether the last testable ASPECT command did not complete successfully. FAILURE evaluates to 1 or true if the last operation failed, 0 otherwise. The FAILURE variable always contains the opposite value of SUCCESS.

SUCCESS

Indicates whether the last testable ASPECT command completed successfully. SUCCESS contains the value 1 for true or 0 for false. The SUCCESS variable always contains the opposite value of FAILURE.


SUCCESS and FAILURE System Variables

  Related Topics

A number of ASPECT script commands set the value of two special global system variables, SUCCESS and FAILURE. They can have the value of either 1 for TRUE or 0 for FALSE. If a command executes successfully, the value of SUCCESS is 1 and FAILURE is 0. If a command fails, the value of SUCCESS is 0 and FAILURE is 1. SUCCESS and FAILURE are used in conditional expressions:

   if SUCCESS                  ; Meaning "if SUCCESS is set to 1".

      ;           .

      ;           .            ; Do something.

      ;           .

   endif

A typical use of SUCCESS and FAILURE is after waitfor commands:

proc main

   waitfor "CONNECT 2400" 60      ; Wait 60 seconds for a connect

                                  ; message to appear at the port.

   if FAILURE                     ; If the waitfor doesn’t succeed

      usermsg "Try again later!"  ; let the user know.

   endif

endproc

Another interesting use of SUCCESS and FAILURE is after a file transfer command, either sendfile or getfile, to see if the transfer started:

proc Xfer

   sendfile zmodem "abc.zip"      ; Send the file abc.zip by zmodem.

   if SUCCESS                     ; If the sendfile is successful, say so

      usermsg "Transmitting file..."

   else

      usermsg "Sorry - try again!"

      ; Otherwise, put up error message.

   endif

endproc

ASPECT even allows an abbreviation of this status-checking method. Any command that sets SUCCESS and FAILURE may be used directly in a conditional expression. The value that is returned to SUCCESS and FAILURE is returned to the conditional; you don’t have to explicitly check the variable. For example:

proc main

   if not waitfor "CONNECT 2400" 60

      ; Wait for a connect message.

      usermsg "Try again later!"      ; If one isn’t received, display

   endif                              ; an error message.

endproc

Exercise

Browse through the commands using the Help "browse" buttons and look for commands that set the SUCCESS and FAILURE system variables.Commands that set SUCCESS and FAILURE have their descriptions specially marked with an "S/F" bullet:

Write a simple logon script in such a way that it provides some error-checking by using these system variables or by using the commands in conditional expressions.


SUCCESS and FAILURE popup
SUCCESS and FAILURE

ASPECT commands which set SUCCESS and FAILURE are indicated by a [image] in their command description.

FAILURE

Indicates whether the last testable ASPECT command did not complete successfully. FAILURE evaluates to 1 or true if the last operation failed, 0 otherwise. The FAILURE variable always contains the opposite value of SUCCESS.

SUCCESS

Indicates whether the last testable ASPECT command completed successfully. SUCCESS contains the value 1 for true or 0 for false. The SUCCESS variable always contains the opposite value of FAILURE.


Script Control Commands

breakpoint	Interrupts execution of a script file and displays the Debug window.

chain	Executes another ASPECT script.

compile	Executes the ASPECT Compiler upon a target source file.

execute	Executes another ASPECT script.

exit	Terminates the executing script.

halt	Terminates the executing script and any parent scripts unconditionally.

longjmp	Returns to a previously marked setjmp location.

setjmp	Marks a location within a script that execution can immediately branch to using the longjmp command.

yield	Suspends script execution, allowing other tasks in Procomm Plus to continue execution until ASPECT is permitted to resume by the system.

 Return to category list


Script Record Mode

  Related Topics

Many script applications are straightforward. For example, scripts that automate logons or file transfers are usually simple sets of keystrokes that are repeated each session. For these repetitive procedures, use Record mode to save each prompt from the host system and each keystroke you type as script commands in an ASPECT source file. Once the file has been compiled, you can use it to perform that same procedure automatically!

Recording a Script

To record a script, follow these steps:

1.	Prepare the host or remote system for the task you want the script to perform.

To create scripts, the Script Recorder "watches" the characters you type and the information the host transmits in response. You’ll need to activate the recorder just before you begin the activity you want the script to reproduce for you.

For example, if you’re recording a logon script for a BBS, you’d want to start the recorder before connecting to the system so that the recorder could "see" the entire logon process.

2.	Start the Script Recorder.

Select Tools | Scripts | Start Recorder from the menu, or click on the Action Bar’s Recorder button. After the Script Recorder is started, the Start Recorder menu command changes to Stop Recorder. The Recorder  button remains depressed while the Script Recorder is running.

3.	Complete the procedure you wish to record.

If you’re connecting to a BBS, respond to its prompts and menus just as you would normally. When you’ve finished the activities that you want the recorded script to perform, select Tools | Scripts | Stop Recorder or click again on the Action Bar’s Recorder icon to stop recording.

4.	Specify a filename for the new script.

When you stop the recorder, Procomm Plus displays a dialog prompting you for the name for the new source file. If you wish, you can also compile the new script from this dialog.

At this point, you may wish to save the script and edit it, rather than attempting to compile it immediately. Scripts built with Record mode sometimes require "fine-tuning" before they’ll successfully run. For example, Procomm Plus might inadvertently capture line noise, or you may need to lengthen a script pause to allow a slow host system more time to respond.


Script Spawning and Chaining

  Related Topics

One ASPECT script can be used to start another ASPECT script within the same instance of Procomm Plus in two different ways, referred to as spawning and chaining. The calling script is referred to as the parent script, while the called script is referred to as the child. A spawned script, upon termination, returns control to the parent; a chained script does not.

When a child script task is spawned using the execute command, the current state of the parent script is stored by ASPECT in a temporary task file. Upon return from the child script, the task information is restored, and the parent script resumes its own execution from the point where it had launched the child.

In addition to saving the current execution location within the script, the task file contains a record of all user-defined global variables, all active when commands, all files opened by ASPECT’s fopen command, all active setjmp/longjmp commands, and all allocated memory blocks and their contents. The task file will not contain information about any active ASPECT dialog boxes, any DDE client conversations which were in effect, the state of the predefined global variables, the current state of the set commands with the possible exception of those comprising the ASPECT environment, the current state of the User window, the state of the current menu items or the state of packet transfer mode. Certain system variables may be restored, however, such as those specific to the script's execution context.

When a script passes execution to another script using the chain command, the parent script is terminated, and will not be restored when the child is finished. No task file is created for a chained script.

When a script spawns or chains to another script, all existing ASPECT dialog boxes in the current script will be destroyed, as will any DDE client conversations currently in effect. The child script will inherit the current values of the pre-defined and any system variables that are not script-specific, as well as the state of all set commands that are not part of the ASPECT environment. In addition, the child will inherit the current User window and all of its objects, any menus created by ASPECT, the state of all menu items and the current state of packet transfer mode.

The script that performs the chain or execute command can determine whether the chained or spawned script will share the same current ASPECT environment settings, or whether it will be assigned the default ASPECT environment settings. This is controlled with the SHARED keyword in the chain or execute command.

If a child is spawned using execute, and the environment is SHARED, then when the child script terminates and control returns to the parent script, any changes to the ASPECT environment are carried back to the parent script’s environment. If the environment was not SHARED with the child script, the parent will resume execution with its own ASPECT environment which had been saved in the task file. Note that, depending on how the ASPECT environment is SHARED, if either the child or the parent script was responsible for keyboard data or received data, and some of that data had not yet been processed, then it is possible that the unprocessed keyboard data will be lost, and the unprocessed received data will be processed by the Terminal rather than by the script that assumes execution.

If a script file is launched on top of another running script, it will be initialized with the default ASPECT environment settings. This situation can arise when a currently running script has set aspect spawn ON, which enables other scripts to interrupt it at any time. If it is uninterrupted, its current execution state being saved in a task file.

Setting aspect spawn ON can be dangerous to a script’s proper execution if that script has dialogs or DDE commands that are active, since these are destroyed when the script is temporarily shut down. Typically, this flag should be set on only when a script can be freely interrupted and resumed without affecting its intended functionality.

The currently running script task may need to know if it was spawned or chained so that it can check for relevant data in the predefined variable set, or determine something about the ASPECT environment that was assigned to it. The system variable $SCRIPTMODE can be referenced to determine how any script was executed. If a script was spawned, the contents of the system variable $PARENTFILE will contain the name of the parent script. If the script was chained, the system variable $CHAINEDFILE will contain the name of the script which issued the chain command.

If the script was launched from a Connection Directory entry, the $DIALENTRY system variable will contain the entry name. By testing the values of $DIALCONNECT and $DIALING, the script can determine if a dial command should be issued to begin the dialing sequence for that entry. The $SCRIPTENV system variable allows a script to determine if the ASPECT environment it has is being shared with the script that launched it.


Sending Keys with ASPECT

  Related Topics

We used the sendkey command in our User window script earlier in this tutorial. sendkey sends a keystroke to the currently active window using that keystroke’s keycode. ASPECT also provides a command called sendkeystr. As you might expect, sendkeystr sends a string. Examine the following script fragments:

sendkey 13

sendkeystr "^M"

Both fragments send a Carriage Return to the active window. With sendkeystr, however, you could also send a string of several characters:

sendkeystr "Send me a kiss by wire!^M"

With sendkey, on the other hand, you can send not only regular character keys, but Alt, Shift, and Control keys as well. For instance:

sendkey ALT 70

sends Alt-F to the currently active window, just as if you’d typed it at the keyboard. If the Terminal window is currently active, the command pulls down the Procomm Plus File menu. Alternately, you can use the command syntax:

sendkey ALT 'F'

Notice the use of the single quotes around the character constant F. ‘F’ is not a string; it is another way of expressing the integer value 70.

sendkey and sendkeystr can be used to send keystrokes to other applications, as long as the appropriate window is first activated. For instance, you may want to switch over to an editor and display a file. These two simple commands allow you not only to create a custom interface for Procomm Plus functions, but to build entire integrated systems! The following script loads Notepad and searches for a string within the displayed file:

#define RUNPATH "c:\windows\notepad phones.txt"

proc main

   string szAreaCode = "573"       ; String to search for.

   run RUNPATH                     ; Run "notepad phones.txt".

   sendkey ALT 'S'                 ; Alt S (for Search).

   sendkeystr "f"                  ; F for Find.

   sendkeystr szAreaCode           ; The search target

   sendkey 13                      ; followed by Enter,

   sendkey 27                      ; then Esc to get out of searching.

endproc

Exercise

Write a script file that prompts for a string from the user, launches Notepad using the run command and searches for that string in a particular file.


Set and Fetch Statements

  Related Topics

Set/Fetch Overview

General Set/Fetch Statements

ASPECT Set/Fetch Statements

CAPTURE Set/Fetch Statements

DIAL Set/Fetch Statements

DIALENTRY Set/Fetch Statements

FAX Set/Fetch Statements

FTP Set/Fetch Statements

INTERNET Set/Fetch Statements

MAIL Set/Fetch Statements

MODEM Set/Fetch Statements

NEWS Set/Fetch Statements

PORT Set/Fetch Statements

PRINT Set/Fetch Statements

TELNET Set/Fetch Statements

TERMINAL Set/Fetch Statements

Advanced Emulation Set/Fetch Statements

PROTOCOL-related Set/Fetch Statements


Set/Fetch Overview

  Related Topics

set and fetch commands are used to retrieve and change options in the Connection Directory, the Setup utility and other features of Procomm Plus. fetched values are placed into data variables of the appropriate type, and may be used directly in corresponding set commands.

Although most set/fetch commands will always succeed, all set/fetch commands update the SUCCESS and FAILURE system variables based on the results of the command. Certain fetch commands may fail if the information given to the command is invalid.

Using set to change Connection Directory entry data will fail when the Connection Directory is displayed.

On the following pages you’ll find descriptions of all set and fetch statements grouped by type, such as the set ASPECT or set ZMODEM types. The first group of statements are general statements that do not fall into a specific group. Where general statements do relate to a specific statement group, a reference is provided so that you can find it more easily.

The set and fetch commands in the statements below are assumed, and are thus not included in the syntax. For example, actionbar must be preceded by set or fetch to form a valid command.

The syntax for the fetch command generally follows that of its partner set command. For example, to determine the filename referenced as the top Action Bar, the fetch command would be:

fetch actionbar top strvar

since fetch actionbar returns a string value. To determine the number of seconds that the alarm would sound, the fetch command would be:

fetch alarmtime intvar

since fetch alarmtime returns an integer. In cases where the set command accepts an ON and OFF keyword, fetch will return 0 for OFF, and 1 for ON. For example:

fetch alarm intvar

would report the status of the Sound Alarm option in Setup, System, System Options.


Some Notes on Design

  Related Topics

So far you have learned the basic structural elements of the ASPECT language. Before going on to more advanced topics, let’s discuss various approaches to designing script programs.

If you sit down and start writing a very complex ASPECT script without any planning at all, you may become frustrated and dissatisfied with the results. ASPECT is a simple language to use, but if you randomly start experimenting with commands it’s easy to get lost in its power. Here are some questions to ask yourself before actually starting to code:

•	What is the purpose of the script?

•	What are the necessary procedures to accomplish this purpose?

•	What user input does the script need, and what is the best way to gather this input?

•	Are there any necessary supporting procedures or functions? Can I reuse functions and procedures, either in this script or in other scripts, by generalizing them?

Suppose you want to write a script that downloads several files in the middle of the night when phone rates are cheaper. Each night, you want to be able to specify exactly which files to download, and to tell the computer what time to place the call. In addition, you want Procomm Plus to hang up the call after a specified amount of on-line time has elapsed. You might come up with the following answers to the above questions:

•	Purpose of script: to call a BBS and download user-specified files within a user-specified time period.

•	Necessary procedures:

•	Ask user for files to download, time to call, and maximum length of session.

•	Wait for right start time.

•	Dial the call.

•	Set up some sort of when statement so the script can know when end time has been reached. call a procedure to hang up line if end time reached.

•	Logon to BBS.

•	Transmit names of files to download.

•	Download files.

•	Log-off BBS if files finished in specified time period.

•	Script needs the following user input:

•	Time to call.

•	Length of time before ending session.

•	Files to download.

It is best to get this input in a single dialog box. Start and end times can be chosen via option buttons or list boxes and file names can be entered in edit boxes.

•	Support procedures or functions:

•	Input file names must be error-checked for the number of characters in the filename and extension. This function or procedure is needed for every file name specified by the user. I can generalize it so that it’s useful in other scripts.

•	File names are delimited by spaces or carriage returns when sent to the BBS. Once again, this is a general purpose function. Perhaps I can use the "AddCr" function discussed earlier in Functions.

•	The script needs to check whether or not files are properly downloaded, and needs to report the status. This may end up as two procedures.

There are important elements you are leaving out at this point, but at least you have an idea of where to start your script. It is now possible to sketch out what you need to include in a main procedure, without writing any code:

start of main procedure

   get user input             ; This procedure may call yet another

                              ; one for dialog box.

   process user input         ; Need to process info from dialog,

                              ; error check etc.

   show waiting message       ; While waiting...

   start of loop

      if time == start time

         go on                ; This "go on" procedure will call all

                              ; other worker procedures and functions.

         when elapsed time reached hang up

                              ; From this point on we wait for the

                              ; specified session length to be reached.

                              ; Script will end in "hang up" procedure.

      endif

   end of loop

end of main procedure

This rough "pseudo-code" is obviously not ASPECT syntax, and you haven’t defined any variables or worked on the procedures, but you have outlined the basic logic, which is often the most difficult task. Of course, you may change some of the basic logic. For instance, you may not want the on-line session to hang up in the middle of a transfer. At this point it is useful to ask yourself several new questions:

•	What kinds of variables do I need? Do any have to be global?

•	Are there any procedures that may be more efficient as functions? Can I use the return value immediately in an expression?

•	Are there variables that should be passed by reference instead of value?

•	Can I simplify my functions or procedures by using ASPECT system variables?

•	What ASPECT commands are the right ones for the various tasks?

Programming in any language is an iterative process, meaning that you often have to go back to your code many times, refining it a little more each time. These iterations should not be shots in the dark. Each time you visit your script file, the logic should become clearer and clearer rather than more obscure.

In the example above, there is very little user interface. It may be useful to work on the user interface before the underlying foundation of the program. Often the process of designing the interface, called "prototyping", raises new issues or clarifies the direction the script should take.

There is no magic formula for constructing good scripts, but there are some stylistic conventions that keep you from getting lost in your code:

•	Comment extensively, more than you think is necessary.

•	You may know your code intimately today, but two weeks from now it may make no sense at all without good comments.

•	Indent consistently.

ifs should line up with endifs, whiles with endwhiles. As you nest your code, make sure to indent the same number of spaces or tabs for lines or blocks of code that are at the same level. Most programmers indent using 2 or 3 spaces.

•	Use global variables only when necessary.

Globals may change in other procedures without you realizing it, leading to unexpected results, known as "bugs".

•	Name your variables descriptively.

A carefully chosen variable name like MyFileNames communicates so much more than StrVar4.

•	Create reusable functions and procedures whenever possible.

There are several sample ASPECT files in your ASPECT directory that serve as good examples of coding style.


Spawning and Chaining ASPECT scripts

  Related Topics

ASPECT allows one script to call another in two ways: chaining and executing. With the execute command, you can spawn a child script and return to the point in your parent script where you issued the command. This allows the creation of worker scripts containing procedures or functions that can be used in a variety of applications. When you spawn a script, only the values of the predefined global variables S0 - S9, I0 - I9, L0 - L9 and F0 - F9 are preserved. If you want to pass a value to a child script, use these predefined globals. Consider these sample scripts:

; File MAIN.WAS

proc main

   S0 = "hello"               ; Assign S0 the value "hello"

   usermsg S0                 ; and display it.

   execute "change.wax"       ; Call the file that manipulates S0

   usermsg S0                 ; and show the changed value.

endproc

; File CHANGE.WAS

proc main

        S0 = "goodbye"        ; Reassign S0 the value "goodbye"

endproc                       ; and return to parent.

In addition to executing scripts, you can chain to them with the chain command. When you chain to a script, control is not automatically passed back to the calling script when the chained script completes.

Chaining and executing scripts is useful in building complex ASPECT systems and in creating reusable modules. There are several important considerations, however, when working with chained or executed script files. A parent script’s dialog boxes are destroyed and any active DDE client sessions are terminated when you execute or chain to another script.

For more information, see the chain command and the execute command. Also, see Script Spawning and Chaining.

Exercise

Write a script file that asks the user for a name and address and calls another script to format and display this information.


Step-by-Step: Resolving Compile-Time Errors

  Related Topics

Compile-time errors are usually generated by statements that contain one or more syntax errors, just like the error in our example. Compile-time errors are usually easy to resolve since the ASPECT Compiler detects and reports them as it processes your source file(s).

To resolve compile-time errors, follow these steps:

1.	Open the source file that contains the error.

If the error occurs in the file shown in the Compile Progress groupbox, you can click on the Edit Source File button. The ASPECT Compiler will automatically load the file into your editor.

2.	Go to the line number indicated in the error message.

If you’re using the ASPECT Editor, you can press Ctrl-G, and enter the number in the Goto Line dialog. The ASPECT Editor will move the cursor to the specified line.

Always start with the first error shown in the Message List window. One source-file error can generate more than one Compile-Time error message.

3.	Examine the error message given by the compiler.

In our example, the compiler reported "Invalid expression token". Because our string variable mystring was misspelled as mmystring, the compiler couldn’t find a valid declaration to determine how to interpret the usermsg command.

If you’re still uncertain about the meaning of the error message, refer to the syntax statement for the ASPECT command you’re using. Make sure that you haven’t omitted a vital keyword, or tried to use a datatype that is not allowed for the command.

If you’re using the ASPECT Editor, you can quickly open a command’s help reference by placing the cursor on the command and pressing <Ctrl><F1>, or by clicking on the command with the right mouse button..

4.	Locate the word or symbol flagged by the compiler.

In our example, "mmystring" was flagged because the compiler couldn't find a string variable by that name. There are a variety of things that can cause compile-time errors, however. If you don't immediately understand why the compiler flagged the line as a problem, try comparing the command you've used in the problem line against its normal syntax.

Solving compile-time errors can be frustrating when you’re trying to learn a new programming language, but be patient. As you become more acquainted with ASPECT, you’ll find that it becomes easier and easier.

A complete list of compile-time errors appears in Compile-Time Error Messages.


Step-by-Step: Resolving Run-Time Errors

  Related Topics

Resolving a run-time error is usually more difficult than resolving a compile-time error. Because ASPECT scripts are compiled, a run-time error will not be directly connected to statement syntax. We must learn more about the error before we can attempt to resolve it.

The script below demonstrates a fairly common logic error. Strings in ASPECT are limited to 256 characters, but their character indexes are zero-based. This means that to target the last string position, the proper strputc command should be:

strputc teststr 255 ‘&’   ; Target the last char position

Instead, the for loop increments the bad_index variable from 0 to 256. The script executes normally until bad_index equals 256, at which point

strputc teststr 256 ‘&’   ; Bad Index value!

is targeting a non-existent 257th character position in teststr.

; Demonstration of Run-Time error.

proc main

   string teststr = ""             ; Declare test string, init to null

   string showstr                  ; Declare string for display

   integer testlen                 ; Declare int. to report test length

   integer bad_index               ; Declare int. index to test string

   clear                           ; Eliminate screen clutter.

   for bad_index = 0 upto 256      ; This is wrong!

                                   ; String length...

      strputc teststr bad_index '&'; ... must not

                                   ; exceed 256 chars!

      strlen teststr testlen       ; Get length,

                                   ; format show string.

      strfmt showstr "`"TestStr`" is %d chars." testlen

      locate 1 1                   ; Move the cursor

      termwrites showstr           ; Write the string.

   endfor

endproc

Let’s use what we already know about the run-time error in this script to learn how to resolve other such errors. To resolve a run-time error, take the following steps:

1.	Consider the run-time error message given by Procomm Plus.

In our example, Procomm Plus reported Error 1: Value out of range, which indicates that an argument value given to one of the commands in the example was not valid. Because our example script is quite brief, it’s easy to examine it line-by-line, and verify the arguments for each of the commands.

In larger, more complex script projects, line-by-line evaluation is impractical. When searching for causes in such scripts, consider:

•	What portion of the script was executing when the error occurred?

•	What commands in the script relate to the run-time error?

For example, a string-related command is an unlikely culprit for an Error 02: Divide by zero, while a math-related command is unlikely to cause an Error 04: String length limit exceeded.

•	If the script had previously run without an error, what has changed? have new commands or procedures have been added to the script?

If the cause of the problem is not immediately clear, proceed to Step 2.

2.	Recompile the script after enabling the Compile for debug check box.

Procomm Plus provides a debugging utility to assist you in tracking down problems in complex scripts. To use the debugger, however, you’ll need to recompile the script with the Compile for debug check box enabled.

Press <Alt><F3> to open the Compile/Edit ASPECT File dialog, then click on the Compile Options button to open the ASPECT Compiler Options dialog:

The Compile for debug option, if enabled, instructs the compiler to include debugging information in the compiled script. Procomm Plus displays this information in the debugging window if the script is aborted, or if a run-time error occurs.

If you enable Compile for debug, you can also enable two other important options for additional debugging information: Create map file and Include line numbers.

The Create map file option instructs the ASPECT Compiler to generate a text file with an extension of .map. The text file contains details about your compiled script, including information about its variables and labels. It also provides details about the script's procedures and functions, and reports the number of times each procedure or function is called throughout the script.

The Include line numbers option is only available if you're generating a .map file. It instructs the ASPECT Compiler to include a line number table in the .map file. If a run-time error occurs, you can use the line number table to locate the approximate line in the source file that is causing the problem.

After you've enabled the Compile for debug option, click on OK to close the dialog. Now, re-compile the script by clicking on Compile in the Compile/Edit ASPECT File dialog, and proceed to Step 3.

3.	Run the script, repeating the actions that led up to the error.

Our example script requires no user interaction to force its run-time error. However, if your script relies on user input, or other variable conditions, you'll need to reproduce the conditions that led to the run-time error.

When you have compiled for debug, Procomm Plus responds to a run-time error by displaying the ASPECT Run Time Debugger window:

If a script has been compiled for debugging, the debug window can be activated at any time during execution by pressing Ctrl-Break. If the script is currently executing a command that can be exited with Ctrl-Break, it will be canceled when script execution resumes.

4.	Use the information provided by the debugger.

The debugger window displays the information you need to track down a run-time error message:

•	The error message generated by the problem.

•	The name of the procedure or function executing when the error occurred.

•	The offset into the target .wax file where the error occurred.

•	The name of the source .was file.

•	The text of the line in the source file containing the offending code.

•	The offending line of code from the source file.

In our example script, the debugger shows line number 10:

strputc teststr bad_index `&'

as the offending source line. Since our error message relates to an invalid range, we know that either the index argument bad_index, or the character argument `&' to strputc is at fault. The ampersand `&' enclosed in single quotes is a valid character, so the value of bad_index must be the problem.

If the value of bad_index is invalid, what is it? You could determine the value by inserting a message command of some kind in the script before the strputc line. Then, when the script executed, you would know that the last value reported for bad_index before the error was invalid. However, the debugger has an easier way.

The debugger's Variable drop-down list box allows you to select a Global, Local or Predefined variable, and display its contents or value in the dialog. Simply click on the down-arrow icon beside the list, and select the variable name you want!

Initially, the Variable list box shows Predefined variables. Our variable, bad_index is a Local variable; to view Local variables, select [Local] from the list. You can then select bad_index, and see that, indeed, 256 is the invalid value.

If our variable had been an array, the debugger would have enabled the Array Offset field, and the Next and Prev buttons, allowing us to look through the array's elements for problem values.

There are other important buttons available in the debugger window:

•	Click on Continue to attempt continuation of the suspended script. The debugger window will close and the script will resume normally.

•	Click on Step to continue execution of the suspended script on a line-by-line basis. The debugger window will remain open as the script executes, allowing you to monitor the selected Variable values.

•	Click on Edit Source to open the source .was file for editing. The ASPECT Editor will place you on the source line indicated in the debugging window.

•	Click on Exit Script to terminate the script without resuming execution. The debugger window will close.

In our example script, we can select bad_index as the target in the debugger's Variable list, then click on the Step button to step through each line of our script and watch the value of bad_index change.

If you're unable to discover the source of the problem using the information provided by the debugger after the error occurs, proceed to Step 5.

5.	Use the breakpoint command to open the debugger before the problem occurs.

The breakpoint command suspends script execution, and opens the ASPECT Run Time Debugger window. It allows you to look "under the hood" of your script, without forcing a run-time error to open the debugger window.

A breakpoint command is ignored by the compiler when a script is compiled without the Compile for Debug option enabled, making it unnecessary to insert conditional-compilation code around each breakpoint!

You can insert the breakpoint command anywhere in your script. However, it is generally placed at the start or end of a procedure or function, or around a suspect block of code. You can also specify a message to be posted in the debugger's Message field to help you determine which breakpoint has fired.


Storing Information in Array Variables

  Related Topics

Along with local and global variables, you may also declare local and global array variables. Arrays are best thought of as collections of information that you can reference using a single name. They are used to group together variables of the same type and relation. Individual parts of an array are known as elements of the array, and are referenced using subscripts or indices corresponding to their locations.

Declaring an Array

Remember that in declaring a normal variable, we had to tell the compiler the name of the variable, and its data type:

string Mauve

Declaring an array is similar, but we have to tell the compiler the dimensions of the array. We do this by adding a subscript expression:

string MauveArray[12]

The declaration for MauveArray is very similar to the declaration of Mauve, above. Other than the variable names, the only real difference is its subscript expression, [12]. The subscript expression tells the compiler how many strings are contained in the array. In MauveArray, we have declared a single-dimensioned array containing 12 string elements.

ASPECT also allows you to create multi-dimensioned arrays. For example, the declaration:

integer FiveByFive[5][5]

creates an array of integers with 25 elements, arranged in five rows of five elements each.

In our examples, we have used integer constants for subscript expressions. However, you can use any integer or long value for a subscript expression.

Accessing Array Elements

Array names are handled by the compiler in the same way as names for non-array variables. To access the array elements, however, you must supply the element number you’re referencing:

Mauve[0] = "What is this color?"

Mauve[1] = "Who owns this car?"

The statements above assign the first and second array elements in Mauve to "What is this color?" and "Who owns this car?", respectively.

The subscript expression for the first element in Mauve is 0. This is because array indices are zero-based. The first element is addressed using a subscript expression of zero, and the last element in a row or column is addressed using a subscript of one less than the declaration subscript value.

Using a value stored in an array is just like using any other variable:

transmit Mauve[1]

usermsg Mauve[0]

Global and Local Arrays

Like other variables, arrays can be declared as either local or global. The following example shows how to declare both local and global array variables:

string Names[10]        ; Declare global string array with 10 elements.

proc main

   integer Ages[10]     ; Declare local integer array with 10 elements.

   ;     .              ; Other commands

   ;     .

endproc

Notice how the declaration for the array called Names appears outside of the procedure block and the declaration for the array called Ages appears inside of the procedure block. Names is a globally declared array variable and Ages is a locally declared array variable. Both of the array variables in the above example may be used by commands within the procedure called main, but only Names may be used by other procedures.

Now, let’s add some assignments to our script file:

string Names[10]               ; Declare string array with 10 elements.

proc main

integer Ages[10]               ; Declare integer array with 10 elements.

   Names[0] = "John T. Smith"  ; Assign a value to the first element of

                               ; our array of names.

   Ages[0] = 89                ; Assign a value to the first element of

                               ; our array of ages.

endproc

In the script example above, Names[0] is used to reference the first element in the array called Names, and Ages[0] is used to reference the first element in the array called Ages. Assigning and retrieving information from arrays is made easy with the use of variable subscripts.

As a practical example, let’s make our script file read a list of names and ages from a file and put them in our Names and Ages arrays. You’ll need to create a text file called "NAMES.LST" in a text editor like the ASPECT Editor and fill it with 10 names. Follow each name by a comma and an age. Your newly created file should look something like:

Bob Jennings,35

Frosty T. Snowman,1

Joseph Risingstar,18

E.L. Capitan,51

.

.

Now we can change our script file to open the NAMES.LST file, read names and ages from the file, separate the names from the ages, and put the names into the Names array and the ages into the Ages array. The resulting script file looks like this:

string Names[10]                          ; Declare string array with 10 elements.

proc main

   integer Ages[10]                       ; Declare integer array with 10 elements.

   integer Count = 0                      ; Variable subscript used to reference our

                                          ; arrays.

   string szLine                          ; Variable to store line from file.

   string szTemp                          ; Temporary variable used for Age.

   if fopen 0 "NAMES.LST" READ

                                          ; Open name file for read only.

      while not feof 0                    ; Loop while we’re not at end of the file.

          fgets 0 szLine                  ; Get a line from the file and extract the

                                          ; name and age.

          strtok Names[Count] szLine "," 1

          strtok szTemp szLine "," 1

          atoi szTemp Ages[Count]

                                          ; Convert the age to an integer and put

                                          ; it into our Ages array.

          if (Count += 1) == 10

                                          ; Increment array subscript and make

             exitwhile                    ; sure that we don’t increment past the

          endif                           ; last elements in the two arrays .

       endwhile

       fclose 0                           ; Close our file of names and ages.

    else                                  ; Display a message if an error occurred.

       errormsg "Couldn’t open NAMES.LST for input!"

    endif

endproc

In this example, the variable called Count is used to reference the elements in the Names and Ages arrays. You could expand this example to include displaying the list of names and ages, pumping them into a spreadsheet or word processing program with DDE, or many other tasks.

ASPECT accepts subscript expressions that exceed the number of elements in an array but a run-time error is displayed if such a case occurs. For more information about using arrays, including memory requirements and addressing, see "Arrays".

Exercise

Write a script that reads a list of software products and their prices from a file, stores the product names and prices in arrays and then calculates and displays the average price of all of the products. Make your script file support at least 50 products.


String Commands

nullstr	Tests a string variable for the null condition.

rstrcmp	Compares the contents of two strings up to the specified length.

strcat	Concatenates one string to another string variable.

strchr	Searches for the first occurrence of a character in a given string.

strcmp	Compares two strings.

strcpy	Assigns a string to a string variable.

strcspn	Searches a string for a character contained in a second string.

strdelete	Removes characters from the contents of a string variable.

strextract	Returns a string from a list of elements.

strfind	Tests for the occurrence of the specified text within a variable.

strfmt	Creates a formatted string using a template and specified variables.

strgetc	Returns the ASCII value of a single character in a string.

stricmp	Performs a case-insensitive comparison of two strings.

strinsert	Inserts the contents of a string into another string.

strlen	Returns the length of a string or string variable’s contents.

strlwr	Converts the contents of a string variable to all lowercase.

strncmp	Performs a case-sensitive comparison of two strings for a specified length.

strnicmp	Performs a case-insensitive comparison of two strings for a specified length.

strputc	Modifies the value of a single character within a string.

strquote	Places the contents of a string within double quotes.

strrchr	Searches for the last occurrence of a character in a given string.

strread	Reads a block of data from a string.

strreplace	Searches a string for a specific pattern of characters and replaces that pattern with another string.

strrev	Reverses the contents of a string.

strright	Copies a string of characters from the end of a string.

strsearch	Searches a string for a specific character or pattern of characters.

strset	Sets the characters in a string variable to a specified ASCII value.

strspn	Searches a string for the first character that does not occur within a second string.

strtok	Parses a delimited string into tokens.

strupdt	Overwrites a string with another string at a specified index.

strupr	Converts the contents of a string variable to all uppercase.

strwrite	Writes a block of data to a string.

substr	Copies the indicated number of characters from a string, beginning at a specified position.

 Return to category list


Syntactic Compile-Time Error Messages

  Related Topics

Compilation will continue when one of these error messages occurs, but the error must be resolved before a target script can be created. When displayed in the Aspect Compiler window, the error message will include a line number indicating the location of the error in the source file.

C000	Illegal character
C001	Missing terminating quote
C002	Missing space between tokens
C003	Unexpected escape sequence
C004	Maximum token length exceeded
C005	Escape sequence character out of range
C006	Invalid character constant
C007	New line character in constant
C020	Invalid token
C021	Unexpected token(s) at end of line
C022	Missing token
C023	Invalid expression token
C024	Invalid command or expression token
C025	Unexpected command
C026	Invalid use of reserved word
C027	Invalid identifier or name
C028	Duplicate symbol
C029	Missing comma in token list
C030	Undefined label
C031	Invalid label location
C032	Variable limit exceeded
C033	Variable not defined
C034	Maximum stack displacement exceeded
C050	Invalid preprocessor command
C051	Preprocessor command must occur as first token
C052	Maximum macro definition length exceeded
C053	Maximum macro argument length exceeded
C054	Maximum macro expansion length exceeded
C055	Missing #ENDCOMMENT command
C056	Missing #ENDIF command
C060	Missing ENDSWITCH command
C061	Missing ENDCASE command
C062	Missing ENDIF command
C063	Missing ENDWHILE command
C064	Missing ENDFOR command
C065	Missing PROC or FUNC command
C066	Missing ENDPROC or ENDFUNC command
C080	Missing WITH before argument list
C081	Invalid number of arguments
C082	Mismatched argument type
C083	Maximum argument count exceeded
C084	Missing or invalid return type or value
C085	Procedure does not return a value
C086	Undefined procedure or function
C087	Unresolved procedure or function call
C088	Missing procedure MAIN
C100	Expression too complex
C101	Missing operator
C102	Missing operand
C103	Missing right paren
C104	Missing left paren
C105	Missing right bracket
C106	Missing left bracket
C107	Missing variable operand
C108	Missing colon
C109	Unexpected colon
C110	Invalid operand
C111	Invalid variable operand
C112	Invalid use of operator
C113	Invalid floating point operation
C114	Illegal initializer expression
C115	Divide by zero
C116	Value out of range
C120	Invalid subscript expression
C121	Invalid constant expression
C122	Subscript on non-array
C123	Maximum array dimensions exceeded
C124	Maximum array elements exceeded
C150	Invalid number
C151	Invalid numeric variable
C152	Invalid numeric constant
C153	Invalid integer
C154	Invalid integer variable
C155	Invalid integer constant
C156	Invalid long
C157	Invalid long variable
C158	Invalid long constant
C159	Invalid float
C160	Invalid float variable
C161	Invalid float constant
C162	Invalid string
C163	Invalid string variable
C164	Invalid string constant
C165	Invalid integer or string
C166	Invalid number or string
C167	Invalid numeric or string variable
C168	Invalid numeric or string constant
C169	Invalid global variable
C200	Duplicate control ID
C201	Too many controls in dialog box
C202	Default button already defined
C203	Missing ENDDIALOG command
C204	Missing ENDGROUP command


System Variables

  Related Topics

System variables are "read-only" variables to which ASPECT and Procomm Plus may assign specific values. They are available throughout a script. For example, although you cannot change the value of the variable $ROW, which is always equal to the current row position of the terminal cursor, you can read it from anywhere within a script and use it in any statement where an integer value is accepted.

A script can reference system variables to determine operating conditions, on-going processes, window and task information, user actions and other events. The results of many ASPECT commands can also be tested with the SUCCESS and FAILURE system variables.

For more information, and complete descriptions of all ASPECT system variables, see The System Variables.


System Variables Overview

  Related Topics

ASPECT provides a number of variables that are used to report the status of operations and events in Procomm Plus. These variables have values that are maintained internally by Procomm Plus and ASPECT. A script cannot directly alter the value of a system variable, but many ASPECT commands can cause the system variable’s value to change.

A system variable is "read only", meaning it can only be used in commands where a constant is permitted. A system variable cannot be used in place of a data variable, since this would imply that the system variable is to be set to a result value upon termination of a command. System variables cannot be passed by reference to a user-defined procedure or function, but they can be passed by value. Other usage restrictions may apply on a per-command basis. For example, a system variable cannot be used within a dialogbox command group.

Certain system variables reset their values to a default setting after they are accessed. Others have values that remain unchanged for the duration of script execution. Still other system variables change value dynamically based on current program activities and operations.

The following system variables return window ids, and can be used in any ASPECT command where a window id is required: $ACTIVEWIN, $CHATWIN, $DIALDIR, $FOCUSWIN, $LMOUSEWIN, $MAINWIN, $MONITORWIN, $MMOUSEWIN, $POINTERWIN, $PWMAINWIN, $RMOUSEWIN, $SETUP and $USERWIN.

$POINTERTASK, $PWTASK and $TASK return task ids. Their values can be used in any ASPECT command where a task id is required.

Option set item strings are returned by $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $MAILOPTIONS, $NEWSOPTIONS, $PROTOCOL, $TELNETOPTIONS, $TERMFONT, $TERMCOLORS, $TERMINAL and $WINCOLORS.

The following integer system variables reset their values to 0 after they are accessed: $ACTIONBAR, $ASPMENU, $DDEADVISE, $ERRORNUM, $LMOUSEEVENT, $MCINOTIFY, $OBJECT, $PKRECV, $PKSEND and $RMOUSEEVENT. $XFERSTATUS also resets to 0 after being accessed, but only when its value does not indicate an ongoing transfer.

SUCCESS and FAILURE are two special global system variables.

For more detailed information on the system variables, see The System Variables


System Variables and the when Command

  Related Topics

In addition to watching for incoming text, key presses, dialog events and so forth, you can use when commands to detect when the values of ASPECT system variables change. For example, suppose we want a script file that displays the position of the mouse pointer on the status line, but we only want to update the status line when the position of the mouse pointer changes. We need two when commands that check the status of the $POINTERX and $POINTERY system variables. Our when commands would look like this:

when $POINTERX call PointerChanged

when $POINTERY call PointerChanged

Since we don’t care which of the two values changes, we may as well call the same procedure in both cases. $POINTERX contains the X location of the mouse cursor and $POINTERY contains the Y location. When $POINTERX or $POINTERY changes, our script calls the procedure named PointerChanged. In PointerChanged, we can display the values of $POINTERX and $POINTERY on the status line. Our resulting script file might look like:

#define TRUE    1

proc main

   PointerChanged()                      ; Display beginning message on the

                                         ; status line and set up our whens.

   when $POINTERX call PointerChanged    ; Watch the $POINTERX value.

   when $POINTERY call PointerChanged    ; Watch the $POINTERY value.

   while TRUE                            ; Loop forever.

   endwhile

endproc

proc PointerChanged                      ; Procedure to displays pointer

                                         ; location on the status line.

   statmsg "( %d, %d )" $POINTERX $POINTERY

endproc

In our script, PointerChanged is called at the beginning to display the mouse pointer's location before entering the endless while ... endwhile loop at the end of the main procedure. If we don’t make this call at the beginning of our script file, the status line message doesn’t appear until after the user has moved the mouse. Thereafter, PointerChanged is called anytime the value of $POINTERX or $POINTERY changes. statmsg is used to display the position of the mouse pointer on the status line.

As stated earlier, you can sense a change in the value of any ASPECT system variable. Be aware that some system variables are reset to their default value when their state is read with the when command. An example of this is the $DDEADVISE system variable. It’s value is set back to 0 after a corresponding when event occurs. System Variables contains more detailed information on each of the system variables.

Exercise

Rewrite the example for the menubar command. Make it use a when clause to sense when a menu item is selected.


TELNET Set/Fetch Statements

  Related Topics

The following set/fetch commands control Telnet settings within Procomm Plus. They correspond to options in the Telnet dialog in Setup.

telnet autologon OFF | ON

Determines whether or not Procomm Plus will allow automatic Telnet logons. This command corresponds to the Allow automatic Telnet logon check box in the Setup, Internet, Telnet dialog. fetch returns a 0 if the check box is not active, or a 1 if it is checked.

telnet baudrate baudrate | DISABLED

Determines whether or not Procomm Plus will force the baud rate to a certain speed or not. The second baudrate is a reference to a long variable specifying the port speed to use. This command corresponds to the Force speed to: field in the Setup, Internet, Telnet dialog. fetch returns an index.

telnet binarymode OFF | ON

Determines whether the session is in binary mode. This command corresponds to the Set session to binary mode check box in the Setup, Internet, Telnet dialog. fetch returns a 0 if the check box is not active, or a 1 if it is checked.

telnet negotiation OFF | ON

Specifies whether to disable all types of Telnet negotiation. This command corresponds to the Disable all Telnet negotiation: check box in the Setup, Internet, Telnet dialog. fetch returns a 0 if the check box is not active or a 1 if it is checked. If this check box is enabled, it will override the other two Negotiate... fields.

telnet options index | string

Specifies the active set of Telnet options corresponding to the Current Telnet Options: list in the Setup, Internet, Telnet dialog. Either the zero-based index or the name of an option set as it appears in the Current Telnet Options list may be used. fetch returns the contents of the Current Telnet Options field in a string.

If the set dialentry access command has been used to specify a Telnet-class Connection Directory entry, set/fetch telnet options only affects that entry.

telnet terminal size OFF | ON

Determines whether or not Procomm Plus will negotiate terminal size. This command corresponds to the Negotiate terminal size check box in the Setup, Internet, Telnet dialog. fetch returns a 0 if the check box is not active or a 1 if it is checked.

telnet terminal type OFF | ON

Determines whether or not Procomm Plus will negotiate the terminal emulation to use. This command corresponds to the Negotiate terminal type check box in the Setup, Internet, Telnet dialog. fetch returns a 0 if the check box is not active or a 1 if it is checked.

telnet xwindow string

Specifies the string to use when negotiating with an Xwindow host. This command corresponds to the Set Xwindow value to: field in the Setup, Internet, Telnet dialog. fetch returns the string currently specified, or a null string if none is specified.


TERMINAL Set/Fetch Statements

  Related Topics

The following set/fetch commands control emulation settings within Procomm Plus. They correspond to options in the Terminal Options, Terminal Fonts and Terminal Colors dialogs in Setup.

terminal autosize WINDOW | FONT | OFF

Determines whether the size of the Terminal window is adjusted based on the size of the Procomm Plus main window, or based on the size of the current Terminal font. This command corresponds to the Terminal autosize field in the Setup, Data, Terminal Fonts dialog. fetch returns 0 for WINDOW, 1 for FONT or 2 for OFF.

terminal backspace NONDEST | DEST

Determines whether Procomm Plus erases or preserves the character under the cursor when a backspace is received. This command corresponds to the Destructive backspace check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for NONDEST or 1 for DEST.

terminal blinkrate integer

Specifies the pace at which blinking characters blink in the Terminal window. Values range from 0 to 9, slowest to fastest. This command corresponds to the Blink rate horizontal scroll bar in Setup, Data, Terminal Colors. fetch returns an integer reflecting the position of the thumb on the Blink rate horizontal scroll bar.

terminal blockcursor OFF | ON

Determines the size of the cursor in the Terminal window. If set to OFF, the cursor is a line. If ON, the cursor is a block. This command corresponds to the Block cursor check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF or 1 for ON.

terminal colors index | string

Specifies the Current Terminal Colors set. This command corresponds to the Current Terminal Colors list in the Setup, Data, Terminal Colors dialog. The zero-based index or the name of an entry in the Current Terminal Colors list may be specified. fetch returns the name of the Current Terminal Colors set in a string.

The set dialentry access command may be used to target a Data- or Telnet-class Connection Directory entry for the set terminal colors command.

terminal columns integer

Determines whether Procomm Plus uses an 80-column or a 132-column Terminal display. This command corresponds to the Terminal size X Columns list in the Setup, Data, Terminal Options dialog. fetch returns 80 for 80 columns or 132 for 132 columns.

Only the ADM31, TTY, TVI-955, DEC family (VT-xxx), AT&T family, and WYSE family terminals support 132 columns.

terminal enquiry OFF | ON | CISB

Determines Procomm Plus’s response to a received ENQ, ASCII 5, character. When set to ON, the string specified by the set terminal enquirystr command is sent. When set to CISB, the ENQ character initiates a CompuServe B+ file transfer. This command corresponds to the Enquiry field in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF, 1 for ON or 2 for CISB.

terminal enquirystr string

Specifies the string to be sent in response to a received ENQ, ASCII 5, character when Terminal enquiry is set ON. This command corresponds to the Enquiry response edit field in the Setup, Data, Terminal Options dialog. fetch returns the current contents of the field in a string.

terminal font index | string

Specifies the Current Terminal Font. This command corresponds to the Current Terminal Font list in the Setup, Data, Terminal Fonts dialog. The zero-based index or the name of an entry in the Current Terminal Font list may be specified. fetch returns the name of the Current Terminal Font list entry in a string.

The set dialentry access command may be used to target a Data- or Telnet-class Connection Directory entry for the set terminal font command.

terminal fontname string

Specifies the font used to display information in the Terminal window. This command corresponds to the Font list box in the Setup, Data, Terminal Fonts dialog. Specify the name of the font just as it appears in the Font list box. fetch returns the name of the current font in a string.

terminal fontsize integer

Specifies the size of the current font. This command corresponds to the Size list box in the Setup, Data, Terminal Fonts dialog. fetch returns an integer reflecting the size of the current Terminal font.

terminal frame OFF | ON

Determines whether Procomm Plus displays a frame around the Terminal window. This command corresponds to the Display terminal frame check box in the Setup, Data, Window Colors dialog. fetch returns 0 for OFF or 1 for ON.

terminal hostprint ENABLE | DISABLE

Specifies whether Procomm Plus responds to print commands sent by a host system. With set terminal hostprint DISABLE, Procomm Plus ignores host print commands. This command corresponds to the Disable host printing check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for ENABLE or 1 for DISABLE.

terminal keyboardfile terminal | string | filename

Specifies the keyboard mapping file to use with the current Terminal emulation. The filename extension, if specified, must be .KBD. If no extension is specified, the string must match either a base terminal name, such as ANSIBBS, or a name that was imported from a .DLT file.

You can also specify a Terminal keyword name such as ANSIBBS, WYSE50, or TVI950. This command corresponds to the Terminal keyboard file located in the Setup, Data, Terminal Options dialog. fetch returns the name of the keyboard file for the current emulation in a string.

terminal linewrap OFF | ON

Determines whether Procomm Plus wraps incoming characters to the following row when the end of a row is reached. This command corresponds to the Line wrap check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF or 1 for ON.

terminal pattern string

Specifies the graphic pattern surrounding the Terminal window. This command corresponds to the Patterns list in the Setup, Data, Window Colors dialog. fetch returns the name of the current pattern in a string.

terminal rawprint OFF | ON

Enables or disables whether Procomm Plus uses raw print mode for print captures. This command corresponds to the Raw print mode check box in the Setup, Data, Terminal Options dialog.

terminal rows integer

Determines the number of text rows in the Terminal window for the current emulation. Any value from 2 to 99 is acceptable, but some emulations may not be able to address cursor locations beyond row 25. This command corresponds to Terminal Size X Rows list in the Setup, Data, Terminal Options dialog. fetch returns the number of rows available for the current terminal.

terminal rxcr CR | CR_LF

Determines how Procomm Plus reacts when a Carriage Return, ASCII 13, is received. With CR_LF, Carriage Returns are translated to Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs. With CR, Carriage Returns are not translated. This command corresponds to the Incoming CR to CR/LF check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for CR or 1 for CR_LF.

terminal sbpages integer

Determines the number of pages stored by the Scrollback Buffer. Valid values range from 0 to 1300. This command corresponds to the Scrollback pages: field in the Setup, Data, Terminal Options dialog. fetch returns the current number of Scrollback pages.

terminal scroll OFF | ON

Determines the action taken when a character is written to the very last row and column in the Terminal display. This command corresponds to the Screen scroll check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF or 1 for ON.

set terminal scroll has no affect when the Line wrap check box in Setup, Terminal Options is unchecked.

terminal scrollmethod REPAINT | NORMAL

Determines how the Terminal display is repainted when information is scrolled. This command corresponds to the Terminal scroll method: field in the Setup, Data, Terminal Options dialog. fetch returns 0 for REPAINT or 1 for NORMAL.

terminal stripbit8 OFF | ON

Determines whether the 8th or high bit is stripped from received data before it is displayed. Setting this value ON prevents emulations from displaying characters with ASCII values greater than 127, the DEL character. This command corresponds to the Strip bit 8 check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF or 1 for ON.

terminal tabstops integer

Specifies the positions for fixed tab stops in the current emulation. The default is 8 characters; values range from 0 to 254. This command corresponds to the Tab stops every X positions field in the Setup, Data, Terminal Options dialog. fetch returns an integer equal to the tab spacing for the current terminal.

terminal type terminal | index | string

Specifies the current Terminal emulation. This command corresponds to the Current Terminal: list in the Setup, Data, Terminal Options dialog. An emulation keyword, the name of an emulation shown in the Current Terminal list, or the zero-based index of a listed emulation may be specified. fetch returns a string containing the name of the Current Terminal.

For a complete list of keywords and indices for emulations, see Emulation Names and Indices.

The set dialentry access command may be used to target a Data- or Telnet-class Connection Directory entry for the set terminal type command.

terminal update INCREMENTAL | BLOCK | FAST

Determines how the Terminal window is updated when data is received. This command corresponds to the Terminal update: field in the Setup, Data, Terminal Options dialog. fetch returns 0 for INCREMENTAL, 1 for BLOCK or 2 for FAST.

terminal viewcursor OFF | ON

Determines whether the emulation cursor is kept in view while the Terminal window is being updated. This command corresponds to the Keep cursor in view check box in the Setup, Data, Terminal Options dialog. fetch returns 0 for OFF or 1 for ON.


TVI922, VT220, VT320
TVI922, VT220, and VT320 Set/Fetch Statements

emulation bit8mode OFF | ON

Determines how the listed emulations respond to the 8 bit DEC sequences. If ON, the emulation expects command sequences to be prefixed by the cent character, ASCII 155, rather than ESC [, ASCII 27 and ASCII 91. This command corresponds to the 8 bit mode check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.

emulation charset DEC | ISO

Determines the emulation’s startup character set. If DEC is specified, the DEC multi-national character set is used on startup. If ISO is specified, the ISO Latin-1 character set is used. This command corresponds to the Startup Character Set check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the emulations listed. fetch returns 0 for DEC or 1 for ISO.

emulation cursorkeyapp OFF | ON

Determines whether emulation cursor keys generate normal DEC emulation sequences or special application sequences. This command corresponds to the Cursor Key Application Mode check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the emulations listed. fetch returns 0 for OFF or 1 for ON.

emulation keypadapp OFF | ON

Determines whether emulation numeric keypad keys generate normal DEC emulation sequences or special application sequences. This command corresponds to the Keypad Application Mode check box in the Setup, Terminal Options, Advanced Terminal Setup dialog for the listed emulations. fetch returns 0 for OFF or 1 for ON.


Task and Window IDs

  Related Topics

ASPECT allows the manipulation of both tasks and windows. However, tasks and windows are completely different entities and must not be confused! Task id’s represent an entire application running under Windows. Each task can have many separate windows which it displays and controls. Window id’s, on the other hand, represent a single window within a specific task.

ASPECT commands which relate to task manipulation usually begin with the word task in the command name, while commands which use window id’s typically begin with the letters win.


Task/Window Manipulation Commands

firsttask	Returns the first task encountered in the Windows Task List.

nexttask	Returns the next task encountered in the Windows Task List after the execution of a firsttask command..

taskactivate	Activates the task with the specified task id.

taskexists	Tests a task id value and determines whether the task still exists.

taskexit	Terminates a Windows task.

taskname	Returns the executable name associated with a specified task id.

taskpath	Returns the executable directory used by a specified task id.

taskwin	Returns the main or top-level window id associated with a task id.

winactivate	Activates the specified window.

winclose	Sends a "close" message to a window.

wincoord	Returns the location and dimensions of the specified window.

winenabled	Tests the target window to determine its availability to the user or the script.

winexists	Tests for the existence of a window.

winfocus	Specifies the window to receive keyboard input.

winhide	Conceals the target window from view.

winmaximize	Maximizes an application window to fill the screen.

winminimize	Minimizes an application window to an icon.

winmove	Positions an application window.

winowner	Returns owner ID of a window ID.

winrestore	Restores an application window to its previous size from a minimized state.

winshow	Makes a hidden window visible.

winsize	Sizes the specified application window.

winstate	Returns an integer indicating the state of a window.

wintask	Returns the task id of a window.

wintext	Returns the caption or title bar text of a window.

winvisible	Tests whether a window is hidden or visible.

 Return to category list


Terminal Commands

clear	Clears the Terminal window and the status line.

commandmode	Switches the modem on the current connection to command mode.

getcur	Returns the current cursor location on the Terminal display.

locate	Positions the terminal cursor to the location specified by row and column.

sbsave	Empties the Scrollback Buffer into a specified destination.

snapshot	Copies the contents of the current logical terminal screen to a specified destination.

termgetc	Returns a character value from the Terminal window.

termgets	Returns a string from the Terminal window.

termkey	Processes a virtual key value and shift state and sends it to the Terminal window.

termmsg	Writes a formatted string to the Terminal window.

termputc	Writes a character value to a specified location in the Terminal window.

termputs	Writes a string to a specified location in the Terminal window.

termreadc	Reads a character value from the Terminal window at the current cursor location.

termreads	Reads a string from the Terminal window at the current cursor location.

termreset	Resets the Terminal window.

termvkey	Processes an endcoded key value and acts upon it as if it were typed in the Terminal window.

termwritec	Writes a character value to the Terminal window.

termwrites	Writes a string to the Terminal window.

 Return to category list


The ASPECT Commands


The ASPECT Compiler

  Related Topics

The ASPECT Compiler is designed for both flexibility and ease of use. Its various options and settings allow you to determine the amount of information reported to you as your scripts are processed, as well as to control the information optionally stored for debugging activity.

The ASPECT Compiler resides in the Procomm Plus executable directory. It can be run from any application, not just Procomm Plus. For instance, you could select Run from the Windows 95 Start menu and type in "ASPCOMPW", followed by a script filename, and press <Enter> to launch the compiler. Or, if an application provides "programmable" keys or buttons, you could configure one of them to compile a file. Only Procomm Plus, however, allows the user to execute a compiled script.

See the following topics for more information:

The Compilation Process

Opening the Compile/Edit ASPECT File dialog

Compiler Options

Command-Line Syntax

Compile-Time Error Messages

Compiler Warning Messages

ASPECT Run-Time Error Messages


The ASPECT Script Environment

  Related Topics

The ASPECT script environment defines how a script interacts with actions, events, and other features in Procomm Plus such as keystrokes typed at the Terminal window or data received through the current connection. It also determines how the script interprets its own commands and how it controls the operation of other scripts it may launch.

ASPECT allows a script to define much of its own environment including global variables, when events, and dialog boxes for user interaction. These are all owned solely by the executing script and cannot be controlled by another script. Other environmental changes such as custom menus, the User window and packet transfer mode are not "tied" directly to the executing script, although interpreting these events from a second script would be difficult without some kind of understanding between the two scripts.

The critical environment issues for a script that is launched from another script are in regard to those settings that control how that script’s commands behave, and how the script interacts with external events. These "global" environment settings are referred to as the ASPECT environment.

The ASPECT environment consists of the User Path, the Aspect Path, and the settings affected by the set aspect command group.

An ASPECT script maintains its own current disk drive and current working directory. Together, these are referred to as the User Path. The User Path is maintained independent of any changes to the current drive and/or directory that are made outside of ASPECT.

The User Path is used as the default path for directory and file-related commands such as diskfree, getdir, getvolume, findfirst, mkdir, rename, and so forth. The User Path can be changed using the chdir command.

An ASPECT script also maintains its own default path, called the Aspect Path, which is separate and distinct from the User Path. The Aspect Path is referenced for dialog box and User window commands. When a filename without a path is specified in a filespec argument for one of these commands, ASPECT will look for the target file in the Aspect Path directory. The Aspect Path is also assumed for the set aspect helpfile, chain, compile, dllload, dllobjfile, and execute commands. It can be changed with the set ASPECT PATH command, or as an optional action in the chdir command.

Both the Aspect Path and the User Path are used in resolving partial path names. In general, a filespec with a partial path name will be evaluated based on the path normally associated with that command. No path resolution is performed for full path names or for path names that contain a drive designator. If a path name specifies only a drive designator, the current working directory for that drive is assumed.

When a script is executed, and no other script is currently running, it is assigned the default ASPECT environment settings. Included in this process are the normal script start-up functions: setting both the Aspect Path and the User Path to the path containing the script’s .wax file, and initializing the set ASPECT command values to their current defaults.


The ASPECT Utilities

  Related Topics

Two useful utilites, the Dialog Editor and the User Window Editor, are included with Procomm Plus to help design dialog boxes and User windows.

The Dialog Editor allows you to create and edit dialog boxes for use with ASPECT script files, using a visual approach that is much easier than coding a dialogbox statement group by hand. For more information, please refer to the Dialog Editor help file.

The User Window Editor helps you build graphical displays that appear in the Procomm Plus Terminal workspace. The editor allows you to create and edit your User windows with a visual approach that is much easier than making a uwincreate statement group manually. For more information, please refer to the User Window Editor help file.


The Compilation Process

  Related Topics

The ASPECT Compiler is a three-pass compiler. This means that it scans the script source file three times in order to produce the compiled target script file.

The first compilation pass is a quick scan through the file to determine the names of all defined procedures and functions and what each of their calling conventions in terms of parameter ordering and data type. In the case of user-defined functions, the return type is also determined. This pass is called the prototyping pass, and is required to insure that the next compilation pass knows how to correctly parse and verify calls to these procedures and functions.

The second compilation pass performs a syntactical scan of the source file. All variable references and command, procedure, and function arguments are verified for correctness.

If the first and second passes complete without errors, the third compilation pass, referred to as code generation, produces the compiled target script file. A previously existing target file will not be overwritten if the first or second pass produced errors and halted the compilation.


The Description Line

  Related Topics

Procomm Plus uses the first line of a source file for special processing. If that line is a comment beginning with a semicolon, Procomm Plus displays the first 50 characters of the line as a description for that script in the Compile/Edit ASPECT File dialog, and in the Run ASPECT File dialog. For example, if the first line of a source file read:

; Revision 3.0 of Notes.was, an example script

that text would also appear in the Notes field in the Run ASPECT File dialog when the compiled script was selected. The description line can be of any length, but only the first 50 characters will be displayed. If the first line of the source file is not a comment beginning with a semicolon, it is processed by the compiler as a normal command line, and the Notes field remains blank.


The Elements of ASPECT

  Related Topics

This following topics introduce the basics of the ASPECT programming language, including data and variable types, macro definitions, arrays and operators. You'll also find discussions about the basic conventions used throughout this help system and the rules that govern all ASPECT scripts.

ASPECT Building Blocks

The Description Line

Command Words and Parameters

Data Types

User-defined Constants

Escape Sequences

Character Constants

Naming Elements in ASPECT

Predefined Variables

System Variables

User-defined Variables

Global and Local Variables

Parameter Variables

Arrays

Procedures and Functions

Labels

Macros

ASPECT Operators

ASPECT Conventions

Task and Window IDs

Custom Interface Functions

Caret Translation

Formatting Text and Data

ASPECT Program Flow

ASPECT Command Form

The ASPECT Script Environment

Script Spawning and Chaining

Preprocessor Commands

Predefined Macro Definitions

Protocol Names and Indices

Emulation Names and Indices


The System Variables

  Related Topics

$A

$ACTIONBAR

$ACTIONBARS

$ACTIVEWIN

$ASPECTPATH

$ASPMENU

$C

$CALLERID

$CAPTURE

$CARRIER

$CHAINEDFILE

$CHATWIN

$CNCTMSG

$COL

$COMPANY

$CONNECTOPEN

$CTS

$D

$DATAOPTIONS

$DATE

$DDEADVISE

$DDIRFNAME

$DIALCHANGED

$DIALCONNECT

$DIALDIR

$DIALENTRY

$DIALING

$DIALQUEUE

$DIALSELECT

$DTR

$E

$ERRORNUM

$EXITCODE

$F

$FATTR

$FAXFILE

$FAXMESSAGE

$FAXOPTIONS

$FAXRECVCNT

$FAXSENDCNT

$FAXSTATUS

$FDATE

$FEXT

$FILENAME

$FILESPEC

$FLOWSTATE

$FLTIME

$FNAME

$FOCUSWIN

$FSIZE

$FTIME

$FTPCONNECT

$FTPOPTIONS

$FTPSTATUS

$I

$IPADDRESS

$K

$KEYHIT

$L

$LMOUSEEVENT

$LMOUSESTATE

$LMOUSEWIN

$LMOUSEX

$LMOUSEY

$LTIME

$M

$MAILOPTIONS

$MAINWIN

$MAPIENABLED

$MCIDEVICEID

$MCINOTIFY

$METAKEYS

$MISC

$MMOUSEEVENT

$MMOUSESTATE

$MMOUSEWIN

$MMOUSEX

$MMOUSEY

$MODEMCONNECT

$MONITORWIN

$N

$NEWSOPTIONS

$NEWSSTATUS

$NULLSTR

$NUMCOLORS

$NUMTASKS

$O

$OBJECT

$OS

$OSVER

$P

$PARENTFILE

$PASSWORD

$PKRECV

$PKSEND

$PLAYBACK

$POINTERTASK

$POINTERWIN

$POINTERX

$POINTERY

$PROTOCOL

$PWACTIVE

$PWLOCALPATH

$PWMAINWIN

$PWMENUBAR

$PWMENUDEF

$PWMODE

$PWTASK

$PWTASKPATH

$PWTITLEBAR

$PWVER

$PWWINSTATE

$Q

$QUICKSELECT

$R

$RMOUSEEVENT

$RMOUSESTATE

$RMOUSEWIN

$RMOUSEX

$RMOUSEY

$ROW

$RTS

$RXCOUNT

$RXDATA

$S

$SCRIPTENV

$SCRIPTFILE

$SCRIPTMODE

$SCROLLBACK

$SERIALNUM

$SETUP

$SFILENAME

$STATMSG

$STATIONID

$STATUSLINE

$T

$TASK

$TELNETOPTIONS

$TERMCOLS

$TERMCOLORS

$TERMFONT

$TERMINAL

$TERMROWS

$TIME

$TIME24

$TITLEBAR

$TXCOUNT

$TXDATA

$U

$USERDISK

$USERDISKSTR

$USERID

$USERNAME

$USERPATH

$USERWIN

$UWINACTIVE

$V

$VOLUME

$W

$WINCOLORS

$WINPATH

$X

$XFERFILE

$XFERSTATUS

$XOFFRECV

$XOFFSENT

$XPIXELS

$Y

$YPIXELS


The User Window

  Related Topics

A User window is defined with the uwincreate command, which requires arguments and keywords describing the size, position, color and behavior of the window. Elements attached to the User window are known as objects, and are created with the appropriate ASPECT commands following the uwincreate statement.

There is a limit of 32 active objects for each object type. Only one DLL object file can be active at a time, but that DLL can handle multiple objects in the User window.

User Window Object Id’s

Each User window object is assigned its own id value. User window object id’s may have any integer value greater than zero. Duplicate ids are not flagged by the compiler and should be avoided.

The object id is used with the object-related commands such as objhide and objmove to manipulate the object. The value is also assigned to the $OBJECT system variable when the object has been selected by the user. For more information, see the description of the uwincreate command.

User Window Units

User window objects are placed and sized based on User Window Units, or UWUs. An UWU is defined as 1/10000 of the horizontal width and 1/10000 of the vertical height of the background graphic. Units based on the size of the background graphic allow graphic displays designed on one screen resolution to be more accurately represented on different screen resolutions.

In most cases, you will not need to worry about calculations involving User Window Units, as the User Window Editor conveniently handles them for you!


The when ... call Command

  Related Topics

Microsoft Windows is an event-driven environment. This means that programs perform tasks when specific events occur. For example, Windows tells programs when they should draw graphics on the screen, when someone clicks on a button or icon and even when they are allowed to use a device on your system. ASPECT takes advantage of this event-driven design with the when command.

when allows your script to watch for events while it’s performing other activities. For example, suppose that you’re connected to a host system that displays a prompt after every 24 lines of information and waits for you to press <Enter>. You want Procomm Plus to press <Enter> for you when this event occurs. We can accomplish this easily with the when command. Examine the script example below:

proc main

   ; Declare a when command that watches for the prompt and calls

   ; another procedure to send a carriage return.

   when TARGET 0 " Press Enter " call PressEnter

   while $CARRIER               ; Loop while connected.

      yield                     ; Yield script processing time

   endwhile

   when TARGET 0 CLEAR          ; Clear the when clause.

endproc

proc PressEnter

        transmit "^M"           ; Send a carriage return.

endproc

In our example, we declare a when command to watch for the prompt from the remote system. We also suspend the script while we’re on-line or connected using the while ... endwhile loop. Notice that we use the TARGET option to tell ASPECT what type of event to watch for. In this case, TARGET specifies that we’re expecting to receive a text string. The number following the TARGET option is the index of this when clause. Any time Procomm Plus receives the string "Press Enter" our script file sends a carriage return.

There are many events besides when TARGETs that you can watch for in your script files. You can watch for dialog events, key presses, user exits or even sense when incoming information has stopped. Let’s take a look at each of the when commands that you can use in your script files:

when DIALOG 0 call ProcessEvent

This is an example of using the when command to check for dialog events. When you click on an object in the dialog with an id of 0, your script calls the procedure named ProcessEvent. ProcessEvent reads and evaluates the value returned by the dlgevent command.

We’ll discuss dialog boxes in more detail later. For now, let’s take a look at a when clause that watches for a key press:

when ISKEY 0 ’A’ call AKeyPressed

This when clause tells ASPECT to call the procedure named AKeyPressed each time you press the "A" key on your keyboard. As with when TARGETs, an index is used to differentiate multiple when ISKEY clauses. Use the index to selectively clear your when ISKEY clauses. ‘A’ is a constant that the compiler replaces with the value of the "A" key when the script is compiled. ’A’ can be replaced by other virtual key values.

when QUIET 10 call Done

when QUIET allows a script to call a procedure when the communications line is quiet for a specified number of seconds. In the line above, we’re telling our script file to call the procedure called Done when the line is quiet for 10 seconds. If data is received during each 10 second period, Done is never called. If no data is received for over 10 seconds, Done is called.

On the other hand, we may want to call a procedure in timed intervals. Suppose we need a script that calls a procedure every 30 seconds and sends a space character. Our script file might contain the following line:

when ELAPSED 30 call SendSpace

In this example, our script will call the SendSpace procedure every 30 seconds. The SendSpace procedure is used to transmit the space character.

Finally, when clauses may be used to sense when users try to exit our script files. Look at the following line:

when USEREXIT call CleanUp

USEREXIT tells ASPECT that you want to call the specified procedure every time the Stop Script icon is selected, or when the user selects Stop Script from the Tools | Scripts menu. We could use CleanUp to perform final operations to insure that our script exits properly, restoring Setup options that it changed, or closing files. It’s important to remember that you must use the exit or quit command to stop your script if you have created a when USEREXIT clause. Otherwise, the script keeps running even though the user tried to stop it!

Exercise

Create a script file that prompts you with a confirmation message when you try to exit the script.

Use the sdlgmsgbox command to make the message box handling a little easier.


User Window Commands

bitmap	Places a bitmap graphic in the User window.

bitmapbkg	Places a bitmap background in the User window.

dllobject	Identifies a graphic object within a User window to be updated by an associated DLL module.

dllobjfile	Specifies a file containing a graphic object to be accessedd or updated with the dllobject command.

dllobjupdt	Allows a DLL module linked to a DLL object to update that object.

hotspot	Places a mouse-selectable rectangle in the User window.

icon	Displays an icon graphic in the User window.

iconbutton	Displays an icon graphic as a clickable button in the User window.

metafile	Displays a metafile graphic in the User window.

metafilebkg	Places a metafile background in the User window.

objcoord	Returns the location coordinates of an object in the User window.

objhide	Hides an object, or a range of objects in the User window.

objmove	Moves an object identified by an id number to a new location in the User window.

objpaint	Updates the User window and some or all of the objects it contains.

objpointid	Returns the object id, if any, of an object located at a specific point.

objremove	Removes one or more objects from the User window.

objshow	Displays an object previously hidden with objhide.

pushbutton	Places a standard button control in the User window.

uwincreate	Defines a User window which occupies all or part of the Terminal window.

uwinpaint	Paints the entire User window and all of its objects.

uwinremove	Removes the User window background or the entire User window.

uwutowin	Converts X/Y User Window Units to window coordinates.

wintouwu	Converts X/Y coordinates relative to a window into User Window Units.

 Return to category list


User-defined Constants

  Related Topics

A numeric constant is assigned to a particular data type based upon its value and representation. A floating point constant is a decimal number representing a signed real number; it contains an integer part, a fractional part, and an exponent. Floating point constants have the following formats:

[-] digitstr. [digitstr] [e|E [+|-] digitstr ]

or	[-] .digitstr [e|E [+|-] digitstr ]

or	[-] digitstr e|E [+|-] digitstr

where digitstr is a sequence of one or more decimal digits.

No spaces may occur between the characters in the constant. Spaces are shown in the format syntaxes above for readability.

Integer and long constants are signed values which can be represented in decimal (base 10), octal (base 8) or hexadecimal (base 16) notation. A minus sign may precede a constant to make it a negative value.

If the constant begins with the characters "0x" or "0X", it represents a hexadecimal constant; digits ’0’ through ’9’ and ’A’ (or ’a’) through ’F’ (or ’f’) are allowed. If a constant begins with the digit 0, it represents an octal constant; digits ’0’ through ’7’ are allowed. If a constant does not begin with either "0x", "0X", or "0", it is assumed to be a decimal value.

The letter 'l' or 'L' may be applied as a suffix to a integer or long constant to force it to have long type.  The uppercase letter is recommended because the lowercase letter can easily be confused with the number 1. If a suffix is not used, the type assigned to a constant is determined from its value in the absence of a leading minus sign. If the constant is a decimal value, and its value is within the positive range allowed by integer values, it is assigned integer type. Otherwise it is assigned long type.  If the constant is a hexadecimal or octal value between 0 and 0xFFFFFFFF or 037777777777, the constant is assigned integer type.  If the value is decimal and is greater than the largest positive long value, a compile-time error will result.

For example, the smallest integer value -2147483648 can only be represented in hexadecimal or octal notation since, in the absence of the minus sign, the value of the constant is greater than the largest positive integer value.  Thus 0x80000000, for example, can be used to represent this number without generating compile-time errors.  Note that -0x80000000 or -020000000000 will also work.

Note that since integers and longs have the same range of values, the only way to denote a long constant is to use a long suffix.

ASPECT does not provide any unsigned data types.  However certain commands will treat an integer value as an unsigned value.  This means the integer value is always considered a positive value ranging from 0 to 4294967295, even if the integer is specified as a negative decimal value.  Since a positive integer constant may only be specified in decimal up to 2147483647, another notation, hexadecimal or octal, is generally used to represent unsigned integer values larger than this. A negative integer value will work, but its meaning is not as clear as the hexadecimal or octal representation of that number.  For instance -1 is the same as 0xFFFFFFFF or unsigned value 4294967295, -2 is the same as 0xFFFFFFFE or unsigned value 4294967294, and so forth down to -2147483648 which is 0x80000001 or unsigned value 2147483649, and 0x80000000 which represents the integer value -2147483648 or the unsigned integer value 2147483648.

A string constant  is represented by a list of up to 256 characters enclosed within double quotes. Any ASCII character value may occur in a string variable, although some characters are not displayable. To use a quotation mark within a text string, precede it with the special escape character `, ASCII 96. For example:

usermsg "She said `"Hello`"".

The NULL character, ASCII 0, normally indicates the end of a text string and is not considered a part of the 256-character limit. Special escape sequences can be embedded in strings using the "back tick" character, as discussed in Escape Sequences.

For security, all string constants are encrypted during compilation so that they cannot be viewed in the compiled script.


User-defined Variables

  Related Topics

ASPECT uses named elements called variables to store and manipulate values within a script. Variables are passed as arguments to commands, and can be used within expressions. User-defined variable names must adhere to the rules for valid element names. We recommend that you use easily-recognized names that will help you to identify the purpose of particular variables within your script’s source code.

A user-defined variable can be an integer, float, long, or string. For more information about the use of user-defined variables, see Global and Local Variables.


Using Command Descriptions

command

command parameters KEYWORDS

This sample description, for an imaginary ASPECT command called "command", demonstrates and explains the layout used throughout this help system:

The text following the command header provides a brief explanation of the command’s purpose. If the command returns SUCCESS and FAILURE, this text will be marked with an "S/F" bullet - just as this text is. Following the statement of purpose, the command’s full syntax is shown in bold face:

command parameters KEYWORDS

parameters	Parameters are shown in the syntax statement using the terms listed in "ASPECT Conventions". Parameters are always shown in lowercase, and in italic face if they appear in body text.

KEYWORDS	ASPECT KEYWORDS are always shown in uppercase, whether they appear in body text, script examples, syntax lists or headings.

Comments

The "Comments" section provides more detailed information about the command. It often contains notes regarding the command’s interactions with other ASPECT commands or suggestions about using the command in special situations.

ASPECT commands appearing in body text are always shown in lowercase and boldface. For example, addfilename.

ASPECT script examples present all command names in lowercase. However, the only case-sensitive elements within ASPECT are quoted strings and format specifiers used in commands like fstrfmt and strfmt. Feel free to use any combination of upper- and lowercase characters in your scripts to make your code easier to read.

If a command’s purpose is related to other ASPECT commands, set/fetch options or system variables, they will be listed in a "See also" section following any "Comments".


Variables: the basics

  Related Topics

The rest of the examples use an important feature of the ASPECT language: global and local variables.

A variable is a symbol that stands for a changeable value. For example, in the expression "x = 1", x is a variable. Later in your script you can change this variable with the statement "x = y + 1". First x has the value 1 and after the second expression is evaluated, x takes on the value of another variable, y, plus one. Since x is a variable, it's value can change value in the course of a script.

Variables

Variables may represent various data types, including integers and strings. The variable types used most often are strings, integers, and floats for decimal point values. For a more detailed discussion of ASPECT’s data types, see "Data Types".

You must define a variable before your script can use it. Defining a variable involves specifying a name and data type for the variable. This allows the ASPECT Compiler to allocate resources for the variable, and to properly interpret the ASPECT commands which use it.

Variables are normally defined at the beginning of a procedure or function, although a variable definition can occur almost anywhere within an ASPECT script.

Variable Names

Variable names in ASPECT may have up to thirty distinct characters. You can use either upper- or lowercase characters. The compiler treats names in a case-insensitive manner. Thus, "MyValue" and "MYVALUE" each refer to the same variable.

In our examples, we’ve used mixed case characters for variable names because they are easier to read.

Local Variables

This script example shows how variables are declared:

proc main              ; Beginning of main procedure.

string Name            ; Declare string variable called "name".

   Name = "Fred^M"     ; Assign the value of name

   transmit Name       ; and send "Fred^M" out the port.

endproc

In this example, "string Name" tells the compiler to create a variable called "Name", which will contain character data. Once this line is encountered in the file, Name may be used anywhere inside the procedure called main.

Global Variables

Since the "string Name" variable definition appears inside the procedure after the "proc main" statement, it is known as a local variable. It is not available to other procedures. If you move the line outside of the main procedure, the variable becomes available to all procedures in the script and is known as a global variable:

string Name             ; Define the global string variable "Name"

proc main               ; Beginning of main procedure.

   Name = "Fred^M"      ; Assign text to the variable.

   call SendData        ; Call another procedure.

endproc                 ; End of main procedure.

proc SendData           ; Procedure called by another procedure.

   transmit Name        ; Send value of the global variable "Name"

   usermsg "Done!"      ; Put up a message box.

endproc                 ; End of SendData procedure, execution

                        ; returns to calling procedure.

In this case, the variable Name maintains the value "Fred^M" in all procedures, and the word "Fred" is transmitted, followed by a carriage return in SendData. But if we change the value of Name in the main procedure, it changes in SendData as well, because it was declared globally.

Notice how the "=" operator is used to assign a value to the Name variable. You may also assign values to variables when they’re declared, as shown in the following script segment:

string Name = "Fred^M"


Virtual Key Codes Table

  Related Topics

The table below details the mnemonic constant names, hexadecimal values, and key-names for Microsoft Windows virtual key codes, in numeric order. Keys described as "Keyboard specific" may not appear on every keyboard.

Note that VK_A through VK_Z are the same as their ASCII equivalents (’A’ through ’Z’ with hexadecimal values from 0x41 thru 0x5A). VK_0 through VK_9 are the same as their ASCII equivalents (’0’ thru ’9’ with hexadecimal values from 0x30 through 0x39).

To #define these mnemonic key-names and values in your scripts, simply #include the file vkeys.inc, which is located in your default ASPECT directory.

Only keycodes which have an actual keyboard equivalent can be used in a key-sending command. The mouse-related keycodes, for example, cannot be sent. Likewise, you cannot use the keyget command to see a mouse button event. However, you can use the mouse keycodes in a command such as keystate to determine the state of a mouse button.

Virtual Key Codes Table

Mnemonic	Value	Description
VK_LBUTTON	0x01	Left mouse button
VK_RBUTTON	0x02	Right mouse button
VK_CANCEL	0x03	Ctrl-Break
VK_MBUTTON	0x04	Middle mouse button
	0x05-0x07	Undefined
VK_BACK	0x08	Backspace key
VK_TAB	0x09	Tab key
	0x0A-0x0B	Undefined
VK_CLEAR	0x0C	Clear key or Keypad 5 with Num lock off
VK_RETURN	0x0D	Enter or Return key
	0x0E	Undefined
	0x0F	Undefined
VK_SHIFT	0x10	Shift key
VK_CONTROL	0x11	Control or Ctrl key
VK_MENU	0x12	Menu or Alt key
VK_PAUSE	0x13	Pause key
VK_CAPITAL	0x14	Capital or Caps Lock key
	0x15-0x19	Reserved for Kanji Systems
	0x1A	Undefined
VK_ESCAPE	0x1B	Esc or Escape key
	0x1C-0x1F	Reserved for Kanji Systems
VK_SPACE	0x20	spacebar
VK_PRIOR	0x21	Page Up key
VK_NEXT	0x22	Page Down key
VK_END	0x23	End key
VK_HOME	0x24	Home key
VK_LEFT	0x25	Left arrow key
VK_UP	0x26	Up Arrow key
VK_RIGHT	0x27	Right Arrow key
VK_DOWN	0x28	Down Arrow key
VK_SELECT	0x29	Select key
VK_PRINT	0x2A	OEM specific
VK_EXECUTE	0x2B	Execute key
VK_SNAPSHOT	0x2C	Print Screen key
VK_INSERT	0x2D	Insert key
VK_DELETE	0x2E	Delete key
VK_HELP	0x2F	Help key
VK_0-VK_9	0x30-0x39	0 key through 9 key
	0x3A-0x40	Undefined
VK_A-VK_Z	0x41-0x5A	A key through Z key
	0x5B-0x5F	Undefined
VK_NUMPAD0	0x60	Numeric Keypad 0
VK_NUMPAD1	0x61	Numeric Keypad 1
VK_NUMPAD2	0x62	Numeric Keypad 2
VK_NUMPAD3	0x63	Numeric Keypad 3
VK_NUMPAD4	0x64	Numeric Keypad 4
VK_NUMPAD5	0x65	Numeric Keypad 5
VK_NUMPAD6	0x66	Numeric Keypad 6
VK_NUMPAD7	0x67	Numeric Keypad 7
VK_NUMPAD8	0x68	Numeric Keypad 8
VK_NUMPAD9	0x69	Numeric Keypad 9
VK_MULTIPLY	0x6A	Multiply key
VK_ADD	0x6B	Add key
VK_SEPARATOR	0x6C	Separator key
VK_SUBTRACT	0x6D	Subtract key
VK_DECIMAL	0x6E	Decimal key
VK_DIVIDE	0x6F	Divide key
VK_F1	0x70	Function key F1
VK_F2	0x71	Function key F2
VK_F3	0x72	Function key F3
VK_F4	0x73	Function key F4
VK_F5	0x74	Function key F5
VK_F6	0x75	Function key F6
VK_F7	0x76	Function key F7
VK_F8	0x77	Function key F8
VK_F9	0x78	Function key F9
VK_F10	0x79	Function key F10
VK_F11	0x7A	Function key F11
VK_F12	0x7B	Function key F12
VK_F13	0x7C	Function key F13
VK_F14	0x7D	Function key F14
VK_F15	0x7E	Function key F15
VK_F16	0x7F	Function key F16
VK_F17	0x80	Function key F17
VK_F18	0x81	Function key F18
VK_F19	0x82	Function key F19
VK_F20	0x83	Function key F20
VK_F21	0x84	Function key F21
VK_F22	0x85	Function key F22
VK_F23	0x86	Function key F23
VK_F24	0x87	Function key F24
	0x88-0x8F	Unassigned
VK_NUMLOCK	0x90	Num Lock key
VK_OEM_SCROLL	0x91	Scroll Lock key
	0x92-0xB9	Unassigned
	0xBA-0xC0	Keyboard specific
	0xC1-0xDA	Unassigned
	0xDB-0xE4	Keyboard specific
	0xE5	Unassigned
	0xE6	Keyboard specific
	0xE7-0xE8	Unassigned
	0xE9-0xF5	Keyboard specific
	0xF6-0xFE	Unassigned


Warning Level

  Related Topics

The Warning Level setting determines whether the compiler reports warnings, in addition to any syntax errors encountered in the script:

Level 0.

All warnings are suppressed..

Level 1.

The compiler reports unreferenced global, local and parameter variables, unreferenced labels, too many or too few arguments in a macro expansion, and cases where scripts are too large to compile. Level 1 is the default setting.

Level 2.

All Level 1 errors are reported as well as instances of unreferenced procedures or functions, functions ending without return values and redefinitions of user-defined global symbols.


Warning Level 1 Messages

  Related Topics

C700	Too many/few arguments in macro expansion
C701	Unreferenced label
C702	Unreferenced parameter
C703	Unreferenced local variable
C704	Unreferenced global variable
C705	Far calls required (use /F command line option)


Warning Level 2 Messages

  Related Topics

C800	Unreferenced procedure/function
C801	Function ends without returning a value
C802	Redefinition of user-defined global symbol


What Are Scripts?

  Related Topics

If you’ve called an on-line service, host system or electronic bulletin board before, you’ve probably found yourself performing many repetitive tasks. For instance, each day you may connect to a host system, logon with your ID and password, read any new electronic mail you’ve received, upload a data file and logoff. Although this example session is quite simple, it can be tedious. Why not let Procomm Plus do it for you automatically?

An ASPECT script file is a simple ASCII text file you create containing commands to be executed by Procomm Plus. In our example above, you could write a script "source" file, using the ASPECT Editor or another text editor, that would call or connect to your host and perform the same functions, just as if you were entering them at the keyboard. To run the script, you'd compile it, then select the script name from the Action Bar's Script File list box. We’ll discuss more about how you create scripts and the difference between source and compiled script files later. For now, let’s outline a few more of the many applications for ASPECT:

•	Automated fax operations.

If you regularly send or receive faxes, an ASPECT script can easily handle the task for you. It can automatically forward your received faxes to you at another location, and advise you if there was a problem.

•	Automated file transfers.

If you need to transfer files at regular intervals, it’s easy to automate the process as a "background" task. An ASPECT script can connect to a host system and transfer files unattended at the time you set. If an error occurs or Procomm Plus can’t connect, your script can warn you with a dialog message or an alarm tone.

•	Script applications.

Script modules that integrate seamlessly with Procomm Plus, complete with Windows dialog controls, file I/O, printer output, Dynamic Data Exchange (DDE) and error-free packet transfer can all be created with ASPECT. For example, your script could retrieve its spreadsheet data from a Microsoft Excel before it connected to your host, or you could display a dialog box to allow the printing of your received mail. ASPECT offers the power and tools you’ll require to build just about any Windows application!

•	Running your own BBS.

You can use the ASPECT Host script to run your own bulletin board system. The Host script features public and private messages, file transfers, a Chat Mode, call-back and faxes. You can even modify the Host source file and recompile it to add new features or customize the appearance of your system!

•	"Packet mode" transfers.

Two PCs running Procomm Plus can transfer binary data continuously to each other in "packets". This error-free method ensures that commands and characters you type are received accurately by the remote system.

•	Customized features or commands.

You can customize Procomm Plus to add extra commands to the menu system, or you can display your own User window graphics as a portion of the Terminal window, complete with "hot spots", icons and buttons.

Like most other programming languages, ASPECT requires you to "compile" your programs. During this process, the commands, data and text contained in an ASPECT source or .was file are checked for accuracy and reduced from their full-length English format into code that Procomm Plus can read and process quickly. After compiling, the resulting ASPECT executable or .wax file is smaller in size. Also, because any string data is encrypted in the .wax file, it’s much more secure! No one can read your sensitive passwords or other information.

A source script file must be compiled before it can be executed. Source files are not affected in any way by the compile process.

A compiled .wax file cannot be converted to its .was source.


What's been covered?
What’s been covered?

  Related Topics

In the previous examples, you’ve learned the basics of ASPECT and seen some of its real-world applications. If you worked your way through this tutorial, you probably noticed that ASPECT can automate on-line sessions and many more complex tasks! With the added tools provided in the Script Recorder, Dialog Editor and User Window Editor, every level of user can tap into some of the power of ASPECT.

Of course, a tutorial like this can only scratch the surface of a powerful language like ASPECT. Some of the areas not covered in this tutorial include the string manipulation commands, the file I/O commands, the set and fetch commands, conditional compilation and loading DLLs.

Now that you’ve gone through the tutorial, look back through the The Elements of ASPECT and the ASPECT Script Reference sections and study the commands and explanations in greater detail.


ZMODEM Protocol Set/Fetch Statements

The following set/fetch zmodem statements control the operation of the Zmodem transfer protocol. They correspond to options in Setup, Data, Transfer Protocol, with Zmodem selected as the Current Protocol.

zmodem eolconvert OFF | ON

Determines whether Linefeeds, ASCII 10, are changed according to the End of Line convention for the system receiving the file. If ON is specified, Linefeeds in a received file are translated to Carriage Return/Linefeed, ASCII 13/ASCII 10 pairs. This command corresponds to the Use local EOL convention check box. fetch returns 0 for OFF or 1 for ON.

zmodem errordetect CRC16 | CRC32

Determines the error-detection method used in Zmodem file transfers. This command corresponds to the Error detection list. fetch returns 0 for CRC16 or 1 for CRC32.

zmodem origtime OFF | ON

Determines whether files received with the Zmodem protocol preserve their original time and date stamps or the time and date stamps are changed to the time the file is saved. This command corresponds to the Original file time stamp check box. fetch returns 0 for OFF or 1 for ON.

zmodem receiver crashrecover OFF | ALWAYS | CRC | TIMESTAMP | SENDER

Determines how aborted Zmodem downloads are restarted. This command corresponds to the Crash Recovery Options in the Zmodem Receive Options dialog which is available after clicking Change Settings... in the Receiver Crash Recovery Settings groupbox. fetch returns 0 for OFF, 1 for ALWAYS, 2 for CRC, 3 for TIMESTAMP or 4 for SENDER.

zmodem receiver overwrite NEWER | ALWAYS | SKIP | RENAME

Suggests how filename collisions should be handled during a Zmodem download. This command corresponds to the Overwrite Options in the Zmodem Receive Options dialog which is available after clicking Change Settings... in the Receiver Crash Recovery Settings groupbox. fetch returns 0 for NEWER, 1 for ALWAYS, 2 for SKIP and 3 for RENAME.

zmodem sender crashrecover OFF | ALWAYS | CRC

Determines how aborted Zmodem uploads are restarted by the host. This command corresponds to the Crash Recovery Options in the Zmodem Send Options dialog which is available after clicking Change Settings... in the Sender Crash Recovery Settings groupbox. fetch returns 0 for OFF, 1 for ALWAYS or 2 for CRC.

zmodem sender overwrite NEWER | ALWAYS | SKIP

Suggests how the remote system should handle filename collisions during Zmodem transfers. This command corresponds to the Overwrite Options in the Zmodem Send Options dialog which is available after clicking Change Settings... in the Sender Crash Recovery Settings groupbox. fetch returns 0 for NEVER, 1 for ALWAYS or 2 for SKIP.

zmodem txmethod STREAMING | 2KWINDOW | 4KWINDOW

Determines the transmit method used by the Zmodem protocol. This command corresponds to the Transmit method list. fetch returns 0 for STREAMING, 1 for 2KWINDOW or 2 for 4KWINDOW.


addfilename

addfilename pathname filename

Adds a specified filename to a path.

pathname	A string variable containing the path to which the filename will be appended.

filename	A string containing the filename to append.

Example

proc main

   string szPath = "C:\"          ; Path to file.

   string szFname = "File.TXT"    ; Name of file to add to path.

   addfilename szPath szFname     ; Adds the file name to path.

   usermsg "Full path = `"%s`"." szPath

endproc

Comments

addfilename checks the supplied path for a terminating backslash or colon and automatically adds a backslash if appropriate. After the command executes, the completed path is stored in the pathname string variable.

See also

getdir and fullpath; $USERPATH, $ASPECTPATH and $PWLOCALPATH; DOS- or Disk-Related Commands.


alarm

alarm [integer]

Sounds an alarm to alert you to an event.

integer	An optional integer value that specifies the number of seconds the alarm will sound.

Example

proc main

   commandmode ON             ; Enable modem command mode

   pause 1                    ; Wait for start of command mode

   transmit "ATDT5559375^M"   ; Transmit modem command to dial

   if waitfor "CONNECT" 45    ; Wait for a connect for 45 seconds

      alarm 5                 ; Sound the alarm for 5 seconds.

   else

      errormsg "`"CONNECT`" message not found."

   endif

   commandmode OFF

endproc

Comments

alarm uses the Windows default beep sound and is not affected by the status of the set alarm command. The beep will repeat for the duration of the specified alarm time, but a <Ctrl><Break> sequence will abort the alarm sound.

See also

beep and mciexec; set alarmtime command; General Procomm Plus Commands.


ansitokey

ansitokey character intvar

Converts an ANSI character to its corresponding virtual key value and keyboard shift state.

character	The ANSI character to convert.

intvar	The character’s converted keyvalue.

Example

proc main

   integer KeyCode         ; Virtual key code of character.

   ansitokey 'A' KeyCode   ; Get Virtual key code of 'A'.

   termvkey KeyCode        ; Send virtual key code to terminal.

endproc

Comments

The shift state is contained in the high-order byte, and the key code in the low-order byte, as returned by keyget or accepted by termvkey. The numeric keypad keys will not be converted, since ansitokey translates only the main keyboard keys. If the character does not correspond to a key, a (-1) is returned.

See also

ansitooem, keytoansi, keyget and termvkey; Keyboard Commands; OEM/ANSI Commands.


ansitooem

ansitooem {character intvar}{string strvar [strlength]}

Converts an ANSI character or string to OEM equivalent.

character	The ANSI character to convert.

intvar	The character’s converted OEM value.

string	The string to convert to OEM.

strvar	Will contain the converted string.

strlength	The number of characters in the string to convert. If strlength is not specified, the entire contents of the string will be converted.

Example

proc main

   integer ChrVal               ; Variable used for char value.

   ansitooem 0xA9 ChrVal        ; Convert copyright character from

   ; ANSI character set to OEM

   ; character set.

   usermsg "0x%X" ChrVal        ; Display the OEM value for the

endproc

See also

ansitokey and oemtoansi; set aspect codepage command; OEM/ANSI Commands.


atof

atof string floatvar

Converts the contents of an ASCII string to a floating point value.

string	String to convert to a float variable.

floatvar	Variable where the float value is stored.

Example

proc main

   string Input                     ; String used for input.

   float Number                     ; Floating Point number.

   if sdlginput "Float Number Conversion Example" "Enter a Floating Point Number:" Input

      atof Input Number             ; Convert string to float value.

      usermsg "You entered %f!" Number

   endif

endproc

Comments

atoi, atof and atol skip leading white space, including spaces and tabs. Conversion begins at the first numeric character and ends at the first character which is not a part of the number format. The format for floats is:

[sign] [ digits] [.digits] [{d|D|e|E} [sign] digits]

If the string doesn’t contain a float value, atof assigns a value of 0.0.

atof will only convert numbers in base 10.

See also

atoi, atol, ftoa and strtonum; Numeric, String Conversion Commands.


atoi

atoi string intvar

Converts the contents of an ASCII string to an integer value.

string	String to convert to an integer.

intvar	Variable where the integer is stored.

Example

proc main

   string Input                     ; String used for input.

   integer Number                   ; Integer Number.

   if sdlginput "Integer Conversion Example" "Enter an Integer:" Input

      atoi Input Number             ; Convert string to integer.

      usermsg "You entered %d!" Number

   endif

endproc

Comments

Conversion begins at the first digit encountered in the string and stops at the first non-numeric character. If the string doesn’t contain an integer value, atoi assigns a value of 0.

atoi will only convert numbers in base 10.

See also

atof, atol, itoa and strtonum; Numeric, String Conversion Commands.


atol

atol string longvar

Converts the contents of an ASCII string to a long value.

string	String to convert to a long value.

longvar	Variable where the long is stored.

Example

proc main

   string Huge                     ; String used for input.

   long HugeNumber                 ; Number converted from String.

   if sdlginput "Big Numbers" "Enter Number (0 to 2147483647):" Huge

      atol Huge HugeNumber         ; Convert string to long.

      if HugeNumber < 50000        ; See if number is smaller than 50000

         usermsg "%ld isn't so big..." HugeNumber

      else

         usermsg "%ld IS a big number!" HugeNumber

      endif

   endif

endproc

Comments

Conversion begins at the first digit encountered in the string and stops at the first non-numeric character. If the string doesn’t contain a long value, atol assigns a value of 0.

atol will only convert numbers in base 10.

See also

atoi, atof, ltoa and strtonum; Numeric, String Conversion Commands.


beep

beep

Sounds a beep tone, using the Windows default beep sound.

Example

proc main

   transmit "^M^M^M"          ; Send three CR's to wake up host.

   if waitfor "HOST:"         ; Wait for command prompt.

      statmsg "Connected to host."

   else

      statmsg "Host connection not established."

   endif

   beep                       ; Sound the system beep.

endproc

See also

alarm and mciexec; General Procomm Plus Commands.


bitmap

bitmap id left top width height filespec

(or) bitmap id left top label filespec BACKGROUND | USERWIN

Places a bitmap graphic in a dialog box or in the User window. bitmap can only be tested for SUCCESS/FAILURE when it appears in a User window.

Dialog box format

bitmap id left top width height filespec

id	A unique integer constant value assigned to each bitmap.

left top	Integer constant values in Dialog Box Units (DBUs) which determine the position of the top left corner of the bitmap with respect to the dialog box. For more information on DBUs, see Dialog Box Units.

width height	Integer constant values in DBU’s which determine the width and height allowed for the bitmap. Care should be taken in setting the values for width and height. Unlike the format of the uwincreate or User window bitmap command, the dialog box form allots the width and height specified within the command. This could either clip the bitmap, or leave a graphical gap on the right-most or bottom edge of the bitmap.

filespec	A string constant or string variable describing the filename and path of the bitmap to display.

Example

proc main

   ; Display a dialog box and a bitmap. You must have a

   ; bitmap named "cars.bmp" in your script directory.

   dialogbox 0 0 0 100 50 11 "Bitmap Example"

      bitmap 1 5 5 90 40 "cars.bmp"

   enddialog

   pause 5              ; Pause to show off dialog.

   dlgdestroy 0 CANCEL  ; Destroy the dialog box.

endproc

Comments

If no path is included in the filespec argument, the bitmap will be sought in the Aspect Path.

dlgupdate can be used to refresh the bitmap, making it possible for a script to dynamically change the displayed graphic.

See also

dialogbox, dlgupdate, icon, iconbutton and metafile; Dialog Box Commands.

User window format

bitmap id left top label filespec BACKGROUND | USERWIN

id	A unique integer value assigned to each bitmap. The $OBJECT system variable will be updated to this id value when the bitmap is selected by the user with the left mouse button. It is also used with the objpaint command to update the bitmap, and the objremove command to remove the bitmap from the User window.

left top	Integer values which determine the position of the top left corner of the bitmap with respect to the User window or the background graphic. Each integer is expressed in User Window Units or UWUs. For more information on UWUs, see User Window Units.

label	Label displayed with this bitmap. The ampersand (&) can be used to indicate an accelerator for the bitmap. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

filespec	A string constant or global string variable describing the filename and path of the bitmap to display. Local variable strings are not allowed. If a path is not specified, the current Aspect Path will be assumed.

USERWIN | BACKGROUND	Specify USERWIN to "fix" the top left corner of the bitmap in position relative to the upper left corner of the User window. If BACKGROUND is specified, the upper left corner of the bitmap stays over the same spot on a background graphic.
Example

proc main

   ; Display a user window and a bitmap. You must have a

   ; bitmap named "sample.bmp" in your script directory.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

      bitmap 1 500 500 "Bitmap" "sample.bmp" BACKGROUND

   uwinpaint      ; Paint the new user window.

   pause 5        ; Show off the user window.

   uwinremove     ; Destroy the user window.

endproc

Comments

A User window must exist before a bitmap can be used. When the left mouse button is clicked on the bitmap, its label will invert. If no label is specified, the entire bitmap will invert.

See also

icon, iconbutton, pushbutton, dllobject, hotspot, bitmapbkg, metafile, uwincreate, objpaint, objhide, objremove, objshow, objmove, objcoord and objpointid; $OBJECT; User Window Commands.


bitmapbkg

bitmapbkg CENTER | LEFT | RIGHT | TILED CENTER | TOP | BOTTOM
MEMORY | DISK filespec

Places a bitmap background in the User window.

CENTER | LEFT | RIGHT | TILED	The horizontal position of the bitmap background with respect to the User window. If the bitmap is larger than the User window, it will be clipped along the bottom and right edges as necessary.
TILED repeats the bitmap, beginning at the upper left corner of the User window, until the User window is filled with multiple copies of the bitmap. Some of the tiled images may be clipped, depending upon the size of the bitmap.

CENTER | TOP |  BOTTOM	The vertical position of the bitmap background with respect to the User window.
MEMORY | DISK	Determines if the bitmap will be loaded into memory for re-display or reloaded from disk. MEMORY is faster, but DISK can be used to save memory space.
filespec	A string constant or global string variable describing the filename and path of the bitmap to display. If a path is not specified, the current Aspect Path is used by default.

Example

proc main

   ; Display a user window with a bitmap background. You

   ; must have a bitmap named "cars.bmp" in your script directory.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

      bitmapbkg TILED TOP MEMORY "cars.bmp"

   uwinpaint      ; Paint the new user window.

   pause 5        ; Show off the background.

   uwinremove     ; Destroy the user window.

endproc

Comments

The uwinpaint command is used to update the display of the User window.

See also

metafilebkg, bitmap, uwincreate, uwinremove and uwinpaint; User Window Commands.


break

break

Sends a break signal to a remote computer system.

Example

proc main

   if waitfor "Send BREAK"    ; Some hosts expect a break to start

      break                   ; Send a break when asked by host.

      transmit "User ID^M"    ; Transmit user ID to host system.

      transmit "Password^M"   ; Transmit password to host system.

   endif

endproc

Comments

The length of the break can be specified in Setup, Data, Data Options, Advanced or with the set port breaklen command.

See also

set port breaklen; COM-Related Commands.


breakpoint

breakpoint [string | {formatstr arglist}]

Interrupts execution of a script file and displays the Procomm Plus Debug window.

formatstr	A string containing text and/or format specifiers.

arglist	Up to 12 arguments to be processed with the formatstr.

Example

proc main

   integer Var1, Var2      ; Declare some integer variables.

   string Var3, Var4       ; Declare some string variables.

   Var1 = 0, Var2 = 42     ; Initialize integer variables.

   Var3 = "String1"        ; Initialize string variables.

   Var4 = "Testing String 2"

   ; Break program and call debug window. From debug window,

   ; you can display values of declared variables.

   breakpoint

endproc

Comment

The script must be compiled with the debug option ON for breakpoint to operate. Otherwise, the breakpoint command is ignored. The debug option is set by enabling the Compile for Debug check box in the ASPECT Compiler Options dialog.

See also

compile; Script Control Commands.


call

call name [WITH arglist] [INTO variable]

(or) call name [WITH arglist]

Causes script execution to branch to a specified procedure or function and allows a return to the command following the call.

Function format

call name [WITH arglist] [INTO variable]

name	The user-defined name of the procedure or function. Name must follow the standard ASPECT naming conventions.

WITH arglist	An optional list of up to 12 arguments to be passed to the procedure or function. Note that the items in arglist must match the order and number of parameters in the declaration of the called process.

INTO variable	Allowed for functions only. Variable will contain the function’s return value. The variable must be of the same data type as specified for the return value in the function declaration.

Procedure format

call name [WITH arglist]

name	The user-defined name of the procedure or function. Name must follow the standard ASPECT naming conventions.

WITH arglist	An optional list of up to 12 arguments to be passed to the procedure or function. Note that the items in arglist must match the order and number of parameters in the declaration of the called process.

INTO variable	Allowed for functions only. Variable will contain the function’s return value. The variable must be of the same data type as specified for the return value in the function declaration.

Example

proc main

   float Tax, Amount             ; Float variables to contain dollar

   float Total                   ; amount, tax, and total.

   ; Call procedure to get tax and function to figure total.

   Amount = 5.00                 ; Set the amount.

   call SalesTax with &Tax, Amount

   call GetTotal with Tax, Amount into Total

   usermsg "Total = %f" Total    ; Display total.

endproc

proc SalesTax

param float Tax, Amount          ; Passed float Tax and Amount.

   Tax = Amount * .0673          ; Calculate sales tax.

endproc

func GetTotal : float

param float Tax, Amount          ; Declare passed float variables.

   float Total                   ; Declare float to contain total.

   Total = Tax + Amount          ; Figure the total.

   return Total                  ; Return total to calling procedure.

endfunc

Comments

An argument to a function or procedure can be a constant or a variable. Variables are normally passed by value. This means that only the variable’s value is given to the called procedure or function, and that any changes the called process makes to the value do not affect the actual variable.

Variables can also be passed by reference. This means that a reference (or address) to a the variable is given to the called procedure or function, and that any changes made to the corresponding argument by the called process will be recorded in the referenced variable after control returns to the calling procedure or function.

The "&" character, preceding a variable argument in a call statement, indicates that the argument is being passed by reference.

Both functions and procedures can also be called in the shortened format:

name ([arglist])

value = myfunc ([arglist])

Functions called with the shortened format can also be used in general expressions.

The shortened form of function and procedure calls is highly recommended. It is shorter, just as readable, and less verbose. Also, future versions of ASPECT may require it.

See also

return, proc, endproc, func, longjmp and goto; ASPECT Primary Commands.


capture

capture OFF | ON

Controls session capture  during script file execution. The Capture file is a continuous record of all characters received and transmitted.

Example

proc main

   string Name = "file.cap"   ; Name of capture file to open.

   set capture file Name      ; Set name of capture file.

   capture on                 ; Open up the capture file.

   while $CARRIER             ; Loop while connected to remote.

      yield                   ; Yield processing time

   endwhile

   capture off                ; Close the capture file.

endproc

Comments

Capture file recording options determine how data is written to the capture file. To avoid capturing unwanted data, use the clear command first. Note that a set aspect display off command in a script will disable the Capture file.

See also

clear and snapshot; set capture command; General Procomm Plus Commands.


capturestr

capturestr string | {formatstr arglist}

Writes a specified string to the open Capture file. capturestr is often used to insert comments or "landmarks" within a Capture file to record certain events.

string	A string of up to 256 characters.

formatstr	A string of up to 256 characters. The string can contain text and/or format specifiers. For more information, see Formatting Text and Data.

arglist	Up to 12 arguments may be specified for the formatstr to process. These arguments must appear in the order they were specified within the formatstr.

Example

proc main

   string CapName = "file.cap" ;  Name of capture file to open.

   set capture file CapName    ; Set name of capture file.

   capture on                  ; Open up the capture file.

   when TARGET 0 "" call InsertString

   while $CARRIER              ; Loop while connected to remote.

      yield                    ; Yield script processor time

   endwhile

   capture off                 ; Close the capture file.

endproc

proc InsertString

   capturestr "[END OF TEXT]"

endproc

Comments

A Capture file must be opened by the user, or by a script with the capture command for capturestr to work properly.

See also

capture; set capture command; General Procomm Plus Commands.


case

case integer | long | string

Declares a string, integer, or long value to be tested against the switch statement’s target value.

Example

See the example for switch.

Comments

A successful match causes processing to continue with each command on subsequent lines until an endcase or exitswitch command is encountered. Successive case commands appearing before the endcase are ignored. A failed match results in the processing of any subsequent case or default command.

Several case commands can occur within a case/endcase block. These are ignored by any previous case match. Only the commands other than case or default are processed between the matched case and endcase command.

If a case target is matched, the statements following it are executed until an endcase or exitswitch is encountered. If another case is encountered, it’s skipped. Execution then falls through to the next commands following the matched case target. If a match is made with more than one case command, only the statements following the first matched case command will be executed.

default can occur anywhere within the switch statement. case statements occurring between default and its terminating endcase or exitswitch will be ignored.

For more information on case, see the switch command.

See also

switch, default, exitswitch and endcase; ASPECT Primary Commands.


ceil

ceil float numvar

Computes the smallest integral value, with no fractional amount, greater than or equal to a floating point number.

float	A float variable or constant.

numvar	A numeric variable which receives the command result.

Example

proc main

   float Cost = 23.75         ; Cost of a product.

   integer CostRoundedUp      ; Cost of product rounded up.

   ceil Cost CostRoundedUp    ; Round cost up to nearest int.

   usermsg "The cost is about %d..." CostRoundedUp

endproc

See also

floor; Numeric, String Conversion Commands.


chain

chain filespec [SHARED]

Executes another Windows ASPECT script.

filespec	The name of the ASPECT file to chain.

SHARED	Causes the chained script to inherit the parent script’s current ASPECT environment settings, rather than the default settings.

Example

proc main

   if findfirst "*.wax" ; Find a script file to run.

      chain $FILENAME   ; Run the script file found.

      usermsg "This message doesn't get processed!"

   else

      errormsg "No scripts found!"

   endif

endproc

Comments

ASPECT will not return control to the original script, so all processing should be completed before a chain is encountered.

The filespec doesn’t require a path. If the path is not provided, the current Aspect Path is assumed. To change the current Aspect Path, see the set aspect path pathname command.

If an extension of .wax is specified but doesn’t exist, ASPECT will search for a source file with a .was extension and compile it automatically. If an extension of .was is specified, the source is always automatically compiled before execution. If the extension is omitted and the source file is newer than an existing compiled script, the source will automatically be recompiled.

When a script chains to another script, existing ASPECT dialog boxes are destroyed, as are any DDE client conversations currently in effect. However, the chained script inherits the current predefined and system variable values, as well as the state of all set commands, the current User window and its objects, and any menus and menu selections created by ASPECT.

The $CHAINEDFILE system variable will return the name of the script which issued the chain command. If the current script was not chained, it will return null.

The $SCRIPTMODE system variable can be used to determine whether a script process was spawned or chained. $SCRIPTMODE will return 2 if the current task was chained from a parent script. chained scripts can use data already stored in the pre-defined variable set, whether SHARED is specified or not.

For more information about chaining and the Aspect environment, see Script Spawning and Chaining. Also see The ASPECT Script Environment.

See also

call and execute; $SCRIPTMODE, $SCRIPTENV, $ASPECTPATH, and $CHAINEDFILE; Script Control Commands.


chdir

chdir pathname [ASPECTPATH]

Changes the User Path to the specified drive and/or directory.

pathname	Identifies the DOS drive (for example, C:), pathname and directory. The drive identifier is only required if you change the current drive.

[ASPECTPATH]	An optional parameter that sets the Aspect Path to the new User Path.

Example

proc main

   string NewDir              ; New directory containing file.

   string Fname = "hide.me"   ; File to look for.

   NewDir = "c:\hidden"       ; Directory to search.

   chdir NewDir               ; Change to the new directory.

   if isfile Fname            ; Check for the file.

      usermsg "Found `"%s`" in `"%s`"!" Fname NewDir

   else

      errormsg "Couldn't find file `"%s`"." Fname

   endif

endproc

Comments

The User Path is the default path used by many ASPECT commands. If a path isn’t specified, the current User Path is used as the originating directory. For more information, see The ASPECT Script Environment.

See also

mkdir, rmdir, getdir and taskpath; set aspect path; $WINPATH, $USERPATH and $ASPECTPATH; DOS- or Disk-Related Commands.


checkbox

checkbox id left top width height label intvar

Adds a "checkmark" selection control to a script dialog box. The control may be either checked or unchecked.

id	A unique integer constant value assigned to the checkbox. The dlgevent command will assign this value to its target variable when the checkbox is accessed by the user. The value can also be used with dlgupdate to refresh the display of the checkbox.

left top	These integer constants determine the position of the top left corner of the checkbox control in Dialog Box Units, or DBUs. For more information on DBUs, see Dialog Box Units.

width height	Integer constants specifying the width and height of the checkbox in DBUs.

label	A string variable or constant, displayed on the right side of the checkbox. To specify a keyboard accelerator for the checkbox, simply include an ampersand (&) in front of the desired character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

intvar	Contains the value 0 if the box is unchecked and 1 if it is checked. The default checkbox state can be assigned by setting this value to 0 or 1 before the dialog box is displayed.

Example

proc main

integer Lamp 	; Used for lamp checkbox.

integer Tent 	; Used for tent checkbox.

integer Fishing 	; Used for fishing checkbox.

integer Event 	; Dialog event.

; Display a dialog and allow a selection of items from check list.

dialogbox 0 95 113 100 70 11 "Checkbox Example"

checkbox 1 5 5 90 12 "Flashlight and batteries" Lamp

checkbox 2 5 20 90 12 "Tent, stakes, and hammer" Tent

checkbox 3 5 35 90 12 "Fishing pole and tackle" Fishing

pushbutton 4 30 49 40 14 "&OK" ok default

enddialog

while 1

dlgevent 0 Event 	; Read dialog event.

switch Event 	; Evaluate the event.

case 0 	; No event occurred.

endcase

case 1 	; Checkboxes selected.

case 2

case 3

endcase

default 	; Exit case occurred.

exitwhile 	; Exit the while loop.

endcase

endswitch

endwhile

dlgdestroy 0 CANCEL 	; Destroy the dialog box.

if (! Lamp) || (! Tent) || (! Fishing)

usermsg "You forgot some of your camping stuff!"

endif

endproc

Comments

checkbox can only occur within a dialogbox group. When a checkbox is selected, the dlgevent command will update its target variable with the id specified for the checkbox.

See also

dlgevent, dlgupdate and dialogbox; Dialog Box Commands.


clear

clear

Clears the terminal display and the status line.

Example

proc main

   while $CARRIER ; Loop while we're online.

      yield       ; Release script processor time

   endwhile

   pause 2        ; Pause to avoid hangup "noise".

   clear          ; Clear screen after hangup.

endproc

Comments

clear has no effect while the Procomm Plus Terminal window is in Scrollback mode. Script execution merely continues to the next command. If clear is executed while text is being marked in the Terminal window, however, script execution is suspended. After the marking operation is completed or cancelled, the clear command is executed and the script resumes normally.

See Also

Terminal Commands.


clearxoff

clearxoff

Clears an XOFF character, usually Ctrl-S, sent by a remote computer. XON/XOFF flow control, commonly called "software" flow control, is often used to pace the transmission of ASCII data. If the flow of data is accidentally paused by line noise or an embedded XOFF character, this command will resume the transfer.

Example

proc main

   transmit "TYPE TEST.TXT^M" ; Send command to display file.

   waitfor "Sending"          ; Wait for confirmation from host.

   getfile ASCII "test.txt"   ; Initiate an ASCII download.

   while $XFERSTATUS == 1     ; Loop while the file transfer is

      if $FLOWSTATE           ; in progress and check state of

         clearxoff            ; flow control. Clear XOFF if

      endif                   ; flow control active.

   endwhile

         ; This segment could be used if you wanted software flow

         ; control enabled, but inactive during your file transfer.

endproc

Comments

XON/XOFF flow control can often cause a communications session to "hang", since the transmitting computer may wait indefinitely to receive an XON character, Ctrl-Q. clearxoff has no effect if XON/XOFF flow control has been disabled.

See also

set port softflow and $TXCOUNT, $RXCOUNT, $FLOWSTATE and $XOFFRECV; COM-Related Commands.


cliptofile

cliptofile {BITMAP | METAFILE filespec} | {TEXT filespec [APPEND]}

Copies data from the Windows Clipboard to a file.

BITMAP	Write the information as a bitmap.

METAFILE	Write the information as a metafile.  Using a file extension of .emf causes the file to be saved in an enhanced metafile format; otherwise, the file is saved using the "placeable" standard metafile format.

filespec	The target filename; a path is optional. If a path is not specified, the User Path is used by default.

TEXT	Write the information as a text file.

filespec	The target filename; a path is optional. If a path is not specified, the User Path is used by default.

APPEND	Appends the contents to the end of an existing file. If the file does not exist, it will be created.

Example

proc main

string Source = "test.was"    ; Source file to copy.

string DestFile = "new.was"   ; Destination file.

   filetoclip TEXT Source     ; Copy source file to the clipboard.

   cliptofile TEXT DestFile   ; Copy clipboard to destination file.

endproc

Comments

The clipboard must contain valid data of the indicated type for a successful copy operation. The data is not erased from the Windows Clipboard by cliptofile.

See also

cliptostr, filetoclip and pastetext; Clipboard Commands.


cliptostr

cliptostr strvar

Copies text from the Windows Clipboard to a string.

strvar	The target string.

Example

proc main

   string SampleText               ; Text from the clipboard.

   strtoclip ""                    ; Clear the clipboard.

   while 1                         ; Loop forever.

      if $LMOUSESTATE              ; Check on the mouse button.

         cliptostr SampleText

         if not nullstr SampleText ; Make sure text isn't empty.

            transmit SampleText    ; Send text to the port.

            strtoclip ""           ; Clear the clipboard.

         endif

      endif

   endwhile

endproc

Comments

Up to 256 characters can be copied from the Windows Clipboard to the string. The Clipboard must contain textual data of some kind.

See also

cliptofile, filetoclip and strtoclip; Clipboard Commands.


combobox

combobox id left top width height SIMPLE | DROPDOWN | DROPDOWNLIST
itemlist strvar [strlength] [SORT]

Adds a combination edit/selection or "drop-down" selection control to an ASPECT dialog box. Allows the selection of a single item from a list of items.

id	A unique integer constant assigned to the combo box.

left top	Integer constants which determine the position of the top left corner of the combobox control in dialog box units, or DBUs. For more information on DBUs, see Dialog Box Units.

width height	Integer constants which specify the width and height of the combo box in DBUs.

SIMPLE	Causes the list box to be displayed at all times. The current selection in the list box is displayed in the edit control.

DROPDOWN	Causes the list box to be displayed only if the user selects the down arrow icon to the right of the edit control. The current selection is displayed in the edit control.

DROPDOWNLIST	Similar to the DROPDOWN type, but the edit control is replaced by a static text item that displays the current selection in the list box.

itemlist	A string variable or constant containing a list of items to display within the combo box. Each item is separated by a comma.

strvar	Assigned the text of the item selected by the user. This variable can be pre-assigned a value from the list to be displayed as the default selection.

strlength	An optional integer variable or constant indicating the number of characters which can be input by the user into the edit control. The strlength argument is not valid with the keyword DROPDOWNLIST, since that combo box type does not provide an edit field.

SORT	 An optional parameter that sorts the contents of the combo box alphabetically.

Example

proc main

   string FullList           ; List of items to choose from.

   string Items           ; Item selected from list.

   integer Event         ; Dialog event.

   ; Display a dialog box with a list of stuff to choose from.

   FullList = "Bagels,Soup,Bread,Chili,Salad"

   Items = "Bagels"       ; Set default item.

   dialogbox 0 0 0 100 50 11 "Combo Box Example"

      combobox 1 5 5 90 40 DROPDOWNLIST FullList Items SORT

   enddialog

   while 1

      dlgevent 0 Event  ; Get dialog event.

      switch Event      ; Evaluate the event.

         case 0         ; No event occurred.

         endcase

         case 1         ; Check box item selected.

            usermsg "`"%s`" selected!" Items

         endcase

         default        ; Exit method selected.

            exitwhile   ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL  ; Destroy the dialog box.

endproc

Comments

The dlgevent command assigns the id value to its target variable when a selection is made in the combo box by the user. The id value can also be used with dlgupdate to refresh the display of the combo box, or to enable or disable the combo box.

If the combo box contains an edit field, and the user types information into the field, a dialog event will be generated when the combo box loses the input focus.

See also

fcombobox, flistbox, dialogbox, listbox, dlgevent and dlgupdate; Dialog Box Commands.


comgetc

comgetc intvar [integer]

Assigns the next character value in the receive data buffer to an integer variable.

integer	An optional value which specifies the total number of seconds comgetc will wait for an available character.

Example

proc main

   integer Chr          ; Character read from COM port.

   string Hex           ; Hexadecimal output string.

   set aspect RXDATA ON ; Tell Aspect to handle port data.

   while 1              ; Loop forever.

      while $RXDATA     ; Check for characters at port.

         comgetc Chr    ; Get character from port.

         strfmt Hex "%02X" Chr   ; Convert character to Hex.

         termwrites Hex ; Display hex on terminal screen.

         if $COL == 70  ; Check to see if cursor's at

            termwrites "^M^J" ; end of line and write CR/LF

         endif          ; to put cursor on next line.

      endwhile

   endwhile

endproc

Comments

If the receive buffer is empty, or if it remains empty during the specified timeout period, comgetc assigns a value of -1. If a timeout value is specified, the Ctrl-Break sequence can be used to terminate the command before the timeout period has completed.

A character retrieved by the comgetc command will not be displayed in the Terminal window, regardless of the set aspect rxdata state. Similarly, comgetc will not be interrupted by a when $RXDATA condition, since comgetc effectively "steals" data from the received data buffer.

comgetc will fail if the script does not have control of the communications port.

See also

comread and computc; set aspect rxdata and set aspect display; COM-Related Commands.


 commandmode

commandmode OFF | ON

Switches the modem on the current connection to command mode.

Comments

commandmode is equivalent to the Data | Modem Command Mode menu item found in the Terminal window. As long as command mode is active, all answer options are disabled and other applications cannot access the current connection.

commmandmode fails if the current connections is a non-TAPI connection or if the connection could not be opened.

See also

$CONNECTOPEN


compile

compile filespec [string]

Executes the ASPECT Compiler upon the target source file.

filespec	The name of the source file to compile. This file must have an extension of .was on disk, but the extension is not required in the filespec argument.

The Aspect Path is used by default if no path is specified.

string	An optional string containing arguments for the ASPECT Compiler. These arguments are in addition to those currently specified in the pw4.ini file. However, a "/N" argument tells the compiler to ignore the pw4.ini options.

Example

proc main

   string Scriptf                    ; Script file to compile.

   if sdlginput "Compile" "Script:" Scriptf ; Get a script name from user

      if isfile Scriptf              ; See that script exists.

         compile Scriptf "/Z /Q"     ; Compile script file with debug

                                     ; and no screen output.

      else

         errormsg "Script does not exist!"

      endif

   endif

endproc

Comments

Script execution is suspended until the compilation is finished. Ctrl-Break can be used to terminate the compile command, allowing script execution to continue.

For more information about command-line options, see The ASPECT Compiler.

See also

chain, execute and run; Script Control Commands.


computc

computc character

Sends the specified character value to the communications port.

Example

proc main

   if waitfor "Send BREAK"       ; Some hosts expect a signal to start.

      computc 0x03               ; Send CTRL-C to remote system.

      transmit "99999,9999^M"    ; Send user ID to remote system.

      transmit "Password^M"      ; Send password to remote system.

   endif

endproc

Comments

Use termkey to send the current emulation’s Keyboard Mapping code for special keys like the function and cursor control keys.

computc will fail if the script does not have control of the communications port.

Data will be transmitted at a rate determined by the current baudrate and transmit pacing values.  For fastest possible throughput at the current baudrate, make sure that transmit pacing is set to 0.

See also

comgetc, comwrite, transmit and termkey; COM-Related Commands.


comread

comread numvar | {strvar strlength} [integer [intvar]]

Retrieves data from the receive data buffer and stores it in the target variable. The amount of data read depends on the type of data variable specified. For integers it is 4 bytes, for longs 4, for floats 8 and for strings is user-specified.

numvar	The target data variable.

strvar  strlength	A string target variable. strlength is an integer value which specifies the number of characters to be read into strvar. The maximum value is 256 characters.
integer	An optional value which specifies the total number of seconds comread will wait for data. comread will timeout if the requested data has not been received in the specified time. If no timeout value is specified, and the amount of available data is less than the requested amount, comread will fail immediately.

intvar	If specified, this variable will contain the actual count of data read.

Example

proc main

   integer DataVal                 ; Data from the COM port.

   ; The following script segment expects to see a stream of

   ; integers coming into the COM port.

   set aspect RXDATA ON            ; Tell Aspect to handle port data.

   while 1                         ; Loop forever.

      while $RXDATA                ; See if there is data awaiting.

         comread DataVal           ; Get an integer from COM port.

         termmsg "[%d]" DataVal    ; Put the integer on the screen.

      endwhile

   endwhile

endproc

Comments

comread is most commonly used to obtain "raw" data from the port. Because it can store retrieved values as any ASPECT data type, it is the most flexible read port command.

Data retrieved by the comread command will not be displayed in the Terminal Window, regardless of the set aspect rxdata state. Similarly, comread will not be interrupted by a when $RXDATA condition, since comread effectively "steals" data from the received data buffer.

If the amount of data read is less than requested, comread has failed. comread will also fail if the script does not have control of the communications port. Ctrl-Break can be used to terminate a comread command.

See also

comgetc, computc, comwrite, rget, termkey and transmit; COM-Related Commands.


comwrite

comwrite number | {string strlength}

Sends the specified string value to the communications port.

number	An integer, float, or long value to be written to the port.

string	A string value to be written to the port.

strlength	The number of characters to be written from the string. Maximum length of the string is 256 characters.

Example

proc main

   integer _CR = 0x0D         ; Carriage return character.

   integer _LF = 0x0A         ; Linefeed character.

   integer nData              ; Data to be sent out the port.

   nData = _CR                ; Add CR to data to be sent.

   nData += (_LF << 8)        ; Add LF to data to be sent.

   ; The above math phrase shifts the linefeed character from

   ; the low byte of the integer to the high and adds it

   ; to the carriage return (which is in low byte). The

   ; result is the integer 0x0A0D.

   comwrite nData             ; Write CR/LF to COM port.

endproc

Comments

comwrite is often used to send "raw" binary data to a remote system. The amount of data written to the port depends on the data type specified. For more information, see the comread command.

Data will be transmitted at a rate determined by the current baudrate and transmit pacing values.  For fastest possible throughput at the current baudrate, make sure that transmit pacing is set to 0.

comwrite will fail if the script does not have control of the communications port.

See also

comgetc, computc, comread, rget, termkey and transmit; COM-Related Commands.


connect

connect dialclass [GROUP] name [name...][CONNECTALL]

Calls one or more entries in your Connection Directory.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Dial the group(s) specified.

name	A string identifying the entry or group name to dial.

name...	Optional additional entry or group names to dial. Up to 12 names in all can be specified.

CONNECTALL	Initiates a continuous attempt to connect to all selected Connection Directory entries. When a connection is made and then terminated, the dialing process continues to the next entry in the list and resumes dialing. If CONNECTALL is not used, any successful connection will terminate the dialing queue.

Comments

The connect command is a synonym for dial. See dial for more information.

See also

dialadd, dialcancel, dialclass, dialcount, dialcreate, dialdelete, dialfind, dialinsert, dialload, dialname, dialnumber, dialsave and dialstats; set aspect dialingbox, the set dial and set dialentry command families; $DIALCONNECT, $DIALENTRY, $DIALSELECT, $DIALQUEUE, $SCRIPTMODE and $DIALING; Dialing Commands.


connectmanual

connectmanual dialclass string

Connects to the specified telephone number.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

string	A valid telephone number.

Comments

connectmanual is a synonym for dialnumber. Please see dialnumber for more information and an example script.

connectmanual accepts only a single telephone number. For multiple Connection Directory entry number, use the dial or connect command.

connectmanual will fail if a dialing operation or a file transfer is already in effect.

See also

dial, dialcancel and dialload; $DIALING ; the set dial command family; Dialing Commands.


copyfile

copyfile filespec filespec

Copies a file to another file or path.

filespec	The source filename. A fully-qualified path is recommended. If no path is specified, the User Path is used as the default.

filespec	The destination. Either a fully-qualified path, with or without the filename, or a new filename with a path may be specified. If a path is omitted, the User Path is used as the default.

Example

proc main

   string SourceF = "goldmine.was"    ; Source file to copy.

   string DestF = "agedgold.bkp"      ; Destination file name.

   if not copyfile SourceF DestF      ; Backup script files.

      errormsg "Couldn't copy file `"%s`"!" SourceF

   endif

endproc

Comments

copyfile works similar to the DOS COPY command. However, copyfile does not support wildcards. Script execution is suspended until the file is copied.

See also

chdir, delfile, isfile and rename; $USERPATH; DOS- or Disk-Related Commands.


crc16

crc16 intvar string [strlength]

Generates a Cyclic Redundancy Check (CRC) integer value for a specified string. CRC values are often used to determine whether data has been changed by line noise.

intvar	Before the crc16 command is executed, this integer holds the starting value of the CRC polynomial. After the crc16 has executed, it holds the current CRC value.

string	The string to evaluate.

strlength	The string length. If omitted, a null-terminated string is assumed.

Example

proc main

   integer CRCVal = 0        ; CRC for string below.

   string Message            ; String to get CRC for.

   Message = "CRC's are used for security or file integrity tests."

   crc16 CRCVal Message      ; Get CRC for the message.

   usermsg "CRC for the string is 0x%04X." CRCVal

endproc

Comments

Prior to the first execution of this command, the script should set intvar to the desired initial CRC value. Typically, this initial CRC value is 0 or -1, and it must be used when the data is verified at some other time. In other words, two CRC values for the same data cannot be compared unless each CRC value was calculated using the same initial value.

crc16 allows the user to calculate CRC values on a single string or multiple strings. For more than one string, all subsequent executions of crc16 should use the value last returned into intvar by the previous crc16 command. If the optional length isn’t included, the length will be calculated at run-time, assuming a null-terminated string.

crc16 uses CCITT polynomial 0x1021.

See also

comread and comwrite; General Procomm Plus Commands.


ddeadvise

ddeadvise long string gdatavar [integer]

Allows Procomm Plus to request both the initial value of a variable and any subsequent changes to that variable from a Windows Dynamic Data Exchange (DDE) server. Each time the value of the specified variable changes in the server application, Procomm Plus is informed of the change.

long	Specifies the DDE channel number returned by the ddeinit command.

string	The name of the server variable to be monitored.

gdatavar	The name of the Procomm Plus global data variable that will be changed each time the server sends a new value for the specified variable.

integer	An optional identifier, indicating when a specific variable among multiple ddeadvise commands has been updated. The value is used in conjunction with the $DDEADVISE system variable to indicate which ddeadvise command has been updated. The value must be a positive, non-zero value. If not specified, events associated with the server variable will return -1 in $DDEADVISE.

Example

string szText                               ; Text read from DDE link to Excel.

proc main

   long LinkVar, SystemVar                  ; Variables containing DDE Id's.

   ; Set up DDE links to Excel's system and a spreadsheet. Excel

   ; must be running in order for this script to work properly.

   if ddeinit SystemVar "excel" "system"

      ddeexecute SystemVar "[FULL(TRUE)]"   ; Maximize the spreadsheet.

      if ddeinit LinkVar "excel" "sheet1"   ; Set up link to spreadsheet.

         ddepoke LinkVar "R1C1" "Procomm Plus DDE example!"

         dderequest LinkVar "R1C1" szText   ; Read info from DDEPOKE.

         usermsg szText                     ; Display text on status line.

         ddeadvise LinkVar "R1C1" szText    ; Make hot link to row 1,

                                            ; col 1 of the spreadsheet.

         while 1                            ; Loop forever.

            if $DDEADVISE

               ; See if row 1 and col 1 of spreadsheet

               ; changed, if so read it and evaluate.

               if stricmp szText "exit`r`n"

                  exitwhile                 ; Exit the while loop.

               else

                     usermsg szText         ; Display cell contents.

               endif

            endif

         endwhile

         ddeunadvise LinkVar "R1C1"         ; Break hot link to spreadsheet.

         ddeterminate LinkVar               ; Break DDE link to spreadsheet.

         ddeterminate SystemVar             ; Break DDE link to Excel.

      else

         errormsg "Couldn't establish DDE link to spreadsheet!"

      endif

   else

      errormsg "Couldn't establish DDE link to Excel!"

   endif

endproc

Comments

A ddeadvise operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it failed.

The DDE manager only maintains one advise loop per item per conversation.  More than one ddeadvise can be established on the same item, and each can be uniquely identified by using the optional ID.  A ddeunadvise, however, will terminate all active advisements on that item.

See also

ddeinit, dderequest, ddepoke, ddeunadvise and when $ddeadvise; $DDEADVISE; Dynamic Data Exchange Commands.


ddeexecute

ddeexecute long string

Executes a command in another Windows program acting as a Dynamic Data Exchange (DDE) server.

long	Specifies the DDE channel number returned by the ddeinit command.

string	The server application DDE command. Server commands usually must be provided in a specific format; check the server application’s documentation.

Example

See the example for the ddeadvise command.

Comments

A ddeexecute operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it was not. A discussion of DDE client operations appears in Advanced Topics.

See also

ddeinit; Dynamic Data Exchange Commands.


ddeinit

ddeinit longvar string string [integer]

Establishes a Dynamic Data Exchange (DDE) data channel between Procomm Plus and a Windows DDE server application. This channel can be used to exchange data between the two programs, and the client can execute server commands.

longvar	If ddeinit is successful, longvar is a DDE channel number. This channel number can be used in other DDE commands for data exchange and control.

string	The name recognized by the server application for DDE exchanges. This name is usually provided in the server application’s documentation. Typically it is the name of the application itself.

string	The name of the document, file or topic recognized by the server application.

integer	An optional value that uniquely identifies the DDE server application. This value can be used to establish a DDE conversation with a specific instance of an appliction when more than one instance is running. ASPECT assumes that for a typical application, this value is appended to the DDE server name as the ASCII representation of an unsigned integer value (as if a DDE server name string were created with the format "MYAPP%u"). Consult the application documentation to determine what their DDE server naming conventions are. You may have to format your own DDE server name string, and avoid using the optional integer value.

To indentify a unique instance of Procomm Plus, the integer value used should be the main window ID of that instance. This value will be used to produce a DDE server name that uniquely identifies that specific instance of Procomm Plus.

Example

See the example for ddeadvise.

Comments

A ddeinit operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it was not. A discussion of DDE client operations appears in Advanced Topics.

See also

ddeadvise, ddeterminate, ddeexecute, dderequest and ddepoke; Dynamic Data Exchange Commands.


ddepoke

ddepoke long string data

Assigns data from ASPECT to a Windows Dynamic Data Exchange (DDE) server application variable.

long	Specifies the DDE channel number returned by the ddeinit command.

string	The name of the variable or item which will receive the data in the server application.

data	The data to be sent to the server application. It can be any data type supported by ASPECT.

Example

See the example for ddeadvise.

Comments

A ddepoke operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it failed.

See also

dderequest, ddeinit and ddeadvise; Dynamic Data Exchange Commands.


dderequest

dderequest long string datavar

Receives the current value of a variable from a Dynamic Data Exchange (DDE) server application.

long	Specifies the DDE channel number returned by the ddeinit command.

string	The name of the server’s variable or item reference.

datavar	The name of the ASPECT variable which will receive the data.

Example

See the example for ddeadvise.

Comments

A dderequest operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it was not.

See also

ddepoke, ddeinit and ddeadvise; Dynamic Data Exchange Commands.


ddeterminate

ddeterminate long

Terminates an existing Dynamic Data Exchange (DDE) data channel.

long	The DDE channel number returned from the ddeinit command to be terminated.

Example

See the example for ddeadvise.

See also

ddeinit; Dynamic Data Exchange Commands.


ddeunadvise

ddeunadvise long string

Terminates a current ddeadvise condition.

long	Specifies the DDE channel number returned by the ddeinit command.

string	The name of the server variable currently being monitored. This is the same value originally referenced in a previous ddeadvise command.

Example

See the example for ddeadvise.

Comments

A ddeunadvise operation can be tested with the if SUCCESS statement, returning true if the operation was successful and false if it failed.

See also

ddeadvise and ddeinit; Dynamic Data Exchange Commands.


decrypt

decrypt strvar length

Decodes an encrypted string.

strvar	The string to decode. This variable will be updated with the decoded data.

length	The length of the string to decrypt.

Example

proc main

   string TextStr             ; Text string to decrypt.

   integer NumChrs            ; Number of chars from RGET.

   while 1                    ; Loop forever.

      rget TextStr 255        ; Get encrypted str from port.

      strlen TextStr NumChrs  ; Get length of string.

      decrypt TextStr NumChrs ; Decrypt the text string.

      usermsg TextStr         ; Display the decrypted string.

   endwhile

endproc

Comments

The datakey value must be equal to the value used to encrypt the string to properly decrypt the string. It can be set with the set aspect datakey command.

See also

encrypt; set aspect datakey; General Procomm Plus Commands.


default

default

Provides for processing when no match is found among the case statements in a switch statement group.

Example

proc main

   integer Omega = 42         ; Integer to check in switch case.

   switch Omega               ; Find value of numeric variable

      case 0                  ; and display corresponding

         usermsg "Omega = 0"  ; message.

      endcase

      case 1

         usermsg "Omega = 1"

      endcase

      default                 ; Others false, so this executes.

         usermsg "Value not 0 or 1!"

      endcase

   endswitch

endproc

Comments

If a case target is matched, the statements following it are executed until an endcase or exitswitch is encountered. If another case is encountered, it’s skipped. Execution then falls through to the next commands following the matched case target. If a match is made with more than one case command, only the statements following the first matched case command will be executed.

The default command is optional, but there can be only one occurrence of it within a switch statement group. If a default isn’t used and none of the case commands were matched, no action takes place at all.

default can occur anywhere within the switch statement.  case statements occurring between default and its terminating endcase or exitswitch will be ignored.

For further information on default, see the switch command.

See also

switch, case, endcase and exitswitch; ASPECT Primary Commands.


delfile

delfile filespec

Deletes a specified file.

Example

proc main

   string Fname = "file.tmp"  ; Temporary file to delete.

   if not delfile Fname       ; Delete the temporary file.

      errormsg "Couldn't delete `"%s`"!" Fname

   else

      usermsg "`"%s`" deleted." Fname

   endif

endproc

Comments

The filespec may include a full directory path. If the path isn’t specified, the current User Path is assumed. Wildcards are not allowed.

See also

copyfile, rename and isfile; DOS- or Disk-Related Commands.


dial

dial dialclass [GROUP] name [name...] [CONNECTALL]

Calls one or more entries in your Connection Directory.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Dial the group(s) specified.

name	A string identifying the entry or group name to dial.

name...	Optional additional entry or group names to dial. Up to 12 names in all can be specified.

CONNECTALL	Initiates a continuous attempt to connect to all selected Connection Directory entries. When a connection is made and then terminated, the dialing process continues to the next entry in the list and resumes dialing. If CONNECTALL is not used, any successful connection will terminate the dialing queue.

Example

proc main

   dial DATA "Symantec"   ; Dial Symantec entry.

   while $DIALING          ; Loop while dialing.

   endwhile

   if $CARRIER             ; See if we're connected.

      transmit "Hello?"    ; Send a string to say hello.

      hangup               ; Hang up the phone line.

   else

      errormsg "Sorry, not connected."

   endif

endproc

Comments

dial launches a dialing sequence and immediately returns control to the script. To force the script to pause for a connection create a loop testing $DIALING for 0. When $DIALING is set to 0, $DIALCONNECT will indicate the entry responsible for the connection.

dial searches for groups or entry names, but not both at once. The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find either an entry or group name based on a partial name.

All entry names are placed in the dialing queue. If a group name is selected, then all entries in that group are placed in the dialing queue. The $DIALQUEUE system variable will return the number of entries remaining in the list to be dialed.

$DIALSELECT reflects the name of the entry currently being dialed, or the last-selected entry.

The $SCRIPTMODE system variable can be checked to determine if the script was executed from a Connection Directory entry. $DIALENTRY indicates the name of the entry that launched the script.

The dial command will fail if a dialing operation or a file transfer is already in effect.

See also

dialadd, dialcancel, dialclass, dialcount, dialcreate, dialdelete, dialfind, dialinsert, dialload, dialname, dialnumber, dialsave and dialstats; set aspect dialingbox, the set dial and set dialentry command families; $DIALCONNECT, $DIALENTRY, $DIALSELECT, $DIALQUEUE, $SCRIPTMODE and $DIALING; Dialing Commands.


dialadd

dialadd dialclass [GROUP] name

Adds a new entry or group name to the currently loaded Connection Directory.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Create a new group. If this keyword is not specified, a new entry will be created.

name	A string which identifies the name of the new entry or group.

Example

proc main

   dialadd DATA GROUP "BBS List"         ;Add group called 'BBS List'

   dialadd DATA "Garvinsoft BBS"         ;Add a Garvinsoft Entry

   set dialentry access DATA "Garvinsoft BBS";Specify which entry will

                                          ;be accessed

   set dialentry areacode "573"           ;Set the area code

   set dialentry phonenumber "555-1234"   ;Set the phone number

   dialinsert DATA "BBS List" "Garvinsoft BBS";Insert entry into 'BBS

   dialsave                               ;List'group and Save the

                                          ;Connection Directory

endproc

Comments

The dialclass keyword determines the initial dialing class in which the entry will appear. The entry will automatically appear within other classes when the appropriate connection information is entered.

When Connection Directory changes are complete, the dialsave command should be issued to save them.

The dialadd command will fail if the Connection Directory is displayed at its execution time. It will also fail if the provided entry or group name is a null string or if it contains more than 40 characters including the null terminator.

See also

dialcreate, dialdelete, dialinsert and dialsave; the set dialentry command family; Dialing Commands.


dialcancel

dialcancel [CURRENT]

Cancels a current dialing operation.

CURRENT	Cancels the current dialing attempt only, and removes that entry from the queue. If CURRENT is not specified, the entire dialing operation is canceled.

Example

proc main

   when USEREXIT call StopDial   ; Look for user exit.

   dial DATA "Symantec"         ; Dial Symantec entry.

   while $DIALING                ; Loop while dialing.

   endwhile

endproc

proc StopDial

   dialcancel                    ; Cancel the dialing.

endproc

Comments

Essentially, dialcancel has the same effect as the user pressing <Esc> or the Cancel button as the modem is dialing. dialcancel only affects a voice or data dialing attempt. Use the faxcancel command to cancel a fax dial.

See also

dial, dialnumber and faxcancel; set aspect dialingbox; Dialing Commands.


dialclass

dialclass name intvar

Returns a value indicating the entry class(es) for the specified entry.

name	The name of the entry to test. The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper or lower case. The dialfind command can be used to find either an entry or group name based on a partial name.

intvar	Will be set to a value indicating entry class(es) if dialclass was successful.

Example

proc main

   integer TypeFlag                 ; Type of entry.

   dialclass "Syamntec" TypeFlag   ; Get type for DS entry.

   if TypeFlag & 1                  ; See if entry supports Data.

      usermsg "Entry supports DATA."

   endif

   if TypeFlag & 8                  ; See if entry supports Telent

      usermsg "Entry supports FAX."

   endif

endproc

Comments

The following values can be tested:

1	data entry
2	fax entry
4	voice entry
8	Telnet entry
16	FTP entry
64	Mail entry
128	News entry
If an entry contains information for more than one type of entry, the resulting integer will be the sum of those entries. For example, if you have an entry with data, fax and voice information, dialclass will return a value of 7.

When executed with $DIALSELECT, $DIALCONNECT or $DIALENTRY, the returned intvar value will indicate a single class for the named entry, even though it may be a number of other classes as well.

See also

dialadd, dialdelete, dialfind and dialstats; the set dialentry command family; Dialing Commands.


dialcount

dialcount dialclass [GROUP [name]] intvar

Returns the number of entries, groups, or entries within a group for a particular dialing class.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Search a group for entries of the requested dialing class.

name	The name of a particular group to search. The group name must match exactly the information contained in the group name field, including upper- or lower-case. The dialfind command can be used to find a group name based on a partial name.

intvar	This variable will contain the number of entries, groups, or entries within a group that matched the dialing class specified.

Example

proc main

   integer NumEnts                     ; Used to count entries.

   integer Count                       ; Used for loop.

   string EntName                      ; Name of directory entry.

   dialcount DATA NumEnts              ; Get number of DATA entries.

   for Count = 0 upto (NumEnts - 1)    ; dialname zero-based.

      dialname DATA Count EntName      ; Get name of entry.

      dial DATA EntName                ; Dial the current entry.

      while $DIALING                   ; Pause while dialing.

      endwhile

      pause 4                          ; Pause to wait for carrier.

      while $CARRIER                   ; Pause while connected.

         yield                         ; Yield processing time

      endwhile

   endfor

endproc

Comments

If GROUP is not specified, the total number of entries will be returned. If GROUP is specified without a name argument, the total number of groups is returned. If a name argument is specified with GROUP, the total number of entries within that group is returned.

See also

dialfind, dialstats and dialclass; the set dialentry command family; Dialing Commands.


dialcreate

dialcreate filespec

Creates a new Connection Directory file.

Example

proc main

   string DirName                 ; Name of directory to create.

   if sdlginput "Create Directory" "Name:" DirName

      if not nullstr DirName      ; Make sure name isn't empty.

         dialcreate DirName       ; Create the Dialing Directory.

      endif

   endif

endproc

Comments

A Connection Directory file can be created with any filename. If a specific path is not supplied, dialcreate places the new file in the local task path.

The dialcreate command will fail if the Connection Directory is displayed when it executes.

See also

dialadd, dialdelete, dialfind, dialinsert, dialload and dialsave; Dialing Commands.


dialdelete

dialdelete dialclass {GROUP name} | {ENTRY name} | {groupname entryname}

Removes a Connection Directory entry, group, or an entry within a group.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Delete the specified group. The entries contained within the group are not deleted, but rather are made available outside of the deleted group if they are not a member of any other group.

name	The name of the group to delete.

ENTRY	Delete the specified entry.

name	The name of the entry to delete.

groupname entryname	Within the group specified, delete the specified entry. The entry will not be deleted, just removed from the group.
Example

proc main

   string OldEntry                         ; Name of entry to delete.

   if sdlginput "Delete Entry" "Name:" OldEntry

      if not nullstr OldEntry              ; Make sure entry isn’t empty.

         dialdelete DATA ENTRY OldEntry    ; Delete modem entry.

         dialdelete FAX ENTRY OldEntry     ; Delete fax entry.

         dialdelete VOICE ENTRY OldEntry   ; Delete voice entry.

      endif

   endif

endproc

Comments

When an entry name is deleted, it is only deleted from the indicated class. If it exists in any of the other classes, it is not deleted from them.

The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find either an entry or a group name based on a partial name.

When Connection Directory changes are complete, the dialsave command should be issued to save them.

The dialdelete command will fail if the Connection Directory is displayed, or if a dialing operation is already in effect when it executes.

See also

dialadd, dialcreate, dialinsert, dialfind and dialsave; the set dialentry command family; Dialing Commands.


dialfind

dialfind {dialclass [GROUP] name [EXACT]} | NEXT [strvar]

Finds the entry name and/or index associated with a specified name in the specified class.

dialclass	A keyword representing a Connection Directory entry class.

GROUP	Search for a group defined with the specified name.

EXACT	Causes dialfind to find an exact match rather than a case-insensitive substring match..

name	The full or partial text used to search the Connection Directory.

NEXT	Searches for a subsequent Connection Directory match.

strvar	An optional variable assigned the full name of the matching entry or group.

Example

proc main

   string SrchEntry                   ; Entry to search for.

   if sdlginput "Entry Search" "Name:" SrchEntry

      if not nullstr SrchEntry        ; Make sure entry isn't empty.

         if dialfind DATA SrchEntry SrchEntry

            usermsg "The entry is called `"%s`"." SrchEntry

         endif

      endif

   endif

endproc

Comments

A partial name can also result in a match. dialfind will find the first entry or group name whose leading characters match the characters in the partial name without regard for character case.

See also

The set dialentry command family; Dialing Commands.


dialinsert

dialinsert dialclass groupname entryname

Inserts a Connection Directory entry into an existing group.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

groupname	The name of the group to receive the new entry.

entryname	The name of the new entry.

Example

proc main

   dialadd DATA GROUP "BBS List"         ;Add group called 'BBS List'

   dialadd DATA "Garvinsoft BBS"         ;Add a Garvinsoft Entry

   set dialentry access DATA "Garvinsoft BBS";Specify which entry will

                                          ;be accessed

   set dialentry areacode "573"           ;Set the area code

   set dialentry phonenumber "555-1234"   ;Set the phone number

   dialinsert DATA "BBS List" "Garvinsoft BBS";Insert entry into 'BBS

   dialsave                               ;List'group and Save the

                                          ;Connection Directory

endproc

Comments

The group specified must exist before an entry can be inserted. To create a group, use the dialadd command.

The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find an entry or group name based on a partial name.

When Connection Directory changes are complete, the dialsave command should be issued to save them.

The dialinsert command will fail if the Connection Directory is displayed at its execution time.

See also

dialadd, dialdelete, dialfind and dialsave; the set dialentry command family; Dialing Commands.


dialload

dialload filespec

Loads a different Connection Directory.

Example

proc main

   string DirName                 ; Name of directory to open.

   if sdlginput "Open Directory" "Name:" DirName

      if not nullstr DirName      ; Make sure name isn't empty.

         dialload DirName         ; Load the specified directory.

      endif

   endif

endproc

Comments

If a full path is not specified, the local task path is used by default. The filespec can contain the name of any valid Connection Directory file. The .dir extension is not required, but if the filename has an extension other than .dir it must be specified.

The dialload command will fail if the Connection Directory is displayed at its execution time.

See also

dialcreate and dialsave; Dialing Commands.


dialname

dialname dialclass [GROUP [name]] index strvar

Enumerates entries, groups, or entries within a group.

dialclass	A keyword representing a Connection Directory entry class. Valid keywords are: DATA, MAIL, FAX, FTP, NEWS, TELNET, and VOICE.

GROUP	Access groups containing the desired dialing class within the directory. If the name parameter is used, access entry names within the specified group.

name	The name of the group containing the desired entry. The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper or lower case. The dialfind command can be used to find either an entry or group name based on a partial name.

index	The zero-based index of the entry, group, or entry within a group to search.

strvar	Will contain the name of the entry, group, or entry within a group if the search is successful. If dialname is not successful, strvar will be null.

Example

See the example for dialcount.

Comments

If the GROUP keyword is omitted, then entry names in the Connection Directory, including those within groups, will be enumerated.

dialname returns FAILURE if no entry, group, or entry within a group was found for the given index value. To determine the number of entries, the number of groups, or the number of entries within a group, use the dialcount command.

See also

dialadd, dialcount, dialdelete, dialinsert, dialfind and dialload; the set dialentry command family; Dialing Commands.


dialnumber

dialnumber dialclass string

Calls a specified telephone number.

dialclass	A keyword representing a Connection Directory entry class.

string	A valid telephone number.

Example

proc main

   string DialNum                  ; Phone number to dial.

   if sdlginput "Dialer" "Number:" DialNum

      if not nullstr DialNum       ; Make sure numbers not empty.

         dialnumber DATA DialNum   ; Dial the number entered.

      endif

   endif

endproc

Comments

dialnumber accepts only a single telephone number. For multiple Connection Directory entry numbers, use the dial command.

dialnumber will fail if a dialing operation or a file transfer is already in effect.

See also

dial, dialcancel and dialload; $DIALING ; the set dial command family; Dialing Commands.


dialogbox

dialogbox id left top width height style [title] [CALL name] [PARENT id]

Marks the beginning of a dialog box statement group. A dialog box is a customized data entry window that can be controlled by the ASPECT script.

id	An integer variable or constant, greater than or equal to zero, specifying the id for this dialog box. This value is used by other dialog box commands to control, update, or destroy the dialog box.

left top  width height	Constant integer parameters specifying the initial  position and size of the dialog box. Coordinates are relative to the parent’s client window. If no parent is specified, the client window defaults to Procomm Plus’s.
style	An integer constant, defining the behavior and appearance of the dialog box. Add any combination of the following values:

0	A normal modal dialog box. A modal dialog box prevents the user from accessing its owner, whether it is another dialog box or Procomm Plus’s main window. Modal dialog boxes are typically used when input is required before program flow can be continued.

1	A dialog box centered with respect to its parent.

2	A moveable dialog box with caption.

4	A modeless dialog box, which allows the user to access the dialog box’s owner, whether the owner is another dialog box or Procomm Plus’s main window. A modeless dialog box will remain intact while the user performs other tasks in other windows. Typically, modeless dialogs are used when the input is independent of other tasks or actions in Procomm Plus.

8	Trap <Esc>, <Alt><F4> and Close events (event -1). This is used to prevent the user from destroying the dialog box without script intervention.

If not trapped, the <Esc> and <Alt><F4> keys, and the Close command on the dialog box’s system menu will automatically close the dialog box, and will not save any file-related control contents to disk. This includes the flistbox, feditbox and dirlistbox controls.

16	Remove Close command from system menu. This is often used in conjunction with style bit 8 to let the user know that closing the dialog must be done specifically through control actions.

Removing the Close command from the system menu with value 16 does not prevent <Alt><F4> from closing the dialog box. The <Esc>, <Alt><F4>, and Close events must be specifically trapped using value 8 to prevent closure.

32	Hide dialog box until shown with the dlgshow command. Hiding the dialog box allows the script to modify, enable or disable controls before the user sees the dialog. This style is often used with the CALL name option, discussed below.

A dlgshow command must be issued to display a dialog box created with this style option.

64	Suspend script execution until the dialog box is destroyed. This style is used to prevent the script from executing beyond the enddialog command until the dialog box is destroyed.

In order to process dialog events, a when command should precede the dialogbox command, or the optional CALL name form should be used to create a polling loop, to handle dialog events.

If no events are processed, either by a when or a CALL name procedure, the script will resume execution when the dialog box is destroyed, at which time the dlgevent command can be called to determine how the dialog was destroyed. In this case, dlgevent will return either a control id value or -1. Only one event will be available from the event queue, since the dialog box has already been destroyed.

128	Update variables when event is read from queue. This means that an ASPECT result variable associated with a dialog box control will not be updated immediately when the control is accessed and changed. Instead, the variable will be updated when the event is read from the event queue.

Typically, this style option is used when the script intends for one control to interact with another control, yet needs to work with "old" information before fresh input is handled or variable contents are allowed to change.

The event queue is limited in size. If an event occurs when the queue is full, the event that is "bumped" from the head of the queue will cause its associated variable to be updated automatically. A dlgflush command, when used with the optional SAVE argument, will also cause all variables associated with the flushed events to be updated.

An OK button, when selected, closes a dialog box and updates all associated variables within the dialog, regardless of the status of the event queue. A Cancel button does not update associated variables.

dlgevent id flush can be used to flush the dialog box event queue. If dialog box style 128 is specified, use the save argument to update variables whose control events remain in the queue.

256	Version 1.0 compatibility. This style allows a dialog box to retain certain behaviors that it would have had in Procomm Plus version 1.0. This style should not be used normally, as it is intended only for dialog boxes converted from Procomm Plus 1.0 to 2.0. It supports behaviors that could not be converted directly, and relies on id values as they were defined in version 1.0.

These behaviors include saving all file-related controls whenever they lose input focus, letting partial paths resolve to the current working directory rather than the Aspect Path, centering the dialog, if specified, horizontally with respect to Procomm Plus’s main window, rather than both horizontally and vertically with respect to the parent window, not generating a dialog event when an Esc, Alt-F4 or the system menu Close command is issued and the script is trapping these events, setting a single tab stop out of view in a list box, and returning a sequence value for an option button rather than its id.

title	Text displayed in the title bar of the dialog box. This parameter is required for a style 2, Moveable with caption dialog box, but it can be a null string if no text is desired. A string constant or string variable can be used.

PARENT id	This parameter is a dialog box id that identifies the owner of the current dialog box. When an owner dialog box is destroyed, its child dialog boxes will be automatically destroyed as well. Either a constant or global integer can be used for the id value, but it must be greater than or equal to zero.

If PARENT id is not specified, Procomm Plus’s main window is assumed by default.

CALL name	This parameter identifies a procedure to be called when the dialog box is created. It is often used with style 32 dialogs in order to take control of the dialog box before it is displayed. It can also be used to set up a polling loop to process all dialog box events, achieving in effect the same results as style 64 dialog.

Example

proc main

   ; Define and display the dialog box.

   dialogbox 0 0 0 100 50 11 "Dialog Box"

   enddialog

   pause 5               ; Show off the dialog box.

   dlgdestroy 0 CANCEL   ; Destroy the dialog.

endproc

Comments

dialogbox groups are highly structured. All dialog box group commands in a script must appear between dialogbox and enddialog commands, and only dialog box commands may be used within a dialogbox group.

If another dialog box is created using the same id as an existing dialog box, the existing dialog will automatically be destroyed, just as if it were canceled by the user.

Local variables may be used within the dialogbox statement or in any dialog box control statement. However, the dialog box will be automatically destroyed when the procedure that defines the local variables returns.

Up to 255 total controls can be used within a dialogbox. Each control within a dialogbox must have a unique id value, ranging from 1 up to 999. The ASPECT Compiler will detect duplicate id values and return an error message.

The size of the dialog box and all controls placed within it are positioned and sized in Dialog Box Units, or DBUs. For more information on DBUs, see Dialog Box Units.

If a strvar is specified for the caption parameter, it can be changed and updated using dlgupdate with a starting id of 0.

The use of #defined macros within the dialogbox group is allowed. The Procomm Plus Dialog Editor cannot interpret macros, however. To use macros within a dialogbox group, simply insert them after the dialog box is complete.

Controls and graphics in the User window are painted in the order their commands appear in the dialogbox group, and not in the numeric order of their ids.

metafile and bitmap commands should be listed ahead of any controls you wish to place over them. If a dlgupdt command is used to repaint a control that has other controls displayed over it, those control ids should be updated as well.

Access to dialog boxes, and their controls, can be controlled with the enable or disable commands.

See also

dlglist, dlgctrlwin, dlgdestroy, dlgevent, dlgsave, dlgshow, dlgupdate, dlgwin, dlgwinctrl, enable, disable, bitmap, metafile, icon, iconbutton, listbox, flistbox, combobox, fcombobox, editbox, feditbox, text, ftext, dirpath, dirlistbox, groupbox, radiogroup, radiobutton, endgroup, pushbutton and enddialog; Dialog Box Commands.


dialsave

dialsave [filespec]

Saves the current Connection Directory to disk.

filespec	Optional name or complete path for the directory file, if different from the Connection Directory path. Specifying a filename which is different from the currently loaded Connection Directory file is the same as using the Save As... command on the Connection Directory menu.

Any filename and extension can be used. However, the use of a .DIR file extension is highly recommended. No default extension is assigned if one is not specified. The local task path is assumed if no path is specified.

Example

proc main

   dialadd DATA GROUP "BBS List"         ;Add group called 'BBS List'

   dialadd DATA "Garvinsoft BBS"         ;Add a Garvinsoft Entry

   set dialentry access DATA "Garvinsoft BBS";Specify which entry will

                                          ;be accessed

   set dialentry areacode "573"           ;Set the area code

   set dialentry phonenumber "555-1234"   ;Set the phone number

   dialinsert DATA "BBS List" "Garvinsoft BBS";Insert entry into 'BBS

   dialsave                               ;List'group and Save the

                                          ;Connection Directory

endproc

Comments

If the directory is saved under a different filename, that filename becomes the currently loaded Connection Directory file.

The dialsave command will fail if the Connection Directory is displayed at its execution time.

See also

dialadd, dialcreate, dialdelete, dialinsert and dialload; the set dialentry command family; Dialing Commands.


dialstats

dialstats name {longvar longvar longvar} | CLEAR

Retrieves the last date and time called, total connect time, and total calls made for the specified Connection Directory entry.

name	The name of the Connection Directory entry to access. The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find either an entry or group name based on a partial name.

longvar	Will be set to the last date and time on which a connection was made with this entry, using the timeval format as is used by $LTIME. The ltimestrs or ltimestring command can be used to split this value into date and time strings.

longvar	Will be set to the total connect time for this Connection Directory entry, in seconds. It can be converted into a readable time string using the ltimeelapsed command.

longvar	Will be set to the total number of connections made to this entry.

CLEAR	Resets the statistics for this Connection Directory entry. This is the same as a user pressing the Clear button in the Connection Directory Statistics dialog.

Example

proc main

   long LastConn              ; Last connection.

   long TotalConn             ; Total connect time.

   long TotalCalls            ; Total number of connects.

   integer NumEnts            ; Number of directory entries.

   integer Count              ; Used to loop through entries.

   string DirEntry            ; Name of directory entry.

   string LastTime            ; Last connect as string.

   dialcount DATA NumEnts     ; Get number of entries.

   for Count = 1 upto NumEnts ; Loop through entries.

      dialname DATA Count DirEntry   ; Get name of entry.

      dialstats DirEntry LastConn TotalConn TotalCalls

      ltimestring LastConn LastTime

      usermsg "Last Connect: %s" LastTime

      dialstats DirEntry CLEAR ; Clear the entry's stats.

   endfor

endproc

See also

dialname, ltimestrs, ltimeelapsed and ltimestring; Dialing Commands.


dir

dir filespec [strvar]

Displays a standard file listing and optionally returns a filename selected by the user.

strvar	An optional string variable containing the file selected by the user.

Example

proc main

   string Fname            ; String to contain file name.

   string FileSpec         ; String to contain file spec.

   string Attr             ; String to contain attributes.

   FileSpec = "c:\*.*"     ; Set spec to all files in "c:\".

   dir FileSpec Fname      ; Display dir and get file name.

   if SUCCESS              ; See if a file was chosen.

      ; Get and display attributes for chosen file.

      fileget Fname ATTRIBUTE Attr

      usermsg "Attributes for `"%s`" are `"%s`"." Fname Attr

   endif

endproc

Comments

dir displays a standard file selection dialog with the title bar of Directory File List.

The filespec argument in the dir command can contain several file types to display by default. This is done by separating each file type from the previous type with a semicolon. For example, to display all .txt and .doc files, the command would be formed as:

dir "*.TXT;*.DOC"

An optional path may precede the first file type.

See Also

DOS- or Disk-Related Commands.


dirlistbox

dirlistbox id left top width height filespec [filetype] {MULTIPLE filespec} |
{SINGLE strvar} [dirpathid] [HSCROLL] [SORT]

Adds a file selection list box to a Windows dialog box. The list box displays the files, sub-directories and disk drives available.The parent directory of the current directory is also indicated by the usual double periods.

id	A unique integer constant which identifies this control. This value will be stored in dlgevent’s target variable when a selection is made in the dirlistbox.

left top  width height	Integer constants specifying the position and size of the dirlistbox. Coordinates are relative to the dialog box window, specified in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.
filespec	A string variable or constant containing the drive and directory path of the files to be displayed in the list box. If a filespec is included, at least one DOS wildcard character,* or ?, must be included in the filespec. If a path is not included in the filespec, the Aspect Path is assumed.

filetype	A optional string containing characters which represent file attributes.

MULTIPLE  filespec	Filespec is a string variable or constant naming the file created with the multiple files chosen from the displayed list. The file list is carriage return/linefeed-separated. Each entry in the list will be a fully-qualified filespec.
Entries in a pre-existing selection file will be automatically selected within the dirlistbox on start-up, if the paths in the entries is identical to the current path specified in the file list filespec.

If a path is not included in the filespec, the Aspect Path is assumed.

When MULTIPLE filespec is used, a dlgsave or dlgdestroy command should be used to write the selected file names to the disk file. Otherwise, no file will be created.

SINGLE strvar	Will contain the filename selected by the user. strvar can be pre-initialized with a filename, allowing it to already be selected upon entry. Note that this returns a fully-qualified filespec, not just the the filename.

dirpathid	An integer constant specifying an optional dirpath id value. The associated dirpath will be updated with the current directory path selected in the dirlistbox.

HSCROLL	If specified, places horizontal scrollbars on the dirlistbox.

SORT	If specified, causes the file and directory names to be sorted alphabetically.

Example

proc main

   string Directory             ; Path for dirpath control.

   string FileToFind            ; File from directory list box.

   integer Event                ; Dialog event.

   ; Display a dialog box with a dirpath and directory list box.

   dialogbox 0 87 241 122 98 11 "Choose a file"

      dirpath 1 4 2 90 13 Directory

      dirlistbox 2 4 17 112 49 "*.*" single FileToFind 1 sort

      pushbutton 3 41 76 40 14 "&OK" ok default

   enddialog

   while 1

      dlgevent 0 Event          ; Get dialog event.

      switch Event              ; Evaluate event.

         case 0                 ; No event occurred.

         endcase

         case 1                 ; Ignore dirpath

         endcase

         default                ; An exit case was chosen.

            exitwhile           ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL          ; Destroy the dialog.

   if not nullstr FileToFind    ; See if file name is empty.

      usermsg "You chose `"%s`"." FileToFind

   else

      usermsg "No file selected."

   endif

endproc

Comments

dirlistbox can only occur within a dialogbox group. It allows the user to change directories or drives by double-clicking on the desired directory or drive name.

The dirlistbox command accepts an optional filetype string which can be used to limit the search pattern to files with specific attributes. The string may be composed of characters representing attribute types: ’R’ for read-only, ’H’ for hidden, ’S’ for system, ’A’ for archive, ’D’ for directory, and ’I’ for drive.

By default, the search always includes normal files, which are files without attributes or files with read-only and/or archive attributes. Directory names and drives are also normally included. For example, if you specify "HS" for search attributes, all files with no attributes, read-only or archive attributes will also appear in the resulting list, in addition to those files having hidden or system attributes.

The character ’X’ may be included to override the default searching method. This indicates that the search is limited exclusively to those files matching one or more of the specified attributes. A list of directory names can be created by specifying "DX" as the search string; only drives will be displayed if "IX" is used.

In Windows 95, dirlistbox will only display short filenames. ASPECT will automatically convert a long filename to its short filename format in order to make a listbox selection during initialization or update of the dirlistbox control.  To obtain the long filename format for a dirlistbox selection, simply issure a findfirst command with the selected item, and then read the $FILENAME system variable for the result.

In Windows NT, long filenames are displayed in a dirlistbox control and selections must be made using the long filename format.  To obtain a long filename from a short filename, issue a findfirst command and read the $FILENAME result.

If either directories or drives are displayed exclusively in a dirlistbox, then the control id will generate dialog events whenever a drive or directory is selected. If no default button is present, then when a directory is double-clicked, the control will change directories and re-initialize its contents with the sub-directories within the directory that was double-clicked. Double-clicking a drive has no effect when a default button is not present in a drive-exclusive listing.

When the user clicks on a particular filename, dirlistbox places that filename into strvar if SINGLE is specified. If the user double-clicks on a particular filename, dirlistbox assumes that the selection(s) are complete, and will assign the strvar to the selected SINGLE file, or place only the double-clicked selection into the specified MULTIPLE filespec, and select the dialog box’s default button if one is specified.

If a drive or directory is double-clicked, and there is a default button or iconbutton present, then that default button will be automatically selected.

See also

dialogbox, dirpath, dlgevent, dlgsave, dlgdestroy, dlgupdate, iconbutton and pushbutton; Dialog Box Commands.


dirpath

dirpath id left top width height [strvar]

Displays the current disk drive and directory for a dirlistbox control within a dialog box.

id	A unique integer constant which identifies this control.

left top  width height	Integer constants specifying the position and size of the dirpath. Coordinates are relative to the dialog box window in DBUs. For more information on DBUs, see Dialog Box Units.
strvar	If specified, strvar will contain the dirpath contents.

Example

See the example for dirlistbox.

Comments

If referenced in a dirlistbox command, dirpath automatically provides a display of the currently selected path in that dirlistbox. An event will be generated whenever the contents of the dirpath are changed, but only if the optional string result variable is specified.

See also

dialogbox, dlgevent and dirlistbox; Dialog Box Commands.


disable

see below for various formats

Disables dialog box controls, dialog boxes, menu selections or windows. Items that are disabled are grayed and cannot be selected.

disable DIALOGBOX dlgid

dlgid	The unique id of the dialog box to disable, including its controls. If the dialog box has child dialog boxes, they will be disabled as well.

disable DLGCTRL dlgid startid [endid]

dlgid	The unique id of the dialog box containing the control to be disabled.

startid	The id of the first or only control to be disabled.

endid	If specified, allows a range of dialog box controls to be disabled, from startid to endid.

disable ASPMENU startid [endid]

ASPMENU	disables a menu selection generated by an ASPECT script.

startid	The id of the menu selection to be disabled.

endid	If specified, allows a range of menu selections to be disabled, from startid to endid.

disable PWMENU startid [endid] [PERMANENT]

PWMENU	disables a menu selection on the Procomm Plus menus.

startid	The id of the menu selection to be disabled.

endid	If specified, allows a range of menu selections to be disabled, from startid to endid.

PERMANENT	The menu selection(s) will remain disabled after the script terminates.

disable WINDOW window

window	The id of the window to be disabled. This value can be obtained by accessing the $PWMAINWIN, $FOCUSWIN, $ACTIVEWIN, $MAINWIN, $POINTERWIN and $USERWIN system variables. The taskwin, dlgwin, and dlgctrlwin commands also return a window id.

Example

proc main

   integer EventNum               ; Dialog EventNum.

   ; Define a dialog box with button controls

   dialogbox 0 109 94 100 74 11 "Disable Dialog"

      pushbutton 1 5 5 40 40 "Button &1"

      pushbutton 2 55 5 40 40 "Button &2"

      pushbutton 3 30 52 40 14 "&Exit" ok default

   enddialog

   while 1                        ; Loop forever.

      dlgevent 0 EventNum         ; Get next dialog EventNum.

      switch EventNum             ; Evaluate the EventNum.

         case 0                   ; No EventNum occurred, do nothing.

         endcase

         case 1    ; Button 1 was pressed.

            disable DLGCTRL 0 1   ; Disable button 1.

         endcase

         case 2    ; Button 2 was pressed.

            disable DLGCTRL 0 2   ; Disable button 2.

         endcase

         default                  ; Exit was selected.

            exitwhile

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL            ; Get rid of our dialog box.

endproc

Comments

You may wish to disable certain items during the execution of a script to prevent the user from selecting them. disabled items can include any of the Procomm Plus menu items, any control in a dialogbox statement group, any menu item built by the script, or entire dialog boxes.

Use caution when disabling windows! If a window is disabled, it no longer responds to keyboard or mouse input.

Remember when disabling windows, dialog boxes and dialog box controls, if the item you wish to disable has the focus, you should set the focus somewhere else prior to using the disable command. If you disable a windows, dialog box, or dialog box control that has the focus, accelerators and other keystrokes will not be processed properly.

The id values of Procomm Plus menu items can be found in pw4menu.inc, installed by default in the ASPECT directory. This file can be #included for reference in an ASPECT script.

A menu item that was generated by an ASPECT script can only be enabled or disabled when it is displayed. Procomm Plus’s menu items, on the other hand, can always be affected, unless they were disabled by Procomm Plus itself.

The $ASPMENU system variable is used only for menu items created by an ASPECT script. It will not indicate when a Procomm Plus menu item has been selected. Pop-Up menus and menu bars cannot be directly enabled or disabled from within a script.

See also

dialogbox, enable, menupopup, menuitem, winactivate, wintask, taskactivate and taskwin; $ACTIVEWIN, $PWTASK, $TASK and $ASPMENU; General Windows Commands.


disconnect

disconnect

The operation of disconnect is dependent on the current mode. In Data mode, disconnect hangs up the phone. In FTP, Telnet, Mail, and News modes, disconnect terminates the connection with the server.

Example

proc main

   when USEREXIT call Cleanup ; Watch for user exit.

   while $CARRIER             ; Loop while connected.

      yield                   ; Yield processing time

   endwhile

endproc

proc Cleanup

   disconnect                 ; Hang up the phone line.

endproc

Comments

disconnect is not a synonym for hangup.

See Also

hangup; COM-Related Commands.


diskfree

diskfree disk longvar

Returns the free disk space of the specified drive into a long variable.

disk	An integer number designating the drive; 0 indicates the current drive, 1 specifies drive A, 2 indicates drive B and so on up to 26 for drive Z.

longvar	Will contain the number of bytes free on the specified drive.

Example

proc main

   long FreeDisk              ; Amount of free disk space.

   diskfree 0 FreeDisk        ; Get free space on current drive.

   usermsg "%ld bytes free on disk." FreeDisk

endproc

See also

dir, getdir and memavail; $USERPATH and $VOLUME; DOS- or Disk-Related Commands.


dlgctrlwin

dlgctrlwin id ctrlid intvar

Returns the window id of a dialog box control.

id	The id of the dialog box which contains the specified control.

ctrlid	The id of the specified control.

intvar	Will contain the value of the window id of the specified control. This value may be used in any command that accepts a window id.

Example

proc main

   integer ButtonID           ; Window handle for button.

   integer Count = 0          ; Used in while loop below.

   ; Display a dialog and flash a button on and off.

   dialogbox 0 0 0 100 50 11 "Flashing Button"

      pushbutton 1 5 5 90 40 "Flash"

   enddialog

   dlgctrlwin 0 1 ButtonID    ; Get handle of button.

   while (Count++) < 5        ; Loop for count.

      winhide ButtonID        ; Hide the button.

      pause 1                 ; Pause for effect.

      winshow ButtonID        ; Show the button.

      pause 1                 ; Pause for effect.

   endwhile

   dlgdestroy 0 CANCEL        ; Destroy the dialog.

endproc

See also

dialogbox and dlgwinctrl; $FOCUSWIN; Dialog Box Commands.


dlgdestroy

dlgdestroy id CANCEL | OK

Destroys a dialog box.

id	The id of the dialog box to be destroyed.

CANCEL	If CANCEL is specified, the dialog box will be destroyed without updating any changes made to file-related controls.

OK	If OK is specified, the dialog box will be destroyed, but changes made to file-related controls will be saved to disk.

Example

See the example for dirlistbox.

Comments

To save changes made to a file-related control before destroying the dialog, use the dlgsave command. File-related controls include flistbox, feditbox and fcombobox.

Note that if the dialog box was created with style 128, Update variables when event is read, dlgdestroy id OK updates all variables whose events have not been retrieved with dlgevent.

See also

dialogbox, dlgevent, dlgsave, fcombobox, feditbox and flistbox; Dialog Box Commands.


dlgevent

dlgevent id [intvar | {FLUSH [SAVE]}]

Returns the id of a user action within a dialog box, or flushes the EventID queue for the specified dialog box.

id	The dialog box id whose EventID queue will be accessed.

intvar	If intvar is specified, it will return the value of the last dialog box EventID.

FLUSH	If FLUSH is specified, dlgevent will reset the EventID queue for the specified dialog box.

SAVE	Only valid with the FLUSH keyword. Causes variables associated with EventID values to be updated as the values are flushed from the queue.

Example

proc main

   integer EventID         ; Dialog box EventID.

   ; Define and display dialog and wait for EventIDs

   dialogbox 0 88 176 100 50 11 "Dialog Events"

      pushbutton 1 32 17 40 14 "&Exit" ok default

   enddialog

   while 1                 ; Loop forever.

      dlgEvent 0 EventID ; Get dialog EventID.

      switch EventID       ; Evaluate the EventID.

         case 0            ; No EventID occurred.

         endcase

         default           ; Dialog EventID occurred.

            exitwhile      ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL     ; Destroy dialog box.

endproc

Comments

dlgevent will set the intvar argument to a dialog box control ID if an event of that type has occured, to zero if no event is available, to -1 if the dialog box has been closed by <Alt><F4>, <Esc> or the menu Close command, or to -2 if the <F1> key was pressed for context-sensitive help. In addition, the intvar argument is set to -3 if the parent dialog box (if any) was closed via an OK button or destroyed with the OK flag in dlgdestroy.

A child dialog box is destroyed automatically when its parent is destroyed.

The dlgevent id FLUSH SAVE is useful when the dialog box style value includes 128 (Update variables when EventID is read). For more information, see the dialogbox command's style list.

dlgevent sets SUCCESS true when there are dialog events in the event queue. When the optional argument is not specified, an event is not read from the queue.

See also

dialogbox, dlgdestroy, dlgsave and dlgwin; Dialog Box Commands.


 dlgexists

dlgexists id [intvar]

Sets SUCCESS true if the dialog box with the associated id exists.

id	An integer variable or constant specifying the dialog box id. This value is used by other dialog box commands to control, update, or destroy the dialog box.

intvar	This optional integer variable is assigned the value 1 if the dialog exists, or 0 otherwise.

See also

dialogbox, dlgevent, and dlgdestroy; Dialog Box Commands..


dlglist

dlglist id ctrlid {INSERT string [integer]} | {REMOVE integer | string} |
{SELECT integer | string [MULTIPLE]} | {UNSELECT [integer | string]} |
{ITEMCOUNT intvar [intvar]} | {ITEMNAME integer strvar [intvar]} |
{ITEMFIND string [intvar [integer]] [EXACT]}

Adds, removes, counts, retrieves or finds an item from a listbox, flistbox, combobox or fcombobox control.

id	The id of the dialog box containing the target list control.

ctrlid	The target list control id.

INSERT string	The specified string will be inserted into the target control’s itemlist. If the optional integer is not provided, the item will be appended to the end of the list.

integer	If specified, integer is treated, as an index, determining where the string will be inserted in the itemlist. A value of -1 will append the string to the end, while a 0 will insert the string at the top of the list. If the index location is greater than the number of items already in the list, the item will be appended to the end of the list.

REMOVE string	The specified string will be removed from the target control’s itemlist.

integer	If specified, integer is treated as an index, determining where the string will be removed from in the itemlist. A value of -1 will remove all of the items in the list. If the index location is greater than the number of items already in the list, the item will be removed from the end of the list.

SELECT	Specifies strings to be highlighted in the list box.

integer	If specified, integer is treated as an index, determining which item is to be selected.

string	The string of the item to be selected.

MULTIPLE	If specified, this allows ASPECT to highlight multiple selections in a multi-select list box. It is ignored for combo boxes and single-select list boxes.

UNSELECT	Specifies strings to be unselected in the list box.

integer	If specified, integer is treated as an index, determining which item is to be unselected.  If not specified, all selections are removed.

string	The string of the item to be unselected.

ITEMCOUNT intvar
Returns the total number of items within the specified list or combo box. This is useful if you're enumerating a list with an ITEMNAME operation.

intvar	If specified, intvar will be assigned the number of items selected in the list or combo box, although combo boxes can have at most one item selected.

ITEMNAME integer
Retrieves the displayed text associated with a list or combo box entry. integer is a zero-based index.

strvar intvar	strvar will be assigned the text displayed in the list or combo box entry associated with the specified index. intvar will be set to 1 if the entry is selected, 0 otherwise.

ITEMFIND string	Searches a list or combo box for a particular item or entry matching the specified string. The search is case-sensitive.

intvar	intvar returns the index of the entry satisfying the search string.

integer 	Specifies the index after which the search will begin. This allows you to continue searches beyond the first item found. Otherwise, the list is searched from the top.

EXACT	If specified, only exact matches for the search string will be returned.

Example

proc main

   string FullList              ; List of stuff to choose from.

   string Items                 ; Item selected from list.

   Items = "Level,Plane,File"   ; Initialize the list.

   dialogbox 0 73 147 101 80 11 "Dlglist Example"

      listbox 1 5 5 90 40 FullList single Items sort

      pushbutton 2 30 57 40 14 "&Exit" ok default

   enddialog

   pause 2   ; Show off dialog.

   dlglist 0 1 INSERT "Nails"   ; Insert items into list.

   dlglist 0 1 INSERT "Hammer"

   dlglist 0 1 INSERT "Screwdriver"

   dlglist 0 1 INSERT "Ruler"

   dlglist 0 1 INSERT "Chisel"

   pause 5                      ; Show off the dialog.

   dlgupdate 0 1                ; Update the list box, which

   ; restores our list to its original values.

   dlgdestroy 0 CANCEL          ; Destroy the dialog.

endproc

Comments

dlglist returns SUCCESS if the string was successfully added or removed from the target control’s item list, FAILURE otherwise.

dlglist does not affect the contents of the associated control's list variable or list file contents, only the displayed itemlist. If dlglist is used to add or remove list items, these changes are not written to disk with dlgsave. dlglist does not affect dlgsave, since dlgsave only affects the result variables and files.

See also

dialogbox, dlgsave and dlgupdate; Dialog Box Commands.


dlgsave

dlgsave id ctrlid [ctrlid]

Updates variables associated with dialog box controls and forces changes in fcombobox, feditbox and flistbox controls to be written to disk.

id	The id of the dialog box containing the control to be saved.

ctrlid [ctrlid]	The control id, or, if the second [ctrlid] is specified, the beginning of a range of control id’s to be saved.

Example

See the example for feditbox.

Comments

dlgsave is useful for saving file-related controls, or for reading current selections when a dialog box is created using style 128. For more information on dialog box style-bits see the dialogbox command. Typically, dialog box controls update their associated data fields as changes are made to them.

See also

dlgdestroy, dlgevent and dlgupdate; Dialog Box Commands.


dlgshow

dlgshow id

Causes a hidden dialog box to be made visible.

id	The id of the dialog box to be made visible.

Example

proc main

   ; Define and display the dialog box. 32 is added to

   ; the dialog type to keep it hidden until dlgshow.

   dialogbox 0 0 0 100 50 43 "Hidden Dialog"

   enddialog

   usermsg "The dialog is displayed after this message."

   dlgshow 0               ; Show the hidden dialog.

   pause 5                 ; Show off the dialog.

   dlgdestroy 0 CANCEL     ; Destroy the dialog box.

endproc

Comments

dlgshow is only useful for showing dialog boxes of style 32, Hide until shown. Use winshow to display a dialog box hidden with winhide.

See also

enable, disable, dialogbox, dlgwin, winshow and winhide; Dialog Box Commands.


dlgupdate

dlgupdate id ctrlid [ctrlid]

Refreshes the display of a dialog box control, applying any changes made to the control’s associated variables.

id	The id of the dialog box containing the controls to be updated.

ctrlid [ctrlid]	The control id, or, if the second [ctrlid] is specified, the beginning of a range of control id’s to be refreshed.

Example

See the example for dlglist.

Comments

If a gstrvar is used for the dialog box title, it can be refreshed using a start id of 0.

dlgupdate has no effect on files that need to be written to disk.

See also

dialogbox and dlgsave; Dialog Box Commands.


dlgwin

dlgwin id intvar

Returns the window id of the specified dialog box.

id	The id of the dialog box desired.

intvar	Returns the window id value of the dialog box.

Example

proc main

   integer DlgHandle               ; Window handle for dialog.

   integer XPos, YPos              ; X and Y position of dialog.

   ; Define and display dialog then move it around a bit

   dialogbox 0 0 0 100 50 11 "Moving Dialog"

   enddialog

   dlgwin 0 DlgHandle              ; Get window handle for    dialog.

   wincoord DlgHandle XPos YPos    ; Get X and Y position of dialog.

   while (YPos += 10) == $YPIXELS  ; Loop while dialog's on screen.

      winmove DlgHandle XPos YPos  ; Move the dialog.

      mspause 250                  ; Pause for effect.

   endwhile

   dlgdestroy 0 CANCEL             ; Destroy the dialog box.

endproc

Comments

The value returned by dlgwin can be used with winhide, winshow, and other window-related commands to manipulate the state of the dialog box.

See also

dialogbox, enable, disable, winhide, winmove and winshow; Dialog Box Commands.


dlgwinctrl

dlgwinctrl id window intvar

Converts a window id into the corresponding control id, within a given dialog.

id	The target dialog box id.

window	The window id to convert.

intvar	Returns the corresponding control id, if found.

Example

proc main

   integer DlgControl         ; Id of dialog control

   dialogbox 0 0 0 100 50 11 "Under Cursor"

      pushbutton 1 5 5 90 40 "&Over Here"

   enddialog

   while 1                    ; Loop forever.

      dlgwinctrl 0 $POINTERWIN DlgControl

      if DlgControl == 1      ; See if cursor's over button.

         usermsg "Cursor over button!"

         exitwhile            ; Exit the while loop.

      endif

   endwhile

   dlgdestroy 0 CANCEL        ; Destroy the dialog box.

endproc

Comments

Used in conjunction with $FOCUSWIN, dlgwinctrl allows a script to determine which dialog box control has the input focus. This is the opposite function of dlgctrlwin.

FAILURE is set if no control id within a dialog corresponds to the specified window id.

See also

dialogbox and dlgctrlwin; $FOCUSWIN; Dialog Box Commands.


dllcall

dllcall integer string [arglist]

Calls a routine within a .dll module created to interact with ASPECT.

integer	The ID of the DLL previously loaded with dllload.

string	A string identifying the routine to be executed within the DLL. The routine name must be identical to the exported name in the DLL. Note that this name is case-sensitive.

arglist	A maximum of 12 variables can be passed as arguments.

Example

See the example for dllload.

Comments

For complete DLL specifications, please look at the Apsect dll specifications and sample code located on the CD in \samples\Aspect\Creating an Aspect DLL folder.

Only .dlls that have been written with the ASPECT DLL interface specification can be used with this command. Calling an arbitrary .dll may cause a critical application error to occur!

See also

dllload and dllfree; General Windows Commands.


dllfree

dllfree integer

Frees unneeded DLL memory resources.

integer	The DLL id number returned by the dllload command that initiated the process you wish to free.

Example

See the example for dllload.

Comments

Generally, a script should free the DLL modules it has loaded into memory when they’re no longer needed. This frees up application memory that would otherwise be claimed while the script is still being executed. However, Procomm Plus will ensure that all DLL processes loaded by a script are removed at script termination, unless they were loaded using the PERMANENT option, in which case the .dll will not be removed until Procomm Plus terminates.

See also

dllcall and dllload; General Windows Commands.


dllload

dllload filename intvar [PERMANENT]

Loads the specified DLL module into memory.

filename	The name of the .dll to load. If no path is specified, the Aspect Path is assumed.

intvar	An integer id used by the dllcall and dllfree commands to reference the .dll module.

PERMANENT	If this keyword is specified, the dll will remain loaded after the script terminates. It will unload, however, when Procomm Plus terminates.

Example

proc main

string DLLName = "funcs.dll"                ; DLL to load.

integer DLLHandle                           ; Handle to the dll.

   ; Make a call to the "DisplayBMP" function in the DLLHandle,

   ; and pass it the index of a bitmap to display.

   if dllload DLLName DLLHandle             ; Open the Dynamic Link Library.

      if not dllcall DLLHandle "DisplayBMP" 3

         errormsg "Call to `"DisplayBMP`" function failed!"

      endif

      ; In order for Aspect to call a DLLH, the DLL must be an

      ; Aspect-compatible DLL.

      dllfree DLLHandle            ; Free or close the library.

   else

      errormsg "Couldn't open DLLHandle!"

   endif

endproc

Comments

Typically, the only .dlls that should be loaded are those written specifically to interface with ASPECT and the dllcall command. For more information, see the dllcall command.

Note that dllload will only load 32-bit .dll files.

See also

dllcall and dllfree; set aspect path; General Windows Commands.


dllobject

dllobject id left top width height BACKGROUND | USERWIN

Identifies a graphic object within a User window to be updated by an associated DLL module.

id	The control id for the DLL object. $OBJECT will be set to this value when the object is selected by the user.
left top  width height	Integer parameters specifying the initial position and size of the DLL object in User Window Units, or UWUs. For more information, User Window Units. Coordinates are relative to Procomm Plus’s client window.
BACKGROUND | USERWIN	If BACKGROUND is specified, the object stays over the same spot on a background graphic. Specify USERWIN to "fix" the top left corner of the object in position relative to the upper left corner of the User window.
Example

See the example for dllobjfile.

Comment

The dllobj-command family allows Procomm Plus to animate a graphic display with real time data. dllobject assigns an id and defines a position in the User window where the animated object will be displayed. dllobjfile identifies the DLL. dllobjupdt calls the update entry point in the DLL with the data used to animate the object. These are very powerful statements, but they require Windows-compatible DLL modules that have been especially-written for Procomm Plus.

See also

uwincreate, dllobjfile, dllobjupdt, objpaint, objremove, hotspot, bitmap, icon, iconbutton, pushbutton and metafile; $OBJECT; User Window Commands.


dllobjfile

dllobjfile filespec

Specifies a file containing a graphic object to be accessed or updated with the dllobject command.

filespec	If a path is not specified, filespec defaults to the current Aspect Path.
Example

proc main

   string DLLObjName = "objs.dll"         ; DLL object file to load.

   ; Define a user window and place on it a DLL object.

   dllobjfile DLLObjName                  ; Load an objects DLL.

   uwincreate FULL SCREEN 100 0 0 255 METAFILE

   dllobject 1 1000 1000 8000 8000 USERWIN

   uwinpaint                              ; Paint the user window.

   ; Make PW call our DLL and update the object

   ; with the specified parameters.

   dllobjupdt 1 "Text Object!" 23

   pause 5                                ; Pause to show off object.

endproc

See also

uwincreate, dllobject and dllobjupdt; $OBJECT; User Window Commands.


dllobjupdt

dllobjupdt id [arglist]

Allows a DLL module linked to a DLL object to update that object.

id	The identifier assigned by the user in the dllobject command.

arglist	A maximum of 12 variables can be passed as arguments.

Example

See the example for dllobjfile.

See also

uwincreate, dllobject and dllobjfile; User Window Commands.


dos

dos string [MINIMIZED | MAXIMIZED | HIDDEN] [intvar]

Executes a DOS command or another program within a separate DOS window.

string	Any executable command as it would appear on the DOS command line.

MINIMIZED	Forces Procomm Plus to execute the command or program as a minimized icon.

MAXIMIZED	Executes the command or program in a full-screen DOS window.

HIDDEN	Forces Procomm Plus to execute the command or program with no visible DOS window.

intvar	An optional integer variable assigned the task id number of the DOS window. This task id can be used in the taskactivate, taskexit, ddeinit and other commands.

Example

proc main

   string Cmd                       ; DOS command to execute.

   Cmd = "dir *.* > temp.fil"       ; Set DOS command to execute.

   DOS Cmd HIDDEN                   ; Run DOS command hidden.

   ; This is an easy way to get a list of files from a

   ; directory into a file. If you're using DOS 5.0

   ; or greater, you can specify the /B option to get

   ; a cleaner listing.

endproc

Comments

If one of the optional parameters MINIMIZED, MAXIMIZED or HIDDEN is not used, the application runs using a default window size and position.

The dos command is equivalent to using the Run command in the Windows File Manager with the string "COMMAND /C cmndname" as an argument. The DOS session uses the settings in _default.pif, unless a .pif file already exists for command.com.

If the path to the executable command is not specified, the program or external DOS command must be either in the current directory or in the directory specified in your DOS path. ASPECT will, however, change to the directory specified in $USERPATH before attempting to execute the dos command. Also, command.com must be in the directory from which you started your computer, typically the root directory of drive C or in the location specified by the COMSPEC environment variable.

dos can be tested with the if SUCCESS statement, returning false if command.com is not found or true if it is found, even if the command to be executed is invalid or fails to execute. The run command provides a similar function and provides better testing for DOS external commands and other programs.

If you use the dos command to execute a program or command that requires user input, be sure that the user is aware of this, since processing will halt until the required input is provided. The dos command will execute both standard DOS batch files and internal DOS commands. The run command only accepts .com and .exe programs.

See also

run, shell and taskexists; DOS- or Disk-Related Commands.


editbox

editbox id left top width height strvar [strlength]
 [MASKED] [MULTILINE]

Adds an editing box for text entry in an ASPECT dialog box.

id	The control id for the edit box, specified as an integer constant. This value will be reported by dlgevent whenever the editbox contents are changed.

left top  width height	Integer constants specifying the initial position and size of the editbox. Coordinates are relative to the dialog box, specified in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.
strvar	This variable is set to the contents of the edit field when the editbox loses focus. It can be pre-set to reflect a value before the dialog box is shown, or updated using dlgupdate.

strlength	An integer constant or variable, specifying the maximum number of characters that can be typed into the edit field. If the user attempts to type more than the maximum number of characters, an error beep sounds.

MASKED	If specified, an asterisk is displayed for each character typed into the field.

MULTILINE	If specified, allows text to be word-wrapped to the next line in the edit box. Note that the text length is still limited to 256 characters.

Example

proc main

   string TextStr          ; Text from dialog box.

   integer Event           ; Dialog box event.

   ; Define and display dialog with edit box.

   dialogbox 0 0 0 100 70 11 "Edit Box Example"

      editbox 1 5 5 90 40 TextStr MULTILINE

      pushbutton 2 25 50 50 14 "E&xit"

   enddialog

   while 1

      dlgevent 0 Event     ; Read dialog event.

      switch Event         ; Evaluate dialog event.

         case 0            ; No event occurred.

         endcase

         case 1            ; Edit box was changed.

         endcase

         default           ; Exit event selected.

            exitwhile      ; Exit the loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL     ; Destroy dialog box.

   if not nullstr TextStr  ; See that TextStr isn't empty.

      usermsg "You typed:`r`r%s" TextStr

   else

      usermsg "No text entered."

   endif

endproc

Comments

editbox can only occur within a dialogbox statement group. If the user is entering sensitive information, the MASKED option can be used to protect it.

A dialog event is generated when the edit control contents have been changed and the control loses the input focus.

See also

dlgupdate, dialogbox, dlgevent, ftext, text and feditbox; Dialog Box Commands.


else

else

Executes an alternate set of commands when the expression specified in the associated if or elseif commands evaluate as false.

Example

proc main

   integer Number = 25     ; Integer to check in conditional.

   if Number == 1          ; Check to see if number is 1.

      usermsg "The Number is 1."

   else

      usermsg "The Number is %d." Number

   endif

endproc

See also

if, elseif and endif; ASPECT Primary Commands.


elseif

elseif condition

Enables multiple tests within an if/endif command block. elseif can be used instead of if ... endif statement groups.

condition	Conditions can include any numeric expression or any command that sets the SUCCESS and FAILURE system variables.

The not keyword can precede an ASPECT command to logically negate the result of an ASPECT command.

The "!" operator can be used to logically negate a numeric expression or the result of a user-defined function. If the expression evaluates to a non-zero value, then the condition was satisfied and is considered true, while a value of 0 indicates that the test was false.

Example

proc main

   integer FirstVar = 1          ; First integer variable.

   integer SecondVar = 2         ; Second integer variable.

   if FirstVar != 1              ; Check to see if first is not 1.

      usermsg "First is not 1."

   elseif SecondVar == 2         ; Check to see if second is 2.

      usermsg "Second is 2!"

   endif

endproc

See also

if, else and endif; ASPECT Primary Commands.


enable

see formats shown below

Enables dialog box controls, dialog boxes, menu selections or windows.

enable DIALOGBOX dlgid

dlgid	The unique id of the dialog box to enable.

enable DLGCTRL dlgid startid [endid]

dlgid	The unique id of the dialog box containing the control to be enabled.

startid	The id of the control to be enabled.

endid	If specified, allows a range of dialog box controls to be enabled, from startid to endid.

enable ASPMENU | PWMENU startid [endid]

ASPMENU | PWMENU	Determines whether the menu or menu selection to be enabled was generated by Procomm Plus or a Windows ASPECT script.
startid	The id of the menu or menu selection to be enabled.

endid	If specified, allows a range of menu selections to be enabled, from startid to endid.

enable WINDOW window

window	The id of the window to be enabled. This value can be obtained using the winactivate and wintask commands.

Example

proc main

   integer Event           ; Dialog event.

   ; Define a dialog box with button controls

   dialogbox 0 109 94 100 74 11 "Disable Dialog"

      pushbutton 1 5 5 40 40 "Button &1"

      pushbutton 2 55 5 40 40 "Button &2"

      pushbutton 3 30 52 40 14 "&Exit" ok default

   enddialog

   while 1                 ; Loop forever.

      dlgevent 0 Event     ; Get next dialog event.

      switch Event         ; Evaluate the event.

         case 0            ; No event occurred, do nothing.

         endcase

         case 1            ; Button 1 was pressed.

            disable DLGCTRL 0 1  ; Disable button 1.

            enable DLGCTRL 0 2   ; Enable button 2.

         endcase

         case 2            ; Button 2 was pressed.

            disable DLGCTRL 0 2  ; Disable button 2.

            enable DLGCTRL 0 1   ; Enable button 1

         endcase

         default           ; Exit was selected.

            exitwhile

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL     ; Get rid of our dialog box.

endproc

Comments

enable cannot be used to enable something that Procomm Plus has disabled. It applies only to Procomm Plus menu items and dialog box controls created by a script.

Pop-Up menus and menu bars cannot be directly enabled or disabled from within a script.

You may wish to re-enable disabled items during the execution of a script to allow the user to select them. These items can include any of the Procomm Plus menu items, any control in a dialogbox statement group, any menu item built by the script, or entire dialog boxes.

Script menu items can only be enabled on the active menu bar and its pop-up items. Procomm Plus ’s menu items can always be affected, unless they were disabled by Procomm Plus itself. The active menu is always returned by the $PWMENUBAR system variable.

Two useful files are provided with Procomm Plus that can be #included into your scripts. These files are pw4menu.inc, which defines all of Procomm Plus’s menu values, and vkeys.inc, which defines the virtual key codes as shown in Virtual Key Codes Table. Both of these files are installed to the default ASPECT directory.

See also

disable, dialogbox, menupopup and menuitem; $ASPMENU and $PWMENUBAR; General Windows Commands.


encrypt

encrypt strvar strlength

encrypts or encodes the target string.

strvar	The string to encrypt; it will be updated with the encoded data.

strlength	The number of characters to encrypt.

Example

proc main

   string TextStr          ; Text string to encrypt.

   integer Len             ; Length of string to encrypt.

   ; Prompt user for top secret text string.

   sdlginput "Top Secret" "Enter Text to Encrypt: " TextStr

   if SUCCESS              ; See if CANCEL was selected.

      strlen TextStr Len   ; No? get length of text string.

      encrypt TextStr Len  ; Now encrypt text string.

      transmit TextStr     ; Send string to remote system.

      transmit "^M"        ; Send a carriage return.

   endif

endproc

Comments

The encrypt and decrypt commands work on "raw" data. For this reason, you must specify the length of the string to be encoded.

Use caution if writing the encrypted data to a text file. Since the data may contain control characters or even nulls, it is not suitable for a Windows .ini file.

See also

decrypt; set aspect datakey; General Procomm Plus Commands.


endcase

endcase

Concludes the case or default command within the switch command phrase, and transfers control to the line following the endswitch statement.

Example

See the example for switch.

Comments

Regardless of the number of case statements within a switch structure, there must be at least one endcase or the ASPECT Compiler will generate an error.

See also

case, default, exitswitch and switch; ASPECT Primary Commands.


enddialog

enddialog

Marks the end of a dialogbox statement group. For more information, see the dialogbox command.

Example

See the example for dialogbox.

See also

dialogbox; Dialog Box Commands.


endfor

endfor

Concludes the for statement group. At this point, the loop variable is increased or decreased, and execution jumps to the top of the for command block. The for conditions are tested to determine whether another loop iteration is required.

Example

See the example for for.

See also

exitfor, for and loopfor; ASPECT Primary Commands.


endfunc

endfunc

Terminates a function call block. See the func command for further information.

Example

See the example for func.

Comments

Similar to procedure call blocks, endfunc implies a return. However, since functions return values, at least one return statement is necessary within the function statement block. If the endfunc command is encountered before a return command is executed, the return value is undefined.

See also

func and return; ASPECT Primary Commands.


endgroup

endgroup

Concludes a radiogroup block within a dialogbox definition.

Example

See the example for radiogroup.

See also

radiogroup, radiobutton and dialogbox; Dialog Box Commands.


endif

endif

Concludes the if statement group.

Example

See the example for if .

See also

if; ASPECT Primary Commands.


endproc

endproc

Terminates a procedure block.

Example

See the example for proc.

Comments

endproc implies a return to the calling procedure. The return statement isn’t required. For more information, see the proc command.

See also

proc and return; ASPECT Primary Commands.


endswitch

endswitch

Terminates the switch statement group. For more information, see the switch command.

Example

See the example for switch.

See also

switch; ASPECT Primary Commands.


endwhile

endwhile

Terminates the while statement group. Execution jumps to the associated while command, where the condition is tested to determine whether another loop iteration is required. For further information, see the while command.

Example

See the example for while.

See also

exitwhile, loopwhile and while; ASPECT Primary Commands.


errormsg

errormsg string | {formatstr arglist}

Displays an error message dialog box with an exclamation point graphic and accompanying text.

string	A string of up to 256 characters.

formatstr	A string of up to 256 characters; it may contain both text and format specifiers.

arglist	Up to 12 arguments may be specified for the formatstr to process. These arguments must appear in the order they were specified within the formatstr.

Example

proc main

string Fname               ; String to contain name of file.

Fname = "readme.txt"       ; Assign file name to variable and

                           ; try to open the file for READ.

   if not fopen 0 Fname READ

         ; If the fopen is unsuccessful display an error message.

      errormsg "Couldn't open file `"%s`"." Fname

   else

      fclose 0             ; Make sure that file is closed.

   endif

endproc

Comments

A default beep sound accompanies the message. While the dialog is displayed, the script suspends operation until the user clears the dialog by pressing <Enter>, <Esc> or the OK button.

See also

sdlgmsgbox, usermsg, termmsg and statmsg; General Procomm Plus Commands.


execute

execute filespec [SHARED]

Executes another ASPECT script. Control returns to the parent script upon completion.

filespec	Any valid script filename. If a path is not included, the current Aspect Path is used by default.

SHARED	Causes the executed script to inherit the parent script’s current ASPECT environment settings, rather than the default settings.

Example

proc main

string ScriptName               ; Script file to run.

   if sdlginput "Run Script" "Name:" ScriptName

      if isfile ScriptName

         usermsg "Executing Script"

         execute ScriptName     ; Execute the script file.

         usermsg "Returned from Script"

      else

         errormsg "Script doesn't exist!"

      endif

   endif

endproc

Comments

If an extension of .wax is specified, the source file is recompiled automatically if the compiled script doesn’t exist.

If the extension is omitted, execute will first search for a compiled script with the .wax extension. If found, execute will compare the file date and time stamp to the associated source file, if any. If the source file is newer, the script will be recompiled automatically. If a compiled script matching the filespec can’t be found, execute will attempt to compile a corresponding .was file.

If a .was file is specified, the ASPECT Compiler will always attempt compilation.

Only the predefined variables, S0-S9, I0-I9, L0-L9 and F0-F9 can be used to pass values to an executed script. User-defined variables are not accessible between scripts.

The execute command will fail if the specified filespec doesn’t exist or can’t be compiled.

The $SCRIPTMODE system variable can be tested to determine whether the currently executing script was spawned from another script. $SCRIPTMODE will be set to 1 if the script was executed. The $PARENTFILE system variable will contain the name of the script that will resume execution following the termination of the spawned script.

For more information, see Script Spawning and Chaining.

See also

chain; set aspect path; $PARENTFILE and $SCRIPTMODE; Script Control Commands.


exit

exit [integer]

Terminates the executing script file. If the current script was spawned, or is the child of another script, control returns to the parent script.

[integer]	An optional code returned to the parent script if the current script was spawned. The value can be read from the system variable $EXITCODE.

Example

proc main

   usermsg "This example shows how to use the EXIT command."

   ; Stop and return value to parent script. Return

   ; value may be read with $EXITCODE system variable.

   exit 42

endproc

Comments

ASPECT is an excellent housekeeper, "tidying up" when a script terminates. However, a script should follow good programming practices, closing files and releasing memory and DLLs allocated by the script.

See also

halt and pwexit; $EXITCODE, $PARENTFILE and $SCRIPTMODE; Script Control Commands.


exitfor

exitfor

Continues execution with the command following an endfor command. For more information, see the for command.

Example

proc main

   integer Num             ; Integer variable to increment.

   for Num = 0 upto 40     ; Init variable and define loop.

      if Num == 20         ; Check to see if value of variable is

         exitfor           ; equal to 20.

      endif                ; If so, exit the FOR loop.

   endfor

   usermsg "%d" Num        ; Display value of variable.

endproc

See also

endfor, loopfor and for; ASPECT Primary Commands.


exitswitch

exitswitch

Transfers control from within a case or default statement group to the line following the endswitch command. exitswitch is similar to the "C" language break command.

Comments

An exitswitch may only occur within a case/default block.

If an exitswitch command is executed, then all commands between the exitswitch and endcase will not be processed.

Example

proc main

   integer Key                   ; Key value.

   set aspect keys ON            ; Script processes key presses.

   while 1                       ; Loop forever.

      if $KEYHIT                 ; Check for keys in buffer.

         keyget Key              ; Get key from buffer.

         switch Key              ; Evaluate the key.

            default

               keytoansi Key Key ; Convert to ANSI key value

               if Key == 0       ; Make sure key is valid.

                  exitswitch     ; Exit the switch case.

               endif

               computc Key       ; Transmit the key value.

            endcase

         endswitch

      endif

   endwhile

   set aspect keys OFF           ; PW4 handles key presses.

endproc

See also

default, switch and case; ASPECT Primary Commands.


exitwhile

exitwhile

Terminates a while command block and continues execution with the command following the endwhile.

Example

proc main

   integer Loops = 0       ; Integer used to count loops.

   while 1                 ; Loop forever, or until EXITWHILE.

      if (Loops++) == 3    ; Increment loop counter and check

         exitwhile         ; to see if it's == three. If

      endif                ; so, exit the WHILE loop.

   endwhile

endproc

See also

endwhile, while and loopwhile; ASPECT Primary Commands.


exitwindows

exitwindows LOGOFF | REBOOT | SHUTDOWN

Terminates all executing tasks and exits Windows with the specified action.

REBOOT	Causes the computer to perform a cold boot on exiting Windows.

SHUTDOWN	Causes the computer to shutdown on exiting Windows.

LOGOFF 	Logs the user off, shuts down all applications except Procomm Plus and displays the logon dialog.

Comments

SUCCESS and FAILURE are set to indicate whether all tasks actually terminated. Only testing for FAILURE is relevant.

Under Windows 95, exitwindows logoff will shut down all applications running at the same "level" as Procomm Plus, but Procomm Plus will not be shut down. Upon successful completion of this command, you can issue a pwexit to shut down Procomm Plus. Under Windows NT, Procomm Plus will also shut down. In either case, the logon dialog box is displayed.

See also

taskactivate, taskexists, taskexit, taskname and taskwin; General Windows Commands.


faxcancel

faxcancel index | string | CURRENT

Cancels the current fax operation.

index	The option set index of a fax connection as listed in the Current Fax Connection list.

string	The name of the fax modem in the Current Fax Connection list.

CURRENT	The current modem/connection selected in Setup.

Example

See the example for faxsend.

Comments

faxcancel only affects a fax dialing attempt. The dialcancel command can be used to cancel a data or voice dialing attempt.

See also

dialcancel and faxsend; Fax Commands.


faxlist

faxlist RECEIVED | SCHEDULED index strvar [intvar]

Enumerates the faxes displayed in the received or scheduled fax lists.

RECEIVED	If specified, the list of received faxes will be processed.

SCHEDULED	If specified, the list of scheduled faxes will be processed.

index	A zero-based index, specifying the fax list entry to process.

strvar	If the RECEIVED fax list is being processed, strvar will contain the name and extension, .fax or .bft, of the specified fax file. This file will always reside in the received fax directory, as specified in Setup.

If the SCHEDULED fax list is being processed, and the scheduled fax is comprised of a single file, the name and extension, .fax or .bft, of the fax file will be returned. If the scheduled fax was comprised of more than one file, the string returned will be "<<multiple>>". If the scheduled fax was comprised only of a cover sheet, the string returned will be "<<coversheet>>". If the scheduled fax was a fax polling operation, the string returned will be "<<remote poll>>".

intvar	If RECEIVED faxes are being processed, intvar will contain either a 0, new .fax or .bft, 1, viewing was last action on a .fax file, 2, printing was last action on a .fax file, or 3, .bft file has had its contents extracted and saved.

If SCHEDULED faxes are being processed, intvar will contain the number of attempts made to send the fax successfully.

Example

See the example for faxremove.

See also

faxview and faxremove; Fax Commands.


faxmodem

faxmodem index | string [intvar]

Determines if a modem is fax capable.

index	The index number of the modem in the modem table.

string	The name of the modem in the modem table.

intvar	An integer variable that returns 1 or 0 (zero) if the modem is or is not fax capable.

Example

proc main

   integer count=0, Capable, NumModems, countloop

   ; returns the zero-based index of the first fax capable modem

   itemcount MODEM CONNECTION NumModems   ; find out how many modems there are

   NumModems=NumModems-1

   for countloop=0 upto NumModems ;set up a loop

      if faxmodem count capable

         usermsg "Modem %d is fax capable." count

         exitfor

      else

         count++

         if count==NumModems

            usermsg "No fax modems found."

         endif

      endif

   endfor

endproc

See Also

Fax Commands.


faxpoll

faxpoll {DIALDIR [GROUP]} | {index | string | CURRENT | FIRST} string [timeval]

Dials a Connection Directory entry or group, or a specified number, to receive faxes from a host.

DIALDIR	An optional keyword, indicating that the string argument is the name of a Connection Directory entry or group, if GROUP is also specified.

GROUP	An optional keyword, indicating that the argument string contains a group name, rather than an entry name, to dial.

index	The option set index of a fax connection as listed in the Current Fax Connection list.

string	The name of the fax modem in the Current Fax Connection list.

CURRENT	The current modem/connection selected in Setup.

FIRST	The first available fax connection.

string	If DIALDIR is not specified, the string contains a fax number to be dialed. If DIALDIR is specified, the string contains the name of a Connection Directory entry, or a Connection Directory group if DIALDIR GROUP is specified.

timeval	A long value of type timeval, specifying the scheduled date and time for the polling to be performed. If the time specified by timeval has already past, the polling operation will be performed immediately, just as though no scheduled time had been specified.

Example

proc main

   ; Call the Connection Directory

   ; Entry "Procomm Plus" and poll for faxes.

   faxpoll DIALDIR "Procomm Plus"

endproc

Comments

The group or entry names must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find either an entry or group name based on a partial name.

$FAXSTATUS behaves differently when a faxpoll command is executed. $FAXSTATUS will be set to 1 (Busy, sending), when a faxpoll command is being executed, but $FAXFILE will return null, since no file is being sent. $FAXSTATUS can then change from 1 to 2 (Busy, receiving), at which time $FAXFILE has the name of the file being received.

See also

faxsend; Fax Commands.


faxprint

faxprint filespec

Prints a specified fax file.

filespec	The name of the fax file to print.

Example

proc main

   string Fname                  ; Name of fax file to print.

   if sdlgfopen "Fax Print" "C:\Program Files\Procomm Plus\Fax Inbox\*.fax" SINGLE Fname

      if not nullstr Fname       ; Make sure file was chosen.

         faxprint Fname          ; Print the fax file selected.

      endif

   endif

endproc

Comments

faxprint will only accept .fax files, and the extension must be specified. If a fully-qualified path is not specified, the Received fax directory is assumed.

Any file type other than .fax will cause faxprint to fail. However, SUCCESS and FAILURE are not set by faxprint.

See also

faxlist, faxview; Fax Commands.


faxremove

faxremove RECEIVED | SCHEDULED index

Removes a fax from the received or scheduled fax list, returning FAILURE if the specified fax could not be removed.

RECEIVED	The target fax file is in the received fax list.

SCHEDULED	The target fax file is in the scheduled fax list.

index	A zero-based list index, corresponding to an entry in the Received or Scheduled Faxes list. If index is specified as -1, all entries will be removed from the targeted list.

Example

proc main

   string SchFaxName             ; Name of scheduled fax.

   string PromptName             ; used in MsgBox

   integer TriesMade             ; Number of tries made to send

   integer Decision              ; User's response

   if faxlist SCHEDULED 0 SchFaxName TriesMade

      strfmt PromptName "FAX [%s] has been attempted [%d] times." \

         SchFaxName TriesMade

      sdlgmsgbox "Delete Fax?" PromptName STOP YESNO Decision 2

      if (Decision == 6)         ; User said yes!

         faxremove SCHEDULED 0   ; So do it!

      endif

   endif

endproc

See also

faxlist, faxsend and faxcancel; Fax Commands.


faxsend

faxsend {index | string | CURRENT | FIRST string string} | {DIALDIR [GROUP] string}
[COVERSHEET filespec | NONE] [NOTES string] [timeval]
[SINGLE | MULTIPLE filespec [BINARY]] [MEMO filespec]

Dials the specified number, Connection Directory entry or group, and transmits a specified fax file.

index	The option set index of a fax connection as listed in the Current Fax Connection list.

string	The name of the fax modem in the Current Fax Connection list.

CURRENT	The current modem/connection selected in Setup.

FIRST	The first available fax connection.

string	The information to insert in the "To:" field of the transmitted fax.

string	The fax number to dial, in order to send the fax.

DIALDIR string	The name of the Connection Directory entry to dial in order to send the fax. The group or entry name must match exactly the information contained in the associated Connection Directory field, including upper- or lower-case. The dialfind command can be used to find either an entry or group name based on a partial name.

GROUP	An optional keyword, indicating that the argument string contains a group name, rather than an entry name to dial.

COVERSHEET  filespec	If specified, the name of a cover sheet file to be used in the fax transmittal. If a path is not included in the filespec, the cover sheet path in Setup is assumed. If a cover sheet is not specified, the default cover sheet will be used in the fax transmittal. To send a fax without using any cover sheet, use the NONE keyword.
NONE	If specified, the fax will be sent without a cover sheet.

NOTES string	If specified, string will be used in the "Notes" field of the cover sheet. If a cover sheet is not sent with the fax, or the specified cover sheet does not contain a "Notes" field, or the "Notes" field is too small to contain the complete specified string, string will be ignored.

timeval	A long value of type timeval, specifying the scheduled date and time for the fax to be sent. If the current time is already past the time specified by timeval, then the operation will be performed immediately, just as though no scheduled time had been provided.

SINGLE filespec	Filespec is a single file to transmit. If a path is not included in the filespec, the Scheduled Faxes path defined in Setup, Fax Paths is assumed.

MULTIPLE  filespec	Filespec is a file containing one or more filenames to transmit by fax. Each filename should appear on a single line within the selection file. If a path is not included in filespec, the User Path is assumed. However, for filenames within the list of files, the Scheduled Faxes path in Setup, Fax Paths is assumed if no path is specified.
BINARY	If specified, the specified file(s) will be sent as a Binary File Transfer, and will not print as faxes on the receiving side.

MEMO filespec	The ASCII text file specified by filespec will be treated as a memo fax. If a path is not included in filespec, the User Path is assumed.

Example

proc main

   string FileName               ; Fax file to send.

   when USEREXIT call CleanUp    ; Watch for a disconnection.

   if sdlgfopen "Fax Send" "c:\program files\procomm plus\faxsend\*.fax" SINGLE FileName

      if not nullstr FileName    ; Make sure something was selected.

         faxsend FIRST "Symantec" "(123) 555-4321" SINGLE FileName

         while $FAXSTATUS        ; Loop while fax in progress.

            yield                ; Release processing time

         endwhile

      endif

   endif

endproc

proc CleanUp

   faxcancel CURRENT            ; Cancel the fax send if user

                                ; tries to exit script.

endproc

Comments

Under ASPECT, fax transmissions are asynchronous operations, meaning that they can run independently of script execution. A faxsend command only initiates a fax attempt. While the fax is processing, ASPECT executes the next commands in the script. If the script needs to wait for the fax attempt to complete, a while loop should be used to "stall" the script.

If the script executes a while loop to monitor the status of an on-going file transfer, you may find it useful to include the yield command within the loop. The yield command causes ASPECT to release its processing time to the system.

See also

faxpoll, faxlist and faxcancel; Fax Commands.


faxstatus

faxstatus index | string | CURRENT intvar [strvar [strvar [strvar]]]

Queries the status of a specific fax connection.

index	The option set index of a fax connection as listed in the Current Fax Connection list.

string	The name of the fax modem in the Current Fax Connection list.

CURRENT	The current modem/connection selected in Setup.

intvar	An integer which stores the current value of $FAXSTATUS.

strvar	An optional string variable which receives the name of the file being sent or received. The string will be set to null if no fax transaction is in progress for the given connection index.

strvar	An optional string variable which receives the last message associated with the current fax transaction on the specified fax connection.

strvar	An optional string variable which receives the station ID of the location to which the fax is being sent. The string will be set to null if no fax transaction is in progress for the given connection index.

Example

proc main

   string FileName, FaxFile

   integer Status

   while 1

      faxstatus CURRENT Status FileName

      strfmt FaxFile "The current fax modem is sending %s." FileName

      if Status == 0

         strfmt FaxFile "The current fax modem is idle."

      endif

      statmsg FaxFile

   endwhile

endproc

See Also

faxmodem, faxsend, faxpoll, faxcancel, $faxstatus; Fax Commands.


faxview

faxview filespec

Displays a fax file.

filespec	The name of the fax file to view.

Example

proc main

   string Fname               ; Name of fax file to view.

   if sdlgfopen "Fax View" "C:\Program Files\Procomm Plus\Fax Inbox\*.FAX" SINGLE Fname

      if not nullstr Fname    ; Make sure file was chosen.

         faxview Fname

      endif

   endif

endproc

Comments

faxview will only accept .fax files, and the extension must be specified. If a fully-qualified path is not specified, the Received fax path in Setup, Fax, Fax Paths is assumed.

Any file type other than .fax will cause faxview to fail, but faxview does not set SUCCESS and FAILURE.

See also

faxlist and faxprint; Fax Commands.


fclear

fclear id

Clears all end-of-file and error flags associated with the indicated file id.

Example

proc main

   string Fname = "file.chk"         ; Name of file to be opened.

   string LineString                 ; Line read from file.

   if fopen 0 Fname READ             ; Open file for read only.

      fseek 0 0 2                    ; Seek to the end of file.

      while not feof 0               ; Loop while not end of file.

         fgets 0 LineString          ; Read line from file.

      endwhile

      fclear 0                       ; Clear end of file error.

      if not feof 0                  ; Display message if EOF cleared.

         usermsg "End-Of-File Cleared!"

      endif

      fclose 0                       ; Close the file.

   else

      errormsg "Couldn't open `"%s`" for input." Fname

   endif

endproc

See also

fopen, feof and ferror; File I/O Commands.


fclose

fclose id

Closes the file corresponding to the indicated file id.

Example

proc main

   string Fname = "file.txt"          ; Name of file to be opened.

   if fopen 0 Fname CREATE            ; Open and create specified file.

      fputs 0 "This is some text!"    ; Write some text to the file.

      fclose 0                        ; Close file opened for create.

   else

      errormsg "Couldn't open file `"%s`"." Fname

   endif

endproc

Comments

The I/O buffer contents for a file will automatically be written before it is closed if it was opened in WRITE, READWRITE or CREATE mode. fclose can be tested with the if SUCCESS statement, returning false if an error occurred while closing the file.

See also

fopen and fflush; File I/O Commands.


fcombobox

fcombobox id left top width height

SIMPLE | DROPDOWN | DROPDOWNLIST
filespec [OFFSET fileoffset [LENGTH filelength]] strvar
[strlength] [SORT]

Adds a combination edit/selection or "drop-down" selection control to an ASPECT dialog box.

id	A unique integer constant value assigned to the fcombobox. When a selection is made from the list, this value will be reported by dlgevent.

left top  width height	These integer constants determine the position and size of the fcombobox control in Dialog Box Units or DBUs, relative to the dialog box’s dimensions. For more information on DBUs, see Dialog Box Units.
SIMPLE	The list box is displayed at all times. The current selection in the list box is displayed in the edit control.

DROPDOWN	The current selection is displayed in the edit control, but the list box is not displayed unless the user selects the down arrow button next to the edit control.

DROPDOWNLIST	Similar to the DROPDOWN type, but the edit control is replaced by a static text item that displays the current selection in the list box.

filespec	The file containing the items to be displayed. Each item must occur as a separate line in the file. Filespec may include a drive and path. If no path is specified, the Aspect Path is assumed.

OFFSET fileoffset	An optional offset within the file where the list to be displayed begins. A long variable, or a constant.

LENGTH filelength	If filelength is specified, only the allowed number of bytes will be displayed. A long variable, or a constant.

strvar	Contains a single list selection. strvar can be pre-initialized with an item, allowing it to already be selected upon entry.

strlength	If specified, defines the maximum number of characters which can be entered in the edit control. This parameter is not valid with the DROPDOWNLIST style. An integer variable or constant.

SORT	If specified, the contents of the fcombobox will be sorted lexigraphically in ascending order.

Example

proc main

   string NewItem               ; Item selected from list.

   integer Event                ; Dialog box event.

   ; Define and display dialog. For this example, you'll need

   ; a text file called "food.lst" containing a list of

   ; items (one per line).

   dialogbox 0 20 187 100 50 11 "File Combo Box Example"

      fcombobox 1 5 5 90 40 dropdownlist "food.lst" NewItem

      pushbutton 2 29 25 40 14 "&OK" ok default

   enddialog

   while 1

      dlgevent 0 Event          ; Get dialog event.

      switch Event              ; Evaluate the event.

         case 0                 ; No event occurred.

         endcase

         case 1                 ; Check box item selected.

            usermsg "`"%s`" selected!" NewItem

         endcase

         default                ; Exit method selected.

            exitwhile           ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL          ; Destroy the dialog box.

endproc

Comments

Like combobox, this command allows a user to make a single selection from a list. With fcombobox, however, the list of items is taken from a disk file. fcombobox can only occur within a dialogbox group.

If the fcombobox contains an edit field, and the user types information into the field, a dialog event will be generated when the fcombobox loses the input focus.

See also

combobox, dialogbox, dlgsave, dlgupdate, dlgevent, flistbox and listbox; Dialog Box Commands.


fdelblock

fdelblock id integer

Deletes a block of data from the specified file.

id	The target file index.

integer	The size in bytes to be deleted from the target file.

Example

#define _RECSIZE 128                  ; Define the record size.

proc main

   ; Imagine that USER.REC is a file containing records with

   ; a fixed size of 128 bytes.

   if fopen 0 "user.rec" READWRITE    ; Open the user file for read/write.

      fseek 0 (4 * _RECSIZE) 0        ; Seek to fourth record in file.

      fdelblock 0 _RECSIZE            ; Delete the record from the  file.

      fclose 0                        ; Close the user file.

   else

      errormsg "User file not found!"

   endif

endproc

Comments

fdelblock begins deleting data at the current position of the file pointer. The file must be opened with either the READWRITE or CREATE parameters or fdelblock will return FAILURE. If the amount specified is greater than the data remaining in the file, fdelblock will return FAILURE. Use ftell and flength to determine pointer position and filesize.

See also

flength, finsblock, fseek, fstrfmt, ftell, fwrite, ftruncate, fflush and rewind; File I/O Commands.


feditbox

feditbox id left top width height filespec [HSCROLL]

Adds a text editing box displaying the contents of a disk file in an ASPECT dialog box.

id	A unique integer constant value assigned to the feditbox by the script. When the contents of the feditbox are changed and the control loses input focus, this value will be reported by dlgevent.

left top  width height	These integer constants determine the position and size of the feditbox control in Dialog Box Units or DBUs, relative to the dialog box. For more information on DBUs, see Dialog Box Units.
filespec	A string variable or constant containing the name of the file to edit. If a path is not specified, the Aspect Path is assumed.

HSCROLL	An optional parameter allowing horizontal scrolling instead of line "wrapping" at the right margin of the text edit box.

Example

proc main

   integer Event              ; Dialog box event.

   ; Define and display dialog with

   ; File Edit Box and a save button.

   dialogbox 0 0 0 100 50 11 "File Edit Box Example"

   feditbox 1 5 2 90 30 "message.txt"

      pushbutton 2 25 35 50 15 "&Save"

   enddialog

   while 1

      dlgevent 0 Event        ; Read dialog event.

      switch Event            ; Evaluate dialog event.

         case 0               ; No event occurred.

         endcase

         case 1               ; Fedit box was changed.

         endcase

         default              ; Exit event selected.

            if Event == 2     ; See if save was selected.

               dlgsave 0 1    ; Save file edit box to file.

            endif

            exitwhile         ; Exit the loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL        ; Destroy dialog box.

endproc

Comments

If the specified text file doesn’t exist when the feditbox command is executed, it’s created automatically. The feditbox contents are not saved until the dialog box is exited with an OK status. The contents will not be saved if the dialog is terminated with a Cancel.

feditbox supports a maximum file size of 64K for editing, but the actual allowable file size may be less depending on available resources. An error beep will sound whenever a file cannot be loaded or saved. Standard Windows cursor and editing controls are available within an feditbox control.

feditbox can only occur within a dialogbox group.

See also

dialogbox, disable, dlgevent, dlgsave, dlgupdate, editbox, enable, ftext and text; Dialog Box Commands.


feof

feof id [intvar]

Tests for end-of-file condition on the specified file index id.

id	The file id to test.

intvar	If specified, will be set to the result of the test; 0 for false and 1 for true.

Example

proc main

   string Fname = "file.wrk"   ; Name of file to read.

   string FInput               ; Text to read from file.

   if fopen 0 Fname READ       ; Open file for read only.

      while not feof 0         ; Loop while not end of file.

         fgets 0 FInput        ; Read a Chimp from file.

         usermsg FInput        ; Display Chimp to user.

      endwhile

      fclose 0                 ; Close the file.

   else

      errormsg "Can't open `"%s`" for input." Fname

   endif

endproc

Comments

When reading from a file, feof will not return true until an attempt has been made to read past the end of file. Reading just the last character of a file does not set end of file. End of file is generally never set when writing to a file.

See also

fclear, fclose, ferror, fopen, fseek and rewind; File I/O Commands.


ferror

ferror id [intvar]

Tests for any error condition on the specified file index.

id	The file index id to test.

intvar	If specified, will be set to 0 if no error is detected. If an error is detected, intvar will be set to 1.

Example

proc main

   string Fname = "write.txt"      ; Name of file to be opened.

   string LineInfo                 ; Line from file.

   integer Error                   ; Error created by read below.

   if fopen 0 Fname WRITE          ; Open file for write only.

      fgets 0 LineInfo             ; Read from file to generate error.

      ferror 0 Error               ; Get last error concerning file I/O.

      if Error                     ; If there was an error, display

         errormsg "Error!"         ; error message.

      endif

   else

      errormsg "Couldn't open `"%s`" for output." Fname

   endif

endproc

See also

fclear, fclose, feof, fopen, fseek and rewind; File I/O Commands.


fetch

fetch param datavar

Returns the current value(s) of any set command parameter.

param	The desired set command parameter.

datavar	The current value of the specified set command parameter(s). Note that this value must be returned to the proper data type. The variable may be in intvar, strvar or longvar format, depending on the desired set command. The definitions for the set commands include all possible values for each command parameter - see Set and Fetch Statements.

Example

proc main

   string AreaCodeID, EntryNumber

               ;Area code and phone number for the entry.

      ; Set the Dialing Directory entry and return the settings.

      set dialentry access 1 "Symantec"  ;Set dialentry to DATA

      fetch dialentry areacode AreaCodeID     ;Retrieve the area code

      fetch dialentry phonenumber EntryNumber ;Retrieve the phone number

      usermsg "(%s)%s" AreaCodeId EntryNumber

endproc

Comments

ASPECT provides a set/fetch command for every item that can be changed in Procomm Plus Setup, except for items affecting individual window colors and terminal attributes. Note that changes made to the current Setup values will not be saved to disk until the setup save command is issued, or until the user explicitly saves the current settings through the user interface.

Although most fetch commands will always succeed, all fetch commands update the SUCCESS and FAILURE system variables based upon the results of the command. Certain fetch commands may fail if the information given to the command is invalid.

If a fetch command returns an integer value, its corresponding set command will accept either an integer or a keyword. This integer value is checked at run-time, but users should employ the keyword form when setting a value not previously fetched.

The set/fetch commands are organized into groups that correspond to the parameters they affect. In addition, each protocol and each terminal emulation has its own set/fetch group. However, some of these options represent advanced settings which are not available for all emulation or protocols. For more information, see Set and Fetch Statements.

Commands without one of these group identifiers affect the overall operation of Procomm Plus. In general, the fetched value for parameters with OFF | ON syntax is 0 for OFF, 1 for ON. For parameters with NO | YES syntax, fetched values are typically 0 for NO, 1 for YES.

If you’ve set dialentry access to a specific Connection Directory entry, fetch will retrieve values from that entry instead of the current Procomm Plus Setup file. Only certain set/fetch commands have this dual functionality.

See also

setup and set; General Procomm Plus Commands.


fflush

fflush id

Writes the current I/O buffer contents to the specified file id.

id	The file id to be flushed.

Example

proc main

   string Fname = "file.txt"     ; Name of file to be opened.

   integer Count = 0             ; Counts number of loops.

   when USEREXIT call Done       ; Set event for script exit.

   if fopen 0 Fname CREATE       ; Create and open file.

      while Count < 10000        ; Loop 10000 times.

         fstrfmt 0 "%d" Count    ; Write count to our file.

      endwhile

      fclose 0                   ; Close the file.

   else

      errormsg "Can't open `"%s`" for output." Fname

   endif

endproc

proc Done

   fflush 0                      ; Make sure that everything's

   fclose 0                      ; written to file before

   exit                          ; closing it and exiting.

endproc

Comments

If the file was opened in READ mode, the buffer contents are cleared. In CREATE, WRITE or READWRITE mode, buffers are automatically flushed when they’re full or when the file is closed.

This command can be tested with the if SUCCESS statement, returning false if an error occurred while writing the buffer contents to the file.

See also

fclose, fclear and fopen; File I/O Commands.


fgetc

fgetc id intvar

Reads a character from the specified file id into a variable.

id	The file id to access.

intvar	Will be set to a character value if fgetc was successful; -1 otherwise.

Example

proc main

   string Fname = "file.cap"      ; Name of file to be opened.

   string FName2                  ; Name of file.

   string FExt                    ; Extension of file.

   string FDir                    ; Directory of file.

   string FDrive                  ; Drive of directory in file name.

   integer Chr                    ; Character to get from input file.

   ; Extract each component of the file name and append

   ; to the actual name of file ".hex" extension.

   splitpath Fname FDrive FDir FName2 FExt

   strcat FName2 ".hex"           ; Append extension for output file.

   if fopen 0 Fname READ          ; Open input file for read.

      if fopen 1 FName2 CREATE    ; Create output file.

         while not feof 0         ; Loop while not at end of file.

            fgetc 0 Chr           ; Get character from input file

                                  ; and convert it to hex, and

                                  ; put it in the output file.

            fstrfmt 1 "%02X " Chr

         endwhile

         fclose 1                 ; Close our output file.

      else

         errormsg "Couldn't open `"%s`" for output." FName2

      endif

      fclose 0                    ; Close our input file.

   else

      errormsg "Couldn't open `"%s`" for input." Fname

   endif

endproc

Comments

To make sure that a character is available, first check the file status using the feof command. Since a character contains a single byte, the file pointer will be incremented by 1 after performing fgetc.

See also

fgets, fopen, fputc, feof and fread; File I/O Commands.


fgets

fgets id strvar

Reads a string from the file corresponding to a given id into a variable.

id	The file id to access.

strvar	The string receiving the data.

Example

proc main

   string FName                    ; Name of file to read.

   string LineInfo                 ; Line from file.

   if sdlginput "File Name" "Name:" FName

      if isfile FName              ; Make sure file exists.

         if fopen 0 FName READ     ; Open file for read.

            while not feof 0       ; Loop to end of file.

               fgets 0 LineInfo    ; Get line from file.

               termwrites LineInfo

            endwhile

            fclose 0               ; Close the file.

         endif

      else

         errormsg "File doesn't exist."

      endif

   endif

endproc

Comments

Reading will terminate when fgets encounters a line feed character, the end-of-file or when 256 characters have been read.

The string will include the ending line feed if the file wasn’t opened with the optional TEXT parameter. The feof command can test the file before reading it, and the if SUCCESS statement will return false if an error occurred while reading the file.

See also

fgetc, fputs, feof, fread and fopen; File I/O Commands.


fileget

fileget filespec {ATTRIBUTE | DATE | TIME strvar} |

{LTIME | SIZE longvar}

Reports date, time, attributes or size for a given filespec.

filespec	The desired file.

ATTRIBUTE strvar	strvar will contain the attributes of the specified file.

DATE strvar	strvar will contain a date string reflecting the specified file’s last update.

TIME strvar	strvar will contain a time string reflecting the specified file’s last update.

LTIME longvar	longvar will contain a timeval, which can be converted to time/date string(s) using ltimestrs or ltimestring.

SIZE longvar	Will contain the size in bytes of the specified file.

Example

proc main

   string Fname = "c:\io.sys"    ; Name of file to examine.

   string Attr                   ; Attributes for the file.

   ; Get and display the attributes for the file above.

   fileget Fname ATTRIBUTE Attr

   usermsg "`"%s`" attributes are `"%s`"." Fname Attr

endproc

Comment

If no path is specified, the current User Path will be used. Wildcards are not allowed. fileget reports FAILURE if the file could not be found.

When getting attributes with the fileget command, the attribute string may consist of the following characters representing attribute types: ’N’ for normal, ’R’ for read-only, ’H’ for hidden, ’S’ for system, and ’A’ for archive.

fileget SIZE should not be used to get the size of a file that is currently opened with WRITE or CREATE access! The flength command should be used in this case, since it accounts for data which may not have been written to disk when the command is executed.

See also

fileset, findfirst, findnext, ltimestring and ltimestrs; DOS- or Disk-Related Commands.


fileset

fileset filespec {ATTRIBUTE | DATE | TIME string} |

{LTIME | SIZE long}

Sets date, time, attributes and size for a given filespec.

filespec	The target filename.

ATTRIBUTE string	Will set the target file’s attributes to the given value(s).

DATE string	Will set the target file’s date stamp to the given value.

TIME string	Will set the target file’s time stamp to the given value.

LTIME long	Will set the target file’s TIMEVAL to the given value.

SIZE long	Will set the target file’s size to the given value, truncating the file if applicable.

Example

proc main

   string Fname = "hide.me" ; Name of file to hide.

   string Attr                ; Attributes of the file.

   ; Set hidden attribute for file, get attributes

   ; of file, and display them.

   fileset Fname ATTRIBUTE "h"

   fileget Fname ATTRIBUTE Attr

   usermsg "`"%s`" attributes are `"%s`"." Fname Attr

endproc

Comment

If no path is specified, the current User Path will be used. Wildcards are not allowed. fileset returns FAILURE if the file could not be found, or if the requested action could not be performed.

When setting attributes with the fileset command, the attribute string may consist of the following characters representing attribute types: ’N’ for normal, ’R’ for read-only, ’H’ for hidden, ’S’ for system, and ’A’ for archive. A null string will unset all attributes for the target file. The normal attribute is valid only when no other attributes are specified.

This command will set FAILURE if an invalid date string and/or time string is used as an argument to the command.

The time and date strings must reflect valid DOS times and dates. File times work with a 2 second resolution. As a result, the file may actually show a time of one second less than what you set with fileset.

See also

fileget, findfirst, findnext and strsltime; DOS- or Disk-Related Commands.


filetoclip

filetoclip BITMAP | METAFILE | TEXT filespec

Retrieves the contents of a file and places the data in the clipboard.

BITMAP | METAFILE | TEXT	Specifies the filetype for the copy.

filespec	The file which will be copied to the clipboard. If no path is specified, the User Path is assumed.

Example

See the examples for pastetext and cliptofile.

Comments

Note that the input file must be of the proper type for the retrieval to be successful. Bitmaps usually carry the extension .bmp. Metafiles are usually identified with a .wmf extension, and these files must contain the placeable metafile format that is typical within Windows. Enhanced metafile format files, usually identified with a .emf extension, are also supported.

See also

strtoclip, cliptofile and pastetext; Clipboard Commands.


fileview

fileview filespec

Displays a file in a modal dialog box.

filespec	The file to display. If no path is supplied, ASPECT will search for the file in the User Path.

Example

proc main

   string Fname          ; String to contain file name.

   if dir "*.txt" Fname  ; Prompt user for a file name.

      fileview Fname     ; If file chosen, display it.

   endif

endproc

Comments

fileview should only be used with ASCII text files.

See Also

DOS- or Disk-Related Commands.


findfirst

findfirst filespec [string]

Locates a disk file using a specification you provide.

filespec	The argument for the file search. Wildcard characters "?" and "*" are allowed, and a path may be included. findfirst defaults to the current User Path if a path isn’t provided.

string	An optional string specifying the attributes to be used for the search. If this string is omitted, only normal files with no attributes, or just a read-only and/or archive attribute set will be included. Specifying ’N’ for normal, ’R’ for read-only, ’H’ for hidden, ’S’ for system, ’A’ for archive, ’D’ for directory and ’V’ for volume will search those files as well as the normal files.

If the volume is being sought, and a volume label exists, it will always be found regardless of the filespec that was specified. If a volume label is found, the system variables $FILESPEC, $FILENAME and $FNAME will contain up to 11 characters of the volume name, and $FEXT will be set to null.

To search exclusively for files with specific attributes, the character ’X’ may be included. For example, the string "XD" would search only for directories.

Example

proc main

   string FileSpec = "*.was"        ; File specifications to look for.

   if findfirst FileSpec            ; Find first file matching spec.

      usermsg "There are scripts in this directory!"

   else

      errormsg "No scripts in this directory!"

   endif

endproc

Comments

The file’s fully-qualified filespec, name, extension, name and extension, size, date stamp, time stamp and attributes are stored in the system variables $FILESPEC, $FNAME, $FEXT, $FILENAME, $FSIZE, $FDATE, $FTIME and $FATTR respectively. The long value representing the file’s date and time is stored in $FLTIME.

See also

shortpath, fileget, fileset, findnext and strsltime; $FLTIME, $FSIZE, $FATTR, $FDATE, $FEXT, $FILENAME, $FNAME, $FTIME and $FILESPEC; DOS- or Disk-Related Commands.


findnext

findnext

Locates additional disk files with the specification provided in a previously-executed findfirst command.

Example

proc main

   string FileSpec = "*.*"       ; File specifications to look for.

   string Files[20]              ; Array to hold file names.

   integer Idx = 0               ; Index within file list array.

   if findfirst FileSpec         ; Find first file matching spec.

      Files[Idx] = $FILENAME     ; Set element of array to file name.

      Idx += 1                   ; Increment the array pointer.

      while findnext             ; Loop while still finding files.

         Files[Idx] = $FILENAME  ; Set element of array to file name.

         Idx += 1                ; Increment the array pointer.

         if Idx > 19             ; Exit loop if past size of array.

            exitwhile

         endif

      endwhile

   else

      errormsg "No files found!"

   endif

endproc

Comments

The file specification for this command is taken from the previously-used findfirst command. if SUCCESS can be used to test the result of the operation.

As with findfirst, the file’s fully-qualified filespec, name, extension, name and extension, size, date stamp, time stamp and attributes are stored in the system variables $FILESPEC, $FNAME, $FEXT, $FILENAME, $FSIZE, $FDATE, $FTIME and $FATTR respectively. The long value representing the file’s date and time stamp of the file is stored in $FLTIME.

See also

fileget, fileset, findfirst and strsltime; $FLTIME, $FSIZE, $FATTR, $FDATE, $FEXT, $FILENAME, $FNAME, $FTIME and $FILESPEC; DOS- or Disk-Related Commands.


finsblock

finsblock id integer

Inserts a block of space into the specified file id at the current position in the file.

id	The id of the target file.

integer	The size of block to insert.

Example

#define _RECSIZE 128                ; Define the record size.

proc main

   ; Imagine that USER.REC is a file containing records with

   ; a fixed size of 128 bytes.

   if fopen 0 "user.rec" READWRITE  ; Open the user file.

      fseek 0 (4 * _RECSIZE) 0      ; Seek to fourth record in file.

      finsblock 0 _RECSIZE          ; Insert a record into the file.

      fclose 0                      ; Close the user file.

   else

      errormsg "User file not found!"

   endif

endproc

Comments

The file must be opened with either the READWRITE or CREATE parameters or finsblock will return FAILURE. The current file position remains unchanged after inserting the block. thus, new data can be written directly following finsblock. Use if SUCCESS to confirm that the block was inserted before attempting to write to the file, however.

See also

fdelblock; File I/O Commands.


firsttask

firsttask intvar

Returns the first task encountered in the Windows Task List.

intvar	The task id.

Example

proc main

   integer TaskId                  ; Id returned by FirstTask, NextTask.

   string TName                    ; Name of task.

   firsttask TaskId                ; Get the id of first task.

   taskname TaskId TName           ; Get the name of task.

   termmsg "Task: %s`r`n" TName

   while nexttask TaskId           ; Loop while id is not zero.

      taskname TaskId TName        ; Get the name of task.

      termmsg "Task: %s`r`n" TName

   endwhile

endproc

Comments

ASPECT returns id’s only for those tasks that have a top-level window with a caption containing text. Certain special tasks running in Windows may not meet these requirements, and will not be returned. The ordering of tasks is not necessarily preserved between two firsttask commands.

See also

nexttask, taskactivate, taskexit, taskexists, taskname and taskwin; $TASK and $PWTASK; Task/Window Manipulation Commands.


flength

flength id longvar

Returns the file size of an open file.

id	The id of the target file.

longvar	Will contain the length of the target file in bytes.

Example

proc main

   long lSize                    ; Holds the size of our file.

   if fopen 0 "host.usr" READ    ; Open the host.usr file.

      flength 0 lSize            ; Get the size of the file.

      usermsg "`"host.usr`" is %ld bytes long!" lSize

      fclose 0                   ; Close the HOST.USR file.

   else

      errormsg "Couldn't open `"host.usr`" file!"

   endif

endproc

Comments

flength should be used to determine the length of a file which is currently opened with WRITE access, since it will account for data which has not yet been written to disk.

See Also

File I/O Commands.


flistbox

flistbox id left top width height filespec

[OFFSET fileoffset [LENGTH filelength]]

[tabstring] {SINGLE strvar} |
{MULTIPLE filespec} [HSCROLL] [SORT]

Adds a list box to an ASPECT dialog box. Like listbox, this command allows a user to select a single item or multiple items from a list. With flistbox, however, the list of items is taken from a disk file, allowing for a larger list than can be contained in a string.

id	A unique integer constant value assigned to the file list box. This value will be reported by dlgevent when the contents of the file list box are changed, or a selection is made.

left top width height	These integer constants determine the position and size of the flistbox control in Dialog Box Units or DBUs, relative to the dialog box. For more information on DBUs, see Dialog Box Units.

filespec	The file containing the items to be displayed. Each item must occur as a separate line in the file. The filespec may include a drive and path. If no path is specified, the Aspect Path is assumed.

OFFSET fileoffset	An optional offset within the file where the list to be displayed begins. A long variable, or a constant.

LENGTH filelength	If length is specified, only the number of bytes specified in filelength will be displayed. Filelength is a long variable, or a constant.

tabstring	An optional, comma-separated string variable containing numbers in dialog units indicating column locations for tabs contained within the file. If only one tab stop is specified, the file list box will be initialized with multiple stops separated by the single tab stop value. If more than one tab stop is given, then only those tab stops will be initialized.

SINGLE strvar	If specified, strvar contains a single list selection. strvar can be pre-initialized with an item, allowing that item to be pre-selected upon entry to the dialog.

MULTIPLE filespec	Filespec is a string containing the name of the file to be created with the multiple selections chosen from the displayed list. The file described by filespec can be pre-initialized with items, allowing them to be pre-selected upon entry to the dialog.

HSCROLL	If specified, the flistbox provides scroll bars to allow the user to scroll the list items horizontally. Horizontal scrolling is appropriate only for list entries which contain no tab characters.

SORT	If specified, the contents of the flistbox will be sorted alphabetically.

Example

proc main

   string ListItem              ; Item selected from list.

   integer Event                ; Dialog box event.

   ; Display dialog box with list of items. You need

   ; a file called "items.lst" that contains items

   ; to choose from (one on a line).

   dialogbox 0 0 0 100 50 11 "File List Box Example"

      flistbox 1 5 5 90 40 "items.lst" SINGLE ListItem

   enddialog

   while 1

      dlgevent 0 Event          ; Get the dialog event.

      switch Event              ; Evaluate the event.

         case 0                 ; No event occurred.

         endcase

         case 1                 ; Something was chosen.

            usermsg "`"%s`" selected!" ListItem

         endcase

         default                ; Exit case chosen.

            exitwhile           ; Exit the loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL          ; Destroy the dialog box.

endproc

Comments

flistbox allows multiple selections. Each selection is stored in the file specified by MULTIPLE filespec, with each selected item appearing on a separate line. flistbox can only occur within a dialogbox group.

See also

dialogbox, combobox, fcombobox, dlgupdate, listbox and dlgevent; Dialog Box Commands.


float

float name[=expression][,name[=expression]]...

Defines a global or local float variable, or an array of float variables.

name	The name of the new variable. This name must follow the standard ASPECT naming conventions. When defining an array, the subscript expression must evalutate to a constant value.

= expression	An initializer expression. It can specify operators, constants or previously-declared numeric variables, or a function which returns a numeric result. The initializing expression cannot be used when defining an array.

Example

proc main

   float Socks = 1.96            ; Price of the socks.

   float Shoes = 52.23           ; Price of the shoes.

   float Pants = 105.19          ; Price of the pants.

   float Jacket = 89.95          ; Price of the jacket.

   float Shirt = 19.50           ; Price of the shirt.

   float Tie = 5.15              ; Price of the tie.

   float Dollars                 ; Total Amount of Dollars.

   Dollars = Socks + Shoes + Pants + Jacket + Shirt + Tie

   usermsg "This outfit will cost %4.2f!" Dollars

endproc

Comments

Up to 256 global float variables can be defined, as well as 256 global float arrays. Local float definitions are limited by the available stack space at the time the procedure or function is called.

See User Defined Variables, Global and Local Variables and Arrays.

See also

integer, long , param and string; ASPECT Primary Commands.


floor

floor float numvar

Computes the largest integral value, with no fractional amount less than or equal to a floating point number.

float	A float variable or constant.

numvar	A numeric variable to receive the resulting value.

Example

proc main

   float Cost = 42.36               ; Cost of a product.

   integer CostRoundedDown          ; Cost of product rounded down.

   floor Cost CostRoundedDown       ; Round cost down to nearest int.

   usermsg "The cost is about %d..." CostRoundedDown

endproc

See also

ceil; Numeric, String Conversion Commands.


fopen

fopen id filespec READ | WRITE | READWRITE | CREATE |

APPEND | READAPPEND [TEXT] [SHARED]

Opens a file in the indicated mode and assigns it to a file id.

id	The file id to assign to the file. This value must be greater than or equal to zero.

filespec	A valid file specification. If no path is specified, the current User Path is assumed.

READ	Data can only be read from the file.

WRITE	Data can only be written to the file. If a file described by filespec does not exist, it is created.

READWRITE	Data can be read from, or written to the file. If a file described by filespec does not exist, it is created.

CREATE	Will create a new file. If a file described by filespec already exists, CREATE mode will erase its contents. After the file is CREATEd, the filemode assumes READWRITE mode.

APPEND	Data can only be written to the file. Additionally, writes can only be made at the end of the file. If the file specified in filespec does not already exist, APPEND mode will create the file.

READAPPEND	Will allow you to read anywhere within the file, but all writes will be made at the end of the file. If the file specified in filespec does not already exist, READAPPEND mode will create the file.

TEXT	Affects only the fgets and fputs commands. This optional parameter forces ASPECT to strip line feeds and carriage return/line feed combinations from the end of a string during an fgets operation, and forces ASPECT to append a carriage return/line feed combination to a string written with the fputs command. Additionally, if the last string read with an fgets command consists only of an EOF character, a null string is returned.

SHARED	Allows the opened file to be shared with child scripts. Child scripts, as long as they are aware of the file ID, can perform any file I/O operations on SHARED files without having to open the file. It is important to note, however, that any changes to the file or the file position are in effect when the parent script resumes control.

Example

proc main

   string Fname = "read.me"       ; File name to be opened.

   string LineBuffer              ; Line read from file.

   if fopen 0 Fname READ TEXT     ; Open file for read only.

      while not feof 0            ; Loop while not end of file.

         fgets 0 LineBuffer       ; Get line from file.

         termwrites LineBuffer    ; Display on terminal screen.

      endwhile

      fclose 0                    ; Close file opened for read.

   else

      errormsg "Couldn't open file `"%s`"." Fname

   endif

endproc

Comments

The file pointer position is always initially set at the start of the file, no matter what mode is used to open it. An unlimited number of files may be opened at once.

See also

fclose, fdelblock, finsblock, fflush, fputc, fputs, fseek, ftell, fread, feof, ferror, flength, fgets, fgetc, fstrfmt, ftruncate, rewind and fwrite; File I/O Commands.


for

for numvar[=expression] UPTO | DOWNTO number [BY number]

.

.

.

endfor

Repeats a command or series of commands a specific number of times.

numvar	The loop variable used as a counter. If an array element is specified, and the subscript expression contains a variable, changes to that variable within the for command block do not affect which loop variable is examined; the tested variable is determined when initialization is performed.

=expression	Optional initialization expression for the loop variable. Typically this is an assignment expression to initialize the variable.

UPTO | DOWNTO	Indicates whether the variable is to be increased (UPTO) or decreased (DOWNTO) after each iteration.

number	The boundary value for the loop counter. It is inclusive. For example, if UPTO is set to 25 and the counter variable is initialized to 1, the loop will be performed 25 times.

BY number	Determines the amount to be added to (UPTO) or subtracted from (DOWNTO) the target amount after each iteration. This value is typically a positive number, since a negative number in conjunction with the UPTO keyword will result in a step down from the initial value. A negative number in conjunction with the DOWNTO keyword will result in a step up from the initial value.

If BY number is not specified, the default step value is 1. Number must be a constant or simple variable, or an array variable with a constant sub-expression. It cannot be the result of a general expression involving more than 1 variable.

endfor	Required terminator for the for statement group.

Example

proc main

   integer Num                ; Integer variable to increment.

   for Num = 0 upto 100       ; Init variable and define loop.

      statmsg "Num = %d" Num  ; Display value of var on status line.

      mspause 250             ; Pause to allow display of value on

                              ; status line.

   endfor

endproc

Comments

The loopfor and exitfor commands allow branching to the next iteration test or command following the endfor.

See also

while, loopfor and exitfor; ASPECT Primary Commands.


fputc

fputc id character

Writes a character value to a file.

id	The target file id.

character	The character can be any ASCII value. fputc writes a single byte to the file.

Example

proc main

   string Fname = "File.txt"   ; Name of file to be opened.

   if fopen 0 Fname CREATE     ; Open and create specified file.

      fputc 0 'H'              ; Output some characters to our

      fputc 0 'e'              ; newly created file.

      fputc 0 'l'

      fputc 0 'l'

      fputc 0 'o'

      fclose 0                 ; Close file opened for create.

   else

      errormsg "Couldn't open file `"%s`"." Fname

   endif

endproc

See also

fgetc, fopen, fputs and fwrite; File I/O Commands.


fputs

fputs id string

Writes a string to the file corresponding to the specified index.

id	The target file id.

string	Any valid ASPECT constant or variable string.

Example

proc main

   string Fname = "test.txt"      ; Name of file to open.

   if fopen 0 Fname CREATE        ; Create and open a file.

      fputs 0 "This set of "      ; Put lines into file with FPUTS.

      fputs 0 "strings was "

      fputs 0 "written with "

      fputs 0 "FPUTS."

      fclose 0                    ; Close the file opened.

      fileview Fname              ; Display file.

   else

      errormsg "Couldn't open `"%s`" for output." Fname

   endif

endproc

Comments

fputs should only be used on null-terminated strings. The fwrite command can be used to write "raw" data.

If the fopen command used to open the file included the TEXT parameter, fputs will append a CR/LF after writing the string to the file. fputs can be tested with the if SUCCESS statement, returning false if the data cannot be written to the file.

See also

fopen, fputc, fwrite, fstrfmt and fgets; File I/O Commands.


fread

fread id numvar | {strvar strlength} [intvar]

Reads a block of data from a file into a string variable and returns the actual number of bytes read in an integer variable.

id	The source file index.

numvar	An integer, float or long variable. The number of bytes read is determined by the number of bytes of storage contained by numvar’s data type.

strvar	String variable that will hold the results of the read.

strlength	The size in bytes of the block to be read. An integer value between 0 and 256.

intvar	Return value is the actual number of bytes read, which may be less than requested if an error occurs or end-of-file is reached.

Example

proc main

   string Fname = "read.me"           ; Name of file to read.

   string DestName = "read.bkp"       ; Name of file to be written.

   string LineInfo                    ; Line read and written.

   integer Len                        ; Length line read from file.

   if fopen 0 Fname READ              ; Open source file for read.

      if fopen 1 DestName CREATE      ; Create and open dest file.

         while not feof 0             ; Loop while not EOF in source.

            ; Read a line from source file and then write it

            ; to our destination file.

            fread 0 LineInfo 255 Len

            fwrite 0 LineInfo Len

         endwhile

         fclose 1                     ; Close destination file.

      else

         errormsg "Can't open `"%s`" for output." DestName

      endif

      fclose 0                        ; Close source file.

   else

      errormsg "Can't open `"%s`" for input." Fname

   endif

endproc

Comments

ASPECT automatically determines the number of bytes to be read if a numeric variable is specified. An integer argument will cause 4 bytes to be read from the file. A long will read 4 bytes, and a float 8 bytes. The file pointer will be updated accordingly.

The status of this command can be checked by comparing the number of bytes read with the number requested. You can also test for the end-of-file condition. To test for errors while reading a file, use the if SUCCESS or if FAILURE statements.

See also

fgetc, fwrite, fgets and fopen; File I/O Commands.


fseek

fseek id fileoffset integer

Repositions the file pointer for the file corresponding to the specified id.

id	The id of the target file.

fileoffset	Offset of the new position relative to the origin of the fseek. fileoffset, a long variable or constant, can be positive or negative. If fileoffset is a negative constant, enclose the parameter within parenthesis to prevent a "Missing token" error from the ASPECT compiler.

integer	The origin of the fseek operation. Possible values are 0 for beginning of the file, 1 for current pointer position or 2 for end-of-file.

Example

proc main

   string Fname = "test.txt"   ; Name of file to read.

   if fopen 0 Fname READ       ; Open file for read only.

      fseek 0 0 0              ; Put pointer at start of file.

      fseek 0 535 1            ; Put pointer somewhere in middle.

      fseek 0 0 2              ; Put pointer at end of file.

      fclose 0                 ; Close the file.

   else

      errormsg "Can't open `"%s`" for input." Fname

   endif

endproc

Comments

Attempting to reposition the file pointer before the beginning of the file will result in an error. Use ftell to determine the current position of the file pointer.

See also

ftell, fopen, ferror and rewind; File I/O Commands.


fstrfmt

fstrfmt id formatstr [arglist]

Writes a formatted string to the file referenced by the specified id.

id	Target file id.

formatstr	A string containing text and/or data format specifiers.

arglist	Up to 12 arguments to be loaded into the formatstr.

Example

proc main

   string Fname = "File.TXT"          ; Name of file to be opened.

   string TextInfo                    ; Text to insert into line.

   TextInfo = "This string written with FSTRFMT!"

   if fopen 0 Fname CREATE            ; Create and open file.

      fstrfmt 0 "%s" TextInfo         ; Insert text into line and

                                      ; write line to file.

      fclose 0                        ; Close the file.

   else

      errormsg "Couldn't open `"%s`" for output." Fname

   endif

endproc

Comments

The processed formatstr cannot exceed 256 characters. For more information on the formatstr structure, see Formatting Text and Data.

See also

fopen, fputs, fwrite and strfmt; File I/O Commands.


ftell

ftell id longvar

Returns the current file pointer position of the file corresponding to the specified file id.

id	The id of the target file.

longvar	Will contain the number of bytes past the beginning of the file.

Example

proc main

   string Fname = "file.txt"     ; Name of file to read.

   long FilePos                  ; Position of pointer within file.

   if fopen 0 Fname READ         ; Open file for read access.

      fseek 0 256 0              ; Seek 256 bytes from start of file.

      ftell 0 FilePos            ; Get position of pointer within file.

      usermsg "File position = %ld" FilePos

      fclose 0                   ; Close the file.

   else

      errormsg "Couldn't open `"%s`" for read!" Fname

   endif

endproc

Comments

ftell can be used together with fseek to store and return to a particular file location.

See also

fopen, fseek and rewind; File I/O Commands.


ftext

ftext id left top width height filespec [{OFFSET fileoffset [LENGTH filelength]} | DYNAMIC] [HSCROLL]

Displays a text file in an ASPECT dialog box.

id	A unique integer constant value assigned to the ftext control by the script.

left top width height	Integer constants which determine the position and size of the ftext control in Dialog Box Units or DBUs, relative to the dialog box’s dimensions. For more information on DBUs, see Dialog Box Units.

filespec	A constant or string variable containing the name of the file to be displayed. A drive and path may be included. If no path is specified, the Aspect Path is assumed.

fileoffset	An optional offset within the file where the text to be displayed begins. A long variable or constant.

LENGTH filelength	If LENGTH filelength is used, only the number of bytes specified in filelength will be displayed. Filelength is a long variable, or a constant.

DYNAMIC	Allows the file to be updated using dlgupdate in the edit control as it increases in size.
HSCROLL	An optional parameter allowing horizontal scrolling instead of lines "wrapping" at the right margin of the text edit box.

Example

proc main

   string szFileName               ; File to display.

   integer Event                   ; Dialog box event.

   if sdlgfopen "File View" "*.txt" SINGLE szFileName

      if isfile szFileName         ; Make sure file exists.

         dialogbox 0 98 129 193 110 11 "File View"

            ftext 1 6 4 182 73 szFileName

            pushbutton 2 77 86 40 14 "&Exit" ok default

         enddialog

         while 1

            dlgevent 0 Event       ; Get dialog event.

            switch Event           ; Evaluate the event.

               case 0              ; No event occurred.

               endcase

               case 1              ; Text box was selected.

               endcase

               default             ; Exit case was selected.

                  exitwhile        ; Exit the loop.

               endcase

            endswitch

         endwhile

         dlgdestroy 0 CANCEL       ; Destroy the dialog box.

      else

         errormsg "File doesn't exist!"

      endif

   endif

endproc

Comments

ftext supports a maximum file size of 64K. The actual maximum file size may be less depending on available resources, however. An error beep will sound whenever a file cannot be loaded.

An ftext control with dynamic file updating can be reset by changing the filespec to another file or to null and issuing the dlgupdate command.

Standard Windows cursor controls are available within file based text controls. ftext can only occur within a dialogbox group.

See also

dialogbox, feditbox, dlgupdate and text; Dialog Box Commands.


ftoa

ftoa float strvar

Converts a float to an ASCII string and stores it in a string variable.

float	The float value to convert.

strvar	Will contain the converted value.

Example

proc main

   float Scores[5]               ; Test score array.

   float Average                 ; Holds average of scores.

   string AvgStr               ; Average as a string.

   Scores[0] = .05, Scores[1] = .95, Scores[2] = 1.00

   Scores[3] = .78, Scores[4] = .82

   Average = Scores[0] + Scores[1] + Scores[2]

   Average += Scores[3] + Scores[4]

   Average /= 5               ; Figure average of scores.

   ftoa Average AvgStr      ; Change average float to string.

   usermsg "Average Score: %s" AvgStr

endproc

See also

atof, itoa, ltoa, numtostr and strfmt; Numeric, String Conversion Commands.


ftp

ftp LOCAL | REMOTE {CHDIR | MKDIR | RMDIR pathname} |
{COPYFILE | DELFILE | FILELIST filespec} |
{RENAME filespec filespec} | {GETDIR strvar}

Allows file manipulation on either host or local FTP machines.

LOCAL	Tells the script that the following parameters affect the LOCAL machine.

REMOTE	Tells the script that the following parameters affect the host FTP site.

CHDIR	Changes the User Path to the drive and/or directory specified in the pathname parameter.

MKDIR	Creates a new directory using the path and/or directory specified by the pathname parameter.

RMDIR	Removes an empty directory using the path specified by the pathname parameter.

pathname	Identifies the DOS drive (for example, C:), pathname and directory. The drive identifier is only required if you change the current drive.

COPYFILE	Copies the file specified by the filespec parameter.

DELFILE	Deletes the file specified by the filespec parameter.

FILELIST	Enumerates a list of files from the current directory of the specified machine to the file specified by the filespec parameter.

filespec	The name of the file to be affected.

RENAME	Renames an existing file, reporting its results in SUCCESS and FAILURE.

filespec	The source filename.

filespec	The destination filename.

GETDIR	Returns the current working directory path of the current directory into a string variable.

strvar	Contains the current path as returned by getdir.


ftruncate

ftruncate id

Truncates or clips the specified file at the current file position.

id	The target file id.

Example

proc main

   string Fname = "trunc.txt"     ; Name of file to truncate.

   if fopen 0 Fname READWRITE     ; Open file for read and write.

      ftruncate 0                 ; Truncate the file, getting rid

                                  ; of everything.

      fclose 0                    ; Close the file.

   else

      errormsg "Couldn't open file `"%s`"!" Fname

   endif

endproc

Comments

The targeted file is truncated at the current file pointer location. ftruncate with the file pointer at zero essentially overwrites an existing file. fseek can be used to position the file pointer to the desired location.

The target file must have been opened in CREATE, READWRITE, or WRITE mode.

See also

fdelblock, fseek, ftell and rewind; File I/O Commands.


fullpath

fullpath strvar filespec [pathname]

Returns the fully-qualified drive and path for a specified filespec.

strvar	Will contain the resultant drive and path.

filespec	The filename to be tested.

pathname	An optional default pathname used to qualify the filespec. If omitted, the User Path is assumed.

Example

proc main

   string Fname = "file.was"       ; Name of file.

   string PathName                 ; File name with path.

   fullpath PathName Fname         ; Add current path to file name.

   usermsg "Path = `"%s`"." PathName

endproc

Comments

fullpath does not verify that the file exists. Use isfile to test for the existence of a file.

See also

addfilename, getdir, getfilename, getpathname, isfile and splitpath; $USERPATH; DOS- or Disk-Related Commands.


func

func name : datatype

Marks the beginning of a function block.

datatype	Specifies the type of data returned by the function. Valid types are float, integer, long and string.

Example

proc main

   integer Route = 2                      ; Integer to contain route.

   string Roads                           ; String to contain directions.

   Roads = GetRoute(Route )               ; Get route for driver to take.

   usermsg "Driver should take %s." Roads ; Display directions.

endproc

func GetRoute : string

param integer Route                       ; Passed integer route number.

   string Routes[3]                       ; String array to contain routes.

   Routes[0] = "Hwy 63 South to Hwy 54, Hwy 54 South to I-44"

   Routes[1] = "Hwy 63 South to Hwy 54, Hwy 54 North to I-70"

   Routes[2] = "Hwy 63 North to I-70, I-70 West to Hwy 429"

   return Routes[Route]                   ; Return requested route.

endfunc

Comments

A function may define a parameter list. The parameters are variables of any type, and are local to the function. The parameters are initialized with arguments passed via the call which invoked the function. Functions return constant values which cannot be modified directly.

Functions can also be called in "expression" format, which allows functions to be used in general expressions. For example, a function could be used as part of an assignment. The syntax for the expression format is:

var = fname([arglist])

If a function returns a numeric value, it can be used as an expression in if or while statements. For example,

if ! fname([arglist])

would test for a return value of zero from function fname.

The expression form of function calls is highly recommended. It is shorter, just as readable, and less verbose. Also, future enhancements to ASPECT may require it.

Each form constitutes a function call which causes execution to transfer to the start of the function block. When the function is exited, execution returns to the point where the call was made.

See also

call, proc, endfunc, return, setjmp, longjmp and param; ASPECT Primary Commands.


fwrite

fwrite id number | {string strlength} [intvar]

Writes a block of data to a file.

id	The target file id.

number	An integer, float, or long value. The number of bytes to write is determined by the storage requirements of number’s data type.

string	A string or string variable that contains the block to be written.

strlength	The size in bytes, in an integer value between 0 and 256, of the block to be written.

intvar	If specified, will return the number of bytes actually written to the file.

Example

proc main

   string Fname = "Fwrite.txt"          ; Name of file to be created.

   if fopen 0 Fname CREATE              ; Create and open file.

      fwrite 0 "This message" 12        ; Write a text string to file.

      fwrite 0 " was written by " 16    ; Write another string.

      fwrite 0 "fwrite." 7              ; Write one more string.

      fclose 0                          ; Close the file.

   else

      errormsg "Can't open `"%s`" for output." Fname

   endif

endproc

Comments

fwrite can be tested with the if SUCCESS statement, which returns false if the data cannot be written.

See also

fopen, fputc, fputs, fread and fstrfmt; File I/O Commands.


getcur

getcur intvar intvar

Returns the current cursor location on the Terminal display.

intvar	Will contain the current row.

intvar	Will contain the current column.

Example

proc main

integer arow, acol          ; Terminal coordinates

   getcur arow acol

   usermsg "Cursor is at %d,%d" arow acol

endproc

See Also

Terminal Commands.


getdir

getdir disk strvar

Returns the current working directory path of the specified drive into a string variable.

disk	An integer number designating the drive. 0 indicates the current drive, 1 specifies drive A, 2 for drive B and so on, up to 26 for Z.

strvar	Will contain the requested path.

Example

proc main

   string CurrDir              ; Current directory.

   getdir 0 CurrDir            ; Get directory for current drive.

   usermsg "Current path = `"%s`"." CurrDir

endproc

Comments

When retrieving the current working directory path using a disk value of 0, the current User Path will be returned. If a disk value other than 0 is specified, the current working directory for that drive will be returned.

The User Path and current working directory for the drive contained within the User Path may be different!

You can test for possible drive access errors with if SUCCESS or if FAILURE statements.

See also

chdir and taskpath; $USERPATH, $PWTASKPATH and $WINPATH; DOS- or Disk-Related Commands.


getenv

getenv string strvar

Returns the contents of an environment variable definition.

string	An environment variable currently defined in DOS.

strvar	Will contain the requested environment definition, if it exists. Otherwise, strvar will be a null string. if SUCCESS can also be used to test the command results.

Example

proc main

   string WinTemp             ; Path to temporary directory.

   getenv "temp" WinTemp      ; Get the temp variable from env.

   usermsg "Windows temp directory: `"%s`"." WinTemp

endproc

See also

putenv; DOS- or Disk-Related Commands.


getfile

getfile protocol | index | string | DEFAULT [filespec[filespec]]

Receives or downloads a file from a remote computer using the specified transfer protocol, returning SUCCESS if the transfer initiated successfully.

protocol	A keyword that represents a file transfer protocol. For a complete list of protocol keywords and indices, see Protocol Names and Indices.

index	An integer value corresponding to the desired protocol.

string	A string constant or variable which represents a file transfer protocol, or a named-item version of a protocol.

DEFAULT	If DEFAULT is specified, the current default protocol will be used to download the file.

filespec	The name of the file used to store the downloaded file. If the filespec contains a path, the file will be created and saved in the specified path. If no path is included, the file will be saved to the directory specified in the Download path field in Setup, Options, Paths.

filespec	Valid only with the Ind$file protocol, the second filespec must contain the name of the file as it exists on the mainframe.

Example

proc main

   transmit "D testfile.zip^M" ; Send download command to host.

   waitfor "Start Xfer"       ; Wait for signal to start transfer.

   getfile ZMODEM             ; Get file with Zmodem protocol.

   while $XFERSTATUS          ; Pause script while transferring.

      yield                   ; Yield processing time

   endwhile

;   .                         ; Other processes, or even other getfile

;   .                         ; commands could follow the completion

;   .                         ; of the transfer.

endproc

Comments

Under ASPECT, file transfers are asynchronous operations, meaning that they can run independently of script execution. A getfile or sendfile command only initiates a file transfer attempt. While the transfer is processing, ASPECT executes the next commands in the script. If the script needs to wait for the transfer to complete, a while loop like the one shown in the example should be used to "stall" the script.

If the script executes a while loop to monitor the status of an on-going file transfer, you may find it useful to include the yield command within the loop. The yield command causes ASPECT to release its processing time to the system, which can improve file transfer performance.

The when $XFERFILE command can be used to call a separate procedure if the value of $XFERFILE changes.

If a protocol requires a filespec, a path may be included. Otherwise, Procomm Plus uses the directory specified in the Download path field in Data, Data Options, Paths dialog in Setup. Protocols that do not require a filespec receive the filename from the remote system.

The Zmodem, Kermit, Ymodem,Ymodem-G and CIS-B+ protocols do not require a filespec for downloads. The Xmodem, 1K-Xmodem, 1K-Xmodem-G, ASCII and Raw ASCII protocols do. The Ind$file protocol is unique in that it requires two: one filespec for local storage of the received file, and one filespec specifying the name of the file as it exists on the host.

If index, string, or DEFAULT is specified, the compiler will treat the filespecs as optional. It is up to the user to provide the proper filespec information based on the protocol.

See also

sendfile, yield and kermserve; $XFERSTATUS and $XFERFILE; the set protocol, set aspect filexferbox and protocol-specific set commands; File Transfer Commands.


getfilename

getfilename strvar filespec

Extracts a filename from a file specification.

strvar	Will contain the extracted filename. If a filename could not be extracted, strvar will be null.

filespec	The file and pathname to search.

Example

proc main

   string PathName                 ; Path to extract file name from.

   string FName                    ; Name of the file.

   ; Set the full path specification and extract file name.

   PathName = "C:\PROGRAM FILES\PROCOMM PLUS\ASPECT\HOST\HOST.USR"

   getfilename FName PathName      ; Extract file name from path.

   getpathname PathName PathName   ; Extract path without file name.

   usermsg "Path = %s`rFilename = %s" PathName FName

endproc

See also

addfilename, getpathname and splitpath; DOS- or Disk-Related Commands.


getpathname

getpathname strvar filespec

Extracts a pathname from a file specification.

strvar	Will contain the extracted pathname. If a path could not be extracted, strvar will be null.

filespec	The file and pathname to search.

Example

See the example for getfilename.

See also

addfilename, getfilename and splitpath; DOS- or Disk-Related Commands.


getvolume

getvolume disk strvar

Returns the volume label for the specified drive.

disk	An integer number designating the drive. 0 indicates the current drive, 1 specifies drive A, 2 for drive B and so on up to 26 for drive Z.

strvar	Will contain the volume label. If the drive has no label, strvar will be null.

Example

proc main

   string Label             ; Volume label of current drive.

   getvolume 0 Label        ; Retrieve label of current drive.

   usermsg "Volume label of current drive is `"%s`"!" Label

endproc

See also

chdir and getdir; $VOLUME; DOS- or Disk-Related Commands.


goto

goto name

Performs an unconditional branch to the specified label within the current procedure or function.

name	A label within the current procedure. Labels provide a point to which the goto command directs program control.

Example

proc main

   integer Loops = 0       ; Integer to count loops.

Label:                     ; Define a label to jump to.

   Loops++                 ; Increment our loop counter.

   if Loops < 3            ; If the number of loops is still

      goto Label           ; less than 3, jump to label.

   endif

   usermsg "%d" Loops      ; Display number of loops.

endproc

Comments

When ASPECT encounters a goto command, it jumps to the location where the label is defined, resuming execution with the command immediately following the label.

A name used for a label in one procedure can be reused in another procedure, but the label can only be referenced within the procedure where it’s defined. For non-local branching, use the setjmp and longjmp commands. For more information on using labels, see Labels.

See also

setjmp, longjmp and call; ASPECT Primary Commands.


groupbox

groupbox id left top width height [label]

Displays a rectangle with optional text label in an ASPECT dialog box.

id	The control id for the groupbox. An integer constant.

left top width height	Integer constants specifying the position and size of the groupbox in Dialog Box Units or DBUs, relative to the dialog box. For more information on DBUs, see Dialog Box Units.

label	An optional string constant or string variable that appears in the upper left corner of the rectangle. To include a keyboard accelerator for the groupbox, simply include an ampersand in front of the desired character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

The accelerator will direct the input focus to the control whose statement follows the groupbox statement in the dialogbox command group.

Example

proc main

   ; Display a dialog box containing a groupbox and a

   ; button.

   dialogbox 0 59 150 121 71 11 "Groupbox Example"

      groupbox 1 4 8 112 54 "Stuff"

      pushbutton 2 21 22 80 30 "Big Button"

   enddialog

   pause 5                 ; Show off the dialog box.

   dlgdestroy 0 CANCEL     ; Destroy the dialog box.

endproc

Comments

groupbox is used only within a dialogbox statement group. It is used to group dialog box controls graphically, but has no effect on the controls otherwise.

See also

dialogbox; Dialog Box Commands.


halt

halt

Terminates the executing script file and any parent scripts unconditionally.

Example

proc main

   usermsg "This example shows how to use the HALT command."

   ; Stop this script file and parent script file if there

   ; is one.

   halt

endproc

See also

pwexit and exit; $PARENTFILE; Script Control Commands.


hangup

hangup

The operation of hangup is dependent on the current mode. In Terminal mode, hangup hangs up the phone. In FTP, Telnet, Mail, and News modes, disconnect terminates the connection with the server.

Additionally, if Procomm Plus is not running in Terminal mode, and the Internet Connection within the Setup, Internet, Internet Connection panel is not set to External Network, this command attempts to hang up the specified Internet Connection.

Example

proc main

   when USEREXIT call Cleanup ; Watch for user exit.

   while $CARRIER             ; Loop while connected.

      yield                   ; Yield processing time

   endwhile

endproc

proc Cleanup

   hangup                     ; Hang up the phone line.

endproc

See Also

disconnect; COM-Related Commands.


help

help CONTENTS | HELP | {SEARCH [string]} | EXIT | {TOPIC index [POPUP]}

Opens on-line Help.

CONTENTS	Displays the help file contents topic.

HELP	Displays the topic that explains how to use help.

SEARCH[string]	Displays the topic containing the optional search key string, if an exact match was found. Otherwise, the Search dialog is displayed.

EXIT	Causes the help window to close if no other applications are currently using help.

TOPIC index	Displays help for a particular topic, specified by index. TOPIC is only useful for custom help files. Special software tools are required to build custom help files.

POPUP	If specified, the help topic will be displayed in a pop-up window, rather than a full window.

Example

proc main

   string HelpName = "my.hlp"      ; Name of help file to be loaded.

   set aspect helpfile HelpName    ; Set the name of the help file.

   help CONTENTS                   ; Load contents section of help.

endproc

Comments

To load an alternate on-line Help file, use the set aspect helpfile command.

See also

dialogbox; set aspect helpfile; General Procomm Plus Commands.


hotspot

hotspot id left top width height BACKGROUND | USERWIN

Places a mouse-selectable rectangle in the User window.

id	A unique integer value assigned to each hotspot. This id value is used with the objremove command to remove the hotspot from the User window. It is also reported to the $OBJECT system variable when the hotspot is selected by the left mouse button.

left top	Integer values, expressed in User Window Units or UWUs, which determine the position of the top left corner of the hotspot with respect to the User window or the background graphic. For more information on UWUs, refer to User Window Units.

width height	The size of the hotspot in UWUs.

USERWIN | BACKGROUND	Specify USERWIN to "fix" the top left corner of the hotspot in position relative to the upper left corner of the User window. If BACKGROUND is specified, the hotspot stays over the same spot on a background graphic.
Example

proc main

   integer Event              ; User window event.

   ; Create a user window and display a bitmap with a

   ; hotspot over it. Put a bitmap in your script

   ; directory called "button.bmp".

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   bitmap 1 500 500 "Click This" "button.bmp" USERWIN

   hotspot 2 500 500 2000 2000 USERWIN

   uwinpaint                  ; Paint the new user window.

   while 1                    ; Loop forever.

      if (Event = $OBJECT) != 0

         switch Event         ; Evaluate user window event.

            case 2            ; Hotspot was selected.

               exitwhile      ; Exit the while loop.

            endcase

         endswitch

      endif

   endwhile

   uwinremove                 ; Remove the user window.

endproc

Comments

When the left mouse button is clicked down, the hotspot inverts. When the right mouse button is clicked, and not over a non-hotspot object, all hotspots are revealed. If a hotspot has been hidden with objhide, however, it will not be revealed when the right mouse button is clicked down.

A User window must exist before hotspots can be placed. A uwinpaint command must be issued to display User window changes.

See also

uwincreate, icon, iconbutton, bitmap, dllobject, pushbutton, objmove, uwinpaint, objcoord, objpointid, objremove and metafile; $OBJECT; User Window Commands.


icon

icon id left top filespec index

(or) icon id left top filespec index BACKGROUND | USERWIN

Loads an icon from a disk file and displays it within an ASPECT dialog box or the User window. icon has two forms depending on where the icon is displayed. icon can only be tested for SUCCESS/FAILURE when it appears in a User window.

Dialog box format

icon id left top filespec index

id	The control id of the icon. This value can be used by dlgupdate to refresh the icon display. An integer constant.

left top	Integer constants, specifying the location of the icon in Dialog Box Units or DBUs, from the top left corner of the dialog box. For more information on DBUs, see Dialog Box Units.

filespec	A constant or a string variable, containing the name of the icon file. Icons are generally found in files with extensions of .exe, .dll, .nil, .icl, .icn or .ico.

index	Some types of files can contain multiple icons. This integer constant or variable identifies the icon to be loaded. If the file only contains one icon, index should be 0.

Example

proc main

   ; Display a dialog box and an icon. You need an ICON

   ; file called "icons.dll".

   dialogbox 0 0 0 100 50 11 "Icons!"

      icon 1 5 5 "icons.dll" 1

      icon 2 55 5 "icons.dll" 2

   enddialog

   pause 5                 ; Show off dialog and icons.

   dlgdestroy 0 CANCEL     ; Destroy the dialog box.

endproc

See also

dialogbox, iconbutton, dlgupdate, bitmap and metafile; Dialog Box Commands.

User window format

icon id left top filespec index BACKGROUND | USERWIN

id	A unique integer constant or global variable identifying this icon. It can be used by the objremove command to remove the icon.

left top	The location of the icon in User Window Units (UWUs) from the top left corner of the User window. For more information about UWUs, see User Window Units.

filespec	A constant or global string variable which specifies the file containing the icon. If a path is not included in filespec, the current Aspect Path is assumed.

Icons are generally found in files with extensions of .exe, .dll, .nil, .icl, .icn or .ico.

index	Some types of files can contain multiple icons. This integer constant identifies the icon to be loaded. If the file only contains one icon, index should be 0.

BACKGROUND  | USERWIN	Specify USERWIN to fix the top left corner of the icon in position relative to the upper left corner of the User window. Specify BACKGROUND to fix the icon over the same spot on a background graphic.
Example

proc main

      ; Display a user window and some icons. You need to create

      ; an ICON file called "icons.dll" for this example.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   icon 1 500 500 "icons.dll" 1 USERWIN

   icon 2 2000 500 "icons.dll" 2 USERWIN

   uwinpaint               ; Paint the new user window.

   pause 5                 ; Show off the user window.

   uwinremove              ; Destroy the user window.

endproc

Comments

icons are for graphical display only. They do not generate $OBJECT events when clicked upon. A User window must exist before icons can be placed. A uwinpaint command must be issued to display User window changes.

See also

iconbutton, uwincreate, uwinpaint, bitmap, metafile, dllobject, pushbutton, objcoord, objpointid, objpaint, objmove, objremove and hotspot; User Window Commands.


iconbutton

iconbutton id left top label filespec index [OK | CANCEL] [DEFAULT]

(or) iconbutton id left top label filespec index BACKGROUND | USERWIN

Loads an icon from a disk file and displays it within an ASPECT dialog box or a User window. The user may click on this icon to indicate a choice. iconbutton has two forms depending on where the icon is displayed. iconbutton can only be tested with if SUCCESS when it appears in a User window.

Dialog box format

iconbutton id left top label filespec index [OK | CANCEL] [DEFAULT]

id	A unique integer constant value given to the iconbutton. dlgevent will return this value when the iconbutton is selected.

left top	Integer constants, specifying the location of the iconbutton in Dialog Box Units (DBUs) from the top left corner of the dialog box. For more information about DBUs, see Dialog Box Units.

label	A constant or string variable displayed as a label, centered just below the iconbutton. To specify a keyboard accelerator for the iconbutton, simply include an ampersand (&) before the desired character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the ‘R’ displayed as an underscored accelerator.

filespec	A constant or string variable which specifies the file containing the icon to be displayed on the button. Icons are generally found in files with extensions of .exe, .dll, .nil, .icl, .icn or .ico.

index	Some types of files can contain multiple icons. This integer constant or variable identifies the icon to be loaded. If the file only contains one icon, index should be 0.

OK	The dialog box is removed when an OK iconbutton is pressed. Changes made to file-related controls will be saved to disk.

CANCEL	The dialog box is removed when a CANCEL iconbutton is pressed. Changes made to file-related controls will not be saved.

DEFAULT	Specifies that the iconbutton is to be selected when the <Enter> key is pressed and no other button or iconbutton has the input focus, or when a listbox, flist box, combobox, fcombobox or dirlistbox item is double-clicked. Note that only a single button or iconbutton can be named as a default in a dialog box.

Example

proc main

   integer Event              ; Dialog box event.

   ; Display dialog box and icon buttons. You need to

   ; create an ICON file called "icons.dll", with at

   ; least three icons in it for this example.

   dialogbox 0 111 150 100 66 11 "Icon Button Example"

      iconbutton 1 20 5 "Icon #1" "icons.dll" 1

      iconbutton 2 55 5 "Icon #2" "icons.dll" 2

      pushbutton 3 30 46 40 14 "&Exit" ok default

   enddialog

   while 1                    ; Loop forever.

      dlgevent 0 Event        ; Dialog box event.

      switch Event            ; Evaluate the event.

         case 0               ; No event occurred.

         endcase

         case 1               ; Icon #1 selected.

            usermsg "Icon #1 selected!"

         endcase

         case 2               ; Icon #2 selected.

            usermsg "Icon #2 selected!"

         endcase

         default              ; Exit method selected.

            exitwhile         ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL        ; Destroy the dialog box.

endproc

See also

dialogbox, icon, dlgupdate and dlgevent; Dialog Box Commands.

User window format

iconbutton id left top label filespec index BACKGROUND | USERWIN

id	A unique integer value given to this iconbutton. The value is assigned to $OBJECT when the iconbutton has been selected by the user with the left mouse button. It is also used by the objremove command to remove the iconbutton.

left top	If the USERWIN option is specified, these values are the location of the iconbutton in User Window Units, or UWUs, from the top left corner of the User window. For more information about UWUs, see User Window Units.

If the BACKGROUND option is specified, the iconbutton is fixed over a certain area of the background graphic.

label	A constant or global string variable displayed as a label, centered just below the iconbutton. To specify a keyboard accelerator for the iconbutton, simply include an ampersand (&) before the desired character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the ‘R’ displayed as an underscored accelerator.

filespec	A constant or global string variable which specifies the file containing the icon. Icons are generally found in files with extensions of .exe, .dll, .nil, .icl, .icn or .ico.

If a path is not specified in the filespec, the Aspect Path is assumed.

index	Some types of files can contain multiple icons. This integer constant identifies the icon to be loaded. If the file only contains one icon, index should be 0.

BACKGROUND  | USERWIN	Specify USERWIN to fix the top left corner of the icon button in position relative to the upper left corner of the User window. Specify BACKGROUND to fix the button over the same spot on a background graphic.
Example

proc main

   integer Event              ; User window event.

   ; You must have a file called "icons.dll", containing

   ; at least 2 icons for this example.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   iconbutton 1 500 500 "Icon #1" "icons.dll" 1 USERWIN

   uwinpaint                  ; Paint the user window.

   while 1                    ; Loop forever.

      if (Event = $OBJECT) != 0

         switch Event         ; Evaluate the event.

            case 1            ; Icon button selected.

               exitwhile      ; Exit the while loop.

            endcase

         endswitch

      endif

   endwhile

   uwinremove                 ; Destroy the user window.

endproc

Comments

A User window must exist before iconbuttons can be placed. An uwinpaint command must be issued to display User window changes.

See also

icon, uwincreate, uwinpaint, pushbutton, hotspot, metafile, bitmap, dllobject, objcoord, objpointid, objpaint and objremove; $OBJECT; User Window Commands.


if

if condition

..

[elseif condition]

..

[else]

..

..

endif

Executes the commands on the following line if the condition is true.

Commands on the lines between the if statement and the next corresponding elseif, else, or endif command are executed when the condition tested by the if command is true.

[elseif]	A branch point evaluated when the previous if or elseif has evaluated as false.

[else]	A branch point that is executed when the previous if or elseif commands have evaluated as false.

endif	Concludes the if command statement group.

condition	A condition is true if it evaluates as a non-zero value. It is false if it evaluates as zero.

A condition can consist of certain ASPECT commands and their parameters, or a numeric expression:

if { [ not ] command } | { [ ! ] expression }

command	Any ASPECT command which sets the SUCCESS/FAILURE flags. SUCCESS evaluates as true; FAILURE false.

The not keyword can be used to reverse or negate the result of the ASPECT command. For example, when isfile is true, not isfile is false.

expression	A numeric expression, which may include user-defined functions returning numeric results. Numeric system variables such as $CARRIER may also be used, as well as the SUCCESS/FAILURE settings.

The "!" ASPECT operator can be used to negate the results of an user-defined function, or a numeric expression.

Example

proc main

   integer Number                   ; Integer to check in conditional.

   string FileTestStr               ; Variable for reporting

   if not isfile "s9z631mo.jdl"     ; Look for an unlikely filename

      FileTestStr = "the file was not found."

   else

      FileTestStr = "the file was found!"

   endif

   Number = 6 * 8                   ; Set Number equal to something.

   if Number != 42                  ; Check variable to see if it's 42.

      usermsg "%d not equal to 42, and %s" FileTestStr

   else

      usermsg "%d equals 42(?), and %s" FileTestStr

   endif

endproc

Comments

Each if command must end with an endif command. An else or elseif command can be used to provide alternative branches based on the results of the if condition. There can be any number of elseif commands but all must precede the else command if it is used. The command following the else is executed if the condition(s) specified for the preceding if and elseif commands evaluate as false.

Some common uses of the if command are end-of-file testing with feof, file error-checking with ferror and empty string checking with nullstr. See the definitions of these commands for more information.

See also

else, elseif, endif and switch; SUCCESS and FAILURE; ASPECT Primary Commands.


integer

integer name[=expression][,name[=expression]]...

Defines a global or local integer variable or an array of integer variables.

name	The name of the new variable. This name must follow the standard ASPECT naming conventions. When defining an array, the subscript expression must result in a constant value.

= expression	An initializing expression. It can specify operators, constants or previously-declared numeric variables, or a function which returns a numeric result. The initializing expression cannot be used when defining an array.

Example

proc main

   integer Apples = 5            ; Number of apples.

   integer Oranges = 6           ; Number of oranges.

   integer Diff                  ; Difference.

   Diff = Oranges - Apples       ; Compare apples to oranges.

   usermsg "There are %d more Oranges than Apples." Diff

   ; Integers allow you to work with number values from

   ; -2147483648 to 2147483647.

endproc

Comments

Up to 256 global integer variables can be defined, as well as 256 global integer arrays. Local integer definitions are limited by the available stack space at the time the procedure or function is called. See User-defined Variables, Global and Local Variables and Arrays for more information.

See also

float, long, string and param; ASPECT Primary Commands.


intsltime

intsltime integer integer integer integer integer integer longvar

Converts integer date and time values into a long system time format.

integer	An integer between 1970 and 2106 representing the year.

integer	An integer between 1 and 12 representing the month.

integer	An integer between 1 and 31 representing the day.

integer	An integer between 0 and 23 representing the hour.

integer	An integer between 0 and 59 representing the minute.

integer	An integer between 0 and 59 representing the second.

longvar	Assigned a value in timeval format.

Example

proc main

   integer Month, Day            ; Integers to contain date and

   integer Year, Hour            ; time to convert to long

   integer Min, Sec              ; date and time.

   long NewTime                  ; Longs to contain converted

   long Diff                     ; long value and difference.

   Month = 01, Day = 01          ; Assign values to date and time

   Year = 2000, Hour=12          ; integers to convert to long

   Min = 0, Sec = 0              ; time value.

   ; Convert integer values into long time value and find

   ; difference between now and converted date and time.

   intsltime Year Month Day Hour Min Sec NewTime

   Diff = (NewTime - $LTIME )/ 86400

   usermsg "%d days between now and year 2000!" Diff

endproc

See also

strsltime, ltimeints and monthstr; $LTIME; Date and Time Commands.


isfile

isfile filespec [intvar]

Determines if a specified file exists.

filespec	Any valid DOS path and/or filename, including extension. No wildcards are allowed. If no directory is specified, the User Path is assumed.

intvar	If specified, will contain the result of the test. If the file exists, intvar will be 1; otherwise 0.

Example

proc main

   string Fname = "file.txt"   ; File to check for and open.

   if isfile Fname             ; Check to see if the file exists.

      fopen 0 Fname READWRITE  ; Open file for read and write.

   else

      fopen 0 Fname CREATE     ; Open file for create.

   endif

   if not ferror 0             ; Make sure there were no errors.

      fwrite 0 "Addendum" 7    ; Write something into the file.

      fclose 0                 ; Close the file.

   else

      errormsg "Couldn't open file `"%s`"." Fname

   endif

endproc

Comments

The isfile command functions by attempting to open a file in read-only mode. If the file is currently in use by another process, the command may fail even though the file exists. The findfirst command is more reliable.

See also

copyfile, delfile, findfirst and fopen; DOS- or Disk-Related Commands.


itemcount

itemcount itemtype intvar

Returns the number of items within a option set list.

itemtype	A keyword or keyword combination that represents an option set item type. Valid selections for itemtype are discussed in ASPECT Conventions. Note that only one of these selections may be specified per itemcount command. For example:

itemcount DATA OPTIONS "My Modem" i0

intvar	Will receive the number of items in the specified set.

Example

proc main

   integer Count              ; Count of protocols

   string NameOfItem          ; The name of the protocol

   itemcount PROTOCOL Count

   itemname PROTOCOL (Count-1) NameOfItem

   usermsg "The last protocol is [%s]." NameOfItem

endproc

Comments

It is important to note that itemcount returns a non-zero-based value. The index values for the items being counted, however, are zero-based.

See also

itemfind, itemname, itemcreate and itemremove; $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $TELNETOPTIONS, $PROTOCOL, $TERMINAL, $FAXOPTIONS, $TERMFONT, $TERMCOLORS and $WINCOLORS; Option Set Commands.


itemcreate

itemcreate {PROTOCOL name protocol | index | string [intvar]} |
                  {TERMINAL name terminal | index | string [intvar]} |
                  {itemtype name index | string [intvar]}

Creates a new item in an option set list.

itemtype	A keyword or keyword combination that represents an option set item type. Valid selections for itemtype are discussed in ASPECT Conventions. Note that only one of these selections may be specified per itemcreate command. For example:

itemcreate DATA OPTIONS "My Modem" i0

name	A string variable or constant, specifying the name of the item to create.

For valid protocol keywords and indices, see Protocol Names and Indices. Terminal keywords and indices are listed in Emulation Names and Indices.

intvar	Will receive the index value of the new item, if specified.

Example

proc main

   integer ItemIndex             ; Index of new protocol.

   integer NewIndex              ; Index of new ZMODEM.

   itemfind PROTOCOL "Zmodem" ItemIndex

   itemcreate PROTOCOL "Zmodem-2" ItemIndex NewIndex

   sdlgmsgbox "New ZMODEM" "Keep new ZMODEM?" QUESTION \

      YESNO I0 2

   if I0 != 6                    ; If yes not chosen ...

      itemremove PROTOCOL NewIndex

   endif

endproc

Comments

itemcreate returns FAILURE if the item could not be created. itemcreate will fail if either the Connection Directory or Setup is open at the time it executes.  itemcreate will always return FAILURE for the MODEM CONNECTION itemtype.

See also

itemfind, itemname, itemcount and itemremove; $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $TELNETOPTIONS, $PROTOCOL, $TERMINAL, $FAXOPTIONS, $TERMFONT, $TERMCOLORS and $WINCOLORS; Option Set Commands.


itemfind

itemfind {itemtype name [EXACT]} | NEXT [strvar] [intvar]

Searches an option set for a specifically named item.

itemtype	A keyword or keyword combination that represents an option set item type. Valid selections for itemtype are discussed in ASPECT Conventions. Note that only one of these selections may be specified per itemfind command. For example:

itemfind DATA OPTIONS "My Modem" i8

name	A string variable or constant containing a full or partial item name.

EXACT	An optional parameter that causes itemfind to find an exact match rather than a case-insensitive substring match.

NEXT	Continues searching the option set for another occurrence of the previously specified item name.

strvar	If specified, will return the complete name of an option set item if the search is successfull.

intvar	Will receive the index value of the item, if specified.

Example

See the example for itemcreate.

Comments

itemfind reports FAILURE if the item could not be found. Otherwise, it returns the index of the first matching item.

See also

itemcreate, itemname, itemcount and itemremove; $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $TELNETOPTIONS, $PROTOCOL, $TERMINAL, $FAXOPTIONS, $TERMFONT, $TERMCOLORS and $WINCOLORS; Option Set Commands.


itemname

itemname itemtype index strvar

Returns the name of a option set item into a string.

itemtype	A keyword or keyword combination that represents an option set item type. Valid selections for itemtype are discussed in ASPECT Conventions. Note that only one of these may be specified per itemname command. For example:

itemname DATA OPTIONS 0 s8

index	An integer constant or variable, specifying the zero-based index of the option set item whose name is to be returned.

strvar	Will contain the name of the item specified by the index value.

Example

proc main

   integer ItemIndex = 0           ; Index of items in list.

   string ListItemName             ; Name of item in list.

   while 1                         ; Loop forever.

      itemname MODEM CONNECTION ItemIndex ListItemName

      if not nullstr ListItemName

         termwrites ListItemName

         termwrites "^M^J"

      else

         exitwhile                 ; Exit the while loop.

      endif

      ItemIndex++                  ; Increment the item index.

   endwhile

endproc

Comments

itemname returns FAILURE if there is no item associated with that index, or if the index exceeds the item count in the specified option set.

See also

itemfind, itemcreate, itemcount and itemremove; $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $TELNETOPTIONS, $PROTOCOL, $TERMINAL, $FAXOPTIONS, $TERMFONT, $TERMCOLORS and $WINCOLORS; Option Set Commands.


itemremove

itemremove itemtype index | string

Removes a script- or user-created entry from a option set list.

itemtype	A keyword or keyword combination that represents an option set item type. Valid selections for itemtype are discussed in ASPECT Conventions. Note that only one of these may be specified per itemremove command. For example:

itemremove DATA OPTIONS "My Modem"

index	An integer constant or variable, specifying the zero-based index of the item to be removed.

string	A string constant or variable, specifying the name of the item to be removed. The string must match the item’s name exactly, including upper- and lowercase. itemname can be used to find an item name based on a partial string.

Example

See the example for itemcreate.

Comments

itemremove returns FAILURE if the option set item could not be removed. itemremove will fail if any of the following conditions exist at the time it executes:

•	Setup is open.

•	The Connection Directory is open.

•	Another instance of Procomm Plus is running.

•	You're attempting to remove the last item remaining in an option set.

•	You're attempting to remove an item that is currently selected in Setup.

•	You're using the MODEM CONNECTION itemtype.

•	You're attempting to remove the "direct connect-None" in the Modem Connection option set.

•	You're attempting to remove one of the first 9 items or the "IND$FILE" item in the Current Transfer Protocol option set, located in the Data, Transfer Protocol settings panel in Setup.

•	You're attempting to remove one of the first 35 items or the "RIPscrip 1.54" item in the Current Terminal option set, located in the Data, Terminal Options settings panel in Setup.

See also

itemfind, itemname, itemcount and itemcreate; $DATAOPTIONS, $FAXOPTIONS, $FTPOPTIONS, $TELNETOPTIONS, $PROTOCOL, $TERMINAL, $FAXOPTIONS, $TERMFONT, $TERMCOLORS and $WINCOLORS; Option Set Commands.


itoa

itoa integer strvar

Converts an integer to an ASCII string and stores it in a string variable.

integer	The integer value to convert.

strvar	Will contain the converted value.

Example

proc main

   integer Miles = 257              ; Distance traveled.

   integer Gallons = 14             ; Volume of fuel used.

   integer Mileage                  ; Mileage for trip.

   string MileageString             ; Mileage as a string.

   Mileage = Miles / Gallons        ; Figure mileage.

   itoa Mileage MileageString       ; Convert mileage to string.

   usermsg "Miles per Gallon: %s" MileageString

endproc

See also

ftoa, ltoa, numtostr, atoi and strfmt; Numeric, String Conversion Commands.


kermserve

kermserve {GETFILE | SENDFILE filespec} | FINISH | LOGOUT

Issues a Kermit server command, returning SUCCESS and FAILURE based on the outcome. kermserve is only valid if the host is in the Kermit server mode.

GETFILE filespec	Receives a file from a remote system. filespec is any filename that’s valid on the remote system.

SENDFILE filespec	Sends a file to a remote system. filespec is any valid DOS filename, including the extension.

If the script executes a while loop to monitor the status of an on-going file transfer, you may find it useful to include the yield command within the loop. The yield command causes ASPECT to release its processing time to the system, which can improve file transfer performance.

FINISH	Logs out of Kermit server mode.

LOGOUT	Logs out of Kermit server mode and logs off the host.

Example

proc main

   waitfor "kermit"           ; Wait for the Kermit prompt.

   transmit "server^M"        ; Transmit the server command.

   mspause 250                ; Wait for server to initialize.

   kermserve getfile "LIST"   ; Transmit command to get file.

   while $XFERSTATUS          ; Pause while transferring file.

      yield                   ; Yield processing time

   endwhile

   ; The while $XFERSTATUS loop is critical -

   ; otherwise, the script might send the LOGOUT

   ; command before the transfer was complete!

   kermserve LOGOUT           ; Sign off of the host system.

endproc

Comments

Under ASPECT, file transfers are asynchronous operations, meaning that they can run independently of script execution. A kermserve getfile or kermserve sendfile command only initiates a file transfer attempt. While the transfer is processing, ASPECT executes the next commands in the script. If the script needs to wait for the transfer to complete, a while loop like the one shown in the example should be used to "stall" the script.

If the script executes a while loop to monitor the status of an on-going file transfer, you may find it useful to include the yield command within the loop. The yield command causes ASPECT to release its processing time to the system, which can improve file transfer performance.

See also

sendfile and getfile; File Transfer Commands.


keyflush

keyflush

Clears accumulated keystrokes from the keyboard buffer. Any unprocessed keystrokes will be lost. keyflush is only valid when set aspect keys is on.

Example

proc main

   keyflush             ; Clear the keyboard buffer.

   termkey ALT 'D'      ; Send ALT-D to open directory.

   pause 2              ; Pause to show off directory.

   keyflush             ; Clear the keyboard buffer.

   sendkey ALT 'F'      ; Send ALT-F to open "File" menu.

   mspause 250          ; Wait for the directory menu.

   sendkey ALT 'X'      ; Send ALT-X to exit directory.

endproc

See also

keyget; $KEYHIT; set aspect keys; Keyboard Commands.


keyget

keyget [intvar [integer]]

Retrieves a key pressed by the user and optionally stores it in the specified integer variable.

intvar	The returned key value.

integer	An optional timeout value in seconds.

Example

proc main

   locate 23 0                   ; Put cursor on 24th line.

   termwrites "Press any Key"    ; Tell user to press a key.

   keyget                        ; Wait for a key to be pressed.

endproc

Comments

Keys can only be retrieved by the script when Procomm Plus’s main window has the input focus.

The value placed in the numeric variable depends upon the key pressed. The keypress shift state is contained in the high order byte, while the virtual key code is the low order byte. If a timeout value is specified, and keyget does not receive a key value within that time, a value of zero is assigned to the target intvar.

To place the ASCII character corresponding to a virtual key code into a string variable, use the keytoansi or keytooem command.

See also

keystate, keytoansi, keytooem, termvkey and sendvkey; $KEYHIT; set aspect keys; Keyboard Commands.


keystate

keystate keyval intvar

Determines whether a key corresponding to a virtual key code is currently pressed.

keyval	The virtual key code of the key to be tested. The key code does not include the shift state.

intvar	Set to 1 if the key is currently pressed, 0 otherwise.

Example

proc main

   string NumLock, CapsLock, ScrLock

   integer CurrKeyState                ; State of key being checked.

   keystate 0x90 CurrKeyState          ; Get the state of NumLock key.

   NumLock = State(CurrKeyState)         ; Convert state to string (ON,OFF).

   keystate 0x14 CurrKeyState          ; Get state of CapsLock key.

   CapsLock = State(CurrKeyState)        ; Convert state to string (ON,OFF).

   keystate 0x91 CurrKeyState          ; Get state of ScrollLock key.

   ScrLock = State(CurrKeyState)         ; Convert state to string (ON,OFF).

   ; Display the current status of the NumLock,

   ; CapsLock, and ScrollLock keys.

   usermsg "Caps: %s Num: %s Scroll: %s" CapsLock NumLock ScrLock

endproc

func State : string

param integer CurrKeyState

   if CurrKeyState

      return "ON"                    ; Return "ON" if key state is 1.

   else

      return "OFF"              ; Return "OFF" if key state is 0.

   endif

endfunc

Comments

keystate can also be used to test the toggled state of the <Caps Lock>, <Num Lock> and <Scroll Lock> keys. It returns a 1 if these keys are toggled ON and a 0 if they’re toggled OFF. For a list of virtual key code values, see Virtual Key Codes.

See also

keyget; Keyboard Commands.


keytoansi

keytoansi keyval intvar

Converts a key value to its corresponding ANSI character value. A key value is composed of a keyboard shift state and a virtual key value.

keyval	The key value to convert.

intvar	The converted ANSI value. If there is no corresponding ANSI key value, intvar will be -1. Otherwise, intvar will be an ANSI character value in the range of 0 to 255.

Example

proc main

   integer Key                   ; Key pressed.

   integer ANSIKey               ; Converted key code.

   set aspect keys ON            ; Aspect will handle key presses.

   while 1

      if $KEYHIT                 ; Check for a keypress.

         keyget Key              ; Get key from keyboard buffer.

         keytoansi Key ANSIKey   ; Convert keycode to ANSI keycode.

         if ANSIKey != -1        ; Make sure key converted.

            computc ANSIKey      ; Transmit character.

         else

            termvkey Key         ; Process key normally.

         endif

      endif

   endwhile

   set aspect keys OFF           ; PW4 handles key presses.

endproc

See also

keyget, termkey, sendkey, keystate, keytooem and ansitokey; Keyboard Commands.


keytooem

keytooem keyval intvar

Converts a key value to its corresponding OEM character value. A key value is composed of a keyboard shift state and a virtual key value.

keyval	The key value to convert.

intvar	The converted OEM value. If there is no corresponding OEM key value, intvar will be -1. Otherwise, intvar will be an OEM character value in the range of 0 to 255.

Example

proc main

integer KeyVal             ; Key value converted to OEM.

   keytooem 'A' KeyVal     ; Convert key value to OEM.

   usermsg "0x%X" KeyVal   ; Display the OEM value.

endproc

See also

keyget, termkey, sendkey, keystate, keytoansi and oemtokey; set aspect codepage; Keyboard Commands.


listbox

listbox id left top width height itemlist [tabstring]
SINGLE | MULTIPLE strvar [HSCROLL] [SORT]

Adds a list box to an ASPECT dialog box, allowing a user to select one or more items from a list.

id	An integer constant, specifying the control id for the listbox. dlgevent will report this value when a listbox item is selected.

left top width height	Integer constants specifying the position and size of the list box. Coordinates are relative to the left and top edges of the dialog box, in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.

itemlist	A string variable or constant containing a list of items to display within the listbox. Each item is separated by a comma.

tabstring	An optional, comma-separated string variable or constant containing numbers in DBUs indicating column locations for tabs contained within the list. If only one tab stop is specified, the listbox will be initialized with multiple stops separated by the single tab stop value. If more than one tab stop is given, then only those tab stops will be initialized.

SINGLE strvar	Allows a single item to be selected from the list. It will be stored in strvar.

MULTIPLE strvar	Allows one or more items to be selected from the list. They will be stored in strvar, separated by commas.

HSCROLL	Scroll bars will be placed on the listbox, allowing the user to scroll the listed items horizontally. Horizontal scrolling is appropriate only for list entries which contain no tab characters.

SORT	The contents of the listbox will be displayed in alphabetical order.

Example

proc main

   string szList                       ; List of items.

   string szItem                       ; Item selected from list.

   integer Event                       ; Dialog box event.

   ; Display dialog box with list of items.

   szList = "Pen, Pencil, Paperclip, Stapler"

   dialogbox 0 55 96 100 74 11 "File List Box Example"

      listbox 1 5 5 90 40 szList single szItem sort

      pushbutton 2 28 52 40 14 "&Exit" ok default

   enddialog

   while 1

      dlgevent 0 Event                 ; Get the dialog event.

      switch Event                     ; Evaluate the event.

         case 0                        ; No event occurred.

         endcase

         case 1                        ; Something was chosen.

            usermsg "`"%s`" selected!" szItem

         endcase

         default                       ; Exit case chosen.

            exitwhile                  ; Exit the loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL                 ; Destroy the dialog box.

endproc

Comments

The listbox can only occur within a dialogbox statement group. The strvar parameter can be initialized to a specific item, causing that item to be pre-selected when the dialog box is displayed.

See also

combobox, fcombobox, dlglist, dlgupdate, dlgevent, dialogbox and flistbox; Dialog Box Commands.


locate

locate row column

Positions the terminal cursor to the location specified by row and column. Characters received from the remote system are displayed at the current cursor position.

Example

proc main

   integer Row, Col        ; Screen row and column.

   for Row = 0 upto 24     ; Loop through each row of screen.

      for Col = 0 upto 79  ; Loop through each col of screen.

         locate Row Col    ; Move cursor to ( Col, Row ).

         termwritec '*'    ; Put an asterisk at current cursor

      endfor               ; location.

   endfor

endproc

Comments

locate has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command.

If locate is executed while text is being marked in the Terminal window, however, script execution is suspended. After the marking operation is completed or cancelled, the locate command is executed and the script resumes normally.

See also

getcur; $TERMROWS, $TERMCOLS, $ROW and $COL; the set terminal command family; Terminal Commands.


long

long name[=expression][,name[=expression]]...

Defines a global or local long variable.

name	The name of the new variable. This name must follow the standard ASPECT naming conventions. When defining an array, the subscript expression must result in a constant value.

= expression	An initializing expression. It can specify operators, constants or previously-declared numeric variables, or a function which returns a numeric result. The initializing expression cannot be used when defining an array.

Example

proc main

   long FirstLong = 32768L            ; First long value.

   long SecondLong = 1L               ; Second long value.

   long Sum = FirstLong + SecondLong  ; Sum of first long and second.

   usermsg "Sum = %ld." Sum           ; Display the sum of the longs.

endproc

Comments

Up to 256 global long variables can be defined, as well as 256 global long arrays. Local long definitions are limited by the available stack space at the time the procedure or function is called. For more information, see User-defined Variables, Global and Local Variables and Arrays.

See also

integer, float, param and string; ASPECT Primary Commands.


longjmp

longjmp id integer

Returns to a location within a script previously marked with a setjmp command.

id	An integer id specifying the desired jump point previously set using setjmp.

integer	An integer value to return to the setjmp command. This value can be used in commands following setjmp for reporting or decision-making.

Example

See the example for setjmp.

Comments

The marked location is the command following the setjmp. The marked location remains active until a return from the function where it was set, or until another routine uses a setjmp with the same id value.

longjmp does not update variables passed by reference to the procedure in which the longjmp occurs, nor does it update any variables passed by reference for any procedure calls between the setjmp and longjmp commands that have not been returned.

See also

goto, return and setjmp; Script Control Commands.


loopfor

loopfor

Skips the remaining commands in the for command block, and increases or decreases the control variable in a for statement group based on the step value specified in the for command itself.

Example

proc main

   integer Num          ; Integer variable to increment.

   for Num = 0 upto 100 ; Init variable and define loop.

      if Num == 3       ; Check to see if we've looped three.

         loopfor        ; If not, return to start of loop.

      endif

      exitfor           ; Exit the FOR...ENDFOR loop.

   endfor

   usermsg "%d" Num     ; Display value of variable.

endproc

Comments

The control variable is tested to determine whether the limit has been reached. If another iteration should be performed, execution continues with the command following the for command. For further information, see the for command.

See also

for, endfor and exitfor; ASPECT Primary Commands.


loopwhile

loopwhile

Jumps to the conditional test specified in the while command. If another iteration should be performed, execution continues with the command following the while command.

Example

proc main

   integer Loops = 0          ; Integer used to count loops.

   integer Done = 0           ; Integer flag that indicates when

                              ; we're done.

   while !Done                ; Loop while flag is 0, or false.

      if (Loops++) < 3        ; Check to see if we've looped three

                              ; times, increment loop counter,

         loopwhile            ; and return to start of loop.

      endif

      Done = 1                ; Set flag to indicate completion.

   endwhile

endproc

See also

while, endwhile and exitwhile; ASPECT Primary Commands.


ltimeelapsed

ltimeelapsed timeval strvar

Converts a timeval into a time string.

timeval	A long timeval.

strvar	The resulting time string.

Example

proc main

   string PassedTime          ; String to contain elapsed time.

   ; Get the time that's passed since January 1, 1970,

   ; Midnight and display it.

   ltimeelapsed $LTIME PassedTime

   usermsg "Elapsed time, hrs/mins/secs, %s" PassedTime

endproc

Comments

ltimeelapsed can be used to convert the difference between any two timevals into a string that contains the number of hours, minutes and seconds that have elapsed between the two values. Hours can exceed 24.

For example, ltimeelapsed can be used to convert the connect time field returned by the dialstats command.

See also

dialstats; $LTIME; Date and Time Commands.


ltimeints

ltimeints timeval intvar intvar intvar intvar intvar intvar

Converts a long time/date value in system time format into integer variables containing the individual date and time values.

timeval	The timeval to convert.

intvar	The year. A four-digit integer from 1970 to 2106.

intvar	The month. An integer from 1 to 12.

intvar	The day. An integer from 1 to 31.

intvar	The hour. An integer from 0 to 23.

intvar	The minutes. An integer from 0 to 59.

intvar	The seconds. An integer from 0 to 59.

Example

proc main

   integer Month, Day         ; Integers to contain date and

   integer Year, Hour         ; time converted from long

   integer Min, Sec           ; date and time.

   string MonStr              ; String to contain month.

   ; Convert long time value into it's counter parts, year,

   ; month, day, hour, min, and sec.

   ltimeints $LTIME Year Month Day Hour Min Sec

   monthstr Month MonStr   ; Get the month in string format.

   usermsg "Month is %s and it's day %d." MonStr Day

endproc

See also

ltimestring, ltimestrs and intsltime; $LTIME; Date and Time Commands.


ltimemisc

ltimemisc timeval intvar intvar intvar

Returns miscellaneous information about a given timeval.

timeval	A long value.

intvar	Will contain an integer from 1 to 7, denoting the day of the week from 1 for Sunday through 7 for Saturday.

intvar	Will contain an integer from 1 to 365 or 366, indicating the number of the day within the current year.

intvar	Will equal 1 if the current year is a leap year; 0 otherwise.

Example

proc main

   integer LeapYear           ; Stores state of leap year.

   integer DayYear, DayWeek   ; Day of year and day of week.

   string WeekDay, Leap       ; Strings for day and leap state.

   string DayStr              ; Used to display date info.

   ; Get the day of the week, day of the year, and state of leap

   ; year. Leap year is a 0 or 1 value.

   ltimemisc $LTIME DayWeek DayYear LeapYear

   weekdaystr DayWeek WeekDay ; Get day of week in string format.

   if LeapYear                ; See if it's a leap year and if so,

      Leap = "is"             ; adjust string appropriately.

   else                       ; If it's not a leap year, do the

      Leap = "is not"         ; same.

   endif

   ; Create string containing day of week and leap year info

   ; and display it to user.

   strfmt DayStr "Today is %s, it %s a leap year." WeekDay Leap

   usermsg DayStr

endproc

See also

ltimeints. weekdaystr and monthstr; $LTIME; Date and Time Commands.


ltimestring

ltimestring timeval strvar

Converts a long value in system time format into a string variable representing date and time.

timeval	A long value.

strvar	The converted time/date string.

Example

proc main

   string DateStr               ; String to contain date.

   string LastDate              ; String to contain last date.

   ; Get date and time and check against last value. If

   ; the date and time has changed, update status

   ; line with new date and time string.

   while 1                      ; Loop forever.

      ltimestring $LTIME DateStr

      if not strcmp DateStr LastDate

         LastDate = DateStr     ; Set last date to current.

         statmsg DateStr        ; Display date on stat line.

      endif

   endwhile

endproc

Comments

The string will be formatted based on the information contained within the Long Date Format fields of the Windows Control Panel International section.

See also

ltimeelapsed, ltimeints and ltimestrs; $LTIME; Date and Time Commands.


ltimestrs

ltimestrs timeval strvar strvar

Converts a long value in system time format into two string variables representing date and time.

timeval	The timeval to convert.

strvar	The converted date.

strvar	The converted time.

Example

proc main

   string DateString, TimeString      ; Time and date strings.

   ; Convert long time into date and time, in text form,

   ; and display it on the status line.

   ltimestrs $LTIME DateString TimeString

   statmsg "%s %s" DateString TimeString

endproc

Comments

The string will be formatted based on the information contained within the Short Date and Time Format fields of the Windows Control Panel International section.

See also

ltimeints, ltimestring and strsltime; $LTIME; Date and Time Commands.


ltoa

ltoa long strvar

Converts a long to an ASCII string and stores it in a string variable.

long	The long value to convert.

strvar	Will contain the converted value.

Example

proc main

   long FileSize              ; Size of file.

   string szSize              ; Size of file as a string.

   fileget "test.txt" SIZE FileSize

   ltoa FileSize szSize       ; Convert size to a string.

   usermsg "Size of `"test.txt`" is %s." szSize

endproc

See also

atol, ftoa, itoa, strfmt and numtostr; Numeric, String Conversion Commands.


makepath

makepath strvar drive pathname filename extension

Creates a path and/or file specification from individual components.

strvar	Will contain the created pathname.

drive	A string, containing a drive letter.

pathname	The path information to include in the pathname.

filename	The filename to include in the result.

extension	The extension to include in the result.

Example

proc main

   string FileSpecStr           ; Complete file specification.

   string DriveStr              ; Drive for file specification.

   string PathStr             	; Path for file specification.

   string FileStr              	; File for file specification.

   string ExtStr                ; Extension for file spec.

   ; Set the elements of the file specification and create

   ; a full path with file name and extension.

   DriveStr = "c"               ; Set drive to the C drive.

   PathStr = "\program files\procomm plus"      ; Set the path.

   FileStr = "pw4"                	; Set name of file.

   ExtStr = "exe"                 	; Set extension of file.

   makepath FileSpecStr DriveStr PathStr FileStr ExtStr

   usermsg "%s" FileSpecStr       	; Display the file spec.

endproc

See also

addfilename, splitpath, getfilename and getpathname; DOS- or Disk-Related Commands.


mapisend

mapisend string string string string string string [FILE] string string [strvar]

Allows the user to send mail whenever the MAPI interface is loaded and accessible.

string	A string containing your mail logon ID

string	A string containing your mail password.

string	A string containing the names of the recipients of the message. Multiple recipients may be selected by separating the names with semicolons.

string	A string containing the names of the people receiving a "carbon copy" of the message.

string	A string containing the names of recipients receiving a "blind carbon copy".

string	The subject line text for the mail message.

FILE	A keyword which is used to indicate that the following string contains the name of a text file to be used as the message contents.

string	A string containing either the contents of the message or the name of a file if the FILE parameter was specified.

string	A string which allows you to attach file(s) to the message. If you attach multiple files, each filename must be separated by a semicolon.

strvar	An optional parameter which will contain a MAPI error if an error occurs.

Example

proc main

   string szLogonName = "MailUser", MailPass = "Password"

   string To = "Fred Garvin", CC = "My Boss", BCC = "", Subj = "Latest Data"

   string Message, CurrCapFile, MailError

   ; determine the name of the current Capture File

   fetch capture file CurrCapFile

   while $CARRIER                ; wait until carrier drops

   endwhile

   capture OFF                   ; Turn the Capture File off

   strfmt Message "%s" $DATE     ; Assign today's date to Message

   ; send the just finished Capture File to Fred Garvin and

   ; the Boss.  Send it as an attachment to a a Mail message

   ; with the subject of "Latest Data" a message containing

   ; today's date.

   mapisend szLogonName MailPass To CC BCC Subj Message CurrCapFile MailError

   if SUCCESS

      usermsg "Data Sent"        ; Report sent mail.

   else

      errormsg "%s" MailError    ; Report Mail error.

   endif

endproc

Comments

If you are using Microsoft Exchange, the logon name you specify must match the name of a Microsoft Exchange Profile that is currently configured on the computer. In addition, the password argument is not used, and can thus be specified as a null string.


mciexec

mciexec string

Executes a high-level multimedia command.

string	A valid multimedia command.

Example

proc main

   string WinDir = $WINPATH      ; Path to the Windows directory.

   string Wav = "quail.wav"      ; Name of the wave file to play.

   string Cmnd = "SOUND "        ; Command to issue to MCI.

   addfilename WinDir Wav        ; Add wave file to Windows path.

   strcat Cmnd WinDir            ; Add file name and path to command.

   mciexec Cmnd                  ; Execute command and play sound.

endproc

Comments

mciexec is used with multimedia commands like open, set, play and close to control a multimedia device. mciexec requires Multimedia Extension software or direct Windows multimedia support.

See Also

General Windows Commands.


mcisend

mcisend string [strvar [strvar]]

Allows you to issue an MCI command and retrieve the error message or the result of the command.

string	A valid multimedia command.

strvar	Will store any error messages that may be returned.

strvar	Will store any result message that the MCI commmand may provide.

Example

proc main

   string errorinfo, statusinfo

   if mcisend "status cdaudio mode" errorinfo statusinfo

       usermsg statusinfo                 ; display status information

   else                                   ; else command failed

       errormsg errorinfo                 ; display error information

   endif

endproc

Comments

Unlike mciexec, mcisend will not automatically display an error message; you must include coding to make the message appear.

See also

mciexec


memaddress

memaddress id longvar

Returns memory address associated with the specified memory ID.

id	The id referencing a memory block created with a memalloc command.

long	The memory address returned.

Example

Please see the example for memalloc.

Comments

The value returned by a memaddress has no other value within the ASPECT command set. It is designed so that you may reference the memory with typical standard library APIs that accept pointer arguments. It is important to note that it is the user's responsibility to ensure that no data is written outside the area allocated: doing so could likely cause GPFs or some other form of application or system corruption.

Allowing an ASPECT srcript to manipulate a memory block while a .dll or outside process is using it will produce similar results.

See Also

Memory Commands.


memalloc

memalloc id memlength [SHARED]

Allocates a block of contiguous memory for use by an ASPECT script.

id	A integer value which will be used to reference the allocated memory block.

memlength	An integer whose value is treated as an unsigned value, specifying the size, in bytes, to be allocated.

SHARED	Allows the memory block to be shared with child scripts. Child scripts, as long as the are aware of the memory block ID, can perform any file I/O operations on the SHARED memory without having to memalloc the block. It is important to note, however, that any changes to the memory block are in effect when the parent script resumes control.

Example

proc main

   integer nBytes = 255        ; Number of bytes to allocate.

   integer MemID=0             ; ID for allocated memory

   long BlockAddress           ; Address of memory block

   if memalloc MemID nBytes    ; Allocate memory and check for errors.

      usermsg "Memory successfully allocated!"

      memaddress MemID BlockAddress

      usermsg "The memory address is: %l" BlockAddress

      memfree 0                ; Free the allocated memory.

   else

      errormsg "Couldn't allocate memory!"

   endif

endproc

Comments

Use memavail to determine the amount of memory available for use. The results of the allocation can be tested with if SUCCESS.

The maximum size of a block allocated by memalloc is 64K. If more memory is required, subsequent memalloc calls can reserve other contiguous blocks.

If the id given to memalloc equals an id already in use by an existing memory block, the existing block will be destroyed and freed. The id will then reference the newly-created block.

If a size of zero is specified, memalloc will create a valid id with a block size of zero, and report SUCCESS. Because of data alignment issues, the actual size of the allocated block may be slightly larger than the specified amount. memsize will always return the actual size of the allocated block. Memory accesses are valid up to the actual size of the allocated block.

ASPECT will release unfreed memory allocated by a script, but users are advised to employ memfree to release a block when it’s no longer needed.

The allocated memory block will be uninitialized. To be certain of its contents, use the memset command.

See also

memavail, memfree, memrealloc, memread, memwrite and memset; Memory Commands.


memavail

memavail longvar

Returns the amount of contiguous free memory available for allocation, or for running other programs into a long variable.

Example

proc main

   long Mem                      ; Available memory.

   memavail Mem                  ; Get free global memory.

   usermsg "%ld Bytes Free" Mem  ; Display free memory.

endproc

See also

memalloc, memfree and memrealloc; Memory Commands.


memchr

memchr id memindex character [intvar]

Searches for the first occurrence of the specified character in an allocated memory block.

id	The id of the memory block to search.

memindex	The starting position of the search within the target memory block.

character	The desired character value. An integer value from 0 to 255 inclusive.

intvar	Will contain the position of the first occurrence of the desired character in the block.

Example

proc main

   integer Pos                   ; Location of char in memory.

   if memalloc 0 30              ; Allocate some memory.

      memwrite 0 0 "This string is in memory." 30

      if memchr 0 0 'm' Pos      ; Find 'm' in the memory.

         usermsg "'m' found at position %d" Pos

      else

         errormsg "'m' not found!"

      endif

      memfree 0                  ; Free allocated memory.

   else

      errormsg "Couldn't allocate memory!"

   endif

endproc

Comments

If the desired character is not found memchr will return FAILURE. Intvar in that case will contain the number of characters from the starting point of the search to the end of the allocated block.

See also

memalloc, memcmp, memgetc and memicmp; Memory Commands.


memcmp

memcmp id memindex id memindex memlength [intvar]

Performs a byte-by-byte comparison of two memory locations.

id	The control id of an allocated memory block.

memindex	The starting point of the comparison in the first block. An integer value, equal to the number of bytes from the start of the block.

id	The control id of an allocated memory block.

memindex	The starting point of the comparison in the second block. An integer value, equal to the number of bytes from the start of the block.

memlength	The number of bytes to compare.

intvar	Will return 1 if the first location is greater, -1 if the second is greater, and 0 if the two are equal for the length of the search.

Example

proc main

   if memalloc 0 20           ; Allocate first block.

      if memalloc 1 20        ; Allocate second block.

         memwrite 0 0 "This is a string." 20

         memwrite 1 0 "This is a ring." 20

         if memcmp 0 0 1 0 20 ; Compare memory blocks.

            usermsg "The blocks are the same!"

         else

            usermsg "The blocks are different."

         endif

         memfree 1            ; Free block 1.

      else

         errormsg "Can't allocate second block of memory."

      endif

      memfree 0               ; Free block 0.

   else

      errormsg "Can't allocate first block of memory."

   endif

endproc

Comments

Similar to the memcmp function in the "C" language, ASPECT’s memcmp compares each successive byte in the allocated block(s) until they do not have the same value or until the number of bytes specified in length have been compared. It reports SUCCESS if the comparisons were equal for the length of the test; FAILURE otherwise.

If the same id is specified for both memory block id’s, memcmp will compare data within a single block.

See also

memalloc, memicmp, memchr, memgetc, memmove, memputc, memread, memset and memwrite; Memory Commands.


memfree

memfree id

Releases a block of memory previously reserved by memalloc or memrealloc.

id	The id of the memory block to release.

Example

See the example for memalloc.

See also

memalloc and memrealloc; Memory Commands.


memgetc

memgetc id memindex intvar

Retrieves a single character from a block of memory reserved by memalloc.

id	The id of the memory block to access.

memindex	An integer value, equal to the number of bytes from the start of the block, specifying the location of the character to be read.

intvar	The value read, ranging from 0 to 255 inclusive.

Example

See the example for memputc.

See also

memalloc, memputc and memread; Memory Commands.


memicmp

memicmp id memindex id memindex memlength [intvar]

Performs a byte-by-byte, case-insensitive comparison of two memory locations.

id	The control id of an allocated memory block.

memindex	The starting point of the comparison in the first block. An integer value, equal to the number of bytes from the start of the block.

id	The control id of an allocated memory block.

memindex	The starting point of the comparison in the second block. An integer value, equal to the number of bytes from the start of the block.

memlength	The number of bytes to compare.

intvar	Will return 1 if the first location is lexigraphically greater, -1 if the second is greater, and 0 if the two are equal for the length of the search.

Example

proc main

   if memalloc 0 20               ; Allocate first block.

      if memalloc 1 20            ; Allocate second block.

         memwrite 0 0 "The quick brown fox." 20

         memwrite 1 0 "thE qUicK BrOWn foX." 20

         if memicmp 0 0 1 0 20    ; Compare memory blocks.

            usermsg "The blocks are the same!"

         else

            usermsg "The blocks are different."

         endif

         memfree 1                ; Free block 1.

      else

         errormsg "Can't allocate second block of memory."

      endif

      memfree 0                   ; Free block 0.

   else

      errormsg "Can't allocate first block of memory."

   endif

endproc

Comments

Similar to the memicmp function in the ’C’ language, ASPECT’s memicmp compares each successive byte in the allocated block(s) until they do not have the same value or until the number of bytes specified in length have been compared. It reports SUCCESS if the comparisons were equal for the length of the test; FAILURE otherwise.

If the same id is specified for both memory block id’s, memicmp will compare data within a single block.

See also

memalloc, memcmp, memset and stricmp; Memory Commands.


memmove

memmove id memindex id memindex memlength

Copies characters from one location to another, either between different blocks of memory or within the same block.

id	The destination memory block id.

memindex	The starting point of the memmove into the destination block. An integer value, equal to the number of bytes from the start of the block.

id	The source memory block id.

memindex	The starting point of the memmove from the source block. An integer value, equal to the number of bytes from the start of the block.

memlength	The number of characters to move.

Example

proc main

   integer NumBytes                     ; Number of bytes to allocate.

   string TextStr                       ; Text to move in memory.

   TextStr = "Much ado, indeed."        ; Assign text to string variable.

   strlen TextStr NumBytes              ; Get length of string.

   if memalloc 0 NumBytes               ; Allocate first memory block.

      if memalloc 1 NumBytes            ; Allocate second memory block.

         memwrite 0 0 TextStr NumBytes  ; Write text into memory.

         memmove 1 0 0 0 NumBytes       ; Move text from first to second.

         memread 1 0 TextStr NumBytes   ; Read text from memory.

         usermsg TextStr                ; Display text.

         memfree 1                      ; Free second memory block.

      else

         errormsg "Couldn't allocate second memory block!"

      endif

      memfree 0                         ; Free first memory block.

   else

      errormsg "Couldn't allocate first memory block!"

   endif

endproc

Comments

If the source and destinations overlap, the source is copied before it is overwritten. To clear a memory location, use the memset command.

See also

memalloc, memgetc, memset and memwrite; Memory Commands.


memputc

memputc id memindex character

Writes a single character to a location within a memory block allocated by memalloc.

id	The id of the memory block to access.

memindex	An integer value, equal to the number of bytes from the start of the block, specifying the location of the character to be written.

character	The value to write, either a character constant or an integer ranging from 0 to 255 inclusive.

Example

proc main

string Ch, NewString, OldString

integer NumChars, Byte, Index

   sdlginput "Information" "Enter a string:" OldString

   strlen OldString NumChars	;Get the length of OldString

   if memalloc 0 NumChars	;Allocate memory

      for Index=0 upto NumChars-1	;Loop through OldString

         strgetc OldString Index Byte   ;Get a character from the string

         memputc 0 Index Byte	;Write it to memory

      endfor

      for Index=NumChars-1 downto 0	;Loop through the memory backwards

         memgetc 0 Index Byte	;Get the byte

         strfmt Ch "%c" Byte	;Convert it to a character

         strcat NewString Ch	;Add it to NewString

      endfor

      usermsg NewString	;Print out new string

   else

      errormsg "Couldn't allocate memory!"

   endif

endproc

See also

memcmp, memgetc, memputc, memread, memset and memwrite; Memory Commands.


memread

memread id memindex numvar | {strvar strlength}

Reads a block of data from an allocated memory block.

id	The id of the memory block to access.

memindex	An integer value, equal to the number of bytes from the start of the block, specifying the location of the data to be read.

numvar	A float, integer, or long variable.

strvar strlength	A string variable, with a specified number of characters to be read.

Example

See the example for memwrite.

Comments

ASPECT automatically determines the number of bytes to be read if a numeric variable is specified for memread. An integer argument will cause 4 bytes to be read from the block; a long will read 4 bytes; a float 8 bytes. A string will read the number of bytes specified in strlength.

See also

memalloc, memgetc and memwrite; Memory Commands.


memrealloc

memrealloc id memlength

Changes the size of a block of memory previously reserved by memalloc.

id	The id of the target memory block.

memlength	A value specifying the new size of the block. If zero is specified, memrealloc will adjust the block size accordingly and report SUCCESS.

Example

proc main

   integer ByteNum = 1                  ; Number of bytes to allocate.

   string TextStr = "Flowers"           ; String to write to memory.

   if memalloc 0 ByteNum                ; Allocate memory, check for errors.

      strlen TextStr ByteNum            ; Oops - we need more space!

      if memrealloc 0 ByteNum           ; Reallocate for more space.

         memwrite 0 0 TextStr ByteNum   ; Write text to memory.

      else

         errormsg "Couldn't reallocate memory."

      endif

      memfree 0                         ; Free memory.

   else

      errormsg "Couldn't allocate memory!"

   endif

endproc

Comments

If the id of the block does not exist, that is, if a block was not previously reserved with this id using memalloc, the memrealloc command will behave exactly like memalloc. A new block of memory will be reserved and given the id value for identification.

memrealloc will report FAILURE if insufficient memory is available to accomodate an expansion. The target memory block will still be valid, with its original size intact.

See also

memalloc, memavail and memfree; Memory Commands.


memset

memset id memindex character memlength

Initializes a block of memory to a specified value.

id	The id of the target memory block.

memindex	An integer value, equal to the number of bytes from the start of the block, specifying the starting position of memset operation.

character	An integer value from 0 to 255 inclusive, specifying the value to set.

memlength	The number of character positions to set.

Example

proc main

   integer ByteNum = 30        ; Number of bytes to allocate.

   if memalloc 0 ByteNum       ; Allocate memory to store text.

      memset 0 0 0 ByteNum     ; Clear bytes in the area to nulls.

      memfree 0                ; Free allocated memory.

   else

      errormsg "Couldn't allocate memory."

   endif

endproc

Comments

memset is useful in initializing a freshly memallocated block, or in resetting a block for new operations.

See also

memalloc, memmove, memread and memwrite; Memory Commands.


memsize

memsize id intvar

Reports the size of a memory block allocated with memalloc. It can be used to find the size of a block before read or write operations are performed.

id	The id of the target memory block.

intvar	The size in bytes of the allocated block, represented as an unsigned integer value.

Example

proc main

   integer ByteNum                      ; Number of bytes allocated.

   if memalloc 0 255                    ; Allocate a block of memory.

      memsize 0 ByteNum                 ; Get size of block 0.

      usermsg "Size of memory block is %d." ByteNum

      memfree 0                         ; Free the block of memory.

   else

      errormsg "Couldn't allocate memory."

   endif

endproc

See also

memalloc, memavail, memfree and memrealloc; Memory Commands.


memwrite

memwrite id memindex number | {string strlength}

Writes a block of data to an allocated memory block.

id	The id of the target memory block.

memindex	An integer value, equal to the number of bytes from the start of the block, specifying the starting position of memwrite operation.

number	A float, integer, or long constant or variable to be written.

string strlength	A string variable, with a specified number of characters to be written.

Example

proc main

   integer ByteNum                   ; Number of bytes to allocate.

   string TextStr                    ; Text to write to / from memory.

   TextStr = "String Variable."      ; Assign text to string variable.

   strlen TextStr ByteNum            ; Get length of string.

   if memalloc 0 ByteNum             ; Allocate memory to store text.

      memwrite 0 0 TextStr ByteNum   ; Write string to memory.

      memread 0 0 TextStr ByteNum    ; Read string from memory.

      usermsg TextStr                ; Display text.

      memfree 0                      ; Free allocated memory.

   else

      errormsg "Couldn't allocate memory!"

   endif

endproc

Comments

ASPECT automatically determines the number of bytes to be written if a numeric constant or variable is specified for memwrite. An integer argument will cause 4 bytes to be written to the block; a long will write 4 bytes; a float 8 bytes. A string writes the number of bytes specified in strlength.

See also

memalloc, memputc, memset and memread; Memory Commands.


menubar

menubar intvar

Creates a new script menu bar.

intvar	Use the value returned to this variable with the menupopup and menuitem commands to place menus on the bar and the menushow command to display the completed menu bar when all menu popups and menu items have been added to it.

Example

integer UsingMenu=1

proc main

         DrawMenu()

         while UsingMenu

            when $ASPMENU call MenuHandler

            endwhile

endproc

proc DrawMenu

         integer NewMenu, DirMenu

         string MenuItems[5]

         MenuItems[0]="&Hangup", MenuItems[1]="Terminal &Frame"

         MenuItems[2]="&Directory", MenuItems[3]="&Open New Directory"

         MenuItems[4]="E&xit Script"

         menupopup $pwmenubar "&Test" NewMenu

            menuitem NewMenu 11 MenuItems[0]

            menuitem NewMenu 12 MenuItems[1]

            menuitem NewMenu separator

            menupopup NewMenu "&Directory Functions" DirMenu

               menuitem DirMenu 13 MenuItems[2]

               menuitem DirMenu 14 MenuItems[3]

               menuitem NewMenu separator

               menuitem NewMenu 15 MenuItems[4]

         menushow $pwmenubar

endproc

proc MenuHandler

         integer Selected, Status

         Selected = $ASPMENU

         switch Selected

            case 11

               hangup

            endcase

            case 12

               menustate ASPMENU 12 Status

               if Status==0

                  menucheck 12 ON

                  set terminal frame ON

               else

                  menucheck 12 OFF

                  set terminal frame OFF

               endif

            endcase

            case 13

               termkey ALT 'D'

            endcase

            case 14

               termkey ALT 'F'

               termkey 'O'

            endcase

            case 15

               UsingMenu=0

            endcase

         endswitch

endproc

Comments

Any number of menu bars can be created from a script. When the script terminates, existing menu bars it generated will be destroyed automatically.

menupopup and menuitem can be used to attach new items to Procomm Plus’s default menu bar. These items will automatically be destroyed when the script that created them is terminated.

If you have created a menu bar, it will remain available when you chain or execute another script.

See also

menupopup, menuitem and menushow; $PWMENUBAR; Menu Commands.


menucheck

menucheck integer OFF | ON

Places or removes a check mark on a menu item created by an ASPECT script.

integer	The menu item to be checked or unchecked. This is the same value used in creating the menu item.

Example

See the example for menubar.

Comments

A menu pop-up, or an item on the menu bar itself cannot be checked.

The menucheck command only works for a currently displayed menu item that was created by an ASPECT script.

See also

menubar and menuitem; Menu Commands.


menuitem

menuitem integer {integer string [string]} | SEPARATOR

Adds an item to a menu pop-up or menu bar.

integer	The integer value, previously returned from a menubar, menupopup, or menupopupid command, identifying the menu upon which the item is placed.

integer	The id value of the new menu item. Valid ids can range from 1 up to 299. The id is returned in $ASPMENU when the menu item is selected by the user.

string	The menu item text.

string	If specified, will be displayed on the status line as help text whenever the menu item is highlighted.

SEPARATOR	Adds a menu separation line. A separator does not require an id.

Example

See the example for menubar.

Comments

menuitem allows an ampersand ("&") to precede the "accelerator" character on a menu. The character will be displayed with an underscore in the menu, indicating that the user can hold down the <Alt> key and press this character to select the item from the menu. However, the ampersand should not precede a numeric character. If the ampersand is not specified, Windows defaults to the first character of the menu text as the accelerator key.

Created menu items remain available when you chain or execute another script.

See also

disable, enable, menubar, menucheck, menupopup, menupopupid, menushow, menustate, menuselect and when $ASPEMENU, $ASPMENU; Menu Commands.


menuitemcount

menuitemcount integer intvar

Returns the number of items on a menu bar or pop-up menu.

integer	The ID of the menu pop-up to be counted.

intvar	The returned number of items on the menu.

Example

proc main

   integer MenuID                      ; ID of the menu

   integer PopupID                     ; ID of the pop-up menu

   integer Count                       ; number of items on the menu

   menubar MenuID                      ; create a menu

   menuitem MenuID 1 "&Test"           ; add an item

   menupopup MenuId "&Popup" PopupID   ; add a pop-up menu

   menushow MenuID                     ; display the menu

   menuitemcount MenuID Count          ; count the items on the menu

   ; display a message

   usermsg "There are %d items on the menu" Count

endproc

Comments

The returned value can be used to assist in enumerating pop-up menus using menupopupid. Menu Item separators, the bars that separate two menu items, are included in the count.

See Also

menubar, menuitem, menupopup, menuselect,Menu Commands.


menupopup

menupopup integer string [string] intvar

Adds a pop-up menu to an existing pop-up menu or menu bar.

integer	Identifies the menu or menus to which the new menu will be added. This value is taken from a previous menubar, menupopup, or menupopupid command. The $PWMENUBAR system variable contains the menu bar id currently used by Procomm Plus. Several pop-up menu ids are reserved by Procomm Plus and may not be used; for details, see the menuitem command.

string	The menu text.

string	If specified, will be displayed on the Procomm Plus status line as help text for the menu pop-up.

intvar	The id value of the new menu.

Example

See the example for menubar.

Comments

"Nested" menus can be built by adding multiple pop-up menus atop one another. Simply use the integer variable returned from menupopup, or one of Procomm Plus’s predefined menu pop-up ids as the integer value when creating nested popups.

menupopup allows an ampersand ("&") to precede the "accelerator" character on a menu. The character will be displayed with an underscore on the menu, indicating that the user can hold down the <Alt> key and press this character to select the item from the menu. However, the ampersand should not precede a numeric character. If the ampersand is not specified, Windows defaults to the first character of the menu text as the accelerator key.

If you have created any menu pop-ups, they will remain available when you chain or execute another script.

See also

menubar, menuitem, menupopupid, and menushow; $PWMENUBAR; Menu Commands.


menupopupid

menupopupid integer integer intvar

Returns the menu ID of a pop-up menu on a menu bar or other pop-up menu.

integer	The owner menu ID.

integer	The position on that menu where the pop-up is located.

intvar	The returned ID of the menu pop-up.

Example

proc main

   integer MenuID                         ; ID of menu

   integer PopupID                        ; ID of pop-up menu

   integer PopupID2                       ; Another pop-up menu ID

   menubar MenuID                         ; create a menu

   menuitem MenuID 1 "&Test"              ; add an item to the menu

   menupopup MenuId "&Popup" PopupID      ; add a pop-up item to the menu

   menushow MenuID                        ; display the menu

   menupopupid MenuID 1 PopupID2          ; determine the ID of the pop-up in position 1 (0 based)

   usermsg "The Pop-Up has an id of %d." PopupID2   ; display a message

endproc

Comments

If there is no pop-up at the corresponding position (the second integer), Success/Failure is set, and 0 (zero) is returned to the intvar.

See also

menupopup, menushowpopup, Menu commands.


menuselect

menuselect ASPMENU | PWMENU integer

Selects a Procomm Plus or ASPECT menu item.

ASPMENU | PWMENU	Specifies whether the menu item to be selected originates from a script or from Procomm Plus itself.

integer	The id of the menu item to be selected.

Example

#include "pw4menu.inc"         ; Include file of menu macros.

proc main

   menuselect PWMENU _4SETUP   ; Select setup window option.

endproc

Comments

Comments

Procomm Plus’s menu items can be selected even when a different menu bar is displayed, but menu items created by an ASPECT script must be displayed in order to be selected. A menu item cannot be selected when it is disabled. You cannot retrieve the state of a menu pop-up or an item on the menu bar itself.

Procomm Plus’s main window must have the input focus for menuselect to be used.

Two useful files are provided with Procomm Plus that can be #included into your scripts. These files are pw4menu.inc, which defines all of Procomm Plus’s menu values, and vkeys.inc, which defines the virtual key codes as shown in Virtual Key Codes. Both of these files are installed to the default ASPECT directory.

See also

menuitem and menucheck; Menu Commands.


menushow

menushow integer | PWMENU

Displays the menu bar corresponding to the specified menu bar id value. menushow can be used to display updates to the current menu bar.

integer	Identifies the menu bar to show. This value is taken from a previous menubar command. The $PWMENUBAR system variable contains the menu bar id currently used by Procomm Plus.

If the value is 0, the current menu bar will be removed.

PWMENU	If specified, the default Procomm Plus menu bar will be restored.

Example

See the example for menubar.

See also

menubar, menuitem, menupopup and when $ASPMENU; Menu Commands.


menushowpopup

menushowpopup integer integer integer LEFT | CENTER | RIGHT LEFT | RIGHT

Displays a floating pop-up menu.

integer	The pop-up menu ID.

integer	Ths X screen coordinate for the menu.

integer	The Y screen coordinates for the menu.

LEFT	The left side of the pop-up menu is aligned with the specified X screen coordinate.

CENTER	The pop-up menu is centered relative to the specified X screen coordinate.

RIGHT	The right side of the pop-up menu is aligned with the specified X screen coordinate.

LEFT | RIGHT	Specifies which mouse button is tracked for the menu item selection.

Example

proc main

   integer PopupID                        ; ID of pop-up menu

   integer Selected                       ; Menu item selected

   menupopup 0 "" PopupID                 ; create a floating pop-up menu

   menuitem PopupID 1 "Hello World"       ; add an item to the menu

   menuitem PopupID 2 "Goodbye"           ; add another item

   menushowpopup PopupID 100 100 CENTER LEFT   ; display the menu

   Selected = $ASPMENU                    ; determine which item the user selected

   if Selected == 1                       ; item number 1 was selected

      usermsg "Hello World"               ; display a message

   endif

   if Selected == 2                       ; item number 2 was selected

      usermsg "Goodbye"                   ; display a message

   endif

endproc

See Also

menuitem, menupopup, menupopupid, $ASPMENU;Menu Commands.


menustate

menustate ASPMENU | PWMENU integer intvar

Reports the state of a Procomm Plus or ASPECT menu item.

ASPMENU | PWMENU	Specifies whether the menu item originates from a script or from Procomm Plus itself.

integer	The id of the menu item to be tested; a variable or constant.

intvar	A bitflag value, with the following possible values: 0x01 for grayed, 0x02 for disabled or 0x04 for checked.

Example

#include "pw4menu.inc"                 ; Include file of menu macros.

proc main

   integer State                       ; State of menu item.

   menustate PWMENU _4ICOLABELS State

   if State == 0                       ; See if ToolTips are off.

      usermsg "ToolTips are OFF."

   else

      usermsg "ToolTips are ON."

   endif

endproc

Comments

If the menu item was generated by an ASPECT script, menustate will only work if the menu item is currently displayed. Procomm Plus’s menu items, on the other hand, can be tested whether they’re displayed or not. When a menu item is grayed, it is disabled by default. You cannot test the state of a menu pop-up, or an item on the menu bar itself.

Two useful files are provided with Procomm Plus that can be #included into your scripts. These files are pw4menu.inc, which defines all of Procomm Plus’s menu values, and vkeys.inc, which defines the virtual key codes as shown in Virtual Key Codes. Both of these files are installed to the default ASPECT directory.

See also

menuitem, menubar, menupopup, menucheck and menuselect; Menu Commands.


metafile

metafile id left top width height filespec

(or) metafile id left top width height filespec BACKGROUND | USERWIN

Displays a Windows metafile (.wmf) or enhanced metafile (.emf) graphic within a User window or dialog box. metafile can only be tested for SUCCESS/FAILURE when it appears in a User window.

Dialog box format

metafile id left top width height filespec

id	A unique integer constant value given to the metafile, used by the dlgupdate command to refresh the metafile.

left top	Integer constants which determine the top left corner position of the metafile with respect to the top left corner of the dialog box. Values are in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.

width height	The metafile display size integer constants. Values are expressed in DBUs.

filespec	String constant or variable specifying the name of the metafile to display. If a path is not given, the default Aspect Path is assumed.

Example

proc main

   ; Display dialog box and show metafile. You need to create

   ; a metafile called "dolphin.wmf" for this example.

   dialogbox 0 0 0 100 50 11 "Metafile Example"

      metafile 1 5 5 90 40 "dolphin.wmf"

   enddialog

   pause 5           ; Show off the dialog box.

endproc

See also

bitmap, dialogbox, dlgevent, dlgupdate, icon, and iconbutton; Dialog Box Commands.

User Window form

metafile id left top width height filespec BACKGROUND | USERWIN

id	A unique integer value given to the metafile, used by the objremove command to remove the metafile.

left top	Integer values which determine the top left corner position of the metafile with respect to the top left corner of the User window or background graphic. Values are in User Window units or UWUs. For more information on UWUs, see User Window Units.

width height	The metafile display size in UWUs.

filespec	String constant or global variable specifying the name of the metafile to display in the window. If a path is not given, the current Aspect Path is assumed.

USERWIN | BACKGROUND	Specify USERWIN to "fix" the top left corner of the metafile in position relative to the upper left corner of the User window. If BACKGROUND is specified, the metafile stays over the same spot on the background graphic; if the size of the background graphic changes, the metafile will also change in proportion.
Example

proc main

         ; Display a user window and a metafile called "bkgrnd.wmf".

         uwincreate FULL SCREEN 100 255 255 255 BITMAP

         metafile 1 500 500 9000 9000 "bkgrnd.wmf" USERWIN

         uwinpaint                  ; Paint the user window.

         pause 5                    ; Show off the metafile.

         uwinremove                 ; Destroy the user window.

endproc

Comment

Metafiles are usually identified with a .wmf extension, and these files must contain the placeable metafile format that is typical within Windows. Enhanced metafile format files, usually identified with a .emf extension, are also supported.

The User window must exist before a metafile can be displayed. The uwinpaint command must be issued to display User window changes.

A metafile cannot be selected by mouse click. The metafile will fill the rectangle defined by the width and height values, but the aspect ratio will not be automatically maintained.

See also

uwincreate, uwinpaint, objpaint, objcoord, objpointid, objremove, metafilebkg, bitmap, hotspot, icon, iconbutton, pushbutton, dllobject and when $OBJECT; User Window Commands.


metafilebkg

metafilebkg CENTER | LEFT | RIGHT CENTER | TOP | BOTTOM
SCALE | EXACT filespec

Places a Windows metafile or enhanced metafile background in the User window.

CENTER | LEFT | RIGHT	The horizontal position of the metafile background with respect to the User window. If the User window is based on the total screen size in pixels rather than the Terminal window and the metafile is larger than the User window, the metafile will be clipped to fit.

CENTER | TOP | BOTTOM 	The vertical position of the metafile background with respect to the User window.

SCALE | EXACT	Determines how the background will appear. If set to SCALE, Procomm Plus displays the graphic using arbitrarily scaled axis and the image will be stretched or squeezed to fill the entire image area. This is called anisotropic mapping.

If set to EXACT, the original graphic’s height and width ratio is maintained, which preserves the exact shape of the image. Because of this ratio, the image may not fill the entire User window. This is called isotropic mapping.

filespec	The name of the metafile to display as the background. If a path is not specified, the current Aspect Path is assumed.

Example

proc main

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   metafilebkg CENTER CENTER SCALE "Background.wmf"

   uwinpaint            ; Paint the user window.

   pause 5              ; Show off the background.

   uwinremove           ; Destroy the user window.

endproc

Comments

Metafiles are usually identified with a .wmf extension, and these files must contain the placeable metafile format that is typical within Windows. Enhanced metafile format files, usually identified with a .emf extension, are also supported.

See also

bitmapbkg, uwincreate, uwinpaint, uwinremove and metafile; User Window Commands.


metakey

metakey ALT | ALTSHIFT | ALTCTRL | ALTCTRLSHIFT integer

Executes the specified Meta key.

integer	An integer value from 0 to 9, designating the metakey to execute.

Example

proc main

   metakey ALTCTRLSHIFT 1  ; Execute the ALTCTRLSHIFT 1 meta key.

endproc

Comments

Use the set metakeyfile command to load individual keyboard metakey files. Issue the statement set aspect spawn ON before the metakey command if the desired metakey is defined to run a script file.

set metakeys can be used to control display of the Meta Keys.

See also

termkey; set metakeyfile, set metakeys and set aspect spawn; General Procomm Plus Commands.


mkdir

mkdir pathname

Creates a new directory using a path and/or directory name you provide.

pathname	The desired path or directory name. If a pathname is not provided, the User Path is assumed for the default directory.

Example

proc main

   string NwDir = "TEMP"         ; Temporary directory to create.

   string Fname = "DEL.ME"       ; File to create in temporary dir.

   mkdir NwDir                   ; Create new directory.

   chdir NwDir                   ; Change to the new directory.

   if fopen 0 Fname CREATE       ; Create the temporary file.

      fputs 0 "Temporary"        ; Put something in temporary file.

      fclose 0                   ; Close the file.

   else

      errormsg "Couldn't create `"%s`"." Fname

   endif

endproc

See also

chdir, getdir and rmdir; $USERPATH; set aspect path; DOS- or Disk-Related Commands.


monthstr

monthstr integer strvar [SHORT]

Returns the name of the specified month.

integer	A value from 1 to 12.

strvar	Will contain the name of the month.

SHORT	If specified, the returned name will be abbreviated.

Example

proc main

   string DateStr                ; String to contain date.

   string Month                  ; String to contain month.

   integer MonthNum              ; Integer to contain month.

   DateStr = $DATE               ; Assign date to string variable.

   substr Month DateStr 0 2      ; Extract month from date.

   atoi Month MonthNum           ; Convert month string to integer.

   monthstr MonthNum Month       ; Get the month in string form.

   usermsg "It is the month of %s." Month

endproc

See also

ltimeints, ltimestring, ltimestrs and weekdaystr; $LTIME; Date and Time Commands.


mspause

mspause integer

Pauses script execution for the specified number of milliseconds.

Example

proc main

   integer Count = 0          ; Integer used for counting.

   while (Count++) < 3        ; Loop 3 times.

      transmit "^M"           ; Transmit a carriage return.

      mspause 250             ; Pause script for 250 ms.

   endwhile

endproc

Comments

Unlike the pause command, mspause can’t be aborted with the <Ctrl><Break> key sequence. The delay has a maximum length of 1000 milliseconds. The number of milliseconds specified is subject to a 55 millisecond granularity.

See also

pause; General Procomm Plus Commands.


nexttask

nexttask intvar

Returns subsequent in tasks in the Windows Task List after the execution of a firsttask command.

intvar	The task id.

Example

See the example for firsttask.

Comments

The firsttask and nexttask commands return ids only for those tasks that have a top-level window with a caption containing text. Since certain special tasks running in Windows may not meet these requirements, they will not be enumerated. Therefore, the number of tasks returned may be less than that indicated by the $NUMTASKS system variable. A return value of 0 indicates there are no further tasks to enumerate.

Note that the number of tasks enumerated is current with respect to the last firsttask command. If your script doesn’t make use of this information quickly, the number of tasks could easily change!

See also

firsttask, taskname and taskpath; $NUMTASKS and $TASK; Task/Window Manipulation Commands.


nullstr

nullstr string [intvar]

Tests a string variable for the null or empty condition.

string	The string to test.

intvar	If specified, will be updated to 1 if the string is null or 0 if the string is not null.

Example

proc main

   string TextStr             ; String for text entry.

   transmit "Name? "          ; Ask remote user for some information.

   rget TextStr 30            ; Get some text from the remote user.

   if nullstr TextStr         ; Check to see if text is null.

      transmit "^M^J^M^JYou must enter a valid Name!^M^J"

   endif

endproc

Comments

A null string is one whose first character has the value 0 (zero). nullstr is more commonly used as an expression for if/while/elseif statements.

See Also

String Commands.


numtostr

numtostr number strvar [integer]

Converts a numeric value to a string.

number	A float, integer or long value to convert.

strvar	The result of the conversion.

integer	If specified, the base value of the number to be converted. The base value can range from 2 up to 36. The letters ’A’ to ’Z’ are used to represent digits above 9 for bases greater than 10.

Example

proc main

   integer Number = 137           ; Decimal number.

   string BinaryNum               ; Binary form of number.

   numtostr Number BinaryNum 2    ; Convert number to base 2.

   usermsg "%s" BinaryNum         ; Display the binary number.

endproc

Comments

The optional base type is not allowed for floating-point conversions. The default base is 10.

See also

ftoa, itoa, ltoa, strfmt and strtonum; Numeric, String Conversion Commands.


objcoord

objcoord id intvar intvar UWUS | PIXELS

Returns the location coordinates of a User window object.

id	The control id given to the target object when it was defined in the uwincreate block.

intvar intvar	Will be updated to values reflecting the top left corner position of the button with respect to the top left corner of the User window or background graphic, depending on how the object was created.

UWUS	If specified, the integer values are interpreted as relative to the top left corner of the background graphic or User Window depending on how the object was created. For more information on UWUs, see User Window Units.

PIXELS	If specified, the integer values are treated as absolute User window pixel coordinates, with no relative conversions applied. The 0,0 pixel is defined as the top left corner of the User window.

Example

proc main

   integer nLeft, nTop           ; Coordinates of userwin object.

   integer Count                 ; Used in the loop below.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

      bitmap 1 500 500 "" "button.bmp" USERWIN

   uwinpaint                     ; Paint the user window.

   objcoord 1 nLeft nTop UWUS    ; Get coordinates of object.

   while (Count++) < 300         ; Loop for count of 300.

      nTop += 10                 ; Inc Y position of object.

      objmove 1 nLeft nTop UWUS  ; Move object down screen.

   endwhile

   uwinremove                    ; Remove the user window.

endproc

Comments

The objcoord command returns the x and y (left and top) coordinates of the object with the corresponding id. The coordinates are relative to the User window, and are the same type of coordinates as returned by $LMOUSEX, $LMOUSEY, $RMOUSEX and $RMOUSEY.

ojbcoord returns FAILURE if the target object is currently hidden. If objcoord fails, no coordinate values are returned.

See also

objmove; $LMOUSEX, $LMOUSEY, $RMOUSEX and $RMOUSEY; User Window Commands.


objhide

objhide startid [endid]

Hides a User window object, or a range of objects.

startid	The id of the target object.

endid	If specified, all objects whose ids are in the range of startid and endid will be hidden. If startid is greater than endid, a run-time error will occur.

Example

proc main

   integer Count = 0          ; Used in loop.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

      bitmap 1 500 500 "" "button.bmp" USERWIN

   uwinpaint                  ; Paint the user window.

   while (Count++) < 5        ; Loop for count of 5.

      objhide 1               ; Hide the bitmap.

      pause 1                 ; Pause for effect.

      objshow 1               ; Show the bitmap.

      pause 1                 ; Pause for effect.

   endwhile

   uwinremove                 ; Remove the user window.

endproc

Comments

objhide removes an object from the User window display, and prevents repaints of that object until it is shown using objshow. objshow will repaint an object immediately, even if it was not hidden. objpaint cannot paint a hidden object.

A User window event will not be generated if the user clicks within the region where a hidden object currently resides.

An object can be made to "blink" by creating a loop cycling objshow and objhide.

See also

objshow; User Window Commands.


objmove

objmove id left top UWUS | PIXELS [NOPAINT]

Moves a User window object identified by an id number to a new location in the User window.

id	The control id given to the target object when it was defined in the uwincreate block.

left top	Integer values which determine the new top left corner position of the button with respect to the top left corner of the User window or background graphic, depending on how the object was created.

UWUS	If specified, the integer values are interpreted as relative to the top left corner of the background graphic or User Window depending on how the object was created. For more information on UWUs, see User Window Units.

PIXELS	If specified, the integer values are treated as absolute User window pixel coordinates. No relative conversions are applied. The 0,0 pixel is defined at the top left corner of the User window.

NOPAINT	An optional parameter which prevents the redisplay of the moved object until an objpaint command is executed.

Example

proc main

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

      bitmap 1 500 500 "" "button.bmp" USERWIN

   uwinpaint                      ; Paint the user window.

   pause 2                        ; Show off the bitmap.

   objmove 1 0 0 PIXELS NOPAINT   ; Move the bitmap object.

   uwinpaint                      ; Repaint user window.

   objpaint 1                     ; Paint object in new location.

   pause 5                        ; Pause for effect.

   uwinremove                     ; Destroy the user window.

endproc

Comments

By default, the object is repainted when it’s moved. Use objremove to remove the object from the User window.

When NOPAINT is specified, the object will still be visible in its old location. If the User window is re-sized or repainted, any objects which were moved but not repainted may be painted in their new locations. Unless the window is entirely repainted, the objects in their old locations may still appear on the display. To prevent this, use objhide to hide the object being moved until a repaint of the moved object is reasonable.

See also

uwincreate, objhide, objpaint and objremove; User Window Commands.


objpaint

objpaint [startid] [endid]

Updates the User window and some or all of the objects it contains. objpaint should be used to update the display after any change to a User window object.

startid	The id of the window object to paint.

endid	If specified, all objects whose ids range between startid and endid will be painted. If startid is greater than endid, a run-time error will occur.

Example

proc main

   string sBMPfile                        ; bitmap to display

   string sBMPfspec                       ; Search string

   strfmt sBMPfspec "%s\*.bmp" $WINPATH   ; set search string to windows directory

   findfirst sBMPfspec                    ; find the first bmp file in the windows directory

   if SUCCESS                             ; if one is found

      strfmt sBMPfile "%s\%s" $WINPATH $FILENAME                  ; set the bitmap filename

      uwincreate full window 100 255 255 255 bitmap               ; create a user window

         bitmap 100 500 500 "Click here to exit" sBMPfile userwin ; place a bitmap

      uwinpaint                                                   ; paint the window

      when $OBJECT call BitmapClick

      pause 1

      findnext                                                    ; find the next file

      while SUCCESS                                               ; while there is another file

         strfmt sBMPfile "%s\%s" $WINPATH $FILENAME               ; set the bitmap filename

         objremove 100                                            ; remove the old bitmap

         uwinpaint                                                ; repaint the window

         bitmap 100 500 500 "Click here to exit" sBMPfile userwin ; draw a new bitmap

         objpaint 100                                             ; display the bitmap

         pause 1                                                  ; pause for effect

         findnext                                                 ; find the next file

      endwhile

   endif

endproc

proc BitmapClick                                                  ; when the user clicks on the bitmap

   integer Response

   sdlgmsgbox "Windows backgrounds" "Would you like to quit?" STOP YESNO Response

   if Response == 6                                               ; if the user answered yes

      exit                                                        ; end the program

   endif

endproc

See also

uwincreate, objcoord, objpointid, objhide, objmove, objshow, and objremove; User Window Commands.


objpointid

objpointid integer integer intvar UWUS | PIXELS

Returns the object id, if any, of an object located at a specified point.

integer	The X-User window coordinate desired.

integer	The Y-User window coordinate desired.

intvar	Will be updated with the object id of an object located at the given coordinates, if one exists.

UWUS	If specified, the integer values are interpreted as relative to the top left corner of the background graphic or User Window depending on how the object was created. For more information on UWUs, see User Window Units.

PIXELS	If specified, the integer values are treated as absolute User window pixel coordinates, with no relative conversions applied. The 0,0 pixel is defined at the top left corner of the User window.

Example

proc main

   integer ObjectId              ; Id of object under pointer.

   uwincreate FULL SCREEN 100 255 255 255 METAFILE

      bitmap 1 500 500 "" "button.bmp" USERWIN

   ; set $LMOUSEX and $LMOUSEY ref. coordinates to the user window.

   set aspect mousecoord $USERWIN

   uwinpaint                     ; Paint the new user window.

   while 1

      objpointid $LMOUSEX $LMOUSEY ObjectId PIXELS

      if ObjectId == 1           ; See if cursor is over bitmap.

         usermsg "Cursor over bitmap!"

         exitwhile               ; Exit the while loop.

      endif

   endwhile

   uwinremove                    ; Destroy the user window.

endproc

Comments

objpointid returns FAILURE if the specified coordinates are not contained by a User window object, or if the point is contained by a hidden object.

See also

uwincreate, objcoord, objpaint, objhide, objmove, objshow, and objremove; User Window Commands.


objremove

objremove startid [endid]

Removes one or more User window objects. However, objpaint must be used to update the display after the objects are removed.

startid	The id of the window object to remove.

endid	If specified, all objects whose ids range between startid and endid will be removed. If startid is greater than endid, a run-time error will occur.

Example

proc main

   uwincreate FULL SCREEN 100 255 255 255 METAFILE

      metafile 1 500 500 9000 9000 "mars.wmf" USERWIN

   uwinpaint               ; Paint the user window.

   pause 2                 ; Show off the metafile file.

   objremove 1             ; Remove the metafile.

   uwinpaint               ; Repaint the user window.

   pause 5                 ; Show off the user window.

   uwinremove              ; Destroy the user window.

endproc

See also

uwincreate, objcoord, objpointid, objhide, objmove, objshow, objremove, objpaint, icon, iconbutton, metafile, bitmap, pushbutton, bitmapbkg, dllobject, metafilebkg, and hotspot; User Window Commands.


objshow

objshow startid [endid]

Displays an object previously hidden with objhide.

startid	The id of the window object to show.

endid	If specified, all objects whose ids range between startid and endid will be shown. If startid is greater than endid, a run-time error will occur.

Example

See the example for objhide.

Comments

objshow will repaint an object immediately, even if it was not previously hidden. An object can be made to "blink" by creating a loop cycling objshow and objhide.

See also

uwincreate, objcoord, objpointid, objhide, objmove, objpaint and objremove; User Window Commands.


oemtoansi

oemtoansi {character intvar} | {string strvar [strlength]}

Converts an OEM character or string to their respective ANSI character equivalents.

character	The character to convert.

intvar	Will contain the OEM character’s ANSI equivalent.

string	The string to be converted.

strvar	Will contain the converted string.

strlength	An optional integer, indicating the number of characters to convert in the target string. If strlength is not specified, the entire string will be converted.

Example

proc main

   integer ChrVal             ; Holds converted value below.

   oemtoansi 0xA9 ChrVal      ; Convert the specified OEM

                              ; value to ANSI.

   usermsg "0x%X" ChrVal      ; Display the ANSI value.

endproc

See also

oemtokey and ansitooem; set aspect codepage; OEM/ANSI Commands.


oemtokey

oemtokey character intvar

Converts an OEM character to its key value.

character	The character to convert.

intvar	On SUCCESS, intvar will contain the OEM character’s keyboard equivalent. On FAILURE, intvar is undefined.

Example

proc main

   integer KeyCode         ; Virtual key code of character.

   oemtokey 'A' KeyCode    ; Get key code of 'A'.

   termvkey KeyCode        ; Send key code to terminal.

endproc

See also

ansitokey, keytooem and oemtoansi; set aspect codepage; Keyboard Commands; OEM/ANSI Commands.


param

param datatype name[,name]...

Defines a parameter variable in a procedure or function.

datatype	The desired data type, which can be either float, integer, long or string. Statements calling the function or procedure in which the param appears must use the identical data type and order for the arguments that are passed to it.

name	The name of the parameter variable. It will only be valid within the function or procedure in which it appears, and it must follow the ASPECT naming conventions.

Example

proc main

   integer A, B, C            ; Declare three integer variables.

   integer Sum                ; Sum of all three numbers.

   A = 2, B = 4, C = 8        ; Give the three variables values.

   Sum = Add( A, B, C )       ; Call function to add the numbers.

   usermsg "Sum = %d." Sum    ; Display the sum of the numbers.

endproc

func Add : integer

param integer X, Y, Z         ; Declare three passed integers.

   integer Sum                ; Sum of all three numbers.

   Sum = X + Y + Z            ; Figure sum of the numbers.

   return Sum                 ; Return the sum of the numbers.

endfunc

Comments

param commands must follow directly after a proc or func command. Up to 12 parameter variables can be defined. No other commands may appear between any two consecutive param commands.

Multiple definitions of the same data type must be separated by commas. Initializing expressions are not allowed in parameter declarations. Arrays cannot be defined as parameters to procedures or functions. For more information, see Parameter Variables.

See also

func, proc, integer, float, long, string and call; ASPECT Primary Commands.


pastetext

pastetext

Sends text in the Windows Clipboard to the active port.

Example

proc main

   string Source = "files.lst"   ; File containing list of files.

   waitfor "Send File List:"     ; Wait for command from host system.

   filetoclip TEXT Source        ; Copy file to clipboard.

   pastetext                     ; Paste list to active port.

endproc

Comments

When pastetext is executed, the Clipboard data must be text.

See also

filetoclip, strtoclip, cliptostr and cliptofile; Clipboard Commands.


pause

pause integer | FOREVER

Halts script execution for the specified number of seconds.

integer	A positive integer value indicating the number of seconds to pause execution.

FOREVER	If specified, causes script execution to be paused indefinitely.

Example

proc main

   integer Count = 0          ; Integer used for counting.

   while (Count++) < 3        ; Loop 3 t imes.

      transmit "^M"           ; Transmit a carriage return.

      pause 2                 ; Pause for 2 seconds.

   endwhile

endproc

Comments

Unlike the mspause command, pause can be aborted with the <Ctrl><Break> key sequence. This command can be tested with the if SUCCESS and if FAILURE statements. FAILURE is set if pause was terminated by the <Ctrl><Break> key sequence.

Any active when commands will still "fire" while the pause command is executing.

The pause FOREVER command will yield processing time to other applications.

See also

mspause and when elapsed; General Procomm Plus Commands.


pkmode

pkmode OFF | {ON txtimeout rxtimeout}

Toggles error-free packet mode on and off. If pkmode is on, your script can receive an error-free packet from another PC running an ASPECT script using the pksend statement.

txtimeout	The timeout value in seconds for transmitted packets.

rxtimeout	The timeout value in seconds for received packets.

Example

See the example for pksend.

Comments

FAILURE is set if packet transfer mode was not successfully initiated. Additional SUCCESS and FAILURE information can be obtained from the $PKSEND and $PKRECV system variables.

If you have activated pkmode and chain or execute a script, pkmode will remain enabled until a pkmode off is issued.

See also

pksend, pkrecv and when; $PKSEND and $PKRECV; Packet Mode Commands.


pkrecv

pkrecv intvar strvar intvar [rxtimeout]

Receives an error-free packet from another PC running an ASPECT script that has issued a pksend statement.

intvar	An integer variable assigned after the packet has been successfully received. Intvar’s value is the byte specified in the sending PC’s pksend statement. It is typically used to identify the contents of the packet. Valid values range from 0 to 255.

strvar	The data packet sent by the pksend statement after it is successfully received. The packet may include binary data.

intvar	The number of received bytes in this packet. Valid values range from 0 to 256.

rxtimeout	The amount of time that Procomm Plus will wait in packet receive mode before signaling a timeout. This value is initially set using the pkmode command, but you can specify this optional parameter to change the timeout when the pkrecv statement is executed.

Example

See the example for pksend.

Comments

pksend and pkrecv allow the script to send commands and any type of data between PCs running Procomm Plus, guaranteeing error-free transfer. A when $PKRECV event statement will be triggered when a change occurs as the result of the pkrecv. $PKRECV can also be tested to determine the status. The values for $PKRECV are:

Value	Meaning
0	packet not received or idle (default state)
1	packet received successfully
2	timeout occurred, packet not received
3	errors occurred, packet not received
See also

pkmode, pksend and when; $PKRECV; Packet Mode Commands.


pksend

pksend integer string strlength [txtimeout]

Sends an error-free packet to another PC running an ASPECT script.

integer	This value can be used as an identifier for the contents of the packet, or for any other purpose. It can be any value from 0 to 255. This value is available as an integer variable from the pkrecv command after the packet has been successfully received.

string	The data to be sent in the packet. Raw data may be included.

strlength	Determines the number of bytes to send in this packet.

txtimeout	An integer specifying the amount of time Procomm Plus will attempt to send the packet. This value is initially set with the pkmode command, but you can specify this optional parameter to change the timeout when the pksend statement is executed.

Example

proc main

   string FileNameStr                 	 ; Name of file to send.

   pkmode ON 60 60                     	 ; Set packet send and receive on.

   sdlgfopen "PKSEND" "*.*" SINGLE FileNameStr ; Get name of file to transfer.

   if isfile FileNameStr              	 ; Make sure file exists.

      SendPacketFile( FileNameStr )    	 ; Call the send routine to send file.

   else

      errormsg "File not transferred!"

   endif

endproc

proc SendPacketFile

param string FileNameStr                ; Name of file to send.

   string LineInfo                        ; Line from file.

   integer NumChars                     ; Number of characters read.

   if fopen 0 FileNameStr READ          ; Open file for read access.

      while not feof 0                  ; Loop while not at end of file.

         ; Get line from file and send it to remote. Abort

         ; if packet not sent.

         fread 0 LineInfo 255 NumChars

         if ! SendPacket( LineInfo, NumChars )

            errormsg "Couldn't send packet. Transfer aborted."

         endif

      endwhile

      SendPacket( "[Done]", 6 )

      fclose 0                          ; Close the file.

   else

   errormsg "Couldn't open file `"%s`"." FileNameStr

   endif

endproc

func SendPacket : integer

param string LineInfo                     ; Line to send to remote.

param integer Len                       ; Length of line to send.

   integer bSuccess = 0                 ; Set success flag to false.

   integer Status                       ; Status of packet send.

   integer Errors = 0                   ; Number of errors.

   while 1                              ; Loop until exitwhile.

      pksend 1 LineInfo Len               ; Send the packet.

      while ! (Status = $PKSEND)

      endwhile

      if Status == 1                    ; Evaluate the status of pksend.

         bSuccess = 1                   ; Set success flag to true.

         exitwhile                      ; Exit the while loop.

      endif

      Errors += 1                       ; Increment the error count.

      if Errors >= 3 || Status == 4

         exitwhile                      ; Exit the loop and return error.

      endif

   endwhile

   return bSuccess                      ; Return success or failure.

endfunc

; Receiving script.

proc main

   string FileNameStr                   ; Name of file to get.

   pkmode ON 60 60                      ; Set packet send and receive on.

   sdlgfopen "PKRECV" "*.*" FileNameStr ; Get name of file to transfer.

   if not isfile FileNameStr            ; Make sure file doesn't exist.

      GetPacketFile( FileNameStr )      ; Call the get routine to send file.

   else

      errormsg "File not transferred!"

   endif

endproc

proc GetPacketFile

param string Fname                      ; Name of file to get.

   integer PakType, Len                 ; Type of packet and length.

   integer Status                       ; Status of packet receive.

   integer Errors = 0                   ; Errors received during transfer.

   string LineInfo                      ; Line from file.

   if fopen 0 Fname CREATE              ; Open and create file.

      while 1                           ; Loop until exitwhile.

         if (Status == $PKRECV)

            if Status == 1              ; Packet received successfully.

               pkrecv PakType LineInfo Len

               if strncmp LineInfo "[Done]" 6

                  exitwhile

               endif

               fwrite 0 LineInfo Len

            else

            Errors += 1                 ; Increment the error count.

            if Errors >= 3              ; If error count exceeded abort.

               xfercancel               ; Cancel to signal sending script.

               exitwhile                ; Exit the while loop.

            endif

         endif

      endif

      endwhile

      fclose 0                          ; Close the file.

   else

      xfercancel                        ; Cancel to signal sending script.

      errormsg "Couldn't create file `"%s`"." Fname

   endif

endproc

Comments

After a pksend statement is executed, Procomm Plus will attempt to send the packet three times during the timeout period. A when $PKSEND event statement will be triggered when a change occurs as the result of the pksend statement; the system variable $PKSEND can be tested to determine the status. The values for $PKSEND are:

Value	Meaning
0	packet in progress or idle (default state).
1	packet sent successfully.
2	timeout occurred, packet not sent.
3	errors occurred, packet not sent.
4	packet send canceled by receiver, packet not sent.
See also

pkmode, pkrecv and when; $PKSEND; Packet Mode Commands.


playback

playback OFF | filespec

Plays back a Capture file or stops a playback currently in progress.

OFF	Aborts the playback of a Capture file in progress.

filespec	The Capture file to be played back.

Example

proc main

   string FName                 ; Name of file to play back.

   if sdlginput "File Playback" "Name:" FName

      if not nullstr FName   ; Make sure file isn't null.

         playback FName      ; Play back the chosen file.

      else

         errormsg "No file entered!"

      endif

   endif

endproc

Comments

If set aspect rxdata on has been issued, ASPECT will "see" playback data as if it were incoming data from the communications port.

If a path is not specified, playback defaults to the Capture file directory.

See also

set aspect rxdata; $PLAYBACK; General Procomm Plus Commands.


printalign

printalign LEFT | CENTER | RIGHT

Determines how text will be positioned when sent to the printer with the printstr and printchar commands. Choices are left-justified, right-justified or centered text.

Example

See the example for printer.

Comments

The justification stays in effect until the next printalign statement is executed. LEFT alignment must be set whenever the printtabstr command is used.

If alignment is set to CENTER or RIGHT, do not attempt to change the print attribute or font except at the beginning of a new line.

See also

printer, printattr, printmargin, printstr, printchar, printtabstr, printtabs and printfont; the set print command family; Printer Commands.


printattr

printattr NORMAL | { [BOLD] [ITALIC] [UNDERLINE] }

Sets the character attributes for text sent to the printer with the printstr, printtabstr and printchar commands. printattr can be used to format printed output with any combination of bold, italic or underlined characters.

NORMAL	Sets or resets the current printer font to normal character attributes.

BOLD	Sets the current printer font to bold character attributes.

ITALIC	Sets the current printer font to italic character attributes.

UNDERLINE	Sets the current printer font to underline character attributes.

Example

See the example for printer.

Comments

The attributes stay in effect until the next printattr statement is executed. NORMAL removes any previously set attributes.

If alignment is set to CENTER or RIGHT, do not attempt to change the print attribute except at the beginning of a new line.

See also

printer, printmargin, printstr, printchar, printtabstr, printtabs and printfont; the set print command family; Printer Commands.


printcapture

printcapture OFF | ON

Routes characters received by Procomm Plus or entered by the user to the printer.

Example

proc main

   printcapture ON         ; Turn on the print device.

   while $CARRIER          ; Loop while connected.

      yield                ; Yield processing time

   endwhile

   printcapture OFF        ; Turn off the print device.

endproc

Comments

printcapture sends characters to the current printer or the printer specified by the set print device script command.

See also

capture, snapshot and sbsave; the set print command family; Printer Commands.


printchar

printchar character

Prints a character on the "open" printer at the current position.

Example

See the example for printer.

Comments

A Tab character, ASCII 9, causes subsequent data to be printed at the next 8-character interval on the current line. A Carriage Return, ASCII 13, or Line Feed character, ASCII 10, causes the current line to be terminated and a new line to begin, while a Form Feed character, ASCII 12, causes subsequent data to print on a new page. These "special" formatting characters are ignored when printing raw data.

For more information on opening a printer and defining the current character position, please refer to printer.

See also

printer, printtabstr and printstr; Printer Commands.


printer

printer { OPEN [RAW] } | CLOSE | CANCEL

Opens the current printer for any of the print command family.

OPEN	Activates the current Windows printer. You can select a printer to open with the set print device command. If the printer was previously opened, it will be closed and re-opened, which terminates the previous print job.

RAW	If specified, causes all data to pass through to the printer, with no Line Feed, Form Feed, Tab or print attributes. Also, all print commands such as printattr, printfont, printalign, printmargin and printtabs will be ignored.

This mode is useful for printing data that is already in PostScript form. If the printer’s Windows driver does not support a "pass-through" mode, Procomm Plus will attempt a best-fit output mode.

CLOSE	Closes the printer previously opened within a script, terminating the current print job. If a script terminates before closing the printer, it will be closed automatically by ASPECT.

CANCEL	Ends a printing session and deletes any outstanding text to be printed.

Example

proc main

   string TextStr             ; Text string to print.

   TextStr = "This is a normal text string!"

   if printer open            ; Open the print device.

      printfont "HELV" 10     ; Set font to Helvetica.

      printalign CENTER       ; Choose centered printing.

      printattr BOLD ITALIC   ; Change print type to Bold /

                              ; italic.

      printmargin 1.0 1.0     ; Set the print margins.

      printchar 'R'           ; Print a character.

      printchar 'O'           ; Print a character.

      printchar 'N'           ; Print a character.

      printstr "`r`n"         ; Print an end of line.

      if printfit TextStr     ; Make sure text fits.

         printstr TextStr     ; Print the text string.

      else

         errormsg "Text won't fit on print device!"

      endif

      printtabs 1.5 2.0 6.0   ; Set some print tabs.

      printtabstr "This`tstring`tis`tabnormal!"

      printer close           ; Close the print device.

   else

      errormsg "Couldn't open the printer device!"

   endif

endproc

Comments

A printer must first be opened before you issue any print statements. The current printer parameters or the values specified by set print commands act as defaults when the printer is first opened.

printchar and printstr begin printing at the current character position, which is defined as one of three different positions: the top left margin of a new page, the next character position after a previous printchar or printstr or the left margin one line below a previous printtabstr. The current position for any printtabstr is the left margin one line below the last line printed.

If any print command is attempted that would print the line below the bottom margin, the new line will be printed at the top left margin on the next page.

To print formatted text from a script, simply use printer open, followed by any combination of these printing commands: printalign, printattr, printfont, printmargin, printtabs, printtabstr, printchar or printstr.

See also

printalign, printattr, printfont, printmargin, printtabs, printfit, printchar, printstr and printtabstr; the set print command family; Printer Commands.


printfit

printfit string [strlength]

Determines if a string will print on the current page.

string	The string to test.

strlength	The length of the test string. If strlength is not provided, a null-terminated string is assumed and its length is determined automatically.

Example

See the example for printer.

Comments

In essence, printfit operates the same as printstr, except that no printing occurs. printfit sets the SUCCESS flag if the string can be printed on the current page. If the string would cause the printing to begin on the next page, the FAILURE flag is set. printfit can be used to prevent page breaks within paragraphs.

printfit always returns SUCCESS if the printer was opened for raw data printing.

See also

printer, printstr and printtabstr; the set print command family; Printer Commands.


printfont

printfont font size

Selects a new printer font for subsequent printchar, printtabstr or printstr commands.

font	A string specifying the name of the font to use.

size	An integer which determines the size of the font to use. Values can range from 0 to 255 points. The value 0 automatically selects a standard font size for the open printer.

Example

See the example for printer.

Comments

The printer will use the font and size specified in a printfont command until another printfont command is issued. printfont has no effect if the printer was opened for raw data printing.

If alignment is set to CENTER or RIGHT, do not attempt to change the print font except at the beginning of a new line.

See also

printer, printalign, printmargin, printtabs, printstr, printchar, printtabstr and printattr; Printer Commands.


printmargin

printmargin left [right [top [bottom]]]

Determines the page margins for data printed from Procomm Plus.

left	Specifies the left margin in inches. A float value.

right	Specifies the right margin in inches. A float value.

top	Specifies the top margin in inches. A float value.

bottom	Specifies the bottom margin in inches. A float value.

Example

See the example for printer.

Comments

The optional margins must be specified in sequence. They define a rectangle where the text will be printed. For example, a left margin setting of 5 inches would result in a column alignment down the right side of the page.

If a margin is set to a value that is less than the minimum margin or greater than the available printing area, the minimum margin will be used. A negative value is ignored, and will result in no change to the particular margin value.

printmargin has no effect if the printer was opened for raw data printing.

See also

printer, printattr, printalign, printfont and printtabs; the set print command family; Printer Commands.


printstr

printstr string [strlength]

Sends a specified string to the open printer.

string	The text string to send to the printer.

strlength	An optional integer specifying the amount of data to print. If strlength is not provided, a null-terminated string is assumed and its length is determined automatically.

Example

See the example for printer.

Comments

printstr "streams" text onto the page using the selected font and attributes within the margins. Continued use of the printstr command without the use of an intervening printmargin will "append" each string to the previous string. An attempt to print below the bottom margin prints the remainder of the string on the next page.

If the printer was opened in raw mode, all "special" formatting is disabled. If the printer was not opened in raw mode, a Tab, ASCII 9, is expanded to fixed tab stops at eight character intervals, a Carriage Return, ASCII 13, a Line Feed, ASCII 10, or a Carriage Return/Line Feed pair force a new line, and a Form Feed, ASCII 12, forces the printer to advance to the next page.

For more information on opening a printer and defining the current character position, please see the printer command.

See also

printer, printchar and printtabstr; the set print command family; Printer Commands.


printtabs

printtabs CLEAR | float [float...]

Determines the tab positions for the strings printed with the printtabstr command.

CLEAR	Clears any previously-set tabs, defaulting to 8-character tab stops.

float [float...]	A series of float values representing the desired tab stops. Values are referenced in sequence from the left margin, in units of inches. Up to 12 tab stops may be specified.

Example

See the example for printer.

Comments

The tab values represent distances from the left margin. If more tabs occur within a string than are set by printtabs, the default 8-character tab stop value will be assumed.

printtabs only sets the tabs for the printtabstr statement. Tabs in strings that are printed using printstr will still default to every eighth character position.

See also

printer, printtabstr, printalign, printmargin, printstr and printattr; Printer Commands.


printtabstr

printtabstr string [strlength]

Prints a line of text, expanding tabs to the positions set with the printtabs command.

string`	The text to print.

strlength	If strlength is not provided, a null-terminated string is assumed, and its length is determined automatically.

Example

See the example for printer.

Comments

The line of text is printed beginning at the left margin, one line below the last line printed or, if printing on a new page, at the top margin. The text will be clipped if it extends beyond the right margin. printtabstr is especially useful for printing tables.

The printtabstr is only useful when text alignment is left-justified, since tab values are measured from the left margin. If text alignment is centered or right-justified, printtabstr behaves exactly like printstr.

Other formatting characters such as Carriage Returns, ASCII 13, Line Feeds, ASCII 10, or Form Feeds, ASCII 12, are processed as in the printstr and printchar commands. All formatting is disabled if the printer has been opened in raw mode.

See also

printer, printchar, printstr and printtabs; the set print command family; Printer Commands.


proc

proc name

Marks the beginning of a procedure block. Each procedure must be given a unique name, and every ASPECT script must have a procedure called "main" which indicates the starting point of script execution.

Example

proc main

   integer Area                     ; Integer to contain area.

   integer Diameter = 8             ; Integer to contain diameter.

   CircleArea( &Area, Diameter )    ; Get area of circle.

   usermsg "%d" Area                ; Display approx area of circle.

endproc

proc CircleArea

param integer Area                  ; Passed integer area.

param integer Diameter              ; Passed integer diameter.

   integer Radius                   ; Integer to contain radius.

   Radius = Diameter / 2            ; Calculate radius of circle.

   Area = 3.14 * (Radius * Radius)  ; Calculate area of circle.

endproc

Comments

Any procedure except main may define a parameter list; the parameters are variables of any type, and are local to the procedure. Parameters are initialized with arguments passed via the call which invoked the procedure.

Procedures can be referenced either by using the call command:

call myproc [with arglist]

or by using the "shortened" form:

myproc([arglist])

Each form constitutes a procedure call which causes execution to transfer to the start of the procedure block. When the procedure is exited, execution returns to the point where the call was made.

The shortened form of procedure calls is highly recommended. It is shorter, just as readable, and less verbose. Also, future enhancements to ASPECT may require it.

See also

call, func, param, return, setjmp, longjmp and endproc; Procedures and Functions; ASPECT Primary Commands.


profilerd

profilerd filespec string string strvar | intvar

Reads a specified item value from any portion of a specified Windows .ini disk file.

filespec	The name of the .ini file to reference. If a path is not specified, the Windows directory ($WINPATH) will be used.

string	The name of the topic containing the desired item.

string	The item name containing the desired value.

strvar | intvar	The value returned into a string or integer variable.

Example

proc main

string ProgList                   ; List of programs from WIN.INI.

   ; Read the "Load=" line from the WIN.INI file.

   profilerd "win.ini" "windows" "Load" ProgList

   usermsg "Load = %s" ProgList   ; Display contents of Load line.

endproc

Comments

If the name of the topic or item does not exist in the target .ini file, strvar will be null; intvar will equal -1. If the item is being stored into intvar, but the item does not contain numeric data, then 0 will be assigned.

See also

profilewr; General Windows Commands.


profilewr

profilewr filespec string string string | integer

Writes a specified item value to any portion of a specified Windows .ini disk file.

filespec	The name of the target .ini file. If a path is not specified, the Windows directory ($WINPATH) will be used.

string	The name of the topic containing the desired item.

string	The item name.

string | integer	The data to be written.

Example

proc main

   string IniFile = "pw4.ini"       ; .ini file to write info to.

   ; The following command writes a new section to the

   ; pw4.ini file called "Extra Stuff". Under the new

   ; section, it writes "Temp = 5".

   profilewr IniFile "Extra Stuff" "Temp" 5

endproc

Comments

Any strings containing TAB characters (ASCII 0x09) used with this command will be truncated at the TAB.

See also

profilerd; General Windows Commands.


pushbutton

pushbutton id left top width height label [OK | CANCEL] [DEFAULT]

(or) pushbutton id left top width height label USERWIN | BACKGROUND

Places a standard pushbutton control within an ASPECT dialog box or User window. The user may click on this control to indicate a choice. pushbutton has two forms depending on where the button is displayed.

Dialog box format

pushbutton id left top width height label [OK | CANCEL] [DEFAULT]

id	An integer constant used as a control value for the button. This value is reported by dlgevent when the button is selected by the user.

left top	Location of the button from the top left corner of the dialog box. Values are integer constants in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.

width height	Integer constants representing the size of the button in DBUs.

label	A string variable or constant containing the text displayed on the button face. To specify a keyboard shortcut key, preface the desired character with an ampersand (&) character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

dlgupdate can be used to update the text.

OK	The dialog box is removed when an OK button is pressed. Changes made to file-related controls will be saved to disk.

CANCEL	The dialog box is removed when a CANCEL button is pressed. Any changes made to file-related controls will not be saved.

DEFAULT	Specifies that the button is to be selected when the <Enter> key is pressed and no other button has the input focus, or when a list box, file list box, combo box, file combo box or directory list box item is double-clicked. Note that only a single button or icon button can be named as default in a dialog box.

Example

proc main

   integer Event           ; Dialog box event.

   dialogbox 0 0 0 100 50 11 "Button Example"

      pushbutton 1 5 5 90 40 "&Push Me"

   enddialog

   while 1

      dlgevent 0 Event     ; Get dialog event.

      switch Event         ; Evaluate dialog event.

         case 0            ; No event occurred.

         endcase

         case 1            ; Button was pressed.

            exitwhile      ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL     ; Get rid of dialog box.

endproc

See also

dialogbox, enable, disable, iconbutton, dlgevent and dlgupdate; Dialog Box Commands.

User window format

pushbutton id left top width height label USERWIN | BACKGROUND

id	A unique integer value given to the button. The value is assigned to $OBJECT when the button has been selected by the user. It is used by the objremove command to remove the button.

left top	Integer values which determine the top left corner position of the button with respect to the top left corner of the User window or background graphic. Values are in User Window Units or UWUs. For more information on UWUs, see User Window Units.

width height	The size of the button in UWUs.

label	A constant or string variable containing the text displayed on the button face. To specify an accelerator for the button, preface the desired character with an ampersand (&) character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

BACKGROUND  | USERWIN	Specify USERWIN to fix the top left corner of the button in position relative to the upper left corner of the User window. Specify BACKGROUND to fix the button over the same spot on a background graphic. If the background is a metafile displayed with the SCALE option, the button both stays over the same spot and is re-sized in proportion to the new background dimensions.
Example

proc main

integer Event              ; User window event.

   uwincreate FULL SCREEN 100 255 255 255 METAFILE

   pushbutton 1 500 500 750 750 "&Big Button" USERWIN

   uwinpaint               ; Paint user window and button.

   while 1                 ; Loop forever.

      if (Event = $OBJECT) != 0

         switch Event      ; Evaluate user window event.

            case 1         ; Button chosen.

               usermsg "Good-bye!"

               exitwhile   ; Exit the while loop.

            endcase

         endswitch

      endif

   endwhile

   uwinremove              ; Remove the user window.

endproc

Comments

A User window must exist before buttons  can be placed. A uwinpaint command must be issued to display User window changes.

See also

uwincreate, uwinpaint, objcoord, objpointid, objpaint, objremove, hotspot, icon, iconbutton, dllobject, bitmap and metafile; $OBJECT; User Window Commands.


putenv

putenv string

Adds or changes an environment variable definition.

string	A string containing an environment variable and setting. For example, "VARIABLE=TRUE".

Example

proc main

   string EnviroString                  ; String to put into environment.

   EnviroString = "This is some text"   ; Assign a value to string variable.

   putenv EnviroString                  ; Put string into the environment.

endproc

Comments

Environment variables can be used to pass information between scripts or applications.

putenv can be tested with the if SUCCESS and if FAILURE statements to determine whether the environment modification was successful.

See also

getenv; DOS- or Disk-Related Commands.


pwexit

pwexit

Terminates the executing script file, disconnects and then exits Procomm Plus.

Example

proc main

   when USEREXIT call Done ; Trap when user tries to exit script.

   while 1                 ; Loop forever.

      yield                ; Yield processing time

   endwhile

endproc

proc Done

   pwexit                  ; Close Procomm Plus.

endproc

See also

exit, exitwindows, halt, taskexit and winclose; General Procomm Plus Commands.


pwmode

pwmode TERMINAL | FTP | MAIL | NEWS | TELNET | integer

Places Procomm Plus into one of six execution modes.

TERMINAL	A keyword which places Procomm Plus into Terminal mode.

FTP	A keyword which places Procomm Plus into FTP mode.

MAIL	A keyword which places Procomm Plus into Internet Mail Client mode.  If there is no mail serveraddress specified in Setup, a switch to Mail mode will result in a dialog prompt.

NEWS	A keyword which places Procomm Plus into News Reader mode. If there is no news serveraddress specified in Setup, a switch to News mode will result in a dialog prompt.

TELNET	A keyword which places Procomm Plus into Telnet mode.

integer	A value from 0 (zero) to 5 which places Procomm Plus into the associated mode, listed above.

Example

proc main

   if $PWMODE        ; if Procomm Plus is in a mode other than data terminal

      pwmode 0       ; switch to data terminal mode

   endif

endproc

See also

menuselect, $PWMODE.


pwtitlebar

pwtitlebar {string [PERMANENT]} | RESTORE

Specifies the text to display in the Procomm Plus program title bar.

string	The title text. A maximum of the first 64 characters of this string can be displayed.

PERMANENT	If specified, will cause the new title bar information to remain after the script has terminated.

RESTORE	If specified, this keyword disables the PERMANENT setting, and causes Procomm Plus to redisplay the current title bar.

Example

proc main

   string NewTitleStr                ; New title for Procomm Plus.

   ; Display the name of the currently executing script file

   ; in the title bar for Procomm Plus.

   strfmt NewTitleStr "Procomm Plus - %s" $SCRIPTFILE

   pwtitlebar NewTitleStr            ; Change Procomm Plus's title.

   pause 5                           ; Show off the change.

endproc

Comments

Procomm Plus changes the title bar based on numerous conditions and situations, such as switching modes and minimizing the application. Use the PERMANENT keyword to prevent Procomm Plus from changing the title bar. Use the RESTORE keyword to disable the permanent setting, and redisplay the current Procomm Plus title bar.

See also

$TITLEBAR and $PWTITLEBAR; General Procomm Plus Commands.


radiobutton

radiobutton id left top width height label

Places a radio button/option button control in an ASPECT dialog box.

id	An integer constant used as the control id for the option button. It will be assigned to the control variable used by the option button’s associated radiogroup statement when the option button is selected by the user.

left top width height	Integer constants specifying the position and size of the option button relative to the dialog in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.

label	A string constant or variable which will be displayed with the button control. To specify a keyboard accelerator for the option button, simply include an ampersand (&) before the desired character. To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

Example

See the example for radiogroup.

Comments

radiobutton may only appear within a radiogroup/endgroup block. The control variable used by the radiogroup statement can be initialized to pre-select a particular option button.

A single option button, or a range of option buttons can be enabled or disabled using their respective control ids. To disable an entire group, the option button group id can be referenced.

dlgupdate can be used to update a option button.

See also

radiogroup, endgroup, enable, disable, dlgupdate, dlgevent and dialogbox; Dialog Box Commands.


radiogroup

radiogroup id intvar

Marks the beginning of a group of radiobutton statements.

id	An integer constant used as a control id.

intvar	The control variable to be associated with this group.

Example

proc main

   integer Choice = 2         ; Used for radio button group.

   integer Event              ; Dialog box event.

   dialogbox 0 0 0 100 50 11 "Choose One"

      radiogroup 1 Choice  ; Define radio group.

         radiobutton 2 5 5 90 12 "&Green"

         radiobutton 3 5 20 90 12 "&Red"

      endgroup

      pushbutton 4 25 35 50 15 "&Done"

   enddialog

   while 1

      dlgevent 0 Event        ; Get dialog box event.

      switch Event            ; Evaluate the event.

         case 0               ; No event occurred.

         endcase

         case 1               ; Radio group control selected.

         endcase

         default              ; Exit case selected.

            exitwhile         ; Exit the while loop.

         endcase

      endswitch

   endwhile

   dlgdestroy 0 CANCEL        ; Destroy the dialog box.

   if Choice == 2             ; Evaluate radio group state.

      usermsg "Green!"

   else

      usermsg "Red!"

   endif

endproc

Comments

When an option button within a group is selected, the intvar associated with that group is assigned the id value of the selected button. dlgevent reports the option button group id value when an option button is selected.

Each radiogroup statement must be matched with an endgroup statement. radiogroup statements cannot be nested.

A option button group, including the buttons it contains, can be disabled or enabled by specifying its control id. A single option button, or a range of option buttons can be enabled or disabled using their respective control ids.

See also

dialogbox, enable, disable, dlgupdate, endgroup and radiobutton; Dialog Box Commands.


rand

rand intvar [integer]

Returns a random value, ranging from 0 to 2147483647.

intvar	Will store the returned value.

integer	Specifies a seed value for the random number generator. The default seed value is 1 when Procomm Plus starts up.

Example

proc main

   integer Number             ; Random number.

   integer Seed               ; Seed for better randomization.

   rand Seed                  ; Get a random integer.

   rand Number Seed           ; Get random integer with seed.

      ; Convert random number to a number between 0 and 5.

   Number = Number % 6

   usermsg "The number is %d." Number

endproc

Comments

The optional seed integer is generally specified for the initial call to rand. Subsequent calls should not include the same seed value, or the same value will be repeatedly returned.

See Also

Numeric, String Conversion Commands.


rename

rename filespec filespec

Renames an existing file, reporting its results in SUCCESS and FAILURE.

filespec	The source filename.

filespec	The destination filename.

Example

proc main

   string Fname = "INDX.TMP"          ; Name of file to rename.

   string NewFName = "LAST.IDX"       ; New name for the file.

   if not rename Fname NewFName       ; Rename the file.

      errormsg "Couldn't rename `"%s`" to `"%s`"." Fname NewFName

   endif

endproc

Comments

If no path is supplied, rename searches the User Path for the source file. Files can be renamed to a different directory on the same drive, which is equivalent to moving them from one directory to another.

See also

delfile, chdir and copyfile; $USERPATH; DOS- or Disk-Related Commands.


return

return [expression]

Exits the current procedure or function and resumes processing at the statement following the procedure or function call.

expression	Expression is required for functions, but not allowed within procedures. If a function returns a string, then specify a string constant or variable as the expression. If a function returns a numeric value, specify any numeric constant, variable or expression.

Example

See the example for func.

Comments

A return statement placed in the "main" procedure terminates the script. The endproc command includes a tacit return, but a function must include a return expression statement, or an error will occur at compile-time.

Any setjmp commands invoked in the current procedure or function will no longer be active upon a return from that procedure. The same is true for any when commands that were executed to monitor changes in any local variables within the current procedure or function.

See also

proc, endproc, setjmp, longjmp, func and call; ASPECT Primary Commands.


rewind

rewind id

Repositions the file pointer corresponding to the specified id back to the beginning of the file. All end-of-file and error flags are cleared as the pointer is moved to the start of the file.

id	The id of the target file.

Example

proc main

   string Fname = "Rewind.txt"      ; Name of file to read.

   string Line                      ; Line from file.

   string Name = "Hello"            ; String to look for.

   if fopen 0 Fname READ TEXT       ; Open file for read access.

      while not feof 0              ; Loop while not end of file.

         if fgets 0 Line            ; Get a line from the file.

            if stricmp Line Name

               rewind 0             ; Backup and look for another.

               if stricmp Name "Good-Bye"

                  exitwhile         ; Exit loop when name found.

               endif

               Name = "P.S."        ; Set Name to new value.

            endif

         endif

      endwhile

      fclose 0                      ; Close the file.

   else

      errormsg "Couldn't open `"%s`" for reading!" Fname

   endif

endproc

See also

fseek, fopen and fclear; File I/O Commands.


rget

rget strvar [strlength [integer | FOREVER]] [RAW]

Receives and stores a text string sent by a remote system.

strvar	The variable where the data will be stored.

strlength	An integer value ranging from 0 to 256, specifying the maximum number of characters to receive before continuing processing. If strlength is not included, the maximum of 256 characters is used.

integer	Determines the maximum number of seconds to wait for the string from the remote system before timing out. If not specified, the default of 30 seconds is used.

FOREVER	Forces the rget to wait indefinitely for the requested number of characters, or for the character value specified with set aspect rgetchar.

RAW	If specified, rget data will be retrieved unchanged from the receive data buffer, bypassing the translate table and 8th-bit stripping.

Example

proc main

string Name                   ; Remote user's name.

   transmit "Name? "          ; Prompt remote user for name.

   rget Name 20               ; See if user entered name.

   transmit "^M^J^M^JHello "  ; Send a message to remote user.

   transmit Name

   transmit ", how are you?^M^J"

endproc

Comments

rget completes when the character defined by set aspect rgetchar is received, when the specified number of characters are received or when the specified/default time expires. Execution continues with the next statement in the script.

Data retrieved by the rget command will not be displayed in the Terminal window, regardless of the set aspect rxdata state. rget will not be interrupted by a when $RXDATA condition, since rget effectively "steals" data from the received data buffer.

rget can be tested with the if FAILURE command, which returns true when rget times out. rget will fail if the script does not have control of the communications port.

rget can be exited with the <Ctrl><Break> key, returning FAILURE. To rget a result message from a modem, if rgetchar is set to its default of Carriage Return, you need to do two rgets: one to strip the Carriage Return or rgetchar sent by the modem before its message, and one to capture the modem message itself, since rget ends as soon as it encounters a Carriage Return or rgetchar.

See also

comgetc and comread; set aspect rgetchar; COM-Related Commands.


rmdir

rmdir pathname

Removes an empty directory using a specified path.

pathname	The directory to be removed.

Example

proc main

   string NwDir = "GOODBYE"   ; Dir to create and remove.

   mkdir NwDir                ; Create a new directory.

   rmdir NwDir                ; Remove our new directory.

endproc

Comments

If no path is supplied, rmdir removes a sub-directory in the User Path directory. rmdir reports SUCCESS if the directory was removed; FAILURE otherwise.

See also

chdir, mkdir and getdir; $USERPATH and $ASPECTPATH; set aspect path; DOS- or Disk-Related Commands.


rstrcmp

rstrcmp string string strlength

Compares the contents of two strings up to the specified length.

string string	The string constants or variables to be compared. They can contain raw data, or nulls.

strlength	The number of character positions to test.

Example

proc main

   string DataStr              ; String to contain data.

   string TextStr              ; String to contain literals.

   TextStr = "^O`x0`x9"        ; Assign non-printables to string.

   comread DataStr 3           ; Read three characters from port.

         ; Compare data from port to data in our text string.

   if rstrcmp DataStr TextStr 3

      usermsg "Data from port matches our Text String!"

   else

      usermsg "Data from port doesn't match text string!"

   endif

endproc

Comments

rstrcmp’s results can be tested with the if SUCCESS or if FAILURE. SUCCESS indicates that the strings are equivalent for the strlength tested.

See also

stricmp, strcmp, strnicmp and strncmp; String Commands.


run

run string [ MINIMIZED | MAXIMIZED | HIDDEN ] [intvar]

Executes an external program in a separate window.

string	A string describing any executable program, optionally including a DOS path and program arguments. Arguments should be separated from the program name with spaces.

MINIMIZED	Starts the program in a minimized or iconic environment.

MAXIMIZED	Starts the program in a maximized or full-screen window.

HIDDEN	Starts the program without a visible window.

intvar	If specified, intvar is assigned the task id number of the program which is executed. This id can then be used in the taskactivate and taskexit commands, or other commands that use a task id.

Example

proc main

   string Prog = "pbrush.exe" ; Program to execute.

   run Prog                   ; Execute the Windows PaintBrush program.

endproc

Comments

run can be tested with the if SUCCESS statement. It returns false if the program could not be executed. run cannot be used for DOS internal commands and batch files; use the dos command instead. If a path is not specified, the program must reside in the User Path or in a directory included in the DOS path. ASPECT will change to the directory specified in $USERPATH before attempting to execute the run command.

run defaults to a normal startup environment if MINIMIZED, MAXIMIZED or HIDDEN is not specified.

See also

taskactivate, taskexists, metakey, dos and shell; DOS- or Disk-Related Commands.


rxflush

rxflush

Clears the receive data buffer. Any characters that have been received but not processed or displayed will be lost when rxflush executes.

Example

proc main

   string DataStr                    ; Data from COM port.

   rxflush                           ; Clear all awaiting COM data.

   transmit "Enter 50 chars: "       ; Ask remote for 50 characters.

   rget DataStr 50                   ; Get 50 characters from remote.

endproc

Comments

rxflush will function only when ASPECT has access to the communications port. For example, it will not have any effect during file transfers or fax operations.

See also

txflush; $RXCOUNT and $RXDATA; COM-Related Commands.


sbsave

sbsave CLIPBOARD | CAPTURE | {FILE filespec [APPEND]} | PRINTER

Empties the Terminal window’s Scrollback Buffer into a file, the Windows Clipboard, the current Capture file or the "open" system printer.

CLIPBOARD	The Scrollback Buffer will be copied to the Windows Clipboard.

CAPTURE	The Scrollback Buffer will be copied into the Capture file.

FILE filespec	The Scrollback Buffer will be copied into a text file specified by filespec. If a path is not specified, the file will be created in the Capture path specified in Setup.

APPEND	Appends the contents to the end of the file specified in filespec. If the file does not exist, it will be created.

PRINTER	The Scrollback Buffer will be copied to the printer.

Example

proc main

   ; Save the contents of the scroll back buffer to specified

   ; file. You can use this command when you want to "take

   ; a picture" of the scrollback buffer.

   sbsave FILE "scrollbk.pic" ; Save scrollback to file.

endproc

Comments

When the copy destination is an existing disk file, the current contents of the file are erased. Similarly, existing contents are destroyed if the copy destination is the Windows Clipboard.

If CAPTURE is specified, a Capture file must have been opened previously either by a script command or user input.

If FILE is specified, the file described by filespec already exists, and the APPEND parameter is not given, its contents will be erased.

See also

snapshot; set terminal sbpages; Terminal Commands.


screentowin

screentowin window intvar intvar

Converts X/Y screen coordinates into coordinates relative to the specified window ID.

window	The window id.

intvar	Initially contains the screen’s X coordinate and is updated to contain the window’s X coordinate.

intvar	Initially contains the screen’s Y coordinate and is updated to contain the window’s Y coordinate.

Example

proc main

   integer X[2], Y[2]         ; X and Y screen coordinates.

   X[0] = X[1] = $POINTERX    ; Set both X coordinates to mouse pos.

   Y[0] = Y[1] = $POINTERY    ; Set both Y coordinates to mouse pos.

                              ; Change X and Y to win relative.

   screentowin $PWMAINWIN X[1] Y[1]

   usermsg "Screen X: %d Y: %d Window X: %d Y: %d" X[0] Y[0] X[1] Y[1]

endproc

Comment

Coordinates are converted relative to the client area of the window. The client area begins at a point inside the window frame, if any, and below the caption bar and menu bar, if any. The screen coordinates can be retrieved from the $POINTERX and $POINTERY system variables.

See also

setpointer, wincoord and wintoscreen; $POINTERX, $POINTERY, $XPIXELS, $YPIXELS, $POINTERWIN and $POINTERTASK; General Windows Commands.


sdlgfopen

sdlgfopen title filespec {SINGLE strvar} | {MULTIPLE filespec}

Displays a standard File Open dialog, allowing the user to search drives and paths and select files. sdlgfopen returns SUCCESS or FAILURE, depending on whether the user pressed the OK button.

title	Specifies a title string for dialog.

filespec	A filespec specifying the type of files to display. This variable may contain multiple file types in the form "*.txt;*.doc" and will be filled with the filespec of the selected file when succesful.

SINGLE strvar	On SUCCESS, strvar is filled with the filespec of the file selected by the user.

MULTIPLE filespec	On SUCCESS, filespec is filled with the name of a file which contains a list of filespecs selected by the user.

Example

proc main

   string FileName                ; String to contain file name.

   string FileSpec                ; String to contain file spec.

   ; Get a file name from user by displaying standard Windows

   ; file open box.

   FileSpec = "c:\*.*"            ; Set spec to all files in "c:\".

   if sdlgfopen "Choose File" FileSpec SINGLE FileName

      usermsg "You chose to open `"%s`"." FileName

   endif

endproc

See also

dir, sdlgsaveas, sdlgmsgbox and sdlginput; General Procomm Plus Commands.


sdlginput

sdlginput title prompt strvar [strlength] [MASKED] [DEFAULT]

Displays a standard Windows dialog box allowing the user to input a single line of text. Returns SUCCESS if user presses OK; FAILURE otherwise.

title	Specifies a title string for the dialog.

prompt	Specifies a prompt string to be displayed in the input box.

strvar	Returns the string entered by the user.

strlength	If specified, the number of characters a user is allowed to enter. If the user attempts to enter more than strlength characters, an error beep will sound.

MASKED	Causes input to be displayed as asterisks (*). This is convenient for input of sensitive data, such as passwords.

DEFAULT	If DEFAULT is specified, the current value of strvar is displayed as a default. The user need only press <Enter> to select this string.

Example

proc main

   string Name                ; String to contain user name.

   transmit "^M"              ; Get host's attention.

   if waitfor "User Id"       ; Watch for user identification

                              ; prompt and get user's name.

      sdlginput "Information" "User Id: " Name

      transmit Name           ; Transmit users name followed by

      transmit "^M"           ; carriage return.

   else

      errormsg "Host didn't respond!"

   endif

endproc

See also

sdlgfopen, sdlgmsgbox and sdlgsaveas.


sdlgmsgbox

sdlgmsgbox title string icon button intvar [integer] [BEEP]

Displays a standard dialog box with a specified icon and button.

title	Specifies the text to be displayed as the dialog title.

string	Specifies the text to be displayed within the dialog. The text can act as a user prompt or warning.

icon	Determines the graphic icon to display in the dialog box. Values are:

INFORMATION	A lowercase letter "i".

EXCLAMATION	An exclamation point.

QUESTION	A question mark.

STOP	A stop sign.

NONE	No icon displayed.

button	Determines the standard button configuration provided in the dialog box. Values are:

OK	A single button labeled OK, suitable for user confirmation of an information display.

OKCANCEL	Two buttons, labeled OK and Cancel.

RETRYCANCEL	Two buttons, labeled Retry and Cancel.

YESNO	Two buttons, labeled Yes and No.

YESNOCANCEL	Three buttons labeled Yes, No and Cancel.

ABORTRETRY	Three buttons labeled Abort, Retry and Ignore.

intvar	Returns the button selected by the user. Values are:

1 - OK

2 - Cancel

3 - Abort

4 - Retry

5 - Ignore

6 - Yes

7 - No

integer	Specifies the default button for this dialog. Valid values can be 1, 2 or 3, corresponding to the first, second and third buttons in the order they appear in the dialog.

BEEP	Specifies that the default Windows beep sound will accompany the dialog.

Example

proc main

   integer Choice = 0            ; Integer to use with dialog.

   while Choice != 2             ; Loop while user doesn't cancel.

      transmit "^M"              ; Transmit return and wait for   response.

      if waitfor "Welcome"

         sdlgmsgbox "" "Host not responding." STOP RETRYCANCEL Choice

      else

         exitwhile               ; Exit loop if host responds.

      endif

   endwhile

   if Choice == 2                ; See if user aborted.

      usermsg "Aborted by user!"

   else

      usermsg "Connected!"

   endif

endproc

See also

statmsg, sdlginput, sdlgfopen, sdlgsaveas, usermsg and errormsg.


sdlgsaveas

sdlgsaveas title filespec strvar

Displays a standard Windows File Save As dialog. sdlgsaveas is used to name a file or confirm a file name before it is saved. sdlgsaveas reports SUCCESS if the OK button was pressed.

title	Specifies a title string for the dialog.

filespec	A filespec specifying the type of files to display. This variable may contain multiple file types in the form "*.txt;*.doc" and will be filled with the filespec of the selected file when succesful.

strvar	Returns the filespec chosen by the user.

Example

proc main

   string FnameStr                ; String to contain file name.

   string FileSpec               ; String to contain file spec.

   ; Get a file name from user by displaying standard Windows

   ; saveas dialog box.

   FileSpec = "c:\*.bat"         ; Set spec to all ".BAT" files.

   if sdlgsaveas "SaveAs" FileSpec FnameStr

      usermsg "You chose to save file as `"%s`"." FnameStr

   endif

endproc

Comments

sdlgsaveas tests for a valid filespec, and will prompt the user to change it if it’s invalid. If the filespec already exists, sdlgsaveas queries the user before overwriting it.

See also

sdlgfopen, sdlgmsgbox and sdlginput; General Procomm Plus Commands.


sendfile

sendfile protocol | index | string | DEFAULT [filespec [filespec]]

Sends or "uploads" a file to a remote computer using the indicated transfer protocol, returning SUCCESS if the transfer successfully initializes.

protocol	A keyword representing a file transfer protocol.

index	An integer value corresponding to the desired protocol.

string	A string constant or variable which represents a file transfer protocol, or a named-item version of a protocol.

DEFAULT	If DEFAULT is specified, the current default protocol will be used to upload the file.

filespec	If specified, the name of the file to be uploaded. The filespec may contain a path and/or a filename. If a path is not provided, the file is sought in the default upload directory specified in Setup.

filespec	Valid only for and required with Ind$file transfers. It specifies the name of the file to be created on the host system.

Example

proc main

   transmit "U SendFile.ZIP^M"      ; Tell host that we're sending file.

   waitfor "Start Xfer"             ; Wait for signal to start transfer.

   sendfile ZMODEM "SendFile.ZIP"   ; Upload using ZMODEM protocol.

   while $XFERSTATUS                ; Pause script while transferring.

      yield                         ; Yield processing

   endwhile

;   .                               ; Other processes, or even other sendfile

;   .                               ; commands could follow the completion

;   .                               ; of the transfer.

endproc

Comments

Under ASPECT, file transfers are asynchronous operations, meaning that they can run independently of script execution. A getfile or sendfile command only initiates a file transfer attempt. While the transfer is processing, ASPECT executes the next commands in the script. If the script needs to wait for the transfer to complete, a while loop like the one shown in the example should be used to "stall" the script.

If the script executes a while loop to monitor the status of an on-going file transfer, you may find it useful to include the yield command within the loop. The yield command causes ASPECT to release its processing time to the system, which can improve file transfer performance.

The when $XFERSTATUS condition can be used to call a separate procedure if the value of $XFERSTATUS changes.

The Zmodem, Kermit, Ymodem, Ymodem-G, Xmodem, 1K-Xmodem, 1K-Xmodem-G, ASCII and Raw ASCII protocols require a single filespec for uploads. The CIS-B+ protocol does not require any filespec, as it is provided by the host. The Ind$file protocol is unique in that it requires two filespecs: one for local access of the stored file, and one specifying the name of the file as it will be created on the mainframe.

If index, string or DEFAULT is specified, the compiler will treat the filespecs as optional. It is up to the user to provide the proper filespec information based on the protocol.

For a list of the protocol names, index values, and sendfile filespec requirements, see Protocol Names and Indices.

See also

getfile, kermserve, yield and when $xferstatus; the set protocol, set aspect filexferbox and the protocol-specific set commands; File Transfer Commands.


sendkey

sendkey [ALT | CTRL | SHIFT | ALTSHIFT | ALTCTRLSHIFT | CTRLSHIFT]
vkey [EXTENDED]

Processes a keyboard shift state and a virtual key value and sends it to the focus window of the active application.

ALT ... CTRLSHIFT	The shift states of the described keys.

vkey	The virtual key value to process. For a complete list of virtual key code values, see Virtual Key Codes.

EXTENDED	Extends the range of keycode values to those used by the extended 101/102 keyboard.

Example

proc main

   winactivate $PWMAINWIN  ; Make sure Procomm Plus has focus.

   sendkey ALT 'F'         ; Send ALT-F to open file menu.

   mspause 250             ; Pause to wait for menu.

   sendkey 'L'             ; Send an 'l' to open playback.

   pause 2                 ; Pause to show of playback selection.

   sendkey ALT 'C'         ; Send ALT-C to cancel playback.

   ; Note that the difference between SENDKEY and TERMKEY is

   ; that TERMKEY sends the specified key code to the

   ; terminal window and SENDKEY sends the key code to the

   ; active window.

endproc

Comment

If your script uses the command set aspect keys on, any keys received by Procomm Plus when the main window has the input focus will be processed by sendkey.

See also

sendkeystr, keyget, termkey, termvkey, winfocus and sendvkey; $FOCUSWIN; set aspect keys; General Windows Commands.


sendkeystr

sendkeystr string

Sends a string to the active window or dialog, just as if the user had typed it.

Example

proc main

   termkey ALT 'O'         ; Send ALT-O to open "Online" menu.

   mspause 250             ; Pause to wait for menu.

   termkey 'A'             ; Send 'a' to select Capture option.

   pause 1                 ; Pause to wait for dialog.

   sendkeystr "BBS"        ; Send name of file to Capture open

                           ; dialog.

   pause 1                 ; Pause to wait for text entry.

   sendkey ALT 'O'         ; Send ALT-O to select "Ok" button.

endproc

Comment

The currently-active window receives keys representing all characters in the string. If the active window changes, however, the window that was active at the time the sendkeystr command was executed will still receive the keys. If the window is destroyed, any remaining keys not yet processed are discarded.

In addition to sending keys to an active Windows application, sendkeystr can also send keystrokes to another Procomm Plus session, if it is the active window.

See also

termkey, sendkey, sendvkey, taskactivate and winfocus; $FOCUSWIN and $TASK; set aspect keys command; General Windows Commands.


sendvkey

sendvkey keyval

Processes an encoded key value and sends it to the focus window of the active application.

keyval	An integer value representing both a key and the current keyboard state. For more information on keyval, see ASPECT Conventions. A complete list of virtual key code values is contained in Virtual Key Codes.

Example

proc main

   sendvkey 0x444          ; send ALT-D to bring up Dialing Directory

   sendvkey 0x44D          ; send Alt-M for manual dial

endproc

Comment

If your script uses the command set aspect keys on, any keys received by Procomm Plus when the main window has the input focus can be processed by sendvkey.

Keystrokes cannot be sent to a DOS compatibility window.

See also

termvkey, keyget, sendkey, sendkeystr, taskactivate and winfocus; the set aspect keys command; $ACTIVEWIN and $FOCUSWIN; General Windows Commands.


set

set param data

Changes system parameters that control various Procomm Plus and ASPECT operations. set commands can change the settings in Setup and the Connection Directory for your applications.

param	One or more keywords identifying the parameter to be changed.

data	The new setting for this parameter. Data can be a keyword, integer, long or string, depending on the parameter requirements.

Example

proc main

integer NumRows                  ; Number of terminal rows.

   fetch terminal rows NumRows   ; Get number of rows.

   set terminal rows 99          ; Make a lot of rows.

   pause 5                       ; Pause for effect.

   set terminal rows NumRows     ; Restore number of rows.

endproc

Comments

Any set command which expects a keyword when its value is being set will also allow an integer value to be used. The value is range-checked at run-time. This means that when a fetch statement is used to obtain the current setting, that same value returned by fetch can be used as an argument for the related set command. It is recommended, however, that a script use the keyword form when setting values not previously obtained from a fetch statement rather than using a hard-coded value.

To save changes to the current settings, use the setup save command. To restore the current changes, use the setup restore command.

To change a Connection Directory entry’s information, first use the set dialentry access command. To save or restore Connection Directory changes, use the dialsave and dialload commands.

set will return SUCCESS or FAILURE, depending on whether the set command could be executed. For complete information on set statements, refer to Set and Fetch Statements.

See also

fetch; General Procomm Plus Commands.


setjmp

setjmp id intvar

Marks a location within a script that you can immediately "jump" to with the longjmp command.

id	An integer id value identifying the marked location for the longjmp command.

intvar	An integer variable, initialized to 0 at execution. This variable will contain a new value when the longjmp is executed, allowing further processing, depending on the script’s execution at the point of the setjmp.

Example

proc main

   integer Done            ; Integer variable to indicate

                           ; that the routine is finished.

   setjmp 0 Done

   if Done != 42           ; See if routine was done.

      GetSysID()           ; Call proc to get System ID.

   endif

endproc

proc GetSysID

   integer Done = 0        ; Integer to return in LongJmp.

   if waitfor "42"         ; Check for text from remote.

      Done = 42            ; Set variable to show done.

   endif

   longjmp 0 Done          ; Jump to SETJMP 0 in Main.

endproc

Comments

The marked location is the command following the setjmp. It remains active until a return from the function where it was set, or until another routine uses a setjmp with the same id. Any number of setjmp locations can be active at once.

See also

longjmp, goto and call; Script Control Commands.


setpointer

setpointer integer integer

Moves the mouse pointer to the specified X/Y screen coordinates. setpointer is valid only when Procomm Plus is the active application.

integer	The X screen coordinate. The system variable $POINTERX returns this value for the current mouse pointer position.

integer	The Y screen coordinate. The system variable $POINTERY returns this value for the current mouse pointer position.

Example

proc main

   integer NewX, NewY               ; New X and Y location for mouse cursor.

   for NewX = 0 upto 639 by 10      ; Loop through every 10 pixels X.

      for NewY = 0 upto 479 by 10   ; Loop through every 10 pixels Y.

         setpointer NewX NewY       ; Set cursor location to X and Y.

      endfor

   endfor

endproc

See also

wincoord; $POINTERTASK, $POINTERWIN, $XPIXELS, $YPIXELS, $POINTERX and $POINTERY; General Procomm Plus Commands.


setup

setup SAVE | RESTORE

Manipulates the Procomm Plus Setup facility.

SAVE	Saves the current Procomm Plus settings to PW4.PRM.

RESTORE	Makes the last settings saved to PW4.PRM the current settings.

Example

proc main

   while $CARRIER       ; Suspend script while online.

      yield             ; Surrender processing time

   endwhile

   setup RESTORE        ; Restore setup in case changes

                        ; were made while online.

endproc

Comments

Typically, user changes are saved to disk as soon as the user presses OK to leave Setup. However, changes caused by an ASPECT script or by dialing a directory entry are not saved automatically. This prevents temporary settings from affecting the start-up settings. setup provides the ability to undo temporary changes, or to make them permanent.

setup RESTORE will fail if either the Connection Directory or Setup is open, if a file transfer or fax operation is in progress or if Procomm Plus is dialing a directory entry at the time setup executes.

See also

set; General Procomm Plus Commands.


shell

shell [intvar]

Displays the DOS command prompt.

intvar	An integer variable which will return the task id of the DOS session.

Example

proc main

   integer TaskId             ; Task id of the DOS shell.

   shell TaskId               ; Load and execute the DOS shell.

   while taskexists TaskId    ; Pause script while shell is running.

      yield                   ; Yield processing time

   endwhile

endproc

Comments

The DOS session created by the shell command will run full-screen or windowed, depending on the Windows mode and the settings in the _DEFAULT.PIF file. You may run any program that can be normally run from DOS at this time. To close the DOS window, type EXIT at the DOS command line.

shell sets SUCCESS/FAILURE depending on whether the DOS box was successfully opened. ASPECT will change to the directory specified in $USERPATH before attempting to execute the shell command.

See also

taskexists, metakey, dos and run; DOS- or Disk-Related Commands.


 shortpath

shortpath filespec strvar

Sets a string variable to contain the short path name of the filespec.

filespec	A string containing a path.

strvar	A string variable to receive the short version of filespec.

Comments

This command resolves paths with respect to the User Path. To obtain the long name of a file from the short name, call findfirst.  The command fails if the file cannot be found, or if the volume does not support 8.3 aliases.

See also

findfirst


snapshot

snapshot CLIPBOARD | CAPTURE | {FILE filespec} | PRINTER | SBBUFFER

Copies the contents of the current Terminal display to a disk file, the Windows Clipboard, the current Capture file, the system printer or the Scrollback Buffer.

CLIPBOARD	The Terminal display contents will be written to the Windows Clipboard. Any existing Clipboard contents will be erased.

CAPTURE	The Terminal display contents will be written to the Capture file. A Capture file must be open before snapshot executes.

FILE filespec	The Terminal display contents will be written to the specified file. If a path is not specified, the Capture path specified in Setup will be used.

APPEND	Appends the contents to the end of the file specified in filespec. If the file does not exist, it will be created.

PRINTER	The Terminal display contents will be printed.

snapshots to the printer are usually performed when print capturing is off. However, it may be useful for certain full-screen applications where data doesn’t scroll off the screen automatically.

SBBUFFER	The Terminal display contents will be written to the Scrollback Buffer.

Example

proc main

   integer Id                 ; Task id of NOTEPAD.

   snapshot FILE "scr.txt"    ; Capture screen to file.

   run "notepad scr.txt" Id   ; Run notepad for editing.

   while taskexists Id        ; Pause while Notepad's running.

      yield                   ; Give up processing time

   endwhile

endproc

Comments

The Terminal display contents captured by snapshot may be comprised of information from the Scrollback Buffer or from the current logical terminal screen. snapshot captures the information that is visible to the user at the time the command is executed.

If the file described by filespec already exists and the APPEND parameter is not given, its contents will be erased.

See also

sbsave and printcapture; Terminal Commands.


splitpath

splitpath filespec strvar strvar strvar strvar

Splits a file and pathname.

filespec	The source filespec.

strvar	Will contain the drive letter and colon, for example, "E:".

strvar	Will contain the path information, for example, "\PROCOMM PLUS\ASPECT\"

strvar	Will contain the filename, for example, "FIDDLER"

strvar	Will contain the filename extension, if any. For example, "BMP".

Example

proc main

   string FullName             ; Full name of file with path.

   string DriveStr             ; Drive from path above.

   string PathStr              ; Path to file from above.

   string FName                ; Name of the file.

   string FNameExt             ; Extension of the file.

   ; Set FullName to a file name with path and split it

   ; into its 4 components.

   FullName = "c:\program files\bin\pw4.exe"

   splitpath FullName DriveStr PathStr FName FNameExt

   usermsg "Name = `"%s`", Extension = `"%s`"." FName FNameExt

endproc

See also

getfilename, getpathname and makepath; DOS- or Disk-Related Commands.


statclear

statclear

Clears the status line at the bottom of the Terminal window.

Example

proc main

   while 1                       ; Loop forever.

      if not nullstr $STATMSG    ; See if there's anything on stat

         statclear               ; line and if so, clear it.

      else

         yield                   ; Otherwise, yield our time

      endif

   endwhile

endproc

See also

statmsg and clear; General Procomm Plus Commands.


statmsg

statmsg string | {formatstr arglist} [beep]

Displays a formatted message on the Terminal window status line. The message remains visible until another command clears or resets it.

string	A string of up to 256 characters.

formatstr	A string constant or variable, which may contain format specifiers. For a detailed explanation of formatstr, see Formatting Text and Data.

arglist	An optional list of up to 12 arguments matching specifiers within the formatstr.

beep	An optional parameter which sounds the Miscellaneous errors sound defined in the System | System Options panel within Setup.  If this sound is not defined, the Windows default beep sound is played. The message text will blink for the duration of the beep.

Example

proc main

   string Curr, Prev = ""     ; Current and previous time values.

   while 1                    ; Loop forever.

      ltimestring $LTIME Curr ; Get current time string value.

      if not strcmp Curr Prev ; See if the time string value has

         statmsg Curr         ; changed. If so, update stat

         Prev = Curr          ; line and Prev time value.

      endif

   endwhile

endproc

See also

errormsg, sdlgmsgbox, statclear, termmsg and usermsg; General Procomm Plus Commands.


strcat

strcat strvar string [strlength]

Concatenates a string onto a string variable.

strvar	The variable to which the second string is concatenated. The resulting string must be less than or equal to 256 characters in length; it is always null-terminated.

string	The string constant or variable concatenated to strvar.

strlength	An integer specifying the maximum number of characters to be copied from the second string.

Example

proc main

   string FirstStr, SecondStr    ; Strings to concatenate.

   string ThirdStr               ; Third string to concatenate.

   FirstStr = "Negative, "       ; Assign value to first string.

   SecondStr = "Neutral "        ; Assign value to second string.

   ThirdStr = "Positive"         ; Assign value to third string.

   strcat FirstStr SecondStr     ; Concat. first string to second.

   strcat FirstStr "or "         ; Concat. "or"

   strcat FirstStr ThirdStr      ; Concat. first and second to third.

   strcat FirstStr "?"

   usermsg FirstStr              ; Display newly formed message.

endproc

See also

strcpy, strupdt and strfmt; String Commands.


strchr

strchr string character [intvar]

Searches for the first occurrence of a character in a given string, returning SUCCESS or FAILURE depending on the outcome.

string	The string constant or variable to search.

character	The desired character value, between 0 and 255 inclusive.

intvar	If specified, will contain the zero-based index within the string where the character occurs or -1 if the character is not contained within the string.

Example

proc main

   string TextStr                ; Text string to search.

   TextStr = "1 2 3 4 5 6"       ; Assign value to search string.

   if strchr TextStr '5'         ; Look for target char in string.

      usermsg "Search string contains target char!"

   else

      usermsg "Search string doesn't contain target char!"

   endif

endproc

See also

strcspn, strrchr, strsearch, strfind, strcmp, stricmp, strncmp and strnicmp; String Commands.


strcmp

strcmp string string [intvar]

Performs a case-sensitive comparison on two strings, for the length of the shorter string.

string	The first string constant or variable.

string	The second string constant or variable.

intvar 	If specified, intvar will be set to 0 if the strings are identical. It will be greater than 0 if the first string is lexicographically greater than the second and less than 0 if the first string is lexicographically less than the second.

Example

proc main

   string FirstStr, SecondStr      ; Two strings to compare.

   FirstStr = "First"              ; Assign arbitrary value to first.

   SecondStr = "Second"            ; Assign arbitrary value to second.

   if strcmp FirstStr SecondStr    ; See if the two strings match.

      usermsg "The two strings are identical."

   else

      usermsg "The two strings are different."

   endif

endproc

Comments

For case-insensitive comparisons, see stricmp or strnicmp. To compare strings for a specified number of characters, see strnicmp or strncmp.

See also

stricmp, strfind, strnicmp, strncmp, rstrcmp, strupr and strlwr; String Commands.


strcpy

strcpy strvar string [strlength]

Assigns a string to a string variable.

strvar	The target string variable. It will always be null-terminated.

string	The string constant or variable to be copied. It can contain "raw" data to be copied.

strlength	An integer specifying the maximum number of characters to copy from the second string.

Example

proc main

string Source, DestStr         ; Strings to copy from and to.

   Source = "Copy String!"     ; Assign value to source string.

   strcpy DestStr Source       ; Copy source string to destination.

   usermsg DestStr             ; Display the destination string.

endproc

Comments

Strings can also be assigned to each other with the assignment operator "=". For example, S0 = S3.

See also

strfmt, substr and strupdt; String Commands.


strcspn

strcspn string string [intvar]

Searches a string for a character contained in a second string.

string	The string to be searched.

string	A string containing the characters to be tested.

intvar	If specified, will return the position of the first character in the first string which equals a character contained in the second string.

Example

proc main

   string Text1               ; First text string.

   string Text2               ; Second text string.

   integer Pos                ; Location where the two strings

                              ; are the same.

   Text1 = "This text will be searched for [S,s,e,a,r,c,h,t, ' ' or .]."

   Text2 = "Search characters."

   strcspn Text1 Text2 Pos    ; Find a contained character

   usermsg "The strings match at %d." Pos

endproc

Comments

If no characters within the second string are found in the first string, strcspn will return the length of the first string, and report FAILURE. strcspn’s results are zero-indexed.

To search for characters that do not occur in a string, see the strspn command.

See also

strspn, strcmp, stricmp, strncmp, strnicmp and rstrcmp; String Commands.


strdelete

strdelete strvar strindex strlength

Removes characters from the contents of a string variable.

strvar	The target string variable.

strindex	The index of the first character in the string to be removed.

strlength	An integer specifying the number of characters to remove, beginning at the location specified by strindex.

Example

proc main

   string Source                 ; String to use as source.

   string TargetStr              ; String to use as target.

   integer Pos                   ; Integer to contain pos of item.

   integer Len                   ; Integer to contain len of item.

   integer nItem = 0             ; Initialize current item pointer.

   integer Choice                ; Integer used in standard dialog.

                                 ; Assign a list to our source string. We set all

                                 ; characters in string to NULL to make sure

                                 ; that the string is truly empty.

   strset Source 0 0 255         ; Set string to NULL's.

   Source = "Red,Yellow,Blue,Green,Orange,Purple"

   while 1                       ; Loop forever, or until EXITWHILE.

      ; Extract item indicated by Item pointer and prompt

      ; user to delete or leave item in source string.

      strextract TargetStr Source "," nItem

      if nullstr TargetStr       ; Check to see if we've reached

         exitwhile               ; the end of source string

      endif                      ; and if so, exit loop.

      sdlgmsgbox "Remove?" TargetStr QUESTION YESNO Choice

      if Choice == 6             ; Check to see if user chose "YES"

                                 ; and if so, find pos in source.

         strfind Source TargetStr Pos

         strlen TargetStr Len    ; Get length of item and add

         Len++                   ; one to account for comma.

         ; Delete target string from source string.

         strdelete Source Pos Len

      else

         nItem++                 ; Increment pointer to next item.

      endif

   endwhile

   usermsg Source                ; Display resulting list.

endproc

See also

strextract, strinsert, strreplace, strtok and substr; String Commands.


strextract

strextract strvar string string integer

Returns a string from a list of elements.

strvar	A string variable which will receive the output characters.

string	A list of elements separated by a common series of characters.

string	The common series of characters that separate each element in the list string. This string could contain a single character such as a space, comma or tab, or several characters.

integer	A zero-based integer specifying the occurrence to return.

Example

proc main

   string FileList             ; String to contain list of files.

   string CurFname             ; String to contain current file.

   integer nItem = 0           ; Integer to indicate current file.

   ; Assign a list of files to our file list string and

   ; check all files to see that they exist in current

   ; directory.

   FileList = "File.txt,Second.doc,Three.lst"

   while 1                     ; Loop forever, or until EXITWHILE.

                               ; Extract file from list and confirm

                               ; file exists. If not, display message.

      strextract CurFname FileList "," nItem

      if not nullstr CurFname  ; See if we're at the end of list.

         if not isfile CurFname   ; If not, see if the file exists.

            errormsg "File `"%s`" doesn't exist." CurFname

         endif

         nItem++               ; Increment our item pointer.

      else

         exitwhile             ; If blank file name, exit loop.

      endif

   endwhile

endproc

Comments

strextract is useful for extracting specific items from a comma- or tab-separated string. To determine the number of items in a delimited string list, use the strsearch command.

See also

strchr, strcspn, strfind, strsearch, strtok and substr; String Commands.


strfind

strfind string string [intvar] [MATCHCASE]

Tests for an occurrence of the specified text within a string, reporting SUCCESS or FAILURE depending on the outcome of the test.

string	The string constant or variable to be searched.

string	The string constant or variable containing the target characters.

intvar	An integer variable that if specified, will contain the zero-based index within the string where the first character of the search string occurs or -1 if the search string is not contained within the string.

MATCHCASE	By default, strfind is case-insensitive. Specifying MATCHCASE forces a case-sensitive search.

Example

proc main

   string TextStr                   ; Text string to search.

   TextStr = "Brave New World."     ; Assign value to string.

   if strfind TextStr "World"       ; Check for target text in string.

      usermsg "Target string found in search string!"

   else

      errormsg "Target string not found in search string!"

   endif

endproc

See also

strchr, strcspn, strsearch and strrchr; String Commands.


strfmt

strfmt strvar formatstr [arglist]

Creates a formatted string using a template, and modifies it with string or numeric variables. strfmt is similar to "sprintf" in the C programming language.

strvar	Variable where the formatted string will be stored. The maximum length of the expanded string is 256 characters.

formatstr	A string constant or variable, which may contain format specifiers. For a full description of the format specifiers supported by ASPECT, see Formatting Text and Data.

arglist	An optional list of up to 12 arguments matching specifiers within the formatstr. Values are taken sequentially, left-to-right from the first parameter listed to the last for format types found in the formatstr.

Example

proc main

   integer X, Y, Z               ; Integers for point coordinates.

   string Coords                 ; String for formatted coords.

   ; Insert integer values into format string and display

   ; the new string contents.

   X = 5, Y = 29, Z = 2          ; Assign values to variables.

   strfmt Coords "Point at (%d, %d, %d)." X Y Z

   usermsg Coords

endproc

See also

strcpy, strupdt and strcat; String Commands.


strgetc

strgetc string strindex intvar

Returns the ASCII value of a single character within a string.

string	The source string.

strindex	The character position of the desired character.

intvar	Will contain the character value.

Example

proc main

   integer Pos = 0                       ; Integer index within string.

   integer Chr = -1                      ; Character from string.

   string TextStr                        ; String to get characters from.

   string HexStr = ""                    ; String to contain hex values.

   string Hex                            ; String used for hex conversion.

   TextStr = "Add these characters!"     ; Assign text to string.

   while Chr != 0                        ; Loop while character not null.

      strgetc TextStr Pos Chr            ; Get character from string.

      strfmt Hex "%02X " Chr             ; Convert character to hex.

      strcat HexStr Hex                  ; Add char to string of hex values.

      Pos++                              ; Increment index within string.

   endwhile

   usermsg HexStr                        ; Display newly created hex string.

endproc

See also

strchr, strcspn, substr and strputc; String Commands.


stricmp

stricmp string string [intvar]

Performs a case-insensitive comparison of two strings.

string	The first string constant or variable.

string	The second string constant or variable.

intvar	If specified, intvar will be greater than zero if the first string is lexicographically greater than the second, 0 if the strings are equal, and less than zero if the second string is greater than the first.

Example

proc main

   string First, Sec          ; Two strings to compare.

   First = "lower case"       ; Assign value to first string.

   Sec = "LOWER CASE"         ; Assign value to second string.

   if stricmp First Sec       ; See if the two strings match

      usermsg "The two strings are identical."

   else

      usermsg "The two strings are different."

   endif

endproc

Comments

stricmp performs a case-insensitive comparison for the length of the shorter string. To perform comparisons on specified string lengths, see strncmp or strnicmp.

See also

strcmp, strncmp, strnicmp and rstrcmp; String Commands.


string

string name[=expression][,name[=expression]]...

Defines a global or local string variable, or an array of string variables.

name	The name of the new variable. Name must follow the standard ASPECT naming conventions. When defining an array, the subscript expression must result in a constant value.

=string	An initializer expression. It can be a quoted string or a previously-declared string variable, or a function that returns a string result.

Example

proc main

string TextStr               ; Text to display.

   if sdlginput "Input Text" "Text:" TextStr

      usermsg "You entered `"%s`"." TextStr

   endif

endproc

Comments

Up to 256 global string variables can be defined, as well as 256 global string arrays. Local string definitions are limited by the available stack space at the time the procedure or function is called. See User-defined Variables, Global and Local Variables and Arrays.

See also

param, long, float and integer; ASPECT Primary Commands.


strinsert

strinsert strvar string strindex [strlength]

Inserts the contents of a string into another string.

strvar	The target string. Its resultant length must be less than or equal to 256 characters.

string	A string constant or variable containing the characters to be inserted.

strindex	The index within the strvar to insert the specified characters.

strlength	If specified, the number of characters from the source string to insert into strvar. Otherwise, a null-terminated string is assumed and the string will be inserted up to the null character. Raw data can be inserted by specifying a strlength.

Example

proc main

   string Presidents                ; String to insert from.

   string Name                      ; String to insert into.

   ; Assign a list of presidents to our target string variable.

   ; Get name from user and insert it into list. And

   ; display the new list of presidents.

   Presidents = "Lincoln,Jefferson,Washington,Roosevelt"

   sdlginput "Presidents" "Name: " Name

   if not nullstr Name              ; See if a NULL was entered.

      strcat Name ", "              ; Add comma and space to name.

      strinsert Presidents Name 0   ; Insert name into president list.

   endif

   usermsg Presidents               ; Display list of presidents.

endproc

See also

strcpy, strdelete, strfmt and strupdt; String Commands.


strlen

strlen string intvar

Returns the length of a null-terminated string into an integer variable.

intvar	Will equal the count of characters in the string, up to but not including the null character, ASCII 0.

Example

proc main

   integer Len                ; Integer for length of string.

   string TextStr             ; String to test for length.

   ; Assign value to text string, find the length, and

   ; display the length.

   TextStr = "This is an example string."

   strlen TextStr Len         ; Get length of text string.

   usermsg "Text string contains %d characters." Len

endproc

See Also

String Commands.


strlwr

strlwr strvar

Converts the contents of a string variable to all lowercase characters.

strvar	The string to be converted to lowercase.

Example

proc main

   string DataStr                    ; String to contain data from port.

   transmit "Send me data!"          ; Signal remote host to send data.

   if rget DataStr 6                 ; Get text from remote host.

      strlwr DataStr                 ; Convert text to lower case

                                     ; for comparison.

      if strcmp DataStr "Test"       ; See if text is what we expect.

         usermsg "Text found!"       ; If so, display message found.

      else                           ; If not, display message not found.

         usermsg "Text not found!"

      endif

   else                              ; If no text from host, display error.

      errormsg "No text from remote!"

   endif

endproc

See also

strupr; String Commands.


strncmp

strncmp string string strlength [intvar]

Performs a case-sensitive comparison of two strings for a specified length.

string	The first string constant or variable.

string	The second string constant or variable.

strlength	An integer specifying the maximum number of characters to be compared.

intvar	If specified, intvar will be greater than zero if the first string is lexicographically greater than the first, 0 if the strings are equal, and less than zero if the second string is greater.

Example

proc main

   string Text1, Text2            ; Strings to compare.

   Text1 = "STRNCMP compares items to specified length."

   Text2 = "STRNCMP compares"

   if strncmp Text1 Text2 16      ; Compare two text strings.

      usermsg "The two strings match!"

   else

      usermsg "The two strings don't match."

   endif

endproc

See also

strcmp, stricmp, strnicmp and rstrcmp; String Commands.


strnicmp

strnicmp string string strlength [intvar]

Performs a case-insensitive comparison of two strings for a specified length.

string	The first string constant or variable.

string	The second string constant or variable.

strlength	An integer specifying the maximum number of characters to be compared.

intvar	If specified, intvar will be greater than zero if the first string is lexicographically greater than the first, 0 if the strings are equal, and less than zero if the second string is greater.

Example

proc main

   string Text1, Text2           ; Strings to compare.

   Text1 = "Whales are amazing creatures."

   Text2 = "WHALES are MAMMALS."

   if strnicmp Text1 Text2 11    ; Compare the two strings.

      usermsg "The two strings match!"

   else

      usermsg "The two strings don't match."

   endif

endproc

See also

strcmp, strncmp, stricmp and rstrcmp; String Commands.


strputc

strputc strvar strindex character

Modifies the value of a single character within a string.

strvar	The target string. strputc can be used to shorten a string variable by specifying a character value of 0 at the desired strindex location.

strindex	The position within the string to place the character. strindex is zero-based from the beginning of the string.

character	The character to put into the string.

Example

proc main

   integer Pos = 0               ; Integer index within string.

   integer Chr = -1              ; Character from source string.

   string Source                 ; String to get chars from.

   string DestStr                ; String to put chars into.

   Source = "Copy me!"           ; Assign text to string.

   while Chr != 0                ; Loop while character not null.

      strgetc Source Pos Chr     ; Get char from source string.

      strputc DestStr Pos Chr    ; Put char into dest string.

      Pos++                      ; Increment index within source.

   endwhile

   usermsg DestStr               ; Display destination string.

endproc

See also

strgetc, strinsert, strupdt and strset; String Commands.


strquote

strquote strvar

Places the contents of a string variable in double quotes.

Example

proc main

   string Quote               ; String to contain quote.

   string Sig                 ; String to contain signature.

   ; Assign quote to quote string and signature

   ; to signature string. Then display both.

   Quote = "A Penny Saved is a Penny Earned"

   Sig = "`r`r`t`t-Ben Franklin"

   strquote Quote             ; Add quotation marks.

   strcat Quote Sig           ; Attach signature to quote.

   usermsg Quote              ; Display the quote.

endproc

See also

strfmt; String Commands.


strrchr

strrchr string character [intvar]

Searches for the last occurrence of a character in a given string, reporting SUCCESS or FAILURE depending on the outcome of the search. strrchr behaves identically to strchr, except that its search begins at the end or "right" of the target string.

string	The string constant or variable to search.

character	The desired character value between 0 and 255 inclusive.

intvar	An integer variable that if specified, will contain the zero-based index within the string where the character occurs or -1 if the character is not contained within the string.

Example

proc main

   integer Pos                ; Position of character.

   ; Find the last occurrence of the letter 'f' in

   ; the string and display its position.

   if strrchr "A string full of characters." 'f' Pos

      usermsg "'f' was found at %d." Pos

   else

      usermsg "'f' not found in string!"

   endif

endproc

See also

strchr, strsearch, strfind, strcmp, stricmp, strncmp, strcspn and strnicmp; String Commands.


strread

strread string strindex numvar | {strvar strlength}

Reads a block of data from a string.

string	The string to access.

strindex	An integer value, equal to the number of bytes from the start of the string, specifying the location of the data to be read.

numvar	A float, integer, or long variable.

strvar strlength	A string variable, with a specified number of characters to be read.

Example

proc main

   integer count, index, value

   string intvals

   if comread intvals (10 * sizeof(integer))

       for count = index = 0 upto 9          ; loop 10 times

          strread intvals index value        ; read integer from string

          index += sizeof(integer)           ; increment string index

          usermsg "The value of integer index %d is: %d" count value

       endfor

   endif

endproc

Comments

ASPECT automatically determines the number of bytes to read if a numeric variable is specified for strread. An integer argument will cause 4 bytes to be read from the string; a long will read 4 bytes, and a float 8 bytes. A string will read the number of bytes specified in strlength.

See Also

strwrite, strgetc, and substr.


strreplace

strreplace strvar string string [integer] [MATCHCASE]

Searches a string variable for a specific character or pattern of characters, replacing the target character or character pattern with another string.

strvar	The string variable to be searched and updated.

string	The target character or pattern of characters to be replaced.

string	The replacement text. If string is specified as empty quotations (""), the target character(s) will be deleted and not replaced.

integer	An optional value specifying the maximum number of replacements to perform. The default is all occurrences found of the target text.

MATCHCASE	If specified, forces the search to be case-sensitive.

Example

proc main

   string TextStr             ; String in which to replace text.

   ; Assign a value to our string variable and correct our

   ; bad grammar. We'll change the occurrence of

   ; "ain't" to "is still".

   TextStr = "`"Ain't`" ain't bad grammar everywhere!"

   strreplace TextStr "ain't" "is still"

   usermsg TextStr            ; Display our text string.

endproc

See also

strputc, strdelete, strinsert, strsearch, strfind, strfmt and strextract; String Commands.


strrev

strrev strvar

Reverses the contents of a string variable.

Example

proc main

   string TextStr             ; String to contain palindrome.

   string Backwards           ; String to contain reverse of text.

   while 1                    ; Loop forever.

      ; Get a palindrome candidate from the user and check

      ; to see if it's truly a palindrome.

      sdlginput "Enter Palindrome" "Text: " TextStr

      if !SUCCESS             ; If "Cancel" is selected, exit

         exitwhile            ; loop.

      endif

      Backwards = TextStr     ; Set reverse string to text.

      strrev Backwards        ; Reverse our backwards string.

      ; See if the forward string matches reverse string.

      if stricmp TextStr Backwards  ; Ignore character case

         usermsg "Congrats! `"%s`" is a Palindrome." TextStr

      else

         errormsg "`"%s`" is not a Palindrome!" TextStr

      endif

   endwhile

endproc

See also

strright, strupdt and strputc; String Commands.


strright

strright strvar string strlength

Copies a string of characters from the end of a string. strright behaves identically to substr, except that it returns the characters from the right side of the string without having to specify a starting index.

strvar	The output string.

string	The input string.

strlength	The number of characters to return.

Example

proc main

   string Name                ; Strings to contain full name and

   string LastName            ; last name.

   integer Pos                ; Integers for pos of space char and

   integer Len                ; length of name string.

   ; Get users full name, excluding middle initial,

   ; extract user's last name and display it.

   sdlginput "Enter Name" "Full Name: " Name

   if SUCCESS

      if not nullstr Name     ; Check to see if name is null.

         strlen Name Len      ; Get length of string entered.

         strchr Name ' ' Pos  ; Find first occurrence of space.

         if Pos == 0          ; Check to see if index is negative.

            Pos = 0           ; Set position to zero position.

         else

            Pos++             ; If space found, set pos to next

         endif                ; character.

         ; Figure number of characters to extract and

         ; extract them from right side of name string.

         Len = Len - Pos

         strright LastName Name Len

         usermsg "Last Name is `"%s`"." LastName

      else                    ; If name is null, display error.

         errormsg "No name entered!"

      endif

   endif

endproc

See also

strcpy, substr and strextract; String Commands.


strsearch

strsearch string string [intvar] [MATCHCASE]

Searches a string for a specific character or pattern of characters.

string	The string to be searched.

string	The target character or pattern of characters.

intvar	The number of occurrences of the target.

MATCHCASE	If specified, forces the search to be case-sensitive.

Example

proc main

   string TextStr                ; Text string to search.

   integer Number                ; Integer for number of occurr.

   TextStr = "1 2 3 4 5 6"       ; Assign value to search string.

   ; Find and display the number of spaces in string.

   strsearch TextStr " " Number

   usermsg "There are %d spaces in search string." Number

endproc

Comments

strsearch can be used to count delimiting characters within a string, making it extremely useful with strextract and list operations.

See also

strcspn, strchr, strrchr, strfind, strreplace and strextract; String Commands.


strset

strset strvar strindex character strlength

Sets the characters in a string variable to a specified ASCII value.

strvar	The target string variable. It is not automatically null-terminated.

strindex	The starting position within the target string.

character	The value to set, from 0 to 255, inclusive.

strlength	The number of character positions to set. The starting position plus strlength must not exceed the allowed length of an ASPECT string variable, or an error will occur at run-time.

Example

proc main

   string TextStr                ; String to contain 40 asterisks.

   strset TextStr 0 '*' 40       ; Set string for 40 asterisks.

   usermsg TextStr               ; Display the 40 asterisks.

endproc

See also

strputc, strdelete, strupdt and strinsert; String Commands.


strsltime

strsltime string string longvar

Converts a date string and time string into a long variable.

string	The date, in the format specified by Short date style in the Date tab of the Regional Settings section of the Windows Control Panel.

string	The time, in the format specified by Time style in the Time tab of the Regional Settings section of the Windows Control Panel.

longvar	Will receive the resultant timeval.

Example

proc main

   string FirstStr                  ; String to contain first date.

   string SecondStr                 ; String to contain second date.

   long LTime1, LTime2              ; Longs to contain long dates.

   long Diff                        ; Long to contain difference.

   FirstStr = "01/01/95"            ; Set beginning date.

   SecondStr = "12/31/99"           ; Set ending date.

   ; Convert first and second dates to long values and

   ; calculate number of days between them.

   strsltime FirstStr $TIME24 LTime1

   strsltime SecondStr $TIME24 LTime2

   Diff = ( LTime2 - LTime1 ) / 86400

   usermsg "%d days between %s and %s" Diff FirstStr SecondStr

endproc

Comments

This command will set FAILURE if an invalid date string and/or time string is used as an argument to the command.

See also

ltimestrs, intsltime and ltimestring; $LTIME, $DATE and $TIME; Date and Time Commands.


strspn

strspn string string [intvar]

Searches a string for the first character that does not occur within a second string.

string	The string to be searched. If it is comprised entirely of characters from the second string, strspn will return the length of the first string and report FAILURE.

string	The string containing the target character(s). To search for characters in a string that do occur within another string, see the strcspn command.

intvar	If specified, will return the position of the first character in the first string which does not occur in the second string.

Example

proc main

   string Text1               ; First text string.

   string Text2               ; Second text string.

   integer Pos                ; Location where uncontained char appears.

   integer Char               ; Character at location

   Text1 = "This text is tested for any character but [S,s,e,a,r,c,h,t, ' ' or .]."

   Text2 = "Search characters."

   if strspn Text1 Text2 Pos  ; Find where strings differ.

      strgetc Text1 Pos Char  ; Get the uncontained char value

      usermsg "The character [%c] appears in Text1 but not in Text2!" Char

   else

      usermsg "All characters in Text1 appear in Text2"

   endif

endproc

See also

strchr, strcspn, strfind, strrchr, strsearch; String Commands.


strtoclip

strtoclip string | {formatstr arglist}

Copies information from a string to the Windows Clipboard.

string	A string of up to 256 characters.

formatstr	A string of up to 256 characters. The string can contain text and/or format specifiers. For more information, see Formatting Text and Data.

arglist	Up to 12 arguments may be specified for the formatstr to process. These arguments must appear in the order they were specified within the formatstr.

Example

proc main

   string TextToCopy          ; Text to put into NOTEPAD.

   TextToCopy = "This text should appear in the notepad window."

   strtoclip TextToCopy       ; Copy string to clipboard.

   run "notepad.exe"          ; Run Windows NOTEPAD.

   pause 1                    ; Pause to wait for NOTEPAD.

   sendkey ALT 'E'            ; Send ALT-E to open "Edit" menu.

   mspause 250                ; Pause to wait for NOTEPAD.

   sendkey 'P'                ; Select PASTE to paste string.

endproc

See also

cliptofile, cliptostr and filetoclip; Clipboard Commands.


strtok

strtok strvar strvar string [integer]

Parses a delimited string into tokens.

strvar	Will be assigned the token string.

strvar	The delimited source string. Its contents will be altered by strtok. As tokens are written to the first strvar, they are removed from the delimited source strvar.

string	A string constant or variable containing delimiters for the search. If more than one delimiter is specified in this string, strtok searches for the first occurrence of a character not within the delimiter set.

integer	Optional parameter with a value of 1 or greater, specifying the occurrence of a token to extract. If this argument is given, all tokens preceding the specified token index will be thrown away.

Example

proc main

   string DataStr                 ; String to contain data.

   string ItemStr                 ; String to contain extracted item.

   DataStr = "4D,61,72,6B,75,73"  ; Assign hex values to data list.

   while 1                        ; Loop forever, or until EXITWHILE.

      strtok ItemStr DataStr "," 1 ; Get first item from data list.

      if nullstr ItemStr          ; Check to see if item is null.

         exitwhile                ; If so, exit loop.

      endif

      usermsg "Data item is `"%s`"." ItemStr

   endwhile

endproc

See also

strextract, strspn, strcspn and strsearch; String Commands.


strtonum

strtonum string numvar [integer]

Converts a string to a numeric value.

string	The string to convert.

numvar	The result of the conversion.

integer	If specified, the base value of the number to be converted. Valid values range from 2 to 36, inclusive. If a base is not specified it will be determined by the first two characters of the string. If the first character is 0 (zero) and the second character is NOT x or X, octal notation will be assumed and the string will be converted using base 8. If the first character is a 0 (zero) and the second character is an x or X, hex notation will be assumed and the sting will be converted using base 16. If the first character is a digit from 1 to 9, decimal notation will be assumed and the string will be converted using base 10. If the first character is a + (plus) or - (minus) the base will be determined using the second and third characters. Bases greater than 10 use the alphabetical characters A to Z to represent digits greater than 9.

The base specifier is not valid for floating-point conversions.

Example

proc main

   string BinaryNum                  ; Binary number.

   integer Number                    ; Binary converted to decimal.

   BinaryNum = "00101010"            ; Set binary number.

   strtonum BinaryNum Number 2       ; Convert number to base 10.

   usermsg "And the number is...%d!" Number

endproc

See also

atof, atoi, atol and numtostr; Numeric, String Conversion Commands.


strupdt

strupdt strvar string strindex strlength

Overwrites a string with another string at a specified index. strupdt is similar to strputc, but the characters replaced in the target string are taken from a string rather than an integer.

strvar	The target string which will be overwritten. If strupdt writes past the end of strvar, strvar will not automatically be null-terminated, unless the null character from the source string is copied.

string	The source string, which will be written to the first string. It may include "raw" character data, including nulls, ASCII 0.

strindex	The starting position in the target string where the source string will be written. strindex is zero-based.

strlength	The number of characters to write. strlength plus strindex must not exceed 256, the maximum length of a string, or a run-time error will occur.

Example

proc main

   string TargetStr              ; String to contain target text.

   string Source                 ; String to contain source text.

   ; Assign values to target and source strings.

   TargetStr = "There is a test"

   Source = "This was an example"

   strupdt TargetStr Source 0 8  ; Update target with first three

   usermsg TargetStr             ; characters of source and

                                 ; display resulting string.

endproc

See also

strputc, strfind, strinsert and strreplace; String Commands.


strupr

strupr strvar

Converts the contents of a string variable to all uppercase characters.

strvar	The string to be converted to uppercase.

Example

proc main

   string TextStr             ; String to convert to upper case.

   ; Get user id, convert to uppercase, and send it to host

   sdlginput "Enter Id" "User ID: " TextStr

   strupr TextStr             ; Convert text to upper case.

   transmit TextStr           ; Transmit upper case string to host

endproc

See also

strlwr; String Commands.


strwrite

strwrite string strindex numvar | {strvar strlength}

Writes a block of data to a string.

string	The target string.

strindex	An integer value, equal to the number of bytes from the start of the string, specifying the starting position of the strwrite operation.

numvar	A float, integer, or long variable to be written.

strvar strlength	A string variable, with a specified number of characters to be written.

Example

proc main

   integer count, index

   string intvals

   for count = index = 0 upto 9             ; loop 10 times

      strwrite intvals index count          ; write integer value to string

      index += sizeof(integer)              ; increment string index

   endfor

endproc

Comments

ASPECT automatically determines the number of bytes to be written if a numeric variable is specified for strwrite. An integer argument will cause 4 bytes to be written to the string; a long will write 4 bytes, and a float 8 bytes. A string writes the number of bytes specified in strlength.

See Also

strread, strputc, and strupdt.


substr

substr strvar string strindex strlength

Copies the indicated number of characters from a string, beginning at a specified position.

strvar	The target string.

string	The source string. It can contain "raw" character data.

strindex	The character position in the source string from which copying should begin. The value is zero-indexed.

strlength	The number of characters to extract from the source string. strlength plus strindex must not exceed 256, the maximum length of a string, or a run-time error will occur.

Example

proc main

   string Message                ; String to contain message.

   string MsgCode                ; String to contain message code.

   comread Message 50            ; Get message sent by host system.

   substr MsgCode Message 1 3    ; Extract hypothetical three digit

                                 ; code, maybe encased in brackets.

                                 ; "[123] Message", for example.

   usermsg "Error code = %s" MsgCode

endproc

See also

strgetc, strupdt, strcpy, strsearch and strfind; String Commands.


switch

switch integer | long | { string [strlength] [MATCHCASE] }

case string | integer | long

...

[exitswitch]

...

[endcase]

[default]

...

endcase

endswitch

Provides multiple decision points by comparing a string, integer or long to one or more values. switch requires the use of case, endcase and endswitch commands. The use of the default command is optional.

integer | long | string	The source variable or constant to be compared with the string or value specified in each case statement.

strlength	If specified, determines the number of characters to test in the comparison(s).

MATCHCASE	String comparisons are case-insensitive by default. MATCHCASE causes them to be case-sensitive.

case string |  integer | long	Compares the switch command’s source argument to the "target" of the case command.
If the switch argument does not match a case target, the processing of subsequent case or default commands continues.

When a match is found between the switch source and the case target, command processing continues on the line following the case command until an endcase or exitswitch command is encountered.

Items in the case statement must match the data types used in the switch statement. For example, you cannot compare a string to an integer.

exitswitch	Causes processing to pass unconditionally to the command on the line following the endswitch statement. Statements between exitswitch and endswitch will not be processed.

endcase	Concludes processing of commands following a case or default command and passes control to the command on the line following the endswitch command. The endcase command is an implied exitswitch. Once an endcase is encountered, the only commands that can follow it are another case, a default or an endswitch.

default	An optional statement used within the switch structure. If no match is found in any previous case statement, the commands following the default statement will be processed unconditionally until an endcase or exitswitch command is encountered. Processing then passes to the command on the line following the endswitch command. default has no effect on overall execution.

endswitch	Terminates a switch command group.

Example

proc main

   integer Alpha = 2             ; Integer to check in switch case.

   switch Alpha                  ; Find value of numeric variable

      case 0                     ; and display corresponding

         usermsg "Alpha = 0"     ; message.

      endcase

      case 1

         usermsg "Alpha = 1"

      endcase

      case 2

         usermsg "Alpha = 2"

      endcase

   endswitch

endproc

Comments

A switch statement, in effect, substitutes for a group of if/elseif/else conditions. switch statement groups can be nested if required.

switch supports multiple case commands within a single case...endcase statement group. A single statement group can be executed by matching the target item with any one of several case commands. Since the end of a command group is always an endcase command, at least one endcase must occur whenever case or default is used.

If a case target is matched, the statements following it are executed until an endcase or exitswitch is encountered. If another case is encountered, it’s skipped. Execution then falls through to the next commands following the matched case target. If a match is made with more than one case command, only the statements following the first matched case command will be executed.

The default command is optional, but there can be only one occurrence of it within a switch statement group. If a default isn’t used and none of the case commands were matched, no action takes place at all.

default can occur anywhere within the switch statement. case statements occurring between default and its terminating endcase or exitswitch will be ignored.

If you’re using strings with switch, you can control the case-sensitivity of a match with the MATCHCASE keyword. By default, all matching is case-insensitive.

If the switched-upon item is a variable, a copy of its value is kept at the time the switch command was processed. Any changes to that variable will not affect matches that are made among the associated case commands.

See also

case, default, endcase, endswitch and exitswitch; ASPECT Primary Commands.


taskactivate

taskactivate task

Activates the task with the specified task id, reporting FAILURE if the task could not be activated, or didn’t exist.

Example

proc main

   integer TaskId             ; Id of the task we'll run.

   run "notepad.exe" TaskId   ; Run Notepad.

   taskactivate TaskId        ; Activate it and give it focus.

endproc

Comments

The taskactivate command will only activate top level windows that have a caption containing text.

See also

run, taskexists and taskexit; $TASK and $PWTASK; Task/Window Manipulation Commands.


taskexists

taskexists task [intvar]

Tests a task id value, setting SUCCESS and FAILURE based on whether the task still exists.

task	A task id previously returned by the run, dos, firsttask, nexttask or wintask command.

intvar	If specified, intvar will be set to either 1, meaning the task exists, or 0, meaning the task does not exist.

Example

proc main

   integer TaskId             ; Id of the application we'll run.

   run "notepad.exe" TaskId   ; Run Notepad program.

   while taskexists TaskId    ; Pause script while Notepad's running.

      yield                   ; Yield processing time

   endwhile

endproc

Comments

taskexists is typically used to test for completion of a task within a DOS compatibility window to allow "pacing" of multiple asynchronous tasks.

See also

taskactivate, taskexit, firsttask and nexttask; Task/Window Manipulation Commands.


taskexit

taskexit task

Terminates a Windows task.

task	The id of the task to be terminated.

Example

proc main

   integer TaskId             ; Id of the task we'll run.

   run "notepad.exe" TaskId   ; Run Notepad.

   taskactivate TaskId        ; Make sure that it's active.

   taskexit TaskId            ; Close the Notepad program.

endproc

Comments

The taskexit command will only work with top level windows that have a caption containing text.

See also

taskactivate, taskexists, taskname, taskpath and exitwindows; $TASK and $PWTASK; Task/Window Manipulation Commands.


taskname

taskname task strvar

Returns the executable name associated with a specified task id.

task	The id of the desired task.

strvar	Will contain the associated executable name.

Example

proc main

   string TskName              ; Name of task corresponding to id.

   taskname $TASK TskName      ; Get name of active task.

   if strncmp TskName "NOTE" 4 ; See if active application is Notepad.

      taskexit $TASK           ; Close down the task, if it is Notepad.

   else

      usermsg "Current task isn't Notepad."

   endif

endproc

See also

run, taskpath, firsttask and nexttask; $TASK; Task/Window Manipulation Commands.


taskpath

taskpath task strvar

Returns the executable directory used by a specified task id.

task	The id of the desired task.

strvar	Will contain the path to the executable directory used by the task id.

Example

proc main

   string PathStr, StrName         ; Path and name of task.

   taskname $TASK StrName          ; Get name of active task.

   taskpath $TASK PathStr          ; Get path of active task.

   usermsg "`"%s`" has a path of `"%s`"." StrName PathStr

endproc

See also

taskexists, taskname, firsttask, nexttask and run; $TASK; Task/Window Manipulation Commands.


taskwin

taskwin task intvar

Returns the main or top-level window id associated with the specified task id, setting FAILURE if the task does not exist, or has no top-level window.

task	The desired task id.

intvar	Will contain the window id associated with the specified task.

Example

proc main

   integer WinId            ; Handle, or id, of window.

   taskwin $TASK WinId      ; Get window handle of active task.

   winmaximize WinId        ; Maximize the active application.

endproc

Comments

The taskwin command will only work with top-level windows that have a caption containing text. In addition, some tasks may have more than one top-level window and only the first window id associated with the task will be returned.

See also

run and wintask; $TASK; Task/Window Manipulation Commands.


termgetc

termgetc row column intvar

Returns a character value from the Terminal window.

row column	Integer values specifying the desired terminal location.

intvar	Will contain the character value.

Example

proc main

   integer Chr, Col           ; Character and column.

   for Col = 0 upto 10        ; Loop through first 10 columns.

      termgetc 0 Col Chr      ; Get character at column location.

      computc Chr             ; Write character to the port.

   endfor

endproc

Comments

termgetc does not alter the current cursor location on the Terminal display.

termgetc has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termgetc is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, the termgetc command is executed and the script resumes normally.

See also

termgets, termwritec, termreadc, termputc and locate; $ROW and $COL; Terminal Commands.


termgets

termgets row column strvar [strlength]

Returns a string from the Terminal window.

row column	Integer values specifying a terminal location.

strvar	Will contain the ASCII string.

strlength	The number of characters to read from the Terminal window. If strlength is not specified, termgets will read to the end of the current line.

If strlength is specified and is greater than the number of characters remaining on the current line, the process will "wrap" to the next line and continue reading characters up to the specified strlength.

Example

proc main

   string Line                   ; Line to write to file.

   integer Row                   ; Current row to get.

   if fopen 0 "scr.txt" CREATE   ; Create file to write screen to.

      for Row = 0 upto 24        ; Loop through each row on screen.

         termgets Row 0 Line 79  ; Get line specified by row.

         fputs 0 Line            ; Write line from screen to file.

      endfor

      fclose 0                   ; Close file opened for create.

   else

      errormsg "Couldn't open file!"

   endif

endproc

Comments

termgets has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termgets is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termgets executes and the script resumes normally.

See also

termgetc, termputs, termreads and locate; $ROW and $COL; Terminal Commands.


termkey

termkey [ALT | CTRL | SHIFT | ALTSHIFT | ALTCTRLSHIFT | CTRLSHIFT]
vkey [EXTENDED]

Processes a virtual key value with the keyboard shift state and sends it to the Terminal window, just as if the key had been pressed.

ALT ... CTRLSHIFT	Keyboard shift state values.

vkey	A key-character value. For a complete list of virtual key code values, see Virtual Key Codes.

EXTENDED	Extends the range of keycode values to those used by the extended 101/102 keyboard.

Example

proc main

   termkey ALT 'H'       ; Send ALT-H to open "Help" menu.

   mspause 250           ; Wait on the PW menu.

   termkey 'A'           ; Send 'a' to open "About" box.

   pause 2               ; Pause to show off about box.

   sendkey ALT 'O'       ; Send ALT-O to select "Ok" button.

endproc

Comment

The termkey command only sends keys to the Terminal or Telnet communication windows.

If your script uses the command set aspect keys on, the termkey command will not allow the script to receive the key value sent.

If the key corresponds to a function, that function is performed. If a menu pop-up is displayed, it will respond to keys sent by termkey. Otherwise, if the key corresponds to a character, it’s sent out the active port.

See also

termvkey, sendkey, keyget and menuselect; set aspect keys; Terminal Commands.


termmsg

termmsg string | {formatstr arglist} [RAW]

Writes a formatted string to the Terminal window at the current cursor location, updating that location accordingly. termmsg does not process caret ("^") sequences.

string	A string of up to 256 characters.

formatstr	A string containing text and/or format specifiers. For more information on formatstr, see Formatting Text and Data.

arglist	An optional list of up to 12 arguments. They must appear in the same order as the specifiers in the formatstr.

RAW	Writes the resultant string to the Terminal window without any processing of its contents.

Example

proc main

   string szHello = "Hello World!"  ; String to display on terminal.

   termmsg "`r`n"

   termmsg "*****************************`r`n"

   termmsg "* Introducing the script *`r`n"

   termmsg "* example of termmsg... *`r`n"

   termmsg "* *`r`n"

   termmsg "* %s *`r`n" szHello

   termmsg "*****************************`r`n"

endproc

Comments

termmsg has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termmsg is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termmsg executes and the script resumes normally.

See also

strfmt, termputs, termwrites and locate; Terminal Commands.


termputc

termputc row column character [RAW]

Writes a single character to a specified location in the Terminal window without changing the current cursor location.

row column	Integer values specifying a terminal location.

character	An integer value from 0 to 255, inclusive.

RAW	Writes the character to the Terminal window without any processing of its value.

Example

proc main

   string Line = "Send Slowly"   ; String to display on screen.

   integer Len             ; Length of string.

   integer Pos             ; Index within string.

   integer Chr             ; Character extracted from string.

   strlen Line Len         ; Get length of string.

   Len --                  ; Adjust len. Strings are 0 based.

   for Pos = 0 upto Len    ; Loop through to length of string.

      strgetc Line Pos Chr ; Get character from string.

      termputc 10 Pos Chr  ; Put character onto screen.

      pause 1              ; Wait a while before displaying

   endfor                  ; the next character.

endproc

Comments

termputc has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termputc is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termputc executes and the script resumes normally.

See also

termmsg, termputs, termgetc, termreadc and locate; $ROW and $COL; Terminal Commands.


termputs

termputs row column string [RAW]

Writes a string to a specified location in the Terminal window without updating the current cursor location.

row column	Integer values specifying a terminal location.

string	The string to be written.

RAW	Writes the string to the Terminal window without any processing of its contents. If RAW is not specified, termputs translates caret sequences into their appropriate ASCII values.

Example

proc main

   string Line                  ; Line to write to screen.

   integer therow = 1

   if fopen 0 "file.txt" READ   ; Open a file to write to screen.

      while not feof 0          ; Loop while not end of file.

         fgets 0 Line           ; Get line from file.

         termputs therow 1 Line ; Put line from file onto screen.

         therow++               ; Increment row counter

      endwhile

      fclose 0                  ; Close file opened for read.

   else

      errormsg "Couldn't open file!"

   endif

endproc

Comments

termputs has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termputs is executed while text is being marked in the Terminal window, however, script execution is suspended. After the marking operation is completed or canceled, the termputs command is executed and the script resumes normally.

See also

termmsg, termputc and termwrites; $ROW and $COL; Terminal Commands.


termreadc

termreadc intvar

Reads a character value from the terminal window at the current cursor location, updating the location accordingly.

intvar	The character value.

Example

proc main

   integer thechar           ; character we'll read

   locate 3, 3

   termreadc thechar

   usermsg "We read %c at %d, %d." thechar $row $col

endproc

Comments

termreadc has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termreadc is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termreadc executes and the script resumes normally.

See also

termwritec and termreads; $ROW and $COL; Terminal Commands.


termreads

termreads strvar [strlength]

Reads a string from the Terminal window, starting at the current cursor location. termreads updates the location accordingly.

strvar	Receives the data read from the Terminal window.

strlength	The number of characters to read. If string length is not specified, termreads will read to the end of the current line.

If strlength is specified and is greater than the number of characters remaining on the current line, the process will "wrap" to the next line and continue reading characters up to the specified strlength.

Example

proc main

   string thestring           ; String we'll read

   locate 1, 3                ; Move the cursor

   termreads thestring 25     ; Read 25 characters

   usermsg "We read `"%s`" ending at %d, %d." thestring $row $col

endproc

Comments

termreads has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termreads executes while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termreads executes and the script resumes normally.

See also

termwrites and termreadc; $ROW and $COL; Terminal Commands.


termreset

termreset

Clears the Terminal window, moves the cursor to row 0, column0, and re-initializes the emulation.

Example

proc main

   hangup               ; Hang up the phone line.

   pause 1              ; Pause to avoid disconnect "noise".

   termreset            ; Clear and reset terminal.

endproc

Comments

If termreset is executed while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termreset executes and the script resumes normally.

See also

clear and locate; set terminal command family; Terminal Commands.


termvkey

termvkey keyval

Processes an encoded key value and acts upon it as if it were typed in the Terminal window.

keyval	An integer value representing both a key and the current keyboard state. For more information on key values, see ASPECT Conventions.

Example

proc main

   integer AltD = 0x0444      ; Virtual key code value for ALT-D.

   termvkey AltD           ; Send ALT-D to open the Dial menu.

endproc

Comment

The termvkey command only sends keys to the Terminal or Telnet communication windows.

If your script uses the command set aspect keys on, the termvkey command will not allow the script to receive the key value sent.

If the key corresponds to a function, that function is performed. If a menu pop-up is displayed, it will respond to keys sent by termvkey. Otherwise, if the key corresponds to a character, it’s sent out the active port.

A complete list of virtual key code values appears in Virtual Key Codes.

See also

termkey, sendkey, keyget and menuselect; set aspect keys; Terminal Commands.


termwritec

termwritec character [RAW]

Writes a single character to the Terminal window at the current cursor location, updating the location accordingly.

character	The character value to write.

RAW	Writes the character to the Terminal window without any processing of its value.

Example

proc main

   integer Chr             ; Character received.

   set aspect rxdata ON    ; Aspect handles received data.

   while 1                 ; Loop forever.

      while $RXDATA        ; Loop while data is received.

         comgetc Chr       ; Get character from port.

         termwritec Chr    ; Write character to terminal.

      endwhile

   endwhile

endproc

Comments

termwritec has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termwritec executes while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termwritec executes and the script resumes normally.

See also

termputc, termwrites, termmsg and termreadc; Terminal Commands.


termwrites

termwrites string [RAW]

Writes a string to the Terminal window at the current cursor location, updating the location accordingly.

string	The string to write.

RAW	Writes the string to the Terminal window without any processing of its contents. If RAW is not specified, termwrites will process caret sequences.

Example

proc main

   string szData                ; Data received.

   set aspect rxdata ON         ; Aspect handles received data.

   while 1                      ; Loop forever.

      if $RXDATA                ; Check for received data.

         comread szData $RXDATA ; Get characters from port.

         termwrites szData      ; Write characters to terminal.

      endif

   endwhile

endproc

Comments

termwrites has no effect while the Procomm Plus Terminal is in Scrollback mode. Script execution merely continues to the next command. If termwrites executes while text is being marked in the Terminal window, script execution is suspended. After the marking operation is completed or canceled, termwrites executes and the script resumes normally.

See Also

Terminal Commands.


text

text id left top width height label LEFT | RIGHT | CENTER

Displays a text string in an ASPECT dialog.

id	An integer constant used as the control id.

left top width height	Integer constants specifying the size and position of the text box in Dialog Box Units or DBUs. For more information on DBUs, see Dialog Box Units.

label	The string constant or a string variable to be displayed. If a string variable is specified for the label, it can be dynamically changed and then updated on-screen with dlgupdate.

If the text control is to be used as a label for another control, it should be placed immediately preceding that control. You can then specify a keyboard accelerator for that control simply by including an ampersand (&) in the label in front of the desired character.

To display an ampersand in the label, use two ampersands. For example, the text "&R&&D" used as a label would display "R&D", with the R displayed as an underscored accelerator.

LEFT	Align the text with the left margin of the text box.

CENTER	Align the text in the center of the text box.

RIGHT	Align the text with the right margin of the text box.

Example

proc main

   dialogbox 0 0 0 100 50 11 "Text Example"

      text 1 5 5 90 12 "Text may be used to make" LEFT

      text 2 5 20 90 12 "the function of dialogs" LEFT

      text 3 5 35 90 12 "clearer." LEFT

   enddialog

   pause 5                 ; Show off the dialog text.

   dlgdestroy 0 CANCEL     ; Destroy the dialog box.

endproc

See also

dlgupdate, dialogbox and ftext; Dialog Box Commands.


transmit

transmit string [RAW]

Sends a character string to the active port. If local echo is on, transmit echoes the string to the Terminal display.

string	May contain non-printing characters. For more information, see Escape Sequences.

RAW	If specified, causes the characters to be sent to the port without translation of any kind.

Example

proc main

   waitfor "Name"                ; Wait for name prompt.

   transmit "Fred Garvin^M"      ; Transmit user name.

   waitfor "Password?"           ; Wait for password prompt.

   transmit "awesome^M"          ; Transmit password.

endproc

Comments

By default, the transmit command performs caret translation and outgoing translate table conversions on transmitted data. For an explanation of caret (^) translation, see Caret Translation.

If the Pause character is contained within the string, it will be translated into a time delay and not transmitted.

Data will be transmitted at a rate determined by the current baudrate and transmit pacing values. For fastest possible throughput at the current baudrate, make sure that transmit pacing is set to 0.

transmit reports FAILURE if the port is unavailable or if the transmit data buffer can’t accommodate the length of the string.

See also

comwrite and computc; $TXDATA; COM-Related Commands.


txflush

txflush

Clears the transmit data buffer. Any untransmitted characters remaining in the buffer are discarded.

Example

proc main

   txflush                    ; Flush transmit buffer to clear

   transmit "ABCDEFGHIJKL^M"  ; any interference and then

                              ; send something to host.

endproc

Comments

txflush is used to clear the transmit data buffer in preparation for some task. txflush will not clear the buffer if ASPECT does not have access to the port, such as during file transfers or fax operations.

See also

rxflush; $TXCOUNT and $TXDATA; COM-Related Commands.


usermsg

usermsg string | {formatstr arglist}

Displays a message string in a standard Windows message box with an information icon. The dialog remains until the <Esc> or <Enter> key is pressed, or a button is selected.

string	A string of up to 256 characters.

formatstr	A string of up to 256 characters. The string can contain text and/or format specifiers. For more information , see Formatting Text and Data.

arglist	Up to 12 optional arguments. These must occur in the same order as the format specifiers in the formatstr.

Example

proc main

   integer Answer                ; Integer to display.

   Answer = 6 * 7                ; Assign a value to our integer.

   usermsg "6 * 7 is %d!" Answer ; Display Answer in a message box.

endproc

See also

errormsg, statmsg, sdlgmsgbox and termmsg; General Procomm Plus Commands.


uwincreate

uwincreate TOP | BOTTOM | LEFT | RIGHT | FULL SCREEN | WINDOW | PIXELS
integer R G B BITMAP | METAFILE

Defines a User window which occupies all or part of the Terminal window. A User window displays objects such as pushbuttons and bitmaps on the Terminal window. These objects can be moved, hidden, shown, refreshed and removed using the appropriate script commands.

Although User windows can be created and maniplutaed in any mode, User windows and associated controls are only displayed in Terminal and Telnet modes.

TOP | ... | FULL	Specifies the position of the User window as it corresponds to the Terminal window. The remainder of the Terminal window displays normally. If the smaller Terminal window is not large enough to display all of the text, vertical and horizontal scroll bars are added automatically.

If FULL is specified, the Terminal window area is completely filled by the User window, and no text will be displayed.

SCREEN | 	SCREEN displays the User window at a "fixed" size based on a percentage of the screen size. The percentage is specified with the integer parameter.

WINDOW |	WINDOW displays the User window in proportion to a percentage of the Terminal window. The percentage is specified with the integer parameter.

PIXELS	PIXELS specifies the actual size of the User window in pixels, specified with the integer parameter. The User window will have different physical sizes under different screen resolutions.

integer	For SCREEN or WINDOW, the size of the User window specified as a percentage of the physical screen or the Terminal window; if the location is set to FULL, this value defaults to 100 percent. For PIXELS, the number of pixels used relative to the window placement. If the window is located at the TOP or BOTTOM, this figure is relative to the number of pixels on the vertical axis; if the window is positioned at the LEFT or RIGHT, it’s relative to the horizontal axis.

R	Defines the level of red for the User window background. An integer value ranging from 0, for no red to 255 for maximum red.

G	Defines the level of green for the User window background. An integer value ranging from 0, for no green to 255 for maximum green.

B	Defines the level of blue for the User window background. An integer value ranging from 0, for no blue to 255 for maximum blue.

For example, to set a white background for the User window, use the RGB values 255, 255, 255. A black background is set with 0, 0, 0.

BITMAP | METAFILE	Affects only those objects placed with the BACKGROUND option in a User window without a bitmap or metafile background.

BITMAP forces an object placed in the User window to act as if placed on a bitmap background. The object’s position is fixed.

METAFILE forces an object placed in the User window to act as if placed on a metafile background. The object’s position is maintained in proportion to the User window size.

Example

proc main

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   uwinpaint               ; Paint the user window.

   pause 5                 ; Show off user window.

   uwinremove              ; Destroy the user window.

endproc

Comments

Because of the complex interaction between the User window, background graphics and objects, we strongly recommend that you use the User Window Editor to create these graphic displays. The User Window Editor generates these statements and calculates the position and size information for each object automatically!

The following objects can be placed in a User window:

bitmap	Displays a bitmap graphic.

dllobject	Defines an area within the User window which will be updated by a DLL module.

hotspot	Defines an area within the User window that can be selected with a mouse.

icon	Displays an icon graphic.

iconbutton	Displays an icon on a clickable button.

metafile	Displays a Windows metafile graphic.

pushbutton	Displays a button with a text label.

bitmapbkg	Displays a Windows bitmap as a background for the User window. A hotspot can be used to make an area of the background reactive to a mouse click.

metafilebkg	Displays a Windows metafile as a background for the User window. A hotspot can be used to make an area of the background reactive to a mouse click.

When objects are created in the User window, they are placed and sized based on User Window Units or UWUs. For more information on UWUs, see User Window Units.

User window object ids may have any integer value greater than 0.

There is a limit of 32 active objects for each object type and only one DLL object file can be active at a time.

The uwinpaint command must be used to display the User window after it is defined. It can also be used to update the User window if any changes are made to it. To refresh one or more objects within the window, use the objpaint command with the id(s) of the object(s) you wish to update.

A User window responds to both left and right mouse button events that occur within its boundaries. When a left mouse button is pressed, the $LMOUSEEVENT system variable is set to 1, and the $LMOUSEX and $LMOUSEY system variables are set to the User window coordinates corresponding to the current mouse pointer location. When the mouse button is released, the $LMOUSEX and $LMOUSEY coordinates are updated again, possibly with different User window coordinates if the mouse was moved while the button was held down. The $LMOUSESTATE system variable indicates the current state of the left mouse button, up or down. The $LMOUSEEVENT, however, is only generated for the mouse button down event. The right mouse button has a corresponding set of system variables which are updated in the same manner.

When the left mouse button is clicked upon a bitmap, hotspot, iconbutton, or pushbutton, a User window event is generated in the $OBJECT system variable, its contents being set to the id value of the clicked-upon object. The $OBJECT event is not generated until the mouse button is released.

When a right mouse button is clicked and held down while the mouse pointer is not currently over any User window object other than a hotspot, the User window will reveal the locations of all hotspot objects by inverting their locations on the screen. Hidden hotspots will not be revealed by this action.

No User window event will be generated if the user clicks over a hidden User window object.

A User window will remain available if you chain or execute another script without issuing a uwinremove.

A User window is different from both the Terminal window and a Windows dialog box. A User window can co-exist with any portion of the Terminal window or may entirely replace it depending on the Terminal window size setting.

See also

bitmap, metafile, pushbutton, bitmapbkg, metafilebkg, icon, iconbutton, hotspot, dllobject, objhide, objpaint, objpointid, objremove, objshow, dllobjfile, dllobjupdt, uwinpaint, uwinremove, wintouwu and uwutowin; $LMOUSESTATE, $LMOUSEX, $LMOUSEY, $LMOUSEEVENT, $RMOUSESTATE, $RMOUSEX, $RMOUSEY, $RMOUSEEVENT, $OBJECT and $USERWIN; User Window Commands.


uwinpaint

uwinpaint

Paints the entire User window, and all of its objects. uwinpaint must be called to initially display the User window after it is created.

Example

See the example for uwincreate.

See also

uwincreate, objremove, objmove, objshow, objhide, objpointid and objcoord; $USERWIN; User Window Commands.


uwinremove

uwinremove [BACKGROUND]

Removes the User window background, or the entire User window. unwinremove does not affect User window objects.

Example

See the example for uwincreate.

See also

uwincreate, objremove, objmove, objshow, objhide, objpointid and objcoord; $USERWIN; User Window Commands.


uwutowin

uwutowin intvar intvar USERWIN | BACKGROUND

Converts X/Y User Window Units, which are measured in pixels, to window coordinates.

intvar	The X coordinate value to convert. For more information, see User Window Units.

intvar	The Y coordinate value to convert.

USERWIN	Convert the X/Y values relative to the upper left corner of the User window.

BACKGROUND	Convert the X/Y values relative to the background graphic. If X and Y are both zero, uwutowin intvar intvar BACKGROUND will report the background graphic’s actual User window coordinates.

Example

proc main

   integer UWUX = 500, UWUY = 500    ; X and Y of metafile in UWU's.

   uwincreate FULL SCREEN 100 255 255 255 BITMAP

   metafile 1 UWUX UWUY 9000 9000 "sunrise.wmf" USERWIN

   uwinpaint                         ; Paint the user window.

   uwutowin UWUX UWUY USERWIN        ; Convert UWU coords to window.

   UWUX -= 50, UWUY -= 50            ; Subtract 50 pixels from loc.

   wintouwu UWUX UWUY USERWIN        ; Convert window coords to UWU.

   objmove 1 UWUX UWUY UWUS          ; Move the metafile.

   uwinpaint                         ; Repaint the user window.

   pause 5                           ; Pause for effect.

   uwinremove                        ; Remove the user window.

endproc

See also

uwincreate, when , wintouwu and wintoscreen; $LMOUSEX, $LMOUSEY and $USERWIN; User Window Commands.


waitfor

waitfor string [integer | FOREVER] [MATCHCASE] [RAW] [STRIP]

Pauses processing until a target string is received from the active port. waitfor reports SUCCESS if the target string was received. It reports FAILURE if it timed out, or if it was aborted with the <Ctrl><Break> key sequence.

string	A string of text and/or numeric characters up to 256 characters in length. An exact character match is required, but the match is not case-sensitive unless you specify MATCHCASE.

Caret sequences in the string will be translated to control characters unless RAW is specified. For more information about caret (^) translation, see Caret Translation.

integer	An integer value, specifying the number of seconds to wait for the target string before timing out and continuing execution. If neither integer nor FOREVER is specified, waitfor’s default timeout period is 30 seconds.

FOREVER	If FOREVER is specified, Procomm Plus will wait indefinitely for the target string. It will not time out.

MATCHCASE	If specified, forces a case-sensitive match of the specified string.

RAW	If specified, incoming data will be retrieved unchanged from the receive data buffer, bypassing caret translation, the Translate Table and 8th-bit stripping if it is enabled for the current emulation.

STRIP	If specified, causes the target string to be removed from the incoming data stream. The stripped target is thus prevented from being processed by the Terminal window or ASPECT.

Example

proc main

   transmit "^C"              ; Transmit a wake up signal to

   waitfor "User Id"          ; host and wait for user id prompt.

   transmit "99999,9999^M"    ; WAITFOR and TRANSMIT are very

   waitfor "Password"         ; handy for sign-on scripts.

   transmit "Password^M"      ; Transmit password.

endproc

Comments

Any active when commands will continue to "fire" during the execution of waitfor.

See also

waitquiet and when target; COM-Related Commands.


waitquiet

waitquiet [integer [integer | FOREVER] ]

Pauses processing until the receive data line has been inactive for a number of seconds. waitquiet reports FAILURE if it was exited with the <Ctrl><Break> key sequence, or if it timed out before satisfying the inactive period.

integer	The number of seconds that the line must be inactive. If not specified, the default of 15 seconds is used.

integer | FOREVER	The number of seconds that Procomm Plus will wait to satisfy for the inactive period. If neither integer nor FOREVER is specified, the default of 30 seconds is used.

FOREVER forces the script to pause indefinitely until the line is quiet for the required number of seconds.

Example

proc main

   transmit "TYPE TEST.TXT^M"    ; Send command to display file on host.

   waitfor "Sending"             ; Wait for confirmation from host.

   getfile ASCII "test.txt"      ; Initiate an ASCII download.

   waitquiet 15 FOREVER          ; Wait until the line is quiet for

                                 ; 15 seconds. GETFILE doesn't

                                 ; pause script until finished.

   transmit "OFF^M"              ; Transmit hangup command.

   hangup                        ; Hang up the phone line.

endproc

Comments

If none of the optional parameters are used, waitquiet pauses execution of the script for up to 30 seconds while waiting for the receive data line to be inactive for 15 seconds.

Any active when commands will continue to "fire" during the execution of the waitquiet command.

See also

waitfor and when quiet; $RXDATA and $RXCOUNT; COM-Related Commands.


waituntil

waituntil { string [string] } | timeval

Pauses processing until the specified date and/or time.

string [string]	A time string and optional date string, specifying when script processing should continue. The date and time strings must conform to the Short date style and Time style formats specified in the Windows Control Panel's Regional Settings section.

If the date string is not specified, the default is the current date.

timeval	A long time value that specifies both time and date.

Example

proc main

   string DateStr             ; String to contain date.

   string TimeStr             ; String to contain time.

   DateStr = "12/31/99"       ; Assign date to date string.

   TimeStr = "11:59:59"       ; Assign time to time string.

   waituntil TimeStr DateStr  ; Wait until turn of century.

endproc

Comments

This command will set FAILURE if an invalid date string and/or time string is used as an argument to the command. Active when commands will continue to "fire" during the execution of the waituntil command.

See also

when elapsed and pause; General Procomm Plus Commands.


weekdaystr

weekdaystr integer strvar [SHORT]

Returns the day of the week.

integer	A value from 1 to 7, corresponding to Sunday through Saturday.

strvar	Will contain the day of the week. If SHORT is specified, the day will be abbreviated.

Example

proc main

   integer DayWeek            ; Day of the week.

   integer DayYear            ; Day of the year.

   integer LeapYear           ; Leap year flag.

   string Day                 ; Day of week as string.

   ltimemisc $LTIME DayWeek DayYear LeapYear

   weekdaystr DayWeek Day     ; Get day of week in string form.

   usermsg "It is %s!" Day    ; Display day of week.

endproc

See also

monthstr and ltimemisc; Date and Time Commands.


when

when event {call name} [SUSPEND]

(or) when event CLEAR | {RESUME [RESET]} | SUSPEND

(or) when CLEAR | {RESUME [RESET]} | SUSPEND

Forces a procedure or function call when a particular event occurs. Once a when command is executed, it remains in effect until a when clear command is encountered, or the script terminates.

Active when commands are reset to inactive when another script is chained or spawned. If control reverts back to the calling script, however, any previously-set when commands are once again activated.

A called procedure that processes a particular event will finish completely before it is called again, preventing recursive event handling. However, a when event of a different type can interrupt another when procedure that’s currently executing. The set aspect whensuspend can be used to prevent a when’s firing on top of other whens that have not yet returned from their called procedures.

The when command is perhaps the most versatile of the ASPECT commands, and the number of whens allowed is virtually unlimited. The when has three general forms:

when event Form

when event {call name} [SUSPEND]

Where event is:

DIALOG id	call the procedure when a dialog event has occurred in the dialog identified by the id value. Generally, this would be used to allow the called procedure to handle the dialog event(s). dlgevent must be used to clear the targeted dialog’s event queue, or the when will fire repeatedly.

ISKEY id keyval	call the procedure when the specified keyval has been pressed. Id is any unique integer index value. The keyval argument should only be specified when defining a new event.

STRIP	STRIP can be specified to prevent the targeted keyval from being passed to the Terminal window or script. STRIP should only be specified when defining a new ISKEY event.

ELAPSED id duration	call procedure when the specified period of time has elapsed since the when command was initialized or last triggered. id is a unique integer index value. Duration is a positive integer value, expressed in the number of seconds, and is only required when defining an active when. That is, when a call statement appears in the same when command line.

QUIET duration	call procedure when no characters have been received for the specified period of time. Duration is a positive integer value, expressed in the number of seconds, and is only required when defining an active when. That is, when a call statement appears in the same when command line.

ASPECT can only "see" incoming data that was destined for the Terminal display or for ASPECT. It cannot "see" data that is received during a file transfer or fax operation.

TARGET id string	call the procedure when characters matching the specified string are received. id is any unique integer index value. String should only be specified when defining a new when. String can contain "raw" data.

MATCHCASE	MATCHCASE can be specified for a case-sensitive comparison of the target string to received data. It should only be specified when defining a new when TARGET event.

RAW	RAW can be specified to disable caret translation on the target string, and to disable translate table conversion and 8th-bit stripping for the current emulation on received data. It should only be specified when defining a new when TARGET event.

STRIP	If specified, causes the target string to be removed from the incoming data stream. The stripped target is thus prevented from being processed by the terminal or ASPECT. It should only be specified when defining a new when TARGET event.

USEREXIT	call procedure when the user presses the Script halt button on the Action Bar or selects Script | Stop Script command. This allows the script to branch to a "cleanup" procedure before it terminates. If the script issues the statement set aspect control on, the USEREXIT procedure will not be called.

The called procedure must issue an exit or halt command to terminate the script. Otherwise the script will not terminate.

datavar	call procedure when the target datavar has changed. If a local datavar is specified, the when will be automatically cleared when the procedure or function returns.

sysvar	call procedure when the target sysvar has changed. when can be used for any variable, but it is perhaps most useful for system variables such as $ASPMENU, $CARRIER, $CNCTMSG, $DDEADVISE, $KEYHIT, $LMOUSEEVENT, $OBJECT, $RMOUSEEVENT, $RXDATA and $XFERSTATUS.

If the specified system variable is one that automatically resets its value after it is accessed, the use of its name in a when command does not constitute an "access". A direct assignment or other reference must be made to clear the value and to prevent the when from firing repeatedly.

Certain system variables have special properties in when commands, due to the unique needs of Windows and serial communications. Please refer to  "System Variables" for more information, and for other system variables that may be useful in when conditions.

CALL name	The name of the procedure to call when the appropriate event has occurred, or the specified variable has changed. The called procedure must not require any parameters.

SUSPEND	If specified, response to other when conditions will be suppressed until the called procedure or function returns.

SUSPENDing when conditions does not eliminate ASPECT’s response to those conditions. Instead, the SUSPENDed whens are saved in a queue until the SUSPENDing when command has finished executing.

This may result in unexpected when firings if the script is not configured to account for when events that occur during the SUSPENDed period. This is true of when ELAPSED, when ISKEY, when QUIET, when TARGET and the when USEREXIT commands. It is not true of when variable commands, meaning that changes to a variable which occur during a SUSPENDed period will not cause a when variable to fire.

Example

proc main

   when TARGET 0 "First?" call FirstName

   when TARGET 1 "Last?" call LastName

   while $CARRIER       ; Loop while connected.

      yield             ; Release ASPECT process time

   endwhile

endproc

proc FirstName

   transmit "John^M"    ; Transmit first name.

endproc

proc LastName

   transmit "Doe^M"     ; Transmit last name.

endproc

Comments

In general, when commands using the system variables "fire" when those variables change values from their default or inactive state to another state. The procedure handling the when event should access the system variable to reset its value. Otherwise it will be automatically cleared when the procedure returns and the script will lose the value. Refer to System Variables for more information.

Specifying a when index already in use by another when of the same type will cause the original when to be removed.

when event Control Form

Any number of when DIALOG/ISKEY/TARGET commands can be active simultaneously. Each condition can be individually or globally enabled or disabled using the when [command] CLEAR/SUSPEND/RESUME commands, as explained below:

when event CLEAR | {RESUME [RESET]} | SUSPEND

Where event is:

DIALOG id	The when condition associated with the specified dialog id will be affected.

ELAPSED ID	The when ELAPSED condition associated with the specified id will be affected.

ISKEY id	The when condition associated with the specified ISKEY id will be affected.

QUIET	The when QUIET condition will be affected.

TARGET id	The when condition associated with the specified target id will be affected.

USEREXIT	The when USEREXIT condition will be affected.

datavar	The when datavar condition will be affected.

sysvar	The when sysvar condition will be affected.

And the actions are:

CLEAR	Remove the specified when condition(s).

RESUME	Enable the specified when condition(s) which had previously been disabled with SUSPEND. If whens have been globally suspended, the specified when will remain disabled.

RESET	Clears any of the specified pending when events from firing when it is RESUMEd.

SUSPEND	Disable the specified when condition(s).

SUSPENDing when conditions does not eliminate ASPECT’s response to those conditions. Instead, the SUSPENDed whens are saved in a queue until the SUSPENDing when command has finished executing.

This may result in unexpected when firings if the script is not configured to account for when events that occur during the SUSPENDed period. This is true of when ELAPSED, when ISKEY, when QUIET, when TARGET and the when USEREXIT commands. It is not true of when variable commands, meaning that changes to a variable which occur during a SUSPENDed period will not cause a when variable to fire.

when Global Control Form

when conditions can also be globally controlled:

when CLEAR | {RESUME [RESET]} | SUSPEND

CLEAR	CLEAR all when conditions.

RESUME	RESUME all when conditions. Those whens which had not been individually SUSPENDed will now be allowed to fire.

RESET	Clears all pending when events from firing when they are RESUMEd.

SUSPEND	SUSPEND all when conditions.

SUSPENDing when conditions does not eliminate ASPECT’s response to those conditions. Instead, the SUSPENDed whens are saved in a queue until the SUSPENDing when command has finished executing.

This may result in unexpected when firings if the script is not configured to account for when events that occur during the SUSPENDed period. This is true of when ELAPSED, when ISKEY, when QUIET, when TARGET and the when USEREXIT commands. It is not true of when variable commands, meaning that changes to a variable which occur during a SUSPENDed period will not cause a when variable to fire.

See also

waitfor, pause, call, func, proc and waitquiet; set aspect whensuspend; "The System Variables"; COM-Related Commands; General Procomm Plus Commands.


while

while condition

Repeats a series of commands until the test condition becomes false.

condition	The conditions allowed for the while command are identical to those of the if command. For more information, see the if command.

To create an infinite loop within a while construct, specify a non-zero constant for the condition as in:

while 1

Example

proc main

   integer Loops = 0             ; Integer used to count loops.

   while (Loops++) < 3           ; Loop and increment variable three

   endwhile                      ; times.

   usermsg "I looped %d times!" Loops

endproc

Comments

Under Windows NT 4.0, the following loop can monopolize CPU utilization when, in fact, the script needs to peform very little processing:

   while 1 ;  while TRUE would also work

   .

   .

   .

   endwhile

To prevent this wasteful CPU utilization, place a yield command at the end of the while loop.

See also

exitwhile, loopwhile, endwhile, yield, and if; ASPECT Primary Commands.


winactivate

winactivate window | string

Activates the window with the specified title or window id, reporting FAILURE if the specified window could not be activated. winactivate is used primarily with the sendkey command to ensure that the keystrokes are sent to the correct window.

window	The id of the window to activate.

string	The current title text of the window to be activated. Note that the title bar may change depending on the application, so you must ensure that the current title text matches this string. The string is not case-sensitive.

Example

proc main

   while 1                          ; Loop forever.

      if $TASK != $PWTASK           ; Is current task PW?

         winactivate $PWMAINWIN     ; Activate PW main window.

      endif

   endwhile

endproc

Comments

The winactivate command cannot be used on a hidden window.

See also

taskwin, winclose, winexists, winfocus, winstate, wintask, taskactivate and wintext; $ACTIVEWIN, $FOCUSWIN and $MAINWIN; Task/Window Manipulation Commands.


winclose

winclose window

Sends a "close" message to a window, just as if the user had pressed <Alt><F4>.

window	The window id.

Comments

proc main

   if $setup                       ; if setup window is displayed

      winclose $setup              ; close the setup window

   endif

endproc

See also

winactivate; $ACTIVEWIN, $FOCUSWIN and $MAINWIN; Task/Window Manipulation Commands.


wincoord

wincoord window left top [width [height]]

Returns the location and dimensions of the specified window in screen coordinates. wincoord can be used with winmove and winsize to control the location and size of the target window.

window	The target window id.

left top width height	Integer variables which will receive the requested values.

Example

proc main

   integer nLeft, nTop           ; Left and top coordinates of window.

   integer nWidth, nHeight       ; Width and height of window.

   ; Get active window's coordinates and size and display them.

   wincoord $ACTIVEWIN nLeft nTop nWidth nHeight

   usermsg "L: %d T: %d W: %d H: %d" nLeft nTop nWidth nHeight

endproc

See also

screentowin, winmove and winsize; $XPIXELS and $YPIXELS; Task/Window Manipulation Commands.


winenabled

winenabled window [intvar]

Tests the target window to determine its availability to the user or to the script. winenabled can be used to determine whether a script-generated dialog box has been disabled.

window	The target window id.

intvar	Will be set to 1 if the window is enabled or 0 if the window is disabled.

Example

proc main

   disable WINDOW $PWMAINWIN  ; Disable the PW window.

   if winenabled $PWMAINWIN   ; Is PW's window is enabled?

      usermsg "Procomm Plus's main window is enabled."

   else

      usermsg "Procomm Plus's main window is disabled."

   endif

   enable WINDOW $PWMAINWIN   ; Enable the window.

endproc

See also

enable, disable, winvisible, winhide, winmaximize, winminimize, winshow and winstate; Task/Window Manipulation Commands.


winexists

winexists window [intvar]

Tests for the existence of a window. winexists can be used to test whether an application is still active.

window	The id of the target window.

intvar	If specified, intvar will be 0 if the window does not exist or 1 if the window does exist.

Example

proc main

   integer hWin, TaskId       ; Window and task id of application.

   run "PBRUSH.EXE" TaskId    ; Run PaintBrush and get task id.

   taskwin TaskId hWin        ; Get PaintBrush's window id.

   while winexists hWin       ; Pause until PaintBrush is closed.

      yield                   ; Release script processor time

   endwhile

endproc

See also

taskexists, taskwin, winactivate, winfocus, winstate and wintask; Task/Window Manipulation Commands.


winfocus

winfocus window

Specifies the window to receive keyboard input.

window	The id of the window that is to receive input. This value can be obtained by checking the $FOCUSWIN variable when the desired window is active. Alternately, you may use the title text of any window that has a title bar. This can be an application or any dialog box with a title bar.

Example

proc main

   integer WinId              ; Handle to PWEDIT's window.

   integer TaskId             ; PWEDIT's task id.

   run "PWEDIT.EXE" TaskId    ; Run PWEDIT and get task id.

   taskwin TaskId WinId       ; Get window id for task.

   winfocus WinId             ; Set focus to PWEDIT's window.

endproc

Comments

Typically, the focus window and the active window are the same. Controls within dialog boxes, however, are an exception. The control has the focus but the dialog is active!

The winfocus command cannot be used to set the focus to a disabled or hidden window.

See also

taskwin, dlgwin, dlgctrlwin, enable, disable and winactivate; $FOCUSWIN; Task/Window Manipulation Commands.


winhide

winhide window

Conceals the target window from view.

window	The target window id.

Example

proc main

   integer hWin               ; Handle to application's window.

   integer TaskId             ; Application's task id.

   run "dosapp.exe" TaskId    ; Run DOS app. and get task id.

   taskwin TaskId hWin        ; Get window handle of DOS app.

   winhide hWin               ; Hide the DOS application.

   pause 5                    ; Wait for 5 seconds.

   winshow hWin               ; Show the DOS application.

endproc

Comments

Hiding a window prevents it from "seeing" mouse and keyboard events. If the window is currently active when it is hidden, another window will become active.

Be careful when hiding modal dialog boxes. A modal dialog box does not allow users to access Procomm Plus’s parent window, and the user cannot access a hidden dialog!

See also

disable, enable and winshow; Task/Window Manipulation Commands.


winmaximize

winmaximize window

Maximizes an application window to fill the entire display screen. winmaximize only affects windows which have maximize buttons.

window	The target window id.

Example

proc main

   winmaximize $PWMAINWIN  ; Maximize the PW main window.

endproc

See also

winminimize and winrestore; Task/Window Manipulation Commands.


winminimize

winminimize window

Minimizes an application window to an icon.

Example

proc main

   winminimize $PWMAINWIN  ; Minimize the PW main window.

endproc

Comments

winminimize is only valid for windows which have a minimize button - typically these are top-level windows.

If winminimize is used to minimize a main or top-level window which is currently disabled, you will be unable to restore the application from its iconic state.

See also

winmaximize and winrestore; Task/Window Manipulation Commands.


winmove

winmove window x y

Positions an application window. winmove works only with windows which can be moved.

window	The target window id.

x y	The top and left coordinates, respectively, of the desired location. Coordinates are measured in screen pixels.

Example

proc main

integer hWnd               ; Window handle of active task.

   taskwin $TASK hWnd      ; Get window handle of task.

   winmove hWnd 0 0        ; Move active window to top left.

endproc

Comments

Use the winsize command to change the size of the application window.

See also

wincoord and winsize; Task/Window Manipulation Commands.


winowner

winowner window intvar

Returns owner ID of a window ID.

window	The ID of the window whose ownership is unknown.

intvar	An integer variable to receive the owner window's ID.

Example

proc main

   integer WinID                       ; Windows ID of the dialog

   integer OwnerID                     ; Windows ID of the owner of the dialog

   dialogbox 0 32 42 143 50 0          ; draw a dialog

      text 1 38 21 84 8 "This is a test dialog" left

   enddialog

   dlgwinID 0 WinID                    ; get the Windows ID of the dialog

   winowner WinID OwnerID              ; get the Windows ID of the owner of the dialog

   winfocus OwnerID                    ; switch the focus to the owner of the dialog

endproc

Comments

A window that has no owner is actually owned by the desktop. FAILURE is set if the window has no owner, or if an invalid id was specified.

See also

taskwin, winactivate, winclose, winfocus, winstate, wintask, wintext, $PWMAINWIN, $ACTIVEWIN, $FOCUSWIN; Task/Window Manipulation Commands.


winrestore

winrestore window

Restores an application window to its previous size from a minimized or maximized state.

window	The target window id.

Example

proc main

   winminimize $PWMAINWIN   ; Minimize the PW main window.

   pause 5                  ; Wait for five seconds.

   winrestore $PWMAINWIN    ; Restore the PW window.

endproc

See also

winmaximize and winminimize; Task/Window Manipulation Commands.


winshow

winshow windows

Makes a hidden window visible.

window	The target window id.

Example

See the example for winhide.

See also

disable, enable and winhide; Task/Window Manipulation Commands.


winsize

winsize window dx dy

Sizes the specified application window.

window	The window id.

dx	The new width of the target window, measured in screen pixels.

dy	The new height of the target window, measured in screen pixels.

Example

proc main

   ; Size active window to fill the entire screen.

   winsize $ACTIVEWIN $XPIXELS $YPIXELS

endproc

See also

winhide, winminimize, winmaximize, winmove and winshow; Task/Window Manipulation Commands.


winstate

winstate window intvar

Returns an integer reflecting the state of a window. If the window does not exist, winstate will report FAILURE.

window	The window id.

intvar	Intvar will equal 0 if the window is minimized, 1 if the window is restored and 2 if the window is maximized.

Example

proc main

integer State                  ; State of the window.

   winstate $PWMAINWIN State   ; Get state of PW window.

   if State == 0               ; See if PW is minimized.

      winmaximize $PWMAINWIN   ; Maximize PW.

   endif

endproc

See also

winenabled, winvisible, winmaximize, winminimize, winrestore and winshow; Task/Window Manipulation Commands.


wintask

wintask window intvar

Returns the task id of a window. wintask reports FAILURE if no task could be found for the given window.

window	The window id.

intvar	The task id. This value can be used with taskactivate, taskexit, and other task-commands.

Example

proc main

   integer TaskId             ; Task id of app with active window.

   wintask $ACTIVEWIN TaskId  ; Get task id of active application.

   taskexit TaskId            ; Exit the active application.

endproc

See also

taskwin; $MAINWIN, $TASK, $PWTASK, $ACTIVEWIN and $FOCUSWIN; Task/Window Manipulation Commands.


wintext

wintext window strvar

Retrieves the caption or title bar text of a window.

window	The window id. If the window is a dialog box control such as an editbox or pushbutton, wintext returns the text within the control rather than the dialog’s caption. Note, however, that wintext cannot retrieve the text of an edit control within another application.

strvar	Will receive the requested text. Strvar will be null if the target window has no title text.

Example

proc main

   string TextStr              ; Title of the active window.

   wintext $ACTIVEWIN TextStr  ; Get title of active window.

   usermsg "Active window title is `"%s`"." TextStr

endproc

See also

dlgwin and dlgctrlwin; $ACTIVEWIN and $FOCUSWIN; Task/Window Manipulation Commands.


wintoscreen

wintoscreen window intvar intvar

Converts the X/Y coordinates that are relative to a window into absolute screen coordinates.

window	The window id.

intvar	The window X coordinate value to convert.

intvar	The window Y coordinate value to convert.

Example

proc main

   integer X = 0, Y = 0          ; Window relative X and Y position of

                                 ; top / left of Procomm Plus window.

   wintoscreen $PWMAINWIN X Y    ; Convert window relative to screen.

   usermsg "Procomm Plus is at %d, %d." X Y

endproc

Comment

Screen and window coordinates are measured in pixels. Window coordinates are relative to the client area of a window, which begins at a point inside the window frame, if any, and below the caption and menu bars, if any.

The intvar arguments must be initialized to the values to convert.

See also

screentowin, wincoord and uwutowin; $XPIXELS and $YPIXELS; General Windows Commands.


wintouwu

wintouwu intvar intvar BACKGROUND | USERWIN

Converts X/Y coordinates relative to a window into User Window Units.

intvar	The User window X coordinate value to convert.

intvar	The User window Y coordinate value to convert.

BACKGROUND	Convert values relative to the User window background graphic.

USERWIN	Convert values relative to the User window proper.

Example

See the example for uwutowin.

Comment

Window coordinates are measured in pixels and are relative to the window’s client area. The client area of a window is the area that begins at a point inside the window frame, if any, and below the caption and menu bars, if any.

The intvar arguments must be initialized to the values to convert.

See also

when mouseevent, uwutowin and wintoscreen; $LMOUSEX, $LMOUSEY and $USERWIN; User Window Commands.


winvisible

winvisible window [intvar]

Tests whether a window is hidden or visible. winvisible reports SUCCESS if the target window is visible. It reports FAILURE if the window is hidden or if a window could not be found using the specified window id.

window	The target window id.

intvar	If specified, will be 1, meaning the window is visible or 0, meaning the window is hidden.

Example

proc main

   winhide $PWMAINWIN         ; Hide the Procomm Plus window.

   if winvisible $PWMAINWIN   ; See if Procomm Plus is visible.

      usermsg "Procomm Plus is visible."

   else

      usermsg "Procomm Plus is hidden!"

   endif

   winshow $PWMAINWIN         ; Show the Procomm Plus window.

endproc

See also

winstate, winenabled, winexists, winhide and winshow; Task/Window Manipulation Commands.


wizard

wizard filespec

Activates a Procomm Plus wizard. The wizard command reports SUCCESS if the specified wizard is successfully finished. It reports FAILURE if the specified wizard was not found, or if the user presses the wizard's Cancel button.

filespec	A string variable or constant that contains the name of the wizard file.

Example

proc main

   wizard "wizftp.wiz"

endproc

Comments

The filespec can contain the name of any valid Procomm Plus wizard file. If a full path is not specified, the local task path is used by default.

Only one wizard may be executed at a time with ASPECT.


xfercancel

xfercancel

Cancels a current file transfer operation. xfercancel has the same effect as the user pressing <Esc> or the Cancel button during a file transfer.

Example

proc main

   when USEREXIT call CleanUp ; Clean up when user quits.

   while 1                    ; Loop and wait for user to quit.

      yield                   ; Yield process time

   endwhile

endproc

proc CleanUp

   if $XFERSTATUS             ; If file transfer in progress,

      xfercancel              ; cancel it and wait for a bit.

      pause 3

   endif

   pwexit                     ; Exit Procomm Plus.

endproc

See also

sendfile and getfile; set aspect filexferbox; File Transfer Commands.


xlatin

xlatin intvar | {strvar strlength}

Converts a character or string using the current incoming Translate Table values.

intvar	The character value to process.

strvar	The string to process.

strlength	The number of characters to process in the string.

Example

proc main

   integer Chr                   ; Character from com port.

   integer Key                   ; Character from keyboard.

   integer ANSIKey               ; Key converted to ANSI key.

   set aspect rxdata ON          ; Aspect processes com data.

   set aspect keys ON            ; Aspect handles key presses.

   while 1                       ; Loop forever.

      if $RXDATA                 ; Check for received data.

         comgetc Chr             ; Get character from port.

         xlatin Chr              ; Translate incoming character.

         termwritec Chr          ; Write character to terminal.

      endif

      if $KEYHIT                 ; Check for key presses.

         keyget Key              ; Get key from keyboard buffer.

         keytoansi Key ANSIKey   ; Convert key to ANSI key.

         if ANSIKey == 0         ; See that key is normal.

            xlatout Key          ; Translate outgoing character.

            computc Key          ; Write character to com port.

         else

            termvkey Key         ; Make PW process the key.

         endif

      endif

   endwhile

endproc

See also

xlatout and xlatstr; set translate command; General Procomm Plus Commands.


xlatout

xlatout intvar | {strvar strlength}

Converts a character or string using the current outgoing Translate Table values.

intvar	The character value to process.

strvar	The string to process.

strlength	The number of characters to process in the string.

Example

See the example for xlatin.

See also

xlatin and xlatstr; set translate command; General Procomm Plus Commands.


xlatstr

xlatstr strvar intvar

Performs caret translation on a string.

strvar	The string to be translated.

intvar	Will be updated with the length of the translated string.

Example

proc main

   string TextStr              ; Text string to display.

   integer Len                 ; Length of converted string.

   TextStr = "^[[0;35m^[[1;1H^M^JIs that my Porsche?^M^J"

   xlatstr TextStr Len         ; Translate string.

   termwrites TextStr          ; Write string to terminal.

endproc

Comments

transmit, waitfor, when target, termputs and termwrites also perform caret translation. For more information, see Caret Translation.

See also

xlatin and xlatout; General Procomm Plus Commands.


yield

yield

Suspends script execution, allowing other tasks within Procomm Plus to continue execution until ASPECT is permitted to resume script execution by the system.

Example

See the example for getfile.

Comments

Under Windows NT 4.0, the following loop can monopolize CPU utilization when, in fact, the script needs to peform very little processing:

while 1 ;  while TRUE would also work

.

.

.

endwhile

To prevent this wasteful CPU utilization, place a yield command at the end of the while loop.

See also

pause; Script Control Commands.