C++ Native Functions: `com.ibm.streamsx.store.distributed`

Specialized toolkits - release 4.3.1.0-i20200220 > com.ibm.streamsx.dps 4.1.1 > com.ibm.streamsx.store.distributed > C++ Native Functions

This page documents native functions that can be invoked from SPL, including the SPL interfaces that can be used to invoke each of the native functions.

Functions

public stateful void dpsBase64Decode(rstring str, mutable rstring decodedResultStr)

Base64 decode a given string.

Parameters

str

the string to decode

decodedResultStr

mutable parameter that will contain the decoded result.


rstring base64EncodedString = "bXlEQlN0b3JlMQ==";
mutable rstring base64DecodedString = "";
// base64DecodedString will have a value o:f "myDBStore1"
dpsBase64Decode(rowKey, base64DecodedString);

public stateful void dpsBase64Encode(rstring str, mutable rstring encodedResultStr)

Base64 encode a given string.

Parameters

str

the string to encode

encodedResultStr

mutable parameter that will contain the encoded result.


mutable list<rstring>[5] cn = [];
dpsBase64Encode("cf1:Company", cn[0]);
dpsBase64Encode("IBM", cn[1]);
dpsBase64Encode("Microsoft", cn[2]);
dpsBase64Encode("Amazon", cn[3]);
dpsBase64Encode("Google", cn[4]);

//the cn array will now contain the decoded values

public stateful uint64 dpsBeginIteration(uint64 store, mutable uint64 err)

This function gets a store iterator that can be used to iterate over all the key-value pairs in a given store id. No other operations that can modify the state can be used until after dpsEndIteration() is called for this same store. Once a store iterator is obtained, it must be released by calling dpsEndIteration() once the iterator is no longer needed. See the documentation for dpsGetNext() for a complete example of how to use the iterator.

Parameters

store: handle of the store for which an iterator is needed.
err: Contains the error code describing the result of the function call. Will be '0' if no error occurred, otherwise will have a non-zero value.

Returns

an value representing an iterator that can be used with the two other store iteration functions, dpsGetNext() and dpsEndIteration().

public stateful void dpsClear(uint64 store, mutable uint64 err)

Clear the given store.

Parameters

store: the handle of the store to clear
err: Contains the error code describing the result of the operation. Will be '0' if the store was successfully emptied, otherwise will have a non-zero value.

<any T1, any T2> public stateful uint64 dpsCreateOrGetStore(rstring name, T1 key, T2 value, mutable uint64 err)

Create a new process store with a given name or simply return its handle it already exists.

Parameters

name: the name of the store to retrieve, or to create if it doesn't already exist.
key: this variable should be provided to indicate the type of the key to use in the store.
value: this variable indicates the type of the values in the store.
err: mutable variable provided that will contain the error code, if an error occurs. Will be set to '0' if the store was created successfully, or a non-zero value otherwise.

Returns

the process store handle of the created store. If an error occurs, the return value of this function is undefined. It is recommended that the store id is cached in your application.


   mutable uint64 err = 0ul;
   mutable uint64 s = 0ul;
   rstring dummyRstring = "";
   uint32 dummyUint32 = 0u;
   s = dpsCreateOrGetStore("myDBStore1", dummyRstring, dummyUint32, err);

   if (err != 0ul) {
         uint64 rc = dpsGetLastStoreErrorCode;
         rstring msg = dpsGetLastStoreErrorString();
         printStringLn("Unexpected error in creating a store named myDBStore1: rc = " + (rstring)rc + ", msg = " + msg);
   }

<any T1, any T2> public stateful uint64 dpsCreateStore(rstring name, T1 key, T2 value, mutable uint64 err)

Create a new process store with a given name.

Parameters

name: the name of the store to create
key: this variable should be provided to indicate the type of the key to use in the store.
value: this variable indicates the type of the values in the store.
err: mutable variable provided that will contain the error code, if an error occurs. Will be set to '0' if the store was created successfully, or a non-zero value otherwise.

Returns

the process store handle, if created. It is advisable to cache the store id in your application. The return value will be '0' if a process store with the same name already exists, and undefined if there is an error.


  mutable uint64 err = 0ul;
  mutable uint64 s = 0ul;
  rstring dummyRstring = "";
  uint32 dummyUint32 = 0u;
  s = dpsCreateStore("myDBStore1", dummyRstring, dummyUint32, err);

  if (err != 0ul) {
         uint64 rc = dpsGetLastStoreErrorCode;
         rstring msg = dpsGetLastStoreErrorString();
         printStringLn("Unexpected error in creating a store named myDBStore1: rc = " + (rstring)rc + ", msg = " + msg);
   }

<any T1, any T2> public stateful void dpsDeserialize(uint64 store, blob data, T1 dummyKey, T2 dummyValue, mutable uint64 err)

This function deserializes a given blob containing one or more serialized key-value pairs. The specified store will be populated with the deserialized data. This technique can be used to copy the contents of one store into another.

Parameters

store

the handle of the store into which the deserialized data will be saved.

data

the data to deserialize and save into the specified store.

dummyKey

variable indicating the type of the keys in the store

dummyValue

variable indicating the type of the values in the store

err

a mutable variable that will contain the error code describing the result of the deserialization. Will be '0' if deserialization was successful, and a non-zero value otherwise.


mutable uint64 err = 0ul;
rstring dummyRstring = "";
list<rstring> dummyRstringList = ["1", "2"];
mutable blob sData = [];
dpsSerialize(s1, sData, dummyRstring, dummyRstringList, err);

if (err == 0ul) {
   //now deserialize it into another store.
   dpsDeserialize(store2, sData, dummyRstring, dummyRstringList, err);
	
   if (err != 0ul) {
 	//perform error handling using dpsGetLastStoreErrorCode() and dpsGetLastStoreErrorString()
   }

public stateful void dpsEndIteration(uint64 store, uint64 iterator, mutable uint64 err)

This function must be called once all iteration is complete.

Parameters

store: the handle of the store.
iterator: the store iterator id obtained from dpsBeginIteration().
err: Contains the error code. Will be '0' if no error occurs, and a non-zero value otherwise.

public stateful uint64 dpsFindStore(rstring name, mutable uint64 err)

Find a process store given its name.

Parameters

name: The name of the store to look up.
err: This parameter will be set by the function to contain the error code if an error occurs finding the store, and '0' otherwise.

Returns

The process store handle if found, 0 otherwise.

<any T1, any T2> public stateful boolean dpsGet(uint64 store, T1 key, mutable T2 item, mutable uint64 err)

Given a key, retrieves its value from the given store. This function has better performance than dpsGetSafe since it doesn't carry out any safety checks.

Parameters

store: the handle identifying the store in question.
key: the key of the item to look up
item: if the key exists in the store and has a value of the same type, this parameter will be set to the key's value.
err: contains the non-zero error code, if an error occurs, or will have a value of '0'.

Returns

true if the if the operation was successful and the store contains an item with the given key and a matching type, and false if the key-value pair wasn't found.

public stateful void dpsGetDetailsAboutThisMachine(mutable rstring machineName, mutable rstring osVersion, mutable rstring cpuArchitecture)

Get details of the client machine where this operator is running. The machine name, Linux OS version and the CPU architecture (x86 or PPC) will be assigned to the corresponding parameters

Parameters

machineName

the value of this parameter will be set to the machine's name.

osVersion

the value of this parameter will be set to the Linux OS version.

cpuArchitecture

the value of this parameter will be set to the CPU architecture of the client.


rstring dbProductName = dpsGetNoSqlDbProductName();
// Get the details about the machine where this operator is running.
mutable rstring machineName = "", osVersion = "", cpuArchitecture = "";
dpsGetDetailsAboutThisMachine(machineName, osVersion, cpuArchitecture);
// Display the NoSQL DB product name being used 
printStringLn("=====================================================");
printStringLn("Details about this DPS client machine:");
printStringLn("NoSQL key-value store product name: " + dbProductName);
printStringLn("Machine name: " + machineName);
printStringLn("OS version: " + osVersion);
printStringLn("CPU architecture: " + cpuArchitecture);
printStringLn("=====================================================");

public stateful uint64 dpsGetLastErrorCodeTTL()

Get the error code of the last error occurred involving data that was stored with a Time To Live (TTL).


Returns: the error code, or '0' if the last TTL store operation was successful.

public stateful rstring dpsGetLastErrorStringTTL()

Get the description of the last error that occurred involving data stored with a Time To Live (TTL).


Returns: the error message, or the empty string if the last TTL store operation was successful.

public stateful uint64 dpsGetLastStoreErrorCode()

Get the error code of the last store error.


Returns: the error code for the last store operation or '0' if the last operation was successful.

public stateful rstring dpsGetLastStoreErrorString()

Get the description of the last store error.


Returns: the error message, or the empty string if the last data store operation was successful.

<any T1, any T2> public stateful boolean dpsGetNext(uint64 store, uint64 iterator, mutable T1 key, mutable T2 value, mutable uint64 err)

This function is used to get the next key and value of given types in the given store when iterating over all the items in the store. The key and value parameters must be of the same type that was used when the store was originally created using either dpsCreateStore() or dpsCreateOrGetStore().

Parameters

store: the store being iterated over
iterator: the iterator handle, must have been created from a previous call to dpsBeginIteration()
key: a mutable variable to store the key for the current key-value pair in the iteration sequence
value: a mutable variable to store the value for the current key-value pair
err: Contains the error code. Will be '0' if no error occurs, and a non-zero value otherwise.

Returns

true if the next key-value pair was successfully returned, or if store is empty, and false if the end of the iteration was reached. If this method returns false because the store is empty or the end of the iteration was reached, the err parameter will have a value of '0'. If an error occurs, the function will return false and the err parameter will have a non-zero value.


mutable uint64 err = 0ul;
uint64 it = dpsBeginIteration(s, err); 
mutable rstring key = "";
mutable rstring value = "";
					
while (dpsGetNext(s, it, key, value, err)) {
   printStringLn("'" + key + "' => " + value);
}
if (err != 0){ 
	//an error occurred during iteration
}
dpsEndIteration(s, it, err);

public stateful rstring dpsGetNoSqlDbProductName()

Get the name of the NoSQL database product being used.

<any T1, any T2> public stateful boolean dpsGetSafe(uint64 store, T1 key, mutable T2 item, mutable uint64 err)

Given a key, retrieve its value from the given store. Returns true if the store did contain an item with the given key and a matching type, false otherwise. This function is identical to dpsGet, with the exception that it does safety checks and is therefore slower.

public stateful rstring dpsGetSplTypeNameForKey(uint64 store)

Get the SPL type name for the key of a given store id.

Parameters

store: the handle for the store in question.

Returns

the type for the keys in the store.

public stateful rstring dpsGetSplTypeNameForValue(uint64 store)

Get the SPL type name for the value of a given store id.

Parameters

store: the handle for the store in question

Returns

the type for the values in the store

public stateful rstring dpsGetStoreName(uint64 store)

Get the store name for a given store id.

Parameters

store: the store to look up

Returns

the name used to create the store, if it exists.

<any T1, any T2> public stateful boolean dpsGetTTL(T1 key, mutable T2 item, mutable uint64 err)

Get an item that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to look up
item: will receive the saved value for the given key.
err: will receive the error code if an error occurs, or will be set to '0' otherwise.

Returns

true if the global TTL store did contain an item with the given key and a matching type, false otherwise or if an error occurs.


mutable rstring myKey = "", myValue = "";
myKey = "New York";
myValue = "";
mutable uint64 err = 0ul;
boolean res = dpsGetTTL(myKey, myValue, err);
			    
if (res == true) {
   printStringLn("TTL based key-value pair is read successfully. Key=" + 
      myKey + ", Value=" + myValue);
} else {
  //handle error using dpsGetLastErrorCodeTTL() and dpsGetLastErrorStringTTL())
}

<any T1, any T2> public stateful boolean dpsGetTTL(T1 key, mutable T2 item, mutable uint64 err, boolean encodeKey, boolean encodeValue)

Get an item that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to look up (In this API, you can specify whether the key is base64 encoded or not.)
item: will receive the saved value for the given key.
err: will receive the error code if an error occurs, or will be set to '0' otherwise.
encodeKey: set to true if the key shall be base64 encoded, set to false otherwise.
encodeValue: set to true if the value shall be base64 encoded, set to false otherwise.

Returns

true if the global TTL store did contain an item with the given key and a matching type, false otherwise or if an error occurs.


mutable rstring myKey = "", myValue = "";
myKey = "New York";
myValue = "";
mutable uint64 err = 0ul;
    // In this overloaded API, the final parameter can be used to specify whether the 
    // key was originally base64 encoded or not.
boolean res = dpsGetTTL(myKey, myValue, err, true);
			    
if (res == true) {
   printStringLn("TTL based key-value pair is read successfully. Key=" + 
      myKey + ", Value=" + myValue);
} else {
  //handle error using dpsGetLastErrorCodeTTL() and dpsGetLastErrorStringTTL())
}

<any T1> public stateful boolean dpsHas(uint64 store, T1 key, mutable uint64 err)

Check if an item exists in the given store.

Parameters

store: the store handle representing the store to check.
key: the key to look up.
err: contains the error code for this function call. Will be '0' if no error occurs, otherwise will have a non-zero value.

Returns

true if the given store does contain an item with the given key, false otherwise.

<any T1> public stateful boolean dpsHasTTL(T1 key, mutable uint64 err)

Check if an item exists that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to look up. Can be any SPL type.
err: mutable parameter that receives the error code for this function call. If the error code is non-zero, an error has occurred.

Returns

true if a TTL item with the given key exists, false if no such item exists or if an error occurs.


mutable rstring myKey = "";
myKey = "New York";
mutable uint64 err = 0ul;
boolean res = dpsHasTTL(myKey, err);
			    
if (res == true) {
   printStringLn("Unexpected error: TTL based key-value pair 'New York':'Albany' is still present after the TTL expiration.");
} else if (err == 0ul) {
 //no error occurred and the element was not found
   printStringLn("key-value pair 'New York':'Albany' was not found, this may be because it was removed after its TTL expiration.");
}

<any T1> public stateful boolean dpsHasTTL(T1 key, mutable uint64 err, boolean encodeKey)

Check if an item exists that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to look up. Can be any SPL type. (In this API, you can specify whether the key is base64 encoded or not.)
err: mutable parameter that receives the error code for this function call. If the error code is non-zero, an error has occurred.
encodeKey: set to true if the key shall be base64 encoded, set to false otherwise.

Returns

true if a TTL item with the given key exists, false if no such item exists or if an error occurs.


mutable rstring myKey = "";
myKey = "New York";
mutable uint64 err = 0ul;
    // In this overloaded API, the final argument is used to specify whether the key is base64 encoded or not.
boolean res = dpsHasTTL(myKey, err, true);
			    
if (res == true) {
   printStringLn("Unexpected error: TTL based key-value pair 'New York':'Albany' is still present after the TTL expiration.");
} else if (err == 0ul) {
 //no error occurred and the element was not found
   printStringLn("key-value pair 'New York':'Albany' was not found, this may be because it was removed after its TTL expiration.");
}

public stateful boolean dpsIsConnected()

It allows to check the connection status of the back-end data store.


Returns: true if the connection is established, false otherwise.

public stateful void dpsPersist(mutable uint64 err)

Persist any operations involving stores used in this application to disk.

Parameters

err: contains the error code for this function call. Will be '0' if no error occurs and if all write operations received before this function was called have been committed to storage. It also returns '0' if the database does not support this operation. It will be non-zero if an error occurs.

<any T1, any T2> public stateful boolean dpsPut(uint64 store, T1 key, T2 item, mutable uint64 err)

Put a new key-value pair into a store. This function has better performance than dpsPutSafe since no safety checks are done to ensure that there is a valid user created store present. Hence, use the dpsPut() function only when there is a user created store present in the back-end DB infrastructure. If this rule is violated, the back-end infrastructure will have inconsistent data items. The specified key and item must be of the same type as those used to create the store in dpsCreateStore or dpsCreateOrGetStore, otherwise, store operations will produce undesired results.

Parameters

store: The handle specifying the store.
key: The key for the new pair.
item: The value for the new pair. Must be the same type as the value that was provided when the store was created.
err: Will be set to '0' on success, and will be non-zero otherwise.

Returns

If no error occurs, returns true, and false otherwise.


	rstring dummyRstring = "";
	uint32 dummyUint32 = 0u;
	mutable uint64 err = 0ul;
	mutable uint64 dbStore_handle = 0ul;
	dbStore_handle = dpsCreateStore("myDBStore1", dummyRstring, dummyUint32, err);

	//..perform error checks	
	
	mutable uint64 err = 0ul;
	mutable boolean result = true;
	rstring key = "IBM";
	uint32 value = 399;
	err = 0ul;
	result = dpsPut(dbStore_handle, key, value, err);
	
	if (err != 0ul) {
		//use  dpsGetLastStoreErrorCode() and  dpsGetLastStoreErrorString() as needed
	}

<any T1, any T2> public stateful boolean dpsPutSafe(uint64 store, T1 key, T2 item, mutable uint64 err)

Put an item into the given store. This function is identical to dpsPut, however, it performs additional safety checks. As a result, this function will be slower than dpsPut.

Parameters

store: The handle specifying the store.
key: The key for the new pair.
item: The value for the new pair. Must be the same type as the value that was provided when the store was created.
err: Will be set to '0' on success, and will be non-zero otherwise.

Returns

If no error occurs, returns true, and false otherwise.

<any T1, any T2> public stateful boolean dpsPutTTL(T1 key, T2 item, uint32 ttl, mutable uint64 err)

Put an key-value pair with in a TTL (Time To Live in seconds) value into the global area of the back-end data store. The key and value can be any SPL type.

Parameters

key: the key with which to associate the given value
item: the value to associate with the key
ttl: the amount of time, in seconds, this pair will be kept in the global store before it is automatically removed. A value of '0' means that this pair will be in the store indefinitely until manually removed via dpsRemoveTTL.
err: will be set to '0' if the operation was successful, and a non-zero value otherwise.

Returns

true if the operation is successful, false otherwise.


    mutable rstring myKey = "", myValue = "";
myKey = "New York";
myValue = "Albany";
mutable uint64 err = 0ul;
// Put a key-value pair with 5 seconds of TTL.
boolean res = dpsPutTTL(myKey, myValue, 5u, err);
                
if (res == false) {
           //handle error using dpsGetLastErrorCodeTTL() and  dpsGetLastErrorStringTTL());
}

<any T1, any T2> public stateful boolean dpsPutTTL(T1 key, T2 item, uint32 ttl, mutable uint64 err, boolean encodeKey, boolean encodeValue)

Put a key-value pair with in a TTL (Time To Live in seconds) value into the global area of the back-end data store. The key and value can be any SPL type.

Parameters

key: the key with which to associate the given value (In this API, key can be configured to be base64 encoded or not.)
item: the value to associate with the key
ttl: the amount of time, in seconds, this pair will be kept in the global store before it is automatically removed. A value of '0' means that this pair will be in the store indefinitely until manually removed via dpsRemoveTTL.
err: will be set to '0' if the operation was successful, and a non-zero value otherwise.
encodeKey: set to true if the key shall be base64 encoded, set to false otherwise
encodeValue: set to true if the value shall be base64 encoded, set to false otherwise

Returns

true if the operation is successful, false otherwise.


    mutable rstring myKey = "", myValue = "";
myKey = "New York";
myValue = "Albany";
mutable uint64 err = 0ul;
// Put a key-value pair with 5 seconds of TTL.
    // In this overloaded API, 5th and 6th arguments let you configure the key to be base64 encoded or not as well as
    // the value to be serialized or not before storing it in the back-end data store.)
boolean res = dpsPutTTL(myKey, myValue, 5u, err, false, false);
                
if (res == false) {
           //handle error using dpsGetLastErrorCodeTTL() and  dpsGetLastErrorStringTTL());
}

<any T1, any T2> public stateful boolean dpsPutTTL(T1 key, T2 item, uint32 ttl, mutable uint64 err, uint32 storedKeySize, uint32 storedValueSize, boolean encodeKey, boolean encodeValue)

Put a key-value pair with in a TTL (Time To Live in seconds) value into the global area of the back-end data store. The key and value can be any SPL type.

Parameters

key: the key with which to associate the given value (In this API, key can be configured to be base64 encoded or not.)
item: the value to associate with the key
ttl: the amount of time, in seconds, this pair will be kept in the global store before it is automatically removed. A value of '0' means that this pair will be in the store indefinitely until manually removed via dpsRemoveTTL.
err: will be set to '0' if the operation was successful, and a non-zero value otherwise.
storedKeySize: Will be set to the actual storage size occupied by the given key in the back-end data store.
storedValueSize: Will be set to the actual storage size occupied by the given value in the back-end data store.
encodeKey: set to true if the key shall be base64 encoded, set to false otherwise
encodeValue: set to true if the value shall be base64 encoded, set to false otherwise

Returns

true if the operation is successful, false otherwise.


    mutable rstring myKey = "", myValue = "";
myKey = "New York";
myValue = "Albany";
mutable uint64 err = 0ul;
    mutable uint32 storedKeySize = 0u;
    mutable uint32 storedValueSize = 0u;
// Put a key-value pair with 5 seconds of TTL.
    // In this overloaded API, 7th and 8th arguments let you configure the key to be base64 encoded or not as well as
    // the value to be serialized or not before storing it in the back-end data store.)
    // When this API returns successfully, 5th and 6th arguments will have storage size for the key and the value.
boolean res = dpsPutTTL(myKey, myValue, 5u, err, storedKeySize, storedValueSize, false, false);
                
if (res == false) {
           //handle error using dpsGetLastErrorCodeTTL() and  dpsGetLastErrorStringTTL());
}

public stateful boolean dpsReconnect()

It allows to reconnect to the back-end data store. A simple example that waits 5 seconds and tries to reconnect is given below.

Returns

true if the connection could be re-established, false otherwise.


// invoke a DPS function
mutable uint64 err = 0ul;
dpsPut(storeHandle, myKey, myValue, err);	

// check for connection problems, DPS_CONNECTION_ERROR = 102, DL_CONNECTION_ERROR = 501
if(err == 102ul || err == 501ul) {
	// wait 5 seconds 
	block(5.0);
	// retry to connect 
	if (dpsReconnect() == false) {
		// if that was not successful, give up
		abort();
	}
}

<any T1> public stateful boolean dpsRemove(uint64 store, T1 key, mutable uint64 err)

Remove an item from the given store.

Parameters

store: handle of the store from which the key will be removed
key: the key to remove. Can be a valid SPL type.
err: contains the non-zero error code, if an error occurs, or will have a value of '0'.

Returns

true if the store did contain an item with the given key, false otherwise.


mutable uint64 err = 0ul;
mutable boolean result = true;
rstring key = "IBM";
result = dpsRemove(store_id, key, err);

    if (res==true && err==0ul) {
         // remove has succeeded 
    } else {
         //handle error using dpsGetLastStoreErrorCode() and  dpsGetLastStoreErrorString() 
    }

public stateful boolean dpsRemoveStore(uint64 store, mutable uint64 err)

Remove a process store given its handle.

Parameters

store: The process store handle identifying the store to remove.
err: This parameter will contain the error code, if an error occurs. Or will be set '0' if the remove operation was successful.

Returns

true if the store existed and was successfully removed.


mutable boolean result = true;
result = dpsRemoveStore(dbStore_handle, err);

if (err != 0ul) {
	uint64 rc = dpsGetLastStoreErrorCode();
	printStringLn("Unexpected error in removing a store: rc = " + (rstring)rc + ", msg = " + dpsGetLastStoreErrorString());
}

<any T1> public stateful boolean dpsRemoveTTL(T1 key, mutable uint64 err)

Remove an item that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to remove.
err: will receive the error code if an error occurs or will be set to '0' if the remove was successful.

Returns

true if an item with the given key was removed, false otherwise.

<any T1> public stateful boolean dpsRemoveTTL(T1 key, mutable uint64 err, boolean encodeKey)

Remove an item that was stored with a TTL (Time To Live in seconds) value.

Parameters

key: the key to remove. (In this API, you can specify whether the key is base64 encoded or not.)
err: will receive the error code if an error occurs or will be set to '0' if the remove was successful.
encodeKey: set to true if the key shall be base64 encoded, set to false otherwise.

Returns

true if an item with the given key was removed, false otherwise.

public stateful boolean dpsRunDataStoreCommand(list<rstring> cmdList, mutable rstring resultValue, mutable uint64 err)

This is a Redis specific API using which any aribitrary Redis command can be executed by providing the different parts of that Redis command inside a list of strings. This API is vastly better than the other native data store run API shown above. It allows the keys and values to have spaces and quotes. It allows two way command execution by returning the result of the Redis command execution. This suits well for the string based key and values where the user wants to format their own valid Redis command.

public stateful boolean dpsRunDataStoreCommand(rstring cmd, mutable uint64 err)

This function can be used to execute simple arbitrary back-end data store (fire and forget) native commands. This includes any native commands that don't have to fetch and return key-value pairs or return size of the database, like Insert and Delete. However, key and value can only have string types.

Parameters

cmd: the command to execute.
err: a mutable variable that will contain the error code in case an error occurs executing the command. Will be '0' on success and non-zero otherwise.

Returns

true if the one way command was successful, and false otherwise.


// Insert a key-value pair by using the popular Redis set command.
cmd = "set foo bar";
err = 0ul;
res = dpsRunDataStoreCommand(cmd, err);
					  
if (res == true) {
   printStringLn("Running a Redis native command 'set foo bar' worked correctly.");
} else {
   uint64 rc = dpsGetLastStoreErrorCode();
       rstring msg = dpsGetLastStoreErrorString();
   printStringLn("Error in running a Redis native command 'set foo bar'. Error code=" + 
		(rstring)rc + ", msg = " + msg);
}

public stateful boolean dpsRunDataStoreCommand(uint32 cmdType, rstring httpVerb, rstring baseUrl, rstring apiEndpoint, rstring queryParams, rstring jsonRequest, mutable rstring jsonResponse, mutable uint64 err)

This is an advanced function that can be used to execute arbitrary back-end data store two way native commands for database technologies that work with cURL. A HTTP request is sent to the server and the response is saved in the jsonResponse parameter. This function is not supported with Redis. Therefore, this function can only be used with database technologies that are currently not officially supported by Streams, such as HBase. See the samples for this toolkit for a detailed example.

<any T1, any T2> public stateful void dpsSerialize(uint64 store, mutable blob data, T1 dummyKey, T2 dummyValue, mutable uint64 err)

This function serializes all the key-value pairs in a given store id into a blob. The blob can be used to recreate all the key-value pairs into another store. This is a useful technique for copying an entire store into a different store. See dpsDeserialize() for a detailed example on how to use the serialization functions to copy a store.

Parameters

store: the handle of the store to serialize.
data: a mutable blob that will contain all the key-value pairs in the store once the serialization is complete.
dummyKey: a dummy variable to indicate the type of the key
dummyValue
err: a mutable variable that will contain the error code describing the result of the serialization. Will be '0' if no error occurs, and a non-zero value otherwise.

public stateful boolean dpsSetConfigFile(rstring dpsConfigFile)

Allows for setting a path to the configuration file. Relative paths are relative to the toolkit root directory. If not set, then 'etc/no-sql-kv-store-servers.cfg' file will be used. If a file with the given name is not found, the DPS toolkit tries to read the configuration from a Streams application configuration object with the given name. In order to use the Streams application configuration, the user must call the dpsSetConfigFile method to specify the Streams app config name. In the Streams application configuration, the user has to specify every configuration line as an individual property. The names of the properties are as shown below. Following is an example of how a DPS application configuration named dps-cfg-for-app1 would be created using the streamtool:


streamtool mkappconfig --property dps.nosql.db=redis dps-cfg-for-app1   
streamtool chappconfig --property dps.server1=MyMachine1:6379:MyPassword dps-cfg-for-app1
streamtool chappconfig --property dps.server2=MyMachine2:6379:MyPassword dps-cfg-for-app1
streamtool chappconfig --property dps.server3=MyMachine3:6379:MyPassword dps-cfg-for-app1
streamtool chappconfig --property dps.server4=MyMachine4:6379:MyPassword dps-cfg-for-app1

Parameters

dpsConfigFile: the path to the configuration file or the name of an application configuration that should be used

Returns

returns always true

public stateful uint64 dpsSize(uint64 store, mutable uint64 err)

Get the total number of key-value pairs in the given store.

Parameters

store: the handle of the store in question.
err: contains the error code for this function call. Will be '0' if no error occurs, otherwise will have a non-zero value.

Returns

the size of the store. The return value of this function is undefined if an error occurs.

public stateful boolean initializeDpsNoException()

Allows you to initialize the connection to DPS without throwing an exception on failure.


     The purpose of this is to allow the DPS connection to be attempted during
	 operator initialization, and not prevent startup from completing on failure.
     Return true if we successfully established a connection or false if not.

C++ Native Functions: com.ibm.streamsx.store.distributed

C++ Native Functions: `com.ibm.streamsx.store.distributed`