NAME

OS2::Process - exports constants for system() call, and process control on OS2.

SYNOPSIS

    use OS2::Process;
    $pid = system(P_PM | P_BACKGROUND, "epm.exe");

DESCRIPTION

Optional argument to system()

the builtin function system() under OS/2 allows an optional first argument which denotes the mode of the process. Note that this argument is recognized only if it is strictly numerical.

You can use either one of the process modes:

        P_WAIT (0)      = wait until child terminates (default)
        P_NOWAIT        = do not wait until child terminates
        P_SESSION       = new session
        P_DETACH        = detached
        P_PM            = PM program

and optionally add PM and session option bits:

        P_DEFAULT (0)   = default
        P_MINIMIZE      = minimized
        P_MAXIMIZE      = maximized
        P_FULLSCREEN    = fullscreen (session only)
        P_WINDOWED      = windowed (session only)

        P_FOREGROUND    = foreground (if running in foreground)
        P_BACKGROUND    = background

        P_NOCLOSE       = don't close window on exit (session only)

        P_QUOTE         = quote all arguments
        P_TILDE         = MKS argument passing convention
        P_UNRELATED     = do not kill child when father terminates

Access to process properties

On OS/2 processes have the usual parent/child semantic; additionally, there is a hierarchy of sessions with their own 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.

my_type()

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

file_type(file)

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

T_NOTSPEC (0): Application type is not specified in the executable header.
T_NOTWINDOWCOMPAT (1): Application type is not-window-compatible.
T_WINDOWCOMPAT (2): Application type is window-compatible.
T_WINDOWAPI (3): Application type is window-API.

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

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.
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.
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.
T_PHYSDRV (0x40): Set to 1 if the executable file is a physical device driver.
T_VIRTDRV (0x80): Set to 1 if the executable file is a virtual device driver.
T_PROTDLL (0x100): Set to 1 if the executable file is a protected-memory dynamic link library module.
T_32BIT (0x4000): Set to 1 for 32-bit executable files.

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

@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).

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.]

ppid()

returns the PID of the parent process.

ppidOf($pid = $$)

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

sidOf($pid = $$)

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

Control of VIO sessions

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

out_codepage(): gets code page used for screen output (glyphs). -1 means that a user font was loaded.
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.
in_codepage(): gets code page used for keyboard input. 0 means that a hardware codepage is used.
in_codepage_set($cp): sets code page used for keyboard input.
($w, $h) = scrsize(): width and height of the given console window in character cells.
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.
($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).
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.
screen(): gets a buffer with characters and attributes of the screen.
screen_set($buffer): restores the screen given the result of screen().

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.

process_entry()

returns a list of the following data:

Title of the process (in the Ctrl-Esc list);
window handle of switch entry of the process (in the Ctrl-Esc list);
window handle of the icon of the process;
process handle of the owner of the entry in Ctrl-Esc list;
process id of the owner of the entry in Ctrl-Esc list;
session id of the owner of the entry in Ctrl-Esc list;
whether visible in Ctrl-Esc list;
whether item cannot be switched to (note that it is not actually grayed in the Ctrl-Esc list));
whether participates in jump sequence;
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.
switch-entry handle.

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

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).

process_entries()

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

process_hentries()

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

change_entry()

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

change_entryh()

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

Title()

returns a title 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().)

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. Keep in mind that some versions of OS/2 leak memory with such a manipulation.

SwitchToProgram($sw_entry)

switch to session given by a switch list handle.

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.

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 "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 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 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 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, Activated (=Windows in the parent/child tree between the root and the window with focus; usually indicate such "active state" by titlebar highlights), Enabled/Disabled (this influences *an ability* to receive user input (be focused?), and may change appearance, as for enabled/disabled buttons), Visible/Hidden, Minimized/Maximized/Restored, Modal, etc.

WindowText($hwnd)

gets "a text content" of a window.

WindowText_set($hwnd, $text)

sets "a text content" of a window.

WindowPos($hwnd)

gets window position info as 8 integers (of SWP), in the order suitable for WindowPos_set(): $x, $y, $fl, $w, $h, $behind, @rest.

WindowPos_set($hwnd, $x, $y, $flags = SWP_MOVE, $wid = 0, $h = 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.

WindowProcess($hwnd)

gets PID and TID of the process associated to the window.

ActiveWindow([$parentHwnd])

gets the active subwindow's handle for $parentHwnd or desktop. Returns FALSE if none.

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.

FocusWindow()

returns the handle of the focus window. Optional argument for specifying the desktop to use.

FocusWindow_set($hwnd)

set the focus window by handle. Optional argument for specifying the desktop to use. E.g, the first entry in program_entries() is the Ctrl-Esc list. To show it

       WinShowWindow( wlhwnd, TRUE );
       WinSetFocus( HWND_DESKTOP, wlhwnd );
       WinSwitchToProgram(wlhswitch);

ShowWindow($hwnd [, $show])

Set visible/hidden flag of the window. Default: $show is TRUE.

PostMsg($hwnd, $msg, $mp1, $mp2)

post message to a window. The meaning of $mp1, $mp2 is specific for each message id $msg, they default to 0. E.g., in C it is done similar to

    /* Emulate `Restore' */
    WinPostMsg(SwitchBlock.tswe[i].swctl.hwnd, WM_SYSCOMMAND,
               MPFROMSHORT(SC_RESTORE),        0);

    /* Emulate `Show-Contextmenu' (Double-Click-2) */
    hwndParent = WinQueryFocus(HWND_DESKTOP);
    hwndActive = WinQueryActiveWindow(hwndParent);
    WinPostMsg(hwndActive, WM_CONTEXTMENU, MPFROM2SHORT(0,0), MPFROMLONG(0));

    /* Emulate `Close' */
    WinPostMsg(pSWB->aswentry[i].swctl.hwnd, WM_CLOSE, 0, 0);

    /* Same but softer: */
    WinPostMsg(hwndactive, WM_SAVEAPPLICATION, 0L, 0L);
    WinPostMsg(hwndactive, WM_CLOSE, 0L, 0L));
    WinPostMsg(hwndactive, WM_QUIT, 0L, 0L));

$eh = BeginEnumWindows($hwnd)

starts enumerating immediate child windows of $hwnd in z-order. The enumeration reflects the state at the moment of BeginEnumWindows() calls; use IsWindow() to be sure.

$kid_hwnd = GetNextWindow($eh)

gets the next kid in the list. Gets 0 on error or when the list ends.

EndEnumWindows($eh)

End enumeration and release the list.

@list = ChildWindows($hwnd)

returns the list of child windows at the moment of the call. Same remark as for enumeration interface applies. Example of usage:

  sub l {
    my ($o,$h) = @_;
    printf ' ' x $o . "%#x\n", $h;
    l($o+2,$_) for ChildWindows $h;
  }
  l 0, $HWND_DESKTOP

IsWindow($hwnd)

true if the window handle is still valid.

QueryWindow($hwnd, $type)

gets the handle of a related window. $type should be one of QW_* constants.

IsChild($hwnd, $parent)

return TRUE if $hwnd is a descendant of $parent.

WindowFromId($hwnd, $id)

return a window handle of a child of $hwnd with the given $id.

  hwndSysMenu = WinWindowFromID(hwndDlg, FID_SYSMENU);
  WinSendMsg(hwndSysMenu, MM_SETITEMATTR,
      MPFROM2SHORT(SC_CLOSE, TRUE),
      MPFROM2SHORT(MIA_DISABLED, MIA_DISABLED));

WindowFromPoint($x, $y [, $hwndParent [, $descedantsToo]])

gets a handle of a child of $hwndParent at ($x,$y). If $descedantsToo (defaulting to 0) then children of children may be returned too. May return $hwndParent (defaults to desktop) if no suitable children are found, or 0 if the point is outside the parent.

$x and $y are relative to $hwndParent.

EnumDlgItem($dlgHwnd, $type [, $relativeHwnd])

gets a dialog item window handle for an item of type $type of $dlgHwnd relative to $relativeHwnd, which is descendant of $dlgHwnd. $relativeHwnd may be specified if $type is EDI_FIRSTTABITEM or EDI_LASTTABITEM.

The return is always an immediate child of hwndDlg, even if hwnd is not an immediate child window. $type may be

EDI_FIRSTGROUPITEM: First item in the same group.
EDI_FIRSTTABITEM: First item in dialog with style WS_TABSTOP. hwnd is ignored.
EDI_LASTGROUPITEM: Last item in the same group.
EDI_LASTTABITEM: Last item in dialog with style WS_TABSTOP. hwnd is ignored.
EDI_NEXTGROUPITEM: Next item in the same group. Wraps around to beginning of group when the end of the group is reached.
EDI_NEXTTABITEM: Next item with style WS_TABSTOP. Wraps around to beginning of dialog item list when end is reached.
EDI_PREVGROUPITEM: Previous item in the same group. Wraps around to end of group when the start of the group is reached. For information on the WS_GROUP style, see Window Styles.
EDI_PREVTABITEM: Previous item with style WS_TABSTOP. Wraps around to end of dialog item list when beginning is reached.

OS2::localMorphPM class

This class morphs the process to PM for the duration of the given context.

  {
    my $h = OS2::localMorphPM->new(0);
    # Do something
  }

The argument has the same meaning as one to OS2::MorphPM(). Calls can nest with internal ones being NOPs.

TODO

Constants (currently one needs to get them looking in a header file):

  HWND_*
  WM_*                  /* Separate module? */
  SC_*
  SWP_*
  WC_*
  PROG_*
  QW_*
  EDI_*
  WS_*

Show/Hide, Enable/Disable (WinShowWindow(), WinIsWindowVisible(), WinEnableWindow(), WinIsWindowEnabled()).

Maximize/minimize/restore via WindowPos_set(), check via checking WS_MAXIMIZED/WS_MINIMIZED flags (how to get them?).

$^E

the majority of the APIs of this module set $^E on failure (no matter whether they die() on failure or not). By the semantic of PM API which returns something other than a boolean, it is impossible to distinguish failure from a "normal" 0-return. In such cases $^E == 0 indicates an absence of error.

BUGS

whether a given API dies or returns FALSE/empty-list on error may be confusing. This may change in the future.

AUTHOR

Andreas Kaiser <ak@ananke.s.bawue.de>, Ilya Zakharevich <ilya@math.ohio-state.edu>.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)