home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / pmprtf / pmprintf.doc < prev    next >
Text File  |  1992-08-18  |  7KB  |  162 lines
  1.  
  2. PMprintf -- 'printf' support for Presentation Manager programs
  3. ==============================================================
  4. Copyright (c) IBM Corporation, 1991, 1992.
  5.  
  6.  
  7. Introduction
  8. """"""""""""
  9.  
  10. * Would you like to use the C standard function 'printf' in your PM
  11.   programs for debugging, occasional error messages, etc.?
  12.  
  13. * Do you have existing subroutines, that use printf, that you'd like to
  14.   use in PM programs?
  15.  
  16. If you answer yes to either of these, you may find the PMprintf tool
  17. useful.  PMprintf comprises two parts:
  18.  
  19.   printf.obj -- an object file, compiled with IBM C Set/2, which you
  20.     link in with your PM program just like any other subroutine.  This
  21.     provides the printf service to that program.  You write printf calls
  22.     in your C program in the usual way; the printf subroutine buffers
  23.     the data (on a per-thread basis in multi-thread programs) and adds
  24.     each completed line to a message queue.  For example, the following
  25.     printf call will write a line to the PMprintf application and sound
  26.     the Alert (bell):
  27.  
  28.       printf("This seems to work\a\n");
  29.  
  30.     Sample source (in C) is also provided for the printf function.
  31.  
  32.   pmprintf.exe -- is a PM application which sets up the queue used by
  33.     printf and then "catches" and displays incoming printf lines.  It is
  34.     a kind of 'monitor' or 'virtual console' which will accept lines
  35.     from any number of processes that use printf.  PMprintf offers a
  36.     number of options, including the ability to log the incoming lines
  37.     to a file.  See below for a short description of the options.
  38.  
  39.     If PMprintf has been started then it will display the incoming lines
  40.     from printf calls in other processes.  If it has not been started,
  41.     then printf calls are quietly ignored (they return 0, not an error).
  42.     PMprintf can be started or stopped at any time, and printf calls
  43.     will then become active or be ignored as appropriate.
  44.  
  45. Sample source for printf (printf.c) is included in the package; this
  46. offers certain customization options (for example, you can cause a
  47. prefix to be added to the start of each line so that different
  48. applications can have unique output lines, or cause lines to be broken
  49. at a certain length). There are also some usage hints and minor
  50. restrictions, documented in the header of printf.c.
  51.  
  52.  
  53. pmprintf.exe
  54. """"""""""""
  55. pmprintf.exe is a standard PM application that can be started in any
  56. of the usual ways (from a window, from a program object, from
  57. startup.cmd, etc.).  It presents a standard PM window with an action bar
  58. and a list box.  The list box is used for displaying and scrolling the
  59. most recent 300 lines received from printf calls in the same or other
  60. processes.  The action bar selections are as follows:
  61.  
  62. File:
  63.   Has the following sub-items:
  64.   Write all old lines to LogFile
  65.     All lines in the list are immediately written to the LogFile.  The
  66.     lines are not erased from the list, are not timestamped, and will be
  67.     truncated if longer than 500 characters.
  68.   Log new lines to LogFile
  69.     If checked, all incoming lines are written (logged) to the file
  70.     (called the LogFile) named by selecting 'LogFile name'.  The LogFile
  71.     is opened when logging is activated, and closed when de-activated.
  72.   Timestamp new lines to LogFile
  73.     If checked, all new lines written to the LogFile are prefixed with
  74.     the date and time that the line was sent by the printf subroutine
  75.     (this could be some time earlier than the time of display by
  76.     PMprintf, especially if Pause was used).  The timestamps could show
  77.     the wrong local time if you do not set the TZ environment variable
  78.     (see notes in printf.c for more details).
  79.   LogFile name...:
  80.     Allows alteration of the name of the LogFile.  The default name is
  81.     'c:\pmprintf.log'.  Any previous LogFile in use is closed.  If the
  82.     new LogFile already exists, printf lines will be appended at the end
  83.     of the file.  The dialog box for changing the name also offers a
  84.     'Log new lines' checkbox, for convenience.
  85.   Erase LogFile:
  86.     Erases ('resets') the current LogFile.  No confirmation is
  87.     requested.
  88.   Close:
  89.     Same as selecting Close in the System menu.
  90.   Once changed, the LogFile name, logging state, and timestamp state are
  91.   preserved in OS2.INI, and become the default when PMprintf is next
  92.   started.
  93. Options:
  94.   Has the following sub-items:
  95.   Erase lines:
  96.     Discards all previously displayed lines.  Use this to clear the
  97.     PMprintf screen and recover the storage used for displaying "old"
  98.     lines in which you have no further interest.
  99.     The 'Esc' key may also be used to clear the PMprintf screen, and has
  100.     the same effects.
  101.   Beep on arrival:
  102.     If checked, PMprintf will beep to alert you when a new line arrives
  103.     from a printf call.
  104.   Save window position:
  105.     Saves the current window position (in OS2.INI).  This is used when
  106.     PMprintf next starts, and is also saved automatically if PMprintf
  107.     is Closed or OS/2 is shut down.
  108.      Different positions are saved for
  109.     the 16-bit and 32-bit versions.
  110.   Self test:
  111.     If checked, PMprintf will call printf itself to display a line on
  112.     screen, and then allow selection of lines in the display: each
  113.     selection causes a new line to be added.  This is used to check that
  114.     printf and the queuing mechanism are working.
  115. Pause:
  116.   Used to stop new messages scrolling the screen.  Selecting Pause will
  117.   stop incoming messages; the Pause item is then replaced by a
  118.   highlighted Restart item -- no incoming messages will be displayed
  119.   until Restart is selected.
  120. Help:
  121.   Refers to this document.
  122.  
  123.  
  124. Installation
  125. """"""""""""
  126. Unpack the files from PMPRTF.ZIP into any directory. To check the
  127. program works, "start pmprintf" and then select the "Self Test" item
  128. under "Options".  You should see a line appear in the PMprintf window:
  129. this was created by the 'printf' subroutine being called by PMprintf.
  130.  
  131.  
  132. Using printf in application programs
  133. """"""""""""""""""""""""""""""""""""
  134. You can use printf calls in application programs with PM applications or
  135. not.  The printf subroutine uses sprintf() to do its formatting, so
  136. output should be identical.  Note that the '\n' newline character is
  137. expected (indeed, required) before a line is deemed complete and is
  138. sent to the catcher application (PMprintf).  However, once sent it is in
  139. a public queue and should appear even if the sending application then
  140. terminates abnormally.  See PRINTF.C for more notes and details.
  141.  
  142.  
  143. Named Queues
  144. """"""""""""
  145. By default, the public queue for PMprintf is named "PRINTF32" or for the
  146. 32-bit version of PMprintf.  If required, you can set up multiple
  147. PMprintf sessions with different queue names, by specifying a different
  148. name as a parameter (up to eight characters) following the keyword
  149. 'QUEUE' when starting PMprintf.  For example, if started with:
  150.  
  151.   start pmprintf queue Fred
  152.  
  153. then PMprintf will use the public queue name '\QUEUES\FRED', and the
  154. name "Fred" will be shown in the title of the PMprintf window.  Note
  155. that the Self Test function is not available when a named queue is used.
  156. Do not send 32-bit printf() output to a 16-bit catcher, or vice versa.
  157.  
  158.  
  159. -----------
  160.  
  161. Mike Cowlishaw, IBM UK Laboratories
  162.