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);

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);

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);

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);

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);

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);

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);

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);

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;
          }
        }

  // ...