---------------------------------------------------------------------------
Perl for NT (based on Perl 4.036)
Release notes 

----------------------------------------------------------------------------
7/8/93
Second release
----------------------------------------------------------------------------

IMPORTANT CHANGE FROM THE LAST RELEASE!  All of the pre-defined
variables for registry access (such as $HKEY_LOCAL_MACHINE) have been
removed from the interpreter and moved into the file registry.pl. This
file can be accessed by putting a 'require' statment in your perl
script, i.e.:

		require "registry.pl";

This was due to the large number of constants required for accessing
the registry. Rather than clutter the internals of the interpreter it
was thought easier to move the values into a file and require it when
needed. 

This release adds the pre-defined subroutine &Spawn, that creates an
independent process. &Spawn allows creation of processes for
bi-directional communication using pipes. It's usage is:

	&Spawn ("cmd /c dir/w", $pid, readHandle, writeHandle, errHandle)
		|| die "cannot spawn cmd.exe: $!\n";

The read, write, and error handles are optional. If not specified
the new process inherits the creating processes input, output, and
error file handles.

The perl scripts regupdat.cmd and uninstal.cmd were added to the
distribution to allow quick modification and removal of perl's keys in 
the NT registry. This is for folks that like to move the installed
version around. They are not normally needed, since the registry keys
are automatically updated by the setup installation procedure.

More testing has been done on this release. All the registry access
routines that access keys and values have been tested. The routines
that modify the structure of the registry (&RegLoadKey,
&RegReplaceKey, &RegRestoreKey, &RegSaveKey, and &RegUnloadKey) have
not been tested, since I have yet to discover the NT privledge that a
process needs to modify the registry structure :-(.

Some bugs were discovered in the initial release (gasp!) and these
have been fixed. Most were in specifying the size of data items
written to the registry.

Error reporting still has problems because there are two sets of error
numbers, one for the C runtime library (CRT) and the other for Win32
functions.  The numbers overlap, so there is no easy way to determine
whether the error came from the CRT or from a Win32 function. Until a
better mechanism is developed, the CRT errors are reported for numbers
that overlap.

Some mysterious problem with cmd.exe and command file execution has
required a change in the way perl scripts are executed from command
files. The perl switch '-S' should be removed from the command line
where perl is run. This is a change for build 438 of NT. If you are
running on an earlier version, then the -S switch will still be
required.


----------------------------------------------------------------------------
5/20/93
Initial release
----------------------------------------------------------------------------

This is the initial release of Perl for NT. In addition to winsock
access, this release adds user-defined routines to access the NT
Registry database. For information on how to use the registry access
routines, see the new file registry.txt.


----------------------------------------------------------------------------
5/12/93
Second Beta Release
----------------------------------------------------------------------------

This release of Perl for NT has support for the Winsock sockets
interface. Minimal testing has been done, but this version will
connect to an ftp server and the echo service on my system. See the
sample program sock.cmd in the eg directory. Supported functions are:

		accept
		bind
		connect
		getpeername
		getsockname
		getsockopt
		listen
		recv
		send
		setsockopt
		shutdown
		socket
		gethostbyname
		getservbyname
		getprotobyname
		
Remember that Winsock only supported Internet domain sockets. For more
information read the help file "Windows Sockets Help" that is
delivered with the Win32 Software Development Kit.

Also, a problem was seen during installation. Some sites haven't
delivered PROGTOOLS and so don't have the unzip.exe executable. To fix
this, the delivery site now has a copy of unzip.exe. When delivering
perl, please copy all of the files from the delivery system
(ajax.b11.ingr.com) to your system, then run the installation script.

----------------------------------------------------------------------------
5/6/93
First Beta Release
----------------------------------------------------------------------------

This is the first Beta release of the Perl port to Windows NT. Most of
the testing for this release (97.62% ;-) has been done on the March
Beta release of NT. The testing that was done on the December release
turned up some problems in the C runtime library that have not been
solved, so perl on the December release in mostly an unknown quantity.

There are not many external differences between this release and the
last Alpha release; mostly just additional tests added to the test
suite.

Internally, changes have been made that should speed up script
processing. Process creation for backticks, systems, and opens to/from
piped commands have been optimized so that cmd.exe is not started
unless the command string contains i/o redirection or pipes.

For information about differences between the Unix release of Perl and
this release, read the sections of this file starting with "General
Information". For information on what features of perl are supported,
have been tested, etc., see the file status.txt. For example perl
scripts that run under NT, including a script that will make an
existing perl script runnable under NT, see the files in the eg
directory. 

----------------------------------------------------------------------------
4/28/93
Second Alpha release
----------------------------------------------------------------------------

This release fixes a bug in the initial release and updates the
testing status of features listed in status.txt.  It also renames some
of the scripts in the lib directory to fit the 8.3 file name
restrictions.

The following library scripts were renamed:

    lib\timelocal.pl  -> lib\timelocl.pl
    lib\shellwords.pl -> lib\shwords.pl
    lib\newgetopt.pl  -> lib\ngetopt.pl
    lib\importenv.pl  -> lib\impenv.pl
    lib\finddepth.pl  -> lib\finddep.pl
    lib\exceptions.pl -> lib\except.pl


NOTE: This release has only been tested on the March Beta release of
NT. I'll be testing perl on the December release in the next few days
and will determine if it's feasible to make the changes needed to run
on December.  It's possible that there will be two releases, one for 
December and one for March, but that decision will have to be made
based on the amount of work required to create and maintain a December
version.

A list of the features in status.txt that have changed from the first
release:  

        Command line options:

            -a: changed from Untested to Tested
            -i: changed from Untested to Tested
            -S: changed from Untested to Tested
            -U: changed from Untested to NYI

        File test operators

            -c: changed from Untested to N/A
            -b: changed from Untested to N/A
            -o: changed from Untested to Tested
            -p: changed from Untested to NYI
            -f: changed from Untested to Tested
            -d: changed from Untested to Tested
            -e: changed from Untested to Tested
            -z: changed from Untested to Tested
            -s: changed from Untested to Tested
            -t: changed from Untested to Tested
            -w: changed from Untested to Tested
            -x: changed from Untested to Tested
            -R: changed from Untested to Tested
            -W: changed from Untested to Tested
            -X: changed from Untested to Tested
            -O: changed from Untested to Tested
            -T: changed from Untested to Tested
            -B: changed from Untested to Tested
            -M: changed from Untested to Tested
            -A: changed from Untested to Tested
            -C: changed from Untested to Tested

        Literals

            Here-Is:: changed from Untested to Tested

        Search and Replace Functions

            ?<pattern>?: changed from Untested to Tested
            /<pattern>/: changed from Untested to Tested

        System Interaction

            getlogin: changed from Untested to NYI


        Arithmetic functions

            atan2: changed from Untested to Tested
            sin: changed from Untested to Tested
            sqrt: changed from Untested to Tested
            log: changed from Untested to Tested
            int: changed from Untested to Tested
            cos: changed from Untested to Tested
            exp: changed from Untested to Tested


        File operations

            truncate: changed from NYI to Tested

        Input / Output

            binmode: changed from Untested to Tested

        Miscellaneous
            scalar: changed from Untested to Tested
            wantarray: changed from Untested to Tested

        Special Arrays

            @INC: changed from Untested to Tested

        The Perl Debugger

            L: changed from Untested to Tested
            X: changed from Untested to Tested
            S: changed from Untested to Tested
            D: changed from Untested to Tested
            d: changed from Untested to Tested
            w: changed from Untested to Tested
            r: changed from Untested to Tested


        Environment Variables

            PERLLIB: changed from Untested to Tested

        Perl Library Routines

            abbrev.pl: changed from Untested to Tested
            ctime.pl: changed from Untested to Tested
            find.pl: changed from NYI to Tested

Problems that were fixed:

        - Fixed default search path for perl library routines to
          contain the drive letter as well as the path. This currently
          is c:\win32app\ingr\perl\lib. Later releases are planned to
          have the ability to be installed on any drive.


----------------------------------------------------------------------------
4/22/93 
First Alpha Release
---------------------------------------------------------------------------

These are the release notes for the Alpha release of Perl for NT. The
port was done by starting with the DOS port, then discarding most of
that and reimplementing the functions required. For a complete list of
the perl features that we plan to support, see the file status.txt.
This file also indicates the testing status of each feature.


---------------------------------------------------------------------------
General Information
---------------------------------------------------------------------------

There are some changes in how perl scripts are written and invoked on
NT (versus how they are invoked on Unix).  However, these changes
should not be too radical to make perl unusable for NT. In general be
very careful of things depending on wild card expansion and specifics
of command line arguments (i.e. how /bin/sh, or any shell for that
matter, treats quotes). The NT command interpreter (cmd.exe) does not
treat single quotes in a similar manner as unix shells, in fact it
treats single quotes as just another character.

Getting your perl script to execute without explicitly invoking perl
takes some strange contortions. Trying to emulate the Unix sharp-bang
facility (#!) was interesting. Here is an incantation that we've found
to work:

    1. Give your perl script a ".cmd" extension. This tells the
       command interpreter (cmd.exe) that it's ok to execute.
       (No, really!).

    2. Put the following text at the start of your file:

        @rem = '
        @echo off
        perl %0.cmd %1 %2 %3 %4 %5 %6 %7 %8 %9
        goto endofperl
        @rem ';

    3. Now type in your perl script.

    4. Put the following lines at the end of your perl script
        __END__
        :endofperl

The five lines of #2 are both legal perl and legal commands for the
command interpreter, cmd.exe. The first time the file is executed (by
cmd.exe) the command interpreter will interpret the "@rem -'" as a
comment and the "@echo off" as a command to turn off echoing commands.
It will then execute perl with the script name as the first argument
and the parameters to the command file as arguments to perl. When perl
sees the file the first five lines are interpreted as an assignment to
the array @rem. When perl finished executing the perl statements it
will terminate and the goto statememt will be executed by the command
interpreter.

The __END__ line of #4 is magic to perl and tells the interpreter that
there is no more legal perl source in the file. The :endofperl is th
target of the command interpreter's goto statement from #2.

Make sure that when you run the script, you do so without the
extension, since the %0 parameter to the command interpreter is
exactly what you typed. 

It's ugly, but it works. Note that there is a now a perl script in the
eg directory named ntcvt.cmd. It will perform the above steps on an
existing perl script. 




---------------------------------------------------------------------------
Globbing (wildcard expansion)
---------------------------------------------------------------------------

Many scripts depend on a unix shell (sh, ksh, csh, etc) to do wildcard
expansion. This construct is often used in perl scripts:

        $srcfiles = `echo *.c src/*.c inc/*.h`;

This will not work under NT, because the echo command for the command
interpreter (cmd.exe) does not expand wildcards. The prefered (at
least for the moment ;-) mechanism is globbing (anything between angle
brackets that's not a filehandle is considered to be a pattern to be
globbed). The above example could be translated like this:

        $srcfiles = join (" ", <*.c src/*.c inc/*.h>);

The glob pattern returns either an array of filenames or the next file
of the list depending on context (page 78 of Programming Perl). In the
above example it returns an array of filenames. If used in a while
loop test it would return a filename for each iteration of the loop.

Note that you can use either forward or back slashes for directory
separators, but if you use backslashes, then you must use two of them:

        $srcfiles = join (" ", <*.c src\\*.c inc\\*.h>);

Remember that whatever directory separator that you use will be in the
strings returned.

Another method is to use readdir with grep:

        opendir(D, ".") || die "Can't open \".\": $!\n";
        @files = grep (/^.*\.c$/, readdir(D));
        closedir(D);
        $srcfiles = join (" ", @files);

Hopefully I'll be able to implement globing in the interpreter later
on, but for now it runs a program named perlglob through a popen'ed
pipe. 


---------------------------------------------------------------------------
Processes
---------------------------------------------------------------------------

There are some significant differences in how NT treats processes
versus how Unix treats processes.

Process creation is the first big difference. Unix uses the fork(2)
system call to create an new process and the exec(2) system call to
load a new executable into the new processes address space. NT merges
these steps into one operation with the CreateProcess system service.

There is no equivalent to the fork operation under NT. For this reason
the perl call 'fork' was not implemented. With the addition of the
&Spawn subroutine, there are now four ways to create a process on NT:
use &Spawn, backticks, the system command, or with the open command.

Another difference is process hierarchy and process groups.  NT does
not maintain any relationship between a process and the process that
created it. This throws all of the parent/child relationships used in
Unix out the window. For this reason the perl functions regarding
parent process id and process groups were not implemented. There is
simply no way to determine the creating process id and there is no
tree of processes maintained to allow process groups.


---------------------------------------------------------------------------
Users and Groups
---------------------------------------------------------------------------

This is a real rat's nest. Both NT and Unix have the concept of user
id's; the problem is with Unix's notion of real and effective uids. NT
doesn't have this concept, so separate file test operators for real
versus effective uid ownership don't make sense.

Groups also pose a problem in this port. At any point in time, a Unix
process is associated with one group; this is it's group id. With NT,
a user (hence a user id) may be a member of several groups
simultaneously. NT processes are associated with a user id, so they
also may be members of several groups.


---------------------------------------------------------------------------
Internationalization
---------------------------------------------------------------------------

The current port of perl has no facilities for internationalization.
We are holding off implementing locale support, wide character and
multi-byte character support until we find out what is planned for
Perl 5.  


---------------------------------------------------------------------------
System Calls
---------------------------------------------------------------------------

The perl command 'syscall' allows a unix perl script to call an
arbitrary system call by invoking the syscall(2) system call. There is
no corresponding facility within the NT system services. At least I
haven't found it yet. 


---------------------------------------------------------------------------
File Systems
---------------------------------------------------------------------------

Due to the differences between the Unix file system concept and the
various file systems implemented on NT, the stat command will act
differently. There are no inodes associated with files on NT file
systems, and since there are no links, the link field is useless. 
For more information on what is returned from the perl command 'stat',
see the help file for the Microsoft C/C++ Runtime Library.

The FAT file system has no concept of execute permission and it will
only allow a file to be made read-only (write protected). There is no
means to read-protect a FAT file. This means that the only valid modes
for a FAT file are 0666 (rw-rw-rw) and 0444 (r--r--r--). Be careful
looking at modes returned from stat.

The NTFS file system offers more features than the FAT file system,
but I haven't researched it enough to tell how we can take advantage
of it from within perl. As I learn more about NTFS and implement it in
the port, I'll mail out information to the mailing list.

NOTE: A new pre-defined varible has been added to perl, $FsType. This
variable contains a string that is the name of the file system type
for the current directory (i.e. FAT, HPFS, or NTFS).


---------------------------------------------------------------------------
File Times
---------------------------------------------------------------------------
The stat and utime calls seem to have difficulties with Daylight
Savings Time. The following perl script fails:

        open (B, ">b") || die "Can't open b for output: $!\n";
        print B "foo\n";
        close B;
        $foo = (utime 500000000,500000001,'b');
        ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
         $atime,$mtime,$ctime,$blksize,$blocks) = stat('b');
        print "stat reports times as:\n";
        print "   atime: $atime ", &ctime($atime);
        print "   mtime: $mtime ", &ctime($mtime);

Instead of the atime and mtime being 500000000 and 500000001 as you
would expect, they are off by one hour (500003600 and 500003601). This
looks like a C/C++ runtime library problem. For the moment, use utime
cautiously. We'll try to find a work around while we're waiting for
Microsoft to fix the problem(s).


---------------------------------------------------------------------------
Command line arguments
---------------------------------------------------------------------------

Be careful when porting a perl script that uses the shell's echo
command. Besides the problems of wildcard expansion (listed above
under Globbing), cmd.exe does not strip white space like a unix shell.
The following script illustrates a problem discovered in the Perl Test
Suite:

    $x = `echo foo | perl -e "while (<>) {print $_;}" Ioargv.tmp -`;

    if ($x eq "a line\nfoo\n") {print "ok 2\n";} else {print "not ok 2\n";}

The script failed because of the space between 'foo' and '|' on the
first line. The echo command echo's EVERYTHING up to the pipe or
redirection or end-of-line. Take this into account when examining
input that was piped in by the echo command.
