view release on metacpan or  search on metacpan

lib/DBD/MVS_FTPSQL.pm  view on Meta::CPAN

  my $dbh = DBI->connect("dbi:MVS_FTPSQL:$DSN", $username, $password) 
    or die "Cannot connect: " . $DBI::errstr;

It connects to the DB2 subsystem C<$ssid> of the mainframe whose hostname is C<$hostname>.
Refer to the L<DSN string|/"DSN string"> section of this document for details on matching
the configuration of the mainframe you want to connect to (in particular the attributes
L<hostname|/"hostname">, L<port|/"port"> and L<ssid|/"ssid">). 
It could be a good idea to take also a look at the L<EXAMPLES|/"EXAMPLES"> section below.

=head1 DESCRIPTION

This pure Perl module lets you submit SQL queries (that's it, only SELECT statements) to a DB2 subsystem 
installed on a mainframe,  provided that: 

=over 4

=item *

The IBM FTP Communications Server (CS) on the mainframe side was installed 
with the (optional) SQL query function enabled ( see the section
L<Installing the SQL query function on the Communications Server|/"Installing the SQL query function on the Communications Server"> 
for additional information on this subject).

=item *

You supply, as mentioned in the L<SYNOPSIS|/"SYNOPSIS"> section above, enough information, 
inside the DSN string of the L<DBI::connect()|DBI/connect> statement, to identify and locate the 
L<ssid|/"ssid"> (the four character DB2 subsystem identifier) you want to connect to
and the L<hostname|/"hostname"> and L<port|/"port"> of the IBM FTP CS that will taxi your queries.

=item * 

You can submit queries via QMF (Query Management Facility) or, in other words,
your account has C<SELECT> privileges on the subsystem that contains the tables
you want to query.

=item *

Your account on the mainframe has write permissions to either a 
I<"swap"> directory (that you can specify via the DSN facultative attribute 
L<remote_directory|/"remote_directory">) or your home directory (if you omit it). This directory
will be utilized as a temporary storage area for the files containing the 
sql statements you submit.
No harm will be done to other files located there.
For more details read the L<DSN string|/"DSN string"> section of this document.

=back

This document focuses primarily on specific issues regarding this particular DBI 
driver and it assumes that you are familiar with the DBI architecture. If not the case, please read the L<DBI documentation|DBI> first to acquire a general 
knowledge of its classes and methods. 

=head2 DSN string

The following instruction: 

  my $dbh = DBI->connect("dbi:MVS_FTPSQL:$DSN", $username, $password)
            or die $DBI::errstr;  

establishes a connection to the DB2 subsystem identified by the DSN string 
C<$DSN>, using as login credentials the C<$username> and C<$password> supplied. 
Notice that in the OS/390 or z/OS environment you don't connect to a 
database, instead you have to connect to the DB2 subsystem which gives 
access to all the databases it contains (a mainframe database has very 
little to do with its pc counterpart as it is basically a logical grouping 
of tables, other objects and so, in many ways, it's more similar to a pc 
schema).   

The DSN string consists of a list of I<argument=value> pairs separated by semicolons,
like the example below: 

  # Identifies the DB2 subsystem DDB2 accessible through an IBM FTP CS 
  # running at foo.com:9999
  my $DSN = 'hostname=foo.com;port=9999;ssid=DDB2'; 

The following is a list of allowed arguments and their meaning, arranged in order of relevance.

=over 4

=item C<hostname>

The mainframe hostname or ip address. This argument is mandatory.

=item C<port>

Denotes the port on which the IBM FTP CS installed on the mainframe is listening and defaults to 21. 
Do not confuse this (ftp) port with the DRDA port; this is not a DRDA driver.

=item C<ssid>

A 4 character string representing a DB2 subsystem identifier.
You can omit this attribute and rely on the default specified
in the IBM FTP CS configuration dataset C<FTP.DATA>
(the IBM book Communications Server: IP Configuration Reference 
covers this topic in detail ).

If, however, while connecting to the DB2 subsystem <ssid>, you receive the 
error message:

  DBD::MVS_FTPSQL::st execute failed: attempt to connect to <ssid> failed

this means that the default value doesn't match an existing DB2 subsystem and you need 
to explicitly specify it. Notice that this is the same error message that you
receive if the ssid you specify doesn't exist.
If you don't know the ssid of the DB2 subsystem(s) installed on the 
mainframe you are trying to connect to ask your system administrator 
or read the L<"How to find out the DB2 subsystem IDs"|/"How to find out the DB2 subsystem IDs"> section of this document.

=item C<remote_prefix>

The first 4 characters of the temporary dataset name that will be 
used to store the query on the mainframe. The default prefix is 'FSQL', 
so the dataset will be named with the first unassigned string of the 
sequence FSQL0001, FSQL0002, FSQL0003 and so on (this prevents overwriting 
existing files).
Please note that you don't need to interact with those files directly as they 
only serve to upload the query to the mainframe before the  execution 
and they will be deleted suddenly after.
The files will be allocated for the minimum retention possible period
(0 days) so if something goes wrong they will be deleted anyway the 
next day.