The DECWMail-to-Tpu connection ------------------------------ The DECWMail-to-TPU connection is a program which allows DECWindows Mail to use an existing DECWindows TPU editing session as its editor. The TPU editor may be any DECWindows TPU based editor, EVE in any of its forms, or LSEDIT. The editor does not need to be active on the same node as DECWindows Mail, but if it isn't, then one will need to insure that SYS$SCRATCH refers to the same disk and directory. The instructions for setting yourself up follow. Please report any problems, major or minor, that you find. M. Erik Husby Lotus Development Corp. 1 Rogers St. Cambridge, MA. 02138 (617)693-4490 email: husby@eisner.decus.org How it works. ------------- DECWindows Mail has the ablity to use different editors. When you select DECWindows EVE, for instance, it creates a subprocess and starts EVE in it. This can be time consuming. The DECWMail-to-Tpu uses a different approach. Mail will still create a subprocess to run the small program DECWMail-to-Tpu in. The DECWMail-To-Tpu program will search the windows on the display looking for a TPU window. If a TPU window is found, the names of the input and output files will be placed in properties on the root window. The TPU window will be brought to the front and given input focus. Through a special TPU$CALLUSER shared image, TPU procedures can retrieve the names of the input and output files and edit them. A TPU procedure will signal the DECWMail-To-Tpu program that is done editing by manipulating the properties. DECWMail-To-Tpu will then bring the Mail:Send window to the front and give it input focus so that you can send the mail. Note: A window property is very similar to a VMS logical name. It is an arbitrary collection of data given a name and stored in the X server. The first time you run DECWMail-to-Tpu, it needs to search the complete window tree for the TPU window. This may take a noticeable amount of time. Therefore DECWMail-to-TPU will store the DECW$MAIL and TPU window ids as properties on the root window. DECWMail-to-Tpu will validate the window ids it finds on the root window before using them and if necessary will do the search again. If no TPU window is found, DECWMail-to-Tpu will exit with a call to LIB$DO_COMMAND to invoke the editor of your choice similar to what DECW$MAIL would do by default. Installing the DECWMail-To-Tpu connection. ------------------------------------------ A. Files needed for the DECWMail-to-Tpu connection. NOTE: All executables where linked on a VMS 5.4 system. Used by DECW$MAIL. DECWMAILTPU.COM -- Called by DECW$MAIL in a subprocess. DECWMAILTPU.EXE -- Called by DECWMAILTPU.COM to trigger TPU. Used by either EVE or LSEDIT. TPU$CALLUSER.EXE -- A TPU$CALLUSER shared image. TPU$CALLUSER.TPU -- TPU code to call routines in TPU$CALLUSER.EXE DECWMAIL.TPU -- EVE commands to setup mail editing buffer. Used by LSEDIT. DECWMAIL.LSE -- LSE procedure to compile DECWMAIL.TPU and define LSE commands to setup mail editing buffer. Other files included in the kit. AAAREADME.TXT -- abstract of program. DECWMAILTPU.C -- Source of the DECW$MAIL-to-TPU program. DECWMAILTPU.OBJ -- Object of the DECW$MAIL-to-TPU program. LSE$INITIALIZATION.LSE -- Sample LSE initialization commands. TPU$CALLUSER.C -- Source of the TPU$CALLUSER.EXE shared image. TPU$CALLUSER.COM -- Procedure to compile and link TPU$CALLUSER.EXE TPU$CALLUSER.OBJ -- Object of TPU$CALLUSER.C. TPU$CALLUSER.OPT -- Linker options for TPU$CALLUSER.EXE VMS.H -- Various helpful VMS C definitions. B. Steps needed to use the DECWMail-to-Tpu connection with LSEDIT. 1. Prepare LSEDIT to use the TPU$CALLUSER.EXE and related TPU procedures. 1A. Define the logical name TPU$CALLUSER to point to the TPU$CALLUSER.EXE $ DEFINE TPU$CALLUSER disk:[directory]TPU$CALLUSER.EXE 1B. Extend LSE's TPU procedures to include TPU$CALLUSER.TPU and DECWMAIL.TPU. This can be done with DECWMAIL.LSE. This LSE command file will compile the TPU programs and define two keys, ALT/M and ALT/Z. LSE> GO FILE DECWMAIL.LSE LSE> DO NOTE: DECWMAIL.LSE uses the logical name TPU_: to locate the necessary files. Either edit DECWMAIL.LSE or define the logical name to be the correct directory. Save the modified TPU section. LSE> SAVE SECTION sectionname 1C. In your LSE$INITIALIZATION file (which you need to create if you do not have one), include the line: call decwmail_module_init 2. If you are using DECWindows Motif V1, follow these steps to prepare DECW$MAIL to use DECWMAILTPU.EXE as the "editor". 2A. Select the "Options Send..." menu item. 2B. Press the "Change Editor List..." button. 2C. In the "Editor Name:" field, enter the name for this editor, "DECWMailTPU" is suggested. In the "Editor Command:" field enter: "@disk:[directory]DECWMAILTPU %s %s LSEDIT". Where 'disk:[directory]' is where you have stored the files DECWMAILTPU.EXE and DECWMAILTPU.COM. 2D. Select "Method: DECwindows" toggle button. 2E. Press "OK". 2F. To select the new editor, use the "Default Editor:" option menu. 3. If you are using DECWindows V2 (XUI), then you will need to edit the SYS$LOGIN:DECW$MAIL.DAT file to define the new editor. You will want to add the following 3 lines to the SYS$LOGIN:DECW$MAIL.DAT file. Mail.editor.4name: DECWMailTpu Mail.editor.4DCLcommand: @disk:[directory]DECWMAILTPU %s %s LSEDIT Mail.editor.4method: 0 The number '4' should be changed if you have already extended the editor selection menu. And 'disk:[directory]' is where you have stored the files DECWMAILTPU.EXE and DECWMAILTPU.COM. To specify DECWMailTpu as your editor: 3A. select the "Customize Send Attributes..." menu item. 3B. In the "Default Editor" popup menu, select "DECWMailTpu". 3C. Press the "OK" button to accept the changes. 3D. To make the selection permanent, select the "Customize Save Attributes" menu item. 4. You should now be ready to test this out. 4A. Start up your LSEdit session using the section file created in step 1 and with the logical name TPU$CALLUSER defined. 4B. Verify that the TPU$CALLUSER procedures can be called by executing: LSE> DO/TPU "MESSAGE(USER_VERSION())" You should see something like: "Husby tpu$calluser 1.6 at 99999999" where "99999999" is the virtual address where the TPU$CALLUSER.EXE sharable image was loaded. If you do not see such a message than the TPU$CALLUSER.EXE is not loading properly. Verify that the logical name is correct and that the TPU$CALLUSER.TPU procedures are loaded. 4C. Start up DECW$MAIL. 4C1. Specify DECWMailTPU as your default editor. 4C2. Press the "Create-Send" button. 4C3. You will see the "Mail: Send" window appear with the text "Using editor DECWMailTPU" in the message area. 4C4. After a brief pause, your LSEdit window will pop to the front with input focus. 4C5. Press M. The buffer "DECW$MAIL Edit" will appear. 4C6. Edit your message. 4C7. When done editing, press Z. The DECW$MAIL buffer will be written out and deleted. The LSEdit window will then revert to the buffer you were in before pressing M. 4C8. The LSEdit window will be pushed to the back of the screen and the "Mail: Send" window will be brought to the front with input focus. NOTE: There is a known bug with the Motif version of DECW$MAIL whereby it may not get input focus properly. Clicking the mouse in the approriate text field should solve this. 4C9. Fill out the rest of the "To:" and "Subject:" fields and mail your message. C. Using DECWMail-to-Tpu connection with EVE. 1. To prepare EVE for the connection, simply include a reference to DECWMAIL.TPU into the master file used by EVE BUILD (See SYS$EXAMPLES:EVE$BUILD.TPU for details.) The file will define two EVE commands, DECWMAIL INIT, and DECWMAIL DONE. It is recommended that you bind the key ALT-M to DECWMAIL INIT. 2. If you are using DECWindows Motif V1, follow the instructions in B.2 for setting up DECW$MAIL, replacing LSEDIT with EDIT/EVE in the "Editor Command:" field. 3. If you are using DECWindows V2 (XUI), for the instructions in B.3 replacing LSEDIT with EDIT/EVE in the "Mail.editor.4DCLcommand" field. 4. The testing of EVE is similar to that for LSEdit. 4A. Start up EVE with the section file you just created and the logical name TPU$CALLUSER defined. 4B. Verify that the TPU$CALLUSER procedures can be called by the command: Command: TPU MESSAGE(USER_VERSION()) You should see something like: "Husby tpu$calluser 1.6 at 99999999" where "99999999" is the virtual address where the TPU$CALLUSER.EXE sharable image was loaded. If you do not see such a message than the TPU$CALLUSER.EXE is not loading properly. Verify that the logical name is correct and that the TPU$CALLUSER.TPU procedures are loaded. 4C. Follow the instructions in B.4C D. Debugging Notes: If you suspect that you are getting errors running the editor, modify the command to be: "@disk:[directory]DECWMAILTPU/OUTPUT=alogfile %s %s editor" And define the logical name DCL_DEBUG as 1 in a logical name table that is visible to DECW$MAIL. You will see the DCL code and any error messages in the log file. The executable can also be compiled and linked /DEBUG. If you use the DECWindows DEBUGGER you do not need to bother creating a debugging terminal.