ascript4

ltimestrs timeval strvar strvarConverts a long value in system time format into two string variables representing date and time.

timevalThe timeval to convert.

strvarThe converted date.

strvarThe converted time.

Example

proc main string szDate, szTime ; Time and date strings.

; Convert long time into date and time, in text form, ; and display it on the status line.

ltimestrs $LTIME szDate szTime statmsg "%s %s" szDate szTimeendproc

CommentsThe string will be formatted based on the information contained within the Short Date and Time Format fields of the International section of the Windows Control Panel.

See alsoltimeints, ltimestring and strsltime; $LTIME in Appendix B, "System Variables".

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

longThe long value to convert.

strvarWill 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." szSizeendproc

See alsoatol, ftoa, itoa, strfmt and numtostr.

makepath strvar drive pathname filename extensionCreates a path and/or file specification from individual components.

strvarWill contain the created pathname.

driveA string, containing a drive letter.

pathnameThe path information to include in the pathname.

filenameThe filename to include in the result.

extensionThe extension to include in the result.

Example

proc main string szFileSpec ; Complete file specification. string szDrive ; Drive for file specification. string szPath ; Path for file specification. string szFile ; File for file specification. string szExt ; Extension for file spec.

; Set the elements of the file specification and create ; a full path with file name and extension.

szDrive = "C:\" ; Set drive to the C drive.

szPath = "PROWIN2" ; Set the path. szFile = "PW2" ; Set name of file. szExt = "EXE" ; Set extension of file.

makepath szFileSpec szDrive szPath szFile szExt usermsg "%s" szFileSpec ; Display the file spec.endproc

See alsoaddfilename, splitpath, getfilename and getpathname

mciexec stringExecutes a high-level multimedia command..

stringA 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

Commentsmciexec is used with multimedia commands like open, set, play and close to control a multimedia device (for example, a CD-ROM player). mciexec requires Multimedia Extension software or direct Windows multimedia support.

memalloc id memlengthAllocates a block of contiguous memory for use by an ASPECT script.

idA integer value which will be used to reference the allocated memory block.

memlengthAn integer whose value is treated as an unsigned value, specifying the size, in bytes, to be allocated.

Example

proc main integer nBytes = 255 ; Number of bytes to allocate.

if memalloc 0 nBytes ; Allocate memory and check for errors. usermsg "Memory successfully allocated!" memfree 0 ; Free the allocated memory. else errormsg "Couldn't allocate memory!" endifendproc

CommentsUse memavail to determine the amount of memory available for use; if SUCCESS can be used to test the results of the allocation.

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.

Note: The allocated memory block will be uninitialized; to be certain of its contents, use the memset command.

See alsomemavail, memfree, memrealloc, memread, memwrite and memset.

memavail longvarReturns the amount of contiguous free memory (or RAM) 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 alsomemalloc, memfree and memrealloc.

memchr id memindex character [intvar]Searches for the first occurrence of the specified character in an allocated memory block.

idThe id of the memory block to search.

memindexThe starting position of the search within the target memory block.

characterThe desired character value; an integer value from 0 to 255 inclusive.

intvarIf specified, 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 20 ; Allocate some memory. memwrite 0 0 "This is Bob's home." 20 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!" endifendproc

CommentsIf the desired character is not found memchr will return FAILURE; the intvar argument in that case will contain the number of characters from the starting point of the search to the end of the allocated block.

See alsomemalloc, memcmp, memgetc and memicmp.

memcmp id memindex id memindex memlength [intvar]Performs a byte-by-byte comparison of two memory locations.

idThe control id of an allocated memory block.

memindexThe starting point of the comparison in the first block. An integer value, equal to the number of bytes from the start of the block.


memindexThe starting point of the comparison in the second block. An integer value, equal to the number of bytes from the start of the block.

memlengthThe number of bytes to compare.

[intvar]If specified, 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 "Closer to the heart." 20 memwrite 1 0 "Closer to the shirt." 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." endifendproc

CommentsSimilar to the memcmp function in the 'C' language, ASPECT 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.Note that if the same id is specified for both memory block id's, memcmp will compare data within a single block.

See alsomemalloc, memicmp, memchr, memgetc, memmove, memputc, memread, memset and memwrite.

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

idThe id of the memory block to release.

ExampleSee example for memalloc.

See alsomemalloc and memrealloc.

memgetc id memindex intvarRetrieves a single character from a block of memory reserved by memalloc.

idThe id of the memory block to access.

memindexAn integer value, equal to the number of bytes from the start of the block, specifying the location of the character to be read.

intvarThe value read; it will be an integer ranging from 0 to 255 inclusive.

ExampleSee example for memputc.

See alsomemalloc, memputc and memread.

memicmp id memindex id memindex memlength [intvar]Performs a byte-by-byte, case-insensitive comparison of two memory locations.


memindexThe starting point of the comparison in the first block. An integer value, equal to the number of bytes from the start of the block.


memindexThe starting point of the comparison in the second block. An integer value, equal to the number of bytes from the start of the block.

memlengthThe number of bytes to compare.

[intvar]If specified, 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." endifendproc

CommentsSimilar to the memicmp function in the 'C' language, ASPECT 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.Note that if the same id is specified for both memory block id's, memicmp will compare data within a single block.

See alsomemalloc, memcmp, memset and stricmp.

memmove id memindex id memindex memlength

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

idThe destination memory block id.

memindexThe starting point of the memmove into the destination block. An integer value, equal to the number of bytes from the start of the block.

idThe source memory block id.

memindexThe starting point of the memmove from the source block. An integer value, equal to the number of bytes from the start of the block.

memlengthThe number of characters to move.

Example

proc main integer nBytes ; Number of bytes to allocate. string szText ; Text to move in memory.

szText = "Much ado, indeed." ; Assign text to string variable. strlen szText nBytes ; Get length of string.

if memalloc 0 nBytes ; Allocate first memory block. if memalloc 1 nBytes ; Allocate second memory block. memwrite 0 0 szText nBytes ; Write text into memory. memmove 1 0 0 0 nBytes ; Move text from first to second.

memread 1 0 szText nBytes ; Read text from memory. usermsg szText ; 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!" endifendproc

CommentsIf the source and destinations overlap, the source is copied before it is overwritten.To clear a memory location, use the memset command, below.

See alsomemalloc, memgetc, memset and memwrite.

memputc id memindex characterWrites a single character to a location within a memory block allocated by memalloc.


memindexAn integer value, equal to the number of bytes from the start of the block, specifying the location of the character to be written.

characterThe value to write, either a character constant or an integer ranging from 0 to 255 inclusive.

Example

proc main integer Num = 42 ; Integer to write to memory. integer HiByte, LoByte ; High byte and low byte of number.

if memalloc 0 2 ; Allocate space for integer. HiByte = Num >>>> 8 ; Shift bits right to get hi byte. LoByte = (Num <<<< 8) >>>> 8; Shift bits left / right to get lo byte. memputc 0 0 HiByte ; Write high byte into memory. memputc 0 1 LoByte ; Write low byte into memory. memgetc 0 0 HiByte ; Get hi byte of integer from memory.

memgetc 0 1 LoByte ; Get lo byte of integer from memory. HiByte <<<<= 8 ; Shift high byte to where it belongs. Num = HiByte + LoByte ; Put integer back together again. usermsg "%d" Num ; Display the integer. memfree 0 ; Free up allocated memory. else errormsg "Couldn't allocate memory for integer!" endifendproc

See alsomemcmp, memgetc, memputc, memread, memset and memwrite.

memread id memindex numvar | {strvar strlength}Reads a block of data from an allocated memory block.


memindexAn integer value, equal to the number of bytes from the start of the block, specifying the location of the data to be read.

numvarA float, integer, or long variable.

strvar strlengthA string variable, with a specified number of characters to be read.

ExampleSee example for memwrite.

CommentsASPECT automatically determines the number of bytes to be read if a numeric variable is specified for memread. An integer argument will cause 2 bytes to be read from the block; a long will read 4 bytes, and a float 8 bytes.

See alsomemalloc, memgetc and memwrite.

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

idThe id of the target memory block.

memlengthA 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 nBytes = 1 ; Number of bytes to allocate. string szText = "Flowers" ; String to write to memory.

if memalloc 0 nBytes ; Allocate memory, check for errors. strlen szText nBytes ; Oh wait. We need more space! if memrealloc 0 nBytes ; Reallocate memory for more space. memwrite 0 0 szText nBytes ; Write text to memory. else errormsg "Couldn't reallocate memory." endif

memfree 0 ; Free up our memory.

else

errormsg "Couldn't allocate memory!" endifendproc

CommentsIf the id of the block does not exist, that is, 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.

See alsomemalloc, memavail and memfree.

memset id memindex character memlengthInitializes a block of memory to a specified value.


memindexAn integer value, equal to the number of bytes from the start of the block, specifying the starting position of memset operation.

characterAn integer value from 0 to 255 inclusive specifying the value to set.

memlengthThe number of character positions to set.

Example

proc main integer nBytes = 30 ; Number of bytes to allocate.

if memalloc 0 nBytes ; Allocate memory to store text. memset 0 0 0 nBytes ; Clear bytes in the area to nulls. memfree 0 ; Free allocated memory. else errormsg "Couldn't allocate memory." endifendproc

Commentsmemset is useful in initializing a freshly memallocated block, or in resetting a block for new operations.

See alsomemalloc, memmove, memread and memwrite.

memsize id intvarReports the size of a memory block allocated with memalloc.


intvarThe size in bytes of the allocated block; the value represents an unsigned integer value.

Example

proc main integer nBytes ; Number of bytes allocated.

if memalloc 0 255 ; Allocate a block of memory. memsize 0 nBytes ; Get size of block 0. usermsg "Size of memory block is %d." nBytes memfree 0 ; Free the block of memory. else errormsg "Couldn't allocate memory." endifendproc

Commentsmemsize can be used to find the size of a block before read or write operations are performed.

See alsomemalloc, memavail, memfree and memrealloc.

memwrite id memindex number | {string strlength}Writes a block of data to an allocated memory block.


memindexAn integer value, equal to the number of bytes from the start of the block, specifying the starting position of memwrite operation.

numberA float, integer, or long constant or variable to be written.

string strlengthA string variable, with a specified number of characters to be written.

Example

proc main integer nBytes ; Number of bytes to allocate. string szText ; Text to write to / from memory.

szText = "Swirled Cheese." ; Assign text to string variable. strlen szText nBytes ; Get length of string.

if memalloc 0 nBytes ; Allocate memory to store text. memwrite 0 0 szText nBytes ; Write string to memory. memread 0 0 szText nBytes ; Read string from memory. usermsg szText ; Display text.

memfree 0 ; Free allocated memory. else errormsg "Couldn't allocate memory!" endifendproc

CommentsASPECT automatically determines the number of bytes to be written if a numeric constant or variable is specified for memwrite. An integer argument will cause 2 bytes to be written to the block; a long will write 4 bytes, and a float 8 bytes. A string writes the number of bytes specified in strlength.

See alsomemalloc, memputc, memset and memread.

menubar intvarCreates a new script menu bar.

intvarUse 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 menubar when all menu popups and menu items have been added to it.

Example

proc main string FileMenu[4] ; Items to appear on the file menu. integer hMenu, hFile ; Handles to the menu and popup. integer Event ; Menu event.

FileMenu[0] = "&New", FileMenu[1] = "&Open" FileMenu[2] = "&Save", FileMenu[3] = "&Auto Save"

menubar hMenu ; Create a menu bar and set handle. menupopup hMenu "&File" hFile ; Create a popup menu. menuitem hFile 1 FileMenu[0] ; Create menu items in file popup.

menuitem hFile 2 FileMenu[1] menuitem hFile 3 FileMenu[2] menuitem hFile 4 FileMenu[3]

menushow hMenu ; Show the menu bar. while 1 ; Loop forever. if (Event = $ASPMENU) != 0 switch Event ; Evaluate menu event. case 4 ; Auto Save item selected. menustate ASPMENU 4 Event if Event == 0 ; See if auto save is off. menucheck 4 ON ; Checkmark auto save.

else menucheck 4 OFF; Un-checkmark auto save. endif endcase default ; Default case. endcase endswitch endif endwhileendproc

CommentsAny number of menubars can be created from a script. When the script terminates, existing menu bars generated by a script will be destroyed automatically.menupopup and menuitem can be used to attach new items to PROCOMM PLUS's default menu bar - these items will be destroyed when the script that created them is terminated.

See alsomenupopup, menuitem and menushow; $PWMENUBAR in Appendix B, "System Variables".

menucheck integer OFF | ONPlaces or removes a check mark on a menuitem created by an ASPECT script.

integerThe menuitem to be checked or unchecked. This is the same value used in creating the menuitem.

ExampleSee example for menubar.CommentsA menuitem on the menubar itself cannot be checked.

If the menuitem was generated by an ASPECT script, menucheck will only work if the menuitems are currently displayed. PROCOMM PLUS's menuitems, on the other hand, can be affected whether they're displayed or not.

See alsomenubar and menuitem.

menuitem integer {integer string [string]} | SEPARATORAdds an item to a menu popup or menu bar.

integerThe integer value, previously returned from a menupopup or menubar command, identifying the menu upon which the item is placed. PROCOMM PLUS provides pre-defined ids for its popup menus (see below).

integerThe id value of the new menuitem. Valid ids can range from 1 up to 299; this value is returned into $ASPMENU when the menuitem is selected by the user.

stringThe menuitem text.

[string]If specified, will be displayed on the status line as help text whenever the menuitem is highlighted.

separatorAdds a menu separation line. A separator does not require an id.

ExampleSee example for menubar.CommentsThe id value of the menu item is returned in $ASPMENU when the item is selected.PROCOMM PLUS's valid reserved menu popup id values are:

Menu ID Associated Popup Menu 0 File

1 Edit2 Setup3 Online4 Fax5 Scripts6 Tools7 Help

menuitem allows an ampersand ("&") to precede the "accelerator" character on a menu - this indicates that the user can hold down the Alt key and press this character to select the item from the keyboard. 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.

See alsodisable, enable, menubar, menucheck, menupopup, menushow, menustate, menuselect and when $ASPMENU; $ASPMENU in Appendix B, "System Variables".

menupopup integer string [string] intvarAdds a popup menu to an existing popup menu or menubar.

integerIdentifies the menu or menus to which the new menu will be added. This value is taken from a previous menupopup or menubar command; the $PWMENUBAR system variable contains the menu bar id currently used by PROCOMM PLUS. Several popup menu ids are predefined by PROCOMM PLUS that may also be used; see menuitem for details.

stringThe menu text.

[string]If specified, will be displayed on the PROCOMM PLUS status line as help text.

intvarThe id value of the new menu.

ExampleSee example for menubar.

Comments"Nested" menus can be built by adding multiple popup menus atop one another - simply use the integer variable returned from menupopup, or one of PROCOMM PLUS's predefined menu popup ids as the integer value when creating nested popups.menupopup allows an ampersand ("&") to precede the "accelerator" character on a menu - this indicates that the user can hold down the Alt key and press this character to select the item from the keyboard. 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.

See alsomenubar, menuitem and menushow; $PWMENUBAR in Appendix B, "System Variables".

menuselect ASPMENU | PWMENU integerSelects a PROCOMM PLUS or ASPECT menuitem.

ASPMENU | PWMENUSpecifies whether the menuitem originates from a script or from PROCOMM PLUS itself.

integerThe id of the menuitem to be selected.

Example

#include "menuids.inc" ; Include file of menu macros.

proc main menuselect PWMENU _SETUP ; Select setup window option.endproc

CommentsPROCOMM PLUS's menu items can be selected even when a different menu bar is displayed, but menuitems created by an ASPECT script must be displayed in order to be selected. A menu item cannot be selected when it is disabled.PROCOMM PLUS's main window must have the input focus for menuselect to be used.

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 alsomenuitem and menucheck.

menushow integer|PWMENUDisplays the menu bar corresponding to the specified menu bar id value.

integerIdentifies 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 menubar will be removed.

PWMENUIf specified, the default PROCOMM PLUS menubar will be restored.

ExampleSee example for menubar.

CommentsUse this command to display updates to the current menu bar.

See alsomenubar, menuitem, menupopup and when $ASPMENU; $ASPMENU in Appendix B, "System Variables".

menustate ASPMENU | PWMENU integer intvarReports the state of a PROCOMM PLUS or ASPECT menu item.

ASPMENU | PWMENUSpecifies whether the menuitem originates from a script or from PROCOMM PLUS itself.

integerThe id of the menuitem to be tested; a variable or constant.

intvarA bitflag value, with the following possible values: 0x01 (grayed), 0x02 (disabled) or 0x04 (checked).

Example

#include "menuids.inc" ; Include file of menu macros.

proc main integer State ; State of menu item.

menustate PWMENU _ICOLABELS State if State == 0 ; See if Icon Labels are off. usermsg "Icon Labels are OFF." else usermsg "Icon Labels are ON." endifendproc

CommentsIf the menuitem was generated by an ASPECT script, menustate will only work if the menuitem is currently displayed. PROCOMM PLUS's menuitems, on the other hand, can be tested whether they're displayed or not.When a menuitem is grayed, it is disabled by default.

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 alsomenuitem, menubar, menupopup, menucheck and menuselect.

metafile id left top width height filespec

metafile id left top width height filespec BACKGROUND | USERWINDisplays a Windows metafile (.WMF) 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:

idA unique integer constant value given to the metafile. Used by the dlgupdate command to refresh the metafile.

left topInteger 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 (DBUs). For more information on DBUs, see "User Window and Dialog Units" in Chapter 2 of this manual.

width heightThe metafile display size integer constants. Values are expressed in DBUs.

filespecString constant or global variable specifying the name of the metafile to display. If a path is not given, the default Aspect path will be used.

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 alsobitmap, dialogbox, dlgevent, dlgupdate, icon, and iconbutton.

User Window form:

metafile id left top width height filespec BACKGROUND | USERWIN

idA unique integer value given to each metafile. Used by the objremove command to remove the metafile.

left topInteger 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 UWUs; see "User Window and Dialog Units" in Chapter 2 for more information.

width heightThe metafile display size in UWUs.

filespecString 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 will be used.

USERWIN | BACKGROUNDSpecify 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 ; "bigdog.wmf".

uwincreate FULL SCREEN 100 255 255 255 BITMAP metafile 1 500 500 9000 9000 "bigdog.wmf" USERWIN uwinpaint ; Paint the user window.

pause 5 ; Show off the metafile. uwinremove ; Destroy the user window.endproc

CommentThe User window must exist before a metafile can be displayed and 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 alsouwincreate, uwinpaint, objpaint, objcoord, objpointid, objremove, metafilebkg, bitmap, hotspot, icon, iconbutton, pushbutton, dllobject and when $OBJECT; $OBJECT in Appendix B, "System Variables".

metafilebkg CENTER|LEFT|RIGHT CENTER|TOP|BOTTOM SCALE|EXACT filespecPlaces a Windows metafile background in the User window.

CENTER |LEFT |RIGHTThe 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 |BOTTOMThe vertical position of the metafile background with respect to the User window.

SCALE|EXACTDetermines 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 (or "isotropic"), 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.

filespecThe name of the metafile to display as the background. If a path is not specified, the current Aspect Path will be used.

Example

proc main uwincreate FULL SCREEN 100 255 255 255 BITMAP metafilebkg CENTER CENTER SCALE "missouri.wmf" uwinpaint ; Paint the user window.

pause 5 ; Show off the background. uwinremove ; Destroy the user window.endproc

See alsobitmapbkg, uwincreate, uwinpaint, uwinremove and metafile.

metakey ALT | ALTSHIFT | ALTCTRL | ALTCTRLSHIFT integerExecutes the specified Meta key.

integerAn integer value from 0 to 9, designating the metakey to execute.

Example

proc main metakey ALTCTRLSHIFT 1 ; Execute the ALTCTRLSHIFT 1 meta key.endproc

CommentsUse the set metakeyfile command to load individual keyboard metakey files. Issue the statement set aspect spawn ON before the metakey command if the desired meta key is defined to run a script file.set metakeys can be used to control display of the metakeys.

See alsotermkey; set metakeyfile, set metakeys and set aspect spawn in Appendix A, "Set and Fetch Statements".

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

pathnameThe 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 szFname = "DEL.ME" ; File to create in temporary dir.

mkdir NwDir ; Create new directory. chdir NwDir ; Change to the new directory.

if fopen 0 szFname CREATE ; Create the temporary file. fputs 0 "Temporary" ; Put something in temporary file. fclose 0 ; Close the file. else errormsg "Couldn't create `"%s`"." szFname

endifendproc

See alsochdir, getdir and rmdir; $USERPATH in Appendix B, "System Variables"; set aspect path in Appendix A, "Set and Fetch Statements".

monthstr integer strvar [SHORT]Returns the name of the specified month.

integerA value from 1 to 12.

strvarWill contain the name of the month.

SHORTIf 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 alsoltimeints, ltimestring, ltimestrs and weekdaystr; $LTIME in Appendix B, "System Variables".

mspause integerPauses 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. endwhileendproc

CommentsUnlike the pause command, mspause can't be aborted with the Ctrl-Break key; the delay has a maximum length of 1000 milliseconds. The number of milliseconds specified is subject to a 55 millisecond granularity.

See alsopause.

nexttask intvarReturns subsequent in tasks in the Windows Task List after the execution of a firsttask command.

intvarThe task id.

Example

See example for firsttask.

CommentsWindows ASPECT returns 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 alsofirsttask, taskname and taskpath; $NUMTASKS and $TASK in Appendix B, "System Variables".

nullstr string [intvar]Tests a string variable for the null condition (no contents).

stringThe string to test.

intvarIf specified, will be updated to 1 (the string is null) or 0 (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 value!^M^J" endifendproc

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

numtostr number strvar [integer]Converts a numeric value to a string.

numberA float, integer or long value to convert.

strvar

The result of the conversion.

integerIf 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 szBinary ; Binary form of number.

numtostr Number szBinary 2 ; Convert number to base 2. usermsg "%s" szBinary ; Display the binary number.endproc

CommentsThe optional base type is not allowed for floating-point conversions; the default base is 10.

See alsoftoa, itoa, ltoa, strfmt and strtonum.

objcoord id intvar intvar UWUS | PIXELSReturns the location coordinates of a User window object.

idThe control id given to the target object when it was defined.

intvar intvarWill 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.

UWUSIf 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 and Dialog Units" in Chapter 2.

PIXELSIf 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 nTop nLeft; Move object down screen. endwhile

uwinremove; Remove the user window.

endproc

CommentsThe 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 alsoobjmove; $LMOUSEX, $LMOUSEY, $RMOUSEX and $RMOUSEY in Appendix B, "System Variables".

objhide startid [endid]Hides a User window object, or a range of objects.

startidThe id of the target object.

endidIf 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 below.

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

Commentsobjhide 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 alsoobjshow.

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.

idThe control id given to the target object when it was defined.

left topInteger 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.

UWUSIf are 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 and Dialog Units" in Chapter 2.

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

NOPAINTAn 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 "" "zoom.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

CommentsBy 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 (such as when the window is brought to the foreground from behind another window), 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 alsouwincreate, objhide, objpaint and objremove.

objpaint [startid][endid]Updates the User window and some or all of the objects it contains.

startidThe id of the window object to paint.

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

ExampleSee example for objmove.

Commentsobjpaint should be used to update the display after any change to a User window object.

See alsouwincreate, objcoord, objpointid, objhide, objmove, objshow, and objremove.

objpointid integer integer intvar UWUS | PIXELSReturns the object id, if any, of an object located at a specified point.

integerThe X-User window coordinate desired.

integerThe Y-User window coordinate desired.

intvarWill be updated with the object id of an object located at the given coordinates.

UWUSIf 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 and Dialog Units" in Chapter 2.

PIXELSIf 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 "" "zoom.bmp" 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

Commentsobjpointid will return FAILURE if the specified coordinates are not contained by a User window object, or if the point is contained by a hidden object.

See alsouwincreate, objcoord, objpaint, objhide, objmove, objshow, and objremove.

objremove startid [endid]Removes one or more User window objects.

startid

The id of the window object to remove.

endidIf 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

CommentsAn objpaint command must be issued to update the display after removing objects.

See alsouwincreate, objcoord, objpointid, objhide, objmove, objshow, objremove, objpaint, icon, iconbutton, metafile, bitmap, pushbutton, bitmapbkg, dllobject, metafilebkg, and hotspot.

objshow startid [endid]Displays an object previously hidden with objhide.

startidThe id of the window object to show.

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

ExampleSee example for objhide.

Commentsobjshow 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 alsouwincreate, objcoord, objpointid, objhide, objmove, objpaint and objremove.

oemtoansi {character intvar} | {string strvar [strlength]}Converts an OEM character or string to their respective ANSI character equivalents.

characterThe character to convert.

intvarWill contain the OEM character's ANSI equivalent.

stringThe string to be converted.

strvarWill contain the converted string.

strlengthAn optional integer, indicating the number of characters to convert in the target string. If 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 alsooemtokey and ansitooem; set aspect codepage in Appendix A, "Set and Fetch Statements".

oemtokey character intvarConverts an OEM character to its key value.

characterThe character to convert.

intvarWill contain the OEM character's keyboard equivalent.

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

Commentsoemtokey reports SUCCESS or FAILURE based on the outcome of the conversion.

See alsoansitokey, keytooem and oemtoansi; set aspect codepage in Appendix A, "Set and Fetch Statements".

param datatype name[,name]...Defines a parameter variable in a procedure or function.

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

nameThe name of the parameter variable. It will only be valid within the function or procedure in which it appears, and 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 : integerparam 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

Commentsparam 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 on using parameter variables, see "Parameter Variables" in Chapter 2 of this manual.

See alsofunc, proc, integer, float, long, string and call.

pastetextSends text in the Windows Clipboard to the active COM 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 COM port.endproc

CommentsWhen pastetext is executed, the Clipboard data must be text.

See alsofiletoclip, strtoclip, cliptostr and cliptofile.

pause integer | FOREVERHalts script-file execution for the specified number of seconds.

integerA positive integer value indicating the number of seconds to pause execution.

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

CommentsUnlike the mspause command, pause can be aborted with the Ctrl-Break key. This command can be tested with the if SUCCESS and if FAILURE statements; FAILURE is set if pause was terminated by the user pressing the Ctrl-Break key.Any active when commands will still "fire" while the pause command is executing.

Note: The pause FOREVER command will yield processing time to other applications.

See alsomspause and when elapsed.

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 a Windows ASPECT script using the pksend statement.

txtimeoutThe timeout value in seconds for transmitted packets.

rxtimeoutThe timeout value in seconds for received packets.

ExampleSee example for pksend.

CommentsFAILURE is set if packet transfer mode was not successfully initiated - for example, if your script attempts to enter packet mode during a protocol file transfer. Additional SUCCESS and FAILURE information can be obtained from the $PKSEND and $PKRECV.

See alsopksend, pkrecv and when; $PKSEND and $PKRECV in Appendix B, "System Variables".

pkrecv intvar strvar intvar [rxtimeout]Receives an error-free packet from another PC running a Windows ASPECT script that has issued a pksend statement.

intvarAn integer variable assigned after the packet has been successfully received; its 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.

strvarThe data packet sent by the pksend statement after it is successfully received. The packet may include binary data.

intvarThe number of received bytes in this packet. Valid values range from 0 to 256.

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

ExampleSee example for pksend.

Commentspksend 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; the global variable $PKRECV can also be tested to determine the status. The values for $PKRECV are:

0 - packet not received or idle (default state)1 - packet received successfully2 - timeout occurred, packet not received3 - errors occurred, packet not received

See alsopkmode, pksend and when; $PKRECV in Appendix B, "System Variables".

pksend integer string strlength [txtimeout]Sends an error-free packet to another PC running a Windows ASPECT script.

integerThis value can be used as an identifier for the contents of the packet - or for any other purpose; it has a valid range of 0 to 255. This value is available as an integer variable from the pkrecv command after the packet has been successfully received.

stringThe data to be sent in the packet. Raw data may be included.

strlengthDetermines the number of bytes to send in this packet.

txtimeoutAn 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

; The following two scripts depict what two scripts may look like when; employing the use of the PKSEND and PKRECV commands. PKSEND and PKRECV

; can only be used between two copies of PROCOMM PLUS.

; Sending script.

proc main string szFileName ; Name of file to send.

pkmode ON 60 60 ; Set packet send and receive on. sdlgfopen "PKSEND" "*.*" szFileName ; Get name of file to transfer. if isfile szFileName ; Make sure file exists. SendPuppy( szFileName ) ; Call the send routine to send file.

else errormsg "File not transferred!" endifendproc

proc SendPuppyparam string szFileName ; Name of file to send. string szLine ; Line from file. integer NumChars ; Number of characters read.

if fopen 0 szFileName 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 szLine 255 NumChars if ! SendPacket( szLine, 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`"." szFileName endifendproc

func SendPacket : integerparam string szLine ; 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 szLine 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 szFileName ; Name of file to get.

pkmode ON 60 60 ; Set packet send and receive on. sdlgfopen "PKRECV" "*.*" szFileName ; Get name of file to transfer. if not isfile szFileName; Make sure file doesn't exist. GetPuppy( szFileName ) ; Call the get routine to send file. else errormsg "File not transferred!" endifendproc

proc GetPuppyparam string szFname ; Name of file to get. integer nType, Len ; Type of packet and length.

integer Status ; Status of packet receive. integer Errors = 0 ; Errors received during transfer. string szLine ; Line from file.

if fopen 0 szFname CREATE ; Open and create file. while 1 ; Loop until exitwhile. if (Status == $PKRECV) if Status == 1 ; Packet received successfully. pkrecv nType szLine Len if strncmp szLine "[Done]" 6 exitwhile endif fwrite 0 szLine 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`"." szFname endif

endproc

CommentsAfter 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:

0 - packet send in progress or idle (default state)1 - packet sent successfully2 - timeout occurred, packet not sent3 - errors occurred, packet not sent4 - packet send canceled by receiver, packet not sent

See alsopkmode, pkrecv and when; $PKSEND in Appendix B, "System Variables".

playback OFF|filespecPlays back a Capture file or stops a playback currently in progress.

OFFAborts the playback of a Capture file in progress.

filespecThe Capture file to be played back.

Example

proc main string szName ; Name of file to play back.

if sdlginput "File Playback" "Name:" szName if not nullstr szName ; Make sure file isn't null. playback szName ; Play back the chosen file. else

errormsg "No file entered!" endif endifendproc

CommentsIf 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 alsoset aspect rxdata in Appendix A, "Set and Fetch Statements"; $PLAYBACK in Appendix B, "System Variables"

printalign LEFT|CENTER|RIGHTDetermines how text will be positioned when sent to the printer with the printstr and printchar commands; possible choices are left-justified, right-justified or centered text.

ExampleSee example for printer.

CommentsThe justification stays in effect until the next printalign statement is executed.LEFT alignment must be set whenever the printtabstr command is used.

See alsoprinter, printattr, printmargin, printstr, printchar, printtabstr, printtabs and printfont; the set print command family in Appendix A, "Set and Fetch Statements".

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.

NORMALSets or resets the current printer font to normal character attributes.

BOLDSets the current printer font to bold character attributes.

ITALICSets the current printer font to italic character attributes.

UNDERLINESets the current printer font to underline character attributes.


CommentsThe attributes stay in effect until the next printattr statement is executed. NORMAL removes any previously set attributes.

See alsoprinter, printmargin, printstr, printchar, printtabstr, printtabs and printfont; the set print command family in Appendix A, "Set and Fetch Statements".

printcapture OFF |ONRoutes 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. endwhile printcapture OFF; Turn off the print device.endproc

Commentsprintcapture sends characters to the current printer specified by the File menu Printer Setup command or the set print device script command.

See alsocapture, snapshot and sbsave; the set print command family in Appendix A, "Set and Fetch Statements".

printchar characterPrints a character on the "open" printer at the current position.


CommentsA 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 the description of the printer command.

See alsoprinter, printtabstr and printstr.

printer {OPEN[RAW]}|CLOSE|CANCELOpens the current printer for any of the print command family.

OPENActivates the Windows printer currently specified under the File menu Printer Setup command. 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.

RAWIf 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 does not support a "pass-through" mode (a Windows driver limitation), PROCOMM PLUS will attempt a best-fit output mode.

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

CANCELEnds a printing session and deletes any outstanding text to be printed.

Example

proc main string szText ; Text string to print.

szText = "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 szText ; Make sure text fits. printstr szText ; 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

CommentsA printer must first be opened before you issue any print statements. The parameters that are set using the File Menu Printer Setup command 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, printstr.

See alsoprintalign, printattr, printfont, printmargin, printtabs, printfit, printchar, printstr and printtabstr; the set print command family in Appendix A, "Set and Fetch Statements".

printfit string [strlength]Determines if a string will print on the current page.

stringThe string to test.

strlengthThe length of the test string. If strlength is not provided, a null-terminated string is assumed and its length is determined automatically.


CommentsIn essence, printfit operates the same as printstr except 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 alsoprinter, printstr and printtabstr; the set print command family in Appendix A, "Set and Fetch Statements".

printfont font size Selects a new printer font for subsequent printchar, printtabstr or printstr commands.

fontA string specifying the name of the font to use.

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


CommentsYou can preview the available fonts and sizes for any installed printer by viewing them in the Printer Fonts section of the PROCOMM PLUS Printer Setup dialog; select the File menu Printer Setup command to display this dialog.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.

See alsoprinter, printalign, printmargin, printtabs, printstr, printchar, printtabstr and printattr.

printmargin left [right [top [bottom]]]Determines the page margins for data printed from PROCOMM PLUS.

leftSpecifies the left margin in inches; a float value.

rightSpecifies the right margin in inches; a float value.

topSpecifies the top margin in inches; a float value.

bottomSpecifies the bottom margin in inches; a float value.


CommentsIf 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 and printmargin will set the FAILURE flag. 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.

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 alsoprinter, printattr, printalign, printfont and printtabs; the set print command family in Appendix A, "Set and Fetch Statements".

printstr string [strlength]Sends a specified string to the open printer.

stringThe text string to send to the printer.

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


Commentsprintstr "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 refer to the description of the printer command.

See alsoprinter, printchar and printtabstr; and the set print command family in Appendix A, "Set and Fetch Statements".

printtabs CLEAR | float [float...]}Determines the tab positions for the strings printed with the printtabstr command.

CLEARClears 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


CommentsThe 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.This statement 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 alsoprinter, printtabstr, printalign, printmargin, printstr and printattr.

printtabstr string [strlength]Prints a line of text, expanding tabs to the positions set with the printtabs command.

stringThe text to print.

strlengthIf the optional strlength parameter is not provided, a null-terminated string is assumed and its length is determined automatically.


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

Note: 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 alsoprinter, printchar, printstr and printtabs; the set print command family in Appendix A, "Set and Fetch Statements".

proc nameMarks the beginning of a procedure block.

Example

proc main integer Area ; Integer to contain area. integer Diameter ; Integer to contain diameter.

Diameter = 8 ; Initialize Diameter to a value and get ; area of circle. CircleArea( &Area, Diameter ) usermsg "%d" Area ; Display approx area of circle.endproc

proc CircleAreaparam 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

CommentsEach 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).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 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.

Note: The shortened form of procedure calls is highly recommended; it is shorter, just as readable, and less verbose. Also, future versions of ASPECT may require it.

See alsocall, func, param, return, setjmp, longjmp and endproc; the "Procedures and Functions" section in Chapter 2 of this manual.

profilerd filespec string string strvar|intvarReads a specified item value from any portion of a specified Windows .INI disk file.

filespecThe name of the .INI file to reference.

stringThe name of the topic containing the desired item.

stringThe item name containing the desired value.

strvar|intvarThe 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

CommentsIf the name of the topic or item does not exist in the target .INI file, the string variable will be null; the integer variable will equal -1. If the item is being stored into an integer variable, but the item does not contain numeric data, then 0 will be assigned.

See alsoprofilewr.

profilewr filespec string string string|integerWrites a specified item value to any portion of a specified Windows .INI disk file.

filespecThe name of the target .INI file.

stringThe name of the topic containing the desired item.

stringThe item name.

string|integerThe data to be written.

Example

proc main string IniFile = "PW2.INI" ; .INI file to write info to.

; The following command writes a new section to the ; PW2.INI file called "Extra Stuff". Under the new ; section, it writes "Temp = 5".

profilewr IniFile "Extra Stuff" "Temp" 5endproc

See alsoprofilerd.

pushbutton id left top width height label [OK | CANCEL] [DEFAULT]pushbutton id left top width height label USERWIN | BACKGROUNDPlaces a standard pushbutton control within a Windows 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:

idThe control value for the pushbutton; this value is reported by dlgevent when the button is selected by the user. An integer constant.

left topLocation of the icon from the top left corner of the dialog box. Values are integer constants in Dialog Box Units (DBUs). For more information on DBUs, see "User Window and Dialog Box Units" in Chapter 2.

width heightInteger constants representing the size of the button in DBUs.

labelA global 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.

OKThe dialog box is removed when an OK pushbutton is pressed. Changes made to file-related controls will be saved to disk.

CANCELThe dialog box is removed when a CANCEL pushbutton is pressed; any changes made to file-related controls will not be saved.

DEFAULTSpecifies that the pushbutton is to be selected when the Enter key is pressed and no other pushbutton has the input focus, or when a listbox, flistbox, combobox, fcombobox or dirlistbox item is double-clicked. Note that only a single pushbutton or iconbutton can be named as a default in a dialog box.

Example

proc main integer Event ; Dialog box event.

dialogbox 0 0 0 100 50 11 "Pushbutton 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 alsodialogbox, enable, disable, iconbutton, dlgevent and dlgupdate.

User window format:

pushbutton id left top width height label USERWIN | BACKGROUND

idA unique integer value given to the button. The value is assigned to $OBJECT when the button has been selected by the user and is used by the objremove command to remove the button.

left topInteger 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 (UWUs).

width heightThe size of the button in UWUs.

labelA 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 | USERWINSpecify 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 9000 9000 "&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 ; Pushbutton chosen. usermsg "Good-bye!"

exitwhile ; Exit the while loop.

endcase endswitch endif endwhile uwinremove ; Remove the user window.endproc

CommentsA User window must exist before pushbuttons of the "User window format" can be placed and a uwinpaint command must be issued to display User window changes.

See alsouwincreate, uwinpaint, objcoord, objpointid, objpaint, objremove, hotspot, icon, iconbutton, dllobject, bitmap and metafile; $OBJECT in Appendix B, "System Variables".

putenv stringAdds or changes an environment variable definition.

stringA string containing an environment variable and setting. For example, "VARIABLE=TRUE".

Example

proc main string szString ; String to put into environment.

szString = "Smiles = Good" ; Assign a value to string variable. putenv szString ; Put string into the environment.endproc

CommentsEnvironment variables can be used to pass information from one script to another, or from PROCOMM PLUS to another application.This command can be tested with the if SUCCESS and if FAILURE statements to determine whether the environment modification was successful.

See alsogetenv.

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 endwhileendproc

proc Done pwexit ; Close PROCOMM PLUS.endproc

Commentspwexit will terminate both the script and PROCOMM PLUS.

See alsoexit, exitwindows, halt, taskexit and winclose.

pwtitlebar {string [PERMANENT]}| RESTORESpecifies the text to display in the PROCOMM PLUS program title bar.

stringThe title text - a maximum of the first 64 characters of this string can be displayed.

PERMANENTIf specified, will cause the new titlebar information to remain after the script has terminated.

RESTOREIf specified, the title bar will be restored to its value prior to the last use of the pwtitlebar command with the PERMANENT keyword.

Example

proc main string szTitle ; New title for PROCOMM PLUS.

; Display the name of the currently executing script file in the title bar for PROCOMM PLUS.

strfmt szTitle "PROCOMM PLUS - %s" $SCRIPTFILE pwtitlebar szTitle ; Change PROCOMM PLUS's title. pause 5 ; Show off the change.endproc

CommentsThe previous title bar value is saved whenever pwtitlebar is executed with a string, but without the PERMANENT keyword. If there was no previous occurrence of pwtitlebar, or if PERMANENT was specified in the previous occurrence, then pwtitlebar RESTORE will restore the original default value of the PROCOMM PLUS title bar.Once the pwtitlebar command is executed with either the PERMANENT or RESTORE keyword, any previously saved title bar value will be discarded. When all scripts have terminated, the title bar will be automatically restored to the saved value, if any.

Changes to the title bar will also be displayed when PROCOMM PLUS is minimized.

See alsoThe $TITLEBAR and $PWTITLEBAR in Appendix B, "System Variables".

ascript4

Documents

string szfile file

string szsize size of

string cmnd

string variables

string wav

string szpath path

ascii string

string szext extension