| | Upgrade Guide |
The functions in this section were made obsolete in either the Panther, JAM or Prolifics products. Some of the deprecated functions are unofficially documented at:
http://www.prolifics.com/spider/resdocs/jam5/jam5-syntax/jam5-intro.html
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
COMcomponent whose method you want to call. The handle is returned throughsm_com_obj_createforCOMobjects,sm_prop_idfor ActiveX controls.method- The name of the method. Periods are allowed as part of the method specification, as in:
Application.Quitp1, 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
typelibcannot be used to determine the parameter's type,@obj canbe used to specify the object ID of the parameter. Generally, this syntax will not be necessary. For an example of its usage, see the example undersm_com_load_picture.
32-bit 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_methodcalls methods that are part of COM components' inter faces. Usage of this function is no longer recommended; usesm_obj_callinstead to ensure component portability.To find which methods are available, refer to the documentation supplied with the COM component, use the Prolifics Axview utility, or use the View
Component 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.
@objmay 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(int obj_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_createfor COM objects,sm_prop_idfor ActiveX controls.prop- The designated COM property. For indexed properties, use brackets to specify the occurrence.
32-bit Windows, Web
Client
- The property's current value, returned as a string.
sm_com_get_propretrieves property values from a COM component. Usage of this function is no longer recommended; usesm_obj_get_propertyinstead 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.
32-bit Windows
Server
sm_com_logwrites messages to an error log named server.log in the COM component's application directory. Usage of this function is no longer recommended; usesm_loginstead 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.
32-bit Windows
Client
- 1 Success: the component's object ID.
sm_com_obj_createinstantiates COM components. Usage of this function is no longer recommended; usesm_obj_createinstead to ensure component portability. The COM component must support theIDispatchinterface (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 Prolifics editor specifies the name and
CLSIDof 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(int obj_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.
32-bit Windows
Client
- 0 Always.
sm_com_obj_destroyremoves COM components. Usage of this function is no longer recommended; usesm_obj_delete_idinstead 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 nodes, node and font (but not tree):
call sm_com_obj_destroy (nodes, 1)To destroy the COM component (tree) and all derived components (nodes, node and font):
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.
errorHexidecimal- 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.)
32-bit Windows
Client
sm_com_onerrorspecifies 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; usesm_obj_onerrorinstead to ensure component portability.An error handler will only be fired on negative exception codes; use
sm_com_resultto 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(int error);
error- Error code to be returned to the client.
32-bit Windows
Server
sm_com_raise_exceptionsends 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; see winer ror.h. Usage of this function is no longer recommended; usesm_raise_exceptioninstead 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.
32-bit Windows
Server
- 0 Not an COM method.
sm_com_receive_argsreceives 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; use
sm_receive_argsinstead 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.
32-bit Windows
Server
- 0 Not an COM method.
sm_com_return_argsis 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; usesm_return_argsinstead 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 ( int obj_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_createfor COM objects,sm_prop_idfor 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. Prolifics 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. For an example of its usage, see the example undersm_com_load_picture.
32-bit Windows, Web
Client
On Windows platforms:
- The
HRESULTfrom the most recent COM component function call. Refer towinerror.hfor values; 0 is the value forS_OK.
- 0 Success.
sm_com_set_propsets the value of the specified COM component property. Usage of this function is no longer recommended; usesm_obj_set_propertyinstead to ensure component portability.When setting properties for ActiveX controls, this function can be used on all platforms for
CLSIDand 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