GLOBAL DATA AREA & DOS2OS2 API
by Karly Court Software

Contents
License Agreement....................1
Introduction.........................2
Installation and Sample Files........2
Global Data Area Description.........3
GDA Virtual Device Driver............3
Global Data Area Functions...........3
	Send Data to GDA................3
	Receive Data from GDA...........3
	Update Data in GDA..............4
	Read Data From GDA..............4
	Reset Update/Read Semaphores....5
	Dos Sleep.......................5
Dos API Description..................6
Dos API Functions....................6
	Start OS2/DOS/WIN Session.......6
	Create Event Semaphore..........7
	Open Event Semaphore............7
	Close Event Semaphore...........8
	Post Event Semaphore............8
	Reset Event Semaphore...........8
	Query Event Semaphore...........9
	Wait Event Semaphore............9
Coming Soon!.........................9

License Agreement
You may use the software contained in this package for evaluation purposes
free of charge.  However, if you use the software libraries for commercial or
in-house development you must register the software with Karly Court
Software.  Registering the software entitles you to install the device driver
on an unlimited number of systems in your company.  You may also modify
the source code with no restrictions.  Karly Court Software is not responsible
for any damages resulting from the use of this product.  The price of the
product is $59.00 US.  This product is offered to help Dos and Windows
developers migrate their systems to the OS/2 platform and the registration
fee is requested to help offset costs incurred in its development.  When you
register, you will receive the latest version of the software, printed documen-
tation, and all source code.

Introduction
One of the benefits of OS/2 is the ability to not only run true 32-bit programs
in a multithreaded environment, but to also run older 16-bit DOS and
Windows programs.  This is quite an accomplishment given the fact that DOS
was not designed as a multitasking environment and that Windows is a
"cooperative" rather than pre-emptive multitasker.  Being able to operate
programs from three different platforms at the same time is great, but one
shortcoming of OS/2 is the lack of interprocess facilities for the DOS and
Windows environment.  IBM's direction is for DOS programs to use named
pipes, but that requires an OS/2 program to initially create the pipe.
Windows and OS/2 programs can communicate using DDE and other
clipboard related functions but at considerable overhead.  This is where the
Global Data Area and Dos API functions help.  They allow DOS, Windows,
and OS/2 programs to read and write to a small 1K data area that is common
to all programs.  Often a programmer may only want to set a flag that other
sessions can check or to pass messages between a group of programs.  By
using a very small virtual device driver and a set of "undocumented" DOS
interrupt calls this can now be done.

Installation and Sample Files
To install the files on your system perform these steps.
Create a directory DOS2OS2.
	md DOS2OS2

Copy this file to the DOS2OS2 directory where sdrive is the source drive
and ddrive is the destination drive that contains the DOS2OS2 directory.
	copy sdrive:\DOS2OS2.ZIP ddrive:\DOS2OS2\DOS2OS2.ZIP

Unzip this file in the DOS2OS2 directory.
	cd DOS2OS2
	pkunzip -do DOS2OS2.ZIP

Add the following line to the end of your OS/2 config.sys file 
where drive is the drive letter that the files were installed.
	device=drive:\DOS2OS2\VDOSAPI.SYS

Your are now ready to use the GDA functions!

Included in this package are the following samples file:
	VDOSAPI.SYS GDA Virtual Device Driver
	TESTAPIL.EXE    Dos large model test program
	TESTAPIS.EXE    Dos small model test program
	TESTOS2.EXE OS/2 character mode test program
	WINAPI.EXE      Windows menu driven test program
	DOSAPI.H        Header file for Dos/Windows libraries
	DOSAPI_L.LIB    Dos large model library
	DOSAPI_S.LIB    Dos small model library
	OS2API.H        Header file for OS/2 library
	OS2API.LIB      OS/2 library

Registered users of this package will receive source code to the device
driver, source code to the libraries and test programs, and a stub program
with documentation that allows OS/2 programs to execute in a VDM.

Global Data Area Description
As mentioned, named pipes are recommended by IBM for interprocess
communications between Dos applications and OS/2.  Named pipes can only
be created at this time by an OS/2 program.  Also, a named pipe can only be
used between one set of programs at a time.  Named pipes are not
persistent; when the pipe is closed the data is gone.  By using a permanent
1K global data area that all platforms can access these limitations are
overcomed.  This data area is controlled by a virtual device driver using the
following functions:

Global Data Area Functions

-----------------------------------------------------------------------
DosApi_Send         [OS/2, DOS, Windows]

Function:   Sets GDA to a range of bytes starting at a given offset.

Syntax:   include "dosapi.h"
		unsigned int DosApi_Send(char far *pBuffer,
			short ByteRange, short BuffOffSet);

Remarks:  DosApi_Send copies the range of bytes pointed to by
		pBuffer for ByteRange number of bytes starting at the GDA
		offset BuffOffSet.

Returns:  If the sum of ByteRange and BuffOffSet exceed the length
		of the GDA (1024 bytes) decimal 11 is returned.
		If the VDOSAPI driver is not loaded decimal 127 is returned.

-----------------------------------------------------------------------
DosApi_Recv         [OS/2, DOS, Windows]

Function: Returns a range of bytes from the GDA starting at a given
		offset.

Syntax:   include "dosapi.h"
		unsigned int DosApi_Recv(char far *pBuffer,
			short ByteRange, short BuffOffSet);

Remarks:  DosApi_Recv copies from the GDA ByteRange number of
		bytes starting at the offset BuffOffSet to the address pointed
		to by pBuffer.

Returns:  If the sum of ByteRange and BuffOffSet exceed the length
		of the GDA (1024 bytes) decimal 11 is returned.
		If the VDOSAPI driver is not loaded decimal 127 is returned.

-----------------------------------------------------------------------
DosApi_Update          [OS/2, DOS, Windows]

Function: Sets GDA to a range of bytes starting at a given offset if
		the update semaphore is posted.

Syntax:   include "dosapi.h"
		unsigned int DosApi_Update(char far *pBuffer,
			short ByteRange, short BuffOffSet);

Remarks:  DosApi_Update copies the range of bytes pointed to by
		pBuffer for ByteRange number of bytes starting at the GDA
		offset BuffOffSet.  This function is identical to the
		DosApi_Send function with one difference: No data is
		copied if the update semaphore is set.  The DosApi_Read
		function posts the update semaphore to allow the GDA to be
		updated again.  This function teamed with the DosApi_Read
		function is designed for serialized transfer of large amounts
		of data similar to a named pipe without the overhead. One
		process updates the GDA while another reads it.  The
		update and read semaphores prevent two successive
		updates without a read and vice versa.
		The DosApi_Send and DosApi_Recv functions have no
		effect on the semaphores used by these functions and may
		be used as desired.

Returns:  If the sum of ByteRange and BuffOffSet exceed the length
		of the GDA (1024 bytes) decimal 11 is returned.
		If the no DosApi_Read or DosApi_Reset has occurred since
		the last DosApi_Update call decimal 12 is returned.
		If the VDOSAPI driver is not loaded decimal 127 is returned.

-----------------------------------------------------------------------
DosApi_Read         [OS/2, DOS, Windows]

Function: Returns a range of bytes from the GDA starting at a given
		offset if the read semaphore is posted..

Syntax:   include "dosapi.h"
		unsigned int DosApi_Read(char far *pBuffer,
			short ByteRange, short BuffOffSet);

Remarks:  DosApi_Read copies from the GDA ByteRange number of
		bytes starting at the offset BuffOffSet to the address pointed
		to by pBuffer.  This function is identical to the
		DosApi_Recv function with one difference: No data is
		copied if the read semaphore is set.  The DosApi_Update
		function posts the update semaphore to allow the GDA to be
		read again.  Refer to the DosApi_Update Remarks: for
		more details.

Returns:  If the sum of ByteRange and BuffOffSet exceed the length
		If the no DosApi_Update or DosApi_Reset has occurred
		since the last DosApi_Update call decimal 13 is returned.
		of the GDA (1024 bytes) decimal 11 is returned.
		If the VDOSAPI driver is not loaded decimal 127 is returned.

-----------------------------------------------------------------------
DosApi_Reset            [OS/2, DOS, Windows]

Function: Resets the update and read semaphores prior to a
		serialized transfer using the DosApi_Update and
		DosApi_Read functions.

Syntax:   include "dosapi.h"
		unsigned int DosApi_Reset( void);

Remarks:  Prior to transferring data between processes using the
		DosApi_Update and DosApi_Read combination, call
		the DosApi_Reset function to insure a valid initial
		semaphore state.

Returns:  If the VDOSAPI driver is not loaded decimal 127 is returned.

-----------------------------------------------------------------------
DosAPI_Sleep            [DOS, Windows]

Function: Yields the VDM session for a specified length of time

Syntax:   include "dosapi.h"
		unsigned int DosApi_Sleep( short SleepHths );

Remarks:  DosAPI_Sleep surrenders the current VDM session for the
		length of time specified by SleepHths.  This period of time
		is in hundredths of a second.  This function is useful when
		using the update and read functions in a VDM to prevent
		"burning up a loop" while checking for the update or read
		semaphore to be posted.  OS/2 has its own DosSleep
		function and it should be used instead of this one.  Also, VDM
		processing is blocked during the sleep period.  For this
		reason, it is better to use Windows timers to emulate this
		function or the Yield() function.  Using the DosAPI_Sleep
		function in Windows would block ALL applications in a full
		screen session.  Another alternative in a VDM session is to
		call interrupt 0x2F function 0x1680 (Dos idle function).


Returns:  Always returns zero.

Dos API Description
Another technique that can be used to implement interprocess
communication is the use of semaphores.  Although not as powerful as the
GDA routines, semaphores can be used when simple coordination between
tasks is required.  The semaphore routines included with this package are
event semaphores which are the most common.  Also included in this
package are routines to start other OS/2, DOS, or Windows sessions from
within a VDM.

Dos API Functions

-----------------------------------------------------------------------
DosStartSession         [DOS, Windows]

Function: Starts a new OS/2, DOS, or Windows session.

Syntax:   include "dosapi.h"
		unsigned int DosStartSession( Session_Data far *SessData );

Remarks:  Following are the parameters of the SessData structure:
		typedef struct {
			unsigned int Sess_Struct_Len; 
			/* Must be 0x18,0x1E,0x20,0x32, or 0x3C */
			unsigned int Sess_Relation;
			/* 00 independent, 01 child */
			unsigned int Sess_Fore_Back;
			/* 00 foreground, 01 background */
			unsigned int Sess_Trace;
			/* 00-02, 00 = no trace */
			char far *Sess_Program_Title;
			/* max 62 chars or 0000:0000 */
			char far *Sess_Program_Name;
			/* max 128 chars or 0000:0000 */
			char far *Sess_Program_Args;
			/* max 144 chars or 0000:0000 */
			unsigned long Sess_Term_Queue;
			/* reserved, must be 00000000 */
			char far *Sess_Environment;
			/* max 486 bytes or 0000:0000 */
			unsigned int Sess_Inheritance;
			/* 00 or 01 */
			unsigned int Sess_Type;
			/* 00 OS/2 session manager determines type */
			/* 01 OS/2 full-screen */
			/* 02 OS/2 window */
			/* 03 PM */
			/* 04 VDM full-screen */
			/* 07 VDM window */
			char far *Sess_Icon_Filename;
			/* max 128 chars or 0000:0000 */
			unsigned long Sess_Pgm_Handle;
			/* reserved, must be 00000000 */
			unsigned int Sess_Pgm_Control;
			unsigned int Sess_Column;
			unsigned int Sess_Row;
			unsigned int Sess_Width;
			unsigned int Sess_Height;
			unsigned int Sess_Reserved; /* 0x00 */
			unsigned long Sess_Object_Buffer;
			/* reserved, must be 00000000 */
			unsigned long Sess_Object_BufferLen;
			/* reserved, must be 00000000 */
		} Session_Data;

Returns:  If Session_Data is set incorrectly decimal 418 is returned.

-----------------------------------------------------------------------
Dos32CreateEventSem     [DOS, Windows]

Function: Creates an event semaphore.

Syntax:   include "dosapi.h"
		unsigned int Dos32CreateEventSem( char far *SemName,
			unsigned long far *SemHandle,
			unsigned long SemFlags, unsigned char SemState);

Remarks:  Creates an event semaphore with the name SemName.
		The semaphore name must start with the prefix "\SEM32\".
		The parameter SemHandle is a pointer to the handle of the
		semaphore.  Refer to the OS/2 documentation regarding the
		meaning of the SemFlags and SemState parameters or use
		zero as a default for most uses.

Returns:  If an invalid parameter is passed decimal 87 is returned.
		If an invalid name is passed decimal 123 is returned.
		If a duplicate name is passed 285 is returned.

-----------------------------------------------------------------------
Dos32OpenEventSem       [ DOS, Windows]

Function: Opens an event semaphore.

Syntax:   include "dosapi.h"
		unsigned int Dos32OpenEventSem( char far *SemName,
			unsigned long far *SemHandle);

Remarks:  Opens an event semaphore with the name SemName.
		The semaphore name must start with the prefix "\SEM32\".
		The parameter SemHandle is a pointer to the handle of the
		semaphore.

Returns:  If an invalid parameter is passed decimal 87 is returned.
		If an invalid name is passed decimal 123 is returned.
		If a duplicate name is passed decimal 285 is returned.
		If the semaphore is not found decimal 187 is returned.

-----------------------------------------------------------------------
Dos32CloseEventSem      [ DOS, Windows]

Function: Closes an event semaphore.

Syntax:   include "dosapi.h"
		unsigned int Dos32CloseEventSem( unsigned long
			SemHandle);

Remarks:  Closes an event semaphore with the handle SemHandle.

Returns:  If an invalid handle is passed decimal 6 is returned.
		If the semaphore is busy decimal 301 is returned.

-----------------------------------------------------------------------
Dos32PostEventSem       [ DOS, Windows]

Function: Posts an event semaphore.

Syntax:   include "dosapi.h"
		unsigned int Dos32PostEventSem( unsigned long SemHandle);

Remarks:  Posts an event semaphore with the handle SemHandle.

Returns:  If an invalid handle is passed decimal 6 is returned.
		If too many posts to this semaphore decimal 298 is returned.
		If the semaphore is already posted 299 is returned

-----------------------------------------------------------------------
Dos32ResetEventSem      [ DOS, Windows]

Function: Resets an event semaphore.

Syntax:   include "dosapi.h"
		unsigned int Dos32ResetEventSem( unsigned long
			SemHandle, unsigned int far *SemPostCount);

Remarks:  Posts an event semaphore with the handle SemHandle. The
		number of times the semaphore was posted since the last reset
		is pointed to by SemPostCount.

Returns:  If an invalid handle is passed decimal 6 is returned.
		If the semaphore is already reset decimal 300 is returned

-----------------------------------------------------------------------
Dos32QueryEventSem     [ DOS, Windows]

Function: Queries an event semaphore for the post count.

Syntax:   include "dosapi.h"
		unsigned int Dos32QueryEventSem( unsigned long
			SemHandle, unsigned int far *SemPostCount);

Remarks:  Queries an event semaphore with the handle SemHandle. The
		number of times the semaphore was posted since the last reset
		is pointed to by SemPostCount.

Returns:  If an invalid handle is passed decimal 6 is returned.
		If an invalid parameter is passed decimal 87 is returned.

-----------------------------------------------------------------------
Dos32WaitEventSem       [ DOS, Windows]

Function: Waits for an event semaphore to be posted.

Syntax:   include "dosapi.h"
		unsigned int Dos32WaitEventSem( unsigned long SemHandle,
			unsigned char SemWaitSec);

Remarks:  Waits for an event semaphore with the handle SemHandle to
		be posted.. The number of seconds to wait is determined the
		SemWaitSec parameter.

Returns:  If an invalid handle is passed decimal 6 is returned.
		If the semaphore wait period times out decimal 640 is returned.

Coming Soon!
Enhancements to the product are already underway!  New features for the next release are:

	Local Data Area Support - In addition to a global data area, a local
		data area will be included.  This area is visible only to programs
		running in the current session.  Useful for passing data between
		programs in batch or command files, etc.

	Dos/Windows Access to OS/2 API's - By expanding the functionality
		of the GDA virtual device driver, API's currently only accessible
		in OS/2 sessions may be called by Dos/Windows sessions.

	Popup Messages - Background programs can send popup messages
		regardless of the GUI of the foreground process.




