Introduction
When you issue an API in Documentum, you get a return code. In most cases, this return code will tell you whether the API succeeded or failed. If you are issuing the APIExec or APISet APIs, a successful return code is -1. If the return code is 0, the API failed. If you issue the APIGet API, the value that is returned is the value that you requested. When using APIGet, there is not an explicit success/failure return code, though in some cases, you can detect a failure if it returns an empty string when you were expecting a value.
But for the purposes of this discussion, let’s stick to talking about APIExec and APISet, which have explicit success/failure return codes.
If you execute an API and get an invalid return code, you know that you have encountered an error. This error could be caused by many things – there could be a system error (like the network or docbase being down), the data you are trying to enter might be bad (like trying to specify a character in an interger field), or the syntax of the API could be wrong. If you get an invalid return code, you should look for a Documentum error message to get more explicit information on what went wrong.
Error Messages
The getmessage API
Documentum places all error messages, warnings, and informational messages into a message queue. To access this queue, you execute the getmessage API.
strErrorMessage = APIGet("getmessage,c")
The Error Message Queue
The getmessage API returns all of the error messages that are currently in the error message queue, not just the most recent message. Sometimes, when you issue the getmessage API, you receive several messages. This can occur when you haven’t retrieved earlier, unrelated messages. However, when you encounter some errors, you might get 2 or three messages queued up at once. One would be a general message, the other a more specific message. For example, if you try to assign an invalid ACL to an object, you will receive the following two error messages when you attempt to save the object
[DM_SYSOBJECT_E_CANT_FETCH_ACL]error: "Failed to fetch the ACL 'sdfsdf' in domain 'Admin' for dm_folder 'test'."
[DM_ACL_E_CANT_FETCH_ACL]error: "Failed to fetch the ACL 'sdfsdf' in the domain 'Admin'."
Although these error messages seem similar, you can see that the first error message is a SYSOBJECT error message while the second message is an ACL error message. In this case, the ACL error message was generated first. When you issue the getmessage API, you will receive the most recent message first.
Note: You will often encounter a message that looks like this:
[DM_SESSION_I_SESSION_START]info: "Session 010f42a480003a3a started for user Admin."
This message is an informational message (you can tell because of the info: following the bracketed string of text). Documentum generates this message whenver your session has been inactive for a while. After a period of inactivity, Documentum will disconnect you from the server to conserve resources. The next time you make a request of the server, Documentum will automatically reconnect without you knowing. For this reason, you may find this informational message waiting in the bottom of your message queue. So if you encounter this message, you can ignore it.
Interpreting the Error Message
An error message is made up of two parts, the error ID and the error message text. The error ID is the bracketed string of text at the beginning of the error message, and the error message text is the descriptive text following the error ID.
The error ID itself is made up of three parts:
- The subsystem of Documentum that encountered the error (the type of error)
- The type of message (Informational, Warning, or Error)
- The specific error
For example, in the DM_SESSION_I_SESSION_START error ID, the DM_SESSION is the subsystem that generated the error, I indicates that the message is informational, and SESSION_START is the specific type of message withing the session manager subsystem.
Detailed Error Reference
Now that you know how to retrieve the error and interpret it, how do you get more detailed information about what caused the error and what to do to fix it? Unfortunately, Documentum does not currently publish a detailed list of its error messages in any of its reference manuals. Hoever, Documentum does provide a list of its error messages in another location. This list actually gets installed when you install the Documentum server.
There is a subdirectory called messages inside the product directory on the server. This directory is filled with several files that contain detailed information about the different informational, warning, and error messages that Documentum can generate. Each file is named for a particular subsystem. For example, the file that contains information about the DM_SESSION sybsytstem is named dmsess.e. Here is an excerpt from that file.
$Id: errorhandling.xml,v 1.2 2004/11/30 07:23:56 mikey Exp $
; dmSession class errors; Session warning codes.;.facility DM_SESSION.severity INFORMATION
SESSION_START SS "Session %s started for user %s."
;CAUSE: This is an informational message generated at session startup.
;ACTION: None. Informational message only.
;PARAMETERS: The id of the session and the client node name of the user;
SESSION_QUIT S "Session %s quit."
;CAUSE: This is an informational message generated at session close.
;ACTION: None. Informational message only.
;PARAMETERS: The id of the session and the current time
These files are organized by the severity of the message. All of the informational messages are grouped together, all of the warnings are grouped together, etc. Each group is preceded by the .severity tag. In the excerpt above, you can see that these are informational messages because of the .severity INFORMATION on line 7.
Within the severity group, individual messages are noted by their specific error code. As you can see, the DM_SESSION_I_SESSION_START message begins on line 8 with SESSION_START. The text of the message appears next, with placeholders for any runtime values that need to be inserted – in this case, the Session ID and the User Name.
But the really interesting information is noted by the CAUSE and ACTION tags. This is what makes this file worthwhile. As a developer, if you encounter an error that you do not understand, you can go to the message file and look up it’s cause and what actions to take to prevent the error in the future. This is one of the great developer’s tricks that not many people know about.
