Session

Reference to functions related to creating and closing Salience sessions, license authentication, loading configurations, and obtaining information about the current session.

lxaLoadLicense

Summary: This function should be provided a valid license and produces a LexalyticsLicense structure, which handles license authentication. This structure should then be passed to lxaOpenSalienceSession to proceed with session creation. After use, lxaFreeString should be called on the passed char buffer to free used memory.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaLoadLicense(const char *acPath, LexalyticsLicense *pLicense, char **acError);

Parameter

Description

acPath

Pointer to a null-terminated string containing the path to the required license file

pLicense

Pointer to a LexalyticsLicense structure

acError

Pointer to a char buffer

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
    a valid LexalyticsLicense */

  char *acLicensePath = "/path/to/license/file";
  char *acError;
  LexalyticsLicense oLicense;

  // Load license
  if(lxaLoadLicense(acLicensePath, &oLicense, &acError) != LXA_OK) {
    // Print to standard output stream and free used memory 
    std::cout << acError << std::endl;
    lxaFreeString(acError);
    lxaFreeLicense(&acLicensePath);
    return 1;
  }

  // ...

lxaOpenSalienceSession

Summary: This function takes the LexalyticsLicense structure created with lxaLoadLicense and creates a SalienceSession structure. This structure must exist before any other functions can be performed because its address is expected as an argument.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaOpenSalienceSession(LexalyticsLicense *pLicense, SalienceSessionStartup *pOptions, SalienceSession **ppSession);

Parameter

Description

pLicense

Pointer to a LexalyticsLicense structure

pOptions

Pointer to a SalienceSessionStartup structure

ppSession

Pointer to pointer to a SalienceSession structure

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
      a valid LexalyticsLicense */

  char *acDataDirectory = "/path/to/data/directory";

  // Load startup options
  SalienceSessionStartup oStartup;
  strcpy(oStartup.acDataDirectory, acDataDirectory);
  oStartup.nStartupLog = 1;

  // Open SalienceSession
  SalienceSession *pSession; 
  if(lxaOpenSalienceSession(oLicense, &oStartup, &pSession) != LXA_OK) {
    return 1;
  }

  // ...

lxaCloseSalienceSession

Summary: This function takes an active SalienceSession structure, makes available any resources allocated to it, and ends the session.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaCloseSalienceSession(SalienceSession *pSession);

Parameter

Description

pSession

Pointer to a SalienceSession structure

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
    a valid LexalyticsLicense */

  // Open Salience Session
  SalienceSession *pSession; 
  if(lxaOpenSalienceSession(oLicense, &oStartup, &pSession) != LXA_OK) {
    return 1;
  }

  // ...

  if(lxaCloseSalienceSession(pSession) != LXA_OK) {
    return 1;
  }

lxaGetSalienceVersion

Summary: This function takes a pointer to a character buffer and returns the current version of the Salience Engine. You can use this to display a version of the underlying Salience Engine in use. After use lxaFreeString on the pointer to char passed to this function to release memory.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetSalienceVersion(char ** ppBuffer);

Parameter

Description

ppBuffer

Pointer to a char buffer that contain the current version of Salience

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
    a valid LexalyticsLicense */

  char *acVersion;
  lxaGetSalienceVersion(&acVersion);

  // Print to std::cout and release allocated memory
  std::cout << acVersion << std::endl;
  lxaFreeString(acVersion);

  // ...

lxaGetDefaultSalienceLocation

Summary: Gets the root location for the Salience installation. On Windows, this is based on the value of a registry key created during install. On Linux, it is based on the lxainstall environment variable. After use call lxaFreeString on ppBuffer to release the memory.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetDefaultSalienceLocation(char **ppBuffer);

Parameter

Description

ppBuffer

Pointer to a char buffer that will contain the location of your Salience installation

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
    a valid LexalyticsLicense */

  char *acRootPath;
  lxaGetDefaultSalienceLocation(&acRootPath);

  // Print to std::cout and release allocated memory
  std::cout << acRootPath << std::endl;
  lxaFreeString(acRootPath);

  // ...

lxaAddSalienceConfiguration

Summary: This function takes a pointer to a SalienceSession structure, buffer for user directory, and buffer for configuration id. It will add the user directory, with the specified configurations to the provided Salience session. To access additional processing options and results from the new configuration use acConfigurationID. Calling this method with a value for acConfigurationID that has been previously added will result in an error.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaAddSalienceConfiguration(SalienceSession *pSession, const char *acUserDir, const char *acConfigurationID);

Parameter

Desctription

pSession

Pointer to a SalienceSession structure

acUserDir

Path to a user directory to use for this configuration

acConfigurationID

Character buffer specifying a unique identifier for this configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with
    a valid LexalyticsLicense */

  char *pUserDir = "path/to/user/dir";
  char *pConfigurationID = "your-config-id-here";

  if(lxaAddSalienceConfiguration(pSession, pUserDir, pConfigurationID) != LXA_OK) {
    return 1; 
  }

  // ...

lxaRemoveSalienceConfiguration

Summary: This function removes the user defined configuration matching the specified configuration ID from the current Salience session. If acConfigureationID is either empty or is unrecognized this will result in error.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaRemoveSalienceConfiguration(SalienceSession *pSession, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

acConfigurationID

Character string specifying a unique identifier for a configuration previously added to the session

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession has already been opened with a valid LexalyticsLicense
     and that the configuration you're removing has already been added */

  char *pConfigurationID = "your-config-id-here";

  if(lxaRemoveSalienceConfiguration(pSession, pConfigurationID) != LXA_OK) {
    return 1; 
  }

  // ...

lxaRunModelSmokeTest

Summary:" This function runs smoke tests to ensure that the installed Salience version is compatible with the models in the data directory. Please use the output of this function to create detailed reports for support engagements.

A smoke test is successful if the number of "success" messages is at least 1 (showing that smoke testing was invoked) and the number of "failure" messages is 0 (showing that no errors arose during smoke testing).

The acConfigurationID parameter specifies the configuration for the results, which are returned in a ModelSmokeTestList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaRunModelSmokeTest(SalienceSession *pSession, ModelSmokeTestList *pSuccesses, ModelSmokeTestList *pFailures, const char *acConfigurationID = nullptr);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pSuccesses

Pointer to a ModelSmokeTestList structure that will get filled in by the call

pFailures

Pointer to a ModelSmokeTestList structure that will get filled in by the call

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

// Assuming a SalienceSession has already been opened with a valid LexalyticsLicense

    ModelSmokeTestList oSuccesses;
  ModelSmokeTestList oFailures;

  // No argument for acConfigurationID to use default configuration
  int result = lxaRunModelSmokeTest(pSession, &oSuccesses, &oFailures);

  if (result != 0) {
    std::cout << "function failed with Salience error " << result <<  endl;
  } else if (oSuccesses.nEntries == 0) {
      std::cout << "smoke testing was not successfully invoked." << endl;
    } else if (oFailures.nEntries == 0) {
        std::cout << "No errors found." << endl;
      } else {
          for (int i = 0; oFailures.nEntries; i++) {
            std::cout << "acModelPath: " << oFailures.pEntries->acModelPath << endl;
            std::cout << "acMessage: " << oFailures.pEntries->acMessage << endl;
            std::cout << "acExplanation: " << oFailures.pEntries->acExplanation << endl;
            std::cout << "acDocumentId: " << oFailures.pEntries->acDocumentId << endl;
            std::cout << "acExpectedLabel: " << oFailures.pEntries->acExpectedLabel << endl;
            std::cout << "acActualLabel: " << oFailures.pEntries->acActualLabel << endl;
            std::cout << "acExpectedSpanOffset: " << oFailures.pEntries->acExpectedSpanOffset << endl;
            std::cout << "acActualSpanOffset: " << oFailures.pEntries->acActualSpanOffset << endl;
            std::cout << "acExpectedSpanLength: " << oFailures.pEntries->acExpectedSpanLength << endl;
            std::cout << "acActualSpanLength: " << oFailures.pEntries->acActualSpanLength << endl;
          }
        }

  // ...