home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
dos2os2.zip
/
GDA.TXT
< prev
next >
Wrap
Text File
|
1995-02-19
|
18KB
|
443 lines
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.