home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / ASYNC1 / README
Encoding:
Text File  |  1989-12-11  |  11.3 KB  |  328 lines
  1.                        async1 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 Microsoft C Compiler and utilities, and
  10. that uses the NetWare network library.
  11.  
  12.  
  13.  
  14.  
  15. 2.  Overview
  16.  
  17. This example is similar to the async example, but adds a
  18. feature that allows the client to issue multiple
  19. asynchronous remote procedure calls to different servers.
  20.  
  21.  
  22.  
  23.  
  24. 3.  Keywords
  25.  
  26. asynchronous, non-blocking, Hooks, Traps, RPC macros,
  27. polling, import statement
  28.  
  29.  
  30.  
  31.  
  32. 4.  Files
  33.  
  34. Source files for this example reside in the following sub-
  35. directories:
  36.  
  37. server:
  38.  
  39.      Contains code and build procedures for the server part
  40.      of this distributed application.  The server consists
  41.      of the server control procedure, which is provided with
  42.      the product distribution, the dispatcher procedure and
  43.      server stub routines, which are generated by the RPC
  44.      Compiler, and the remote procedures, which are provided
  45.      with this example.
  46.  
  47.      rproc.c       remote procedure application code
  48.  
  49.      server.mk     makefile for building the server
  50.  
  51.      serv_def.h    include file with macro definitions for
  52.                    the server control procedure
  53.  
  54. client:
  55.  
  56.      Contains code and build procedures for the client part
  57.      of this distributed application.  The client consists
  58.      of the client main program and any associated routines,
  59.      which are provided with this example, and the client
  60.      stubs, which are generated by the RPC compiler.
  61.  
  62.      client.c      client application code (main program)
  63.  
  64.      client.mk     makefile for building the client
  65.  
  66. common:
  67.  
  68.      Contains the RPC interface specification used by the
  69.      RPC compiler to create the client and server stubs.
  70.      The RPC interface specification imports the
  71.      asynchronous RPC specification file to provide the
  72.      asynchronous interface.
  73.  
  74.      async1.rpc    RPC interface specification for this
  75.                    example
  76.  
  77. async1:
  78.  
  79.      Contains the RPC interface specification consisting of
  80.      client stub Hooks and Traps code and the source code
  81.      for poll_reply, which provide for an asynchronous
  82.      interface.
  83.  
  84.      async1_i.rpc  asynchronous RPC specification and
  85.                    polling routine
  86.  
  87.      async1_i.mk   makefile for building the asynchronous
  88.                    object files and include file
  89.  
  90.      Note that the RPC Compiler is run only once with this
  91.      RPC specification file as input.  Generally, the
  92.      Compiler should be run with the file twice: once for
  93.      the client and once for the server, producing header
  94.      files and RPC code files for each.  However, for this
  95.      example the procedure is simplified because the single
  96.      header file produced can be used by both the client and
  97.      the server, the RPC Compiler is told to run in client
  98.      mode, and the only application code in the file is for
  99.      the client.
  100.  
  101.  
  102.  
  103.  
  104. 5.  Network Configuration
  105.  
  106. Before you can run this example, you may have to ask your
  107. system administrator to configure your system specifically
  108. for your needs.  The required configuration is described in
  109. the file: ..\..\READSPX
  110.  
  111.  
  112.  
  113.  
  114. 6.  Server Name
  115.  
  116. As distributed, the server for this example will register
  117. under the name "example".  However, it is strongly suggested
  118. that a unique server name be assigned to this example before
  119. it is built.
  120.  
  121. A unique server name will prevent two or more users from
  122. invoking a server process using the same server name.
  123. Choose a server name not likely to be selected by someone
  124. else.  For example, use your user or login name.
  125.  
  126. The server name must be changed in both the client and the
  127. server, and the SAME name must be used.  To change the
  128. server name for the client program, change to the client
  129. directory (client) and edit the file client.c.  Change the
  130. #define Server_Name statement as follows:
  131.  
  132.       #define Server_Name "example"
  133.           is changed to
  134.       #define Server_Name "myname"
  135.  
  136. To change the server name for the server program, change to
  137. the server directory (server) and edit the file serv_def.h,
  138. which contains the define statements for the server control
  139. procedure.  As with the client program, simply change the
  140. #define Server_Name statement.
  141.  
  142.  
  143.  
  144.  
  145. 7.  Building Client & Server
  146.  
  147. Procedures are included for building the example program.
  148. These procedures assume that your environment is set up as
  149. follows:
  150.  
  151.    - The PATH environment variable must specify the location
  152.      of the RPC Compiler executable files.
  153.  
  154.    - The LIB environment variable must specify the location
  155.      of the RPC runtime libraries.
  156.  
  157.    - The INCLUDE environment variable must specify the
  158.      location of the RPC .h include files.
  159.  
  160.    - The PDUDIR environment variable must specify the
  161.      location of the RPC .rpc files.
  162.  
  163.    - The RPCSCP environment variable must specify the
  164.      location of the RPC server control procedures.
  165.  
  166. The PATH, LIB, and INCLUDE environment variables should be
  167. set in your autoexec.bat file by modifying their current
  168. definitions. The PDUDIR and RPCSCP environment variables can
  169. be set in your autoexec.bat file, or in a local .bat file,
  170. or directly with the "set" command.
  171.  
  172. Since a distributed application runs on two machines, you
  173. must install an executable version of the client or server
  174. on another machine.  If the two machines are identical, you
  175. can build both executables (the client and server) on one
  176. machine and then move one of the executables.  However, if
  177. the two machines are not identical, you must follow the
  178. directions on the other machine for running this example and
  179. build one of the executable programs there (note that the
  180. executable filenames may differ across products).
  181.  
  182. Note that with the Microsoft C Compiler and utilities,
  183. numerous warnings will be generated when executing the
  184. makefiles. For example, you may see a "target does not
  185. exist" or "module not in library" warning. These simply mean
  186. that the file the makefile is currently creating does not
  187. yet exist. Generally, all warnings may be ignored.
  188.  
  189. To build the example program, you simply execute the build
  190. procedures in each subdirectory as follows:
  191.  
  192.   1.  Change to the async1 directory and build the files
  193.       associated with the imported RPC specification file:
  194.  
  195.            make async1_i.mk
  196.  
  197.   2.  Change to the client directory (client) and build the
  198.       client:
  199.  
  200.            make client.mk
  201.  
  202.   3.  Change to the server directory (server) and build the
  203.       server:
  204.  
  205.            make server.mk
  206.  
  207.  
  208.  
  209.  
  210.  
  211. 8.  Running the Distributed Application
  212.  
  213. The server program should be started before the client
  214. program is run.
  215.  
  216. To run the example on two machines, proceed as follows:
  217.  
  218.   1.  Change to the server directory (server) on the machine
  219.       running the server and start the server:
  220.  
  221.            server
  222.  
  223.   2.  Change to the client directory (client) on the machine
  224.       running the client and start the client:
  225.  
  226.            client
  227.  
  228.  
  229.  
  230.  
  231.  
  232. 9.  Description
  233.  
  234. This example demonstrates a client that uses a non-blocking
  235. RPC interface.  Using this interface, the client can
  236. generate an RPC request and continue executing until the RPC
  237. reply is returned by the server.  Once the reply is
  238. received, the client can then obtain the results returned by
  239. the remote procedure.
  240.  
  241. To facilitate the use of this style of asynchronous client
  242. interface, this example separates the non-blocking client
  243. code into a special RPC specification called "async1_i.rpc."
  244. This RPC specification contains Hooks and Traps statements
  245. to customize client stubs so that they do not block for
  246. replies.  Thus, by importing "async1_i.rpc" within an RPC
  247. specification, all client stubs generated from this
  248. specification provide an asynchronous client interface to
  249. the described remote procedures.
  250.  
  251. Once the client stubs have been customized to incorporate
  252. the asynchronous code, the client can call a client stub to
  253. generate a request and send this to the server.  Having
  254. initiated the remote procedure, the client stub returns to
  255. the client code so that this code can continue execution.
  256. Once the reply has been received, the client code can once
  257. again call the client stub.  This second call to the client
  258. stub receives the reply, unpacks the results, and returns
  259. these results to the client code.  To ensure that the
  260. results are handled properly, the client code must call the
  261. client stub twice with exactly the same parameters.
  262.  
  263. Unlike the "async_i.rpc" specification shown in the async
  264. example, the "async1_i.rpc" specification customizes client
  265. stubs so that information about expected reply messages is
  266. stored in dynamically allocated memory referenced by a
  267. parameter passed to and returned by every client stub.  This
  268. parameter, called "cli_rpc_handle", must be declared as a
  269. pointer to a character pointer and must be declared as a
  270. parameter within every client stub.  By using these
  271. parameters, the client can issue several RPC requests
  272. simultaneously to different servers and continue executing
  273. until any of the replies are detected.
  274.  
  275. To assist in determining when the reply has been received,
  276. the "async1_i.rpc" specification is accompanied by an object
  277. module containing a routine called poll_reply.  This routine
  278. is declared as follows:
  279.  
  280.      int poll_reply(char *rpc_handle)
  281.  
  282. Whenever poll_reply is called, this procedure must be passed
  283. a character pointer initialized by a call to a client stub.
  284. The poll_reply procedure then determines the status
  285. concerning the reply associated with the remote procedure
  286. call identified by the rpc_handle parameter.  The poll_reply
  287. procedure then returns an integer value.
  288.  
  289. A value of 1 means that a reply has been received; call the
  290. stub again with exactly the same parameters as before.
  291. A value of 0 means that a reply has not been received yet;
  292. continue as before, but do not call the stub yet.
  293. An error code value means that an error was detected; call
  294. the stub again with exactly the same parameters as before so
  295. the state machine can clean up.
  296.  
  297. Using the poll_reply procedure, the client can determine
  298. when to call the client stub procedure again in order to
  299. handle the reply sent by the server.
  300.  
  301. Note that, unlike the async example, the client can use this
  302. interface to issue several RPC requests simultaneously.
  303. However, there is no guarantee that any one server can
  304. handle more than a single pending RPC request from the
  305. client.  Thus, to ensure proper interaction, the client must
  306. only issue one RPC request at a time to a single server.
  307.  
  308. Further note that a server requires no special modifications
  309. to interact with an asynchronous client.  In fact, the same
  310. server may interact with both synchronous and asynchronous
  311. clients.
  312.  
  313. However, the RPC specification for the application does
  314. require modification.  In order to pass the RPC state
  315. information to the client stub (in the "cli_rpc_handle"
  316. variable), the RPC specification that declares the remote
  317. procedures must specify that an extra parameter is being
  318. "passed" to each remote procedure.  Then, using Entry and
  319. Exit statements in the client stub customization code, the
  320. client stub can access that parameter.  Note that, in fact,
  321. the parameter is passed to each remote procedure, but it can
  322. safely be ignored, as its only use is in the client stub
  323. code.
  324.  
  325. For more information on adding custom code, see the
  326. NetWare RPC User's Manual, "Customizing the RPC Code,"
  327. Chapter 7.
  328.