webMethods Integration Server C/C++ API Documentation

webMethods Integration Server C/C++ API Documentation

Introduction

C/C++ API are based on the Java Native Interface(JNI) - these APIs wrap the JNI as a convenience to working with the core Java APIs. However, the JNI may be used directly in place of, or in conjunction with these APIs. Since these APIs provide with wrappers over the core Java APIs, please consult those APIs directly to better understand their capabilities.

C/C++ Service API

C/C++ Service APIs are used exclusively by C Services. These APIs allow the service to invoke other services using the invokeWmService() or invokeWmServiceThreaded() function. Simply synthesize the required input record and pass along with the folder name and service name. For backward compatibility, the session record is used in invokeWmService(). However, it is no longer needed and therefore not used in invokeWmServiceThreaded(). To retrieve the results from the threaded invoke, you need to call getWmServiceThreadData(). Also note that threaded invoke creates a return context which must be freed with freeWmSvrContext() when no longer needed. However, the standard server context passed in to your service is created (and freed) in the code generation service template and should therefore not be explicitly freed.

These APIs also allow you to handle errors/exceptions in C Services. You may log an error message to Integration Server's default log file with logWmServiceError(). You may also create an error record with throwWmServiceErrorMsg() or throwWmServiceError().

C/C++ Client API

C/C++ Client APIs are used to implement C clients that invoke IS Services. It uses JNI to wrap the Java-based APIs implemented as Context (for normal invocations) and TContext (for guaranteed delivery or transactional invocations).

Normally, you will first call initWmClient() to initialize the JNI environment. However, if you need to modify the standard JVM arguments, or pass properties to the JVM, you will need to do so before initialization. To set JVM options, construct your own JDK1_1InitArgs (see jni.h) and set the external variable wm_jvm_args. To pass properties, call initJVM1_1Args(char** properties) with a zero-terminated array of strings in "name=value" form; Java classpath is set directly from the CLASSPATH environment variable. When done make sure to call shutdownWmClient().

All API calls are tagged with the type of context that is being used. Note that the TContext shares some calls with the normal client context - in particular setting rpc types, connection attributes, and security credentials. Also note that the transactional calls (Tx) can only be used with TContext as they all require a transaction id(WmTid) whereas the synchronous and asynchronus calls are only used with a normal context. When using the TContext from a client, you will also have to initialize the transaction manager, as well as shut it down when you are done. If you intend to share contexts between threads, make sure to clone your context with cloneWmContext(). For TContext, make sure to call initWMTContext() from same master thread after calling initWMClient().

Utilities API

Utilities API are used by C/C++ Service and C/C++ Client. These are listed below:

Record API
Record APIs allow you to handle WmRecord - the primary structures for all service invocations. Virtually all API functions take one or more WmRecord as arguments and return a WmRecord (or a char *).
Four types of structures are implemented as WmRecord: records, record arrays, string arrays, and string tables. (Strings are translated directly to and from c 'char *').

The webMethods Integration Server invokes a service with an input record. The input record is the 'root' of all input arguments. Use the getWm{type}() functions to extract input arguments; For nested records, multiple calls are needed. Use the getWm{type}ByIndex() to extract record and string arrays, and getWm{type}ByIndices() to extract string tables. To get array and table sizes, use the appropriate function.
The service returns an output record. Use setWm{type}() functions to insert output arguments. To create nested records, use the newWm{type}() functions. For array and table records, insert values using setWm{type}ByIdx() and setWm{type}ByIndices().

Remember to deallocate WmRecord structure with freeWmRec() when no longer used.

Following example routine shows how to create a string array record and how to set and retrieve data from it.
```
	int Test() {

	    	WmRecord *myRec;

	    	WmContext *con;

	    	char *yesterday, *today, *tomorrow;



	    	con = newWmClientContext(); //create a new client context



		myRec = newWmStringArray(con, 3); //Create a string array

		if (myRec == 0)

			return -1; 	//error occurs, return



		//set data to the string array

		if (!setWmStringByIdx(myRec, 0, "Yesterday, Oct 13, 1999"))

			return -1;      //error occurs, return



		if (!setWmStringByIdx(myRec, 1, "Today, Oct 14, 1999"))

			return -1;      //error occurs, return



		if (!setWmStringByIdx(myRec, 2, "Tomorrow, Oct 13, 1999"))

			return -1;      //error occurs, return



		//retrieve data back from the string array and display



 		fprintf(stderr, "Data retrieved\n");

		yesterday = getWmStringByIdx(myRec,0);

		fprintf(stderr, "Yesterday: %s\n", yesterday);



		today = getWmStringByIdx(myRec,1);

		fprintf(stderr, "Today: %s\n", today);



		tomorrow = getWmStringByIdx(myRec,2);

		fprintf(stderr, "Tomorrow: %s\n", tomorrow);



		//do clean up

		freeWmRec(&myRec);

		freeWmContext(&con);

		freeWmString(&yesterday);

		freeWmString(&today);

		freeWmString(&tomorrow);



		return 1;

	}

	
```
String API
String APIs allow you to work with records other than your service's input and output record. The code generator synthesizes field names for all the records used by your service with makeWmName(). You may also use it directly to create the jstring global references needed to name the fields of your records. Also when done remember to clean up all retrieved references with freeWmName() for objects and freeWmString() for strings.
Support API
Suuport APIs are several support calls. They can be used to initialize C/C++ APIs and client context. Also if you need to process exception information directly, you can retrieve the error type and error message with getWmErrType() and getWmErrMsg().

webM-IS-CAPI-910-20160415