PA_SetVariable

version 2003

PA_SetVariable (vName; aVariable; clearOldValue)

Parameter	Type		Description
vName	char *		Name of the variable to modify
aVariable	PA_Variable		Content to put in vName
clearOldValue	char		1 = Dispose previous content of the variable

The routine PA_SetVariable changes the content of the 4D variable, whose name is vName, to the content of aVariable. If clearOldValue is 1, then the previous content of the variable is properly cleared.

In compiled mode, it is the plug-in's responsibility to not change the kind of the variable. If PA_SetVariable modifies the kind of a variable, unpredictable result may occur.

For sample variables, the values are duplicated in the 4D variable, and PA_ClearVariable can be used on aVariable. On the other hand, for BLOBs, Text and picture variables, it is the handle to their data which is duplicated, not the data itself. So, as a rule, remember that once PA_SetVariable is called for Text, BLOB or picture variable, its handle belongs to 4th Dimension, and you must not call PA_ClearVariable for the source variable aVariable.

If you have get a "complex" a variable using PA_GetVariable and then you call PA_SetVariable on it, there are 2 choices:

• If you modified the data of the handle (PA_SetHandleSize, PA_MoveBlock),pass 0 in clearOldValue, since the handle to the data is still valid, an,d you surely do not want to dispose of it.

• If you have already a new handle ready for this variable, then you must set clearOldValue to 1 so that 4D can properly dispose of the memory used by the previous handle.

(1) Setting the OK system variable. This can be useful after a time consuming operation, to tell the user that the operation has succeed or not, since 4D Developers have the habit to use the OK variable in such case.

   void SetOK (char newValue)
   {
      PA_Variable   ok;
      
   // Note that in interpreted mode, OK may be undefined
   // In compiled mode, its kind must not be changed, so we
   // GetVariable and do not touch to it's field kind.
      ok = PA_GetVariable((char *) "\pOK"); // using P strings under MacOS

      if(PA_GetLastError() == eER_NoErr)
      {
         switch (PA_GetVariableKind(ok))
         {
            case eVK_Real:
               if(newValue)
                  PA_SetRealVariable(ok, 1.0);
               else
                  PA_SetRealVariable(ok, 0.0);
               break;
            case eVK_Longint:
               if(newValue)
                  PA_SetLongintVariable(ok, 1);
               else
                  PA_SetLongintVariable(ok, 0);
               break;
         }
      // Now, change the value of the "OK" variable in 4D
         PA_SetVariable((char *) "\pOK", ok, 1);
      }
   }

(2) Modify a BLOB variable data (don't clear its old value) by filling it with 0s

   void PutZerosInBlobVar (char *vName)
   {
      PA_Variable   blob = PA_GetVariable(vName);
      PA_Handle      h;
      char         *pt;
      long         i, size;

      if(PA_VariableKind(blob) == eVK_Blob)
      {
         h = PA_GetBlobHandleVariable(blob);
         if(h)
         {
         // Some work on that handle
            size = PA_GetHandleSize(h);
            pt = PA_LockHandle(h);
            for(i = 0; i < size; i++)
               *pt++ = (char) 0;
            PA_UnlockHandle(h);

         // Now, tell 4D we changed this variable
         // As we worked on the original variable handle, we MUST NOT DISPOSE of the "old content"
            PA_SetVariable(vName, blob, 0);
         }
      }
   }

(3) Modify a BLOB variable by changing its handle.

   void InitializeMyBlob (char *vName)
   {
      PA_Variable   blob;
      PA_Handle      h;
      char         *pt;

      h = PA_NewHandle(4);
      if(h)
      {
      // Some work on that handle
         pt = PA_LockHandle(h);
         * (long *) pt = 'ABCD';
         PA_UnlockHandle(h);
      // SetBlobHandleVariable sets the kind of the variable to eVK_Blob for us
         PA_SetBlobHandleVariable(blob, h);
      // Now, put this handle in the variable
      // As we worked on a new handle, we MUST DISPOSE of the old one
         PA_SetVariable(vName, blob, 1);
      // Now, h belongs to 4th Dimension,, we must not dispose of it.
      }
   }

No reference.

PA_GetLastError keeps the last error that occurred before calling the routine.