       OS/2 2.x Frequently Asked Questions, Programmer's Edition
                       Version 2.0, June 1, 1993

                              Compiled by
                 Barry Jaspan <bjaspan@athena.mit.edu>
                                  and
                  Jeff Garzik <jgarzik@nyx.cs.du.edu>


Introduction
------------
This FAQ is for programming and development-related issues for OS/2 2.x.
It is freely distributable.  Direct all responses and questions to
jgarzik@nyx.cs.du.edu.  Mention of a product does not constitute an
endorsement.  Answers to questions closer to the bottom of the list may
rely on information given in prior answers.  Customers outside the
United States should not necessarily rely on 800 telephone numbers, part
numbers, or upgrade policies contained in this list; all prices are
listed in United Stated dollars unless otherwise specified.

Sometimes you will find a question that has been asked so often that it
deserves a place in the FAQ, regardless of whether I saw an answer to
that question or not.  In those cases I will simply put the question in
the header title, and put "(answer me!)" as the text.  This is a hint to
help me find someone who can answer this question.  And don't
forget...  PLEASE CONTRIBUTE ANY INFORMATION YOU CAN.

Many of the answers in this FAQ refer to anonymous ftp site
FTP-OS2.NMSU.EDU. The name 'ftp-os2' is used as a shorthand to refer to
this site.  It has become, by default, the Internet storehouse for OS/2
files.  If you cannot get files from this site (for whatever reason),
then check OS/2 Software Sources for a source near you.  What the hell -
check it anyway!  You may find a more convenient method of getting files
than from ftp-os2.


Release Notes
-------------
IMPORTANT NOTE:  Because of disk space problems, this FAQ, both INF and
ASCII forms, are uploaded to CDROM.COM on the Internet until ftp-os2
begins accepting submissions again.

This is the brand spanking newly updated version of Barry Jaspan's
programming FAQ (which he graciously mailed to me).

I (Jeff Garzik) am now the maintainer of the programming FAQ, since
Barry said he didn't have the time to keep it updated.

The FAQ isn't real complete right now since I haven't received and
tested all of the programs I promised.  I have high hopes for this FAQ -
I hope to keep it updated with benchmarks of the current compilers for
OS/2, and reviews of books, etc., etc.


Questions Covered in this Release
---------------------------------
(1.0) Languages, Compilers, Debuggers
     (1.1) What programming languages come with OS/2 2.x?
     (1.2) What C/C++ development environments are available?
     (1.3) What is the difference between the two GNU C packages?
     (1.4) How can I view the GNU C documentation?
     (1.5) What other programming languages are available for OS/2?
     (1.6) Which of these compilers can be used to generate PM apps?
     (1.7) What is REXX?  How do I write and run a REXX program?
     (1.8) What debuggers are available for OS/2?
     (1.9) Where can I get documentation on the OBJ/LIB/EXE format used by OS/2 2.x?
     (1.10) Please summarize this information, and tell me what I need to do OS/2 development.
     (1.11) GCC/2 crashes with a trap when I try to compile a program.  Why?
(2.0) Tools, Toolkits, Accessories
     (2.1) How do I recompile EPM (easily)?
     (2.2) What programming editors are available for OS/2?
     (2.3) What programming tools/toolkits/accessories are available for OS/2?
     (2.4) What GNU tools are available and where can I find them?
     (2.5) Is a socket library available?  How can I use it?
(3.0) Programming, Porting
     (3.1) How do I change the master environment?
     (3.2) What is the best way to communicate between processes?
     (3.3) What is the best way to communicate between threads?
     (3.4) How do I put bitmaps on buttons?
     (3.5) Can a PM program tell if there's a previous instance of itself running?
     (3.6) Is there an easy way to get printer output?
     (3.7) How can I recompile public domain/shareware source code for OS/2?
     (3.8) How can I port my DOS program to OS/2?
     (3.9) How can I port my Windows program to OS/2?
     (3.10) Is OS/2 suitable for real time programs?
     (3.11) How do I write an OS/2 device driver?
     (3.12) How can I simulate (Unix feature) under OS/2?
     (3.13) How does programming PM compare to programming X?
     (3.14) Why doesn't printf() produce output when I expect it to?
(4.0) Documentation, Help
     (4.1) Where can I get information on OS/2 APIs and programming?
     (4.2) Where can I get sample code?
     (4.3) Are there any OS/2 programming classes or seminars?
     (4.4) What are good reference books for programming in OS/2 and PM?
     (4.5) What are the OS/2 redbooks, and how do I get them?
(5.0) Miscellaneous
     (5.1) What is available for multimedia programming under OS/2?
     (5.2) What is available for AI/neural net programming under OS/2?
     (5.3) Are there any special programming software offers I should know about?
     (5.4) Technical Support
     (5.5) Developer's Assistance Program


(1.0) Languages, Compilers, Debuggers
-------------------------------------
This section covers the programming tools currently available for OS/2.


(1.1) What programming languages come with OS/2 2.x?
----------------------------------------------------
The original BASIC and BASICA (for systems with BASIC in ROM), DOS's
QBASIC, and OS/2's REXX come with OS/2 2.x.


(1.2) What C/C++ development environments are available?
--------------------------------------------------------
Many companies offer C or C++ compilers.  The following list is almost
guaranteed to be incomplete, somewhat inaccurate, and always out of
date.

IBM Workset/2, 1-800-3-IBM-OS2, $895.  Includes the C Set/2 compiler,
the IPMD multithreaded PM debugger, the Workframe/2 development
environment, and the Developer's Toolkit (utilities and online
documentation).  These pieces are also available separately.  The full
product announcement is available on ftp-os2.  Bug reports for C Set/2
can be mailed to cset2@vnet.ibm.com, for Workframe/2 to
workframe@vnet.ibm.com and will go straight to the developers.

NOTE:  Workset/2 was available at a promotional rate of $295 in the US
and $399 in Canada, but the originally announced end dates have passed.
I do not know if the promotion has been extended, so I assume it has
not.

Watcom C 9.0, (519) 886-3700.

JPI C and C++, (415) 967-3200 (USA), +44 234 267500 (UK/Europe), $180.

Glockenspiel C++, (+353)-1-733166.

Microway C++, $595.

Borland C++ for OS/2

GNU C.  Two flavors of the GNU C compiler are available, both on
ftp-os2.  GCC/2 is in /pub/os2/2.x/unix/gnu/gcc2-233, and emx/gcc is in
/pub/os2/2.x/unix/gnu/emx-0.8f.


(1.3) What is the difference between the two GNU C packages?
------------------------------------------------------------
The two versions of GNU C that are available were ported to OS/2 with
different goals and philosophies in mind and therefore have different
characteristics.  However, both systems include a fairly complete C
library and can be used to compile useful programs, although their
support of Unix-specific semantics differs.  Furthermore, both systems
are being actively developed and are constantly improving.

The goal of GCC/2 is to create a pure, freely redistributable OS/2 2.x
development environment with no extra baggage for backwards
compatibility; it is based on the assumption that DOS will die and is
not worth worrying about.  It is based on GNU C 2.3.3, supports C and
C++, and can create PM programs.  It produces "native" 32 bit .OBJ files
that are linked with OS/2's LINK386.EXE, and can be linked together with
.OBJ files produced by IBM C Set/2 and other compatible compilers.  The
mailing list os2gcc@charon.mit.edu exists for discussion of this port;
send mail to os2gcc-request@charon.mit.edu for subscription information.

emx/gcc 0.8f, also based on GNU C 2.3.3, supports C, C++, and Objective
C and can create PM programs.  emx's goal is to make porting Unix
programs easier by emulating Unix semantics as closely as possible. It
produces programs that can run both under OS/2 using EMX.DLL and under
DOS using the emx DOS extender.  emx/gcc uses standard Unix development
tools like ld and nm, and attempts to support Unix-isms like select()
and fork().  A version of gdb exists that can debug emx/gcc programs. An
emx-related mailing list exists; send mail to LISTSERV@ludd.luth.se with
a message body of "help" for subscription information.  (Note that this
is a *NEW* address for the emx discussion list.)


(1.4) How can I view the GNU C documentation?
---------------------------------------------
GNU C/C++ comes with documentation from the Free Software Foundation in
texinfo (.texi) format.  This documentation is about gcc in general, and
has no OS/2-specific information.

All utilities needed to compile/view/tex the texinfo files are readily
available for OS/2.  The GNU texinfo package, available on ftp-os2 in
pub/os2/all/gnu/gnuinfo.zoo, includes makeinfo.exe for compiling
texinfo, info.exe for viewing them, and texinfo.tex and texindex.exe for
TeXing them.

An ASCII text version of the gcc documentation is also available on
ftp-os2, in the file pub/os2/2.x/gnu/gcc21/gcctxt.zoo.

An INF hypertext version of the gcc (and related programs) documentation
was uploaded recently to ftp-os2, but has not been moved out of the
/pub/uploads directory yet.

emx/gcc includes its own hypertext style reader and texinfo files.


(1.5) What other programming languages are available for OS/2?
--------------------------------------------------------------
Virtually all of them: Assembler, COBOL, Pascal, Fortran, Smalltalk,
Modula-2, LISP, Forth, Perl, and more.  The OS/2 Tools Guide on ftp-os2
(pub/os2/all/info/tinf26.zoo) contains information on these and more.

[Vendors, ftp sites, phone numbers, prices?]

Pascal: Microway ($595), JPI ($180)

Modula-2: JPI ($180), Stonybrook

Fortran:

  Microway ($595), Watcom

  f2c Fortran-to-C translator: ftp-os2

Cobol: IBM Cobol/2

Smalltalk: Digital Smalltalk/PM V, Parc Place Smalltalk

Perl 4.0.10: ftp-os2

LISP:

  Common LISP: ma2s2.mathematik.uni-karlsruhe.de

  XLisp: ftp-os2

XScheme: ftp-os2

J: ftp-os2


(1.6) Which of these compilers can be used to generate PM apps?
---------------------------------------------------------------


IBM C Set/2 can generate PM apps.  Workset/2 includes many sample
programs and the complete on-line reference.

GNU C/C++ 2.1 can generate PM apps, and includes a sample program that
does it.  emx/gcc can too, with some limitations (what are they?).

Most commercial C and C++ compilers can.  WATCOM C and FORTRAN and all
of JPI's can, too.  You will probably want the IBM Developer's
Toolkit, or similar documentation, however.


(1.7) What is REXX?  How do I write and run a REXX program?
-----------------------------------------------------------
REXX is the IBM SAA (Systems Application Architecture) standard,
user-friendly programming language.  It is available for IBM mainframes,
Unix, the Amiga, DOS (Mansfield's Professional REXX), Windows, and many
other platforms.  It has been a part of standard OS/2 since Version 1.3.
Programs written in REXX that do not use system-specific libraries are
fully portable.

OS/2 2.x comes with an online REXX reference, and printed REXX
documentation is available (Mike Cowlinshaw's REXX book, IBM's twin
guides).  The Usenet group comp.lang.rexx discusses REXX programming.


(1.8) What debuggers are available for OS/2?
--------------------------------------------
IPMD, a PM-based debugger, ships with C Set/2.  It is capable of source-
and assembly-level debugging multithreaded 16 bit and 32 bit OS/2
applications

emx comes with gdb, the GNU debugger.  

Borland C++/2 comes with a PM-based debugger (Turbo Debugger GX) which
has the same basic functionality as IPMD.

There are also several commercial debuggers on the market.  WATCOM C and
FORTRAN come with WVIDEO, a full-screen source or assembly lever
debugger that handles multithreaded 16 and 32 bit OS/2 programs.
Multiscope, others?


(1.9) Where can I get documentation on the OBJ/LIB/EXE format used by OS/2 2.x?
-------------------------------------------------------------------------------
The .EXE format was described briefly in PC Magazine, Vol 11 No. 12
(June 30, 1992?); it was also described in a 1988 issue.

It is also available in text form from ftp-os2 as
/pub/os2/2.x/programming/lxexe.doc.


(1.10) Please summarize this information, and tell me what I need to do OS/2 development.
-----------------------------------------------------------------------------------------
(answer me!)


(1.11) GCC/2 crashes with a trap when I try to compile a program.  Why?
-----------------------------------------------------------------------
Because you didn't read the README or INSTALL files, probably.  There
are three general reasons GCC/2 will crash:

        1.  You did not set up the environment variables in CONFIG.SYS
        properly.  Read doc/INSTALL for instructions.

        2.  Some program that gcc expects to be in the PATH is not;
        unfortunately, gcc crashes instead of just printing an error
        message.  You may forgotten to install something, or your PATH
        may be wrong; see above.  Giving gcc the -v option will cause it
        to print each command line as it executes it; this will tell you
        which program is missing.

        3.  You are trying to get gcc to link your program for you. It
        cannot because ld does not exist, and so it crashes (see item
        2).  You must specify -c, -E, or -S on every invokation of gcc,
        and then use LINK386.EXE to create an executable.  See the
        sample makefiles for an example of how to do this.


(2.0) Tools, Toolkits, Accessories
----------------------------------
This section covers tools, toolkits, and accessories available to OS/2
programmers.


(2.1) How do I recompile EPM (easily)?
--------------------------------------
(answer me!)


(2.2) What programming editors are available for OS/2?
------------------------------------------------------
OS/2 2.x comes with the Enhanced Editor (EPM).

GNU Emacs 18.58 is available.  It requires you to have emx installed on
your machine, but it comes with all the emx files you will need. Emacs
is available on ftp-os2 in /pub/os2/2.x/gnu/emacs.  (If you want to
recompile emacs, you will need the full emx distribution; see question
1.2.)

Several public-domain vi clones are available, including elvis, Stevie
and levee.  The MKS Toolkit also includes vi.

Many other text editors are available.  

Epsilon, by Luguru, (412) 421-5678.  DOS upgrade to OS/2 is $90.
        Character based editor.

Q-EDIT, by SemWare, (404) 641-9002.  Character based editor, almost
        identical to Q-Edit for DOS.  Does not support long filenames.

Brief, KEDIT, others? [Vendors, phone numbers, prices?]


(2.3) What programming tools/toolkits/accessories are available for OS/2?
-------------------------------------------------------------------------
The IBM Programmer's Toolkit, included in Workset/2, includes many
tools.

Borland has released ObjectVision for OS/2.  [Details?]

Borland C++ for OS/2 also includes a number of utilities, such as the
Resource Workshop.

The MKS Toolkit, available from MKS ($349 USD, 800-265-2797 or
inquiry@mks.com), has over 160 Unix tools, including Korn shell, tar,
vi, awk, grep, tail, cpio, and so forth.  It also contains a Lex and
Yacc capable of generating C, C++, and Turbo Pascal code.

There is a product called ARGO/UX which provides a BSD environment for
OS/2.  [details?]


(2.4) What GNU tools are available and where can I find them?
-------------------------------------------------------------
Nearly all the GNU utilities have been ported to OS/2 2.x - and nearly
all of those ports are located on ftp-os2 in /pub/os2/2.x/unix/gnu.
Other, more involved (or independent) ports of GNU software is scattered
about ftp-os2, including a PM version of GhostView and GhostScript.


(2.5) Is a socket library available?  How can I use it?
-------------------------------------------------------
IBM's TCP/IP 1.2.1 ($200, part #02G6968) includes an optional
Programmer's Toolkit ($500, part #02G6973).  It includes a socket
library, and support for Sun RPC, NCS RPC, and a limited Kerberos
capability.  It requires IBM C Set/2 or another compiler that
understands 16-bit code.

FTP Software, Inc., has an OS/2 version of its TCP/TCP product.  They
can be reached at (617) 246-0900 or info@ftp.com.

Walt Corey, KZ1F, is porting KA9Q to OS/2 and PM. The current version of
his code is available for ftp from giskard.uthscsa.edu. This is still a
work in progress, with rough edges here and there, and in particular
there's no Ethernet (or anything but async serial, i.e. SLIP, PPP, and
KISS) support yet, though that's high on the priority list. You can
email Walt at kz1f@giskard.uthscsa.edu.

If you have the IBM TCP/IP 1.2 base package and IBM C Set/2, you can use
the TCPIPDLL.DLL directly.  A 32 bit socket library interface to do this
for you will be available shortly.  It will also be possible to call
TCP/IP functions from programs generated with gcc.  (Yes, yes, I know
I've been promising this for a while.  I apologize for the delay; be
patient.)


(3.0) Programming, Porting
--------------------------
This section covers general programming and porting practices.


(3.1) How do I change the master environment?
---------------------------------------------
Quick and simple answer: you don't.

In OS/2 it is literally impossible for you to change the master
environment from one of your programs.  Do be able to do so would
fatally disrupt the programming paradigm that has existed for ages:
Your program does not alter the master environment. Your program is the
slave, not the master.  Therefore, no capability was built into OS/2 to
facilitate this.

There is, however, a kludge.

As you know, a .CMD file can alter the master environment.  This is the
nature of batch files (ok, so I'm a MS-DOG dinosaur and still call them
batch files instead of command files or scripts).  Therefore, you can
place a sequence of commands in the batch file that will take your
program's output and alter the environment of your current shell.

That's as close as you are gonna get to the master environment.  You can
always create your own sort of environment variables, in the form of
shared memory or named pipes.


(3.2) What is the best way to communicate between processes?
------------------------------------------------------------
There is more than one way - and you get to decide which is right for
you!

Shared Memory

Shared memory is pretty self-explanatory.  It is a memory segment that
is allocated by one program, and then made available to other programs.
When all the programs are done with it, then it is disposed of.  You can
name shared memory.  So if you want two programs to communicate, then
let them look for memory with the same name and communicate that way.

Named Pipes

Named pipes are a lot like shared memory, but think of a named pipe as a
file instead of a single block of memory.  Each process can create,
read, write, and destroy a named pipe, much like you can a file.

The difference between named pipes and shared memory is that a named
pipe link is hot; With shared memory, data can be left in (as a sleeper,
if you will), process 1 exits, process 2 accesses the data in memory,
then deallocates the memory.  With shared memory, a process doesn't even
have to exist to leave a message for another process.

Queues

I wouldn't really think of these as ways to communicate between
processes, but some nifty programmer might come up with a good use for
queues.  Nevertheless, an OS/2 queue is a standard First-In First-Out
(FIFO) queue data/operation structure.  However, OS/2 makes it really
special because more than one process (or thread) can write to this
queue.


(3.3) What is the best way to communicate between threads?
----------------------------------------------------------
The best way to communicate between threads is sometimes also the best
way to communicate between processes.  However, when communicating
between threads you can utilize two (very important) techniques:

Semaphores

In order to share application resources, and not write to the same space
at the same time, you have to have some kind of flags that tell the
thread when it should stop, when it should keep on going, and so on.
Semaphores provide this capability.  Semaphores are not for passing
data.  They merely exist as simple flags between threads and you should
treat them as such.  (It would be nice sometimes if semaphores worked
across processes, but they don't.)

Global Variables

"Hey Jeff - I thought this was supposed to be about nifty OS/2-specific
tricks!"  It is!  You can now use those old nasty things, global
variables, in new ways.  In conjunction with semaphores, you can pass
data very easily between threads with global variables.  Here's a simple
example:

1. Create a global variable called PassData.
2. Create a semaphore called OkToPassData.
3. Create a semaphore called DataPassed.
4. Have two threads work at the same time:
        a. If the semaphore DataPassed is true:
                1. Set the semaphore OkToPassData to false.
                2. Read the data in the global.
                3. Set the semaphore DataPassed to false.
                4. Set the semaphore OkToPassData to true.
        b. When a thread wants to pass data, wait for the semaphore to be
           clear.
        c. Set the semaphore OkToPassData to false.
        d. Put the data in the global.
        e. Set the semaphore DataPassed to true.
        f. Set the semaphore OkToPassData to true.

Of course, there are issues of deadlock and other such nonsense that
corporate chaps get paid to consider, but that's beyond the scope of
this document.


(3.4) How do I put bitmaps on buttons?
--------------------------------------
Stefan Gruendal (Stefan_Gruendel@wue.maus.de) writes:

But to my question:  How do I build my own "smart icons", i.e. bitmaps
on pushbuttons, that optically "move into the screen"? I didn't find any
way to achieve this with the Toolkit's Dialog Editor.  But as mentioned
above, I know there's a way.

Starting with OS/2 2.x, a new button style was added - BS_ICON - which
allows you to do what you are trying to accomplish.  It works, as far as
I know, only for pushbuttons, and the icon or bitmap is taken from the
resource file, whose resource id is specified in the pushbutton text.

For example:

In FOO.H:

#define IDBM_BUTTON 256
#define IDPB_BUTTON 257

In FOO.RC:

BITMAP IDBM_BUTTON BUTTON.BMP

In FOO.C:

sprintf(achText,"#%d",IDBM_BUTTON);
 
hwndButton=WinCreateWindow(hwndClient,
                           WC_BUTTON,
                           achText,
                           WS_VISIBLE|BS_PUSHBUTTON|BS_ICON,
                           10,
                           10,
                           32,
                           32,
                           hwndClient,
                           HWND_TOP,
                           IDPB_BUTTON,
                           NULL,
                           NULL);

The bitmap is stretched or compressed to fill the button.

(Quoted almost directly from EDMI/2 Edition 1)


(3.5) Can a PM program tell if there's a previous instance of itself running?
-----------------------------------------------------------------------------
Raja Thiagarajan (sthiagar@bronze.ucs.indiana.edu) writes:

Can a PM program tell if there's a previous instance of itself running?
In Win3.x (but apparently NOT Win32), there's a hPrevInst handle; is
there an OS/2 2.x equivalent?  Basically, I'm thinking in terms of a
program that would try to borrow resources from a previous instance if a
previous instance is running.  (Specifically, if my palette animation
program gets started twice, the second instance oughta share palettes
with the first instance!)

What you're really asking is two questions:

        1. How can I determine if a previous instance of my application
        is already running?

        2. How can I share resources between multiple instances of my
        application?

To answer your first question, you need to enumerate all of the main
windows present on the desktop, and figure out if any of them are yours.
This is achieved using the following code:

HWND queryAppInstance(PCHAR pchClassWanted)
{
   HENUM heEnum;
   HWND hwndTop;
   HWND hwndClient;
   CHAR achClass[256];
 
   heEnum=WinBeginEnumWindows(HWND_DESKTOP);
 
   hwndTop=WinGetNextWindow(heEnum);
   while (hwndTop!=NULLHANDLE) {
      hwndClient=WinWindowFromID(hwndTop,FID_CLIENT);
      if (hwndClient!=NULLHANDLE) {
         WinQueryClassName(hwndClient,sizeof(achClass),achClass);
         if (strcmp(achClass,pchClassWanted)==0) {
            WinEndEnumWindows(heEnum);
            return hwndClient;
         } /* endif */
      } /* endif */

      hwndTop=WinGetNextWindow(heEnum);
   } /* endwhile */

   WinEndEnumWindows(heEnum);
   return NULLHANDLE;
}

To answer your second question, the only way that I know of to share
resources is to place them in a DLL.  The procedure to do this is as
follows:

        o Create a dummy source file with an empty procedure in it.
        o Compile the source file and link as a DLL.
        o Add your resources to the DLL in the same manner as you would
        to an executable.

Then, when your application starts, you simply call WinLoadLibrary  (the
preferred way) or DosLoadModule to load the DLL.  These functions return
a handle to the DLL which must then be used in any function which loads
resources (e.g. GpiLoadBitmap, WinLoadPointer, etc.).

Note that this procedure does not require knowing the window handle of
any previous instance of your application because OS/2 implements DLLs
in a shared fashion (which I suspect is one of the reasons they were
created in the first place).  All you need to know is the name of the
DLL.  This technique can also be used to share resources between
different applications.

(Quoted almost directly from EDMI/2 Edition 1)


(3.6) Is there an easy way to get printer output?
-------------------------------------------------
A reader who desires to remain anonymous writes:

Generally:  My understanding was that OS/2 would handle printing for me.
That is to say that I wouldn't have to create separate printer drivers
for every printer under the sun (or any for that matter).  Since I am
creating an image on the screen that is device independent (well, mostly
anyway), is there an easy way to get printer output?

PM achieves a level of device independence by defining a logical output
space.  This logical output space is then bound to a physical output
space, which creates a mapping of logical characteristics to their
physical counterparts.  The logical and physical output spaces are
referred to as the presentation space and the device context (HPS and
HDC) and are bound to one another by using either the GpiAssociate
function or by specifying GPIA_ASSOC to the GpiCreatePS function.

The easiest way to accomplish what you desire is to organize your
drawing code into one or more functions with a single entrypoint that
accepts an HPS as a parameter.  Then, when you want to draw to the
screen, you can call WinGetPS/WinBeginPaint to get an HPS and call the
function. When you want hardcopy, you call DevOpenDC to get an HDC and
GpiCreatePS to get an HPS and call the function.

Note that to get hardcopy, you need to perform some additional setup to
get things to work properly.  The two most important things are that you
initialize the DEVOPENSTRUC structure properly before calling DevOpenDC
and that you send the following escape codes (via DevEscape) at the
following times:

  hdcPrn=DevOpenDC(...);
  hpsPrn=GpiCreatePS(...);

  DevEscape(...,DEVESC_STARTDOC,...);

  if (!doDraw(hpsPrn)) {
     DevEscape(...,DEVESC_ABORTDOC,...);
  } /* endif */

  DevEscape(...,DEVESC_ENDDOC,...);

  GpiDestroyPS(hpsPrn);
  DevCloseDC(hdcPrn);

I'm not sure because I can't seem to find my copy anywhere, but I belive
that the book by Graham Winn (entitled something to the effect of
"Building applications using the OS/2 Presentation Manager") dedicates a
chapter to the nuances of printing.

(Quoted almost directly from EDMI/2 Edition 1)


(3.7) How can I recompile public domain/shareware source code for OS/2?
-----------------------------------------------------------------------
Most publicly available OS/2 programs come with binaries (since there is
currently only one OS/2 architecture).  If you are porting source code
from another system (for example, Unix), you will first need to acquire
a compiler.  See section 1 for information on compilers; in particular,
note that the GNU C compiler is available.

You should realize that many publicly available programs have already
been ported to OS/2.  Check the many FTP sites carrying OS/2 programs
before you reinvent any wheels (the OS/2 User's FAQ contains information
on FTP site).

Most Unix applications (through the use of emx/gcc) port with extreme
ease; DOS and Windows applications are a tougher problem, and require
many changes before they can be recompiled as a native OS/2 program.

(It is interesting to note that MicroSoft C v6.0 will compile bound OS/2
programs, which will run under DOS and OS/2 without
modification.)


(3.8) How can I port my DOS program to OS/2?
--------------------------------------------
To the first approximation, you don't have to --- OS/2 2.x's DOS support
is excellent, and your DOS program will probably just work; similarly,
OS/2 2.x supports Windows 3.0 (and soon 3.1) programs.  See the OS/2
User's FAQ for details.

[That was Barry Jaspan's opinion.  I believe that you should make every
effort to recompile your existing DOS programs for OS/2 2.x.  They will
run faster in many cases, and both (a) use less memory and (b) be able
to use more memory than their DOS counterparts. - Jeff]

If you truly want to port your DOS program over to OS/2, then study the
libraries available to you.  The core code (if you wrote it correctly)
will probably not change much.  You will just have to change the user
interface stuff.

If your program is a real simple one that uses standard input and
output, then you will probably not make very many changes to your
program when converting it to OS/2.

You should also realize that neato and nifty DOS tricks (like grabbing
an interrupt whenever you feel like it, or writing directly to almost
anywhere) are completely out of the question.


(3.9) How can I port my Windows program to OS/2?
------------------------------------------------
IBM Workset/2 includes Mirrors, a toolkit designed to help port Windows
applications to OS/2.  [Details?]

There are also several toolkits available that allow you to make calls
to a common API library, and your source will work across the two
platforms without any changes at all.

However, if you want to bite the bullet and port it, then be prepared to
make a lot of changes.  Just like porting regular DOS programs, you will
have to scrap most, if not all, of your user interface.  Your core code,
if modular and abstract enough, should come through the port relatively
unscathed.


(3.10) Is OS/2 suitable for real time programs?
-----------------------------------------------
Yes!  There is a special priority you can assign your programs
(ForegroundServer Mode) via DosSetPriority() which will give your
process (note, not thread, but process) the maximum allowable CPU time.

Another route is to use DosEnterCritSec()/DosExitCritSec().  Calling the
former will disable thread switching (hopefully for a short period of
time), and calling the latter will enable thread switching again.


(3.11) How do I write an OS/2 device driver?
--------------------------------------------
There's a book called Writing OS/2 2.0 Device Drivers in C
from Van Nostrand-Reinhold.  There's also IBM's flood of printed
material.


(3.12) How can I simulate (Unix feature) under OS/2?
----------------------------------------------------
1. fork
2. fork/exec
3. select
4. job control

In general, you can't.  select() depends heavily on the fact that all
sources and sinks of data originate in the filesystem and are identified
by a coherent set of file descriptors; these assumptions are not true
under OS/2.  For (almost) any particular kind of data source/sink
(files, sockets, pipes) you can achieve most of select()'s semantics.  A
decent solution to this problem requires a C library that maintains its
own array of file descriptors and information on each one such that it
can dispatch to the appropriate module in response to library calls.
The C libraries delivered with gcc and emx/gcc will have such
functionality in the (possibly near) future, but don't yet.

A working version of fork() comes with the emx/gcc libraries.  The
author cautions that this is not the way to multitask, though, because
it eats up a lot of resources (since it literally duplicates the current
process, leaving everything but the PID unchanged).  _beginthread() is
the suggested solution if at all possible.


(3.13) How does programming PM compare to programming X?
--------------------------------------------------------
Many people have said "PM is much cleaner."  Until I hear from someone I
trust with extensive experience with both (I only know X), however, this
FAQ will take no position.

There was an unsubstantiated rumor that someone was porting an X library
to OS/2 (X-Windows, not X-Mode or any other X), I dunno whether this has
been substantiated or not.

IBM and a few other manufacturers have built their own X servers for
OS/2.  [details?]


(3.14) Why doesn't printf() produce output when I expect it to?
---------------------------------------------------------------
For historical reasons, most Unix C libraries' stdio default to using
line buffered streams, whereas most DOS and OS/2 C libraries' stdio
default to using fully buffered streams.  ANSI C species that standard
output should be line buffered when connected to an interactive device,
but not all libraries are ANSI compliant.  You can control the buffering
algorithm used for a particular stream with the setvbuf() function.

If you didn't understand that paragraph, read on.

printf() is part of the Standard I/O (stdio) library, which uses
buffered streams for file IO.  ANSI C specifies three algorithms for
deciding when to flush the buffer (i.e. when to print buffered data to
the file):

        o not buffered.  Data is flushed to the file as soon as
        possible, usually immediately after being received.

        o line buffered.  Data is flushed to the file when a newline is
        received (and the newline is also flushed).

        o fully buffered.  Data is flushed to the file when the buffer
        is full.

Buffered data is always flushed when the stream is closed or when
fflush() is called.  Since standard output is flushed when main() exits,
all data printed with printf() will appear at that time, if it has not
already.  However, ANSI C does not require that a stream be flushed when
scanf() is called on it.  Therefore, if you print to a fully buffered
stream and then request input on it, it is likely that the input will be
read before the printed data appears.

You can control the buffering algorithm used for a particular stream
with the setvbuf() function.  For example, the statement
setvbuf(stdout, NULL, _IOLBF, BUFSIZ) sets standard output to be
line-buffered, which is what most Unix programmers expect.  Any decent C
reference will cover all of this material.

The gcc 2.1 library will have a line-buffered stdout by default in a
future release.


(4.0) Documentation, Help
-------------------------
This section covers documentation and help available for OS/2
programming.


(4.1) Where can I get information on OS/2 APIs and programming?
---------------------------------------------------------------
The IBM Programmer's Toolkit, included in Workset/2, includes a complete
on-line syscall reference.

You can order the seventeen volume IBM OS/2 Technical Library (possibly
at a discount, see question 1.2) and/or order various volumes
individually; the file pub/os2/2.x/info/os2pubs.txt lists all (many?) of
the IBM OS/2-related reference manuals, as of May 20, 1992, along with
ordering information.


(4.2) Where can I get sample code?
----------------------------------
There is a lot of sample code included in the IBM Toolkit, and 4 sample
programs (with source) included with C Set/2.  GNU C/C++, from ftp-os2,
includes a sample C, C++, and C++ PM program.  The OS/2 Redbooks also
have some sample code.  ftp-os2 also has little bits of OS/2 and PM
source code lying around in the /pub/os2/2.x/programming directory.


(4.3) Are there any OS/2 programming classes or seminars?
---------------------------------------------------------
Yes.  Call IBM at either 1-800-3-IBM-OS2 in U.S. (or the PS/2 Help
Center).  Local IBM branches frequently hold OS/2 classes and seminars.
I haven't seen third party efforts in this regard, but I know they
exist.

See pub/os2/2.x/info/ivleague.txt on ftp-os2 for a list of third-party
support organizations.


(4.4) What are good reference books for programming in OS/2 and PM?
-------------------------------------------------------------------
Van Nostrand Reinhold publishes a number of books on OS/2 2.x.  Those
that relate to programming are:

INTEGRATING APPLICATIONS WITH OS/2 2.0
By William H. Zack
0-422-01234-9

CLIENT SERVER PROGRAMMING WITH OS/2 2.0
By Robert Orfali and Daniel Harkey, IBM Corporation
0-422-01219-5

WRITING OS/2 2.0 DEVICE DRIVERS IN C
By Steven J. Mastrianni; Foreword by John Soyring, IBM Corporation
0-442-01141-5

OS/2 2.0 PRESENTATION MANAGER GPI:
A Programming Guide to Text, Graphics, And Printing
By Graham C.E. Winn, IBM Corporation
0-442-00739-6

THE COBOL PRESENTATION MANAGER PROGRAMMING GUIDE
By David M. Dill, Consultant
0-442-01293-4

LEARNING TO PROGRAM OS/2 2.0 PRESENTATION MANAGER BY EXAMPLE:
Putting the Pieces Together
By Stephen Knight, IBM Corportaion
0-442-01292-6


(4.5) What are the OS/2 redbooks, and how do I get them?
--------------------------------------------------------
IBM publishes so-called "redbooks" on many products, including OS/2 2.x.
They seem to be a combination of power-user's guides and design
information that may be of use to both users and programmers [I haven't
received my copies yet, so I cannot say for sure.]  These are usually
intended only for special IBM customers and contain documentation that
is generally unavailable anywhere else.  You can order these books
directly from IBM (see below).  All of the following names are
implicitly preceeded by "OS/2 Version 2.0."

Volume 1: Control Program: GG24-3730, $4.15

  Technical information on Memory Management, Task Mangement, Support,
  Installation Considerations, Hardware Considerations, Boot Manager,
  National Language Considerations, Intel 386 architecture, Channel
  Architecture and SCSI.  Documents config.sys.

Volume 2: DOS and Windows Environment, GG24-3731, $6.20

  MVDM,8086 Emulation,MVDM DOS emulation, Device Drivers, Memory
  Extender Support, Installing and Migrating Applications, Windows
  Applications, DPMI, Running DOS apps,DOS settings, VMB.

Volume 3:  PM and Workplace Shell GG24-3732, $3.65

  Available now, but I don't know precisely what's in it.

Volume 4: Application Development GG24-3774, $5.25

  Technical programming info (includes list in C) Overview,
  Object-Oriented Apps, PM application model, flat memory model,
  building PM app, Workplace AOAShell and System Object Model, Direct
  Manipulation (Drag/drop), PM resources, Multitasking Considerations,
  SAA CUA considerations, App Migration, Mixing 16 and 32 bit
  application modules, compiling and link editing (SOM), Adding Online
  Help, Problem Determination, Managing Development, Naming conventions.

Volume 5: Print Subsystem, GG24-3775, $5.20

  Not Available yet.

The special part number GBOF-2254 is for all currently available volumes
(presently 1-4).

ORDERING INFORMATION:

The OS/2 2.x Redbooks are available from IBM's TeleServices customer
support number.  The number is 1-800-7654-IBM (1-800-765-4426).  You can
pay by credit card or mail in a check after calling.  The order will
take about 2 weeks but can be sped up by paying for faster shipping.

You can also order the redbooks from your local IBM Branch Office
library.  Some possibly useful phone numbers are included here.

        IBM Central Library, Los Angeles CA: (213) 621-6710
                P.O. Box 60737
                Los Angeles, CA 90060
        Canada: (800) 465-1234, ext 4205 ($33.52)
        UK: (0256) 478166, (#36.51, credit cards accepted)
        Australia (Victoria): 698-1234 ($46.80 A)
                IBM Australia
                The Library
                211 Sturt Street
                South Melbourne, 3205
                Att: Kate Seeley
        Denmark: 33 32 40 55 (dkk 310)


(5.0) Miscellaneous
-------------------
This section covers questions not covered in previous sections.


(5.1) What is available for multimedia programming under OS/2?
--------------------------------------------------------------
The OS/2 2.x Multimedia package is now available.  Call the
IBM Multimedia office at (800) 426-9402 ext. 150.


(5.2) What is available for AI/neural net programming under OS/2?
-----------------------------------------------------------------
LISP and XScheme are available from ftp-os2.  There are also some
AI/neural net tools listed in tinf26.zoo.


(5.3) Special software offers
-----------------------------
Here are some of the OS/2 software products that represent particularly
good values.  Most prices do not include shipping and handling.

        o Borland C++ for OS/2.  Available from Below Zero in Calgary
          (phone 800-461-2777, 403-547-0669, or FAX 403-547-1018) for
          about $136 U.S., including shipping.  Add GST in Canada.
          Below Zero will export outside North America.

        o IBM PL/I.  Not everyone is a PL/I programmer, but IBM is
          offering free copies of Workframe/2 with every purchase and
          free product videos. Phone 800-426-3346 ext. STL10 for more
          information on the two packages available.

(Quoted almost directly from OS/2 General FAQ)


(5.4) Technical Support
-----------------------
How can I get answers to my OS/2 questions?

If your question is not answered in this List, post a note to the
appropriate Usenet conference:

comp.os.os2.apps                carries discussions related to finding
                                or using any application running under
                                OS/2

comp.os.os2.networking          looks at networking issues

comp.os.os2.advocacy            deals with opinions and speculation

comp.os.os2.programmer.porting  helps programmers move applications over
                                to OS/2 from other operating systems and
                                environments

comp.os.os2.programmer.misc     addresses anything else related to OS/2
                                programming

comp.os.os2.beta                explores beta releases of OS/2

comp.os.os2.ver1x               supports all releases of OS/2 prior to
                                Version 2.0

comp.os.os2.announce            carries important OS/2 announcements

comp.os.os2.bugs                discusses possible bugs found in
                                released versions of the operating
                                system

comp.os.os2.multimedia          fosters conversation about OS/2
                                multimedia (including MMPM/2),

comp.os.os2.setup               offers a place to talk about setup and
                                installation issues

comp.os.os2.misc                is for any other OS/2-related discussion

comp.lang.rexx                  discusses REXX programming

These groups are also watched closely by OS/2 experts from IBM.

A LISTSERVer distributes its own OS/2 conference by mail; send a single
line message with the word HELP to listserv@cc1.kuleuven.ac.be for full
instructions; or send the same message to listserv@frors12.circe.fr for
information on an unedited mailing list.  To subscribe to the
Multimedia Presentation Manager/2, send a single line message with the
phrase SUBSCRIBE MMOS2-L (Your Name) to mail-server@knex.via.mind.org.

Your local FidoNet BBS may carry OS/2 echo conferences and/or OS2NET. If
not, ask your system operator to join them.  CompuServe (FIND OS/2) and
Prodigy are also excellent resources.

The IBM PC Co. BBS's (modem 404-835-6600) message areas, product
database, and PS/2 Assistant file(s) are invaluable resources.
Information on the new OS/2 BBS is included in the OS/2 2.0 package. In
the United States IBM has toll free technical support (phone
800-237-5511), an OS/2 Hotline (general information, orders, upgrades,
phone 800-3-IBM-OS2; ask about OS/2 videotapes, T-shirts, and other
accessories), the HelpWare Center (phone 800-PS2-2227), a software order
line (phone 800-IBM-CALL), two FAX information services (phone
800-IBM-4FAX and/or 800-IBM-3395), and an educational inquiries line
(phone 800-222-7257).  In Canada phone IBM Personal Systems Software at
800-465-1234.

Any of the regular DOS or Windows resources (e.g. books, magazines,
shareware/freeware sources) will be useful since both environments come
with OS/2 2.0.

(taken from OS/2 General FAQ)


(5.5) Developer's Assistance Program (DAP)
------------------------------------------
OS/2 2.0 developers should contact the IBM Developer Assistance Program
(phone 407-982-6408); membership is free.  (You may also join on
CompuServe with GO OS2DAP.)  The OS/2 Professional Developer's Kit
CD-ROM, containing a wide selection of development tools and code, and
the OS/2 2.1 Beta CD-ROM are both available from IBM (phone
800-3-IBM-OS2 to order in the United States for between $15 and $20
each, shipping included; in Canada, phone 800-465-1234; in Australia,
phone Rohaini Cain or Mike Voris at 13-2426 ext. 7684; elsewhere,
contact the International OS/2 User Group by phoning 285-641175 in the
U.K.)  The OS/2 Device Driver Development Kit CD-ROM is also now
available from IBM.  To order phone 407-982-4239 (FAX 407-982-4218) in
North America, 61-2-354-7684 (FAX 61-2-354-7766) in most of the Far East
and Pacific Rim, 81-3-5563-5897 (FAX 81-3-5563-4957) in Japan,
81-2-528-1548 (FAX 82-2-528-1414) in Korea, or 011-52-627-1846 (FAX
011-52-395-7812) in Latin America.

(taken from the OS/2 general FAQ)


OS/2 Software Sources
---------------------
The following BBSes hold large OS/2 libraries:

Name                            Number
----------------------------------------------
Fernwood                        (203) 483-0348
OS/2 Shareware                  (703) 385-4325
Bay Area OS/2                   (510) 657-7948
Gateway/2                       (314) 554-9313
Greater Chicago Online          (708) 895-4042
OS/2 San Diego                  (619) 558-9475
OS/2 Las Vegas                  (702) 433-5535
IBM Germany                     049-711-785-7777
IBM Denmark                     45-42-88-72-22
OS/2 UK                         0454-633197
IBM UK                          0256-336655
IBM Norway                      47-66-99-94-50
OS/2 Norway                     47-22-38-09-49
OS/2 Australia                  61-2-241-2466

(The monthly Worldwide OS/2 BBS Listing, available from these BBSes,
lists others.)  The IBM PC Company BBS (modem 404-835-6600) has some
shareware/freeware as well, along with CSDs and the PS/2 Assistant (an
invaluable resource for locating almost any sort of information on
OS/2). For information on IBM's new OS/2 BBS phone 800-547-1283.  IBM
Canada maintains several support BBSes:

     (416) 946-4255
     (514) 938-3022
     (604) 664-6464
     (416) 946-4244

The Usenet conference comp.binaries.os2 carries OS/2 software.  And
several sites are available via anonymous ftp.  (No ftp?  Send a single
line message with the word HELP to bitftp@pucc.bitnet or
ftpmail@decwrl.dec.com to learn about ftp mail servers.)  Some are (with
Internet node numbers and subdirectories):

Site                            IP Address      Home OS/2 Directory
-------------------------------------------------------------------
ftp-os2.nmsu.edu                128.123.35.151  pub/os2
hobbes.nmsu.edu                 
software.watson.ibm.com         129.34.139.5    pub/os2
mtsg.ubc.ca                     137.82.27.1     os2:
access.usask.ca                 128.233.3.1     pub/archives/os2
luga.latrobe.edu.au             131.172.2.2     pub/os2
funic.funet.fi                  128.214.6.100   pub/os2
pdsoft.lancs.ac.uk              148.88.64.2     micros/ibmpc/os2
ftp.uni-stuttgart.de            129.69.1.12     soft/os2
src.doc.ic.ac.uk                146.169.2.1     computing/systems/os2
zaphod.cs.uwindsor.ca           137.207.224.3   pub/local/os2
ftp.luth.se                     130.240.18.2    pub/pc/os2

The ftp-os2.nmsu.edu library is available on CD-ROM from Walnut Creek
(phone 510-947-5996).  EMS (phone 301-924-3594) offers an OS/2
shareware/freeware library on diskette.

Other sources include CompuServe (FIND OS/2) and archive servers (send a
single line message with the word HELP to listserv@cc1.kuleuven.ac.be or
mail-server@rus.uni-stuttgart.de for more information, or use ftp).
TRICKLE servers are also available outside the United States.  For more
information on TRICKLE services, including automatic file subscription
procedures, send a single line message with the word HELP to any one of
the following sites nearest you:

Country         Address
---------------------------------------
Austria         TRICKLE@AWIWUW11.BITNET
Belgium         TRICKLE@BANUFS11.BITNET
Colombia        TRICKLE@UNALCOL.BITNET
France          TRICKLE@FRMOP11.BITNET
Germany         TRICKLE@DEARN.BITNET
Israel          TRICKLE@TAUNIVM.BITNET
Italy           TRICKLE@IMIPOLI.BITNET
Netherlands     TRICKLE@HEARN.BITNET
Sweden          TRICKLE@SEARN.BITNET
Turkey          TRICKLE@TREARN.BITNET
                TRICKLE@TRMETU.BITNET

IBM has been releasing freely distributable employee written software
(e.g. Visual REXX) and OS/2 patches to these sites.

(The previous was taken almost verbatim from the OS/2 General FAQ)


Bugs / Obtaining this FAQ / Contacting the Author
-------------------------------------------------
Reporting Bugs and Errors in the FAQ

With the advent of all this nifty hypertext IPF stuff, there are bound
to be bugs and errors in this FAQ, simply by Murphy's Law.  (Anything
that can go wrong, will go wrong)  If you find an error, however,
insignificant, please send me a note (through one of the ways listed
below) telling me what's wrong with the FAQ.

Obtaining this FAQ

This FAQ is distributed on a regular basis to:

        1. ftp-os2.nmsu.edu on the Internet
        2. IBM PCC BBS in Atlanta, GA (404-835-6600) 14.4k V.32bis
        3. Information Overload in Atlanta, GA (1:133/308 FidoNet)
           (404-471-1549) 19.2k ZyXEL V.32bis

All other sites should receive this FAQ on a trickle-down basis from
these sites.

This FAQ is distributed in two versions, ASCII and INF.  The INF version
is binary and viewable only by the VIEW.EXE program that comes with
OS/2.  The filename is PFAQnnIN.ZIP, where 'nn' is the FAQ version.  The
ASCII version is text and is viewable by any program that can view text
(which includes most word processors).  The filename is PFAQnnAS.ZIP,
where 'nn' is the FAQ version.

Contacting the Author

I can be contacted in a multitude of ways:

        o Internet.  This is the preferred method.  E-mail me at
          jgarzik@nyx.cs.du.edu.  You may see me posting from one of my
          two Georgia Tech accounts, gtd543a@cc.gatech.edu and
          gtd543a@prism.gatech.edu.  Don't be alarmed.  I have my mail
          forwarded. I ask people to e-mail me at nyx because my account
          there is permanent. My account at GT is contingent on my
          staying at Tech.  I lose it when I either get kicked out or
          graduate.
        o FidoNet.  I check this one at least one or twice a week.
          Jeff Garzik@1:133/103 FidoNet. This account is contingent on
          my staying in Atlanta.  Which I plan to for quite some time.
        o US Postal Service.  This will stay while I am at Tech also.

                Jeff Garzik
                25861 Georgia Tech Station
                Atlanta, GA  30332

        o Face to face.  This is the toughest, because no one knows what
          I look like and most people reading this FAQ don't hang out at
          Tech for fun.  (I know I wouldn't!)  But the next time you are
          in Atlanta, GA, if you see a 6' guy with a goatee and a punk
          rock t-shirt, don't hesitate to ask if it's me...


Credits
-------
The following people have contributed in numerous and not-so-numerous
ways to this document to make it what it is today, and what it will be
tomorrow.  Give a big round of applause for...

Barry Jaspan <bjaspan@athena.mit.edu>
Jeff Garzik <jgarzik@nyx.cs.du.edu>
Byers R E James <zoorejb@nusunix2.nus.sg>
Stefan Gruendal <Stefan_Gruendel@wue.maus.de>
Raja Thiagarajan <sthiagar@bronze.ucs.indiana.edu>
Larry Saloman <os2man@panix.com>
Timothy Sipples <sip1@ellis.uchicago.edu>

Ok, so the list is a little short right now.  If you contributed to
Barry's FAQ and you are not listed here, then please send me your name
and I'll be glad to include you in this list.

I have obtained some information from sources other than people also.
Besides being credited above, here is another list:

OS/2 Frequently Asked Questions List v2.0l  (Available from ftp-os2
in /pub/os2/all/info/faq/faq20l.zip)

Electronic Developers' OS/2 Magazine  (Available from ftp-os2 in
/pub/os2/all/info/edmi/*)

[EOF] -- End Of FAQ ;-)

