Declaring pointer host variables in C programs

If you use the Db2 coprocessor, you can use pointer host variables with statically or dynamically allocated storage. These pointer host variables can point to numeric data, non-numeric data, or a structure.

About this task

You can declare the following types of pointer host variables:

Scalar pointer host variable: A host variable that points to numeric or non-numeric scalar data.
Array pointer host variable: A host variable that is an array of pointers.
Structure array host variable: A host variable that points to a structure.

Procedure

To declare pointer host variables in C and C++ programs:

Include an asterisk (*) in each variable declaration to indicate that the variable is a pointer.

Restrictions:

You cannot use pointer host variables that point to character data of an unknown length. For example, do not specify the following declaration: char * hvcharpu. Instead, specify the length of the data by using a bounded character pointer host variable. A bounded character pointer host variable is a host variable that is declared as a structure with the following elements:
- A 4-byte field that contains the length of the storage area.
- A pointer to the non-numeric dynamic storage area.
You cannot use untyped pointers. For example, do not specify the following declaration: void * untypedprt .

Examples

Example: Scalar pointer host variable declarations

Table 1. Example declarations of scalar pointer host variables
Declaration	Description
`short *hvshortp;`	hvshortp is a pointer host variable that points to two bytes of storage.
`double *hvdoubp;`	hvdoubp is a pointer host variable that points to eight bytes of storage.
`char (*hvcharpn) [20];`	hvcharpn is a pointer host variable that points to a nul-terminated character array of up to 20 bytes.

Example: Bounded character pointer host variable declaration

The following example code declares a bounded character pointer host variable called hvbcharp with two elements: len and data.

struct {
  unsigned long len;
  char * data;
  } hvbcharp;

Example: array pointer host variable declarations

Table 2. Example declarations of array pointer host variables
Declaration	Description
`short * hvarrpl[6]`	hvarrp1 is an array of 6 pointers that point to two bytes of storage each.
`double * hvarrp2[3]`	hvarrp2 is an array of 3 pointers that point to 8 bytes of storage each.
`struct { unsigned long len; char * data; } hvbarrp3[5];`	hvbarrp3 is an array of 5 bounded character pointers.

Example: Structure array host variable declaration

The following example code declares a table structure called tbl_struct.

struct tbl_struct
{
  char  colname[20];
  small int colno;
  small int coltype;
  small int collen;
};

The following example code declares a pointer to the structure tbl_struct. Storage is allocated dynamically for up to n rows.

struct tbl_struct *ptr_tbl_struct =
 (struct tbl_struct *) malloc (sizeof (struct tbl_struct) * n);