PowerBuilder Native Interface Programmers Guide and Reference
PBNI Interfaces, Structures, and Methods

Description

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

Syntax

AcquireArrayItemValue( pbarray array, pblong dim[ ])

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.

See also

ReleaseValue

Description

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

Syntax

AcquireValue ( IPBValue* value ) 

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

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 ) 

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

Description

Adds a global reference to the specified PowerBuilder object.

Syntax

AddGlobalRef (pbobject  obj)

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

Description

Adds a local reference to the specified PowerBuilder object.

Syntax

AddLocalRef (pbobject  obj)

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

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

Description

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

Syntax

CreateResultSet (IPB_ResultSetAccessor* rs)

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

Description

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

Syntax

FindClass(pbgroup group, LPCTSTR name)

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

Description

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

Syntax

FindClass(pbgroup group, pbint classID)

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

Description

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

Syntax

FindGroup(LPCTSTR name, pbgroup_type 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

Description

Finds a function that has the specified argument list.

Syntax

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

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.

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

Description

Frees memory allocated by InitCallInfo.

Syntax

FreeCallInfo(PBCallInfo *ci)

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

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 ) 

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

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 ) 

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

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 ) 

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

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 ) 

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

Description

Obtains information about an array.

Syntax

GetArrayInfo(pbarray array)

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

Description

Obtains the datatype of an item in an array.

Syntax

GetArrayItemType( pbarray array, pblong dim[ ])

Return value

pbuint.

See also

Get<type>ArrayItem

GetArrayInfo

GetArrayLength

IsArrayItemNull

NewBoundedObjectArray

NewBoundedSimpleArray

NewUnboundedObjectArray

NewUnboundedSimpleArray

ReleaseArrayInfo

SetArrayItemToNull

SetArrayItemValue

Set<type>ArrayItem

Description

Obtains the length of an array.

Syntax

GetArrayLength(pbarray array)

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

Description

Returns a pointer to the data buffer for a blob.

Syntax

GetBlob(pbblob bin)

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

Description

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

Syntax

GetBlobLength (pbblob bin)

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

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)

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

Description

Returns the name of a class in lowercase.

Syntax

GetClassName(pbclass cls)

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

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

Description

Converts data in a pbdate object to a string.

Syntax

GetDateString(pbdate date)

Return value

LPCTSTR.

See also

NewDate

ReleaseDateString

SetDate

Description

Converts data in a pbdatetime object to a string.

Syntax

GetDateTimeString(pbdatetime datetime)

Return value

LPCTSTR.

See also

NewDateTime

ReleaseDateTimeString

SetDateTime

Description

Converts decimal data in a pbdec object to a string.

Syntax

GetDecimalString(pbdec dec)

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

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

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.

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

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

Description

Obtains the internal ID of a class instance variable.

Syntax

GetFieldID(pbclass cls, LPCTSTR fieldName)

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

Description

Obtains the name of the specified field.

Syntax

GetFieldName(pbclass cls, pbfieldID fid)

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

Description

Obtains the datatype of a field declared by a class.

Syntax

GetFieldType(pbclass cls, pbfieldID fid)

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

Description

Returns the internal ID of a global variable.

Syntax

GetGlobalVarID(LPCTSTR name)

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

Description

Obtains the datatype of a global variable.

Syntax

GetGlobalVarType(pbfieldID fid)

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

Description

Obtains the marshaler object associated with a proxy object.

Syntax

GetMarshaler(pbproxyObject obj)

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

Description

Returns the ID of the requested method.

Syntax

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

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

Description

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

Syntax

GetMethodIDByEventID(pbclass cls, LPCTSTR eventID)

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

Description

Obtains a pointer to the interface of a native class.

Syntax

GetNativeInterface(pbobject obj)

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

Description

Returns the number of fields in the specified class.

Syntax

GetNumOfFields(pbclass cls)

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

Description

Obtains the value of a global variable of type Any.

Syntax

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

Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyField

GetPBAnyGlobalVar

GetPBAnySharedVar

Description

Obtains the value of a variable of type Any.

Syntax

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

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.

See also

GetPBAnyArrayItem

GetPBAnyGlobalVar

GetPBAnySharedVar

Description

Obtains the value of a global variable of type Any.

Syntax

GetPBAnyGlobalVar( pbfieldID fid, pbboolean& isNull )

Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyArrayItem

GetPBAnyField

GetPBAnySharedVar

Description

Obtains the value of a shared variable of type Any.

Syntax

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

Return value

IPB_Value*.

Usage

See GetPBAnyField.

See also

GetPBAnyArrayItem

GetPBAnyField

GetPBAnyGlobalVar

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)

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

Description

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

Syntax

GetResultSetAccessor (pbobject rs)

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

Description

Returns the internal ID of a shared variable.

Syntax

GettSharedVarID(pbgroup group, LPCTSTR fieldname)

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

Description

Obtains the datatype of the specified shared variable.

Syntax

GetSharedVarType ( pbgroup group, pbfieldID fid ) 

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

Description

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

Syntax

GetString (pbstring* string)

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

Description

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

Syntax

GetStringLength (pbstring string)

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

Description

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

Syntax

GetSuperClass(pbclass cls)

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

Description

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

Syntax

GetSystemClass (pbclass cls)

Return value

pbclass or null on error.

See also

GetMethodID

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

Description

Converts data in a pbtime object to a string.

Syntax

GetTimeString(pbtime time)

Return value

LPCTSTR.

See also

NewString

ReleaseTimeString

SetString

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

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

Description

Initializes the PBCallInfo structure.

Syntax

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

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

Description

Invokes system or user global functions.

Syntax

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

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

Description

Invokes a class member method.

Syntax

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

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

Description

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

Syntax

IsArrayItemNull( pbarray array, pblong dim[ ])

Return value

pbboolean.

See also

GetArrayItemType

Set<type>ArrayItem

SetArrayItemToNull

Description

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

Syntax

IsAutoInstantiate(pbclass)

Return value

pbboolean.

Description

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

Syntax

IsFieldArray(pbclass cls, pbfield fid)

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

Description

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

Syntax

IsFieldNull(pbobject obj, pbfield fid)

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

Description

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

Syntax

IsFieldObject(pbclass cls, pbfield fid)

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

Description

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

Syntax

IsGlobalVarArray(pbfield fid)

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

Description

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

Syntax

IsGlobalVarNull( pbfield fid)

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

Description

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

Syntax

IsGlobalVarObject( pbfield fid)

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

Description

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

Syntax

IsNativeObject(pbobject obj)

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

Description

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

Syntax

IsSharedVarArray(pbgroup group, pbfield fid)

Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarNull

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

Description

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

Syntax

IsSharedVarNull(pbgroup group, pbfield fid)

Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarObject

Set<type>SharedVar

SetSharedVarToNull

Description

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

Syntax

IsSharedVarObject(pbgroup group, pbfield fid)

Return value

pbboolean.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

Set<type>SharedVar

SetSharedVarToNull

Description

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

Syntax

NewBlob (const void* bin, pblong len)

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

Description

Creates a bounded PowerBuilder object or structure array.

Syntax

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

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

Description

Creates a bounded simple data array.

Syntax

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

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

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

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

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

Description

Creates a new object of the specified type.

Syntax

NewObject(pbclass cls)

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

Description

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

Syntax

NewProxyObject(pbclass cls)

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

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

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

Description

Creates an unbounded PowerBuilder object or structure data array.

Syntax

NewUnboundedObjectArray(pbclass cls)

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

Description

Creates an unbounded simple data array.

Syntax

NewUnboundedSimpleArray(pbuint type)

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

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

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.

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

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

Description

Releases memory returned by GetArrayInfo.

Syntax

ReleaseArrayInfo(PBArrayInfo* pbarrayinfo)

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

Description

Frees the memory acquired using GetDateString.

Syntax

ReleaseDateString(LPCTSTR string)

Return value

None.

See also

GetDateString

Description

Frees the memory acquired using GetDateTimeString.

Syntax

ReleaseDateTimeString(LPCTSTR string)

Return value

None.

See also

GetDateTimeString

Description

Frees the memory acquired using GetDecimalString.

Syntax

ReleaseDecimalString(LPCTSTR string)

Return value

None.

See also

GetDecimalString

Description

Releases the pointer obtained using GetResultSetAccessor.

Syntax

ReleaseResultSetAccessor (IPB_ResultSetAccessor* rs)

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

Description

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

Syntax

ReleaseString(LPCTSTR string)

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

Description

Frees the memory acquired using GetString.

Syntax

ReleaseTimeString(LPCTSTR string)

Return value

None.

See also

GetTimeString

Description

Frees the IPB_Value acquired using AcquireValue or AcquireArrayItemValue.

Syntax

ReleaseValue(IPB_Value* value)

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.

See also

AcquireArrayItemValue

AcquireValue

Description

Removes a global reference to the specified PowerBuilder object.

Syntax

RemoveGlobalRef (pbobject  obj)

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

Description

Removes a local reference to the specified PowerBuilder object.

Syntax

RemoveLocalRef (pbobject  obj)

Return value

None.

See also

AddLocalRef

PopLocalFrame

PushLocalFrame

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)

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

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

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 ) 

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

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 ) 

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

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 ) 

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

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 ) 

Return value

PBX_RESULT.

See also

Get<type>SharedVar

GetSharedVarID

GetSharedVarType

IsSharedVarArray

IsSharedVarNull

IsSharedVarObject

SetSharedVarToNull

Description

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

Syntax

SetArrayItemToNull( pbarray array, pblong dim[ ])

Return value

pbboolean.

See also

IsArrayItemNull

Description

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

Syntax

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

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

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)

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

Description

Resets the value of the specified pbdate object.

Syntax

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

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

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)

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

Description

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

Syntax

SetDecimal(pbdec dec, LPCTSTR dec_str)

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

Description

Sets the value of the specified field to null.

Syntax

SetFieldToNull(pbobject obj, pbfield fid)

Return value

None.

See also

GetFieldID

GetFieldType

Get<type>Field

GetNumOfFields

IsFieldArray

IsFieldNull

IsFieldObject

Set<type>Field

Description

Sets the value of the specified global variable to null.

Syntax

SetGlobalVarToNull(pbobject obj, pbfield fid)

Return value

None.

See also

GetGlobalVarID

GetGlobalVarType

Get<type>GlobalVar

IsGlobalVarArray

IsGlobalVarNull

IsGlobalVarObject

Set<type>GlobalVar

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)

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

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)