libmms(3LIB)							Interface Libraries						      libmms(3LIB)

NAME

       libmms - Media Management System library

SYNOPSIS

       cc [ flag... ] file... -lmms [ library... ]

DESCRIPTION

       Functions in this library provide access to the Media Management System (MMS).

       The  Media  Management  System  (MMS) is a distributed removable media management system. It is based on IEEE 1244, Media Management System
       (MMS). Client applications request MMS to mount and unmount cartridges and process them after they are mounted. Applications use Media Man-
       agement Protocol (MMP) commands to make requests. The Media Management System (MMS) client API provides basic functions that give an appli-
       cation the ability to connect to MMS, send commands to MMS, and interpret the responses to the commands.

       For a client to establish a connection to MMS, it needs to first initialize a session and then establish  the  connection.  There  are  two
       types of sessions:

       synchronous     A synchronous connection means that the client waits for a response for each command that it sends to MMS.

       asynchronous    A asynchronous connections means the client can continue to send commands to MMS without waiting for a response to the com-
		       mands.

       The type of session is specified with the choice of initialization function, either mms_init() or mms_ainit().

       The connection is established with the hello function, mms_hello().

       Within an asynchronous session, the client can also send synchronous commands.

       If a client's instance is configured to allow multiple sessions, the client can create more than one session, in any  combination  of  syn-
       chronous and asynchronous types. The client must manage which commands are sent over which session.

       If  the	client's  instance  is not configured to allow multiple sessions and a second init function is called, the client's hello function
       receives an "unwelcome" response from MMS.

       Any command sent using the asynchronous send function, mms_send_acmd(), specifies a callback routine that  is  invoked  when  the  MMS  API
       receives  a response to the command. This callback routine is a client-specified function. A callback function can not issue other commands
       to MMS because the callback function is executed as part of the MMS API's reader thread.

       An asynchronous session allows the client to also issue commands using  the  synchronous  send  function,  mms_send_cmd(),  waiting  for  a
       response before returning.

       A client can receive notification of certain events that occur within MMS through the event notification mechanism.

       Routines are provided by the API to help in the processing of responses to the client's commands.

       For OpenSolaris platforms, libmms is released in shared object (.so) format, installed in /usr/lib/libmms.so.

       The following table lists libmms library routines and indicates the type of connection that supports them and whether they are optional.

	     Routine		     Availability		     Required
       ---------------------------------------------------------------------------------
       mms_init()	     synchronous		    required for synchronous
       ---------------------------------------------------------------------------------
       mms_ainit()	     asynchronous		    required for asynchronous
       ---------------------------------------------------------------------------------
       mms_hello()	     synchronous and asynchronous   required for both
       ---------------------------------------------------------------------------------
       mms_send_cmd()	     synchronous and asynchronous   required  for  synchronous,
							    optional for asynchronous
       ---------------------------------------------------------------------------------
       mms_send_acmd()	     synchronous and asynchronous   required for  asynchronous,
							    optional for synchronous
       ---------------------------------------------------------------------------------
       mms_read_response()   synchronous and asynchronous   required  for  intermediate
							    response to mms_send_cmd()
       ---------------------------------------------------------------------------------
       mms_free_rsp()	     synchronous and asynchronous   required for both
       ---------------------------------------------------------------------------------
       mms_goodbye()	     synchronous		    required for synchronous
       ---------------------------------------------------------------------------------
       mms_agoodbye()	     asynchronous		    required for asynchronous

       The following routines are used by a client to to process the response to a MMS command.

       mms_rsp_type()	       Returns the type of response that was received for the command.

       mms_handle_err_rsp()    Returns the error code and error message from an error response.

       mms_get_tree()	       Returns the parse tree of the response.

       mms_get_attribute()     Obtains the value associcated with a attribute name from a response in namevalue mode.

USAGE

       To make a client application able to use MMS, build the client with access to the MMS API library routines and then configure the  applica-
       tion.

	   1.	  Get a copy of the MMS source tree.

	   2.	  Include <mms_api.h> and <mms_sym.h> in the makefile. The path is the san-andreas/include/$(OBJ_DIR). For example, OBJ_DIR is the
		  obj/SunOS_5.10_sparc_DEBUG.

	   3.	  Link the client to the mms library to get the MMS API. A client can link either statically or dynamically. To link  the  library
		  statically, the path is san-andreas/lib/$(OBJ_DIR). To link at runtime, MMS is installed in /opt/SUNWsmmms/lib/libmms.so.

	   4.	  Link with either libcommon.so or libcommon.a depending on if the client is dynamically linked or statically linked.

	   5.	  Create  the client's application name in MMS database. Client application instances must be created within MMS database in order
		  for clients to establish  a connection with MMS.

	   6.	  Use the MMS database password to connect to MMS. The default database password is a construction of the  administrator  password
		  with the characters " dbadmin" appended.

INTERFACES

       The shared object libmms.so.1 provides the public interfaces defined below. See Intro(3) for additional information on shared object inter-
       faces.

       mms_agoodbye		     mms_ainit
       mms_free_rsp		     mms_get_attribute
       mms_get_str		     mms_get_tree
       mms_goodbye		     mms_handle_err_rsp
       mms_hello		     mms_init
       mms_read_response	     mms_rsp_type
       mms_send_acmd		     mms_send_cmd

FILES

       /usr/lib/libmms.so.1	  shared object

       /usr/lib/64/libmms.so.1	  64-bit shared object

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWmmsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Uncommitted		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       Intro(3), mms_init(3MMS), mms_rsp_type(3MMS), mms_send_cmd(3MMS), attributes(5)

SunOS 5.11							    2 Dec 2008							      libmms(3LIB)