![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rpcread.me CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / info|
Return to rpcread.me CVS log | Up to [WindowsNT SDKs] / mstools / info |
Microsoft Windows NT Build 297 06-28-1992
More Information about Microsoft RPC version 1.0
____________________________________________________________
This document contains important information about Microsoft
RPC version 1.0 that is not included in the Microsoft RPC
Programmer's Guide and Reference or in online help.
Using Notepad to View This Document
To move through this document, press PAGE UP and PAGE DOWN
or click the arrows at the top and bottom of the scroll bar
along the right side of the window.
To print this document, choose the Print command from the
File menu.
For Help on using Notepad, press F1.
____________________________________________________________
Introduction
Microsoft RPC SDK 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 MS-DOS
C/C++ language header files and run-time libraries for
Microsoft Windows NT, Microsoft Windows, and MS-DOS
Sample programs for Microsoft Windows NT, Microsoft
Windows, and MS-DOS
RPC reference online help files and PostScript(TM)
files
The Microsoft Windows NT SDK contains both the Microsoft
Windows NT and Microsoft Windows 3.x/MS-DOS versions of the
RPC SDK.
Installation
The Microsoft Windows NT SDK installs the components of the
Microsoft Windows NT RPC SDK as part of its standard
installation. No additional installation is required.
You must install the Microsoft Windows 3.x and MS-DOS
versions of the RPC toolkit. This software requires:
Microsoft C/C++ version 7.0
DOS Protected Mode Interface (DPMI) server that
supports version 0.9 or later of the DPMI specification and
the MS-DOS extensions to the DPMI (or Microsoft Windows 3.1)
Microsoft LAN Manager version 2.1 with NetBEUI, Named
Pipes, or TCP/IP
To install the Microsoft Windows and MS-DOS version of the
RPC toolkit, run the Setup program that is available in the
directory NT\MSTOOLS\RPC_DOS\NSETUP under Microsoft Windows 3.x.
The environment variables INCLUDE, LIB, and PATH should be
set to point to the directories that contain the Microsoft
C/C++ version 7.0 development tools. (The C/C++ version 7.0
installation program sets these environment variables.)
RPC Documentation
The following Microsoft RPC version 1.0 reference materials
are available in published book form and in PostScript file
format:
RPC Programmer's Guide and Reference
Part I: Programmer's Guide
Part II: Run-time API Reference
Part III: MIDL Language Reference
The PostScript files allow you to print individual chapters
of the documentation on your own PostScript printer.
The following run-time and MIDL reference help files are
available on line:
RPC10WH.HLP WinHelp run-time API reference
RPC10QH.HLP QuickHelp run-time API reference
MIDL10WH.HLP WinHelp MIDL reference
MIDL10QH.HLP QuickHelp MIDL reference
RPC sample program source files are available in the
directory NT\MSTOOLS\SAMPLES\RPC. The file
NT\MSTOOLS\SAMPLES\RPC\README.TXT describes each sample.
____________________________________________________________
Contents
This document contains additional information on the
following topics:
1.0 DCE interoperability issues
2.0 Packing and alignment considerations
3.0 String arrays not transmitted correctly; use pointers
4.0 MIDL switch "-env generic" not supported
5.0 Cast char constants as small in OSF compatibility mode
6.0 MIDL type wchar_t not supported in all modes
7.0 MIDL attribute pointer_default() not OSF compatible
8.0 MIDL interprets "handle" in attribute list as keyword
9.0 C stub source code causes compilation warnings
10.0 Use tagged structure declarations
11.0 Unsized arrays not supported
12.0 Updated command line help for the MIDL compiler
13.0 RpcBindingToStringBinding does not return network address
14.0 RpcServerUseAllProtseqs, RpcNetworkInqProtseqs incomplete
15.0 DCE error codes not mapped to Win32 error codes
16.0 Using the MS-DOS UuidGen utility with Microsoft Windows NT
17.0 Creating installation disks for your application
18.0 New LAN Manager 2.1 DLL required for Windows clients
19.0 Running the locator and endpoint mapper
20.0 Updating RPC registry entries for new NetBIOS configurations
21.0 RPC application exception handling for Microsoft Windows 3.x
____________________________________________________________
1.0 DCE interoperability issues
The Microsoft implementations of the name service and
endpoint mapper that are provided with this release of
Microsoft RPC version 1.0 do not interoperate with DCE
implementations.
The endpoint mapper is the equivalent of the DCE RPC daemon
rpcd. DCE clients cannot resolve endpoints from the
Microsoft endpoint mapper and Microsoft clients cannot
resolve endpoints from the DCE RPC daemon rpcd.
This release of Microsoft RPC version 1.0 defines the type
error_status_t as unsigned short. DCE implementations define
error_status_t as unsigned long.
Full pointers (pointers associated with the attribute [ptr])
are not completely implemented in this release of Microsoft
RPC version 1.0. To allow portability of DCE applications,
MIDL treats full pointers as unique pointers, which means
that aliasing is not supported. The use of full pointers
that cause aliasing can cause undefined results.
DCE host names are case-sensitive. Specify the hostname
exactly as it appears or the client will not be able to
locate the host server.
Other differences between the Microsoft and DCE
implementations are documented in the RPC Programmer's Guide
and Reference.
2.0 Packing and Alignment Considerations
You must use the same packing and alignment settings (/Zp
switch) with both the C compiler and the MIDL compiler.
Using different packing levels for each compiler causes
undefined results. Default values are set for each target
operating system. You can specify the /Zp switch to verify
that the correct packing and alignment settings are used on
both compilers.
For Microsoft Windows 3.x and MS-DOS-based distributed
applications, use one of the following two methods:
a. Compile using /Zp2 with both the MIDL and C compilers
b. Compile using any /Zp level (use the same level
for both the MIDL and C compilers; the level /Zp4 produces
the most efficient marshalling code) and add the following
code to the files RPC.H and RPCNDR.H:
#pragma pack(2) /* at start of rpc.h and rpcndr.h */
...
#pragma pack () /* at end, restore default level */
3.0 String arrays not transmitted correctly; use pointers
Arrays of strings are not transmitted correctly in some
cases because the MIDL compiler contains a known software
error that leads to incorrect stub source files. In this
release, avoid the use of such string arrays as the
following:
typedef [string] char str[80];
void foo([out,length_is(*len)] str array[100],
[out] short *len);
In this release of Microsoft RPC version 1.0, an [out] array
of string pointers must be initialized with valid non-null
values before the remote procedure call. When an array of
null pointer values is transmitted to the server, the stub
does not correctly allocate storage for the strings on
return to the client. For example, the array pArray must be
initialized:
typedef [string] char * PSTRINGTYPE;
void OutStringSArray(
[in, out] long * psize,
[out, size_is(*psize)] PSTRINGTYPE * pArray);
4.0 MIDL switch "-env generic" not supported
The MIDL compiler environment switch "-env generic" is
not supported in this version. When your target operating
system is the same as the development environment, you do
not have to specify an environment switch; the default
settings are correct. Otherwise, use the specific
environment switch that corresponds to your target
application environment: "-env win32", "-env win16", or
"-env dos".
5.0 Cast char constants as small in OSF compatibility mode
The MIDL compiler expects char constants to be type
small. The following definition generates a type mismatch
error message:
const char c = 'a'; // fails with type mismatch error
Use the following statement to avoid the error:
const char c = (small) 'a';
This temporary solution applies only to this release of
Microsoft RPC version 1.0 and will generate errors in OSF
versions of the IDL compiler and in future releases of the
MIDL compiler.
6.0 MIDL type "wchar_t" not supported in all modes
The extended character type wchar_t is not fully supported
in this release of Microsoft RPC version 1.0.
The wchar_t type is supported in the following modes:
implicit_local
app_config
ms_ext
(ms_ext + implicit_local)
The wchar_t type is not supported in the following modes:
OSF compatibility mode (no switches)
(implicit_local + app_config)
(ms_ext + app_config)
(ms_ext + app_config + implicit_local)
7.0 MIDL attribute pointer_default() not OSF compatible
The pointer_default() attribute in this release of Microsoft
RPC version 1.0 is not completely compatible with the DCE
implementation. For example, in the Microsoft
implementation, the following function parameter is a
reference pointer:
pointer_default(ptr);
...
typedef x * MY_POINTER_TYPE;
...
Foo(MY_POINTER_TYPE px);
The DCE implementation treats px as a full pointer in the
above example.
8.0 MIDL interprets "handle" in attribute list as keyword
The MIDL compiler supplied with this release of Microsoft
RPC version 1.0 interprets the token "handle" as a keyword
in the context of an attribute list. For example, consider
an IDL file that contains the following implicit handle
declaration:
[implicit_handle (handle_t handle)]
Because the MIDL compiler interprets the name "handle" as a
keyword rather than as a variable name, MIDL returns an
error code indicating that the "handle" keyword is used
incorrectly in the above example.
C keywords such as "auto", "static", and "extern" generate
similar errors during MIDL compilation. Do not use MIDL or C
keywords as variable names.
9.0 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.
Unsigned character string arguments generate "incompatible
pointer assignment warnings" when you compile the stubs. The
C run-time library functions use char * arguments rather
than unsigned char * arguments. Compiler warning messages
about mismatched comparisons between integral types and
mismatched pointer assignments in stubs can be safely
ignored.
10.0 Use tagged structure declarations
The MIDL compiler assigns temporary tags to untagged
structures. When you use more than one IDL file to build
your distributed application, the MIDL compiler may assign
the same temporary name to both untagged structures and fail
to link.
You can avoid these link errors by specifying using tagged
structure declarations for types imported or shared between
interfaces.
For example, the following untagged structure
UNTAGGED_STRUCT can be changed to the tagged structure
TAGGED_STRUCT:
typedef struct {
char * pszName;
char * pszAddress;
} UNTAGGED_STRUCT;
typedef struct _TAGGED_STRUCT {
char * pszName;
char * pszAddress;
} TAGGED_STRUCT;
11.0 Unsized arrays not supported
This release of Microsoft RPC version 1.0 does not support
character arrays that are specified without the array size.
Specify the array size or use a character pointer.
For example, the following function argument is not
supported:
foo ([in, string] char ac[]);
Use char pointers or specify the array size. The following
function arguments are supported:
foo([in, string] char char_array[100]);
foo([in, string] char * char_array);
12.0 Updated command line help for the MIDL compiler
The updated help text for the MIDL compiler appears as
follows:
-MIDL COMPILER OPTIONS-
-MODE-
/ms_ext Microsoft extensions mode
/app_config Application configuration mode
/implicit_local Assume non-remote data is [local]
-INPUT-
/acf filename Specify the attribute configuration file
/I directory Specify directory for import and include files
/import ms_ext Compile only needed portions of imported IDL files
/import ms_nt Compile only needed portions of imported IDL files
/import osf Assume imported IDL files are compiled separately
/no_def_idir Ignore the current and the INCLUDE directories
-OUTPUT FILE GENERATION-
/client all Generate client stub and aux files
/client aux Generate client auxiliary file only
/client none Generate no client files
/client stub Generate client stub file only
/out directory Destination directory for output files
/server all Generate server stub and aux files
/server aux Generate server aux file only
/server none Generate no server files
/server stub Generate server stub file only
/syntax_check Check syntax only; do not generate output files
/Zs Check syntax only; do not generate output files
-OUTPUT FILE NAMES-
/caux filename Specify client auxiliary file name
/cstub filename Specify client stub file name
/cswtch filename Specify switch stub file name
/Fs filename Generate a listing file
/header filename Specify header file name
/saux filename Specify server auxiliary file name
/sstub filename Specify server stub file name
-C COMPILER AND PREPROCESSOR OPTIONS-
/cc_cmd cmd_line Specify C compiler for stub, aux files
/cc_opt options Specify options associated with C compiler
/cpp_cmd cmd_line Specify name of C preprocessor
/cpp_opt options Specify additional C preprocessor
options
/D name[=def] Pass #define name, optional value to C preprocessor
/no_cpp Turn off the C preprocessing option
/U name Remove any previous definition (undefine)
-ENVIRONMENT-
/char signed C compiler default char is signed
/char unsigned C compiler default char is unsigned
/char ansi7 Char values limited to 0-127
/env dos MS-DOS client
/env win16 Microsoft Windows 16-bit (Win 3.x)
/env win32 Microsoft Windows 32-bit (NT)
/env generic Produce one header for all environments
-ERROR AND WARNING MESSAGES-
/error all Check for all types of errors
/error allocation Check for out of memory errors
/error enum Check for errors converting long, short enum
/error trees Check for aliasing errors only
/no_warn Suppress compiler warning messages
-OPTIMIZATION-
/pack {1|2|4|8} Designate packing level of structures
/space_opt Optimize code for space rather than speed
/Zp{1|2|4|8} Designate packing level of structures
-MISCELLANEOUS-
/? List MIDL compiler switch settings
@response_file Accept input from a response file
/confirm Display options without compiling MIDL source
/help Display a list of MIDL compiler switches
/prefix "s1" "s2" Replace default suffix "s1" with prefix "s2"
13.0 RpcBindingToStringBinding does not return network address
The RPC API function RpcBindingToStringBinding, when used
with the named pipe loadable transport, does not return the
network address.
Use the function RpcStringBindingParse to obtain the other
components of the binding string, use the Win32 function
GetComputerName to obtain the computer name that represents
the network address, then call RpcStringBindingCompose to
reconstruct the correct string binding from these
components.
14.0 RpcServerUseAllProtseqs, RpcNetworkInqProtseqs Incomplete
The RPC API functions RpcNetworkInqProtseqs and
RpcServerUseAllProtseqs return status codes that indicate
success but the functions do not operate properly.
RpcNetworkInqProtseqs returns a RPC_PROTSEQ_VECTOR data
structure with a count value of 0 and no pointers to
protocol sequence strings.
Rather than call RpcServerUseAllProtseqs, call
RpcServerUseProtseq for each supported protocol sequence:
RPC_STATUS RpcStatus;
RpcStatus = RpcServerUseProtseq("ncacn_np",
MaxCalls, SecurityDescriptor);
...
RpcStatus = RpcServerUseProtseq("ncacn_ip_tcp",
MaxCalls, SecurityDescriptor);
...
RpcStatus = RpcServerUseProtseq("ncacn_dnet_nsp",
MaxCalls, SecurityDescriptor);
...
RpcStatus = RpcServerUseProtseq("ncacn_nb_nb",
MaxCalls, SecurityDescriptor);
...
RpcStatus = RpcServerUseProtseq("ncalrpc",
MaxCalls, SecurityDescriptor);
15.0 DCE error codes not mapped to Win32 error codes
In this release of Microsoft RPC version 1.0, the run-time
API functions RpcEp* return DCE error codes rather than the
documented Win32 error codes. The DCE error codes, RPC error
manifest, and Win32 error codes are as follows:
Win32 error code RPC Manifest DCE error code
1751 EPT_S_INVALID_ENTRY 0x1c110007
1752 EPT_S_CANT_PERFORM_OP 0x1c110001
1753 EPT_S_NOT_REGISTERED 0x1c110004
The RPC header files define the manifests to the Win32 error
code values but the RPC runtime functions return the DCE
values. Redefine the manifests in your application to the
DCE values, as follows:
#undef EPT_S_CANT_PERFORM_OP
#define EPT_S_CANT_PERFORM_OP 0x1c110001
#undef EPT_S_INVALID_ENTRY
#define EPT_S_INVALID_ENTRY 0x1c110007
#undef EPT_S_NOT_REGISTERED
#define EPT_S_NOT_REGISTERED 0x1c110004
16.0 Using the MS-DOS UuidGen utility with Microsoft Windows NT
The UuidGen utility is supplied for MS-DOS only. No version
is supplied for native Microsoft Windows NT. However, you
can run the MS-DOS version of this utility in the Microsoft
Windows NT MS-DOS screen group. The utility is available in
compressed format in the MSTOOLS\RPC_DOS directory. To
decompress the UuidGen utility, use the following command on
Microsoft Windows 3.x:
setup /z uuidgen.ex_ drive:\directory\uuidgen.exe
where drive: and directory specify a directory on your path.
17.0 Creating installation disks for your application
Two batch files help you create RPC run-time installation
disks that can accompany your distributed application. These
batch files create installation disks that contain the Setup
program and the Microsoft RPC run-time libraries, allowing
you to distribute the Microsoft RPC run-time libraries with
your distributed application. The following two batch files
are provided:
wrundisk.bat creates Microsoft Windows/MS-DOS run-time
install disk
drundisk.bat creates MS-DOS-only run-time install disk
17.1 Creating installation disks for Microsoft Windows applications
Insert a formatted, blank floppy disk in the destination
drive. Start the installation disk utility by typing
"wrundisk" followed by the optional source and destination
drive names. The wrundisk.bat file uses the following
syntax:
wrundisk [source:[path] [dest:]]
where
source is a disk or directory that contains the compressed
files that are provided in the Microsoft Windows NT SDK
directory \mstools\rpc_dos\disk1.
dest is a drive name specifying the drive that contains the
formatted, blank floppy disk.
For example,"wrundisk c:\nt\mstools\rpc_dos\disk1 a:" copies
the compressed files to the floppy disk in the drive A.
Your application user can then use the Setup program under
Microsoft Windows on the resulting installation disk to
install the RPC run-time libraries for Microsoft Windows and
MS-DOS.
17.2 Installation disks for MS-DOS Distributed Applications
The drundisk utility copies files from an installed RPC SDK.
To ensure that all MS-DOS loadable transports are present on
the run-time installation disk, you must select all loadable
transports at the time you install the Microsoft RPC SDK.
Insert a formatted, blank floppy disk in the destination
drive. Start the installation utility by typing "drundisk"
followed by the optional source and destination drive names.
The drundisk.bat file uses the following syntax:
drundisk [directory [dest:]]
where directory is the name of the directory that contains
all loadable transport (.RPC) files and all name service
dynamic link libraries.
For example, the command "drundisk c:\lanman.dos\netprog a:"
copies the MS-DOS run-time libraries, the loadable transport
files, and name service DLLs from the C hard drive to the
floppy disk in drive A. Your application user can then use
the Setup program on the run-time installation disk to
install the RPC run-time libraries.
18.0 New LAN Manager 2.1 DLL required for Windows clients
Install an updated version of the dynamic link library
NETAPI.DLL for Microsoft Windows 3.x clients that use
Microsoft LAN Manager 2.1 named pipes. This version of the
LAN Manager API library corrects a software error.
To install the new version of this library, connect to the
directory that contains the Setup program and the compressed
source files, then enter the command:
setup /z netapi.dl_ drive:\directory\netapi.dll
where drive and directory specify the path to the LAN
Manager 2.1 directory that contains NETAPI.DLL. For example,
if LAN Manager is installed in the directory C:\LANMAN.DOS,
use the command:
setup /z netapi.dl_ c:\lanman.dos\netprog\netapi.dll
19.0 Running the locator and endpoint mapper
In this release of Microsoft RPC version 1.0, the locator
and endpoint mapper are not provided as services but as
programs that you must start from the Microsoft Windows NT
command line. The locator is the Microsoft implementation of
the RPC name service independent API functions (NSI). The
endpoint mapper allows the use of dynamic endpoints.
Start the locator using the following command syntax:
locator /noservice
Start the endpoint mapper on the RPC server using the
following syntax:
rpcss noservice
Start the locator and endpoint mapper before starting the
server application. In this release of Microsoft RPC version
1.0, distributed applications that use the RPC NSI API
functions must run the server and client applications on the
same computer.
20.0 Updating RPC registry entries for new NetBIOS configurations
The Microsoft RPC Setup program automatically maps protocol
strings to NetBIOS lana numbers and writes these settings in
the registry. These mappings work as long as you only have
one network card and one network protocol. If this is not
the case, or if you change your network configuration after
installing Microsoft RPC, you must update the registry to
indicate the new correspondences between protocol strings
and NetBIOS lana numbers.
For Microsoft Windows NT, the mapping string appears in the
registry tree under \Software\Microsoft\Rpc\NetBios. For
MS-DOS, the mapping string appears in the registry file
RPCREG.DAT.
The mapping string uses the following syntax:
ncacn_nb_<protocol><digit> = <lana_number>
where
<protocol> indicates the protocol type. For MS-DOS, the
valid <protocol> value is "nb". For Microsoft Windows NT,
valid <protocol> values are as follows:
<protocol> Protocol type
xns XNS
nb NetBEUI
tcpip TCP/IP
<digit> indicates a unique digit associated with each
instance of a protocol. Use the value 0 for the first
instance of a protocol and use the next consecutive digit
for each additional instance of that protocol. For example,
assign the value ncacn_nb_nb0 to the first NetBEUI entry;
assign the value ncacn_nb_nb1 to the second NetBEUI entry.
<lana_number> indicates the NetBIOS lana number. A unique
lana number is associated with each network adapter present
in the computer. For more information about the lana number,
see your network documentation.
For example, the following mapping string describes a
configuration that uses the NetBEUI protocol over an adapter
card that is assigned lana number 0:
ncacn_nb_nb0=0
When you install a second card that supports both XNS and
NetBEUI protocols, the mapping strings appear as follows:
ncacn_nb_nb0=0
ncacn_nb_nb1=1
ncacn_nb_xns0=2
21.0 RPC application exception handling for Microsoft Windows 3.x
A software error in this release of Microsoft RPC version
1.0 can cause your Microsoft Windows 3.x RPC application to
GP fault after repeated exceptions and repeated execution of
the application.
When the top-level exception handler exits with an
exception, an internal data structure is left in an
incorrect state. Repeated execution of the same application
can then cause memory corruption.
You can avoid this error by guaranteeing that the final top-
level try block of the program is exited normally (without
an exception). Use the following structure in your
application:
RpcTryExcept
{
...
}
RpcExcept(...)
{
...
}
/* add a try-finally block here */
volatile x = 1; /* assure this code is present */
RpcTryFinally
{
if (x == 2)
x++;
}
RpcFinally
{
x = 3;
}
RpcEndFinally;
RpcEndExcept
The volatile variable x does not perform any useful function
for the application. It is present only to ensure that the
RpcTryFinally structure is present after the C compiler
optimizes the application.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.