Preparing for Application Development

Software Requirements

Software is really where the interests of most of us lie; before you can develop TCP/IP applications you may need to invest a small fortune to acquire the correct tools. This is not meant to scare you away from software development, but these tools can get expensive, especially if you opt for the so-called "professional" packages, which usually include advanced debugging and analysis tools.

Of course, you need to have OS/2 installed on your system. All of the source code in this book was developed on systems with OS/2 Warp 3.0 installed. Warp ships with a Bonus Pack disk containing the Internet Access Kit (IAK). This is usually enough to run Internet programs; however, in order to develop these TCP/IP applications, you will need additional software.

IBM's current product push is directed toward a product called Warp Connect. This version of the operating system will likely replace the current, more limited Warp package and will be the only offering available for the upcoming Power PC system. Warp Connect offers an integrated TCP/IP interface consisting of two layers of software. The Multi-Protocol Transfer Services (MPTS) contains all the low-level services to interface to a network interface adapter or to a serial modem using a SLIP or PPP layer. The second half of the TCP/IP interface is essentially identical to what the IAK provides, including some basic client applications like WebExplorer.

If you are building new network applications, you would be wise to recommend Warp Connect for your end users since it simplifies the TCP/IP installation and use; however, as a developer you will still need to purchase the IBM TCP/IP Programmer's Toolkit because the libraries and C header files are not included with Warp Connect.

You will also need a C/C++ compiler. The GNU C/C++ compiler for OS/2 is free; however, it was not used to develop any of the code in this book, so you may experience some unexpected problems. The IBM CSet++ compiler for OS/2 is adequate, as is the C++ for OS/2 offering from Borland International, and you may also want to take a look at the Watcom C++ compiler if you are concerned with portability or executable size.

You will also need a TCP/IP base kit and a Programmer's Toolkit. All the examples in this book were created using the IBM TCP/IP base pack and Programmer's Toolkit. FTP Software also offers a complete TCP/IP development system, so price may be the deciding factor when selecting your development environment.

You can save hundreds of dollars by ordering IBM's Developer Connection for OS/2 CDs. This is not intended to offer a free plug for IBM; the Developer Connection CDs include practically everything you will need to build the applications in this book, as well as lots of additional reference information such as the IBM OS/2 Redbooks, and a number of abbreviated books related to OS/2 programming. The Developer Connection CDs represent the best software value you will find for OS/2 development tools.

The following is a list of software required to create the libraries and applications in this book. These are personal recommendations and do not necessarily represent the best value or most functional products.

Visual Development Tools

IBM has recently announced VisualAge C++ for OS/2, which is a new product to replace CSet++. VisualAge C++ is a development package that contains the compiler and debugger tools with which you may already be familiar; however, it also includes an innovative new tool called VisualBuilder, which is a highly graphical development system. VisualBuilder can be used to create applications graphically by dropping "parts" onto a work canvas and connecting them together. Application construction with VisualBuilder actually involves very little programming at all, at least in the traditional sense.

This sounds like the ideal environment, but there is one very large drawback known as a run-time library. The run-time library (which is actually several dynamic link libraries or DLLs) used by VisualBuilder, is the same one that any program built with the IBM ICLUI classes uses, and must accompany any application you develop with VisualBuilder. Including an additional set of DLLs with your application is not a terrible set-back, except that the combined size of the ICLUI DLLs typically hovers at around 1 Mbyte. You can pare this down by remanufacturing the library, but this solution is not an easy one. Alternately, you can statically link to the ICLUI library, but this does not solve the size problem either, since the equivalent ICLUI code then gets buried in your executable, bloating it substantially.

An aphorism that I have sworn by for many years is: You can develop applications fast or you can develop them well. VisualAge and most other graphical development tools live up to this realization. When used as prototyping tools, applications like VisualBuilder work very well. However, this type of tool typically lacks the luster required for production code and subsequent maintenance support. You cannot comment a graphical image, so revisiting an application as part of the maintenance phase of a project can become a serious problem.

Although you could likely develop all of the applications in this book with VisualAge C++ for OS/2, we will deliberately avoid it. This book is an exercise in understanding how to build classes for a user interface and networking, and though I have not specifically touched on the subject, the applications I will build throughout this book are, for the most part, portable to other operating systems. You will of course need to rewrite or modify the PMCLASS, NVCLASS, and NETCLASS classes, but everything else in the applications should recompile on other platforms with minimal modifications, provided you take care to minimize or eliminate calls to the OS/2 specific API.

Please do not infer that I dislike VisualBuilder specifically or visual tools in general. Indeed, VisualBuilder is an excellent tool for prototyping applications quickly, but realize that you cannot get something for nothing - the convenience of the VisualBuilder and ICLUI class library comes with an associated cost.

Additional Tools

There are a number of other tools that you will find invaluable while developing for OS/2. These are summarized in the table below:

Compiler Precautions

If you have tried to compile any of the IBM TCP/IP sample applications that ship with the TCP/IP Programmer's Toolkit using the Borland compiler, you already know that you run into some annoying inconsistencies between the compiler and the libraries. The TCP/IP libraries and headers provided by IBM are decidedly slanted toward their own CSet++ compiler, and will generate compile errors using most other compilers.

Although you can use the Borland C++ for OS/2 package to develop TCP/IP applications for OS/2, you will need to make changes to some of Borland's header files. These changes are required to use the IBM TCP/IP Programmer's Toolkit, since it references some keywords which are specific to the CSet++ compiler. These patches may also work for other compilers, such as Watcom C++ or the GNU compiler.

You will need to insert a few additional defines into one of the headers files. Where you do this is not important, as long as you ensure the header file, where the changes are made, is loaded before any of the TCP/IP headers. For the Borland compiler the logical place to add these definitions is the OS2DEF.H header.

Using a text editor (the Borland IDE will do nicely), edit the OS2DEF.H file located in the \INCLUDE subdirectory of the Borland C++ installation. You will see a section of code as follows:

#if    defined(__BORLANDC__)
  #define APIENTRY        __syscall
  #define EXPENTRY        __syscall
  #define APIENTRY16      __far16 __pascal
  #define PASCAL16        __far16 __pascal
  #define CDECL16         __far16 __cdecl
  #define FAR16PTR        __far16 *
#else

Listing 1-1 Part of original Borland OS2DEF.H

In this section, before the #else, add the following:

// Changes to use IBM TCP/IP
#define   _Optlink   __stdcall
#define   _Packed
#define   _System    __syscall
#define   _Export    __export

Listing 1-2 Additions to Borland OS2DEF.H

The IBM CSet++ compiler uses these keywords to modify the calling sequence used when compiling source functions. Generally, Borland offers similar support but has renamed the items for compatibility with their compiler products on other platforms, such as Windowsand Windows NT.

The second file that needs to be modified is IO.H in the Borland \INCLUDE directory. This file contains an incomplete prototype for the ioctl() function. I was unable to find any reference to ioctl() in the the Borland documentation and libraries and I am left wondering why this code is here in the first place. At any rate, the ioctl() function is correctly defined in the TCP/IP header files, so the erroneous Borland definition can be commented out. In IO.H, find the code shown in Listing 1-3, and either remove it or comment it out.

#ifdef __IN_IOCTL
int  _RTLENTRY           ioctl   ();
#else
int  _RTLENTRY  _EXPFUNC ioctl   (int __handle, int __func, ...);
    /* optional 3rd and 4th args are: void _FAR * __argdx, int argcx */
#endif

Once these lines have been added to OS2DEF.H and removed from IO.H, you should be ready to build any of the TCP/IP applications in this book using the Borland compiler.

Using MAKE and NMAKE

The IBM CSet++ ships with the NMAKE utility, which can perform an incremental build for any given target file. Borland provides a similar utility called MAKE.

Almost all the executable examples and DLLs developed in this book are compiled from multiple source code files. Since you probably don't have the time or desire to recompile every module each time you make a change, you can use MAKE to compile from a script that recompiles only those files that are dependent on any changes you make to a given source file, greatly improving compile time.

The companion disk includes only NMAKE scripts for CSet++. The Borland integrated development environment supports project files that can be easily converted to MAKE equivalents using the PRJ2MAK utility provided in the Borland installation. For this reason no MAKE files for the Borland environment are provided on the companion disk.

The following listing illustrates the basic MAKE file structure that I will use as a quick review of the NMAKE conditional build process.

# Sample MAKE file

# Compiler and Linker parameters
cflags = /C /Gm+ /Se /Ss /Ms /Re /Q+ /Gs+ /Kb /Ko+
lflags= /NOE /NOD /ALIGN:16 /M /PM:pm /SE:2048 /noi

# Compile Rules
.cpp.obj:
   icc $(cflags) $*.cpp

.rc.res
   rc -r $*.rc

# Build rule for entire project
ALL : base.exe base.mak

# Build rule for base.exe
base.exe : base.obj base.res
   link386 $(lflags) base.obj, base.exe, base,DDE4MBS+TCP32DLL+SO32DLL,
base.def;
   rc base.res base.exe

# Build rules for source files
base.res : base.rc
base.obj : base.cpp base.hpp

Listing 1-4 Sample MAKE file (BASE.MAK)

In this example, the MAKE file BASE.MAK first sets up the default compile and link parameters in cflags and lflags, then creates rules which will be used to convert C++ source and resource files to object code. The remainder of the MAKE file contains dependencies for the various output targets. For instance, BASE.OBJ will be created if either BASE.CPP or BASE.HPP has changed. This will result in BASE.EXE being relinked in order to add the new code from BASE.OBJ.

It sounds a bit confusing, and MAKE can initially create almost as many problems as it solves, but once you build a few MAKE files, you will become accustomed to their requirements and you should eventually notice some development benefits. Don't shy away from using MAKE files - they really are nothing more than lists of dependency rules.

MAKE is a tool with roots planted firmly in the UNIX world. Manufacturers of PC compilers mistakenly believe that MAKE is straightforward, so they have tended to neglect the creation of adequate documentation for it. The best place to find information about MAKE is in a UNIX manual set. If you are lucky enough to have access to UNIX programmer's documentation, you can find very detailed MAKE information there.

The BASE.MAK file makes reference to some files which you may not immediately appreciate. The .DEF, .RC, and .RES files are unique to OS/2 PM (and Windows) so if you have never programmed for OS/2 they will appear alien. Almost all the applications in Part III will use these files; we'll discuss them in greater detail at that time.

Dynamic Link Libraries

Chances are good that if you have done any serious programming in the past, you are already familiar the concept of object libraries. Libraries are used whenever you have code that you use frequently and choose not to recompile every time you build your application code. Libraries offer the advantage of convenience, but also the distinct disadvantage of bloating your application code. Depending on how the library is constructed, the linker may actually link code from the library that is not used by the application, thus causing unnecessary code bloat. There is a better way, however, and it is known as a dynamic link library.

Dynamic link libraries do not really differ from static object libraries very much. Like static libraries, they can contain all of the common code for applications; however, there are several distinct differences. DLL code is not linked directly into an application. The linker simply links in a set of pointers to DLL functions. The results are smaller on-disk applications.

When an application linked to a DLL is loaded, the operating system verifies that the DLL is loaded into memory for the program to use. If OS/2 does not find the DLL in memory, it loads the DLL into memory automatically. Other than code size, there doesn't appear to be any other significant benefits realized through DLL use. So where are the advantages of dynamic link libraries?

Well, since the operating system controls the loading of the DLL code, it can detect when a copy of the DLL is already in memory. If a second copy of the application is executed, or a second application is developed to use the same DLL, the operating system ensures that only a single copy of the DLL is in memory to serve both programs. This means that, no matter how many programs are executing, there will only ever be one copy of the DLL loaded by the operating system, maximizing the efficiency of available system memory.

DLLs offer a second significant advantage for software maintenance. Because a DLL is basically a separate program, problems in the field can often be corrected without having to recompile the application. As long as the function interfaces in a DLL remain unchanged, they can be rebuilt to add new or corrected code without needing to recompile any of the applications that use the library.

If you are still not convinced of the advantages of DLLs, remember that Presentation Manager is essentially a collection of DLLs containing hundreds of kilobytes of code for the graphics engine, window manager, communications, etc. Every PM program will use some portion of this code, so if your basic "Hello World" program did not have the support of the system DLLs it could be as large as 100K or more!

All classes developed in this book will be placed in three DLLs, as follows:

NVCLASS.DLL	This library contains all classes for non-visual components. This includes classes for threading, semaphores, etc.
PMCLASS.DLL	This library contains all classes associated with the components of an application. Windows, buttons, toolbars, and dialogs are all part of this library.
NETCLASS.DLL	The NETCLASS.DLL implements all network-specific code. This contains a basic network class, as well as more specific classes for communicating using the News, FTP, and Gopher protocols. You will likely want to extend this class library to accommodate new network objects for other protocols you may implement.

These DLLs will be developed in the next part of this book, and will be used by all of the applications that we will create in Part III.

Project Directory Structure

The companion disk uses a particular directory structure to separate and organize the source code. Either use this project structure or develop your own architecture, but do take some appropriate action to keep your documentation and source code in order. Many projects have gone awry due to poor organization of source code and electronic documentation. The following diagram illustrates the directory structure used on the companion disk.

Figure 1-1 Project directory structure

In the structure shown in Figure 1-1 you should rename \APPLICATION to something that is appropriate for your own needs. The \SOURCE directory contains all of the source code related to your application, excluding the source for any help file you may be planning. Depending on the formality required for your project, you may have a number of documents you can store in the \DOCS directory. At the very least you will have some sort of bug list and/or wish list file that you can store in this subdirectory.

Where to Find Additional Tools and Information

There are a number of sites on the Internet where you can locate additional assistance and information. The first place to find an answer to just about any question is the Usenet news service. Newsgroups represent the largest bulletin board on the planet; here you will find several groups and thousands of people waiting to answer your questions (or to have questions answered). I have certainly quizzed many participants in the OS/2 newsgroups to find information for this book, and you would be wise to do the same when you begin writing your own applications. I have summarized some of the Usenet newsgroups catering to OS/2 below, but don't forget that you may also find answers in several of the 13,000 or more common newsgroups - many questions are independent of the operating system, so you may want to ask in groups outside the OS/2 domain.

comp.os.os2.announce	A moderated group covering news of OS/2 events, new books or products, and availability of new OS/2 technical information. A good place to find out about new OS/2 paraphernalia.
comp.os.os2.advocacy	An unmoderated group where you can find out about OS/2's strengths and weaknesses as OS/2 advocates meet advocates of other operating systems head on. This group can be humorous reading at times.
comp.os.os2.apps	If you have questions regarding any current OS/2 applications, this group is usually the place to go.
comp.os.os2.misc	This group deals with miscellaneous OS/2 information.
comp.os.os2.beta	This group contains a discussion of beta releases of OS/2 and other products.
comp.os.os2.bugs	If you find what you think is an OS/2 bug, you can post a request for assistance in this group. Many of OS/2's developers and IBM technical people frequent this group, so it's a good place to get help straight from the source.
comp.os.os2.multimedia	This group discusses the multimedia capabilities of OS/2. This includes setup and use, as well as some programming issues.
comp.os.os2.networking.misc	This group provides information about miscellaneous networking issues, including discussions of LanServer and NetWare, as well as setup for Ethernet cards, etc.
comp.os.os2.networking.mail-news	A relatively recent newsgroup specifically designed to support questions and information related to news and mail programs.
comp.os.os2.networking.tcp-ip	This group focuses on TCP/IP networking; you will want to spend some time here in order to familiarize yourself with the many protocols involved in successful networking. Contributors are generally helpful, and should be able to resolve any problems you may have with TCP/IP services or applications.
comp.os.os2.programmer.misc	This group focuses on miscellaneous programming issues related to OS/2. This is the group where you will ask most of your programming questions.
comp.os.os2.programmer.porting	This groups discusses issues related to porting programs from other platforms into OS/2.
comp.os.os2.programmer.oop	If you are interested in object-oriented programming, then start reading this group. The activity in this group is often minimal, but it does offer a great deal of insight into tools and techniques of OOP as they relate to OS/2.
comp.os.os2.programmer.tools	This group discusses the many OS/2 program development tools available.
comp.os.os2.setup	If you are having any problems related to setting up your OS/2 system, send your questions to this group.
comp.os.os2.games	This is becoming a very popular group as the use of OS/2 for game-playing and game development increases.

There are also a number of useful FTP and Gopher sites available on the Internet. Some sites are dedicated to OS/2, while others are good places to reference TCP/IP-related material. I have summarized a few of them below.

ftp://ftp.cdrom.com/pub/os2	This server is one of two main watering holes for those who thirst for OS/2 software. You will find many megabytes of OS/2 software, ranging from mainstream compilers and applications to obscure graphing applications, etc.
ftp://hobbes.nmsu.edu/pub/os2	This is a mirror of ftp.cdrom.com, useful because the previous site is often quite busy.
ftp://software.watson.ibm.com/pub/os2	This site is IBM's main point for software patches and Employee Written Software. This includes not only OS/2 patches, but also updates for IBM's networking products and software development tools.
ftp://ftp01.ny.us.ibm.net	Another IBM server, dealing specifically with Warp and Internet Access Kit developments and patches. You will also find demos for some of the latest games for OS/2 here.
ftp://ftp.uu.net	This is one of many sites containing copies of the RFCsRFC for TCP/IP. You will also find many other useful programs on this server, but you will have to hunt a bit.
gopher://os2info.gopher.ibm.com	This gopher server contains the entire IBM Employee Written Software library, as well as patches and newsletters for OS/2.
gopher://gopher.micro.umn.edu	The original gopher server at the University of Minnesota, containing a great deal of useful information regarding the Gopher protocol and other data that you may find interesting.

The World Wide Web is exploding into a viable information service and, naturally, there are web pages dedicated to OS/2 as well. You will find dozens of invaluable TCP/IP and Internet related pages out there too. In order to give you a head start on the Web, I have included the following table of relevant home pages.

http://info.cern.ch/	This is the original World Wide Web server. Here you will find a vast array of information regarding WWW and specifications for HTMLHypertext Markup Language;HTML. If you dig around a bit on this server, you will also find pointers to all of the RFCs for the Internet protocols.
http://webster.ibmlink.ibm.com/	This server is supported by IBM and provides press releases and a list of product specification sheets published by IBM, as well as customer testimonials for these products.
http://www.ibm.net	The main entry point for IBM's OS/2 information services, where you will find a great deal of OS/2 data, including lists of current applications, games, and other programs.
http://www.austin.ibm.com	This page is provided by IBM for OS/2 developers, more specifically for members of the Developer Assistance Program (DAP)IBMDeveloper Assistance Program or the Software Developer Operations (SDO) program. Here you will find information about special offers, beta programs, and product announcements from IBM.
http://www.teamos2.org	This page has been provided for TeamOS/2 use and offers lots of useful information. It includes a list of recommended shareware applications for OS/2. All program categories are covered, including graphics, communications, networking, etc.
http://www.os2bbs.com	This page is loaded with interesting OS/2 information including David Barnes's page of favorite software.

The information outlined above by no means represents a complete list of on-line sources for TCP/IP or OS/2. In fact, between the time I wrote these words and the time you read them, the number of relevant information sources will likely have doubled or even tripled. If you need some starting points, use a news client to send a query to an appropriate Usenet group.

Chapter Summary

This chapter has discussed necessary preparation for building TCP/IP applications for OS/2. You should now have a better feeling for the compiler and system requirements involved, as well as some background on other debugging and development aids that you may find useful. You should also have a better understanding of where you can find answers to your questions and additional information, using the various Internet sources. Finally, you should now have some appreciation of the methods by which you can organize and manage software projects.