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.

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 extension .exe if no extension is present (add extension . to suppress).

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

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

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.

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.

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.

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.

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 child's 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 (take keyboard events) or not, Activated (=Frame windows in the 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.

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

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.

Set window visibility state flag for the window for subsequent drawing. No actual drawing is done at this moment. Use ShowWindow($hwnd, $state) when redrawing is needed. While update is disabled, changes to the "window state" do not change the appearance of the window. Default: $update is TRUE.

Results in WM_ENABLED message sent to the window. Typically, this would change the appearance of the window. If at the moment of disabling focus is in the window (or a descendant), focus is lost (no focus anywhere). If focus is needed, it can be reassigned explicitly later.

these functions take $hwnd as an argument. IsWindowEnabled() queries the state changed by EnableWindow(), IsWindowVisible() the state changed by ShowWindow(), IsWindowShowing() is true if there is a part of the window visible on the screen.

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. All the functions in this group require (morphing to) PM.

gets a handle of a child of $hwndParent at ($x,$y). If $descedantsToo (defaulting to 1) 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.

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

gets the actual window handle of the PM desktop; most APIs accept the pseudo-handle HWND_DESKTOP instead. Keep in mind that the WPS desktop (one with WindowText() being "Desktop") is a different beast?!

Resets $^E. One may need to call it before the Win*-class APIs which may return 0 during normal operation. In such a case one should check both for return value being zero and $^E being non-zero. The following APIs do ResetWinError() themselves, thus do not need an explicit one:

gets the content of the clipboard. An optional argument is the format of the data in the clipboard (defaults to CF_TEXT). May croak with error PMERR_INVALID_HWND if no data of given $fmt is present.

Note that the usual convention is to have clipboard data with "\r\n" as line separators. This function will only work with clipboard data types which are delimited by "\0" byte (not included in the result).

Same as ClipbrdText_2byte(), but will assume that the shorts represent an Unicode string in UCS-2le format (little-endian 2-byte representation of Unicode), and will provide the result in Perl internal utf8 format (one short of input represents one Perl character).

Note that Firefox etc. export their selection in unicode types of this format.

sets the text content of the clipboard after removing old contents. Unless the optional argument $no_convert_nl is TRUE, will convert newlines to "\r\n". Another optional argument $fmt is the format of the data in the clipboard (should be an atom, defaults to CF_TEXT). Other arguments are as for ClipbrdData_set. Croaks on failure.

Returns a handle to clipboard data of the given format as an integer. Format defaults to CF_TEXT (in this case the handle is a memory address).

Clipboard should be opened before calling this function. May croak with error PMERR_INVALID_HWND if no data of given $fmt is present.

The result should not be used after clipboard is closed. Hence a return handle of type CLI_POINTER may need to be converted to a string and stored for future usage. Use MemoryRegionSize() to get a high estimate on the length of region addressed by this pointer; the actual length inside this region should be obtained by knowing particular format of data. E.g., it may be 0-byte terminated for string types, or 0-short terminated for wide-char string types.

Sets the clipboard data of format given by atom $fmt. Format defaults to CF_TEXT.

$fmtInfo should declare what type of handle $data is; it should be either CFI_POINTER, or CFI_HANDLE (possibly qualified by CFI_OWNERFREE and CFI_OWNERDRAW flags). It defaults to CFI_HANDLE for $fmt being standard bitmap, metafile, and palette (undocumented???) formats; otherwise defaults to CFI_POINTER. If format is CFI_POINTER, $data should contain the string to copy to clipboard; otherwise it should be an integer handle.

If $convert_nl is TRUE (the default), "\n" in $data are converted to "\r\n" pairs if $fmt is CFI_POINTER (as is the convention for text format of the clipboard) unless they are already in such a pair.

Sets the clipboard data of format given by atom $fmt. Format defaults to CF_TEXT. $data should be an address (in givable unnamed shared memory which should not be accessed or manipulated after this call) or a handle in a form of an integer.

Low-level access to the list of formats currently available in the clipboard. Returns the atom for the format of clipboard after $fmt. If $fmt is 0, returns the first format of clipboard. Returns 0 if $fmt is the last format. Example:

$addr should be a memory address (encoded as integer). This call finds the largest continuous region of memory belonging to the same memory object as $addr, and having the same memory flags as $addr. $flags is the value of the memory flag of $addr (see docs of DosQueryMem(3) for details). If optional argument $size_lim is given, the search is restricted to the region this many bytes long (after $addr).

($addr and $size are rounded so that all the memory pages containing the region are inspected.) Optional argument $interrupt (defaults to 1) specifies whether region scan should be interruptible by signals.

Use class OS2::localClipbrd to ensure that clipboard is closed even if the code in the block made a non-local exit.

The duration and frequency of the alarms can be changed by the OS2::SysValues_set(). The alarm frequency is defined to be in the range 0x0025 through 0x7FFF. The alarm is not generated if system value SV_ALARM is set to FALSE. The alarms are dependent on the device capability.

Since flashing window persists even when application ends, it is very important to protect the switching off flashing from non-local exits. Use the class OS2::localFlashWindow for this. Creating the object of this class starts flashing the window until the object is destroyed. The above example becomes:

Shows a simple messagebox with (optional) icon, message $text, and one or more buttons to dismiss the box. Returns the indicator of which action was taken by the user. If optional argument $title is not given, the title is constructed from the application name. The optional argument $flags describes the appearance of the box; the default is to have Cancel button, INFO-style icon, and a border for moving. Flags should be a combination of

Buttons on the box: or Button Group
MB_OK OK
MB_OKCANCEL both OK and CANCEL
MB_CANCEL CANCEL
MB_ENTER ENTER
MB_ENTERCANCEL both ENTER and CANCEL
MB_RETRYCANCEL both RETRY and CANCEL
MB_ABORTRETRYIGNORE ABORT, RETRY, and IGNORE
MB_YESNO both YES and NO
MB_YESNOCANCEL YES, NO, and CANCEL
Color or Icon
MB_ICONHAND a small red circle with a red line across it.
MB_ERROR a small red circle with a red line across it.
MB_ICONASTERISK an information (i) icon.
MB_INFORMATION an information (i) icon.
MB_ICONEXCLAMATION an exclamation point (!) icon.
MB_WARNING an exclamation point (!) icon.
MB_ICONQUESTION a question mark (?) icon.
MB_QUERY a question mark (?) icon.
MB_NOICON No icon.
Default action (i.e., focussed button; default is MB_DEFBUTTON1)
MB_DEFBUTTON1 The first button is the default selection.
MB_DEFBUTTON2 The second button is the default selection.
MB_DEFBUTTON3 The third button is the default selection.
Modality indicator
MB_APPLMODAL Message box is application modal (default).
MB_SYSTEMMODAL Message box is system modal.
Mobility indicator
MB_MOVEABLE Message box is moveable.

With MB_MOVEABLE the message box is displayed with a title bar and a system menu, which shows only the Move, Close, and Task Manager choices, which can be selected either by use of the pointing device or by accelerator keys. If the user selects Close, the message box is removed and the usResponse is set to MBID_CANCEL, whether or not a cancel button existed within the message box.

Esc key dismisses the dialogue only if CANCEL button is present; the return value is MBID_CANCEL.

With MB_APPLMODAL the owner of the dialogue is disabled; therefore, do not specify the owner as the parent if this option is used.

Additionally, the following flag is possible, but probably not very useful:

Help button
MB_HELP a HELP button appears, which sends a WM_HELP
message is sent to the window procedure of the
message box.

Similar to MessageBox(), but allows more flexible choice of button texts and the icon. $buttons_Icon is a reference to an array with information about buttons and the icon to use; the semantic of this array is the same as for argument list of process_MB2_INFO(). The default value will show one button Dismiss which will return 0x1000.

Other optional arguments are the same as for MessageBox().

NOTE. Remark about MBID_CANCEL in presence of MB_MOVABLE is equally applicable to MessageBox() and MessageBox2().

low-level workhorse to implement MessageBox2(); calculates the second argument of _MessageBox2(). $buttons is a reference to array of button descriptions. $iconID is either an ID of icon for the message box, or a string of the form "SP#number"; in the latter case the number's system icon is chosen; this field is ignored unless $flags contains MB_CUSTOMICON flag. $flags has the same meaning as mobility, modality, and icon flags for MessageBox() with addition of extra flags

MB_CUSTOMICON Use a custom icon specified in hIcon.
MB_NONMODAL Message box is nonmodal

$flags defaults to MB_INFORMATION or MB_CUSTOMICON (depending on whether $iconID is non-0), combined with MB_MOVABLE.

Each button's description takes two elements of the description array, appearance description, and the return value of MessageBox2() if this button is selected. The appearance description is either an array reference of the form [$button_Text, $button_Style], or the same without $button_Style (then style is BS_DEFAULT, making this button the default) or just $button_Text (with "normal" style). E.g., the list

Foo => 100, Bar => 101, [Baz] => 102

will show three buttons Foo, Bar, Baz with Baz being the default button; pressing buttons return 100, 101, or 102 correspondingly.

In particular, exactly one button should have BS_DEFAULT style (e.g., given as [$button_Name]); otherwise the message box will not have keyboard focus! (The only exception is the case of one button; then [$button_Name] can be replaced (for convenience) with plain $button_Name.)

If text of the button contains character ~, the following character becomes the keyboard accelerator for this button. One can also get the handle of system icons directly, so 'SP#22' can be replaced by OS2::Process::get_pointer(22); see also SPTR_* constants.

NOTE With MB_NONMODAL the program continues after displaying the nonmodal message box. The message box remains visible until the owner window destroys it. Two notification messages, WM_MSGBOXINIT and WM_MSGBOXDISMISS, are used to support this non-modality.

Function os2constant($name) returns the value of the constant; to decrease the memory usage of this package, only the constants used by APIs called by Perl functions in this package are made available.

For direct access, see also the "EXPORTS" section; the latter way may also provide some performance advantages, since the value of the constant is cached.

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.

In addition to symbols described above, the following constants (available also via module OS2::Process::Const) are exportable. Note that these symbols live in package OS2::Process::Const, they are not available by full name through OS2::Process!