_Load( ) API Library Routine

Places the value of the memory variable or current record field specified by loc into val.

int _Load(Locator FAR *loc, Value FAR *val)
Locator FAR *loc;         /* Variable location. */
Value FAR *val;            /* Holds value of the variable. */

Remarks

_Load( ) returns 0 if the routine is successful. If the routine fails, it returns a negative integer whose absolute value is a Visual FoxPro error number. You can use _Load( ) to retrieve the contents of a memo field, but it doesn't retrieve characters in the field after the first 65,000 bytes. If loc specifies a one-dimensional array, Visual FoxPro returns the value of the first element of the array.

_Load( ) doesn't work with objects. If loc specifies an object reference, _Load( ) returns 0 without filling the val Value structure. Use _Evaluate( ) to obtain an object reference.

If the setting of the Locator field l_offset is – 1, Visual FoxPro returns a logical value structure that indicates whether the current record in the specified work area is deleted:

• ev_length = .T. = DELETED( )

• ev_length = .F. = NOT DELETED( )

  Note   _Load( ) creates a handle only when the memory variable your program is loading is a character string (ev_type = 'C'). All other data types store their values in the Value structure itself. Your program must free the handles created with _Load( ).

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 converts to uppercase a string argument passed by reference.

Visual FoxPro Code

SET LIBRARY TO LOAD   
x = "abc"
= XUPPER(@x)
? x

C Code

#include <pro_ext.h>

void FAR Upper(ParamBlk FAR *parm)
{
      char FAR *pString;
      Value val;
      int i;
//
//   _Load() and _Store are the functions of interest for pass-by-reference.
//
   _Load(&parm->p[0].loc, &val);
//
//   FoxPro doesn't check the type of pass-by-reference arguments, so we do.
//
  if (val.ev_type != 'C')
   {
      _Error(9); // "Data type mismatch"
   }
  pString = _HandToPtr(val.ev_handle);

   for (i = 0; i < val.ev_length; i++)
   {
      if ('a' <= *pString && *pString <= 'z')
      {
         *pString += ('A' - 'a');
      }
      pString++;
   }
   _Store(&parm->p[0].loc, &val);
   // 
   // We need to free the handle that we created with  _LOAD()
   //
   _FreeHand(val.ev_handle);
}

FoxInfo myFoxInfo[] =
{
   {"XUPPER", (FPFI) Upper, 1, "R"},
};

FoxTable _FoxTable =
{
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

_ALen( ) API Library Routine | _FindVar( ) API Library Routine | _NameTableIndex( ) API Library Routine | _NewVar( ) API Library Routine | _Release( ) | _Store( ) API Library Routine | Accessing the Visual FoxPro API