Distributed Storage Functions

The Distributed Storage Profile enables you to access a distributed storage solution from APL without having to provide details about its type or implementation.

The APL functions described in this section use a key-value model to read, store and remove data via the specified profile. The functions can optionally use sessions that are either committed or rolled back in order to secure transaction consistency.

The following functions for Distributed Storage described here are:

Initializing Storage

dsInitStorage

The dsInitStorage function returns a Distributed Storage Profile object that is used in subsequent APL calls to distributed storage functions.

any dsInitStorage(string profid)

Parameter

Description

Parameter

Description

profid

A string containing a reference to a Distributed Storage Profile.

Returns

A Distributed Storage Profile object.

Example - Using dsInitStorage

any storage=null;

initialize {
    storage = dsInitStorage("default.ds_profile"); 
    if(null != dsLastErrorMessage()) {
        //Error Handling
    }
}

 

Note!

The dsInitStorage function must be used in the initialize block and not consume block.

Storing and Removing Data

The following functions  enable you to perform changes on data in a distributed storage:

  • dsStore

  • dsStoreUdr

  • dsStoreMany

  • dsStoreManyUdrs

  • dsRemove

  • dsRemoveMany

dsStore

The dsStore function stores a key-value pair in a distributed storage.

void dsStore( any profid, string key, bytearray value, any transid)

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

key

The key of a key-value pair.

value

The value of a key-value pair.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to store data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

Example - Using dsStore

dsStoreUdr

The dsStoreUdr function stores a key-value pair in a distributed storage.

void dsStoreUdr( any profid, string key, drudr myUDR, any transid)

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

key

The key of a key-value pair.

myUDR

The UDR to be stored.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to store data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

dsStoreMany

The dsStoreMany function stores a set of key-value pairs in a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

values

The key-value pairs to store.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to store data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

dsStoreManyUdrs

The dsStoreManyUdrs function stores a set of key-value pairs in a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

myUDRs

The key-value pairs to store.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to store data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

dsCommand

The dsCommand function stores data with a Time To Live (TTL) on the entry by updating the ‘expiration’ field for data in Couchbase, meaning it will be removed when it gets too old.

You can also use the dsCommand to extend the expiration field of the data in Couchbase using the “touch” action.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

action

The action you want to perform, “ttlStore” for storing UDRs with TTL or “touch“ to extend the TTL.

key

The key of a key-value pair.

ttl

Time To Live in seconds.

myUDR

The UDR to be stored.

Returns

Nothing.

dsRemove

The dsRemove function removes a key-value pair, identified by a key, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

key

The key of the key-value pair to remove.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to remove data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

dsRemoveMany

The dsRemoveMany function removes a list of key-value pairs, identified by a list of keys, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

keys

The keys of the key-value pairs to remove.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to remove data in non-transaction mode. If the identifier is set the transaction is completed by calling dsCommitTransaction.

Returns

Nothing.

Reading Data

The following functions  enable you to read data from a distributed storage.

  • dsRead

  • dsReadUdr

  • dsReadMany

  • dsReadManyUdrs

dsRead

The dsRead function reads a value, identified by a key, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

key

The key of a key-value pair.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to read data in non-transaction mode. If the identifier is set, the read key-value pair is locked for other transactions untildsCommitTransaction or dsRollbackTransaction is called.

Returns

A bytearray containing the value of a key-value pair.

dsReadUdr

The dsReadUdr function reads a set of UDRs, identified by a list of keys, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

key

The key of a key-value pair.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to read data in non-transaction mode. If the identifier is set, the read key-value pair is locked for other transactions untildsCommitTransaction or dsRollbackTransaction is called.

Returns

A UDR identified by the key parameter.

dsReadMany

The dsReadMany function reads a set of key-value pairs, identified by a list of keys, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

keys

The keys of the key-value pairs to be read.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to read data in non-transaction mode. If the identifier is set, the read key-value pairs are locked for other transactions untildsCommitTransaction or dsRollbackTransaction is called.

Returns

A map containing the key-value pairs.

dsReadManyUdrs

The dsReadManyUdrs function reads a key-value map, identified by a key, from a distributed storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

keys

The keys of the key-value pairs to be read.

transid

The transaction identifier that is returned by dsBeginTransaction. Use a null value to read data in non-transaction mode. If the identifier is set, the read key-value pairs are locked for other transactions untildsCommitTransaction or dsRollbackTransaction is called.

Returns

A map containing the key-value pairs.

Transaction Functions

The following functions provide transaction safety by performing commit or rollback on a set of calls to a Distributed Storage Profile:

  • dsBeginTransaction

  • dsCommitTransaction

  • dsRollbackTransaction

dsBeginTransaction

The dsBeginTransaction function begins a new transaction and returns an object that can be used in subsequent APL calls to distributed storage functions.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

Returns

A transaction identifier.

dsCommitTransaction

The dsCommitTransaction function ends a transaction and commits changes that has been made using the specified transaction identifier.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

transid

The transaction identifier that is returned by dsBeginTransaction.

Returns

Nothing.

dsRollbackTransaction

The dsRollbackTransaction function ends a transaction and reverts changes that has been made using the specified transaction identifier.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

transid

The transaction identifier that is returned by dsBeginTransaction.

Returns

Nothing.

Iterator Functions

The following functions  are used for traversing through a set of keys in a distributed storage:

  • dsCreateKeyIterator

  • dsCreateREKeyIterator

  • dsGetNextKey

  • dsDestroyKeyIterator

dsCreateKeyIterator

The dsCreateKeyIterator function creates an iterator object that is used in subsequent APL calls to other iterator functions.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

startkey

The key to start iterating at.

stopkey

The key to finish iterating at.

Returns

An iterator object used in subsequent APL calls to dsGetNextKey and dsDestroyKeyIterator.7.5.2. dsGetNextKey.

dsCreateREKeyIterator

The dsCreateREKeyIterator function creates an iterator object that is used in subsequent APL calls to other iterator functions.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

searchpattern

A search pattern which may include wild card '*'.

Returns

An iterator object used in subsequent APL calls to dsGetNextKey and dsDestroyKeyIterator.

dsGetNextKey

The dsGetNextKey function gets the next available key from a distributed storage using an iterator object. Each subsequent call to the function returns the next key in the iterator's range.

Parameter

Description

Parameter

Description

profid

The Distributed Storage Profile.

iterator

The iterator object returned by dsCreateKeyIterator.

Returns

The key of a key-value pair. A null value is returned if a key cannot be found.

dsDestroyKeyIterator

The dsDestroyKeyIterator function destroys an iterator object created with dsCreateKeyIterator in order to free up memory. It is good practice to always include a call to this function in the APL code though it may not be required for all types of storage.

Parameter

Description

Parameter

Description

profid

The Distributed Storage profile.

iterator

The iterator object returned by dsCreateKeyIterator.

Returns

Nothing

Error Handling

dsLastErrorMessage

The dsLastErrorMessage function returns the error message from the last call to a distributed storage function. Distributed storage functions that are not used for error handling, do not return error codes and generally do not cause runtime errors. For this reason, The dsLastErrorMessage function must be called after each operation to validate success.

Parameter

Description

Parameter

Description

Returns

An error message, or null if no error has occurred since the last call to this function. The content of message depends on the type of profile that is used with the Distributed Storage profile. For example, with a Couchbase profile, the error message is identical to the error message exposed by the Couchbase API.