home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0010 - 0019 / ibm0010-0019 / ibm0010.tar / ibm0010 / CDOSDSK6.ZIP / CDOSDSK6.TD0 / QUELIB / QUELIB.DOC < prev    next >
Encoding:
Text File  |  1989-01-16  |  10.5 KB  |  322 lines
  1.                      Queue Library Documentation
  2.  
  3.                              Version 1.0
  4.  
  5.                              9 July 1986
  6.  
  7.  
  8. SECTION 1 - OVERVIEW
  9. This   document   describes  the  queue  libraries   QUELIBS.LIB   and 
  10. QUELIBL.LIB  provided  by  DR  for use interfacing  the  Lattice,  and 
  11. compatible,  C  compilers to the versatile queue system of  Concurrent 
  12. DOS and Networked DOS Plus.  
  13.  
  14.  
  15. 1.1 Models Supported
  16. QUELIBS.LIB  provides  for small model support whilst  QUELIBL.LIB  is 
  17. available for programers using the large model.  
  18.  
  19.  
  20. 1.2 Use & Restrictions
  21. No charge  is made  for  the  library  and  no royalties  are  due  on
  22. distribution.
  23.  
  24.  
  25. 1.3 Warranty
  26. No warranty is offered or implied.  Any problems encountered using the
  27. library  should be reported  to your local Digital Research  Technical
  28. Support Centre. Persons reporting problems will be offered updates, if
  29. available.
  30.  
  31.  
  32. SECTION 2 - TECHNICAL DETAILS
  33.  
  34.  
  35. 2.1 Queue Restrictions 
  36. The  following  restrictions  (in  addition to those  imposed  by  the 
  37. operating system) are applicable.
  38.  
  39.  
  40. 2.1.1 No. Queues
  41. A maximum of 16 queues may be open at any one time.  
  42.  
  43.  
  44. 2.1.2 Queue Message Length
  45. No  single  message may exceed 256 bytes in length.   Messages  larger 
  46. than  this should be broken up and sent in  smaller  portions.   
  47.  
  48.  
  49. 2.1.3 Queue Message No
  50. The maximum message depth (or no of messages) is 256.  Note that using 
  51. a large depth of queue may exhaust queue buffer space in the system.
  52.  
  53.  
  54. 2.2 Queue Interface
  55. A  header  file,  QUEBIND.H,  is provided for use with the  Lattice  C 
  56. compiler version 3.00 and later.  To use this header file with earlier 
  57. versions  of this compiler,  or with compatible compilers without  the 
  58. argument type checking facility,  remove the argument type lists  from 
  59. the function declarations. 
  60.  
  61. The following set of functions are provided in the queue library:
  62.  
  63.  
  64. Make Queue
  65.  
  66.      (int) error = q_make(name,size,depth)
  67.  
  68.      name      asciiz terminated name string
  69.                all 8 bits are significant
  70.                names starting with MX have special funtion
  71.                The name is a maximum of 8 characters, names with
  72.                more than 8 characters will be truncated, whilst
  73.                names with less than 8 characters will be space
  74.                padded to 8.
  75.  
  76.      size      integer specified size in bytes
  77.  
  78.      depth     integer specified depth in bytes
  79.  
  80.      error      0   indicates successful operation
  81.                -1   indicates system error creating queue
  82.  
  83. The  specified  queue is created in system data area  (SYSDAT).   Note 
  84. that It must be opened before data can be read/written to it.
  85.  
  86. Error  codes  are  returned if there are already sixteen  queues  open 
  87. (Error 7 - No unused queue descriptors), if there is not enough buffer 
  88. space  (Error 8 - No free queue buffer),  or there is already a  queue 
  89. with that name (Error 10 - Queue already in use).
  90.  
  91.  
  92. Open Queue
  93.  
  94.      (int) qid = q_open(name)
  95.  
  96.      name      asciiz terminated name string
  97.                all 8 bits are significant
  98.                names starting with MX have special funtion  
  99.                The name is a maximum of 8 characters, names with
  100.                more than 8 characters will be truncated, whilst
  101.                names with less than 8 characters will be space
  102.                padded to 8.
  103.  
  104.      qid       number in range 0-15 used to reference 
  105.                the specified queue (i.e. the queue handle).
  106.  
  107.                -1   indicates system error opening queue
  108.                
  109.  
  110. All queues must be explicitly opened before a read,  write,  or delete 
  111. operation can be done.
  112.  
  113. An error will result if the queue has not previously been made  (Error 
  114. 9 - Cannot find queue).
  115.  
  116.  
  117.  
  118. Read Queue (Unconditional)
  119.      
  120.      (int) ret = q_read(qid,str)
  121.  
  122.      qid       handle of queue to be read from
  123.  
  124.      str       character array to receive one message
  125.  
  126.      ret        0   indicates success
  127.                -1   indicates system error reading from queue
  128.  
  129. The  q_read function will read a message from a system queue that  has 
  130. previously been opened.  If there are not enough messages to read from 
  131. the  queue,  the  process waits until another process writes into  the 
  132. queue before returning.
  133.  
  134. Errors  are returned for a queue not having previously been opened  or 
  135. having been deleted (Error 9 - Cannot find queue).
  136.  
  137.  
  138. Read Queue (conditional)
  139.      
  140.      (int) ret = q_cread(qid,str)
  141.  
  142.      id        handle of queue to be read from
  143.  
  144.      str       character array to receive one message
  145.  
  146.      ret        0   indicates success
  147.                 1   indicates no message
  148.                -1   indicates system error reading from queue
  149.  
  150. The  q_cread function will read a message from a system queue that has 
  151. previously been opened. If there are no more messages to read from the 
  152. queue,  an  error  code is returned instead of waiting  until  another 
  153. process writes into the queue.
  154.  
  155. Errors  are returned for a queue not having previously been opened  or 
  156. having  been  deleted (Error 9 - Cannot find queue),  or for  no  more 
  157. messages in the queue (Main error 1, extended error 14 - Empty queue).
  158.  
  159.  
  160.  
  161. Write Queue (unconditional)
  162.  
  163.      
  164.      (int) ret = q_write(qid,str)
  165.  
  166.      qid       handle of queue to be writen to
  167.  
  168.      str       character array to send 
  169.  
  170.      ret        0   indicates success
  171.                -1   indicates system error writing to the queue
  172.  
  173. The  q_write function will write a message to a system queue that  has 
  174. previously been opened. If there is no more message space, the process 
  175. waits until another process reads from the queue before returning.
  176.  
  177. Errors  are returned for a queue not having previously been opened  or 
  178. having been deleted (Error 9 - Cannot find queue).
  179.  
  180.  
  181. Write Queue (conditional)
  182.      
  183.      (int) ret = q_cwrite(qid,str)
  184.  
  185.      qid       handle of queue to be written to 
  186.  
  187.      str       character array to send 
  188.  
  189.      ret        0   indicates success
  190.                 1   indicates no queue space 
  191.                -1   indicates system error writing to the queue
  192.  
  193. The q_cwrite function will write a message to a system queue that  has 
  194. previously  been opened.  If there is no more message space,  an error 
  195. code is returned immediately instead of waiting until another  process 
  196. reads from the queue.
  197.  
  198. Errors  are returned for a queue not having previously been opened  or 
  199. having  been  deleted (Error 9 - Cannot find queue),  or for  no  more 
  200. queue space (Main error code 1, extended error code 15 - Full queue).
  201.  
  202.  
  203.  
  204. Delete Queue
  205.     
  206.      (int) ret = q_delete(qid)
  207.  
  208.      qid       handle of queue to remove 
  209.  
  210.      ret        0   indicates success
  211.                -1   indicates system error
  212.  
  213. This call will delete the queue from the system and reclaim the  queue 
  214. buffer space. Any messages in the queue are lost.
  215.  
  216. The  system returns error codes if the queue cannot be deleted  (error 
  217. 10  - queue  in  use) or if the queue has not previously  been  opened 
  218. (error 9 - Cannot find queue).
  219.  
  220.  
  221. Queue Error
  222.  
  223.      (int) error = q_error() 
  224.  
  225.  
  226.      error     system status code following last 
  227.                operation.
  228.  
  229. This  provides  an  extended  error value and should  only  be  called 
  230. following a system error being returned on a queue function.  
  231.  
  232. Possible error codes are:
  233.  
  234.      7         No more  queue descriptors:  Only sixteen queues may be 
  235.                open at any one time.
  236.      8         No  free queue buffer  space:  Queue  buffer  space  is 
  237.                allocated inside sysdat and there is no more available. 
  238.                Either reduce the depth or length of queues, or build a
  239.                new system with more buffer space.
  240.      9         Cannot find queue:
  241.                  OPEN operation :     The queue has not yet been made.
  242.                  READ/WRITE/DELETE :  The queue has not been opened.
  243.      10        Queue in use:   The specified mutual exclusion queue is 
  244.                currently  owned by another process.
  245.      13        No queue access.
  246.      14        Empty queue:   Returned  by q_cread when the queue  was
  247.                empty. In this case the main error return is 1.
  248.      15        Full queue:    Returned  by q_cwrite when the queue was 
  249.                full. In this case the main error return is 1.
  250.      16        CLI queue missing.
  251.  
  252.  
  253. 3.0  Library Creation
  254.  
  255. The library source files are supplied on the disk. The files are:
  256.  
  257.  
  258.      QUEBIND.C                QUEBIND.H             QUEASM.ASM
  259.  
  260.      C part of                Header file           MASM assembly
  261.      bindings                 for quebind.c         part of bindings.
  262.  
  263.  
  264. The  source is written to support two memory models,  the S or C model 
  265. (LARGE_MODEL = FALSE) or the L model (LARGE_MODEL = TRUE).  The C part 
  266. will  pick  up  a  compile  time  definition  and  requires  no   code 
  267. modifications, but the assembler part will require the LARGE_MODEL equ 
  268. set appropriately.
  269.  
  270.  
  271. To compile the bindings:
  272.  
  273.  
  274.  
  275.      L model:
  276.           Set the LARGE_MODEL switch in queasm.asm to TRUE
  277.  
  278.           lc -mls quebind
  279.           masm queasm;
  280.           del quelibl.lib
  281.           lib quelibl+quebind+queasm;
  282.  
  283.  
  284.  
  285.      S model:
  286.           Set the LARGE_MODEL switch in queasm.asm to FALSE
  287.  
  288.           lc -ms quebind
  289.           masm queasm;
  290.           del quelibs.lib
  291.           lib quelibs+quebind+queasm;
  292.  
  293.  
  294. 4.0  Sample Programs
  295.  
  296. Three  sample  programs  are included.  The first  two,  QUETST.C  and 
  297. QUESLAVE.C are a pair.  QUETST will make and open two queues,  INQ and 
  298. OUTQ,  send 1000 messages to the OUTQ queue, printing a message on the 
  299. screen  to indicate the message number being sent.  It will also  scan 
  300. the INQ queue for messages and print them on the screen when received. 
  301. Note  this  program should be started first as it  makes  the  queues. 
  302. QUESLAVE will scan OUTQ for messages and return them to QUETST on INQ. 
  303. Both  programs will print status information on the screen as they run 
  304. - a '<' will be printed when a 'q_cread' call returns empty queue, and 
  305. a  '>'  will  be printed when a 'q_cwrite' call  returns  full  queue. 
  306. Additionally, QUESLAVE will print a '.' on a successful q_cwrite, i.e. 
  307. one '.' per message.
  308. QUETST  will delete the queues on completion,  which should  terminate 
  309. QUESLAVE with error code 9.
  310.  
  311. The  third program QUEDEL.C is used to delete the queues INQ and  OUTQ 
  312. if you stop the quetst program while it is running.
  313.  
  314.  
  315. To create the sample program, %1:
  316.  
  317.      lc -ms %1
  318.      link \lc\s\c+%1,%1,%1/m,\lc\s\lc+quelibs
  319.  
  320. (To use the L memory model, substitute l for s in the above)
  321.  
  322.