ID: Q128944
The information in this article applies to:
Microsoft Product Supports Services offers an Application Note called "Handling Cross-Platform Differences in WordBasic" (XD1155). This document describes differences that you should address when you are creating macros that will run in Microsoft Word under the Macintosh, Microsoft Windows, and Microsoft Windows NT operating systems. This reference contains advanced material about programming macros in WordBasic and is intended for the advanced Word user.
The following file is available for download from the Microsoft Software Library:
~ XD1155.exe (size: 35894 bytes)
ARTICLE-ID: Q119591
TITLE : How to Obtain Microsoft Support Files from Online Services
The following file is available for download from the Microsoft Software Library:
~ XD1155.HQX (size: 50848 bytes)
ARTICLE-ID: Q119591
TITLE : How to Obtain Microsoft Support Files from Online Services
Microsoft(R) Product Support Services Application Note (Text File)
XD1155: HANDLING CROSS-PLATFORM DIFFERENCES IN WORDBASIC
Revision Date: 3/95
No Disk Included
---------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an Application |
| Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
| EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED |
| WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR |
| PURPOSE. The user assumes the entire risk as to the accuracy and |
| the use of this Application Note. This Application Note may be |
| copied and distributed subject to the following conditions: 1) All |
| text must be copied without modification and all pages must be |
| included; 2) If software is included, all files on the disk(s) |
| must be copied without modification (the MS-DOS(R) utility |
| diskcopy is appropriate for this purpose); 3) All components of |
| this Application Note must be distributed together; and 4) This |
| Application Note may not be distributed for profit. |
| |
| Copyright (C) 1995 Microsoft Corporation. All Rights Reserved. |
| Microsoft, MS-DOS, and Windows are registered trademarks and |
| Windows NT is a trademark of Microsoft Corporation. |
| Apple, Mac, and Macintosh are registered trademarks and PowerTalk |
| and QuickDraw are trademarks of Apple Computer, Inc. |
--------------------------------------------------------------------
This Application Note describes differences that you should address when you are creating macros that will run in Microsoft Word under the Macintosh(R), Microsoft Windows, and Microsoft Windows NT(TM) operating systems. This reference contains advanced material about programming macros in WordBasic and is intended for the advanced Word user.
The information in this Application Note applies to Microsoft Word versions 6.0, 6.0a, and 6.0c for Windows, Microsoft Word version 6.0 for the Macintosh, and Microsoft Word version 6.0 for Windows NT.
WARNING: ANY USE BY YOU OF THE CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this macro code "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.
When you are writing cross-platform macros, consider whether the platform requires different system-specific functionality in WordBasic. A different parameter or an entirely different command may be necessary for the macro to run on both the Macintosh and the Windows operating systems.
Most Word for Windows macros work correctly in Word for the Macintosh and Word for Windows NT without modification. However, areas of a macro that deal with operating-system-specific areas may require minor revision.
Areas that may require extra attention include:
- Specifying filenames and paths
- Using settings files
- Working with DDE
- Calling external routines or libraries
AppInfo$()
A cross-platform macro should determine the current operating system, or platform, if the macro contains platform-specific commands. Otherwise, the macro may return a WordBasic error when run on a different operating system.
The WordBasic AppInfo$(1) function will identify which platform is being used when the macro is run. AppInfo$(1) will return the following strings for each platform:
Platform Return Value
-----------------------------
Macintosh "Macintosh xxx"
Windows "Windows xxx"
Windows NT "Windows NT xxx"
You can store the string returned by the function in a variable that can be used to determine which WordBasic commands to execute later in the macro.
The following sample macro illustrates how to use the AppInfo$(1) function:
Sub MAIN
REM Determine Platform
REM ------------------
PlatformVar = 0
If Instr(AppInfo$(1), "Macintosh") <> 0 Then
Platformvar = 1
ElseIf Instr(AppInfo$(1), "Windows NT") <> 0 Then
PlatformVar = 2
End If
REM Remainder of Macro
REM ------------------
Select Case PlatformVar
Case 0
REM WORD FOR WINDOWS COMMANDS GO HERE
Case 1
REM WORD FOR MACINTOSH COMMANDS GO HERE
Case 2
REM WORD FOR WINDOWS NT COMMANDS GO HERE
Case Else
Print "Invalid value"
End Select
End Sub
Choose one platform for writing and editing cross-platform macros and use it consistently. Avoid editing macros on more than one platform if you are developing macros in a version of Word that does not recognize WordBasic commands supported by Word on another platform. For example, if you write a macro in Word 6.0a for Windows, and then the macro is moved to Word 6.0 for the Macintosh, edited, and moved back to Word for Windows and edited, Word for Windows will remove Macintosh- specific commands from the macro. This situation occurs because Word 6.0 and 6.0a for Windows don't recognize the Macintosh commands. For more information, please see the sections regarding converting cross- platform macros in this Application Note.
If you are writing the macro in a version of Word that does not recognize WordBasic commands supported by Word on another platform, test a copy of the macro on the other platform. Note any changes that are required for the macro to run correctly and then add the commands to the original.
Decide whether to distribute the macro in an execute-only format. If the macro is formatted as execute-only, it cannot be edited. Use the MacroCopy statement with the ExecuteOnly parameter set to 1. Because the action cannot be reversed, be sure to make a copy of the macro before setting it to execute-only.
Files$()
The Files$() WordBasic function returns the first filename that matches the file specification parameter. In Windows, the file specification can contain the MS-DOS wildcard characters (the asterisk and question mark); on the Macintosh, the MacID$ command is used to specify files of a certain type.
The following Word for Windows example returns the first file ending in ".doc" in the current directory:
a$ = Files$("*.doc")
a$ = Files$(MacID$("W6BN"))
FileOpen
Word for Windows and Word for Windows NT support opening more than one file at a time with a single FileOpen command. For example, to open the two files, FIRST.DOC and SECOND.DOC, use the following FileOpen command:
FileOpen .Name = "FIRST.DOC SECOND.DOC"
FileOpen .Name = "First"
FileOpen .Name = "Second"
Both Word for the Macintosh and Word for Windows NT support the use of long filenames, including those with one or more spaces.
To open a document whose name contains spaces and to prevent Word for Windows NT from treating the name as separate document names, you must enclose the entire name in quotation marks by adding the quotation mark character, CHR$(34), to the beginning and end of the long filename. The following WordBasic macro command opens a single document called "FIRST.DOC SECOND.DOC":
FileOpen .Name = Chr$(34) + "FIRST.DOC SECOND.DOC" + Chr$(34)
FileOpen .Name = "First Second"
In Windows, Word settings are stored in a text file called WINWORD6.INI. On the Macintosh, settings are stored in a file called Word Settings (6). In Windows NT, Word settings are stored in the Windows NT Registry. Use the SetPrivateProfileString command and GetPrivateProfileString$() function to change or retrieve settings in the WINWORD6.INI file, Word Settings (6) file, or the Windows NT Registry.
The GetPrivateProfileString$() function is used differently depending upon the platform. The syntax for GetPrivateProfileString$() is
GetPrivateProfileString$(Section$,KeyName$,Filename$)
The following examples show how to retrieve the DOC-PATH setting for each platform:
Windows
a$ = GetPrivateProfileString$("Microsoft Word","DOC-
PATH","WINWORD6.INI")
a$ = GetPrivateProfileString$("Microsoft Word", "DOC-PATH","Word
Settings (6)")
a$ =GetPrivateProfileString$("HKEY_CURRENT_USER\Software\
Microsoft\Word\6.0\Options","DOC-PATH","")
In Word 6.0, routines stored in external libraries can be called as functions or subroutines by WordBasic macros. In Word for Windows and Word for Windows NT, the libraries can be either Word add-ins (WLLs) or Windows dynamic-link libraries (DLLs), or they can be executable files (.EXEs). In Word for the Macintosh, only routines in WLLs can be called. The Declare statement specifies the name of the routine, the library file in which it is stored, and any argument types the routine takes.
When a Word for Windows macro is converted to Word for the Macintosh, any Declare statements that refer to DLLs will return the WordBasic error 543, "Unable to open specified library." This error occurs because the Windows libraries (USER.EXE, KRNL386.EXE, and GDI.EXE) do not exist on the Macintosh.
When you convert a Word for Windows macro to Word for Windows NT, make sure that any Declare statements use 32-bit conventions. If the function being called is a Windows API function, there are some general rules you can use to determine the 32-bit Windows NT equivalent API function. For the most accurate information, consult the "Microsoft Win32 Software Developer's Kit."
The name of the DLL containing the function typically has "32" appended to the end of the name. For instance, the equivalent of "kernel" in Windows 3.x is "kernel32" in Windows NT. However, there are exceptions to this rule.
Functions that use strings are typically available in two versions: ANSI and Unicode. Word for Windows NT is an ANSI application and must, therefore, use ANSI application programming interface (API) functions. The ANSI version of API functions have an "A" appended to the end of the function name. For instance, the Windows 3.x function GetWindowsDirectory is GetWindowsDirectoryA under Windows NT.
For all functions under Windows 3.x that use the type Integer, Windows NT uses Long.
Unlike in Windows, DLL functions in Windows NT are case sensitive. For the Declare statement to work, the case of the function name must exactly match the actual case of the function name.
The following two examples
Declare statement for use with Word under Windows 3.x:
Declare Function getwindowsdirectory Lib "Kernel"(WinDir As
String, nSize As Integer) As Integer
Declare Function GetWindowsDirectoryA Lib "Kernel32"(WinDir
As String, nSize As Long) As Long
For more information regarding standard Windows function libraries such as GDI.EXE and USER.EXE, see the "Microsoft Windows Programmer's Reference, Volume 2." For a list of the appropriate module and library for each function, see "Volume 1." Windows NT functions are documented in the "Microsoft Win32 Programmer's Reference, Volume 3" and "Volume 4."
In addition, the "Microsoft Word Developer's Kit, Second Edition," contains tools for creating add-ins that interact directly with Word using the Microsoft Word application programming interface (Word API).
DDE is a protocol WordBasic can use to extract information from other applications or to send commands to other applications. When a client application (the application requesting information or sending commands) begins a DDE conversation, it must specify the name of the application (the server) and the subject of the conversation (the topic).
Below are the DDE application names for Microsoft Word:
Windows:
"WinWord" or "WordDocument"
"WinWord" or "MSWord" or "WordDocument"
"WinWord" or "MSWord"
The following example initiates a DDE conversation with Microsoft Excel for the Macintosh or Microsoft Excel for Windows. In this example the DDERequest$() command is used to get a list of the currently supported topics, which are then inserted into the current document.
Sub MAIN
REM First Determine Platform
PlatformVar = 0
If Instr(AppInfo$(1), "Macintosh") <> 0 Then
Platformvar = 1
ElseIf Instr(AppInfo$(1), "Windows NT") <> 0 Then
PlatformVar = 2
End If
REM Then Perform the Commands
Select Case PlatformVar
REM The Mac Commands:
Case 1
If AppIsRunning(MacID$("XCEL")) = 0 Then
Shell MacID$("XCEL"), 4
End If
chan = DDEInitiate("Excel", "System")
topics$ = DDERequest$(chan, "Topics")
Insert topics$
REM The Windows and Windows NT Commands:
Case 0, 2
If AppIsRunning("Excel") = 0 Then
Shell "c:\EXCEL5\EXCEL.EXE", 4
End If
chan = DDEInitiate("Excel", "System")
topics$ = DDERequest$(chan, "Topics")
Insert topics$
Case Else
End Select
End Sub
NOTE: When an application runs on more than one platform, the same
application may have a different application name in Windows and on
the Macintosh. Because of these differences, it is better to use OLE
automation for macros that will run on more than one platform. OLE
automation is another protocol that allows an application to share
data with or control another application. For more information
regarding OLE automation, please see the "Microsoft Word Developer's
Kit, Second Edition" pages 181 through 190.
A macro created in Word version 6.0, 6.0a, or 6.0c for Windows that contains Macintosh-specific WordBasic commands will return the following error when run in Word 6.0 for the Macintosh unless you "dirty" the macro first:
WordBasic Error 124, "Unknown Command, Subroutine, or Function"
After you edit and save (that is, dirty) the macro in Word for the Macintosh, the Macintosh-specific commands should run without error. Dirtying the macro in Word for the Macintosh is necessary only once. Ideally, you should dirty the macro once prior to distributing the macro to other Macintosh Word users.
Macintosh-specific commands are those WordBasic commands that are available only on the Macintosh platform. The following example contains the Macintosh-specific command MacID$().
Sub Main
a$ = MacID$("TEXT")
End Sub
If you create a macro in Word for the Macintosh and copy the template that contains the macro to Word 6.0 or 6.0a for Windows, Word permanently removes the Macintosh-specific WordBasic commands from the macro when you edit and save the macro in Word 6.0 or 6.0a for Windows. Word does not restore the Macintosh commands when you transfer the macro back to the Macintosh platform, and as a result, the macro will not run correctly on the Macintosh.
The following Macintosh Word 6.0 macro contains a Macintosh-specific function named MacID$.
Sub MAIN
a$ = MacID$("TEXT")
End Sub.
Sub MAIN
a$ = ("TEXT")
End Sub
NOTE: The Macintosh-specific command MacID$ was deleted.
Word 6.0c for Windows does not delete unknown (Macintosh-specific) commands from your Word for the Macintosh macros when you transfer them to Word 6.0c for Windows. Word 6.0c will instead display "Unrecognized_Statement" in place of the Macintosh commands.
If you create the following macro in Word 6.0 for the Macintosh
Sub Main
a$ = MacID$("TEXT")
End Sub
Sub Main
a$ = Unrecognized_Statement33134("TEXT")
End Sub
If you transfer the template that contains the macro back to Word 6.0 for the Macintosh, you must dirty the macro in Word for the Macintosh. In other words, you must open the macro in Word for the Macintosh, make a small change such as adding a space, and save the macro. This action changes the token IDs back to the Macintosh-specific WordBasic commands, such as MacID$(). Dirtying the macro in Macintosh Word is necessary only once. Ideally, you should dirty the macro once before distributing the macro to other Word for the Macintosh users.
Note that Macintosh-specific WordBasic statements and functions are recognized by Word 6.0 for Windows NT.
DETERMINING WHETHER QUICKDRAW(TM) IS INSTALLED
GetSystemInfo$()
QuickDraw GX is Apple(R)'s new version of QuickDraw, which is the language the Macintosh uses to draw images to the screen. If installed, QuickDraw GX provides the means for Word 6.0 to access different Page Setup options available under QuickDraw GX.
When you write a macro that contains Macintosh-specific commands referring to QuickDraw GX, such as FileMacPageSetupGX or FileCustomMacPageSetupGX, the macro must first determine whether QuickDraw GX is installed.
You can use the GetSystemInfo$(519) function to determine whether QuickDraw GX is installed on the system under which the macro is running. The return value of GetSystemInfo$(519) is "Yes" if QuickDraw GX is installed and "No" if it is not. The following macro illustrates one way the GetSystemInfo$(519) function can be used:
Sub MAIN
If GetSystemInfo$(519) = "Yes" Then
MsgBox "QuickDraw GX is installed on this system."
Else
Msgbox "QuickDraw GX is not installed on this system."
End If
End Sub
The following table lists WordBasic statements and functions that are valid only when Word is running on the Macintosh. A WordBasic statement or function that is only available in Word for Macintosh will generate an "Unknown command" error if run on the Windows platform.
EditCreatePublisher EditPublishOptions EditSubscribeOptions EditSubscribeTo EditFindBorder EditFindFrame EditFindTabs EditReplaceBorder EditReplaceFrame EditReplaceTabs FileCustomMacPageSetupGX FileDocumentLayout FileMacPageSetup FileMacPageSetupGX ListCommands Outline Outline() Shadow Shadow() MacScript MacScript$() MountVolume AOCEAddRecipient AOCEAuthenticateUser() AOCEClearMailerField AOCECountRecipients() AOCEGetRecipient$() AOCEGetSender$() AOCEGetSubject$() AOCESendMail AOCESetSubject FileAOCEAddMailer FileAOCEDeleteMailer FileAOCEExpandMailer FileAOCEForwardMail FileAOCENextLetter FileAOCEReplyAllMail FileAOCEReplyMail FileAOCESendMail FilePrintOneCopy FileQuit ShowClipboard
Note on QuickDraw GX: QuickDraw GX must be installed in order to use the FileCustomMacPageSetupGX, and FileMacPageSetupGX commands. QuickDraw is the language the Mac(R) uses to draw images to the screen and interpret print files. QuickDraw GX is Apple's new optional version of QuickDraw included with System Software 7.5. If installed, QuickDraw GX provides the means for Word 6.0 to access different Page Setup options.
Note on PowerTalk(TM) and AOCE: The WordBasic Apple Open Collaboration Environment (AOCE) commands require that PowerTalk be installed on your Macintosh. PowerTalk is the client software for AOCE technology. It is integrated into Apple's System 7 Pro and 7.5 operating systems. AOCE facilitates collaboration among users through electronic mail, voice mail, and fax messages.
The following table lists WordBasic statements and functions that are valid only when Word is running under Windows or Windows NT. The commands listed below are not available and generate "Unknown Command" errors when run under Word for the Macintosh.
AppHide AppMaximize AppMaximize() AppMinimize AppMinimize() AppMove AppRestore AppRestore() AppSendMessage AppShow AppSize AppWindowHeight AppWindowHeight() AppWindowPosLeft AppWindowPosLeft() AppWindowPosTop AppWindowPosTop() AppWindowWidth AppWindowWidth() Connect ControlRun Environ$() ExitWindows FilePrintSetup HelpWordPerfectHelp HelpWordPerfectHelpOptions MicrosoftAccess MicrosoftPublisher MicrosoftSchedule RunPrin(((TM)))anager ToggleScribbleMode
Using the GetProfileString$() function to return a path setting in the Word Settings (6) file results in a path that contains "garbage" characters or symbols (that is, corruption).
To avoid having the function return unusable information, use the GetPrivateProfileString$() function. For example:
Sub MAIN
a$=GetPrivateProfileString$("Microsoft Word", "USER-DOT-PATH",
"Word Settings (6)")
MsgBox a$
End Sub
Using WordBasic commands to control the size or position of a custom
The following commands, which control the size or position of user dialog boxes in Word 6.0 for Windows, are not available in Word 6.0 for the Macintosh and return errors:
AppSize AppMove AppWindowHeight AppWindowWidth AppWindowPosTop AppWindowPosLeft
The AppSize command is used to control the height and width of a custom dynamic dialog box by placing the dialog box in the case structure of a dialog box function. (The case structure defines which dialog box functions will be performed based on the user's input, or action.)
The following AppSize command refers to the dialog box title, Title$, as defined earlier in the initialization of the dialog box; and the numbers refer to the width and height of the dialog box.
AppSize Title$ 300,400
The DlgFocus statement, which is used within a dialog box function to set the focus on a dialog box control (for example, a push button) while the dialog box is displayed, does not work in Word 6.0 for the Macintosh.
When a dialog box control has the focus, it is active and responds to keyboard input. Push buttons with the focus appear to have a darker ring around them.
The command does not return a WordBasic error when the macro is run, but the focus is not set to the desired control.
In the following example, the DlgFocus statement in Case 1 of the dialog box function sets the focus to the control specified by MyControl1. This statement sets the focus correctly in Word 6.0 for Windows.
Sub Main
Begin Dialog UserDialog 320, 144, "Microsoft Word", .MyDlgFunction
OKButton 10, 6, 88, 21
CancelButton 10, 30, 88, 21
PushButton 57, 101, 88, 21, "Mybutton", .MyControl1
End Dialog
Dim dlg As UserDialog
x = Dialog(dlg)
End Sub
Function MyDlgFunction(identifier$, action, suppvalue)
Select Case action
Case 1
DlgFocus "MyControl1"
Case Else
End Select
End Function
The Word 6.0 for the Macintosh WordBasic macro language fails to send certain noncharacter keystrokes when using the SendKeys statement. Due to a system limitation, the full set of keystrokes are not supported on the Macintosh. See online Help in Word for a list of keystrokes that are supported.
When you create a user dialog box with WordBasic and run the macro that contains the dialog box in Word for the Macintosh, designated access keys (or shortcut keys) do not appear with an underline. However, although the characters are not underlined, the access keys do, in fact, work as expected. After the user presses the COMMAND key for a moment, an underline will appear under the specified characters. (It is not necessary to "turn on" the underline in Word 6.0 for Windows; the access keys are always underlined.)
NOTE: You can add access keys to a dialog box to allow quick access to items from the keyboard. When an access key is defined for an item in a user dialog box, the user can press COMMAND + the specified character to select or clear a check box, pull down a list, or choose a command button. You can specify the access letter in the WordBasic Dialog Editor by typing an ampersand in front of the letter in the Text$ box; for example, "C&heck Box" in line 6 of the macro below will display an underscored "h" in the dialog box.
To automatically display shortcut keys in a dialog box upon running a macro (without the user having to first press the COMMAND key), add a MenuMode statement to the macro. To see how to add the MenuMode statement, see the example below.
Sub MAIN
MenuMode
Begin Dialog UserDialog 320,144, "Microsoft Word"
OKButton 10, 6, 88, 21
CancelButton 10, 30, 88, 21
CheckBox 150, 84, 100, 18, "C&heck Box", .CheckBox1
End Dialog
Dim dlg As UserDialog
n = Dialog(dlg)
End Sub
WordBasic uses a different ANSI character sort order than that used by the Sort Text command on the Table menu in Word.
Furthermore, the ANSI character sort order differs between Word for the Macintosh and Word for Windows, both for WordBasic and for the Sort Text command. In other words, there are four different ANSI character sort orders.
The specific sort order of ANSI characters is relevant when you write WordBasic macros that compare items based on their sort order. The sort order is predictable for alphabetic and numeric characters (for example, A comes before B, 3 comes before 4, and so forth). However, the sort order for the remaining characters is not predictable, so a sort order list is helpful. For example, to determine whether "!" is greater or less than "?", you must refer to a sort order list (or run a SortArray macro to sort the characters).
The following macro determines the WordBasic sort order of ANSI characters and inserts into the open document each character followed by a tab and the corresponding ASCII code value.
Sub MAIN
REM Construct a 2 variable array
Dim c$(255), a(255)
For i = 1 To 255
c$(i) = Chr$(i)
a(i) = I
Next i
REM Compares 2 characters at a time to determine sort order
For i = 1 To 254
For j = i + 1 To 255
If c$(i) > c$(j) Then
REM If 1st var > than 2nd var compared then switch them
temp$ = c$(i)
c$(i) = c$(j)
c$(j) = temp$
temp = a(i)
a(i) = a(j)
a(j) = temp
REM Inserts the characters and their values in a document
Print i, j
EndIf
Next j
Next i
For i = 1 To 255
Insert c$(i) + Chr$(9) + Str$(a(i))
InsertPara
Next i
End Sub
Certain GetSystemInfo$() function types
Using the following function types with GetSystemInfo$() in Word for Windows NT return an empty string:
Keywords : kbappnote kbfile kbmacro winword ntword macword word6
Version : MACINTOSH: 6.0; WINDOWS:6.0
Platform : MACINTOSH WINDOWSLast Reviewed: December 30, 1998