I.    TSM Interaction with EDT
    
      TSM requires of the library the ability to:

            mount a volume 
	    dismount a volume
	    eject a volume to a export station
	    query the status of a volume
	    release a volume to a scratch tape pool

      TSM communicates to EDT by starting an elmdt child process, opens a
      pipe, and sends through a string containing a command, a library name, 
      and additional fields in support of these commands.  EDT, at its
      simpliest, translates the commands onto ACSLS and then translates the
      results back to TSM.

      In greater detail, TSM starts a elmdt process to complete a specified
      task or set of tasks, then severs connection with the elmdt process
      which in turn exits.  The task or sets of tasks can be shown and thought
      of as process cycles:

            initialize
	    initialize - mount - dismount
	    initialize - release
	    initialize - begin batch - query vol - query vol ... end batch
	    initialize - begin batch - query vol - eject vol - que...end batch

      The singular initialize occurs when TSM initializes.

      A variety of processes require a volume mount including backup/restore,
      archive/retrieve, dbbackup, copy storage pool.

      Release occurs when there is no longer any valid data left on the volume
      and it can be returned to the scratch pool.  Either an administrative
      discard data or reclamation process will result in a release operation.
      Also move drmedia from state vault will result in a release operation. 

      The batched volume queries occur on query drmedia and query media.
      The batched volume queries occur on move drmedia and move media.


      Initialize is accompanied by a library name matching the external
      library definition within TSM.  EDT must reply either: 
            SUCCESS  NOT_READY  INTERNAL_ERROR 


      Release is accompanied by a library name and a volume name. 
      EDT must reply either:
            SUCCESS  INTERNAL_ERROR
	    VOLUME_UNKNOWN  VOLUME_UNAVAILABLE  

      TSM however, no matter the return will consider the volume released.


      Query vol is accompanied by a library name and a volume name.  
      EDT must reply either:
            SUCCESS  LIBRARY_ERROR  INTERNAL_ERROR
	    VOLUME_UNKNOW  VOLUME_UNAVAILABLE  
	    CANCELLED  TIMED_OUT  

      If non success, EDT must state volume status as UNDEFINED.  
      If success, EDT must state volume status as IN_LIBRARY or NOT_IN_LIBRARY.

    
      Eject vol is accompanied by a library name and a volume name.  
      EDT must reply: 
            SUCCESS  LIBRARY_ERROR  INTERNAL_ERROR
	    VOLUME_UNKNOWN  VOLUME_UNAVAILABLE  
	    CANCELLED  TIMED_OUT INTERNAL_ERROR


      Dismount vol is accompanied by a library name and a volume name.  
      EDT must reply:
            SUCCESS  DRIVE_ERROR  LIBRARY_ERROR INTERNAL_ERROR
      TSM however, no matter the return will consider the volume dismounted. 


      Mount vol is accompanied by a library name, a volume name or SCRTCH,
      access mode readwrite or readonly, drivetype, and a mount wait time
      limit. EDT must reply: 
            SUCCESS  DRIVE_ERROR  LIBRARY_ERROR  INTERNAL_ERROR
	    VOLUME_UNKNOWN VOLUME_UNAVAILABLE
	    CANCELLED  TIMED_OUT

      If success, EDT must also supply the device name through which TSM can
      direct data I/O, and in the case of a scratch mount request, supply the
      name of the volume mounted.

      TSM's reaction to a failed mount is varied, depending on what process is
      requesting the mount.  However, there are several rules of thumb that
      can be followed.  

	  - If volume unavailable is returned TSM tends to mark
	    the volume as unavailable.  An administrator must update the
	    volumes  access to readwrite in order for the volume to be again
	    available for mount.  
         -  If the returned error is drive error, TSM tends to retry upwards
	    of 3 times to again request the mount of the volume.  
	 -  Other failure returns tend to force the requesting process to
	    cancel or retry at a later time.


II.   Mount Control Variables

      There are several control variables within TSM that control aspects of
      the EDT mount-dismount process cycle. 

      Some are connected to the device class.

            mount wait:	
	    sets the amount of time EDT waits for an available drive or for a
	    volume to be freed from a drive.  This wait period is passed onto
	    EDT as the timelimit parameter with the mount command.  By default
	    this period is 60 minutes.

            mount retention:
	    determines the amount of time a volume remains idle in a drive.
	    Once mount retention period expires, a dismount is issued to
	    EDT. The default retention period is 60 minutes.

	    mount limit:
	    controls the number of concurrent mount requests.
	    Mount limit must be set equal to or less than the physical number
	    of drives defined in an EDT library description. This description
	    bares the same libname as the TSM external library definition.

      One is connected to the storage pools associated with a device class.

            maxscratch:
	    In order to activate the ability to request scratch volume mounts,
	    this value must be set higher than the default of 0.

      
      Drive sharing guidelines:
      - Mount retention must be set low, 2 minutes or less.      
      - Mount limit must be equal to or less than the physical number of 
	drives that EDT is configured to use.
      - Adjusting mount wait time for Mount Traffic Control.
	see guide "EDT Functionality".


III.  TSM configuration for external library manager.

      NOTE:  For LAN Free configuration, do not use this example.

      A configuration example for TSM is shown in the EDT Config guide.  Its a
      fairly basic set up:
            - define an external library definition referenced by "libname".
	    - define the library path to the EDT executable elmdt
            - define a device class, setting the drive type, associating it
	      with the library, and setting mount control variables.
	    - defining storage pools, associating it with the device class and
	      setting max scratch limit. 
            - creating and activating a management policy to backup and
	      archive to the storage(s) pools.

      Two major differences you will note between the example and a typical
      TSM setup is that there is no need to define drives and no need to go
      through a lib inventory checkin.


      set servername <servname>
      ex: set servername SERV1

      register node <nodename> <password> domain=standard
      ex: register node kazak admin domain=standard


      define library <libname> libtype=external
      ex: define library TSM1 libtype=external

      define path <source> <dest> srctype=server desttype=library \
      externalmanager=<path>

      ex: define path SERV1 TSM1 srctype=server desttype=library \
	  externalmanager='/usr/lpp/GESedt-acsls/bin/elm'

      define devclass <name> devtype=<type> library=<libname> \
      mountlimit=<number of physical drives> mountretention=<time>

      ex: define devclass DEV1 devtype=ECART library=TSM1 \
      mountlimit=2 mountretention=2


      At this juncture, you should be able to do a dbbackup
    
      backup db devclass=<name> type=full scratch=yes
      ex: backup db devclass=DEV1 type=full scratch=yes

      NOTE: You must have volumes assigned to your media manager
      scratch category.

      define stg <name> <devclassname> maxscratch=#
      ex: define stg STG1 DEV1 maxscratch=1000

      To go directly to tape:
      update co standard standard standard type=backup dest=STG1
      activate po standard standard


IV.   How Volumes are Requested for Mount, Private and Scratch Volumes
   
      Normally, the TSM data storage manager requires that you go through a 
      checkin process in which volumes are "checked in" to a library with 
      either "private" or "scratch" status.  This provides an inventory of 
      volumes that can be requested for mount.  This list is shown with the 
      TSM command, "query library volume".

      Private status volumes must be directly assigned to a TSM storage pool 
      in order for them to be requested for mount.  This is done with the
      command: "define vol <stgpool> <volid>"
      Volumes assigned directly to a TSM storage pool, must already contain a
      valid internal tape label.  Use the utility elm_label, if a label needs
      to be placed on a volume.

      Scratch status means the volumes do not need to be assigned directly 
      to a TSM storage pool to be requested for mount.  When a storage pool 
      is defined, you may set the "maxscratch" parameter to a number greater 
      than 0, which enables scratch use; you can also update the storage pool 
      to set the maxscratch parameter.

      Scratch volumes are selected in the following manner.  
      - If there are no private volumes or all private volume are full, and 
        scratch use is enabled for a TSM storage pool, a scratch volume is 
        requested for mount.  
      - Once a scratch volume is mounted for data storage, it is assigned to 
        the TSM storage pool as a private volume.
      - Thereafter, the volume is requested for mount by name.  

      Additional mount requests will always look first to see if a private
      volume can be used to store data ahead of requesting a scratch volume.
      If any one of the following reasons exist, a mount scratch request will
      be made instead of a request for a private volume:
      - All private volumes full.
      - Private volumes access is readonly or unavailable, and request is 
        for a readwrite volume.
      - All eligible private volumes are currently in use.
      - Collocation is enabled, where volumes will contain data for specific
        clients.

      Over time (and in a short period of time at that) the inventory of
      private volumes assigned to the TSM storage pool will build.


      When TSM has finished with a volume it is "released" back to the scratch
      tape pool.
 

V.    EDT and TSM's DRM.

      DRM is a optionally licensed TSM module.  It works hand in hand with the 
      backup storage pool operation easing the tracking of copy volumes and 
      database backup volumes moved offsite and reintroduced back into the 
      robotic library.

      There are two main drmedia operations:
      Query Drmedia: Query volumes to see if they are in the library or not.
      Move Drmedia:  Move drmedia volumes out or back into the library.

      When move drmedia is used to eject volumes from the library, it sends an
      eject request for each volume onto EDT.  The problem is that ACSLS eject
      is interactive.  You will not receive a response until either the eject
      command times out or a tape operator opens the cap door, removes the
      volume, closes the cap door, and the robot scans the cap.  Performing
      this task for each drm volume is unfeasible.

      Because of this, EDT by default dummies out an eject request and returns
      and returns success.  
      - You can run move drmedia in a manner that places the name of the
        volume into a file creating a list of volumes to be ejected.  
      - You can then use the acsls_eject utility to open the file and
	eject the volumes a cap door full at a time.  
      - Furthermore, if you run move drmedia in the recommended fashion, and
	your eject process fails,  it is a simple matter to get TSM to update
	drmedia status back to a mountable state for another try and moving
	the volumes back out of the library. 

      Recommended Method:

      When vols are in the notmountable state you can run q drmedia and it
      will contact EDT to see if the vols are truly in the library.  If so, q
      drmedia will convert any vol still in the library to the mountable
      state, thereby syncing TSM with reality.

      ex: q drmedia

      Volume Name        State         Last Update           Automated       
                                       Date/Time             LibName         

      001311             Mountable     04/07/04 20:23:14     LIB1            
      001312             Mountable     04/07/04 20:30:14     LIB1            
      001314             Mountable     04/07/04 19:43:49     LIB1


      Run your move drmedia command in the following format:

      example:
	    move drmedia * wherestate=mountable copystgpool=COPY_STG1 \
	    cmd="&VOL" cmdfilename=/tmp/vol_list.txt append=yes

      - Notice that the second continuation line shows the name of the volume
        being processed by move drmedia is appended to a list volnames.

      - Notice that the state is not being pushed all the way to vault.
	The next automated state is "not mountable".  If the eject later
        fails, you can do q drmedia, EDT confirms a vol is still in the
        library, and the drmedia state is turned back to "mountable".

      - If you move from state mountable "tostate=vault", and later the real
        eject fails, you will have to update each volume in TSM back to access
        readwrite and each dbbackup vol has to have the volhistory updated.

      - If you add to move drmedia tolocation="message txt" and you have tape
        operator messages enabled, you will see in the EDT message log:

	example:
		<368718> EDT0460  SEV 5  07-05-2004 11:41:06
			 EJECT ISV007
			 message text


      Once the vol list is established, run the utility, acsls_eject, ejecting
      vols a cap door full at a time:

      example:  acsls_eject -l /tmp/vol_list.txt -c 0,0,0 -d 12

        
      If the eject fails at any time, run q_drmedia once again to establish
      what vols are again "mountable".  In general it would not hurt to again
      run q drmedia.


      Finally, run move drmedia, moving vols to the vault state:

      example:
	    move drmedia * wherestate=notmountable copystgpool=COPY_STG1 \
	    tostate=vault.

      Once volumes are in the vault state, q drmedia will no longer contact
      EDT to see if the volume is in the library.


VI.   Scanning Scratch pools for vols owned by TSM.

      Utility elm_filter_vols provides a method of filtering TSM storage pools
      and volume history for volumes it is using.  You can use the created
      list of volumes with the set scratch utility to scan ACSLS scratch tape
      pools and remove any volume owned by TSM if found in the pool.

      *NOTES*  
      - This program opens a shell to the system and executes
        the tsm administrative command dsmadmc.  If you observe the 
        output of the program, you will see the form of the dsmadmc command.
      - The exception is under Windows, where the command wzrdhlpr.exe is
        executed, usually found in Program Files\tivoli\tsm\console.
        This program is finicky about how it is called and needs the support of
        several other files from the console directory.  You are best served
        to copy the the files wzrdhlpr.exe, dscameng.txt, and DSM.OPT in the
        console directory into the EDT-ACSLS bin directory where the
        elm_filter_vols resides.


      #! /bin/ksh
      #

      EDT=/usr/lpp/GESedt-acsls/bin
      EDTUTIL=/usr/lpp/GESedt-acsls/util

      # Create list of all volumes assigned to storage pools,

      $EDT/elm_filter_vols -I admin -P admin -q -F 
      sleep 1

      # Scan volume history for all volumes of type dbbackup, append volume
      # names to list in file.
      $EDT/elm_filter_vols -o dbbackup -F -A
      sleep 1

      # Do the same for any dbdump and export volumes
      $EDT/elm_filter_vols -o dbdump -F -A
      sleep 1
      $EDT/elm_filter_vols -o export -F -A
      sleep 2

      # Proceed with scratch pool cleanse
      $EDTUTIL/acsls_setscratch -f ./vol_list.txt -c -p 100

      rm -f vol_list.txt
      return 0
      # end of script



      If you wish to only check newly created volumes:

      
      #! /bin/ksh
      #

      EDT=/usr/lpp/GESedt-acsls/bin
      EDTUTIL=/usr/lpp/GESedt-acsls/util

      # Create list of all volumes assigned to storage pools,
      # create temporary file, base name vollist, and redirect list to file.

      $EDT/elm_filter_vols -q -F
      sleep 1

      # Scan volume history for all volumes of type dbbackup, append volume
      # names to list in file.
      $EDT/elm_filter_vols -o dbbackup -F -A
      sleep 1

      # Do the same for any dbdump and export volumes
      $EDT/elm_filter_vols -o dbdump -F -A
      sleep 1
      $EDT/elm_filter_vols -o export -F -A
      sleep 2

      # Read volume names from list and report ownership of vols
      # Place any errors or standard output in file daily_volrpt.txt

      if [ -a vol_list_save.txt ] ; then
	  diff vol_list.txt vol_list_save.txt > vol_list_diff.txt
      else
	  cp vol_list.txt vol_list_diff.txt
      fi

      # Proceed with scratch pool cleanse
      $EDTUTIL/acsls_setscratch -f ./vol_list.txt -c -p 100

      sleep 1

      mv vol_list.txt vol_list_save.txt
      rm -f vol_list.txt
      rm -f vol_list_diff.txt
      return 0

      # end of script