The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Fame - Perl5 access to FAME

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');

SUMMARY

  1. All but 6 C HLI 7.7 functions are fully implemented in native perl code. Not implemented: cfmlsts, cfmrdfa, cfmrrng, cfmrsts, cfmwrng, cfmwsts.

  2. For implementations with the FRB extensions, all hli_* functions are implemented fully. famedbpath is also implemented.

  3. New perl-like functions have been added (see FAME Utilities). These provide an interface to TIE and the FAME interpreter.

  4. Values of hli.h are available.

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:

Fame::HLI

Includes almost all the CHLI functions as well as some simple utilities.

Fame::DB

Includes a TIE interface using the Fame::HLI package, as well a high-level object-oriented functions for reading and writing data.

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.

HLI.H

Values of hli.h are accessed by adding "&Fame::HLI::" in front of the name. Thus, HDAILY becomes &Fame::HLI::HDAILY.

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.

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;

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.

$x = new Fame::LANG

Create a new LANG object and open the work database.

$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.

$x->exec($fxn)

Execute the given function and return an array (not a scalar) of the results.

$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.

$x->destroy

Close the work database and remove the LANG object.

$x->{status}

The HLI status of the last command.

$x->{workdb}

The HLI database key for the work database.

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.

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.

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.

$dbkey = &Fame::HLI::fameopen($name);
$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.

&Fame::HLI::fameclose($dbkey);

Close database.

$type = &Fame::HLI::famegettype($dbkey,$objnam);

Get an object's type.

$freq = &Fame::HLI::famegetfreq($dbkey,$objnam);

Get an object's frequency.

@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
@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).

@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.

&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;

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)").

NOTES

  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.

  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.

  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.

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.

AUTHOR

 Fernando Trias
 ftrias@bigfoot.com