MORE INFORMATION
Introduction
Microsoft RPC version 1.0 is a toolkit for developing network-aware
distributed applications in C/C++. The RPC toolkit includes:
- MIDL compilers for Microsoft Windows NT and Microsoft Windows 3.x.
- C/C++ language header files (.H) and run-time libraries (.LIB and .DLL)
for Microsoft Windows NT, Microsoft Windows 3.x, and MS-DOS.
- Sample programs for Microsoft Windows NT, Microsoft Windows 3.x,
Microsoft Windows for Workgroups, and MS-DOS.
- RPC reference Help files, Windows Write files, and PostScript files.
The Win32 SDK contains the Microsoft Windows NT and Microsoft Windows 3.x
versions of the RPC SDK.
Installation
The Microsoft Win32 SDK installs the components of the Microsoft RPC
toolkit as part of its standard installation. No additional installation is
required.
To develop client-side distributed applications for MS-DOS, Microsoft
Windows 3.x, and Windows for Workgroups version 3.1, you must install the
Microsoft Windows 3.x/MS-DOS version of the RPC toolkit. Cross-compilation
of Windows version 3.x and MS-DOS clients with Microsoft Windows NT
requires a 16-bit C compiler in the Microsoft Windows NT environment. This
development environment is not installed during RPC SDK setup. The
Microsoft RPC toolkit for MS-DOS and Microsoft Windows 3.x requires:
- A 16-bit compiler such as Microsoft Visual C++ Development System
for Windows or the Microsoft C/C++ 7.0 compiler.
- One of the following:
- Microsoft Windows for Workgroups version 3.1 (or later) with named
pipes, NetBIOS, or TCP/IP.
-or-
- Microsoft LAN Manager version 2.1 (or later) with named pipes,
NetBIOS, or TCP/IP.
-or-
- DEC PATHWORKS 4.0 (or later) with NetBIOS, TCP/IP, or DECNet.
-or-
- Novell Netware 3.x with SPX.
-or-
- Other networking software compatible with the Windows Sockets API
standard.
To install the Microsoft Windows 3.x/MS-DOS version of the RPC toolkit, run
the Setup program in the directory MSTOOLS\RPC_DOS. To start the Setup
program, choose the Run command from the File menu in the Microsoft Windows
3.x Program Manager.
When you install the RPC toolkit in a directory different from the
directory you used for Microsoft C/C++ version 7.0, you must set the
environment variables INCLUDE, LIB, and PATH to point to the directories
that contain the RPC header files, libraries, and DLLs and binaries,
respectively. You cannot install the RPC toolkit in the same directory as
the Visual C++ compiler binaries because of name conflicts.
RPC Documentation
The following Microsoft RPC version 1.0 reference materials are available
in Windows Write format and in PostScript file format:
Microsoft RPC Programmer's Guide and Reference:
- Part I: Programmer's Guide
- Part II: MIDL Language Reference
- Part III: Run-Time API Reference
- Part IV: Installing RPC
- Part V: Appendixes
Use the PostScript files to print individual chapters of the documentation
on your PostScript printer.
The following run-time and MIDL reference Help file is available on line:
RPC.HLP WinHelp MIDL and run-time API reference
RPC sample-program source files are available in the directory
MSTOOLS\SAMPLES\RPC. MS-DOS and Microsoft Windows 3.x versions of some
samples are available when you install the Windows 3.x/MS-DOS version of
the RPC toolkit. The file MSTOOLS\SAMPLES\RPC\README.TXT describes the
available samples.
Release Notes for MIDL compiler
1.0 The following release notes relate to the MIDL compiler and to building
distributed applications.
1.1 Packing and Alignment Considerations
You must use the same packing and alignment settings (/Zp switch) for both
the C compiler and the MIDL compiler. Using different packing levels for
the two compilers causes undefined results. Specify the /Zp switch to
verify that the correct packing and alignment settings are used on both
compilers.
This release of the MIDL compiler does not support the switches /Zp1 and
/Zp2 in the MIPS environment, although the compiler does not prevent the
use of /Zp1 and /Zp2.
Use /Zp1 or /Zp2 for 16-bit client platforms. Objects of types with natural
alignment greater than 2 that are allocated on the stack as local variables
in the client application are not necessarily allocated on 4- and 8-byte
boundaries by the C compiler. Because the C compiler does not guarantee
alignment on the stack, marshaling from and unmarshaling into such
objects may cause problems.
Generic stubs (/env generic) must be specified with /Zp1 or /Zp2 in 16-bit
client environments. Generic stubs specified with /Zp1 or /Zp2 cannot be
used in the MIPS environment. MIDL uses /Zp4 by default for generic stubs.
1.2 C Stub Source Code Causes Compilation Warnings
The stub files generated by the MIDL compiler may generate warnings when
they are compiled at compiler warning-level 3 and higher. These warnings
can generally be safely ignored.
When your C compiler does not use the same default character sign as the
MIDL compiler, use the MIDL compiler switch /char to generate explicit
declarations in the header file. For more information, see the Microsoft
RPC programming documentation.
1.3 Use Six-Character Filenames on the FAT File System
Because RPC version 1.0 appends _C, _X, and similar extensions to
filenames, limit your filenames to six characters or less. Filenames that
total more than eight characters are too long for some file systems and can
fail.
1.4 Specifying Local and UUID Attributes
If the base IDL file contains no procedures, you don't have to specify
local or UUID attributes.
1.5 MIDL Extra Server Files in the Windows 3.x/MS-DOS Environment
MIDL does not produce server files in the Windows 3.x/MS-DOS environment.
For this reason, if you specify the /env switch as /env dos or /env win16,
server stubs are not produced. To produce server stubs, specify that the
/env switch is either /env win32 or /env generic.
1.6 Working with Visual C++ on 16-Bit Machines
Do not install the 16-bit RPC toolkit in the same directory as Visual C++.
MIDL requires the Microsoft C 7.0 front end for C preprocessing. The
installer will install the Microsoft C 7.0 front end if needed. Use the
/cpp_cmd switch to make sure MIDL is using the right C compiler.
1.7 Memory Leak Possible with Multiple Context Handles
Memory can leak when data argument(s) precede context-handle argument(s)
and the call is directed by another handle. The leak happens on the server
side if the data requires memory allocation and if the context handle that
is used (as opposed to initialized) is invalid. The stub raises an
exception as it is supposed to, but it doesn't do the clean up.
1.8 Use Zero or Positive Values for the size_is and length_is Variables
You must use a zero or a positive value for the size_is and length_is
variables. A negative value for the size_is or length_is variable causes an
exception.
1.9 RPC Cannot Pass More than 63K Worth of Data on 16-Bit Platforms
An MS-DOS or Windows 3.x system cannot pass more than 63K worth of data in
a single remote procedure call. Trying to pass more than 63K worth of data
results in undefined behavior.
1.10 Windows 3.x Applications Using the [callback] Attribute
If you use the [callback] attribute for a procedure specified in the IDL
file and if your application runs with Windows 3.x, you must compile all
stubs with the /GA C-compiler switch. Note that the /GA switch should not
be used for Windows callback functions (as opposed to RPC callback
functions) that are called in the context of another process.
1.11 Building RPC Samples with Visual C++ for Microsoft Windows NT
You can build RPC applications with the Visual C++ SDK for Microsoft
Windows NT using the RPC*.H files distributed with that SDK. To build RPC
samples with Visual C++ for Windows NT, add the following definition to
RPC.H (this applies to Intel processors only):
#define _CRTAPI1 _cdecl
Release Notes for RPC Run-Time/Transport Libraries & Windows NT Services
2.0 The following release notes are related to the RPC run-time libraries,
transport libraries, and Windows NT services provided with Microsoft RPC
version 1.0.
2.1 RpcServerUseAllProtseqs Requires a Null Security Descriptor
The RpcServerUseAllProtseqs security-descriptor parameter must be set to
NULL in this release of Microsoft RPC version 1.0. The null parameter
allows everyone access.
2.2 Named-Pipes Security Descriptor
Named pipes (ncacn_np) allows everyone access when a null security
descriptor is supplied. This accessibility is independent of whether or not
the account used to start the server has a default ACL.
2.3 Multiple Networks
The Microsoft Locator does not work with a router.
2.4 RpcNsBindingExport IP Addresses
If a server has two IP addresses and as a result is on two subnets,
RpcNsBindingExport adds only one of the two addresses to the name service.
For this reason, clients on one of the two networks cannot import a valid
handle to that server. Clients that already know the server address will
work using either well-known or dynamic endpoints.
2.5 SPX Transport Limitations
The MS-DOS SPX transport does not function in a Windows DOS box or Windows
NT DOS box. The Windows SPX transport does not function in Windows standard
mode or in emulation mode with Windows NT.
2.6 All Machines Must Use the Same SPX Packet Size
To use the ncacn_spx protocol sequence (RPC over SPX), both the client and
the server must use the same maximum IPX packet size. Otherwise,
multipacket RPC calls will fail with RPC_S_CALL_FAILED. To adjust the
packet size on a machine running MS-DOS, Windows 3.x, or Windows for
Workgroups, add the following line to your NET.CFG or SHELL.CFG file:
IPX PACKET SIZE LIMIT=xxxx
Here xxxx is the packet size in bytes.
Consult your Novell documentation for more information. Note that some
older drivers do not support setting IPX PACKET SIZE LIMIT.
To adjust the maximum packet size on machines running Windows NT, use
REGEDT32.EXE to set HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Services\NWLINKIPX\NetConfig\Driver01\MaxPktSize to the proper value.
Consult the Windows NT Resource Kit for more information on the registry.
2.7 Windows 3.x Applications Using TCP/IP Must Call RpcWinSetYieldInfo
Applications based on Windows 3.x that use TCP/IP (ncacn_ip_tcp) must call
the RpcWinSetYieldInfo routine. Applications making RPC calls that don't
call RpcWinSetYieldInfo will always hit an exception. The exception occurs
because Windows Sockets API standard requires that applications yield while
using the network.
2.8 When Writing MS-DOS Applications, Avoid Calling _exit Directly
Always write your RPC applications for MS-DOS to call the complete
C-library termination function exit or _cexit rather than the quick
C-library termination function _exit or _c_exit because the
quick-termination functions do not call the atexit function. The MS-DOS
RPC run-time libraries use the atexit function to clean up system
resources. When you call the _exit or _c_exit function, the atexit function
is not invoked and resources are not freed correctly.
Release Notes for Installation & Configuration Issues for This Release
3.0 The following release notes are related to installation and
configuration issues for this release:
3.1 Using Microsoft RPC with Microsoft Windows for Workgroups
To successfully run Microsoft RPC distributed applications with Microsoft
Windows for Workgroups version 3.1, you must use the Windows for Workgroups
network services. Stop all real-mode network services before starting
Windows for Workgroups. At the MS-DOS prompt, type:
net stop workstation /y
win
3.2 Creating Installation Disks for Your Distributed Application
After you have developed your distributed application using Microsoft RPC,
you should provide a way for your users to install your application.
To enable your users to install your application, perform the following
steps when installing RPC:
- Copy your executable files.
- Copy Microsoft RPC run-time and transport DLLs.
- Set Microsoft RPC-related registry entries as needed.
To provide an installation tool for your users, use the Microsoft Setup
Toolkit for Windows. Microsoft Setup provides important version-control
features that prevent users from overwriting newer versions of the RPC run-
time libraries with older, incompatible versions.
You can also use the template batch files provided with Microsoft RPC for
MS-DOS and Windows 3.x to help your users install your distributed
applications. The files DRUNDISK.BAT and WRUNDISK.BAT copy the Microsoft
RPC Setup program and associated files and direct the Microsoft RPC Setup
program to install all needed RPC system files. You must customize the .INF
file for your application. For more information about changing the .INF
file, see the documentation for the Microsoft Setup Toolkit for Windows.
If you use another installation method, you should implement some form of
version control. Version-control methods ensure that you do not distribute
incompatible versions of the RPC run-time and transport libraries that can
cause software errors in your application and other applications.
Some files include an embedded version-control number for use by the Setup
Toolkit for Windows. These files are noted in the lists below.
The following Microsoft Windows 3.x RPC files should be installed in the
system directory or in a directory specified by the LIBPATH environment
variable:
DNETAPI.DLL Non-Microsoft environments for DEC PATHWORKS
interoperability with Microsoft LAN Manager
NETAPI.DLL Microsoft LAN Manager transport DLL; has version number
for use with Microsoft Setup
RPCNS1.DLL Microsoft RPC name-service provider
RPCRT1.DLL Microsoft RPC client run-time library
RPC16C1.DLL RPC transport DLL for client-side named pipes
RPC16C3.DLL RPC transport DLL for client-side WinSock TCP/IP
RPC16C3X.DLL RPC transport DLL for client-side WSOCKETS.DLL TCP/IP
RPC16C4.DLL RPC transport DLL for client-side DECnet
RPC16C5.DLL RPC transport DLL for client-side NetBIOS
RPC16C6.DLL RPC transport DLL for client-side SPX
The following MS-DOS RPC files should be installed in a directory that is
specified by the PATH environment variable:
RPCNS.RPC Microsoft RPC name-service provider
RPCNSLM.RPC Microsoft RPC name-service provider LAN Manager support
RPCNSMGM.RPC Microsoft RPC name-service provider support module
RPC16C1.RPC RPC transport DLL for client-side named pipes
RPC16C3.RPC RPC transport DLL for client-side TCP/IP
RPC16C4.RPC RPC transport DLL for client-side DECnet
RPC16C5.RPC RPC transport DLL for client-side NetBIOS
RPC16C6.RPC RPC transport DLL for client-side SPX
You need not install the Microsoft Windows NT versions of the Microsoft RPC
run-time libraries and transports. Microsoft Windows NT computers support
Microsoft RPC version 1.0. If you want to run Microsoft Windows 3.x or
MS-DOS RPC applications with Microsoft Windows NT, install the above RPC
DLLs on the system.
Setting RPC Registry Entries
Your installation procedure should set any registry entries your
application needs. Registry entries are used by the RPC run-time libraries
and the RPC name-service provider to obtain information about the transport
an application intends to use.
By default, MS-DOS and Windows 3.x registry entries are present in the file
RPGREG.DAT in the root directory of the boot drive. You can use a different
file by setting the value of the environment variable RPC_REG_DATA_FILE to
the path and filename of the alternate file.
The RPC Setup program for MS-DOS and Microsoft Windows 3.x creates the
registry file RPCREG.DAT. If you write your own installation program, you
must create RPCREG.DAT and set appropriate entries for the name-service and
NetBIOS transports supported in that environment.
If the Microsoft Locator is the name-service provider:
\Root\Software\Microsoft\Rpc\NameService\Protocol=ncacn_np
\Root\Software\Microsoft\Rpc\NameService\NetworkAddress=\\.
\Root\Software\Microsoft\Rpc\NameService\Endpoint=\pipe\locator
\Root\Software\Microsoft\Rpc\NameService\DefaultSyntax=3
If CDS is the name-service provider via NSID:
\Root\Software\Microsoft\Rpc\NameService\Protocol=ncacn_ip_tcp
\Root\Software\Microsoft\Rpc\NameService\NetworkAddress=NSID host name
\Root\Software\Microsoft\Rpc\NameService\Endpoint=
\Root\Software\Microsoft\Rpc\NameService\DefaultSyntax=3
The NetBIOS transport entries have the following form:
\Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_<A><B>=<C>
Where:
< A > is the NetBIOS sub-protocol sequence (nb, ipx, or tcp).
< B > is a unique digit for each protocol sequence.
< C > is the lana number.
For example, if you have two net cards in a system, running NetBEUI on both
and TCP/IP on one, and the lana numbers on the system are configured as
NetBEUI on card0 is 0, TCP/IP on card0 is 1, and NetBEUI on card1 is 2,
then the RPC NetBIOS registry entries are:
\Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_nb0=0
\Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_nb1=2
\Root\Software\Microsoft\Rpc\NetBios\ncacn_nb_tcp0=1
For more information about the strings generated in the file RPCREG.DAT,
run Microsoft RPC Setup and inspect the strings.