9 Oracle Key Vault Client SDK Error Handling APIs
This section describes the interfaces for Oracle Key Vault error management.
- okvErrGetDepth
okvErrGetDepth
is used to return the depth of the error stack otherwise0
is returned. - okvErrGetDepthForBatch
okvErrGetDepthForBatch
is used to return the depth of the error stack for the provided batch job number otherwise 0 is returned. - okvErrGetNum
okvErrGetNum
returns the error number on top of the error stack. - okvErrGetNumAtDepth
okvErrGetNumAtDepth
returns the error number at the specified depth of the error stack. - okvErrGetNumAtDepthForBatch
okvErrGetNumAtDepthForBatch
returns the error number at the specified depth of the error stack for the provided batch job number. - okvErrGetNumForBatch
okvErrGetNumForBatch
returns the error number on top of the error stack for the provided batch job number. - okvErrReset
okvErrReset
resets the error stack in the environment handle. - okvGetTextForErrNum
okvGetTextForErrNum
returns the text of the error number.
Parent topic: Oracle Key Vault Client C SDK API Reference
9.1 okvErrGetDepth
okvErrGetDepth
is used to return the depth of the error stack otherwise 0
is returned.
Catetory
Error handling API
Purpose
okvErrGetDepth
is used to return the depth of the error stack
otherwise 0 is returned if no error was recorded in the error stack.
Syntax
ub1 okvErrGetDepth(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
Return Values
Return Value | Description |
---|---|
ub1 |
Oracle Key Vault error stack depth. Success: A non-zero positive number, which is the depth of the error stack, is returned. Failure: Zero is returned, since depth is zero if no error is recorded. |
Comments
None.
Example
ub4 err_depth = okvErrGetDepth(env); if (err_depth == 0) { printf("No Error \n"); } else { printf("Error\n"); }
9.2 okvErrGetDepthForBatch
okvErrGetDepthForBatch
is used to return the depth of the
error stack for the provided batch job number otherwise 0 is returned.
Catetory
Error handling API
Purpose
okvErrGetDepthForBatch
is used to return the depth of the error stack for the provided batch job number, otherwise 0 is returned.
Syntax
ub1 okvErrGetDepthForBatch(OKVEnv *env, ub4 batchjobnum);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
batchjobnum |
IN |
Batch job number. |
Return Values
Return Value | Description |
---|---|
ub1 |
Oracle Key Vault error stack depth. Success: A non-zero positive number which is the depth of the error stack for the respective batch job is returned. Failure: Zero is returned, since depth is zero if no error is recorded for the respective batch job. |
Comments
Here batchjobnum
is the number in which the operations are batched.
For example, if the user wants to create a key, activate a key, revoke it, and then
destroy it, all of these operations are batched in the same order. That is,
batchjobnum
for create a key is 1
,
batchjobnum
for activate a key is 2
,
batchjobnum
for revoke is 3
and
batchjobnum
for destroy is 4
. Once the batch job
execution finishes, the user can pass in the batch job number for
okvErrGetDepthForBatch
to get the depth of the errors from the
respective batch job error stack.
If batch job number provided is invalid, then zero (0) is returned by this API.
Example
ub4 err_depth = 0; okvBatchCreate(env); okvCreateKey(...); /* 1st Batch Job */ okvActivate(...); /* 2nd Batch Job */ okvRevoke(...); /* 3rd Batch Job */ okvDestroy(...); /* 4th Batch Job */ okvBatchExecute(env); /* Check error on top of the error stack for 1st batch job */ if (okvErrGetNumForBatch(env, 1)) { printf("Found error for 1st batch job"); err_depth = okvErrGetDepthForBatch(env, 1); printf("Depth of the error stack is %d", err_depth); }
9.3 okvErrGetNum
okvErrGetNum
returns the error number on top of the error
stack.
Catetory
Error handling API
Purpose
okvErrGetNum
returns the error number on top of the error stack. OKV_SUCCESS
is returned if no error recorded.
Syntax
OKVErrNo okvErrGetNum(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
Return Values
Return Value | Description |
---|---|
OKVErrNo |
Oracle Key Vault error number. Success: The error number on top of the error stack is returned. Failure: |
Comments
None.
Example
printf("Setting up Oracle Key Vault session\n"); okvConnect(env); if (okvErrGetNum(env)) { printf("Could not setup the Oracle Key Vault session\n"}; return 1; } else { printf("Successfully setup Oracle Key Vault session\n\n"); }
9.4 okvErrGetNumAtDepth
okvErrGetNumAtDepth
returns the error number at the specified depth of the error stack.
Catetory
Error handling API
Purpose
okvErrGetNumAtDepth
returns the error number at the specified depth of the error stack otherwise OKV_SUCCESS
is returned.
Syntax
OKVErrNo okvErrGetNumAtDepth(OKVEnv *env, ub1 depth);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
depth |
IN |
Depth at which the error number is needed. |
Return Values
Return Value | Description |
---|---|
OKVErrNo |
Oracle Key Vault error number. Success: The error number at the specified depth in the error stack is returned. Otherwise: |
Comments
okvErrGetNumAtDepth
returns OKV_SUCCESS
if the depth specified is more than that returned by okvErrGetDepth
.
Example
ub4 err_depth = okvErrGetDepth(env); while (err_depth > 0) { ub4 error = 0; /* Get error number to get error text */ error = okvErrGetNumAtDepth(env, err_depth--); printf("Error %d: %s \n", error, okvGetTextForErrNum(error)); }
9.5 okvErrGetNumAtDepthForBatch
okvErrGetNumAtDepthForBatch
returns the error number at the specified depth of the error stack for the provided batch job number.
Catetory
Error handling API
Purpose
okvErrGetNumAtDepthForBatch
returns the error number at the specified depth of the error stack for the provided batch job number, otherwise OKV_SUCCESS
is returned.
Syntax
OKVErrNo okvErrGetNumAtDepthForBatch(OKVEnv *env, ub4 batchjobnum, ub1 depth);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
batchjobnum |
IN |
Batch job number. |
depth |
IN |
Depth at which the error number is needed. |
Return Values
Return Value | Description |
---|---|
OKVErrNo |
Oracle Key Vault error number. Success: The error number at the specified depth in the error stack is returned for the respective batch job number. Otherwise: |
Comments
batchjobnum
is the number in which the operations are batched. For
example, if the user wants to create a key, activate a key, revoke it, and then destroy
it, all of these operations are batched in the same order; that is,
batchjobnum
for create a key is 1
,
batchjobnum
for activate a key is 2
,
batchjobnum
for revoke is 3
, and
batchjobnum
for destroy is 4
. Once the batch
execution finishes, the user can pass in the batch job number and the depth at which the
error is needed for okvErrGetNumAtDepthForBatch
to get the error
details.
If the batch job number provided is invalid, then OKV_SUCCESS
(0) is
returned by this API. okvErrGetNumAtDepthForBatch
returns
OKV_SUCCESS
if the depth specified is more than that returned by
okvErrGetDepthForBatch
.
Example
ub4 err_depth = 0; okvBatchCreate(env); okvCreateKey(...); /* 1st Batch Job */ okvActivate(...); /* 2nd Batch Job */ okvRevoke(...); /* 3rd Batch Job */ okvDestroy(...); /* 4th Batch Job */ okvBatchExecute(env); /* Check error on top of the error stack for 1st batch job */ if (okvErrGetNumForBatch(env, 1)) { printf("Found error for 1st Batch Job"); err_depth = okvErrGetDepthForBatch(env, 1); printf("Depth of the error stack is %d", err_depth); while (err_depth > 0) { ub4 error = 0; /* Get error number to get error text */ error = okvErrGetNumAtDepthForBatch(env, 1, err_depth--); printf("Error %d: %s \n", error, okvGetTextForErrNum(error)); } }
9.6 okvErrGetNumForBatch
okvErrGetNumForBatch
returns the error number on top of the error stack for the provided batch job number.
Catetory
Error handling API
Purpose
okvErrGetNumForBatch
returns the error number on top of the error stack for the provided batch job number. OKV_SUCCESS
is returned if no error recorded.
Syntax
OKVErrNo okvErrGetNumForBatch(OKVEnv *env, ub4 batchjobnum);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
batchjobnum |
IN |
Batch job number. |
Return Values
Return Value | Description |
---|---|
OKVErrNo |
Oracle Key Vault error number. Success: The error number on top of the error stack for the respective batch job is returned. Failure: |
Comments
batchjobnum
is the number in which the operations are batched. For
example, if the user wants to create a key, activate a key, revoke it and then destroy
it, all of these operations are batched in the same order. That is,
batchjobnum
for create a key is 1
,
batchjobnum
for activate a key is 2
,
batchjobnum
for revoke is 3
, and
batchjobnum
for destroy is 4
. Once the batch
execution finishes, the user can pass in the batch job number for
okvErrGetNumForBatch
to get the error from the top of the respective
batch job error stack.
If batch job number provided is invalid, then OKV_SUCCESS
(0) is
returned by this API.
Example
okvBatchCreate(env); okvCreateKey(...); /* 1st Batch Job */ okvActivate(...); /* 2nd Batch Job */ okvRevoke(...); /* 3rd Batch Job */ okvDestroy(...); /* 4th Batch Job */ okvBatchExecute(env); /* Check error on top of the error stack for 1st Batch Job */ if (okvErrGetNumForBatch(env, 1)) { printf("Found error for 1st Batch Job"); }
9.7 okvErrReset
okvErrReset
resets the error stack in the environment
handle.
Catetory
Error handling API
Purpose
okvErrReset
resets the error stack in the environment handle.
Syntax
void okvErrReset(OKVEnv *env);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
env |
|
Oracle Key Vault environment handle. |
Return Values
No values returned.
Comments
None.
Example
/* Do some KMIP operations like adding attribute to an object and get the same attributes, below is an illustration of using 'okvErrReset' when getting the individual attibutes */ ub4 umask = 0; ub4 state = 0; printf("Trying to get Crypto Usage Mask value from State Attribute\n"); okvAttrGetCryptoUsageMask(env, ttlv, &umask); if (okvErrGetNum(env)) /* Check for errors */ okvErrReset(env); /* this will come in handy when we don’t want to keep getting the same errors for the next set of API calls where we try to get the individual Attribute values */ printf("Trying to get State value from State Attribute\n"); okvAttrGetState(env, ttlv, &state); if (okvErrGetNum(env)) /* Check for errors */ okvErrReset(env);
9.8 okvGetTextForErrNum
okvGetTextForErrNum
returns the text of the error number.
Category
Error handling API
Purpose
okvGetTextForErrNum
returns the text of the the error number. If the
error number is not valid, a pointer to NULL
is returned.
Syntax
oratext *okvGetTextForErrNum(OKVErrNo err_no);
Parameters
Parameter | IN/OUT | Description |
---|---|---|
errno |
|
Oracle Key Vault error number |
Return Values
Return Value | Description |
---|---|
oratext * |
Oracle Key Vault error text. Success: Pointer to text of the error is returned. Failure: |
Comments
None.
Example
ub4 error = 0; printf("Error %d: %s \n", error, okvGetTextForErrNum(error));