                       CPI-C Programming in C

     Welcome to the README file accompanying the diskette for the
     McGraw-Hill Book:

     "CPI-C Programming in C:  An Application Developer's Guide to APPC"
     by John Q. Walker II and Peter J. Schwaller, ISBN 0-07-911733-3,
     1994.

DISKETTE VERSION 1.03, OCTOBER 15, 1994
     Copyright c John Q. Walker II and Peter J. Schwaller 1994.

     This diskette contains files with material having additional
     copyright designations.  These copyrights are noted in the
     respective files.

WHAT'S IN THIS FILE
-    Copy This Diskette
-    Steps to Build the Sample Programs
-    Steps to Configure the Sample Programs
-    What's in Each Directory
-    Compiling:  Common Problems
-    Linking:  Common Problems
-    For the Latest Version of the Book and Diskette
-    Changes in Each Version

COPY THIS DISKETTE
       (for DOS, Windows, and OS/2)
     Use XCOPY to copy this entire diskette to the hard drive of your
     computer.  For example, to copy it from the A drive to the
     "cpicc1" directory on your C: drive, enter the following
     command:

        XCOPY a:\*.* c:\cpicc1\  /S /E /V

STEPS TO BUILD THE SAMPLE PROGRAMS
       (for DOS, Windows, and OS/2)
       1. Ensure that your C compiler is set up properly.  In most cases,
          your PATH, LIB, and INCLUDE environment variables must specify
          the directories that contain the files your compiler needs.
          Consult your compiler documentation for more information.
       2. Add the \INCLUDE directory from this disk to the list of
          directories in your INCLUDE environment variable.  This allows
          your C compiler to find the CPIC.H and WINCPIC.H header files.
       3. Set up the environment variables required by our .MAK files. To
          do this, run the .CMD or .BAT file appropriate to your compiler:

          - BCOS2.CMD - Borland C++ for OS/2 (32-bit OS/2)
          - ICSET2.CMD  - IBM C Set/2 (32-bit OS/2)
          - ICSETPP.CMD - IBM C Set++ (32-bit OS/2)
          - MSC6.CMD  - Microsoft C 6.00A (16-bit or 32-bit OS/2, small model)
          - MSC6.BAT  - Microsoft C 6.00A (DOS, small model)
          - MSC7S.BAT  - Microsoft C 7.00 (DOS, small model)
          - MSC7W.BAT - Microsoft C 7.00 (Windows QuickWin, large model)

          The DOS and Windows makefiles are designed for use with the
          CPI- C libraries for IBM's Networking Services/DOS, version
          1.1 or later.  The macro CM_DOS is defined at compile time to
          activate the right sec tions of CPIC.H.

          - The DOS makefiles are designed to be linked with library
            file CPICNSDR.LIB, which is the real-mode CPI-C library for
            Networking Services/DOS.

          - The Windows makefiles are designed to be linked with library
            file CPICNSDW.LIB, which is the Windows 3.x CPI-C library for
            Networking Services/DOS.

          If you are compiling in DOS and run out of environment space,
          increase the /E: parameter on the DOS SHELL command.  For
          example, to increase your environment space to 1000 bytes,
          modify your SHELL variable in CONFIG.SYS as shown:

              SHELL=c:\dos\command.com /E:2000

          The OS/2 makefiles are designed for use with IBM's OS/2
          Communications Manager/2, version 1.0 or later.  The macro
          CM_OS2 is defined at compile time to activate the right
          sections of CPIC.H.  The OS/2 makefiles are designed to be
          linked with library file CPIC.LIB, the OS/2 CPI-C library for
          any version of Communications Manager/2.

       4. Change directory to one of the source code sample
          directories from this diskette.  See the "What's in Each
          Directory" section below.

       5. Run MAKE or NMAKE (depending upon your compiler) against
          the makefile in the subdirectory.  For example:

          make -f classic5.mak or nmake -f classic5.mak

          The makefile name corresponds to the directory name; for
          example, CLASSIC5.MAK is in the CLASSIC5 directory.  To make
          all the source code on the diskette, run the NMAKEALL.BAT
          batch file for DOS or Windows, the NMAKEALL.CMD file for OS/2,
          or MAKEALL.BAT or .CMD for Borland.

STEPS TO CONFIGURE THE SAMPLE PROGRAMS
       (for DOS, Windows, and OS/2)
          You'll need a local LU defined on each computer where either
          the client or server program is running.  You'll also need to
          be sure that modes named #INTER and #BATCH are defined.  We
          assume your computers already have these definitions is place.

       -  For each CPI-C client program you run, you need an entry in
          your CPI-C side information.
       -  For each CPI-C server program you run, you need a TP
          definition.

          We've put all the side information entries that we used in the
          book into a single file.

       -  For IBM's OS/2 Communications Manager/2, the file of side
          information entries is named SIDEINFO.NDF
       -  For IBM's Networking Services/DOS, the file of side
          information entries is named SIDEINFO.NSD

     We've created our symbolic destination names by putting an "S"
     at the end of the client program's name; for example, HELLO1S is
     used by program HELLO1.EXE.  We've created the TP name by
     putting a "D" at the end of the client program's name; for
     example, HELLO1D is used to start program HELLO1D.EXE.  We've
     used #INTER or #BATCH as the mode names throughout all the
     examples.  We've put the string "REPLACE_THIS_STRING" in the
     partner LU name field.  You'll need to replace this with the
     partner LU name of the computer where the server program is
     located.

     Similarly, we've put all the TP definitions into a single file.
       -  For IBM's OS/2 Communications Manager/2, the file of TP
          definitions is named DEFINETP.NDF
       -  For IBM's Networking Services/DOS, the file of TP definitions
          is named DEFINETP.NSD

     The TP names match those configured in the corresponding
     client's side information entries.  We've created the filespec
     for the server program by assuming you've used XCOPY to copy the
     entire diskette into a directory named "cpicc1" on the c: drive.
     We've configured all server programs as "attach-manager-started"
     for OS/2, and as "operator-started" for DOS.

     These four files, SIDEINFO.NDF, SIDEINFO.NSD, DEFINETP.NDF, and
     DEFINETP.NSD, are found in the \CONFIG directory on the
     diskette.  These files must be appended to your existing
     configuration file, since these aren't the only definitions you
     need in order to run these programs.  You need to assure that a
     local LU is defined on each computer, and that a link is defined
     to the partner computer or to an adjacent APPN network node.

       -  When using OS/2 Communications Manager/2, append
          SIDEINFO.NDF to the current .NDF file you are using on the
          client computer, and append DEFINETP.NDF to the current .NDF
          file you are using on the server computer.  If you plan to run
          both client and server programs on the same OS/2 computer,
          append both files to your existing .NDF file.

       -  When using Networking Services/DOS, append file SIDEINFO.NSD
          to your existing SIDEINFO.NSD file (which is located in the
          directory where you start Networking Services/DOS).  Append
          file DEFINETP.NSD to your existing DEFINETP.NSD file (also
          located in your NS/DOS directory).

WHAT'S IN EACH DIRECTORY

\APING
       Source code and compiled executables for the APING program.
       Use this program to get APPC set up the first time on your
       computer(s).

\CONFIG
       Contains files with side information entries and TP defini
       tions, for OS/2 Communications Manager/2 and Networking
       Services/DOS.

\CPICINFO
       Three text files, with the following information:
          - CPICPLAT.TXT -- platforms and operating systems which
            support CPI-C
          - SECURITY.TXT -- IBM platforms and their support for
            conversation security
          - CDROM.TXT -- details on the CD-ROM you need to get:  "The
            Best of APPC, APPN, and CPI-C"

\INCLUDE
       The latest CPIC.H and WINCPIC.H header files.

\OS2INF
       Contains two .INF files, which are hypertext help files for
       OS/2.  They can be viewed using the OS/2 VIEW command.  The
       files are:
       -  CPICRC.INF - a practical guide to the CPI-C return codes (same
          as Appendix A of "CPI-C Programming in C")
       -  SENSDATA.INF - a guide to APPC/APPN sense data values

The following directories contain source code shown in the book.

\HELLO
       Source code of the HELLO sample programs from Chapters 3, 5,
       6, 7, and 8 of the book.

\BUFFER
       Source code of the Flush programs from Chapter 9 of the book.

\LOOP
       Source code of the looping programs from Chapter 10 of the
       book.

\CLASSIC5
       Source code of the five classic transactions from Chapter 18
       of the book.

\SERROR
       Source code of the looping Send_Error programs from Chapter
       20 of the book.

\TRACE
       Source code of the trace procedures from Chapter 21 of the
       book.

\SETUP
       Source code of the robust, reusable setup routine from
       Chapter 22 of the book.

\DATACONV
       Source code of the data conversion procedures from Chapter 24
       of the book.

\SECURE
       Source code of the security procedures from Chapter 25 of the
       book.

\SERVER
       Source code of the server programs from Chapter 27 of the
       book.

COMPILING:  SOME COMMON PROBLEMS
       -  file CPIC.H is not found
          Add the directory containing CPIC.H to the INCLUDE
          environment variable used by your compiler.

       -  macro CM_CID_SIZE is not defined
          The compiler is finding an older version of CPIC.H, before the
          CPIC.H file provided on this diskette.  Modify your INCLUDE
          environment variable so the directory that contains our CPIC.H
          is first.

       -  When issuing NMAKE or MAKE:
            "xxxx.c: program not found" (in DOS)
               "xxxx.c cannot be run in an OS/2 session" (in OS/2)
          You must run the .BAT or .CMD appropriate for your compiler to
          set up the proper environment variables.

       -  When making SECURE.MAK with WINCPIC.H, failure to compile
          SECURE.C, with lots of error and warning messages.
          The WinCPIC spec is still broken:  it specifies that
          conversation user IDs and passwords are 8 bytes in length,
          rather than the CPI-C 1.2 standard of 10 bytes.  Please feel
          free to provide your feedback to Microsoft on this
          incompatibility.

       -  When making SERVER.MAK in DOS or Windows, "server.c: program
          not found"
          The programs in SERVER.MAK require multi-threaded support.
          You cannot build these programs for DOS or Windows.

       -  When making any makefile (except SERVER.MAK in DOS)
          "xxxxxxx.c: program not found"
          You need to set up the environment variables CPICCC, CPICLINK,
          and so on.  Use one of the provided setup files, such as
          MSC6.BAT, MSC7W.BAT, ICSETPP.CMD, or BCOS2.CMD, or create your
          own setup file for your compiler and linker.  Use one of these
          provided setup batch files as a model for creating your own
          setup.

       -  warning message:  "statement as no effect" when compiling for
          production environment, not debug
          We've put assert() statements throughout our code.  The
          assert() statements results in a macro, which generates useful
          code in debug mode, but generates an empty line when NDEBUG is
          defined.  Some compilers generate warnings when they encounter
          this empty line.

       -  warning message:  "else-statement is empty" or "if-statement
          is empty"
          In many places in our sample code we've placed comments inside
          an "if" or "else" block, without any executable code.  These
          warnings are generated by several compilers.

       -  errors naming INTENTIONAL_SYNTAX_ERROR and
          define_a_system_in_cpic_h
          You are compiling using header file CPIC.H, but you haven't
          activated the variables or typedefs needed for the specific
          operating system you are using.  For example, define macro
          "CM_OS2" to activate the variables needed by the OS/2
          Communications Manager.  See the top of CPIC.H for a list of
          available macro definitions.  Use these as a model if you are
          porting CPIC.H for use on a system not in this list.

LINKING:  SOME COMMON PROBLEMS
       -  When linking for DOS with MSC 6.00A, many occurrences of
          error L2029:  `DOSxxxx' : unresolved external
          Your SLIBCE.LIB file is an OS/2 library file.  Either change
          the MSC6.BAT file to specify SLIBCER instead of SLIBCE, or
          assure that SLIBCE.LIB is a DOS library file (for example, by
          renaming SLIBCER to SLIBCE).

FOR THE LATEST INFORMATION
     Modern programming is all about iterative refinement.  We've
     given you the highest quality book and diskette we could today.
     Happily, we know that you'll find things we missed or think of
     better ways to illustrate some of these concepts.  We also know
     you'll think of code improvements, and_believe it or not_you may
     even find bugs.  Finally, CPI-C itself is continuing to evolve,
     and we plan future editions of this book.

     We want to hear from you.  Much of our book is the result of our
     ongoing collaboration with programmers around the world.  We'd like
     to collaborate with you on future refinements.  Here are two ways
     to reach us via electronic mail:

       John Q. Walker II
       -    CompuServe:  72440,1544
              Internet:  72440.1544@compuserve.com

       Peter J. Schwaller
       -    CompuServe:  73602,3201
              Internet:  73602.3201@compuserve.com

     If you can't reach us via e-mail, you'll always be able to reach
     us by traditional mail, via our publisher.

        CPI-C Programming in C
        McGraw-Hill Books
        Jay Ranade Series
        P.O. Box 338
        Grand Central Station, New York  10163-0338  U.S.A.

     We'll keep the latest version of this diskette on CompuServe and on
     the Internet.

     CompuServe:  Log on to CompuServe, and enter "GO APPC" at the !
     prompt.  This will take you to the APPC Forum.  Download the file
     named "CPICC1.ZIP" in binary from the Sample Programs library.

     Internet:  For the power user, here's the URL:

      ftp://networking.cary.ibm.com/pub/appc_appn/sample_code/cpicc1.zip

     Here are some more helpful directions:

        1) FTP to networking.cary.ibm.com
        2) Login as "anonymous".  Enter your userid as the password
        3) Change directory (CD) to /pub/appc_appn/sample_code
        4) Set the transfer type to binary (BIN)
        5) Transfer "cpicc1.zip" (get cpicc1.zip)

     No matter how you get the CPICC1.ZIP file, you'll need to run
     the following command:

        PKUNZIP -n -o -d CPICC1.ZIP

     to unpack the files.

     We've saved many of the source code files on this diskette with
     tabs (that is, whenever there's a run of 8 blanks, it is
     replaced in the source file by a tab character).  We did this to
     save space.  This is compatible with all the compilers, text
     editors, and command-line processors we know_let us know if you
     encounter any problems.

Get the book at your local bookstore, or direct from McGraw-Hill:
     McGraw-Hill, Inc.
     attention:  Michele Sanders
     13311 Monterey Avenue
     Blue Ridge Summit, PA  17294

     call 800-822-8158 for credit card orders
          be sure to have the ISBN number handy:  0-07-911733-3

     call Lida Watson at 800-842-3075 for quantity discount information

Book Reviews
     The press has been very favorable on our book.  Be sure to see the
     following book review:

     - "IBM Internet Journal," September 1994, page 54 (file REVIEW1.DOC
       on this diskette)

VERSION 1.03 CHANGES TO THIS DISKETTE
     All files updated for version 1.03 of this diskette are dated:
     October 15, 1994, 01:03:00

     - updated DOCPIC.C and DOCPIC.H, adding a new "do_request_to_send"
       procedure (not shown in the book).  If you'd like to issue
       Request_To_Send(), here's the procedure to use.  Note that the
       Send_Data() and Receive() procedures in DOCPIC.C ignore the
       incoming request_to_send_received signal, so they may need to be
       modified.

     - added "(void)0" in all the places where no code was being
       executed.  This saves a warning in the IBM C Set++ compiler.
       Files:  TRACE.H, DOCPIC.C.

     - changed the IBMC.CMD file to ICSET2.CMD, to set up the compiler
       and linker for IBM C Set/2.  Added file ICSETPP.CMD, the set up
       for the later IBM C Set++ compiler.

     - updated SERRLOOP.C to put the return statement at the bottom,
       saving a warning.

     - added DATACONV.MAK, to build the code in its directory.

VERSION 1.02 CHANGES TO THIS DISKETTE
     All files updated for version 1.02 of this diskette are dated:
     September 15, 1994, 01:02:00

     - got the newest version of header file WINCPIC.H from Microsoft
       Windows NT SNA Server, version 2.1, and updated it for
       compatibility, replacing the earlier version on this diskette.
       Use this updated version instead of the one shipped with SNA
       Server 2.1.  This updated file appears in the \INCLUDE
       subdirectory.

       There is still an incompatibility between WinCPIC and the CPI-C
       1.2 standard on the length of conversation security user IDs and
       passwords.  CPI-C 1.2 says they're 10 bytes long; WinCPIC says
       only 8 bytes.  For long-term portability, use the extension calls
       (starting with "xc") to specify 8-bytes user IDs or passwords.

     - updated files HELLO1.C, HELLO2.C, and CREDIT.C to cast the
       argument for strlen() as (char *), avoiding a warning on some
       compilers.

     - updated the opening comments of the .BAT and .CMD files, to
       clearly describe the compilers and CPI-C product libraries they
       service.

VERSION 1.01 CHANGES TO THIS DISKETTE
     All files updated for version 1.01 of this diskette are dated:
     September 1, 1994, 01:01:00

     - updated the headers of DEFINETP.NDF and SIDEINFO.NDF to say IBM
       OS/2 Communications Manager/2, not Networking Services/DOS.

     - updated procedure handle_receive_error() in DOCPIC.C to examine
       the return code before handling status_received.

     - updated memcpy() call in DOCPIC.C to avoid a warning with MSC 7.

     - updated handle_return_code() in DOCPIC.C to print the return code
       name and number.

     - updated .C files to consistently put the constant on the
       right-hand side of compare statements.

     - added the \LOOP subdirectory and code (omitted from version 1.00)

     - cosmetically cleaned up the code in SETUP.C.

     - updated APING and its source files to version 2.44

VERSION 1.00
     All files in version 1.00 of this diskette are dated:
     May 1, 1994, 01:00:00

     - This is the version of the diskette that accompanies the first
       printing of the book.

