home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / progs / pmprtf / pmprintf.doc < prev    next >
Encoding:
Text File  |  1993-06-02  |  9.1 KB  |  214 lines
  1.                                                             PMprintf 2.56
  2.    PMprintf -- 'printf' support for OS/2 Presentation Manager
  3.    ==========================================================
  4.  
  5.    Copyright (c) International Business Machines Corporation, 1991, 1993.
  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.  You can change the
  64.    font used in the list box by dragging a font from the OS/2 font
  65.    palette and dropping it on the list box.
  66.  
  67.    The menu bar offers selections for controlling the logging of the
  68.    printf lines to a file called the "LogFile", along with other options.
  69.    The choices are as follows: 
  70.  
  71.  
  72.    ----- 'File': control logging to file -----
  73.  
  74.    'Write all old lines to LogFile': 
  75.        All lines in the list are immediately written to the LogFile.  The
  76.        lines are not erased from the list, are not timestamped, and will
  77.        be truncated if longer than 500 characters.  
  78.  
  79.    'Log new lines to LogFile': 
  80.        If checked, all incoming lines are written (logged) to the
  81.        LogFile.  The LogFile is opened when logging is activated, and
  82.        closed when de-activated.  
  83.  
  84.    'Timestamp new lines to LogFile': 
  85.        If checked, all new lines written to the LogFile are prefixed with
  86.        the date and time that the line was sent by the printf subroutine
  87.        (this could be some time earlier than the time of display by
  88.        PMprintf, especially if Pause was used).  The timestamps could
  89.        show the wrong local time if you do not set the TZ environment
  90.        variable (see notes in printf.c for more details).  
  91.  
  92.    'LogFile name...': 
  93.        Allows alteration of the name of the LogFile.  The default name is
  94.        'c:\pmprintf.log'.  Any previous LogFile in use is closed.  If the
  95.        new LogFile already exists, printf lines will be appended at the
  96.        end of the file.  The dialog box for changing the name also offers
  97.        a 'Log new lines' checkbox, for convenience.  
  98.  
  99.    'Erase LogFile': 
  100.        Erases ('resets') the current LogFile.  No confirmation is
  101.        requested.  
  102.  
  103.    'Close': 
  104.        Closes PMprintf (same as selecting Close in the System menu).
  105.  
  106.    Once changed, the LogFile name, logging state, and timestamp state are
  107.    preserved in OS2.INI, and become the default when PMprintf is next
  108.    started.
  109.  
  110.    To look at an 'active' LogFile, use a program or command that allows
  111.    shared reading of files.  TYPE is one such command; its output may be
  112.    redirected to a file to take a snapshot copy of the LogFile.  For
  113.    example: 
  114.  
  115.       type c:\pmprintf.log > snapshot.log
  116.  
  117.  
  118.    ----- 'Options': miscellaneous options -----
  119.  
  120.    'Erase lines': 
  121.        Discards all previously displayed lines.  Use this to clear the
  122.        PMprintf screen and recover the storage used for displaying "old"
  123.        lines in which you have no further interest.  This does not affect
  124.        the LogFile.  
  125.  
  126.        The 'Esc' key may also be used to clear the PMprintf screen, and
  127.        has the same effects.  
  128.  
  129.    'Beep on arrival': 
  130.        If checked, PMprintf will beep to alert you when a new line
  131.        arrives from a printf call.  
  132.  
  133.    'Save window position': 
  134.        Saves the current window position and state (in OS2.INI).  This is
  135.        used when PMprintf next starts, and is also saved automatically if
  136.        PMprintf is Closed or OS/2 is shut down.  
  137.  
  138.    'Self test': 
  139.        If checked, PMprintf will call printf itself to display a line on
  140.        screen, and then allow selection of lines in the display: each
  141.        selection causes a new line to be added.  This is used to check
  142.        that printf and the queuing mechanism are working.
  143.  
  144.  
  145.    ----- 'Pause', 'Restart', and 'Help': -----
  146.  
  147.    'Pause': 
  148.        Used to stop new printf lines scrolling the screen.  Selecting
  149.        Pause will cause incoming lines to be queued; the 'Pause' choice
  150.        is then replaced by a 'Restart' choice -- no incoming lines will
  151.        be displayed (added to the listbox and displayed) until 'Restart'
  152.        is selected.  
  153.  
  154.    'Restart': 
  155.        Restarts the displaying of printf files, after 'Pause' has been
  156.        selected (see above).  
  157.  
  158.    'Help': 
  159.        Displays the program information and Copyright notice, and refers
  160.        to this document.
  161.  
  162.  
  163.    Installation
  164.    """"""""""""
  165.    Unpack (unzip) the files from PMPRTF.ZIP into any directory.  To check
  166.    the program works, "start pmprintf" and then select the "Self Test"
  167.    item under "Options".  You should see a line appear in the PMprintf
  168.    window: this was created by the 'printf' subroutine being called by
  169.    PMprintf.   
  170.  
  171.  
  172.    Using printf in application programs
  173.    """"""""""""""""""""""""""""""""""""
  174.    You can use printf calls in application programs with PM applications
  175.    or not.  The printf subroutine uses sprintf() to do its formatting, so
  176.    output should be identical.
  177.  
  178.    printf.obj is linked with your main program, just like any other
  179.    subroutine.  If you have problems linking (such as duplicate symbols,
  180.    etc.), try recompiling printf.c with the same options that you use for
  181.    your main program.  You may also need to recompile if you wish to
  182.    change any of the compile-time settings in print.c (such as the
  183.    maximum line length).
  184.  
  185.    Note that the '\n' newline character is expected (indeed, required)
  186.    before a line is deemed complete and is sent to the catcher
  187.    application (PMprintf) -- see the example in the Introduction to this
  188.    document.  However, once sent, the line is in a public queue and
  189.    should appear even if the sending application then terminates
  190.    abnormally.  See printf.c for more notes and details.   
  191.  
  192.  
  193.    Named Queues
  194.    """"""""""""
  195.    By default, the public queue for PMprintf is named "PRINTF32" for the
  196.    32-bit version of PMprintf.  If required, you can set up multiple
  197.    PMprintf sessions with different queue names, by specifying a
  198.    different name as a parameter (up to eight characters) following the
  199.    keyword 'QUEUE' when starting PMprintf.  For example, if started with: 
  200.  
  201.       start pmprintf queue Fred
  202.  
  203.    then PMprintf will use the public queue name '\QUEUES\FRED', and the
  204.    name "Fred" will be shown in the title of the PMprintf window.  Note
  205.    that the Self Test function is not available when a named queue is
  206.    used.
  207.  
  208.    Early versions (1.xx) of PMprintf were 16-bit.  Do not send 32-bit
  209.    printf() output to a 16-bit catcher, or vice versa.  
  210.  
  211.    -----------
  212.  
  213.    Mike Cowlishaw, IBM UK Laboratories
  214.