IPB_Session interface

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.

Description

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

Syntax

AcquireArrayItemValue( pbarray array, pblong dim[ ])

Returns

IPB_Value*.

Examples

Example 1

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

Description

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

Syntax

AcquireValue ( IPBValue* value ) 

Returns

IPB_Value*.

Examples

Example 1

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

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 ) 

Returns

PBXRESULT. PBX_OK on success.

Examples

Example 1

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

Description

Adds a global reference to the specified PowerBuilder object.

Syntax

AddGlobalRef (pbobject  obj)

Returns

pbclass or null on error.

Examples

Example 1

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

Description

Adds a local reference to the specified PowerBuilder object.

Syntax

AddLocalRef (pbobject  obj)

Returns

pbclass or null on error.

Examples

Example 1

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

Description

Clears the current PowerBuilder exception object.

Syntax

ClearException ()

Returns

None.

Usage

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

See also

Description

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

Syntax

CreateResultSet (IPB_ResultSetAccessor* rs)

Returns

pbobject.

Examples

Example 1

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("pbvm125.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 EAS Demo DB V125
SQLCA.DBMS = "ODBC"
SQLCA.AutoCommit = False
SQLCA.DBParm = &
   "ConnectString='DSN=EAS Demo DB V125;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

Description

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

Syntax

FindClass(pbgroup group, LPCTSTR name)

Returns

pbclass or null on failure.

Examples

Example 1

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

Description

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

Syntax

FindClass(pbgroup group, pbint classID)

Returns

pbclass or null on failure.

Usage

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

See also

Description

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

Syntax

FindGroup(LPCTSTR name, pbgroup_type type)

Returns

pbgroup or null on failure.

Examples

Example 1

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

Description

Finds a function that has the specified argument list.

Syntax

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

Returns

pbmethodID.

Examples

Example 1

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 pbsig125 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

Description

Frees memory allocated by InitCallInfo.

Syntax

FreeCallInfo(PBCallInfo *ci)

Returns

None.

Examples

Example 1

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

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 ) 

Returns

The value of the array item.

Examples

Example 1

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

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 ) 

Returns

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

Examples

Example 1

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

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 ) 

Returns

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

Examples

Example 1

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

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 ) 

Returns

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

Examples

Example 1

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

Description

Obtains information about an array.

Syntax

GetArrayInfo(pbarray array)

Returns

PBArrayInfo*.

Examples

Example 1

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

Description

Obtains the datatype of an item in an array.

Syntax

GetArrayItemType( pbarray array, pblong dim[ ])

Returns

pbuint.

See also

Description

Obtains the length of an array.

Syntax

GetArrayLength(pbarray array)

Returns

pblong.

Examples

Example 1

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

Description

Returns a pointer to the data buffer for a blob.

Syntax

GetBlob(pbblob bin)

Returns

void*.

Examples

Example 1

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

Description

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

Syntax

GetBlobLength (pbblob bin)

Returns

pblong.

Examples

Example 1

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

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)

Returns

pbclass or null on error.

Examples

Example 1

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

Description

Returns the name of a class in lowercase.

Syntax

GetClassName(pbclass cls)

Returns

LPCTSTR.

Examples

Example 1

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

Description

Obtains the name of the current group.

Syntax

GetCurrGroup( )

Returns

pbgroup or null on failure.

Examples

Example 1

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

Description

Converts data in a pbdate object to a string.

Syntax

GetDateString(pbdate date)

Returns

LPCTSTR.

See also

Description

Converts data in a pbdatetime object to a string.

Syntax

GetDateTimeString(pbdatetime datetime)

Returns

LPCTSTR.

See also

Description

Converts decimal data in a pbdec object to a string.

Syntax

GetDecimalString(pbdec dec)

Returns

LPCTSTR.

Examples

Example 1

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

Description

Obtains the name of an enumerated variable.

Syntax

GetEnumItemName(LPCTSTR enumName, long enumItemValue)

Returns

LPCTSTR.

Usage

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

See also

Description

Obtains the value of an enumerated variable.

Syntax

GetEnumItemValue(LPCTSTR enumName, LPCTSTR enumItemName)

Returns

Long.

Examples

Example 1

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

Description

Obtains the current thrown exception object.

Syntax

GetException ()

Returns

pbobject.

Examples

Example 1

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

Description

Obtains the internal ID of a class instance variable.

Syntax

GetFieldID(pbclass cls, LPCTSTR fieldName)

Returns

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

Examples

Example 1

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

Description

Obtains the name of the specified field.

Syntax

GetFieldName(pbclass cls, pbfieldID fid)

Returns

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

Description

Obtains the datatype of a field declared by a class.

Syntax

GetFieldType(pbclass cls, pbfieldID fid)

Returns

Description

Returns the internal ID of a global variable.

Syntax

GetGlobalVarID(LPCTSTR name)

Returns

pbfieldID or null on failure.

Examples

Example 1

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

Description

Obtains the datatype of a global variable.

Syntax

GetGlobalVarType(pbfieldID fid)

Returns

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

Examples

Example 1

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

Description

Obtains the marshaler object associated with a proxy object.

Syntax

GetMarshaler(pbproxyObject obj)

Returns

IPBX_Marshaler*.

Examples

Example 1

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

Description

Returns the ID of the requested method.

Syntax

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

Returns

pbMethodID of the method or kUndefinedMethodID on error.

Examples

Example 1

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

Description

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

Syntax

GetMethodIDByEventID(pbclass cls, LPCTSTR eventID)

Returns

pbMethodID of the method or kUndefinedMethodID on error.

Examples

Example 1

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

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

See also

Description

Obtains a pointer to the interface of a native class.

Syntax

GetNativeInterface(pbobject obj)

Returns

IPBX_UserObject.

Examples

Example 1

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

Description

Returns the number of fields in the specified class.

Syntax

GetNumOfFields(pbclass cls)

Returns

pbulong.

Examples

Example 1

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

Description

Obtains the value of a global variable of type Any.

Syntax

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

Returns

IPB_Value*.

Usage

Description

Obtains the value of a variable of type Any.

Syntax

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

Returns

IPB_Value*.

Examples

Example 1

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

Description

Obtains the value of a global variable of type Any.

Syntax

GetPBAnyGlobalVar( pbfieldID fid, pbboolean& isNull )

Returns

IPB_Value*.

Usage

Description

Obtains the value of a shared variable of type Any.

Syntax

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

Returns

IPB_Value*.

Usage

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)

Returns

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

Examples

Example 1

Description

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

Syntax

GetResultSetAccessor (pbobject rs)

Returns

IPB_ResultSetAccessor

Examples

Example 1

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

Description

Returns the internal ID of a shared variable.

Syntax

GettSharedVarID(pbgroup group, LPCTSTR fieldname)

Returns

pbfieldID. Returns 0xffff if the ID cannot be found.

Examples

Example 1

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

Description

Obtains the datatype of the specified shared variable.

Syntax

GetSharedVarType ( pbgroup group, pbfieldID fid ) 

Returns

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

Examples

Example 1

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

Description

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

Syntax

GetString (pbstring* string)

Returns

LPCTSTR.

Examples

Example 1

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

Description

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

Syntax

GetStringLength (pbstring string)

Returns

pblong.

Examples

Example 1

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

Description

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

Syntax

GetSuperClass(pbclass cls)

Returns

pbclass or 0 if the class has no ancestor.

Examples

Example 1

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

Description

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

Syntax

GetSystemClass (pbclass cls)

Returns

pbclass or null on error.

See also

Description

Returns a PowerBuilder internal system group.

Syntax

GetSystemGroup()

Returns

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

Description

Converts data in a pbtime object to a string.

Syntax

GetTimeString(pbtime time)

Returns

LPCTSTR.

See also

Description

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

Syntax

HasExceptionThrown()

Returns

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

Examples

Example 1

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

Description

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

Syntax

HasPBVisualObject()

Returns

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

Example 1

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

Description

Initializes the PBCallInfo structure.

Syntax

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

Returns

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

Examples

Example 1

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

Description

Invokes system or user global functions.

Syntax

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

Returns

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

Example 1

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

Description

Invokes a class member method.

Syntax

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

Returns

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

Example 1

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

Description

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

Syntax

IsArrayItemNull( pbarray array, pblong dim[ ])

Returns

pbboolean.

See also

Description

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

Syntax

IsAutoInstantiate(pbclass)

Returns

pbboolean.

Description

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

Syntax

IsFieldArray(pbclass cls, pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsFieldNull(pbobject obj, pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

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

See also

Description

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

Syntax

IsFieldObject(pbclass cls, pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsGlobalVarArray(pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsGlobalVarNull( pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsGlobalVarObject( pbfield fid)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsNativeObject(pbobject obj)

Returns

pbboolean.

Examples

Example 1

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

Description

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

Syntax

IsSharedVarArray(pbgroup group, pbfield fid)

Returns

pbboolean.

See also

Description

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

Syntax

IsSharedVarNull(pbgroup group, pbfield fid)

Returns

pbboolean.

See also

Description

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

Syntax

IsSharedVarObject(pbgroup group, pbfield fid)

Returns

pbboolean.

See also

Description

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

Syntax

NewBlob (const void* bin, pblong len)

Returns

pbblob.

Examples

Example 1

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

Description

Creates a bounded PowerBuilder object or structure array.

Syntax

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

Returns

pbarray or null on failure.

Examples

Example 1

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

Description

Creates a bounded simple data array.

Syntax

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

Returns

pbarray or null on failure.

See also

Description

Creates a new pbdate data object.

Syntax

NewDate()

Returns

pbdate.

Examples

Example 1

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

Description

Creates a new pbdatetime data object.

Syntax

NewDateTime()

Returns

pbdatetime.

Examples

Example 1

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

Description

Allocates resources for a new decimal data object.

Syntax

NewDecimal( )

Returns

pbdec or null on failure.

Examples

Example 1

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

Description

Creates a new object of the specified type.

Syntax

NewObject(pbclass cls)

Returns

pbobject of the given class or structure.

Examples

Example 1

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

Description

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

Syntax

NewProxyObject(pbclass cls)

Returns

pbproxyobject.

Examples

Example 1

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

Description

Creates a new string.

Syntax

NewString(LPCTSTR)

Returns

pbstring.

Examples

Example 1

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

Description

Creates a new pbtime data object.

Syntax

NewTime()

Returns

pbtime.

Examples

Example 1

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

Description

Creates an unbounded PowerBuilder object or structure data array.

Syntax

NewUnboundedObjectArray(pbclass cls)

Returns

pbarray or null on failure.

Usage

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

See also

Description

Creates an unbounded simple data array.

Syntax

NewUnboundedSimpleArray(pbuint type)

Returns

pbarray or null on failure.

Examples

Example 1

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

Description

Description

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

Syntax

ProcessPBMessage()

Returns

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

Examples

Example 1

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

Returns

None.

See also

Description

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

Syntax

Release()

Returns

None.

Examples

Example 1

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)

Returns

PBXRESULT. PBX_OK for success.

Examples

Example 1

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

Description

Frees the memory acquired using GetDateString.

Syntax

ReleaseDateString(LPCTSTR string)

Returns

None.

See also

Description

Frees the memory acquired using GetDateTimeString.

Syntax

ReleaseDateTimeString(LPCTSTR string)

Returns

None.

See also

Description

Frees the memory acquired using GetDecimalString.

Syntax

ReleaseDecimalString(LPCTSTR string)

Returns

None.

See also

Description

Description

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

Syntax

ReleaseString(LPCTSTR string)

Returns

None.

Examples

Example 1

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

Description

Frees the memory acquired using GetTimeString.

Syntax

ReleaseTimeString(LPCTSTR string)

Returns

None.

See also

Description

Frees the IPB_Value acquired using AcquireValue or AcquireArrayItemValue.

Syntax

ReleaseValue(IPB_Value* value)

Returns

None.

Examples

Example 1

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

Description

Removes a global reference to the specified PowerBuilder object.

Syntax

RemoveGlobalRef (pbobject  obj)

Returns

None.

Examples

Example 1

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

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

See also

Description

Removes a local reference to the specified PowerBuilder object.

Syntax

RemoveLocalRef (pbobject  obj)

Returns

None.

See also

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)

Returns

None.

Examples

Example 1

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

Description

Determines whether the PowerBuilder system function Restart has been called.

Syntax

HasPBVisualObject()

Returns

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

Example 1

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

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 ) 

Returns

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

Example 1

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

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 ) 

Returns

PBX_RESULT.

Examples

Example 1

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

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 ) 

Returns

PBX_RESULT.

Examples

Example 1

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

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 ) 

Returns

PBX_RESULT.

See also

Description

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

Syntax

SetArrayItemToNull( pbarray array, pblong dim[ ])

Returns

pbboolean.

See also

Description

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

Syntax

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

Returns

None.

Examples

Example 1

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

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)

Returns

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

Description

Resets the value of the specified pbdate object.

Syntax

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

Returns

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

Examples

Example 1

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

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)

Returns

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

Examples

Example 1

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

Description

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

Syntax

SetDecimal(pbdec dec, LPCTSTR dec_str)

Returns

PBXRESULT. PBX_OK for success.

Examples

Example 1

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

Description

Sets the value of the specified field to null.

Syntax

SetFieldToNull(pbobject obj, pbfield fid)

Returns

None.

See also

Description

Sets the value of the specified global variable to null.

Syntax

SetGlobalVarToNull(pbobject obj, pbfield fid)

Returns

None.

See also

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)

Returns

None.

Examples

Example 1

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

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)

Returns

None.

Examples

Example 1

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.

This set of functions is particularly useful for working with multiple threads of execution in EAServer.

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

Description

Sets the value of the specified shared variable to null.