view release on metacpan or  search on metacpan

lib/Net/TL1UDP.pm  view on Meta::CPAN

package Net::TL1UDP;
    
use strict;
use warnings;
use Socket;
    
BEGIN {
   require Exporter;
   # Set the version for version checking
   our $VERSION = 1.02;
   # Inherit from Exporter to export functions and variables
   our @ISA = qw(Exporter);
   # Functions and variables which are exported by default
   our @EXPORT = qw(
      node_login
      tl1_cmd
      tl1_cmdf
      debug_file
      close_debug
      retrieve_sid
      retrieve_ctag
      command_timeout
      timeout_counter
      inhibit_messages
      sarb_retry_limit
      sarb_retry_delay
      logoff
   );
} 

my $currentCTAG  = 0;      # Initialise the current CTAG value
my $sid          = '';     # Initialise the SID value
my $timeout      = 60;     # Initialise the response timeout value
my $udpPort      = 13001;  # Initialise UDP port number
my $debug        = 0;      # Initialise the debug status
my $deviceIP     = '';     # Initialise the device IP address
my $to_counter   = 0;      # Initialise the timeout counter value
my $inhibit_msgs = 1;      # Initialise the inhibit messages status
my $loginOK      = 0;      # Initialise the logged in state
my $sarb_retries = 0;      # Initialise the SARB retry limit
my $sarb_delay   = 0;      # Initialise the SARB retry delay value

# Function to configure the debug file
sub debug_file  {
   my $filename = shift;
   open (DEBUG, ">$filename") or die "File Error: $!";
   $debug = 1;
   END { close (DEBUG) if (defined (fileno (DEBUG))); }
}

# Function to close the debug file before the script completes
sub close_debug  {
   $debug = 0;
   close (DEBUG) if (defined (fileno (DEBUG)));
}

# Function to retrieve the SID
sub retrieve_sid  { return $sid; }

# Function to return the current CTAG value
sub retrieve_ctag  { return $currentCTAG; }

# Function to retrieve or set the timeout value
sub command_timeout  {
   # If a value has been provided, set the timeout variable
   $timeout = $_[0] if (scalar(@_) == 1 && $_[0] =~ /^\d+$/ && $_[0] > 0);
   return $timeout;
}

# Function to retrieve or set the timeout counter value
sub timeout_counter  {
   # If a value has been provided, set the counter variable
   $to_counter = $_[0] if (scalar(@_) == 1 && $_[0] =~ /^\d+$/ && $_[0] >= 0);
   return $to_counter;
}

# Function to retrieve or set the SARB retry limit value
sub sarb_retry_limit  {
   # If a value has been provided, set the limit variable
   $sarb_retries = $_[0] if (scalar(@_) == 1 && $_[0] =~ /^\d+$/);
   return $sarb_retries;
}

# Function to retrieve or set the SARB retry delay value
sub sarb_retry_delay  {
   # If a value has been provided, set the retry variable
   $sarb_delay = $_[0] if (scalar(@_) == 1 && $_[0] =~ /^\d+$/);
   return $sarb_delay;
}

# Function to retrieve or set the inhibit messages value
sub inhibit_messages  {
   # If a value has been provided, set the inhibit messages value and,
   # if logged into the node, send the allow or inhibit messages command
   if (scalar(@_) == 1 && $_[0] =~ /^[01]$/)  {
      $inhibit_msgs = $_[0];
      if ($loginOK)  {
         &tl1_cmd("INH-MSG-ALL::ALL;") if ($inhibit_msgs == 1);
         &tl1_cmd("ALW-MSG-ALL::ALL;") if ($inhibit_msgs == 0);
      }
   }
   return $inhibit_msgs;
}

# Function to log into the device
sub node_login  {
   if (scalar(@_) == 3 && $_[0] =~ /^\w\S+[:]?\d*$/)  {
      my ($deviceInfo, $username, $password) = @_;
      if ($deviceInfo =~ /:/)  { ($deviceIP, $udpPort) = split (/:/, $deviceInfo); }
      else  { $deviceIP = $deviceInfo; }
      my $login = &tl1_cmd("ACT-USER::${username}:::${password};");
      if ($login && $login =~ /Logged On/i)  {
         if ($login =~ /\s+\w+\s+\d\d-\d\d-\d\d\s\d\d:\d\d:\d\d/)  {
            ($sid) = $login =~ /\s+(\w+)\s\d\d-\d\d-\d\d\s\d\d:\d\d:\d\d/;
            &tl1_cmd("INH-MSG-ALL::ALL;") if ($inhibit_msgs);
         }
         $loginOK = 1;
      }
      else  { &tl1_cmd("LOGOFF"); }
   }
   return $loginOK;
}

# Function to log off of the device

lib/Net/TL1UDP.pm  view on Meta::CPAN

1;
__END__

=head1 NAME

Net::TL1UDP - Transaction Language 1 (TL-1) UDP Interface

=head1 SYNOPSIS

use Net::TL1UDP;

if (node_login('172.29.84.168', 'MYUSER', 'MYPASSWORD'))  {
   print tl1_cmd('RTRV-EQPT::ALL');
   print retrieve_sid;
   logoff;
}

=head1 DESCRIPTION

I<Net::TL1UDP> provides subroutines that communicate directly to a TL-1 device using UDP.  Most TL-1 modules open a telnet session to a TL-1 gateway and use it to communicate with the device.  This module communicates directly with the device.

Net::TL1UDP has been used to communicate with the Alcatel 7300, the Alcatel 7330, and the Alcatel 7342.

=over 4

=item B<node_login ('DEVICE[:PORT]', 'USERNAME', 'PASSWORD')>

Subroutine to log into the device.  The subroutine is using the following TL-1 command:  ACT-USER::(USERNAME):::(PASSWORD).  The default UDP port number is 13001 but can be changed by providing it, preceded by a colon, after the device's IP address o...

If a "logged on" message is received, the subroutine returns a "1"; otherwise, it returns a "0".

=item B<tl1_cmd ('TL-1_COMMAND')>

Sends a TL-1 command to the device.  The result will be an ASCII string containing the response to the command or a "0" (if the command times out or if the login subroutine was not executed).

=item B<tl1_cmdf ('TL-1_COMMAND')>

Sends a TL-1 command to the device.  The result will be a formatted ASCII string containing the response to the command or a "0" (if the command times out or if the login subroutine was not executed).

If the command is successful (COMPLD), it strips off any response data that is NOT encapsulated in double quotation marks and removes the quotation marks as well (returning the "real" data from the response).  If the response did not contain anything...

If the command is unsuccessful (DENY), it will return the complete unformatted response.

=item B<debug_file ('path_to/debug_file')>

Creates a debug file that contains the TL-1 commands and responses.

=item B<close_debug>

Closes the debug file.  If this function is not called, the debug file will be closed (automatically) when the script finishes.

=item B<retrieve_sid>

Returns the System ID (SID) of the device if it can be determined.

=item B<retrieve_ctag>

Returns the current correlation tag (ctag) used by the module.

=item B<command_timeout ([TIMEOUT_SECS])>

Returns the current command timeout (in seconds).  Optionally, if TIMEOUT_SECS is provided, the timeout value can be changed.

The default timeout is 60 seconds.

e.g. - C<command_timeout (120)>

=item B<timeout_counter ([NUMBER])>

Returns the current number of commands that timed out (no response within the command timeout period).  Optionally, if NUMBER is provided, the counter value can be changed (e.g. - reset to 0).

e.g. - C<timeout_counter ()>

=item B<inhibit_messages ([01])>

By default, TL1UDP inhibits all autonomous messages (INH-MSG-ALL) when you log into the device.  If you want to allow autonomous messages, set inhibit_messages(0) or send the "ALW-MSG-ALL::ALL" command.  To inhibit messages again, set inhibit_message...

NOTE:  Allowing autonomous messages could affect responses to your commands.

Since TL1UDP uses a semicolon on a line by itself to determine the end of a response, a long response that is interrupted by an autonomous message (which also contains a semicolon on a line by itself) may cause the response to be terminated premature...

=item B<sarb_retry_limit ([NUMBER])>

Returns the current (maximum) number of command retries that will be performed due to a "Status, All Resources Busy" (SARB) response.  Optionally, if NUMBER is provided, the maximum value can be changed.

The default number of retries is 0.

e.g. - C<sarb_retry_limit ()>

=item B<sarb_retry_delay ([DELAY_SECS])>

Returns the current delay, in seconds, between command retries that will be performed due to a "Status, All Resources Busy" (SARB) response.  Optionally, if DELAY_SECS is provided, the delay can be changed.

If the "sarb_retry_limit" is 0, this parameter is ignored.

The default delay is 0 seconds.

e.g. - C<sarb_retry_limit ()>

=item B<logoff>

Sends a logoff command to the device

=back

=head1 AUTHOR

Peter Carter <pelmerc@gmail.com>

=head1 COPYRIGHT

Copyright (c) 2013-2018 Peter Carter. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut