These are most of the lower level functions used in the
FAME interface. Most users will never need any of these functions,
as the higher level function getfame and putfame do
almost everything they want to do. The functions documented here were
written in the course of implementing getfame and
putfame, and some of them may prove useful on their own.
fameRunning answers TRUE if there is a process called
"FAME SERVER" already running under the user's id and with the current
R process as its parent process.
fameStart initializes the FAME HLI and may open a work database.
Since the work database is always the first one opened, its key is
always 0.
fameStop kills the HLI session and the FAME SERVER process
started by fameStart. In any given R session, you
cannot restart the HLI once it has died for any reason. (This is a
FAME limitation, not an R one.) Death of the R process also kills
the child FAME SERVER process. So it rarely makes sense to call
fameStop explicitly, as it makes any subsequent FAME
interaction in the current R session impossible.
fameState returns the state of the FAME HLI interface, which is
one of c("none", "starting", "running", "dead"). "none" means
the HLI has not been started, "starting" means the HLI has not
finished starting yet (this usually indicates an error), "running"
means the HLI is up and running, while "dead" means the HLI has been
killed, either by an error or by fameStop. In either case,
once the HLI is "dead", it cannot be revived.
fameCommand sends its string argument to the child FAME SERVER
process to be executed. If silent is TRUE, it invisibly
returns a status code that can be sent to fameStatusMessage to
get an error message. If silent is FALSE, the status
message is echoed to standard output. If capture is
TRUE, output from the FAME output channel is returned, with a
"status" attribute holding the FAME status code.
fameStatusMessage looks up and returns the error message
associated with its argument.
fameConnect opens a connection to FAME Database Server (Master
or MCADBS), returning an integer connKey which is used by
fameDbOpen to open a database on that connection.
fameDbOpen opens the named database in the given access mode.
It returns an integer dbKey, which is a required argument for
some of the other functions documented here.
fameDbClose closes the database associated with the
given dbKey.
fameDeleteObject deletes a named object from a database.
fameWriteSeries writes the tis (Time Indexed Series)
object ser as fname in the database associated with
dbKey. If an object by that name already exists in the database
and update is TRUE, the frequency and type of ser
are checked for consistency with the existing object, and if
checkBasisAndObserved is TRUE (not the default), those
items are also checked. Any inconsistencies cause the update to fail.
If all checks are OK, then the range covered by ser is written
to the database. If update if FALSE, any existing
series called fname in the database will be replaced by
ser. This function should probably not be called directly, as
putfame provides a nicer interface.
fameWriteScalar writes the tis (Time Indexed Series)
object ser as fname in the database associated with
dbKey. If an object by that name already exists in the database
and update is TRUE, the frequency and type of ser
are checked for consistency with the existing object, and if
checkBasisAndObserved is TRUE (not the default), those
items are also checked. Any inconsistencies cause the update to fail.
If all checks are OK, then the range covered by ser is written
to the database. If update if FALSE, any existing
series called fname in the database will be replaced by
ser. This function should probably not be called directly, as
putfame provides a nicer interface.
fameWhat returns a list of low level information about an
object in a database, including components named status, dbKey, name,
class, type, freq, basis, observ, fyear, fprd, lyear, lprd, obs, and
range. If getDoc is TRUE, it will also include
description and documentation components. See the FAME
documentation for the CHLI functions cfmwhat and cfmsrng
for details.
fameRunning()
fameStart(workingDB = TRUE)
fameStop()
fameState()
fameCommand(string, silent = TRUE, capture = FALSE)
fameStatusMessage(code)
fameDbOpen(dbName, accessMode = "read", connection = NULL, stopOnFail = TRUE)
fameDbClose(dbKey, closeConnection = FALSE)
fameDeleteObject(db, fname)
fameWriteScalar(dbName, fname, scalar, update = TRUE,
type = c("date", "precision", "boolean", "string", "namelist"))
fameWriteSeries(dbKey, fname, ser, update = FALSE, checkBasisAndObserved = FALSE)
fameWhat(dbKey, fname, getDoc = FALSE)if TRUE (the default) open a temporary working
database whose dbKey will be 0
a FAME command to be executed
run the command quietly if TRUE
capture and return strings from the FAME output channel
if TRUE
an integer status code from FAME
name of or path to the database to open
a string specifying the access model to open the database in: one of "read", "create", "overwrite", "update", or "shared".
created by calling fameConnection. Leave this at the
default NULL setting for local databases.
should the function stop() if the database
cannot be opened? Also, see the return value below.
integer returned by dbOpen
if TRUE, close the
fameConnection associated with the database as well. The default is to
leave the connection open. This implies that whoever opened the
connection in the first place should explicitly close it. This only applies
to databases that were opened on a connection, not to local databases.
name of an object in a FAME database
object to be written to the database
kind of FAME scalar to create in the database. If this
argument is missing, it is inferred from characteristics of
scalar. In fact, the only time you should ever really need to
use this argument is if scalar is a character object of length
one but you really want it to be written as a 'namelist' of length
one, rather than a 'string' scalar.
if TRUE update any existing series by the same
name in place. If FALSE, replace existing series.
can take dbKey or dbName form; that is, it can
be an integer returned by dbOpen, or it can be the name of a
database or path to a database.
a tis time series
see description above for fameWriteSeries
if TRUE, also return the description and
documentation attributes.
fameRunning return a Boolean.
fameStart and fameStop return nothing.
fameStatus returns a string as documented above.
If capture is FALSE, fameCommand invisibly returns a status code.
If capture is TRUE, strings sent to the FAME output
channel are returned as a character vector, and the status code is
returned as the "status" attribute of that vector.
fameStatusMessage returns a message string.
fameDbOpen returns an integer dbKey. If the parameter
stopOnFail is FALSE and the open does not succeed, the
returned integer is -1 and it will have attributes "status" and
"statusMessage" indicating the nature of the failure.
fameDbClose returns a status code.
fameDeleteObject returns a status code.
The return value from fameWriteScalar is useless and should be ignored.
fameWriteSeries returns a status code.
fameWhat returns a list.