PxPlus COM Support

*CONSTANTS

Provides a mechanism for exposing all enumerated constant values from an object's type library.

*ERROR

Wrapper export for last error information.

*FOREACH

Wrapper around an IEnumVariant interface, which is more commonly referred to as a "collection". PxPlus allows this wrapper to be created on both collection objects, as well as single dimension COM SafeArrays. Provides a means of iterating data without regards to the lower or upper bounds of the container.

*GLOBAL

Provides an enumerator for the system-wide list of objects exposed using PvxMakeGlobal.

*MASTER

Serves as a system object for the interop layer. Provides object iteration capabilities, version information, etc.

*PROXY

Allows the developer to expose instantiated PxPlus objects directly to the COM world.

*RECORD

Wrapper around an IRecordInfo interface, which is also referred to as a COM user-defined type (record structure).

*VARARRAY

Wrapper around an OLE safe array of variants. Provides a mechanism for COM array data handling.

*VARIANT

Wrapper around an OLE variant data type. Provides a means for passing data by reference, as well as converting data from a PxPlus type to Automation types.

CLEAR( )

(Method Call) Clears the last error information.

CODE(number)

(Method Call) Returns the OLE code for the passed number, which is treated as an HRESULT to evaluate. If no parameter is passed, the code for the OLEERROR property is returned.

DESCRIPTION$

(Read-Only Property) Contents depends on if the last error was DISP_E_EXCEPTION or not. If so, it returns the object-defined message. If not, it returns the string representation of the OLE HRESULT based on the OLEERROR property.

FACILITY(number)

(Method Call) Returns the OLE facility for the passed number, which is treated as an HRESULT to evaluate. If no parameter is passed, the facility for the OLEERROR property is returned.

HELPCONTEXT

(Read-Only Property) If last error code was DISP_E_EXCEPTION, then this property will return the associated help context number, if available.

HELPFILE$

(Read-Only Property) If the last error code was DISP_E_EXCEPTION , then this property will return the associated help file name, if available.

NUMBER

(Read-Only/Default Property) Returns last object code set for a dispatch call that failed with DISP_E_EXCEPTION.

OLEERROR

(Read-Only Property) Returns the last OLE HRESULT code that was raised.

SEVERITY(number)

(Method Call) Returns the OLE severity for the passed number, which is treated as an HRESULT to evaluate. If no parameter is passed, the severity for the OLEERROR property is returned.

SOURCE$

(Read-Only Property) If the last error code was DISP_E_EXCEPTION, this property will return a textual, human-readable name of the source of the exception, if available.

DATA[$]

(Read Only/Default Property) Returns the item data that was returned from a call to NEXT( ). The actual data type depends on the collection or array item being enumerated.

NEXT( )

(Method Call) This method reads the next available collection or array item into the DATA property and returns true on success. If no further items exist, false will be returned. This method must be called (and return success) before accessing the DATA property.

RESET( )

(Method Call) Resets the "for each" enumerator and clears the DATA property. This allows item enumeration to start from the first item. Only required if a second (or more) iteration is desired.

BINDTO(index/name$)

(Method Call) Returns a reference to the global object specified by either name or index of item in the global list.

COUNT

(Read-Only Property) Returns the count of objects in the system-wide list.

ITEM$(index)

(Method Call) Returns the name of the global object at the specified index.

Note:
ITEM$ should be treated as a zero-based array.

REFRESH( )

(Method Call) Rfreshes the system-wide list of global objects.

CALLCOUNT

(Read-Only Property) Returns the number of command call executions since the interop library was initialized.

COUNT

(Read-Only Property) Returns the number of objects being managed by the interop layer (includes the master object in this count).

ITEM(index)

(Method Call) Returns the interop handle for the object at the specified index. See PVXID.

Note:
ITEM should be treated as a zero-based array.

LISTPVXMETHODS

(Read/Write Property) Determines if the internal PVX methods should be listed when the '* property of an object is queried. Defaults to true (-1).

VERSION$

(Read-Only Property) Returns the file version number for the interop library PVXOCX32.

ASOBJECT(objid)

(Method Call) Allows the COM client to wrap a (PxPlus) object handle. If the objid represents a valid PxPlus object handle, an internal proxy wrapper will be created and the dispatch interface will be returned.

INVOKE(name, flag [, parameters …])

(Method Call) Executes the property or method name specified by the name parameter.

The flag value must be one of the following: 1 (property get), 2 (property set) or 3 (method call). Any parameters that should be passed to the PxPlus object will then follow.

This method is provided to handle overload situations where it can be unclear which property or method should be called:

PROPERTY TEST
PROPERTY TEST$
FUNCTION TEST( )
FUNCTION TEST$( )

Would translate to the following Invoke calls:

.Invoke("TEST", 1)
.Invoke("TEST$", 1)
.Invoke("TEST", 3)
.Invoke("TEST$", 3)

EVALUATE(statement)

(Method Call) Passes the statement string parameter to the PxPlus interpreter for evaluation.

EXECUTE(statement)

(Method Call) Passes the statement string parameter to the PxPlus interpreter for execution.

ADD(data [$])

(Method Call) Adds the value of the data parameter to the currently held variant data. Logical use is for building strings greater than 32K in length but can be used to add numbers, etc. Calling this method will perform an implicit conversion to the data type of the passed parameter.

ADDB(data [$])

(Method Call) Adds the string data parameter to the currently held variant string data. No conversion to Unicode is performed. Requires the passed data parameter to be a either a string or a variant object that contains a string. Also requires the current data to be a string type.

CLEAR( )

(Method Call) Clears the contents of the variant. After the CLEAR finishes, the data type for the variant will be set to E(mpty). If the variant contained an object or array reference, the object will be released.

EXPLICITBYREF

(Read/Write Property) Determines how the variant will be passed if PASSBYREF is set to true. When this property is set to false (zero), a pointer to the variant will be passed to the COM method. When set to true (non-zero), a pointer to the actual data will be passed. The default setting for this property is false.

LEN

(Read-Only Property) Returns the length of the data held by the variant. Logical use is primarily for string data.

LENB

(Read-Only Property) Returns the length of the data held by the variant. This is identical to the LEN property except when the variant contains string data. For strings, the actual byte count is returned, which is not the same as the character count when dealing with Unicode strings.

PASSBYREF

(Read/Write Property) Determines if the variant will be passed by reference. Setting the property to zero indicates false; any other value indicates true. The default setting for this property is true. See EXPLICITBYREF above.

TYPE$

(Read/Write Property) Returns the data type for the data being held in the variant. When set, will attempt to convert the data to the requested data type. An error will occur if the conversion fails. Valid types are:

VAL[$]

(Read/Write Property) Used to get/set the data held by the variant. It should be noted that setting the data may cause an implicit conversion. For example, if the current data type is B, setting the VAL property to 0 will cause a conversion to data type I. When assigning an object to the VAL property, the following notation must be used: object' VAL.PUT(*otherobject).

VALB[$]

(Read/Write Property) Used to get/set the string data held by the variant. The difference between this property and the VAL property is that the data is assigned "as is". No conversion from Unicode to ANSI is performed on the data.

ARRAYTYPE$

(Read-Only Property) Returns the array type. Valid types are:

CLEAR(index [, index])

(Method Call) Clears the data being held in the variant array element. It is legal to call this method without passing in the element index, in which case the index will default to zero. After the clear completes, the element data type is set to E(mpty).

COPY

(Read-Only Property) Returns a variant array object that contains an exact copy of the contents of the current variant array.

CREATE(elements [, elements])

(Method Call) Initializes the variant array to the dimension count and element count for each dimension. This method must be passed at least one element count (to create a single dimensioned array) and can accept a maximum of 20 element counts.

Example:

10 ! Create 1 dim array with 10 elements
20 OBJECT'CREATE(10)
30 ! Create 2 dim array
40 OBJECT'CREATE(10, 100)

Either this method or CREATEVECTOR must first be called before attempting to access data. Calling CREATE multiple times is also allowed but will clear any existing data.

CREATEBYTEARRAY (data [$])

(Method Call) Requires the passed data parameter to be a either a string or a variant object that contains a string. Initializes the array as a single dimension array of byte (ArrayType = "C"), with the element count of the array equal to the length of the data string.

For string data, a conversion to Unicode is performed, resulting in an element count that is 2x the length of the string. If byte handling is desired then, a *VARIANT object should be used.

Example:

10 DEF OBJECT V, "*VARIANT"
20 DEF OBJECT A, "*VARARRAY"
30 V'VALB$="Hello world"
40 A'CREATEBYTEARRAY(*V)

CREATEEX(type$, elements [, elements])

(Method Call) Initializes an array of the type specified by type$, where type$ is one of the valid characters from ARRAYTYPE$. See ARRAYTYPE$ above.

The number of dimensions is determined by the count of passed elements. Each element parameter determines the element count for the dimension. This method must be passed at least one element count (to create a single dimensioned array) and can accept a maximum of 19 element counts.

CREATEVECTOR(data [, data])

(Method Call) Initializes the array as a single dimension variant array with the element count equal to the number of parameters passed in. Each element in the array will be assigned the contents of the corresponding data parameter.

Example:

OBJECT'CREATEVECTOR("John", "Smith", 31, 150.3)

Creates a single dimension array with an LBOUND of zero, a UBOUND of 3, and element data types of: [0] = "S", [1] = "S", [2] = "I", [3] = "R".

Calling CREATEVECTOR multiple times is allowed but will clear any existing data.

DIMENSIONS

(Read-Only Property) Returns the number of dimensions in the variant array.

GETDATA[$](index [, index])

(Method Call) Returns the data being held in the variant array element. It is legal to call this method without passing in the element index, in which case the index will default to zero.

GETDATAEX(index [, index])

(Method Call) Returns the data being held in the variant array element as a variant object. It is legal to call this method without passing in the element index, in which case the index will default to zero.

LBOUND(dimension)

(Method Call) Returns the lower boundary for the dimension in the array. Note that this will always be zero for a valid dimension. When passing dimension, the value should be an integer between 1 and the number of valid dimensions; otherwise, an error occurs.

OLEARRAY

(Read-Only Property) Returns a variant array copy of the current array. If the current ARRAYTYPE$ property is "V", then no conversion is required.

PASSBYREF

(Read/Write Property) Determines if the array will be passed by reference. Setting the property to zero indicates false, any other value indicates true. The default setting for this property is true.

SETDATA(index [, index], data [$])

(Method Call) Assigns the contents of data to the variant array element. It is legal to call this method without passing in the element index, in which case the index will default to zero.

For variant arrays, the data parameter can be any valid data type, including variant and variant array objects. For all other arrays, the data parameter must be convertible to the array type.

TYPE$(index [, index])

(Method Call) Returns the data type for the data being held in the variant array element. It is legal to call this method without passing in the element index, in which case the index will default to zero.

Example:

The following is identical for a two-dimension array:

T$=OBJECT'TYPE$()
T$=OBJECT'TYPE$(0, 0)

Unlike the variant object though, the TYPE property is read only. If conversion of a data type is required, then the use of a variant object is mandatory. See *VARIANT above.

UBOUND(dimension)

(Method Call) Returns the upper boundary for the dimension in the array. This will be one number less than the total count of elements in the dimension:

Example:

0 ... Element_Count -1