{
{   The purpose of this request is to schedule a mainframe or peripheral
{ element for the exclusive use of the requesting job.  The only mainframe
{ elements which may be reserved are PPs and channels.
{
{   All peripheral elements and channels which must be reserved concurrently
{ must be reserved in one request.  A peripheral element is one of the
{ following types of elements:  channel adapter, communications element,
{ controller, external processor, or storage device.  All PPs which must be
{ reserved concurrently must be reserved in one request, but not necessarily
{ the same request as the one which reserved the peripheral elements and
{ channels.
{
{   This request grants special privileges to a system caller.  A system caller
{ is one whose request is made from a system segment.  A system caller is
{ exempt from the following four policies and does not affect the ability of a
{ non-system-caller to perform subsequent reservations in the same job.
{
{    1.  Once a peripheral or channel reservation is granted to a job a
{        subsequent attempt to acquire additional peripheral element or channel
{        reservations will not be allowed; existing reservations of such
{        elements must first be released.  Only elements which have not been
{        reserved by a system caller are considered in this policy.
{
{    2.  If a job has peripheral elements and or channels reserved to it, a
{        subsequent attempt to reserve PPs will be allowed if they are
{        available and if none are already reserved to that job.  Only elements
{        which have not been reserved by a system caller are considered in this
{        policy.
{
{    3.  If a job has a PP reserved to it, further reservations of PPs,
{        channels or peripheral elements to that job will not be allowed;
{        existing PP reservations must first be released.
{
{    4.  The reservations of all elements within a job are automatically
{        released when the task which made the reservation terminates.
{
{   It is recommended that programs requiring multiple schedulable resources
{ obtain those resources in the following order and release them in the inverse
{ order, i.e.  last reserved is first released:
{
{        1.  Tape storage device reservation (RESERVE_RESOURCES).
{
{        2.  File attachments (fsp$open_file, ATTACH_FILE, fsp$attach_file).
{
{        3.  Peripheral and channel element reservations (cmp$reserve_element).
{
{        4.  Maintenance access (msp$request_maintenance_access).
{
{        5.  PP reservations (cmp$reserve_element).
{
{   It is further recommended that a program which gets blocked in its attempt
{ to obtain a particular type of resource, return the resources previously
{ acquired in the inverse order in which they were acquired.  For example, if
{ an attempt to acquire peripheral hardware reservations is blocked, the
{ program should back out of its file attachments and then its tape storage
{ device reservations to avoid a deadlock with other jobs which may be in
{ competition with it for some or all of the same resources.
{
{   Element reservations are not maintained across a system interrupt.  It is
{ the responsibility of the program making the reservation to repeat the
{ reservation process, if desired, after the system recovery completes.  A job
{ may establish a job-recovery condition-handler for this purpose.
{
{
{   PP RESERVATIONS:
{
{   If a PP is requested, the PP must not be currently reserved to a job nor to
{ the NOS/VE system itself.  In a dual-state system, the satisfaction of a
{ request for a PP in IOU0 is contingent upon a successful request of the PP
{ from the NOS or NOS/BE system.  If the PP is acquired, the reservation is
{ allowed and the PP will be returned to the NOS or NOS/BE system when the
{ NOS/VE element reservation is released.
{
{   There are four ways to identify the PP which is desired:
{
{         1.  cmc$choose_any_pp - This selection will return any available
{             PP regardless of IOU.  This selection might commonly be used to
{             acquire a PP to perform a background task or to perform a Central
{             Memory test, etc.  In a system with NIO and CIO PP's, an NIO PP
{             will be selected if available, otherwise, a CIO PP will be
{             selected.  In a system with only CIO PP's, this request will
{             select an available CIO PP.  In a dual IOU system, the search
{             order is IOU1 NIO, IOU0 NIO, IOU1 CIO, IOU0 CIO.
{
{         2.  cmc$choose_pp_by_barrel - This selection will return an NIO PP
{             which is in the "driver barrel" on a CYBER 810/830 system.  On
{             any other system this selection is identical to
{             cmc$choose_any_pp.
{
{         3.  cmc$choose_pp_by_channel - This selection will return any
{             available PP which has access to the channel identified in the
{             request.  In a multiple IOU system, the IOU field of this record
{             must be initialized to uniquely identify the channel.
{
{         4.  cmc$choose_specific_pp - This selection will return only the PP
{             identified by the request.  This option is not implemented on a
{             dual-state system.  In a multiple IOU system, the IOU field of
{             this record must be initialized to uniquely identify the PP.
{
{
{   DATA CHANNEL RESERVATIONS:
{
{   If a data channel is requested, it must be an external data channel which
{ is not currently reserved to a job nor to the NOS/VE system itself.  In a
{ dual-state system, the satisfaction of a request for a channel in IOU0 is
{ contingent upon a successful request of the channel from the NOS or NOS/BE
{ system.  If the channel is acquired, the reservation is allowed and the
{ channel will be returned to the NOS or NOS/BE system when the NOS/VE element
{ reservation is released.  In a multiple-IOU system, the IOU field of the
{ record must be initialized to uniquely identify the channel being reserved.
{
{   If a channel has multiple ports, then all ports of the channel are reserved
{ as a result of requesting any one of the ports.  For example, an I4 CIO
{ channel may be referred to by the name CCH1A, CCH1B, or CCH1; with respect to
{ this request all forms of reference have the same result.
{
{   NOS/VE's policy for channel reservation depends upon whether or not a
{ peripheral which is defined in the active, physical configuration is
{ connected to the channel requested; if this is the case the channel is said
{ to be in the active configuration.
{
{   If the requested channel is not in the active configuration, this request
{ is granted subject to the previously mentioned conditions.
{
{   If the requested channel is in the active configuration, then in addition
{ to other conditions mentioned above, the channel must also be in the ON
{ state, have no elements in the ON or DOWN state connected to it and not be
{ the object of maintenance access.
{
{
{   PERIPHERAL RESERVATIONS:
{
{   For the purposes of the following discussion a peripheral element is
{ reservable by a job if one of the following is true:
{
{         1.  The element is classified as reservable only by a system process
{             and the call was made from a system segment.
{
{         2.  The element is one which is not recognized as a standard
{             peripheral to the NOS/VE operating system, per se.  Elements in
{             this class are defined to NOS/VE by specifying
{             VERIFY_ELEMENT_IDENTIFICATION=FALSE on the DEFINE_ELEMENT
{             subcommand which configures the element to NOS/VE.  Refer to the
{             documentation of the Physical Configuration Utility for the
{             explanation about how elements defined in this manner are
{             categorized as "controllers" and "storage devices" by NOS/VE.
{
{   If a peripheral element is requested it must be a reservable element and
{ must not be currently reserved to a job nor to the NOS/VE system itself.
{
{   Furthermore, if a peripheral element is requested by name or by hardware
{ address, this request will ensure that the value of the element_type field
{ matches the type of the element identified by the peripheral_descriptor
{ field.  Remember that all reservable elements available to a non-system
{ caller are either classified as a controller or a storage device; refer to
{ the description of the DEFINE_ELEMENT subcommand of the Physical
{ Configuration Utility for more information.
{
{   If a peripheral element is requested by name, the name must be defined in
{ the active configuration or the request is denied.
{
{   NOS/VE's reservation policy further depends upon whether or not the
{ peripheral is defined in the active, physical configuration.
{
{   If the requested peripheral is not in the active configuration, this
{ request is granted subject to the previously mentioned conditions.
{
{   If the requested peripheral is in the active configuration, then in
{ addition to other conditions mentioned above, the peripheral must be in the
{ ON state, be a reservable element and not be the object of maintenance
{ access.  If the peripheral is connected to another channel of this mainframe
{ or is connected to another mainframe, it is the caller's responsibility to
{ coordinate this reservation with other jobs and with other mainframes.
{
{   If your task is going to access the peripheral, you must either reserve a
{ channel to the element in this same request or, if your task is a maintenance
{ task, you may use msp$request_maintenance_access to schedule access to the
{ channel.
{
{       CMP$RESERVE_ELEMENT (ELEMENT, STATUS)
{
{ ELEMENT: (input, output)  This parameter specifies the identity of the system
{       element to be reserved to the job.  The identity may be specified using
{       either the name of the element or its hardware address.
{
{       If a peripheral hardware address is specified you must initialize the
{       physical_address_specifier to indicate how many parts of the address
{       are initialized in the address path.  For example, if you are querying
{       a unit, the physical_address_specifier must include a channel, a
{       channel_address and the unit_address and you must initialize all three
{       fields of the hardware address.
{
{       If use_logical_identification is FALSE in any of the fields of the
{       element descriptor and the mainframe has more than one IOU, the name of
{       the IOU must be initialized because the channel and PP identification
{       is ambiguous in this case.  The IOU component of the peripheral
{       descriptor will be ignored on single IOU mainframes.
{
{ STATUS: (output) This parameter specifies the request status.
{
{         CONDITIONS:
{                     cme$cm_element_not_found,
{                     cme$element_already_reserved,
{                     cme$element_downline_connected,
{                     cme$element_not_reservable,
{                     cme$element_state_not_proper,
{                     cme$element_unavailable_in_170,
{                     cme$invalid_state_in_mainframe,
{                     cme$lcm_element_not_found,
{                     cme$lcm_empty_pa_set,
{                     cme$lcm_missing_pa_set_member,
{                     cme$lcm_ring_validation_error,
{                     cme$privileged_job_required,
{                     cme$reserve_not_permitted,
{                     cme$specific_pp_not_reservable.
{
{         IDENTIFIER:  'CM'
{
