Share via


_NewVar( ) API Library Routine

Creates a variable or an array.

NTI _NewVar(char FAR *name, Locator FAR *loc, int flag)
char FAR *name;            /* Variable name. */
Locator FAR *loc;            /* Place. */
int flag;                     /* Scope. */

Remarks

The NTI type definition stands for Name Table Index. See _NameTableIndex( ) API Library Routine for more information about Name Table Index use.

The variable or array name must follow standard Visual FoxPro rules for variable names. The new variable is initialized to the logical value False.

The setting of the Locator field l_subs determines the variable or array type:

  • 0 – a scalar variable

  • 1 – a one-dimensional array of size l_sub1

  • 2 – an array of size l_sub1 by l_sub2 For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

The flag parameter can be NV_PUBLIC or NV_PRIVATE. NV_PRIVATE variables are created as though they were created by the Visual FoxPro routine that called the external routine.

If _NewVar( ) successfully creates the variable, the field l_NTI is filled in with the non-negative NTI of the created variable, and _NewVar( ) returns this number. If _NewVar( ) fails, it returns a negative integer whose absolute value is an internal Visual FoxPro error number.

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example uses _NewVar( ) to create three variables.

Visual FoxPro Code

SET LIBRARY TO NEWVAR  
* As defined in "pro_ext.h"
#define NV_PUBLIC   0
#define NV_PRIVATE   1

= xNewVar('var', 0, 0, 0, NV_PUBLIC)
DISPLAY MEMORY LIKE var

= xNewVar('onedim', 1, 5, 0, NV_PUBLIC)
DISPLAY MEMORY LIKE onedim

= xNewVar('twodim', 2, 5, 6, NV_PUBLIC)
DISPLAY MEMORY LIKE twodim

C Code

#include <pro_ext.h>

void FAR NewVarEx(ParamBlk FAR *parm)
{
   char FAR *varName;
   Locator loc;
   int flag;
   int retValue;

   // Null terminate character string
   if (!_SetHandSize(parm->p[0].val.ev_handle,
      parm->p[0].val.ev_length+1))
   {
      _Error(182); // "Insufficient memory"
   }
   _HLock(parm->p[0].val.ev_handle);
   varName = (char FAR *) _HandToPtr(parm->p[0].val.ev_handle);
   varName[parm->p[0].val.ev_length] = '\0';
   loc.l_subs = parm->p[1].val.ev_long;
   loc.l_sub1 = parm->p[2].val.ev_long;
   loc.l_sub2 = parm->p[3].val.ev_long;
   flag = parm->p[4].val.ev_long;
   if ((retValue = _NewVar(varName, &loc, flag)) < 0) 
   {
      // _NewVar() returns negative Visual FoxPro error number
      _Error(-retValue); 
   }
   _HUnLock(parm->p[0].val.ev_handle);
}

FoxInfo myFoxInfo[] = {
   {"XNEWVAR", (FPFI) NewVarEx, 5, "C,I,I,I,I"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

Concepts

API Library Routines A-Z

Reference

_ALen( ) API Library Routine

_FindVar( ) API Library Routine

_Load( ) API Library Routine

_NameTableIndex( ) API Library Routine

_ObjectRelease( ) API Library Routine

_Store( ) API Library Routine

Other Resources

Accessing the Visual FoxPro API

API Library Routines by Category