tcsMakeDbPoint.3

Manpage of tcsMakeDbPoint

tcsMakeDbPoint

Section: C Library Functions (3)
Updated: 2012-04-23 10:08
Index Return to man pages list

NAME

tcsMakeDbPoint tcsMakeDbPoint_v - Convenience functions to build
database symbolic addresses relative to the TCS
database root point.

SYNOPSIS


#include "tcsBASE.h"
const char* tcsMakeDbPoint(const dbSYMADDRESS dbRoot,
                           const char *format,
                           ...);
const char* tcsMakeDbPoint_v(const dbSYMADDRESS dbRoot,
                             const char *format,
                             va_list va_parList);

DESCRIPTION


Build a database symbolic address relative to the TCS database
root point.

In the typical usage, the first parameter is just dbEMPTY (see
example).

A TCC database symbolic address is built in 2 steps.
- The TCS database root point can be passed as first
  parameter or, by passing dbEMPTY, can be automatically
  retrieved from the system by using  tcsDbRoot(4)
- The path described by the format string given as second
  parameter and by the format parameters (just like a printf())
  is appended to this TCS root path allowing to define a
  complete symbolic address.

If an object contains a hierarchy of points, the top level
object normally call tcsMakeDbPoint(dbEMPTY,....), while
the internal objects can just pass the path already build for the
toplevel (see example).
This function can be safely called only after ccsInit() has
been executed.

A standard TCS application, handling command line arguments via
the tcsMAIN_HANDLER(4) class should call this function
only after having called the Init() method of tcsMAIN_HANDLER(4)

A proper error handling makes sure that these rules are applied

ENVIRONMENT


  TCS_DBPOINT specifies the root point of the TCS database branch,
              if it is not the default.

RETURN VALUES


In case of error the function return NULL

CAUTIONS


This function can be safely called only after ccsInit() has
been executed.

A standard TCS application, handling command line arguments via
the tcsMAIN_HANDLER(4) class should call this function
only after having called the Init() method of tcsMAIN_HANDLER(4)

A proper error handling makes sure that these rules are applied

EXAMPLES


In the constructor of a TCS object, tcsMakeDbPoint() is called
in order to have the object pointing to the proper database support
point depending on the environment settings or on the given
command line parameters.
In the following example constructor definition:

mswCHANGE_FOCUS::mswCHANGE_FOCUS(mswMOD_LIST_MANAGER &listManager) :
   evhDB_TASK(tcsMakeDbPoint(dbEMPTY,":%s:%s",
                             mswDB_ENTRY_POINT,mswDB_FOCUS_POINT)),
   modListManager(listManager)
{
      myCmd = new mswSUB_OBJ( tcsMakeDbPoint(DbPoint(),
                              ":%s.%s",
                              mswCOMP_PATH, mswCOMP_ATTR);
}

the mswCHANGE_FOCUS class must refer on a specific subpoint
in the TCS path.
The path is then built in the following way:
- The TCS root point is retrieved from the system by passing dbEMPTY.
  by default it is ":Appl_data:TCS", can can be changed setting
  the environment variable TCS_DBPOINT os passing proper command line
  parameters.
- The Mode Switching module proper sub-root point is defined in the
  mswDefines.h by the #define  mswDB_ENTRY_POINT.
- The sub-path from the Mode Switching point down to the real
  Change Focuse point is the defined by mswDB_FOCUS_POINT and is appended
  to the end of the path.
In the body of the constructor, a sub-object is dynamically built.
Since it is a component, it is inside the hierarchy of the main object
and it is conveninet to call tcsMakeDbPoint() givin as first
parameter directly this path.

This document was created by man2html, using the manual pages.
Time: 10:08:47 GMT, April 23, 2012

VLT Software Documentation