Upgrade Guide


Appendix C. Obsolete Functions

The functions in this section were made obsolete in either the Panther, JAM or Prolifics products.

Function Name Made Obsolete In Description

sm_achg

JAM 7

sm_apply_prop

JAM 7

sm_ascroll

JAM 7

sm_base_fldno

JAM 7

sm_bitop

JAM 7

sm_chg_attr

JAM 7

sm_com_call_method

Panther 4.2

Calls a method of a COM component (Recommended alternate: sm_obj_call)

sm_com_get_prop

Panther 4.2

Gets a COM component property setting (Recommended alternate: sm_obj_get_property)

sm_com_log

Panther 4.2

Writes a message to a log file (Recommended alternate: sm_log)

sm_com_onerror

Panther 4.2

Installs an error handler (Recommended alternate: sm_obj_onerror)

sm_com_set_prop

Panther 4.2

Sets a property for a COM component (Recommended alternate: sm_obj_set_property)

sm_com_obj_create

Panther 4.2

Instantiates a COM component (Recommended alternate: sm_obj_create)

sm_com_obj_destroy

Panther 4.2

Destroys a COM component (Recommended alternate: sm_obj_delete_id)

sm_com_raise_exception

Panther 4.2

Sends an error code back to the client (Recommended alternate: sm_raise_exception)

sm_com_receive_args

Panther 4.2

Receives a list of in and in/out parameters for a method (Recommended alternate: sm_receive_args)

sm_com_return_args

Panther 4.2

Returns a list of in/out and out parameters for a method (Recommended alternate: sm_return_args)

sm_create_id

JAM 7

sm_destroy_id

JAM 7

sm_finquire

JAM 7

sm_fldno

JAM 7

sm_fldno

JAM 7

sm_fset

JAM 7

sm_ftype

JAM 7

sm_getcurno

JAM 7

sm_get_prop

JAM 7

sm_gp_inquire

JAM 7

sm_iselected

JAM 7

sm_n_bld_fldno

JAM 7

sm_length

JAM 7

sm_max_occur

JAM 7

sm_name

JAM 7

sm_novalbit

JAM 7

sm_num_occurs

JAM 7

sm_oshift

JAM 7

sm_prop_errno

JAM 7

sm_protect

JAM 7

sm_query_msg

JAM 7

sm_rscroll

JAM 7

sm_sc_max

JAM 7

sm_set_prop

JAM 7

sm_sibling

JAM 7

sm_size_of_array

JAM 7

sm_t_scroll

JAM 7

sm_t_shift

JAM 7

sm_unprotect

JAM 7

sm_viewport

JAM 7


sm_com_call_method

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 for COM 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.


Environment

Windows, Web

Scope

Client

Returns

On Windows platforms:

On UNIX platforms for ActiveX controls:

Description

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.

Example

// 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")
return
proc 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

See Also

sm_obj_call

sm_com_get_prop

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_create for COM objects, sm_prop_id for ActiveX controls.

prop
The designated COM property. For indexed properties, use brackets to specify the occurrence.

Environment

Windows, Web

Scope

Client

Returns

Description

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.

Example

#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]" );
}

See Also

sm_obj_get_property

sm_com_log

Writes a message to an error log

int sm_com_log(char *msg);

msg
Message to be printed to the log.

Environment

Windows

Scope

Server

Description

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.

See Also

sm_log

sm_com_obj_create

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.

Environment

Windows

Scope

Client

Returns

Description

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 the IDispatch 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.

Example

//The following JPL procedures create a variable 
// and instantiate the control.

vars id

proc entry
id = sm_com_obj_create("cCustomers")
return

See Also

sm_obj_create

sm_com_obj_destroy

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.


Environment

Windows

Scope

Client

Returns

Description

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 and font (but not tree):

call sm_com_obj_destroy (nodes, 1)

To destroy the COM component tree and all derived components (node and font):

call sm_com_obj_destroy (tree, 1)

Example

// This JPL procedure destroys the component
// referenced by the variable objID on screen exit.

proc exit
{
call sm_com_obj_destroy (objID, 1)
}

See Also

sm_obj_delete_id

sm_com_onerror

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

Environment

Windows

Scope

Client

Description

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

Example

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

See Also

sm_obj_onerror

sm_com_raise_exception

Sends an error code back to the client

int sm_com_raise_exception(int error);

error
Error code to be returned to the client.

Environment

Windows

Scope

Server

Description

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; see winerror.h. Usage of this function is no longer recommended; use sm_raise_exception instead to ensure component portability.

See Also

sm_raise_exception

sm_com_receive_args

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.

Environment

Windows

Scope

Server

Returns

Description

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; use

sm_receive_args instead to ensure component portability.

Example

See the example under the JPL verb receive_args.

See Also

sm_receive_args

sm_com_return_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.

Environment

Windows

Scope

Server

Returns

Description

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.

Example

See the example under the JPL verb receive_args.

See Also

sm_return_args

sm_com_set_prop

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_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.


Environment

Windows, Web

Scope

Client

Returns

On Windows platforms:

On UNIX platforms:

Description

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)

Example

#include <smuprapi.h>
int id;
int retcode;

{
id = sm_prop_id( "spinner" );
retcode = sm_com_set_prop ( id, "Value", "40" );
}

See Also

sm_obj_set_property