home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / da2dem.zip / READ.ME < prev    next >
Text File  |  1993-12-17  |  21KB  |  494 lines
  1.  
  2.                    INTRODUCING DISTRIBUTED APPLICATION/2 (DA/2)
  3.                          - Demonstration Version -
  4.  
  5. ┌──────────────────────────────────────────────────────────────────────────┐
  6. │                            *** NOTICE ***                                │
  7. │ This version of DA/2 was developed especially for the IBM Developer's    │
  8. │ Connection for OS/2 CD-ROM.  It has also been uploaded to CompuServe and │
  9. │ the OS/2 BBS.                                                            │
  10. │                                                                          │
  11. │ You will be able to write sample programs to see the capability of       │
  12. │ DA/2. However, the only data that will flow between a client and         │
  13. │ a server are the words "Developers Connection".                          │
  14. └──────────────────────────────────────────────────────────────────────────┘
  15.  
  16. Distributed Application/2 is a set of application programming interfaces
  17. (APIs) that provide a consistent way to access interprocess and network com-
  18. munication functions under Operating System/2(*) (OS/2*), making
  19. client/server applications easier to create than ever.  Distributed
  20. Application/2 supplies you with a set of APIs designed to help you compete in
  21. the growing client/server programming arena.  The Distributed Application/2
  22. APIs hide the complexity of the supported communications protocols and enable
  23. you to select a communications protocol for your application at run time
  24. without requiring you to change your code.
  25.  
  26. Distributed Application/2 supports the following communications protocols:
  27.  
  28. o   Advanced program-to-program communication (APPC)
  29. o   NetBIOS
  30. o   OS/2 named pipes
  31.  
  32. By supporting these multiple protocols, Distributed Application/2 APIs can be
  33. used to communicate between two threads in a process, two processes in an
  34. application, two modules across a network, or within a program on a single
  35. machine.  You just choose the protocol you wish to use for each communication
  36. conversation.
  37.  
  38. Specifically, Distributed Application/2 starts with a set of simple APIs that
  39. support the transfer of data through the concepts of OPEN, WRITE, READ, and
  40. CLOSE.  These APIs also include features designed to make synchronization
  41. between components easier, such as waiting for a specific message.
  42.  
  43. Distributed Application/2 also provides you with a set of advanced APIs
  44. designed for the server.  These, together with the OPEN, WRITE, READ, and
  45. CLOSE APIs, provide an easy mechanism to synchronize communication between
  46. your running server and multiple clients.
  47.  
  48. The Distributed Application/2 APIs have been enabled for C and REXX;  This
  49. allows you to write distributed applications in multiple programming lan-
  50. guages.
  51.  
  52. You can also use Distributed Application/2 to communicate between
  53. program using Distributed Application/2 and a partner using native APPC calls.
  54.  
  55. This includes:
  56.  
  57. - APPC calls supported by Information Management System (IMS) V4.1
  58.   on an MVS host system
  59.  
  60. - APPC calls supported by Information Management System (IMS)
  61.   using the LU 6.1-LU 6.2 adapter for applications on an MVS host system
  62.  
  63. - APPC calls supported by the DA2SERV CICS program that we provide. This
  64.   gives you access to CICS applications that are not 3270 oriented.
  65.  
  66. - Other APPC subsystems
  67.  
  68.  
  69. When you purchase Distributed Application/2, you receive:
  70.  
  71. o   The APIs enabled for C and REXX
  72.  
  73. o   Complete online documentation for the APIs
  74.  
  75. o   A user-interface facility to manage run-time information
  76.  
  77. o   A utility to rename the redistributable components
  78.  
  79. o   The object file of the host CICS server program for catching
  80.     requests from DA/2 programs.
  81.  
  82.  
  83. SPECIFIED OPERATING ENVIRONMENT
  84. _______________________________
  85.  
  86.  
  87. MACHINE REQUIREMENTS
  88.  
  89. o   A personal computer running OS/2 Version 2.0 or 2.1.
  90.  
  91.     NOTE:  For more information on the OS/2 Version 2.0 machine requirements,
  92.     refer to the IBM OS/2 Version 2.0 Information and Planning Guide
  93.                  ___________________________________________________
  94.     (G326-0160)
  95.  
  96. o   1 MB of hard disk space above that required by OS/2
  97.  
  98. o   .5 MB of memory above that required by OS/2
  99.  
  100. o   2-button mouse or other pointing device
  101.  
  102.  
  103. PROGRAM REQUIREMENTS
  104.  
  105. o   OS/2 Version 2.0 operating system (with ServicePak XR06055)
  106.  
  107. o   IBM Developers Toolkit for OS/2 Version 2.0.
  108.  
  109. o   OS/2 Version 2.1 operating system
  110.  
  111. o   To use Distributed Application/2 with NetBIOS, you need one of the
  112.     following:
  113.  
  114.     -   The LAN Requester feature of OS/2 LAN Server Version 2.0,
  115.         in which case any NetBIOS communication partners must also have
  116.         an IBM LAN requester installed.
  117.  
  118.     -   The LAN Requester feature of OS/2 LAN Server Version 3.0,
  119.         in which case any NetBIOS communication partners must also have
  120.         an IBM LAN requester installed.
  121.  
  122.     -   Novell(**) NetWare(**) Requester for OS/2 2.0 with the Novell
  123.         NetBIOS emulator, in which case any NetBIOS communication
  124.         partners must also have the Novell NetWare requester installed.
  125.  
  126. o   To use Distributed Application/2 with APPC, you also need Extended Ser-
  127.     vices for OS/2 Version 2.0 or Communications Manager/2.
  128.  
  129. Note:  If you are using OS/2 Version 2.0, you should have ServicePak
  130.        XR06055.  However, you may find that Distributed Application/2
  131.        runs on a machine without the SevicePak.
  132.        Please note, however, that service for Distributed Application/2
  133.        is provided only for systems that meet the Program Requirements
  134.        listed above.
  135.  
  136.  
  137. INSTALLING DISTRIBUTED APPLICATION/2
  138. ____________________________________
  139.  
  140. This section contains information needed to install this demonstration
  141. version of Distributed Application/2.  You will use the standard Distributed
  142. Application/2 installation process that you would use after purchasing
  143. the product.  However, in this case, you will be using a directory on
  144. your hard disk as the "source" of the installation, instead of a diskette
  145. drive.
  146.  
  147. Since you are reading this READ.ME file, we assume you have
  148. unpacked the DA2DEM.ZIP file, and its contents are all in one directory.
  149. This will be used as the "source" directory for the installation.
  150. For purposes of this explanation, the directory is called C:\DA2DEMO.
  151.  
  152. 1.  Type the following on the OS/2 command line:
  153.  
  154.       C:\DA2DEMO\INSTALL
  155.  
  156. 3.  Press Enter.
  157.  
  158. 4.  Follow the on-screen prompts displayed by the installation and
  159.     maintenance utility.
  160.  
  161. You are now ready to use Distributed Application/2.  You can erase all of
  162. the files in the "source" installation directory (C:\DA2DEMO).  After you are
  163. finished using the demo, you can use the Installation Utility to delete it.
  164. Open the DA/2 folder, and use the delete option of the utility.
  165.  
  166.  
  167. UPDATING YOUR CONFIG.SYS FILE MANUALLY
  168.  
  169. The installation and maintenance utility copies all the files necessary to
  170. run Distributed Application/2 to your computer's hard disk and automatically
  171. updates your CONFIG.SYS file.
  172.  
  173. If you want to override the default settings and make your own changes to the
  174. CONFIG.SYS file, select UPDATE CONFIG.SYS from the Install window and remove
  175. the check from the checkbox.
  176.  
  177. Distributed Application/2 installs its files in subdirectories of C:\IBMDA.
  178. However, you can override this directory setting at the time of installation
  179. to give the C:\IBMDA directory a different name or to put it on a different
  180. drive.  The following list shows which directories need to be added to the
  181. statements in your CONFIG.SYS file.
  182.  
  183. NOTE:  If you choose a directory other than C:\IBMDA, these directories will
  184. be different on your system.
  185.  
  186. +-------------------------------------+-------------------------------------+
  187. | ADD THIS DIRECTORY:                 | TO THE:                             |
  188. +-------------------------------------+-------------------------------------+
  189. | C:\IBMDA\BIN                        | LIBPATH                             |
  190. +-------------------------------------+-------------------------------------+
  191. | C:\IBMDA\BIN                        | PATH                                |
  192. +-------------------------------------+-------------------------------------+
  193. | C:\IBMDA\BIN                        | INCLUDE                             |
  194. +-------------------------------------+-------------------------------------+
  195. | C:\IBMDA\BIN                        | LIB                                 |
  196. +-------------------------------------+-------------------------------------+
  197. | C:\IBMDA\BIN                        | HELP                                |
  198. +-------------------------------------+-------------------------------------+
  199. | C:\IBMDA\BOOK                       | BOOKSHELF                           |
  200. +-------------------------------------+-------------------------------------+
  201. | C:\IBMDA\CICS\SAMPLES               | PATH                                |
  202. +-------------------------------------+-------------------------------------+
  203.  
  204. Also be sure that any directory in which you intend to keep a connection
  205. profile file (IBMDABB.CP) is added to your DPATH.
  206.  
  207.  
  208. ACCESSING THE ONLINE DOCUMENTATION
  209.  
  210. When you install Distributed Application/2, the installation and maintenance
  211. utility optionally installs the following documents:
  212.  
  213. o   IBM Distributed Application/2 C Guide and Reference
  214.     ___________________________________________________
  215.  
  216. o   IBM Distributed Application/2 REXX Guide and Reference
  217.     ______________________________________________________
  218.  
  219. To access these online documents from the OS/2 command line, do the
  220. following:
  221.  
  222. 1.  Change to the directory in which you want to view the online documents.
  223.     The default directory name is C:\IBMDA.
  224.  
  225. 2.  Type the following on the OS/2 command line:
  226.  
  227.     o   "VIEW EPFDACG.INF" to access the Distributed Application/2 C Guide
  228.                                          _________________________________
  229.     o   "VIEW EPFDARXG.INF" to access the Distributed Application/2 REXX
  230.                                           ______________________________
  231.         Guide
  232.         _____
  233.  
  234. 3.  Press Enter.  You will see the Contents window.
  235.  
  236. 4.  Double-click on the topic you want to view.
  237.  
  238.  
  239. RUNNING THE DISTRIBUTED APPLICATION/2 (DA/2) SAMPLES
  240. ____________________________________________________
  241.  
  242. We assume you have installed the product (or demonstration version),
  243. and have re-booted your PC so that the new PATH and LIBPATH statements
  244. in your CONFIG.SYS have been activated.  For this explanation, we'll
  245. use C:\IBMDA as the name of the directory into which you have installed
  246. DA/2.  If you installed DA/2 into a different directory, you'll need to
  247. use that name in place of C:\IBMDA in the instructions.  We describe how
  248. to run the REXX sample, and the C sample.  You can run either one
  249. (or both) by following these instructions.
  250.  
  251. Running the REXX Sample
  252. -----------------------
  253.  
  254. 1. >Make the samples directory current.<  In an OS/2 window command
  255.    prompt, run these commands, pressing enter after each one:
  256.  
  257.    C:
  258.    CD C:\IBMDA\SAMPLES
  259.  
  260. 2. >Run the REXX sample.<  From the same window command prompt, run the
  261.    client portion of the sample by running this command:
  262.  
  263.    RXCLIENT
  264.  
  265.    2a. >Specify the symbolic name.<  The sample will prompt you for the
  266.        symbolic name of the connection.  Enter this:
  267.  
  268.        RXSAMPLE
  269.  
  270.        Hint: You can discover which connections are defined for the samples
  271.        by starting the Connection Profile Editor from the DA/2 folder on
  272.        the desktop.  Then use the File/Open... pulldown to open this file:
  273.  
  274.        C:\IBMDA\SAMPLES\IBMDABB.CP
  275.  
  276.        Note:            +---> IBMDABB = DA/2
  277.                                 +---> .CP = Connection Profile
  278.  
  279.        Each connection defined in the profile is displayed as an icon, with
  280.        its symbolic name below.  You can double-click on any of the icons
  281.        to examine the details and parameters for that connection.
  282.  
  283.    2b. >Note how the server gets started.<  DA/2 can automatically start
  284.        server programs for you, if they're not already running.  The REXX
  285.        sample starts the server program, RXSERVER.CMD, in an OS/2 window.
  286.        In this sample, the server terminates after the connection is
  287.        closed.
  288.  
  289.    2c. >Some errors matter, and some don't.<  You should see some character
  290.        strings displayed on the client window.  If you see 'Invalid Response'
  291.        messages in the window, it means you're running the demonstration
  292.        version of the DA/2.  That's ok.  Other error messages usually mean
  293.        you have not installed DA/2 correctly.
  294.  
  295. 3. >Learn more by examining the documentation and sample code.<  You should
  296.    take some time to look at the source code for the samples, and the
  297.    online documentation.  This will help you understand more about how
  298.    DA/2 works, and how you can use it to build your client/server
  299.    applications.
  300.  
  301. Running the C Sample
  302. --------------------
  303.  
  304. 1. >Make the samples directory current.<  In an OS/2 window command
  305.    prompt, run these commands, pressing enter after each one:
  306.  
  307.    C:
  308.    CD C:\IBMDA\SAMPLES
  309.  
  310. 2. >Run the C sample.<  The C sample requires you to specify some
  311.    parameters when you run the program.  If you run CCLIENT without
  312.    any, you'll see this brief explanation:
  313.  
  314.       usage: CCLIENT [/R] filename connName
  315.  
  316.       where:  /R  is request response on every DAWrite
  317.  
  318.    At a minimum, you need to specify the filename and connName parameters.
  319.    The filename is any text file containing data you'd like sent to the
  320.    server.  The connection name is the symbolic name of the connection
  321.    between the client and server programs.  (See the "Hint:" in step 2a,
  322.    above, for more information on the connection name.)  Type this command:
  323.  
  324.    CCLIENT CSAMPLES.MAK CSAMPLE
  325.  
  326.    and press enter.
  327.  
  328.    2b. >Note how the server gets started.<  DA/2 can automatically start
  329.        server programs for you, if they're not already running.  The C
  330.        sample starts the server program, CSERVER.CMD, in an OS/2 window.
  331.        In this sample, the server remains running after the connection is
  332.        closed.
  333.  
  334.    2c. >Look for the results.<  The server will write the contents of the
  335.        data it receives to an output file, CSERVER.00n.  'n' will be '0' the
  336.        first time the sample is run (it's a C sample, after all!), and
  337.        will be incremented by 1 each subsequent time you run the sample.
  338.        In this case, CSERVER.000 will contain the contents of CSAMPLES.MAK,
  339.        the filename you specified when running CCLIENT.
  340.  
  341.        If you are using the demonstration version of DA/2, the output file
  342.        written by the server program will only contain:
  343.           "Developer's Connection"
  344.        That's the only data that gets written between client and server.
  345.  
  346. 3. >Learn more by examining the documentation and sample code.<  You should
  347.    take some time to look at the source code for the samples, and the
  348.    online documentation.  This will help you understand more about how
  349.    DA/2 works, and how you can use it to build your client/server
  350.    applications.
  351.  
  352.  
  353. ADDITIONAL INFORMATION FOR THIRD-PARTY DISTRIBUTORS
  354. ___________________________________________________
  355.  
  356. We provide the source files for the online help that you can customize
  357. if you want.
  358.  
  359.  
  360. COMPILING THE ONLINE HELP (EPFPROF.HLP)
  361. _______________________________________
  362.  
  363. The source help file for Distributed Application/2 is EPFPROF.IPF.  You can
  364. change the text in this file. After changing the text, you must recompile
  365. this .IPF file to obtain the .HLP file. The compiler, IPFC.EXE, is part of
  366. the IBM Developers Toolkit for OS/2 2.0.
  367.  
  368. NOTE:  DO NOT change the resource ids (res=nnnn) that identify the help
  369. panels.  The resource ids associate the help panels with the product's source
  370. code.  DO NOT add or delete help panels or their resource ids.
  371.  
  372. 1.  Run IPFC.EXE on EPFPROF.IPF.
  373.  
  374.       IPFC EPFPROF.IPF >ERRORS.TXT
  375.  
  376. 2.  Check the compile messages and statistics in ERRORS.TXT.
  377.  
  378. 3.  If you have errors in the ERRORS.TXT file, make corrections to
  379.     EPFPROF.IPF and repeat steps 1 and 2.
  380.  
  381. EPFPROF.HLP is the online help that can be viewed on the workstation while
  382. using Distributed Application/2.
  383.  
  384.  
  385. CONTENTS OF PRODUCT
  386. _______________________________________
  387.  
  388. The following is a list of the files that are copied to your workstation
  389. when you install Distributed Application/2.  Next to each is a brief
  390. description of the file.  If you chose C:\IBMDA as your install
  391. directory, your installation should look like this:
  392.  
  393. Directory of C:\IBMDA
  394.  
  395.    bin (directory) ....... Contains DA/2 product
  396.    book (directory) ...... Contains DA/2 product documentation
  397.    CONFIG.BAK   .......... Backup of your CONFIG.SYS file (if updated)
  398.    EPFDACAT.ICF .......... Catalog file used for Installation
  399.    EPFDAPKG.PKG .......... Package file used for Installation
  400.    EPFDADSC.DSC .......... Description file used for Installation
  401.    READ.ME      .......... DA/2 READ.ME file
  402.    samples (directory).... Contains DA/2 samples
  403.  
  404. Directory of C:\IBMDA\BIN
  405.  
  406.    EPFAPPC.DLL  .......... DA/2 APPC module
  407.    EPFDAREX.DLL .......... DA/2 Rexx bindings module
  408.    EPFNETB.DLL  .......... DA/2 NetBIOS module
  409.    EPFNETBL.EXE .......... DA/2 NetBIOS daemon
  410.    EPFNP.DLL    .......... DA/2 Named Pipes module
  411.    EPFOCRW.DEF  .......... DA/2 .DEF file to create .LIB file
  412.    EPFOCRW.DLL  .......... DA/2 Main module
  413.    EPFOCRW.H    .......... DA/2 Header file
  414.    EPFOCRW.LIB  .......... DA/2 Library file for linking
  415.    EPFPROF.DLL  .......... DA/2 Connection Profile Editor resource module
  416.    EPFPROF.EXE  .......... DA/2 Connection Profile Editor
  417.    EPFPROF.HLP  .......... DA/2 Connection Profile Editor Help file
  418.    EPFPROF.IPF  .......... DA/2 Connection Profile Editor Help file source
  419.    EPFLEVEL.CMD .......... Extracts version level from module
  420.    DAREN.CMD    .......... Command file to rename re-distributable modules
  421.    EPFRCOPY.EXE .......... Executable to rename re-distributable modules
  422.    EPFIDLDS.EXE .......... Installation utility file
  423.    EPFIEXTS.DLL .......... Installation utility file
  424.    EPFIHPLB.HLP .......... Installation utility file
  425.    EPFIICIS.ICO .......... Installation utility file
  426.    EPFIICO1.ICO .......... Installation utility file
  427.    EPFIMSG.MSG  .......... Installation utility file
  428.    EPFINSTS.EXE .......... Installation utility file
  429.    EPFIPII.DLL  .......... Installation utility file
  430.    EPFIPRCS.EXE .......... Installation utility file
  431.    EPFIUPCK.EXE .......... Installation utility file
  432.  
  433. Directory of C:\IBMDA\BOOK
  434.  
  435.    EPFDACG.INF  .......... DA/2 C Guide
  436.    EPFDARXG.INF .......... DA/2 REXX Guide
  437.  
  438. Directory of C:\IBMDA\SAMPLES
  439.  
  440.    CCLIENT.C    .......... DA/2 C client sample source
  441.    CCLIENT.EXE  .......... DA/2 C client sample executable
  442.    CSAMPLES.MAK .......... DA/2 Make file for C sample
  443.    CSERVER.C    .......... DA/2 C server sample source
  444.    CSERVER.EXE  .......... DA/2 C server sample executable
  445.    IBMDABB.CP   .......... DA/2 C and REXX sample connection profiles
  446.    RXCLIENT.CMD .......... DA/2 REXX client sample
  447.    RXSERVER.CMD .......... DA/2 REXX server sample
  448.  
  449.  
  450. Directory of C:\IBMDA\CICS
  451.  
  452.    DA2SERV.OBJ  .......... Host CICS object file for the DA/2 CICS Server
  453.    LINK.JCL     .......... Sample Host Link Edit JCL
  454.    INSTSAMP.COB .......... Sample CICS program used by the client samples
  455.  
  456. Directory of C:\IBMDA\CICS
  457.  
  458.    DA2SERV.OBJ  .......... Host CICS object file for the DA/2 CICS Server
  459.    DACLNT.H     .......... Include file for clients
  460.    HANDLERR.C   .......... Error handling sample source
  461.    HANDLERR.H   .......... Error handling sample include
  462.    HANDLERR.MAK .......... Error handling sample make file
  463.    PCCLNT.C     .......... PC Sample source
  464.    PCCLNT.EXE   .......... PC Sample executable
  465.    PCCLNT.MAK   .......... PC Sample make file
  466.    PICLNT.C     .......... PI Sample source
  467.    PICLNT.EXE   .......... PI Sample executable
  468.    PICLNT.MAK   .......... PI Sample make file
  469.    PMCLNT.C     .......... PM Sample source
  470.    PMCLNT.EXE   .......... PM Sample executable
  471.    PMCLNT.MAK   .......... PM Sample make file
  472.    QDCLNT.C     .......... QD Sample source
  473.    QDCLNT.EXE   .......... QD Sample executable
  474.    QDCLNT.MAK   .......... QD Sample make file
  475.    QKCLNT.C     .......... QK Sample source
  476.    QKCLNT.EXE   .......... QK Sample executable
  477.    QKCLNT.MAK   .......... QK Sample make file
  478.    QRCLNT.C     .......... QR Sample source
  479.    QRCLNT.EXE   .......... QR Sample executable
  480.    QRCLNT.MAK   .......... QR Sample make file
  481.    QWCLNT.C     .......... QW Sample source
  482.    QWCLNT.EXE   .......... QW Sample executable
  483.    QWCLNT.MAK   .......... QW Sample make file
  484.    RXPCCLNT.CMD .......... REXX Client sample
  485.    TESTCONF.CMD .......... REXX client sample for testing CONFIRM
  486.    TESTNOCF.CMD .......... REXX Client sample for testing NO CONFIRM
  487.  
  488. (*) IBM, Operating System/2, and OS/2 are trademarks of the IBM Corporation
  489.     in the United States and other countries.
  490.  
  491. (**) Novell is a trademark of Novell, Inc.
  492.  
  493. (**) NetWare is a trademark of Novell, Inc.
  494.