process.pm

source of perl for linux application,

=head2 Access to process properties

On OS/2 processes have the usual I<parent/child> semantic;
additionally, there is a hierarchy of sessions with their own
I<parent/child> tree.  A session is either a FS session, or a windowed
pseudo-session created by PM.  A session is a "unit of user
interaction", a change to in/out settings in one of them does not
affect other sessions.

=over

=item my_type()

returns the type of the current process (one of
"FS", "DOS", "VIO", "PM", "DETACH" and "UNKNOWN"), or C<undef> on error.

=item C<file_type(file)>

returns the type of the executable file C<file>, or
dies on error.  The bits 0-2 of the result contain one of the values

=over

=item C<T_NOTSPEC> (0)

Application type is not specified in the executable header.

=item C<T_NOTWINDOWCOMPAT> (1)

Application type is not-window-compatible.

=item C<T_WINDOWCOMPAT> (2)

Application type is window-compatible.

=item C<T_WINDOWAPI> (3)

Application type is window-API.

=back

The remaining bits should be masked with the following values to
determine the type of the executable:

=over

=item C<T_BOUND> (8)

Set to 1 if the executable file has been "bound" (by the BIND command)
as a Family API application. Bits 0, 1, and 2 still apply.

=item C<T_DLL> (0x10)

Set to 1 if the executable file is a dynamic link library (DLL)
module. Bits 0, 1, 2, 3, and 5 will be set to 0.

=item C<T_DOS> (0x20)

Set to 1 if the executable file is in PC/DOS format. Bits 0, 1, 2, 3,
and 4 will be set to 0.

=item C<T_PHYSDRV> (0x40)

Set to 1 if the executable file is a physical device driver.

=item C<T_VIRTDRV> (0x80)

Set to 1 if the executable file is a virtual device driver.

=item C<T_PROTDLL> (0x100)

Set to 1 if the executable file is a protected-memory dynamic link
library module.

=item C<T_32BIT> (0x4000)

Set to 1 for 32-bit executable files.

=back

file_type() may croak with one of the strings C<"Invalid EXE
signature"> or C<"EXE marked invalid"> to indicate typical error
conditions.  If given non-absolute path, will look on C<PATH>, will
add extension F<.exe> if no extension is present (add extension F<.>
to suppress).

=item C<@list = process_codepages()>

the first element is the currently active codepage, up to 2 additional
entries specify the system's "prepared codepages": the codepages the
user can switch to.  The active codepage of a process is one of the
prepared codepages of the system (if present).

=item C<process_codepage_set($cp)>

sets the currently active codepage.  [Affects printer output, in/out
codepages of sessions started by this process, and the default
codepage for drawing in PM; is inherited by kids.  Does not affect the
out- and in-codepages of the session.]

=item ppid()

returns the PID of the parent process.

=item C<ppidOf($pid = $$)>

returns the PID of the parent process of $pid.  -1 on error.

=item C<sidOf($pid = $$)>

returns the session id of the process id $pid.  -1 on error.

=back

=head2 Control of VIO sessions

VIO applications are applications running in a text-mode session.

=over

=item out_codepage()

gets code page used for screen output (glyphs).  -1 means that a user font
was loaded.

=item C<out_codepage_set($cp)>

sets code page used for screen output (glyphs).  -1 switches to a preloaded
user font.  -2 switches off the preloaded user font.

=item in_codepage()

gets code page used for keyboard input.  0 means that a hardware codepage
is used.

=item C<in_codepage_set($cp)>

sets code page used for keyboard input.

=item C<($w, $h) = scrsize()>

width and height of the given console window in character cells.

=item C<scrsize_set([$w, ] $h)>

set height (and optionally width) of the given console window in
character cells.  Use 0 size to keep the old size.

=item C<($s, $e, $w, $a) = cursor()>

gets start/end lines of the blinking cursor in the charcell, its width
(1 on text modes) and attribute (-1 for hidden, in text modes other
values mean visible, in graphic modes color).

=item C<cursor_set($s, $e, [$w [, $a]])>

sets start/end lines of the blinking cursor in the charcell.  Negative
values mean percents of the character cell height.

=item screen()

gets a buffer with characters and attributes of the screen.

=item C<screen_set($buffer)>

restores the screen given the result of screen().  E.g., if the file
C<$file> contains the screen contents, then

  open IN, $file or die;
  binmode IN;
  read IN, $in, -s IN;
  $s = screen;
  $in .= qq(\0) x (length($s) - length $in);
  substr($in, length $s) = '';
  screen_set $in;

will restore the screen content even if the height of the window
changed (if the width changed, more manipulation is needed).

=back

=head2 Control of the process list

With the exception of Title_set(), all these calls require that PM is
running, they would not work under alternative Session Managers.

=over

=item process_entry()

returns a list of the following data:

=over

=item

Title of the process (in the C<Ctrl-Esc> list);

=item

window handle of switch entry of the process (in the C<Ctrl-Esc> list);

=item

window handle of the icon of the process;

=item

process handle of the owner of the entry in C<Ctrl-Esc> list;

=item

process id of the owner of the entry in C<Ctrl-Esc> list;

=item

session id of the owner of the entry in C<Ctrl-Esc> list;

=item

whether visible in C<Ctrl-Esc> list;

=item

whether item cannot be switched to (note that it is not actually
grayed in the C<Ctrl-Esc> list));

=item

whether participates in jump sequence;

=item

program type.  Possible values are:

     PROG_DEFAULT                       0
     PROG_FULLSCREEN                    1
     PROG_WINDOWABLEVIO                 2
     PROG_PM                            3
     PROG_VDM                           4
     PROG_WINDOWEDVDM                   7

Although there are several other program types for WIN-OS/2 programs,
these do not show up in this field. Instead, the PROG_VDM or
PROG_WINDOWEDVDM program types are used. For instance, for
PROG_31_STDSEAMLESSVDM, PROG_WINDOWEDVDM is used. This is because all
the WIN-OS/2 programs run in DOS sessions. For example, if a program
is a windowed WIN-OS/2 program, it runs in a PROG_WINDOWEDVDM
session. Likewise, if it's a full-screen WIN-OS/2 program, it runs in
a PROG_VDM session.

=item

switch-entry handle.

=back

Optional arguments: the pid and the window-handle of the application running
in the OS/2 session to query.

=item process_hentry()

similar to process_entry(), but returns a hash reference, the keys being

  title owner_hwnd icon_hwnd owner_phandle owner_pid owner_sid
  visible nonswitchable jumpable ptype sw_entry

(a copy of the list of keys is in @hentry_fields).

=item process_entries()

similar to process_entry(), but returns a list of array reference for all
the elements in the switch list (one controlling C<Ctrl-Esc> window).

=item process_hentries()

similar to process_hentry(), but returns a list of hash reference for all
the elements in the switch list (one controlling C<Ctrl-Esc> window).

=item change_entry()

changes a process entry, arguments are the same as process_entry() returns.

=item change_entryh()

Similar to change_entry(), but takes a hash reference as an argument.

=item process_hwnd()

returns the C<owner_hwnd> of the process entry (for VIO windowed processes
this is the frame window of the session).

=item Title()

returns the text of the task switch menu entry of the current session.
(There is no way to get this info in non-standard Session Managers.  This
implementation is a shortcut via process_entry().)

=item C<Title_set(newtitle)>

tries two different interfaces.  The Session Manager one does not work
with some windows (if the title is set from the start).
This is a limitation of OS/2, in such a case $^E is set to 372 (type

  help 372

for a funny - and wrong  - explanation ;-).  In such cases a
direct-manipulation of low-level entries is used (same as bothTitle_set()).
Keep in mind that some versions of OS/2 leak memory with such a manipulation.

=item winTitle()

returns text of the titlebar of the current process' window.

=item C<winTitle_set(newtitle)>

sets text of the titlebar of the current process' window.  The change does not
affect the text of the switch entry of the current window.

=item C<swTitle_set(newtitle)>

sets text of the task switch menu entry of the current process' window.  [There
is no API to query this title.]  Does it via SwitchEntry interface,
not Session manager interface.  The change does not affect the text of the
titlebar of the current window.

=item C<bothTitle_set(newtitle)>

sets text of the titlebar and task switch menu of the current process' window
via direct manipulation of the windows' texts.

=item C<SwitchToProgram([$sw_entry])>

switch to session given by a switch list handle (defaults to the entry of our process).

Use of this function causes another window (and its related windows)
of a PM session to appear on the front of the screen, or a switch to
another session in the case of a non-PM program. In either case,
the keyboard (and mouse for the non-PM case) input is directed to
the new program.

=back

=head2 Control of the PM windows

Some of these API's require sending a message to the specified window.
In such a case the process needs to be a PM process, or to be morphed
to a PM process via OS2::MorphPM().

For a temporary morphing to PM use L<OS2::localMorphPM class>.

Keep in mind that PM windows are engaged in 2 "orthogonal" window
trees, as well as in the z-order list.

One tree is given by the I<parent/child> relationship.  This
relationship affects drawing (child is drawn relative to its parent
(lower-left corner), and the drawing is clipped by the parent's
boundary; parent may request that I<it's> drawing is clipped to be
confined to the outsize of the childs and/or siblings' windows);
hiding; minimizing/restoring; and destroying windows.

Another tree (not necessarily connected?) is given by I<ownership>
relationship.  Ownership relationship assumes cooperation of the
engaged windows via passing messages on "important events"; e.g.,
scrollbars send information messages when the "bar" is moved, menus
send messages when an item is selected; frames
move/hide/unhide/minimize/restore/change-z-order-of owned frames when
the owner is moved/etc., and destroy the owned frames (even when these
frames are not descendants) when the owner is destroyed; etc.  [An
important restriction on ownership is that owner should be created by
the same thread as the owned thread, so they engage in the same
message queue.]

Windows may be in many different state: Focused (take keyboard events) or not,
Activated (=Frame windows in the I<parent/child> tree between the root and
the window with the focus; usually indicate such "active state" by titlebar
highlights, and take mouse events) or not, Enabled/Disabled (this influences
the ability to update the graphic, and may change appearance, as for 
enabled/disabled buttons), Visible/Hidden, Minimized/Maximized/Restored, Modal
or not, etc.

The APIs below all die() on error with the message being $^E.

=over

=item C<WindowText($hwnd)>

gets "a text content" of a window.  Requires (morphing to) PM.

=item C<WindowText_set($hwnd, $text)>

sets "a text content" of a window.  Requires (morphing to) PM.

=item C<($x, $y, $flags, $width, $height, $behind, @rest) = WindowPos($hwnd)>

gets window position info as 8 integers (of C<SWP>), in the order suitable
for WindowPos_set().  @rest is marked as "reserved" in PM docs.  $flags
is a combination of C<SWP_*> constants.

=item C<$hash = hWindowPos($hwnd)>

gets window position info as a hash reference; the keys are C<flags width
height x y behind hwnd reserved1 reserved2>.

Example:

  exit unless $hash->{flags} & SWP_MAXIMIZE;	# Maximized

=item C<WindowPos_set($hwnd, $x, $y, $flags = SWP_MOVE, $width = 0, $height = 0, $behind = HWND_TOP)>

Set state of the window: position, size, zorder, show/hide, activation,
minimize/maximize/restore etc.  Which of these operations to perform
is governed by $flags.

=item C<hWindowPos_set($hash, [$hwnd])>

Same as C<WindowPos_set>, but takes the position from keys C<fl width height
x y behind hwnd> of the hash referenced by $hash.  If $hwnd is explicitly
specified, it overrides C<$hash->{hwnd}>.  If $hash->{flags} is not specified,
it is calculated basing on the existing keys of $hash.  Requires (morphing to) PM.

Example:

  hWindowPos_set {flags => SWP_MAXIMIZE}, $hwnd; # Maximize

=item C<($pid, $tid) = WindowProcess($hwnd)>

gets I<PID> and I<TID> of the process associated to the window.

=item C<ClassName($hwnd)>

returns the class name of the window.

If this window is of any of the preregistered WC_* classes the class
name returned is in the form "#nnnnn", where "nnnnn" is a group
of up to five digits that corresponds to the value of the WC_* class name
constant.

=item WindowStyle($hwnd)