os2/OS2/Process/Process.pm

   1 package OS2::Process;
   2
   3 $VERSION = 0.2;
   4
   5 require Exporter;
   6 require DynaLoader;
   7 #require AutoLoader;
   8
   9 @ISA = qw(Exporter DynaLoader);
  10 # Items to export into callers namespace by default. Note: do not export
  11 # names by default without a very good reason. Use EXPORT_OK instead.
  12 # Do not simply export all your public functions/methods/constants.
  13 @EXPORT = qw(
  14         P_BACKGROUND
  15         P_DEBUG
  16         P_DEFAULT
  17         P_DETACH
  18         P_FOREGROUND
  19         P_FULLSCREEN
  20         P_MAXIMIZE
  21         P_MINIMIZE
  22         P_NOCLOSE
  23         P_NOSESSION
  24         P_NOWAIT
  25         P_OVERLAY
  26         P_PM
  27         P_QUOTE
  28         P_SESSION
  29         P_TILDE
  30         P_UNRELATED
  31         P_WAIT
  32         P_WINDOWED
  33         my_type
  34         file_type
  35         T_NOTSPEC
  36         T_NOTWINDOWCOMPAT
  37         T_WINDOWCOMPAT
  38         T_WINDOWAPI
  39         T_BOUND
  40         T_DLL
  41         T_DOS
  42         T_PHYSDRV
  43         T_VIRTDRV
  44         T_PROTDLL
  45         T_32BIT
  46         process_entry
  47         set_title
  48         get_title
  49 );
  50 sub AUTOLOAD {
  51     # This AUTOLOAD is used to 'autoload' constants from the constant()
  52     # XS function.  If a constant is not found then control is passed
  53     # to the AUTOLOAD in AutoLoader.
  54
  55     local($constname);
  56     ($constname = $AUTOLOAD) =~ s/.*:://;
  57     $val = constant($constname, @_ ? $_[0] : 0);
  58     if ($! != 0) {
  59         if ($! =~ /Invalid/ || $!{EINVAL}) {
  60             $AutoLoader::AUTOLOAD = $AUTOLOAD;
  61             goto &AutoLoader::AUTOLOAD;
  62         }
  63         else {
  64             ($pack,$file,$line) = caller;
  65             die "Your vendor has not defined OS2::Process macro $constname, used at $file line $line.
  66 ";
  67         }
  68     }
  69     eval "sub $AUTOLOAD { $val }";
  70     goto &$AUTOLOAD;
  71 }
  72
  73 bootstrap OS2::Process;
  74
  75 # Preloaded methods go here.
  76
  77 sub get_title () { (process_entry())[0] }
  78
  79 # Autoload methods go after __END__, and are processed by the autosplit program.
  80
  81 1;
  82 __END__
  83
  84 =head1 NAME
  85
  86 OS2::Process - exports constants for system() call on OS2.
  87
  88 =head1 SYNOPSIS
  89
  90     use OS2::Process;
  91     $pid = system(P_PM+P_BACKGROUND, "epm.exe");
  92
  93 =head1 DESCRIPTION
  94
  95 the builtin function system() under OS/2 allows an optional first
  96 argument which denotes the mode of the process. Note that this argument is
  97 recognized only if it is strictly numerical.
  98
  99 You can use either one of the process modes:
 100
 101         P_WAIT (0)      = wait until child terminates (default)
 102         P_NOWAIT        = do not wait until child terminates
 103         P_SESSION       = new session
 104         P_DETACH        = detached
 105         P_PM            = PM program
 106
 107 and optionally add PM and session option bits:
 108
 109         P_DEFAULT (0)   = default
 110         P_MINIMIZE      = minimized
 111         P_MAXIMIZE      = maximized
 112         P_FULLSCREEN    = fullscreen (session only)
 113         P_WINDOWED      = windowed (session only)
 114
 115         P_FOREGROUND    = foreground (if running in foreground)
 116         P_BACKGROUND    = background
 117
 118         P_NOCLOSE       = don't close window on exit (session only)
 119
 120         P_QUOTE         = quote all arguments
 121         P_TILDE         = MKS argument passing convention
 122         P_UNRELATED     = do not kill child when father terminates
 123
 124 =head2 Access to process properties
 125
 126 Additionaly, subroutines my_type(), process_entry() and
 127 C<file_type(file)>, get_title() and C<set_title(newtitle)> are implemented.
 128 my_type() returns the type of the current process (one of
 129 "FS", "DOS", "VIO", "PM", "DETACH" and "UNKNOWN"), or C<undef> on error.
 130
 131 =over
 132
 133 =item C<file_type(file)>
 134
 135 returns the type of the executable file C<file>, or
 136 dies on error.  The bits 0-2 of the result contain one of the values
 137
 138 =over
 139
 140 =item C<T_NOTSPEC> (0)
 141
 142 Application type is not specified in the executable header.
 143
 144 =item C<T_NOTWINDOWCOMPAT> (1)
 145
 146 Application type is not-window-compatible.
 147
 148 =item C<T_WINDOWCOMPAT> (2)
 149
 150 Application type is window-compatible.
 151
 152 =item C<T_WINDOWAPI> (3)
 153
 154 Application type is window-API.
 155
 156 =back
 157
 158 The remaining bits should be masked with the following values to
 159 determine the type of the executable:
 160
 161 =over
 162
 163 =item C<T_BOUND> (8)
 164
 165 Set to 1 if the executable file has been "bound" (by the BIND command)
 166 as a Family API application. Bits 0, 1, and 2 still apply.
 167
 168 =item C<T_DLL> (0x10)
 169
 170 Set to 1 if the executable file is a dynamic link library (DLL)
 171 module. Bits 0, 1, 2, 3, and 5 will be set to 0.
 172
 173 =item C<T_DOS> (0x20)
 174
 175 Set to 1 if the executable file is in PC/DOS format. Bits 0, 1, 2, 3,
 176 and 4 will be set to 0.
 177
 178 =item C<T_PHYSDRV> (0x40)
 179
 180 Set to 1 if the executable file is a physical device driver.
 181
 182 =item C<T_VIRTDRV> (0x80)
 183
 184 Set to 1 if the executable file is a virtual device driver.
 185
 186 =item C<T_PROTDLL> (0x100)
 187
 188 Set to 1 if the executable file is a protected-memory dynamic link
 189 library module.
 190
 191 =item C<T_32BIT> (0x4000)
 192
 193 Set to 1 for 32-bit executable files.
 194
 195 =back
 196
 197 file_type() may croak with one of the strings C<"Invalid EXE
 198 signature"> or C<"EXE marked invalid"> to indicate typical error
 199 conditions.  If given non-absolute path, will look on C<PATH>, will
 200 add extention F<.exe> if no extension is present (add extension F<.>
 201 to suppress).
 202
 203 =item process_entry()
 204
 205 returns a list of the following data:
 206
 207 =over
 208
 209 =item
 210
 211 Title of the process (in the C<Ctrl-Esc> list);
 212
 213 =item
 214
 215 window handle of switch entry of the process (in the C<Ctrl-Esc> list);
 216
 217 =item
 218
 219 window handle of the icon of the process;
 220
 221 =item
 222
 223 process handle of the owner of the entry in C<Ctrl-Esc> list;
 224
 225 =item
 226
 227 process id of the owner of the entry in C<Ctrl-Esc> list;
 228
 229 =item
 230
 231 session id of the owner of the entry in C<Ctrl-Esc> list;
 232
 233 =item
 234
 235 whether visible in C<Ctrl-Esc> list;
 236
 237 =item
 238
 239 whether item cannot be switched to (note that it is not actually
 240 grayed in the C<Ctrl-Esc> list));
 241
 242 =item
 243
 244 whether participates in jump sequence;
 245
 246 =item
 247
 248 program type.  Possible values are:
 249
 250      PROG_DEFAULT                       0
 251      PROG_FULLSCREEN                    1
 252      PROG_WINDOWABLEVIO                 2
 253      PROG_PM                            3
 254      PROG_VDM                           4
 255      PROG_WINDOWEDVDM                   7
 256
 257 Although there are several other program types for WIN-OS/2 programs,
 258 these do not show up in this field. Instead, the PROG_VDM or
 259 PROG_WINDOWEDVDM program types are used. For instance, for
 260 PROG_31_STDSEAMLESSVDM, PROG_WINDOWEDVDM is used. This is because all
 261 the WIN-OS/2 programs run in DOS sessions. For example, if a program
 262 is a windowed WIN-OS/2 program, it runs in a PROG_WINDOWEDVDM
 263 session. Likewise, if it's a full-screen WIN-OS/2 program, it runs in
 264 a PROG_VDM session.
 265
 266
 267 =back
 268
 269 =item C<set_title(newtitle)>
 270
 271 - does not work with some windows (if the title is set from the start).
 272 This is a limitation of OS/2, in such a case $^E is set to 372 (type
 273
 274   help 372
 275
 276 for a funny - and wrong  - explanation ;-).
 277
 278 =item get_title()
 279
 280 is a shortcut implemented via process_entry().
 281
 282 =back
 283
 284 =head1 AUTHOR
 285
 286 Andreas Kaiser <ak@ananke.s.bawue.de>,
 287 Ilya Zakharevich <ilya@math.ohio-state.edu>.
 288
 289 =head1 SEE ALSO
 290
 291 C<spawn*>() system calls.
 292
 293 =cut