home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / api111.zip / README
Text File  |  1994-05-19  |  18KB  |  382 lines
  1.                            README (FILE)
  2.  
  3.                 IBM COMMUNICATIONS MANAGER/2 FOR OS/2
  4.  
  5.                            API SUPPORT
  6.  
  7.  
  8.    Communications Manager/2
  9.     - 5622-078 (C) Copyright IBM Corporation 1988, 1993
  10.  
  11.    LICENSE: You may copy and distribute the sample programs in this
  12.             directory in any form without payment to IBM, for the purpose
  13.             of developing, using, marketing or distributing application
  14.             programs for use with Communications Manager.
  15.  
  16.    The material in this directory could include technical inaccuracies, or
  17.    incompatibilities with IBM products, and could be modified or excluded
  18.    from the generally available reference materials.  IBM expressly
  19.    reserves the right, without notice to you, to implement or modify IBM
  20.    Operating System/2 and other IBM products in a manner that affects the
  21.    compatibility or usability of application programs developed by you
  22.    using this material.
  23.  
  24.    International Business Machines Corporation provides this directory
  25.    "as is" without warranty of any kind, either express or implied, including,
  26.    but not limited to, the implied warranties of merchantability or fitness
  27.    for a particular purpose.
  28.  
  29.    It is possible that this directory may contain references to, or
  30.    information about, IBM products (machines and programs), programming or
  31.    services that are not announced in your country.  Such references or
  32.    information must not be construed to mean that IBM intends to announce
  33.    such IBM products, programming or services in your country.
  34.  
  35.    This directory contains documentation, source files, and the supporting
  36.    files for the following Communications Manager/2 Application Program
  37.    Interfaces (APIs):
  38.  
  39.      1) APPC
  40.      2) Common Programming Interface - Communications (CPI-C)
  41.      3) Conventional LU Application (LUA)
  42.      4) Asynchronous Communication Device Interface (ACDI)
  43.      5) Environment Manager (CM Kernel)
  44.      6) Service Point Application Router & Remote Operations Service (ROPS)
  45.      7) Server-Requester Programming Interface (SRPI)
  46.      8) Emulator High Level Language API (EHLLAPI)
  47.      9) X.25
  48.     10) Connection Manager Interface for ISDN (CMI)
  49.  
  50.  
  51.    The C sample programs and related instructions have been developed for
  52.    use with the following C compilers:
  53.  
  54.      1) IBM C Set/2 (32-bit sample programs)
  55.      2) Microsoft C Version 6.0 (16-bit sample programs)
  56.  
  57.    The assembler sample programs and related instructions have been
  58.    developed for use with IBM Macro Assembler/2 (or equivalent).
  59.  
  60.    The COBOL sample programs and related instructions have been developed
  61.    for use with Microfocus COBOL (or equivalent).
  62.  
  63.    The BASIC sample programs and related instructions have been developed
  64.    for use with IBM BASIC/2 (or equivalent).
  65.  
  66.    The REXX sample programs and related instructions have been developed
  67.    for use with IBM REXX.
  68.  
  69.    The following files and subdirectories are in the samples directory:
  70.  
  71.      ACDI          ACDI samples
  72.      CMINCL        API data structures for C, IBM MACRO Assembler/2,
  73.                    and COBOL.  Assembler Interface Macros for SRPI.
  74.                    Communications Manager/2 interface for CPI-C REXX
  75.      CMKAPI        Environment Manager samples
  76.      CMLINK        Communications Manager/2 import libraries
  77.      CONFIG        Configuration Manager samples
  78.      HAPI          EHLLAPI samples
  79.      LUA           LUA samples
  80.      REACTX25      X.25 adapter reactivation sample
  81.      README        API Support documentation
  82.      ROPS          Remote Operations samples
  83.      SNA           APPC, CPI-C, System Management samples
  84.      SRPI          SRPI samples
  85.      X25           X.25 samples
  86.  
  87.    The following is a brief discussion of the documentation and sample
  88.    programs included in each of the subdirectories:
  89.  
  90.    ACDI:
  91.       The ACDI directory contains documentation and sample programs for the
  92.       ACDI API.  ACDI.DOC file contains the documentation and the
  93.       instructions for the ACDI sample programs.  The source code for the
  94.       samples is provided.
  95.  
  96.       Support for both 16-bit and 32-bit C programs is provided.
  97.  
  98.    CMINCL:
  99.       The CMINCL directory contains the Communications Manager/2 API data
  100.       structures for C, IBM MACRO Assembler/2, and COBOL, the Assembler
  101.       Interface Macros for SRPI, and the Communications Manager/2 interface
  102.       for CPI-C REXX.
  103.  
  104.       Support for both 16-bit and 32-bit C/C++ programming is provided
  105.       for the Communications Manager/2 APIs.
  106.  
  107.    CMKAPI:
  108.       The CMKAPI directory contains documentation and sample programs
  109.       that exit or query Communications Manager.  CMKAPI.DOC contains
  110.       the documentation and the instructions for these sample programs.
  111.       The sample programs are written in C and the source code is provided.
  112.  
  113.       Support for both 16-bit and 32-bit C programs is provided.
  114.  
  115.    CMLINK:
  116.       The CMLINK directory contains the Communications Manager/2 API import
  117.       libraries.
  118.  
  119.    CONFIG:
  120.       The CONFIG directory contains sample CMD files for backing up and
  121.       restoring CM/2 configuration files.
  122.  
  123.    HAPI:
  124.       The HAPI directory contains documentation and sample programs for
  125.       the EHLLAPI API.  HAPI.DOC file contains the documentation and
  126.       the instructions for the EHLLAPI sample programs and EHLLAPI
  127.       Program Sampler.  The source code is provided.
  128.  
  129.       Support for both 16-bit and 32-bit C programs is provided.
  130.  
  131.    LUA:
  132.       The LUA directory contains documentation and sample programs for the
  133.       LUA API.  LUA.DOC file contains the documentation and the instructions
  134.       for the LUA API sample programs.  The source code for the sample
  135.       programs is provided.
  136.  
  137.       Support for both 16-bit and 32-bit C programs is provided.
  138.  
  139.    REACTX25:
  140.       The REACTX25 directory contains documentation and a sample program for
  141.       the automatic reactivation of the X.25 adapter when either a link or
  142.       adapter failure occurs.  REACTX25.DOC contains the documentation and
  143.       the instructions for the REACTX25 sample program.  The sample program
  144.       is written in C and the source code is provided.
  145.  
  146.    ROPS:
  147.       The ROPS directory contains documentation and sample programs for the
  148.       Remote Operations Service interface.  The sample programs are written
  149.       in C and the source code is provided.
  150.  
  151.       Support for both 16-bit and 32-bit C programs is provided.
  152.  
  153.    SNA:
  154.      The following sample programs are provided in the SNA
  155.      subdirectory:
  156.  
  157.      APING
  158.        This is a CPIC-C program that exchanges data packets with a partner
  159.        computer and times how long the data transfer takes.  The sample is
  160.        written in C and the source code is provided.  APING.DOC contains
  161.        information which may be useful when configuring, compiling and
  162.        running the sample program.
  163.  
  164.        Support for both 16-bit and 32-bit C programs is provided.
  165.  
  166.      APPCMGMT
  167.        This is a Subsystem Management sample program. The sample program
  168.        issues verbs such as Deactivate Logical Link and Deactivate Session.
  169.        The sample is written in C and the source code is provided.
  170.        APPCMGMT.DOC contains information which may be useful when configuring,
  171.        compiling and running the sample program.
  172.  
  173.        Support for both 16-bit and 32-bit C programs is provided.
  174.  
  175.      APPCTELL
  176.        This is an APPC sample program that sends a VIOPopUp message to the
  177.        specified Partner LU.  The sample is written in C and the source code
  178.        is provided.  APPCTELL.DOC contains information which may be useful
  179.        when configuring, compiling and running the sample program.
  180.  
  181.        Support for both 16-bit and 32-bit C programs is provided.
  182.  
  183.      AREXEC
  184.        This is an APPC sample program that allows you to execute any single
  185.        command line on a remote workstation.  The sample is written in C and
  186.        the source code is provided.  AREXEC.DOC contains information which
  187.        may be useful when configuring, compiling and running the sample
  188.        program.
  189.  
  190.        Support for both 16-bit and 32-bit C programs is provided.
  191.  
  192.      ATELL
  193.        This is a CPI-C sample program that allows a workstation to send a
  194.        message to another workstation. The sample is written in C and the
  195.        source code is provided.  ATELL.DOC contains information which may be
  196.        useful when configuring, compiling and running the sample program.
  197.  
  198.        Support for both 16-bit and 32-bit C programs is provided.
  199.  
  200.      CPI-C File Transfer
  201.        This is a sample CPI-C file requestor and file server. The sample
  202.        programs demonstrate how to transmit a file from one OS/2 workstation
  203.        to another using CPI-C applications program interface calls.  The
  204.        sample programs are written in C and the source code is provided.
  205.        CPICFILE.DOC contains information which may be useful when configuring,
  206.        compiling and running the sample program.
  207.  
  208.        Support for both 16-bit and 32-bit C programs is provided.
  209.  
  210.      CPI-C COBOL samples
  211.        Four sample COBOL programs using CPI-C. CPICOBOL.DOC contains
  212.        information which may be useful when configuring, compiling and
  213.        running the sample program.  The source code is provided.
  214.  
  215.      CPIC REXX samples
  216.        Sample REXX programs that demonstrate how to set and extract CPI-C
  217.        side information using the REXX environment for CPI-C, CPICOMM.
  218.        CPICREXX.DOC contains information which may be useful when
  219.        configuring, compiling and running the sample program.
  220.  
  221.      DISPLAY
  222.        This sample program displays status and configuration information for
  223.        the active SNA configuration of the Communications Manager.  It
  224.        demonstrates the use of the APPC management verbs DISPLAY and
  225.        DISPLAY_APPN for retrieving this information.  The sample is written
  226.        in C and the source code is provided.  DISPLAY.DOC contains information
  227.        which may be useful when configuring, compiling and running the sample
  228.        program.
  229.  
  230.      CMGWSESS
  231.        This sample program requests and formats gateway information using
  232.        the DISPLAY and DISPLAY_APPN verbs. This sample is written in C and
  233.        the source code is provided.
  234.  
  235.        Support for both 16-bit and 32-bit C programs is provided.
  236.  
  237.      APPC File Transfer
  238.        These sample programs use the APPC native application programming
  239.        interface verbs to transmit a file from one OS/2 workstation to
  240.        another.  The samples are written in C and the source code is provided.
  241.        FILE.DOC contains information which may be useful when configuring,
  242.        compiling and running the sample program.
  243.  
  244.      SOC
  245.        This sample program provides an MS sphere of control (SOC)
  246.        application that allows interactive definition, display, and deletion
  247.        of SOC node entries.  It demonstrates the use of the several APPC
  248.        management services verbs. SOC.DOC contains information which may be
  249.        useful when configuring, compiling and running the sample program.
  250.  
  251.    SRPI:
  252.       The SRPI directory contains documentation and sample programs for
  253.       the SRPI API.  SRPI.DOC file contains the documentation and the
  254.       instructions for the SRPI sample programs.  The source code is
  255.       provided.
  256.  
  257.       Support for both 16-bit and 32-bit C programs is provided.
  258.  
  259.    X25:
  260.       The X25 directory contains documentation and sample programs for the
  261.       X.25 API.  X25.DOC file contains the documentation and the instructions
  262.       for the X.25 API sample programs.  The sample programs are written in
  263.       C and the source code is provided.
  264.  
  265.       Support for both 16-bit and 32-bit C programs is provided.
  266.  
  267.    /*******************************************************************/
  268.    /  COMPILING AND LINKING                                            /
  269.    /*******************************************************************/
  270.  
  271.    Building executable programs (.EXE files) from the source code supplied
  272.    in this directory requires the following:
  273.  
  274.    1.  Update the environment to use the Communications Manager/2 API
  275.        data structures and link libraries.
  276.  
  277.    2.  Set the environment and path for the compiler and linker.
  278.  
  279.        For 16-bit C samples an example of these steps would be:
  280.  
  281.        set lib=d:\cmlink;d:\msc\c600\lib;d:\toolkt13\lib;%LIB%
  282.        set include=d:\cmincl;d:\msc\c600\include;d:\toolkt13\c\include;%INCLUDE%
  283.        set path=d:\msc\c600\binb;d:\msc\c600\binp;d:\toolkt13\bin;%PATH%
  284.        set IPFC=d:\toolkt13\ipfc;
  285.  
  286.        For 32-bit C samples an example of these steps would be:
  287.  
  288.        set lib=d:\cmlink;d:\cset2\lib;d:\toolkt20\os2lib;%LIB%
  289.        set include=d:\cmincl;d:\cset2\include;d:\toolkt20\c\os2h;%INCLUDE%
  290.        set path=d:\cset2\bin;d:\toolkt20\os2bin;%PATH%
  291.        set dpath=d:\cset2\locale;d:\cset2\help;%DPATH%
  292.  
  293.        In addition, 32-bit C support requires that the LIBPATH be updated
  294.        with libpath=d:\compile\cset2\dll;d:\compile\toolkt20\dll;.
  295.  
  296.    3.  From the subdirectory containing the sample source code, use the
  297.        makefile (.MAK file) with the NMAKE.EXE utility. Both 16-bit and
  298.        32-bit makefiles are supplied, and are distinguished by the trailing
  299.        '16' or '32' in the filename of the makefile.
  300.  
  301.    4.  The C include files in \CMINCL contain 32-bit structures that are
  302.        conditionally included with the __32BIT__ identifier. __32BIT__ is
  303.        defined whenever the IBM C Set/2 compiler is being run, and the
  304.        application must not try to define this identifier as a compile
  305.        option.
  306.  
  307.        Many C samples files contain code that allow these programs to be
  308.        built with the 32-bit IBM C Set/2 compiler. These samples primarily
  309.        demonstrate techniques for calling Communications Manager/2 DLLs
  310.        from 32-bit applications. All of the Communications Manager/2 APIs
  311.        are enabled for 32-bit application support.
  312.  
  313.        The following guidelines apply when building 32-bit applications:
  314.  
  315.         o  Use the most current 32-bit IBM C Set/2 compiler.
  316.  
  317.         o  Review the C include file in \CMINCL for the specific API which
  318.            will be called.  The files in \CMINCL have been extensively
  319.            updated for Communications Manager/2.
  320.  
  321.         o  Declare data using typedefs defined in the API include files.
  322.  
  323.            Data buffers have been defined implicitly as 16-bit objects (with
  324.            the _Seg16 qualifier), but the application can use these buffers
  325.            as 32-bit objects.  For example, 32-bit memory management can be
  326.            used to allocate an API data buffer.
  327.  
  328.            The characteristics of an API buffer in the 16-bit environment
  329.            also apply to the 32-bit application.  For example, APPC buffers
  330.            may extend to a size of 64K and CPI-C buffers may extend to 32K.
  331.            API structures will not cross 64K segment boundaries due to the
  332.            use of #pragma seg16() statements in the include files.
  333.  
  334.            Be careful to identify members of structures that may require
  335.            explicit thunking in a 32-bit application. For example, an API
  336.            control block can contain a handle to a semaphore that is typed
  337.            as (unsigned long).  This is an address that must have been
  338.            explicitly declared as type (void PTR16) in the 32-bit
  339.            application.  In the application this address would be typecast
  340.            as (unsigned long) when assigned to the handle in the control
  341.            block.  For those cases where this object is returned by the API
  342.            the handle can be used directly (as in Dos16SemWait) without
  343.            conversion.
  344.  
  345.         o  Match the parameter lists in the API call with the prototype
  346.            of the entry point.
  347.  
  348.            For example, the APPC parameter (&vcb) is prototyped as
  349.            (PVOID _Seg16).  In this case, a 32-bit vcb passed by reference
  350.            will be converted to a 16-bit address.  No explicit thunking is
  351.            required by the application code.
  352.  
  353.            If the parameter of a function is prototyped without thunking,
  354.            do not attempt to use a 16-bit address for this parameter.
  355.  
  356.         o  Communications Manager/2 APIs use 16-bit semaphores.  These can
  357.            be used by a 32-bit application that explicitly prototypes the
  358.            following calls:
  359.  
  360.              typedef VOID * _Seg16           HSEM16;
  361.              typedef HSEM16 *                PHSEM16;
  362.              typedef unsigned char * _Seg16  PSZ16;
  363.  
  364.              USHORT _Far16 _Pascal Dos16CreateSem(USHORT,PHSEM16,PSZ16);
  365.              USHORT _Far16 _Pascal Dos16OpenSem(PHSEM16,PSZ16);
  366.              USHORT _Far16 _Pascal Dos16CloseSem(HSEM16);
  367.              USHORT _Far16 _Pascal Dos16SemClear(HSEM16);
  368.              USHORT _Far16 _Pascal Dos16SemSet(HSEM16);
  369.              USHORT _Far16 _Pascal Dos16SemWait(HSEM16,long);
  370.  
  371.            To obtain linkage to Dos16... calls, include OS2386.LIB in the
  372.            list of link libraries.
  373.  
  374.         o  Support for 32-bit C++ application development is also included in
  375.            the files in \CMINCL.  While this is primarily contained in the
  376.            __cplusplus identifier, certain programming conventions are
  377.            necessary to provide this compatibility.  The use of #pragma pack(1)
  378.            rather than _Packed, and the use of _Far16 _Pascal rather than
  379.            #pragma linkage() are requirements of the 32-bit IBM C++ compiler.
  380.  
  381.  
  382.