home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / netds / rpc / dict / readme.txt < prev    next >
Encoding:
Text File  |  1996-01-17  |  10.3 KB  |  293 lines
  1. DICT
  2.  
  3.  
  4. The DICT program demonstrates use of the implicit_handle, context_handle, 
  5. in, and out attributes.
  6.  
  7. SUMMARY
  8. =======
  9.  
  10. This sample program is an example of a non-trivial local application 
  11. converted to a distributed RPC application.
  12.  
  13. The local program is a character-oriented "play" program, which lets a
  14. user insert, delete, and iterate over a dictionary. The dictionary is
  15. based on splay trees, which are printed out in a format described below.
  16.  
  17. We remoted the basic program by taking the interface to the dictionary
  18. (given in dict0.h) and creating an interface to a remote dictionary,
  19. (given in replay.idl) which is remoted using RPC.
  20.  
  21. Following the local dictionary interface, which is minimal and uniform,
  22. the remote interface is also uniform. However, since the local dictionary
  23. is generic (can store any item type, using void* pointers to items),
  24. the interface needed to change to deal with predefined (Record) type
  25. items in order to be remoted using the Microsoft RPC system. Also,
  26. since the local implementation allows a "peek" at the root of the tree
  27. using a DICT_CURR_ITEM macro, the whole interface needed to change.
  28.  
  29. Remote dictionaries are represented by context handles to demonstrate
  30. the use of [context_handle]. Context handles are currently initialized
  31. using a global primitive handle [implicit_handle].
  32.  
  33. State was added to remote dictionaries in order to allow sharing them,
  34. and maintain reference counts. At this time, however, access to shared
  35. dictionaries is *not* serialized! By default each client gets his own
  36. copy of the dictionaries. To use shared dictionaries, start the client
  37. using the -s switch.
  38.  
  39. The use of context to maintain state is also demonstrated by
  40. differentiating between a private iterator, activated by "n" for "next"
  41. and "p" for "previous", and a global shared iterator, activated by "N"
  42. for "Next" and "P" for previous. To start iterators, use "h" - go to
  43. the "head" of the dictionary, or "t" - go to the "tail" of the dictionary.
  44. The private iterator can be reset to DICT_CURR_ITEM using "r".
  45.  
  46. FILES
  47. =====
  48.  
  49. The directory samples\rpc\dict contains the following files for building
  50. the DICT distributed application:
  51.  
  52. File          Description
  53.  
  54. README.TXT    Readme file for the DICT sample
  55. REPLAY.IDL    Interface definition language file
  56. REPLAY.ACF    Attribute configuration file
  57. CLIENT.C      Client main program
  58. SERVER.C      Server main program
  59. PLAY.C
  60. PLAY.H
  61. UTIL0.C
  62. UTIL0.H
  63. DICT0.C
  64. DICT0.H
  65. REPLAY.C
  66. MAKEFILE      Nmake file to build for Windows NT or Windows 95
  67. MAKEFILE.DOS  Nmake file to build for MS-DOS
  68.  
  69. ------------------------------------
  70. Building on Windows NT or Windows 95
  71. ------------------------------------
  72.  
  73. The following environment variables should be already set for you:
  74.  
  75.   set CPU=i386
  76.   set INCLUDE=%SDKROOT%\h
  77.   set LIB=%SDKROOT%\lib
  78.   set PATH=%SDKROOT%\system32;%SDKROOT%\bin
  79.  
  80. where %SDKROOT% is the root directory for the 32-bit Windows SDK.
  81.  
  82. For mips, set CPU=mips
  83. For alpha, set CPU=alpha
  84.  
  85. Build the sample distributed application:
  86.  
  87.   nmake cleanall
  88.   nmake
  89.  
  90. ------------------------------------------
  91. Building the client application for MS-DOS
  92. ------------------------------------------
  93.  
  94. After installing the Microsoft Visual C/C++ version 1.50 development
  95. environment and the 16-bit RPC SDK on a Windows NT or Windows 95
  96. computer, you can build the sample client application from Windows NT
  97. or Windows 95:
  98.  
  99.   nmake -f makefile.dos cleanall
  100.   nmake -f makefile.dos
  101.  
  102. This builds the client application client.exe.
  103.  
  104. You may also execute the Microsoft Visual C/C++ compiler under MS-DOS.
  105. This requires a two-step build process.
  106.  
  107.   Step One: Compile the .IDL files under Windows NT or Windows 95:
  108.  
  109.      nmake -a -f makefile.dos replay.h
  110.  
  111.   Step Two: Compile the C sources (stub and application) under MS-DOS:
  112.  
  113.      nmake -f makefile.dos
  114.  
  115. Using the program:
  116. ------------------
  117.  
  118. To use the local dictionary example, type "play".
  119.  
  120. To use the remote versiom, type "server" on the server side. On the client 
  121. side, for each client use "client" for a fresh,private copy of the 
  122. dictionary, or "client -s" for a shared copy of the dictionary. The 
  123. following command line options are available on the client side.
  124.  
  125. Options:
  126. --------
  127.  
  128. The -? displays the following message:
  129.  
  130. Usage : client [-s] [-n <server>] [-v <view_option>]
  131.  
  132. The -s option is used for using a shared version of the dictionary.
  133.     If none exist, a fresh shared version is created.
  134.  
  135. The -v<option> is used for getting different views of the dictionary:
  136.     -v normal (default) - default view of the dictionary
  137.     (see explanation below)
  138.     -v flat - Flat printout
  139.     -v rev (or -v reverse) - reverses the tree to print left subtree first
  140.     followed by the node, followed by the right subtree, at every level
  141.  
  142. The -n <server_name> is used for specifying a server machine.  Without it
  143.     the server is assumed to run on the same machine.
  144.  
  145.     If you use the -n option you have to make sure that the server is
  146.     ready to receive calls; that is you have to start the server, by typing:
  147.  
  148.     -> server
  149.  
  150.     to the console, even if the server is your own machine.
  151.  
  152. Program structure:
  153. ==================
  154.  
  155. Basic application:
  156. ------------------
  157.  
  158.   dict0.h + dict0.c - These files contain a basic generic dictionary
  159.     implementation, based on Self Adjusting Trees (Splay trees),
  160.     invented by Sleator and Tarjan. In the remote dictionary
  161.     application (replay) the generic dictionary code runs on the server,
  162.     which maintains a data base to be shared by clients.
  163.  
  164.     Note that the generic dictionary data structures contain untyped
  165.     pointers ((void)*), and thus require a special layer of typed trees
  166.     (strongly typed tree nodes) containing items of RPC-able types
  167.     in order to convert the local dictionary package and distribute it
  168.     using the Microsoft RPC system, and particularly the MIDL compiler.
  169.  
  170.     If you are interested in RPC (as opposed to splay trees) treat
  171.     the generic dictionary as a "black box", and ignore the implementation
  172.     details. Otherwise, you are probably looking at the wrong README
  173.     file (and should read Tarjan and Sleators paper first anyhow...)
  174.  
  175. Local dictionary:
  176. -----------------
  177.  
  178.   play.h + play.c - These files contain a simple character-oriented
  179.     interactive demo / test program for the dictionary.
  180.  
  181. Remote dictionary:
  182. ------------------
  183.  
  184.   replay.idl - The Interface Definition Language (IDL) file contains:
  185.  
  186.     o type definitions for the remotable objects required (such as the
  187.       Record item type, RecordTreeNode, etc)
  188.  
  189.     o the context handle definition (a (void)* in this case) providing
  190.       a handle on a remote dictionary
  191.  
  192.     o the signatures for the remote dictionary operations
  193.  
  194.   replay.acf - An Attribute Configuration File (ACF), used here to
  195.     specify the initial binding method. We use implicit_binding to
  196.     bind to the server initially, and to initialize the context handle.
  197.  
  198.   replay.c - This file contains the implementation of the remote, or
  199.     virtual, dictionary (VDict_...) operations. These are required
  200.     only on the server side, and are replaced by caller stubs
  201.     (in replay_c.c) on the client side.
  202.  
  203. Utlities:
  204. ---------
  205.  
  206.   util0.h + util0.c - These files contain utility routines used by both
  207.     the client and server applications to allocate and to free dictionaries
  208.     and trees, as well as pretty-print routines, used to print trees on
  209.     both sides. See description of the user interface portion below for
  210.     further discussion of the tree printing format.
  211.  
  212. Client side:
  213. ------------
  214.  
  215.   client.c - This file contains the driver of the client side program.
  216.     The client binds to the server, initializes a dictionary, and activates
  217.     a context handle for the dictionary on the server side. It then goes
  218.     into a test loop which prints the dictionary tree and prompts the user
  219.     for additional input by printing the following usage message:
  220.  
  221. Usage:
  222. Type a single character, followed by an optional key as follows:
  223.  
  224.     i <key> :: Insert <key> into dictionary
  225.     d <key> :: Delete <key> from dictionary
  226.     f <key> :: Find <key> in dictionary
  227.     N       :: next of current item in dictionary
  228.     P       :: previous of current item in dictionary
  229.     n       :: Next of local current item in dictionary
  230.     p       :: Previous of local current item in dictionary
  231.     h       :: Head (first item) of dictionary
  232.     t       :: Tail (last item) of dictionary
  233.     ?       :: Print this message
  234.     q       :: Quit
  235.  
  236. where <key> is <integer> <string>
  237.  
  238. next op (i d x f n N p P h t ? q):
  239.  
  240. Server side:
  241. ------------
  242.  
  243.   server.c - This file contains a pretty standard server main loop for
  244.     the remote dictionary "replay" demo.
  245.  
  246. Tree print format:
  247. ------------------
  248.  
  249. The tree printing routine prints the keys in a binary search tree using
  250. the following "prinTree" recursive algorithm:
  251.  
  252.     prinTree (right subtree, with current indentation + one "tab");
  253.     print the key at the root (with current indentation);
  254.     prinTree (left subtree, with current indentation + one "tab");
  255.  
  256. Keys are a pair of the form <integer, string>.  Assume the following tree:
  257.  
  258.  
  259.                            -----------
  260.                            |0 : jack |
  261.                            -----------
  262.                           /           \
  263.                      ----------      -----------
  264.                      |0 : don |      |0 : jane |
  265.                      ----------      -----------
  266.                      /       \
  267.                     /         \
  268.                -----------  ----------
  269.                |0 : adam |  |0 : eve |
  270.                -----------  ----------
  271.  
  272. The above print algorithm would print it as follows:
  273.  
  274.  
  275.         0 : jane
  276.     0 : jack
  277.             0 : eve
  278.         0 : don
  279.             0 : adam
  280.  
  281. The left child of a node is printed on the first line following the node
  282. which is indented by one more tab then the given node.
  283. The right child of a node is printed on the last line preceding the node
  284. which is indented by one more tab then the given node.
  285. If you tilt your hand to the left while examining the printed tree format,
  286. it closely resembles the "traditional" format of a rooted binary tree.
  287.  
  288. Known Limitations:
  289. ------------------
  290.  
  291. Shared dictionaries are unprotected, so serialized access to the
  292. dictionary is assumed. Use at your own risk.
  293.