Configuring the embedded global cache by using commands

You can customize the default global cache topology to use a specific port range and listener host, or you can turn off the default topology and specify your own integration server properties. Multiple integration nodes can share a cache by using a cache policy file.

Before you begin

For more information about the default global cache topology, see Data caching overview.

About this task

If you are using the default global cache topology, you can use IBM Integration Bus commands to set a port range and listener host for the cache manager to use, and to report the properties for the cache manager. If you want multiple integration nodes to share data in the cache, or to configure a cache with enhanced availability, you can use commands to specify a policy file. For more information, see Integration node properties.

Use IBM Integration Bus commands to turn off the default topology and set integration server properties explicitly (see Integration server properties).

You can also use the mqsicacheadmin command to clear data from a map. For more information, see mqsicacheadmin command.

Integration node properties

Procedure

To specify a policy for the cache manager to use, set the -b (cachePolicy) parameter on the mqsicreatebroker or mqsichangebroker command.
The cachePolicy parameter specifies the policy to use for the cache manager. You can set this parameter to default, disabled, none, or the fully qualified name of an XML policy file.
- If you set this property to default, the default global cache topology is used. The following example shows how to enable the default cache topology:
```
mqsichangebroker integrationNodeName -b default
```
- If you set this property to disabled, the global cache components in the integration node are disabled. The cache is disabled by default.
- If you set this parameter to none, you must set the integration server properties explicitly.
- If you specify the fully qualified name of a policy file, the integration nodes listed in the policy file are configured to share the data in the global cache. The path name must be absolute, not relative. The following example shows how to use the mqsichangebroker command to set the name of a policy file:
```
mqsichangebroker integrationNodeName -b c:\filepath\policy.xml 
```
  For more information, see Configuring the global cache for multiple integration nodes.
You must stop the integration node before you run the mqsichangebroker command. Changes take effect when you restart the integration node.
To specify a port range for the cache manager to use, set the -r (cachePortRange) parameter on the mqsicreatebroker or mqsichangebroker command.
The cachePortRange parameter specifies a range of ports that the cache manager can use. Set this parameter to generate or to a specific range of ports.
- If you specify a range of ports, the value of this parameter must be in the format xxxx-yyyy, and the range must contain at least 20 ports.
- If you specify generate, the integration node generates a range of ports that are not being used by another integration node on that computer. The integration node chooses a range that starts from 2800. If, for example, another integration node is using ports 2800 to 2819, the integration node generates a range from 2820 to 2839.
You must stop the integration node before you run the mqsichangebroker command. Changes take effect when you restart the integration node.
Use of these parameters is shown in the following example.
```
mqsichangebroker integrationNodeName -b default -r 2809-2825
```
You can also use the mqsichangeproperties command to change integration node properties while the integration node is running, although you do have to restart the integration node for the changes to take effect. To set the policy, port range, and listener host for the integration node, set the -b (componentName) parameter to cachemanager, and use the -n and -v parameters to set the relevant properties, as shown in the following example:
```
mqsichangeproperties integrationNodeName -b cachemanager -o CacheManager -n policy,portRange,listenerHost -v default,generate,host_name
```
To report properties for the cache manager, set the -b parameter on the mqsireportproperties command to cachemanager, as shown in the following example.
```
mqsireportproperties integrationNodeName -b cachemanager -o CacheManager -r
```

Integration server properties

Before you begin

Before you can set properties explicitly for an integration server, you must set the cache policy property to none for the integration node. You can set the policy by using the mqsicreatebroker, mqsichangebroker, or mqsichangeproperties command, as described in Integration node properties. The integration server properties that were set most recently by the integration node-level policy are retained as a starting point for customization.

About this task

If you set the cache policy property to none, you must set properties on the integration servers. If you stop the integration server that contains the only catalog server, the cache becomes unavailable. Therefore, if you switch off the default topology, ensure that you place the catalog server appropriately. If you restart the integration server that hosts the catalog server, it can no longer communicate with the container servers in other integration servers. Although these container servers are still running, they are no longer part of the cache, and your data is lost. Therefore, you must also restart the integration servers that host the container servers. Alternatively, restart the integration node to reset all cache components.

To use the new properties that you set, restart the integration server.

Procedure

To set cache manager properties for an integration server, use the mqsichangeproperties command and specify the object name ComIbmCacheManager.
For example, to start the catalog service in integration server 1, set the enableCatalogService property to true, as shown in the following example.
```
mqsichangeproperties integrationNodeName -e execution_group_1 -o ComIbmCacheManager -n enableCatalogService -v true
```
To provide a specific domain name for the WebSphere eXtreme Scale servers in an integration server, set the domainName property, as shown in the following example. Only servers with the same domain name can participate in the same embedded grid. Therefore, ensure that all servers that participate in the same embedded grid use the same domain name. If you do not set a specific domain name, the integration node creates a domain name that is based on the server names of the catalog servers.
```
mqsichangeproperties integrationNodeName -e execution_group_1 -o ComIbmCacheManager -n domainName -v myDomain
```
To start a container server in integration server 2, set the enableContainerService property to true, as shown in the following example.
```
mqsichangeproperties integrationNodeName -e execution_group_2 -o ComIbmCacheManager -n  enableContainerService -v true
```
For a list of cache manager properties that you can set for an integration server, see Parameter values for the cachemanager component.
To specify a list of listener hosts when using multi-instance integration nodes, enclose the comma-separated list with a pair of backslash characters and quotation marks (\"):
```
mqsichangeproperties integrationNodeName -e execution_group_2 -o ComIbmCacheManager -n  listenerHost -v \"host1,host2\"
```
For more information about configuring the global cache for multi-instance integration nodes, see Configuring the global cache for multi-instance integration nodes.
To report cache manager properties for the integration server, set the -o parameter on the mqsireportproperties command to ComIbmCacheManager, and specify the integration server name, as shown in the following example.
```
mqsireportproperties integrationNodeName -e integrationServerName -o ComIbmCacheManager -r
```