home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Assembler / TFF-AOC.DMS / in.adf / Release3.1 / AutoDocs3.1.lha / doc / cd.doc < prev    next >
Encoding:
Text File  |  1993-08-12  |  43.7 KB  |  1,218 lines
  1. TABLE OF CONTENTS
  2.  
  3. cd.device/CD_ADDCHANGEINT
  4. cd.device/CD_ADDFRAMEINT
  5. cd.device/CD_ATTENUATE
  6. cd.device/CD_CHANGENUM
  7. cd.device/CD_CHANGESTATE
  8. cd.device/CD_CONFIG
  9. cd.device/CD_EJECT
  10. cd.device/CD_GETGEOMETRY
  11. cd.device/CD_INFO
  12. cd.device/CD_MOTOR
  13. cd.device/CD_PAUSE
  14. cd.device/CD_PLAYLSN
  15. cd.device/CD_PLAYMSF
  16. cd.device/CD_PLAYTRACK
  17. cd.device/CD_PROTSTATUS
  18. cd.device/CD_QCODELSN
  19. cd.device/CD_QCODEMSF
  20. cd.device/CD_READ
  21. cd.device/CD_READXL
  22. cd.device/CD_REMCHANGEINT
  23. cd.device/CD_REMFRAMEINT
  24. cd.device/CD_SEARCH
  25. cd.device/CD_SEEK
  26. cd.device/CD_TOCLSN
  27. cd.device/CD_TOCMSF
  28. cd.device/CloseDevice
  29. cd.device/OpenDevice
  30. cd.device/CD_ADDCHANGEINT                           cd.device/CD_ADDCHANGEINT
  31.  
  32.    NAME
  33.        CD_ADDCHANGEINT -- add a disk change software interrupt handler.
  34.  
  35.    FUNCTION
  36.        This command lets you add a software interrupt handler to the
  37.        disk device that gets invoked whenever a disk insertion or removal
  38.        occurs.
  39.  
  40.        You must pass in a properly initialized Exec Interrupt structure
  41.        and be prepared to deal with disk insertions/removals immediately.
  42.        The interrupt is generated by the exec Cause function, so you must
  43.        preserve A6.
  44.  
  45.        To set up the handler, an Interrupt structure must be initialized.
  46.        This structure is supplied as the io_Data to the CD_ADDCHANGEINT
  47.        command.  The handler then gets linked into the handler chain and
  48.        gets invoked whenever a disk change happens.  You must eventually
  49.        remove the handler before you exit.
  50.  
  51.        This command only returns when the handler is removed. That is,
  52.        the device holds onto the IO request until the CD_REMCHANGEINT command
  53.        is executed with that same IO request.  Hence, you must use SendIO()
  54.        with this command.
  55.  
  56.    IO REQUEST INPUT
  57.        io_Device       preset by the call to OpenDevice()
  58.        io_Unit         preset by the call to OpenDevice()
  59.        io_Command      CD_ADDCHANGEINT
  60.        io_Length       sizeof(struct Interrupt)
  61.        io_Data         pointer to Interrupt structure
  62.  
  63.    IO REQUEST RESULT
  64.        io_Error - 0 for success, or an error code as defined in
  65.                   <devices/cd.h>
  66.  
  67.    SEE ALSO
  68.        CD_REMCHANGEINT, <devices/cd.h>, <exec/interrupts.h>,
  69.        exec.library/Cause()
  70.  
  71. cd.device/CD_ADDFRAMEINT                             cd.device/CD_ADDFRAMEINT
  72.  
  73.    NAME
  74.        CD_ADDFRAMEINT -- add a CD-frame software interrupt handler.
  75.  
  76.    IO REQUEST
  77.        io_Device       preset by the call to OpenDevice()
  78.        io_Unit         preset by the call to OpenDevice()
  79.        io_Command      CD_ADDFRAMEINT
  80.        io_Length       sizeof(struct Interrupt)
  81.        io_Data         pointer to Interrupt structure
  82.  
  83.    RESULTS
  84.        io_Error        0 for success, or an error code as defined in
  85.                        <devices/cd.h>
  86.  
  87.    FUNCTION
  88.        This command lets you add a software interrupt handler to the
  89.        disk device that gets invoked whenever a new frame is encountered
  90.        while CD audio is being played.
  91.  
  92.        You must pass in a properly initialized Exec Interrupt structure
  93.        and be prepared to deal with frame interrupts immediately.
  94.        The interrupt is generated by the exec Cause function, so you must
  95.        preserve A6.
  96.  
  97.        To set up the handler, an Interrupt structure must be initialized.
  98.        This structure is supplied in io_Data of the CD_ADDFRAMEINT
  99.        command.  The handler then gets linked into the handler chain and
  100.        gets invoked whenever a frame event occurs.  You must eventually
  101.        remove the handler before you exit.
  102.  
  103.        This command only returns when the handler is removed. That is,
  104.        the device holds onto the IO request until the CD_REMFRAMEINT command
  105.        is executed with that same IO request.  Hence, you must use SendIO()
  106.        with this command.
  107.  
  108.    NOTES
  109.        The interrupt handler can be added before or after a play command is
  110.        sent.  Interrupts will only be generated while CD audio is playing.
  111.        Interrupts will not be generated when audio is paused.
  112.  
  113.    SEE ALSO
  114.        CD_REMFRAMEINT, <devices/cd.h>, <exec/interrupts.h>,
  115.        exec.library/Cause()
  116.  
  117. cd.device/CD_ATTENUATE                                 cd.device/CD_ATTENUATE
  118.  
  119.    NAME
  120.        CD_ATTENUATE -- Attenuate CD audio volume (immediately or gradually)
  121.  
  122.    IO REQUEST
  123.        io_Device       preset by the call to OpenDevice()
  124.        io_Unit         preset by the call to OpenDevice()
  125.        io_Command      CD_ATTENUATE
  126.        io_Data         NULL
  127.        io_Length       duration of volume fade in frames
  128.        io_Offset       target volume level (0 - 0x7FFF) (-1 = status only)
  129.  
  130.    RESULTS
  131.        io_Error        Returns an error if drive does not support attenuation
  132.        io_Actual       current volume level (fade may be monitored)
  133.  
  134.    FUNCTION
  135.        This command will ramp the CD audio volume up or down from its
  136.        current value to the value contained in io_Offset.  The range is 0
  137.        (silence) to 0x7FFF (full volume).  If -1 is specified as the target,
  138.        the attenuation will not be modified; the current attenuation value
  139.        will be returned in io_Actual.
  140.  
  141.        io_Length contains the duration of the fade.  In seconds, this is
  142.        io_Length divided by the current frame rate (usually 75).
  143.  
  144.        Note that this command returns before the fade has completed.  Thus,
  145.        once started, a fade cannot be aborted.  You can, however, send a
  146.        new CD_ATTENUATE command, which will immediately override any fade
  147.        currently in progress.  An io_Length of zero means attenuate
  148.        immediately.
  149.  
  150.        If a gradual attenuation command is sent before the play command, the
  151.        fade will begin as soon as the play command is sent.
  152.  
  153.    EXAMPLE
  154.  
  155.    NOTES
  156.        This command has no effect on Amiga audio volume, only CD audio.
  157.  
  158.        If the drive does not support volume attenuation, but does support
  159.        mute, a value of under $0800 should be considered mute, and equal
  160.        to or above should be full volume.  If chunky attenuation is
  161.        supported, the drive should do the best it can.  If the drive does
  162.        not support volume attenuation at all, an error should be returned.
  163.        Even if only mute is supported, if gradual attenuation is requested,
  164.        the device should still emulate the fade command and mute based on
  165.        the $0800 boundary.
  166.  
  167.    BUGS
  168.  
  169.    SEE ALSO
  170.        CD_INFO
  171.  
  172. cd.device/CD_CHANGENUM                                 cd.device/CD_CHANGENUM
  173.  
  174.    NAME
  175.        CD_CHANGENUM -- return the current value of the disk-change counter.
  176.  
  177.    FUNCTION
  178.        This command returns the current value of the disk-change counter
  179.        The disk change counter is incremented each time a disk is inserted
  180.        or removed from the cd unit.
  181.  
  182.    IO REQUEST INPUT
  183.        io_Device       preset by the call to OpenDevice()
  184.        io_Unit         preset by the call to OpenDevice()
  185.        io_Command      CD_CHANGENUM
  186.  
  187.    IO REQUEST RESULT
  188.        io_Error - 0 for success, or an error code as defined in
  189.                   <devices/cd.h>
  190.        io_Actual - if io_Error is 0, this contains the current value of the
  191.                    disk-change counter.
  192.  
  193. cd.device/CD_CHANGESTATE                             cd.device/CD_CHANGESTATE
  194.  
  195.    NAME
  196.        CD_CHANGESTATE -- check if a "valid" disk is currently in a drive.
  197.  
  198.    FUNCTION
  199.        This command checks to see if there is a "valid" disk in a drive.
  200.  
  201.    IO REQUEST INPUT
  202.        io_Device       preset by the call to OpenDevice()
  203.        io_Unit         preset by the call to OpenDevice()
  204.        io_Command      CD_CHANGESTATE
  205.  
  206.    IO REQUEST RESULT
  207.        io_Error - 0 for success, or an error code as defined in
  208.                   <devices/cd.h>
  209.        io_Actual - 0 means there is a disk while anything else indicates
  210.                    there is no disk.
  211.  
  212.    NOTES
  213.        A "valid" disk is a disk with a readable table of contents.
  214.  
  215. cd.device/CD_CONFIG                                       cd.device/CD_CONFIG
  216.  
  217.    NAME
  218.        CD_CONFIG -- Set drive preferences
  219.  
  220.    IO REQUEST
  221.        io_Device       preset by the call to OpenDevice()
  222.        io_Unit         preset by the call to OpenDevice()
  223.        io_Command      CD_CONFIG
  224.        io_Data         pointer to first entry of TagList
  225.        io_Length       0
  226.  
  227.    RESULTS
  228.        io_Error        0 for success, or an error code as defined in
  229.                        <devices/cd.h>
  230.  
  231.    FUNCTION
  232.        This command sets one or more of the configuration items.
  233.        The configuration items are:
  234.  
  235.        TAGCD_PLAYSPEED                 Default: 75
  236.        TAGCD_READSPEED                 Default: 75 (do not count on this)
  237.        TAGCD_READXLSPEED               Default: 75
  238.        TAGCD_SECTORSIZE                Default: 2048
  239.        TAGCD_XLECC                     Default: 1 (on)
  240.        TAGCD_EJECTRESET                Default: can be 0 (off) or 1 (on)
  241.  
  242.        The speed settings are described in the number of frames (sectors)
  243.        per second.  All CD-ROM drives are capable of the 75 frames/second
  244.        rate.  Some drives are capable of 150 frames/second, and some even
  245.        more.  To determine the maximum frame rate of the drive, use the
  246.        CD_INFO command.  Valid values for caddyless Commodore CD-ROM drives
  247.        are 75 and 150 (normal speed and double speed).  All other values are
  248.        invalid.  You should always make sure the drive is capable of the
  249.        configuration you are requesting by either using the CD_INFO command,
  250.        and/or by checking for an error condition after submitting your
  251.        request.
  252.  
  253.        There are three different types of CD-ROM sectors.  Mode 1 sectors
  254.        (2048 bytes), mode 2 form 1 sectors (2048 bytes), and mode 2 form 2
  255.        sectors (2328 bytes).  Normally, disks are encoded in Mode 1 format.
  256.        Mode 2 form 1 is basically the same as mode 1; however, the mode 2
  257.        form 2 sector format contains no CD-ROM error correction information.
  258.        In order to read information encoded in this sector format, the
  259.        drive's sector size must be configured to 2328 byte sectors.
  260.  
  261.        Error correction (ECC) of the READXL command can be turned off or
  262.        on with this command.  Error correction can be implemented in either
  263.        hardware or software (depending on the CD-ROM drive).  When ECC is
  264.        implemented in software, CPU usage can become bursty.  Errors rarely
  265.        occur on CDs unless they have numerous scratches, but when they do
  266.        occur, they will cause a loss of CPU bandwith.  When ECC is
  267.        implemented in hardware, no CPU bandwidth is lost -- in this case,
  268.        ECC will always be on no matter how you configure the drive because 
  269.        it is free.  The READXL command is used primarily for displaying
  270.        movie-like data.  In this case, speed is essential and data integrety
  271.        is not; however, if the CPU is not being utilized during an XL
  272.        animation there is no need to disable ECC (since the bandwidth is
  273.        there to be used).  The only time ECC should be disabled is when you
  274.        are doing intense calculations in the background of a READXL command,
  275.        AND your program is time-critical.  Do not forget to change this back
  276.        when you are done!
  277.        
  278.        To make the computer reset when a CD is ejected (for an application
  279.        that does not exit), use the TAGCD_EJECTRESET tag.  When possible,
  280.        titles should be able to exit cleanly back to Workbench.  Error
  281.        conditions should be monitored when doing disk I/O.
  282.  
  283.    EXAMPLE
  284.        /* Configure ReadXL for double-speed reading and turn off ECC when */
  285.        /* the ReadXL command is used.                                     */
  286.        
  287.        struct TagItem ConfigList[] = {
  288.  
  289.            { TAGCD_READXLSPEED, 150 },
  290.            { TAGCD_XLECC,       0   },
  291.            { TAG_END,           0   }
  292.            };
  293.  
  294.            ior->io_Command = CD_CONFIG;
  295.            ior->io_Data    = (APTR)&ConfigList;
  296.            ior->io_Length  = 0;
  297.            DoIO(ior);
  298.  
  299.            if (ior->io_Error) printf("Could not be configured\n");
  300.  
  301.    NOTES
  302.        Setting the configuration will not modify the behavior of a read or
  303.        play command already in progress.
  304.  
  305.        This can be a very dangerous command.  If for instance you set
  306.        TAGCD_SECTORSIZE to 2328, you will no longer be able to read any
  307.        data encoded at 2048 byte sectors (e.g. the file system will not be
  308.        able to read the disk anymore).  After you read any data stored with
  309.        this sector format, you should immediately configure back to the
  310.        original default value (even if the read failed -- the disk could
  311.        be removed in the middle of your read).  You should NEVER use this
  312.        command if you are not the exclusive owner of your disk.
  313.  
  314.    BUGS
  315.        TAG_IGNORE, TAG_MORE, and TAG_SKIP do not work.  Do not use these.
  316.  
  317.    SEE ALSO
  318.        CD_INFO, <utility/tagitem.h>
  319.  
  320. cd.device/CD_EJECT                                         cd.device/CD_EJECT
  321.  
  322.    NAME
  323.        CD_EJECT -- Open or close the CD's drive door
  324.  
  325.    IO REQUEST
  326.        io_Command      CD_EJECT
  327.        io_Data         NULL
  328.        io_Length       requested state of drive door (0 == close, 1 == open)
  329.        io_Offset       0
  330.  
  331.    RESULTS
  332.        io_Error        0 for success, or an error code as defined in
  333.                        <devices/cd.h>
  334.        io_Actual       previous state of drive door
  335.  
  336.    FUNCTION
  337.        This command causes the CD-ROM drive's door to open or close.
  338.        The desired state of the drive door is placed in io_Length.  The
  339.        previous state of the drive door is returned in io_Actual.
  340.  
  341.    EXAMPLE
  342.  
  343.    NOTES
  344.  
  345.    BUGS
  346.  
  347.    SEE ALSO
  348.  
  349. cd.device/CD_GETGEOMETRY                             cd.device/CD_GETGEOMETRY
  350.  
  351.    NAME
  352.        CD_GETGEOMETRY -- return the geometry of the drive.
  353.  
  354.    FUNCTION
  355.        This command returns a full set of information about the
  356.        layout of the drive. The information is returned in the
  357.        DriveGeometry structure pointed to by io_Data.
  358.  
  359.    IO REQUEST INPUT
  360.        io_Device       preset by the call to OpenDevice()
  361.        io_Unit         preset by the call to OpenDevice()
  362.        io_Command      CD_GETGEOMETRY
  363.        io_Data         pointer to a DriveGeometry structure
  364.        io_Length       sizeof(struct DriveGeometry)
  365.  
  366.    IO REQUEST RESULT
  367.        io_Error  - 0 for success, or an error code as defined in
  368.                    <devices/cd.h>
  369.        io_Actual - length of data transferred.
  370.  
  371.    SEE ALSO
  372.        CD_GETNUMTRACKS, <devices/trackdisk.h>
  373.  
  374. cd.device/CD_INFO                                           cd.device/CD_INFO
  375.  
  376.    NAME
  377.        CD_INFO -- Return information/status of device
  378.  
  379.    IO REQUEST
  380.        io_Device       preset by the call to OpenDevice()
  381.        io_Unit         preset by the call to OpenDevice()
  382.        io_Command      CD_INFO
  383.        io_Data         pointer to CDInfo structure
  384.        io_Length       sizeof(struct CDInfo)
  385.  
  386.    RESULTS
  387.        io_Error        0 for success, or an error code as defined in
  388.                        <devices/cd.h>
  389.        io_Actual       length of data transferred
  390.  
  391.    FUNCTION
  392.  
  393.        This command returns current configurations and status of the device
  394.        driver.
  395.  
  396.    EXAMPLE
  397.  
  398.        struct CDInfo Info;
  399.  
  400.        ior->io_Command = CD_INFO;               /* Retrieve drive info.    */
  401.        ior->io_Data    = (APTR)Info;            /* Here's where we want it */
  402.        ior->io_Length  = sizeof(struct CDInfo); /* Return whole structure  */
  403.        DoIO(ior);
  404.  
  405.        if (!ior->io_Error) {                    /* Command succeeded       */
  406.  
  407.            if (Info.Status & CDSTSF_PLAYING) printf("Audio is playing\n");
  408.            else                              printf("Audio not playing\n");
  409.            }
  410.  
  411.    NOTES
  412.  
  413.    BUGS
  414.  
  415.    SEE ALSO
  416.        <devices/cd.h>
  417.  
  418. cd.device/CD_MOTOR                                         cd.device/CD_MOTOR
  419.  
  420.    NAME
  421.        CD_MOTOR -- control the on/off state of a drive motor.
  422.  
  423.    FUNCTION
  424.        This command gives control over the spindle motor.  The motor may be
  425.        turned on or off.
  426.  
  427.        If the motor is just being turned on, the device will delay the
  428.        proper amount of time to allow the drive to come up to speed.
  429.        Turning the motor on or off manually is not necessary, the device does
  430.        this automatically if it receives a request when the motor is off.
  431.  
  432.    IO REQUEST INPUT
  433.        io_Device       preset by the call to OpenDevice()
  434.        io_Unit         preset by the call to OpenDevice()
  435.        io_Command      CD_MOTOR
  436.        io_Length       the requested state of the motor, 0 to turn the motor
  437.                        off, and 1 to turn the motor on.
  438.  
  439.    IO REQUEST RESULT
  440.        io_Error - 0 for success, or an error code as defined in
  441.                   <devices/cd.h>
  442.        io_Actual - if io_Error is 0 this contains the previous state of the
  443.                    drive motor.
  444.  
  445. cd.device/CD_PAUSE                                         cd.device/CD_PAUSE
  446.  
  447.    NAME
  448.        CD_PAUSE -- Pause or unPause play command.
  449.  
  450.    IO REQUEST
  451.        io_Device       preset by the call to OpenDevice()
  452.        io_Unit         preset by the call to OpenDevice()
  453.        io_Command      CD_PAUSE
  454.        io_Data         NULL
  455.        io_Length       pausemode : 1 = pause play; 0 = do not pause play;
  456.        io_Offset       0
  457.  
  458.    RESULTS
  459.        io_Actual - if io_Error is 0, this contains the previous pause state.
  460.  
  461.    FUNCTION
  462.        This command will place the CD in, or take the CD out of pause mode.
  463.        The desired pause state is placed in io_Length.  This command only
  464.        effects play commands.  When the audio is playing and the pausemode
  465.        is set, this command will immediately pause the audio output
  466.        suspending the play command until the play is unpaused.  When audio
  467.        is not playing and the pausemode is set, this command will set the
  468.        pause mode (having no immediate effect).  When a play command is
  469.        submitted, the laser will seek to the appropriate position and pause
  470.        at that spot.  The play command will be suspended until the play is
  471.        unpaused (or the play is aborted).
  472.  
  473.    EXAMPLE
  474.  
  475.    NOTES
  476.  
  477.    BUGS
  478.  
  479.    SEE ALSO
  480.  
  481. cd.device/CD_PLAYLSN                                     cd.device/CD_PLAYLSN
  482.  
  483.    NAME
  484.         CD_PLAYLSN -- Play a selected portion of CD audio (LSN form).
  485.  
  486.    IO REQUEST
  487.        io_Device       preset by the call to OpenDevice()
  488.        io_Unit         preset by the call to OpenDevice()
  489.        io_Command      CD_PLAYLSN
  490.        io_Data         NULL
  491.        io_Length       length of play
  492.        io_Offset       starting position
  493.  
  494.    RESULTS
  495.        io_Error        0 for success, or an error code as defined in
  496.                        <devices/cd.h>
  497.  
  498.    FUNCTION
  499.        This command causes the drive to start playing CD audio from the
  500.        specified position until the specified length has passed.
  501.  
  502.        io_Offset specifies the starting position.  io_Length contains
  503.        the amount of time to play.  All data is specified in LSN format.
  504.  
  505.        A DoIO() will not return until the requested number of sectors
  506.        have been played.  A SendIO() will return as soon as the PLAY
  507.        has been started.  At this time other commands can be sent (like
  508.        CD_PAUSE).  To stop a play before the specified length has been
  509.        reached, use AbortIO().
  510.  
  511.    EXAMPLE
  512.        /* Play two minutes, ten seconds of audio starting at 20 minutes, */
  513.        /* 58 seconds, and 10 frames.                                     */
  514.  
  515.        ior->io_Command = CD_PLAYLSN;   /* Play CD audio           */
  516.        ior->io_Offset  = 94360;        /* 20*(60*75) + 58*75 + 10 */
  517.        ior->io_Length  = 9750;         /* 02*(60*75) + 10*75 + 00 */
  518.        DoIO (ior);
  519.  
  520.    NOTES
  521.  
  522.    BUGS
  523.  
  524.    SEE ALSO
  525.        CD_PLAYTRACK, CD_PAUSE, CD_SEARCH, CD_ATTENUATE
  526.  
  527. cd.device/CD_PLAYMSF                                     cd.device/CD_PLAYMSF
  528.  
  529.    NAME
  530.         CD_PLAYMSF -- Play a selected portion of CD audio (MSF form).
  531.  
  532.    IO REQUEST
  533.        io_Device       preset by the call to OpenDevice()
  534.        io_Unit         preset by the call to OpenDevice()
  535.        io_Command      CD_PLAYMSF
  536.        io_Data         NULL
  537.        io_Length       length of play
  538.        io_Offset       starting position
  539.  
  540.    RESULTS
  541.        io_Error        0 for success, or an error code as defined in
  542.                        <devices/cd.h>
  543.  
  544.    FUNCTION
  545.        This command causes the drive to start playing CD audio from the
  546.        specified position until the specified length has passed.
  547.  
  548.        io_Offset specifies the starting position.  io_Length contains
  549.        the amount of time to play.  All data is specified in MSF format.
  550.  
  551.        A DoIO() will not return until the requested number of sectors
  552.        have been played.  A SendIO() will return as soon as the PLAY
  553.        has been started.  At this time other commands can be sent (like
  554.        CD_PAUSE).  To stop a play before the specified length has been
  555.        reached, use AbortIO().
  556.  
  557.    EXAMPLE
  558.        /* Play two minutes, ten seconds of audio starting at 20 minutes, */
  559.        /* 58 seconds, and 10 frames.                                     */
  560.  
  561.        ior->io_Command = CD_PLAYMSF;   /* Play CD audio          */
  562.        ior->io_Offset  = 0x00143A0A;   /* $14=20, $3A=58, $0A=10 */
  563.        ior->io_Length  = 0x00020A00;   /* $02=02, $0A=10, $00=00 */
  564.        DoIO (ior);
  565.  
  566.    NOTES
  567.  
  568.    BUGS
  569.  
  570.    SEE ALSO
  571.        CD_PLAYTRACK, CD_PAUSE, CD_SEARCH, CD_ATTENUATE
  572.  
  573. cd.device/CD_PLAYTRACK                                 cd.device/CD_PLAYTRACK
  574.  
  575.    NAME
  576.        CD_PLAYTRACK -- Play one or more tracks of CD audio.
  577.  
  578.    IO REQUEST
  579.        io_Device       preset by the call to OpenDevice()
  580.        io_Unit         preset by the call to OpenDevice()
  581.        io_Command      CD_PLAYTRACK
  582.        io_Data         NULL
  583.        io_Length       number of tracks to play
  584.        io_Offset       start playing at beginning of this track
  585.  
  586.    RESULTS
  587.        io_Error        0 for success, or an error code as defined in
  588.                        <devices/cd.h>
  589.    FUNCTION
  590.        This command causes the drive to play the specified audio track(s).
  591.        The command will return when the audio has completed.
  592.  
  593.        io_Offset specifies the track number (starting from 1).
  594.  
  595.        io_Length specifies the number of tracks to play (0 is invalid).  
  596.  
  597.    EXAMPLE
  598.  
  599.        ior->io_Command = CD_PLAYTRACK;    /* Play audio tracks     */
  600.        ior->io_Offset  = STARTTRACK;      /* Start with this track */
  601.        ior->io_Length  = 3;               /* Play three tracks     */
  602.        DoIO(ior);
  603.  
  604.    NOTES
  605.  
  606.        PLAY commands are asynchronous with many other CD commands.
  607.        Using a separate I/O request, other commands can be sent to the device
  608.        that can change the behavior of the PLAY command.
  609.  
  610.    BUGS
  611.  
  612.    SEE ALSO
  613.        CD_PLAYMSF, CD_PLAYLSN, CD_PAUSE, CD_SEARCH, CD_ATTENUATE
  614.  
  615. cd.device/CD_PROTSTATUS                               cd.device/CD_PROTSTATUS
  616.  
  617.    NAME
  618.        CD_PROTSTATUS -- return whether the current disk is write-protected.
  619.  
  620.    FUNCTION
  621.        This command is used to determine whether the current disk is
  622.        write-protected.  Currently, this function always returns write-
  623.        protected status.  If write-once CDs are made available at some point,
  624.        this may change.
  625.  
  626.    IO REQUEST INPUT
  627.        io_Device       preset by the call to OpenDevice()
  628.        io_Unit         preset by the call to OpenDevice()
  629.        io_Command      CD_PROTSTATUS
  630.  
  631.    IO REQUEST RESULT
  632.        io_Error - 0 for success, or an error code as defined in
  633.                   <devices/cd.h>
  634.        io_Actual - 0 means the disk is NOT write-protected, while any other
  635.                    value indicates it is.
  636.  
  637. cd.device/CD_QCODELSN                                   cd.device/CD_QCODELSN
  638.  
  639.    NAME
  640.        CD_QCODELSN -- Report current disk position.
  641.  
  642.    IO REQUEST
  643.        io_Device       preset by the call to OpenDevice()
  644.        io_Unit         preset by the call to OpenDevice()
  645.        io_Command      CD_QCODELSN
  646.        io_Data         pointer to QCode structure
  647.        io_Length       0 - MUST be zero (for future compatability)
  648.  
  649.    RESULTS
  650.        io_Error        0 for success, or an error code as defined in
  651.                        <devices/cd.h>
  652.  
  653.    FUNCTION
  654.        This command reports current subcode Q channel time information.  This
  655.        command only returns data when CD Audio is playing (or paused).  At
  656.        any other time, an error is returned.  The Q-Code packet consists of:
  657.  
  658.        struct QCode {
  659.  
  660.            UBYTE        CtlAdr;        /* Data type / QCode type           */
  661.            UBYTE        Track;         /* Track number                     */
  662.            UBYTE        Index;         /* Track subindex number            */
  663.            UBYTE        Zero;          /* The "Zero" byte of Q-Code packet */
  664.            union LSNMSF TrackPosition; /* Position from start of track     */
  665.            union LSNMSF DiskPosition;  /* Position from start of disk      */
  666.            };
  667.  
  668.    EXAMPLE
  669.  
  670.        struct QCode qcode;
  671.  
  672.        ior->io_Command = CD_QCODELSN;  /* Retrieve TOC information */
  673.        ior->io_Length  = 0;            /* MUST be zero             */
  674.        ior->io_Data    = (APTR)qcode;  /* Here's where we want it  */
  675.        DoIO (ior);
  676.  
  677.        if (!ior->io_Error) {           /* Command succeeded        */
  678.  
  679.            printf("Current position is: %ld\n", qcode.DiskPosition.LSN);
  680.            }
  681.  
  682.    NOTES
  683.        This function may not return immediately.  It may take several frames
  684.        to pass by before a valid Q-Code packet can be returned.  Use SendIO()
  685.        and CheckIO() if response time is critical, and the information is
  686.        not.
  687.  
  688.    BUGS
  689.  
  690.    SEE ALSO
  691.        CD_PLAYMSF, CD_PLAYLSN, CD_PLAYTRACK, <devices/cd.h>
  692.  
  693. cd.device/CD_QCODEMSF                                   cd.device/CD_QCODEMSF
  694.  
  695.    NAME
  696.        CD_QCODEMSF -- Report current disk position.
  697.  
  698.    IO REQUEST
  699.        io_Device       preset by the call to OpenDevice()
  700.        io_Unit         preset by the call to OpenDevice()
  701.        io_Command      CD_QCODEMSF
  702.        io_Data         pointer to QCode structure
  703.        io_Length       0 - MUST be zero (for future compatability)
  704.  
  705.    RESULTS
  706.        io_Error        0 for success, or an error code as defined in
  707.                        <devices/cd.h>
  708.  
  709.    FUNCTION
  710.        This command reports current subcode Q channel time information.  This
  711.        command only returns data when CD Audio is playing (or paused).  At 
  712.        any other time, an error is returned.  The Q-Code packet consists of:
  713.  
  714.        struct QCode {
  715.  
  716.            UBYTE        CtlAdr;        /* Data type / QCode type           */
  717.            UBYTE        Track;         /* Track number                     */
  718.            UBYTE        Index;         /* Track subindex number            */
  719.            UBYTE        Zero;          /* The "Zero" byte of Q-Code packet */
  720.            union LSNMSF TrackPosition; /* Position from start of track     */
  721.            union LSNMSF DiskPosition;  /* Position from start of disk      */
  722.            };
  723.  
  724.    EXAMPLE
  725.  
  726.        struct QCode qcode;
  727.  
  728.        ior->io_Command = CD_QCODEMSF;  /* Retrieve TOC information */
  729.        ior->io_Length  = 0;            /* MUST be zero             */
  730.        ior->io_Data    = (APTR)qcode;  /* Here's where we want it  */
  731.        DoIO (ior);
  732.  
  733.        if (!ior->io_Error) {           /* Command succeeded        */
  734.  
  735.            printf("Current position is: %02d:%02d:%02d\n",
  736.                qcode.DiskPosition.MSF.Minute,
  737.                qcode.DiskPosition.MSF.Second,
  738.                qcode.DiskPosition.MSF.Frame);
  739.            }
  740.  
  741.    NOTES
  742.        This function may not return immediately.  It may take several frames
  743.        to pass by before a valid Q-Code packet can be returned.  Use SendIO()
  744.        and CheckIO() if response time is critical, and the information is
  745.        not.
  746.  
  747.    BUGS
  748.  
  749.    SEE ALSO
  750.        CD_PLAYMSF, CD_PLAYLSN, CD_PLAYTRACK, <devices/cd.h>
  751.  
  752. cd.device/CD_READ                                           cd.device/CD_READ
  753.  
  754.    NAME
  755.        CD_READ -- read data from disk.
  756.  
  757.    FUNCTION
  758.        Reads data from the CD into memory.  Data may be accessed on WORD
  759.        boundaries (you are not restricted to sector boundaries as with
  760.        normal disk devices).  Data lengths can also be described in WORD
  761.        amounts.
  762.  
  763.    IO REQUEST INPUT
  764.        io_Device       preset by the call to OpenDevice()
  765.        io_Unit         preset by the call to OpenDevice()
  766.        io_Command      CD_READ
  767.        io_Data         pointer to the buffer where the data should be put
  768.        io_Length       number of bytes to read, must be a WORD multiple.
  769.        io_Offset       byte offset from the start of the disk describing
  770.                        where to read data from, must be a WORD multiple.
  771.  
  772.    IO REQUEST RESULT
  773.        io_Error  - 0 for success, or an error code as defined in
  774.                    <devices/cd.h>
  775.        io_Actual - if io_Error is 0, number of bytes actually transferred
  776.  
  777.    NOTES
  778.        If an error occurs when attempting a CD_READ, the software will
  779.        retry up to 10 times before giving up on the request.  If the
  780.        drive is in double-speed and an error occurs, the software will
  781.        retry once more in double-speed, and if this fails, will retry
  782.        the next 9 times in single-speed.
  783.  
  784.    SEE ALSO
  785.        CD_READXL
  786.  
  787. cd.device/CD_READXL                                       cd.device/CD_READXL
  788.  
  789.    NAME
  790.        CD_READXL -- Read from CD-ROM into memory via transfer list.
  791.  
  792.    IO REQUEST
  793.        io_Device       preset by the call to OpenDevice()
  794.        io_Unit         preset by the call to OpenDevice()
  795.        io_Command      CD_READXL
  796.        io_Data         pointer to transfer list (i.e. struct List *).
  797.        io_Length       maximum transfer length (WORD multiple) or 0.
  798.        io_Offset       byte offset from the start of the disk describing
  799.                        where to read data from, must be a WORD multiple.
  800.  
  801.    RESULTS
  802.        io_Error        0 for success, or an error code as described in
  803.                        <devices/cd.h>
  804.        io_Actual       if io_Error is 0, number of bytes actually transferred
  805.  
  806.    FUNCTION
  807.        This command starts reading data off the disk at the specified
  808.        location and deposits it into memory according to the nodes in a
  809.        transfer list.  The pointer to the list of transfer nodes is placed
  810.        in io_Data.  If you have a non-circular transfer list, simply set
  811.        io_Length to 0 (0 is special and means ignore io_Length) -- your
  812.        transfer will end when your transfer list has been exhausted.  If you
  813.        have a circular transfer list, the list will never end.  In this case,
  814.        the transfer will terminate when io_Length bytes have been
  815.        transferred.
  816.  
  817.        The fields in the CDXL node structure are:
  818.  
  819.        struct  CDXL {
  820.  
  821.            struct MinNode  Node;         /* double linkage                */
  822.            char           *Buffer;       /* data destination              */
  823.            LONG            Length;       /* must be even # bytes          */
  824.            LONG            Actual;       /* bytes transferred             */
  825.            APTR            IntData;      /* interrupt server data segment */
  826.            VOID            (*IntCode)(); /* interrupt server code entry   */
  827.            };
  828.  
  829.        The philosophy here is that you set up the buffers you want filled,
  830.        create CDXL nodes describing the locations and sizes of these
  831.        buffers, link all the nodes together in the order that you'd like
  832.        (even make a circular list for animations), and execute the command.
  833.        The data will be streamed into the appropriate buffers until the
  834.        list has been exhausted, an entry with a Length of zero is
  835.        encountered, io_Length bytes have been transferred (if io_Length is
  836.        non-zero), or the command is aborted with AbortIO().
  837.  
  838.        If you fill in the (*IntCode)() field with a pointer to an interrupt
  839.        routine, your routine will be called when the transfer for the node
  840.        is complete.  Your code will be called before the driver proceeds to
  841.        the next node.  The interrupt should follow the same rules as standard
  842.        interrupts (see AddIntServer of Exec autodocs).  Register A2 will
  843.        contain a pointer to the node just completed.  You may manipulate the
  844.        list from within the interrupt. Your code must be brief (this is an
  845.        interrupt).  When returning from this interrupt, D0 should be cleared
  846.        and an RTS instruction should be used to return.
  847.  
  848.        Servers are called with the following register conventions:
  849.  
  850.            D0 - scratch
  851.            D1 - scratch
  852.  
  853.            A0 - scratch
  854.            A1 - server is_Data pointer (scratch)
  855.            A2 - pointer to CDXL node just completed
  856.  
  857.            A5 - jump vector register (scratch)
  858.  
  859.            all other registers must be preserved
  860.  
  861.    EXAMPLE
  862.  
  863.    NOTES
  864.        Try to make sure that small buffers are not overused.  Each time
  865.        a node is completed, an interrupt is generated.  If you find that
  866.        your computer is acting sluggish, or the CD_READXL command is
  867.        aborting, you are probably generating too many interrupts.  It is
  868.        not efficient to have more than a few of these interrupts generated
  869.        within a vertical blank.
  870.  
  871.        Unlike the READ command, the READXL command will not retry a sector
  872.        if there is an error.  Since the READXL command's purpose is primarily
  873.        for animations, data streaming is considered more important than the
  874.        data itself.  An error will be returned in io_Error if a data error
  875.        did occur.  This command will never drop to a lower speed in the event
  876.        of an error.
  877.  
  878.    BUGS
  879.  
  880.    SEE ALSO
  881.        CMD_READ, CD_SEEK, Autodocs - AddIntServer
  882.  
  883. cd.device/CD_REMCHANGEINT                           cd.device/CD_REMCHANGEINT
  884.  
  885.    NAME
  886.        CD_REMCHANGEINT -- remove a disk change software interrupt handler.
  887.  
  888.    FUNCTION
  889.        This command removes a disk change software interrupt added
  890.        by a previous use of CD_ADDCHANGEINT.
  891.  
  892.    IO REQUEST INPUT
  893.        The same IO request used for CD_ADDCHANGEINT.
  894.  
  895.        io_Device       preset by the call to OpenDevice()
  896.        io_Unit         preset by the call to OpenDevice()
  897.        io_Command      CD_REMCHANGEINT
  898.        io_Length       sizeof(struct Interrupt)
  899.        io_Data         pointer to Interrupt structure
  900.  
  901.    IO REQUEST RESULT
  902.        io_Error - 0 for success, or an error code as defined in
  903.                   <devices/cd.h>
  904.  
  905.    SEE ALSO
  906.        CD_ADDCHANGEINT, <devices/cd.h>
  907.  
  908. cd.device/CD_REMFRAMEINT                             cd.device/CD_REMFRAMEINT
  909.  
  910.    NAME
  911.        CD_REMFRAMEINT -- remove a CD-frame interrupt handler.
  912.  
  913.    IO REQUEST
  914.        The same IO request used for CD_ADDFRAMEINT.
  915.  
  916.        io_Device       preset by the call to OpenDevice()
  917.        io_Unit         preset by the call to OpenDevice()
  918.        io_Command      CD_REMFRAMEINT
  919.        io_Length       sizeof(struct Interrupt)
  920.        io_Data         pointer to Interrupt structure
  921.  
  922.    RESULTS
  923.        io_Error        0 for success, or an error code as defined in
  924.                        <devices/cd.h>
  925.  
  926.    FUNCTION
  927.        This command removes a CD-frame software interrupt added
  928.        by a previous use of CD_ADDFRAMEINT.
  929.  
  930.    BUGS
  931.  
  932.    SEE ALSO
  933.        CD_ADDFRAMEINT, <devices/cd.h>
  934.  
  935. cd.device/CD_SEARCH                                       cd.device/CD_SEARCH
  936.  
  937.    NAME
  938.        CD_SEARCH -- configure the mode in which PLAY commands play
  939.  
  940.    IO REQUEST
  941.        io_Command      CD_SEARCH
  942.        io_Data         NULL
  943.        io_Length       searchmode
  944.        io_Offset       0
  945.  
  946.    RESULTS
  947.        io_Actual - if io_Error is 0, this contains the previous search mode.
  948.  
  949.    FUNCTION
  950.        This command causes a play command to play in fast-forward,
  951.        fast-reverse, or normal play mode.  These modes are defined as:
  952.  
  953.        CDMODE_NORMAL   0   Normal play (current speed setting)
  954.        CDMODE_FFWD     1   Play in fast forward mode  
  955.        CDMODE_FREV     2   Play in fast reverse mode
  956.  
  957.        The search mode can be set before the play command is sent, or during
  958.        a play.  If CD_SEARCH is sent before a play command is sent, the
  959.        mode is set and the command immediately returns.  If the mode is set
  960.        to REV mode, when the play command is sent the play will begin at the
  961.        requested end position and work backwards to the start position.
  962.  
  963.        If CD_SEARCH is sent during a play, the play will automatically
  964.        switch to the desired mode and continue playing until the original
  965.        play command is completed.  If REV mode is set and the beginning of
  966.        the play is encountered before switching back to forward play, the
  967.        play command will terminate with no error.
  968.  
  969.    EXAMPLE
  970.        /* Search in fast forward mode. */
  971.        ior->io_Command = CD_SEARCH;
  972.        ior->io_Data    = NULL;
  973.        ior->io_Offset  = 0;
  974.        ior->io_Length  = CDMODE_FFWD;
  975.        DoIO(ior);
  976.  
  977.    NOTES
  978.  
  979.    BUGS
  980.  
  981.    SEE ALSO
  982.  
  983. cd.device/CD_SEEK                                           cd.device/CD_SEEK
  984.  
  985.    NAME
  986.        CD_SEEK -- position laser at specified location.
  987.  
  988.    FUNCTION
  989.        CD_SEEK moves the laser to the approximate position specified.  The
  990.        io_Offset field should be set to the offset to which the head is
  991.        to be positioned.
  992.  
  993.    IO REQUEST INPUT
  994.        io_Device       preset by the call to OpenDevice()
  995.        io_Unit         preset by the call to OpenDevice()
  996.        io_Command      CD_SEEK
  997.        io_Offset       position where head is to be moved (always LSN format)
  998.  
  999.    IO REQUEST RESULT
  1000.        io_Error - 0 for success, or an error code as defined in
  1001.                   <devices/cd.h>
  1002.  
  1003. cd.device/CD_TOCLSN                                       cd.device/CD_TOCLSN
  1004.  
  1005.    NAME
  1006.        CD_TOCLSN -- Return table of contents information from CD (LSN form).
  1007.  
  1008.    IO REQUEST
  1009.        io_Device       preset by the call to OpenDevice()
  1010.        io_Unit         preset by the call to OpenDevice()
  1011.        io_Command      CD_TOCLSN
  1012.        io_Data         pointer to array where TOC is to be stored
  1013.        io_Length       number of CDTOC entries to be fetched
  1014.        io_Offset       entry to begin at (entry 0 is summary information)
  1015.  
  1016.    RESULTS
  1017.        io_Error        0 for success, or an error code as defined in
  1018.                        <devices/cd.h>
  1019.        io_Actual       Actual number of entries copied
  1020.  
  1021.    FUNCTION
  1022.        This command returns the table of contents of the disk currently in
  1023.        the drive.  The table of contents consists of up to 100 entries.
  1024.        Entry zero is summary information describing the number of tracks
  1025.        and the total number of minutes on the disk.  Entries 1 through N
  1026.        contain information about each individual track.  All position
  1027.        information will be in LSN format.
  1028.  
  1029.        The io_Data field points to an array of CDTOC structures to receive
  1030.        the TOC data.
  1031.  
  1032.        The io_Length field specifies the total number of entries to be
  1033.        fetched.  The array pointed to by io_Data must be at least this many
  1034.        elements in size.
  1035.  
  1036.        The io_Offset field specifies the entry number at which to start
  1037.        copying TOC data into *io_Data.
  1038.  
  1039.        Entry zero (the summary entry) contains the following:
  1040.  
  1041.        struct TOCSummary {
  1042.  
  1043.            UBYTE        FirstTrack;    /* First track on disk (always 1)   */
  1044.            UBYTE        LastTrack;     /* Last track on disk               */
  1045.            union LSNMSF LeadOut;       /* Beginning of lead-out track      */
  1046.            };
  1047.  
  1048.        Track entries (entries 1 through number of tracks) contain:
  1049.  
  1050.        struct TOCEntry {
  1051.  
  1052.            UBYTE        CtlAdr;        /* Q-Code info                  */
  1053.            UBYTE        Track;         /* Track number                 */
  1054.            union LSNMSF Position;      /* Start position of this track */
  1055.            };
  1056.  
  1057.        CDTOC is described as a union between these two structures:
  1058.  
  1059.        union CDTOC {
  1060.  
  1061.            struct TOCSummary Summary;  /* First entry is summary info.  */
  1062.            struct TOCEntry   Entry;    /* Entries 1-N are track entries */
  1063.            };
  1064.  
  1065.  
  1066.    EXAMPLE
  1067.        
  1068.        union CDTOC tocarray[100];
  1069.  
  1070.        ior->io_Command = CD_TOCLSN;        /* Retrieve TOC information */
  1071.        ior->io_Offset  = 0;                /* Start with summary info  */
  1072.        ior->io_Length  = 100;              /* Max 99 tracks + summary  */
  1073.        ior->io_Data    = (APTR)tocarray;   /* Here's where we want it  */
  1074.        DoIO (ior);
  1075.  
  1076.        if (!ior->io_Error) {               /* Command succeeded        */
  1077.  
  1078.            firsttrack   = tocarray[0].Summary.FirstTrack;
  1079.            lasttrack    = tocarray[0].Summary.LastTrack;
  1080.            totalsectors = tocarray[0].Summary.LeadOut.LSN -
  1081.                           tocarray[1].Entry.Position.LSN;
  1082.            }
  1083.  
  1084.    NOTES
  1085.  
  1086.        In the above example, the amount of data on the disk is calculated as
  1087.        being equal to the location of the lead-out track minus the start of
  1088.        the first track (which is never zero).
  1089.  
  1090.    BUGS
  1091.  
  1092.    SEE ALSO
  1093.  
  1094. cd.device/CD_TOCMSF                                       cd.device/CD_TOCMSF
  1095.  
  1096.    NAME
  1097.        CD_TOCMSF -- Return table of contents information from CD (MSF form).
  1098.  
  1099.    IO REQUEST
  1100.        io_Device       preset by the call to OpenDevice()
  1101.        io_Unit         preset by the call to OpenDevice()
  1102.        io_Command      CD_TOCMSF
  1103.        io_Data         pointer to array where TOC is to be stored
  1104.        io_Length       number of CDTOC entries to be fetched
  1105.        io_Offset       entry to begin at (entry 0 is summary information)
  1106.  
  1107.    RESULTS
  1108.        io_Error        0 for success, or an error code as defined in
  1109.                        <devices/cd.h>
  1110.        io_Actual       Actual number of entries copied
  1111.  
  1112.    FUNCTION
  1113.        This command returns the table of contents of the disk currently in
  1114.        the drive.  The table of contents consists of up to 100 entries.
  1115.        Entry zero is summary information describing the number of tracks
  1116.        and the total number of minutes on the disk.  Entries 1 through N
  1117.        contain information about each individual track.  All position
  1118.        information will be in MSF format.
  1119.  
  1120.        The io_Data field points to an array of CDTOC structures to receive
  1121.        the TOC data.
  1122.  
  1123.        The io_Length field specifies the total number of entries to be
  1124.        fetched.  The array pointed to by io_Data must be at least this many
  1125.        elements in size.
  1126.  
  1127.        The io_Offset field specifies the entry number at which to start
  1128.        copying TOC data into *io_Data.
  1129.  
  1130.        Entry zero (the summary entry) contains the following:
  1131.  
  1132.        struct TOCSummary {
  1133.  
  1134.            UBYTE        FirstTrack;    /* First track on disk (always 1)   */
  1135.            UBYTE        LastTrack;     /* Last track on disk               */
  1136.            union LSNMSF LeadOut;       /* Beginning of lead-out track      */
  1137.            };
  1138.  
  1139.        Track entries (entries 1 through number of tracks) contain:
  1140.  
  1141.        struct TOCEntry {
  1142.  
  1143.            UBYTE        CtlAdr;        /* Q-Code info                  */
  1144.            UBYTE        Track;         /* Track number                 */
  1145.            union LSNMSF Position;      /* Start position of this track */
  1146.            };
  1147.  
  1148.        CDTOC is described as a union between these two structures:
  1149.  
  1150.        union CDTOC {
  1151.  
  1152.            struct TOCSummary Summary;  /* First entry is summary info.  */
  1153.            struct TOCEntry   Entry;    /* Entries 1-N are track entries */
  1154.            };
  1155.  
  1156.  
  1157.    EXAMPLE
  1158.        
  1159.    NOTES
  1160.  
  1161.    BUGS
  1162.  
  1163.    SEE ALSO
  1164.  
  1165. cd.device/CloseDevice                                   cd.device/CloseDevice
  1166.  
  1167.    NAME
  1168.        CloseDevice - terminate access to the CD
  1169.  
  1170.    SYNOPSIS
  1171.        CloseDevice(IORequest);
  1172.                    A1
  1173.  
  1174.    FUNCTION
  1175.        This function will terminate access to the unit openned with
  1176.        OpenDevice().
  1177.  
  1178.    INPUTS
  1179.        iORequest - pointer to a struct(IOStdReq)
  1180.  
  1181.    RESULTS
  1182.  
  1183.    NOTES
  1184.  
  1185.    SEE ALSO
  1186.        OpenDevice()
  1187.  
  1188. cd.device/OpenDevice                                     cd.device/OpenDevice
  1189.  
  1190.    NAME
  1191.        OpenDevice - Open a CD unit for access
  1192.  
  1193.    SYNOPSIS
  1194.        error = OpenDevice("cd.device", UnitNumber, IORequest, flags);
  1195.        D0                 A0           D0          A1         D1
  1196.  
  1197.    FUNCTION
  1198.        Opens the cd.device and creates an IORequest for use in accessing
  1199.        the CD.
  1200.  
  1201.    INPUTS
  1202.        UnitNumber - Normally zero; however, this is described as:
  1203.                     Ones digit      = Unit (SCSI unit number)
  1204.                     Tens digit      = LUN (disk within disk changer)
  1205.                     Hundreds digit  = Card number (SCSI card)
  1206.                     Thousands digit = Reserved (must be zero)
  1207.        IORequest  - Pointer to a struct(IOStdReq)
  1208.        flags      - Should be zero.
  1209.  
  1210.    RESULTS
  1211.        error        0 = success, otherwise this is an error.
  1212.  
  1213.    NOTES
  1214.  
  1215.    SEE ALSO
  1216.        CloseDevice()
  1217.  
  1218.