IPB_Value interface

Description

The IPB_Arguments and IPB_Value interfaces pass values between the PowerBuilder VM and PowerBuilder extension modules. Through the IPB_Value interface, you can access information about each variable, including its type, null flag, access privileges, array or simple type, and reference type.

Methods

Method

Description

Get<type>

Set of datatype-specific methods that return a pointer to the data in IPB_Value

GetClass

Returns the class handle of a PowerBuilder object

GetType

Returns the datatype of a single data item or array

IsArray

Returns true if the IPB_Value instance contains an array, otherwise returns false

IsByRef

Returns true if the IPB_Value instance is passed by reference

IsEnum

Returns true if the IPB_Value instance contains a null value, otherwise returns false

IsObject

Returns true if the IPB_Value instance contains an object or object array, otherwise returns false

SetToNull

Used to set the data contained in the IPB_Value instance to null so that data can be reset

Set<type>

Set of datatype-specific methods that set the value of the IPB_Value instance


Get<type>

Description

A set of datatype-specific methods that return a pointer to the data in IPB_Value.

Syntax

GetArray ( ) 
GetBlob( ) 
GetBool ( ) 
GetByte ( ) 
GetChar ( ) 
GetDate ( ) 
GetDateTime( ) 
GetDecimal ( ) 
GetDouble ( ) 
GetInt ( ) 
GetLong( ) 
GetLongLong( ) 
GetObject ( ) 
GetReal( ) 
GetString ( ) 
GetTime( ) 
GetUint( ) 
GetUlong ( ) 

Return value

A predefined PBNI datatype that corresponds to the PowerBuilder datatype in the method name.

Examples

This statement gets the date in the first value in the PBCallInfo structure and splits it into year, month, and day:

Session -> SplitDate(ci-> pArgs -> GetAt(0) ->
GetDate(),&yy,&mm,&dd); 

Usage

If IPB_Value contains a null value, or if you are trying to get a specific datatype from an IPB_Value instance of another datatype, the data retrieved is undetermined. If the datatype is string, blob, decimal, time, date, datetime, array, or object, the return value points to the same address pointed to by IPB_Value. As a result, changing either the variable that holds the return value or the value of the IPB_Value instance affects the other.

See also

Set<type>

GetClass

Description

Returns the class handle of a PowerBuilder object.

Syntax

GetClass( )

Return value

pbclass or null on error.

Examples

pbclass clz = ci-> pArgs-> GetAt(i)-> GetClass();

See also

Get<type>

GetType

Set<type>

GetType

Description

Returns the datatype of a single data item or array.

Syntax

GetType()

Return value

pbuint

Examples

ArgsType = ci->pArgs->GetAt(i)->GetType();
switch (ArgsType) 
{
case pbvalue_int:
if (ci->pArgs->GetAt(i)->IsNull())
pArguments[i].int_val=1;
else
pArguments[i].int_val = 
ci->pArgs->GetAt(i)->GetInt();
break;
...

Usage

If the IPB_Value instance contains an object or structure, GetType returns the class ID of the data. Otherwise, it returns a simple datatype defined in the list of pbvalue_type enumerated types.

See also

Get<type>

GetClass

Set<type>

IsArray

Description

Returns true if the IPB_Value instance contains an array; otherwise, returns false.

Syntax

IsArray( )

Return value

pbboolean

Examples

This example tests whether an IPB_Value instance is an array before obtaining the array:

if(ci->pArgs->GetAt(i)->IsArray())
{
pArguments[i].array_val = 
ci->pArgs->GetAt(i)->GetArray();
continue;
}

See also

IsByRef

IsEnum

IsObject

IsByRef

Description

Returns true if the IPB_Value instance contains a by reference argument; otherwise it returns false.

Syntax

IsByRef()

Return value

pbboolean

Examples

This example shows how you would use IsByRef to test whether an argument is obtained by reference:

if(ci->pArgs->GetAt(i)->IsByRef())
...

See also

IsArray

IsEnum

IsObject

IsEnum

Description

Returns true if the IPB_Value instance contains an enumerated value; otherwise it returns false.

Syntax

IsEnum( )

Return value

pbboolean

See also

GetEnumItemName

GetEnumItemValue

IsNull

Description

Returns true if the IPB_Value instance contains a null value; otherwise, it returns false.

Syntax

IsNull( )

Return value

pbboolean

Examples

This example tests whether an IPB_Value instance contains a null value before attempting to obtain its value:

if(ci->pArgs->GetAt(i)->IsObject()) 
{
if (ci->pArgs->GetAt(i)->IsNull()) 
pArguments[i].obj_val=0;
else
pArguments[i].obj_val = 
ci->pArgs->GetAt(i)->GetObject();
continue;
}
...

See also

IsArray

IsByRef

IsObject

SetToNull

IsObject

Description

Returns true if the IPB_Value instance contains an object or object array; otherwise it returns false.

Syntax

IsObject( )

Return value

pbboolean

Examples

This example tests whether an IPB_Value instance contains an object before attempting to obtain the object:

if( ci->pArgs->GetAt(i)->IsObject()) 
{
if (ci->pArgs->GetAt(i)->IsNull()) 
pArguments[i].obj_val = 0;
else
pArguments[i].obj_val = 
ci->pArgs->GetAt(i)->GetObject();
continue;
}
...

See also

IsArray

IsByRef

IsEnum

Set<type>

Description

Set of datatype-specific methods that set the value of the IPB_Value instance.

Syntax

SetArray ( pbarray array ) 
SetBlob( pbblob blob ) 
SetBool ( pbboolean boolean ) 
SetByte ( pbbyte byte ) 
SetChar ( pbchar char) 
SetDate ( pbdate date ) 
SetDateTime( pbdatetime datetime) 
SetDecimal ( pbdecimal dec) 
SetDouble ( pbdouble double) 
SetInt ( pbint int) 
SetLong( pblong long ) 
SetLongLong( pblonglong longlong ) 
SetObject ( pbobject object) 
SetPBString ( pbstring string) 
SetReal( pbreal real ) 
SetString ( LPCTSTR string) 
SetTime( pbtime time ) 
SetUint( pbuint uint) 
SetUlong ( pbulong ulong ) 

Return value

PBXRESULT.

Examples

This example uses the IPB_Value SetPBString method to set values in PBCallInfo. It also uses the IPB_Session SetString method to set the ret_val string to the return value in the PBCallInfo structure:

pbclass cls;
pbmethodID mid;
PBCallInfo* ci = new PBCallInfo;
pbstring ret_val;
LPCTSTR pStr;

cls= Session -> GetClass(myobj);
if (isAny) 
mid=Session-> GetMethodID(cls, "uf_any_byvalue",
PBRT_FUNCTION, "AAAAA");
else
mid=Session-> GetMethodID(cls, "uf_string_byvalue",
PBRT_FUNCTION, "SSSSS");
Session-> InitCallInfo(cls, mid, ci);

// Call IPB_Value SetPBString method
ci-> pArgs -> GetAt(0) -> SetPBString(s_low);
ci-> pArgs -> GetAt(1) -> SetPBString(s_mid);
ci-> pArgs -> GetAt(2) -> SetPBString(s_high);
pStr = Session -> GetString(s_null);

if (pStr != 0)
{
if (strcmp(pStr, "null") == 0 )
ci-> pArgs -> GetAt(3) -> SetToNull();
else
ci-> pArgs -> GetAt(3) -> SetPBString(s_null);
}

Session -> InvokeObjectFunction(myobj, mid, ci);
ret_val = Session -> NewString("");
// Call IPB_Session SetString method
Session -> SetString(ret_val, Session->GetString
(ci->returnValue->GetString()));
Session -> FreeCallInfo(ci);
delete ci;
return ret_val;

Usage

These methods automatically set the value of IPB_Value to not null and return an error if the datatype to be set does not match the existing datatype. The error code is PBX_E_MISMATCHED_DATA_TYPE. If the value is a read-only argument, it returns the error PBX_E_READONLY_ARGS. If the datatype is string or blob, a deep copy is performed. The existing value is destroyed first, and then the contents of the argument are copied into a new value.

See also

Get<type>

SetToNull

Description

Sets the data contained in the IPB_Value instance to null so the data can be reset.

Syntax

SetToNull( )

Return value

PBXRESULT. If the value is a read-only argument, the error PBX_E_READONLY_ARGS is returned.

Examples

This example shows the use of SetToNull when a null blob value is returned:

case pbvalue_blob:
pStr=(LPCTSTR)Session-> GetBlob(retVal.blob_val); 
if (strncmp(pStr, "null", 4)==0 )
ci->returnValue->SetToNull();
else
 ci->returnValue->SetBlob(retVal.blob_val);
break;
...

See also

IsEnum