PA_ExecuteFunction

version 2003

PA_ExecuteFunction (toExecute; len) → PA_Variable

Parameter	Type		Description
toExecute	char *	→	Text of the statement to execute
len	long	→	Length of toExecute
Function result	PA_Variable	←	Function result

Description

The routine PA_ExecuteFunction allows the 4D plug-in to compute and evaluate any 4th Dimension expression that returns a result. For statements that do not return a result, use PA_ExecuteMethod .


   
    toExecute

is the statement to be executed,

len

is its length.

Once 4th Dimension has evaluated and executed the expression, it returns the result in a structure of type PA_Variable . This API gives the developer accessors to PA_Variables .


 
  
   PA_ExecuteFunction

is subject to the 4th Dimension Language syntax. A 4D function can return String, Text, Numeric (real, long integer, integer), Date, Time, Boolean, Pointer, and Picture or BLOB expressions. It cannot return an array.


 
  
   PA_ExecuteFunction

works like the EXECUTE 4D command with the exception being that it returns a result.

The rule of thumb is that the expression can be executed and evaluated as a one line global method. Then it will execute properly and return a result.

IMPORTANT NOTE:

After the call, it is the 4D plug-in's responsibility to dispose of the variable created by this command. Use PA_ClearVariable for this purpose.


 
  
   PA_ExecuteFunction

allows the 4D plug-in to execute only one line of code.


 toExecute

cannot contain several lines, such as a "Case of" or a "For" block. If you need to execute several lines of 4th Dimension code, write the code as a 4th Dimension expression and then call this expression.

Example of 4D expressions

1. This expression is valid and returns the day of one year from today:

"Current date + 365"

2. Provided ThisFunction is a valid global project method that returns a result, this expression is valid:

ThisFunction (1;"abc")

3. This line is not a valid expression because it contains a syntax error (comma instead of semi-colon):

ThisFunction (1,"abc")

When to use PA_ExecuteFunction

PA_ExecuteFunction

allows the 4D plug-in to evaluate any 4th Dimension expression. The 4D plug-in can, for example, use


 
  PA_ExecuteFunction

to obtain a value which is not accessible using this API.

One powerful use of this routine is the insertion of 4D formulas written by the 4D developers using this type of 4D plug-in. This routine, as well as the other "Execute" routines are used by modules such as 4D Write.

When not to use PA_ExecuteFunction

Before evaluating the 4D plug-in's expression, 4th Dimension needs to check that the syntax is valid, otherwise unpredictable results may occur. In other words, 4th Dimension invokes its interpreter to parse, validate, and tokenize the 4D plug-in text. Then, if the text is valid, the tokenized form is evaluated. So, even if the database is running compiled, 4D will execute the formula call at the speed of an interpreted database. If a 4D plug-in calls a 4th Dimension global function the latter will run compiled, but the call itself is interpreted.

If the 4D plug-in uses PA_ExecuteFunction to call a formula several hundreds or thousands of times inside a loop, the interpreted execution time will become significantly higher than a similarly compiled execution.

Consequently, when using this routine the developer must try to balance the functionality it adds and the inefficiency it introduces compared to compiled code. In this regard, the developer can use the PA_Tokenize and PA_ExecuteTokens routines that use pre-tokenized expressions.

IMPORTANT NOTE
:

Beware of re-entrant calls to the 4D plug-in. See PA_ExecuteMethod .

Example

Getting a date and a text.

   PA_Variable      aText, aDate;
   
   // GetImportedText is a valid method that returns a text
   aText = PA_ExecuteFunction("GetImportedText", 15);
   aDate = PA_ExecuteFunction("Current date", 12);
 
   /* Use API accessors to PA_Variable : PA_GetDateVariable */
 
   /* . . . do something . . .*/
 
   // Clear the text variable
   PA_ClearVariable(&aText);

See Also

PA_ExecuteMethod .

Error Handling

Use PA_GetLastError to see if an error occurred