appCORE - coreInit()

NAME

coreInit() -- configure and initialize appCORE.

SYNOPSIS

include "appcore.h"

int coreInit( coreSPEC_t* s )

DESCRIPTION

The coreInit() function initializes appCORE and must be called before any other appCORE function. If other appCORE functions are called before this function, results are undefined. The user configures appCORE via the coreSPEC_t data record defined below. Always zero the coreSPEC_t record before setting the desired parameters to insure reliable operation, default behavior, and compatibility with future releases.

After successful execution of this function, appCORE shall be in the 'initialized' state. The application can then be started via coreAppStart(), or it is possible to exit the initialized state via coreDeinit(). The coreDeinit() function transitions appCORE back to the 'uninitialized' state.

coreInit() attaches the calling thread to appCORE and performs the necessary initialization of internal data structures to support appCORE functions. The calling thread appears as thread "main" in output logging as this thread is normally the main thread of the process. In a standard appCORE application, the main thread either provides a local console and logging output, or is "parked" waiting for the application to shutdown. coreDeinit() performs a thread detach on this thread. coreInit() and coreDeinit() must be called from the same thread. Refer to the sample applications for an example of a standard appCORE main() function.

PARAMETERS

s   
    typedef struct  _core_spec_
    {
    char ConfigFileName[ MAX_PATH + 1 ];
    
    	Specifies the full path name to the appCORE configuration file as a null
    	terminated string. This element is optional. Parameters defined in this 
    	configuration file take precedence over parameters specified in this
    	specification record. This allows for control of the application without
    	recompiling.
    
    char AppName[ CORE_APP_NAME_LEN + 1 ];
    
    	The name of the application as a null terminated string. This name 
    	appears in the startup banner, can be accessed via a command session,
    	and appears in logging output. This element is optional. The configuration
		file entry is "app.name".
    
    char AppVersion[ CORE_APP_VERSION_LEN + 1 ];
    
    	The version of the application as a null terminated string. This version
    	appears in the startup banner and can be accessed via a command session.
		This element is optional. The configuration file entry is "app.version".
    
    char AppLockFileName[ MAX_PATH + 1 ];
    
    	Specifies the full path name to the application's lock file as a null
    	terminated string. If specified, the application will check for the existence
    	of this file. If found, the function will fail with a return code of -1 and 
    	set errno to EEXIST. If not found, the application will create a file of this
    	name that contains the process identifier (PID). On application exit, the file 
        is deleted. This element is optional. The configuration file entry is 
        "app.lockfile.name". On some platforms, if the file contains a stale PID, it
        is automatically deleted.
    
	int  coreSyslogOn;
    
    	If non-zero, appCORE starts the Syslog component and the Syslog parameters
    	below must be set for correct operation. The configuration file entry is
    	"core.syslog.on".
	
    int AppCmdSesLocalOn;
    
    	If non-zero, the application will present a command session using stdin and
    	stdout. Also, logging output will be displayed on stdout. The configuration
		file entry is "app.console.on"
    
    int AppCmdSesPort;
    
    	If non-zero, the application will listen on this port for incoming 
    	TCP connections. The application will create a command session for each 
    	connection. Multiple command session connections are supported. The config-
		uration file entry is "app.cmd.port".
    
    coreSAI AppCmdSesBindAddr;
    
    	If non-zero, specifies the binding address for the network command session.
    	If not specified, the port will be bound to INADDR_ANY. The configuration file
		entry is "app.cmd.bindaddr".
    
    int  coreTimerOff;
    
    	The timer facility is a standard appCORE feature and is enabled by default.
    	To disable the timer component, this value must be non-zero. The configuration
    	file entry is "core.timer.off".
    
    int  coreNetworkOff; 
    
    	The network facility is a standard appCORE feature and is enabled by default.
    	To disable the network component, this value must be non-zero. The configuration
    	file entry is "core.network.off".
    
    int  coreSignalOff;
    
    	The signal handler facility is a standard appCORE feature and is enabled by 
    	default. To disable the signal handler component, this value must be non-zero.
    	The configuration file entry is "core.signal.off". All platforms support some
    	level of signal handling. 
    	
    int  coreMsgPoolOff;
    
    	The message pool facility is a standard appCORE feature and is enabled by 
    	default. To disable the message pool and use the heap directly for each 
    	message allocation and free operation, this value must be non-zero. The 
    	configuration file entry is "core.msgpool.off".
    
    int  coreStatsMemOn;
    
    	If non-zero, enables the collection of memory statistics. Default behavior
    	is off.
    
    int  coreStatsMsgOn; 
    
    	If non-zero, enables the collection of message statistics. Default behavior
    	is off.
    
    int  coreStatsThrOn;
    
    	If non-zero, enables the collection of thread statistics. Default behavior
    	is off.
    
    coreSAI  coreSysLogAddr;
    
    	If non-zero, defines the send address of a syslog connection.
    
    unsigned short  coreSysLogPort;
    
    	If non-zero, defines the port address of the Syslog connection.
    
    unsigned int    coreSysLogOptions;
    
    	Defines Syslog options
    
    unsigned char   LogLevel[ LZ_MAX - LZ_START ];
    
    	The LogLevel array provides a way to specify any appCORE trace zones before 
        appCORE is started. The specified trace zone levels are copied into the main 
        control block. Trace zones can be initialized via the coreLogZoneInit() 
        function.
    }
    coreSPEC_t;

RETURN VALUE

If successful, coreInit() returns 0. Upon return, all requested appCORE features are functional. If an error occurs, it returns a value of -1 and sets errno to one of the following values:

errno Value	Condition
ECANCELED	appCORE not in the de-initialized state.
ENOENT	Unable to open specified configuration file.
EINVAL	Argument invalid or NULL.

MULTITHREAD SAFETY LEVEL

MT-safe.