NAME
     cmt - Create a new cmt object.

SYNOPSIS
     cmt parentName ?options?

OPTIONS
  -rpc_file
     A read only option that returns the file descriptor  of  the
     RPC connection to the open cm service or process. If no ser-
     vice or process is connected to, rpc_file is set to "".

  -CID
     A read only option that  returns  the  CID  (Connection  ID)
     given  to  the connection by the open cm service or process.
     If no service or process is currently connected to,  CID  is
     set to -1.

  -subobjects
     A read only option that returns a list  of  objects  created
     remotely through this cmt.

  -nameserver
     The hostname of the machine to use as  a  name  server  when
     starting services.

  -nameserver_port
     The port number of the nameserver process.

  -local_close_command
     The command to be called when a connection to a  service  or
     process is closed.

  -check_cmd
     The command is called to check the validity of  all  inbound
     dp_RPC/dp_RDO commands.  See dp_SetCheckCmd in the dp_rpc(n)
     manual page.

  -remote_close_command
     The command executed remotely is a connection to  a  service
     or process is closed.

  -local_lost_connection_command
     The command executed locally if the connection to a  service
     or  process  is unexpectedly lost. This command does not get
     executed if the connection was properly closed.

  -remote_lost_connection_command
     The command executed remotely if the connection to a service
     or  process  is unexpectedly lost. This command does not get
     executed if the connection was properly closed.

DESCRIPTION
     The cmt command creates a new cmt object which can  be  used
     to  connect  to  cm  services and processes running on other
     machines.  Once a connection to  a  service  or  process  is
     established,  the  cmt object can be used to create and con-
     trol other cm objects (including cmt's) in the  remote  pro-
     cess. Using cmt objects to create and link togethor other cm
     objects is the primary method of building applications  with
     the cm toolkit.

WIDGET COMMANDS
     The  cmt  command  creates   a   new   command   objectName.
     ObjectName is generated by concatenating the value of parent
     and a unique string which is  generated  on  the  fly.   The
     empty string is a valid value for parent.  This new command,
     objectName, is used to  invoke  various  operations  on  the
     widget.

     For more information on object names and why they  are  gen-
     erated  by  the  cm  process and not set by the user, please
     read the object management overview for the cm toolkit.

     The command objectName has the following general form:

          objectName option ?arg arg arg...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible:

     objectName configure option ?value option value ...?
          Query or modify  the  configuration  options  described
          above.   Attempting  to  modify a read only option will
          produce an error.

     objectName open -host hostname port_number
     objectName open -service service_name
     objectName open -local
          Opens a connection to a  cm  process  or  service.  The
          remote  process can be specified in one of two ways. By
          using the -host method, the hostname and portnumber  of
          the  process  is  explicitly  specified.  The  -service
          method attempts to contact the nameserver and  have  it
          establish the connection to the specified service.  The
          -local method creates a channel of control to the local
          process without going through any tcl-dp mechanisms. By
          using a cmt object as a channel of  control  for  local
          objects,  the  object  management  facilities  such  as
          object tagging are made  available.  In  addition,  the
          syntax  for  creation and control of local objects will
          match that of remote objects.

     objectName getCID
          Returns the CID. This is just a short cut  command  for
          querying   the   read  only  CID  configuration  option
          described above.

     objectName close
          Closes the connection if open. If  not  open,  it  does
          nothing.

     objectName info keyword(s)
          The info command returns information about the  process
          or  service  to  which currently connected. If not con-
          nected to a service or process, this command will  gen-
          erate  an  error.  The keyword acts as an index to what
          information you want. The information  resides  in  the
          remote service or process. If keyword is not recognized
          or if no information was registered under keyword,  the
          command returns empty string. The following is the list
          of valid keywords:

               service
                    Returns the name of the service.

               version
                    Returns the version number of the service.

               media
                    Returns a list of supported media  types.  An
                    example  of  return  values  might be: {video
                    audio subtext}.

               formats media
                    Given the media type media, returns a list of
                    supported  formats. For example, if media was
                    "video", the return value  might  be:  {mpeg,
                    ucb_mpeg_clip, mjpeg, parrallax_mjpeg}

               objects media format
                    Given the media type  media  and  the  format
                    type  format,  returns  a  list of all object
                    types in the remote service or  process  that
                    can deal with this type of data.

               object_info object_type
                    Returns any information registered with  this
                    object type.

     objectName rpc  ?-events  events?   ?-timeout  milliseconds?
     ?-timeoutReturn callback?  command ?args?
          Sends command and args to the remote cm service or pro-
          cess  for  execution.  The  results  are  returned. The
          -events,  -timeout,  and  -timeoutReturn  options  work
          exactly as documented in the Tcl_DP package.

     objectName rdo  ?-callback  callback?   ?-onerror  callback?
     command ?args?
          Sends command and args to the remote process for execu-
          tion  but  does not wait for a return value. The -call-
          back and -onerror options work  as  documented  in  the
          Tcl_DP package.

     objectName create_object object_type
          This command creates a new object in the remote process
          of  type  object_type.   The  remote  object's  name is
          returned. The remote object's name is also bound to the
          procedure of the same name to invoke and and manipulate
          the remote object. This procedure  is  simply  a  local
          wrapper  that passes any arguments to the remote object
          through the cmt connection.  A few commands and  confi-
          guration  options  for  the remote object, however, are
          dealt with by this local procedure wrapper and  not  by
          the  remote  object  itself.  This  ensures that all cm
          objects will have these configuration options and  com-
          mands  in  common. The common configuration options are
          are set through  the  cmt  object's  "configure_object"
          command  described below. The common commands make up a
          general tagging facility for cm objects. These commands
          are  described next. For more information, please refer
          to the CM Toolkit Object Management Overview.

               Common Commands

               remoteObjectName addtag tag
                    Adds the tag, tag, to remoteObjectName's  tag
                    list.

               remoteObjectName gettags
                    Returns remoteObjectName's tag list.

               remoteObjectName getalltags
                    Returns a list of (CID, taglist) pairs  asso-
                    ciated  with remoteObjectName.  This facility
                    may be useful if the remote object  is  actu-
                    ally  being  shared by more than one applica-
                    tion. The CID  specifies  which  process  has
                    associated   the   taglist  with  the  remote
                    object.

               remoteObjectName deltag tag
                    Deletes the tag, tag, from remoteObjectName's
                    taglist.

     objectName destroy
          Destroys objectName.  This command  also  destroys  any
          remote  objects  created  through objectName as well as
          closing the connection to the cm process or service.

     objectName getobjs ?tag?
          If tag is specified,  returns  a  list  of  all  remote
          objects  created through objectName that contain tag in
          their taglists. If tag is not specified, simply returns
          a list of all objects created through objectName.

     objectName getallobjs tag
          Returns a list of pairs (CID,  object_list)  such  that
          each object in each object_list has tag as part of it's
          taglist. The CID serves to indicate  which  application
          created the objects in the associated object_list.

     objectName configure_object remoteObjectName  option  ?value
     option value ... ?
          Queries and modifies the common  configuration  options
          for remoteObjectName.  The common configuration options
          available are:

               -local_lost_connection_command
                    The command to execute if the  connection  to
                    the remote process is unexpectedly lost.

               -local_destroy_command
                    The command to execute locally if the  remote
                    object is destroyed.

               -remote_lost_connection_command
                    The command to execute remotely if  the  con-
                    nection to the remote process is unexpectedly
                    lost.

               -remote_destroy_command
                    The command to execute remotely if the remote
                    object is destroyed.

KEYWORDS
     cm, cmt, cm toolkit

AUTHORS
     Ketan Patel (kpatel@cs.berkeley.edu)