home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Professional
/
OS2PRO194.ISO
/
os2
/
prgramer
/
pmprtf
/
pmprintf.doc
< prev
next >
Wrap
Text File
|
1992-08-18
|
7KB
|
162 lines
PMprintf -- 'printf' support for Presentation Manager programs
==============================================================
Copyright (c) IBM Corporation, 1991, 1992.
Introduction
""""""""""""
* Would you like to use the C standard function 'printf' in your PM
programs for debugging, occasional error messages, etc.?
* Do you have existing subroutines, that use printf, that you'd like to
use in PM programs?
If you answer yes to either of these, you may find the PMprintf tool
useful. PMprintf comprises two parts:
printf.obj -- an object file, compiled with IBM C Set/2, which you
link in with your PM program just like any other subroutine. This
provides the printf service to that program. You write printf calls
in your C program in the usual way; the printf subroutine buffers
the data (on a per-thread basis in multi-thread programs) and adds
each completed line to a message queue. For example, the following
printf call will write a line to the PMprintf application and sound
the Alert (bell):
printf("This seems to work\a\n");
Sample source (in C) is also provided for the printf function.
pmprintf.exe -- is a PM application which sets up the queue used by
printf and then "catches" and displays incoming printf lines. It is
a kind of 'monitor' or 'virtual console' which will accept lines
from any number of processes that use printf. PMprintf offers a
number of options, including the ability to log the incoming lines
to a file. See below for a short description of the options.
If PMprintf has been started then it will display the incoming lines
from printf calls in other processes. If it has not been started,
then printf calls are quietly ignored (they return 0, not an error).
PMprintf can be started or stopped at any time, and printf calls
will then become active or be ignored as appropriate.
Sample source for printf (printf.c) is included in the package; this
offers certain customization options (for example, you can cause a
prefix to be added to the start of each line so that different
applications can have unique output lines, or cause lines to be broken
at a certain length). There are also some usage hints and minor
restrictions, documented in the header of printf.c.
pmprintf.exe
""""""""""""
pmprintf.exe is a standard PM application that can be started in any
of the usual ways (from a window, from a program object, from
startup.cmd, etc.). It presents a standard PM window with an action bar
and a list box. The list box is used for displaying and scrolling the
most recent 300 lines received from printf calls in the same or other
processes. The action bar selections are as follows:
File:
Has the following sub-items:
Write all old lines to LogFile
All lines in the list are immediately written to the LogFile. The
lines are not erased from the list, are not timestamped, and will be
truncated if longer than 500 characters.
Log new lines to LogFile
If checked, all incoming lines are written (logged) to the file
(called the LogFile) named by selecting 'LogFile name'. The LogFile
is opened when logging is activated, and closed when de-activated.
Timestamp new lines to LogFile
If checked, all new lines written to the LogFile are prefixed with
the date and time that the line was sent by the printf subroutine
(this could be some time earlier than the time of display by
PMprintf, especially if Pause was used). The timestamps could show
the wrong local time if you do not set the TZ environment variable
(see notes in printf.c for more details).
LogFile name...:
Allows alteration of the name of the LogFile. The default name is
'c:\pmprintf.log'. Any previous LogFile in use is closed. If the
new LogFile already exists, printf lines will be appended at the end
of the file. The dialog box for changing the name also offers a
'Log new lines' checkbox, for convenience.
Erase LogFile:
Erases ('resets') the current LogFile. No confirmation is
requested.
Close:
Same as selecting Close in the System menu.
Once changed, the LogFile name, logging state, and timestamp state are
preserved in OS2.INI, and become the default when PMprintf is next
started.
Options:
Has the following sub-items:
Erase lines:
Discards all previously displayed lines. Use this to clear the
PMprintf screen and recover the storage used for displaying "old"
lines in which you have no further interest.
The 'Esc' key may also be used to clear the PMprintf screen, and has
the same effects.
Beep on arrival:
If checked, PMprintf will beep to alert you when a new line arrives
from a printf call.
Save window position:
Saves the current window position (in OS2.INI). This is used when
PMprintf next starts, and is also saved automatically if PMprintf
is Closed or OS/2 is shut down.
Different positions are saved for
the 16-bit and 32-bit versions.
Self test:
If checked, PMprintf will call printf itself to display a line on
screen, and then allow selection of lines in the display: each
selection causes a new line to be added. This is used to check that
printf and the queuing mechanism are working.
Pause:
Used to stop new messages scrolling the screen. Selecting Pause will
stop incoming messages; the Pause item is then replaced by a
highlighted Restart item -- no incoming messages will be displayed
until Restart is selected.
Help:
Refers to this document.
Installation
""""""""""""
Unpack the files from PMPRTF.ZIP into any directory. To check the
program works, "start pmprintf" and then select the "Self Test" item
under "Options". You should see a line appear in the PMprintf window:
this was created by the 'printf' subroutine being called by PMprintf.
Using printf in application programs
""""""""""""""""""""""""""""""""""""
You can use printf calls in application programs with PM applications or
not. The printf subroutine uses sprintf() to do its formatting, so
output should be identical. Note that the '\n' newline character is
expected (indeed, required) before a line is deemed complete and is
sent to the catcher application (PMprintf). However, once sent it is in
a public queue and should appear even if the sending application then
terminates abnormally. See PRINTF.C for more notes and details.
Named Queues
""""""""""""
By default, the public queue for PMprintf is named "PRINTF32" or for the
32-bit version of PMprintf. If required, you can set up multiple
PMprintf sessions with different queue names, by specifying a different
name as a parameter (up to eight characters) following the keyword
'QUEUE' when starting PMprintf. For example, if started with:
start pmprintf queue Fred
then PMprintf will use the public queue name '\QUEUES\FRED', and the
name "Fred" will be shown in the title of the PMprintf window. Note
that the Self Test function is not available when a named queue is used.
Do not send 32-bit printf() output to a 16-bit catcher, or vice versa.
-----------
Mike Cowlishaw, IBM UK Laboratories