IPB_Value interface

PowerBuilder Native Interface

IPB_Value interface

IPB_Value has three sets of methods: helper methods, set methods, and get methods.

Helper methods

The IPB_Value interface helper methods provide access to information about variables and arguments, including the value's class and type, whether it is an array or simple type, whether it is set by reference, and whether the null flag is set. There is also a method that sets the value to null:

virtual pbclass          GetClass() const = 0;
virtual pbint              GetType() const = 0;
virtual pbboolean     IsArray() const = 0;
virtual pbboolean     IsObject() const = 0;
virtual pbboolean     IsByRef() const = 0;
virtual pbboolean     IsNull() const = 0;
virtual PBXRESULT   SetToNull() = 0;

The example shown in the previous section, "IPB_Arguments interface", shows how you can use three of these methods: IsArray, IsObject, and IsNull.

This example shows how you can use the SetToNull method to set the returnValue member of the PBCallInfo structure to null:

if ( ci->pArgs->GetAt(0)->IsNull() ||
   ci->pArgs->GetAt(1)->IsNull() )
   {
// if either of the passed arguments is null,
// return the null value
ci->returnValue->SetToNull();

Set methods

The IPB_Value set methods set values in the PBCallInfo structure. There is a set method for each PowerBuilder datatype: SetInt, SetUint, SetLong, SetUlong, and so on. These methods automatically set the value represented by IPB_Value to not null. The syntax is:

virtual PBXRESULT Set<type>(<pbtype> arg);

For example, the SetLong method takes an argument of type pblong.

In this example, the method has two integer arguments, set to int_val1 and int_val2:

ci-> pArgs -> GetAt(0) -> SetInt(int_val1);
ci-> pArgs -> GetAt(1) -> SetInt(int_val2);

The IPB_Value set methods set the datatype of the value represented by IPB_Value to a specific type. If the original type of the value is any, you can set it to any other type. Then, because the value now has a specific type, setting it to another type later returns the error PBX_E_MISMATCHED_DATA_TYPE. If the argument is readonly, the error PBX_E_READONLY_ARGS is returned.

Get methods

The IPB_Value get methods obtain values from the PBCallInfo structure. There is a get method for each PowerBuilder datatype: GetInt, GetUint, GetLong, GetUlong, and so on.The syntax is:

virtual <pbtype> Get<type>( ); 

For example, the GetString method returns a value of type pbstring.

The following example uses the IPB_Value GetAt method to assign the value at the first index of the pArgs member of the PBCallInfo structure to a variable of type IPB_Value* called pArg. If pArg is not null, the GetLong method sets the variable longval to the value in pArg:

PBCallInfo   *ci
...
pblong longval = NULL;
IPB_Value* pArg = ci-> pArgs-> GetAt(0);
   
if (!pArg->IsNull())
   longval = pArg -> GetLong();

If the value is null, or if you use a get method that is expected to return one datatype when the value is a different datatype (such as using GetLong when the datatype is pbarray), the result returned is undetermined.

The get methods can also be used with the returnValue member of PBCallInfo:

ret_val = ci.returnValue->GetInt();
return ret_val;