You are on page 1of 11

Appendix A.

External Media Management Interface Description
This appendix contains Programming Interface information for the interface that Tivoli Storage Manager provides to external media management programs. The interface consists of request description strings that Tivoli Storage Manager sends and response strings that the external program sends. To use the interface, you must first define an EXTERNAL-type TSM library that represents the media manager. You do not define drives, label volumes, or check in media. See Configuring Libraries Controlled by Media Manager Programs. Refer to your media manager's documentation for that product's setup information. The details of the request types and the required processing are described in the sections that follow. The request types are:         Initialization of the external program Begin Batch End Batch Volume Query Volume Eject Volume Release Volume Mount Volume Dismount

The responses can be right-padded with any number of white-space characters. The libraryname passed in a request must be returned in the response. The volume specified in an eject request or a query request must be returned in the response. The volume specified in a mount request (except for 'SCRTCH') must be returned in the response. When 'SCRTCH' is specified in a mount request, the actual volume mounted must be returned.

CreateProcess Call
The server creates two anonymous uni-directional pipes and maps them to stdin and stdout during the CreateProcess call. According to Microsoft Developer Network documentation, if a standard handle has been redirected to refer to a file or a pipe, the handle can only be used by the ReadFile and WriteFile functions. This precludes normal C functions such as gets or printf. Since the server will never terminate the external program process, it is imperative that the external program recognize a read or write failure on the pipes and exit the process. In addition, the external program should exit the process if it reads an unrecognized command. The external program may obtain values for the read and write handles using the following calls: readPipe=GetStdHandle(STD_INPUT-HANDLE) and writePipe=GetStdHandle(STD_OUTPUT_HANDLE)

7. performs any necessary cleanup. in text form. The server sends an initialization request description string (in text form) into the standard input (stdin) stream of the external program. 8. 2. into the standard input (stdin) stream of the external program. 2. 3. The server loads the external program in a newly created process and creates pipes to the external program. 4. in text form. Processing for Mount Requests To process the mount request: 1. 3. The server waits for the response. The agent sends the MOUNT response (stdout). the process must write an initialization response string (in text form) into its standard output (stdout) stream. the following must occur during server initialization: 1. The agent waits. into its standard output ( stdout) stream. The server waits for the response. The server sends the RELEASE request (stdin). the process must write an initialization response string (in text form) into its standard output (stdout) stream. 4. Processing for Release Requests To process the release request: 1. The server waits for the response. The server sends the DISMOUNT request (stdin). it performs any necessary cleanup and calls the stdlib exit routine. 2. The server closes the pipes. The server sends an initialization request description string (in text form) into the standard input (stdin) stream of the external program. When the agent detects that the pipes are closed. 5. The server sends the MOUNT request (stdin). The server loads the external program (CreateProcess) in a newly created process and creates pipes to the external program. For each external library defined to the server. the process must write an initialization response string. When the external process completes the request. The server loads the external program in a newly created process and creates pipes to the external program. . 5. The agent sends the DISMOUNT response (stdout). 3.Processing during Server Initialization Ensure that the external media management program cooperates with the server during the server's initialization. 4. The server sends an initialization request description string. When the external process completes the request. 6. and calls the stdlib exit routine. When the external process completes the request.

the agent will continue to send these requests. The agent sends the RELEASE response (stdout). performs any necessary cleanup. performs any necessary cleanup. and terminate the current request. The server waits for the response. The agent will detect this when it tries to read from stdin or write to stdout. If the server gets an error while trying to write to the agent. The server sends an initialization request description string (in text form) into the standard input (stdin) stream of the external program. 5. the agent performs any necessary cleanup and calls the stdlib exit routine. 3. If this occurs. The server sends the RELEASE request (stdin). RESULT=resultCode . TSM does not proceed with the subsequent steps. 2. The agent sends the RELEASE response (stdout). it will close the pipes. and calls the stdlib exit routine. After the agent sends a non-SUCCESS return code for any response. and calls the stdlib exit routine. the agent will perform any necessary cleanup and call the stdlib exit routine. the process must write an initialization response string (in text form) into its standard output (stdout) stream. The server loads the external program in a newly created process and creates pipes to the external program. perform any necessary cleanup. even if the code for EJECT or QUERY requests is not equal to SUCCESS. Begin Batch Request The format of the Begin Batch Request is: BEGIN BATCH Format of the external program response: BEGIN BATCH COMPLETE. 4. Processing for Release Requests To process the release request: 1. Error Handling If the server encounters an error during processing. it will close the stdin and stdout streams to the agent exit. If the code for any response (except for EJECT and QUERY) is not equal to SUCCESS. However. When the external process completes the request.5.

RESULT=resultCode where: resultCode One of the following:   SUCCESS INTERNAL_ERROR Volume Query Request The format of the Volume Query Request is: QUERY libraryname volume where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. The external agent must send the End Batch Response and end by using the stdlib exit routine. The format of the End Batch Request is: END BATCH Format of the external program response: END BATCH COMPLETE. Format of the external program response: . volume Specifies the volume name to be queried.where: resultCode One of the following:   SUCCESS INTERNAL_ERROR End Batch Request The End Batch Request is sent by TSM to indicate that no more requests are to be sent by the external library manager for the current process.

If the initialization is not successful. The external media management program can detect whether the initialization request is being sent by itself or with another request by detecting end-offile on the stdin stream. volume Specifies the volume name queried. the server sends an initialization request to the external media management program for each EXTERNAL library. the external program must end by using the exit routine. The server sends an initialization request first. If resultCode is SUCCESS. the exit must return statusValue set to UNDEFINED. The external program must process this request to ensure that the external program is present. RESULT=resultCode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. and ready to process requests. TSM informs its operators that the external program reported its readiness for operations. NOT_IN_LIBRARY means that the volume is not currently in the library.QUERY libraryname volume COMPLETE. Format of the request: . When a valid response is sent by the external program. the external program must end by using the stdlib exit routine (not the return call). If the initialization request is successful. STATUS must be one of the following values:   IN_LIBRARY NOT_IN_LIBRARY IN_LIBRARY means that the volume is currently in the library and available to be mounted. If the initialization is successful. functional. When end-of-file is detected. TSM reports a failure to its operators. the request is sent. resultCode One of the following:        SUCCESS LIBRARY_ERROR VOLUME_UNKNOWN VOLUME_UNAVAILABLE CANCELLED TIMED_OUT INTERNAL_ERROR If resultCode is not SUCCESS. TSM does not attempt any other type of operation with that library until an initialization request has succeeded. STATUS=statusValue. Otherwise. the request fails. Initialization Requests When the server is started.

INITIALIZE libraryname where libraryname is the name of the EXTERNAL library as defined to TSM. Format of the external program response: EJECT libraryname volume COMPLETE. Set this field to some target location value that will assist in placing the volume after it is ejected from the library. It is delimited with single quotation marks. This information is passed without any modification from the TSM inventory. RESULT=resultCode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. Format of the external program response: INITIALIZE libraryname COMPLETE. volume Specifies the volume to be ejected. It is suggested that the external agent post the value of this field to the operator. RESULT=resultcode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. resultcode One of the following:    SUCCESS NOT_READY INTERNAL_ERROR Volume Eject Request The format of the Volume Eject Request is: EJECT libraryname volume 'location info' where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. The customer is responsible for setting its contents with the appropriate UPDATE MEDIA or UPDATE VOLUME command before the move command is invoked. . 'location info' Specifies the location information associated with the volume from the TSM inventory.

RESULT=resultcode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. then issues a request to release a volume. resultcode . The synchronization can be a manual operation. For this reason. TSM returns the volume to scratch. the server starts the external media management program. the external program should log the failure so that the external library inventory can be synchronized later with TSM. The external program must send a response to the release request. resultCode One of the following:        SUCCESS LIBRARY_ERROR VOLUME_UNKNOWN VOLUME_UNAVAILABLE CANCELLED TIMED_OUT INTERNAL_ERROR Volume Release Request When the server returns a volume to scratch status. Format of the external program response: RELEASE libraryname volname COMPLETE.volume Specifies the ejected volume. volname Specifies the name of the volume to be returned to scratch (released). volname Specifies the name of the volume returned to scratch (released). No matter what response is received from the external program. TSM and the external program can have conflicting information on which volumes are scratch. If an error occurs. Format of the request: RELEASE libraryname volname where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. issues a request to initialize.

Format of the request: MOUNT libraryname volname accessmode devicetypes timelimit userid volumenumber 'location' where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. The volume mounted by the external media management program must be a tape with a standard IBM label that matches the external volume label. Possible values are:             3480 3480XF 3490E 3570 3590 3590E 4MM_DDS1 4MM_DDS1C 4MM_DDS2 4MM_DDS2C 4MM_DDS3 4MM_DDS3C . Possible values are READONLY and READWRITE. then issues a request to mount a volume. The most preferred device type is first in the list. accessmode Specifies the access mode required for the volume. Items are separated by commas. the volname is set to SCRTCH. the external program must end immediately by using the stdlib exit routine. with no intervening spaces. If the mount was successful. the external program must remain active. the program must send a response. The external program is responsible for verifying that this request is coming from TSM and not from an unauthorized system. volname Specifies the actual volume name if the request is for an existing volume. When the external program completes the mount request. issues a request to initialize. the server starts the external media management program. devicetypes Specifies a list of device types that can be used to satisfy the request for the volume and the FORMAT specified in the device class. If the mount failed.One of the following:     SUCCESS VOLUME_UNKNOWN VOLUME_UNAVAILABLE INTERNAL_ERROR Volume Mount Request When the server requires a volume mount. If a scratch mount is requested.

. userid Specifies the user ID of the process that needs access to the drive. the external manager responds with the result code TIMED_OUT.                                             4MM_DDS4 4MM_DDS4C 4MM_HP_DDS4 4MM_HP_DDS4C 8MM_8200 8MM_8205 8MM_8500 8MM_8500C 8MM_8900 8MM_AIT 8MM_AITC 8MM_ELIANT 8MM_M2 DLT_2000 DLT_4000 DLT_7000 SDLT DLT_8000 DTF2 DTF GENERICTAPE IBM_QIC4GBC LTO_ULTRIUM OPT_RW_650MB OPT_RW_1300MB OPT_RW_2600MB OPT_RW_5200MB OPT_WORM_650MB OPT_WORM_1300MB OPT_WORM12_5600MB OPT_WORM12_12000MB OPT_WORM14_14800MB QIC_12GBC QIC_20GBC QIC_25GBC QIC_30GBC QIC_50GBC QIC_IBM1000 QIC_525 QIC_5010C REMOVABLEFILE STK_9490 STK_9840 STK_9940 STK_SD3 timelimit Specifies the maximum number of minutes that the server waits for the volume to be mounted. If the mount request is not completed within this time.

After the dismount response is sent. specialfile The fully qualified path name of the device special file for the drive in which the volume was mounted. volname Specifies the name of the volume mounted for the request. If no location information is associated with a volume. When the dismount operation completes. 2 for side B. If the mount request fails. the external process must wait for a request to dismount the volume. nothing is passed to the exit. the value should be set to /dev/null. if volume information is passed. the single quotation marks are not passed. If no volume information exists. One blank character is inserted between the volume number and the left single quotation mark in the location information. the volumenumber is 1 for side A. the volumenumber is 1. Format of the external program response: MOUNT libraryname volname COMPLETE ON specialfile. The external program must ensure that the special file is closed before the response is returned to the server.volumenumber For non-optical media. . then probably the volume has been ejected from the library and needs to be returned to the library before the mount operation can proceed. For optical media. resultcode One of the following:         SUCCESS DRIVE_ERROR LIBRARY_ERROR VOLUME_UNKNOWN VOLUME_UNAVAILABLE CANCELLED TIMED_OUT INTERNAL_ERROR Volume Dismount Request When a successful mount operation completes. the external process ends immediately by using the stdlib exit routine. the external program must send a response to the server. Also. 'location' Specifies the value of the location field from the TSM inventory (for example. The location information should be posted by the agent so that the operator can obtain the volume and return it to the library. RESULT=resultcode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. 'Room 617 Floor 2').

Format of the external program response: DISMOUNT libraryname volname COMPLETE. volname Specifies the name of the volume to be dismounted. volname Specifies the name of the volume dismounted. RESULT=resultcode where: libraryname Specifies the name of the EXTERNAL library as defined to TSM. resultcode One of the following:     SUCCESS DRIVE_ERROR LIBRARY_ERROR INTERNAL_ERROR .Format of the request: DISMOUNT libraryname volname where: libraryname Specifies the name of the EXTERNAL library as defined to TSM.