/ 
Finance-DST-FAN-Mail-0.005000
/ Finance::DST::FAN::Mail::File

NAME

Finance::DST::FAN::Mail::File - Read DST FANMail Files into data structures

SYNOPSIS

my $file = Finance::DST::FAN::Mail::File
    ->new(
          filename        => $path_to_file,
          record_callback => sub{ ... }, #optional
         );
  my $file_date = $file->processed_date;
  my $records = eval { $file->records };
  die("There was an error reading the file: $@") unless defined $records;

 if($file->is_mf){              #Mutual Fund Records
   # ...
 } elsif($file->is_va){         #Variable Annuity Records
   # ...
 } elsif($file->is_reit){       #REIT Records
   # ...
 } elsif($file->is_lp){         #Limited Partnership Records
   # ...
 } elsif($file->is_vul){        #VUL records
   # ...
 }

  for my $record ( @$records ){
     #insert records into database or whatever
     my $cusip = $record->{cusip}; #etc..
  }

DESCRIPTION

This module provides a basic interface for easily reading DST FANMail data files into more meaningful data structures as well as some basic tests of file integrity. A file will only contain information on a single type of financial product type.

For more detailed information on the data keys associated with each file type please see the relevant file's description. The Finance::DST::FAN::Mail::File::* hierarchy is composed of subclasses of this module and all information provided here will also be true of this class' subclasses.

Finance::DST::FAN::Mail::File::APR - Account Position Records (format code 014)

ATTRIBUTES

filename

Required read-only string that represents the path to the file you wish to read.

record_callback

has_record_callback - predicate

Optional read-only code reference that will be called after every logical record is read. Will be passed two arguments, the current instance of the file parser (so you can access file properties) and a hashref representing the record as described above.

You can use this to reduce the memory foot print of your program by keeping only the current account record in memory. Example:

my $callback = sub{
    my($instance, $rec) = @_;
    #process data here;
    %$rec = ();
};
my $file = Finance::DST::FAN::Mail::File:XYZ
  ->load( filename => $file, record_callback => $callback);

#by the time this returns a callback will have been executed for each account
my $recs = eval { $balance->records };
defined($recs) && !$@ ? commit() : rollback() and die($@);

The downside of this method is that if the file is currupted, you will have to catch the exception and rollback changes. Partially transmitted files are NOT that uncommon! Make sure you have a rollback mechanism.

records

clear_records - clearer
has_records - predicate
_build_records - builder

An array reference containing all of the positions contained in the file. This read-only attribute builds lazyly the first time it is requested by actually going through the while file and reading it. If any errors are encountered while reading the file or the file appears to be truncated an exception will be thrown.

File Properties

The following attributes are automatically filled the header is read:

file_type - String
super_sheet_date - DateTime (date only)
processed_date - DateTime (date and, if provided, time)
job_name - String
file_format_code -Numeric String
request_numer - Numeric String
system_id - String
management_code - String
product_type - String (M, R, L, U or V) Mutual Fund, REIT, LP, VUL, Variable Annuity
vul_type - String, applies to VULs only.

The following attribute is automatically filled the trailer is read:

record_count - Integer, number of records in file including all header, detail and trailer records. (essentially wc -l)

_file_handle

_clear_file_handle - clearer
_has_file_handle - predicate
_build__file_handle - builder

This is the IO::File object that holds our filehandle. DO NOT TOUCH THIS. If you mess with this I can almost guarantee you will break something.

PUBLIC METHODS

load key => val

Will load a file and return an instance of the proper file parser. Proper key / value pairs are filename (required), and record_callback (optional).

Informational Predicates

You can use these to easily determine what type of data the file contains.

is_mf - Returns true if data is Mutual Fund
is_va - Returns true if data is Variable Annuity
is_lp - Returns true if data is Limited Partnership
is_vul - Returns true if data is Variable Universal Life
is_reit - Returns true is data is Real Estate Investment Trust
is_delta - Returns true if the file only contains information for the changed records. The opposite of is_refresh.
is_refresh - Returns true if the file contains information for all records. The opposite of is_delta.

meta

See Moose

PRIVATE METHODS

BUILD

At instantiation time this method is called and it opens the file handle and reads the header of the file to get the file date.

See Moose for more information about how BUILD works.

_process_header

This private method reads the first line of the file and processes the header. It also sets the file_date attribute.

_process_footer

Extract the record_count from the footer records for integirity checking.

error

next_line

SEE ALSO

Finance::DST::FAN::Mail::Utils

AUTHOR & LICENSE

Please see Finance::DST::FAN::Mail for more information.