Welcome to the OS390::Stdio module.

In order to build this extension to perl you must get
the gzipped tape archive over to OS/390 or z/OS (ftp in binary mode, cp over
and nfs mount with no XLAT parameter set).

In summary the steps you then need to execute are:

    gunzip OS390-Stdio-0.006.tar.gz
    pax -f -t < OS390-Stdio-0.006.tar
    cd OS390-Stdio-0.006
    perl Makefile.PL
    make
    make test
    make install

If your perl is built to only allow static linking (as is common on OS/390 
or z/OS) then be sure to also run:

    make inst_perl

In detail the steps are:

Unpack the ASCII source code archive (the gunzip can be done on a non 
OE/USS machine if necessary):

    gunzip OS390-Stdio-0.006.tar.gz

From the OE/USS shell unpack the archive specifying that you want
an ASCII -> EBCDIC conversion to take place:

    pax -f -t < OS390-Stdio-0.006.tar

then configure and build (see `perldoc ExtUtils::MakeMaker` for more
information on building staticially linked perl extensions and other 
options to pass to perl on the `perl Makefile.PL` step, as well as
the section "Build tips" below for more info):

    cd OS390-Stdio-0.006
    perl Makefile.PL  [-DNO_WARN_IF_NOT_PDS]
    make

(optional) now make a static perl binary:

    make perl

now run the regression test:

    make test

(see also the section "Regression testing tips" below for more info).

If things look "OK" then install (this may require UID=0 or simply 
write privileges to the appropriate directories):

    make install

(optional) install the statically linked rebuild perl binary:

    make inst_perl


"Documentation"
---------------
Documentation is within Stdio.pm and should be available with:

    perldoc OS390::Stdio

There are also examples of working data set handling code in test.pl,
as well as in stdio_cookbook.pod and pds_test.  This latter program can 
be run after `make test` and it will prompt you for some valid data 
set names. 

You can find the gzip and gunzip programs as well as GNU make at:

    http://www.mks.com/


"Build tips"
------------

I've had no luck with versions of perl prior to 5.005_02.  Hence I
would recommend that you try that or preferrably an even later 
version of perl.  I've also noted that the build works just fine 
on these:

    $ uname -v -r
    07.00 02
    $ uname -v -r
    10.00 02

I've also noted that the build worked fine for V0.003 of this
extension on these:

    $ uname -v -r
    05.00 02
    $ uname -v -r
    06.00 02

But this extension has trouble with __dyninit_t and fldata_t 
structs on:

    $ uname -v -r
    03.00 01

I'd be happy to resolve those build problems with someone - send
me a unified or context diff of the changes you had to make.  Thanks.

Also, I might like to rename this module to ???::Stdio if possible or
necessary.  As far as I know the C runtime extensions that this
perl extension exploits are also available on VSE/ESA and
VM/CMS.  Of course I would be willing to rename mvsopen() and 
mvswrite() if such generalization proves feasible (I'd consider 
s390open() and s390write() if they didn't have a soon-to-expire 
timestamp in them).  Any help with such a project would be greatly 
appreciated since I do not have routine access to VSE or VM.
Thank you.

"Regression testing tips"
-------------------------

In order to see more of what the regression tests are doing look for 
the %ENV varaibles to set, set them, then re-run the `make test` suite.
e.g.:

   $ grep ENV test.pl
   my $DIAG = $ENV{'OS390_STDIO_DIAG'};
   my $GORY = $ENV{'OS390_STDIO_GORY'};
   $ export OS390_STDIO_DIAG='1'
   $ make test

After the `make perl` or `make test` step it should be posible to run 
the pds_test test via:

   ./pds_test

Then answer the questions that arise.  The pds_test script will ask for 
a PDS name and a non-PDS data set name, and will attempt to read 
the DCB and MEMBER list from each as a means of testing pds_mem().  
See also the comments at the head of pds_test for other tips on 
running it.

There is also an smf_test program for testing the smf_record()
routine on systems that have SMF running (and whose SMF.BPX facility
allows a perl program to write to SMF).

##################################################################

Special notes for release 0.006:
--------------------------------
The svc99() routine is now functional.
An smf_record() routine is now available yet will be
untested by test.pl owing to SMF deployment differences.  See
the smf_test enclosed program for a way to test smf_record()
before running `make install`.

The stdio_cookbook.pod document has been expanded.

You now have the option of passing data set names (e.g. partial
names) to the get_dcb() and getname() routines in addition to still
being able to pass mvsopen() file handles.

All 161 tests ought to pass for you.

None of the catalog/VTOC dslist functions (vol_ser dsname_level) work.
I am beginning to suspect that I may need to use either an ISPF callable 
interface (ISPEXEC,) or perhaps assembler calls to either DADSM LOCATE or
perhaps CVAFFILT and CVAFTST && CVAFSEQ layered in via 
C<#pragma linkage(CVAF*,OS)>.  Help with such programming tasks would be 
appreciated (I wonder why it is that a routine was not put into the C 
run-time library? :-).

None of the vsam routines [locate() update() delrec()] have been 
tested at all.  Any volunteers to write tests?

##################################################################

See the Changes file for older information.

Peter Prymmer