Upgrade Guide |
The functions in this section were made obsolete in either the Panther, JAM or Prolifics products.
Calls a method of a COM component or ActiveX widget
char
*sm_com_call_method
(char *method_spec
);
method_spec
- A string specifying the method and its parameters consisting of the following:
object_id
- An integer handle identifying the
COM
component whose method you want to call. The handle is returned through sm_com_obj_create forCOM
objects, sm_prop_id for ActiveX controls.method
- The name of the method. Periods are allowed as part of the method specification, as in:
Application.Quit
p1, p2, ...
- (Optional) A comma-delimited list of the method's parameters. Unused parameters are allowed to be omitted, as in:
sm_com_call_method ("TreeView, \"Add\" , , , , 'First node'")If the COM object's typelib cannot be used to determine the parameter's type,
@obj can
be used to specify the object ID of the parameter. Generally, this syntax will not be necessary.
Windows, Web
Client
On Windows platforms:
- The value returned by the COM component, converted to a string.
On UNIX platforms for ActiveX controls:
- 0 Success.
sm_com_call_method
calls methods that are part of COM components' inter faces. Usage of this function is no longer recommended; use sm_obj_call instead to ensure component portability.To find which methods are available, refer to the documentation supplied with the COM component, use the Panther AxView utility, or use the ViewComponent Interface in the editor for service components.
This function returns a string; the COM component itself can return different types of data.
If you get a "type mismatch" error, refer to the component documentation and check that all the parameters are of the correct type.
@obj
may be needed if any of the parameters must be passed as objects.
// This C function calls the InsertNode method of the
// ActiveX treeview control.
char method[100];
char *parent;
char *child;
int id;
id = sm_prop_id ( "treeview" );
sprintf( method, "InsertNode(%s, \"Child node\"", parent) );
child = sm_com_call_method( id, method );// This is the JPL call for this method. Single quotation
// marks are used surrounding the method in order to pass
// double quotation marks to the method itself.
vars parent
vars child
child = sm_com_call_method \
( treeview->id, "InsertNode", :parent, "Child node")// These JPL procedures instantiate the cCustomers COM
// component and call its GetCustomer method.
vars id
proc entry
id = sm_com_obj_create("cCustomers")
returnproc GetCustomer
call sm_com_call_method(id, "GetCustomer", \
CompanyName, CustomerID, Phone)
return// This JPL procedure closes down Microsoft Excel
// that is running as a COM component.
proc close
call sm_com_call_method(ExcelID, "Application.Quit")
return
sm_obj_call
Gets the value of a property from a COM component
char *sm_com_get_prop(intobj_id
, char *prop
);
- obj_id
- An integer handle that identifies the COM component whose property you want to get. The handle is returned through
sm_com_obj_create
for COM objects, sm_prop_id for ActiveX controls.- prop
- The designated COM property. For indexed properties, use brackets to specify the occurrence.
Windows, Web
Client
- The property's current value, returned as a string.
sm_com_get_prop
retrieves property values from a COM component. Usage of this function is no longer recommended; use sm_obj_get_property instead to ensure component portability.
#include <smuprapi.h>
{
id = sm_prop_id( "spinner" );
value = sm_com_get_prop ( id, "prop" );
}// For an indexed property:
{
id = sm_prop_id( "spinner" );
value = sm_com_get_prop ( id, "prop[5]" );
}
sm_obj_get_property
Writes a message to an error log
int sm_com_log(char *msg
);
msg
- Message to be printed to the log.
Windows
Server
sm_com_log
writes messages to an error log named server.log in the COM component's application directory. Usage of this function is no longer recommended; use sm_log instead to ensure component portability.When this file is activated, in addition to the messages logged with this function, messages are automatically logged when service components are created or destroyed. All messages that would normally appear on the message line or message window are also logged.
During development you should always enable error logging by creating server.log. In production server.log should not be present as logging is a substantial load on the system.server.log must exist in the application directory for logging to take place.
sm_log
Instantiates a COM component
int sm_com_obj_create(char *name
);
int sm_c_com_obj_create(char *clsid
);
clsid
- Specify the
CLSID
(Class ID) of the COM component.- name
- Specify the name of the COM component.
Windows
Client
- 1 Success: the component's object ID.
sm_com_obj_create
instantiates COM components. Usage of this function is no longer recommended; use sm_obj_create instead to ensure component portability. The COM component must support theIDispatch
interface (the "automation interface") so that properties can be set and methods can be called. For returns greater than zero, the call has succeeded and the object ID will be used to access the component.For ActiveX controls, you do not call this function. The ActiveX container in the Panther editor specifies the name and
CLSID
of the component, and makes this call on your behalf.
//The following JPL procedures create a variable
// and instantiate the control.
vars id
proc entry
id = sm_com_obj_create("cCustomers")
return
sm_obj_create
Removes a COM component
int sm_com_obj_destroy(intobj_id
, int force);
obj_id
- An integer handle that identifies the COM component you want to delete, obtained through
sm_com_obj_create
.force
- Specify the type of removal.
If force is zero, only the specified component will be destroyed. Any components obtained as values of a property of the component or returned by the component's method calls will be retained.
If force is zero, then these derived components will also be destroyed.
Windows
Client
- 0 Always.
sm_com_obj_destroy
removes COM components. Usage of this function is no longer recommended; use sm_obj_delete_id instead to ensure component portability. If force is zero, only the specified COM component will be destroyed. Any components obtained as values of a component property or returned by method calls will be retained. If force is non-zero, then these derived components will also be destroyed.the COM object will be removed. Otherwise, the COM component will continue to exist until the last of the dispatch interfaces is deleted by a call to
sm_com_obj_destroy
.For example, the following JPL code creates a treeview control and calls its properties for nodes, node and font:
vars tree, nodes, node, font
tree = sm_com_obj_create ("treeview")
nodes = sm_com_get_prop (tree, "Nodes")
node = sm_com_get_prop (tree, "Item[1]")
font = sm_com_get_prop (node, "FontName")To destroy the COM component
tree
but not nodes, node or font:call sm_com_obj_destroy (tree, 0)To destroy
node
andfont
(but nottree
):call sm_com_obj_destroy (nodes, 1)To destroy the COM component
tree
and all derived components (node
andfont
):call sm_com_obj_destroy (tree, 1)
// This JPL procedure destroys the component
// referenced by the variable objID on screen exit.
proc exit
{
call sm_com_obj_destroy (objID, 1)
}
sm_obj_delete_id
Installs an error handler
void sm_com_onerror(char *handler
);
handler
- The name of the error handler. This C function or JPL procedure will be passed three parameters:
errorNumber
- The error number as an integer. Use this value to test for errors.
errorHexadecimal
- The error number as a string in hexadecimal format, as in
0x80000307
. (This parameter is displayed by the default error handler.)errorMessage
- The text description of the error. (This parameter is displayed by the default error handler.)
Windows
Client
sm_com_onerror
specifies the error handler that will be called if a COM operation returns a negative exception. The return from the handler is ignored. Usage of this function is no longer recommended; use sm_obj_onerror instead to ensure component portability.An error handler will only be fired on negative exception codes; use
sm_com_result
to retrieve positive exceptions.If you do not want an error handler, you must install your own error handler that simple returns.
To restore the default error handler, use
sm_com_onerror(0)
.
// This JPL module specifies an error handler
// similar to the default error handler.
call sm_com_onerror (handler)
proc handler (errnum, errhex, errmsg)
msg emsg "COM Error: " errhex " " errmsg
return
sm_obj_onerror
Sends an error code back to the client
int sm_com_raise_exception(interror
);
- error
- Error code to be returned to the client.
Windows
Server
sm_com_raise_exception
sends an error code back to the client. The client's error handler then decides what to do based on the value sent. Microsoft defines some conventional exception codes for use in COM programming; seewinerror.h
. Usage of this function is no longer recommended; use sm_raise_exception instead to ensure component portability.
sm_raise_exception
Receives a list of in and in/out parameters for a method
int sm_com_receive_args(char *text
);
- text
- List of in/out and out parameters, separated by commas, of field names and global JPL variables.
Windows
Server
- 0 Not an COM method.
sm_com_receive_args
receives a list of arguments, and writes them to the in and in/out parameters of a method. The arguments are written to the parameters in the order received. Usage of this function is no longer recommended; usesm_receive_args instead to ensure component portability.
See the example under the JPL verb receive_args.
sm_receive_args
Returns a method's in/out and out parameters
int sm_com_return_args(char *text
);
text
- List of in/out and out parameters, separated by commas.
Windows
Server
- 0 Not an COM method.
sm_com_return_args
is passed a list of arguments to be written to the in/out and out parameters of a method. Usage of this function is no longer recommended; use sm_return_args instead to ensure component portability.
See the example under the JPL verb receive_args.
sm_return_args
Sets the value of a property of a COM component
int sm_com_set_prop(intobj_id
, char *prop
, char *val
);
obj_id
- An integer handle that identifies the COM component whose property you want to set. The handle is returned through
sm_com_obj_create
for COM objects, sm_prop_id for ActiveX controls.prop
- The designated property. Refer to the Description for information about available properties.
val
- The value to set for the specified property or property item. Panther converts the value to the type expected by the component.
If the value needs to be sent as an object ID,
@obj()
can be used to specify the object ID.
Windows, Web
Client
On Windows platforms:
- The
HRESULT
from the most recent COM component function call. Refer towinerror.h
for values; 0 is the value forS_OK
.
- 0 Success.
sm_com_set_prop
sets the value of the specified COM component property. Usage of this function is no longer recommended; use sm_obj_set_property instead to ensure component portability.When setting properties for ActiveX controls, this function can be used on all platforms for
CLSID
and Control Name and only on Windows for properties of the ActiveX control itself.The properties for a COM components can be determined through the AxView utility, the Properties window for ActiveX controls, and the Component Interface window for service components.
In property specifications, periods are allowed. For example:
sm_com_set_prop (Excel_Sheet,
"ActiveSheet.Cells(1,1).Value", text)For indexed properties, use brackets to specify the occurrence. For example:
sm_com_set_prop (id, "prop[5]", value)
#include <smuprapi.h>
int id;
int retcode;
{
id = sm_prop_id( "spinner" );
retcode = sm_com_set_prop ( id, "Value", "40" );
}
sm_obj_set_property