# 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 to the application. 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 Details for a description of these fields.

#### Return values

Return value | Description
SUCCESS |
CTAERR_ALREADY_DEFINED | Duplicate service or service manager exists in svcname.
CTAERR_ALREADY_INITIALIZED | A Natural Access service was already initialized.
CTAERR_BAD_SIZE | initparms size field is not valid.
CTAERR_FILE_NOT_FOUND | The file name specified in CTA_INIT_PARMS is not found or cta.cfg is not found.
CTAERR_FUNCTION_ACTIVE | Two separate threads called ctaInitialize at the same time. The first thread executed the function correctly. The second thread received 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 or svcnames is incompatible with the Natural Access dispatcher.
CTAERR_INVALID_LIB | The specified action (usually setting the ctaflags bits) could not be performed because the application is not linked to the appropriate Natural Access library.
CTAERR_LOAD_LIB | An error occurred while loading the Natural Access core library.
CTAERR_NOT_FOUND | One or more services are not found or listed services are not found in the configuration file.
CTAERR_SHAREMEM_ACCESS | One of the following conditions occurred: Shared system parameters or tracing is enabled but ctdaemon is not running. CTA_PARM_MGMT_SHARED bit is set in parmflags but one or more of the specified services are 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.

#### Details

ctaInitialize finds all service managers and services that the application needs. Call this function only once at application initialization.

You can register services in one of the following ways:

- Invoke ctaInitialize and specify the service and service manager names of all the services you plan to use. The application can use only the services specified in the call to ctaInitialize.

- Invoke ctaInitialize, pass NULL for svcname, and pass a user-defined Natural Access configuration file name. cta.cfg is the default configuration file name if a file name is not specified. ctaInitialize looks in the [ctasys] header section of the configuration file for the list of service and service manager names.

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 calling ctaInitialize, you can modify and retrieve global default parameters, and create and destroy event queues and contexts.

The CTA_INIT_PARMS structure contains the following fields:

Field | Description
--- | ---
size | Indicates the size of the passed structure.
parmflags | Specifies where the global default parameters are stored. Valid values are: CTA_PARM_MGMT_LOCAL (default) Global default parameters are stored in process local memory. CTA_PARM_MGMT_SHARED Global default parameters are stored in shared system memory. ctdaemon must be running and the shared memory created. An error is returned if ctdaemon is not running. CTA_PARM_MGMT_SHARED_IF_PRESENT Global default parameters are stored in shared system memory and an error is not returned if ctdaemon is not running. If this setting is chosen and ctdaemon is not running, the default parameter management setting is local to the process. If you are using a local or remote server, the system ignores these flags. Parameter management applies to the entire system and cannot be overridden. Refer to Global default parameters for more information on parameter storage.
traceflags | Provides a backlog of trace information on a context when an error condition occurs. To observe trace information for all contexts, do not enable this feature. 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. If you are using a local or remote server, the system ignores these flags.
daemonflags | Set to zero (0).
ctaflags | Specifies the context and queue settings. Valid values are: CTA_NOTIFY_UPDATE_WAITOBJS (0x1) Natural Access sends CTAEVN_UPDATE_WAITOBJS when there is a change to the internal array of Natural Access wait objects. Set this flag 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)(default) Commands from all queues sent to the server are serialized. 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) 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) The Natural Access Server functionality runs in 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) 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 cta.cfg. CTA_CONTEXTNAME_REQUIRE_UNIQUE (0x20) 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) The local server can 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 the file to use to obtain the service names. To use a user-defined file, pass NULL for svcname and pass the user-defined file name. ctaInitialize looks in the [ctasys] header section of the specified file for the service names. If there is a spelling error in the [ctasys] section of the file, the service and service manager are not initialized. To use cta.cfg, pass NULL for svcname and NULL for filename. ctaInitialize looks in the [ctasys] header section of cta.cfg for the service names. If you pass a svcname and a file name, the file name is ignored. If filename does not contain a path, the path specified in the environment variable CTA_DPATH is searched.
ctacompatlevel | Verifies Natural Access compatibility. Valid values are: CTA_COMPATLEVEL Verifies Natural Access compatibility. Zero (0) Omits compatibility checking. The compatibility level is changed if the release includes changes requiring applications to be recompiled. 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 Natural Access configuration file for information on cta.cfg. Refer to Natural Access Server: ctdaemon for more information on ctdaemon.

#### See also

ctaQueryWaitObjects, ctaSetTraceLevel

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