|
Usage and Examples |
|
In PxPlus, a sub-object can be defined as any object that is the return value of another object's property or method call. How is this important? Since a sub-object is owned by the base object, it will be destroyed when the base object is destroyed.
Example:
0010 ! Crystal COM example
0020 DEF OBJECT APP,"CrystalRuntime.Application"
0040 RPT=APP'OPENREPORT("d:\crw8\chart.rpt")
0050 DB=RPT'DATABASE
0060 TBLS=DB'TABLES
0070 TABLE1=TBLS'ITEM(1)
0080 TABLE2=TBLS'ITEM(2)
0090 DELETE OBJECT APP
In the example above, RPT is a sub-object of APP, DB is a sub-object of RPT, TBLS is a sub-object of DB, and TABLE1 and TABLE2 are sub-objects of TBLS.
This ownership is best described as a tree list where:
After line 80 executes, all sub-objects owned by APP will be destroyed. This is done to ensure that the reference counting of APP is brought down to 1 before it is destroyed. This is not a feature of COM, but a feature implemented by the DLL. In a VB application, if APP was freed, the actual COM object would exist in memory until all the other sub-objects were freed (because each sub-object increments the reference count of the parent). While this feature is ideal for most situations, it can cause problems if you delete a parent object and then try to perform actions on one of its sub-objects.
Many objects have methods where the parameters are defined as optional. This is an indication to the developer that the parameter can be excluded. But, how is this accomplished in PxPlus?
Below is an example of an ADO Recordset Open method in VB as translated to PxPlus:
Example:
|
|
VB |
RS.OPEN "GL1_ACCOUNTS", CONN, , , 2 |
|
|
PxPlus |
?RS'OPEN("GL1_Accounts", *CONN, *, *, 2) |
In PxPlus, the optional parameters are passed using "*". The one exception is that PxPlus will not allow "*" to be passed as the last parameter. If these parameters are not required for the method call, then they must be omitted.
Example:
0010 X=RS'OPEN("GL1_Accounts", *CONN, *, *, *) ! Syntax Error
0020 ! The following line is the same as the line above
0030 X=RS'OPEN("GL1_Accounts", *CONN)
The three optional parameters are omitted in line 30. Although syntactically different, line 30 is functionally the same as line 10.
Occasionally, there are cases where an object's property or method is identical to a PxPlus reserved word. When this happens, PxPlus generates a syntax error on any attempt to use the object's property or method name.
Example:
If you queried a calendar control for a property called DAY …
> ?X'DAY
… an Error 20 is generated because DAY is a reserved word. The workaround for this is called aliasing. Aliasing allows a developer to call a property or method by creating user-defined names.
The following could be done to correct the previous example:
0010 Z=X'PVXALIAS("DAY", "FOO")
0020 ! FOO is now a reference to DAY
0030 ?X'FOO
Aliasing may be used on any COM method or property. It is also useful for assigning more meaningful names to object methods and properties.
Due to syntax restrictions, PxPlus does not allow object assignment to properties. The following example (given for illustration purposes) generates an Error #23: Missing/Invalid variable :
10 DEF OBJECT X, "*VARIANT"
20 DEF OBJECT Y, "*VARIANT"
30 X'VAL=*Y ! Error 23 occurs
To handle this situation, method calls are enhanced to accept "invoke hints". An invoke hint indicates to the DLL how a call should actually be invoked: as a function, property get, property set , or property set reference.
The following is a list of valid method invocation hints:
|
|
.GET |
Get property |
|
|
.PUT |
Set property |
|
|
.PUTREF |
Set property reference |
These hints are added to the end of a method/property name so that the call reads as object'method {.hint}(parameters). If you attempt to get or set array properties without using an "invoke hint", the DLL will attempt to resolve the calling type; however, it can only do this by trial and error (up to four separate attempts).
For speed reasons, as well as for clarity, the developer should always specify a hint when calling a property using the syntax of a method call.
In the previous example, line 30 should be changed to:
30 NULL=X'VAL.PUT(*Y) ! Assign object Y to X'VAL
Example:
The following is an example of a grid object that exposes a CELL property that is accessed using a row and column indicator:
|
|
10 DATA=GRID'CELL.GET(ROW, COL) |
! Get the cell value |
|
|
20 DATA= DATA+10 |
! Add 10 to the value |
|
|
30 NULL=GRID'CELL.PUT(ROW, COL, DATA) |
! Set the cell value |
Example 1 - Embedding IE5 or IE6. You must have Internet Explorer installed for this to work.
0010 DEF OBJECT handle, @(2,2,70,16)="Shell.Explorer"
0020 errcode=handle'Navigate2("www.pvxplus.com")
0030 input *
0040 DELETE OBJECT handle
Example 2 - Dynamically creating an object from the OCX toolbox.
0010 PRINT 'CS'
0020 WAIT 0
0030 DEF OBJECT OCX,@(40,1,30,10),"*",ERR=0100
0040 PROG$=OCX'PVXNAME$
0050 ESCAPE
0060 END
0100 PRINT MSG(-1)
Example 3 - Creating a Microsoft Form Frame and adding a button to it. This requires the MS Forms 2.0 Object Library to be installed on the system.
0010 DEF OBJECT FRM, @(40, 2, 30, 12), "Forms.Frame.1"
0020 FRM'PVXMODE=0
0030 CTRLS=FRM'Controls
0040 BTN1=CTRLS'ADD("Forms.CommandButton.1")
0050 BTN1'Top=20
0060 BTN1'Left=20
0070 BTN1'Caption$="Hello World!"
0080 input *
0090 DELETE OBJECT FRM
Example 4 - Creating a Microsoft Word Document from a file reference. This requires MS Word to be installed on the system.
0010 GET_FILE_BOX READ X$,LWD,"Word Document","Word Document|*.doc,"
0020 IF X$="" THEN END
0030 DEF OBJECT WD,@(0,0,80,20),"[file]"+X$
0040 INPUT *
0050 DELETE OBJECT WD
0060 END
Example 5 - Using ADO to display the tables in a Microsoft Access Database.
0010 GET_FILE_BOX READ X$, LWD,"Access Database"," Access Database |*.mdb,"
0020 IF X$="" THEN END
0030 DEF OBJECT CONN,"ADODB.Connection"
0040 CONNSTR$="Provider=Microsoft.Jet.OLEDB.4.0;Data Source="+X$
0050 X=CONN'OPEN(CONNSTR$)
0060 DEF OBJECT VARDATA,"*vararray"
0070 Z=VARDATA'CREATE(4) ! Create single dim array with 4 elements
0080 ! By default, all elements are set to empty
0090 Z=VARDATA'SETDATA(3,"Table") ! Set 4th element to string "Table"
0100 ! Get the schema recordset
0110 R=CONN'OPENSCHEMA(20,*VARDATA)
0120 N$=""; FOR I=0 TO R'FIELDS'COUNT-1; N$=N$+R'FIELDS(I)'NAME$+" | "; NEXT I; PRINT N$
0130 ! Get the first 20 table names, this will return an array
0140 RA=R'GETROWS(20)
0150 FOR I=0 TO RA'UBOUND(2)
0160 TXT$=""
0170 FOR II=0 TO RA'UBOUND(1)
0180 TXT$=TXT$+RA'GETDATA$(II,I)+" | "
0190 NEXT II
0200 PRINT TXT$
0210 NEXT I
Example 6 - Test of Microsoft Script Control (*VARARRAY support). This demonstrates passing a *VARARRAY in a *VARIANT, as well as getting an object returned back "by reference".
0040 DEF OBJECT MSC,"MSScriptControl.ScriptControl"
0050 MSC'LANGUAGE$="" ! Need to clear it in order to get it set.
Documented issue in MSDN
0060 MSC'LANGUAGE$="VBScript"
0070 MSC'ALLOWUI=-1
0080 NL$=CHR(13)+CHR(10)
0090 PGMTEXT$="Sub GiveMeObject( byref obj)"+NL$
0100 PGMTEXT$=PGMTEXT$+"set obj(1)=CreateObject("+QUO+"Excel.Application"+QUO+")"+NL$
0105 PGMTEXT$=PGMTEXT$+"msgbox obj(1)"+NL$
0110 PGMTEXT$=PGMTEXT$+"End Sub"+NL$
0120 Z=MSC'ADDCODE(PGMTEXT$)
0130 DEF OBJECT X,"*variant"
0131 DEF OBJECT A,"*vararray"; Z=A'CREATE(2)
0132 Z=X'VAL.PUT(*A)
0140 Z=MSC'RUN("GiveMeObject",*X)
0150 A=X'VAL ! Get the array back
0155 PRINT A'TYPE$(1) ! Will print "O"
0160 DELETE OBJECT X,ERR=*NEXT
0170 DELETE OBJECT MSC
Example 7 - Using *VARIANT objects and assigning objects to properties.
0010 DEF OBJECT X,"*VARIANT"
0020 DEF OBJECT Y,"*VARIANT"
0030 X'VAL$="Hello World"
0040 Y'VAL=100
0050 Z=Y'VAL.PUT(*X)
0060 PRINT Y'VAL$ ! Will print "Hello World"