1. Developer's Guide
  2. Oracle Key Vault Client C SDK API Reference
  3. Oracle Key Vault Client SDK Error Handling APIs

10 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 otherwise 0 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

10.1 okvErrGetDepth

okvErrGetDepth is used to return the depth of the error stack otherwise 0 is returned.

Category

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

IN

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");
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.2 okvErrGetDepthForBatch

okvErrGetDepthForBatch is used to return the depth of the error stack for the provided batch job number otherwise 0 is returned.

Category

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 batch_job_no);

Parameters

Parameter IN/OUT Description
env

IN

Oracle Key Vault environment handle.
batch_job_no 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 batch_job_no 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, batch_job_no for create a key is 1, batch_job_no for activate a key is 2, batch_job_no for revoke is 3 and batch_job_no 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);
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.3 okvErrGetNum

okvErrGetNum returns the error number on top of the error stack.

Category

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

IN

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: OKV_SUCCESS (0) is returned if there is no error.

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");
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.4 okvErrGetNumAtDepth

okvErrGetNumAtDepth returns the error number at the specified depth of the error stack.

Category

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

IN

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: OKV_SUCCESS (0) is returned if there is no error.

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));
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.5 okvErrGetNumAtDepthForBatch

okvErrGetNumAtDepthForBatch returns the error number at the specified depth of the error stack for the provided batch job number.

Category

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 batch_job_no,
                                     ub1 depth);

Parameters

Parameter IN/OUT Description
env

IN

Oracle Key Vault environment handle.
batch_job_no 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: OKV_SUCCESS (0) is returned if there is no error.

Comments

batch_job_no 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, batch_job_no for create a key is 1, batch_job_no for activate a key is 2, batch_job_no for revoke is 3, and batch_job_no 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));
   }
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.6 okvErrGetNumForBatch

okvErrGetNumForBatch returns the error number on top of the error stack for the provided batch job number.

Category

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 batch_job_no);

Parameters

Parameter IN/OUT Description
env

IN

Oracle Key Vault environment handle.
batch_job_no 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: OKV_SUCCESS (0) is returned if there is no error.

Comments

batch_job_no 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, batch_job_no for create a key is 1, batch_job_no for activate a key is 2, batch_job_no for revoke is 3, and batch_job_no 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");
}

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.7 okvErrReset

okvErrReset resets the error stack in the environment handle.

Category

Error handling API

Purpose

okvErrReset resets the error stack in the environment handle.

Syntax

void okvErrReset(OKVEnv *env);

Parameters

Parameter IN/OUT Description
env

IN

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);

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs

10.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

IN

 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: NULL pointer is returned if the error number is not valid.

Comments

None.

Example

ub4 error = 0;
printf("Error %d: %s \n", error, okvGetTextForErrNum(error));

Related Topics

Parent topic: Oracle Key Vault Client SDK Error Handling APIs