CREATE
The CREATE statement is used to instantiate a distributed object and return an object reference. KCML will act as a client to the object and can call methods exposed by it. Except for client objects there is no event or callback mechanism. No mechanism is provided to access properties or attributes directly though generally this can be done with accessor functions.
The second form is used only by the dynamic DEFQUERY object. This allows an optional list of positional parameter variables that are substituted into the XML query definition where the placeholders $1, $2 etc. are found.
The type of object to create is specified with strexpr1 and must be one of the following case insensitive strings
| strexpr1 | Standard | Object is accessed | Server OS |
|---|---|---|---|
| serverCOM | COM | by server | Windows only |
| clientCOM | COM | by client | Unix or Windows |
| SOAP | SOAP | by server | Unix or Windows |
| Dynamic | KIDL | by server | Unix or Windows |
There will be at least one, and maybe more, strings after the initial strexp1 to specify the class of object and any further information required. The number and meaning depends on the type of object.
Creating COM objects
For COM objects the alpha expression strexpr2 on the right must be either a ProgId or a string ClassId defining the object in the appropriate registry. For example
OBJECT Doc = CREATE "ClientCOM","Word.Basic"
OBJECT rsTable = CREATE "ServerCOM", "ADODB.Recordset"
OBJECT rsTable = CREATE "ServerCOM","{00000535-0000-0010-8000-00AA006D2EA4}"
OBJECT Doc = CREATE "ClientCOM","Word.Basic", DEFEVENT WordEvents
See the page on COM automation for more details about using COM objects in a KCML program.
Events are specified using the optional DEFEVENT clause to specify an event object. Individual event handlers are then declared using DEFEVENT. A current limitation is that each CREATE object clause must name a different event object if using the DEFEVENT clause.
Creating SOAP objects
For SOAP objects strexpr2 represents the URL of the WSDL file describing the SOAP service. WSDL is a schema language that describes SOAP services and the owner of the service should publish a WSDL schema describing the services on the site. The URL can be of type http:// or file://. If the string does not start with one of these prefixes it will be assumed to be a local file. KCML will attempt to connect to that server and fetch the WSDL file and use it to get the details it need to make procedure calls.
An optional further string strexpr3 can be used to specify options as a comma separated list of keyword and value pairs. The keywords themselves are case insensitive though their value may not be. Boolean options can be specified using 0, F or N for false and 1, T or Y for true. Most of this options can be stored in a seperate XML file. See here.
The KCML SOAP client does support SSL/TLS encryption natively by using the https protocol prefix in the endpoint URL. It can also use an SSL tunnel like stunnel to access an SSL site. This might run on the same server or on a different machine in your local network. The tunnel will listen out on one address and if connected to locally will open an SSL connection to the remote end point as specified in the tunnel configuration. The URL for the WSDL and the end points specified in the WSDL can be transparently remapped using the TUNNEL option.
| Keyword | Purpose | Example |
|---|---|---|
| CONFIG | Specify configuration file. See CONFIG. | |
| AUTH | Basic authentication in the form username:password that may be required by the SOAP end point. | AUTH=soapuser:zrma78 |
| PROXY | The location of an HTTP proxy server and optionally any authentication required. Format is [user[:password]@]proxyserver[:port]. Not all proxy servers require a user and password | PROXY=proxy:8080 |
| TUNNEL | Allows mapping of a server and port combination to another server and port specified as TUNNEL=old|new. Port numbers are optional and if omitted default to http i.e. 80. This can be used to redirect the SOAP request through an SSL tunnel. Both the WSDL URL and any endpoints in the WSDL are remapped. There may be more than one TUNNEL option specified. | TUNNEL=www.somesite.com:https|localhost:4001 |
| RETRY | Integer value which specifies the number of times the client should retry a method call in the event of getting no response from the server. NOTE Retry can have unexpected side effects at the server. For example if the request increments a data value at the server before it fails, the retry could cause the data value to be incremented more then once. | RETRY=3 |
| DOC | (Deprecated) Use LIT=Y. Boolean flag which if set to 1 specifies that the SOAP client should operate in document mode. On method calls, in this mode, single scalar strings are passed to and from the server. The strings represent documents that the user is responsible for creating and decoding of received documents. KCML provides only the transport and error handling. | DOC=Y |
| LIT | Boolean flag which if set to 1 specifies that the SOAP client should operate in literal document mode. On method calls, in this mode, single scalar strings are passed to and from the server. The strings represent documents that the user is responsible for creating and decoding of received documents. KCML provides only the transport and error handling. | LIT=Y |
| TOCONN | Specify a timeout in milliseconds for the initial connect to the server. If not set then the default TCP timeout will be used. | |
| TOREAD | Specify a timeout in milliseconds for the each request to the server. If not set then the client will block indefinitely. | |
| VERB | If the WSDL exposes more HTTP bindings that use methods other than the default POST, you can select such bindings by specifying the VERB they use, e.g. VERB=GET. | |
| WSS | Specifiy OASIS Web Services Security options. See here. | |
| INTERFACE | Allows you to manually specifiy the service/port to use. | |
| TRACEFILE | Create a trace file (this option was added to KCML 07.21.01.25256 and KCML 06.20.99.25256 as an alternative to having to use a config file). |
Creating Dynamic objects
Dynamic objects are shared libraries which expose interfaces described by a KCML specific XML interface description language. Some examples available on the KCML website are the Xerces XML DOM parser and the Xalan XSLT transformer.
The required strexp2 is the name of the shared library. It is not necessary to specify any extension as .DLL will be assumed for Windows, .so for Unix and .sl for HP-UX. The libraries are installed with KCML and will reside in the same directory as KCML. This directory then needs to be added to the system's search path for shared libraries by setting the appropriate environment variable:
| Operating System | Variable |
|---|---|
| AIX | LIBPATH |
| HP-UX | SHLIB_PATH |
| All others | LD_LIBRARY_PATH |
The Xerces dynamic object is not available on all operating systems that support KCML 06.20, see System Requirements.
To use dynamic objects on older Unix platforms (e.g. Unixware7.1) it may be necessary to set the USEMALLOC environment variable before running KCML. This tells KCML to allocate memory in a way that will be consistent with the methods used in the library. This happens automatically on NT systems and this environment variable is unnecessary. CREATE will throw an O30.18 error on Unix platforms that require this setting if the variable is not set.
There are some examples of using Xerces DOM here
Syntax examples:
OBJECT x = CREATE "clientCOM", "Excel.Application"
OBJECT c = CREATE "Corba", "Add"
OBJECT s = CREATE "SOAP", "http://services.xmethods.net/soap/urn:xmethods-CurrencyExchange.wsdl", "PROXY=fred:[email protected]:8080"
OBJECT x = CREATE "Dynamic", "dyndom"
There are also some built in dynamic objects such as the one used by DEFQUERY, LDAP and a simple list object.