The DESQview Toolkit Version 1.3 by Gary Chanson (C) 1994 The DESQview Toolkit is Copyright 1994 by Gary Chanson and Starquest Systems. No restrictions are placed on the non-commercial use of this set of programs. These programs and their documentation may be copied and re-distributed provided that they are not changed and no fee is charged for them. An exception is granted to not-for-profit user's groups, which are authorized to charge a nominal fee for materials and handling. Starquest Systems and Gary Chanson assume no liability for damages caused by the use of these programs. DVToolKIT is a set of DESQview (tm) specific utilities which give command line access to many of the functions available thru the DESQview API. The set includes: APPNUM Returns the window number of the current task. DESQ Pops up the DV main menu and sends a string to it. DVM Sends commands thru the DV window manager. FRAME Turns window frames on or off. JUSTIFY Turns cursor justification on or off. KILL Terminates the specified task. MAILBOX Creates, frees and assigns names to mailboxes. MAILBOX.SHP Shared program which assigns a name to mailbox. MESSAGES Returns the pending message count of a mailbox. READMAIL Reads a message from a mailbox. SENDKBD Sends a string to the keyboard of a task. SENDMAIL Sends a string to the mailbox of a task. SOUND Generates tones from the PC's speaker. STATUS Returns the status of the last mailbox read. SWITCH Script enhancement - switches to or runs a program. TITLE Assigns a title to a window. WHOIS Returns the handle of a task. WINDOW Sets the size and position of a window. ZOOM Zooms the foreground window. Each of these programs responds to the -? option switch with a brief help screen. ======================================================================= APPNUM APPNUM returns the window number of the current DESQview task. This is also the index number of this task in the DV "Open window" menu. By default, this utility sends its output to STDOUT which is normally the screen. DOS output redirection can be used to send its output to a file. If the -E option is used, the output will be stored in the environment variable %APPNUM. If the -P option is used, the window number is added to the PROMPT environment variable and will be displayed as part of the prompt in this window. Usage: APPNUM [options] Options: -E returns window number as Environment variable %APPNUM -P add to DOS Prompt -Q Quiet mode ======================================================================= DESQ DESQ pops up the DESQview main menu and sends the specified string as input. This simulates the operator pressing the DESQ key and typing in the specified string. Embedded commands in the form `&' can send any arbitrary key code. may be any 16 bit integer of which the low order byte is the ASCII code and the high order byte is the SCAN code. Numbers prefaced with `$' are assumed to be Hex. To send a `&' character, replace it with `&&'. Note that actions initiated on the menu will act on the current foreground window. Execution from a background task may produce un-expected results. Usage: DESQ [options] string Options: -C Close window -H Hex -L pop up Learn menu -N Next window -Q Quiet mode &n1 any code ======================================================================= DVManager DVManager translates a series of window commands into a DESQview window manager stream and sends it to the default window of the specified task. If no task is specified, the stream will be sent to the default window of the current task. Usage: DVM [options] command command(parameters) ... Options: -Tname destination Task name -Thandle destination Task handle (as returned by WHOIS) -Q Quiet mode Commands: ALLOW EXTEND PASTE UP ASIDE FORE POSITION VIEWPORT BACK FRAME REGION VIRTUAL CANCEL HIDE RIGHT WINDOW COLOR LEFT RUNS [BOTTOM] CURSOR MAXSIZE TITLE [HIDE] DISALLOW MINSIZE TOP [TOP] DOWN ORPHAN UNHIDE [UNHIDE] ECHO ALLOW (list) close,hide,suspend,main,switch,open,quit ASIDE suspend task and hides its window BACK force task to background CANCEL cancel operation, remove DV menu, go to topmost process COLOR (n1) set current color CURSOR (x,y) set cursor position. Upper left corner of window is 0,0 DISALLOW (list) close,hide,suspend,main,switch,open,quit DOWN (x,y,wide,long) scroll down the region from x,y to wide,long ECHO (string) display string EXTEND (yes/no) allow window frame to extend beyond screen FORE force task to foreground FRAME (on/off) enable/disable frame around window HIDE hide window LEFT (x,y,wide,long) scroll left the region from x,y to wide,long MAXSIZE (x,y) set maximum size of physical window MINSIZE (x,y) set minimum size of physical window ORPHAN orphan window POSITION (x,y) set position of physical window REGION (x,y) set scrolling region PASTE orphan window and give to system as paste data RIGHT (x,y,wide,long) scroll right the region from x,y to wide,long RUNS (yes/no) enables/disables running in the background TITLE (name) set window title. This string is displayed in the window frame and on the "switch" menu. TOP make window top in system UNHIDE unhide window UP (x,y,wide,long) scroll up the region from x,y to wide,long VIEWPORT (x,y) set position of viewport within window VIRTUAL (x,y) set size of virtual screen WINDOW (x,y,wide,long) set size and position of physical window [BOTTOM] make window bottom in process [HIDE] hide all window of process [TOP] make window top in process [UNHIDE] unhide all window of process ALLOW, DISALLOW commands: CLOSE close window HIDE hide window MAIN DV main menu OPEN open window menu QUIT quit DV SCISSORS scissors menu SUSPEND suspend task SWITCH switch windows menu ======================================================================= FRAME FRAME controls the display of a frame around the default window of the specified task. If no task is specified, the current task is assumed. A frame can be displayed around a window when the borders of the window are within the displayable area of the screen. The windows of the current task will have a double border and the windows all other tasks will have a single border. Usage: FRAME [options] on FRAME [options] off Options: -Q Quiet mode -Tname name of Task owning window -Thandle handle of Task owning window (as returned by WHOIS) ======================================================================= JUSTIFY JUSTIFY turns window justification on or off for the default window of the current task. With justification on, the position of the viewport of a window (the portion of the window actually displayed) moves so that the cursor is always within the window. With justification off, the position of the viewport remains stationary even if the cursor moves out of it. Optional parameters X and Y control the position of the viewport relative to its window. Usage: JUSTIFY off [x,y] JUSTIFY on Options: -Q Quiet mode ======================================================================= KILL KILL terminates the specified task. The task name must first be assigned to the default mailbox of the task using SPAWN with the -A option or MAILBOX. KILL can be used on any task including the task it is called from. Usage: KILL [options] task Options: -A Awaken -Q Quiet mode -R Restart -S Suspend -T Terminate ======================================================================= MAILBOX MAILBOX creates, frees and assigns names to mailboxes. New mailboxes are the property of the current task, and will be freed when it terminates. If no task is specified, the default mailbox of the current task is named. This identifier is used by other utilities to obtain the handle of this task for inter-task communications. Mailboxes can be used to exchange messages between tasks and as semaphores to control program access and flow. Usage: MAILBOX [options] name Options: -C Conditional mode (only if un-named) - requires v2.5+ -E returns name as Environment variable %MAILBOX - req v2.5+ -F Free mailbox -N create New mailbox in current task -Q Quiet mode -S Show name - requires v2.5+ -Tname name of mailbox or Task -Thandle handle of mailbox or Task (as returned by WHOIS) SEMAPHORES: To setup a semaphore, create a suitably name mailbox and send a message to it to enable it. The first task to read the mailbox, empties it, executes the program which needs protection, and then sends a new message to the mailbox to re-enable it. Each task must interrogate the mailbox using READMAIL -W. The contents of the message are not important. Let's say you want to protect a print job from being disrupted. To start, we need a mailbox named PRINTER as our SEMAPHORE. MAILBOX -N printer ; create a mailbox named PRINTER SENDMAIL printer free ; prime it with a message Now, all print operations must check this mailbox before printing and re-enable it after. READMAIL -W -Tprinter ; test SEMAPHORE and wait... PRINT %1 %2 %3 ; safe to print now SENDMAIL printer free ; re-enable SEMAPHORE Error codes returned: 1 Unrecognized option 2 Illegal parameter 3 DESQview not available 4 Task not found 5 Function not supported by this version of DESQview 6 No mailbox specified 7 New mailbox must be in the current task ======================================================================= MAILBOX.SHP MAILBOX.SHP is a DESQview shared program which assigns the specified data string as the name of the default mailbox of the task. Since shared programs are called from the DV Program Information File (.DVP), no batch file is needed. Enter the program path and name into the "Shared Program - Pathname" field and the mailbox name into the "Shared Program - Data" field on the second page of `Change a Program'. 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Shared Program � � Pathname..: C:\DV\MAILBOX.SHP � � Data......: MyName � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� ======================================================================= MESSAGES MESSAGES returns the status (pending message count) of the mailbox of the specified task. If no task is specified, status of the default mailbox of current task will be read. If the -E option is enabled, status will be returned as the environment variable %MESSAGES. MESSAGES=0 indicates an empty mailbox. Usage: MESSAGES [options] Options: -E returns count as Environment variable %MESSAGES -Q Quiet mode -Tname Task to read mailbox status from -Thandle handle of Task to read mailbox status from ======================================================================= READMAIL Reads the oldest pending message from the specified mailbox. If no messages are pending, and the -W option is enabled, READMAIL will wait for the next message. If no task is specified, the default mailbox of the current task is read. Returns the message, status and handle of the sender. If the -E option is enabled, results are returned in environment variables %MAIL%, %STATUS% and %SENDER%. Status is also returned as ERRORLEVEL. Usage: READMAIL [options] Options: -E returns string as Environment variable %MAIL -Q Quiet mode -Tname name of Task (mailbox) to read from -Thandle handle of Task (mailbox) to read from -W Wait if mailbox is empty ======================================================================= SENDKBD SENDKBD sends the specified string to the keyboard of the specified task. To the receiving task, the string will appear to have come from the keyboard, even if the keyboard is not currently available to that task. The string may contain embedded commands in the form `&' which will be expanded and replaced as sent. Embedded commands in the form `&' can send any arbitrary KEY CODE. may be any 16 bit integer of which the low order byte is the ASCII code and the high order byte is the SCAN code. Numbers prefaced with `$' are assumed to be Hex. To send `&' replace it with `&&'. Usage: SENDKBD [options] string Options: -H Hex -Q Quiet mode -Tname destination Task name -Thandle destination Task handle (as returned by WHOIS) Substitutions: &BS BackSpace &FF FormFeed &CR Carriage Return &LF LineFeed &DEL DELete &NL New Line &EOF End Of File &TAB TABulation &ESC ESCape &BELL ring BELL &Fn1 Function key n1 &n1 any code ======================================================================= SENDMAIL SENDMAIL sends the specified string to the specified mailbox. Optionally send a status byte with the message. Usage: SENDMAIL task string Options: -Sn1 set Status -Q Quiet mode ======================================================================= SOUND SOUND generates tones from the PC's speaker at the specified frequency (in Hz) for the specified duration (in timer ticks). A duration of 18 ticks generates a tone of about 1 second. A frequency of 0 Hz generates silence. If both frequency and duration are zero (or no parameters are entered), the sound queue is cleared. In note mode, notes can be C, C#, D~, D, D#, E~, E, F, F#, G~, G, G#, A~, A, A#, T (tempo) and R (rest). One digit corresponding to octave (0 thru 5) must follow each note without any spaces intervening. One digit corresponding to tempo (1 thru 7, default=5) must follow T. No parameter follows R. C2 corresponds to middle C. A2 is 440 Hz. Usage: SOUND [options] freq,ticks freq,ticks freq,ticks ... SOUND [options] T6 C2 A#3 R B1 ... Options: -Q Quiet mode ======================================================================= SWITCH SWITCH takes the name of a mailbox from the keyboard or script and switches to the window containing that program if already running. If not, the specified DVP file is spawned using the Open Menu key following the semi-colon or the first two characters of the mailbox name unless a DVP file is specified as part of the command. Usage: SWITCH [mailbox-name] [dvp-file] Usage in DESQview scripts: {DESQ}oSW{Enter} or {DESQ}oSW;{Enter} ======================================================================= TITLE TITLE assigns the specified string as the window title of the specified task. If no task is specified, the current task is assumed. This is the string which is displayed in the frame of the window and on the "Open window" menu. It should not be confused with the name assigned to the mailbox. Its use is totally cosmetic. Usage: TITLE [options] string Options: -Q Quiet mode -Tname name of Task -Thandle handle of Task (as returned by WHOIS) ======================================================================= WHOIS WHOIS returns the handle of the specified task. Its purpose is to test for the existence of a task with the specified mailbox name. It can be used to prevent a program from being run in more than one window. usage: WHOIS [options] task options: -E returns handle as Environment variable %TASK -E:name returns handle as Environment variable %NAME -Q Quiet mode ======================================================================= WINDOW WINDOW sets the size and position of the default window of the specified task. If no task is specified, the current task is assumed. usage: WINDOW [options] col,row,wide,long options: -Q Quiet mode -Tname name of Task owning window -Thandle handle of Task owning window (as returned by WHOIS) ======================================================================= ZOOM ZOOM switches the default window of the current task between full screen mode and windowed mode. Usage: ZOOM ======================================================================= 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � Special thanks to Ralf Brown and his Interrupt List � � which helped make this set of utilities possible. � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� Please forward all comments and bug reports to: Gary Chanson 31 Chester Avenue Waltham, MA 02154 617-899-4771 - voice 617-899-6672 - Archane Incantations BBS Email: Gary.Chanson@Channel1.com