home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 11 / 11.iso / n / n001 / 2.ddi / EXAMPLES / DEBUG / README
Encoding:
Text File  |  1989-12-11  |  7.9 KB  |  261 lines
  1.                        debug 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 demonstrates how to incorporate debug code
  18. within the generated RPC code.  Using this debug code, you
  19. will be able to determine problems more readily within your
  20. distributed software.
  21.  
  22.  
  23.  
  24.  
  25. 3.  Keywords
  26.  
  27. error handling, Hooks, Traps, RPC macros, 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 debug RPC
  71.      specification file to provide the display of debugging
  72.      information.
  73.  
  74.      debug.rpc     RPC interface specification for this
  75.                    example
  76.  
  77. debug:
  78.  
  79.      Contains the RPC interface specification consisting of
  80.      client stub, server stub, and dispatcher Hooks and
  81.      Traps code, which provides a display of debugging
  82.      information.
  83.  
  84.      debug_i.rpc   debug RPC specification
  85.  
  86.      debug_i.mk    makefile for building the debug_i include
  87.                    file
  88.  
  89.      Note that the RPC Compiler is run only once with this
  90.      RPC specification file as input.  Generally, the
  91.      Compiler should be run with the file twice: once for
  92.      the client and once for the server, producing header
  93.      files and RPC code files for each.  However, for this
  94.      example the procedure is simplified because the single
  95.      header file produced can be used by both the client and
  96.      the server, and only customization statements are
  97.      included in the file, so the created RPC code file can
  98.      be ignored.
  99.  
  100.  
  101.  
  102.  
  103. 5.  Network Configuration
  104.  
  105. Before you can run this example, you may have to ask your
  106. system administrator to configure your system specifically
  107. for your needs.  The required configuration is described in
  108. the file: ..\..\READSPX
  109.  
  110.  
  111.  
  112.  
  113. 6.  Server Name
  114.  
  115. As distributed, the server for this example will register
  116. under the name "example".  However, it is strongly suggested
  117. that a unique server name be assigned to this example before
  118. it is built.
  119.  
  120. A unique server name will prevent two or more users from
  121. invoking a server process using the same server name.
  122. Choose a server name not likely to be selected by someone
  123. else.  For example, use your user or login name.
  124.  
  125. The server name must be changed in both the client and the
  126. server, and the SAME name must be used.  To change the
  127. server name for the client program, change to the client
  128. directory (client) and edit the file client.c.  Change the
  129. #define Server_Name statement as follows:
  130.  
  131.       #define Server_Name "example"
  132.           is changed to
  133.       #define Server_Name "myname"
  134.  
  135. To change the server name for the server program, change to
  136. the server directory (server) and edit the file serv_def.h,
  137. which contains the define statements for the server control
  138. procedure.  As with the client program, simply change the
  139. #define Server_Name statement.
  140.  
  141.  
  142.  
  143.  
  144. 7.  Building Client & Server
  145.  
  146. Procedures are included for building the example program.
  147. These procedures assume that your environment is set up as
  148. follows:
  149.  
  150.    - The PATH environment variable must specify the location
  151.      of the RPC Compiler executable files.
  152.  
  153.    - The LIB environment variable must specify the location
  154.      of the RPC runtime libraries.
  155.  
  156.    - The INCLUDE environment variable must specify the
  157.      location of the RPC .h include files.
  158.  
  159.    - The PDUDIR environment variable must specify the
  160.      location of the RPC .rpc files.
  161.  
  162.    - The RPCSCP environment variable must specify the
  163.      location of the RPC server control procedures.
  164.  
  165. The PATH, LIB, and INCLUDE environment variables should be
  166. set in your autoexec.bat file by modifying their current
  167. definitions. The PDUDIR and RPCSCP environment variables can
  168. be set in your autoexec.bat file, or in a local .bat file,
  169. or directly with the "set" command.
  170.  
  171. Since a distributed application runs on two machines, you
  172. must install an executable version of the client or server
  173. on another machine.  If the two machines are identical, you
  174. can build both executables (the client and server) on one
  175. machine and then move one of the executables.  However, if
  176. the two machines are not identical, you must follow the
  177. directions on the other machine for running this example and
  178. build one of the executable programs there (note that the
  179. executable filenames may differ across products).
  180.  
  181. Note that with the Microsoft C Compiler and utilities,
  182. numerous warnings will be generated when executing the
  183. makefiles. For example, you may see a "target does not
  184. exist" or "module not in library" warning. These simply mean
  185. that the file the makefile is currently creating does not
  186. yet exist. Generally, all warnings may be ignored.
  187.  
  188. To build the example program, you simply execute the build
  189. procedures in each subdirectory as follows:
  190.  
  191.   1.  Change to the debug directory and build the files
  192.       associated with the imported RPC specification file:
  193.  
  194.            make debug_i.mk
  195.  
  196.   2.  Change to the client directory (client) and build the
  197.       client:
  198.  
  199.            make client.mk
  200.  
  201.   3.  Change to the server directory (server) and build the
  202.       server:
  203.  
  204.            make server.mk
  205.  
  206.  
  207.  
  208.  
  209.  
  210. 8.  Running the Distributed Application
  211.  
  212. The server program should be started before the client
  213. program is run.
  214.  
  215. To run the example on two machines, proceed as follows:
  216.  
  217.   1.  Change to the server directory (server) on the machine
  218.       running the server and start the server:
  219.  
  220.            server
  221.  
  222.   2.  Change to the client directory (client) on the machine
  223.       running the client and start the client:
  224.  
  225.            client
  226.  
  227.  
  228.  
  229.  
  230.  
  231. 9.  Description
  232.  
  233. This example demonstrates how to incorporate debug code
  234. within the generated RPC code.  Using this debug code, you
  235. will be able to determine problems more readily within your
  236. distributed software.
  237.  
  238. The debug code is found in an RPC specification called
  239. "debug_i.rpc." This debug code is added using Hooks and
  240. Traps statements.  Other specifications, including the one
  241. shown in this example, can incorporate the debug code by
  242. importing "debug_i.rpc."
  243.  
  244. Once included, the debug code will display error messages
  245. whenever an error is detected within the RPC code.
  246.  
  247. If you wish to perform more exhaustive debugging, consider
  248. using #define statements to initialize the following defined
  249. constants:
  250.  
  251. SHOW_DETAILS - once defined, exhaustive error messages are
  252. displayed upon every exception
  253.  
  254. SHOW_STATES - once defined, all state transitions are shown
  255.  
  256. The RPC specification show in this example demonstrates how
  257. to define these values.
  258.  
  259. For more information on handling errors, see the NetWare RPC
  260. User's Manual, Chapter 8, "Error Handling."
  261.