Each DNA Library API call will return a subset of the following Error Codes.
See the individual API Call information in the API Reference section.
Guidelines on trapping for errors:
- It is not required to test for all error conditions. Generally, testing for
Result > 0 is sufficient for
most API calls.
- For the main
DNA_Validate() API Call, you may want to test for ERR_VALIDATION_WARNING if you use
Level 3 Validation, and provide a warning message to the User.
- General error trapping would be done for the
DNA_Activate() API call
- To provide usefull feedback to the User that is experiencing a problem
with the Activation Process (beyond just an error number), we provide the
DNA_ERROR() API call which returns a simple
"text" translation of the Error Code that can
be used in dialog boxes presented to your User when there is an error in the Activation process.
- ERR_OPERATION_FAILED is the most common error and is the result of a failed activation.
Our approach is to avoid giving too much feedback on why the activation failed that could be use by hackers
DNA API Error Codes
| Success Codes |
| ERR_NO_ERROR |
0 |
The API Call was successful.
The CDM License file was correctly validated and the License Conditions / Terms are being respected.
If a DNA Server Validation was performed by the DNA Library (typically once per day), an updated CDM License File
was created and stored in the location set by the DNA_SetCDMPathName() API call.
|
| ERR_VALIDATION_WARNING |
-1 |
The <Validation Warning Limit> has been reached and a warning
should be presented to the User that an internet connection is required to perform a DNA Server Validation before the
<EXPIRATION_DATE> is reached.
(See also Notes on ERR_VALIDATION_WARNING
below)
|
| ERR_ACTIVATIONS_EXCEEDED |
-3 |
Applies ONLY to Licenses with Roll-Over Re-activation
The number of allowed computers was exceeded. The current Re-Activation was allowed.
All previous activations / computers have been disabled and will need to be re-activated the next time the
Application is used.
|
| General Failure Codes |
| ERR_NO_CONNECTION |
1 |
Cannot connect to the DNA Server
This can be caused by there being no Internet, or there is a personal Firewall, Router, or Proxy Server blocking
Port 80 access to the Internet.
|
| ERR_CONNECTION_LOST |
2 |
Connection with the DNA Server was lost during the execution of the API Call.
|
| ERR_LOCKOUT |
3 |
A IP Lockout or Re-Activation Lockout
is in effect for this License Code.
The transaction has been rejected.
|
| ERR_INVALID_CDM |
4 |
The existing CDM License file is invalid, disabled or not found.
|
| ERR_INVALID_PRODUCT_KEY |
5 |
Coding error - check API call coding
The <Product_Key> parameter is <BLANK> or is of invalid format.
|
| ERR_INVALID_ACTIVATION_CODE |
6 |
The <ACTIVATION_CODE> parameter is <BLANK> or is of
invalid format.
|
| ERR_INVALID_PASSWORD |
7 |
Coding error - check API call coding
The <PASSWORD> parameter is <BLANK>.
|
| ERR_BANNED_ACTIVATION_CODE |
10 |
The License Code has been Banned / Revoked at the DNA Server.
|
| ERR_NO_EMAIL_PROVIDED |
11 |
For the DNA_SendEvalCode() API call, the <email> parameter was
<BLANK>.
|
| ERR_INVALID_BUILD_NO |
12 |
The <BuildNo> parameter was of invalid format.
|
| ERR_EVAL_CODE_ALREADY_SENT |
13 |
DEPRECATED
The previous Evaluation Code assigned to this User is now resent to the User
and no error is flagged.
|
| ERR_EVAL_CODE_UNAVAILABLE |
14 |
A DNA_SendEvalCode() API call was made by the Application, and the "Reserve"
delivery option was used for Evaluation Codes for this Product, and there are no Evaluation Codes available.
New Evaluation Codes must be generated from the DNA Control Panel.
This option can only be set in consultation with Tech Support.
|
| ERR_CDM_HAS_EXPIRED |
15 |
The CDM License File has expired, and is no longer valid.
(See Notes on ERR_CDM_HAS_EXPIRED
below)
|
| ERR_CODE_HAS_EXPIRED |
16 |
The License Activation Code has expired, and is no longer valid.
(See Notes on ERR_CODE_HAS_EXPIRED
below)
|
| ERR_INVALID_NEW_PASSWORD |
17 |
Applies ONLY to Licenses with Roll-Over Re-activation
Using the DNA_REACTIVATION() API call, the <Current Password> was correct,
but the <New Password> has already been used.
The user should be informed to use a "New and Never Used Password".
|
| ERR_CDM_WRITE_PROTECTED |
18 |
The current User does not have "Read / Write" permission to the
target directory for the CDM License File, as set with the DNA_SetCDMPahtName() API call.
|
| ERR_ACTVATIONS_EXCEEDED_MU |
21 |
An attempt was made to activate a computer or seat beyond the set limit of computers / seats for this License Code.
The Activation / Re-activation was rejected.
Can be returned for the following license types:
|
| ERR_CANCELLED_BY_USER |
98 |
Applies only to the TurnKey Activation
DNA_ProtectionOK API call.
When using the DNA_ProtectionOK() API call, the User selected
Cancel in one of the dialog boxes.
|
| ERR_OPERATION_FAILED |
99 |
Operation failed with the DNA Server.
This is the general error result when a License is no longer valid, or a protection parameter was violated.
No additional information is provided to avoid providing too much information to hackers.
|
| DNA_Query() Result Codes |
|
DNA_Query() is used with the Custom Activation Process
The DNA_Query() will provide an indication of the state of the License Code on the DNA Server
and indicate what next step is required in the Activation or Re-Activation process.
|
| ERR_ACTIVATION_EXPECTED |
8 |
The License Code has not yet been activated. A DNA_Activate() should be performed.
Will be returned for the following license types:
|
| ERR_REACTIVATION_EXPECTED |
9 |
The License Code has already been activated. A DNA_Reactivate() should be performed.
Will be returned for the following license types:
|
| ERR_ACTIVATION_EXPECTED_MU |
19 |
The License Code has not yet been activated. A DNA_Activate() should be performed.
Will be returned for the following license types:
|
| ERR_REACTIVATION_EXPECTED_MU |
20 |
The License Code has already been activated. A DNA_Reactivate() should be performed.
This will be the case when:
Will be returned for the following license types:
|
| DNA_DISABLE |
| DNA_DISABLE |
-2 |
This is used ONLY when you intent to disable the software_DNA Licensing for a Product.
The encrypted / signed file <Product_ID>.DNA was found in the same directory
as the Application
and was authenticated. The Application should be allowed to run.
This provides for a Doomsday situation scenario, where you must stop using software_DNA.
Consult with Technical Support as this is implemented on an exception basis, and requires softWORKZ to provide the
encrypted / signed ".DNA" file for your DNA Product.
|
DNA_ERROR Messages
DNA_ERROR will return a short description of the error <error_No> that
you can use to inform your User of the error that occured during the Activation Process.
You can also use your own descriptions if required.
The default language used in the short description is "English". You can change the language used in the
short description by issuing the DNA_SetLanguage API Call before calling the DNA_Error API Call.
VB.NET
C#.NET
JAVA |
DNA_ERROR() returns a string with a short description of the
error <error_No>
|
| For all other languages |
| API Result |
Description |
| 0 |
a short description of the error <error_no> is returned in the parameter
<Buffer>
|
| 1 |
An error occured with the API Call - likely an error with the parameter syntax |
| 99 |
The size of the parameter <Buffer> is too small to store the value of
the parameter.
|
The <Buffer> should be a buffer of 2,048 Bytes to accomodate all values
|
| <Error_No> |
<Name> |
Short Description |
| 0 |
ERR_NO_ERROR |
<BLANK>
|
| -1 |
ERR_VALIDATION_WARNING |
MUST VALIDATE BEFORE <VALIDATION_LIMIT_DATE>
If you want to retrieve only the "DATE/TIME" and construct your own error text, use
DNA_PARAM("LAST_RESULT_VALUE") when ERR_VALIDATION_WARNING is received.
(See also Notes on ERR_VALIDATION_WARNING
below)
|
| -2 |
ERR_DNA_DISABLE |
DNA_DISABLE |
| -3 |
ERR_ACTIVATIONS_EXCEEDED |
THE NUMBER OF PERMITTED ACTIVATIONS HAS BEEN EXCEEDED. THIS ACTIVATION HAS BEEN
ALLOWED BUT OTHER INSTALLATIONS MAY NEED TO BE RE-ACTIVATED |
| 1 |
ERR_NO_CONNECTION |
NO CONNECTION |
| 2 |
ERR_CONNECTION_LOST |
CONNECTION LOST |
| 3 |
ERR_LOCKOUT |
LOCKOUT UNTIL <LOCKOUT_DATE/TIME>
If you want to retrieve only the "DATE/TIME" and construct your own error text, use
DNA_PARAM("LAST_RESULT_VALUE") when ERR_LOCKOUT is received.
|
| 4 |
ERR_INVALID_CDM |
INVALID CDM |
| 5 |
ERR_INVALID_PRODUCT_KEY |
INVALID PRODUCT KEY
(This is typically a programming logic error and not displayed to the User)
|
| 6 |
ERR_INVALID_ACTIVATION_CODE |
INVALID ACTIVATION CODE
(This is typically a programming logic error and not displayed to the User)
|
| 7 |
ERR_INVALID_PASSWORD |
INVALID PASSWORD
(This is typically a programming logic error and not displayed to the User)
|
| 8 |
ERR_ACTIVATION_EXPECTED |
ACTIVATION EXPECTED
(This is a result of the DNA_Query() API Call, not an error, and not displayed to the User)
|
| 9 |
ERR_REACTIVATION_EXPECTED |
REACTIVATION EXPECTED
(This is a result of the DNA_Query() API Call, not an error, and not displayed to the User)
|
| 10 |
ERR_BANNED_ACTIVATION_CODE |
BANNED ACTIVATION CODE |
| 11 |
ERR_NO_EMAIL_PROVIDED |
NO EMAIL PROVIDED
(This is typically a programming logic error and not displayed to the User)
|
| 12 |
ERR_INVALID_BUILD_NO |
INVALID BUILD NUMBER
(This is typically a programming logic error and not displayed to the User)
|
| 13 |
ERR_EVAL_CODE_ALREADY_SENT |
EVALUATION CODE ALREADY SENT |
| 14 |
ERR_EVAL_CODE_UNAVAILABLE |
EVALUATION CODE UNAVAILABLE |
| 15 |
ERR_CDM_HAS_EXPIRED |
CDM HAS EXPIRED
(See Notes on ERR_CDM_HAS_EXPIRED
below)
|
| 16 |
ERR_CODE_HAS_EXPIRED |
ACTIVATION CODE HAS EXPIRED
(See Notes on ERR_CODE_HAS_EXPIRED
below)
|
| 17 |
ERR_INVALID_NEW_PASSWORD |
THE NEW PASSWORD HAS ALREADY BEEN USED. PLEASE PROVIDE A NEW AND NEVER USED PASSWORD
TO RE-ACTIVATE
|
| 18 |
ERR_CDM_WRITE_PROTECTED |
THE DIRECTORY OR FILE FOR STORING THE LICENSE FILE (CDM) IS WRITE-PROTECTED.
PLEASE ENSURE THAT YOU HAVE READ-WRITE PERMISSIONS FOR THIS DIRECTORY OR FILE AND TRY AGAIN
|
| 19 |
ERR_ACTIVATION_EXPECTED_MU |
ACTIVATION EXPECTED
(This is a result of the DNA_Query() API Call, not an error, and not displayed to the User)
|
| 20 |
ERR_REACTIVATION_EXPECTED_MU |
REACTIVATION EXPECTED
(This is a result of the DNA_Query() API Call, not an error, and not displayed to the User)
|
| 21 |
ERR_ACTIVATIONS_EXCEEDED_MU |
|
| 98 |
ERR_CANCELLED_BY_USER |
CANCELLED BY USER |
| 99 |
ERR_OPERATION_FAILED |
OPERATION FAILED |
DNA_ERROR Overview and Examples
FUNCTION DNA_ERROR(ERROR_NO:INTEGER; MSG:PANSICHAR; MSG_SIZE:INTEGER):INTEGER; STDCALL;
PUBLIC FUNCTION DNA_ERROR(BYVAL ERROR_NO AS INTEGER, BYREF MSG AS STRING, BYVAL MSG_SIZE AS INTEGER) AS INTEGER
INT __STDCALL DNA_ERROR(INT ERROR_NO,CHAR *MSG,INT MSG_SIZE);
INT __STDCALL DNA_ERROR(INT ERROR_NO,CHAR *MSG,INT MSG_SIZE);
INT __STDCALL DNA_ERROR(INT ERROR_NO,CHAR *MSG,INT MSG_SIZE);
PUBLIC NATIVE STRING DNAERROR(INT ERROR_NO);
PUBLIC FUNCTION DNA_ERROR(BYVAL ERROR_NO AS SHORT) AS STRING
PUBLIC STATIC STRING DNA_ERROR(INT ERROR_NO)
Notes on ERR_CDM_HAS_EXPIRED and ERR_CODE_HAS_EXPIRED
ERR_CDM_HAS_EXPIRED and ERR_CODE_HAS_EXPIRED are essentially the same
error condition and are triggered by an expiration of the License Activation Code or an Evaluation License Code, including when the
<Validation Warning Limit> is reached. Both error messages should be considered the same for
error trapping purposes. The difference is whether the expiration was caught locally or by the server.
A code can expire because of the following reasons:
The License Code is an Evaluation Code and the evaluation period is passed.
The License Code is an Activation Code with the <Expiry_Period> option and the period is passed.
The License Code is subject to the Anti-Fraud option, and the License Code has expired because there was no validation
with the DNA Server within the Anti-Fraud period.
The License Code is subject to Level 3 Validation and the License Code has expired because there was no validation with
the DNA Server before the end of the <Validation Period>
The License Code is a Floating License, and was not de-activated and the Floating "Lease" has expired.
In the majority of cases, the error message returned would be ERR_CDM_HAS_EXPIRED because when the CDM
is created, it contains the <expiry_date> and the DNA Library does a local validation of the CDM
before performing a DNA Server Validation.
When the DNA Library does a DNA Server Validation, it may catch other situations where the License Code has expired
unbeknownst to the CDM such as:
In these cases, the error message returned would be ERR_CODE_HAS_EXPIRED.
Notes on ERR_VALIDATION_WARNING
The ERR_VALIDATION_WARNING error_code may be returned in two distinct scenarios:
When using the "Anti-Fraud" option (applies to Level 1 and Level 2 only)
The "Anti-Fraud" option requires a DNA Server-Validation between 45 and 60 days from the initial activation
of the Application. During this period, if software_DNA is not able to perform a DNA Server-Validation
(likely because there is no internet connection), then the DNA_Validate() and the
DNA_ProtectionOK() API will return ERR_VALIDATION_WARNING.
It is recommended that you display a warning to the user that he must validate his software (i.e. connect to the Internet)
in the next 15 days or less.
The DNA Server-Validation needs to be performed only once during the 45 to 60 day period. Once completed
successfully, the API’s will never again return the ERR_VALIDATION_WARNING error_code.
If the License Activation Code has been revoked or "banned" in the DNA Control Panel
(likely because of a credit card chargeback or refund), then the API’s will return the
ERR_BANNED_ACTIVATION_CODE error. If no DNA Server-Validation occurs before the 60 days after
initial activation, the API’s will return the ERR_CODE_HAS_EXPIRED error.
The Anti-Fraud option is selected in the DNA Control Panel.
When using Level 3 Validation
With Level 3 Validation, the <Validation Warning Limit> and the
<Validation Limit> are settings configured on the DNA Server for this product.
The dates can be retrieved from the CDM using the DNA_Param() API Call.
See Retrieving License Information
.
It is recommended that you display a warning to the user that he must validate his software
(i.e. connect to the Internet) before the <Validation_Limit> date.
If no DNA Server-Validation occurs before the <Validation Limit> date, the API’s
will return the ERR_CDM_HAS_EXPIRED or ERR_CODE_HAS_EXPIRED error.