dirpath id left top width height [gstrvar]Displays the current disk drive and directory for a dirlistbox control within a dialog box.

idA unique integer constant which identifies this control.

left top width heightInteger 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 "User Window and Dialog Box Units" in Chapter 2.

gstrvarIf specified, gstrvar will contain the dirpath contents.

ExampleSee example for dirlistbox.

CommentsIf 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 global string result variable is specified.

See alsodialogbox, dlgevent and dirlistbox.

disable DIALOGBOX dlgid

disable DLGCTRL dlgid startid [endid]

disable ASPMENU startid [endid]

disable PWMENU startid [endid][PERMANENT]

disable WINDOW window Disables dialog box controls, dialog boxes, menu selections or windows. Items that are disabled are grayed and cannot be selected.

dlgidThe 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]

dlgidThe unique id of the dialog box containing the control to be disabled.

startidThe id of the first or only control to be disabled.

endidIf specified, allows a range of dialog box controls to be disabled, from (startid) to (endid).

disable ASPMENU startid [endid]

ASPMENUDisables a menu or menu selection generated by a Windows ASPECT script.

startidThe id of the menu or menu selection to be disabled.

endidIf specified, allows a range of menu selections to be disabled, from (startid) to (endid).

disable PWMENU startid [endid][PERMANENT]

PWMENUDisables a menu or menu selection on the PROCOMM PLUS menus.

startidThe id of the menu or menu selection to be disabled.

endidIf specified, allows a range of menu selections to be disabled, from (startid) to (endid).

PERMANENTThe menu will remain disabled after the script terminates.

disable WINDOW window

windowThe 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 Event ; Dialog event.

; Define a dialog box with pushbutton controls.

dialogbox 0 0 0 100 50 11 "Disable Dialog" pushbutton 1 5 5 40 40 "Button &1" pushbutton 2 55 5 40 40 "Button &2" 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. 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

CommentsThe programmer 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; when a window is disabled it no longer responds to keyboard or mouse input!The id values of PROCOMM PLUS menu items can be found in MENUIDS.INC, installed by default in the ASPECT directory. This file can be #included for reference in a Windows 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.

Note: The $ASPMENU system variable is used only for menu items created by a Windows ASPECT script and will not indicate when a PW menu item has been selected.

See alsodialogbox, enable, menupopup, menuitem, winactivate, wintask, taskactivate and taskwin; $ACTIVEWIN, $PWTASK, $TASK and $ASPMENU in Appendix B, "System Variables".

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

diskAn 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.

longvarWill 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." FreeDiskendproc

See alsodir, getdir and memavail; $USERPATH and $VOLUME in Appendix B, "System Variables".

dlgctrlwin id ctrlid intvarReturns the window id of a dialog box control.

idThe id of the dialog box which contains the specified control.

ctrlidThe id of the specified control.

intvarWill contain the value of the window id of the specified control.

Example

proc main integer hPushButton ; Window handle for pushbutton. integer Count = 0 ; Used in while loop below.

; Display a dialog and flash a pushbutton on and off.

dialogbox 0 0 0 100 50 11 "Flashing Button" pushbutton 1 5 5 90 40 "Flash" enddialog

dlgctrlwin 0 1 hPushButton ; Get handle of pushbutton.

while (Count++) << 5 ; Loop for count. winhide hPushButton ; Hide the pushbutton. pause 1 ; Pause for effect.

winshow hPushButton ; Show the pushbutton. pause 1 ; Pause for effect. endwhile dlgdestroy 0 CANCEL ; Destroy the dialog.endproc

CommentsThe returned window id may be used in any command that accepts a window id.

See alsodialogbox and dlgwinctrl; $FOCUSWIN in Appendix B, "System Variables".

dlgdestroy id CANCEL|OKDestroys a dialog box.

idThe id of the dialog box to be destroyed.

CANCELIf specified, the dialog box will be destroyed without updating any changes made to file-related controls.

OKIf specified, the dialog box will be destroyed, but changes made to file-related controls will be saved to disk.

ExampleSee example for dialogbox.

CommentsTo save changes made to a specific control before destroying it, 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 with OK updates all variables whose events have not been retrieved with dlgevent.

See alsodialogbox, dlgevent, dlgsave, fcombobox, feditbox and flistbox.

dlgevent id [intvar | {FLUSH [SAVE]}]Returns the id of a user action within a dialog box, or flushes the event queue for the specified dialog box.

idThe dialog box id whose event queue will be accessed.

intvarIf specified, will return the value of the last dialog box event.

FLUSHIf specified, will reset the event queue for the specified dialog box.

SAVEOnly valid with the flush keyword. Causes variables associated with event values to be updated as the values are flushed from the queue.

Example

proc main integer Event ; Dialog box event.

; Define and display dialog and wait for events.

dialogbox 0 0 0 100 50 11 "Dialog Events" enddialog

while 1 ; Loop forever. dlgevent 0 Event ; Get dialog event. switch Event ; Evaluate the event. case 0 ; No event occurred. endcase default ; Dialog event occurred. exitwhile ; Exit the while loop.

endcase endswitch endwhile dlgdestroy 0 CANCEL ; Destroy dialog box.endproc

Commentsdlgevent will set the intvar argument 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.The dlgevent id flush save is useful when the dialog box style value includes 128 (Update variables when event is read). See the dialogbox style list for more information.

See alsodialogbox, dlgdestroy, dlgsave and dlgwin.

dlglist id ctrlid {INSERT string [integer]} | {REMOVE string}Adds or removes an item from a listbox, flistbox, combobox or fcombobox control.

idThe id of the dialog box containing the target list control.

ctrlidThe target list control id.

INSERT stringThe 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.

integerIf specified, determines the index location where the string will be inserted into the itemlist. A value of -1 will append the string to the end of the list, while a 1 will insert the string at the top. 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 of items.

REMOVE stringThe specified string will be removed from the target control's itemlist.

Example

string szList ; List of stuff to choose from.string szItem ; Item selected from list.

proc main dialogbox 0 0 0 100 50 11 "Dlglist Example" listbox 1 5 5 90 40 szList SINGLE szItem SORT 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"

dlgupdate 0 1 ; Update the listbox. pause 5 ; Show off the dialog.

dlgdestroy 0 CANCEL ; Destroy the dialog.endproc

Commentsdlglist returns SUCCESS if the string was successfully added or removed from the target control's item list; FAILURE otherwise. dlglist does not affect dlgsave, since dlgsave only saves items which have been selected in the target list.

See alsodialogbox, dlgsave and dlgupdate.

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.

idThe id of the dialog box containing the control to be saved.

ctrlid [ctrlid]The control id, or, if the second [ctrlid] is specified, a range of control id's to be saved.

ExampleSee example for feditbox.

Commentsdlgsave is useful for saving file-related controls, or for reading current selections when a dialog box is created using style 128 (see dialogbox for more information on dialog style-bits). Typically, dialog box controls update their associated data fields as changes are made to them.

See alsodlgdestroy, dlgevent and dlgupdate.

dlgshow id Causes a hidden dialog box to be visible.

idThe 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

Commentsdlgshow is only useful for showing dialog boxes of style 32 (hide until shown). Use winshow to display a dialog box hidden with winhide.

See alsoenable, disable, dialogbox, dlgwin, winshow and winhide.

dlgupdate id ctrlid [ctrlid] Refreshes the display of a dialog box control, applying any changes made to the variables that are used to initialize the control.

idThe id of the dialog box containing the controls to be updated.

ctrlid [ctrlid]The control id, or, if the second [ctrlid] is specified, a range of control id's to be refreshed.

ExampleSee example for dlglist.

CommentsIf a gstrvar is used for the dialog box title, it can be refreshed using a start id of 0.

See alsodialogbox and dlgsave.

dlgwin id intvarReturns the window id of the specified dialog box.

idThe id of the dialog box desired.

intvarWill contain the window id value of the dialog box.

Example

proc main integer hDlg ; 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 hDlg ; Get window handle for dialog. wincoord hDlg XPos YPos ; Get X and Y position of dialog. while (YPos += 10) $YPIXELS ; Loop while dialog's on screen. winmove hDlg XPos YPos ; Move the dialog.

mspause 250 ; Pause for effect.

endwhile dlgdestroy 0 CANCEL ; Destroy the dialog box.endproc

CommentsThe value returned by dlgwin can be used with winhide, winshow, and other window-related commands to manipulate the state of the dialog box.

See alsodialogbox, enable, disable, winhide, winmove and winshow.

lgwinctrl id window intvarConverts a window id into the corresponding control id, within a given dialog.

idThe target dialog box id.

windowThe window id to convert.

intvarWill be updated with 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

Commentsdlgwinctrl performs the opposite function of dlgctrlwin. It allows a script to determine which dialog box control has the input focus, when used in conjunction with $FOCUSWIN.FAILURE is set if no control id within a dialog corresponds to the specified window id.

See alsodialogbox and dlgctrlwin; $FOCUSWIN in Appendix B, "System Variables".

dllcall integer string [arglist]Calls a routine or process within a .DLL module that was created to interact with ASPECT.

integerThe ID of the DLL previously loaded with dllload.

stringA string identifying the process to be executed within the DLL.

arglistA maximum of 12 variables can be passed as arguments.

ExampleSee example for dllload.CommentsFor complete DLL specifications, please contact the DLL author or the DATASTORM TECHNOLOGIES BBS.

Warning! 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 alsodllload and dllfree.

dllfree integerFrees unneeded DLL memory resources.

integerThe DLL id number returned by the dllload command that initiated the process you wish to free.

ExampleSee example for dllload.CommentsA script should generally "clean up" 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 alsodllcall and dllload.

dllload filename intvar [PERMANENT]Loads the specified DLL module into memory.

filenameThe name of the DLL to load. If no path is specified, the Aspect Path is assumed.

intvarAn integer id used by the dllcall and dllfree commands to reference the DLL module.

PERMANENTThe DLL will remain loaded after the script terminates. It will unload, however, when PROCOMM PLUS terminates.

Example

proc main string szDLL = "funcs.dll" ; DLL to load. integer hDLL ; Handle to the DLL.

if dllload szDLL hDLL ; Open the Dynamic Link Library.

; Make a call to the "DisplayBMP" function in the DLL, ; and pass it the index of a bitmap to display.

if not dllcall hDLL "DisplayBMP" 3 errormsg "Call to `"DisplayBMP`" function failed!" endif

; In order for Aspect to call a DLL, the DLL must be an

; Aspect compatible DLL.

dllfree hDLL ; Free or close the library. else errormsg "Couldn't open DLL!" endifendproc

CommentsTypically, the only .DLLs that should be loaded are those written specifically to interface with ASPECT and the dllcall command. See the dllcall command reference for more information.

See alsodllcall and dllfree; set aspect path in Appendix A, "Set and Fetch Statements".

dllobject id left top width height BACKGROUND | USERWINIdentifies a graphic object within a User window to be updated by an associated DLL module.

idThe control id for the DLL object; $OBJECT will be set to this value when the object is selected by the user.

left top width heightInteger parameters specifying the initial position and size of the DLL object. Coordinates are relative to PROCOMM PLUS's client window.

USERWIN | BACKGROUNDSpecify USERWIN to "fix" the top left corner of the object in position relative to the upper left corner of the User window. If BACKGROUND is specified, the object stays over the same spot on a background graphic.

ExampleSee example for dllobjfile.

CommentThe 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. Contact the DATASTORM BBS for special application notes describing their use.

See alsouwincreate, dllobjfile, dllobjupdt, objpaint, objremove, hotspot, bitmap, icon, iconbutton, pushbutton and metafile; and $OBJECT in Appendix B, "System Variables".

dllobjfile filespecSpecifies a file containing a graphic object to be accessed or updated with the dllobject command.

filespecIf a path is not specified, filespec defaults to the current Aspect Path.

Example

proc main string szDLL = "objs.dll" ; DLL object file to load.

; Define a user window and place on it a DLL object.

dllobjfile szDLL ; 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 alsouwincreate, dllobject and dllobjupdt; $OBJECT in Appendix B, "System Variables".

dllobjupdt id [arglist]Allows a DLL module linked to a DLL object to update that object.

idThe identifier assigned by the user in the dllobject command.

arglistA maximum of 12 variables can be passed as arguments.

ExampleSee example for dllobjfile.

See alsouwincreate, dllobject and dllobjfile.

dos string [MINIMIZED | MAXIMIZED | HIDDEN] [intvar]Executes a DOS command or another program within a separate DOS window.

stringAny executable command as it would appear on the DOS command line.

MINIMIZEDForces PROCOMM PLUS to execute the command or program as a minimized icon.

MAXIMIZEDExecutes the command or program in a full screen DOS window.

HIDDENForces PROCOMM PLUS to execute the command or program with no visible DOS window.

intvarAn 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

CommentsIf 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 a false if COMMAND.COM is not found and 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. Unlike the run command, the dos command will execute both standard DOS batch files and internal DOS commands; run only accepts .COM and .EXE programs. During Windows Standard mode operation, the DOS session will run full screen.

See alsorun, shell and taskexists.

editbox id left top width height gstrvar [strlength] [MASKED][MULTILINE]Adds an editing box for text entry in a Windows ASPECT dialog box.

idThe control id for the editbox, specified as an integer constant. This value will be reported by dlgevent whenever the editbox contents are changed.

left top width heightInteger constants specifying the initial position and size of the editbox. Coordinates are relative to the dialog box, specified in DBUs. For more information on DBUs, see "User Window and Dialog Box Units" in Chapter 2.

gstrvarThis 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.

strlengthAn integer constant or global 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.

MASKEDIf specified, an asterisk is displayed for each character typed into the field.

MULTILINEIf specified, allows text to be word-wrapped to the next line in the edit box. Note that the text is still limited to 256 characters.

Example

string szText ; Text from dialog box.

proc main integer Event ; Dialog box event.

; Define and display dialog with editbox.

dialogbox 0 0 0 100 50 11 "Editbox Example" editbox 1 5 5 90 40 szText MULTILINE 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 szText ; See that szText isn't empty. usermsg "You typed:`r`r%s" szText else usermsg "No text entered." endifendproc

Commentseditbox can only occur within a dialogbox statement group. If the user is entering sensitive information - for example, a password - use the MASKED option for security.A dialog event is generated when the control has been changed and loses the input focus.

See alsodlgupdate, dialogbox, dlgevent, ftext, text and feditbox.

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 "Bob has 1 brush." else usermsg "Bob has %d brushes." Number endifendproc

See alsoif, elseif and endif.

#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. #endifendproc

See also#define, #ifdef, #ifndef, #elifdef, #elifndef and #undef.

elseif condition

Enables multiple tests within an if/endif command block. elseif can be used instead of if ... endif statement groups.

conditionConditions 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; 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 First = 1 ; First integer variable. integer Second = 2 ; Second integer variable.

if First != 1 ; Check to see if first is not 1. usermsg "First is not 1." elseif Second == 2 ; Check to see if second is 2. usermsg "Second is 2!" endifendproc

See alsoif, else and endif.

#elifdef nameAllows 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.

nameMacro 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 "Debug" usermsg "Debug" ; message. #endifendproc

See also#define, #ifdef, #ifndef, #else, #elifndef and #undef.

#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.

nameMacro 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. #endifendproc

See also#ifdef, #ifndef, #elifdef, #else and #define.

enable DIALOGBOX dlgid

enable DLGCTRL dlgid startid [endid]

enable ASPMENU|PWMENU startid [endid]

enable WINDOW window Enables dialog box controls, dialog boxes, menu selections or windows.

dlgidThe unique id of the dialog box to enable.

enable DLGCTRL dlgid startid [endid]

dlgidThe unique id of the dialog box containing the control to be enabled.

startidThe id of the control to be enabled.

endidIf specified, allows a range of dialog box controls to be enabled, from (startid) to (endid).

enable ASPMENU|PWMENU startid [endid]

ASPMENU | PWMENUDetermines whether the menu or menu selection to be enabled was generated by PROCOMM PLUS or a Windows ASPECT script.

startidThe id of the menu or menu selection to be enabled.

endidIf specified, allows a range of menu selections to be enabled, from (startid) to (endid).

enable WINDOW window

windowThe 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 pushbutton controls.

dialogbox 0 0 0 100 50 11 "Disable Dialog" pushbutton 1 5 5 40 40 "Button &1" pushbutton 2 55 5 40 40 "Button &2" 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

Commentsenable cannot be used to enable something that PROCOMM PLUS disabled. It applies only to PROCOMM PLUS  menu items or menu items and dialog box controls created by a script. The programmer 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 popup items. PROCOMM PLUS 's menuitems can always be affected, unless they were disabled by PROCOMM PLUS itself. The active menu is always returned by the $PWMENUBAR system variable.

Note: Two useful files are provided with PROCOMM PLUS that can be #included into your scripts. These files are MENUIDS.INC, which defines all of PROCOMM PLUSs menu values, and VKEYS.INC, which defines the virtual key codes as defined in Appendix E, "Virtual Key Codes". Both of these files are installed to the default ASPECT directory.

See alsodisable, dialogbox, menupopup, menuitem, $ASPMENU and $PWMENUBAR in Appendix B, "System Variables".

encrypt strvar strlengthencrypts or encodes the target string.

strvarThe string to encrypt; it will be updated with the encoded data.

strlengthThe 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" "Text: " TextStr if SUCCESS ; See if CANCEL was selected. strlen TextStr Len ; Get length of text string. encrypt TextStr Len ; If not, encrypt text string. transmit TextStr ; Send string to remote system. transmit "^M" ; Send a carriage return.

endifendproc

CommentsThe encrypt and decrypt commands work on "raw" data. For this reason, you must specify the length of the string to be encoded.

Also, use caution if writing the encrypted data to a text file. Since the data may contain control characters or even nulls, it should not be written to a Windows .INI file.

See alsodecrypt; the set ASPECT datakey command in Appendix A, "Set and Fetch Statements."

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

ExampleSee example for switch.

CommentsRegardless 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 alsocase, default, exitswitch and switch.

#endcommentMarks the end of a comment block; commands and text which follow are no longer ignored.

ExampleSee example for #comment.

See also#comment.

enddialogMarks the end of a dialogbox statement group.

ExampleSee example for dialogbox.

CommentsFor more information, refer to the description for the dialogbox command.

See alsodialogbox.

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.

ExampleSee example for for.

See alsoexitfor, for and loopfor.

endfuncTerminates a function call block. See the func command for further information.

ExampleSee example for func.

CommentsSimilar 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 alsofunc and return.

endgroupConcludes a radiogroup block within a dialogbox definition.

ExampleSee example for radiogroup.

CommentsFor more information, see the radiogroup command description.

See alsoradiogroup, radiobutton and dialogbox.

endifConcludes the if statement group.

ExampleSee example for if.

See alsoif.

#endifConcludes the #if statement group.

CommentsStatements following the #endif command will be processed normally by the compiler.

See also#define, #elifdef, #elifndef, #else, #ifdef, #ifndef and #undef.

endprocTerminates a procedure block. See the proc command for further information.

ExampleSee example for proc.

Commentsendproc implies a return to the calling procedure. The return statement isn't required.

See alsoproc and return.

endswitchTerminates the switch statement group. See the switch command for further information.

ExampleSee example for switch.

See alsoswitch.

endwhileTerminates the while statement group. Execution jumps to the associated while command, where the condition is tested to determine whether another loop iteration is required. See the while command for further information.

ExampleSee example for while.

See alsoexitwhile, loopwhile and while.

errormsg formatstr [arglist] [RESUME]Displays an error message dialog box with an exclamation point graphic and accompanying text.

formatstr

A string of up to 256 characters; it may contain both text and format specifiers.

arglistUp to 12 arguments may be specified for the formatstr to process; these arguments must appear in the order they were specified within the formatstr.

RESUMEIf specified, ASPECT will allow active when commands to fire while the errormsg dialog is displayed. If RESUME is not specified, all script activity will be suspended until the errormsg dialog is destroyed.

Example

proc main string szFname ; String to contain name of file. szFname = "paint.job" ; Assign file name to variable and ; try to open the file for READ. if not fopen 0 szFname READ

; If the fopen is unsuccessful display an error message.

errormsg "Couldn't open file `"%s`"." szFname else fclose 0 ; Make sure that file is closed. endifendproc

CommentsA 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 pushbutton.

See alsosdlgmsgbox, usermsg, termmsg and statmsg.

execute filespec [SHARED]Executes another Windows ASPECT script (either a source program or a compiled script). Control returns to the parent script upon completion.

filespecAny valid script filename.

SHAREDCauses the executed script to inherit the parent script's current ASPECT environment settings, rather than the default settings.

Example

proc main string szScript ; Script file to run.

if sdlginput "Run Script" "Name:" szScript

if isfile szScript usermsg "Executing Script" execute szScript ; Execute the script file. usermsg "Returned from Script" else errormsg "Script doesn't exist!" endif endifendproc

CommentsThe filespec doesn't require a path. If the path is not provided, the current Aspect Path is used by default.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 automatically will be recompiled. If a compiled script that matches the filespec can't be found, execute will attempt to compile a matching source file (with the .WAS extension).

If a .WAS file is specified, Windows ASPECT always attempts compilation.Only 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 "Chaining and Spawning Scripts" in Chapter 2 of this manual.

See alsochain; set aspect path in Appendix A, "Set and Fetch Statements"; $PARENTFILE and $SCRIPTMODE in Appendix B, "System Variables".

exit [integer]Terminates the executing script file.

[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

CommentsIf the script was spawned or is the child of another script, control returns to the parent script.ASPECT is an excellent housekeeper, 'tidying up' when a script terminates. However, users are encouraged to close files and release memory and DLL's allocated by the script, in keeping with good programming practices.

See alsohalt and pwexit; the $EXITCODE, $PARENTFILE and $SCRIPTMODE system variables in Appendix B.

exitforContinues execution with the command following an endfor command. For further 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 alsoendfor, loopfor and for.

exitswitchTransfers 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.

CommentsAn 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 keyboard buffer. switch Key ; Evaluate the key. default keytoansi Key Key ; Convert key 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 ; PROCOMM PLUS handles key presses.endproc

See alsodefault, switch and case.

exitwhileTerminates 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. endwhileendproc

See alsoendwhile, while and loopwhile.

exitwindowsTerminates all executing tasks and returns the user to the DOS prompt.

Example

proc main integer Choice

sdlgmsgbox "Exit Windows" "Exit Windows?" STOP YESNO Choice 1 if Choice == 6 ; See if user selects the YES button. exitwindows ; Exits Windows gracefully. endifendproc

CommentsSUCCESS and FAILURE are set to indicate whether all tasks actually terminated. Only testing for FAILURE is relevant; SUCCESS indicates that Windows and all Windows tasks (including PROCOMM PLUS and the script) have been terminated!

See alsotaskactivate, taskexists, taskexit, taskname and taskwin.

faxcancelCancels the current fax operation.

ExampleSee example for faxsend.

Commentsfaxcancel only affects a fax dialing attempt; to cancel a data or voice dialing attempt, use the dialcancel command.

See alsodialcancel and faxsend.

faxlist RECEIVED|SCHEDULED index strvar [intvar]Enumerates the faxes displayed in the received or scheduled fax lists.

RECEIVEDIf specified, the list of received faxes will be processed.

SCHEDULEDIf specified, the list of scheduled faxes will be processed.

indexA zero-based index, specifying the fax list entry to process.

strvarIf 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 "". 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.

ExampleSee example for faxremove.

See alsofaxview and faxremove.

faxpoll [DIALDIR [GROUP]] string [timeval]Dials a Dialing Directory entry or group, or a specified number, to receive faxes from a host.

DIALDIRAn optional keyword, indicating that the string argument is the name of a Dialing Directory entry (or group, if GROUP is also specified).

GROUPAn optional keyword, indicating that the argument string contains a group name, rather than an entry name, to dial.

stringIf DIALDIR is not specified, the string contains a fax number to be dialed. If DIALDIR is specified, the string contains the name of a Dialing Directory entry, or a Dialing Directory group if DIALDIR GROUP is specified.

timevalA long value of type timeval, specifying the scheduled date and time for the polling to be performed. If the time specified by timeval is already past the current time, then the polling operation will be performed immediately, as if no scheduled time was provided.

Example

proc main ; Call the fax number we want to poll, tell them our name is ; "Fax Maniac" and poll for faxes.

faxpoll DIALDIR "Fax Maniac" endproc

CommentsThe group or entry names must match exactly the information contained in the associated Dialing 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.

Warning: $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 alsofaxsend.

faxprint filespecPrints a specified fax file.

filespecThe name of the fax file to print.

Example

proc main string szFname; Name of fax file to print.

if sdlgfopen "Fax Print" "C:\PROWIN2\FAXRECV\*.FAX" szFname if not nullstr szFname; Make sure file was chosen. faxprint szFname; Print the fax file selected. endif endifendproc

Commentsfaxprint 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.

Note: Any file type other than .FAX will cause faxprint to fail (however, SUCCESS and FAILURE are not set by this command).

See alsofaxlist, faxview.

faxremove RECEIVED | SCHEDULED indexRemoves a fax from the received or scheduled fax list.

RECEIVEDThe target fax file is in the received fax list.

SCHEDULEDThe 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 corresponding list.

Example

proc main string szFaxName; Name of scheduled fax. string szPrompt; used in MsgBox integer TriesMade; Number of tries made to send integer Decision; User's response if faxlist SCHEDULED 0 szFaxName TriesMade strfmt szPrompt "FAX [%s] has been attempted [%d] times." szFaxName TriesMade sdlgmsgbox "Delete Fax?" szPrompt STOP YESNO Decision 2 if (Decision == 6); User said yes! faxremove SCHEDULED 0; So do it! endif

endifendproc

Commentsfaxremove returns FAILURE if the specified fax could not be removed.

See alsofaxlist, faxsend and faxcancel.

faxsend {string string} | {DIALDIR [GROUP] string} [COVERSHEET filespec | NONE] [NOTES string] [timeval] [SINGLE | MULTIPLE filespec [BINARY]] [MEMO filespec] Dials the specified number, Dialing Directory entry or group, and transmits a specified fax file.

stringThe information to insert in the "To:" field of the transmitted fax.

stringThe fax number to dial, in order to send the fax.

DIALDIR stringThe name of the Dialing Directory entry to dial in order to send the fax. The group or entry name must match exactly the information contained in the associated Dialing 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.

GROUPAn optional keyword, indicating that the argument string contains a group name, rather than an entry name to dial.

COVERSHEET filespecIf 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.

NONEIf specified, the fax will be sent without a cover sheet.

NOTES stringIf specified, this 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, this string will be ignored.

timevalA 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, as if no scheduled time was provided.

SINGLE filespecThe filespec is a single file to transmit. If a path is not included in the filespec, the Sent Faxes path in Setup is assumed.

MULTIPLE filespecFilespec specifies a file containing one or more filename(s) to transmit by fax. Each filename should appear on a single line within the selection file. If a path is not included in the filespec, the User Path is assumed. However, for filenames within the list of files, the Scheduled Faxes path in Setup is assumed if no path is specified.

BINARYIf specified, the specified file(s) will be sent as a Binary File Transfer, and will not print as faxes on the receiving side. For more information, see Chapter 5 in the PROCOMM PLUS USER MANUAL.

MEMO filespecThe specified file will be treated as a memo fax. For more information, see Chapter 5 of the PROCOMM PLUS USER MANUAL. If a path is not included in the filespec, the User Path is assumed.

Example

proc main string szFname; Fax file to send.

when USEREXIT call CleanUp; Watch for a disconnection.

if sdlgfopen "Fax Send" "C:\PROWIN2\FAXSEND\*.FAX" szFname

if not nullstr szFname; Make sure something was selected. faxsend "Joe Fax" "(314) 555-4321" SINGLE szFname while $FAXSTATUS; Loop while fax in progress. endwhile endif endifendproc

proc CleanUp faxcancel; Cancel the fax send if user ; tries to exit script.

endproc

See alsofaxpoll, faxlist and faxcancel.

faxview filespecDisplays a fax file.

filespecThe name of the fax file to view.

Example

proc main string szFname; Name of fax file to view.

if sdlgfopen "Fax View" "C:\PROWIN2\FAXRECV\*.FAX" szFname if not nullstr szFname; Make sure file was chosen. faxview szFname endif endifendproc

Commentsfaxview 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.

Note: Any file type other than .FAX will cause faxview to fail (however, SUCCESS and FAILURE are not set by this command).

See alsofaxlist and faxprint.

fclear id

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

Example

proc main string szFname = "GORBY.CHK"; Name of file to be opened. string szLine ; Line read from file.

if fopen 0 szFname 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 szLine ; 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." szFname endifendproc

See alsofopen, feof and ferror.

fclose idCloses the file corresponding to the indicated file id.

Example

proc main string szFname = "bonzo.txt"; Name of file to be opened.

if fopen 0 szFname CREATE ; Open and create specified file. fputs 0 "Float me home!"; Write some text to the file. fclose 0 ; Close file opened for create. else errormsg "Couldn't open file `"%s`"." szFname endifendproc

CommentsThe I/O buffer contents for a file will automatically be written before it's closed (if it was opened in WRITE, READWRITE or CREATE mode). This command can be tested with the if SUCCESS statement, returning false if an error occurred while closing the file.

See alsofopen and fflush.

fcombobox id left top width height SIMPLE | DROPDOWN | DROPDOWNLIST filespec [OFFSET fileoffset [LENGTH filelength]] gstrvar [strlength] [SORT] Adds a combination edit/selection or "drop-down" selection control to a Windows ASPECT dialog box.

idA 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 heightThese integer constants determine the position and size of the fcombobox control in dialog box units, relative to the dialog box's dimensions. For more information on DBUs, see "User Window and Dialog Box Units" in Chapter 2.

filespecThe 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.

SIMPLEThe list box is displayed at all times; the current selection in the list box is displayed in the edit control.

DROPDOWNSimilar to the SIMPLE type, but the listbox is not displayed unless the user selects the icon next to the text edit control.

DROPDOWNLISTSimilar to the DROPDOWN type, but the edit control is replaced by a static text item that displays the current selection in the list box.

OFFSET fileoffsetAn optional offset within the file where the list to be displayed begins. A global long variable, or a constant.

LENGTH filelengthIf filelength is specified, only the allowed number of bytes will be displayed. A global long variable, or a constant.

gstrvarContains a single list selection. gstrvar can be pre-initialized with an item, allowing it to already be selected upon entry.

strlengthIf specified, defines the maximum number of characters which can be entered in the edit control. This parameter is not valid with the DROPDOWNLIST style. A global

integer variable or constant.

sortIf specified, the contents of the fcombobox will be sorted lexigraphically in ascending order.

Example

string szItem ; Item selected from list.

proc main 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 0 0 100 50 11 "Fcombobox Example" fcombobox 1 5 5 90 40 DROPDOWNLIST "food.lst" szItem 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!" szItem endcase default ; Exit method selected. exitwhile ; Exit the while loop. endcase endswitch endwhile

dlgdestroy 0 CANCEL ; Destroy the dialog box.endproc

CommentsLike 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 alsocombobox, dialogbox, dlgsave, dlgupdate, dlgevent, flistbox and listbox.

fdelblock id integer

Deletes a block of data from the specified file.

idThe target file index.

integerThe 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" READ ; Open the user file for read. 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

Commentsfdelblock begins deleting data at the current position of the file pointer; 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 alsoflength, finsblock, fseek, fstrfmt, ftell, fwrite, ftruncate, fflush and rewind.

feditbox id left top width height filespec [HSCROLL] Adds a text editing box with the contents of a disk file in a Windows ASPECT dialog box.

idA unique integer constant value assigned to the feditbox by the user. When the contents of the feditbox are changed and the control loses input focus, this value will be reported by dlgevent.

left top width heightThese integer constants determine the position and size of the feditbox control in dialog box units, relative to the dialog box's dimensions. For more information on DBUs, see "User Window and Dialog Box Units" in Chapter 2.

filespecA global string variable containing the name of the file to edit. If a path is not specified, the Aspect Path is assumed.

HSCROLLAn 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 Feditbox and ; a save button.

dialogbox 0 0 0 100 50 11 "Feditbox 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 feditbox to file. endif exitwhile ; Exit the loop. endcase endswitch endwhile dlgdestroy 0 CANCEL ; Destroy dialog box.endproc

CommentsIf 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; they will not be saved if the dialog is terminated with a Cancel.feditbox supports a maximum file size of 64K for editing - however, this figure 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 alsodialogbox, disable, dlgevent, dlgsave, dlgupdate, editbox, enable, ftext and text.

feof id [intvar]Tests for end-of-file condition on the specified file index id.

idThe file id to test.

intvarIf specified, will be set to the result of the test; 0 for false and 1 for true.

Example

proc main string szFname = "MONKEYS.WRK"; Name of file to read. string Chimp ; Text to read from file.

if fopen 0 szFname READ ; Open file for read only. while not feof 0 ; Loop while not end of file. fgets 0 Chimp ; Read a Chimp from file. usermsg Chimp ; Display Chimp to user. endwhile

fclose 0 ; Close the file. else errormsg "Can't open `"%s`" for input." szFname

endifendproc

CommentsWhen 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 alsofclear, fclose, ferror, fopen, fseek and rewind.

ferror id [intvar] Tests for any error condition on the specified file index.

idThe file index id to test.

intvarIf specified, will be set to 0 for no error; 1 otherwise.

Example

proc main string szFname = "WRITE.TXT"; Name of file to be opened. string szLine ; Line from file. integer Error ; Error created by read below.

if fopen 0 szFname WRITE ; Open file for write only. fgets 0 szLine ; 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." szFname endifendproc

See alsofclear, fclose, feof, fopen, fseek and rewind.

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

paramThe desired set command parameter.

datavarThe 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. The definition for the set commands, in Appendix A, "Set and Fetch Statements", includes all possible values for each command parameter.

Example

proc main string szCountryCode ; Country code for the entry. string szAreaCode ; Area code for the entry. string szNumber ; Phone number for the entry.

; Set the Dialing Directory entry and return the settings.

set dialentry access "DATASTORM" fetch dialentry countrycode szCountryCode fetch dialentry areacode szAreaCode

fetch dialentry phonenumber DATA szNumber

usermsg "%s (%s) %s" szCountryCode szAreaCode szNumber

endproc

CommentsASPECT 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 saved 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 11 groups that correspond to the parameters they affect:

ASPECTAffects overall script operation.

CAPTUREAffects capture file options.

COMPILERAffects compiler options.

CONNECTIONAffects connection options.

DIALDIRAffects the Dialing Directory options.

DIALENTRYAffects Dialing Directory entries or groups.

FAXAffects fax modem setup and control.

MODEMAffects data modem setup and control.

PHONECARDAffects phonecard options in Setup.

PORTAffects COM port setup.

PRINTAffects printer setup and control.

In addition, each protocol and each terminal emulation has its own set/fetch group. However, many of these options represent advanced settings which are not available for all terminals or protocols. For more information, see Appendix A, "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 Dialing 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.For more information, see Appendix A, "Set and Fetch Statements".

See alsosetup and set; "Set and Fetch Statements" in Appendix A.

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

idThe file id to be flushed.

Example

proc main string szFname = "CAPT.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 szFname 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." szFname

endifendproc

proc Done fflush 0 ; Make sure that everything's fclose 0 ; written to file before

exit ; closing it and exiting.endproc

CommentsIf the file was opened in READ mode, the buffer contents are cleared.In CREATE, WRITE or READ/WRITE 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 alsofclose, fclear and fopen.

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

idThe file id to access.

intvarWill be set to a character value if fgetc was successful; -1 otherwise.

Example

proc main string szFname = "codes.cap"; Name of file to be opened. string FName ; 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 szFname FDrive FDir FName FExt

strcat FName ".HEX" ; Append extension for output file. if fopen 0 szFname READ ; Open input file for read. if fopen 1 FName 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." FName endif

fclose 0 ; Close our input file. else errormsg "Couldn't open `"%s`" for input." szFname endifendproc

CommentsTo make sure 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 alsofgets, fopen, fputc, feof and fread.

fgets id strvarReads a string from the file corresponding to a given id into a variable.

idThe file id to access.

strvarThe string receiving the data.

Example

proc main string szName ; Name of file to read. string szLine ; Line from file.

if sdlginput "File Name" "Name:" szName if isfile szName ; Make sure file exists. if fopen 0 szName READ ; Open file for read. while not feof 0 ; Loop to end of file. fgets 0 szLine ; Get line from file. termwrites szLine endwhile fclose 0 ; Close the file.

endif else errormsg "File doesn't exist." endif endifendproc

CommentsThe 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 alsofgetc, fputs, feof, fread and fopen.

fileget filespec {ATTRIBUTE | DATE | TIME strvar} | {LTIME | SIZE longvar} Reports date, time, attributes and size for a given filespec.

filespecThe desired file.

ATTRIBUTE strvarstrvar will contain the attributes of the specified file.

DATE strvarstrvar will contain a date string reflecting the specified file's last update.

TIME strvarstrvar will contain a time string reflecting the specified file's last update.

LTIME longvarlongvar will contain a timeval, which can be converted to time/date string(s) using ltimestrs or ltimestring.

SIZE longvarWill contain the size in bytes of the specified file.

Example

proc main string szFname = "C:\IO.SYS"; Name of file to examine. string Attr ; Attributes for the file.

; Get and display the attributes for the file above.

fileget szFname ATTRIBUTE Attr usermsg "`"%s`" attributes are `"%s`"." szFname Attrendproc

CommentIf 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: 'R' for read-only, 'H' for hidden, 'S' for system, and 'A' for archive. A null string indicates that the file has no attributes.

Note: 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 alsofileset, findfirst, findnext, ltimestring and ltimestrs.

fileset filespec {ATTRIBUTE | DATE | TIME string} | {LTIME | SIZE long}Sets date, time, attributes and size for a given filespec.

filespecThe target filename.

ATTRIBUTE stringWill set the target file's attributes to the given value(s).

DATE stringWill set the target file's date stamp to the given value.

TIME stringWill set the target file's time stamp to the given value.

LTIME longWill set the target file's timeval to the given value.

SIZE longWill set the target file's size to the given value, truncating the file if applicable.

Example

proc main string szFname = "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 szFname ATTRIBUTE "h" fileget szFname ATTRIBUTE Attr usermsg "`"%s`" attributes are `"%s`"." szFname Attrendproc

CommentIf 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: '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.

Note: 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 alsofileget, findfirst, findnext and strsltime.

filetoclip BITMAP | METAFILE | TEXT filespecRetrieves the contents of a file and places the data in the clipboard.

BITMAP |METAFILE |TEXTSpecifies the filetype for the copy.

filespecThe file which will be copied to the clipboard; if no path is specified, the User Path is assumed.

ExampleSee examples for pastetext and cliptofile.

CommentsNote that the input file must be of the proper type for the retrieval to be successful - bitmaps usually carry the extension .BMP, while metafiles are usually identified with a .WMF extension.

See alsostrtoclip, cliptofile and pastetext.

fileview filespecDisplays a file in a modal dialog box.

filespecThe file to display; if no path is supplied, ASPECT will search for the file in the User Path.

Example

proc main string szFname ; String to contain file name.

if dir "*.txt" szFname ; Prompt user for a file name. fileview szFname ; If file chosen, display it. endifendproc

Commentsfileview should only be used with ASCII text files.

findfirst filespec [string]Locates a disk file using a specification you provide.

filespecThe 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.

stringAn 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 '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

For a more practical example, see findnext.

CommentsThe 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 alsofileget, fileset, findnext and strsltime; $FLTIME, $FSIZE, $FATTR, $FDATE, $FEXT, $FILENAME, $FNAME, $FTIME and $FILESPEC in Appendix B, "System Variables".

findnextLocates 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!" endifendproc

CommentsThe 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 alsofileget, fileset, findfirst and strsltime; $FLTIME, $FSIZE, $FATTR, $FDATE, $FEXT, $FILENAME, $FNAME, $FTIME and $FILESPEC in Appendix B, "System Variables".

finsblock id integerInserts a block of space into the specified file id at the current position in the file.

idThe id of the target file.

integerThe 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!" endifendproc

CommentsThe current file position remains unchanged after inserting the block. Thus, new data can be written directly following finsblock. if SUCCESS should be used to confirm that the block was inserted before the script attempts to write to the file, however.

See alsofdelblock.

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

intvarThe task id.

Example

proc main integer TaskId ; Id returned by FirstTask, NextTask. string szName ; Name of task.

firsttask TaskId ; Get the id of first task. taskname TaskId szName ; Get the name of task. termmsg "Task: %s`r`n" szName while nexttask TaskId ; Loop while id is not zero. taskname TaskId szName ; Get the name of task. termmsg "Task: %s`r`n" szName endwhileendproc

CommentsWindows 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.Ordering of tasks is not necessarily preserved between two firsttask commands.

See alsonexttask, taskactivate, taskexit, taskexists, taskname and taskwin; $TASK and $PWTASK in Appendix B, "System Variables".

flength id longvar Returns the file size of an open file.

idThe id of the target file.

longvarWill contain the length of the target file in bytes.

Example

proc main long Size; Holds the size of our file.

if fopen 0 "HOST.USR" READ; Open the HOST.USR file. flength 0 Size; Get the size of the file. usermsg "`"HOST.USR`" is %ld bytes long!" Size fclose 0; Close the HOST.USR file. else errormsg "Couldn't open `"HOST.USR`" file!" endifendproc

Commentsflength 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.