home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / PMPRINT.ZIP / PMPRINTF.DOC next >
Text File  |  1991-03-20  |  6KB  |  136 lines
  1.  
  2.     PMprintf -- 'printf' support for Presentation Manager programs
  3.     ==============================================================
  4.                                           Mike Cowlishaw, Feb 1991
  5.  
  6. * Would you like to use the C standard function 'printf' in your PM
  7.   programs for debugging, occasional error messages, etc.?
  8.  
  9. * Do you have existing subroutines, that use printf, that you'd like to
  10.   use in PM programs?
  11.  
  12. If you answer yes to either of these, you may find the PMprintf tool
  13. useful.  PMprintf comprises two parts:
  14.  
  15.   printf.obj -- an object file which you link in with your PM program
  16.     just like any other subroutine.  This provides the printf service to
  17.     that program.  You write printf calls in your C program in the usual
  18.     way; the printf subroutine buffers the data (on a per-thread basis
  19.     in multi-thread programs) and adds each completed line to a message
  20.     queue.  For example, the following printf call will write a line to
  21.     the PMprintf application and sound the Alert (bell):
  22.  
  23.       printf("This seems to work\a\n");
  24.  
  25.     Source (in C) is also provided for the printf function.
  26.  
  27.   pmprintf.exe -- is a PM application which sets up the queue used by
  28.     printf and then "catches" and displays incoming printf lines.  It is
  29.     a kind of 'monitor' or 'virtual console' which will accept lines
  30.     from any number of processes that use printf.  PMprintf offers a
  31.     number of options, including the ability to log the incoming lines
  32.     to a file.  See below for a short description of the options.
  33.  
  34.     If PMprintf has been started then it will display the incoming lines
  35.     from printf calls in other processes.  If it has not been started,
  36.     then printf calls are ignored (they return 0, not an error).
  37.     PMprintf can be started or stopped at any time, and printf calls
  38.     will then become active or be ignored as appropriate.
  39.  
  40. Source for printf (printf.c) is included in the package; this offers
  41. certain customization options (for example, you can cause a prefix to be
  42. added to the start of each line so that different applications can have
  43. unique output lines, or cause lines to be broken at a certain length).
  44. There are also some and usage hints and minor restrictions, documented
  45. in the header of printf.c.
  46.  
  47. pmprintf.exe
  48. ============
  49.  
  50. pmprintf.exe is a standard PM application that can be started in any
  51. of the usual ways (from a window, from Start Programs, from startup.cmd,
  52. etc.).  It presents a standard PM window with an action bar and a list
  53. box.  The list box is used for displaying and scrolling the most recent
  54. 250 lines received from printf calls in the same or other processes.
  55. The action bar selections are as follows:
  56.  
  57. File:
  58.   Has five sub-items:
  59.   Logging Active:
  60.     If checked, all incoming lines are written (logged) to the file
  61.     (called the LogFile) named by selecting LogFile Name.  The LogFile
  62.     is opened when logging is activated, and closed when de-activated.
  63.   Timestamp LogFile:
  64.     If checked, all lines written to the LogFile are prefixed with the
  65.     date and time that the line was sent by the printf subroutine (this
  66.     could be some time earlier than the time of display by PMprintf,
  67.     especially if Pause was used).
  68.   LogFile Name...:
  69.     Allows alteration of the name of the LogFile.  The default name is
  70.     'c:\pmprintf.log'.  Any previous LogFile in use is closed.  If the
  71.     new LogFile already exists, printf lines will be appended at the end
  72.     of the file.  The dialog box for changing the name also offers a
  73.     'Logging Active' checkbox, for convenience.
  74.     Once changed, the Logfile name is preserved in OS2.INI, and becomes
  75.     the default when PMprintf is next started.
  76.   Erase LogFile:
  77.     Erases ('resets') the current LogFile.  No confirmation is
  78.     requested.
  79.   Exit:
  80.     Same as selecting Exit on the action bar.
  81. Options:
  82.   Has three sub-items:
  83.   Erase Lines:
  84.     Discards all previously displayed lines.  Use this to clear the
  85.     PMprintf screen and recover the storage used for displaying "old"
  86.     lines in which you have no further interest.
  87.     The 'Esc' key may also be used to clear the PMprintf screen.
  88.   Beep on Arrival:
  89.     If checked, PMprintf will beep to alert you when a new line arrives
  90.     from a printf call.
  91.   Self Test:
  92.     If checked, PMprintf will call printf itself to display a line on
  93.     screen, and then allow selection of lines in the display: each
  94.     selection causes a new line to be added.  This is used to check that
  95.     printf and the queuing mechanism are working.
  96. Pause:
  97.   Used to stop new messages scrolling the screen.  Selecting Pause will
  98.   stop incoming messages; the Pause item is then replaced by a
  99.   highlighted Restart item -- no incoming messages will be displayed
  100.   until Restart is selected.
  101. Exit:
  102.   Closes down PMprintf, after asking for confirmation.  (Double click on
  103.   the system menu icon at top left for immediate close-down.)
  104. Help:
  105.   Refers to this document.
  106.  
  107. Installation
  108. ============
  109.  
  110. Download the PMPRINTF RAMBIN, in binary.  Use LOADRAM2 (often called
  111. simply LOADRAM) to unpack the files.  To check it works, "start
  112. pmprintf" and then select the "Self Test" item under "Options".  You
  113. should see a line appear in the PMprintf window: this was created by the
  114. 'printf' subroutine being called by PMprintf.
  115.  
  116. Caveats
  117. =======
  118.  
  119. PMprintf and printf were compiled using the IBM C/2 compiler (1.1). They
  120. were developed under OS/2 1.3 using the 1.3 Toolkit, though seem to run
  121. OK under OS/2 1.2.  They have not been fully tested in that environment.
  122. Note that, because printf uses the C Library function sprintf to do its
  123. formatting, you cannot use DosCreateThread to start a thread that uses
  124. printf; you must use _beginthread.  Thanks to Sam Detweiler and Bertrand
  125. Denoix for alerting me to this restriction!
  126.  
  127.  
  128. History
  129. =======
  130.  
  131. 1.0   7Feb91  Initial Release
  132. 1.1  12Feb91  Save/Restore LogFileName in OS2.INI
  133. 1.2  16Feb91  Improved printf routine: no restriction on number of
  134.               arguments
  135. 1.3  19Mar91  Allow Esc key for Clear; restrict number of lines kept
  136.