Tip   In Windows 95 and Windows NT Workstation 4.0, you can use a system policy to define the default value for the Save as type option in the Save As dialog box (File menu) for all Office 97 users in your workgroup (except for users of Access and Outlook, which do not support this option). In the Windows System Policy Editor, set the following policies:

User\Excel\Tools_Options\Transition\Default Save

User\PowerPoint\Tools_Options\Save\Default Save

User\Word\Tools_Options\Save\Default Save

For more information, see "Using Windows System Policies to Customize Office" in Chapter 7, "Customizing and Optimizing Microsoft Office."

Upgrading Microsoft Access 1.x

Using a process called enabling, Access 97 can read data and run queries, forms, reports, macros, and Access Basic code in an Access version 1.x database without changing the format. This allows Access 97 users to share data with Access 1.x users. As an alternative to enabling, Access 97 can establish links to tables in an Access 1.x database.

All Access 1.x database objects, including macros and Access Basic code, can also be converted to 97 format. However, Access Basic code that relies on 16­bit DLLs and API calls must be modified to run in a 32­bit application. For more information, see "Porting Your 16-bit Office-Based Solutions to 32-bit Office" later in this chapter.

If you need to move Access 97 data to an Access 1.x database, Access 97 can export only tables. You cannot export any other database objects to the Access 1.x database, including queries, macros, forms, reports, and modules.

For more information about upgrading to Access 97, see Chapter 11, "Upgrading from Previous Versions of Microsoft Access."

Upgrading Microsoft Excel 4.0

Excel 97 can read documents saved in Excel version 4.0 format and save documents in Excel 4.0 format. Excel 97 can also run macros created in the Excel 4.0 XLM macro language; however, macros that make 16­bit DLL or API calls may require changes before they can be run in a 32­bit application. For more information, see "Porting Your 16-bit Office-Based Solutions to 32-bit Office" later in this chapter.

For more information about upgrading to Excel 97, see Chapter 12, "Upgrading from Previous Versions of Microsoft Excel."

Upgrading PowerPoint 3.0

PowerPoint 97 can open and save presentations in PowerPoint version 3.0 format. For more information about upgrading to PowerPoint 97, see "Upgrading from PowerPoint 3.0" in Chapter 14, "Upgrading from Previous Versions of Microsoft PowerPoint."

Upgrading Word 2.0

Word 97 can read documents saved in Word version 2.0 format, and save documents in Word 2.0 format. WordBasic macros in Word 2.0 templates are not supported in Word 97.

For more information about upgrading to Word 97, see Chapter 15, "Upgrading from Previous Versions of Microsoft Word."

Changes to your existing code are required if your 16­bit Office solutions (including those created for Access or Microsoft Project) call a 16­bit Windows application programming interface (API) or 16­bit Windows dynamic­link library (DLL), and you are porting that code to a 32­bit Office application (including Access 97 or Microsoft Project 97).

Porting your solution code is necessary because 16­bit API calls and 16­bit DLL calls (referred to in this section as API calls) do not execute correctly when the solution code containing those calls is run in a 32­bit Office application. This section applies to solution code that uses APIs in the following products: Access, Excel, Microsoft Project, and Word.

Note   If your 16­bit solutions continue to reside inside a 16­bit application, then they are not affected when you port them to 32­bit Windows. For example, existing 16­bit Office solutions, 16­bit Visual Basic, and 16­bit Microsoft FoxPro applications, even if they call 16­bit APIs, run just fine on Windows 95 or Windows NT operating systems. It is only when users want to run solutions code that includes 16­bit API calls on a 32­bit application that porting is required.

To ensure that Office­based solutions run successfully under the Windows 95 and Windows NT operating systems, solution providers and developers must follow this rule: neither a 32­bit compiled application nor solution code called from a 32­bit Office application can make direct 16­bit API or DLL calls. In addition, neither a 16­bit compiled application nor solution code called from a 16­bit application can make direct 32­bit API or DLL calls. This inability to make calls back and forth between 16­bit and 32­bit layers occurs in both the Windows 95 and Windows NT operating systems because of their advanced flat­memory­model management systems, as well as the way in which they load DLLs.

To prepare for Office 97, you must change your solution code to make Win32® API calls when the solution code is executed from 32­bit Office applications. If this is not possible (for example, you don't have access to the source code of the DLL), you must change the solution code to thunk through an intermediate DLL to make the 16­bit API call.

Updating solution code to support Win32 API calls is a relatively simple mechanical process. A more significant task is to write code that is operating­system­independent (that is, so the solution code runs on both 16­bit and 32­bit Office applications). This section discusses both of these tasks, as well as other 16­to­32­bit API issues you may need to handle.

Note   Although you must update API calls when porting solution code to 32­bit operating systems, you do not need to change code that uses OLE Automation or dynamic data exchange (DDE). All OLE and DDE code continues to work regardless of whether the applications are 16­bit or 32­bit. OLE and DDE insulate automation calls, so all combinations of containers (clients) and servers (16/16, 16/32, 32/16, and 32/32) work under Windows 95 and Windows NT operating systems.

How This Section Is Organized

The remainder of this section is organized in terms of complexity, from the simplest upgrading scenarios to the most complex.

• "Which API Should Your Solution Code Call?" is a quick overview of which API you should be using, according to your application needs.
• "Calling the Win32 API" describes what an API is and discusses the issues involved in converting existing 16­bit API calls to Win32 API calls, and finding and testing the Declare statements.
• "Writing a Single Code Base for 16-bit and 32-bit Office Applications" supplies code samples for writing solution code that runs on both a 16­bit and a 32­bit Office applications.
• "Determining Whether a 32-bit Application Is Running" describes how to determine whether your Office application is 16­bit or 32­bit and how to select the appropriate 16­bit or 32­bit API call.
• "Recompiling DLLs" tells you what to do to make the DLL and solution code work on Windows 95 and Windows NT operating systems if your solution code calls a custom DLL.
• "Thunking" tells you how, if you cannot recompile your DLLs, you can add an intermediate DLL.
• "Advanced Programming Topics" explains translating C­API declarations to Visual Basic or Visual Basic for Applications.

Which API Should Your Solution Code Call?

When you write solution code for your own use, you write it for the version of the Office application you have and for your operating system. Distributing this solution to others, however, means that you have to make it also work on their computers, which may use different versions of Windows and Office applications.

While the operating system isn't an issue, whether the Office application is 16­bit or 32­bit is important. The application, and not the operating system, determines which API you use in porting your solution code: you must use 16­bit APIs with 16­bit applications, and 32­bit APIs with 32­bit applications.

Note   Office (including 32­bit Access and 32­bit Microsoft Project) products do not run on Win32s®. Because FoxPro does run on this operating system, however, FoxPro programmers should use the same rules for choosing the API. Also, the Win32s, Windows NT, and Windows 95 operating systems do not have identical sets of API calls. For more information, see the Win32 SDK documentation in the Development Library (in particular, see the Compatibility Tables in the Win32 Programmer's Reference, Vol. 5).

Calling the Win32 API

To write calls to the Win32 API, you must do the following:

• Understand what Windows API calls are.
• Understand the differences between 16­bit and 32­bit Windows APIs.
• Use Win32api.txt to find the correct Declare statement.
• Test an API Declare statement.

What Is an API Call?

An API call in C, Visual Basic, or other languages places a series of values (parameters) at a location in memory (the stack) and then requests the operating system or DLL to execute a function (the procedure call) using the values provided. The function reads the values (call stack) and executes its function code using those values or the data that the values point to.

If a result is returned, it is placed at another location (return register) for the calling application to use. This is shown in the following illustration. To ensure accuracy, the number of bytes of data on the stack is verified before and after the procedure is called. The message "Bad DLL calling convention" appears when the wrong number of bytes are in the stack.

In practical terms, Windows API calls are how applications request services (screen control, printers, memory, and so forth) from the operating system. There are approximately 300 API calls in Windows 3.0, over 700 API calls in Windows 3.1, and over 1,000 API calls in Windows 95. These API calls are packaged in executable files and DLLs found in the Windows folder — User.exe, Gdi.exe, and one of the following
KERNEL files: Krnl286.exe, Krnl386.exe, or Kernel32.dll.

To call an API from your solution code, use these four steps:

1. Identify the file containing the API.
2. Determine the parameters required by the API.
3. Create a Declare statement for the API.
4. Call the function with valid parameters.

The following is a simple example for the GetVersion API call that obtains the version of Windows that is running. The GetVersion API call is located in KERNEL under 16­bit Windows and does not use any parameters (so the Declare statement has empty parentheses). The following Declare statement is written for 16­bit Windows for use by Visual Basic for Applications:

Declare Function GetVersion Lib "KERNEL" () As Long

By comparison, here is the same function as it would be used by an Office 97 application running on 32­bit Windows:

Declare Function GetVersion Lib "KERNEL32" () As Long

Although the Windows API name stays the same, the location of the API has changed to KERNEL32. Because you are calling from a 32­bit application, you must make a 32­bit API call. The parameter data type, on the other hand, did not change (it remained a Long). In general, the function parameters change more and require more attention than the parameters of the return value. Understanding the differences between 16­bit API calls and 32­bit API calls is essential to porting your solution code to Windows 95.

What Are the Differences Between a 16­bit and a 32­bit Windows API?

As shown in the previous example, most 32­bit Windows API calls have the same name or a very similar name to the 16­bit API calls. In fact, the documentation may show the same arguments, with the only apparent difference being the library name change from KERNEL to KERNEL32. However, the code must handle the following changes in addition to the name change:

• Case­sensitivity
• Unicode or ANSI options
• Change of parameter data type (shown in the previous example)

These items can require subtle changes in the Declare statements that are not always easy to identify.

Case Sensitivity

The first issue in moving to 32­bit Windows API calls is case sensitivity in the name of the function. API calls under 16­bit Windows are not case sensitive and work if you enter the function name as GetVERSION, GeTvErSiOn, or getversion. In other words, in 16­bit Windows the following statements are equivalent:

Declare Function GetVersion Lib "KERNEL" () As Long
Declare Function GeTvErSiOn Lib "KERNEL" () As Long

API calls under 32­bit Windows, however, are case­sensitive for the function call and must be correctly entered in the Declare statement. In other words, the following statements are not equivalent in 32­bit Windows:

Declare Function GetVersion Lib "KERNEL32" () As Long
Declare Function GeTvErSiOn Lib "KERNEL32" () As Long

The easiest way to handle this change is to always use the Alias control word. The contents of an Alias string map to the actual API call name (which is case sensitive), but the function name used in code, which appears between Function and Lib, is not case sensitive and does not change if you type it different ways in your code or use the same name for variables or procedures. Using the Alias control word, the GetVersion function (32­bit Windows) would be entered as:

Declare Function GetVersion Lib "KERNEL32" Alias "GetVersion" () As Long

The case of API names doesn't matter when writing code: as long as you enter the function name correctly in the Alias string, and you spell the function name in code the same way as in the Declare statement, the function is automatically mapped by Visual Basic or Visual Basic for Applications back to the correct Declare function.

Note   The Alias control word is the single most important thing you can use in preparing to switch to 32­bit operating systems because it means you only have to change the contents of the Declare statement and not every instance of the function being called in your code.

Unicode or ANSI Options

Both the Windows NT and Windows 95 operating systems have two API interfaces. One interface is based on the American National Standards Institute (ANSI) character set, where a single byte represents each character. The other interface was created for the Unicode character set, where two bytes represent each character. All 16­bit Windows operating systems and applications use the ANSI character set. All 32­bit versions of Windows add Unicode to allow foreign language characters to be represented. C programmers handle this by setting a flag in their include file (*.h). The flag causes hundreds of macros throughout the C include files to select the correct Unicode or ANSI functions. All western language versions of Office products use ANSI for Visual Basic for Applications code. Therefore, programmers using current versions of Visual Basic for Applications or other macro languages should always use the ANSI version of the API call. When using the Win32api.txt file, this choice is made for you. For more information about this file, see "Change of Parameter Data Type," later in this section. To distinguish the ANSI version from the Unicode version, the ANSI version adds an A to the end of the API name, and the Unicode version adds a W. (W is for wide, as in the width of the bytes provided for characters.) The name of an API call includes either the character A or W at the end of the API name only if the API requires parameters with string (character) data types.

The Win32 SDK documentation in the Development Library does not record the permutations of the name of the API call. The documentation gives only the name of the root function and its library name. The actual name of the API in the library can be one of the following:

• MyAPICall, which uses no character strings in the call.
• MyAPICallA, which uses ANSI character strings in the call.
• MyAPICallW, which uses Unicode character strings in the call.

To understand the differences, see the following diagram showing the amount of data the API expects to find on possible call stacks for an example function (the 16­bit version is padded because 16­bit Windows always pads the stack to 16 bits).

The three possible declarations for MyAPICall are shown in the following example, organized to make comparison easier. All of the statements use the Alias control word so that the function name used in code (MyAPICall) does not have to change even if the name of the function called is appended with an A or a W:

'16 bits
Declare function MyAPICall Lib "MYDLL.DLL" Alias "MyAPICall" (
	ByVal hwndForm As Integer,
	ByVal lpstrCaption$,
	ByVal hAccKey As String,
	 ByVal iMagicNumber As Integer
	) As Integer
'32­bit ANSI
Declare function MyAPICall Lib "MYDLL32.DLL" Alias "MyAPICallA" (
	ByVal hwndForm As Long,
	ByVal lpstrCaption$,
	ByVal hAccKey As String,
	ByVal iMagicNumber As Long
	) As Long
'32­bit UNICODE * For illustration only.
Declare function MyAPICall Lib "MYDLL32.DLL" Alias "MyAPICallW" (
	ByVal hwndForm As Long,
	ByVal lpstrCaption$,
	ByVal hAccKey As String,
	ByVal iMagicNumber As Long
	) As Long

Any one of these declarations would add the function MyAPICall to your application; you can only have one MyAPICall function.

This code sample introduces the ByVal keyword, which allows you to pass Visual Basic parameters to a API function by value. By Value is the default for functions written in C and is therefore the default for Windows API calls. The reason you must use ByVal is that Visual Basic and Visual Basic for Applications default to ByRef (By Reference passes a pointer to the value rather than the value itself), which is not what API calls expect. ByVal can also be used to convert a Visual Basic string to a null­terminated C string. ByVal is included in the Declare statements in Win32api.txt, so you know when to use it.

Note   For more information about ByVal, see the Microsoft Developer Network (MSDN) article Q110219 How to call Windows API from VB, or published references such as PC Magazine Visual Basic Programmer's Guide to the Windows API by Dan Appleman, published by Ziff­Davis Press.

Change of Parameter Data Type

The easiest way to get the new required parameter data types for 32­bit API functions is to copy the appropriate API Declare statement from Win32api.txt into your source code.

Another source of information is the Win32 Programmer's Reference on the MSDN Development Library CD, which is discussed in "Advanced Programming Topics" later in this section. This reference may occasionally be required to resolve questions about the inclusion or exclusion of ByVal in the declaration or the need to put parentheses around the actual value passed.

If you use the Win32 Programmer's Reference, however, you must be careful to properly convert C to Visual Basic data types. For example, don't mistake a C int for a Visual Basic for Applications Integer. Many Windows data types and Visual Basic Integer data types are no longer the same size, as shown in the following table. It is critical to remember that the sizes of many API parameters have changed, and you must not assume they are the same.

Finally, whether you use Win32api.txt or the Win32 Programmer's Reference, judicious use of the Alias control word may assist you in changing parameter data types by allowing existing 16­bit code that calls the API to be left unchanged. The ByVal control word and automatic type conversion in Visual Basic, Access Basic, WordBasic, and Visual Basic for Applications change the size of parameters for you in many cases (Integer to Long, for example). Alternatively, type conversion extends integers with a sign (+/ – ) that may lead to incorrect long parameters and cause overflows on conversion from Long to Integer. Again, the best solution is to check Win32api.txt or the Win32 Programmer's Reference to get the correct functions.

What Types of Errors Can Occur with an API Declare Statement?

After you create a Declare statement, it may not work. While there are many mistakes possible in a Declare statement, the following are the most common errors:

• Error 453: Function is not defined in specified DLL

  Either you misspelled the function name or you have a problem with case in the function name. Functions are case­sensitive in Win32; they are not case­sensitive in 16­bit Windows.

• Error 48: Error in loading DLL

  Usually, this error is caused by having the wrong size or arguments, but it may also occur for some of the reasons described under Error 53.

• Error 53: File Not Found

  Windows checks the loaded libraries for matches; if the DLL is not loaded, Windows attempts to load the DLL from disk. Many functions available in the 16­bit Windows on Windows (WOW) layer on Windows NT Server are not available directly on Windows NT Workstation.

  Calling the 16­bit Windows and Win32 GetProfileString function from a 16­bit and a 32­bit solution gives a confusing set of error messages. The 16­bit application call finds KERNEL and fails to find KERNEL32, while the 32­bit application finds KERNEL32 and fails to find KERNEL. The general cause of this error is a mismatch of calls and operating systems. The solution is to write code that works in both 16­bit and 32­bit environments.

Writing a Single Code Base for 16­bit and 32­bit Office Applications

If users in your workgroup are running both 16­bit and 32­bit versions of an Office application — Excel 5.0 and 97, for example — should you put the 16­bit API call or the 32­bit API call in your solution? Excel, for example, is not like Visual Basic version 4.0, which allows conditional compilation of code into the executable files, but instead runs solution code in workbook files which may be opened in either the 16­bit or the 32­bit version of the application. The solution is to put both the 16­bit API call and the 32­bit API call inside an If...Then...Else control structure.

With 32­bit applications using the same solution code as 16­bit applications, you do not know which API to call in the solution code. Your code must determine whether the application is 16­bit or 32­bit in order to make the correct API call. Each application makes this determination using a set of different questions:

• Access

  Is the host application 16­bit Access 2.0 or earlier, or 32­bit Access 95 or 97?

• Excel

  Is the host application 16­bit Excel 5.0 or earlier, or 32­bit Excel 5.0 for Windows NT operating system or 32­bit Excel for Windows 95 or 97?

• Microsoft Project

  Is the host application 16­bit Microsoft Project version 3.0, or 32­bit Microsoft Project version 4.0 or later?

• Word

  Is the host application 16­bit Word 6.0 or earlier, or 32­bit Word 6.0 for Windows NT or Word for Windows 95 or 97?

If you make the wrong API call, an error occurs. The solution code must determine whether the application is a 16­bit application or a 32­bit application, so it can make the appropriate call.

The solution is to put every API call into a wrapper — a Visual Basic procedure or an Excel 4.0 macro. This wrapper routinely checks the bitness of the application and selects the appropriate API call. Place these wrappers in separate modules so that your code can be easily reused. Some API calls (for example, GetPrinterDriveDirectory and GetWinMetaFileBits) are not available in all 32­bit operating environments, which means that the structure of an API wrapper can become as complex as this:

Function MyAPICall$(ByVal Args)
	If Engine32() Then
		'Select is rarely needed
		Select Case OS32() 'Based on GetVersionEx API
		Case 0 'Win32s
			....
		Case 1 'NT 3.1
			....
		Case 2 'NT 3.5
			....
		Case 3 'Windows 95
			....
		End Select
	Else '16­bit
		....
	End If
End Function

An API wrapper this complex is the exception, however, and not the rule.

Compiled languages, such as FoxPro and Visual Basic, build 16­bit or 32­bit application executable files. The executable file targets either 16­bit API calls or 32­bit API calls. You can determine the appropriate API calls while building the application. You can select the calls in one of two ways: either by having all the 16­bit declarations in one file and all the 32­bit declarations in another file and manually switching them in a project; or by using the #IF... #ELSE... directives and conditional compilation supported by Visual Basic 4.0.

If you must support Visual Basic version 3.0 and Visual Basic 4.0 applications concurrently, separate files may reduce code maintenance. If you support FoxPro, you have no problem using 16­bit API calls from compiled 32­bit FoxPro solutions because the RegFN functions automatically thunk from the 32­bit layer to the 16­bit layer if needed.

Compiled 32­bit languages may require some minor differences in API calls depending on the 32­bit operating system. For example, developers must program context menus differently for Windows 95 than for Windows NT operating systems.

Determining Whether a 32­bit Application Is Running

In the previous section, writing application­independent code is achieved by adding code for both 16­bit and 32­bit scenarios. However, you still need to determine in source code whether the application is a 32­bit application or a 16­bit application.

The code in the following examples determines whether these are 32­bit applications.

• In Excel 5.0, Excel 95, Excel 97, Microsoft Project 4.0, Microsoft Project 95, or Microsoft Project 97:

  Function Engine32%()
  	If instr(Application.OperatingSystem,"32") then Engine32%=True
  End Function
  
  
  

• In Word 6.0, Word 95, or Word 97:

  Function Engine32
  	If Val(GetSystemInfo$(23)) > 6.3 Or Len(GetSystemInfo$(23))= 0 _
  		Then Engine32 = ­ 1 Else Engine32 = 0
  End Function
  
  
  

• In Access 1.1 or higher:

  Function Engine32% ()
  If SysCmd(7) > 2 Then Engine32% = True
  End Function
  
  
  

Note   The Application.OperatingSystem property in Excel and Microsoft Project does not return the version of Windows you have installed, but the layer of Windows that the application is running on, for example, the 16­bit subsystem in Windows NT Workstation.

Putting It All Together

For examples of code for particular applications, you should consult the MSDN, and find the article entitled Corporate Developer's Guide to Office 95 API Issues. For information about connecting to MSDN, see "Microsoft Developer Network" in Appendix E, "Other Support Resources."

The following simple example may help you understand some issues.

Declare Function GetTickCount32 Lib "KERNEL32" Alias "GetTickCount" () _
	As Long
Declare Function GetTickCount16 Lib "USER" Alias "GetTickCount" () _
	As Long

Function GetRightTickCount() As Long
If Engine32%() Then
	GetRightTickCount = GetTickCount32()
Else
	GetRightTickCount = GetTickCount16()
End If
End Function

In this example, the GetTickCount API has the same name for both 16­bit Windows and 32­bit Windows, so you must use an Alias control word to change the function name in at least one of the Declare statements. In the example, the names in both Declare statements are changed to GetTickCount32 and GetTickCount16. Next, depending on the application's bitness, GetTickCount is mapped to the correct API function name (GetTickCount32 or GetTickCount16) and its associated API call. In this example, GetTickCount in your code is mapped to GetTickCount32 (in the GetTickCount function), which is in turn mapped to GetTickCount in KERNEL32, when Engine32% is True.

Word Sample Declare­Method Solution

Word has a different Declare format and syntax. The Word solution is more complex because you cannot place both the 16­bit and 32­bit Declare statements in the same macro. The solution is to create three macro libraries: APICALL16 and APICALL32, which contain the Declare statements for each operating environment; and a 16­bit/32­bit interoperability macro, APICALLS.

First, create a macro library called APICALL16. This macro contains all the 16­bit API Declare statements.

 'This is APICALL16 ­­ all 16­bit Declare statements are placed here.
Declare Function GetTickCount16 Lib "USER" Alias "GetTickCount"() _
	As Long
Function GetTickCount
GetTickCount = GetTickCount16
End Function

Second, create a macro library called APICALL32. This macro contains all the 32­bit API Declare statements.

'This is APICALL32 ­­ all 32­bit Declare statements are placed here.
Declare Function GetTickCount32 Lib "KERNEL32" Alias "GetTickCount"() _
	As Long
Function GetTickCount
GetTickCount = GetTickCount32
End Function

Third, create a macro library called APICALLS. This macro contains Engine32 and the procedures your solution code calls.

'This is APICALLS ­­ no Declare statements may be in this macro.
Function Engine32
Engine32 = 0
If Val(AppInfo$(2)) > 5 Then
   OS$ = GetSystemInfo$(23)
   If Val(OS$) > 6.3 Or Len(OS$) = 0 Then Engine32 = ­ 1
End If
End Function

Function GetTickCount
If Engine32 Then
   GetTickCount = APICall32.GetTickCount
Else
   GetTickCount = APICall16.GetTickCount
End If
End Function
'Other API function calls are placed here.

You can now call this function from your solution code. You must preface your calls with APICALLS. For example:

Sub MAIN
MsgBox Str$(APICalls.GetTickCount)
End Sub

To convert Word solutions to run on 16­bit and 32­bit products

1. Create a new module called APICALLS.
2. Create the Engine32 function in APICALLS.
3. Create a new module called APICALL16.
4. Locate all the 16­bit Declare statements in the solution and move them to APICALL16.
5. Create a new module called APICALL32.
6. Create the equivalent 32­bit Declare statements and put them to APICALL32.
7. Using the preceding template, create functions for each API in each of the three macro libraries.
8. Add APICALLS before all calls to the API in your solution code.
9. Test each function.

This process allows existing calls in other modules to be left untouched. After the developer defines and tests these macros, the developer can add them to Normal.dot and reuse the macros in other solutions so as to cut conversion time.

Recompiling DLLs

This section has so far focused on the issue of updating Windows API calls — but the issues for solution code that calls 16­bit DLLs that you have bought, developed, or used is exactly the same. The developer must change all 16­bit DLL Declare calls in solution code to 32­bit calls. This requires creating a 32­bit version of the DLL (at least) and possibly changing the Declare statement (or, in Excel 4.0 macros, the Register function).

This also means a separate DLL must exist for both the 16­bit application and the 32­bit application. For file management, the name of the 32­bit DLL should include 32 at the end. The developer must recompile the DLL as a 32­bit Ansi.dll. The parameters passed to the DLL must use the stdcall­passing protocol to talk to 32­bit Visual Basic for Applications, instead of the PASCAL­passing protocol used with 16­bit Windows. Place the calls for the 16­bit and 32­bit versions of the DLL in a wrapper similar to the API wrapper described previously.

For more information about recompiling applications, see Chapter 1, "Porting 16­bit Code to 32­bit Windows," in Programming Techniques from the Microsoft Visual C++® version 2.1 documentation in the Development Library, or see your C compiler documentation.

Thunking

When you do not have the source code of a DLL, your solution is to use thunking to port your solution to Windows 95. Thunking enables direct 16­bit and 32­bit calls but requires much more work than simply changing the Windows API call. If you cannot change or recompile the 16­bit DLL, you must write a new 32­bit DLL wrapper to access the 16­bit DLL. The 32­bit application calls to this 32­bit wrapper DLL, which then calls the original 16­bit DLL.

Thunking allows parameters to be pushed correctly on the stack, enables a DLL of a different bitness to load in your process, and converts memory addresses from offset (32­bit) to segment::offset (16­bit). Even if you do the thunking work, however, some issues remain. For example, pointers to memory locations require additional work in 16­bit and 32­bit scenarios.

There are several ways to thunk, depending on your operating system: Windows 95 and Windows NT thunk differently. For an overview of thunking across the Windows operation systems, as well as references to more information about thunking, see Diving into the Requirements for the Windows 95 Logo in the Development Library.

Advanced Programming Topics

Most developers writing solution code know the C language, and the following information is provided to assist them in using their knowledge of C to create Declare statements for Visual Basic and Visual Basic for Applications using the tools they already have.

Working from C Declarations

Apart from the API location changing (from KERNEL to KERNEL32), the main issue in moving from 16­bit API calls to 32­bit API calls is the change in the size of parameter data types. Some background information may help you understand what has changed and why. Windows 3.x was designed for the Intel 80286 CPU, where the hardware handles data two bytes at a time, or in 16­bit words. Windows 95 was designed for later CPUs, where the hardware can handle data four bytes at a time, or in 32­bit words. The following list shows how Visual Basic represents an Integer as opposed to how Windows represents an int:

• Integer and int are each two bytes in the 16­bit Windows operating system and in 16­bit Excel, Visual Basic, Access, Word, and Microsoft Project.
• Integer is two bytes in 32­bit Excel, Visual Basic, Access, Word for Windows, and Microsoft Project.
• int is four bytes in the 32­bit Windows operating systems, Windows 95, and Windows NT.

To illustrate how this change in size can affect a call, recall the fictional MyAPICall API used earlier. The MyAPICall call needs the handle to the application's window (HWND), a string, a character, and an integer to be placed on the stack. In C, the function would be:

int MyAPICall (HWND hwndForm, LPSTR lpstrCaption, TCHAR tchAccKey, _
	int iMagicNumber)

Each parameter has two parts: the data type (HWND, LPSTR, TCHAR, int) and the field name (hwndForm, lpstrCaption, tchAccKey, iMagicNumber). Each data type requires a specific number of bytes to represent it. Each field name has some odd­looking characters as a prefix — these characters (known as Hungarian notation) indicate the data type, such as int or lpstr.

Windows has many data types that API calls use as parameters. The following table shows some of the more significant data types used by Windows 95 API calls. Many Windows data types use the C data type of int. (When int changed from 16­bits to 32­bits, the related Windows data types also changed.)

Thus, converting the MyAPICall API call from C, the declarations for MyAPICall using Visual Basic for Applications, Access Basic, or WordBasic would be as follows (organized to make comparison easier):

'16 bits
Declare Function MyAPICall Lib "MYDLL.DLL" Alias "MyAPICall" (
	ByVal hwndForm As Integer,
	ByVal lpstrCaption As String,
	ByVal hAccKey As String,
	ByVal iMagicNumber As Integer
	) As Integer
'32 bits
Declare Function MyAPICall Lib "MYDLL32.DLL" Alias "MyAPICall" (
	ByVal hwndForm As Long,
	ByVal lpstrCaption As String,
	ByVal hAccKey As String,
	ByVal iMagicNumber As Long
	) As Long

A final tool you may find useful is the following table, which maps C language declaration data types to their Visual Basic equivalents.

Visual Basic data type	Size of variable	Corresponding 16­bit Windows data types	Corresponding 32­bit Windows data types
Integer	2 bytes	int, short, WORD, HWND, HANDLE, WCHAR	short, WCHAR
Long	4 bytes	long, LPSTR	int, long, HANDLE, HWND, LPSTR
C data type	Size in Windows 3.x and Windows for Workgroups 3.x (16­bit)	Size in Win32s, Windows NT operating system, and Windows 95 (32­bit)
unsigned int, UINT, int	2 bytes	4 bytes
short	2 bytes	2 bytes
long	4 bytes	4 bytes
char, CHAR	1 byte	1 byte
WORD	2 bytes	2 bytes
Handle (hWnd, hDC, hMenu)	2 bytes	4 bytes
LPSTR	4 bytes	4 bytes
WCHAR	2 bytes	2 bytes
TCHAR (ANSI or Unicode)	1 byte	1 or 2 bytes
POINT	4 bytes	8 bytes
C language declaration data type	Visual Basic equivalent	Called with this variable
Boolean	ByVal B As Boolean	Any Integer or Variant variable
Pointer to a string (LPSTR)	By Val S As String	Any String or Variant variable
Pointer to an integer (LPINT)	I As Integer	Any Integer or Variant variable
Pointer to a long integer (LPDWORD)	L As Long	Any Long or Variant variable
Pointer to a structure (for example, LPRECT)	S As Rect	Any variable of that user­defined type
Integer (INT, UINT, WORD, BOOL)	ByVal I As Integer	Any Integer or Variant variable
Handle (32 bit, HWND)	ByVal H As Long	Any Long or Variant variable
Long (DWORD, LONG)	ByVal L As Long	Any Long or Variant variable
Pointer to an array of integers	I as Integer	The first element of the array, such as I(0)
Pointer to a void (void*)	V As Any	Any variable (use ByVal when passing a string)
Void (function return value)	Sub Procedure	Not applicable
NULL	As Any	ByVal 0&
Char (TCHAR)	ByVal Ch As String	Any String or Variant variable
Using the Win32 Programmer's Reference The two primary sources for Win32 API information are the Win32 Programmer's Reference and a list of Microsoft­supplied Win32 Declare statements for Visual Basic, such as Win32api.txt. The Development Library contains a listing with explanations of the entire Win32 API set in the Win32 Programmer's Reference. For more information about the Development Library, see "Microsoft Developer Network," in Appendix E, "Other Support Resources."