home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / MISC / OS2 / OS2YOU20.ZIP / SPECS.DOC < prev    next >
Encoding:
Text File  |  1991-02-21  |  6.1 KB  |  141 lines
  1. Specifications for communications with Os2You via pipes.
  2. ========================================================
  3.  
  4.  
  5. The pipe format
  6. ===============
  7. Os2You creates a named pipe with unlimited pipe instances possible.
  8. The pipe is a full duplex message pipe with no write behind allowed.
  9. Os2You tries to allocate a 16 Kbyte output buffer and 1 Kbyte input
  10. buffer, but will work with any buffer size actually supplied by the
  11. API.
  12.  
  13. If the pipe is broken by Os2You, this will mean that Os2You has ended
  14. the conversion with the terminal program.
  15.  
  16. If the pipe is broken by the terminal program during a conversion,
  17. Os2You will treat this as a carrier loss, and try to end the running
  18. program, and the current remote session.
  19.  
  20.  
  21.  
  22.  
  23. Reading the pipe
  24. ================
  25. A terminal program wishing to communicate with Os2You via pipes should
  26. preferable open the pipe in blocking mode and in message read mode.  Note
  27. that when coding for a single tasking environment (like DOS), it might be
  28. necessary to use non blocking mode, as you have to serve writing, even if
  29. you don't get anything reading the pipe.  It is possible to put the Os2You
  30. program in "Anti blocking mode", which means that Os2You will send "empty"
  31. messages (=Flag set to 0) to prevent blocking when reading the pipe.  This
  32. is done by sending first Esc and then zero (1Bh, 00h).  A message will
  33. have the following structure:
  34.  
  35.   RECORD
  36.     Flag     : CHAR;                        (* One byte character *)
  37.     CurRow   : CARDINAL;                    (* Two byte unsigned integer *)
  38.     CurCol   : CARDINAL;                    (* Two byte unsigned integer *)
  39.     Length   : CARDINAL;                    (* Two byte unsigned integer *)
  40.     Reserved : ARRAY [1..30000] OF CHAR;    (* 30000 byte character buffer *)
  41.   END;
  42.  
  43. The message is of variable size.  When a message is received, the Flag
  44. character will reflect the type of message received.
  45.  
  46. If <Flag> is set to 00H this indicates the session begins.  No special
  47. action is required of the terminal program, but it might send a Esc-b
  48. sequence to set Os2You to binary screen mode.
  49.  
  50. If <Flag> is set to 01H this indicates a cursor position command.  The
  51. <CurRow> and <CurCol> parameters will contain the cursor positions the
  52. terminal program should set.  If the <Length> value is non-zero a new
  53. message will follow immidiatly, containing a direct image of the video
  54. buffer.  The whole message (or as much of it that is allowed by the
  55. terminal programs screen size), should be placed in the logical video
  56. buffer, and be displayed.  Note, that if <CurRow> and <CurCol> both
  57. are set to 65535 (all bits set), this means that the Os2You session
  58. is ending.
  59.  
  60. If <Flag> is set to any other value than 00H or 01H, the whole message
  61. will contain text that should be displayed at the screen with a ordinary
  62. write command.  It might contain ANSI-sequences, so your terminal program
  63. should set the ANSI-mode on.
  64.  
  65. If the terminal can't read the pipe in message mode, it is still
  66. possible to get all functionality using ordinary byte stream mode,
  67. although this will require more coding.  It is recommended to use
  68. non blocking mode when writing DOS-applications as DOS is not re-
  69. entrant and you can't write to the pipe, while the program is blocked
  70. in a read operation.  The program should behave in the following manner:
  71.  
  72. Read a block of any size from the pipe.  Scan and retain the position
  73. for the first occurance of a 00H byte in the block.  Scan and retain
  74. the position for the first occurance of a 01H byte in the block.
  75.  
  76. Write the characters before the first occurance of 00H or 01H byte to
  77. screen, using ordinary write-commands.
  78.  
  79. If the position for the 00H byte is less than the position for 01H
  80. byte, a <Flag> of 00H is assumed, and proper action is taken.
  81.  
  82. If the position for the 01H byte is less than 00H byte a <Flag> of 01H is
  83. assumed.  Assure that you have at least six characters following the
  84. <Flag> byte, and map them to the message block showed above.  Set the
  85. cursor position according to this.  If the <Length> value is set in
  86. this block, you should read <Length> bytes further (including any
  87. previous read bytes not used yet), and move these bytes directly to
  88. video memory.
  89.  
  90. Any trailing characters not yet used by previous decoding, should be
  91. rescanned and decoded again, until there are no 00H or 01H bytes in
  92. the remaining block.  This remaining block should then be displayed
  93. using ordinary write commands.
  94.  
  95. Note, that OS/2 1.2 and Lan Server 1.2 didn't work correctly sometimes
  96. when reading large messages from a remote pipe.  Therefore you should
  97. limit your pipe reads to maximum 4 kByte reads, and merge the next
  98. read with the current if you get the ERRROR_MORE_DATA error.
  99.  
  100.  
  101.  
  102.  
  103.  
  104. Writing to the pipe
  105. ===================
  106. To send characters to Os2You, the terminal program should send messages of
  107. the length one byte, containing the ASCII-code of the character sent to
  108. Os2You.  It is important that no messages longer than 1 byte are sent to
  109. over the pipe, as Os2You will just ignore the remaining part of the message
  110. or treat it as an invalid client, and end the conversion.  The same Esc-
  111. sequences as described in the documentations are used when using pipes.
  112.  
  113.  
  114.  
  115.  
  116. Examples
  117. ========
  118. Here is an example on how the read pipe (message mode) thread looks like
  119. in Lanterm2.Mod:
  120.  
  121. LOOP
  122.   BytesRead := PipeRead();         (* Read Pipe and place result in Buffer *)
  123.   CASE Buffer.Flag OF
  124.     | CHR(0) : TempCh := CHR(27);
  125.                IF Dos.Write(Handle,ADR(TempCh),1,BytesWritten) = 0 THEN END;
  126.                TempCh := 'b';
  127.                IF Dos.Write(Handle,ADR(TempCh),1,BytesWritten) = 0 THEN END;
  128.     | CHR(1) : IF Vio.SetCurPos(Buffer.CurRow,Buffer.CurCol,0) = 0 THEN END;
  129.                IF Buffer.Length <> 0 THEN
  130.                  BytesRead := PipeRead();
  131.                  IF BytesRead > ScrLen THEN
  132.                    Lib.WordMove(ADR(Buffer),LVBPtr,ScrLen DIV 2);
  133.                  ELSE
  134.                    Lib.WordMove(ADR(Buffer),LVBPtr,BytesRead DIV 2);
  135.                  END;
  136.                  IF Vio.ShowBuf(0,ScrLen,0) = 0 THEN END;
  137.                END;
  138.       ELSE     IF Vio.WrtTTY(ADR(Buffer),BytesRead,0) = 0 THEN END;
  139.   END;
  140. END;
  141.