=head1 NAME
Fame - Perl5 access to FAME
=head1 SYNOPSIS
use Fame;
[$X =] tie %hash, Fame::DB, $dbname|$mode...
@data=@{$hash{"object:1jan80:31dec81"}}
untie %hash
&Fame::HLI::cfmddes($status,$dbkey,$desc);
print "error" if $status != &Fame::HLI::HSUCC;
$db = new Fame::DB $dbname|$mode...;
@data = $db->Read($name, $start, $end);
$db->Write($name, $start, @data);
$interp = new Fame::LANG;
$interp->command('open <access read> "db"');
@profit = $interp->exec('revenue.qtr - sales.qtr');
=head1 SUMMARY
=over 4
=item 1.
All but 6 C HLI 7.7 functions are fully implemented in native perl
code. Not implemented: cfmlsts, cfmrdfa, cfmrrng, cfmrsts, cfmwrng,
cfmwsts.
=item 2.
For implementations with the FRB extensions, all hli_* functions are
implemented fully. famedbpath is also implemented.
=item 3.
New perl-like functions have been added (see FAME Utilities). These
provide an interface to TIE and the FAME interpreter.
=item 4.
Values of hli.h are available.
=back
=head1 DESCRIPTION
This is a long section. The first part describes essential FAME hli.h
macros. The second part, TIE, deals with the TIEHASH mechanism for
accessing FAME data. The next part deals with high level functions
for reading and writing. Following is a short description about
accessing the FAME interpreter. The next parts deal with more direct
control of the C HLI. Familiarity with the C HLI is assumed in this
last part.
Three subpackages are defined by this package:
=over 4
=item Fame::HLI
Includes almost all the CHLI functions as well as some simple
utilities.
=item Fame::DB
Includes a TIE interface using the Fame::HLI package, as well a
high-level object-oriented functions for reading and writing data.
=item Fame::LANG
Provides a simple object-oriented way to run programs, commands, and
functions in the FAME 4GL language. It uses the Fame::HLI package.
=back
=head2 HLI.H
Values of hli.h are accessed by adding "&Fame::HLI::" in front of the
name. Thus, HDAILY becomes &Fame::HLI::HDAILY.
=head2 TIE
You can use the Perl TIEHASH mechanism for accessing most of the FAME
database features. Unlike with Fame, the default open mode is
read-only. First, open the databases with the tie command:
tie(%db, Fame::DB, "prices", "orders");
You may specify a fame open mode by using it before the databases for
which the mode should be used:
tie(%db, Fame::DB, &Fame::HUMODE, "prices");
Instead of listing the databse names, you may also specify a reference
to an array. Either way, the new hash is tied to all the opened
databases so that they are searched for objects in the order
specified.
Data is read by indexing the hash (%db in our example) using the
object name and an optional start and end date. The index is the
object name followed by a ":", the start date, a ",", and the end
date. However, only the object name is required. When accessed this
way, the hash returns a reference to an array so it must be
indirected. For example
@{$db{"ibm:1jun95,31jun95"}}
will return an array containing the values of "ibm" from 1jun95 to
31jun95. Note the use of the @{} construct which returns the values
of a reference. The dates must be in a format consistent with the
frequency of the object ("ibm"), which in this case is daily.
Likewise, to write values to the database, assign the hash to an
array reference. For example
$db{"ibm:1jun95"} = [1,4,6];
will write out the numbers 1, 4, and 6 starting at date 1jun95.
fameperl will write the given number of elements starting at the given
date. You may specify an end date, but it will be silently ignored.
This construct will only write data to existing data object. To
create objects, you must use the C HLI routines or the functions
described below.
Hash functions, like "each" and "keys" will work by performing a
wildcard lookup on the database. The variable $Fame::DB::WILD
contains a string with the FAME wildcard specification (default "?").
There are certain variables in the Fame::DB package which are used as
defaults by some Fame::DB functions. $Fame::DB::FREQ contains the
default frequency code. This code can be one of the valid HLI
frequency codes such as &Fame::HLI::HDAILY. The following data items
similarly can take on any valid and appropriate HLI code.
$Fame::DB::TYPE contains the default data type. $Fame::DB::BASIS
contains the default basis attribute. $Fame::DB::OBSERVED contains
the default observed attribute. $Fame::DB::CLASS is the default
class.
=head2 FUNCTIONS
There are several high level functions for reading, writing and
creating data object. These functions can be used as both normal
function calls and object-oriented calls. They are summarized below.
The first function opens a database using the same syntax as the tie
command.
$ref = &Fame::DB::new($db_path|$db_mode...)
$db_path database path
$db_mode access mode from Fame::HLI
An alternative syntax for the Fame::DB::new syntax is
$ref = new Fame::DB $db_path|$db_mode;
There are also two other functions for adding databases to an
existing object.
$ref->append($db_path|$db_mode...);
or
$ref->append_db($dbkey...)
The following functions take as their first parameter either a
reference to array of databases as returned by Fame::DB::new or a
single database key number.
@val = &Fame::DB::Read($db, $name, $start, $end)
@val array of values read
$db database key (or $ref)
$name string object name
$start start string date
$end end string date
.
&Fame::DB::Write($db, $name, $start, @val)
$db database key (or $ref)
$name string object name
$start start string date
@val array of values to store
.
&Fame::DB::Create($db, $name [, $class, $freq, $type, $basis, $obs])
$db database key (or $ref)
$name object name
The following are optional:
$class class code
$freq frequency code
$type object type
$basis basis attribute
$obs observed attribute
An alternative object-oriented syntax for all of the above functions
would be:
@data = $ref->Read($name, $start, $end);
where $ref is an object of type Fame::HLI which would usually be
initialized by
$ref = new Fame::DB $dbname;
=head2 FAME 4GL
There is also a simple object-oriented interface to the FAME 4GL
language using the HLI FAME/Server HLI functions. There are several
methods for doing this in Fame::LANG.
=over 4
=item $x = new Fame::LANG
Create a new LANG object and open the work database.
=item $x->command($cmd)
Execute the command $cmd. If the command is more than one line long,
all lines except the last one must be followed by "&&", the FAME
line-continuation string.
=item $x->exec($fxn)
Execute the given function and return an array (not a scalar) of the
results.
=item $x->inp($file)
Input the lines file named $file (this file should follow the "&&"
line-continuation standard) and execute the commands with command().
Note that you cannot use $x->command("inp file"). FAME will ignore
this command.
=item $x->destroy
Close the work database and remove the LANG object.
=item $x->{status}
The HLI status of the last command.
=item $x->{workdb}
The HLI database key for the work database.
=back
=head2 C HLI
The Fame::HLI package includes almost all of the C HLI functions available
form Fame. The typical C HLI function is translated directly to perl. For
example, to call cfmddes from C HLI, you would use:
cfmddes(&status,dbkey,desc);
In fameperl, you would use:
&Fame::HLI::cfmddes($status,$dbkey,$desc);
Perl makes no distinction between pointers and values. Thus, all
variables (whether output or input) are specified the same way. Perl
takes care of modifying those values it has to modify.
=head2 SPECIAL FUNCTIONS
There are exceptions. Functions which use a range (or other array
with a limited and fixed length) are called with one variable for
every array element. Thus, cfmsrng would be called from C as:
cfmsrng(&status,freq,&sy,&sp,&ey,&ep,range,&numobs);
From perl, each element of range must be specified. Thus, you would
use the following:
&Fame::HLI::cfmsrng($status,$freq,$sy,$sp,$ey,$ep,
$range1,$range2,$range3,$numobs);
The functions which require this type of array expansion are: cfmrstr,
cfmsbm, cfmsfis, cfmsnm, cfmspm, cfmwstr.
Some functions have not been implemented. See Summary for a list.
=head2 UTILITY FUNCTIONS
There are several functions which assist perl users in rapidly getting
and updating FAME data. Most of the C HLI functions that write or
read data are not implemented. In their place, you should use the
functions described in this section.
When missing value translation is not specified, missing values are
returned as string "NA", "ND", "NC" if the values are numeric; this
will evaluate to a zero in a numeric context. For strings, "" is
returned.
=over 4
=item $dbkey = &Fame::HLI::fameopen($name);
=item $dbkey = &Fame::HLI::fameopen($name,$mode);
Open a FAME database. First, look at the FAME databse directory as
given by famedbpath. If the database is not there, then try to open
it in the current directory. Returns -1 on error.
=item &Fame::HLI::fameclose($dbkey);
Close database.
=item $type = &Fame::HLI::famegettype($dbkey,$objnam);
Get an object's type.
=item $freq = &Fame::HLI::famegetfreq($dbkey,$objnam);
Get an object's frequency.
=item @list = $Fame::HLI::famegetinfo($dbkey,$objnam);
Get info (as returned by cfmwhat) with:
($class,$type,$freq,$basis,$observ,$fyear,$fprd,
$lyear,$lprd,$cyear,$cmonth,$cday,$myear,$mmonth,
$mday,$desc,$doc) = @list
The following table describes the order of your parameters for easy
reference in an array context:
Name #
------------ ---
class 0
type 1
freq 2
basis 3
observed 4
first year 5
first period 6
last year 7
last period 8
create year 9
create month 10
create day 11
modify year 12
modify month 13
modify day 14
description 15
documentation 16
=item @data = &Fame::HLI::fameread($dbkey,$objnam,$syear,$sprd,$eyear,$eprd);
Read data for the given range of dates. Returns undef if there's
a problem (the $Fame::HLI:status variable should be set with the
error code).
=item @data = &Fame::HLI::famereadn($dbkey,$objnam,$numobs,@r,@m);
@r=($range1,$range2,$range3);
@m=($tmiss,$mistt1,$mistt2,$mistt3);
Read a given number of value starting with the values of a given
range. Get the rangex values with the functions cfmsrng, cfmsfix.
This function will read the whole range of values, but only store
numobs of them. You can get the value of numobs when setting the
range. The missing value variables must contain data even if no
translation is being done.
=item &Fame::HLI::famewrite($dbkey,$objnam,$year,$prd,@list);
Writes out all the elements of @list into the object staring with the
given date. Returns error status if failed; 0 if sucessful.\n;
=back
=head2 ERRORS
Errors in the utility functions are generally not reported. However,
an empty list or undef returned from a function call generally means
there is an error. You can also check the variable Fame::HLI::status
which returns the HLI status code for the last HLI function that was
executed by a utility function. This value is not affected by calling
HLI functions directly from perl (such as "&cfmini($s)").
=head2 NOTES
=over 4
=item 1.
The source code is written in Perl, C and CLI (a common language
interface). It does not use the standard Perl 5 extension macro
language "xs" because the code was originally written for both Perl 4
and Tcl. Because it uses CLI, a lot of the code is the same for both
interfaces.
=item 2.
FAME is a registered trademark of Fame Information Services. Neither
this program nor its author are associated with Fame Information
Services, nor does the author guarantee this software in any way.
This software is derived from public domain work done at the Federal
Reserve Board, Washington, DC.
=item 3.
Everything except the Fame::HLI component is Copyright 1995-1997 by
Fernando Trias. Parts of the Fame::HLI component are also Copyright
1995 by Fernando Trias. These are marked as such.
=back
=head1 BUGS
There's an object symbolic name inconsistency between the Fame C HLI
library and the perl executable. Both have an symbol named "Error".
You may have to edit the perl executable and change all occurrences of
"Error" to something like "ErroX"; the Makefile includes a line for
doing this automatically (make patchperl). Alternatively, you can
try to edit the Fame dynamic libarary file in the same way.
Fame also handles some functions as #define's in hli.h. This is not
the best coding practice, since it confuses the linking process. I
cannot guarantee that further versions of Fame will not do this also
and possibly affect this extension.
=head1 AUTHOR
Fernando Trias
trias@ix.netcom.com
http://www.netcom.com/~trias
=cut