home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / multimed / mmpm2 / mcirexx.inf (.txt) < prev    next >
Encoding:
OS/2 Help File  |  1993-04-23  |  33.6 KB  |  1,168 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. This book discusses how you can use Media Control Interface textual string 
  5. commands within a REXX Program to enable application control of media devices. 
  6.  
  7. The first section, Media Control Interface String Commands, describes the 
  8. standard Media Control Interface string commands that are recognized by all 
  9. media devices, as well as some common device-specific commands. 
  10.  
  11. The second section, Using MCI String Commands in a REXX File, describes how you 
  12. can use string commands in a REXX file (with some limitations) rather than 
  13. having to use the programming APIs. 
  14.  
  15.  
  16. ΓòÉΓòÉΓòÉ 2. Media Control Interface Commands ΓòÉΓòÉΓòÉ
  17.  
  18. The Media Control Interface (MCI) provides a view of the OS/2 multimedia system 
  19. that is similar to that of a video and audio home entertainment system..  Each 
  20. component in the system is known as a media device, and can be controlled by a 
  21. set of textual string-oriented commands. 
  22.  
  23. Media devices can be both internal and external hardware devices.  Some devices 
  24. are compound devices and can open files, such as waveaudio or MIDI.  Other 
  25. devices are controllable external devices that can be controlled directly, such 
  26. as a CD-ROM device or videodisc. 
  27.  
  28.  
  29. ΓòÉΓòÉΓòÉ 2.1. Standard String Commands - Introduction ΓòÉΓòÉΓòÉ
  30.  
  31. There are standard Media Control Interface string commands that are recognized 
  32. by all devices.  MCI devices are required to support the use of these commands. 
  33. Extended commands can add other options to these commands. 
  34.  
  35. In addition to the standard Media Control Interface string commands, each 
  36. device also supports a set of commands specific to its device type. Where 
  37. possible, these type-specific commands are identical between types. For 
  38. example, the basic PLAY command is identical for videodisc, wave audio, and CD 
  39. audio players. 
  40.  
  41. The format of the strings follows.  Select one of the highlighted words for 
  42. additional information: 
  43.  
  44. COMMAND OBJECT [KEYWORDS] [WAIT] 
  45.  
  46. For commands which return string information, such as CAPABILITY and STATUS, 
  47. the WAIT keyword is required. 
  48.  
  49. Examples: 
  50.  
  51. o Open the file foo.wav, give it the wave alias: open foo.wav alias wave wait 
  52. o Open the default compact disc device, give it the CD alias: open cdaudio 
  53.   alias cd wait 
  54. o Open the second of two audio devices, give it the wave2 alias: open 
  55.   waveaudio02 alias wave2 wait 
  56. o Play foo.wav, using the wave alias: play wave wait 
  57.  
  58. Proceed to the next panel for a list of the standard commands. 
  59.  
  60.  
  61. ΓòÉΓòÉΓòÉ <hidden> Command Object ΓòÉΓòÉΓòÉ
  62.  
  63. The object associated with a Media Control Interface command can be one of the 
  64. following: 
  65.  
  66. o Device type - The default device of a given type.  The possible types of 
  67.   controllable devices include the following: 
  68.  
  69.    Videotape - A videotape player or recorder. 
  70.    Videodisc - A videodisc player. 
  71.    CDaudio - A CD-ROM device which supports standard compact disc playback. 
  72.    Waveaudio - A device which supports digital audio files ("sound board"). 
  73.    Sequencer - A device which supports MIDI files. 
  74.    Digitalvideo - A device which supports audio/video files, either 
  75.    hardware-assisted or software motion video-only. 
  76.  
  77. If you have multiple devices of the same type, the MMPM/2 Multimedia Setup 
  78. program allows you to decide which device should be the default for that type. 
  79.  
  80. o Device name - A name of a particular device.  Device names are of the form 
  81.   DevicetypeNN, where Devicetype is one of the device types given above, and NN 
  82.   is a value (01, 02,...) indicating which device of that type is to be 
  83.   controlled. 
  84.  
  85. o Filename - The name of a file to be opened or controlled.  When a filename is 
  86.   opened, MMPM/2 first examines the file's extension, then its type, to 
  87.   determine which device is associated to the file. 
  88.  
  89. o Alias - A string that was specified on a previous OPEN command.  This string 
  90.   can then be used as the object name in subsequent commands. 
  91.  
  92.  
  93. ΓòÉΓòÉΓòÉ 2.2. Command List ΓòÉΓòÉΓòÉ
  94.  
  95.  
  96. ΓòÉΓòÉΓòÉ <hidden> Commands ΓòÉΓòÉΓòÉ
  97.  
  98. Select a command for more information: 
  99.  
  100. o ACQUIRE 
  101. o CAPABILITY 
  102. o CLOSE 
  103. o CONNECTOR 
  104. o INFO 
  105. o LOAD 
  106. o OPEN 
  107. o PAUSE 
  108. o PLAY 
  109. o RECORD 
  110. o RELEASE 
  111. o RESUME 
  112. o SAVE 
  113. o SEEK 
  114. o SET 
  115. o STATUS 
  116. o STOP 
  117.  
  118.  
  119. ΓòÉΓòÉΓòÉ <hidden> ACQUIRE ΓòÉΓòÉΓòÉ
  120.  
  121. ACQUIRE object items WAIT Gains the use of the physical resources associated 
  122.                     with the object. 
  123.  
  124.                     The following optional items modify the basic command: 
  125.  
  126.    o exclusive 
  127.    o exclusive instance 
  128.    o queue 
  129.  
  130.  
  131. ΓòÉΓòÉΓòÉ <hidden> exclusive ΓòÉΓòÉΓòÉ
  132.  
  133. Obtains exclusive use of the resources associated with the object.  No other 
  134. applications can obtain use of the device until the RELEASE command is 
  135. executed. 
  136.  
  137.  
  138. ΓòÉΓòÉΓòÉ <hidden> exclusive instance ΓòÉΓòÉΓòÉ
  139.  
  140. Obtains exclusive use of only the resources needed by the object.  Other 
  141. applications may be able to use the same device concurrently, depending upon 
  142. the number and types of resources they require. 
  143.  
  144.  
  145. ΓòÉΓòÉΓòÉ <hidden> queue ΓòÉΓòÉΓòÉ
  146.  
  147. Requests use of the resources associated with the object.  If another 
  148. application has exclusive use of the same physical resources, then this command 
  149. will wait until the resources can be acquired. 
  150.  
  151.  
  152. ΓòÉΓòÉΓòÉ <hidden> CAPABILITY ΓòÉΓòÉΓòÉ
  153.  
  154. CAPABILITY object items WAIT Requests information about a particular capability 
  155.                     of a device. The WAIT keyword must be specified in order to 
  156.                     receive the returned string information. While other 
  157.                     capabilities are defined for specific devices and device 
  158.                     types, the following items can always be specified: 
  159.  
  160. o can record 
  161. o has audio 
  162. o has video 
  163. o can eject 
  164. o can play 
  165. o can save 
  166. o compound device 
  167. o uses files 
  168. o can lockeject 
  169. o can setvolume 
  170. o preroll type 
  171. o preroll time 
  172. o device type 
  173. o message item 
  174.  
  175.  
  176. ΓòÉΓòÉΓòÉ <hidden> can record ΓòÉΓòÉΓòÉ
  177.  
  178. Returns true if the device supports recording. 
  179.  
  180.  
  181. ΓòÉΓòÉΓòÉ <hidden> has audio ΓòÉΓòÉΓòÉ
  182.  
  183. Returns true if the device supports audio playback. 
  184.  
  185.  
  186. ΓòÉΓòÉΓòÉ <hidden> has video ΓòÉΓòÉΓòÉ
  187.  
  188. Returns true if the device supports video playback. 
  189.  
  190.  
  191. ΓòÉΓòÉΓòÉ <hidden> can eject ΓòÉΓòÉΓòÉ
  192.  
  193. Returns true if the device can eject the media. 
  194.  
  195.  
  196. ΓòÉΓòÉΓòÉ <hidden> can play ΓòÉΓòÉΓòÉ
  197.  
  198. Returns true if the device can play. 
  199.  
  200.  
  201. ΓòÉΓòÉΓòÉ <hidden> can save ΓòÉΓòÉΓòÉ
  202.  
  203. Returns true if the device can save data. 
  204.  
  205.  
  206. ΓòÉΓòÉΓòÉ <hidden> compound device ΓòÉΓòÉΓòÉ
  207.  
  208. Returns true if the device requires an element name. 
  209.  
  210.  
  211. ΓòÉΓòÉΓòÉ <hidden> uses files ΓòÉΓòÉΓòÉ
  212.  
  213. Returns true if the device requires a file path name. 
  214.  
  215.  
  216. ΓòÉΓòÉΓòÉ <hidden> can lockeject ΓòÉΓòÉΓòÉ
  217.  
  218. Returns true if the device can disable the manual ejection of the media. 
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ <hidden> can setvolume ΓòÉΓòÉΓòÉ
  222.  
  223. Returns true if the device supports software control of volume level. 
  224.  
  225.  
  226. ΓòÉΓòÉΓòÉ <hidden> preroll type ΓòÉΓòÉΓòÉ
  227.  
  228. Returns the preroll characteristics of the device: Returns notified if the 
  229. preroll time for the device is variable. Returns deterministic if the prerolled 
  230. time for the device is fixed. Returns none if the device does not support 
  231. preroll. 
  232.  
  233.  
  234. ΓòÉΓòÉΓòÉ <hidden> preroll time ΓòÉΓòÉΓòÉ
  235.  
  236. Returns the deterministic or maximum notified preroll time in MMTIME units.  A 
  237. value of 0 for a notified preroll device indicates the preroll time is not 
  238. bounded. 
  239.  
  240.  
  241. ΓòÉΓòÉΓòÉ <hidden> device type ΓòÉΓòÉΓòÉ
  242.  
  243. Returns one of the following: 
  244.  
  245. o animation 
  246. o ampmix 
  247. o cdaudio 
  248. o cdxa 
  249. o digitalvideo 
  250. o overlay 
  251. o sequencer 
  252. o videodisc 
  253. o waveaudio 
  254. o other 
  255.  
  256.  
  257. ΓòÉΓòÉΓòÉ <hidden> message item ΓòÉΓòÉΓòÉ
  258.  
  259. Returns true if the device supports the message specified by item. 
  260.  
  261.  
  262. ΓòÉΓòÉΓòÉ <hidden> CLOSE ΓòÉΓòÉΓòÉ
  263.  
  264. CLOSE object      Closes the device context and frees resources.  The object to 
  265.                   close should be the same one used when the device context was 
  266.                   initially opened. 
  267.  
  268. Select the following word for an example of how to use the CLOSE command. 
  269.  
  270. Example: 
  271.  
  272.  
  273. ΓòÉΓòÉΓòÉ <hidden> CONNECTOR ΓòÉΓòÉΓòÉ
  274.  
  275. CONNECTOR object action items Enables, disables, or queries the status of 
  276.                     connectors on a device. 
  277.  
  278. An action must be specified.  The possible values are: 
  279.  
  280. enable      Enables information flow through the indicated connector. Use of 
  281.             this option requires that the number or type options, or both must 
  282.             also be specified. 
  283. disable     Disables information flow through the indicated connector. Use of 
  284.             this option requires that the number or type options, or both must 
  285.             also be specified. 
  286. query       Queries the status of the indicated connector.  The return value 
  287.             will be either "true" or "false" to indicate enabled or disabled 
  288.             respectively. Use of this option requires that the number or type 
  289.             options, or both must also be specified. 
  290.  
  291. The following items modify the basic command: 
  292.  
  293. o number <connector_number> 
  294. o type <connector_type> 
  295.  
  296. Examples: 
  297.  
  298. o Query the waveaudio device to determine whether the line in connector is 
  299.   enabled: 
  300.  
  301.                     connector waveaudio query type line in wait
  302.  
  303. o Enable the microphone connector of the device opened with alias wave: 
  304.  
  305.                        connector wave enable type microphone
  306.  
  307.  
  308. ΓòÉΓòÉΓòÉ <hidden> number <connector_number> ΓòÉΓòÉΓòÉ
  309.  
  310. The connector number on which to perform the requested action. If this item is 
  311. omitted, the first connector is assumed.  If the type item is included, then 
  312. the connector number is interpreted as a relative offset within the specified 
  313. connector type. 
  314.  
  315.  
  316. ΓòÉΓòÉΓòÉ <hidden> type <connector_type> ΓòÉΓòÉΓòÉ
  317.  
  318. The type of connector to which the requested action applies.  The following 
  319. connector types are defined: 
  320.  
  321. MIDI stream 
  322.  
  323.     Digital input or output for a sequencer device.  This data is typically 
  324.     streamed to an amplifier mixer device. 
  325. CD stream 
  326.  
  327.     Digital output for a CD audio device capable of reading the data directly 
  328.     off of a disk.  The data is typically streamed to an amplifier mixer 
  329.     device. 
  330. wave stream 
  331.  
  332.     Digital input or output for a waveform audio device.  The data is typically 
  333.     streamed to an amplifier mixer device. 
  334. XA stream 
  335.  
  336.     Digital output for a CD-ROM/XA device.  The data is typically streamed to 
  337.     an amplifier mixer device. 
  338. amp stream 
  339.  
  340.     Digital input or output for an amplifier mixer device. 
  341. headphones 
  342.  
  343.     The connector on the device which is labeled or is typically used to attach 
  344.     headphones to the device. 
  345. speakers 
  346.  
  347.     The connector on the device which is labeled or is typically used to attach 
  348.     speakers to the device. 
  349. microphone 
  350.  
  351.     The connector on the device which is labeled or is typically used to attach 
  352.     a microphone to the device. 
  353. line in 
  354.  
  355.     The connector on the device which is labeled or is typically used to 
  356.     provide line level input to the device. 
  357. line out 
  358.  
  359.     The connector on the device which is labeled or is typically used to 
  360.     provide line level output from the device. 
  361. video in 
  362.  
  363.     The connector on the device which is labeled or is typically used to 
  364.     provide video input to the device. 
  365. video out 
  366.  
  367.     The connector on the device which is labeled or is typically used to 
  368.     provide video output from the device. 
  369.  
  370.  
  371. ΓòÉΓòÉΓòÉ <hidden> INFO ΓòÉΓòÉΓòÉ
  372.  
  373. INFO object product Returns a string identifying product information associated 
  374.                   with the object. 
  375.  
  376. For example, if you have an IBM audio adapter, you would issue: 
  377.  
  378.                              info waveaudio product
  379.  
  380. One possible return string is "IBM M-Audio Adapter". 
  381.  
  382.  
  383. ΓòÉΓòÉΓòÉ <hidden> product ΓòÉΓòÉΓòÉ
  384.  
  385. Returns a description of the hardware associated with a device.  This usually 
  386. includes the manufacturer and model information. 
  387.  
  388.  
  389. ΓòÉΓòÉΓòÉ <hidden> LOAD ΓòÉΓòÉΓòÉ
  390.  
  391. LOAD object       Loads a new device element (file) into a previously opened 
  392.                   device context. 
  393.  
  394. The following item modifies the basic command: 
  395.  
  396. o filename 
  397.  
  398. Note:   If you wish to load and play a digital video file using REXX programs, 
  399.         then you should run the REXX program using PMREXX.  See the section 
  400.         entitled REXX Command File Limitations section for other restrictions. 
  401.  
  402. Select the following word for an example of how to use the LOAD command. 
  403.  
  404. Example: 
  405.  
  406.  
  407. ΓòÉΓòÉΓòÉ <hidden> filename ΓòÉΓòÉΓòÉ
  408.  
  409. Name of the file to be loaded.  NEW is a reserved filename, which instructs 
  410. MMPM/2 to open an untitled file (use the SAVE command to save this file). 
  411.  
  412.  
  413. ΓòÉΓòÉΓòÉ <hidden> OPEN ΓòÉΓòÉΓòÉ
  414.  
  415. OPEN object items Opens a specific device context for subsequent manipulation. 
  416.  
  417. The following items modify the basic command: 
  418.  
  419. o shareable 
  420. o type device_type 
  421. o alias device_alias 
  422.  
  423. A number representing the opened context, called the device ID, is returned 
  424. upon successful completion of the OPEN command. 
  425.  
  426. Select the following word for an example of how to use the OPEN command. 
  427.  
  428. Example: 
  429.  
  430.  
  431. ΓòÉΓòÉΓòÉ <hidden> shareable ΓòÉΓòÉΓòÉ
  432.  
  433. Initializes the device as shareable. Specifying shareable makes the resources 
  434. of the device available to other device contexts.  If shareable is not 
  435. specified with open, the resource will be exclusively acquired when the device 
  436. is opened. 
  437.  
  438.  
  439. ΓòÉΓòÉΓòÉ <hidden> type device_type ΓòÉΓòÉΓòÉ
  440.  
  441. Specifies the compound device used to control a device element. As an 
  442. alternative to type, Media Control Interface can use the extended attributes or 
  443. file extensions associated with the file to select the controlling device. 
  444.  
  445.  
  446. ΓòÉΓòÉΓòÉ <hidden> alias device_alias ΓòÉΓòÉΓòÉ
  447.  
  448. Specifies an alternate name for the given device. If an alias is specified, it 
  449. must be used in subsequent references to avoid automatic open. 
  450.  
  451. OPEN returns a device ID that is used for subsequent calls for procedure 
  452. interface, if desired. 
  453.  
  454.  
  455. ΓòÉΓòÉΓòÉ <hidden> PAUSE ΓòÉΓòÉΓòÉ
  456.  
  457. PAUSE object      Stops playing.  The difference between PAUSE and STOP is 
  458.                   device dependent.  On video devices, PAUSE generally 
  459.                   continues to display the last frame, whereas STOP causes the 
  460.                   display to blank.  A device that is paused can frequently 
  461.                   begin playing again with less latency than if it were 
  462.                   stopped. 
  463.  
  464.  
  465. ΓòÉΓòÉΓòÉ <hidden> PLAY ΓòÉΓòÉΓòÉ
  466.  
  467. PLAY object items Begin playing the file or device. 
  468.  
  469. The following items modify the basic command: 
  470.  
  471. o from pos 
  472. o to pos 
  473.  
  474. Select the following word for an example of how to use the PLAY command. 
  475.  
  476. Example: 
  477.  
  478.  
  479. ΓòÉΓòÉΓòÉ <hidden> from pos ΓòÉΓòÉΓòÉ
  480.  
  481. Specifies the position at which to start playing. If this keyword is omitted, 
  482. the device starts playing at the current position. 
  483.  
  484.  
  485. ΓòÉΓòÉΓòÉ <hidden> to pos ΓòÉΓòÉΓòÉ
  486.  
  487. Specifies the position at which to stop playing. If this keyword is omitted, 
  488. the device plays to the end of the media. 
  489.  
  490.  
  491. ΓòÉΓòÉΓòÉ <hidden> RECORD ΓòÉΓòÉΓòÉ
  492.  
  493. RECORD object items Starts recording data.  By default, recording does not 
  494.                   overwrite existing data but rather inserts data at the 
  495.                   current position.  On devices (such as audio or video tape) 
  496.                   that cannot support inserting data, recording overwrites 
  497.                   existing data by default. 
  498.  
  499. The following items modify the basic command: 
  500.  
  501. o insert 
  502. o overwrite 
  503. o from pos 
  504. o to pos 
  505.  
  506.  
  507. ΓòÉΓòÉΓòÉ <hidden> insert ΓòÉΓòÉΓòÉ
  508.  
  509. Data is to be added to the device element. This is the default on devices that 
  510. support insertion of data (file-oriented devices).  An error is returned if the 
  511. device does not support INSERT. 
  512.  
  513.  
  514. ΓòÉΓòÉΓòÉ <hidden> overwrite ΓòÉΓòÉΓòÉ
  515.  
  516. Recorded data replaces existing data in the device element. This is the default 
  517. on devices that do not support insertion of data (for example, videotape). 
  518.  
  519.  
  520. ΓòÉΓòÉΓòÉ <hidden> from pos ΓòÉΓòÉΓòÉ
  521.  
  522. Specifies the position at which to start recording. If this keyword is omitted, 
  523. the device starts recording at the current position. 
  524.  
  525.  
  526. ΓòÉΓòÉΓòÉ <hidden> to pos ΓòÉΓòÉΓòÉ
  527.  
  528. Specifies the position at which to start or stop recording. If this keyword is 
  529. omitted, the device records to the end of the media. 
  530.  
  531.  
  532. ΓòÉΓòÉΓòÉ <hidden> RELEASE ΓòÉΓòÉΓòÉ
  533.  
  534. RELEASE object [return resource] Notifies MMPM/2 that the physical resources 
  535.                   associated with the object are no longer required. 
  536.  
  537. Control of the physical device is not necessarily lost when the command is 
  538. executed. 
  539.  
  540. If the return resource keywords are specified, then control of the physical 
  541. resources for a given device will be given to the last application which lost 
  542. it. 
  543.  
  544.  
  545. ΓòÉΓòÉΓòÉ <hidden> RESUME ΓòÉΓòÉΓòÉ
  546.  
  547. RESUME object     Resumes playing or recording from a paused state, keeping 
  548.                   previously specified settings in effect. 
  549.  
  550.  
  551. ΓòÉΓòÉΓòÉ <hidden> SAVE ΓòÉΓòÉΓòÉ
  552.  
  553. SAVE object [filename] Saves data for the device. 
  554.  
  555.  
  556. ΓòÉΓòÉΓòÉ <hidden> filename ΓòÉΓòÉΓòÉ
  557.  
  558. The destination path and name of the file to be saved.  If a filename was 
  559. specified during the LOAD command, then you do not need to specify a filename 
  560. when saving the file; the data will be saved using the current filename. 
  561.  
  562. If an untitled file was loaded, then a filename must be specified, or an error 
  563. will be returned. 
  564.  
  565.  
  566. ΓòÉΓòÉΓòÉ <hidden> SEEK ΓòÉΓòÉΓòÉ
  567.  
  568. SEEK object items Finds the specified position and stops. 
  569.  
  570. The following items modify the basic command: 
  571.  
  572. o to pos 
  573. o to start 
  574. o to end 
  575.  
  576. Select the following word for an example of how to use the SEEK command. 
  577.  
  578. Example: 
  579.  
  580.  
  581. ΓòÉΓòÉΓòÉ <hidden> to pos ΓòÉΓòÉΓòÉ
  582.  
  583. The position at which to stop the seek. 
  584.  
  585.  
  586. ΓòÉΓòÉΓòÉ <hidden> to start ΓòÉΓòÉΓòÉ
  587.  
  588. Seek to the beginning of the media. 
  589.  
  590.  
  591. ΓòÉΓòÉΓòÉ <hidden> to end ΓòÉΓòÉΓòÉ
  592.  
  593. Seek to the end of the media. 
  594.  
  595.  
  596. ΓòÉΓòÉΓòÉ <hidden> SET ΓòÉΓòÉΓòÉ
  597.  
  598. SET object items  Establishes the desired setttings for the object being 
  599.                   controlled. 
  600.  
  601. The following items modify the basic command: 
  602.  
  603. o audio 
  604. o door closed 
  605. o door open 
  606. o door locked 
  607. o door unlocked pos 
  608. o master MIDI 
  609. o master none 
  610. o master SMPTE 
  611. o slave file 
  612. o slave MIDI 
  613. o slave none 
  614. o slave SMPTE 
  615. o time format milliseconds 
  616. o time format MMTIME 
  617. o speed format percentage 
  618. o speed format fps 
  619. o video off 
  620. o video on 
  621.  
  622. Select the following word for an example of how to use the SET command. 
  623.  
  624. Example: 
  625.  
  626.  
  627. ΓòÉΓòÉΓòÉ <hidden> audio items ΓòÉΓòÉΓòÉ
  628.  
  629. Sets the audio attributes of the device context specified by items. 
  630.  
  631. all 
  632.     Apply to both or all of the channels (default). 
  633. left 
  634.     Apply to left channel. 
  635. right 
  636.     Apply to right channel. 
  637. volume percentage 
  638.     Set the device/mixer channel volume level. 
  639. on 
  640.     Enable audio output. 
  641. off 
  642.     Disable audio output. 
  643. over milliseconds 
  644.  
  645.     Apply the change over the specified time period (fade). 
  646.  
  647.  
  648. ΓòÉΓòÉΓòÉ <hidden> door closed ΓòÉΓòÉΓòÉ
  649.  
  650. Retracts the tray and closes the door, if possible. 
  651.  
  652.  
  653. ΓòÉΓòÉΓòÉ <hidden> door open ΓòÉΓòÉΓòÉ
  654.  
  655. Opens the door and ejects the tray, if possible. 
  656.  
  657.  
  658. ΓòÉΓòÉΓòÉ <hidden> door locked ΓòÉΓòÉΓòÉ
  659.  
  660. Locks the media cover on the device (if any).  This disables manual ejection of 
  661. the media from the device. 
  662.  
  663.  
  664. ΓòÉΓòÉΓòÉ <hidden> door unlocked ΓòÉΓòÉΓòÉ
  665.  
  666. Unlocks the media cover on the device (if any).  This enables manual ejection 
  667. of the media from the device. 
  668.  
  669.  
  670. ΓòÉΓòÉΓòÉ <hidden> master MIDI ΓòÉΓòÉΓòÉ
  671.  
  672. Sets the MIDI sequencer as the synchronization source.  Synchronization data is 
  673. sent in MIDI format.  The IBM sequencer does not support this option. 
  674.  
  675.  
  676. ΓòÉΓòÉΓòÉ <hidden> master none ΓòÉΓòÉΓòÉ
  677.  
  678. Inhibits the sequencer from sending synchronization data. The IBM sequencer 
  679. does not support this option. 
  680.  
  681.  
  682. ΓòÉΓòÉΓòÉ <hidden> master SMPTE ΓòÉΓòÉΓòÉ
  683.  
  684. Sets the MIDI sequencer as the synchronization source. Synchronization data is 
  685. sent in SMPTE format.  The IBM sequencer does not support this option. 
  686.  
  687.  
  688. ΓòÉΓòÉΓòÉ <hidden> slave file ΓòÉΓòÉΓòÉ
  689.  
  690. Sets the MIDI sequencer to use file data as the synchronization source.  This 
  691. is the default. 
  692.  
  693.  
  694. ΓòÉΓòÉΓòÉ <hidden> slave MIDI ΓòÉΓòÉΓòÉ
  695.  
  696. Sets the MIDI sequencer to use incoming data, with the MIDI file for the 
  697. synchronization source.  The sequencer recognizes synchronization data with the 
  698. MIDI format.  The IBM sequencer does not support this option. 
  699.  
  700.  
  701. ΓòÉΓòÉΓòÉ <hidden> slave none ΓòÉΓòÉΓòÉ
  702.  
  703. Sets the MIDI sequencer to ignore synchronization data. 
  704.  
  705.  
  706. ΓòÉΓòÉΓòÉ <hidden> slave SMPTE ΓòÉΓòÉΓòÉ
  707.  
  708. Sets the MIDI sequencer to use incoming MIDI data for the synchronization 
  709. source.  The sequencer recognizes synchronization data with the SMPTE format. 
  710. The IBM sequencer does not support this option. 
  711.  
  712.  
  713. ΓòÉΓòÉΓòÉ <hidden> timed format milliseconds ΓòÉΓòÉΓòÉ
  714.  
  715. Sets the time format, to milliseconds.  You can abbreviate milliseconds as ms. 
  716.  
  717.  
  718. ΓòÉΓòÉΓòÉ <hidden> timed format MMTIME ΓòÉΓòÉΓòÉ
  719.  
  720. Sets the time format, to MMTIME.  There are 3000 MMTIME units per second. 
  721.  
  722.  
  723. ΓòÉΓòÉΓòÉ <hidden> speed format percentage ΓòÉΓòÉΓòÉ
  724.  
  725. Set the speed format, to percentage. 
  726.  
  727.  
  728. ΓòÉΓòÉΓòÉ <hidden> speed format fps ΓòÉΓòÉΓòÉ
  729.  
  730. Set the speed format, to frames-per-second. 
  731.  
  732.  
  733. ΓòÉΓòÉΓòÉ <hidden> video off ΓòÉΓòÉΓòÉ
  734.  
  735. Disables video output. 
  736.  
  737.  
  738. ΓòÉΓòÉΓòÉ <hidden> video on ΓòÉΓòÉΓòÉ
  739.  
  740. Enables video output. 
  741.  
  742.  
  743. ΓòÉΓòÉΓòÉ <hidden> STATUS ΓòÉΓòÉΓòÉ
  744.  
  745. STATUS object items Obtains status information for the device. 
  746.  
  747. The following items modify the basic command: 
  748.  
  749. o Keywords common to all devices: 
  750.  
  751.    - length 
  752.    - mode 
  753.    - position 
  754.    - ready 
  755.    - time format 
  756.    - volume 
  757.  
  758. o Device-specific keywords: 
  759.  
  760.    - current track 
  761.    - length track number 
  762.    - number of tracks 
  763.    - position in track 
  764.    - position track number 
  765.    - speed format 
  766.  
  767. Select the following word for an example of how to use the STATUS command. 
  768.  
  769. Example: 
  770.  
  771.  
  772. ΓòÉΓòÉΓòÉ <hidden> current track ΓòÉΓòÉΓòÉ
  773.  
  774. Returns the current track. 
  775.  
  776.  
  777. ΓòÉΓòÉΓòÉ <hidden> length ΓòÉΓòÉΓòÉ
  778.  
  779. Returns the total length of the segment. 
  780.  
  781.  
  782. ΓòÉΓòÉΓòÉ <hidden> length track number ΓòÉΓòÉΓòÉ
  783.  
  784. Returns the length of the track specified by number. 
  785.  
  786.  
  787. ΓòÉΓòÉΓòÉ <hidden> mode ΓòÉΓòÉΓòÉ
  788.  
  789. Returns the current mode of the device:  not ready, stopped, playing, seeking, 
  790. recording, paused, or other. 
  791.  
  792.  
  793. ΓòÉΓòÉΓòÉ <hidden> number of tracks ΓòÉΓòÉΓòÉ
  794.  
  795. Returns the number of tracks on the media. 
  796.  
  797.  
  798. ΓòÉΓòÉΓòÉ <hidden> position ΓòÉΓòÉΓòÉ
  799.  
  800. Returns the current position. 
  801.  
  802.  
  803. ΓòÉΓòÉΓòÉ <hidden> position track number ΓòÉΓòÉΓòÉ
  804.  
  805. Returns the position of the start of the track specified by number. 
  806.  
  807.  
  808. ΓòÉΓòÉΓòÉ <hidden> position in track ΓòÉΓòÉΓòÉ
  809.  
  810. Returns the current position relative to the beginning of the track. 
  811.  
  812.  
  813. ΓòÉΓòÉΓòÉ <hidden> ready ΓòÉΓòÉΓòÉ
  814.  
  815. Returns true if the device is ready. 
  816.  
  817.  
  818. ΓòÉΓòÉΓòÉ <hidden> time format ΓòÉΓòÉΓòÉ
  819.  
  820. Returns the time format. 
  821.  
  822.  
  823. ΓòÉΓòÉΓòÉ <hidden> speed format ΓòÉΓòÉΓòÉ
  824.  
  825. Returns the speed format. 
  826.  
  827.  
  828. ΓòÉΓòÉΓòÉ <hidden> volume ΓòÉΓòÉΓòÉ
  829.  
  830. Returns the current volume setting.  The volume is returned as a string in the 
  831. format left:right where left and right are percentages of the maximum 
  832. achievable effect for the left and right channels respectively.  Leading zeros 
  833. are suppressed for the volume level in each channel. 
  834.  
  835.  
  836. ΓòÉΓòÉΓòÉ <hidden> STOP ΓòÉΓòÉΓòÉ
  837.  
  838. STOP object       Stops the device. 
  839.  
  840. Select the following word for an example of how to use the STOP command. 
  841.  
  842. Example: 
  843.  
  844.  
  845. ΓòÉΓòÉΓòÉ <hidden> String Command Examples ΓòÉΓòÉΓòÉ
  846.  
  847. The following string command example is used to play a digital audio file. 
  848.  
  849. open waveaudio alias w shareable wait
  850. load w sound.wav wait
  851. set w time format ms wait
  852. setpositionadvise w on every 500 wait
  853. play
  854. seek w to 0 wait
  855. play
  856. close w wait
  857.  
  858. The following string command example is used to play a CD. 
  859.  
  860. open cdaudio alias c shareable wait
  861. set w time format ms wait
  862. setpositionadvise w on every 500 wait
  863. play
  864. stop w wait
  865. close w wait
  866.  
  867.  
  868. ΓòÉΓòÉΓòÉ <hidden> String Command Examples ΓòÉΓòÉΓòÉ
  869.  
  870. This example shows opening a CD player and playing the entire CD.  The status 
  871. commands let the application know if a CD is present and the drive is ready. 
  872. The SET command will set the time base to milliseconds for all future commands. 
  873.  
  874. open cdaudio01 alias cdaud1 shareable wait
  875. status cdaud1 media present wait
  876. status cdaud1 mode wait
  877. set cdaud1 time format milliseconds wait
  878. seek cdaud1 to start wait
  879. play cdaud1
  880. close cdaud1 wait
  881.  
  882.  
  883. ΓòÉΓòÉΓòÉ 3. Using MCI String Commands in a REXX File ΓòÉΓòÉΓòÉ
  884.  
  885. If you are a REXX-knowledgeable user, you can use Media Control Interface 
  886. string commands in a REXX file (with some limitations) rather than having to 
  887. use the programming APIs.  For example, you can: 
  888.  
  889. o Start a REXX command file using the MCI string interface commands. 
  890. o End a REXX command file with the MCI string interface commands. 
  891. o Send a MCI command string. 
  892. o Get a MCI error string. 
  893. o Get the device ID associated with an MCI device alias. 
  894.  
  895. REXX is not designed to be a fully-functional multimedia scripting language. 
  896. Support is provided for fundamental multimedia capabilities only.  See the REXX 
  897. Command File Limitations section for further information. 
  898.  
  899. Note:   For more information about programming in REXX, see the REXX 
  900.         Information online manual, which, if it was selected during 
  901.         installation, is located in the Information folder. 
  902.  
  903.  
  904. ΓòÉΓòÉΓòÉ 3.1. REXX Command File Limitations ΓòÉΓòÉΓòÉ
  905.  
  906. In order to manage MCI resources and devices using REXX command files 
  907. effectively, you should first note the following: 
  908.  
  909. o Since a REXX command file can not receive notification when it is losing or 
  910.   gaining access to an MCI device, it should open the devices exclusively. 
  911.   Commands should be sent with the wait keyword.  If the device is opened with 
  912.   the shareable flag, the command file must be careful to do ACQUIRE EXCLUSIVE 
  913.   and RELEASE RETURN RESOURCE commands around its other device commands; 
  914.   otherwise, subsequent commands may fail with an error indicating an inactive 
  915.   instance. 
  916.  
  917.   It is possible that the ACQUIRE EXCLUSIVE command will fail if the device is 
  918.   in use by another program; the command file should handle this situation. 
  919.   Exclusive opens may also fail if the device is in use by another program. 
  920.  
  921. o A REXX command file should not hold the device open exclusive for long 
  922.   periods of time. 
  923.  
  924. o REXX is typically running in a non-PM session, even if it is run from a 
  925.   windowed command prompt.  Therefore, MCI commands that require PM will fail. 
  926.  
  927.   Digital video, image devices, or clipboard cut-and-paste commands will not 
  928.   function properly in this environment.  Use PMREXX to execute a REXX command 
  929.   file that uses digital video. 
  930.  
  931. o REXX does not receive PM messages; notify commands will return an error. 
  932.   REXX supports synchronous commands with the wait flag, and asynchronous 
  933.   commands without the wait flag.  However, the command file is not notified 
  934.   when the operation completes.  It is possible to poll the device in some 
  935.   situations by doing a status mode to determine when the file has finished 
  936.   playing. 
  937.  
  938. o The MCI string interface is capable of doing implicit opens when a command is 
  939.   issued on a media object without opening the device.  For example, `play 
  940.   clock.wav wait'. will implicitly open and close the waveaudio device. 
  941.   However, these opens are shareable, and could cause you to lose access of the 
  942.   device. 
  943.  
  944.  
  945. ΓòÉΓòÉΓòÉ 3.2. mciRxInit ΓòÉΓòÉΓòÉ
  946.  
  947. Function:  mciRxInit 
  948.  
  949. Syntax:  call mciRxInit 
  950.  
  951. Purpose:  Initialize a REXX command file so that MCI string interface commands 
  952. may be used. 
  953.  
  954. Parameters:  None. 
  955.  
  956. Returns:  Returns type of failure if a failure occurs, otherwise 0 for 
  957. successful. 
  958.  
  959. Remarks:  This function must be called in order to have the other MCI REXX API 
  960. registered properly.  See the REXX Program Example section for a programming 
  961. example. 
  962.  
  963. This function is registered in REXX by the following REXX code: 
  964.  
  965.  
  966.    Call RXFUNCADD "mciRxInit", "MCIAPI", "mciRxInit"
  967.    Call mciRxInit
  968.  
  969.  
  970. ΓòÉΓòÉΓòÉ 3.3. mciRxExit ΓòÉΓòÉΓòÉ
  971.  
  972. Function:  mciRxExit 
  973.  
  974. Syntax:  call mciRxExit 
  975.  
  976. Purpose:  Terminate a REXX command file that contains MCI string commands. 
  977.  
  978. Parameters:  None. 
  979.  
  980. Returns:  Returns type of failure if a failure occurs, otherwise 0 for 
  981. successful. 
  982.  
  983. Remarks:  This function must be called so that allocated resources can be 
  984. returned to the system. See the REXX Program Example section for an 
  985. illustration of this command. 
  986.  
  987.  
  988. ΓòÉΓòÉΓòÉ 3.4. mciRxGetDeviceID ΓòÉΓòÉΓòÉ
  989.  
  990. Function:  mciRxGetDeviceID 
  991.  
  992. Syntax:  DevID = mciRxGetDeviceID(alias) 
  993.  
  994. Purpose:  Get the device ID associated with an MCI device alias. 
  995.  
  996. Parameters: 
  997.  
  998. alias  - input The device alias that was specified on a previous OPEN command. 
  999.  
  1000. Returns :  DevID - A device ID number. This is the same value that is returned 
  1001. from a successful OPEN command. 
  1002.  
  1003. See the REXX Program Example section for an illustration of this command. 
  1004.  
  1005.  
  1006. ΓòÉΓòÉΓòÉ 3.5. mciRxGetErrorString ΓòÉΓòÉΓòÉ
  1007.  
  1008. Function:  mciRxGetErrorString 
  1009.  
  1010. Syntax:  frc = mciRxGetErrorString (rc, 'errstr') 
  1011.  
  1012. Purpose:  Get an MCI error string. 
  1013.  
  1014. Parameters: 
  1015.  
  1016. rc - input Return code from an MCI REXX function. 
  1017.  
  1018. errstr - output REXX variable name in which to store the returned error string. 
  1019.           The variable name must be enclosed in quotes. 
  1020.  
  1021. Returns:  frc - return code. This is 0 if the function completed successfully. 
  1022. errstr contains a string describing the return code that was supplied as a 
  1023. parameter. 
  1024.  
  1025. Remarks:  See the REXX Program Example section for an illustration of this 
  1026. command. 
  1027.  
  1028.  
  1029. ΓòÉΓòÉΓòÉ 3.6. mciRxSendString ΓòÉΓòÉΓòÉ
  1030.  
  1031. Function:  mciRxSendString 
  1032.  
  1033. Syntax:  rc = mciRxSendString (cmdstr, 'retstrvar', reserved1, reserved2)
  1034.  
  1035. Purpose:  Send a MCI command string. 
  1036.  
  1037. Parameters: 
  1038.  
  1039. cmdstr - input MCI command string. 
  1040.  
  1041. retstrvar - output REXX variable name to store the return string from the MCI 
  1042.           command.  This variable should be enclosed in quotes. 
  1043.  
  1044. reserved1  - input Reserved field should be set to 0. 
  1045.  
  1046. reserved2 - input Reserved field should be set to 0. 
  1047.  
  1048. Returns:  rc - return code. This value is 0 if the command was successful, 
  1049. otherwise it is an MMPM/2 error code. The retstrvar variable specified may 
  1050. contain string information, depending upon the command. 
  1051.  
  1052. Remarks:  See the REXX Program Example section for an illustration of this 
  1053. command. 
  1054.  
  1055.  
  1056. ΓòÉΓòÉΓòÉ 3.7. REXX Program Example ΓòÉΓòÉΓòÉ
  1057.  
  1058. When MMPM/2 is installed, two REXX command files are placed in the \MMOS2 
  1059. directory: 
  1060.  
  1061. o PLAY.CMD - Allows you to play a multimedia file or device 
  1062. o RECORD.CMD - Allows you to record digital audio data from a microphone to a 
  1063.   specified filename. 
  1064.  
  1065. The following OS/2 REXX program illustrates how to use the multimedia REXX and 
  1066. Media Control Interface commands to open, query, set, and manipulate a 
  1067. multimedia file: 
  1068.  
  1069. /* Load and initialize Multimedia REXX support */
  1070. call RXFUNCADD 'mciRxInit','MCIAPI','mciRxInit'
  1071. call mciRxInit
  1072.  
  1073. /* Open the default digital audio device for exclusive use */
  1074. rc = mciRxSendString('open waveaudio alias wave wait', 'RetStr', '0', '0')
  1075.  
  1076. /* Check for an error, call a function to return an error string */
  1077. if rc <> 0 then
  1078. do
  1079.    MacRC = mciRxGetErrorString(rc, 'ErrStVar')
  1080.    say 'rc =' rc ', ErrStVar =' ErrStVar
  1081. end
  1082.  
  1083. /* Load a digital audio file */
  1084. rc = mciRxSendString('load wave sample.wav wait', 'RetStr', '0', '0')
  1085.  
  1086. /* Obtain the ID for the device context that was just opened */
  1087. DevID = mciRxGetDeviceID(wave)
  1088.  
  1089. say 'DevID =' DevID
  1090.  
  1091. /* Set the time format to milliseconds */
  1092. call mciRxSendString 'set wave time format ms', 'RetStr', '0', '0'
  1093.  
  1094. /* Determine whether the microphone connection enable */
  1095. call mciRxSendString 'connector wave query type microphone wait',
  1096.                      ,'RetStr', '0', '0'
  1097.  
  1098. say 'connector query microphone:  RetStr =' RetStr
  1099.  
  1100. /* Query the length of the opened file, value is in millseconds */
  1101. call mciRxSendString 'status wave length wait', 'RetStr', '0', '0'
  1102.  
  1103. say 'status wave length:  RetStr =' RetStr
  1104.  
  1105. /* Play the multimedia file, wait for completion */
  1106. call mciRxSendString 'play wave wait', 'RetStr', '0', '0'
  1107.  
  1108. /* "Rewind" to the beginning of the file */
  1109. call mciRxSendString 'seek wave to start wait', 'RetStr', '0', '0'
  1110.  
  1111. /* Close the device context */
  1112. call mciRxSendString 'close wave', 'RetStr', '0', '0'
  1113.  
  1114. /* Ensure proper termination of Multimedia REXX */
  1115. call mciRxExit
  1116.  
  1117. exit(0)
  1118.  
  1119.  
  1120. ΓòÉΓòÉΓòÉ 3.7.1. PLAY.CMD ΓòÉΓòÉΓòÉ
  1121.  
  1122. Syntax: 
  1123.  
  1124.   PLAY FILE=filename|DEV=device [TIMEFMT=timefmt] [FROM=from] [TO=to]
  1125.  
  1126. Purpose:  Play a multimedia file or device. 
  1127.  
  1128. Parameters: 
  1129.  
  1130. FILE=filename Name of the file to be played back. 
  1131.  
  1132. DEV=device Name of the desired device to be used for playback. 
  1133.  
  1134. TIMEFMT=timefmt The time format to be used, usually associated with the FROM= 
  1135.           and TO= parameters. 
  1136.  
  1137. FROM=from The starting position within the file or device to begin playback. 
  1138.           This value is in MMTIME units, unless TIMEFMT= was specified. 
  1139.  
  1140. TO=to     The position within the file or device to stop playback.  This value 
  1141.           is in MMTIME units, unless TIMEFMT= was specified. 
  1142.  
  1143. Remarks:  Either FILE=filename or DEV=device must be specified (both can be 
  1144. provided, to play a file on a specific device). 
  1145.  
  1146.  
  1147. ΓòÉΓòÉΓòÉ 3.7.2. RECORD.CMD ΓòÉΓòÉΓòÉ
  1148.  
  1149. Syntax: RECORD filename 
  1150.  
  1151. Purpose:  Record digital audio from the microphone of the default waveaudio 
  1152. device to the specified filename. 
  1153.  
  1154. Parameters: 
  1155.  
  1156. filename  The name of the file to contain the recorded digital audio data. 
  1157.  
  1158.  
  1159. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  1160.  
  1161. Keywords are command-specific.  Reference the Commands section for details 
  1162. about keywords for a specific command. 
  1163.  
  1164.  
  1165. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  1166.  
  1167. The keyword WAIT can be used on any command.  It instructs MMPM/2 to wait until 
  1168. the command is completed before returning.