home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff290.lzh / IPC / Sources / FormatServer.DOC < prev    next >
Text File  |  1989-12-11  |  8KB  |  170 lines
  1.  
  2.                             FormatServer
  3.                               _______
  4.  
  5.                  Formatted output IPC Server Module
  6.  
  7.  
  8. This program is a Server for IPC that both provides a demonstration of
  9. technique and has a useful function.  It accepts a message containing
  10. numeric, character and string items, together with appropriate
  11. format-specifying items, and generates a formatted output string.  This
  12. string may be sent to the server's own console window, or may be returned
  13. to the client, or may be written to a supplied file handle.
  14.  
  15. This server avoids each module having to have its own output mechanisms.
  16. In a lot of cases -- error messages and so on -- it will probably  be
  17. convenient to send reports (suitably tagged with an identifying string) to
  18. the common FormatServer window.  Where a module does need its own window it
  19. still does not have to be burdened with the space needed for 'printf' if it
  20. uses this server.
  21.  
  22. The IPCPort served by this module is named "Print_Format".  Only one
  23. IPCMessage ID ('CNVA'), as described below, is handled by this version
  24. (except for 'QUIT'), but there can be many variations on the items
  25. included, to determine the contents, format, and destination of the output
  26. string.
  27.  
  28. The server will run until either it is sent a 'QUIT' message by any client,
  29. or the number of current clients drops to zero (from non-zero, so that it
  30. doesn't terminate if there are initially no clients).  It will also
  31. terminate immediately if the user gives the process a ctrl-C break.
  32.  
  33.  
  34. Message Format:
  35.  
  36. The IPCMessage Type ID accepted by FormatServer is 'CNVA' ("CoNVert to
  37. Ascii"). It may contain an arbitrary number of items.  Optionally, the
  38. first may be a "disposition control" item (see below); if it is absent, the
  39. formatted string will be displayed in the FormatServer console window.
  40.  
  41. Items to be formatted may be of the following types:
  42.  
  43.     INTG    -- ii_Ptr contains a 32-bit integer value to be converted to
  44.                its ASCII representation (ii_Size = 0).
  45.  
  46.     REAL    -- ii_Ptr contains a 32-bit floating-point value to be
  47.                converted (ii_Size = 0).  (Note -- care will be needed
  48.                when inserting the original 'float' value into ii_Ptr, to
  49.                make sure that the compiler doesn't apply an unintended
  50.                conversion!  FormatServer converts the supplied value to
  51.                'double' and uses the "%g" format to output it.)
  52.  
  53.     STRG
  54.     LINE
  55.     TEXT    -- equivalent IDs representing ASCII strings to be inserted in
  56.                the output.  (Although FormatServer treats them equivalently,
  57.                they may have different meanings in other environments: in
  58.                particular, LINE is a conplete single line of text without
  59.                its terminating newline, TEXT is an arbitrary block of text
  60.                that may contain newline characters, and STRG is possibly a
  61.                partial line.)
  62.  
  63.     CHAR    -- A single ASCII character (in the least-significant byte of
  64.                ii_Ptr; ii_Size = 0).
  65.  
  66.  
  67. If no format-specifying items are supplied, default formats are used ("%ld"
  68. for integer, "%g" for floats (cast to double by FormatServer), "%s" for
  69. strings, and "%c" for characters).  For further control, you can either
  70. prefix an item with a single-item format string, or include a multi-item
  71. format specification.
  72.  
  73.     PAT1    -- ii_Ptr points to a "printf" type format string containing
  74.                exactly one conversion specifier, which must be appropriate
  75.                for the immediately following item.  Aside from the single
  76.                specifier that must be present, the contents of the string
  77.                are arbitrary.
  78.  
  79.     PATS    -- ii_Ptr points to a format string that contains conversion
  80.                specifiers for ALL the remaining items in the message; no
  81.                other format or extraneous item may appear after this. There
  82.                is no check that the number of items matches the number of
  83.                specifiers; any unmatched items won't be converted; extra
  84.                specifiers will produce garbage.
  85.                There is one restriction on this form: REAL items cannot
  86.                be included (because there is no easy way to do the
  87.                conversion to double on individual items of a set -- all
  88.                other types are passed as 32-bit quantities); use PAT1
  89.                instead, which does not have this restriction.
  90.  
  91. As stated earlier, by default the converted string is displayed in the
  92. FormatServer window, but if the first item is one of the following the
  93. destination will be changed appropriately.
  94.  
  95.     RETS    -- (RETurn String) When the message is replied to the client
  96.                (successfully), this item will contain a pointer to a data
  97.                block containing the converted string.  The client can
  98.                select one of two possible options for the source of this
  99.                data block: a) if the original message contains a non-NULL
  100.                ii_Ptr value, the converted string will be placed at that
  101.                address, PROVIDED that the supplied value of ii_Size is
  102.                large enough to hold it; otherwise the item will be flagged
  103.                IPC_FAILED | IPC_NOTKNOWN and no conversion will be done;
  104.                b) if the supplied ii_Ptr value is NULL, a suitably large
  105.                block of memory will be allocated for the string; the item
  106.                will be flagged IPC_TRANSFER to indicate that the Client
  107.                MUST dispose of the memory block when done.
  108.  
  109.  
  110.     FILH    -- (FILe Handle) If present, this must have a valid AmigaDOS
  111.                file handle in ii_Ptr (ii_Size = 0).  The converted string
  112.                will be written to this file (which might for instance be
  113.                the Client's Output() console or file).  (Note that under
  114.                AmigaDOS multiple processes can write to a single file
  115.                handle without problems; the system takes care of locking.)
  116.  
  117. It is possible for both RETS and FILH itmes to be included in the message,
  118. in which case both paths will be used; if either is present, no output ever
  119. is sent to the FormatServer window. There cannot be more than one of each
  120. kind of item, though.  It is actually not necessary that they be the first
  121. items, but that is the preferred position for clarity.
  122.  
  123. Any item Ids other than those mentioned above will be ignored, UNLESS they
  124. appear in positions following a format item (PAT1 or PATS) where a value is
  125. expected, in which case an error will be flagged and no conversion will be
  126. performed.
  127.  
  128.  
  129. Example:
  130.  
  131. A message sent to FormatServer containing
  132.  
  133.     ipc_Id          CNVA
  134.     ipc_ItemCount   4
  135.  
  136.     item 1  ii_Id       RETS
  137.             ii_Size     0       (will be set to block size on return)
  138.             ii_Ptr      NULL    (will point to data block on return)
  139.  
  140.     item 2  ii_Id       PAT1
  141.             ii_Size     0       (indicates MYOB to server)
  142.             ii_Ptr      pointer to string "Test line #%3d "
  143.  
  144.     item 3  ii_Id       INTG
  145.             ii_Size     0
  146.             ii_Ptr      1       (some integer value)
  147.  
  148.     item 4  ii_Id       STRG
  149.             ii_Size     0
  150.             ii_Ptr      pointer to string "...that's it\n"
  151.  
  152. would return
  153.  
  154.     "Test line #  1 ...that's it"
  155.  
  156. to the client.
  157.  
  158. Note the use of 0 values for string sizes; this is permissible where the
  159. pointer is to a client-owned area of memory that the server must not alter;
  160. the size field WOULD be necessary if the item was being passed to a more
  161. general server, or the server was to take over management of the item --
  162. then of course the block would also have to be in public memory.  The
  163. ii_Size field in any case does NOT represent the length of the string
  164. itself: if non-zero it would represent the data-block containing the
  165. string, which could be considerably bigger than the string.
  166.  
  167.                             % % % % % % %
  168.  
  169.  
  170.