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:

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)
    C    ommands 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.