home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 4.ddi / EXAMPLES / PERSIST / README
Encoding:
Text File  |  1989-09-14  |  7.6 KB  |  242 lines
  1.                       persist Example
  2.  
  3.  
  4.  
  5.  
  6. 1.  Environment
  7.  
  8. This example is designed to be built and executed on a PC
  9. that runs DOS, the Watcom C Compiler and utilities, and that
  10. uses the NOVELL SPX network library.
  11.  
  12.  
  13.  
  14.  
  15. 2.  Overview
  16.  
  17. This example demonstrates a client program that uses a
  18. persistent binding; in other words, a binding that is used
  19. for multiple remote procedure calls.  Thus, in this example,
  20. the client will establish a binding with the server, use
  21. this binding for subsequent remote procedure calls, and
  22. finally terminate the binding once the server is no longer
  23. required.
  24.  
  25.  
  26.  
  27.  
  28. 3.  Keywords
  29.  
  30. persistent binding, single-binding model, connection_id
  31. binding type
  32.  
  33.  
  34.  
  35.  
  36. 4.  Files
  37.  
  38. Source files for this example reside in the following sub-
  39. directories:
  40.  
  41. server:
  42.  
  43.      Contains code and build procedures for the server part
  44.      of this distributed application.  The server consists
  45.      of the server control procedure, which is provided with
  46.      the product distribution, the dispatcher procedure and
  47.      server stub routines, which are generated by the RPC
  48.      Compiler, and the remote procedures, which are provided
  49.      with this example.
  50.  
  51.      rproc.c       remote procedure application code
  52.  
  53.      server.mk     makefile for building the server
  54.  
  55.      serv_def.h    include file with macro definitions for
  56.                    the server control procedure
  57.  
  58. client:
  59.  
  60.      Contains code and build procedures for the client part
  61.      of this distributed application.  The client consists
  62.      of the client main program and any associated routines,
  63.      which are provided with this example, and the client
  64.      stubs, which are generated by the RPC compiler.
  65.  
  66.      client.c      client application code (main program)
  67.  
  68.      client.mk     makefile for building the client
  69.  
  70. common:
  71.  
  72.      Contains the RPC interface specification used by the
  73.      RPC compiler to create the client and server stubs.
  74.  
  75.      persist.rpc   RPC interface specification for this
  76.                    example
  77.  
  78.  
  79.  
  80.  
  81. 5.  Network Configuration
  82.  
  83. Before you can run this example, you may have to ask your
  84. system administrator to configure your system specifically
  85. for your needs.  The required configuration is described in
  86. the file: ..\..\READSPX
  87.  
  88.  
  89.  
  90.  
  91. 6.  Server Name
  92.  
  93. As distributed, the server for this example will register
  94. under the name "example".  However, it is strongly suggested
  95. that a unique server name be assigned to this example before
  96. it is built.
  97.  
  98. A unique server name will prevent two or more users from
  99. invoking a server process using the same server name.
  100. Choose a server name not likely to be selected by someone
  101. else.  For example, use your user or login name.
  102.  
  103. The server name must be changed in both the client and the
  104. server, and the SAME name must be used.  To change the
  105. server name for the client program, change to the client
  106. directory (client) and edit the file client.c.  Change the
  107. #define Server_Name statement as follows:
  108.  
  109.       #define Server_Name "example"
  110.           is changed to
  111.       #define Server_Name "myname"
  112.  
  113. To change the server name for the server program, change to
  114. the server directory (server) and edit the file serv_def.h,
  115. which contains the define statements for the server control
  116. procedure.  As with the client program, simply change the
  117. #define Server_Name statement.
  118.  
  119.  
  120.  
  121.  
  122. 7.  Building Client & Server
  123.  
  124. Procedures are included for building the example program.
  125. These procedures assume that your environment is set up as
  126. follows:
  127.  
  128.    - The PATH environment variable must specify the location
  129.      of the RPC Compiler executable files.
  130.  
  131.    - The LIB environment variable must specify the location
  132.      of the RPC runtime libraries.
  133.  
  134.    - The INCLUDE environment variable must specify the
  135.      location of the RPC .h include files.
  136.  
  137.    - The PDUDIR environment variable must specify the
  138.      location of the RPC .rpc files.
  139.  
  140.    - The RPCSCP environment variable must specify the
  141.      location of the RPC server control procedures.
  142.  
  143. The PATH, LIB, and INCLUDE environment variables should be
  144. set in your autoexec.bat file by modifying their current
  145. definitions. The PDUDIR and RPCSCP environment variables can
  146. be set in your autoexec.bat file, or in a local .bat file,
  147. or directly with the "set" command.
  148.  
  149. Since a distributed application runs on two machines, you
  150. must install an executable version of the client or server
  151. on another machine.  If the two machines are identical, you
  152. can build both executables (the client and server) on one
  153. machine and then move one of the executables.  However, if
  154. the two machines are not identical, you must follow the
  155. directions on the other machine for running this example and
  156. build one of the executable programs there (note that the
  157. executable filenames may differ across products).
  158.  
  159. To build the example program, you simply execute the build
  160. procedures in each subdirectory as follows:
  161.  
  162.   1.  Change to the client directory (client) and build the
  163.       client:
  164.  
  165.            wmake /f  client.mk
  166.  
  167.   2.  Change to the server directory (server) and build the
  168.       server:
  169.  
  170.            wmake /f  server.mk
  171.  
  172.  
  173.  
  174.  
  175.  
  176. 8.  Running the Distributed Application
  177.  
  178. The server program should be started before the client
  179. program is run.
  180.  
  181. To run the example on two machines, proceed as follows:
  182.  
  183.   1.  Change to the server directory (server) on the machine
  184.       running the server and start the server:
  185.  
  186.            server
  187.  
  188.   2.  Change to the client directory (client) on the machine
  189.       running the client and start the client:
  190.  
  191.            client
  192.  
  193.  
  194.  
  195.  
  196.  
  197. 9.  Description
  198.  
  199. This example demonstrates a client program that uses a
  200. persistent binding; in other words, a binding that is used
  201. for multiple remote procedure calls.  Thus, in this example,
  202. the client will establish a binding with the server, use
  203. this binding for subsequent remote procedure calls, and
  204. finally terminate the binding once the server is no longer
  205. required.
  206.  
  207. You should consider using persistent connections when your
  208. client and server interact extensively, and the overhead of
  209. binding establishment will impact the design of your
  210. distributed application.
  211.  
  212. In addition to increasing performance, a persistent binding,
  213. client-server relationship allows a server to offer an
  214. interface that groups a set of remote procedures into a
  215. logical category.  You may want to consider using persistent
  216. bindings in cases where the remote procedures are related
  217. functionally or act upon the same data structures. Indeed,
  218. the persistent-binding model can be used in performing a
  219. transaction style of client-server interaction.
  220.  
  221. To demonstrate a persistent connection, the client is set up
  222. to "sleep" between remote procedure calls, so it keeps the
  223. binding open for a short time.  If, during that time,
  224. another client were to try to establish a binding to this
  225. server, that client would wait.  The multicli example shows
  226. how to support multiple client process bindings
  227. simultaneously.
  228.  
  229. See Chapter 4, "Process Binding," and Chapter 14, "Server
  230. Control Procedures" of the NetWare RPC User's Manual for
  231. more information on persistent bindings and single-
  232. binding servers.
  233.  
  234. Note that the server shown in this example is a single-
  235. threaded server; in other words, the server handles one and
  236. only one binding at any point in time.  Other client
  237. requests must wait their turn, until the server completes
  238. handling the preceding bindings.  If your environment
  239. supports multi-threaded processes or multi-tasking, other
  240. examples will demonstrate the use of a multi-threaded or
  241. multi-tasking server supporting persistent bindings.
  242.