[This is preliminary documentation and subject to change.]
To obtain media to use, an application uses the AllocateNtmsMedia function, specifying a media pool from which to obtain the medium. The AllocateNtmsMedia function assigns media to the application and returns a logical media identifier (LMID) to the application. Only media in online libraries can be allocated to the application. To allocate both sides of the specified medium, the application can use the New and Next options to allocate. New returns media that has both sides available and reserves the reverse side. Using the Next option and specifying the LMID of a side already allocated, the application can obtain an LMID for the reverseside of the medium
The media pool can be set up to automatically draw from the Scratch pool upon allocation. If no media are available in its media pool, RSM automatically moves online media from the Scratch pool and assigns it to the application. If no media are available, RSM generates an operator request for new media.
Because the application is not guaranteed the type of label on a medium, the application is required to write its own label on the medium and use the UpdateNtmsOmidInfo function to notify RSM of the new label identifier. This does not have to be done immediately after the allocate command, because RSM can use the current label identifier until the current owner overwrites the label. After the application overwrites the label, it must notify RSM of the change as soon as possible to prevent a mismatch between the RSM version of the label and the actual label. If the application does not notify RSM of the label change, the media is moved to the Import pool, and the application must import the media to be able to access it again.