Saving a user state

The routine manager provides information about arguments and return values of a UDR in the MI_FPARAM structure that is associated with a UDR. In addition, you can store the address of private-state information, called user-state information, in a special field of the MI_FPARAM structure.

The database server passes the same MI_FPARAM structure to every invocation of the UDR within the same routine sequence. When your user-state information is part of the MI_FPARAM structure, your UDR can access this information across all the invocations within the same routine sequence. Your routine can use this private area of the MI_FPARAM structure to cache information that preserves its own state.

The MI_FPARAM structure can hold a user-state pointer that points to this private state information. The user-state pointer references a thread-private place holder that allows a UDR to associate a user-defined state information with a routine sequence. The following table shows that the DataBlade® API provides the following accessor functions to access the user state of a UDR.
Table 1. User-state information in the MI_FPARAM structure
User-state information DataBlade® API accessor function
Obtain the user-state pointer from the MI_FPARAM structure of a UDR. mi_fp_funcstate()
Set the user-state pointer in the MI_FPARAM structure of a UDR. mi_fp_setfuncstate()
User-state information is useful for a UDR in the following cases:
  • To save information between invocations of an iterator function.
  • To replace static or global variables in C function.

    Use of the MI_FPARAM structure to hold state information enables a UDR to access global information without the use of static or global variables. It is never safe to use static and global variables that are updated because the updated value is not visible if the thread migrates to another virtual processor (VP) and concurrent activity is not interleaved.

Important: Avoid the use of static and global variables in a UDR. If a UDR uses variables with these scopes, it is an ill-behaved routine. You must execute an ill-behaved UDR in a separate virtual-processor class, called a user-defined VP.