Low-level CDM API

Below you will find a description of the external procedures in the CDM library that make up the low-level CDM API. These methods will mostly be called by higher-level AIMMS procedures in the CDM library, but may potentially also be called independently to implement functionality beyond that of the higher level functions.

Library Management Functions

cdm::CreateCDMRuntimeLibrary(categoryMap, categoryOrder, alternateName)

This function creates the CDMRuntime library, and sets up the internal data structures in the libcdm.dll needed to communicate category data with a CDM server.

Arguments:
  • categoryMap – provides the map of all identifiers to a CDM category
  • categoryOrder – specifies the relative order of dependencies between such identifiers, where a higher order identifier depends on lower order identifiers
  • alternateName – specifies an optional alternate name for each identifier under which it may still be found in the CDM database in case of a name change.
cdm::UninitializeCDMLibrary()

This function closes all connections to the CDM service the CDM client is connected to, stops the embedded CDM server (if started), and removes all internal data structures for categories and identifiers in those categories in the libcdm.dll.

cdm::StartListeningToDataChanges(timeout)

This function will cause libcdm.dll register itself with the AIMMS engine to be notified of changes to any identifier data, and starts separate thread to examine which CDM category (if any) are affected by these data changes, and for each of them calls an internal callback procedure specified in the cdm::CreateCategory() or cdm::ConnectToCategory() calls (with default implementation cdm::DataChangeProcedure) to act upon such a change. Based on the user-specified settings for the category, the CDM library may decide to automatically commit such changes, or register the change for the user to act upon, or take the actions implemented by a user-specified callback.

Arguments:
  • timeout – notifies the timeout in milliseconds, the libcdm.dll will wait before examining all CDM categories after receiving the last data change notification from the AIMMS engine
cdm::StopListeningToDataChanges()

This function will cause libcdm.dll to stop reacting to data change notifications by the AIMMS engine.

ApplicationDB Functions

cdm::ConnectToApplicationDatabase(URL, dbName, timeout)

Create a connection to the CDM server at the specified hostname and port, connect to the given application database, and register the given application database to use this connection for subsequent low-level calls. If the application database requested does not exist yet, the CDM server will create an empty application database with the given name. The call will fail if the server cannot be reached, of if the user is not authorized to access the application database.

Arguments:
  • URL – should be of the form tcp://hostname:port and specifies the hostname and TCP port where the CDM server can be reached
  • dbName – specifies the name of the application database to connect to. Notice that a single CDM server can serve multiple application database, each hosting a separate CDM data repository.
  • timeout – specifies the timeout that will be applied on any call to the given CDM server (default 90000 ms). Increase this number only when your application makes huge commits, which cannot be handled by the CDM server within the default timeout.

When successfully connecting to the CDM service, the cdm::ConnectToApplicationDatabase() function will call the cdm::SetCDMConnectedState() callback. This callback will also be called whenever the connection to the CDM service drops. The cdm::SetCDMConnectedState() will store the connected state in the cdm::ConnectedToCDMService parameter, and will call the procedure pointed to by the cdm::ConnectedStateProcedureHook parameter. This allows you to gracefully handle connection state changes in your application code, e.g. by trying to reconnects if the connection drops.

cdm::DeleteApplicationDatabase(dbName)

Delete the given application database. The function will fail if there is no connection the given application database, of if the user is not authorized to delete the application database.

Arguments:
  • dbName – specifies the name of the application database to delete.
cdm::GetKeyValue(dbName, key, value)

Retrieve the value for the given key from the key-value store embedded within given application database. The function will fail if the specified key cannot be found.

Arguments:
  • dbName – specifies the application database
  • key – specifies the key to look for
  • value – specifies the output argument in which the value will be stored.
cdm::SetKeyValue(dbName, key, value)

Set the value for the given key in the key-value store embedded within given application database. The function will fail if the user attempts to set the value for a protected key.

Arguments:
  • dbName – specifies the application database
  • key – specifies the key to set
  • value – specifies the value to be stored.

Branch and Revision Functions

cdm::EnumerateBranches(db, activeOnly)

Enumerate all branches in the given application database

Arguments:
  • db – specifies the application database to query
  • activeOnly – specifies whether to only list branches which have an active status
cdm::CreateBranch(db, branchName, branchAuthor, branchcomment, fromBranch, fromRev, authProfile)

Create a new branch from a given revision on an existing branch in a given application database. The function will if branch already exists in the application database, if the user has no global authorization to create branches, or to create branches on the given branch

Arguments:
  • db – specifies the name of the application database in which to create a new branch
  • branchName – specifies the name of the new branch to create
  • branchAuthor – specifies the name of the user who creates the branch.
  • branchcomment – specifies the comment entered by the user when creating the branch
  • fromBranch – specifies the branch name from which to branch
  • fromRev – specifies the revision on fromBranch from which to branch
  • authProfile – specifies the authorization profile name to apply to the new branch. If left empty, the new branch will inherit the authorization profile from its parent branch
cdm::SetBranchStatus(db, branchName, active)

Set the branch status to either active or inactive, which will effect the result of cdm::EnumerateBranches(). The function will fail if the branch does not exist, or if the user is not authorized to change the branch status.

Arguments:
  • db – specifies the name of the application database in which to set the branch status
  • branchName – specifies the name of the branch for which to set the status
  • active – specifies whether the branch should be set as active (1) or inactive (0)
cdm::GetGlobalBranch(db, branch)

Get the branch name of the branch in the application database set as the global branch. The gobal branch is initially set to the master branch. When calling the high-level cdm::ConnectToApplicationDB() procedure, the CDM library will checkout the latest revision of the global branch after connecting to an application database.

Arguments:
  • db – specifies the name of the application database for which to retrieve the global branch
  • branch – is the output parameter in which the global branch will be stored
cdm::SetGlobalBranch(db, branchName)

Set the global branch for a given application database. The function will fail if the branch does not exist in the application database, or if the user has no authorization to set the global branch.

Arguments:
  • db – specifies the name of the application database for which to set the global branch
  • branchName – specifies the name of the global branch to set.
cdm::GetRevisions(db, branchName, lowRev)

Get the information about all revisions on a specific branch of an application database. The results will be stored in the identifiers in the Library Interface/Revision Information section of the CDM library.

Arguments:
  • db – specifies the name of the application database from which to retrieve revision information
  • branchName – specifies the branch to use as a filter to retrieve revision information
  • lowRev – specifies the lowest revision number to retrieve.

Authorization Functions

cdm::EnumerateAuthorizationProfiles(db, activeOnly)

Enumerate the existing authorization profiles from the application database. The results will be stored in the identifiers in the Library Interface/Authorization section of the CDM library.

Arguments:
  • db – specifies the application database from which to retrieve authorization profiles
  • activeOnly – specifies whether to retrieve active authorization profiles only
cdm::AddAuthorizationProfile(db, profileName)

Add a new authorization profile to the application database. The details of the authorization profile to add will be taken from the identifiers in the Library Interface/Authorization section of the CDM library. The function will fail if the user is not authorized to add authorization profiles, or if the profile cannot be found in the model data.

Arguments:
  • db – specifies the application database to which to add a new authorization profile
  • profileName – specifies the name of the authorization profile to add
cdm::SetAuthorizationProfileStatus(db, profileName, active)

Set the authorization profile status to either active or inactive, which will effect the result of cdm::EnumerateAuthorizationProfiles(). The function will fail if the authorization profile does not exist, or if the user is not authorized to change the authorization profile status.

Arguments:
  • db – specifies the name of the application database in which to set the authorization profile status
  • profileName – specifies the name of the authorization profile for which to set the status
  • active – specifies whether the authorization profile should be set as active (1) or inactive (0)
cdm::SetBranchAuthorization(db, branchName, profileName)

Apply a given authorization profile to a branch in the application database. The function will fail if the profile does not exist or if the user is not authorized to change the authorizations for the given branch.

Arguments:
  • db – specifies the name of the application database for which to set the authorization profile for the branch
  • branchName – specifies the name of the new branch for which to set the authorization profile
  • profileName – specifies the name of the authorization profile to apply.

Category Functions

cdm::CreateCategory(db, category, notificationProcedure, dataChangeProcedure)

Create a new category, or update an existing category in the given application database, according to he category information passed through the cdm::CreateRuntimeLibrary() function, and set the notification and data change callback functions for the category. The function will fail if the user is not authorized to create or update the category, or if no information has been specified for the category in the call to cdm::CreateRuntimeLibrary().

Arguments:
  • db – specifies the application database in which to create or update a category.
  • category – specifies the category name to add or update.
  • notificationProcedure – specifies the notification callback to be used when new revision are added for the given category (defaults to cdm::DefaultCommitInfoNotification)
  • dataChangeProcedure – specifies the data change callback to be used when the CDM library detects changes in the data of the identifiers in the category (defaults to cdm::DataChangeProcedure)
cdm::ConnectToCategory(db, category, notificationProcedure, dataChangeProcedure)

Connect to an existing category in the given application database, according to he category information passed through the cdm::CreateRuntimeLibrary() function, and set the notification and data change callback functions for the category. The function will fail if the user is not authorized to connect the existing category, or if the category specification provided through cdm::CreateRuntimeLibrary() does not match the category information stored in the application database.

Arguments:
  • db – specifies the application database in which to connect to an existing category.
  • category – specifies the category name to connect to.
  • notificationProcedure – specifies the notification callback to be used when new revision are added for the given category (defaults to cdm::DefaultCommitInfoNotification)
  • dataChangeProcedure – specifies the data change callback to be used when the CDM library detects changes in the data of the identifiers in the category (defaults to cdm::DataChangeProcedure).

Commit and Pull Functions

cdm::CheckoutSnapshot(category, branch, revid, labelsOnly, skipInactive)

Checkout a data snapshot for all identifiers the specified category from the application database, for a given branch and revision. The snapshot can be specified to only retrieve the labels for root sets, or to also contain inactive data, i.e. identifier values registered in the application database for tuples containing root set elements that are not actually contained in the root set themselves in the snapshot. As a result of the call both the actual identifiers of the category will be updated, as well as the shadow identifiers holding the latest committed values and the revision numbers at which these values where committed. Also the branch and revision information for the category will be set to checkout revision. The function will fail if the user has no read access for the category or branch.

Arguments:
  • category – specifies the category for which to retrieve the data snapshot
  • branch – specifies the branch from which to retrieve the data snapshot for the category
  • revid – specifies the (optional) specific revision on the branch from which to retrieve the snapshot, if not specified the head of the specified branch will be taken
  • labelsOnly – specifies an optional argument whether or not to only retrieve root set elements, defaults to 0
  • skipInactive – specifies an optional argument whether or not to skip inactive data in the snapshot, defaults to 1
cdm::RevertToSnapshot(category, branch, revid, skipInactive)

Checkout a data snapshot for all identifiers the specified category from the application database, for a given branch and revision. The snapshot can be specified to also contain inactive data, i.e. identifier values registered in the application database for tuples containing root set elements that are not actually contained in the root set themselves in the snapshot. As a result of the call only the actual identifiers of the category will updated, but not the shadow identifiers holding the latest committed values and the revision numbers at which these values where committed, and the branch and revision information for the category will not be updated either. The function will fail if the user has no read access to the category or branch. This function will only revert the category to the requested category locally, committing the category after this call will be actually reverting the data on the current branch of the category to the state of the specified branch and revision in the application database as well.

Arguments:
  • category – specifies the category for which to retrieve the data snapshot
  • branch – specifies the branch from which to retrieve the data snapshot for the category
  • revid – specifies the (optional) specific revision on the branch from which to retrieve the snapshot, if not specified the head of the specified branch will be taken
  • skipInactive – specifies an optional argument whether or not to skip inactive data in the snapshot, defaults to 1
cdm::PullChanges(category, resolved)

Retrieve and apply the changes for all identifiers in the given category, compared to the state of the model data for the current branch and revision of that category. The resulting changes will be applied to the actual identifiers, as well as to the shadow identifiers holding the latest committed values and the revision numbers at which these values where committed. In case there are conflicts between the changes being applied pulled from the application database, and changes made to the local identifiers by the end-user, the CDM library will try to resolve the conflicts based on the current model settings. The function will fail if the user has no read access to the category or branch. If the function succeeds without conflicts, the branch and revision information for the category will be set to latest revision on the current branch.

Arguments:
  • category – specifies the category for which o
  • resolved – specifies an output argument, which indicates whether any conflicts were successfully resolved.
cdm::CherryPickChanges(category, branch, revfrom, revto, resolved)

Cherry pick changes from a range from a given branch, and apply them to all identifiers in the specified category in your current branch. The resulting changes will only be applied to the actual identifiers, In case there are conflicts between the changes being applied pulled from the application database, and changes made to the local identifiers by the end-user, the CDM library will try to resolve the conflicts based on the current model settings. To commit them to the application database, subsequently call the function cdm::CommitChanges(). The function will fail if the user has no read access to the category or branch to cherry pick from.

Arguments:
  • category – specifies the category to which to apply the cherry pick operations
  • branch – specifies the branch from which to cherry pick
  • revfrom – specifies the lower bound of the range of revisions on the specified branch to cherry pick changes from
  • revto – specifies the upper bound of the range of revisions on the specified branch to cherry pick changes from
  • resolved – specifies an output argument, which indicates whether any conflicts were successfully resolved.
cdm::ApplyCommits(category, branch, revfrom, revto, resolved, assignToId, applyToCommitted)

Apply changes from a range from a given branch, to the actual and/or committed identifiers of the specified category. In case there are conflicts between the changes being applied pulled from the application database, and changes made to the local identifiers by the end-user, the CDM library will try to resolve the conflicts based on the current model settings. The function will fail if the user has no read access to the category or branch to cherry pick from. This function is a more general version of cdm::CherryPickChanges() and has its main use when merging branches.

Arguments:
  • category – specifies the category to which to apply the selected commits
  • branch – specifies the branch from which to apply the selected commits
  • revfrom – specifies the lower bound of the range of revisions on the specified branch to apply the selected commits from
  • revto – specifies the upper bound of the range of revisions on the specified branch to apply the selected commits from
  • resolved – specifies an output argument, which indicates whether any conflicts when applying the commits to the actual identifiers were successfully resolved.
cdm::MergeDeltaInWithId(category)

Actually merge the changes stored in the DeltaInIdentifiers in CDMRuntime library for the specified category into the actual identifiers. Changes will only be applied if the corresponding tuple in DeltaInRevisionIdentifiers holds a non-zero value. This low-level procedure is used when merging branches, and can used to merge incoming changes when pulling changes or merging branches did not resolve successfully, and manual intervention is required. For examples of use, inspect the function cdm::MergeBranches.

Arguments:
  • category – specifies the category to which to apply the stored delta in changes.
cdm::CommitChanges(category, commitInfoProcedure)

Compute the local changes between the actual identifiers in the given category, and, if any, commit the resulting change set to the current branch of the category in the application database. If successful, update the CommittedIdentifiers with the local changes, and set the revision for the category to the revision under which the change set was stored. The function will fail if the user has no write access to the category or branch, or if the client is not at the latest revision of the current branch of the category. In the latter case, the client application should first pull the changes of current category, resolve any conflicts, and re-commit.

Arguments:
  • category – specifies the category for which to commit local changes to the current branch of the category in the application database
  • commitInfoProcedure – specifies an (optional) callback procedure (with default cdm::CommitInfoProvider), which will be called to retrieve the commit author and comment to be associated with the commit
cdm::RollbackChanges(category)

Reset the actual values of all identifiers in the given category, back to the values stored in the CommittedIdentifiers in the CDMRuntime library for the given category.

Arguments:
  • category – specifies the category for which to rollback the local changes
cdm::GetValuesLog(category, paramref, lowRev)

Retrieve a history log of previous values for a slice of an identifier in the given category on the current branch and store the history in the corresponding ValueLogIdentifiers of the CDMRuntime library. You can use this function to retrieve a detailed overview of changes to the given identifier slice, which you can, for instance, subsequently present to an end-user of your application.

Arguments:
  • category – specifies the category containing the identifier for which to retrieve the history log
  • paramref – specifies a slice of an identifier in your model for which to retrieve the history log
  • lowRev – specifies the lower bound of revisions for which to report any changes to the given identifier slice.
cdm::ComputeDeltaOut(category)

Compute the changes between the actual identifiers of the given category and the committed values stored in the CommittedIdentifiers section of CDMRuntimeLibrary for the category, store the changed values in the DeltaOutIdentifiers and set the corresponding tuples in the DeltaOutRevisionIdentifiers to 1. This low-level function is used when visually inspecting the differences between revisions.

Arguments:
  • category – specifies the category for which to compute the local changes.
cdm::ResolveIdentifierConflicts(category, idName, useLocal)

Low-level function used to resolved all conflicts for a given identifier in a category, either by always using the local changes or by always using the remote changes in case of a conflict. This function is used by the visual conflict resolution method implemented in the CDM library.

Arguments:
  • category – specifies the category for which to resolve conflicts
  • useLocal – specifies whether to always use local changes (1) or remote changes (0).
cdm::SetRevision(category, branch, revid)

Set the branch and revision for a given category, regardless of the actual contents of the identifiers in the category, and the contents of the category related shadow identifiers in the CDMRuntime library. Use this function only if you know what you are doing, as subsequent commits and pulls may give unexpected results if the state of the data in the shadow identifiers does not match the specified branch and revision.

Arguments:
  • category – specifies the category for which to set the branch and revision
  • branch – specifies the branch to set for the category
  • revid – specifies the (optional) specific revision within the branch to set for the category, if not set the head revision of the branch will be taken

Embedded Server Functions

cdm::StartEmbeddedCDMServer(path, configPath)

Start an embedded CDM server, which can be used for testing CDM during application development. The function fails if the listen port for the CDM service has already been taken.

Arguments:
  • path – specifies the directory where libcdmservice.dll can be found
  • configPath – specifies the directory from which to take the CDMConfig.xml file from which the embedded server will read its configuration
cdm::StopEmbeddedCDMServer()

Stop an embedded CDM server started earlier.

Utility Functions

cdm::CloneElementInCategory(category, setName, elemName, newName)

Clone a existing element to a new element in a given set, and clone all data defined for the existing element in the given category for the new element. If the existing element occurs in data of multiple categories, you may have to call this function for each category to achieve the desired effect.

Arguments:
  • category – specifies the category for which to clone all data for all identifiers in the category.
  • setName – specifies the set in which to clone the existing element
  • elemName – specifies the element name of the existing element
  • newName – specifies the element name of the new element to be cloned
cdm::EmptyElementInCategory(category, setName, elemName)

Empty all data defined over the existing element in the given category. If the existing element occurs in data of multiple categories, you may have to call this function for each category to achieve the desired effect.

Arguments:
  • category – specifies the category for which to empty all data for all identifiers in the category.
  • setName – specifies the set for which to empty all data for the existing element
  • elemName – specifies the element name of the existing element
cdm::CreateUuid(uuid)

Create a Universally Unique Identifier (UUID)

Arguments:
  • uuid – string output argument, in which the created UUID will be stored.