NUCM-2.0 Documentation
Interface

[Concepts | Interface]

This section describes the NUCM interface which consists of eight classes of functions:

Access - functions to gain and relinquish access to artifacts in a NUCM logical repository
Versioning - functions to version artifacts
Collection - functions to manipulate collections
Query - functions to query for certain information
Attribute - functions to manipulate attributes of artifacts
Removal - functions to remove artifacts from a NUCM logical repository
Distribution - functions to manipulate the physical distribution of artifacts in a NUCM logical repository
Miscellaneous - functions to perform miscellaneous tasks

All interface functions use the NdbErrnovariable to indicate, if an error occurred, the type of error that occurred.

NUCM-2.0 Documentation
Interface: Access

The following functions are provided by NUCM to gain and relinquish access to artifacts in a NUCM logical repository:

nc_open - opens an artifact in a workspace
nc_close - closes an artifact in a workspace

NUCM-2.0 Documentation
Interface: Access: nc_open

Signature

int  nc_open(const char*  path,
             const char*  p_cwd,
	     const char*  prefix_target,
             const char*  t_cwd)

Functionality

Gains access to the artifact determined by the parameters path and p_cwd and places its contents in the workspace determined by the parameters prefix_target and t_cwd. The contents of the artifact is always retrieved from a NUCM logical repository, even if the parameters path and p_cwd point to an artifact already existing in another workspace.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact determined by path and p_cwd has not been opened in the workspace
NdbOpen	:	the artifact is already open in the workspace
NdbExist	:	a different artifact with the same name already exists in the workspace
NdbUnequal	:	the path and target represent two different artifacts that have the same name
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming our repository is filled with projects, and in particular contains a project "my_project" that has the members "1", "2", "3", "4", and "5". Assuming furthermore a workspace exist with no contents at this point:

   /home/bigtime/andre/workspace

This project and its members can be opened in the workspace as follows:

   #include "nc.h"

   t_memberlist*  memberlist;
   t_memberlist*  member;

   nc_open("//serl.cs.colorado.edu:1234/nucm_root/my_project",
	   "",
	   "/home/bigtime/andre/workspace",
	   "");
   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      nc_open(member->name,
	      "/home/bigtime/andre/workspace/my_project",
	      "/home/bigtime/andre/workspace/my_project",
	      "");
      member = member->next;
   }

Note that the first call to nc_open uses a path that includes a repository, but that the subsequent calls simply use a path in the workspace to open artifacts. Execution of the above code fragment results in the following workspace contents:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

An alternative use of nc_open occurs when existing artifacts in a workspace are opened in a different workspace. For example, to make a copy of the above workspace in a different workspace "/home/serl/carzanig/workspace", the following code fragment can be used:

   #include "nc.h"

   t_memberlist*  memberlist;
   t_memberlist*  member;

   nc_open("/home/bigtime/andre/workspace/my_project",
	   "",
	   "/home/serl/carzanig/workspace",
	   "");
   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      nc_open(member->name,
	      "/home/bigtime/andre/workspace/my_project",
	      "/home/serl/carzanig/workspace/my_project",
	      "");
      member = member->next;
   }

The result of execution of this code fragment is two identical workspaces that reside in different places.

NUCM-2.0 Documentation
Interface: Access: nc_close

Signature

int  nc_close(const char*  target,
              const char*  t_cwd,
              int  forced)

Functionality

Relinquishes access to an artifact. The artifact is removed from the workspace. If the artifact is a collection, all members of the collection are removed as well. If the artifact is a collection and itself or one or more of its members is initiated, the close does not succeed unless the close is forced. A close is forced if the value of the parameter forced is 1, a close is not forced if the value of the parameter forced is 0.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbInitiated	:	the artifact is a collection and itself or one or more of its members is initiated and the close is not forced

Example

Assuming a workspace has been opened that contains a project "my_project" and its members "1", "2", "3", "4", "5". Assume furthermore artifact "1" has been initiated. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

This workspace can be closed as follows:

   #include "nc.h"

   nc_close("/home/bigtime/andre/workspace/my_project/1",
	    "",
	    1);
   nc_close("/home/bigtime/andre/workspace/my_project",
	    "",
	    0);

The first call to nc_close forces artifact "1" to be closed even though it has been initiated. The second call to nc_close closes all the artifacts within my_project as well. The resulting workspace contents is as follows:

   /home/bigtime/andre/workspace

Of course, a single call

   #include "nc.h"

   nc_close("/home/bigtime/andre/workspace/my_project",
	    "",
	    1);

would have had the same effect as the above two calls, but would have also closed other artifacts that could have been initiated, whereas the separation in two calls will generate an error if another artifact was initiated.

NUCM-2.0 Documentation
Interface: Versioning

The following interface functions are provided by NUCM to version artifacts:

nc_initiatechange - initiates change on an artifact in a workspace
nc_abortchange - aborts change on an artifact in a workspace
nc_commitchange - creates a new version of an artifact in a workspace
nc_commitchangeandreplace - overwrites an existing version of an artifact in a workspace

NUCM-2.0 Documentation
Interface: Versioning: nc_initiatechange

Signature

int  nc_initiatechange(const char*  target,
                       const char*  t_cwd)

Functionality

Initiates change on the artifact determined by the interpretation of the parameters target and t_cwd. Only artifacts in a workspace can be initiated. Once the artifact is initiated, it can be modified. However, it can not be initiated again until either nc_commitchange, nc_commitchange, or nc_commitchangeandreplace has been called for the artifact. It is possible for a single artifact to be initiated multiple times as long as each initiation takes place in a different workspace.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbInitiated	:	the artifact is already initiated in the workspace

Example

   /home/bigtime/andre/workspace

This project and its members can be opened and initiated in the workspace as follows:

   #include "nc.h"

   t_memberlist*  memberlist;
   t_memberlist*  member;

   nc_open("//serl.cs.colorado.edu:1234/nucm_root/my_project",
	   "",
	   "/home/bigtime/andre/workspace",
	   "");
   nc_initiatechange("my_project",
	             "/home/bigtime/andre/workspace");
   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      nc_open(member->name,
	      "/home/bigtime/andre/workspace/my_project",
	      "/home/bigtime/andre/workspace/my_project",
	      "");
      nc_initiatechange(member->name,
	                "/home/bigtime/andre/workspace/my_project");
      member = member->next;
   }

Execution of the above code fragment results in the following workspace contents:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

The artifacts "1", "2", "3", "4", and "5" can at this point all be changed. In addition, "my_project" can be manipulated using the collection interface functions.

NUCM-2.0 Documentation
Interface: Versioning: nc_abortchange

Signature

int  nc_abortchange(const char*  target,
                    const char*  t_cwd,
		    int  forced)

Functionality

Aborts change on the artifact determined by the interpretation of the parameters target and t_cwd. The contents of the artifact is restored to the contents of the version that was initiated, and the artifact can not be modified anymore. If the artifact is a collection, all members of the collection are closed. If the artifact is a collection and one or more of its members is initiated, the abort does not succeed unless the abort is forced. An abort is forced if the value of the parameter forced is 1, an abort is not forced if the value of the parameter forced is 0.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbNotInit	:	the artifact is not initiated
NdbInitiated	:	the artifact is a collection and one or more of its members is initiated and the abort is not forced
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its members "1", "2", "3", "4", and "5" have been opened and initiated in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To abort change on artifact "5" and return it to its original state, the following code fragment can be used:

   #include "nc.h"
   
   nc_abortchange("my_project/5",
	          "/home/bigtime/andre/workspace",
		  1);

Artifact "5" will now have been returned to its original contents before nc_initiatechange was applied to it. To return the whole workspace to its original state, use the following code fragment:

   #include "nc.h"

   nc_abortchange("my_project",
	          "/home/bigtime/andre/workspace",
		  1);

The workspace will now have been returned to the following state:

   /home/bigtime/andre/workspace/my_project

NUCM-2.0 Documentation
Interface: Versioning: nc_commitchange

Signature

int  nc_commitchange(const char*  target,
                     const char*  t_cwd,
                     char*  version)

Functionality

Commits change on the artifact determined by the interpretation of the parameters target and t_cwd. A new version of the artifact is created in a logical NUCM repository and the contents of the new version is set to the current contents of the artifact. The previous version of the artifact in the repository remains unchanged. After committing change, the artifact can not be modified anymore. The parameter version is set to the version number of the newly created artifact. It is assumed that the parameter version holds enough space to place the version number in. The resulting value is NULL-terminated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbNotInit	:	the artifact is not initiated
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its member "5" have been opened and initiated in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To store the changes made to artifact 5, add an collection 6 to "my_project", and to store the changes made to "my_project", both by creating a new version of the artifact, the following code fragment can be used:

   #include "nc.h"
   
   char  newversion[MAX_VERSION_LENGTH + 1];

   nc_commitchange("my_project/5",
	           "/home/bigtime/andre/workspace",
		   newversion);
   mkdir("/home/bigtime/andre/workspace/my_project/6",
	 0644);
   nc_add("my_project/6",
	  "/home/bigtime/andre/workspace",
	  "/home/bigtime/andre/workspace/my_project",
	  "");
   nc_commitchange("my_project",
	           "/home/bigtime/andre/workspace",
		   newversion);

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5
					    6

NUCM-2.0 Documentation
Interface: Versioning: nc_commitchangeandreplace

Signature

int  nc_commitchangeandreplace(const char*  target,
                               const char*  t_cwd)

Functionality

Commits change on the artifact determined by the interpretation of the parameters target and t_cwd. No new version of the artifact is created in a NUCM logical repository, instead the contents of the initiated version of the artifact is set to the current contents of the artifact. After committing change, the artifact can not be modified anymore.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbNotInit	:	the artifact is not initiated
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its member "5" have been opened and initiated in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To store the changes made to artifact 5, add an collection 6 to "my_project", and to store the changes made to "my_project", both without creating a new version of the artifact but by overwriting the current version, the following code fragment can be used:

   #include "nc.h"
   
   nc_commitchangeandreplace("my_project/5",
	           "/home/bigtime/andre/workspace");
   mkdir("/home/bigtime/andre/workspace/my_project/6",
	 0644);
   nc_add("my_project/6",
	  "/home/bigtime/andre/workspace",
	  "/home/bigtime/andre/workspace/my_project",
	  "");
   nc_commitchangeandreplace("my_project",
	                     "/home/bigtime/andre/workspace");

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5
					    6

NUCM-2.0 Documentation
Interface: Collection

The following interface functions are provided by NUCM to manipulate collections:

nc_add - adds an artifact to a collection
nc_remove - removes an artifact from a collection
nc_rename - renames an artifact in a collection
nc_replaceversion - replaces an artifact in a collection with a different version of the artifact
nc_copy - copies the history of an artifact and adds the copied artifact to a collection

NUCM-2.0 Documentation
Interface: Collection: nc_add

Signature

int  nc_add(const char*  path,
            const char*  p_cwd,
	    const char*  prefix_target,
            const char*  t_cwd)

Functionality

Adds the artifact determined by the parameters path and p_cwd to the collection determined by the path prefix_target and t_cwd. The collection has to which the artifact is added has to be initiated. Three types of additions are possible:

addition of a new artifact: the artifact is a file (atom) or directory (collection) in the file system that is currently not maintained by NUCM. If the artifact is not present in the current workspace, it is copied there. A new artifact is created in the NUCM logical repository, and its contents is set to the current contents of the artifact in the workspace. A new collection is by definition empty when added.
import of an existing artifact in another workspace: the artifact is an artifact that is already maintained by NUCM and has been opened in another workspace. The artifact is copied into the current workspace. No new artifact is created in the NUCM logical repository, instead both the collection where the artifact came from and the collection to which it has been added reference the same artifact.
mount of an existing artifact in a NUCM logical repository: the artifact is an artifact that is maintained by a NUCM logical repository. The artifact is copied from the NUCM logical repository into the current workspace. No new artifact is created in the NUCM logical repository, instead the collection references the existing artifact. This variant of the addition interface function is the function that is capable of combining artifacts from various NUCM physical repositories into a NUCM logical repository.

The initial version of the artifact that is created is 1.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbLonely	:	no collection present in the workspace to which the artifact can be added
NdbNotInit	:	the collection to which to add the artifact is not initiated
NdbExist	:	a different artifact with the same name already exists in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, each project being a member of the nucm_root collection. Furthermore, an empty workspace has been created earlier:

   /home/bigtime/andre/workspace

To create a new project "my_project", the following code fragment can be used:

   #include "nc.h"
   
   nc_open("//serl.cs.colorado.edu:1234/nucm_root",
	   "",
	   "/home/bigtime/andre/workspace",
	   "");
   nc_initiatechange("nucm_root",
		     "/home/bigtime/andre/workspace");
   mkdir("/home/bigtime/andre/workspace/nucm_root/my_project,
	 0644);
   nc_add("my_project",
	  "/home/bigtime/andre/workspace/nucm_root",
	  "/home/bigtime/andre/workspace/nucm_root",
	  "");
   nc_commitchangeandreplace("nucm_root",
	                     "/home/bigtime/andre/workspace");
   nc_close("/home/bigtime/andre/workspace/nucm_root",
	    "");

The workspace is now empty again. To populate the newly created project with for example the existing files ".login" and ".cshrc" from "/home/bigtime/andre", the following code fragment can be used:

   #include "nc.h"
   
   char  newversion[MAX_VERSION_LENGTH + 1];

   nc_open("//serl.cs.colorado.edu:1234/nucm_root/my_project",
	   "",
	   "/home/bigtime/andre/workspace",
	   "");
   nc_initiatechange("my_project",
		     "/home/bigtime/andre/workspace");
   nc_add(".login",
	  "/home/bigtime/andre",
	  "my_project",
	  "/home/bigtime/andre/workspace");
   nc_add(".cshrc",
	  "/home/bigtime/andre",
	  "my_project",
	  "/home/bigtime/andre/workspace");
   nc_commitchange("my_project",
	           "/home/bigtime/andre/workspace",
		   &newversion);

A new version of "my_project" has been created with ".login" and ".cshrc" as its members. The workspace now looks like:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc

Assuming the first code fragment above has been used to create a new project "his_project" as well, but that the project is still empty. To populate "his_project" with the same artifacts ".login" and ".cshrc" from "my_project" the following code fragment can be used:

   #include "nc.h"

   char  newversion[MAX_VERSION_LENGTH + 1];

   nc_open("//serl.cs.colorado.edu:1234/nucm_root/his_project",
	   ""
	   "/home/bigtime/andre/workspace",
	   "");
   nc_initiatechange("his_project",
		     "/home/bigtime/andre/workspace");
   nc_add(".login",
	  "/home/bigtime/andre/workspace/my_project",
	  "/home/bigtime/andre/workspace/his_project",
	  "");
   nc_add("//serl.cs.colorado.edu:1234/nucm_root/my_project/.cshrc",
	  "",
	  "/home/bigtime/andre/workspace/his_project",
          "");
   nc_commitchange("his_project",
	           "/home/bigtime/andre/workspace",
		   &newversion);

The first nc_add illustrates an import from one workspace into another, the second nc_add illustrates a mount as it directly references an artifact in a repository. The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc
				/his_project/.login
					     .cshrc

Both ".login" artifacts and both ".cshrc" artifacts represent the same respective artifact.

NUCM-2.0 Documentation
Interface: Collection: nc_remove

Signature

int  nc_remove(const char*  target,
               const char*  t_cwd,
               int  forced)

Functionality

Removes the artifact determined by the parameters target and t_cwd from the collection in the workspace. If the artifact has been opened, the artifact is removed from the workspace. If the artifact is a collection, its members are removed from the workspace as well. If the artifact is a collection and itself or one or more of its members is initiated, the remove does not succeed unless the remove is forced. A remove is forced if the value of the parameter forced is 1, a remove is not forced if the value of the parameter forced is 0. The collection from which the artifact is removed has to be initiated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbLonely	:	no collection present in the workspace from which the artifact can be removed
NdbNotInit	:	the collection from which to remove the artifact is not initiated
NdbInitiated	:	the artifact is a collection and itself or one or more of its members is initiated and the remove is not forced

Example

Assuming a repository is filled with projects, and in particular contains two projects "my_project" and "his_project" that both contain the artifacts ".login" and ".cshrc". Furthermore, a workspace has been created earlier in which "my_project" and its artifacts have been opened:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc

To remove ".cshrc" from "my_project", the following code fragment can be used:

   #include "nc.h"
   
   nc_initiatechange("my_project",
		     "/home/bigtime/andre/workspace");
   nc_remove(".cshrc",
	     "/home/bigtime/andre/workspace/nucm_root",
	     "/home/bigtime/andre/workspace/nucm_root",
	     "");
   nc_commitchangeandreplace("my_project",
	                     "/home/bigtime/andre/workspace");

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/.login

The artifact ".cshrc" still exists in the repository at this point, as "his_project" still contains it. If we now want to remove all of "his_project", the following code fragment can be used:

   #include "nc.h"
   
   nc_open("//serl.cs.colorado.edu:1234/nucm_root",
	   "",
	   "/home/bigtime/andre/workspace",
	   "");
   nc_initiatechange("nucm_root",
		     "/home/bigtime/andre/workspace");
   nc_remove(".his_project",
	     "/home/bigtime/andre/workspace/nucm_root",
	     0);
   nc_commitchangeandreplace("nucm_root",
	                     "/home/bigtime/andre/workspace");
   nc_close("nucm_root",
	    "/home/bigtime/andre/workspace",
	    0);

Two things are noteworthy about this code fragment. Firstly, "his_project" did not need to have been opened to be removed from "nucm_root". Would it have been opened, it would have been removed from the workspace. Secondly, artifact ".cshrc" is not referenced by "my_project", and as "his_project" is removed from the repository and it contained the last reference to ".cshrc", ".cshrc" will be garbage collected.

NUCM-2.0 Documentation
Interface: Collection: nc_rename

Signature

int  nc_rename(const char*  target,
               const char*  t_cwd,
               const char*  new_name)

Functionality

Renames the artifact determined by the parameters target and t_cwd in the collection in the workspace to the name given in the parameter new_name. If the artifact has been opened, it is also renamed in the workspace. The collection in which the artifact is renamed has to be initiated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbLonely	:	no collection present in the workspace in which the artifact can be renamed
NdbNotInit	:	the collection in which to rename the artifact is not initiated
NdbExist	:	a different artifact with the same name already exists in the workspace

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that contains the artifacts ".login" and ".cshrc". Furthermore, a workspace has been created earlier in which "my_project" and its artifacts have been opened:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc

To rename ".login" and ".cshrc" to "autoexec.bat" and "config.sys", the following code fragment can be used:

   #include "nc.h"
   
   nc_initiatechange("my_project",
		     "/home/bigtime/andre/workspace");
   nc_rename(".login",
	     "/home/bigtime/andre/workspace/my_project",
	     "autoexec.bat");
   nc_rename(".cshrc",
	     "/home/bigtime/andre/workspace/my_project",
	     "config.sys");
   nc_commitchangeandreplace("my_project",
	                     "/home/bigtime/andre/workspace");

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/autoexec.bat
					    config.sys

It should be noted that ".login" and ".cshrc" did not need to have been opened to be renamed.

NUCM-2.0 Documentation
Interface: Collection: nc_replaceversion

Signature

int  nc_replaceversion(const char*  target,
                       const char*  t_cwd,
                       const char*  version,
		       int  forced)

Functionality

Replaces the current version of the artifact determined by the parameters target and t_cwd in the collection in the workspace with the version determined by the parameter version. If the artifact has been opened, it is also replaced in the workspace. If the artifact is a collection, all members of the collection are closed. If the artifact is a collection and one or more of its members are initiated, the replacement does not succeed unless the replacement is forced. A replacement is forced if the value of the parameter forced is 1, a replacement is not forced if the value of the parameter forced is 0. The collection in which the version of the artifact is replaced has to be initiated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbLonely	:	no collection present in the workspace in which the artifact can be replaced
NdbNotInit	:	the collection in which to replace the artifact is not initiated
NdbInitiated	:	the artifact is a collection and one or more of its members is initiated and the remove is not forced
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc

To change the version of ".login" to be version "3" in the collection "my_project", the following code fragment can be used:

   #include "nc.h"
   
   char  version[MAX_VERSION_LENGTH + 1];

   nc_initiatechange("my_project",
		     "/home/bigtime/andre/workspace");
   nc_version("my_project/.login",
	      "/home/bigtime/andre/workspace",
	      version);
   if (strcmp(version, "3") != 0) {
      nc_replaceversion("my_project/.login",
			"/home/bigtime/andre/workspace",
			"3",
			1);
   }
   nc_commitchangeandreplace("my_project",
	                     "/home/bigtime/andre/workspace");

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc

It should be noted that ".login" and ".cshrc" did not need to have been opened to be renamed. In addition, the code fragment can be rewritten as follows:

   nc_initiatechange("my_project",
		     "/home/bigtime/andre/workspace");
   nc_replaceversion("my_project/.login",
		     "/home/bigtime/andre/workspace",
		     "3",
	  	     1);
   nc_commitchangeandreplace("my_project",
	                     "/home/bigtime/andre/workspace");

as nc_replaceversion already checks whether the current version of an artifact is the requested version and won't take any action if it is.

NUCM-2.0 Documentation
Interface: Collection: nc_copy

Signature

int  nc_copy(const char*  path,
             const char*  p_cwd,
	     const char*  prefix_target,
             const char*  t_cwd,
	     const t_server*  server)

Functionality

Copies the history of the artifact determined by the parameters path and p_cwd to the NUCM server determined by the parameter server, and then adds this newly created artifact to the collection determined by the path prefix_target and t_cwd. The new artifact is opened in the workspace. The collection has to be initiated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbLonely	:	no collection present in the workspace to which the artifact can be added
NdbNotInit	:	the collection to which to add the artifact is not initiated
NdbExist	:	a different artifact with the same name already exists in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that contains the artifacts ".login" and ".cshrc". In addition, it contains an empty project "his_project". Furthermore, a workspace has been created earlier in which "my_project" and its artifacts, as well as "his_project", have been opened:

   /home/bigtime/andre/workspace/my_project/.login
					    .cshrc
				 his_project/

To populate "his_project" with ".login" and ".cshrc" as separate objects with a separate version history, the following code fragment can be used:

   #include "nc.h"

   t_server  server;
   
   strcpy(server.host, "anchor.cs.colorado.edu");
   sprintf(server.port, "%d", NUCM_PORT):
   nc_initiatechange("his_project",
		     "/home/bigtime/andre/workspace");
   nc_copy(".login",
	   "/home/bigtime/andre/workspace/my_project",
	   "/home/bigtime/andre/workspace/his_project",
	   "",
	   &server);
   nc_copy("//serl.cs.colorado.edu:1234/nucm_root/my_project/.cshrc",
           "",
	   "/home/bigtime/andre/workspace/his_project",
	   "",
	   &server);
   nc_commitchangeandreplace("his_project",
	                     "/home/bigtime/andre/workspace");

The workspace now looks as follows:

   /home/bigtime/andre/workspace/my_project/autoexec.bat
					    config.sys

It should be noted that ".login" and ".cshrc" did not need to have been opened to be renamed.

NUCM-2.0 Documentation
Interface: Query

The following interface functions are provided by NUCM to query for certain information:

nc_list - determines the members of a collection
nc_gettype - determines the type of an artifact
nc_version - determines the version of an artifact
nc_lastversion - determines the last created version of an artifact
nc_existsversion - determines the existence of a version of an artifact
nc_isinitiated - determines whether an artifact is initiated or not

NUCM-2.0 Documentation
Interface: Query: nc_list

Signature

int  nc_list(const char*  path,
             const char*  p_cwd,
             t_memberlist**  memberlist)

Functionality

Sets the value of the parameter memberlist to the list of artifacts contained in the NUCM collection determined by the interpretation of the parameters path and p_cwd. Each member in the list contains the name and version of an artifact contained in the NUCM collection. The list of members is allocated for the caller, but needs to be de-allocated by the caller.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbAtomList	:	the artifact is an atom and can not be listed
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects. To obtain a list of projects that are available in the repository, the following code fragment can be used:

   #include "nc.h"

   t_memberlist*  memberlist;
   t_memberlist*  member;

   nc_list("//serl.cs.colorado.edu:1234/nucm_root",
	   "",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      printf("%s, %s\n", member->name, member->version);
      member = member->next;
   }

NUCM-2.0 Documentation
Interface: Query: nc_gettype

Signature

int  nc_gettype(const char*  path,
                const char*  p_cwd)

Functionality

Determines the type of the NUCM artifact determined by the interpretation of the parameters path and p_cwd.

Return Values

COLLECTION	: everything went ok and the artifact is a collection
ATOM	: everything went ok and the artifact is an atom
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To determine the type of each of the artifacts "1" and "5", the following code fragment can be used:

   #include "nc.h"
   
   int  type;

   type = nc_gettype("my_project/1",
		     "/home/bigtime/andre/workspace");
   if (type == -1) {
      printf("Error obtaining type\n");
   } elseif (type == ATOM) {
      printf("Type is ATOM\n");
   } else {
      printf("Type is COLLECTION\n");
   }
   type = nc_gettype("my_project/5",
		     "/home/bigtime/andre/workspace");
   if (type == -1) {
      printf("Error obtaining type\n");
   } elseif (type == ATOM) {
      printf("Type is ATOM\n");
   } else {
      printf("Type is COLLECTION\n");
   }

NUCM-2.0 Documentation
Interface: Query: nc_version

Signature

int  nc_version(const char*  path,
                const char*  p_cwd,
                char*  version)

Functionality

Sets the value of the parameter version to the version number of the artifact determined by the interpretation of the parameters path and p_cwd. It is assumed that the parameter version holds enough space to place the version number in, i.e., is at least MAX_VERSION_LENGTH in size. The resulting value is NULL-terminated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To determine the version of each of the artifacts "1", "2", "3", "4", and "5", the following code fragment can be used:

   #include "nc.h"
   
   t_memberlist*  memberlist;
   t_memberlist*  member;
   char  version[MAX_VERSION_LENGTH + 1];

   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      nc_version(member->name,
		 "/home/bigtime/andre/workspace/my_project",
		 version);
      printf("%s: version %s", member->name, version);
      member = member->next;
   }

NUCM-2.0 Documentation
Interface: Query: nc_lastversion

Signature

int  nc_lastversion(const char*  path,
                    const char*  p_cwd,
                    char*  version)

Functionality

Sets the value of the parameter version to the version number of the last created version of the artifact determined by the interpretation of the parameters path and p_cwd. It is assumed that the parameter version holds enough space to place the version number in, i.e., is at least MAX_VERSION_LENGTH in size. The resulting value is NULL-terminated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To update the workspace with the last version of each of the artifacts "1", "2", "3", "4", and "5", the following code fragment can be used:

   #include "nc.h"
   
   t_memberlist*  memberlist;
   t_memberlist*  member;
   char  lastversion[MAX_VERSION_LENGTH + 1];
   char  version[MAX_VERSION_LENGTH + 1];
   char  newartifact[MAXPATHLEN + 1];

   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      nc_lastversion(member->name,
		     "/home/bigtime/andre/workspace/my_project",
		     lastversion);
      nc_version(member->name,
		 "/home/bigtime/andre/workspace/my_project",
		 version);
      if (strcmp(lastversion, version) != 0) {
	 nc_close(member->name,
		  "/home/bigtime/andre/workspace/my_project",
		  0);
         sprintf(newartifact, "%s%c%s", member->name, VERSION_SEPARATOR,
		 lastversion);
	 nc_open(newartifact,
		 "/home/bigtime/andre/workspace/my_project",
		 "/home/bigtime/andre/workspace/my_project",
		 "");
      }
      member = member->next;
   }

The workspace looks as follows now (the same as above):

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

The contents of the artifacts "1", "2", "3", "4", and "5" however is different from the previous workspace if the version in the workspace was not identical to the last version of the artifact.

NUCM-2.0 Documentation
Interface: Query: nc_existsversion

Signature

int  nc_existsversion(const char*  path,
                      const char*  p_cwd,
		      const char*  version)

Functionality

Determines whether the version determined by the parameter version of the artifact determined by the interpretation of the parameters path and p_cwd exists.

Return Values

1	: everything went ok and the version does exist
0	: everything went ok and the version does not exist
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project". To examine which versions of "my_project" exist, the following code fragment can be used:

   #include "nc.h"

   char  lastversion[MAX_VERSION_LENGTH + 1];
   char  version[MAX_VERSION_LENGTH + 1];
   int  result;
   int  i;

   nc_lastversion("//serl.cs.colorado.edu:1234/nucm_root/my_project/4",
		  "",
		  lastversion);
   for (i = 1 ; i <= atoi(lastversion) ; i++) {
      sprintf(version, "%d", i);
      result = nc_existsversion("//serl.cs.colorado.edu:1234/nucm_root/my_project/4",
				"",
				version);
      if (result == -1) {
	 printf("Error during examination of existence of version %d", i);
      } else if (result == 0) {
	 printf("Version %d does not exist\n", i);
      } else {
	 printf("Version %d does exist\n", i);
      }
   }

NUCM-2.0 Documentation
Interface: Query: nc_isinitiated

Signature

int  nc_isinitiated(const char*  target,
                    const char*  t_cwd)

Functionality

Determines whether the artifact determined by the interpretation of the parameters target and t_cwd is initiated.

Return Values

1	: everything went ok and the artifact is initiated
0	: everything went ok and the artifact is not initiated
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace

Example

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To examine which artifacts in the workspace have been initiated, the following code fragment can be used:

   #include "nc.h"
   
   t_memberlist*  memberlist;
   t_memberlist*  member;
   int  result;

   nc_list("my_project",
	   "/home/bigtime/andre/workspace",
	   &memberlist);
   member = memberlist;
   while (member != NULL) {
      result = nc_isinitiated(member->name,
		              "/home/bigtime/andre/workspace/my_project");
      if (result == -1) {
	 printf("Error during examination of %s\n", member->name);
      } else if (result == 0) {
	 printf("%s not initiated\n", member->name);
      } else {
	 printf("%s initiated\n", member->name);
      }
      member = member->next;
   }

NUCM-2.0 Documentation
Interface: Attribute

The following interface functions are provided by NUCM to manipulate attributes of individual versions of artifacts:

nc_testandsetattribute - sets the value of an attribute of an artifact
nc_getattributevalue - determines the value of an attribute of an artifact
nc_removeattribute - removes an attribute from an artifact

NUCM-2.0 Documentation
Interface: Attribute: nc_testandsetattribute

Signature

int  nc_testandsetattribute(const char*  path,
		            const char*  p_cwd,
		            const char*  attrname,
			    const char*  value)

Functionality

If and only if the attribute determined by the parameter attrname does not exist for the NUCM artifact determined by the interpretation of the parameters path and p_cwd, creates this attribute in a NUCM logical repository and sets its value to the value of the parameter value.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbExist	:	the attribute exists already and can not be overwritten
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its members "1" and "2" have been opened and initiated in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2

To store a new version of "2" and to record some context of the changes made, the following code fragment can be used:

   #include "nc.h"

   char  newversion[MAX_VERSION_LENGTH + 1];

   nc_commitchange("2",
		   "/home/bigtime/andre/workspace/my_project",
		   &newversion);
   nc_testandsetattribute("my_project/2",
			  "/home/bigtime/andre/workspace",
			  "author",
			  "Andre van der Hoek");
   nc_testandsetattribute("my_project/2",
			  "/home/bigtime/andre/workspace",
			  "comments",
			  "Created a new version to demonstrate NUCM");
   nc_testandsetattribute("my_project/2",
			  "/home/bigtime/andre/workspace",
			  "date",
			  "05/27/1997");

NUCM-2.0 Documentation
Interface: Attribute: nc_getattributevalue

Signature

int  nc_getattributevalue(const char*  path,
		          const char*  p_cwd,
		          const char*  attrname,
			  char*  value)

Functionality

Returns the value of the parameter attrname for the NUCM artifact determined by the interpretation of the parameters path and p_cwd. It is assumed that the parameter value holds enough space to place the value of the attribute in. The resulting value is NULL-terminated.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbNonExist	:	the attribute does not exist
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its members "1" and "2" have been opened in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2

To examine the context of the latest changes made to "2", the following code fragment can be used:

   #include "nc.h"

   char  value[1024 + 1];

   nc_getattributevalue("my_project/2",
			"/home/bigtime/andre/workspace",
			"author",
			value);
   printf("The author was: %s", value);
   nc_getattributevalue("my_project/2",
			"/home/bigtime/andre/workspace",
			"comments",
			value);
   printf("The comments were: %s", value);
   nc_getattributevalue("my_project/2",
			"/home/bigtime/andre/workspace",
			"date",
			value);
   printf("The date was: %s", value);

NUCM-2.0 Documentation
Interface: Attribute: nc_removeattribute

Signature

int  nc_removeattribute(const char*  path,
		         const char*  p_cwd,
		         const char*  attrname)

Functionality

Physically removes the attribute determined by the parameter attrname for the NUCM artifact determined by the interpretation of the parameters path and p_cwd from a NUCM logical repository.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbNonExist	:	the attribute does not exist
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its members "1" and "2" have been opened in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2

To update the context of the changes made to the current version of "2", the following code fragment can be used:

   #include "nc.h"

   char  value[1024 + 1];

   nc_getattributevalue("my_project/2",
			"/home/bigtime/andre/workspace",
			"comments",
			&value);
   nc_removeattribute("my_project/2",
		      "/home/bigtime/andre/workspace",
		      "comments");
   sprintf(value, "%s\n%s", value,
	   "Forgot to demonstrate that attributes can be removed too");
   nc_testandsetattribute("my_project/2",
			  "/home/bigtime/andre/workspace",
			  "comments",
			  value);

NUCM-2.0 Documentation
Interface: Removal

Signature

int  nc_destroyversion(const char*  path,
		       const char*  p_cwd,
		       const char*  version)

Functionality

Physically removes a single version of the NUCM artifact determined by the interpretation of the parameters path and p_cwd from a NUCM logical repository. The version that is removed is determined by the parameter version, and is only removed if it is not referenced by any collections.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbRefcount	:	the version of the artifact can not be removed because it is still referenced by one or more collections
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with project, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Artifact "4" has many versions, and some of these versions are members of other projects. To remove all versions of "4" that are not members of any project, the following code fragment can be used:

   #include "nc.h"

   char  lastversion[MAX_VERSION_LENGTH + 1];
   char  version[MAX_VERSION_LENGTH + 1];
   int  i;

   nc_lastversion("//serl.cs.colorado.edu:1234/nucm_root/my_project/4",
		  "",
		  lastversion);
   for (i = 1 ; i <= atoi(lastversion) ; i++) {
      sprintf(version, "%d", i);
      result = nc_destroyversion("//serl.cs.colorado.edu:1234/nucm_root/my_project/4",
				 "",
				 version);
      if (result == -1) {
	 if (NdbErrno == NdbRefCount) {
	    printf("Version %d is a member of a project\n", i);
	 } else {
	    printf("Error during removal of version %d", i);
	 }
      } else {
	 printf("Version %d was removed\n", i);
      }
   }

NUCM-2.0 Documentation
Interface: Distribution

The following interface functions are provided by NUCM to manipulate the physical distribution of artifacts in a logical repository:

nc_move - moves an artifact to a different physical repository
nc_getlocation - determines the physical location of an artifact
nc_setmyserver - sets the default NUCM server for a CM client

NUCM-2.0 Documentation
Interface: Distribution: nc_move

Signature

int  nc_move(const char*  path,
	     const char*  p_cwd,
	     const t_server*  server)

Functionality

Physically moves the history of the NUCM artifact determined by the interpretation of the parameters path and p_cwd to the NUCM server addressed by the parameter server. The move has no other effect than that the history of the artifact is moved to a different physical location, all operations on the artifact continue to operate as normal.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a repository is filled with projects, and in particular contains a project "my_project" that has members "1", "2", "3", "4", and "5". Furthermore, "my_project" and its members "1" and "2" have been opened in a workspace. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2

A new repository has been created, with an access server running on machine "anchor.cs.colorado.edu" that listens to default port "1234", and that the project and its members "2", "3", and "4" have to be moved into that repository. The following code fragment can be used to do so:

   #include "nc.h"

   t_server  server;

   strcpy(server.host, "anchor.cs.colorado.edu");
   sprintf(server.port, "%d", NUCM_PORT);
   nc_move("//serl.cs.colorado.edu/nucm_root/my_project/3",
	   "",
	   &server);
   nc_move("//serl.cs.colorado.edu/nucm_root/my_project/4",
	   "",
	   &server);
   nc_move("my_project",
	   "/home/bigtime/andre/workspace"
	   &server);
   nc_move("2",
	   "/home/bigtime/andre/workspace/my_project",
	   &server);

Note that port "1234" is the default port a NUCM access server listens to, so we use the NUCM_PORT macro to set it in the variable server. In addition, the workspace has not changed, and artifacts can still be accessed and versioned in the same way. The only thing that has changed is the physical location of the artifacts that have been moved.

NUCM-2.0 Documentation
Interface: Distribution: nc_getlocation

Signature

int  nc_getlocation(const char*  path,
                    const char*  p_cwd,
                    t_server*  server)

Functionality

Determines the address of the NUCM server where the history of the NUCM artifact determined by the interpretation of the parameters path and p_cwd is physically located, and places the resulting server address in the parameter server.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbUnknown	:	the path does not represent a NUCM artifact
NdbNotOpen	:	the NUCM artifact has not been opened in the workspace
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming a workspace has been opened that contains a project "my_project" and its members "1", "2", "3", "4", and "5". The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project/1
					    2
					    3
					    4
					    5

To obtain the physical location of "my_project" and members "2" and "3", the following code fragment can be used:

   #include "nc."h

   t_server  server;

   nc_getlocation("my_project/2",
                  "/home/bigtime/andre/workspace/",
		  &server);
   printf("location: %s, %s", server.host, server.port);
   nc_getlocation("3",
                  "/home/bigtime/andre/workspace/my_project",
		  &server);
   printf("location: %s, %s", server.host, server.port);
   nc_getlocation("my_project",
                  "/home/bigtime/andre/workspace/",
		  &server);
   printf("location: %s, %s", server.host, server.port);

NUCM-2.0 Documentation
Interface: Distribution: nc_setmyserver

Signature

void  nc_setmyserver(const t_server*  server)

Functionality

Sets the default NUCM server that serves this client to the server addressed by the parameter server. The default NUCM server is the server where newly created artifacts are stored.

Return Values

None

NdbErrno Codes

None

Example

Assuming two access servers are running on two different machines: "serl.cs.colorado.edu" and "anchor.cs.colorado.edu" and both are listening to the default NUCM port. Assume a workspace exist in which a project "my_project" has been opened and initiated. The workspace looks as follows:

   /home/bigtime/andre/workspace/my_project

The following code fragment illustrates how different artifacts can be added to different repositories.

   #include "nc.h"

   t_server  server;

   strcpy(server.host, "serl.cs.colorado.edu");
   sprintf(server.port, NUCM_PORT);
   nc_setmyserver(&server);
   nc_add("/usr/include/stdio.h",
	  ""
	  "/home/bigtime/andre/workspace/my_project",
	  "");
   strcpy(server.host, "anchor.cs.colorado.edu");
   nc_setmyserver(&server);
   nc_add("/usr/include/malloc.h",
	  ""
	  "/home/bigtime/andre/workspace/my_project",
	  "");

Note that port "1234" is the default port a NUCM access server listens to, so we use the NUCM_PORT macro to set it in the variable server. After execution of this code fragment, "stdio.h" will physically be located at "serl.cs.colorado.edu" and "malloc.h" at "anchor.cs.colorado.edu".

NUCM-2.0 Documentation
Interface: Miscellaneous

The following interface functions are provided by NUCM for miscellaneous purposes:

nc_ping - determines whether a NUCM server is up
nc_shutdown - shuts down a NUCM server

NUCM-2.0 Documentation
Interface: Miscellaneous: nc_ping

Signature

int  nc_ping(const t_server*  server)

Functionality

Determines whether the NUCM server addressed by the parameter server is up.

Return Values

1	: everything went ok and the server is up
0	: everything went ok and the server is not up
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

To see whether an access server is active on a machine "serl.cs.colorado.edu" and is listening to port "1234", the following code fragment can be used:

   #include "nc.h"

   t_server  server;

   strcpy(server.host, "serl.cs.colorado.edu");
   sprintf(server.port, "%d", NUCM_PORT);
   if ((running = nc_ping(&server)) == -1) {
      fprintf(stderr, "nc_ping failed\n");
   } else if (running) {
      printf("server %s, %d is running\n", server.host, server.port);
   } else {
      printf("server %s, %d is not running\n", server.host, server.port);
   }

Note that port "1234" is the default port a NUCM access server listens to, so we use the NUCM_PORT macro to set it in the variable server.

NUCM-2.0 Documentation
Interface: Miscellaneous: nc_shutdown

Signature

int  nc_shutdown(const t_server*  server)

Functionality

Shuts down the NUCM server addressed by the parameter server. The server is not shut down until all pending requests have been served. However, no new requests are accepted.

Return Values

0	: everything went ok
-1	: an error occurred

NdbErrno Codes

NdbOk	:	everything went ok
NdbConnect	:	the server is down or not reachable
NdbComm	:	a communication error occurred
NdbProtocol	:	a failure occurred in the NUCM protocol
NdbNotAvail	:	service is not available

Example

Assuming an access server is active on a machine "serl.cs.colorado.edu" and is listening to port "1234". To deactivate the server, the following code fragment can be used:

   #include "nc.h"

   t_server  server;

   strcpy(server.host, "serl.cs.colorado.edu");
   sprintf(server.port, "%d", NUCM_PORT);
   nc_shutdown(&server);

Note that port "1234" is the default port a NUCM access server listens to, so we use the NUCM_PORT macro to set it in the variable server.

[Top | Quick Index] [Concepts | Interface]

SERL <serl.cs.colorado.edu>

NUCM-2.0 Documentation Interface

NUCM-2.0 Documentation Interface: Access

NUCM-2.0 Documentation Interface: Access: nc_open

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Access: nc_close

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Versioning

NUCM-2.0 Documentation Interface: Versioning: nc_initiatechange

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Versioning: nc_abortchange

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Versioning: nc_commitchange

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Versioning: nc_commitchangeandreplace

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Collection

NUCM-2.0 Documentation Interface: Collection: nc_add

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Collection: nc_remove

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Collection: nc_rename

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Collection: nc_replaceversion

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Collection: nc_copy

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Query

NUCM-2.0 Documentation Interface: Query: nc_list

Signature

Functionality

Return Values

NdbErrno Codes

Example

NUCM-2.0 Documentation Interface: Query: nc_gettype

Signature

Functionality

NUCM-2.0 Documentation
Interface

NUCM-2.0 Documentation
Interface: Access

NUCM-2.0 Documentation
Interface: Access: nc_open

NUCM-2.0 Documentation
Interface: Access: nc_close

NUCM-2.0 Documentation
Interface: Versioning

NUCM-2.0 Documentation
Interface: Versioning: nc_initiatechange

NUCM-2.0 Documentation
Interface: Versioning: nc_abortchange

NUCM-2.0 Documentation
Interface: Versioning: nc_commitchange

NUCM-2.0 Documentation
Interface: Versioning: nc_commitchangeandreplace

NUCM-2.0 Documentation
Interface: Collection

NUCM-2.0 Documentation
Interface: Collection: nc_add

NUCM-2.0 Documentation
Interface: Collection: nc_remove

NUCM-2.0 Documentation
Interface: Collection: nc_rename

NUCM-2.0 Documentation
Interface: Collection: nc_replaceversion

NUCM-2.0 Documentation
Interface: Collection: nc_copy

NUCM-2.0 Documentation
Interface: Query

NUCM-2.0 Documentation
Interface: Query: nc_list

NUCM-2.0 Documentation
Interface: Query: nc_gettype

NUCM-2.0 Documentation
Interface: Query: nc_version

NUCM-2.0 Documentation
Interface: Query: nc_lastversion

NUCM-2.0 Documentation
Interface: Query: nc_existsversion

NUCM-2.0 Documentation
Interface: Query: nc_isinitiated

NUCM-2.0 Documentation
Interface: Attribute

NUCM-2.0 Documentation
Interface: Attribute: nc_testandsetattribute

NUCM-2.0 Documentation
Interface: Attribute: nc_getattributevalue

NUCM-2.0 Documentation
Interface: Attribute: nc_removeattribute

NUCM-2.0 Documentation
Interface: Removal

NUCM-2.0 Documentation
Interface: Distribution

NUCM-2.0 Documentation
Interface: Distribution: nc_move

NUCM-2.0 Documentation
Interface: Distribution: nc_getlocation

NUCM-2.0 Documentation
Interface: Distribution: nc_setmyserver