Management services are the services that manage the storage resources. For example, use a management service to enter a volume, eject a volume, and bring a volume online or offline.
These services need to communicate with the mechanical component of the solution, and the response time depends on the type of operation and the mechanical latencies. The management services are implemented as an asynchronous call. A management services is asynchronous because it returns before the job has been executed.
The completion of the operation returns a program or job ID which the calling service needs to call to obtain the results when they are available.
When the asynchronous service returns, it provides a job ID as part of the response. The return codes are.
0 (Web service call associated with this job ID is complete.)
1 (Web service call associated with this job ID is still in progress.)
-1 (No such web service call with the job ID is found in the system.)
The programmer implementing the Web Services client needs to periodically call the getJobStatus Web Service by passing it the job ID to obtain the status of the job.
Once getJobStatus returns a "0", call the getJobResult Web Service to obtain the service result.
Each asynchronous Web Services can take a varying amount of time to complete. The back-end times out if there is a failure on the mechanical side. This guide provides guidelines on the maximum recommended time for the third-party Web Services client to wait before timing out.
Refer to "Status Services" for information on getJobStatus and getJobResult.
To manage volumes using LTFS-LE, volumes must be assigned to the LTFS-LE application.
When a volume is assigned to LTFS-LE, it is automatically placed online and added to the default volume pool. When a non-formatted volume is assigned, the volume is automatically formatted for use with LTFS-LE.
assignVolume(String[] volsers)
Pre-conditions:
Verify that a compatible drive is available and that the volume is offline, unassigned, idle, not in a pool, and available before assigning the volume. The volume or volumes must exist in the library.
To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Ensure that the volume is in one of the required states and take corrective action, if necessary, before proceeding.
LTFS-LE Web Service to call:
assignVolume([volser1, volser2, ...]) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now assigned to the LTFS-LE software. If the volume is not LTFS-formatted, the volume is automatically LTFS-formatted.
volsers are the volume serial numbers of the volume or volumes to be assigned. The input parameters are an array of strings and enable multiple volumes to be assigned.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one or more volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Unassigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be assigned.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Unassigned to be assigned.
Example: The volume EL0010's LTFS-LE Assignment Status is Assigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be assigned.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be assigned.
Example: The volume SL0010's Inuse Status is In Use.
If the volume is already in the default volume pool, the exception thrown is: The volume <volser> is already assigned in the Default Volume Pool.
Example: The volume EL0010 is already assigned in the Default Volume Pool.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:assignVolume>
<arg0>F50233</arg0>
<arg0>F50234</arg0>
</ns1:assignVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns2:assignVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1220</return>
</ns2:assignVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume SL0010's Assignment Status is Assigned</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume SL0010's Assignment Status is Assigned</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This API function ejects one or more LTFS-LE volumes from the library.
Considering the message size, LTFS LE only supports ejecting up to 30 volumes using the mailslot (CAP). Ejects are done in fours until all volumes are completely ejected. There is no timeout. This is an asynchronous call.
ejectVolume(String[] volsers,String acs,String lsm,String cap)
Pre-condition:
Verify that: the volume(s) is finalized and offline before ejecting; a CAP is available; and the ACS is the same as the library configured. To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
If the volume is online and not in use, finalize the volume:
finalizeVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
If the volume is online, take the volume offline before executing the eject API call:
offlineVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
LTFS-LE WebService chain to call:
ejectVolume([volser1,volser2,...],acs,lsm,cap) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is ejected from the library. The user must walk up to the library and retrieve the volume after opening the CAP door.
volser is the serial numbers of the volume or volumes to be ejected.
acs is the library ACS identifier.
lsm is the library LSM identifier.
cap is the library CAP (mailslot) ID used to eject the volume.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one or more volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the number of volumes specified is greater than 30, the exception thrown is: The number of volumes to eject must be 30 or less.
If the acs parameter is null, the exception thrown is: The parameter acs is null.
If the lsm parameter is null, the exception thrown is: The parameter lsm is null.
If the cap parameter is null, the exception thrown is: The parameter cap is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Offline and Idle, the exceptions thrown are:
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to eject the volume.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to eject the volume.
Example: The volume SL0010's Inuse Status is In Use.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:ejectVolume>
<arg0>F50234</arg0>
<arg0>F50233</arg0>
<arg1>3</arg1>
<arg2>0</arg2>
<arg3>1</arg3>
</ns1:ejectVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401 -wss-wssecurity-secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:ejectVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1213</return>
</ns2:ejectVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume SL0010's Status is Online</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume SL0010's Status is Online</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This is an asynchronous call that enters one or more volumes into the library using the CAP (mailslot).
enterVolume(String acs,String lsm,String cap)
Pre-condition:
There is no specific pre-condition for entering a volume into the CAP. However, the administrator or service must gather the CAP identifier (acs, lsm, and cap_id), and ensure that a CAP is available and is not in the middle of an operation (pending, eject, enter, or audit) before executing this command.
LTFS-LE WebService chain to call:
enterVolume(acs,lsm,cap) getJobStatus(jobId) <poll each 10s until status is complete> getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is entered into the library.
acs is the library ACS identifier.
lsm is the library LSM identifier.
cap is the library CAP (mailslot) ID used to enter the volume.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If the acs parameter is empty, the exception thrown is: The parameter acs is null.
If the lsm parameter is empty, the exception thrown is: The parameter lsm is null.
If the cap parameter is empty, the exception thrown is: The parameter cap is null.
Examples:
ACS 4 is inconsistent with the library acs 7.
Invalid ACS number.
This depends on the time it takes the administrator to enter the volume into the CAP.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:enterVolume>
<arg0>3</arg0>
<arg1>0</arg1>
<arg2>1</arg2>
</ns1:enterVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:enterVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1212</return>
</ns2:enterVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text> Invalid ACS number. </ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>Invalid ACS number.</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
Use the finalizeVolume command to commit any changes to the volume. Typically, this action is performed before the volume is taken offline to be ejected out of the library. Finalizing a volume applies any unwritten metadata or unapplied file deletes to the volume. This action ensures that the actions on the global namespace are reflected on the physical volume. Failing to finalize a volume before taking it offline can likely delay taking the volume offline.
finalizeVolume(String volser)
Pre-conditions:
Verify that a compatible drive is available and that the volume is online, in a pool, idle, and available before finalizing the volume. To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Ensure that the volume is in all the required states and take corrective action, if necessary, before proceeding.
LTFS-LE Web Service to call:
finalizeVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, any pending operations that need to be applied to the volume have been applied to the volume.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
volser is the volume serial number of the volume to be finalized.
jobId is the job ID used to retrieve the job status and result.
ValidationFailedException
Exceptions can be thrown:
If the volser is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be finalized.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be brought offline.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Online to be brought offline.
Example: The volume EL0010's Status is Offline.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be brought offline.
Example: The volume SL0010's Inuse Status is In Use.
If the volume is not in the default volume pool, the exception thrown is: The volume <volser> is not in the Default Volume Pool.
Example: The volume EL0010 is not in the Default Volume Pool.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:finalizeVolume>
<arg0>F50233</arg0>
</ns1:finalizeVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:finalizeVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1219</return>
</ns2:finalizeVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume SL0010's Status is Offline</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume SL0010's Status is Offline</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
An asynchronous call that formats the volume into an LTFS-formatted volume. The LTFS-LE WebService does not require confirmation nor does it perform any validation of the volume. You must be aware of the volume that is being formatted and ensure that the correct volume is formatted.
When a volume is formatted, all previous data on the volume is deleted.
formatVolume(String volser)
Pre-condition:
Verify the volume is offline, assigned, and available before formatting the volume. Check that there is a compatible drive available.
To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Ensure that the volume is in the state required by the precondition.
Take corrective actions, if necessary, before proceeding.
LTFS-LE Web Service chain to call:
formatVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now LTFS-LE formatted.
volser is the serial number of the volume to be LTFS-LE formatted.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If the volser is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be formatted.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be formatted.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be finalized.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be formatted.
Example: The volume SL0010's Inuse Status is In Use.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:formatVolume>
<arg0>F50234</arg0>
</ns1:formatVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:formatVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1215</return>
</ns2:formatVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Available Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Aailable Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This asynchronous call formats the volume into an LTFS format and is used when a volume must be formatted in a specific drive. The volume and drive must be compatible.
formatVolumeWithDrive (String volser, String driveSN)
Pre-condition:
Verify that the volume is offline, assigned, and available before formatting the volume. The volume and drive must exist in library and the volume and drive must be compatible. The drive must be in an idle or available state.
To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1,volser2,...])
Ensure that the volume is in the state required by the precondition.
Take corrective actions, if necessary, before proceeding.
LTFS-LE Web Service chain to call:
formatVolumeWithDrive(volser,driveSN) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now LTFS-LE formatted.
volser is the volume serial number.
driveSN is the drive serial number of the drive formatting the volume.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions that can be thrown:
Volumes:
If the volser serial number is not entered, the exception thrown is: The parameter volsers is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be formatted.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be formatted.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be formatted.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be formatted.
Example: The volume SL0010's Inuse Status is In Use.
Drives:
If the drive serial number is not entered, the exception thrown is: The parameter driveSN is null.
If the drive does not exist in LTFS-LE, the exception thrown is: The drive <driveSN> is not in the LTFS-LE Database.
Example: The drive 123456 is not in the LTFS-LE Database.
If the drive status is not Available, Assigned, and Online the exceptions thrown are:
The drive <driveSN>'s Availability Status is <drive's real availableStatus>. The drive must be Available to be used.
Example: The drive 123456's Availability Status is Unavailable.
The drive <driveSN>'s LTFS-LE Assignment Status is <drive's real assignedStatus>. The drive must be Assigned to be used.
Example: The drive 123457's LTFS-LE Assignment Status is Unassigned.
The drive <driveSN>'s Status is <drive's real onlineStatus>. The drive must be Online to be used.
Example: The drive 123456's Status is Offline.
Volume Type and Drive Type Incompatibility:
If the volume type and drive type are not compatible, the exception thrown is: The volume <volser>'s type <vol_type> is not compatible with the drive <driveSN>'s type <drive_type>.
Example: The volume EL0010's type LTO-5 is not compatible with drive 123456's type T1C.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:formatVolumeWithDrive>
<arg0>F50234</arg0>
<arg1>576001000421</arg1>
</ns1:formatVolumeWithDrive>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:formatVolumeWithDriveResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1215</return>
</ns2:formatVolumeWithDriveResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Availablility Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Availablility Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This asynchronous call finds the volume path in the global namespace.
getVolumePath(volser)
Pre-Condition:
The volume status should be available and assigned. The unassigned volume has no volser folder.
volser is the volume serial number for the volume path to be found.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If the volser is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available and Assigned the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to get the volume path.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to get the volume path.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:getVolumePath>
<arg0>F50233</arg0>
</ns1:getVolumePath>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2: getVolumePath xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1225</return>
</ns2: getVolumePath >
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Availablility Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Availablility Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This is an asynchronous call that places the volume in an offline state and enables the ejecting, vaulting, formatting, assigning, and unassigning of one or more volumes.
offlineVolume(String[] volser)
Pre-conditions:
Verify that the volume exists in the library, is online, assigned, available, and in a pool before setting it offline. Check that there is a compatible drive available. The offline operation finalizes the volume automatically.
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Finalize the volume if the volume is in an online assigned state.
finalizeVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
LTFS-LE Web Service chain to call:
offlineVolume([volser1, volser2, ...]) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now offline.
volsers are the volume serial numbers of the volume or volumes to be taken offline. The input parameters are an array of strings; the call allows multiple volumes to be taken offline.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one or more of the volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Online, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be brought offline.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be brought offline.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Online to be brought offline.
Example: The volume EL0010's Status is Offline.
If the volume is not in the default volume pool, the exception thrown is: The volume <volser> is not in the Default Volume Pool.
Example: The volume EL0010 is not in the Default Volume Pool.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:offlineVolume>
<arg0>F50234</arg0>
<arg0>F50233</arg0>
</ns1:offlineVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:offlineVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1218</return>
</ns2:offlineVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Availability Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Availablility Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
An asynchronous call that places the volume in an online state which enables the reading, writing or finalizing of volume.s.
onlineVolume(String[] volsers)
Pre-conditions:
Verify that the volume exists in the library and is offline, assigned, in pool, idle, and available before setting it online. Check that there is a compatible drive available.
getVolumeInfoByVolser([volser1, volser2, ...])
LTFS-LE Web Service to call:
onlineVolume([volser1, volser2, ...]) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now online.
volsers are the volume serial numbers of the volume or volumes to be brought online. The input parameters are an array of strings; the call allows multiple volumes to be brought online.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one or more volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be brought online.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be brought online.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be brought online.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be brought online.
Example: The volume SL0010's Inuse Status is In Use.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:onlineVolume>
<arg0>F40244</arg0>
<arg0>F43022</arg0>
</ns1:onlineVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:onlineVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1217</return>
</ns2:onlineVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume SL0010's Aailablity Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume SL0010's Availability Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This asynchronous call moves the volume folder from the /LTFSLE/LOST+FOUND+VOLUMES/ to the /LTFSLE/ folder.
prepareVolume(volser)
Pre-conditions:
Verify that the volume folder is located in/LTFSLE/LOST+FOUND+VOLUMES and that the volume exists in the library and is offline, assigned, and available before preparing the volume. To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Obtain the location of the volume.
getVolumePath(volser)
Ensure that the volume is in all required states and take corrective action, if necessary, before proceeding.
LTFS-LE Web Service to call:
prepareVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume folder is now accessible from the /LTFSLE folder.
volser is the volume serial number to prepare to be accessible through the /LTFSLE/ location.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If the volser is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, and Offline the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to initiate the prepareVolume command.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to initiate the prepareVolume command.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to initiate the prepareVolume command.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to initiate the prepareVolume command.
Example: The volume SL0010's Inuse Status is In Use.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:prepareVolume>
<arg0>F50233</arg0>
</ns1:prepareVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:prepareVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1221</return>
</ns2:prepareVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Availability Status is Unavailable</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Availability Status is Unavailable</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This command unassigns a volume from LTFS-LE.
unassignVolume(String[] volsers)
Pre-conditions:
Verify that the volume exists in the library, is offline, assigned, in a pool, and available before unassigning the volume. To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Ensure that the volume is in all required states and take corrective action, if necessary, before proceeding.
LTFS-LE Web Service to call:
unassignVolume([volser1, volser2, ...]) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is unassigned from LTFS-LE.
volsers are the volume serial numbers of the volume or volumes to be unassigned. The input parameters are an array of strings and enable multiple volumes to be unassigned.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one of or more volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be unassigned.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to be unassigned.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be unassigned.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be unassigned.
Example: The volume SL0010's Inuse Status is In Use.
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:unassignVolume>
<arg0>F50233</arg0>
<arg0>F50234</arg0>
</ns1:unassignVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:unassignVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1221</return>
</ns2:unassignVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Inuse Status is In Use</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Inuse Status is In Use</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This asynchronous unformatVolume call removes the LTFS format from the volume. When an LTFS volume is unformatted, the LTFS format headers (metadata and data partitions) are removed from the volume and the volume becomes a standard, non-LTFS volume.
The LTFS-LE Web Service does not require confirmation nor does it perform any validation of the volume. However, when a volume is unformatted, all previous data on the volume is deleted. You must be aware of the volume that is being unformatted and ensure that the correct volume is unformatted.
Pre-condition:
Verify that the volume is offline, unassigned, available, and idle before unformatting the volume. Check that there is a compatible drive available.
To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1, volser2, ...])
Ensure that the volume is in the state required by the pre-condition.
Take corrective actions, if necessary, before proceeding.
LTFS-LE Web Service chain to call:
unformatVolume(volser)
getJobStatus(jobId) < poll each 10s until status is complete >
getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is LTFS-LE no longer formatted and the LTFS-LE format has been removed from the volume.
volser is the serial numbers of the volume to be unformatted.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If the volser is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Unassigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be unformatted.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Unassigned to be unformatted.
Example: The volume EL0010's LTFS-LE Assignment Status is Assigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be unformatted.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be unformatted.
Example: The volume SL0010's Inuse Status is In Use.
If the volume is in the default volume pool, the exception thrown is: The volume <volser> is in the Default Volume Pool. The volume must be removed from the Default Volume Pool before it can be unformatted.
Example: The volume EL0010 is in the Default Volume Pool.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:unformatVolume>
<arg0>F50344</arg0>
</ns1:unformatVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:unformatVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1216</return>
</ns2:unformatVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's inuseStatus is In Use</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's inuseStatus is In Use</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This asynchronous call removes the LTFS format from the volume. When an LTFS volume is unformatted, the LTFS format headers (metadata and data partitions) are removed from the volume and the volume becomes a standard, non-LTFS volume.
unformatVolumeWithDrive (String volser, String drivesn)
Pre-condition:
The volume and drive must exist in library. The volume and drive must be compatible. The volume must be unassigned, offline, not in a pool, and available. The drive must be in an idle, online, or available state.
To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1,volser2,...])
Ensure that the volume is in the state required by the precondition.
Take corrective actions, if necessary, before proceeding.
LTFS-LE Web Service chain to call:
unformatVolumeWithDrive(volser,drivesn) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is now LTFS-LE formatted.
volser is the volume serial number to be unformatted.
drivesn is the drive serial number that is a string of characters and numbers,
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions that can be thrown:
Volumes:
If the volser serial number is not entered, the exception thrown is: The parameter volser is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Unassigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to be unformatted.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Unassigned to be unformatted.
Example: The volume EL0010's LTFS-LE Assignment Status is Assigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to be unformatted.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to be unformatted.
Example: The volume SL0010's Inuse Status is In Use.
If the volume is in the default volume pool, the exception thrown is: The volume <volser> is in the Default Volume Pool. The volume must be removed from the Default Volume Pool before it can be unformatted.
Example: The volume EL0010 is in the Default Volume Pool.
Drives:
If the drive serial number is not entered, the exception thrown is: The parameter driveSN is null.
If the drive does not exist in LTFS-LE, the exception thrown is: The drive <driveSN> is not in the LTFS-LE Database.
Example: The drive 123456 is not in the LTFS-LE Database.
If the drive status is not Available, Assigned, and Online the exceptions thrown are:
The drive <driveSN>'s Availability Status is <drive's real availableStatus>. The drive must be Available to be used.
Example: The drive 123456's Availability Status is Unavailable.
The drive <driveSN>'s LTFS-LE Assignment Status is <drive's real assignedStatus>. The drive must be Assigned to be used.
Example: The drive 123457's LTFS-LE Assignment Status is Unassigned.
The drive <driveSN>'s Status is <drive's real onlineStatus>. The drive must be Online to be used.
Example: The drive 123456's Status is Offline.
Volume Type and Drive Type Incompatibility:
If the volume type and drive type are not compatible, the exception thrown is: The volume <volser>'s type <vol_type> is not compatible with the drive <driveSN>'s type <drive_type>.
Example: The volume EL0010's type LTO-5 is not compatible with drive 123456's type T1C.
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:unformatVolumeWithDrive>
<arg0>F50344</arg0>
<arg1>576001000421</arg1>
</ns1:unformatVolumeWithDrive>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:unformatVolumeWithDriveResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1216</return>
</ns2:unformatVolumeWithDriveResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's type LTO-5 is not compatible with drive 123456's type T1C</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's type LTO-5 is not compatible with drive 123456's type T1C</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>
This API function vaults one or more LTFS-LE volumes that are present in the LTFS-LE default volume pool. You can only vault one volume at a time.
This asynchronous call vaults up to 30 volumes using the CAP (mailslot). There is room for four volumes on the mailslot. If the user vaults 30 volumes, then volumes are sent to the mailslot four at a time until all ejects are complete.
vaultVolume(String[] volsers,String acs,String lsm,String cap)
Pre-condition:
Verify that a CAP is available and that the volume is available, assigned, offline, idle, and in a pool before vaulting. The total number of volumes should be less than or equal to 30. Volumes must be in the same library configured. To do this:
Obtain the volume status:
getVolumeInfoByVolser([volser1,volser2,...])
If the volume is in an online assigned state, finalize the volume:
finalizeVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
If the volume is online, take the volume offline before executing the vaultVolume API call:
offlineVolume(volser) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
LTFS-LE WebService chain to call:
vaultVolume([volser1,volser2,...],acs,lsm,cap) getJobStatus(jobId) < poll each 10s until status is complete > getJobResult(jobId)
Post-condition:
Once the series of Web Services calls have been executed, the results are an XML document. You must convert them into appropriate return codes. If the API calls succeed, the volume is entered into the library. The user must walk up to the library and retrieve the volume after opening the CAP door.
volsers are the serial number of the volume or volumes to be vaulted.
acs is the library ACS identifier.
lsm is the library LSM identifier.
cap is the library CAP (mailslot) ID used to eject the volume.
jobId is the job ID used to retrieve the job status and result.
Valid responses are shown in the SOAP Response example. Refer to the Glossary for definitions.
ValidationFailedException
Exceptions can be thrown:
If one or more volser serial numbers are not entered, the exception thrown is: The parameter volsers is null.
The volser is the first volume that does not meet any constraint (not all the volumes specified by volsers).
If the number of volumes specified is greater than 30, the exception thrown is: The number of volumes to vault must be 30 or less.
If the acs parameter is null, the exception thrown is: The parameter acs is null.
If the lsm parameter is null, the exception thrown is: The parameter lsm is null.
If the cap parameter is null, the exception thrown is: The parameter cap is null.
If the volume does not exist in LTFS-LE, the exception thrown is: The volume <volser> is not in the LTFS-LE Database.
Example: The volume EL0010 is not in the LTFS-LE Database.
If the volume status is not Available, Assigned, Offline, and Idle, the exceptions thrown are:
The volume <volser>'s Availability Status is <volser's real availableStatus>. The volume's Availability Status must be Available to vault the volume.
Example: The volume EL0010's Availability Status is Unavailable.
The volume <volser>'s LTFS-LE Assignment Status is <volser's real assignedStatus>. The volume's LTFS-LE Assignment Status must be Assigned to vault the volume.
Example: The volume EL0010's LTFS-LE Assignment Status is Unassigned.
The volume <volser>'s Status is <volser's real onlineStatus>. The volume's Status must be Offline to vault the volume.
Example: The volume EL0010's Status is Online.
The volume <volser>'s Inuse Status is <volser's real inuseStatus>. The volume's Inuse Status must be Idle to vault the volume.
Example: The volume SL0010's Inuse Status is In Use.
This depends on the time taken for the admin to remove the volume from the CAP (mailslot).
<?xml version = '1.0' encoding = 'UTF-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1
="http://sb.ejb.ws.mds.ltfsle.oracle/">
<env:Header>
<ns1:Security>
<ns1:UsernameToken>
<ns1:Username>username</ns1:Username>
<ns1:Password>password</ns1:Password>
</ns1:UsernameToken>
</ns1:Security>
</env:Header>
<env:Body>
<ns1:vaultVolume>
<arg0>F50234</arg0>
<arg0>F50233</arg0>
<arg1>3</arg1>
<arg2>0</arg2>
<arg3>1</arg3>
</ns1:vaultVolume>
</env:Body>
</env:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
-secext-1.0.xsd" S:mustUnderstand="true">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd">
<wsu:Created>2014-06-17T14:36:36Z</wsu:Created>
<wsu:Expires>2014-06-17T14:37:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:vaultVolumeResponse xmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<return>1214</return>
</ns2:vaultVolumeResponse>
</S:Body>
</S:Envelope>
<?xml version = '1.0' encoding = 'UTF-8'?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns3:Fault xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3
="http://www.w3.org/2003/05/soap-envelope">
<ns3:Code>
<ns3:Value>ns3:Receiver</ns3:Value>
</ns3:Code>
<ns3:Reason>
<ns3:Text>The volume EL0010's Inuse Status is In Use</ns3:Text>
</ns3:Reason>
<ns3:Detail>
<ns2:ValidationFailedExceptionxmlns:ns2="http://sb.ejb.ws.mds.ltfsle.oracle/">
<message>The volume EL0010's Inuse Status is In Use</message>
</ns2:ValidationFailedException>
</ns3:Detail>
</ns3:Fault>
</S:Body>
</S:Envelope>