home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dos2os2.zip / GDA.TXT < prev    next >
Text File  |  1995-02-19  |  18KB  |  443 lines
  1. GLOBAL DATA AREA & DOS2OS2 API
  2. by Karly Court Software
  3.  
  4. Contents
  5. License Agreement....................1
  6. Introduction.........................2
  7. Installation and Sample Files........2
  8. Global Data Area Description.........3
  9. GDA Virtual Device Driver............3
  10. Global Data Area Functions...........3
  11.     Send Data to GDA................3
  12.     Receive Data from GDA...........3
  13.     Update Data in GDA..............4
  14.     Read Data From GDA..............4
  15.     Reset Update/Read Semaphores....5
  16.     Dos Sleep.......................5
  17. Dos API Description..................6
  18. Dos API Functions....................6
  19.     Start OS2/DOS/WIN Session.......6
  20.     Create Event Semaphore..........7
  21.     Open Event Semaphore............7
  22.     Close Event Semaphore...........8
  23.     Post Event Semaphore............8
  24.     Reset Event Semaphore...........8
  25.     Query Event Semaphore...........9
  26.     Wait Event Semaphore............9
  27. Coming Soon!.........................9
  28.  
  29. License Agreement
  30. You may use the software contained in this package for evaluation purposes
  31. free of charge.  However, if you use the software libraries for commercial or
  32. in-house development you must register the software with Karly Court
  33. Software.  Registering the software entitles you to install the device driver
  34. on an unlimited number of systems in your company.  You may also modify
  35. the source code with no restrictions.  Karly Court Software is not responsible
  36. for any damages resulting from the use of this product.  The price of the
  37. product is $59.00 US.  This product is offered to help Dos and Windows
  38. developers migrate their systems to the OS/2 platform and the registration
  39. fee is requested to help offset costs incurred in its development.  When you
  40. register, you will receive the latest version of the software, printed documen-
  41. tation, and all source code.
  42.  
  43. Introduction
  44. One of the benefits of OS/2 is the ability to not only run true 32-bit programs
  45. in a multithreaded environment, but to also run older 16-bit DOS and
  46. Windows programs.  This is quite an accomplishment given the fact that DOS
  47. was not designed as a multitasking environment and that Windows is a
  48. "cooperative" rather than pre-emptive multitasker.  Being able to operate
  49. programs from three different platforms at the same time is great, but one
  50. shortcoming of OS/2 is the lack of interprocess facilities for the DOS and
  51. Windows environment.  IBM's direction is for DOS programs to use named
  52. pipes, but that requires an OS/2 program to initially create the pipe.
  53. Windows and OS/2 programs can communicate using DDE and other
  54. clipboard related functions but at considerable overhead.  This is where the
  55. Global Data Area and Dos API functions help.  They allow DOS, Windows,
  56. and OS/2 programs to read and write to a small 1K data area that is common
  57. to all programs.  Often a programmer may only want to set a flag that other
  58. sessions can check or to pass messages between a group of programs.  By
  59. using a very small virtual device driver and a set of "undocumented" DOS
  60. interrupt calls this can now be done.
  61.  
  62. Installation and Sample Files
  63. To install the files on your system perform these steps.
  64. Create a directory DOS2OS2.
  65.     md DOS2OS2
  66.  
  67. Copy this file to the DOS2OS2 directory where sdrive is the source drive
  68. and ddrive is the destination drive that contains the DOS2OS2 directory.
  69.     copy sdrive:\DOS2OS2.ZIP ddrive:\DOS2OS2\DOS2OS2.ZIP
  70.  
  71. Unzip this file in the DOS2OS2 directory.
  72.     cd DOS2OS2
  73.     pkunzip -do DOS2OS2.ZIP
  74.  
  75. Add the following line to the end of your OS/2 config.sys file 
  76. where drive is the drive letter that the files were installed.
  77.     device=drive:\DOS2OS2\VDOSAPI.SYS
  78.  
  79. Your are now ready to use the GDA functions!
  80.  
  81. Included in this package are the following samples file:
  82.     VDOSAPI.SYS GDA Virtual Device Driver
  83.     TESTAPIL.EXE    Dos large model test program
  84.     TESTAPIS.EXE    Dos small model test program
  85.     TESTOS2.EXE OS/2 character mode test program
  86.     WINAPI.EXE      Windows menu driven test program
  87.     DOSAPI.H        Header file for Dos/Windows libraries
  88.     DOSAPI_L.LIB    Dos large model library
  89.     DOSAPI_S.LIB    Dos small model library
  90.     OS2API.H        Header file for OS/2 library
  91.     OS2API.LIB      OS/2 library
  92.  
  93. Registered users of this package will receive source code to the device
  94. driver, source code to the libraries and test programs, and a stub program
  95. with documentation that allows OS/2 programs to execute in a VDM.
  96.  
  97. Global Data Area Description
  98. As mentioned, named pipes are recommended by IBM for interprocess
  99. communications between Dos applications and OS/2.  Named pipes can only
  100. be created at this time by an OS/2 program.  Also, a named pipe can only be
  101. used between one set of programs at a time.  Named pipes are not
  102. persistent; when the pipe is closed the data is gone.  By using a permanent
  103. 1K global data area that all platforms can access these limitations are
  104. overcomed.  This data area is controlled by a virtual device driver using the
  105. following functions:
  106.  
  107. Global Data Area Functions
  108.  
  109. -----------------------------------------------------------------------
  110. DosApi_Send         [OS/2, DOS, Windows]
  111.  
  112. Function:   Sets GDA to a range of bytes starting at a given offset.
  113.  
  114. Syntax:   include "dosapi.h"
  115.         unsigned int DosApi_Send(char far *pBuffer,
  116.             short ByteRange, short BuffOffSet);
  117.  
  118. Remarks:  DosApi_Send copies the range of bytes pointed to by
  119.         pBuffer for ByteRange number of bytes starting at the GDA
  120.         offset BuffOffSet.
  121.  
  122. Returns:  If the sum of ByteRange and BuffOffSet exceed the length
  123.         of the GDA (1024 bytes) decimal 11 is returned.
  124.         If the VDOSAPI driver is not loaded decimal 127 is returned.
  125.  
  126. -----------------------------------------------------------------------
  127. DosApi_Recv         [OS/2, DOS, Windows]
  128.  
  129. Function: Returns a range of bytes from the GDA starting at a given
  130.         offset.
  131.  
  132. Syntax:   include "dosapi.h"
  133.         unsigned int DosApi_Recv(char far *pBuffer,
  134.             short ByteRange, short BuffOffSet);
  135.  
  136. Remarks:  DosApi_Recv copies from the GDA ByteRange number of
  137.         bytes starting at the offset BuffOffSet to the address pointed
  138.         to by pBuffer.
  139.  
  140. Returns:  If the sum of ByteRange and BuffOffSet exceed the length
  141.         of the GDA (1024 bytes) decimal 11 is returned.
  142.         If the VDOSAPI driver is not loaded decimal 127 is returned.
  143.  
  144. -----------------------------------------------------------------------
  145. DosApi_Update          [OS/2, DOS, Windows]
  146.  
  147. Function: Sets GDA to a range of bytes starting at a given offset if
  148.         the update semaphore is posted.
  149.  
  150. Syntax:   include "dosapi.h"
  151.         unsigned int DosApi_Update(char far *pBuffer,
  152.             short ByteRange, short BuffOffSet);
  153.  
  154. Remarks:  DosApi_Update copies the range of bytes pointed to by
  155.         pBuffer for ByteRange number of bytes starting at the GDA
  156.         offset BuffOffSet.  This function is identical to the
  157.         DosApi_Send function with one difference: No data is
  158.         copied if the update semaphore is set.  The DosApi_Read
  159.         function posts the update semaphore to allow the GDA to be
  160.         updated again.  This function teamed with the DosApi_Read
  161.         function is designed for serialized transfer of large amounts
  162.         of data similar to a named pipe without the overhead. One
  163.         process updates the GDA while another reads it.  The
  164.         update and read semaphores prevent two successive
  165.         updates without a read and vice versa.
  166.         The DosApi_Send and DosApi_Recv functions have no
  167.         effect on the semaphores used by these functions and may
  168.         be used as desired.
  169.  
  170. Returns:  If the sum of ByteRange and BuffOffSet exceed the length
  171.         of the GDA (1024 bytes) decimal 11 is returned.
  172.         If the no DosApi_Read or DosApi_Reset has occurred since
  173.         the last DosApi_Update call decimal 12 is returned.
  174.         If the VDOSAPI driver is not loaded decimal 127 is returned.
  175.  
  176. -----------------------------------------------------------------------
  177. DosApi_Read         [OS/2, DOS, Windows]
  178.  
  179. Function: Returns a range of bytes from the GDA starting at a given
  180.         offset if the read semaphore is posted..
  181.  
  182. Syntax:   include "dosapi.h"
  183.         unsigned int DosApi_Read(char far *pBuffer,
  184.             short ByteRange, short BuffOffSet);
  185.  
  186. Remarks:  DosApi_Read copies from the GDA ByteRange number of
  187.         bytes starting at the offset BuffOffSet to the address pointed
  188.         to by pBuffer.  This function is identical to the
  189.         DosApi_Recv function with one difference: No data is
  190.         copied if the read semaphore is set.  The DosApi_Update
  191.         function posts the update semaphore to allow the GDA to be
  192.         read again.  Refer to the DosApi_Update Remarks: for
  193.         more details.
  194.  
  195. Returns:  If the sum of ByteRange and BuffOffSet exceed the length
  196.         If the no DosApi_Update or DosApi_Reset has occurred
  197.         since the last DosApi_Update call decimal 13 is returned.
  198.         of the GDA (1024 bytes) decimal 11 is returned.
  199.         If the VDOSAPI driver is not loaded decimal 127 is returned.
  200.  
  201. -----------------------------------------------------------------------
  202. DosApi_Reset            [OS/2, DOS, Windows]
  203.  
  204. Function: Resets the update and read semaphores prior to a
  205.         serialized transfer using the DosApi_Update and
  206.         DosApi_Read functions.
  207.  
  208. Syntax:   include "dosapi.h"
  209.         unsigned int DosApi_Reset( void);
  210.  
  211. Remarks:  Prior to transferring data between processes using the
  212.         DosApi_Update and DosApi_Read combination, call
  213.         the DosApi_Reset function to insure a valid initial
  214.         semaphore state.
  215.  
  216. Returns:  If the VDOSAPI driver is not loaded decimal 127 is returned.
  217.  
  218. -----------------------------------------------------------------------
  219. DosAPI_Sleep            [DOS, Windows]
  220.  
  221. Function: Yields the VDM session for a specified length of time
  222.  
  223. Syntax:   include "dosapi.h"
  224.         unsigned int DosApi_Sleep( short SleepHths );
  225.  
  226. Remarks:  DosAPI_Sleep surrenders the current VDM session for the
  227.         length of time specified by SleepHths.  This period of time
  228.         is in hundredths of a second.  This function is useful when
  229.         using the update and read functions in a VDM to prevent
  230.         "burning up a loop" while checking for the update or read
  231.         semaphore to be posted.  OS/2 has its own DosSleep
  232.         function and it should be used instead of this one.  Also, VDM
  233.         processing is blocked during the sleep period.  For this
  234.         reason, it is better to use Windows timers to emulate this
  235.         function or the Yield() function.  Using the DosAPI_Sleep
  236.         function in Windows would block ALL applications in a full
  237.         screen session.  Another alternative in a VDM session is to
  238.         call interrupt 0x2F function 0x1680 (Dos idle function).
  239.  
  240.  
  241. Returns:  Always returns zero.
  242.  
  243. Dos API Description
  244. Another technique that can be used to implement interprocess
  245. communication is the use of semaphores.  Although not as powerful as the
  246. GDA routines, semaphores can be used when simple coordination between
  247. tasks is required.  The semaphore routines included with this package are
  248. event semaphores which are the most common.  Also included in this
  249. package are routines to start other OS/2, DOS, or Windows sessions from
  250. within a VDM.
  251.  
  252. Dos API Functions
  253.  
  254. -----------------------------------------------------------------------
  255. DosStartSession         [DOS, Windows]
  256.  
  257. Function: Starts a new OS/2, DOS, or Windows session.
  258.  
  259. Syntax:   include "dosapi.h"
  260.         unsigned int DosStartSession( Session_Data far *SessData );
  261.  
  262. Remarks:  Following are the parameters of the SessData structure:
  263.         typedef struct {
  264.             unsigned int Sess_Struct_Len; 
  265.             /* Must be 0x18,0x1E,0x20,0x32, or 0x3C */
  266.             unsigned int Sess_Relation;
  267.             /* 00 independent, 01 child */
  268.             unsigned int Sess_Fore_Back;
  269.             /* 00 foreground, 01 background */
  270.             unsigned int Sess_Trace;
  271.             /* 00-02, 00 = no trace */
  272.             char far *Sess_Program_Title;
  273.             /* max 62 chars or 0000:0000 */
  274.             char far *Sess_Program_Name;
  275.             /* max 128 chars or 0000:0000 */
  276.             char far *Sess_Program_Args;
  277.             /* max 144 chars or 0000:0000 */
  278.             unsigned long Sess_Term_Queue;
  279.             /* reserved, must be 00000000 */
  280.             char far *Sess_Environment;
  281.             /* max 486 bytes or 0000:0000 */
  282.             unsigned int Sess_Inheritance;
  283.             /* 00 or 01 */
  284.             unsigned int Sess_Type;
  285.             /* 00 OS/2 session manager determines type */
  286.             /* 01 OS/2 full-screen */
  287.             /* 02 OS/2 window */
  288.             /* 03 PM */
  289.             /* 04 VDM full-screen */
  290.             /* 07 VDM window */
  291.             char far *Sess_Icon_Filename;
  292.             /* max 128 chars or 0000:0000 */
  293.             unsigned long Sess_Pgm_Handle;
  294.             /* reserved, must be 00000000 */
  295.             unsigned int Sess_Pgm_Control;
  296.             unsigned int Sess_Column;
  297.             unsigned int Sess_Row;
  298.             unsigned int Sess_Width;
  299.             unsigned int Sess_Height;
  300.             unsigned int Sess_Reserved; /* 0x00 */
  301.             unsigned long Sess_Object_Buffer;
  302.             /* reserved, must be 00000000 */
  303.             unsigned long Sess_Object_BufferLen;
  304.             /* reserved, must be 00000000 */
  305.         } Session_Data;
  306.  
  307. Returns:  If Session_Data is set incorrectly decimal 418 is returned.
  308.  
  309. -----------------------------------------------------------------------
  310. Dos32CreateEventSem     [DOS, Windows]
  311.  
  312. Function: Creates an event semaphore.
  313.  
  314. Syntax:   include "dosapi.h"
  315.         unsigned int Dos32CreateEventSem( char far *SemName,
  316.             unsigned long far *SemHandle,
  317.             unsigned long SemFlags, unsigned char SemState);
  318.  
  319. Remarks:  Creates an event semaphore with the name SemName.
  320.         The semaphore name must start with the prefix "\SEM32\".
  321.         The parameter SemHandle is a pointer to the handle of the
  322.         semaphore.  Refer to the OS/2 documentation regarding the
  323.         meaning of the SemFlags and SemState parameters or use
  324.         zero as a default for most uses.
  325.  
  326. Returns:  If an invalid parameter is passed decimal 87 is returned.
  327.         If an invalid name is passed decimal 123 is returned.
  328.         If a duplicate name is passed 285 is returned.
  329.  
  330. -----------------------------------------------------------------------
  331. Dos32OpenEventSem       [ DOS, Windows]
  332.  
  333. Function: Opens an event semaphore.
  334.  
  335. Syntax:   include "dosapi.h"
  336.         unsigned int Dos32OpenEventSem( char far *SemName,
  337.             unsigned long far *SemHandle);
  338.  
  339. Remarks:  Opens an event semaphore with the name SemName.
  340.         The semaphore name must start with the prefix "\SEM32\".
  341.         The parameter SemHandle is a pointer to the handle of the
  342.         semaphore.
  343.  
  344. Returns:  If an invalid parameter is passed decimal 87 is returned.
  345.         If an invalid name is passed decimal 123 is returned.
  346.         If a duplicate name is passed decimal 285 is returned.
  347.         If the semaphore is not found decimal 187 is returned.
  348.  
  349. -----------------------------------------------------------------------
  350. Dos32CloseEventSem      [ DOS, Windows]
  351.  
  352. Function: Closes an event semaphore.
  353.  
  354. Syntax:   include "dosapi.h"
  355.         unsigned int Dos32CloseEventSem( unsigned long
  356.             SemHandle);
  357.  
  358. Remarks:  Closes an event semaphore with the handle SemHandle.
  359.  
  360. Returns:  If an invalid handle is passed decimal 6 is returned.
  361.         If the semaphore is busy decimal 301 is returned.
  362.  
  363. -----------------------------------------------------------------------
  364. Dos32PostEventSem       [ DOS, Windows]
  365.  
  366. Function: Posts an event semaphore.
  367.  
  368. Syntax:   include "dosapi.h"
  369.         unsigned int Dos32PostEventSem( unsigned long SemHandle);
  370.  
  371. Remarks:  Posts an event semaphore with the handle SemHandle.
  372.  
  373. Returns:  If an invalid handle is passed decimal 6 is returned.
  374.         If too many posts to this semaphore decimal 298 is returned.
  375.         If the semaphore is already posted 299 is returned
  376.  
  377. -----------------------------------------------------------------------
  378. Dos32ResetEventSem      [ DOS, Windows]
  379.  
  380. Function: Resets an event semaphore.
  381.  
  382. Syntax:   include "dosapi.h"
  383.         unsigned int Dos32ResetEventSem( unsigned long
  384.             SemHandle, unsigned int far *SemPostCount);
  385.  
  386. Remarks:  Posts an event semaphore with the handle SemHandle. The
  387.         number of times the semaphore was posted since the last reset
  388.         is pointed to by SemPostCount.
  389.  
  390. Returns:  If an invalid handle is passed decimal 6 is returned.
  391.         If the semaphore is already reset decimal 300 is returned
  392.  
  393. -----------------------------------------------------------------------
  394. Dos32QueryEventSem     [ DOS, Windows]
  395.  
  396. Function: Queries an event semaphore for the post count.
  397.  
  398. Syntax:   include "dosapi.h"
  399.         unsigned int Dos32QueryEventSem( unsigned long
  400.             SemHandle, unsigned int far *SemPostCount);
  401.  
  402. Remarks:  Queries an event semaphore with the handle SemHandle. The
  403.         number of times the semaphore was posted since the last reset
  404.         is pointed to by SemPostCount.
  405.  
  406. Returns:  If an invalid handle is passed decimal 6 is returned.
  407.         If an invalid parameter is passed decimal 87 is returned.
  408.  
  409. -----------------------------------------------------------------------
  410. Dos32WaitEventSem       [ DOS, Windows]
  411.  
  412. Function: Waits for an event semaphore to be posted.
  413.  
  414. Syntax:   include "dosapi.h"
  415.         unsigned int Dos32WaitEventSem( unsigned long SemHandle,
  416.             unsigned char SemWaitSec);
  417.  
  418. Remarks:  Waits for an event semaphore with the handle SemHandle to
  419.         be posted.. The number of seconds to wait is determined the
  420.         SemWaitSec parameter.
  421.  
  422. Returns:  If an invalid handle is passed decimal 6 is returned.
  423.         If the semaphore wait period times out decimal 640 is returned.
  424.  
  425. Coming Soon!
  426. Enhancements to the product are already underway!  New features for the next release are:
  427.  
  428.     Local Data Area Support - In addition to a global data area, a local
  429.         data area will be included.  This area is visible only to programs
  430.         running in the current session.  Useful for passing data between
  431.         programs in batch or command files, etc.
  432.  
  433.     Dos/Windows Access to OS/2 API's - By expanding the functionality
  434.         of the GDA virtual device driver, API's currently only accessible
  435.         in OS/2 sessions may be called by Dos/Windows sessions.
  436.  
  437.     Popup Messages - Background programs can send popup messages
  438.         regardless of the GUI of the foreground process.
  439.  
  440.  
  441.  
  442.  
  443.