home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / TIMER / README
Encoding:
Text File  |  1989-12-11  |  9.1 KB  |  281 lines
  1.                        timer 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 shows how to add custom code to an RPC
  18. specification so that a client can set a limit on the time
  19. it waits for a response from a remote procedure.
  20.  
  21.  
  22.  
  23.  
  24. 3.  Keywords
  25.  
  26. timeout, Hooks, Traps, RPC macros, polling
  27.  
  28.  
  29.  
  30.  
  31. 4.  Files
  32.  
  33. Source files for this example reside in the following sub-
  34. directories:
  35.  
  36. server:
  37.  
  38.      Contains code and build procedures for the server part
  39.      of this distributed application.  The server consists
  40.      of the server control procedure, which is provided with
  41.      the product distribution, the dispatcher procedure and
  42.      server stub routines, which are generated by the RPC
  43.      Compiler, and the remote procedures, which are provided
  44.      with this example.
  45.  
  46.      rproc.c       remote procedure application code
  47.  
  48.      server.mk     makefile for building the server
  49.  
  50.      serv_def.h    include file with macro definitions for
  51.                    the server control procedure
  52.  
  53. client:
  54.  
  55.      Contains code and build procedures for the client part
  56.      of this distributed application.  The client consists
  57.      of the client main program and any associated routines,
  58.      which are provided with this example, and the client
  59.      stubs, which are generated by the RPC compiler.
  60.  
  61.      client.c      client application code (main program)
  62.  
  63.      client.mk     makefile for building the client
  64.  
  65. common:
  66.  
  67.      Contains the RPC interface specification used by the
  68.      RPC compiler to create the client and server stubs.
  69.      The RPC interface specification imports the timer RPC
  70.      specification file to provide the time-out interface.
  71.  
  72.      timer.rpc     RPC interface specification for this
  73.                    example
  74.  
  75. timer:
  76.  
  77.      Contains the RPC interface specification consisting of
  78.      client stub Hooks code and the source code for
  79.      poll_reply, which provide for a time-out interface.
  80.  
  81.      timer_i.rpc   timer RPC specification and polling
  82.                    routine
  83.  
  84.      timer_i.mk    makefile for building the timer library
  85.                    and include file
  86.  
  87.      Note that the RPC Compiler is run only once with this
  88.      RPC specification file as input.  Generally, the
  89.      Compiler should be run with the file twice: once for
  90.      the client and once for the server, producing header
  91.      files and RPC code files for each.  However, for this
  92.      example the procedure is simplified because the single
  93.      header file produced can be used by both the client and
  94.      the server, the RPC Compiler is told to run in client
  95.      mode, and the only application code in the file is for
  96.      the client.
  97.  
  98.  
  99.  
  100.  
  101. 5.  Network Configuration
  102.  
  103. Before you can run this example, you may have to ask your
  104. system administrator to configure your system specifically
  105. for your needs.  The required configuration is described in
  106. the file: ..\..\READSPX
  107.  
  108.  
  109.  
  110.  
  111. 6.  Server Name
  112.  
  113. As distributed, the server for this example will register
  114. under the name "example".  However, it is strongly suggested
  115. that a unique server name be assigned to this example before
  116. it is built.
  117.  
  118. A unique server name will prevent two or more users from
  119. invoking a server process using the same server name.
  120. Choose a server name not likely to be selected by someone
  121. else.  For example, use your user or login name.
  122.  
  123. The server name must be changed in both the client and the
  124. server, and the SAME name must be used.  To change the
  125. server name for the client program, change to the client
  126. directory (client) and edit the file client.c.  Change the
  127. #define Server_Name statement as follows:
  128.  
  129.       #define Server_Name "example"
  130.           is changed to
  131.       #define Server_Name "myname"
  132.  
  133. To change the server name for the server program, change to
  134. the server directory (server) and edit the file serv_def.h,
  135. which contains the define statements for the server control
  136. procedure.  As with the client program, simply change the
  137. #define Server_Name statement.
  138.  
  139.  
  140.  
  141.  
  142. 7.  Building Client & Server
  143.  
  144. Procedures are included for building the example program.
  145. These procedures assume that your environment is set up as
  146. follows:
  147.  
  148.    - The PATH environment variable must specify the location
  149.      of the RPC Compiler executable files.
  150.  
  151.    - The LIB environment variable must specify the location
  152.      of the RPC runtime libraries.
  153.  
  154.    - The INCLUDE environment variable must specify the
  155.      location of the RPC .h include files.
  156.  
  157.    - The PDUDIR environment variable must specify the
  158.      location of the RPC .rpc files.
  159.  
  160.    - The RPCSCP environment variable must specify the
  161.      location of the RPC server control procedures.
  162.  
  163. The PATH, LIB, and INCLUDE environment variables should be
  164. set in your autoexec.bat file by modifying their current
  165. definitions. The PDUDIR and RPCSCP environment variables can
  166. be set in your autoexec.bat file, or in a local .bat file,
  167. or directly with the "set" command.
  168.  
  169. Since a distributed application runs on two machines, you
  170. must install an executable version of the client or server
  171. on another machine.  If the two machines are identical, you
  172. can build both executables (the client and server) on one
  173. machine and then move one of the executables.  However, if
  174. the two machines are not identical, you must follow the
  175. directions on the other machine for running this example and
  176. build one of the executable programs there (note that the
  177. executable filenames may differ across products).
  178.  
  179. Note that with the Microsoft C Compiler and utilities,
  180. numerous warnings will be generated when executing the
  181. makefiles. For example, you may see a "target does not
  182. exist" or "module not in library" warning. These simply mean
  183. that the file the makefile is currently creating does not
  184. yet exist. Generally, all warnings may be ignored.
  185.  
  186. To build the example program, you simply execute the build
  187. procedures in each subdirectory as follows:
  188.  
  189.   1.  Change to the timer directory and build the files
  190.       associated with the imported RPC specification file:
  191.  
  192.            make timer_i.mk
  193.  
  194.   2.  Change to the client directory (client) and build the
  195.       client:
  196.  
  197.            make client.mk
  198.  
  199.   3.  Change to the server directory (server) and build the
  200.       server:
  201.  
  202.            make server.mk
  203.  
  204.  
  205.  
  206.  
  207.  
  208. 8.  Running the Distributed Application
  209.  
  210. The server program should be started before the client
  211. program is run.
  212.  
  213. To run the example on two machines, proceed as follows:
  214.  
  215.   1.  Change to the server directory (server) on the machine
  216.       running the server and start the server:
  217.  
  218.            server
  219.  
  220.   2.  Change to the client directory (client) on the machine
  221.       running the client and start the client:
  222.  
  223.            client -l loops
  224.  
  225.       If the argument "loops" is passed to the client, it
  226.       specifies the number of times the remote procedures
  227.       are called. If no argument is specified, the
  228.       procedures are called only once.
  229.  
  230.  
  231.  
  232.  
  233. 9.  Description
  234.  
  235. This example shows how to add custom code to an RPC
  236. specification so that a client can set a limit on the time
  237. it waits for a response from a remote procedure.
  238.  
  239. To facilitate the ability of the client to limit time for a
  240. remote procedure call, this example separates the client
  241. timer code into a special RPC specification called
  242. "timer_i.rpc." This RPC specification contains Hooks
  243. statements to customize client stubs so that they do not
  244. wait for replies beyond a specified time limit.  By
  245. importing "timer_i.rpc" within an RPC specification, all
  246. client stubs generated from this specification provide
  247. client interfacse to the described remote procedures that
  248. can limit time spent waiting for replies.
  249.  
  250. Once the client stubs have been customized to incorporate
  251. the timer code, the client can call a client stub to
  252. generate a request and send this request to the server.
  253. Having initiated the remote procedure call, the client stub
  254. polls to determine if a reply has been received.  If one is
  255. not received within a specified time, the client stub
  256. returns an error code to the client, as defined in the
  257. imported RPC specification "timer_i.rpc."
  258.  
  259. To assist in determining when the reply message has been
  260. received, the "timer_i.rpc" specification is accompanied by
  261. a library containing a routine called poll_reply.  This
  262. procedure returns an integer value.
  263.  
  264. A value of 1 means that a reply has been received; call the
  265. stub again with exactly the same parameters as before.
  266. A value of 0 means that a reply has not been received yet;
  267. continue as before, but do not call the stub yet.
  268. An error code value means that an error was detected; call
  269. the stub again with exactly the same parameters as before so
  270. the state machine can clean up.
  271.  
  272. Using the poll_reply procedure, the client stub can
  273. determine when the reply has been received from the server.
  274.  
  275. Note that a server requires no special modifications to
  276. interact with a client that includes this timer code.
  277.  
  278. For more information on adding custom code, see the
  279. NetWare RPC User's Manual, "Customizing the RPC Code,"
  280. in Chapter 7.
  281.