home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmprtf.zip / pmprintf.doc < prev    next >
Text File  |  1995-11-04  |  9KB  |  217 lines
  1.                                                             PMprintf 2.57
  2.    PMprintf -- 'printf' support for OS/2 Presentation Manager
  3.    ==========================================================
  4.  
  5.    Copyright (c) International Business Machines Corporation, 1991, 1995.
  6.    All rights reserved.  
  7.  
  8.  
  9.    Introduction
  10.    """"""""""""
  11.    o   Would you like to use the C standard function 'printf' in your PM
  12.        programs for debugging, occasional error messages, etc.?  
  13.  
  14.    o   Do you have existing subroutines, that use printf, that you'd like
  15.        to use in PM programs?
  16.  
  17.    If you answer yes to either of these, you may find the PMprintf tool
  18.    useful.  PMprintf comprises two parts: 
  19.  
  20.    printf.obj: 
  21.        an object file, compiled with IBM C Set/2, which you link in with
  22.        your PM program just like any other subroutine.  This provides the
  23.        printf service to that program.  You write printf calls in your C
  24.        program in the usual way; the printf subroutine buffers the data
  25.        (on a per-thread basis in multi-thread programs) and adds each
  26.        completed line to a message queue.  For example, the following
  27.        printf call will write a line to the PMprintf application and
  28.        sound the Alert (bell): 
  29.  
  30.           printf("This seems to work\a\n");
  31.  
  32.        Sample source (in C) is provided for the printf function.
  33.  
  34.    pmprintf.exe: 
  35.        a PM application which sets up the queue used by printf and then
  36.        "catches" and displays incoming printf lines.  It is a kind of
  37.        'monitor' or 'virtual console' which will accept lines from any
  38.        number of processes that use printf.  PMprintf offers a number of
  39.        options, including the ability to log the incoming lines to a
  40.        file.  See below for a short description of the options.  
  41.  
  42.        If PMprintf has been started then it will display the incoming
  43.        lines from printf calls in other processes.  If it has not been
  44.        started, then printf calls are quietly ignored (they return 0, not
  45.        an error).  PMprintf can be started or stopped at any time, and
  46.        printf calls will then become active or be ignored as appropriate.
  47.  
  48.    Sample source for printf (printf.c) is included in the package; this
  49.    offers certain customization options (for example, you can cause a
  50.    prefix to be added to the start of each line so that different
  51.    applications can have unique output lines, or cause lines to be broken
  52.    at a certain length).  There are also some usage hints, notes, and
  53.    minor restrictions, documented in the header of printf.c.  
  54.  
  55.  
  56.    pmprintf.exe
  57.    """"""""""""
  58.    pmprintf.exe, the program that "catches" printf lines, is a standard
  59.    PM application that can be started in any of the usual ways (from a
  60.    window, from a program object, from startup.cmd, etc.).  It presents a
  61.    standard PM window with an action bar and a list box.  The list box is
  62.    used for displaying and scrolling the most recent 300 lines received
  63.    from printf calls in the same or other processes.
  64.  
  65.    You can change the font or background colour used in the list box by
  66.    dragging a font or colour from the OS/2 palettes and dropping it on
  67.    the list box.  These settings, along with other PMprintf settings, are
  68.    stored in the OS/2 user INI file.
  69.  
  70.    The menu bar offers selections for controlling the logging of the
  71.    printf lines to a file called the "LogFile", along with other options.
  72.    The choices are as follows: 
  73.  
  74.  
  75.    ----- 'File': control logging to file -----
  76.  
  77.    'Write all old lines to LogFile': 
  78.        All lines in the list are immediately written to the LogFile.  The
  79.        lines are not erased from the list, are not timestamped, and will
  80.        be truncated if longer than 500 characters.  
  81.  
  82.    'Log new lines to LogFile': 
  83.        If checked, all incoming lines are written (logged) to the
  84.        LogFile.  The LogFile is opened when logging is activated, and
  85.        closed when de-activated.  
  86.  
  87.    'Timestamp new lines to LogFile': 
  88.        If checked, all new lines written to the LogFile are prefixed with
  89.        the date and time that the line was sent by the printf subroutine
  90.        (this could be some time earlier than the time of display by
  91.        PMprintf, especially if Pause was used).  The timestamps could
  92.        show the wrong local time if you do not set the TZ environment
  93.        variable (see notes in printf.c for more details).  
  94.  
  95.    'LogFile name...': 
  96.        Allows alteration of the name of the LogFile.  The default name is
  97.        'c:\pmprintf.log'.  Any previous LogFile in use is closed.  If the
  98.        new LogFile already exists, printf lines will be appended at the
  99.        end of the file.  The dialog box for changing the name also offers
  100.        a 'Log new lines' checkbox, for convenience.  
  101.  
  102.    'Erase LogFile': 
  103.        Erases ('resets') the current LogFile.  No confirmation is
  104.        requested.  
  105.  
  106.    'Close': 
  107.        Closes PMprintf (same as selecting Close in the System menu).
  108.  
  109.    Once changed, the LogFile name, logging state, and timestamp state are
  110.    preserved in OS2.INI, and become the default when PMprintf is next
  111.    started.
  112.  
  113.    To look at an 'active' LogFile, use a program or command that allows
  114.    shared reading of files.  TYPE is one such command; its output may be
  115.    redirected to a file to take a snapshot copy of the LogFile.  For
  116.    example: 
  117.  
  118.       type c:\pmprintf.log > snapshot.log
  119.  
  120.  
  121.    ----- 'Options': miscellaneous options -----
  122.  
  123.    'Erase lines': 
  124.        Discards all previously displayed lines.  Use this to clear the
  125.        PMprintf screen and recover the storage used for displaying "old"
  126.        lines in which you have no further interest.  This does not affect
  127.        the LogFile.  
  128.  
  129.        The 'Esc' key may also be used to clear the PMprintf screen, and
  130.        has the same effects.  
  131.  
  132.    'Beep on arrival': 
  133.        If checked, PMprintf will beep to alert you when a new line
  134.        arrives from a printf call.  
  135.  
  136.    'Save window position': 
  137.        Saves the current window position and state (in OS2.INI).  This is
  138.        used when PMprintf next starts, and is also saved automatically if
  139.        PMprintf is Closed or OS/2 is shut down.  
  140.  
  141.    'Self test': 
  142.        If checked, PMprintf will call printf itself to display a line on
  143.        screen, and then allow selection of lines in the display: each
  144.        selection causes a new line to be added.  This is used to check
  145.        that printf and the queuing mechanism are working.
  146.  
  147.  
  148.    ----- 'Pause', 'Restart', and 'Help': -----
  149.  
  150.    'Pause': 
  151.        Used to stop new printf lines scrolling the screen.  Selecting
  152.        Pause will cause incoming lines to be queued; the 'Pause' choice
  153.        is then replaced by a 'Restart' choice -- no incoming lines will
  154.        be displayed (added to the listbox and displayed) until 'Restart'
  155.        is selected.  
  156.  
  157.    'Restart': 
  158.        Restarts the displaying of printf files, after 'Pause' has been
  159.        selected (see above).  
  160.  
  161.    'Help': 
  162.        Displays the program information and Copyright notice, and refers
  163.        to this document.
  164.  
  165.  
  166.    Installation
  167.    """"""""""""
  168.    Unpack (unzip) the files from PMPRTF.ZIP into any directory.  To check
  169.    the program works, "start pmprintf" and then select the "Self Test"
  170.    item under "Options".  You should see a line appear in the PMprintf
  171.    window: this was created by the 'printf' subroutine being called by
  172.    PMprintf.   
  173.  
  174.  
  175.    Using printf in application programs
  176.    """"""""""""""""""""""""""""""""""""
  177.    You can use printf calls in application programs with PM applications
  178.    or not.  The printf subroutine uses sprintf() to do its formatting, so
  179.    output should be identical.
  180.  
  181.    printf.obj is linked with your main program, just like any other
  182.    subroutine.  If you have problems linking (such as duplicate symbols,
  183.    etc.), try recompiling printf.c with the same options that you use for
  184.    your main program.  You may also need to recompile if you wish to
  185.    change any of the compile-time settings in print.c (such as the
  186.    maximum line length).
  187.  
  188.    Note that the '\n' newline character is expected (indeed, required)
  189.    before a line is deemed complete and is sent to the catcher
  190.    application (PMprintf) -- see the example in the Introduction to this
  191.    document.  However, once sent, the line is in a public queue and
  192.    should appear even if the sending application then terminates
  193.    abnormally.  See printf.c for more notes and details.   
  194.  
  195.  
  196.    Named Queues
  197.    """"""""""""
  198.    By default, the public queue for PMprintf is named "PRINTF32" for the
  199.    32-bit version of PMprintf.  If required, you can set up multiple
  200.    PMprintf sessions with different queue names, by specifying a
  201.    different name as a parameter (up to eight characters) following the
  202.    keyword 'QUEUE' when starting PMprintf.  For example, if started with: 
  203.  
  204.       start pmprintf queue Fred
  205.  
  206.    then PMprintf will use the public queue name '\QUEUES\FRED', and the
  207.    name "Fred" will be shown in the title of the PMprintf window.  Note
  208.    that the Self Test function is not available when a named queue is
  209.    used.
  210.  
  211.    Early versions (1.xx) of PMprintf were 16-bit.  Do not send 32-bit
  212.    printf() output to a 16-bit catcher, or vice versa.  
  213.  
  214.    -----------
  215.  
  216.    Mike Cowlishaw (mfc@vnet.ibm.com), IBM UK Laboratories
  217.