|
|
|
Allocates a magneto-optical media drive.
Syntax
REC I32 I32A @64A
AIFMOALLOCATE ( overall_status, ldev, 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:
- media name = MYMEDIA
- subname1 = @
- subname2 = @
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:
Label 1:
- media name = MYMEDIA
- subname1 = SUB1
- subname2 = SUB2
Label 2:
- media name = MYMEDIA
- subname1 =
- subname2 = SUB2
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 |
|
