File Coverage

blib/lib/FTN/Database/Nodelist.pm

Criterion	Covered	Total	%
statement	30	30	100.0
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod	2	2	100.0
total	37	37	100.0

package FTN::Database::Nodelist;

use warnings;
use strict;
use Carp qw( croak );

=head1 NAME

FTN::Database::Nodelist - Fidonet/FTN Nodelist SQL Database operations.

=head1 VERSION

Version 0.40

=cut

our $VERSION = '0.40';

=head1 DESCRIPTION

FTN::Database::Nodelist is a Perl module containing common nodelist related functions
for Fidonet/FTN Nodelist related processing on a Nodelist table in an SQL Database,
including one that defines the fields for such a Nodelist table. The SQL database
engine is one for which a DBD module exists, defaulting to SQLite.

=head1 EXPORT

The following functions are available in this module:  define_nodelist_table(),
drop_nodelist_table(), ftnnode_index_fields(), remove_ftn_domain().

=head1 FUNCTIONS

=head2 define_nodelist_table

Syntax:  $fields = define_nodelist_table();

This function returns a string that contains the SQL which defines a
Nodelist table for use in an SQL database being used for Fidonet/FTN
processing,

Except for the I field, which is defined in the create_ftn_table
subroutine itself, the defined fields are as follows:

=cut

sub define_nodelist_table {

    my $table_fields = '';

=over 4

=item type

The I field may by empty or may contain one of the following keywords:
Zone, Region, Host, Hub, Pvt, Hold, or Down. Defaults to an empty string, which
indicates a normal nodelist entry.

=cut

    $table_fields  = "type      VARCHAR(6) DEFAULT '' NOT NULL, ";

=item zone

The I field is a number in the range of 0 to 32767 that is the zone number
for a particular nodelist table entry. Defaults to the number one.

=cut

    $table_fields .= "zone      SMALLINT  DEFAULT '1' NOT NULL, ";

=item net

The I field is used to contain a number in the range of 0 to 32767 that is
the net number for a particular nodelist table entry. Defaults to the number one.

=cut

    $table_fields .= "net       SMALLINT  DEFAULT '1' NOT NULL, ";

=item node

The I field is used to contain a number in the range of 0 to 32767 that is
the node number for a particular nodelist table entry. Defaults to the number one.

=cut

    $table_fields .= "node      SMALLINT  DEFAULT '1' NOT NULL, ";

=item point

The I field is used to contain a number in the range of 0 to 32767 that is
the point number for a particular nodelist table entry. Defaults to the number zero.

=cut

    $table_fields .= "point     SMALLINT  DEFAULT '0' NOT NULL, ";

=item region

The I field is used to contain a number in the range of 0 to 32767 that is
the region number for a particular nodelist table entry. Defaults to the number zero.

=cut

    $table_fields .= "region    SMALLINT  DEFAULT '0' NOT NULL, ";

=item name

The I field is used to contain the system name as a string.
It can contain up to 48 characters and defaults to an empty string.

=cut

    $table_fields .= "name      VARCHAR(48) DEFAULT '' NOT NULL, ";

=item location

The I field is used to contain the location of the system as a string.
It can contain up to 48 characters and defaults to an empty string.

=cut

    $table_fields .= "location  VARCHAR(48) DEFAULT '' NOT NULL, ";

=item sysop

The I field is used to contain a string indicating the system operator.
It can contain up to 48 characters and defaults to an empty string.

=cut

    $table_fields .= "sysop     VARCHAR(48) DEFAULT '' NOT NULL, ";

=item phone

The I field is used to contain a string indicating the phone number for
the system. It can contain up to 32 characters and defaults to the string
I<'000-000-000-000>.

=cut

    $table_fields .= "phone     VARCHAR(32) DEFAULT '000-000-000-000' NOT NULL, ";

=item baud

The I field is used to contain the baud rate for the system that a particular
nodelist table entry is for. It can contain up to 6 characters and defaults to I<300>.

=cut

    $table_fields .= "baud      CHAR(6) DEFAULT '300' NOT NULL, ";

=item flags

The I field is used to contain the nodelist flags for the system that a particular
nodelist table entry is for. It can contain up to 128 characters and defaults to a string
containing a single space.

=cut

    $table_fields .= "flags     VARCHAR(128) DEFAULT ' ' NOT NULL, ";

=item domain

The I field is used to contain the domain name for the system that a particular
nodelist table entry is for. It can contain up to 8 characters and defaults to the
string I.

=cut

    $table_fields .= "domain    VARCHAR(8) DEFAULT 'fidonet' NOT NULL, ";

=item ftnyear

The I field is used to contain the 4 digit integer representing the
year that a particular nodelist table entry is valid. Defaults to the number
zero.

=cut

    $table_fields .= "ftnyear   SMALLINT  DEFAULT '0' NOT NULL, ";

=item yearday

The I field is used to contain the three digit day of the year that
a particular nodelist table entry is valid for. Defaults to the number zero.

=cut

    $table_fields .= "yearday   SMALLINT  DEFAULT '0' NOT NULL, ";

=item source

The I field is used to indicate the source of the data that a particular
nodelist table entry is from. For instance, it could be used to give the name of
the nodelist file that the data is from. It can contain up to 16 characters and
defaults to the string I.

=cut

    $table_fields .= "source    VARCHAR(16) DEFAULT 'local' NOT NULL, ";

=item updated

The I field is used to contain a timestamp for when a particular
nodelist table entry was last updated. Defaults to now.

=back

=cut

    $table_fields .= "updated   TIMESTAMP DEFAULT 'now' NOT NULL ";

    return($table_fields);

}

=head2 ftnnode_index_fields

Syntax:  $fields = ftnnode_index_fields();

This is a function that returns a string containing a comma separated list of
the fields that are intended for use in creating the ftnnode database index.
The index contains the following fields:  zone, net, node, point, domain,
ftnyear, and yearday.

=cut

sub ftnnode_index_fields {

    my $field_list = 'zone,net,node,point,domain,ftnyear,yearday';

    return($field_list);

}

=head1 EXAMPLES

An example of opening an FTN database, then creating a nodelist table,
loading data to it, then creating an index on it, and the closing
the database:

    use FTN::Database;
    use FTN::Database::Nodelist;

    my $db_handle = open_ftn_database(\%db_option);
    $fields = define_nodelist_table();
    create_ftn_table($db_handle, $table_name, $fields);
    ...   (Load data to nodelist table)
    ftnnode_index_tables($db_handle, $table_name);
    close_ftn_database($db_handle);

=head1 AUTHOR

Robert James Clay, C<<  >>

=head1 BUGS

Please report any bugs or feature requests via the web interface at
L. I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.

Note that you can also report any bugs or feature requests to
C, or through the web interface at
L;
however, the FTN-Database Issue tracker at the SourceForge project
is preferred.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc FTN::Database::Nodelist


You can also look for information at:

=over 4

=item * FTN::Database issue tracker

L

=item * RT: CPAN's request tracker

L

=item * Search CPAN

L

=back

=head1 SEE ALSO

 L,  L,
 L

=head1 COPYRIGHT & LICENSE

Copyright 2010-2013 Robert James Clay, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


=cut

1; # End of FTN::Database::Nodelist