ctaInitialize

Establishes a list of services available to a Natural Access application.

Prototype

DWORD ctaInitialize ( CTA_SERVICE_NAME svcname[], unsigned nsvcs, CTA_INIT_PARMS *initparms)

Argument	Description
svcname	Pointer to an array of service names to make available for the application process. The CTA_SERVICE_NAME structure is: typedef struct { char svcname; / name of service / char svcmgrname; /* name of service manager */ } CTA_SERVICE_NAME;
nsvcs	Number of services in svcname.
initparms	Pointer to a structure containing initialization parameters. The CTA_INIT_PARMS structure is: typedef struct { DWORD size; DWORD parmflags; DWORD traceflags; DWORD daemonflags; DWORD ctaflags; char *filename; DWORD ctacompatlevel; DWORD reserved } CTA_INIT_PARMS; See the Details section for a description of these fields.

Return values

Return value	Description
SUCCESS
CTAERR_ALREADY_DEFINED	There is a duplicate service or service manager in svcname.
CTAERR_ALREADY_INITIALIZED
CTAERR_BAD_ARGUMENT	initparms is NULL.
CTAERR_BAD_SIZE	initparms size field is not valid.
CTAERR_FILE_NOT_FOUND	The filename specified in CTA_INIT_PARMS is not found or cta.cfg is not found.
CTAERR_FUNCTION_ACTIVE	Two separate threads have called ctaInitialize at the same time. The first thread executes the function correctly, the second thread receives this error.
CTAERR_INCOMPATIBLE_PARMS	The same services provided by two or more service managers have different standard parameters.
CTAERR_INCOMPATIBLE_REVISION	One of the specified services/svcnames is incompatible with the Natural Access dispatcher.
CTAERR_INVALID_LIB	The specified action (usually setting ctaflags bits) could not be performed because the application is not linked to the appropriate Natural Access library.
CTAERR_LOAD_LIB	There was an error loading the Natural Access core library.
CTAERR_NOT_FOUND	One or more services are not found or listed services are not found in filename.
CTAERR_SHAREMEM_ACCESS	Shared system parameters or tracing is enabled but ctdaemon is not running, or the CTA_PARM_MGMT_SHARED bit is set in parmflags but one or more of the specified services is not being managed within ctdaemon. Update cta.cfg to contain all required services and restart ctdaemon.
CTAERR_WRONG_COMPAT_LEVEL	Installed Natural Access compatibility level is different from the application-specified compatibility level.

Events

None.

Details

This function finds all service managers and services that the application needs. It should be called only once at application initialization.

Note: If you want to use a remote server but pass NULL for svcname and pass the configuration file name cta.cfg, cta.cfg on the local server may not specify the same available services as the remote server.

After ctaInitialize is called, global default parameters can be modified and retrieved, and event queues and contexts can be created and destroyed.

The CTA_INIT_PARMS structure contains the following fields:

Field	Description
size	Size of the passed structure.
parmflags	Specifies where the global default parameters are stored. If you want global default parameters to be stored in process local memory, set parmflags to CTA_PARM_MGMT_LOCAL (this is the default). If you want global default parameters to be stored in shared system memory, ctdaemon must be running and the shared memory created. If you want global default parameters to be stored in shared system memory, and you want an error to be returned if ctdaemon is not running, set parmflags to CTA_PARM_MGMT_SHARED. If this setting is chosen and ctdaemon is not running, CTAERR_SHAREMEM_ACCESS is returned. Since an error is not returned if ctdaemon crashes, parmflags cannot be used to check ctdaemon. If you want global default parameters to be stored in shared system memory, but you do not want an error to be returned if the ctdaemon is not running, set parmflags to CTA_PARM_MGMT_SHARED_IF_PRESENT. If this setting is chosen and ctdaemon is not running, the default parameter management setting will be local to the process. If using a local or remote server, these flags are ignored. Parameter management is system-global automatically, and cannot be overridden. Refer to Global default parameters for more information on parameter storage.
traceflags	Allows you to receive a backlog of trace information on a context when an error condition occurs. Enable this feature if you want to see what happens on a per-context basis when you get an error. Do not enable this feature if you want to observe trace information for all contexts. Set the CTA_TRACE_ENABLE bit to enable tracing. ctdaemon must be running and maintaining the system-wide trace buffer for all Natural Access applications. Since an error is not returned if ctdaemon crashes, traceflags cannot be used to check ctdaemon. Set the CTA_TRACE_ENABLE and CTA_TRACE_ON_ERROR bits to enable the backtracing on error option. To write all recently logged trace messages on a particular context to ctdaemon, call ctaLogTrace, specifying the context you want to analyze, and set the traceseverity argument to CTA_TRACE_SEVERITY_ERROR. These flags are ignored if using a local or remote server.
daemonflags	Set to zero (0).
ctaflags	CTA_NOTIFY_UPDATE_WAITOBJS (0x1) When set, Natural Access sends a CTAEVN_UPDATE_WAITOBJS event when there is a change to the internal array of Natural Access wait objects. This flag should be set when wait objects are managed by the application. Do not set this flag if wait objects are managed by Natural Access. Refer to ctaRegisterWaitObject to allow Natural Access to manage the application wait objects. CTA_COMMS_SERIALIZE (0x2) When set, commands from all queues sent to the server are serialized (this is the default). This mode requires fewer system resources, allowing more event queues to be created. This flag is ignored if the application is using Natural Access functionality in the process address space (inproc). Note: When this bit is set under UNIX, a process cannot fork. Each process must create its own session to the server. CTA_COMMS_NOTSERIALIZE (0x4) When set, commands from all queues sent to the server are not serialized. This mode requires more system resources, limiting the number of event queues that can be created. This flag is ignored if the application is using Natural Access functionality in the process address space (inproc). CTA_MODE_LIBRARY (0x8) When set, the Natural Access Server functionality runs within the process address space. Contexts created using this flag are specific to the application and cannot be shared. This flag corresponds to the DefaultServer=inproc parameter in cta.cfg. CTA_MODE_SERVER (0x10) When set,the Natural Access Server functionality runs in a Natural Access Server (ctdaemon) that is separate from the application, but on the same host. Contexts created using this flag can be shared. This flag corresponds to the DefaultServer=localhost parameter in the cta.cfg. CTA_MODE_LIBRARY \| CTA_MODE_SERVER (0x18) When set, the Natural Access Server functionality runs within the process address space. The setting corresponds to the DefaultServer=inproc parameter in the cta.cfg. Because of changes in Natural Access software, this setting is no longer recommended. If you want to create a shared context within Natural Access Server (ctdaemon), refer to ctaCreateContext for more information. CTA_CONTEXTNAME_REQUIRE_UNIQUE (0x20) When set, Natural Access cannot modify the context name to ensure uniqueness. If two applications specify the same context name, the second application receives an error. This flag is ignored if the application is using Natural Access functionality in the process address space (inproc). CTA_CONTEXTNAME_CREATE_UNIQUE (0x40) When set, this flag allows the local server to modify context names specified by client applications so that context names are not duplicated (default). This flag is ignored if the application is using Natural Access functionality in the process address space (inproc).
filename	Determines what file name is used to obtain the service names. If you pass NULL for svcname and pass a user-defined filename, ctaInitialize looks in the [ctasys] header section of the specified file name for the service names. Errors are ignored. For example, if there is a spelling error in the [ctasys] section of the file, the service and service manager will not be initialized. If you pass NULL for svcname and filename is also NULL, ctaInitialize looks in cta.cfg. If you pass a svcname and pass a filename, the file name is ignored. If filename does not contain a path, the path specified in the environment variable CTA_DPATH is searched.
ctacompatlevel	Set to CTA_COMPATLEVEL to verify Natural Access compatibility. To omit compatibility checking, set this value to zero (0). The compatibility level is changed if the release includes changes that require applications to be re-compiled because these changes are not backward compatible. Refer to Verifying compatibility for more information.
reserved	Reserved for future use. Set this value to zero (0).

Refer to Initializing Natural Access applications for more information.

Refer to Contents of the Natural Access configuration file for information on the cta.cfg file. Refer to Natural Access server: ctdaemon for more information on ctdaemon.

Example

static CTA_SERVICE_NAME InitServices[] = { { "ADI", "ADIMGR" },
                                           { "SWI", "SWIMGR" },
                                           { "VCE", "VCEMGR" } };

void DemoInitialize()
{
    DWORD ret;
    CTA_INIT_PARMS initparms = { 0 };

    /* Initialize size of init parms structure */
    initparms.size = sizeof(CTA_INIT_PARMS);

    /* Use process global default parameters */
    initparms.parmflags |= CTA_PARM_MGMT_LOCAL;

    /* If daemon running then initialize tracing */
    initparms.traceflags = CTA_TRACE_ENABLE;

    /* Notify when Natural Access changes its internal list of wait objects*/
    initparms.ctaflags = CTA_NOTIFY_UPDATE_WAITOBJS;

    /* Verify Natural Access compatibility */
    initparms.ctacompatlevel = CTA_COMPATLEVEL;

    /* Initialize Natural Access */
    ctaInitialize(InitServices,
                  sizeof(InitServices)/sizeof(InitServices[0]),
                  &initparms);
}

Note: For QX boards, replace ADIMGR with QDIMGR.