 |
» |
|
|
|
Allocates a magneto-optical media drive. Syntax | |
REC I32
AIFMOALLOCATE(overall_status, ldev,
I32A @64A
itemnum_array, item_array,
RECA I32
itemstatus_array, user_id)
|
Parameters | |
- overall_status
record by reference (required) Returns the overall status of the call. A zero indicates a successful call. A negative value indicates an error in the overall call, not specific to any particular item. A positive value indicates the last element in itemstatus_array, signaling an error condition. Refer to appendix A for meanings of status values. Record type: status_type (Refer to appendix B.) - ldev
32-bit signed integer by reference (required) This parameter returns the logical device number (ldev) of the
optical drive allocated.
- itemnum_array
32-bit signed integer array by reference (optional) This is an array of integers, terminated by an element containing the
value zero, used to define the corresponding option
given in the item_array parameter. If this optional parameter is
specified, the item_array parameter and the itemstatus_array parameter
must both be supplied. Default: nil
- item_array
64-bit address array by reference (optional) An array with the same number of elements as the itemnum_array
parameter, each of which is a globalanyptr that points to the
appropriate type needed by each particular item number. The
value used for each option is taken from, or returned to, the
location pointed to by the globalanyptr in this array. When
this parameter is supplied, the itemnum_array parameter and the
itemstatus_array parameter must both be supplied. Array type: globalanyptr (Refer to Appendix B.) Default: nil
- itemstatus_array
record array by reference (optional) If problems are detected with the specific items, an error status
is placed in the corresponding element of this array for each item
with an error. The overall_status parameter indicates whether any
individual items contained errors, and the element of the last
detected error. This array must contain as many elements as are
contained in the itemnum_array and the item_array parameters. A zero indicates a successful operation. A negative value indicates
an error condition. A positive value indicates a warning. Array type: status_type (Refer to Appendix B.) Default: nil - user_id
32-bit signed integer by value (optional) The user ID assigned to a vendor at the time of purchase of the Architected Interface Facility: Operating System product.
If it is not passed, the caller must have previously called
AIFACCESSON. Default: 0
Operation Notes | |
AIFMOALLOCATE provides a way to allocate a
magneto-optical
media drive for dedicated use.
Attempting to mount media (using AIFMOMOUNT)
will fail with an error if the specified drive is
not currently
allocated. When this AIF is used, the optical
drive is allocated using the
pin of the calling process.
A drive that is allocated
must be deallocated using the same pin. If you are the
process that performed the allocate, you can call AIFMODEALLOCATE
without explicitly specifying the pin.
In addition,
if you are the process that performed the allocate,
you can call AIFMOMOUNT/DISMOUNT and
AIFMOGET/PUT without
explicitly specifying the pin.
If you are not the process that performed the allocate,
attempting to deallocate, mount, dismount, etc.,
without passing the pin for the process that performed the allocate
will fail with an error.
The pin can be returned to the user through the pin item number
in the call to AIFMOALLOCATE.
Allocating an optical drive does not prevent other processes from
accessing media mounted on the allocated drive, but it does prevent
other processes from dismounting the current media and mounting
another piece of media, unless they know the pin
used to allocate the drive.
If the process performing the allocate terminates
before the deallocate of the drive is performed
the deallocate will occur during normal process
termination clean up. That is, process termination will
handle cleaning up after any outstanding 'allocates'
performed through the AIFs for the terminating
process. If the
input ldev item or media label item is not specified,
the first unallocated
optical drive will be allocated.
Note, for this case, if all drives are currently allocated
by other processes, an error will be
returned. Also, note, if all the magneto-optical drives
on the system are allocated by the
calling process, and AIFMOALLOCATE is called without specifying
an ldev item or media label item,
an error will not be returned but the ldev parameter will not
return any particular ldev value. If a particular item is specified more than once in a call to
this AIF, the first occurrence of it will be used. For example, if
item 17101 (Pin) is passed in twice, the value for the pin of the calling
process will be returned in the corresponding item array for the
first index for which this item was passed and a warning will
be returned in the item status array for the second index for which
this item was passed (a value will not be returned in the item array
for the second index). Likewise, if item 17102 (ldev) is passed in
twice, the first ldev value that is passed is used to perform the
allocate, and the 2nd ldev value is ignored (a warning is
returned in the item status array). Note, passing in the ldev
(or media label) item in more than once does NOT attempt to
allocate more than drive. When this AIF is used, no actual Autochanger or I/O operations are performed. Refer to the Programming Example in Appendix C, or the AIFMOMOUNT
Operation Notes for more information. AIFMOALLOCATE Item Descriptions | |
The following table provides detailed descriptions of
item numbers and corresponding items associated with
AIFMOALLOCATE. Table 3-17 AIFMOALLOCATE Item Descriptions | Item Number | Item Name (Data Type) Release First Available Description
|
|---|
| 17101 | Pin (I32); Release 5.0 Returns the pin of the calling process. The pin can be used with other
magneto-optical AIF's for verification of ownership for an
optical media drive. Default: Pin of the calling process | | 17102 | Input ldev (I32); Release 5.0 Passes the logical device number (ldev) of the optical
drive to allocate. This item is not valid if the media label item
is specified. Default: nil | | 17103 | Media label (REC) Release 5.0 Passes a media label record. This record consists of a
media name, subname1, and subname2. The media name consists of an
array of 1 to 32 characters and identifies the first part of the
media label. Subname1 and subname2 consist of arrays of 1 to 16
characters and identify the second and third parts of
the media label. Each of the fields of this record must be left
justified. When this item is passed,
the first
available drive which can access the specified media is allocated.
Note, the specified media is not
allocated, only a drive which can access the requested media is
allocated.
By specifying a media label, you are not required to know the optical
drive's ldev numbers. The media name,
subname1, and subname2 must contain either a name
or the character "@".
"@" indicates that this field
should be ignored. For example, if the following was passed: this would lock a drive which can access any piece of media
whose media name was "MYMEDIA". The following
media labels would be considered matching the above passed
media label: This item is not valid if the input ldev item is specified. Also, it is
invalid to specify a media name, subname1, or subname2 that is longer than
1 character and whose first character is the character "@". Record type: media_label_type (Refer to Appendix A) Default: nil |
|
