Functions and statements for working with other programs

LotusScript® provides several functions and statements that you can use to work with other programs and with the operating system.

Function/Statement

Purpose

Shell function

Starts another program

Shellid function

Starts another program and returns its task ID.

ActivateApp function

Activates (gives focus to) the specified window

SendKeys statement

Sends keystrokes to the active window

Environ function

Returns the current value of an environment variable

Yield function/statement

Transfers control during script execution to the operating system

The Windows platform supports all of these functions and statements. The UNIX platforms and the Macintosh support some. Also, different client products may choose not to support certain functions. For example, Notes® does not support SendKeys and Yield. Additionally, Yield is only useful in a Win 16 environment. For more information, see Appendix B, "Platform Differences."

The following example uses all of these functions and statements to interact with a Windows accessory, Notepad:

  • The Environ function returns the Windows Temp directory, the directory where Windows creates and maintains temporary files.
    Note: On the Windows platforms, the operating system and some programs make use of environment variables that you set. Under MS-DOS, for example, you use CONFIG.SYS, AUTOEXEC.BAT, and other batch files to set environment variables. You can use the MS-DOS Set command to see a list of environment variables and their current settings. In a script, you can use the Environ function to return the current value of an environment variable.
  • The Shell function starts NOTEPAD.EXE.
  • The ActivateApp function makes sure that Notepad has the focus so that keystrokes can be sent to it.
  • SendKeys statements save a note the user writes in a text file, minimize the Notepad window, and close Notepad.
  • The Yield function lets Windows pass control to Notepad so the user can use it to compose a note.

There are two module-level variables and four subs.

The module-level variables are String variables:

Dim startDir As String ' The current directory at startup.
Dim fileName As String ' The note file name.

The four subs are Initialize, CreateNote, ReadNote, and Terminate. Initialize automatically executes when the module is loaded. In turn, Initialize calls CreateNote and ReadNote. Terminate executes before the module is unloaded.

The Initialize sub makes the Windows Temp directory the current directory, makes sure that a file named _MYNOTE.EXE exists and is empty, calls the CreateNote sub, then calls the ReadNote sub.

Sub Initialize
   Dim tempDir As String, taskID As Integer
   ' Store the name of the current directory, then make the
   ' Windows Temp directory the current directory.
   startDir$ = CurDir$
   tempDir$ = Environ("Temp") 
   ChDir tempDir$
   fileName$ = "_MYNOTE.TMP"
   ' Make sure the file exists and is empty before
   ' opening Notepad.
   fileNum% = FreeFile
   Open fileName$ For Output As fileNum%
   Write #fileNum% ' The file now contains only an empty line.
   Close fileNum% ' Open the file (guaranteed to exist) in Notepad. taskID% = Shell("notepad " & fileName$)
   CreateNote ' Create the note. See the CreateNote sub below.
   ReadNote ' Display the note. See the ReadNote sub below.
End Sub

The CreateNote sub creates a header for the note, including the current date and time, displays a message, activates (shifts focus to) Notepad, and sends the header to Notepad. It then yields control to Windows for 10 seconds so the user can type into Notepad. If the 10-second While loop with the Yield were excluded, script execution would continue without any pause, giving the user no time to enter a note.

After 10 seconds, an ActivateApp statement insures that Notepad has the focus (in case the user has shifted focus to another window), and a SendKeys statement sends keystrokes for the File Save menu command and the Control menu Minimize command.

The keystrokes for File Save are ALT+FS and the keystrokes for Minimize are ALT+spacebar+N. ALT+spacebar+C opens the Control menu in the Notepad title bar. In a SendKeys statement, % represents the ALT key.

Sub CreateNote
   Dim header As String, finish As Single
   MessageBox "Write your note."
   header$ = Format(Now, LongDate) &"~~Note: "
   ActivateApp "notepad - " & fileName$
   SendKeys "~" & header$, TRUE ' Send the note header
                                ' to Notepad.
   finish! = Timer + 10
   While Timer < finish!
      Yield
   Wend
   ActivateApp "notepad - " & fileName$
   SendKeys "%fs% n",TRUE ' Save the file
                          ' and minimize the window.
End Sub

The ReadNote sub displays a message box, opens the file that was just saved, inputs the file contents into a String variable, and displays a message with the contents. The file name appears in the message box title bar.

Sub ReadNote
   MessageBox "Read your note."
   fileNum% = FreeFile
   Open fileName$ For Input As #fileNum% 
   message$ = Input$(LOF(fileNum%), fileNum%)
   Close fileNum%
   MessageBox message$,, fileName$
End Sub

The Terminate sub executes. An ActivateApp statement shifts focus to Notepad, in case the user moved the focus to another window. A SendKeys statement sends ALT+F4 to Notepad, which closes Notepad. The sub then makes the current directory at startup the current directory again.

Sub Terminate
   ActivateApp "notepad - " & fileName$
   SendKeys "%{f4}", TRUE
   ChDir startDir$
End Sub