The Memcached package provides the client interface API to a Memcached server. The major functionalities offered in the Memcached Package are the following:

Init() and AddServer() initializes the client and sets up the list of Memcached servers. Must be called before calling any other features.
Add(), Set(), Get(), Delete() and Replace() are the basic functions for manipulating Memcached values.
MultiGet() retrieves multiple values from Memcached.
Increment() and Decrement() increments and decrements a Memcached value respectively.
Stats() and Version() returns information for a server.

Class Attributes

DATA_ERROR

Data was not stored.

ERROR

Generic error constant.

INIT_ERROR

Error initializing Memcached.

KEYALREADYEXIST

Specified key already exists in cache.

KEYNOTFOUND

Specified key was not found in the cache.

NOMEMORY

Out of memory error constant.

NOTINITIALIZED

Memcached not initialized. Call Init() to initialize Memcached.

SERVERNOTFOUND_ERROR

The specified server could not be found in the server list.

SUCCESS

Return code for a successful operation.

Class Methods

Add( String key, String value, Integer valueLength, Integer timeout, Integer flags )

Add a key/value pair to the cache

AddServer( String host, Integer port, Integer min, Integer smax, Integer max, Integer ttl )

Add a server to the client server list.

Decrement( String key, Integer num )

Decrement the value corresponding to key by num.

Delete( String key, Integer timeout )

Delete the key entry in the cache.

Get( String key )

Retrieve the value corresponding to key.

Increment( String key, Integer num )

Increment the value corresponding to key.

Init( Integer maxServers )

Initialize the Memcached client.

MultiGet( List keyList )

Retrieve multiple values corresponding to the keys in keyList.

Replace( String key, String newValue, Integer newValueLength, Integer timeout, Integer flags )

Replace the value corresponding to key with newValue.

Set( String key, String value, Integer valueLength, Integer timeout, Integer flags )

Set a key/value pair to the cache

Stats( String host, Integer port )

Return a set of statistics for the specified server.

Version( String host, Integer port )

Return the version number for the specified server.

Class Attributes

Error DATA_ERROR

The data could not be stored in Memcached.

Error ERROR

Generic error constant.

Error INIT_ERROR

Server failed to initialize.

Error KEYALREADYEXIST

Key already exists in cache.

Error KEYNOTFOUND

Key not found.

Error NOMEMORY

Not enough memory.

Error NOTINITIALIZED

Memcached not initialized. Call Init() to intialize before calling any other features.

Error SERVERNOTFOUND_ERROR

Server not found.

Integer SUCCESS

Return code for an successful operation.

Class Methods

Add

Integer Add( String key,
             String value,
             Integer valueLength,
             Integer timeout,
             Integer flags )

Add a key/value pair to the cache.

Parameters

key

String containing the key to be added to the cache.

value

String containing the value to be added to the cache.

valueLength

Length of value to be added.

timeout

Time, in seconds, for the data to live on the server. Enter 0 for indefinite timeout.

flags

Any flags set by the client for this key.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
KEYALREADYEXIST	key already exists in the cache
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
DATA_ERROR	value could not be stored in Memcached.
ERROR	any other errors

AddServer

Integer AddServer( String host,
                   Integer port,
                   Integer min,
                   Integer smax,
                   Integer max,
                   Integer ttl )

Add a server to the Memcached client server list.

Parameters

host

hostname of the server.

port

port of the server.

min

minimum number of client sockets to open.

smax

soft maximum number of client connections to open.

max

hard maximum number of client connections to open.

ttl

time to live, in seconds, of a client connection.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
NOMEMORY	Not enough memory to add server.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Decrement

Integer Decrement( String key,
Integer num )

Decrement the value corresponding to key by num.

Parameters

key

key to the value being decremented.

num

number to decrement by.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Delete

Integer Delete( String key,
Integer timeout )

Delete key from the cache.

Parameters

key

The key to delete.

timeout

time for the delete to stop other clients from adding.

Returns:

An Integer indicating the return status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
SERVERNOTFOUND_ERROR	No servers were found
KEYNOTFOUND	The key was not found in the cache.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Get

String Get( String key )

Get the value corresponding to key from the cache.

Parameters

key

The key to get.

Returns:

A string containing the retrieved value if successful else an error code. Possible error codes are:

Result	Meaning
KEYNOTFOUND	The key was not found in the cache.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Increment

Integer Increment( String key,
Integer num )

Increment the value corresponding to key by num.

Parameters

key

key to the value being incremented.

num

number to increment by.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Init

Integer Init( Integer maxServers )

Initialize the Memcached client with a maximum of maxServers servers.

Parameters

maxServers

Maximum number of servers that can be added to this client.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
INIT_ERROR	Server failed to initialize.

MultiGet

Assoc MultiGet( List keyList )

Get a list of values, corresponding to the list of keys in keyList, from the cache.

Parameters

keyList

A list keys to get from the cache.

Returns:

An Assoc containing the retrieved key/value pairs if successful else an error code. Possible error codes are:

Result	Meaning
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Replace

Integer Replace( String key,
                 String newValue,
                 Integer newValueLength,
                 Integer timeout,
                 Integer flags )

Add a key/value pair to the cache.

Parameters

key

String containing the key to be replaced in the cache.

newValue

String containing the new value to replace the current value corresponding to key in the cache.

newValueLength

Length of the newValue.

timeout

Time, in seconds, for the data to live on the server. Enter 0 for indefinite timeout.

flags

Any flags set by the client for this key.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
KEYNOTFOUND	key not found in the cache
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
DATA_ERROR	newValue could not be stored in Memcached.
ERROR	any other errors

Set

Integer Set( String key,
             String value,
             Integer valueLength,
             Integer timeout,
             Integer flags )

Set a key/value pair to the cache.

Parameters

key

String containing the key to be added to the cache.

value

String containing the value to be added to the cache.

valueLength

Length of value to be added.

timeout

Time, in seconds, for the data to live on the server. Enter 0 for indefinite timeout.

flags

Any flags set by the client for this key.

Returns:

A return code indicating the operation status. Possible values are:

Result	Meaning
SUCCESS	Operation was successful
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
DATA_ERROR	value could not be stored in Memcached.
ERROR	any other errors

Stats

Assoc Stats( String host,
Integer port )

Retrieves statistics for the specified server.

Parameters

host

hostname of the server.

port

port of the server.

Returns:

Returns an Assoc containing various statistics for the specified server. The Assoc contains the following keys:

version	Version string of this server
pid	Process id of this server process
uptime	Number of seconds this server has been running
time	current UNIX time according to the server
pointer_size	The size of a pointer on the current machine
rusage_user	Accumulated user time for this process
rusage_system	Accumulated system time for this process
curr_items	Current number of items stored by the server
total_items	Total number of items stored by this server
bytes	Current number of bytes used by this server to store items
curr_connections	Number of open connections
total_connections	Total number of connections opened since the server started running
connection_structures	Number of connection structures allocated by the server
cmd_get	Cumulative number of retrieval requests
cmd_set	Cumulative number of storage requests
get_hits	Number of keys that have been requested and found present
get_misses	Number of items that have been requested and not found
evictions	Number of items removed from cache because they passed their expiration time
bytes_read	Total number of bytes read by this server
bytes_written	Total number of bytes sent by this server
limit_maxbytes	Number of bytes this server is allowed to use for storage
threads	Number of threads the server is running (if built with threading)

If unsuccessful the following error codes may be returned:

Result	Meaning
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors

Version

String Version( String host,
Integer port )

Retrieves the version number for the specified server.

Parameters

host

hostname of the server.

port

port of the server.

Returns:

Returns a string containing the version number for the specified server if successful else returns an error code. Possible error codes are:

Result	Meaning
SERVERNOTFOUND_ERROR	No servers were found.
NOTINITIALIZED	Memcached not initialized. Call Init() before calling any other features.
ERROR	any other errors