IPB_Session interface

AcquireArrayItemValue
AcquireValue
Add<type>Argument
AddGlobalRef
AddLocalRef
ClearException
CreateResultSet
FindClass
FindClassByClassID
FindGroup
FindMatchingFunction
FreeCallInfo
Get<type>ArrayItem
Get<type>Field
Get<type>GlobalVar
Get<type>SharedVar
GetArrayInfo
GetArrayItemType
GetArrayLength
GetBlob
GetBlobLength
GetClass
GetClassName
GetCurrGroup
GetDateString
GetDateTimeString
GetDecimalString
GetEnumItemName
GetEnumItemValue
GetException
GetFieldID
GetFieldName
GetFieldType
GetGlobalVarID
GetGlobalVarType
GetMarshaler
GetMethodID
GetMethodIDByEventID
GetNativeInterface
GetNumOfFields
GetPBAnyArrayItem
GetPBAnyField
GetPBAnyGlobalVar
GetPBAnySharedVar
GetProp
GetResultSetAccessor
GetSharedVarID
GetSharedVarType
GetString
GetStringLength
GetSuperClass
GetSystemClass
GetSystemGroup
GetTimeString
HasExceptionThrown
HasPBVisualObject
InitCallInfo
InvokeClassFunction
InvokeObjectFunction
IsArrayItemNull
IsAutoInstantiate
IsFieldArray
IsFieldNull
IsFieldObject
IsGlobalVarArray
IsGlobalVarNull
IsGlobalVarObject
IsNativeObject
IsSharedVarArray
IsSharedVarNull
IsSharedVarObject
NewBlob
NewBoundedObjectArray
NewBoundedSimpleArray
NewDate
NewDateTime
NewDecimal
NewObject
NewProxyObject
NewString
NewTime
NewUnboundedObjectArray
NewUnboundedSimpleArray
PopLocalFrame
ProcessPBMessage
PushLocalFrame
Release
ReleaseArrayInfo
ReleaseDateString
ReleaseDateTimeString
ReleaseDecimalString
ReleaseResultSetAccessor
ReleaseString
ReleaseTimeString
ReleaseValue
RemoveGlobalRef
RemoveLocalRef
RemoveProp
RestartRequested
Set<type>ArrayItem
Set<type>Field
Set<type>GlobalVar
Set<type>SharedVar
SetArrayItemToNull
SetArrayItemValue
SetBlob
SetDate
SetDateTime
SetDecimal
SetFieldToNull
SetGlobalVarToNull
SetMarshaler
SetProp
SetSharedVarToNull
SetString
SetTime
SetValue
SplitDate
SplitDateTime
SplitTime
ThrowException
TriggerEvent
UpdateField

Description

The IPB_Session interface is used to interoperate with PowerBuilder. An abstract interface, it defines methods for accessing PowerScript data, calling PowerScript functions, catching and throwing PowerScript exceptions, and setting a marshaler to convert PowerBuilder data formats to the user's communication protocol.

Methods

This table lists functions by category. Full descriptions in alphabetic order follow the table.

Purpose

Method

Description

Managing sessions

Release

Releases this IPB session. The IPB_Session object becomes invalid after the call.

Managing object references

AddGlobalRef

Adds a global reference to the specified PowerBuilder object.

 

AddLocalRef

Adds a local reference to the specified PowerBuilder object.

 

NewObject

Creates a new object of the specified type.

 

PopLocalFrame

Pops the current local reference frame from the current native method stack frame.

 

PushLocalFrame

Pushes a local reference frame onto the current native method stack frame.

 

RemoveGlobalRef

Removes a global reference to the specified PowerBuilder object.

 

RemoveLocalRef

Removes a local reference to the specified PowerBuilder object.

Managing shared properties

GetProp

Retrieves a pointer to the data value of a variable that has been registered as a shared property for the current IPB session.

 

RemoveProp

Removes the specified variable from the list of properties of the current IPB session.

 

SetProp

Adds a new variable to the list of properties of the current session or changes the value of an existing variable.

Handling the PowerBuilder message queue

ProcessPBMessage

Checks the PowerBuilder message queue and, if there is a message in the queue, attempts to process it.

Handling exceptions

ClearException

Clears the current PowerBuilder exception object.

 

GetException

Obtains the current thrown exception object.

 

HasExceptionThrown

Checks for the existence of an exception that has been thrown but not cleared.

 

ThrowException

Throws a PowerBuilder exception or inherited exception, replacing the existing exception if one exists.

Passing arguments

Add<type>Argument

Adds an argument in a variable argument PowerBuilder call.

 

FreeCallInfo

Frees memory allocated by InitCallInfo.

 

InitCallInfo

Initializes the PBCallInfo structure.

Finding PowerBuilder classes and objects

FindGroup

Searches for a group with a given name and group type in the current library list.

 

FindClass

Searches for a class with a given name within a given group.

 

FindClassByClassID

Searches for a class with a given name and a given ID.

 

GetClass

Returns the class handle of a PowerBuilder object.

 

GetClassName

Returns the name of a class in lowercase.

 

GetCurrGroup

Returns the name of the current group.

 

GetSuperClass

Returns the base class of a class, if any.

 

GetSystemClass

Returns the system class handle of a PowerBuilder object.

 

GetSystemGroup

Returns the class that contains all the system global functions.

 

IsAutoInstantiate

Returns true if the specified class is an autoinstantiated class; otherwise returns false.

Working with functions and events

FindMatchingFunction

Finds a function that has the specified argument list.

 

GetMethodID

Returns the ID of the requested function.

 

GetMethodIDByEventID

Returns the ID of the function that has a given predefined PowerBuilder event ID.

 

InvokeClassFunction

Invokes system or user global functions.

 

InvokeObjectFunction

Invokes a class member function.

 

TriggerEvent

Triggers a PowerBuilder event.

Working with enumerated variables

GetEnumItemName

Obtains the name of an enumerated variable.

 

GetEnumItemValue

Obtains the value of an enumerated variable.

Working with global variables

GetGlobalVarID

Returns the name of a global variable.

 

GetGlobalVarType

Returns the datatype of a global variable.

 

Get<type>GlobalVar

Returns the value of a global variable of a specific datatype.

 

GetPBAnyGlobalVar

Obtains the value of a global variable of type Any.

 

IsGlobalVarArray

Returns true if the global variable contains an array, otherwise returns false.

 

IsGlobalVarNull

Returns true if the global variable contains a null value, otherwise returns false.

 

IsGlobalVarObject

Returns true if the global variable contains a pbobject, otherwise returns false.

 

Set<type>GlobalVar

Sets the value of a global variable of a specific datatype.

 

SetGlobalVarToNull

Sets the value of a shared variable to null.

Working with shared variables

GetSharedVarID

Returns the name of a shared variable.

 

GetSharedVarType

Returns the datatype of a shared variable.

 

Get<type>SharedVar

Returns the value of a shared variable of a specific datatype.

 

GetPBAnySharedVar

Obtains the value of a shared variable of type Any.

 

IsSharedVarArray

Returns true if the shared variable contains an array, otherwise returns false.

 

IsSharedVarNull

Returns true if the shared variable contains a null value, otherwise returns false.

 

IsSharedVarObject

Returns true if the shared variable contains a pbobject, otherwise returns false.

 

Set<type>SharedVar

Sets the value of a shared variable of a specific datatype.

 

SetSharedVarToNull

Sets the value of a shared variable to null.

Working with arrays

Get<type>ArrayItem

Returns the value of an array item of a specific datatype.

 

GetArrayInfo

Obtains information about an array.

 

GetArrayItemType

Obtains the datatype of an item in an array.

 

GetArrayLength

Returns the length of an array.

 

GetPBAnyArrayItem

Obtains the value of an array item of type Any.

 

IsArrayItemNull

Returns true if the array item contains an array, otherwise returns false.

 

NewBoundedSimpleArray

Creates a bounded simple data array.

 

NewUnboundedSimpleArray

Creates an unbounded simple data array.

 

NewBoundedObjectArray

Creates a bounded PowerBuilder object or structure array.

 

NewUnboundedObjectArray

Creates an unbounded PowerBuilder object or structure data array.

 

ReleaseArrayInfo

Releases memory returned by GetArrayInfo.

 

Set<type>ArrayItem

Sets the value of an array item of a specific datatype.

 

SetArrayItemToNull

Sets the value of an array item to null.

Working with strings

GetStringLength

Returns the length of a string in bytes without the terminator.

 

GetString

Returns a pointer to the string passed in as an argument.

 

NewString

Creates a new string.

 

ReleaseString

Releases the memory used by a string.

 

SetString

Frees an existing string and assigns a new string value to it.

Working with binary large objects

GetBlob

Returns a pointer to the data buffer for a blob.

 

GetBlobLength

Returns the length in bytes of blob data in a buffer.

 

NewBlob

Creates a new blob and duplicates a buffer for the new blob data.

 

SetBlob

Destroys the existing data in a blob and copies data into it from a buffer.

Working with decimal values

GetDecimalString

Converts decimal data in a pbdec object to a string.

 

NewDecimal

Allocates resources for a new decimal data object.

 

ReleaseDecimalString

Frees the memory acquired using GetDecimalString.

 

SetDecimal

Converts a string to a decimal.

Working with date and time values

GetDateString

Converts data in a pbdate object to a string.

 

GetDateTimeString

Converts data in a pbdatetime object to a string.

 

GetTimeString

Converts data in a pbtime object to a string.

 

NewDate

Creates a new pbdate data object.

 

NewDateTime

Creates a new pbdatetime data object.

 

NewTime

Creates a new pbtime data object.

 

ReleaseDateString

Frees the memory acquired using GetDateString.

 

ReleaseDateTimeString

Frees the memory acquired using GetDateTimeString.

 

ReleaseTimeString

Frees the memory acquired using GetTimeString.

 

SetDate

Resets the value of the specified pbdate object.

 

SetDateTime

Resets the value of the specified pbdatetime object.

 

SetTime

Resets the value of the specified pbtime object.

 

SplitDate

Splits the specified pbdate object into a year, month, and day.

 

SplitDateTime

Splits the specified pbdatetime object into a year, month, and day.

 

SplitTime

Splits the specified pbtime object into a year, month, and day.

Working with data values

AcquireArrayItemValue

Clones the data in the PBCallInfo structure in an array item and resets the IPB_Value pointer.

 

AcquireValue

Clones the data in the PBCallInfo structure and resets the IPB_Value pointer.

 

ReleaseValue

Frees the value acquired by the AcquireValue or AcquireArrayItemValue method.

 

SetValue

Sets the value of one IPB_Value object to the value of another IPB_Value object

Working with fields

GetFieldID

Obtains the internal ID of a class instance variable.

 

GetFieldName

Obtains the name of the specified field.

 

GetFieldType

Obtains the datatype of a class instance variable.

 

GetNumOfFields

Obtains the number of fields in the specified class.

 

GetPBAnyField

Obtains the value of a variable of type Any.

 

Get<type>Field

Obtains a pointer to the instance variable data for a specified variable.

 

IsFieldArray

Returns true if the field contains an array, otherwise returns false.

 

IsFieldNull

Returns true if the field contains a null value array, otherwise returns false.

 

IsFieldObject

Returns true if the field contains a pbobject, otherwise returns false.

 

Set<type>Field

A set of datatype-specific functions. Sets the value of an instance field of an object.

 

Set<type>Field

A set of datatype-specific functions. Sets the value of an instance field of an object.

 

UpdateField

Refreshes a visual property of a PowerBuilder object.

Working with native classes

GetNativeInterface

Obtains a pointer to the interface of a native class.

 

IsNativeObject

Determines whether a pbobject is an instance of a native class.

Accessing result sets from DataWindows and DataStores

CreateResultSet

Creates a result set object using a pointer to an IPB_ResultSetAccessor object.

 

GetResultSetAccessor

Obtains an interface through which you can read data from a result set.

 

ReleaseResultSetAccessor

Releases the pointer obtained using GetResultSetAccessor.

Working with marshaler extensions

GetMarshaler

Obtains the marshaler object associated with a proxy object.

 

NewProxyObject

Creates a proxy for a remote object.

 

SetMarshaler

Sets a marshaler that will be used to invoke remote methods and convert PowerBuilder data formats to the user's communication protocol.


AcquireArrayItemValue

Description

Clones the data in the PBCallInfo structure in an array item and resets the IPB_Value pointer.

Syntax

AcquireArrayItemValue( pbarray array, pblong dim[ ])

Argument

Description

array

A valid pbarray structure.

dim

A pblong array to hold the indexes of all dimensions of the array. The size of the array must equal the dimensions of array.


Return value

IPB_Value*.

Examples

This FOR loop acquires the value of an item in an array and sets the value in another array:

for( i=1; i <= bound; i++)
{
   dim[0]= i;
   ipv = Session -> AcquireArrayItemValue(refArg, dim);
   Session -> SetArrayItemValue(*i_array, dim, ipv);
   Session -> ReleaseValue(ipv);
}

Usage

The AcquireArrayItemValue method enables you to retain the data in the PBCallInfo structure for a single array item.

The AcquireArrayItemValue method is independent of the type of the data but is most useful for acquiring the value of pointer values, such as pbvalue_string, pbvalue_blob, and so on. When you call FreeInfo, the data is not freed and the pointer returned by AcquireArrayItemValue is still valid.

When you no longer need the data, you must call the ReleaseValue method to free the data. Failing to do so causes a memory leak.

The PBVM clones a new IPB_Value and resets the existing one. If you attempt to get or acquire the original value, the value returned is zero or null until another IPB_Value is set to the value.

Working with large arrays

The processing that the AcquireArrayItemValue and ReleaseValue methods perform results in poor performance when handling large arrays. It is more efficient to get the type of the array and handle each type with appropriate type-specific functions.

See also

ReleaseValue

AcquireValue

Description

Clones the data in the PBCallInfo structure and resets the IPB_Value pointer.

Syntax

AcquireValue ( IPBValue* value ) 

Argument

Description

value

The value to be returned


Return value

IPB_Value*.

Examples

The AcquireValue method is used to obtain a message argument value. Later, when the value is no longer needed, it is released using ReleaseValue to avoid memory leaks:

// Acquire a value
MessageArg = session->AcquireValue
   ( ci->pArgs->GetAt(0) );
pbstring pbMessage = MessageArg->GetString() ;
Message = (LPSTR)session->GetString(pbMessage) ;
...
// Cleanup phase
if (MessageArg)
{
   Session->ReleaseValue ( MessageArg ) ;
}

Usage

The AcquireValue method enables you to retain the data in the PBCallInfo structure. The AcquireValue method is independent of the type of the data but is most useful for acquiring the value of pointer values such as pbvalue_string, pbvalue_blob, and so on. When you call FreeInfo, the data is not freed and the pointer returned by AcquireValue is still valid.

If the value acquired is an array, the entire array is acquired. To acquire a single element in an array, use the AcquireItemValue method.

When you no longer need the data, you must call the ReleaseValue method to free the data. Failing to do so causes a memory leak.

The PBVM clones a new IPB_Value and resets the existing one. If you attempt to get or acquire the original value, the value returned is zero or null until another IPB_Value is set to the value.

See also

AcquireArrayItemValue

ReleaseValue

Add<type>Argument

Description

Adds an argument of a specific type in a variable argument PowerBuilder call.

Syntax

AddArrayArgument ( PBCallInfo *ci, pbblob value, pbboolean IsNull ) 
AddBlobArgument ( PBCallInfo *ci, pbblob value, pbboolean IsNull ) 
AddBoolArgument ( PBCallInfo *ci, pbboolean value, pbboolean IsNull ) 
AddByteArgument ( PBCallInfo *ci, pbbyte value, pbboolean IsNull ) 
AddCharArgument ( PBCallInfo *ci, pbchar value, pbboolean IsNull ) 
AddDateArgument ( PBCallInfo *ci, pbdate value, pbboolean IsNull ) 
AddDateTimeArgument ( PBCallInfo *ci, pbdatetime value, pbboolean IsNull ) 
AddDecArgument ( PBCallInfo *ci, pbdec value, pbboolean IsNull ) 
AddDoubleArgument ( PBCallInfo *ci, pbdouble value, pbboolean IsNull ) 
AddIntArgument ( PBCallInfo *ci, pbint value, pbboolean IsNull ) 
AddLongArgument ( PBCallInfo *ci, pblong value, pbboolean IsNull ) 
AddLongLongArgument ( PBCallInfo *ci, pblonglong value, pbboolean IsNull ) 
AddObjectArgument ( PBCallInfo *ci, pbobject value, pbboolean IsNull ) 
AddPBStringArgument ( PBCallInfo *ci, pbstring value, pbboolean IsNull ) 
AddRealArgument ( PBCallInfo *ci, pbreal value, pbboolean IsNull ) 
AddStringArgument ( PBCallInfo *ci, LPCTSTR value, pbboolean IsNull ) 
AddTimeArgument ( PBCallInfo *ci, pbtime value, pbboolean IsNull ) 
AddUintArgument ( PBCallInfo *ci, pbuint value, pbboolean IsNull ) 
AddUlongArgument ( PBCallInfo *ci, pbulong value, pbboolean IsNull ) 

Argument

Description

ci

The PBCallInfo to which the argument is to be added.

value

The value to be added to the arguments array.

IsNull

Indicates whether the argument is null. The default is false.


Return value

PBXRESULT. PBX_OK on success.

Examples

This code tests that adding an integer argument to a PBCallInfo structure ci works correctly:

long Cmy_pbni:: f_Retrieve(IPB_Session* session, pbint retrieve_args, pbobject dwobj)
{
   pbclass cls;
   pbmethodID mid;
   PBCallInfo* ci = new PBCallInfo;
   pblong ret_val;
   PBXRESULT ret;

   cls = session-> GetClass(dwobj);
   mid = session-> GetMethodID
      (cls, "retrieve", PBRT_FUNCTION, "LAV");
   if (mid == kUndefinedMethodID) 
      return -1;

   session-> InitCallInfo(cls, mid, ci);

   ci-> pArgs-> GetAt(0)-> SetInt(retrieve_args);
   session-> AddIntArgument(ci, retrieve_args, false); 

   ret = session->InvokeObjectFunction(dwobj, mid, ci);
   if (ret!= PBX_OK)
      ret_val= ret;
   else
      ret_val= ci-> returnValue-> GetLong();

   session-> FreeCallInfo(ci);
   delete ci;

   return ret_val;
}

Usage

This call is used in variable argument PowerBuilder calls, such as datawindow.retrieve(arg). After the call, the value returned by ci->pArgs->GetCount() increases by one.

See also

GetCount

InvokeClassFunction

InvokeObjectFunction

AddGlobalRef

Description

Adds a global reference to the specified PowerBuilder object.

Syntax

AddGlobalRef (pbobject  obj)

Argument

Description

obj

A valid PowerBuilder object handle


Return value

pbclass or null on error.

Examples

This example checks whether a return value is null, and if it is not, adds a global reference to it to the session:

if (ci-> returnValue-> IsNull())
   ret_val = 0;
else
   {
   ret_val = ci-> returnValue-> GetObject();
   Session -> AddGlobalRef(ret_val);
} 

See also

RemoveGlobalRef

AddLocalRef

Description

Adds a local reference to the specified PowerBuilder object.

Syntax

AddLocalRef (pbobject  obj)

Argument

Description

obj

A valid PowerBuilder object handle


Return value

pbclass or null on error.

Examples

This example defines functions that add and remove local references:

void MyPBNIClass::reference()
{
   d_session->AddLocalRef(d_pbobject);
}

void MyPBNIClass::unreference()
{
   if(d_pbobject != NULL)
      d_session->RemoveLocalRef(d_pbobject);
}

See also

PopLocalFrame

PushLocalFrame

RemoveLocalRef

ClearException

Description

Clears the current PowerBuilder exception object.

Syntax

ClearException ()

Return value

None.

Usage

HasExceptionThrown returns false after a call to ClearException. If no exception has been thrown, this call has no effect.

See also

GetException

HasExceptionThrown

ThrowException

CreateResultSet

Description

Creates a result set object using a pointer to an IPB_ResultSetAccessor object.

Syntax

CreateResultSet (IPB_ResultSetAccessor* rs)

Argument

Description

rs

A pointer to an IPB_ResultSetAccessor object


Return value

pbobject.

Examples

This example loads the PBVM and calls the f_ret and f_in functions in the custom class user object n_rs in the PBL pbrs.pbl. The PowerScript for the functions is shown after the C++ code:

#include "stdafx.h"
#include "windows.h"
#include "pbni.h"
#include "vector"
using std::vector;

void main(int argc, char* argv[])
{
   HINSTANCE hinst = LoadLibrary("pbvm190.dll");

   typedef PBXRESULT (*P_PB_GetVM)(IPB_VM** vm);

   P_PB_GetVM getvm = (P_PB_GetVM)GetProcAddress(hinst,
      "PB_GetVM");
   IPB_VM*   pbvm;

   getvm(&pbvm);

   IPB_Session* session = NULL;
   vector<LPCSTR> ll(1);

   ll[0] = "pbrs.pbl";
      pbvm->CreateSession("pbrs", &ll[0], 1, &session);

   pbgroup group = session->FindGroup("n_rs",
      pbgroup_userobject);
   if (group == NULL) return;
      pbclass cls = session->FindClass(group, "n_rs");
   if (cls == NULL) return;
         pbobject obj = session->NewObject(cls);
   if (obj == NULL) return;

   pbmethodID mid = session->GetMethodID(cls, "f_ret",
      PBRT_FUNCTION, "Cresultset.");
   PBCallInfo ci;
   session->InitCallInfo(cls, mid, &ci);
   session->InvokeObjectFunction(obj, mid, &ci);
     // Use the result set returned from f_ret to
   // create an IPB_ResultSetAccessor rsa
   pbobject rs = ci.returnValue->GetObject();
   IPB_ResultSetAccessor* rsa = 
      session->GetResultSetAccessor(rs);

   // Create a result set object from rsa
   pbobject rsobj = session->CreateResultSet(rsa);
   

   // Call the f_in method
   mid = session->GetMethodID(cls, "f_in",
      PBRT_FUNCTION, "IRCresultset.");
   PBCallInfo ci1;
   session->InitCallInfo(cls, mid, &ci1);
   // Set the result set object rsobj as the
   // argument for f_in
   ci1.pArgs->GetAt(0)->SetObject(rsobj);
   session->InvokeObjectFunction(obj, mid, &ci1);


   session->FreeCallInfo(&ci);
   session->FreeCallInfo(&ci1);
}

f_ret retrieves data from a database into a DataStore and generates a result set:

ResultSet rs
DataStore ds

Long sts
Integer li_ret

// Profile Demo Database V190
SQLCA.DBMS = "ODBC"
SQLCA.AutoCommit = False
SQLCA.DBParm = &
   "ConnectString='DSN=Demo Database V190;UID=dba;PWD=sql'"
connect using sqlca;

ds = Create DataStore
ds.DataObject = ""
ds.DataObject = "d_rs"
ds.SetTransObject(sqlca)
w_main.dw_1.SetTransObject(sqlca)

long ll_ret, rows, rows2
ll_ret = ds.Retrieve()
ll_ret = w_main.dw_1.Retrieve()
//ds.sharedata(w_main.dw_1)
rows = ds.RowCount()
rows2 = w_main.dw_1.RowCount()
messagebox("info from f_ret", " row count is " &
   + string(rows) + " or " + string(rows2))
sts = ds.GenerateResultSet(rs)

Return rs

f_in takes a result set, rs, as an argument and uses it to create a DataStore:

DataStore ds
Int cnt, li_ret

ds = Create DataStore
ds.CreateFrom(rs)
cnt = ds.RowCount()
messagebox("info from f_in", "row count is " + string(cnt))
Return cnt

Usage

To use the IPB_ResultSetAccessor interface, load the PBVM, obtain a result set from a PowerBuilder application, and call GetResultSetAccessor on this result set to get an IPB_ResultSetAccessor interface object. You can then call the methods of this object to get information about the result set. You can also call CreateResultSet using this object as an argument to create a result set that you can return to PowerBuilder.

When you call CreateResultSet, the AddRef function of the IPB_ResultSetAccessor interface is called on the rs argument implicitly to add a reference to the interface pointer.

See also

AddRef

GetResultSetAccessor

IPB_ResultSetAccessor interface

ReleaseResultSetAccessor

FindClass

Description

Searches for a class with a given name within a given group.

Syntax

FindClass(pbgroup group, LPCTSTR name)

Argument

Description

group

The handle of the group in which the class resides

name

The class name in lowercase


Return value

pbclass or null on failure.

Examples

This example finds the group associated with the f_getrow function and uses the group to find the class:

group = session->FindGroup("f_getrow",
   pbgroup_function);
if ( group==NULL ) 
   return;
cls = session->FindClass(group, "f_getrow");
if ( cls==NULL ) 
   return;

Usage

This method searches for a PowerBuilder class with the given name in the given group. For example, in a window definition w_1, w_1 is a group, and w_1 and controls contained in it are all classes of group w_1.

See also

FindGroup

NewObject

FindClassByClassID

Description

Searches for a class with a given name and a given ID.

Syntax

FindClass(pbgroup group, pbint classID)

Argument

Description

group

The handle of the group in which the class resides

classID

The class name in lowercase


Return value

pbclass or null on failure.

Usage

This method searches for a PowerBuilder class with the given name and the given ID.

See also

FindGroup

NewObject

FindGroup

Description

Searches for a group with a given name and group type in the current library list.

Syntax

FindGroup(LPCTSTR name, pbgroup_type type)

Argument

Description

name

The group name in lowercase

type

An enumerated type defined in pbgroup_type


Return value

pbgroup or null on failure.

Examples

This example finds the group associated with user_exception and uses the group to find the class:

group = session-> FindGroup("user_exception",
   pbgroup_userobject);
if ( group==NULL ) 
   return;
cls = session->FindClass(group, "user_exception")

See also

FindClass

NewObject

FindMatchingFunction

Description

Finds a function that has the specified argument list.

Syntax

FindMatchingFunction(pbclass cls, LPCTSTR methodName, PBRoutineType rt, LPCTSTR readableSignature) 

Argument

Description

cls

pbclass containing the method.

methodName

The string name of the method in lowercase.

rt

Type of the method: PBRT_FUNCTION for function or PBRT_EVENT for event.

readableSignature

A comma-separated string listing the types of the method's arguments. The return type of the method is not included in the string. See the Usage section for examples.


Return value

pbmethodID.

Examples

This example returns the method ID of a function named uf_test that takes an integer and a double as arguments:

pbclass cls;
pbmethodID mid;
PBCallInfo* ci = new PBCallInfo;  
unsigned long ret_val;

cls = Session -> GetClass(myobj);
mid = Session -> FindMatchingFunction(cls, "uf_test",
   PBRT_FUNCTION, "int, double");

Session -> InitCallInfo(cls, mid, ci);

Usage

FindMatchingFunction provides an alternative to the GetMethodID function. It requires a list of the function's arguments (the readableSignature) instead of the signature obtained using the pbsig190 tool.

This table shows the readableSignature for each of several functions.

Function prototype

Signature

void test1()

""

int test2()

""

string test3(int a, double b)

"int, double"

datastore test4(powerobject a[], double b[2 to 10, 1 to 7])

"powerobject[], double[2 to 10, 1 to 7]"

int test5(readonly int a[10,20], ref long c[])

"readonly int[10,20], ref long[])"


FindMatchingFunction does not check the access type of the function, so you can use it to obtain the method ID of a private function. GetMethodID cannot obtain the method ID of a private function.

See also

GetMethodID

FreeCallInfo

Description

Frees memory allocated by InitCallInfo.

Syntax

FreeCallInfo(PBCallInfo *ci)

Argument

Description

ci

A pointer to the preallocated PBCallInfo structure


Return value

None.

Examples

FreeCallInfo should be called when the PBCallInfo structure is no longer needed:

Session->InvokeObjectFunction(myobj, mid, ci);

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

Usage

This method frees memory allocated by InitCallInfo but does not free the structure ci itself.

See also

InitCallInfo

Get<type>ArrayItem

Description

Obtains the value of an array item of a specified type.

Syntax

GetBlobArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetBoolArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetByteArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetCharArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetDateArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetDateTimeArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetDecArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetDoubleArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetIntArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull) 
GetLongArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetLongLongArrayItem (pbarray array, pblonglong dim[ ], pbboolean& IsNull) 
GetObjectArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetRealArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetStringArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetTimeArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetUintArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 
GetUlongArrayItem ( pbarray array, pblong dim[ ], pbboolean& IsNull ) 

Argument

Description

array

A valid pbarray structure

dim

The dimension of the array item to be obtained

IsNull

Indicates whether the array item is null


Return value

The value of the array item.

Examples

This example gets the value of an array item of type pbobject:

pbobject      pPBObject = NULL;
pbboolean     bIsNull = 0;
pblong        dim[1];

dim[0] = pbl + 1;
pPBObject = session->GetObjectArrayItem(array, dim, bIsNull);

See also

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

Get<type>Field

Description

A set of methods that gets the value of an instance field of an object.

Syntax

GetArrayField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetBlobField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetBoolField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetByteField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetCharField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetDateField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetDateTimeField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetDecField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetDoubleField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetIntField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetLongField( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetLongLongField( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetObjectField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetRealField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetStringField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetTimeField ( pbobject obj, pbfieldID fid, pbint value ) 
GetUintField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 
GetUlongField ( pbobject obj, pbfieldID fid, pbboolean& isNull ) 

Argument

Description

obj

The handle of the object whose field is to be accessed

fid

The field ID of the specified object

isNull

Indicates whether the field is null


Return value

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

Examples

This example gets the value of a field of type pbstring:

pbboolean   isNull;
pbstring pstr = 
   session->GetStringField(proxy, fid, isNull);
if (pstr != NULL)
{
   myclass = session->GetString(pstr);
   // process myclass   }

See also

GetFieldID

GetFieldType

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

SetFieldToNull

Set<type>Field

Get<type>GlobalVar

Description

A set of methods that gets the value of a global variable of a specific datatype.

Syntax

GetArrayGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetBlobGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetBoolGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetByteGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetCharGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetDateGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetDateTimeGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetDecGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetDoubleGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetIntGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetLongGlobalVar( pbfieldID fid, pbboolean& isNull ) 
GetLongLongGlobalVar( pbfieldID fid, pbboolean& isNull ) 
GetObjectGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetRealGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetStringGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetTimeGlobalVar ( pbfieldID fid, pbint value ) 
GetUintGlobalVar ( pbfieldID fid, pbboolean& isNull ) 
GetUlongGlobalVar ( pbfieldID fid, pbboolean& isNull ) 

Argument

Description

fid

The field ID of the global variable

isNull

Indicates whether the variable is null


Return value

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

Examples

This code gets the value of a global variable of datatype long using its field ID:

fid = session -> GetGlobalVarID("l_gvar");
l_val = session -> GetLongGlobalVar(fid, isNull);
session -> SetLongGlobalVar(fid, l_val + 1);

See also

GetGlobalVarID

GetGlobalVarType

IsGlobalVarArray

IsGlobalVarNull

IsGlobalVarObject

SetGlobalVarToNull

Set<type>GlobalVar

Get<type>SharedVar

Description

A set of methods that gets the value of a shared variable of a specific datatype.

Syntax

GetArraySharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetBlobSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetBoolSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetByteSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetCharSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetDateSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetDateTimeSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetDecSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetDoubleSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetIntSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetLongSharedVar( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetLongLongSharedVar( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetObjectSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetRealSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetStringSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetTimeSharedVar ( pbgroup group, pbfieldID fid, pbint value ) 
GetUintSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 
GetUlongSharedVar ( pbgroup group, pbfieldID fid, pbboolean& isNull ) 

Argument

Description

group

The group whose shared variable is to be accessed

fid

The field ID of the shared variable

isNull

Indicates whether the variable is null


Return value

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

Examples

This code gets the value of a shared variable of type integer:

curGroup = session -> GetCurrGroup();
fid = session -> GetSharedVarID(curGroup, "i_svar");
if (fid == 0xffff) 
{
   MessageBox(NULL, "Illegal fid!", "default", MB_OK);
   return;
}
i_val = session-> GetIntSharedVar(curGroup, fid, isNull);
session-> SetIntSharedVar(curGroup, fid, i_val+1);

See also

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

GetArrayInfo

Description

Obtains information about an array.

Syntax

GetArrayInfo(pbarray array)

Argument

Description

array

A valid array handle


Return value

PBArrayInfo*.

Examples

This IF-ELSE statement populates a PBArrayInfo structure if the array in the first value of a PBCallInfo structure is not null:

if ( !(ci->pArgs->GetAt(0)->IsNull()) )
{
   array = ci->pArgs->GetAt(0)->GetArray();
   pArrayInfo = session->GetArrayInfo (array);
   pArrayItemCount = session->GetArrayLength(array);
}
else
{
   // NULL array
pArrayItemCount = 0;
}

Usage

If the array is an unbounded array, the bounds information in PBArrayInfo is undetermined. The returned PBArrayInfo must be freed later by ReleaseArrayInfo.

See also

Get<type>ArrayItem

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

GetArrayItemType

Description

Obtains the datatype of an item in an array.

Syntax

GetArrayItemType( pbarray array, pblong dim[ ])

Argument

Description

array

A valid pbarray structure.

dim

A pblong array to hold the indexes of each dimension of the array. The size of the array must equal the dimensions of array.


Return value

pbuint.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

GetArrayLength

Description

Obtains the length of an array.

Syntax

GetArrayLength(pbarray array)

Argument

Description

array

A valid array handle


Return value

pblong.

Examples

This IF-ELSE statement populates a PBArrayInfo structure. If the array in the first value of a PBCallInfo structure is not null, it sets the value of the pArrayItemCount variable to the length of the array:

if ( !(ci->pArgs->GetAt(0)->IsNull()) )
{
   array = ci->pArgs->GetAt(0)->GetArray();
   pArrayInfo = session->GetArrayInfo (array);
   pArrayItemCount = session->GetArrayLength(array);
}
else
{
   // NULL array
pArrayItemCount = 0;
}

See also

Get<type>ArrayItem

GetArrayInfo

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewBoundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

GetBlob

Description

Returns a pointer to the data buffer for a blob.

Syntax

GetBlob(pbblob bin)

Argument

Description

bin

A pointer to the source buffer


Return value

void*.

Examples

In this CASE clause, the value returned from GetBlob is cast to the LPCTSTR variable pStr. If it is not null, the return value in the PBCallInfo structure is set to the value of the blob:

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);
         Session -> ReleaseValue(retVal);
      }
   break;

See also

GetBlobLength

NewBlob

SetBlob

GetBlobLength

Description

Returns the length in bytes of blob data in a buffer.

Syntax

GetBlobLength (pbblob bin)

Argument

Description

bin

A pointer to the source buffer


Return value

pblong.

Examples

In this example, the IPB_Value GetBlob function is used to get a blob value from the PBCallInfo structure. The length of the blob is used as an argument to the NewBlob function:

PBCallInfo* ci = new PBCallInfo;
pbblob ret_val;
pblong bloblen;

ret_val = ci.returnValue-> GetBlob();
bloblen = Session-> GetBlobLength(ret_val);
ret_val = Session-> NewBlob   (Session->GetBlob(ret_val), bloblen);

See also

GetBlob

NewBlob

SetBlob

GetClass

Description

Returns the class handle of a PowerBuilder object. This function is most frequently used to obtain a class handle for use with the GetMethodID function.

Syntax

GetClass (pbobject  obj)

Argument

Description

obj

A valid PowerBuilder object handle


Return value

pbclass or null on error.

Examples

In this example, GetClass is used to obtain the class of a variable of type UserData so that the class can be used as an argument to the GetMethodID function:

BOOL CALLBACK CFontEnumerator::EnumFontProc
(
   LPLOGFONT lplf, 
   LPNEWTEXTMETRIC lpntm, 
   DWORD FontType, 
   LPVOID userData
)
{
   UserData* ud = (UserData*)userData;
   pbclass clz = ud->session->GetClass(ud->object);
   pbmethodID mid = ud->session->GetMethodID
      (clz, "onnewfont", PBRT_EVENT, "IS");

   PBCallInfo ci;
   ud->session->InitCallInfo(clz, mid, &ci);

   pbstring str = ud->session->NewString
      (lplf->lfFaceName);
   ci.pArgs->GetAt(0)->SetPBString(str);
   ud->session->TriggerEvent(ud->object, mid, &ci);
  pbint ret = ci.returnValue->GetInt();
   ud->session->FreeCallInfo(&ci);

   return ret == 1   TRUE : FALSE;
}

See also

GetClassName

GetMethodID

GetClassName

Description

Returns the name of a class in lowercase.

Syntax

GetClassName(pbclass cls)

Argument

Description

cls

A valid class handle


Return value

LPCTSTR.

Examples

This example gets the name of a class and sets the size of the variable stLength to the length of the returned string plus 1:

LPCTSTR myClassName = session->GetClassName( myClass );
size_t stLength = strlen( (LPSTR)myClassName ) + 1;

Usage

When you have finished using the name, call the ReleaseString method to free the memory acquired.

See also

GetClass

ReleaseString

GetCurrGroup

Description

Obtains the name of the current group.

Syntax

GetCurrGroup( )

Return value

pbgroup or null on failure.

Examples

This example gets the name of the current group and uses it to obtain the identifier of a shared variable, get the shared variable's value, and reset the shared variable's value:

curGroup = session -> GetCurrGroup();
fid = session -> GetSharedVarID(curGroup, "i_svar");
if (fid == 0xffff) 
{
   MessageBox(NULL, "Illegal fid!", "default", MB_OK);
   return;
}
i_val = session-> GetIntSharedVar(curGroup, fid, isNull);
session-> SetIntSharedVar(curGroup, fid, i_val+1);

See also

Get<type>SharedVar

GetSharedVarID

Set<type>SharedVar

GetDateString

Description

Converts data in a pbdate object to a string.

Syntax

GetDateString(pbdate date)

Argument

Description

date

The pbdate data object to be converted to a string.


Return value

LPCTSTR.

See also

NewDate

ReleaseDateString

SetDate

GetDateTimeString

Description

Converts data in a pbdatetime object to a string.

Syntax

GetDateTimeString(pbdatetime datetime)

Argument

Description

datetime

The pbdatetime data object to be converted to a string.


Return value

LPCTSTR.

See also

NewDateTime

ReleaseDateTimeString

SetDateTime

GetDecimalString

Description

Converts decimal data in a pbdec object to a string.

Syntax

GetDecimalString(pbdec dec)

Argument

Description

dec

The pbdec data object to be converted to a string.


Return value

LPCTSTR.

Examples

This code checks whether a value in the PBCallInfo structure is null. If it is not, it sets the value in the pArguments array to the value in PBCallInfo:

case pbvalue_dec:
if (ci->pArgs->GetAt(i)->IsNull())
{
   pArguments[i].dec_val = Session->NewDecimal();
   Session->SetDecimal(pArguments[i].dec_val, "1.0");
}
   else
   pArguments[i].dec_val = 
      ci->pArgs->GetAt(i)->GetDecimalString();
break;

See also

NewDecimal

ReleaseDecimalString

SetDecimal

GetEnumItemName

Description

Obtains the name of an enumerated variable.

Syntax

GetEnumItemName(LPCTSTR enumName, long enumItemValue)

Return value

LPCTSTR.

Usage

When you have finished using the name, call the ReleaseString method to free the memory acquired.

See also

GetEnumItemValue

ReleaseString

GetEnumItemValue

Description

Obtains the value of an enumerated variable.

Syntax

GetEnumItemValue(LPCTSTR enumName, LPCTSTR enumItemName)

Return value

Long.

Examples

This example gets the numeric value for the boolean! enumerated value, then uses it to return the string value:

pblong lType = session->GetEnumItemValue("object",
   boolean" ); // returns 138
   LPCTSTR szEnum = session->GetEnumItemName( "object", 
   lType ); // returns "boolean"

Usage

GetEnumItemValue and GetEnumItemName support enumerated types. They allow you to convert the name of an enumerated value, a string with an appended exclamation mark (!), to an integer value, and vice versa.

The ! character must be omitted

When you use these functions, the enumItemName should not use the appended exclamation mark (!) character.

To return an enumerated value from an extension to PowerScript, you must use the SetLong function to set the value of the enumerated variable into IPB_Value. Using SetInt or SetShort fails. However, you can use GetInt or GetShort as well as GetLong to obtain the enumerated variable's value, assuming the value is in the appropriate range. For example, if you attempt to use GetInt to obtain a value that is more than 32767, the returned value is truncated.

See also

GetEnumItemName

GetException

Description

Obtains the current thrown exception object.

Syntax

GetException ()

Return value

pbobject.

Examples

This code gets the current exception object, clears the exception, and gets the class of the exception object:

pbclass cls;
pbobject  ex;
...
ex = session-> GetException();
session-> ClearException();
cls = session-> GetClass(ex);

See also

ClearException

HasExceptionThrown

GetFieldID

Description

Obtains the internal ID of a class instance variable.

Syntax

GetFieldID(pbclass cls, LPCTSTR fieldName)

Argument

Description

cls

The class in which the field resides

fieldName

The instance member name, in lowercase


Return value

pbfieldID or 0xffff if a field ID cannot be found.

Examples

This function obtains the identifier of a class's visible field, if it exists, and uses it to set the value of the field:

void CallBack::f_setvisible(IPB_Session* session,
   pbobject dwobj)
{
   pbclass cls;
   IPB_Value* pv;
   pbfieldID fid;
   pbstring strtmp;
   bool isTrue;
   pbboolean isNull;

   cls = session-> GetClass(dwobj);
   fid = session-> GetFieldID(cls, "visible");
   if (fid == kUndefinedFieldID) 
      return;
   isTrue = session-> GetBoolField(dwobj, fid, isNull); 
   if (isTrue)
      session -> SetBoolField(dwobj, fid, false);
    else
      session -> SetBoolField(dwobj, fid, true);
    return ;
}

Usage

GetFieldID is one of a set of functions that allows native code to access the fields of Java objects and get and set their values. You use GetFieldID to retrieve the value of a field, specifying the class name and the field name. The field ID returned can be used as an argument to the related functions.

See also

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

Set<type>Field

SetFieldToNull

GetFieldName

Description

Obtains the name of the specified field.

Syntax

GetFieldName(pbclass cls, pbfieldID fid)

Argument

Description

cls

The class that defines the field

fid

The internal ID of the class instance variable


Return value

LPCTSTR.

The field name of the specified field. If an incorrect field ID is specified, this function returns null.

Usage

When you have finished using the name, call the ReleaseString method to free the memory acquired.

See also

GetFieldID

ReleaseString

GetFieldType

Description

Obtains the datatype of a field declared by a class.

Syntax

GetFieldType(pbclass cls, pbfieldID fid)

Argument

Description

cls

The class that defines the field

fid

The internal ID of the class instance variable


Return value

pbint.

A simple datatype defined in the list of pbvalue_type enumerated types, such as pbvalue_int. See PBNI enumerated types.

Examples

This statement gets the type of the specified field ID:

 pbint pbfieldType = session->GetFieldType(cls, fid);

See also

GetFieldID

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

Set<type>Field

SetFieldToNull

GetGlobalVarID

Description

Returns the internal ID of a global variable.

Syntax

GetGlobalVarID(LPCTSTR name)

Argument

Description

name

The name of the global variable in lowercase


Return value

pbfieldID or null on failure.

Examples

This example gets the internal identifier of a long variable and uses it to get and set a global variable:

fid = session -> GetGlobalVarID("l_gvar");
l_val = session -> GetLongGlobalVar(fid, isNull);
session -> SetLongGlobalVar(fid, l_val + 1);

See also

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarNull

IsGlobalVarObject

SetGlobalVarToNull

Set<type>GlobalVar

GetGlobalVarType

Description

Obtains the datatype of a global variable.

Syntax

GetGlobalVarType(pbfieldID fid)

Argument

Description

fid

The internal ID of the class instance variable


Return value

pbuint.

A simple datatype defined in the list of pbvalue_type enumerated types.

Examples

This code tests getting and setting a global integer variable using the field ID fid:

fid = session -> GetGlobalVarID("i_gvar");
if (session -> GetGlobalVarType(fid) == pbvalue_int)
   {
      i_val=session -> GetIntGlobalVar(fid,isNull);
      session -> SetIntGlobalVar(fid,i_val+1);
   }

See also

GetGlobalVarID

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarNull

IsGlobalVarObject

SetGlobalVarToNull

Set<type>GlobalVar

GetMarshaler

Description

Obtains the marshaler object associated with a proxy object.

Syntax

GetMarshaler(pbproxyObject obj)

Argument

Description

obj

An object of type pbproxyObject for which you want to find the marshaler.


Return value

IPBX_Marshaler*.

Examples

This code creates a Java marshaler object and associates it with a proxy. Later, GetMarshaler is used to get the marshaler object:

// Create JavaMarshaler
JavaMarshaler* marshaler = new JavaMarshaler(env,
   proxy, jobj);

// Associate the JavaMarshaler with the 
// PowerBuilder proxy
session-> SetMarshaler(proxy, marshaler);

ci-> pArgs-> GetAt(0)-> SetObject(proxy);

ci-> returnValue-> SetLong(kSuccessful);

return PBX_OK;
...
// Get the marshaler
IPBX_Marshaler* pIPBX_Marshaler = NULL;

pIPBX_Marshaler =(IPBX_Marshaler*)session
   -> GetMarshaler(proxy);

See also

SetMarshaler

GetMethodID

Description

Returns the ID of the requested method.

Syntax

GetMethodID(pbclass cls, LPCTSTR methodName, PBRoutineType rt, LPCTSTR signature, pbboolean publicOnly)

Argument

Description

cls

pbclass containing the function.

methodName

The string name of the method in lowercase.

rt

Type of the method: PBRT_FUNCTION for function or PBRT_EVENT for event.

signature

Internal signature of the PowerBuilder function, used to identify polymorphic methods in one class. Obtained with the pbsig190 tool. If the signature is a null string (" "), the first method found with the name methodName is returned.

publicOnly

A boolean that determines whether only public methods are searched (true) or all methods are searched (false). The default is true.


Return value

pbMethodID of the method or kUndefinedMethodID on error.

Examples

This function uses GetMethodID to obtain the identifier (mid) of the onnewfont function so that the identifier can be used to initialize the PBCallInfo structure and call the function:

BOOL CALLBACK CFontEnumerator::EnumFontProc
(
   LPLOGFONT lplf, 
   LPNEWTEXTMETRIC lpntm, 
   DWORD FontType, 
   LPVOID userData
)
{
   UserData* ud = (UserData*)userData;
   pbclass clz = ud->session->GetClass(ud->object);
   pbmethodID mid = ud->session->GetMethodID(clz,
      "onnewfont", PBRT_EVENT, "IS");

   PBCallInfo ci;
   ud->session->InitCallInfo(clz, mid, &ci);
   pbstring str = ud->session->
      NewString(lplf->lfFaceName);
   ci.pArgs->GetAt(0)->SetPBString(str);
   ud->session->TriggerEvent(ud->object, mid, &ci);
   pbint ret = ci.returnValue->GetInt();
   ud->session->FreeCallInfo(&ci);

   return ret == 1   TRUE : FALSE;
}

Usage

The GetMethodID function is used to obtain the ID of a method so you can use it to invoke functions and trigger events.

See also

FindMatchingFunction

InvokeObjectFunction

TriggerEvent

Calling PowerScript from an extension

GetMethodIDByEventID

Description

Returns the ID of the method that has a given predefined PowerBuilder event ID.

Syntax

GetMethodIDByEventID(pbclass cls, LPCTSTR eventID)

Argument

Description

cls

pbclass containing the method

eventID

A PowerBuilder predefined event string, such as pbm_bnclicked


Return value

pbMethodID of the method or kUndefinedMethodID on error.

Examples

This statement obtains the ID of the event identified by the name pbm_lbuttonup:

pbmethodID mid = d_session->GetMethodIDByEventID(clz,
   "pbm_lbuttonup");

See also

GetMethodID

GetNativeInterface

Description

Obtains a pointer to the interface of a native class.

Syntax

GetNativeInterface(pbobject obj)

Argument

Description

obj

A valid object handle


Return value

IPBX_UserObject.

Examples

This example invokes the function f_retrieve in the native class Cmy_pbni to retrieve a DataWindow object:

long f_retrieve(IPB_Session* session, pbint iarg,
   pbobject dwObj, pbobject extObj)
{
   Imy_pbni* pImy_pbni = NULL;
   pblong lRet;
   if (session -> IsNativeObject(extObj) )
   {
      pImy_pbni = (Imy_pbni*) session ->
         GetNativeInterface(extObj);

      lRet = pImy_pbni-> f_Retrieve(session,
         iarg, dwObj);
   }
   return lRet;
}

Usage

Use this method in conjunction with IsNativeObject to obtain a direct reference to the IPBX_UserObject associated with a native class in the same PowerBuilder extension. The class and its methods can then be accessed directly.

See also

IsNativeObject

GetNumOfFields

Description

Returns the number of fields in the specified class.

Syntax

GetNumOfFields(pbclass cls)

Argument

Description

cls

A valid class handle for the class whose field is to be accessed


Return value

pbulong.

Examples

This code gets the numbers of fields in the class clz:

pbclass clz = d_session->GetClass(d_pbobj);
pbulong nf = d_session->GetNumOfFields(clz);

See also

GetFieldID

Get<type>Field

IsFieldArray

IsFieldNull

IsFieldObject

SetFieldToNull

Set<type>Field

GetPBAnyArrayItem

Description

Obtains the value of a global variable of type Any.

Syntax

 GetPBAnyArrayItem( pbarray array, pblong dim[], pbboolean& isNull )

Argument

Description

array

A valid pbarray structure.

dim

A pblong array to hold the indexes of each dimension of the array. The size of the array must equal the dimensions of array.

isNull

Indicates whether the variable is null


Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyField

GetPBAnyGlobalVar

GetPBAnySharedVar

GetPBAnyField

Description

Obtains the value of a variable of type Any.

Syntax

GetPBAnyField( pbobject obj, pbfieldID fid, pbboolean& isNull )

Argument

Description

obj

A valid object handle for the object whose value is to be obtained

fid

The field ID of the variable

isNull

Indicates whether the variable is null


Return value

IPB_Value*.

Examples

This example tests all the functions used to get the value of variables of type Any, using PushLocalFrame and PopLocalFrame to simulate the scope of a function call:

session->PushLocalFrame();
pbgroup vgroup = session->FindGroup("n_test",
   pbgroup_userobject);
pbclass vcls = session->FindClass(vgroup, "n_test");
pbobject vobj = session->NewObject(vcls);
pbboolean isNull;

pbfieldID vfid = session->GetFieldID(vcls, "i_a");
IPB_Value* value = session->GetPBAnyField(vobj, 
   vfid, isNull);
pbstring str = value->GetString(); // save actual value

vfid = session->GetSharedVarID(vgroup, "s_a");
value = session->GetPBAnySharedVar(vgroup, 
   vfid, isNull);
//Get the actual value here.

vfid = session->GetGlobalVarID("g_a");
value = session->GetPBAnyGlobalVar(vfid, isNull);
//Get the actual value here.

vfid = session->GetFieldID(vcls, "i_array");
pbarray arr = session->GetArrayField(vobj, 
   vfid, isNull);    //Get the any array first.

long dim = 1;
value = session->GetPBAnyArrayItem(arr, &dim, isNull);
//Get the actual value here.
session->PopLocalFrame();

Usage

The value you retrieve must be of datatype Any to use this function; that is, the variable associated with the function must be declared as a variable of type Any in the development environment. If it is not, the function returns a null pointer and the value of isNull is set to true.

This function returns a pointer to an IPB_Value instance. When it is called, memory is allocated for the returned IPB_Value instance, and the pointer is recorded in the current local frame. The pointer is deleted automatically when the current local frame is popped, which occurs when the current local function returns (you can also call PopLocalFrame to force the frame to be popped).

If you want to use the value returned, you must save the value pointed to by the IPB_Value instance (not the IPB_Value instance itself) before the frame is popped. If you save the pointer itself, the value is only valid until the original value is destroyed.

You can use the AcquireValue function to save the value, or one of the IPB_Value Get<type> functions. For example, the following code saves the string value in the IPB_Value instance ivalue into the string str. The value in str can be used after the local frame is popped and ivalue is deleted:

IPB_Value* ivalue = session->GetPBAnyField(vobj, vfid,
   isNull);
pbstring str = ivalue->GetString();

If you do not know the actual datatype of the Any variable, use the IPB_Value GetType function to get its datatype first, then use the appropriate get function to get its value.

IPB_Value holds a reference to the original value

The value in the IPB_Value instance is a reference to the original value. If you change the actual value of the returned IPB_Value, the original value is also changed. If you use the AcquireValue function to save the value, it clones a new IPB_Value and resets the existing IPB_Value pointer.

See also

GetPBAnyArrayItem

GetPBAnyGlobalVar

GetPBAnySharedVar

GetPBAnyGlobalVar

Description

Obtains the value of a global variable of type Any.

Syntax

GetPBAnyGlobalVar( pbfieldID fid, pbboolean& isNull )

Argument

Description

fid

The field ID of the variable

isNull

Indicates whether the variable is null


Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyArrayItem

GetPBAnyField

GetPBAnySharedVar

GetPBAnySharedVar

Description

Obtains the value of a shared variable of type Any.

Syntax

GetPBAnySharedVar( pbgroup group, pbfieldID fid, pbboolean& isNull )

Argument

Description

group

The group to which the variable belongs

fid

The field ID of the variable

isNull

Indicates whether the variable is null


Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyArrayItem

GetPBAnyField

GetPBAnyGlobalVar

GetProp

Description

Retrieves a pointer to the data value of a variable that has been registered as a shared property for the current IPB session.

Syntax

GetProp(LPCTSTR name)

Argument

Description

name

The name of the variable whose value is to be retrieved.


Return value

Void*. If the variable does not exist, returns null.

Examples

See SetProp.

Usage

The variable's name must first be registered with the session using the SetProp function.

See also

RemoveProp

SetProp

GetResultSetAccessor

Description

Obtains an interface through which you can read data from a result set.

Syntax

GetResultSetAccessor (pbobject rs)

Argument

Description

rs

A pbobject holding a result set obtained using CreateResultSet


Return value

IPB_ResultSetAccessor

Examples

This example gets a result set, rs, from the return value of a PowerScript function and uses it to create an IPB_ResultSetAccessor object, rsa:

pbobject rs = ci.returnValue->GetObject();
IPB_ResultSetAccessor* rsa = 
   session->GetResultSetAccessor(rs);

See also

CreateResultSet

ReleaseResultSetAccessor

GetSharedVarID

Description

Returns the internal ID of a shared variable.

Syntax

GettSharedVarID(pbgroup group, LPCTSTR fieldname)

Argument

Description

group

The group to which the shared variable belongs

fieldname

The name of the field that contains the shared variable, in lowercase


Return value

pbfieldID.

Returns 0xffff if the ID cannot be found.

Examples

This code uses GetSharedVarID to obtain the field ID of a shared variable, then uses that ID to obtain the value of the variable:

curGroup = session -> GetCurrGroup();
fid = session -> GetSharedVarID(curGroup,"i_svar");
if (fid == 0xffff) 
{
   MessageBox(NULL, "Illegal fid!", "default", MB_OK);
   return;
}
i_val = session -> GetIntSharedVar(curGroup, fid,
   isNull);

See also

Get<type>SharedVar

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

GetSharedVarType

Description

Obtains the datatype of the specified shared variable.

Syntax

GetSharedVarType ( pbgroup group, pbfieldID fid ) 

Argument

Description

group

The group to which the shared variable belongs

fid

The internal field ID of the shared variable


Return value

pbuint.

A simple datatype defined in the list of pbvalue_type enumerated types.

Examples

This example gets the field ID of a shared variable, then uses that ID to get the type of the shared variable:

pbuint pbvaltype;
curGroup = session -> GetCurrGroup();
fid = session -> GetSharedVarID(curGroup,"i_svar");
pbvaltype = session -> GetSharedVarType(curGroup, fid);

See also

Get<type>SharedVar

GetSharedVarID

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

GetString

Description

Returns a pointer to the string passed in as an argument.

Syntax

GetString (pbstring* string)

Argument

Description

string

A pointer to a pbstring


Return value

LPCTSTR.

Examples

This example uses the IPB_Value GetString function to obtain a string value from the PBCallInfo structure. If the string is not null, the IPB_Session GetString function sets the value of the proxyname string to a pointer to the returned value:

string proxyName;
{
   pbstring pn = ci->pArgs->GetAt(2)->GetString();

   if (pn == NULL)
   {
      ci->returnValue->SetLong(kInvalidProxyName);
      return PBX_OK;
   }
   else
   {
      proxyName = session->GetString(pn);
   }
}

Usage

When you have finished using the string, call the ReleaseString method to free the memory acquired.

See also

GetStringLength

NewString

ReleaseString

SetString

GetStringLength

Description

Returns the length of a string in bytes without the terminator.

Syntax

GetStringLength (pbstring string)

Argument

Description

string

The pbstring whose length is to be determined


Return value

pblong.

Examples

These statements set the value of a pblong variable to the length of a string:

pblong long_val;
pbstring str_val;
long_val = session-> GetStringLength( str_val );

See also

GetString

NewString

SetString

GetSuperClass

Description

Returns the ancestor class of the specified class, if any.

Syntax

GetSuperClass(pbclass cls)

Argument

Description

cls

A valid class handle for the descendant class


Return value

pbclass or 0 if the class has no ancestor.

Examples

These statements get the class of an object in the PBCallInfo structure, the ancestor class of that class, and then the name of the ancestor class:

pbclass cls, cls_parent;
LPCSTR clsname;

cls = Session-> GetClass(ci-> pArgs-> GetAt(0)->
   GetObject());
cls_parent = Session-> GetSuperClass(cls);
clsname = Session-> GetClassName(cls_parent);

See also

GetClass

GetClassName

GetSystemClass

Description

Returns the first system class that the input class inherits from.

Syntax

GetSystemClass (pbclass cls)

Argument

Description

cls

A descendant class whose ancestor system class is to be determined


Return value

pbclass or null on error.

See also

GetMethodID

GetSystemGroup

GetSystemGroup

Description

Returns a PowerBuilder internal system group.

Syntax

GetSystemGroup()

Return value

pbclass or null on error.

Usage

GetSystemGroup returns the PowerBuilder internal system group, which contains all the system types such as PowerObject, NonVisualObject, Structure, Window, CommandButton, and so on. You can use this system group to obtain a system class. You might need to call PowerScript functions in the PowerBuilder extension. To achieve this, you first need to get the pbclass that the PowerScript function class resides in. This code gets the PowerBuilder system function class:

pbgroup sysGroup = session->GetSystemGroup();
pbclass sysFuncClass = session->FindClass(sysGroup,
   "SystemFunctions");

After you get the system class, you can obtain the method ID of a PowerScript function by calling FindMatchingFunction, and then you can invoke the PowerScript function.

See also

FindMatchingFunction

GetSystemClass

GetTimeString

Description

Converts data in a pbtime object to a string.

Syntax

GetTimeString(pbtime time)

Argument

Description

time

The pbtime data object to be converted to a string.


Return value

LPCTSTR.

See also

NewString

ReleaseTimeString

SetString

HasExceptionThrown

Description

Checks for the existence of an exception that has been thrown but not cleared.

Syntax

HasExceptionThrown()

Return value

pbboolean.

Returns true if a PowerBuilder exception has been thrown but not cleared.

Examples

This example tests whether an exception has been thrown so it can be handled and cleared:

try
{
   session->InvokeObjectFunction(pbobj, mid, &ci);
   // Was PB exception thrown 
   if (session-> HasExceptionThrown())
   {
       // Handle PB exception
       session-> ClearException();
   }
}

See also

ClearException

GetException

ThrowException

HasPBVisualObject

Description

Determines whether any PowerBuilder windows, visible or hidden, are still in existence.

Syntax

HasPBVisualObject()

Return value

pbboolean.

Returns true if any PowerBuilder windows are still alive. If any windows that are not response windows are still alive, the PowerBuilder application returns immediately unless you manually add a message loop.

Examples

This example is similar to the example for RestartRequested, but it includes a call to HasPBVisualObject that opens a message loop if the return value is true:

PBXRESULT   PB_MyWinAppRunner::RunApplication()
{
    PBXRESULT res;
    pbboolean restart = FALSE;

    do    {
        res = StartApplication();
        if (res == PBX_OK)
        // Process message dispatch
        {
          if ( GetSession()->HasPBVisualObject() )
          {
            MSG msg;
            while ( GetMessage(&msg, 0, 0, 0) )
            {
              TranslateMessage(&msg);
              DispatchMessage(&msg);

              if ( !GetSession()->HasPBVisualObject() )
                  break;
            }
          }
        }
        else
            break;

        restart = GetSession()->RestartRequested();
        if (restart)
            RecreateSession();
    } while (restart);

    return CleanApplication();
}

Usage

RestartRequested and HasVisualPBObject are used in the implementation of the IPB_VM RunApplication function. You no longer need to use an external message loop to check for Windows messages when you call the RunApplication function as you did in versions of PBNI prior to PowerBuilder 10.5.

See also

RestartRequested

RunApplication

InitCallInfo

Description

Initializes the PBCallInfo structure.

Syntax

InitCallInfo(pbclass cls, pbmethodID mid, PBCallInfo *ci)

Argument

Description

cls

The pbclass containing the method

mid

The pbMethodID returned by GetMethodID

ci

A pointer to a preallocated PBCallInfo structure


Return value

PBXRESULT. Returns PBX_OK on success, and PBX_E_INVALID_ARGUMENT on failure.

Examples

This example shows the implementation of a TriggerEvent function in a visual class. It takes an event name as an argument, obtains the class and method ID needed to initialize the PBCallInfo structure, triggers the event, and frees the PBCallInfo structure:

void CVisualExt::TriggerEvent(LPCTSTR eventName)
{
   pbclass clz = d_session->GetClass(d_pbobj);
   pbmethodID mid = d_session->GetMethodID(clz,
      eventName, PBRT_EVENT, "I");

   PBCallInfo ci;
   d_session->InitCallInfo(clz, mid, &ci);
   d_session->TriggerEvent(d_pbobj, mid, &ci);
   d_session->FreeCallInfo(&ci);
}

Usage

On return, this method allocates enough space for the arguments, and then initializes the arguments and return value. You must set appropriate values in the PBCallInfo structure. Note that the structure itself must have been allocated before the call.

See also

FreeCallInfo

InvokeClassFunction

Description

Invokes system or user global functions.

Syntax

InvokeClassFunction(pbclass cls, pbmethodID mid, PBCallInfo *ci)

Argument

Description

cls

The class that contains the global function. If this is a system function, cls is obtained with GetSystemFunctionsClass; otherwise, it is obtained with FindGroup and FindClass, with the function name as the group/class name.

mid

The pbMethodID returned by GetMethodID.

ci

A pointer to a preallocated PBCallInfo structure.


Return value

PBXRESULT. Returns PBX_OK for success, or one of the following for failure:

PBX_E_INVALID_ARGUMENT

PBX_E_INVOKE_METHOD_INACCESSABLE

PBX_E_INVOKE_WRONG_NUM_ARGS

PBX_E_INVOKE_REFARG_ERROR

PBX_E_INVOKE_METHOD_AMBIGUOUS

PBX_E_INVOKE_FAILURE

PBX_E_INVOKE_FAILURE

Examples

This example gets the PowerBuilder system class and uses it to invoke the double function:

cls = session-> GetSystemClass();
mid = session-> GetMethodID (cls, "double", PBRT_FUNCTION, "DA");
session-> InitCallInfo(cls, mid, ci);
ci->pArgs -> GetAt(0) -> SetPBString(mystr);
session -> InvokeClassFunction(cls, mid, ci);

Usage

On return, this method allocates enough spaces for the arguments, and then initializes arguments and return value. You must set appropriate values in the PBCallInfo structure. Note that the structure itself must have been allocated before the call.

See also

InvokeObjectFunction

InvokeObjectFunction

Description

Invokes a class member method.

Syntax

InvokeObjectFunction(pbobject obj, pbmethodID mid, PBCallInfo *ci)

Argument

Description

obj

The pbobject containing the method

mid

The pbMethodID returned by GetMethodID

ci

A pointer to a preallocated PBCallInfo structure


Return value

PBXRESULT. Returns PBX_OK for success, or one of the following for failure:

PBX_E_INVALID_ARGUMENT

PBX_E_INVOKE_METHOD_INACCESSABLE

PBX_E_INVOKE_WRONG_NUM_ARGS

PBX_E_INVOKE_REFARG_ERROR

PBX_E_INVOKE_METHOD_AMBIGUOUS

PBX_E_INVOKE_FAILURE

PBX_E_INVOKE_FAILURE

Examples

This code invokes the DataWindow Update function and returns its integer return value:

pbclass cls;
pbmethodID mid;
PBCallInfo* ci = new PBCallInfo;
pbint ret_val;

cls = session->GetClass(dwobj);
mid = session->GetMethodID (cls, "Update", PBRT_FUNCTION, "I");
session->InitCallInfo(cls, mid, ci);

session->InvokeObjectFunction(dwobj, mid, ci);

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

See also

InvokeClassFunction

IsArrayItemNull

Description

Returns true if the array item contains a null value; otherwise it returns false.

Syntax

IsArrayItemNull( pbarray array, pblong dim[ ])

Argument

Description

array

A valid pbarray structure that you want to check for a null-valued array item.

dim

A pblong array to hold the indexes of each dimension of the array. The size of the array must equal the dimensions of array.


Return value

pbboolean.

See also

GetArrayItemType

Set<type>ArrayItem

SetArrayItemToNull

IsAutoInstantiate

Description

Returns true if the specified class is an autoinstantiated class; otherwise it returns false.

Syntax

IsAutoInstantiate(pbclass)

Argument

Description

cls

A valid class handle or structure


Return value

pbboolean.

IsFieldArray

Description

Returns true if the field of the specified object is an array; otherwise it returns false.

Syntax

IsFieldArray(pbclass cls, pbfield fid)

Argument

Description

cls

A valid class handle for the class whose field is to be accessed

fid

The field ID of the specified object


Return value

pbboolean.

Examples

This code tests whether the field identified by fid is an array, and if so, gets the array value:

fid = session->GetFieldID(cls, "arr_val");
if (session->IsFieldArray(cls, fid))
{
   arr_val=session->GetArrayField(myobj, fid, isNull);
...

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldNull

IsFieldObject

SetFieldToNull

Set<type>Field

IsFieldNull

Description

Returns true if the field of the specified object is a null value; otherwise it returns false.

Syntax

IsFieldNull(pbobject obj, pbfield fid)

Argument

Description

obj

A valid object handle for the object whose field is to be accessed

fid

The field ID of the specified object


Return value

pbboolean.

Examples

These statements test whether the field identified by fid is null:

fid = session -> GetFieldID(cls, "i_val");
if (session -> IsFieldNull(myobj, fid)) 

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldObject

SetFieldToNull

Set<type>Field

IsFieldObject

Description

Returns true if the field of the specified object is an object; otherwise it returns false.

Syntax

IsFieldObject(pbclass cls, pbfield fid)

Argument

Description

cls

A valid class handle for the class whose field is to be accessed

fid

The field ID of the specified object


Return value

pbboolean.

Examples

These statements test whether the field identified by fid is an object:

fid = session -> GetFieldID(cls, "obj_val");
if (session -> IsFieldObject(myobj, fid)) 

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

SetFieldToNull

Set<type>Field

IsGlobalVarArray

Description

Returns true if the global variable contains an array; otherwise it returns false.

Syntax

IsGlobalVarArray(pbfield fid)

Argument

Description

fid

The field ID of the global variable


Return value

pbboolean.

Examples

These statements test whether the field identified by fid is a global variable array:

fid = session -> GetGlobalVarID("arr_gvar");
if (session -> IsGlobalVarArray(fid))
{
   arr_val=session -> GetArrayGlobalVar(fid, isNull);
...

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarNull

IsGlobalVarObject

SetGlobalVarToNull

Set<type>GlobalVar

IsGlobalVarNull

Description

Returns true if the global variable contains a null value; otherwise it returns false.

Syntax

IsGlobalVarNull( pbfield fid)

Argument

Description

fid

The field ID of the global variable


Return value

pbboolean.

Examples

These statements test whether the field identified by fid is a global variable array:

fid = session -> GetGlobalVarID("arr_gvar");
if (session -> IsGlobalVarArray(fid))
{
   arr_val=session -> GetArrayGlobalVar(fid, isNull);
...

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarObject

SetGlobalVarToNull

Set<type>GlobalVar

IsGlobalVarObject

Description

Returns true if the global variable contains an object; otherwise it returns false.

Syntax

IsGlobalVarObject( pbfield fid)

Argument

Description

fid

The field ID of the global variable


Return value

pbboolean.

Examples

These statements test whether the field identified by fid is a global variable object. If it is, its value is set to another global variable object:

fid = session -> GetGlobalVarID("obj2_gvar");
   if (session -> IsGlobalVarObject(fid))
   {
      obj_val = session -> GetObjectGlobalVar(fid,
         isNull);
      cls = session -> GetClass(obj_val);
      fid = session -> GetFieldID(cls, "text");
      s_val = session -> GetStringField(obj_val, fid,
         isNull);
      mystr = session -> GetString(s_val);
      // Set the value of obj2_gvar to obj1_gvar
      fid = session -> GetGlobalVarID("obj1_gvar");
      session -> SetObjectGlobalVar(fid, obj_val);
   }

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarNull

SetGlobalVarToNull

Set<type>GlobalVar

IsNativeObject

Description

Determines whether a pbobject is an instance of a native class.

Syntax

IsNativeObject(pbobject obj)

Argument

Description

obj

A valid object handle


Return value

pbboolean.

Examples

The f_getrow function uses IsNativeObject to test whether extObj is a native class. If so, it gets the native interface and invokes the f_getrowcount function in the other class:

long f_getrow(IPB_Session* session, pbobject dwObj,
   pbobject extObj)
{
   long lRet;
   Imy_pbni* pImy_pbni = NULL;
   IPBX_NonVisualObject* pp=NULL;

    if (session -> IsNativeObject(extObj) )
   {
      pp = (IPBX_NonVisualObject*) session ->
         GetNativeInterface(extObj);
      pImy_pbni = static_cast<Imy_pbni*>(pp);
      lRet = pImy_pbni-> f_GetRowCount(session, dwObj);
   }
   return lRet;
}

Usage

Use this method in conjunction with GetNativeInterface to obtain a direct reference to the IPBX_UserObject associated with another native class, so that the class and its methods can be accessed directly.

See also

GetNativeInterface

IsSharedVarArray

Description

Returns true if the shared variable contains an array; otherwise it returns false.

Syntax

IsSharedVarArray(pbgroup group, pbfield fid)

Argument

Description

group

The group whose shared variable is to be accessed

fid

The field ID of the shared variable


Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

IsSharedVarNull

Description

Returns true if the shared variable contains a null value; otherwise it returns false.

Syntax

IsSharedVarNull(pbgroup group, pbfield fid)

Argument

Description

group

The group whose shared variable is to be accessed

fid

The field ID of the shared variable


Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

IsSharedVarObject

Description

Returns true if the shared variable contains an object; otherwise it returns false.

Syntax

IsSharedVarObject(pbgroup group, pbfield fid)

Argument

Description

group

The group whose shared variable is to be accessed

fid

The field ID of the shared variable


Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

Set<type>SharedVar

SetSharedVarToNull

NewBlob

Description

Creates a new blob and duplicates a buffer for the new blob data.

Syntax

NewBlob (const void* bin, pblong len)

Argument

Description

bin

A void pointer that points to the source buffer

len

The length in bytes of the data in the buffer


Return value

pbblob.

Examples

If the blob value in the PBCallInfo structure is null, this code creates a new blob value with four bytes in the pArguments array; otherwise, it sets the blob value in the pArguments array to the value in the PBCallInfo structure:

if (ci->pArgs->GetAt(i)->IsNull())
   pArguments[i].blob_val = 
      Session->NewBlob("null", 4);
else   pArguments[i].blob_val = 
      ci->pArgs->GetAt(i)->GetBlob();

Usage

The buffer containing the new blob data is freed when PopLocalFrame is called.

See also

PopLocalFrame

SetBlob

NewBoundedObjectArray

Description

Creates a bounded PowerBuilder object or structure array.

Syntax

NewBoundedObjectArray(pbclass cls, pbuint dimension, PBArrayInfo::ArrayBound* bounds)

Argument

Description

cls

A valid class handle of the type of PowerBuilder object or structure array to be created

dimension

A number greater than one that indicates the dimension of the array to be created

bounds

An array containing the upper and lower boundaries of the array to be created


Return value

pbarray or null on failure.

Examples

int size;
pbarray pbin_a;
PBArrayInfo* ai;
PBXRESULT ret;
pbclass cls;
pbgroup group;

size = sizeof(PBArrayInfo) +
   sizeof(PBArrayInfo::ArrayBound);
ai = (PBArrayInfo*)malloc(size);
ai-> bounds[0].upperBound=2;
ai-> bounds[0].lowerBound=1;
ai-> bounds[1].upperBound=2;
ai-> bounds[1].lowerBound=1;
ai-> numDimensions=2;

// Create new array pbin_a
group = session-> FindGroup("w_main", pbgroup_window);
if (group==NULL) 
   return;
cls = session->FindClass(group, "commandbutton");
if( cls==NULL) 
   return;
pbin_a = session->NewBoundedObjectArray(cls, 
   ai-> numDimensions, ai-> bounds); 

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

NewBoundedSimpleArray

Description

Creates a bounded simple data array.

Syntax

NewBoundedSimpleArray(pbuint type, pbuint dimension, PBArrayInfo::ArrayBound* bounds)

Argument

Description

type

An enumerated variable of type pbvalue_* indicating the type of simple unbounded array to be created

dimension

A number greater than one that indicates the dimension of the array to be created

bounds

An array containing the upper and lower boundaries of the array to be created


Return value

pbarray or null on failure.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

NewDate

Description

Creates a new pbdate data object.

Syntax

NewDate()

Return value

pbdate.

Examples

This example tests whether a date value exists, and, if it does not, it creates a new pbdate object and sets its value to the first day in January, 1900:

if (ci->pArgs->GetAt(0)->IsNull())
{
   pArguments[i].date_val = Session->NewDate();
   Session->SetDate(pArguments[i].date_val,
      1900,1,1); // Date: 1900-01-01
   isNull[i]=true;
}
else
{
   pArguments[i].date_val = 
      ci->pArgs->GetAt(i)->GetDate();
   isNull[i]=false;
}

Usage

The initial value is 1900-1-1.

See also

SetDate

SplitDate

NewDateTime

Description

Creates a new pbdatetime data object.

Syntax

NewDateTime()

Return value

pbdatetime.

Examples

This example tests whether a date/time value exists, and, if it does not, it creates a new pbdate object and sets its value to the beginning of January, 1900:

if (ci->pArgs->GetAt(i)->IsNull())
{
   pArguments[i].datetime_val=Session->NewDateTime();
   Session->SetDateTime(pArguments[i].datetime_val,
      1900, 1 , 1, 1, 1, 1); // Datetime:
                             // 1900-01-01 01:01:01
}
else
{
   pArguments[i].datetime_val = 
      ci->pArgs->GetAt(i)->GetDateTime();
}

Usage

The initial value is 1900-1-1 0:0:0.0.

See also

SetDateTime

SplitDateTime

NewDecimal

Description

Allocates resources for a new decimal data object.

Syntax

NewDecimal( )

Return value

pbdec or null on failure.

Examples

if (ci->pArgs->GetAt(i)->IsNull())
{
   pArguments[i].dec_val=Session->NewDecimal();
   Session->SetDecimal(pArguments[i].dec_val,"1.0");
}   else
   pArguments[i].dec_val = 
      ci->pArgs->GetAt(i)->GetDecimal();

See also

GetDecimalString

ReleaseDecimalString

SetDecimal

NewObject

Description

Creates a new object of the specified type.

Syntax

NewObject(pbclass cls)

Argument

Description

cls

The type of object or structure instance to be created


Return value

pbobject of the given class or structure.

Examples

pbclass cls;
pbobject ex;
pbgroup group;

group = session-> FindGroup ("user_exception", pbgroup_userobject);
if (group==NULL) 
   return;
cls = session->FindClass(group, "user_exception");
if (group==NULL) 
   return;
ex = session->NewObject(cls);

Usage

The returned object's life cycle is restricted to the current frame unless AddGlobalRef is called on the object.

See also

FindClass

FindGroup

NewProxyObject

Description

Creates a proxy for a remote object. The proxy is used to extend the network protocol in PowerBuilder.

Syntax

NewProxyObject(pbclass cls)

Argument

Description

cls

The type of object or structure instance to be created


Return value

pbproxyobject.

Examples

This example creates a new proxy object, creates a marshaler, and associates the marshaler with the proxy object:

pbproxyObject proxy = session->NewProxyObject(cls);
if (proxy == NULL)
{
   ci->returnValue->SetLong(kFailToCreateProxy);
   return PBX_OK;
}

// Create MyMarshaler
MyMarshaler* marshaler = new MyMarshaler (env, proxy, obj);

// Associate MyMarshaler with the proxy
session->SetMarshaler(proxy, marshaler);

ci->pArgs->GetAt(0)->SetObject(proxy);

ci->returnValue->SetLong(kSuccessful);

return PBX_OK;

See also

GetMarshaler

SetMarshaler

NewString

Description

Creates a new string.

Syntax

NewString(LPCTSTR)

Return value

pbstring.

Examples

pbclass cls;

cls = session->GetSystemFunctionsClass();
if( cls == NULL )
{
   ret_val = session->NewString("null"); 
   return ret_val;
}

Usage

The returned string is destroyed when PopLocalFrame is called.

See also

SetString

NewTime

Description

Creates a new pbtime data object.

Syntax

NewTime()

Return value

pbtime.

Examples

These statements split a time into hours, minutes, and seconds, and then use the resulting values to set the value of a new time object:

Session->SplitTime(ci.returnValue->GetTime(), &hh,
   &mm, &ss);
ret_val = Session-> NewTime();
Session-> SetTime(ret_val, hh, mm, ss);

Usage

The initial value is 0:0:0.0.

See also

SetTime

SplitTime

NewUnboundedObjectArray

Description

Creates an unbounded PowerBuilder object or structure data array.

Syntax

NewUnboundedObjectArray(pbclass cls)

Argument

Description

cls

A valid class handle of the type of PowerBuilder object or structure array to be created


Return value

pbarray or null on failure.

Usage

An unbounded array can have only one dimension, so no dimension information is needed.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

NewUnboundedSimpleArray

Description

Creates an unbounded simple data array.

Syntax

NewUnboundedSimpleArray(pbuint type)

Argument

Description

type

An enumerated variable of type pbvalue_* indicating the type of simple unbounded array to be created


Return value

pbarray or null on failure.

Examples

This example creates an unbounded simple data array of the type returned by the getDataType method, which returns a string of the form dt_type. Most of the case statements have been removed for the sake of brevity:

if (d_returnType.isArray())
   {
      returnValue.l = env->CallObjectMethodA(obj,
         mid, values.get());
      pbarray v;

      switch(d_returnType.getDataType())
      {
      case dt_boolean:
         v = session->NewUnboundedSimpleArray
            (pbvalue_boolean);
         break;

      case dt_short:
         v = session->NewUnboundedSimpleArray
            (pbvalue_int);
         break;
// CASE statements omitted
...
      default:
         v = session->NewUnboundedSimpleArray
            (pbvalue_any);
         break;
      }

      ci->returnValue->SetArray(v);

Usage

An unbounded array can have only one dimension, so no dimension information is needed.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

PopLocalFrame

Description

Pops the current local reference frame from the current native method stack frame, removing all local references to the objects added in that local frame. All the pbobject, pbstring, and pbdecimal variables created by calling NewDecimal, NewObject, or NewString in the current frame are destroyed automatically.

Syntax

PopLocalFrame()

Return value

None.

See also

AddLocalRef

PushLocalFrame

RemoveLocalRef

ProcessPBMessage

Description

Checks the PowerBuilder message queue and, if there is a message in the queue, attempts to process it.

Syntax

ProcessPBMessage()

Return value

pbboolean.

Returns true if a PowerBuilder message was processed, and false otherwise.

Examples

This message loop in a WinMain function processes a PowerBuilder message if a message has been received and an IPB session is running:

   try   {
       while (GetMessage(&msg, NULL, 0, 0)) 
       {
          TranslateMessage(&msg);
          DispatchMessage(&msg);

          // Call to ProcessPBMessage
          if (session)
             session->ProcessPBMessage();
      }

This overloaded WindowProc function in an MFC application processes a PowerBuilder message:

LRESULT CCallPBVCtrl::WindowProc(UINT message, 
   WPARAM wParam, LPARAM lParam)
{
   d_session->ProcessPBMessage();
   return CDialog::WindowProc(message, wParam, lParam);
}

Usage

Each time this function is called, it attempts to retrieve a message from the PowerBuilder message queue and process it. It is similar to the PowerBuilder Yield function; however, ProcessPBMessage processes only one message at a time, and it processes only PowerBuilder messages. The Yield function also processes Windows messages.

Use this function when PowerBuilder windows or visual controls are called from C++ applications or from extensions to ensure that events posted to the PowerBuilder message queue are processed.

If the function is not inserted in the C++ application in a way that results in it being called repeatedly, posted events are not processed in the PowerBuilder application.

For most applications, ProcessPBMessage can be inserted in a message loop in the WinMain function. If you use Microsoft Foundation Classes (MFC), you cannot modify the built-in message loop. To ensure that the ProcessPBMessage function is called repeatedly, you can overload the CWnd::WindowProc function and insert ProcessPBMessage into the overloaded function.

PushLocalFrame

Description

Pushes a local reference frame onto the current native method stack frame. A local frame is analogous to a scope in C++.

Syntax

PushLocalFrame()

Return value

None.

See also

PopLocalFrame

RemoveLocalRef

Release

Description

Releases the current IPB_Session. The IPB_Session object becomes invalid after the call.

Syntax

Release()

Return value

None.

Examples

This example shows a call to Release. The example checks whether there is a valid session object before attempting to release it:

if (pIPB_ObjectFactory)
{
   pIPB_ObjectFactory->Release();
   pIPB_ObjectFactory = NULL;
}

ReleaseArrayInfo

Description

Releases memory returned by GetArrayInfo.

Syntax

ReleaseArrayInfo(PBArrayInfo* pbarrayinfo)

Argument

Description

pbarrayinfo

A valid PBArrayInfo handle


Return value

PBXRESULT. PBX_OK for success.

Examples

This example shows how ReleaseArrayInfo should be called when memory allocated by GetArrayInfo is no longer needed:

PBArrayInfo* ai; 
...
session->ReleaseArrayInfo(ai);

Usage

If the array is an unbounded array, the bounds information in PBArrayInfo is undetermined.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

ReleaseDateString

Description

Frees the memory acquired using GetDateString.

Syntax

ReleaseDateString(LPCTSTR string)

Argument

Description

string

The string to be released from memory


Return value

None.

See also

GetDateString

ReleaseDateTimeString

Description

Frees the memory acquired using GetDateTimeString.

Syntax

ReleaseDateTimeString(LPCTSTR string)

Argument

Description

string

The string to be released from memory


Return value

None.

See also

GetDateTimeString

ReleaseDecimalString

Description

Frees the memory acquired using GetDecimalString.

Syntax

ReleaseDecimalString(LPCTSTR string)

Argument

Description

string

The string to be released from memory


Return value

None.

See also

GetDecimalString

ReleaseResultSetAccessor

Description

Releases the pointer obtained using GetResultSetAccessor.

Syntax

ReleaseResultSetAccessor (IPB_ResultSetAccessor* rs)

Argument

Description

rs

A pointer to the IPB_ResultSetAccessor object to be released


Return value

None.

Examples

This statement releases the IPB_ResultSetAccessor object rsa:

Session->ReleaseResultSetAccessor(rsa);

Usage

When you call ReleaseResultSetAccessor, the Release function of the IPB_ResultSetAccessor interface is called on the rs argument to release the interface pointer.

See also

CreateResultSet

GetResultSetAccessor

ReleaseString

Description

Frees the memory acquired using GetString, GetClassName, GetFieldName, or GetEnumItemName.

Syntax

ReleaseString(LPCTSTR string)

Argument

Description

string

The string to be released from memory


Return value

None.

Examples

The following example gets a pointer to each of two strings passed in as arguments, concatenates them in a new string, then releases the memory used by the original strings:

pbstring psppcls:: f_add_string(IPB_Session* session, pbstring arg1, pbstring arg2)
{
   LPCTSTR pStr1,pStr2;
   TCHAR tmp[100];
   pbstring ret;

   pStr1=session-> GetString(arg1);
   pStr2=session-> GetString(arg2);
   _tcscpy(tmp,pStr1);
   _tcscat(tmp,pStr2);
   ret = session -> NewString(tmp);
   session-> ReleaseString(pStr1);
   session-> ReleaseString(pStr2);

   return ret ;

}

Usage

Do not use this function to release a string obtained using GetDateString, GetTimeString, GetDateTimeString, or GetDecimalString. Each of these Get methods has a corresponding Release method.

See also

GetClassName

GetEnumItemName

GetFieldName

GetString

ReleaseTimeString

Description

Frees the memory acquired using GetString.

Syntax

ReleaseTimeString(LPCTSTR string)

Argument

Description

string

The string to be released from memory


Return value

None.

See also

GetTimeString

ReleaseValue

Description

Frees the IPB_Value acquired using AcquireValue or AcquireArrayItemValue.

Syntax

ReleaseValue(IPB_Value* value)

Argument

Description

value

The string to be released from memory


Return value

None.

Examples

The AcquireValue method is used to obtain a message argument value. Later, when the value is no longer needed, it is released using ReleaseValue to avoid memory leaks:

// Acquire a value
MessageArg = session->AcquireValue
   ( ci->pArgs->GetAt(0) );
pbstring pbMessage = MessageArg->GetString() ;
Message = (LPSTR)session->GetString(pbMessage) ;
...
// Cleanup phase
if (MessageArg)
{
   Session->ReleaseValue ( MessageArg ) ;
}

Usage

When you no longer need the data acquired using the AcquireValue or AcquireArrayItemValue method, you must call the ReleaseValue method to free the data. Failing to do so causes a memory leak.

Warning

Do not use ReleaseValue to release a value that was not acquired using AcquireValue or AcquireArrayItemValue. If you do, the PowerBuilder VM might crash.

See also

AcquireArrayItemValue

AcquireValue

RemoveGlobalRef

Description

Removes a global reference to the specified PowerBuilder object.

Syntax

RemoveGlobalRef (pbobject  obj)

Argument

Description

obj

A valid PowerBuilder object handle


Return value

None.

Examples

void MyPBNIClass::reference()
{
   d_session->AddGlobalRef(d_pbobject);
}

void MyPBNIClass::unreference()
{
   if(d_pbobject != NULL)
      d_session -> RemoveGlobalRef(d_pbobject);
}

See also

AddGlobalRef

RemoveLocalRef

Description

Removes a local reference to the specified PowerBuilder object.

Syntax

RemoveLocalRef (pbobject  obj)

Argument

Description

obj

A valid PowerBuilder object handle


Return value

None.

See also

AddLocalRef

PopLocalFrame

PushLocalFrame

RemoveProp

Description

Removes the specified variable from the list of properties of the current IPB session. You must free the memory to which the property points.

Syntax

RemoveProp(LPCTSTR name)

Argument

Description

name

The name of the variable to be removed


Return value

None.

Examples

These statements remove prop_name from the list of variables associated with the session and delete the pointer created to point to the variables value:

session -> RemoveProp(prop_name);
delete SetValue;

Usage

SetProp enables you to use a variable value throughout an IPB session. Use RemoveProp to remove the variable from the list of variables associated with the session when it is no longer needed. You must also free the memory associated with the variable.

See also

GetProp

SetProp

RestartRequested

Description

Determines whether the PowerBuilder system function Restart has been called.

Syntax

HasPBVisualObject()

Return value

pbboolean.

Returns true when the PowerBuilder system function Restart is called. When RestartRequested returns true, you should destroy the existing IPB_Session object and create a new one to restart the application.

Examples

In the following example, StartApplication, RecreateSession, and CleanApplication are functions of the PB_MyConsoleAppRunner class. StartApplication is similar to the IP_VM RunApplication function, but it uses an existing session. RecreateSession releases the current session and creates a new one. CleanApplication triggers the application's Close event and releases resources. In the example, RestartRequested is called in a DO loop to test whether the PowerBuilder Restart function has been called. If it has, the RecreateSession function is called:

PBXRESULT   PB_MyConsoleAppRunner::RunApplication()
{
    PBXRESULT res;
    pbboolean restart = FALSE;

    do
    {
        res = StartApplication();
        if (res != PBX_OK)
            break;

        restart = GetSession()->RestartRequested();
        if (restart)
            RecreateSession();

    } while (restart);

    return CleanApplication();
}

Usage

RestartRequested and HasVisualPBObject are used in the implementation of the IPB_VM RunApplication function. You no longer need to use an external message loop to check for Windows messages when you call the RunApplication function as you did in versions of PBNI prior to PowerBuilder 10.5.

See also

HasPBVisualObject

RunApplication

Set<type>ArrayItem

Description

Assigns a value to an array item of a specific type.

Syntax

SetBlobArrayItem ( pbarray array, pblong dim[ ], pbblob value ) 
SetBoolArrayItem ( pbarray array, pblong dim[ ], pbboolean value ) 
SetByteArrayItem ( pbarray array, pblong dim[ ], pbbyte value ) 
SetCharArrayItem ( pbarray array, pblong dim[ ], pbchar value ) 
SetDateArrayItem ( pbarray array, pblong dim[ ], pbdate value ) 
SetDateTimeArrayItem ( pbarray array, pblong dim[ ], pbdatetime value ) 
SetDecArrayItem ( pbarray array, pblong dim[ ], pbdec value ) 
SetDoubleArrayItem ( pbarray array, pblong dim[ ], pbdouble value ) 
SetIntArrayItem ( pbarray array, pblong dim[ ], pbint value ) 
SetLongArrayItem ( pbarray array, pblong dim[ ], pblong value ) 
SetLongLongArrayItem ( pbarray array, pblonglong dim[ ], pblong value ) 
SetObjectArrayItem ( pbarray array, pblong dim[ ], pbobject obj ) 
SetPBStringArrayItem ( pbarray array, pblong dim[ ], pbstring value ) 
SetRealArrayItem ( pbarray array, pblong dim[ ], pbreal value ) 
SetStringArrayItem ( pbarray array, pblong dim[ ], LPCTSTR value ) 
SetTimeArrayItem ( pbarray array, pblong dim[ ], pbtime value ) 
SetUintArrayItem ( pbarray array, pblong dim[ ], pbuint value ) 
SetUlongArrayItem ( pbarray array, pblong dim[ ], pbulong value ) 

Argument

Description

array

A valid pbarray handle.

dim

A pblong array to hold indexes of each dimension. The number of dimensions must equal the number of dimensions of the array.

value

The new value of the array item.


Return value

PBXRESULT. PBX_OK for success.

If the index exceeds the bounds of a bounded array, it returns PBX_E_ARRAY_INDEX_OUTOF_BOUNDS.

If the data passed in does not match the datatype of the array, it returns PBX_E_MISMATCHED_DATA_TYPE.

Examples

This example creates a new unbounded simple array. In the FOR loop, application-specific code (not shown here) gets array values, which are then added to the array using SetPBStringArrayItem:

pblong         dim[1];
char *         cstr;
pbuint   numDimensions = 1;
PBArrayInfo::ArrayBound bound;

bound.lowerBound = 1;
bound.upperBound = size;
d_pbarray = d_session->NewBoundedSimpleArray
    (pbvalue_string, numDimensions, &bound);

for (int i = 1; i <= size; i++ )
{
   dim[0] = i;
      // add application-specific code here to
   // get array value
   pbstring pValue = d_session->NewString(cstr);
   d_session->SetPBStringArrayItem(d_pbarray, dim, pValue);

   delete [] cstr;
}
pbv.SetArray(d_pbarray);

Usage

This method assigns the IPB_Value pointed to by the value argument to the array item in the same way that the IPB_Value Set<type> method sets a value.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayItemType

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>Field

Description

A set of methods that set a new value in an instance field of an object.

Syntax

SetArrayField ( pbobject obj, pbfieldID fid, pbarray value ) 
SetBlobField ( pbobject obj, pbfieldID fid, pbblob value ) 
SetBoolField ( pbobject obj, pbfieldID fid, pbboolean value ) 
SetByteField ( pbobject obj, pbfieldID fid, pbbyte value ) 
SetCharField ( pbobject obj, pbfieldID fid, pbchar value ) 
SetDateField ( pbobject obj, pbfieldID fid, pbdate value ) 
SetDateTimeField ( pbobject obj, pbfieldID fid, pbdatetime value ) 
SetDecField ( pbobject obj, pbfieldID fid, pbdec value ) 
SetDoubleField ( pbobject obj, pbfieldID fid, pbdouble value ) 
SetIntField ( pbobject obj, pbfieldID fid, pbint value ) 
SetLongField ( pbobject obj, pbfieldID fid, pblong value ) 
SetLongLongField ( pbobject obj, pbfieldID fid, pblonglong value ) 
SetObjectField ( pbobject obj, pbfieldID fid, pbobject value ) 
SetPBStringField ( pbobject obj, pbfieldID fid, pbstring value ) 
SetRealField ( pbobject obj, pbfieldID fid, pbreal value ) 
SetStringField ( pbobject obj, pbfieldID fid, LPCTSTR value ) 
SetTimeField ( pbobject obj, pbfieldID fid, pbtime value ) 
SetUintField ( pbobject obj, pbfieldID fid, pbuint value ) 
SetUlongField ( pbobject obj, pbfieldID fid, pbulong value ) 

Argument

Description

obj

The handle of the object whose field is to be accessed

fid

The field ID of the specified object

value

The value to be set


Return value

PBX_RESULT.

Examples

These statements set a new string value in a string field:

pbstring str = session->NewString(d_message.c_str());
if (str != NULL)
   session->SetPBStringField(d_pbobj, d_fidMsg, str);

Usage

When you change any visual property of a PowerBuilder object by calling Set<type>field functions, the property is changed but the property is not refreshed in the graphical user interface. UpdateField refreshes the visual properties of PowerBuilder objects. You must call UpdateField explicitly when changing any visual property with the Set<type>field functions.

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

SetFieldToNull

UpdateField

Set<type>GlobalVar

Description

A set of methods that set the value of a global variable of a specific datatype.

Syntax

SetArrayGlobalVar ( pbfieldID fid, pbarray value ) 
SetBlobGlobalVar ( pbfieldID fid, pbblob value ) 
SetBoolGlobalVar ( pbfieldID fid, pbboolean value ) 
SetByteGlobalVar ( pbfieldID fid, pbbyte value ) 
SetCharGlobalVar ( pbfieldID fid, pbchar value ) 
SetDateGlobalVar ( pbfieldID fid, pbdate value ) 
SetDateTimeGlobalVar ( pbfieldID fid, pbdatetime value ) 
SetDecGlobalVar ( pbfieldID fid, pbdec value ) 
SetDoubleGlobalVar ( pbfieldID fid, pbdouble value ) 
SetIntGlobalVar ( pbfieldID fid, pbint value ) 
SetLongGlobalVar( pbfieldID fid, pblong value ) 
SetLongLongGlobalVar( pbfieldID fid, pblonglong value ) 
SetObjectGlobalVar ( pbfieldID fid, pbobject value ) 
SetPBStringGlobalVar ( pbfieldID fid, pbstring value ) 
SetRealGlobalVar ( pbfieldID fid, pbreal value ) 
SetStringGlobalVar ( pbfieldID fid, LPCTSTR value ) 
SetTimeGlobalVar ( pbfieldID fid, pbtime value ) 
SetUintGlobalVar ( pbfieldID fid, pbuint value ) 
SetUlongGlobalVar ( pbfieldID fid, pbulong value ) 

Argument

Description

fid

The field ID of the global variable

value

The value to be set


Return value

PBX_RESULT.

Examples

This shows how to add 1 to the value of a global variable:

fid = session -> GetGlobalVarID("l_gvar");
l_val = session -> GetLongGlobalVar(fid, isNull);
session -> SetLongGlobalVar(fid, l_val + 1);

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarObject

SetGlobalVarToNull

Set<type>SharedVar

Description

A set of methods that set the value of a shared variable of a specific datatype.

Syntax

SetArraySharedVar ( pbgroup group, pbfieldID fid, pbarray value ) 
SetBlobSharedVar ( pbgroup group, pbfieldID fid, pbblob value ) 
SetBoolSharedVar ( pbgroup group, pbfieldID fid, pbboolean value ) 
SetByteSharedVar ( pbgroup group, pbfieldID fid, pbbyte value ) 
SetCharSharedVar ( pbgroup group, pbfieldID fid, pbchar value ) 
SetDateSharedVar ( pbgroup group, pbfieldID fid, pbdate value ) 
SetDateTimeSharedVar ( pbgroup group, pbfieldID fid, pbdatetime value ) 
SetDecSharedVar ( pbgroup group, pbfieldID fid, pbdec value ) 
SetDoubleSharedVar ( pbgroup group, pbfieldID fid, pbdouble value ) 
SetIntSharedVar ( pbgroup group, pbfieldID fid, pbint value ) 
SetLongSharedVar( pbgroup group, pbfieldID fid, pblong value ) 
SetLongLongSharedVar( pbgroup group, pbfieldID fid, pblonglong value ) 
SetObjectSharedVar ( pbgroup group, pbfieldID fid, pbobject value ) 
SetPBStringSharedVar ( pbgroup group, pbfieldID fid, pbstring value ) 
SetRealSharedVar ( pbgroup group, pbfieldID fid, pbreal value ) 
SetStringSharedVar ( pbgroup group, pbfieldID fid, LPCTSTR value ) 
SetTimeSharedVar ( pbgroup group, pbfieldID fid, pbtime value ) 
SetUintSharedVar ( pbgroup group, pbfieldID fid, pbuint value ) 
SetUlongSharedVar ( pbgroup group, pbfieldID fid, pbulong value ) 

Argument

Description

group

The group whose shared variable is to be accessed

fid

The field ID of the shared variable

value

The value to be set


Return value

PBX_RESULT.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

SetSharedVarToNull

SetArrayItemToNull

Description

Sets the value of an array item to a null value.

Syntax

SetArrayItemToNull( pbarray array, pblong dim[ ])

Argument

Description

array

A valid pbarray structure in which you want to set an array item to null.

dim

A pblong array to hold the indexes of each dimension of the array. The size of the array must equal the dimensions of array.


Return value

pbboolean.

See also

IsArrayItemNull

SetArrayItemValue

Description

Sets the value of an array item to the value of an IPB_Value.

Syntax

SetArrayItemValue( pbarray array, pblong dim[ ], IPB_Value* src)

Argument

Description

array

A valid pbarray structure in which you want to set an array item to null.

dim

A pblong array to hold the indexes of each dimension of the array. The size of the array must equal the dimensions of array.

src

The value to which the array item is to be changed.


Return value

None.

Examples

This code sets the value of each item in an array:

for( i=1; i <= bound; i++)
{
   dim[0]= i;
   ipv = Session -> AcquireArrayItemValue(refArg, dim);
   Session -> SetArrayItemValue(*i_array, dim, ipv);
   Session -> ReleaseValue(ipv);
}

Usage

The SetArrayItemValue method does not verify that the datatype of the replacement value matches the datatype of the original value.

See also

AcquireArrayItemValue

ReleaseValue

SetArrayItemToNull

SetValue

SetBlob

Description

Destroys the existing data in a blob and copies data into it from a buffer.

Syntax

SetBlob (pbblob blb, const void* bin, pblong len)

Argument

Description

blb

A valid pbblob object whose value is to be reset

bin

A pointer to the source buffer

len

The length in bytes of the data in the buffer


Return value

PBXRESULT. Returns PBX_OK for success or PBX_E_INVALID_ARGUMENT if the new blob value is invalid; otherwise, returns PBX_E_OUTOF_MEMORY.

Usage

A deep copy is performed. The existing value is destroyed first, and then the contents of the bin argument are copied into a new value.

See also

NewBlob

SetDate

Description

Resets the value of the specified pbdate object.

Syntax

SetDate (pbdate date, pbint year, pbint month, pbint day)

Argument

Description

date

The pbdate object to be reset

year

A year in the range 1000 to 3000

month

A month in the range 1 to 12

day

A day in the range 1 to 31


Return value

PBX_RESULT. PBX_OK for success or PBX_E_INVALID_ARGUMENT if the new date is invalid.

Examples

This example sets the date to March 12, 1938:

session->SetDate(date_val, 1938, 3, 12);

Usage

If the parameters are invalid, the date is reset to 1900-1-1.

See also

NewDate

SplitDate

SetDateTime

Description

Resets the value of the specified pbdatetime object.

Syntax

SetDate (pbdatetime dt, pbint year, pbint month, pbint day, pbint hour, pbint minute, pbdouble second)

Argument

Description

dt

The pbdatetime object to be reset

year

A year in the range 1000 to 3000

month

A month in the range 1 to 12

day

A day in the range 1 to 31

hour

An hour in the range 0 to 23

minute

A minute in the range 0 to 59

second

A second in the range 0 to 59.999999


Return value

PBX_RESULT. PBX_OK for success or PBX_E_INVALID_ARGUMENT if the new datetime is invalid.

Examples

This example sets the datetime value to August 19, 1982 at 10:30:45.10:

session->SetDate(date_val, 1982, 8, 19, 10, 30, 45.1);

Usage

If the parameters are invalid, the datetime value is reset to 1900-1-1 0:0:0.0.

See also

NewDateTime

SplitDateTime

SetDecimal

Description

Sets the value of a decimal variable to decimal data in a string.

Syntax

SetDecimal(pbdec dec, LPCTSTR dec_str)

Argument

Description

dec

The decimal data object to be set

dec_str

The string containing the data to be converted to a decimal


Return value

PBXRESULT. PBX_OK for success.

Examples

This example uses the IPB_Session SetDecimal method to set the value of a variable of type pbdec, then uses the IPB_Value SetDecimal method to set the return value in the PBCallInfo structure:

pbdec pbdecRet = NULL;
LPTSTR  lpDecValueToReturn = NULL;

...
pbdecRet = session -> NewDecimal();
session -> SetDecimal( pbdecRet,
    (LPCTSTR)lpDecValueToReturn);
ci -> returnValue -> SetDecimal(pbdecRet);

Usage

If the string contains invalid data, the decimal value is set to 0.0.

See also

GetDecimalString

NewDecimal

ReleaseDecimalString

SetFieldToNull

Description

Sets the value of the specified field to null.

Syntax

SetFieldToNull(pbobject obj, pbfield fid)

Argument

Description

obj

A valid object handle

fid

The field ID of the specified object


Return value

None.

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

Set<type>Field

SetGlobalVarToNull

Description

Sets the value of the specified global variable to null.

Syntax

SetGlobalVarToNull(pbobject obj, pbfield fid)

Argument

Description

fid

The field ID of the global variable


Return value

None.

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarNull

IsGlobalVarObject

Set<type>GlobalVar

SetMarshaler

Description

Sets a marshaler that will be used to invoke remote methods and convert PowerBuilder data formats to the user's communication protocol.

Syntax

SetMarshaler(pbproxyObject obj, IPBX_Marshaler* marshaler)

Argument

Description

obj

An object of type pbproxyObject to be used as a proxy for a remote object that was created using NewProxyObject

marshaler

A class inherited from IPBX_Marshaler


Return value

None.

Examples

This example creates a JavaMarshaler class and associates it with a proxy object:

// Create JavaMarshaler
JavaMarshaler* marshaler = new JavaMarshaler (env, proxy, jobj);

// Associate the JavaMarshaler with the PB proxy
session->SetMarshaler(proxy, marshaler);

ci->pArgs->GetAt(0)->SetObject(proxy);

ci->returnValue->SetLong(kSuccessful);
return PBX_OK;

Usage

The SetMarshaler function associates an object of type IPBX_Marshaler with a PBProxy object. It is possible to associate multiple marshaler objects with a single proxy object. It is also possible to associate one marshaler object with multiple proxy objects. Neither of these is good coding practice and should be avoided.

Before calling SetMarshaler, you can call the IPB_Session GetMarshaler function to obtain an existing marshaler object associated with a given proxy object, and then destroy the existing marshaler object before associating a new marshaler with the proxy.

When a proxy object is destroyed, it calls the associated marshaler object's Destroy method. If multiple proxy objects are associated with a single marshaler object, you need to implement some form of reference counting. Otherwise, the marshaler object is destroyed when the first associated proxy object is destroyed, and subsequent calls to the marshaler object's Destroy method, when other associated proxy objects are destroyed, will throw exceptions.

To avoid these issues, there should be a one-to-one relationship between marshaler and proxy objects.

See also

GetMarshaler

GetMethodID

SetProp

Description

Adds a new variable to the list of properties of the current session or changes the value of an existing variable.

Syntax

SetProp(LPCTSTR name, void* data)

Argument

Description

name

The name of the property to be set

data

A pointer to the data buffer where the variable's value resides


Return value

None.

Examples

In this example, the native class has two functions. This is their description passed in the PBX_GetDescription function:

"subroutine f_setprop(int a)\n"
"function int f_getprop()\n"

The functions are associated with these enumerated values:

enum MethodIDs
{
   mid_SetProp = 0,
   mid_GetProp = 1
};

When the f_setprop function is called from PowerBuilder, the following code sets the value of the pointer SetVal to the integer value passed in by f_setprop, then registers that value in the session with the property name prop_name:

int* SetVal = new int;

if (mid == mid_SetProp)
{
   *SetValue = ci -> pArgs -> GetAt(0) -> GetInt();
   session -> SetProp(prop_name, SetVal);
}

When the f_getprop function is called, the following code uses GetProp to set the GetValue pointer to point to the value associated with prop_name, and then sets the return value to *GetValue:

if (mid == mid_GetProp)
{
   int* GetVal;
   GetValue = (int *)session -> GetProp(prop_name);
   ci -> returnValue -> SetInt(*GetVal);
}

Usage

SetProp enables you to use a variable value throughout an IPB session without using a global variable, which is susceptible to namespace conflicts with other sessions. SetProp is one of a set of three functions:

  • Use SetProp to register a new variable with the session or to change the value of an existing variable.

  • Use GetProp to access the variable.

  • Use RemoveProp to remove the variable from the list of variables associated with the session when it is no longer needed.

Suppose you want to throw an exception from within a PBNI extension and the exception itself is also defined by the PBNI extension. You call the IPB_Session NewObject function to create an instance of the exception, causing the PBX_CreateNonVisualObject function to be called.

One way to set the value of the fields of the exception before the function returns in a thread-safe manner is to create a new object or structure to hold the exception information before calling NewObject. You can call SetProp to store the structure or the object in the current IPB_Session. When PBX_CreateNonVisualObject is called, you can call GetProp to get the structure or object to obtain the exception information, then call RemoveProp to remove the data you stored in the current session.

See also

GetProp

RemoveProp

SetSharedVarToNull

Description

Sets the value of the specified shared variable to null.

Syntax

SetSharedVarToNull(pbgroup group, pbfield fid)

Argument

Description

group

The group to which the shared variable belongs

fid

The field ID of the shared variable


Return value

None.

Examples

This example tests the IsSharedVarNull and SetSharedVarToNull functions:

curGroup = session -> GetCurrGroup();
cls = session -> GetClass(myobj);

fid = session -> GetSharedVarID(curGroup, "i_svar");
if (session -> IsSharedVarNull(curGroup, fid))
   session -> SetIntSharedVar(curGroup, fid, 1);
else
   session -> SetSharedVarToNull(curGroup, fid);

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetString

Description

Frees an existing string and assigns a new string value to it by performing a deep copy.

Syntax

SetString (pbstring string, LPCTSTR src)

Argument

Description

string

A valid pbstring variable whose value is to be replaced

src

The string to be assigned to string


Return value

PBXRESULT. Returns PBX_OK for success or PBX_E_INVALID_ARGUMENT if the new string value is invalid; otherwise, returns PBX_E_OUTOF_MEMORY.

Examples

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

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);

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("");
Session -> SetPBString(ret_val, Session->GetString
               (ci->returnValue->GetString()));
Session -> FreeCallInfo(ci);
delete ci;
return ret_val;

Usage

A deep copy is performed. The existing value is destroyed first, and then the contents of the src argument are copied into a new value.

See also

NewString

SetTime

Description

Resets the value of the specified pbtime object.

Syntax

SetTime (pbtime time, pbint hour, pbint minute, pbdouble second)

Argument

Description

time

The pbtime object to be reset

hour

An hour in the range 0 to 23

minute

A minute in the range 0 to 59

second

A second in the range 0 to 59.999999


Return value

PBX_RESULT. PBX_OK for success or PBX_E_INVALID_ARGUMENT if the new time is invalid.

Examples

This code puts a new time with the value 01:01:01 into the time_val property of the pArguments array if the value in the PBCallInfo structure is null. Otherwise it sets time_val to the time in the PBCallInfo structure:

if (ci->pArgs->GetAt(i)->IsNull())
{
   pArguments[i].time_val = Session-> NewTime();
  Session->SetTime(pArguments[i].time_val, 1, 1, 1); 
                                    // Time: 01:01:01
}
else
{
   pArguments[i].time_val = 
      ci-> pArgs-> GetAt(i)-> GetTime();
}

Usage

If the parameters are invalid, the time is reset to 0:0:0.0.

See also

NewTime

SplitTime

SetValue

Description

Sets the value of one IPB_Value object to the value of another IPB_Value object.

Syntax

SetValue( IPB_Value* dest, IPB_Value* src)

Argument

Description

dest

The value to be replaced

src

The value to which dest is to be changed


Return value

None.

Examples

These statements set the return value in the PBCallInfo structure ci to the value IPBValue_ret, then release the IBPValue_ret structure:

Session -> SetValue(ci -> returnValue, IPBValue_ret);
Session -> ReleaseValue(IPBValue_ret);

Usage

Unlike the IPB_Value Set<type> methods, the SetValue method does not verify that the datatype of the replacement value matches the datatype of the original value. The original value is freed and a new value is cloned from the src value. Use this method if you want to swap two different IPB_Value objects that have different types.

See also

AcquireValue

ReleaseValue

SplitDate

Description

Splits the specified pbdate object into a year, month, and day.

Syntax

SplitDate (pbdate date, pbint *year, pbint *month, pbint *day)

Argument

Description

date

The pbdate object to be split

year

A year in the range 1000 to 3000

month

A month in the range 1 to 12

day

A day in the range 1 to 31


Return value

PBX_RESULT. PBX_OK for success.

Examples

This statement splits the date in the first value in the PBCallInfo structure:

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

See also

NewDate

SetDate, SplitDateTime

SplitDateTime

Description

Splits the specified pbdatetime object into a year, month, day, hour, minute, and second.

Syntax

SplitDateTime(pbdatetime dt, pbint *year, pbint *month, pbint *day, pbint *hour, pbint *minute, pbdouble *second)

Argument

Description

dt

The pbdatetime object to be split

year

A year in the range 1000 to 3000

month

A month in the range 1 to 12

day

A day in the range 1 to 31

hour

An hour in the range 0 to 23

minute

A minute in the range 0 to 59

second

A second in the range 0 to 59.999999


Return value

PBX_RESULT. PBX_OK for success.

See also

NewDateTime

SetDateTime

SplitDate

SplitTime

SplitTime

Description

Splits the specified time object into an hour, minute, and second.

Syntax

SplitTime(pbtime time, pbint *hour, pbint *minute, pbdouble *second)

Argument

Description

time

The pbtime object to be split

hour

An hour in the range 0 to 23

minute

A minute in the range 0 to 59

second

A second in the range 0 to 59.999999


Return value

PBX_RESULT. PBX_OK for success.

Examples

These statements split a time into hours, minutes, and seconds, and then use the resulting values to set the value of a new time object:

Session->SplitTime(ci.returnValue->GetTime(), &hh,
   &mm, &ss);
ret_val = Session-> NewTime();
Session-> SetTime(ret_val, hh, mm, ss);

See also

NewTime

SetTime

ThrowException

Description

Throws a PowerBuilder exception or inherited exception, and replaces the existing exception if there is one.

Syntax

ThrowException (pbobject ex)

Argument

Description

ex

The exception to be thrown. The exception must first be created with NewObject.


Return value

None.

Examples

This code creates a new exception object in the class user_exception_pspp, invokes its SetMessage function, and throws the exception:

pbclass cls;
pbmethodID mid;
pbobject ex;
pbgroup group;
PBCallInfo* ci = new PBCallInfo;

//  Throw exception 
group = session-> FindGroup("user_exception_pspp",
   pbgroup_userobject);
if (group==NULL) 
   return;
cls = session->FindClass(group, "user_exception_pspp");
if (group==NULL) 
   return;
ex = session -> NewObject(cls);
mid = session-> GetMethodID(cls,
   "setmessage", PBRT_FUNCTION, "QS");
session-> InitCallInfo(cls,mid,ci);

ci-> pArgs[0].SetPBString(session, "Test exception");

session -> InvokeObjectFunction(ex,mid,ci);
session -> ThrowException(ex);
if (!ThrowToPB)
   session -> ClearException();
session -> FreeCallInfo(ci);
delete ci;
return;

See also

ClearException

GetException

HasExceptionThrown

TriggerEvent

Description

Triggers a PowerBuilder event.

Syntax

TriggerEvent(pbobject obj, pbmethodID mid, PBCallInfo *ci)

Argument

Description

obj

The pbobject containing the method

mid

The pbMethodID returned by GetMethodID

ci

A pointer to a preallocated PBCallInfo structure


Return value

PBXRESULT. Returns PBX_OK for success, or one of the following for failure:

PBX_E_INVALID_ARGUMENT

PBX_E_INVOKE_METHOD_INACCESSABLE

PBX_E_INVOKE_WRONG_NUM_ARGS

PBX_E_INVOKE_REFARG_ERROR

PBX_E_INVOKE_METHOD_AMBIGUOUS

PBX_E_INVOKE_FAILURE

Examples

This code triggers the clicked event on a DataWindow object:

cls = session->GetClass(dwobj);
mid = session->GetMethodID
   (cls, "clicked", PBRT_EVENT, "LIILCdwobject.");
session->InitCallInfo(cls, mid, ci);
session->TriggerEvent(dwobj, mid, ci);
...

See also

GetClass

GetMethodID

UpdateField

Description

Refreshes a visual property of a PowerBuilder object.

Syntax

UpdateField(pbobject obj, pbfieldID fid)

Argument

Description

obj

The pbobject whose user interface property needs to be changed

fid

The field ID of the object


Return value

PBXRESULT. Returns success or failure.

Examples

This function changes the title of a DataWindow control:

void CallBack::f_newtitle(IPB_Session* session, pbstring str_val, pbobject dwobj)
{

   pbclass cls;
   pbfieldID fid;
   cls=session->GetClass(dwobj);
   fid=session->GetFieldID(cls, "title");
   if (fid==kUndefinedFieldID)
      return;
   session -> SetPBStringField(dwobj,fid,str_val);
   session -> UpdateField(dwobj,fid);
   return ;
 }

Usage

When you change any visual property of a PowerBuilder object by calling Set<type>field functions, the property is changed but the property is not refreshed in the graphical user interface. UpdateField refreshes the visual properties of PowerBuilder objects. You must call this function explicitly when changing any visual property with the Set<type>field functions.

See also

Set<type>Field