ats (metacp)

Synopsis

ats acknowledge
[-handle handle_name]
-messageid message_ID
-topic topic_name
-timeout timeout

ats initialize
[-bindid bind_session_id]
[-handle handle_name]
[-prot protocol_file_name]
[-repeat repeat_count]
[-servername MSS_servername]
[-timeout timeout]
[-topicprefix topic_prefix]
[-type type]
[-cluster cluster]
[-resource resource]

ats publish
[-handle handle_name]
-header message_header_information
[-message message_body]
-topic topic_list

ats receive
[-handle handle_name]
-timeout timeout
-topic topic

ats replay
-prot protocol_file_name

ats send
[-handle handle_name]
-header message_header_information
[-message message_body]
-topic topic

ats subscribe
[-handle handle_name]
-topic topic_list
-timeout timeout
[-onemessage]
[-nodestroy]

ats terminate
[-handle handle_name]

ats help

ats operations

Purpose

A metacp object that manages the asynchronous transport service. This is a messaging service that is based on JMS (Java messaging service). It supports the publish - subscribe model. A unlimited number of publisher clients can send messages to a defined topic to the message server. Other clients can subscribe to topics. That is that they get all messages that were published to a specific topic. There are no specific rules how to define topics and messages.

Arguments

operation: The name of the ats operation for which to display help information.

Operations

ats acknowledge

Destroys a message from the message server. The syntax is as follows:

ats acknowledge
[-handle handle_name]
-messageid message_ID
-topic topic_name
-timeout timeout

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel
-messageid message_ID: Specifies the message id of the message that is to be destroyed from the server. The message_ID is the result returned by the corresponding ats subscribe operation. It is a base64 encoded string that represents the internal message identifier of the underlying messaging system, for example QU1RIFFNX3NjaG1pZDAyIBS8nz8gABYF.
-topic topic_name: Specifies the name of the topic the client uses for deleting the message, for example dxm.event.pwd.changed.
-timeout timeout: The operation stops after timeout seconds. A value of 0 implies that the underlying message system returns after destroying the message.

The ats acknowledge operation destroys the message with the specified ID from the server.

Example

ats acknowledge
      -messageid QU1RIFFNX3NjaG1pZDAyIBS8nz8gABYF
      -topic dxm.event.pwd.changed
      -timeout 1

ats initialize

Initializes a connection to the message server. The syntax is as follows:

Options

-bindid bind_session_id
-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel
-prot protocol_file_name: Specifies the filename of the protocol file. All messages sent and all messages received are written into this file. This file can be used for the ats replay operation if the same messages should be re-sent.

Publish operations are written into the protocol file in the following format:

Operation=publish
Header=message_header_1
Header=message_header_2
...
Message=message
Topic=topic_1
Topic=topic_2

Subscribe operations are written into the protocol file in the following format:

Operation=subscribe
Header=message_header_1
Header=message_header_2
Topic=topic_1
...
TimeOut=time_out_in_seconds
Message=message

Currently only one ATS connection is supported in the protocol file. Furthermore no other options can be specified together with the options –prot.

-repeat repeat_count: Specifies the number of retries for retrieving the message queue server information. Default value, if missing, is 10.
-timeout timeout: Specifies the timeout to be used for retrieving the message queue server information. Default value, if missing, is 30.
-topicprefix topic_prefix: Specifies the topic prefix to be used as part of a JMS topic if metacp should send automatically JMS messages (containing the SMPL representation of an update request), for example "dxm.event" as part of the topic

dxm.event.LDAP.cluster='my-cluster'.resource='my-resource'
-type type: Specifies the type to be used as part of a JMS topic if metacp should send automatically JMS messages (containing the SMPL representation of an update request), for example "LDAP" as part of the topic

dxm.event.LDAP.cluster='my-cluster'.resource='my-resource'

-cluster cluster: Specifies the cluster to be used as part of a JMS topic if metacp should send automatically JMS messages (containing the SMPL representation of an update request), for example "my-cluster" as part of the topic

dxm.event.LDAP.cluster='my-cluster'.resource='my-resource'
-resource resource: Specifies the resource to be used as part of a JMS topic if metacp should send automatically JMS messages (containing the SMPL representation of an update request), for example "my-resource" as part of the topic

dxm.event.LDAP.cluster='my-cluster'.resource='my-resource'

The ats initialize operation initializes connection to the message server. The connection must be terminated by performing an ats terminate operation.

The message server is identified by using an MSS server name and retrieving its related message server. The relevant information is read from the directory and therefore an LDAP connection needs to be available.

There are two ways to select a message server:

If no options are given, the ats initialize operation reads the bind information stored in the configuration file install_path*/server/conf/dxmmsssvr.ini* to retrieve all relevant information from the DIT for setting up a connection to the messaging system. In that case, the complete set of bind information must be available in the configuration file, namely the password (and optionally PIN).
In order to setup a JMS connection to any other message server, the MSS server name can be given in the parameter –servername. An existing LDAP connection is required and is identified either by the bind session given in –bindid, or the default LDAP bind session is used. Furthermore the parameters –repeat and –timeout will be evaluated.

If metacp should propagate JMS requests (containing the SPML representation of an update request) to a given JMS topic then specify the options -topicprefix, -type, -cluster, and -resource. When metacp later on performs the update operations (using meta addentry, meta modifyentry, meta removeentries, or meta modifydn) JMS messages are propagated automatically to the given topic.

Example

ats initialize -prot ATS_trace01
ats initialize -servername myMSS -bindid myLDAPbind

ats publish

Publishes a message. The syntax is as follows:

ats publish
[-handle handle_name]
-header message_header_information
[-message message_body]
-topic topic_list

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel.
-header message_header_information: Is a comma separated list of header fields, for example DXMVersion=1.0,DXMInstId=100,DXMOperation=…,…

You can define your own messages. See the event manager utility script in the DirX Identity default applications for examples for messages.
-message message_body: Specifies the message text. There are no specific rules how to define the message text.
-topic topic_list: Is a comma separated list of topics for that the message is published, for example dxm.command.main,DXM.stateTracker,DXM.myserver.fileservice.

The ats publish operation publishes a message. The operation returns the message ID on success.

Example

The following ats publish operations creates a workflow instance at the server. It returns the message ID main_1067593458_2888_0:

ats publish
   -topic dxm.command.main
   -header DXMReplyTo=dxm.command.event.mss_reply,
       JMSReplyTo=dxm.command.event.mss_reply,
       DXMVersion=1.10,
       DXMObjectName=cn=BA_MetaStore2CSVfile_Full\,
         dxmC=CSVfile\,
         dxmC=uid-c0671b98-96a4c-e98fe4f404--7f95\,
         dxmC=Workflows\,
         dxmC=DirXmetahub,
       DXMObjectType=3,
       DXMInitiatorType=1,
       DXMType=1,
       JMSType=1

The following ats publish operation executes the instance created in example 1. It returns the message ID main_1067593458_2888_1:

ats publish
   -topic dxm.command.main
   -header DXMReplyTo=dxm.command.event.mss_reply,
        JMSReplyTo=dxm.command.event.mss_reply,
        DXMVersion=1.10,
        DXMObjectName=cn=BA_MetaStore2CSVfile_Full\,
          dxmC=CSVfile\,
          dxmC=uid-c0671b98-96a4c-e98fe4f404--7f95\,
          dxmC=Workflows\,
          dxmC=DirXmetahub,
        DXMOperation=10,
        DXMWorkflowActivity=,
        DXMType=8,
        JMSType=8,
        DXMInstId=main_1067593458_2888_0

The following ats publish operation destroys the instance created in example 1. It returns the message ID main_1067593458_2888_2:

ats publish
   -topic dxm.command.main
   -header DXMReplyTo=dxm.command.event.mss_reply,
       JMSReplyTo=dxm.command.event.mss_reply,
       DXMVersion=1.10,
       DXMType=2,
       JMSType=2,
       DXMInstId=main_1067593458_2888_1

ats receive

Receives messages from the message service using specified topic (that identifies the message service’s queue). The syntax is as follows:

ats recive
[-handle handle_name]
-timeout timeout
-topic topic

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel.
-timeout timeout: The operation stops after timeout seconds. A value of 0 implies that operation returns all currently available messages and then stops.
-topic topic: Specifies the topic name that gets mapped to the message service’s queue name.

The ats receive operation reads a message from the message service’s queue defined in the option -topic.

Example

ats receive -topic dxm.my.topic -timeout 5

If you look at the sample of ats send then the result is the following:

{dxm.my.topic DXMVersion=1,DXMType=10 {Hello world}}

ats replay

Re-sends all publish operations that have been written to the specified protocol file in another session. The syntax is as follows:

ats replay
-prot protocol_file_name

Options

-prot protocol_file_name: Specifies the filename of the protocol file that has been written in another session.

The ats replay operation performs all publish operations that it finds in the specified protocol file. (See also the ats initialize operation.)

Example

*ats replay -prot ATS_trace01*

ats send

Sends a message to the queue. The syntax is as follows:

ats send
[-handle handle_name]
-header message_header_information
[-message message_body]
-topic topic

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel.
-header message_header_information: Is a comma separated list of header fields, for example DXMVersion=1.0,DXMInstId=100,DXMOperation=…,…

You can define your own messages.
-message message_body: Specifies the message text. There are no specific rules how to define the message text.
-topic topic: Specifies the topic name that gets mapped to the message service’s queue name.

The ats send operation sends a message to a message service’s queue. The operation returns the message ID on success.

Example

ats send -topic dxm.my.topic
              -header DXMVersion=1,DXMType=10
              -message "Hello world"

ats subscribe

Subscribes to the specified topic list. The syntax is as follows:

ats subscribe
[-handle handle_name]
-topic topic_list
-timeout timeout
[-onemessage]
[-nodestroy]

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel
-topic topic_list: Is a comma seperated list of topics the client wants to subscribe to, for example dxm.command.main,DXM.stateTracker,DXM.myserver.fileservice.
-timeout timeout: The operation stops after timeout seconds. A value of 0 implies that operation returns all currently available messages and then stops.
-onemessage: The operation stops after the first message has been returned.
-nodestroy: The operation does not destroy the messages returned. These messages must be destroyed by performing an ats acknowledge operation. The corresponding message Ids are returned.

The ats subscribe operation subscribes to the topic list specified in the option -topic.

The operation returns all messages available on success. If the -nodestroy option is specified the returned messages contain also the base 64 encoded message IDs that must be used when performing the ats acknowledge operations to destroy the messages from the server. The messages are returned in aTcl list with the following format:

{topic1 header_info_t1_1 message_t1_1 [message_ID_t1_1]}
{topic1 header_info_t1_2 message_t1_2 [message_ID_t1_2]}
…
{topic2 header_info_t2_1 message_t2_1 [message_ID_t2_1]}
{topic2 header_info_t2_2 message_t2_2 [message_ID_t2_2]
…

Example

ats subscribe
      -topic dxm.event.pwd.changed
      -timeout 20
      -onemessage
      -nodestroy

The return value is as follows:

{dxm.event.pwd.changed
{JMSType=513,
DXMVersion=1.10,
DXMUserData=
<event name="dxm.event.PWD_CHANGED">
<source application="APETA" type="ADS" resource="ASW" />
<entry>
<identifier type="urn:oasis:names:tc:SPML:1:0#UserIDAndOrDomainName">
    <id>1002</id>
</identifier>
<operationalAttributes>
    <attr name="encryptedAttributes"> <value>password</value> </attr>
</operationalAttributes>
<attributes>
    <attr name="username"> <value>test</value> </attr>
    <attr name="password">
            <value>{E:00000001:cn=server-admin,
                          1.3.12.2.1107.1.3.102.4.13.17=DirXmetahub}
                           i7qivioOPuaAlicWdTZztGHewT8WSP65iix
                           VvpPT4txUz17IMAnavlb7deREKVYU
                           /ak2FjuIv815ZLltfFpz8Sm7nA4qpeZBW
                           2mj67dwWIqvBH2QRkeAOOd+RGRbw
                           0nzAlM93rNcpNnSrPqj8qiwr2RnY2WvX
                           j+izJmNiKoZsYk=
            </value>
    </attr>
    <attr name="passwordexpired"> <value>0</value> </attr>
</attributes>
</entry>
</event>,
JMSExpiration=86400,
JMSMessageID=_1067432986_-1_1,
JMSDeliveryMode=0,
JMSDestination=dxm.event.pwd.changed,
JMSPriority=1,
JMSRedelivered=0,
JMSTimestamp=1067433251}
QU1RIFFNX3NjaG1pZDAyIBS8nz8gABYF}

where

"dxm.event.pwd.changed" represents the topic,

"QU1RIFFNX3NjaG1pZDAyIBS8nz8gABYF" at the end represents the base 64 encoded message ID that must be used when performing the ats acknowledge operation

and the remaining information represents the message.

ats terminate

Terminates a connection to the message server. The syntax is as follows:

ats terminate
[-handle handle_name]

The ats terminate operation terminates a connection to the message server. It releases all resources. The connection was previously initialized by an ats initialize operation.

Options

-handle handle_name: Specifies an ATS session identifier in order to support multiple ATS sessions in parallel

Example

ats terminate

ats help

Returns help information about the ats object and its operations. The syntax is as follows:

ats help

Example

ats help

ats operations

Returns a list of operations that can be performed on the ats object. The syntax is as follows:

ats operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example

ats operations

The output of the sample command is as follows:

acknowledge initialize publish replay subscribe terminate help operations