NAME

OS390::Stdio - S/390 standard I/O functions via POSIX/XPG extensions

SYNOPSIS

use OS390::Stdio qw( &get_dcb &getname &pds_mem &sysdsnr
                     &mvsopen &mvswrite 
                     &flush &forward &rewind &resetpos
                     &remove &tmpnam 
                     &vsamdelrec &vsamlocate &vsamupdate
  # future dslist        &dsname_level &vol_ser 
  # future SVC 99        &dynalloc &dynfree &svc99 
                   );

@dslist = dsname_level("FRED");
$uniquename = tmpnam;
$fh = mvsopen("//MY.STUFF","a recfm=F") or die $!;
$name = getname($fh);
print $fh "Hello, world!\n";
flush($fh);
rewind($fh);
$line = <$fh>;
undef $fh;  # closes data set
$fh = mvsopen("dd:MYDD(MEM)", "recfm=U");
sysread($fh,$data,128);
close($fh);
remove("dd:MYDD(MEM)");
@members = pds_mem("//SYS1.SPECIAL");

DESCRIPTION

This package gives Perl scripts access via POSIX extensions to several C stdio operations not available through Perl's CORE I/O functions. The specific routines are described below. These functions are prototyped as unary operators, with the exception of mvsopen which takes two arguments, mvswrite which takes three arguments, dynalloc, svc99 which take several arguments, and tmpnam which takes none.

All of the routines are available for export, though none are exported by default. All of the constants used by vsamupdate to specify update options are exported by default. The routines are associated with the Exporter tag FUNCTIONS, the experimental routines are associated with the Exporter tag EXPERIMENAL, and the constants are associated with the Exporter tag CONSTANTS, so you can more easily choose what you'd like to import:

# import constants, but not functions
use OS390::Stdio;  # same as use OS390::Stdio qw( :DEFAULT );
# import functions, but not constants
use OS390::Stdio qw( !:CONSTANTS :FUNCTIONS ); 
# import both
use OS390::Stdio qw( :CONSTANTS :FUNCTIONS ); 
# import neither
use OS390::Stdio ();
# import everything
use OS390::Stdio (:CONSTANTS :FUNCTIONS :EXPERIMENTAL );

Of course, you can also choose to import specific functions by name, as usual.

This package ISA IO::File, so that you can call IO::File methods on the handles returned by mvsopen. The IO::File package is not initialized, however, until you actually call a method that OS390::Stdio doesn't provide. This is done to save startup time for users who don't wish to use the IO::File methods.

In the following DSH refers to a data set handle such as returned by the mvsopen routine. For OS data sets NAME refers to either a double slashed name such as //BETTY.BAM, or members such as //BETTY.BAM(BAM); or to dd names such as dd:WILMA.PEBBLES.

flush EXPR

This function causes the contents of stdio buffers for the specified data set handle to be flushed. If undef is used as the argument to flush, all currently open data set handles are flushed. Like the CRTL fflush() routine, the buffering mode and file type can have an effect on when output data is flushed. flush returns a true value if successful, and undef if not.

forward DSH

forward resets the current position of the specified data set handle to the end of the data set. It's really just a convenience method equivalent in effect to fseek($fh,0L,SEEK_END). It returns a true value if successful, and undef if it fails. See also rewind and resetpos.

get_dcb DSH

This function retrieves the data control block information for the data set handle passed to it and returns it in a hash with keys approximated by the names of the elements of the fldata_t struct (see the documentaton for the fldata() C RTL routine for further information).

For example:

use OS390::Stdio qw(mvsopen get_dcb);
my $dshandle = mvsopen("//SEDIMENT.SLATE","r");
my %slate_dcb = get_dcb($dshandle);
close($dshandle);
for (sort(keys(%slate_dcb))) {
    print "$_ = $slate_dcb{$_}\n";
}

For the inverse (i.e. setting data set attributes) use appropriate arguments with either mvsopen, dynalloc, or svc99. For just the filename you can use getname in place of get_dcb.

getname DSH

The getname function returns the data set filename associated with a Perl I/O handle (via fldata()). If an error occurs, it returns undef.

As an example consider:

$dshandle = mvsopen("//FOO.BAR","r");
$fullname = getname($dshandle);
$hlq = $fullname;
$hlq =~ s/\'([^\.]+)\..*/$1/;  # strip leading ' and trailing DS names
print "The high level qualifier (HLQ) is $hlq\n";

or, assuming you are authorized to do so, in order to switch to a different HLQ:

$mydshandle = mvsopen("//FOO.BAR","r");
$myfullname = getname($mydshandle);
$bobsuid = '214';
setuid($bobsuid);
$bobsdshandle = mvsopen("//FOO.BAR","r");
$bobsfullname = getname($bobsdshandle);
$bobshlq = $bobsfullname;
$bobshlq =~ s/\'([^\.]+)\..*/$1/;
print "Bob's pwname is ",(getpwuid($<))[0],"\n";
print "Bob's high level qualifier (HLQ) is $bobshlq\n";

Note that both of these examples assume that UIDs map directly to profile prefixes, whereas they may not in general. To obtain more extensive information for a given data set handle see get_dcb.

mvsopen NAME MODE

The mvsopen function enables you to specify optional arguments to the CRTL when opening a data set. Its operation is similar to the built-in Perl open function (see perlfunc for a complete description), but it will only open normal data sets; it cannot open pipes or duplicate existing I/O handles. The MODE is typically taken from:

qw(r w a r+ w+ a+ rb wb ab rt wt at rb+ wb+ ab+ rt+ wt+ at+)

Additional MODE keyword parameters can be passed from:

qw(acc= blksize= byteseek lrecl= recfm= type= asis password= noseek)

(See the C/C++ MVS Programming Guide and the C/C++ MVS Library Reference descriptions of fopen() for detailed information on NAME and MODE arguments.) If successful, mvsopen returns a data set handle; if an error occurs, it returns undef.

You can use the data set handle returned by mvsopen just as you would any other Perl file handle. The class OS390::Stdio ISA IO::File, so you can call IO::File methods using the handle returned by mvsopen. However, useing OS390::Stdio does not automatically use IO::File; you must do so explicitly in your program if you want to call IO::File methods. This is done to avoid the overhead of initializing the IO::File package in programs which intend to use the handle returned by mvsopen as a normal Perl data set handle only. When the scalar containing a OS390::Stdio data set handle is overwritten, undefd, or goes out of scope, the associated data set is closed automatically.

mvswrite DSH EXPR LEN

The mvswrite function provides access to stdio's fwrite() function. For example:

use OS390::Stdio qw(mvsopen mvswrite);
my $dshandle = mvsopen("//BED.ROCK","w+");
my $fred,$data,$chrs_written;
$fred = 100.00;
$data = sprintf("Fred's salary is \$%3.2f",$fred);
$chrs_written = mvswrite($dshandle,$data,length($data));
close($dshandle);

pds_mem NAME

Returns a list of members for the named PDS directory. A list with a single undef element is returned for PDS directories that have no members as well as for data set names that are not partitioned (in the latter case a warning may appear on STDERR depending on how OS390::Stdio was compiled on your system). For example:

use OS390::Stdio qw(pds_mem);
my @member_list = pds_mem("//SLATE.PDS");
foreach my $mem (@member_list) {
    print "PDS.SLATE($mem)\n";
}

remove NAME

This function deletes the data set (member) named in its argument, returning a true value if successful and undef if not. It differs from the CORE Perl function unlink in that it does not try to reset DS access if you are not authorized to delete the data set.

resetpos DSH

resetpos resets the current position of the specified data set handle to the current position. This is useful for switching between input and output at a given location. It's really just a convenience method equivalent in effect to fseek($fh,0L,SEEK_CUR). It returns a true value if successful, and undef if it fails. See also forward and rewind or Perl's builtin seek. (This was not called setpos to avoid namespace collision).

rewind DSH

rewind resets the current position of the specified data set handle to the beginning of the data set. It's really just a convenience method equivalent in effect to seek($fh,0,0). It returns a true value if successful, and undef if it fails. See also forward and resetpos.

sysdsnr NAME

Returns true if the named data set is available to fopen() in "r" mode. Note that perl's built in stat() function as well as the various file test operators such as -r do not work with OS data sets.

tmpnam

The tmpnam function returns a unique string which can be used as an HFS (POSIX) data set name when creating temporary storage. If, for some reason, it is unable to generate a name, it returns undef. Note that in order to ensure the creation of an OS data set try using mvsopen with a data set name of the form //&&name.

vsamdelrec DSH

Deletes a record from a VSAM data set via the C RTL fdelrec() routine. You must seek to the proper record before invoking vsamdelrec of course. See also mvsopen, vsamlocate, and vsamupdate.

vsamlocate DSH, key, key_len, options

Locates a record in a VSAM data set via the C RTL flocate() routine. See also mvsopen, vsamdelrec, and vsamupdate.

vsamupdate DSH, record, length

Updates a record in a VSAM data set via the C RTL fupdate() routine. See also mvsopen, vsamdelrec, and vsamlocate.

The following functions are experimental: V 0.001: Some are not currently working and either produce fatal errors or simply do not work as intended.

dsname_level

This function returns a ds list for a given HLQ plus optional additional qualifiers. It returns undef if it encounters an error. (The name was taken from the ISPF 3.4 panel entry). See also vol_ser.