[Java programming language only]

Catalog service domain administrative tasks

You can use the Jacl or Jython scripting languages to manage catalog service domains in your WebSphere® Application Server configuration. With WebSphere DataPower® XC10 Appliance, you define catalog service domains to establish connections with the catalog servers that are running on the appliance. Creating this configuration is required for dynamic cache data grids only.

Requirements

You must have the WebSphere eXtreme Scale Client installed in your WebSphere Application Server environment.

List all administrative tasks

To get a list of all of the administrative tasks that are associated with catalog service domains, run the following command with wsadmin:
wsadmin>$AdminTask help XSDomainManagement 

Commands

The administrative tasks for catalog service domains include the following commands:

createXSDomain

The createXSDomain command registers a new catalog service domain.
Table 1. createXSDomain command arguments
Argument Description
-name (required) Specifies the name of the catalog service domain that you want to create.
-default Specifies whether the catalog service domain is the default for the cell. The default value is true. (Boolean: set to true or false)
-properties Specifies custom properties for the catalog service domain.
-enableXIO
Specifies whether IBM eXtreme IO (XIO) or the Object Request Broker (ORB) is used for transport communication in this catalog service domain.
true
Specifies that XIO is used.
false
Specifies that the ORB is used.
If you do not specify a value, the default is true (XIO enabled). If you have remote servers in your catalog service domain, the -enableXIO parameter does not configure XIO or ORB on the remote servers. To configure transports on remote servers, specify the transport type when you start the remote servers.
Table 2. defineDomainServers step arguments
Argument Description
name_of_endpoint Specifies the name of the catalog service endpoint.
  • For existing application servers: The name of the endpoint must be in the following format: cell_name\node_name\server_name
  • For remote servers: Specifies the host name of the remote server. You can have the same name for multiple endpoints, but the client port values must be unique for each endpoint.
custom_properties Specifies custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks ("") for this argument.
endpoint_ports
Specifies the port numbers for the catalog service domain endpoint. The ports must be specified in the following order: <client_port>,<listener_port>
Client Port
Specifies the port that is used for communication between the catalog servers in the catalog service domain. This value is required for catalog servers that are running in WebSphere Application Server processes only and can be set to any port that is not being used elsewhere.
Listener Port
Specifies the port that is used for communication with clients. This value is required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.
For WebSphere DataPower XC10 Appliance remote endpoints: Use the value 2809 for the appliance remote endpoints.

Return value:

Batch mode example usage

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -defineDomainServers step arguments using a specific array of properties. This array of properties is in the format name_of_endpoint custom_properties endpoint_ports. The endpoint_ports value is a list of ports that must be specified in the following order: <client_port>,<listener_port>.

Interactive mode example usage
  • Using Jacl:
    $AdminTask createXSDomain {-interactive}
  • Using Jython string:
    AdminTask.createXSDomain ('[-interactive]')

deleteXSDomain

The deleteXSDomain command deletes a catalog service domain.

Required parameters:
-name
Specifies the name of the catalog service domain to delete.

Return value:

Batch mode example usage
  • Using Jacl:
    $AdminTask deleteXSDomain {-name TestDomain }
  • Using Jython string:
    AdminTask.deleteXSDomain('[-name TestDomain ]')
Interactive mode example usage
  • Using Jacl:
    $AdminTask deleteXSDomain {-interactive}
  • Using Jython string:
    AdminTask.deleteXSDomain ('[-interactive]')

getDefaultXSDomain

The getDefaultXSDomain command returns the default catalog service domain for the cell.

Required parameters: None

Return value: The name of the default catalog service domain.

Batch mode example usage
  • Using Jacl:
    $AdminTask getDefaultXSDomain
  • Using Jython string:
    AdminTask.getDefaultXSDomain
Interactive mode example usage
  • Using Jacl:
    $AdminTask getDefaultXSDomain {-interactive}
  • Using Jython string:
    AdminTask.getDefaultXSDomain ('[-interactive]')

listXSDomains

The listXSDomains command returns a list of the existing catalog service domains.

Required parameters: None

Return value: A list of all of the catalog service domains in the cell.

Batch mode example usage
  • Using Jacl:
    $AdminTask listXSDomains
  • Using Jython string:
    AdminTask.listXSDomains
Interactive mode example usage
  • Using Jacl:
    $AdminTask listXSDomains {-interactive}
  • Using Jython string:
    AdminTask.listXSDomains ('[-interactive]')

modifyXSDomain

The modifyXSDomain command modifies an existing catalog service domain.

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -modifyEndpoints, -addEndpoints and -removeEndpoints step arguments using a specific array of properties. This array of properties is in the format name_of_endpoint host_name custom_properties endpoint_ports. The endpoint_ports value is a list of ports that must be specified in the following order: <client_port>,<listener_port>.

Table 3. modifyXSDomain command arguments
Argument Description
-name (required) Specifies the name of the catalog service domain that you want to edit.
-default If set to true, specifies that the selected catalog service domain is the default for the cell. (Boolean)
-properties Specifies custom properties for the catalog service domain.
-enableXIO
Specifies whether IBM eXtreme IO (XIO) or the Object Request Broker (ORB) is used for transport communication in this catalog service domain.
true
Specifies that XIO is used.
false
Specifies that the ORB is used.
If you do not specify a value, the default is true (XIO enabled). If you have remote servers in your catalog service domain, you cannot configure XIO on the remote servers.
Table 4. modifyEndpoints step arguments
Argument Description
name_of_endpoint Specifies the name of the catalog service endpoint.
  • For existing application servers: The name of the endpoint must be in the following format: cell_name\node_name\server_name
  • For remote servers: Specifies the host name of the remote server. You can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint. This value must be a fully-qualified domain name if you are configuring an appliance.
endpoint_ports
Specifies the port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order: <client_port>,<listener_port>
Client Port
Specifies the port that is used for communication between the catalog servers in the catalog service domain. This value is required for catalog servers that are running in WebSphere Application Server processes only and can be set to any port that is not being used elsewhere.
Listener Port
Specifies the port that is used for communication with clients. This value is required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.
For WebSphere DataPower XC10 Appliance remote endpoints: Use the value 2809 for the appliance remote endpoints.
Table 5. addEndpoints step arguments
Argument Description
name_of_endpoint Specifies the name of the catalog service endpoint.
  • For existing application servers: The name of the endpoint must be in the following format: cell_name\node_name\server_name
  • For remote servers: Specifies the host name of the remote server. You can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint. This value must be a fully-qualified domain name if you are configuring an appliance.
custom_properties Specifies custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks ("") for this argument.
endpoint_ports
Specifies the port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order: <client_port>,<listener_port>
Client Port
Specifies the port that is used for communication between the catalog servers in the catalog service domain. This value is required for catalog servers that are running in WebSphere Application Server processes only and can be set to any port that is not being used elsewhere.
Listener Port
Specifies the port that is used for communication with clients. This value is required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.
For WebSphere DataPower XC10 Appliance remote endpoints: Use the value 2809 for the appliance remote endpoints.
Table 6. removeEndpoints step arguments
Argument Description
name_of_endpoint Specifies the name of the catalog service endpoint to delete.

Return value:

Batch mode example usage
  • Using Jacl:
    $AdminTask modifyXSDomain {-name TestDomain -default true -modifyEndpoints 
    {{xhost1.ibm.com "" ,2809}} -addEndpoints {{xhost2.ibm.com "" ,2809}}} 
    -removeEndpoints {{xhost3.ibm.com}}}
  • Using Jython string:
    AdminTask.modifyXSDomain('[-name TestDomain  
    -default false -modifyEndpoints [[xhost1.ibm.com "" ,2809]] 
    -addEndpoints [[xhost3.ibm.com "" ,2809]] 
    -removeEndpoints [[xhost2.ibm.com]]]')
  • Modify an existing catalog service domain to turn on IBM eXtremeIO:
    AdminTask.modifyXSDomain('[-name testDomain -enableXIO true]')
Interactive mode example usage
  • Using Jacl:
    $AdminTask modifyXSDomain {-interactive}
  • Using Jython string:
    AdminTask.modifyXSDomain ('[-interactive]')

getTransport

The getTransport command displays the transport type for the catalog service domain: IBM eXtremeIO (XIO) or Object Request Broker (ORB). If you run this command on a catalog service domain that contains remote servers, or if the catalogServerName is a remote server, an error results. You must use the xscmd -c showTransport command for remote servers.

Required parameters:
-domainName
Specifies the name of the catalog service domain for which to display the transport type.
-catalogServerName
Specifies the name of the catalog server for which to display the transport type.

Return value: ORB or XIO

Display the transport for a catalog service domain
  • Using Jacl:
    $AdminTask getTransport {-domainName TestDomain }
  • Using Jython string:
    AdminTask.getTransport('[-domainName testDomain]')
Display the transport for a catalog server
  • Using Jacl:
    $AdminTask getTransport {-catalogServerName myCell01\myNode01\container1 }
  • Using Jython string:
    AdminTask.getTransport('[-catalogServerName myCell01\myNode01\container1]')
Interactive mode example usage
  • Using Jacl:
    $AdminTask getTransport {-interactive}
  • Using Jython string:
    AdminTask.getTransport ('[-interactive]')

testXSDomainConnection

The testXSDomainConnection command tests the connection to a catalog service domain.

Required parameters:
-name
Specifies the name of the catalog service domain to which to test the connection.
Optional parameters
-timeout
Specifies the maximum amount of time to wait for the connection, in seconds.

Return value: If a connection can be made, returns true, otherwise, connection error information is returned.

Batch mode example usage
  • Using Jacl:
    $Admintask testXSDomainConnection
  • Using Jython string:
    AdminTask.testXSDomainConnection
Interactive mode example usage
  • Using Jacl:
    $AdminTask testXSDomainConnection {-interactive}
  • Using Jython string:
    AdminTask.testXSDomainConnection ('[-interactive]')

testXSServerConnection

The testXSServerConnection command tests the connection to a catalog server. This command works for both stand-alone servers and servers that are a part of a catalog service domain.

Required parameters:
host
Specifies the host on which the catalog server resides.
listenerPort
Specifies the listener port for the catalog server.
Optional parameters
timeout
Specifies the maximum amount of time to wait for a connection to the catalog server, in seconds.

Return value:

Batch mode example usage
  • Using Jacl:
    $Admintask testXSServerConnection {-host xhost1.ibm.com -listenerPort 2809}
  • Using Jython string:
    AdminTask.testXSServerConnection('[-host xshost3.ibm.com -listenerPort 2809]')
Interactive mode example usage
  • Using Jacl:
    $AdminTask testXSServerConnection {-interactive}
  • Using Jython string:
    AdminTask.testXSServerConnection ('[-interactive]')