PA_ExecuteMethodByID

4D - Documentation   Français   English   German   4D Plugin API, Command Theme List   4D Plugin API, Command Alphabetical List   Back   Previous   Next

version 2003


PA_ExecuteMethodByID (id; parameters; paramCount) PA_Variable

ParameterTypeDescription
idlongID of the method to execute
parametersPA_Variable *Parameters of the method
paramCountshortCount of parameters in parameters
Function resultPA_VariableResult if the method is a function

Description

The routine PA_ExecuteMethodByID executes the 4D global Method of function whose unique ID number is passed in id.

A 4D plug-in obtains the unique ID number of a 4th Dimension global Method or function using PA_GetMethodID.

Contrary to the routines PA_ExecuteMethod, PA_ExecuteFunction, PA_ExecuteTokens and PA_ExecuteTokensAsFunction, PA_ExecuteMethodByID allows the 4D plug-in to only call a specific type of 4th Dimension global Method or function present in the database.

A 4D plug-in cannot execute a 4th Dimension statement nor evaluate a 4th Dimension expression using this entry point.

On the other hand, PA_ExecuteMethodByID allows the 4D plug-in to skip both the tokenization and interpretation phases when the 4D plug-in calls the 4th Dimension global Method or function.

The 4D plug-in does not have to build a statement or expression text to be tokenized, executed, or evaluated. The 4D plug-in calls the Method or the function using its unique ID number and specifing its parameters the fashion explained below.

The advantage of using this routine is speed optimization, especially when used in a compiled database. The call to the 4th Dimension global method or function is made at the same speed as native code execution (no tokenization nor interpretation is involved.)

The 4D plug-in specifies the number of parameters to be passed to the method or function in paramCount.

The 4D plug-in passes the parameter(s) using an array of PA_Variable data structures that are allocated before the call.

The array of PA_Variable is defined in the PublicTypes.h header file.

IMPORTANT NOTE:

After the call, it is the 4D plug-in's responsibility to dispose of the result if its type is Text, Picture or BLOB. Use PA_ClearVariable for this purpose.

Using PA_ExecuteMethodByID assumes the developer knows or can predict the syntax of the 4D global method or function called. This is, for example, the case of the WR ON EVENT internal callback performed by 4D Write. The manual of this 4D plug-in tells users and developers how they must declare and implement a 4D Write event function.

If the 4D plug-in uses PA_ExecuteMethodByID to implement a similarly optimized calling scheme, be sure to properly inform users and developers how they must declare and implement the 4th Dimension function or Method in the manual of the 4D plug-in.

In addition, make sure users or developers are provided with a routine which they can use to tell the 4D plug-in which Method or function is to be called. The 4D plug-in will need the name of this 4th Dimension Method or function in order to get its unique ID number.

If a 4D plug-in calls a routine that does not exist a syntax or runtime error is returned.

If the 4D plug-in calls a routine with the wrong parameter(s) or result information:

A Syntax Error is returned if the database is interpreted.

A Runtime error is returned if the database is compiled with "Range Checking" on.

A System Error may occur if "Range Checking" is off (speed has a price).

Example

Plug-in documentation tells the 4D developer that he can write a callback method that must declare one parameter as a long and a second parameter as a string of 31 minimum. The first parameter is the number of external areas that are in use, the second will be the name of an external area. The method does not have a return result (it is a command).

   // gMethodID is a global variable that stores the call back method ID
   // methodName was received as parameter and correctly extracted
   // (using PA_GetStringParameter)
   gMethodID = PA_GetMethodID(methodName);

   // The callback execution
   void DoTheCallback()
   {
      PA_Variable   params[2];
      PA_Variable   dummyVar;
   // Set first parameter. gCountActiveAreas is a global counter
      PA_SetLongintVariable( &params[0], gCountActiveAreas);
   // Set the second parameter
      PA_SetStringVariable(&params[1], "TheSuperName" );

   // Now, we can execute the method
      dummyVar = PA_ExecuteMethodByID(gMethodID, params, 2);
   }

See Also

PA_GetMethodID.

Error Handling

Use PA_GetLastError to see if an error occurred


4D - Documentation   Français   English   German   4D Plugin API, Command Theme List   4D Plugin API, Command Alphabetical List   Back   Previous   Next