[p5sagit/p5-mst-13.2.git] / os2 / OS2 / Process / Process.pm

package OS2::Process;

$VERSION = 0.2;

require Exporter;
require DynaLoader;
#require AutoLoader;

@ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
	P_BACKGROUND
	P_DEBUG
	P_DEFAULT
	P_DETACH
	P_FOREGROUND
	P_FULLSCREEN
	P_MAXIMIZE
	P_MINIMIZE
	P_NOCLOSE
	P_NOSESSION
	P_NOWAIT
	P_OVERLAY
	P_PM
	P_QUOTE
	P_SESSION
	P_TILDE
	P_UNRELATED
	P_WAIT
	P_WINDOWED
	my_type
	file_type
	T_NOTSPEC
	T_NOTWINDOWCOMPAT
	T_WINDOWCOMPAT
	T_WINDOWAPI
	T_BOUND
	T_DLL
	T_DOS
	T_PHYSDRV
	T_VIRTDRV
	T_PROTDLL
	T_32BIT
	process_entry
	set_title
	get_title
);
sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.  If a constant is not found then control is passed
    # to the AUTOLOAD in AutoLoader.

    local($constname);
    ($constname = $AUTOLOAD) =~ s/.*:://;
    $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	if ($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
	    ($pack,$file,$line) = caller;
	    die "Your vendor has not defined OS2::Process macro $constname, used at $file line $line.
";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

bootstrap OS2::Process;

# Preloaded methods go here.

sub get_title () { (process_entry())[0] }

# Autoload methods go after __END__, and are processed by the autosplit program.

1;
__END__

=head1 NAME

OS2::Process - exports constants for system() call on OS2.

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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

=head2 Access to process properties

Additionaly, subroutines my_type(), process_entry() and
C<file_type(file)>, get_title() and C<set_title(newtitle)> are implemented.  
my_type() returns the type of the current process (one of 
"FS", "DOS", "VIO", "PM", "DETACH" and "UNKNOWN"), or C<undef> on error.

=over 4

=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 4

=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 4

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

=item process_entry()

returns a list of the following data:

=over 4

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

=back

=item C<set_title(newtitle)> 

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

=item get_title() 

is a shortcut implemented via process_entry().

=back

=head1 AUTHOR

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

=head1 SEE ALSO

C<spawn*>() system calls.

=cut
Commit	Line	Data
760ac839	1	package OS2::Process;
760ac839	2
7f61b687	3	$VERSION = 0.2;
7f61b687	4
760ac839	5	require Exporter;
760ac839	6	require DynaLoader;
7f61b687	7	#require AutoLoader;
760ac839	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
7f61b687	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
760ac839	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/) {
	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
7f61b687	77	sub get_title () { (process_entry())[0] }
7f61b687	78
760ac839	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
7f61b687	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
bbc7dcd2	131	=over 4
7f61b687	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
bbc7dcd2	138	=over 4
7f61b687	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
bbc7dcd2	161	=over 4
7f61b687	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
bbc7dcd2	207	=over 4
7f61b687	208
bbc7dcd2	209	=item *
7f61b687	210
	211	Title of the process (in the C<Ctrl-Esc> list);
	212
bbc7dcd2	213	=item *
7f61b687	214
	215	window handle of switch entry of the process (in the C<Ctrl-Esc> list);
	216
bbc7dcd2	217	=item *
7f61b687	218
	219	window handle of the icon of the process;
	220
bbc7dcd2	221	=item *
7f61b687	222
	223	process handle of the owner of the entry in C<Ctrl-Esc> list;
	224
bbc7dcd2	225	=item *
7f61b687	226
	227	process id of the owner of the entry in C<Ctrl-Esc> list;
	228
bbc7dcd2	229	=item *
7f61b687	230
	231	session id of the owner of the entry in C<Ctrl-Esc> list;
	232
bbc7dcd2	233	=item *
7f61b687	234
	235	whether visible in C<Ctrl-Esc> list;
	236
bbc7dcd2	237	=item *
7f61b687	238
	239	whether item cannot be switched to (note that it is not actually
	240	grayed in the C<Ctrl-Esc> list));
	241
bbc7dcd2	242	=item *
7f61b687	243
	244	whether participates in jump sequence;
	245
bbc7dcd2	246	=item *
7f61b687	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
7f61b687	266	=back
	267
	268	=item C<set_title(newtitle)>
	269
	270	- does not work with some windows (if the title is set from the start).
	271	This is a limitation of OS/2, in such a case $^E is set to 372 (type
	272
	273	help 372
	274
	275	for a funny - and wrong - explanation ;-).
	276
	277	=item get_title()
	278
	279	is a shortcut implemented via process_entry().
	280
	281	=back
	282
760ac839	283	=head1 AUTHOR
760ac839	284
7f61b687	285	Andreas Kaiser <ak@ananke.s.bawue.de>,
7f61b687	286	Ilya Zakharevich <ilya@math.ohio-state.edu>.
760ac839	287
	288	=head1 SEE ALSO
	289
	290	C<spawn*>() system calls.
	291
	292	=cut