home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxgpib.zip / RXGPIB.INF (.txt) < prev    next >
OS/2 Help File  |  1999-04-21  |  11KB  |  316 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. rxGPIB is a REXX DLL that allows access to the National Instruments AT-GPIB 
  5. boards. This particular board has OS/2 drivers available, but up until now, the 
  6. functions were only available through C programs. rxGPIB now enables REXX to 
  7. access them as well. 
  8.  
  9. Please note that rxGPIB was written for prototyping purposes. It will not set 
  10. any speed records for data acquisitions, but for many lab instrument 
  11. applications it is more than adequate. 
  12.  
  13. Currently, only a subset of the IEEE488 functions are included in rxGPIB. They 
  14. are the only functions I currently need. Depending on demand, I may add more 
  15. functions in the future. You are free to use rxGPIB, and if you do, let me know 
  16. if you would like to see additional functions added. 
  17.  
  18. To run rxGPIB, you need the National Instruments AT-GPIB card and OS/2 drivers. 
  19. You can find National Instuments at: 
  20.  
  21. http://www.natinst.com 
  22.  
  23. The drivers, library and sample C code can be found at: 
  24.  
  25. ftp://ftp.natinst.com/support/gpib/os2/at-gpib/atos2v22.zip 
  26.  
  27. Also necessary are the NI-488.2M Software Reference Manual for OS/2, part 
  28. number 320610B-01 and NI-488.2M Function Reference Manual for OS/2, part number 
  29. 320611-01. Both of the manuals can be downloaded from the National Instruments 
  30. web site at: 
  31.  
  32. http://www.natinst.com/support/techdocs.htm 
  33.  
  34. For a description on how to use rxGPIB see rxGPIB Function Description 
  35.  
  36. For individual function description see each section below. 
  37.  
  38. IBCLR | IBFIND | IBLOC | IBRD | IBRDF | IBWRT | IBWRTF 
  39.  
  40.  
  41. ΓòÉΓòÉΓòÉ 2. rxGPIB Function Description ΓòÉΓòÉΓòÉ
  42.  
  43. rxGPIB is essentially a wrapper DLL to allow REXX to access the IEEE488 
  44. functions. rxGPIB closely follows the programming rules as outlined in the 
  45. National Instruments documents for the NI-488 function calls. 
  46.  
  47. Some differences are: 
  48.  
  49. Each IEEE488 function inside rxGPIB is preceded with an rx, so IBFIND will 
  50. become rxIBFIND. 
  51.  
  52. Each function inside rxGPIB will return the decimal values of ibsta and iberr 
  53. along with any additional data on one single line, i.e. reading a parameter 
  54. from an oscilloscope may return the following data: 
  55.  
  56. 8448 0 TA:PAVA MAX,0E-3 V,OK 
  57.  
  58. The value 8448 (2100hex) is ibsta indicating END or EOS detected and I/O 
  59. completed. The next value is iberr and it is set to zero since ibsta did not 
  60. indicate any errors. The remaining string is the data returned from the 
  61. instrument. 
  62.  
  63. The value of iberr as returned by rxGPIB will always be zero, unless bit 15 of 
  64. ibsta is set. 
  65.  
  66. The buffer sizes for reading and writing operations are set to 512 bytes each. 
  67.  
  68. The length of the device name for rxIBFIND is limited to 20 characters or less. 
  69.  
  70. To find out the version level of rxGPIB, simply add the line rc = 
  71. RXDLLVersion() to your program. The return value will be in the form rxGPIB 
  72. vX.YY. 
  73.  
  74. Consult the NI-488.2M Software Reference Manual for OS/2, part number 
  75. 320610B-01 for explanation of ibsta and iberr. 
  76.  
  77. See the included REXX CMD file for examples on how to use these IEEE488 
  78. functions. 
  79.  
  80.  
  81.    GPLoadFuncs
  82.  
  83.    GPDropFuncs
  84.  
  85.    rxIBCLR
  86.  
  87.    rxIBFIND
  88.  
  89.    rxIBLOC
  90.  
  91.    rxIBRD
  92.  
  93.    rxIBRDF
  94.  
  95.    rxIBWRT
  96.  
  97.    rxIBWRTF
  98.  
  99.  
  100. ΓòÉΓòÉΓòÉ 2.1. GPLoadFuncs ΓòÉΓòÉΓòÉ
  101.  
  102. This function loads rxGPIB.DLL to be used within your REXX program. A REXX 
  103. program using rxGPIB must contain the following two lines to access other 
  104. functions inside rxGPIB: 
  105.  
  106.    CALL RXFuncAdd 'GPLoadFuncs', 'RXGPIB', 'GPLoadFuncs'
  107.    CALL GPLoadFuncs
  108.  
  109. Standard REXX errors are returned for this function, for example: Error 43 - 
  110. Routine not found if rxGPIB.DLL can't be found. rxGPIB.DLL must be in the 
  111. current directory or in a directory where the LIBPATH statement points to. 
  112.  
  113.  
  114. ΓòÉΓòÉΓòÉ 2.2. GPDropFuncs ΓòÉΓòÉΓòÉ
  115.  
  116. This function unloads rxGPIB.DLL from memory. A REXX program using rxGPIB must 
  117. contain the following line to unload rxGPIB: 
  118.  
  119.    CALL GPDropFuncs
  120.  
  121.  
  122. ΓòÉΓòÉΓòÉ 2.3. rxIBCLR ΓòÉΓòÉΓòÉ
  123.  
  124. Clears a specific device. 
  125.  
  126. The command is used as follows: 
  127.  
  128.    rc = rxIBCLR(deviceunit)
  129.  
  130. The deviceunit is the integer value returned by the function rxIBFIND. 
  131.  
  132. The return value rc consists of two integer values separated by a space: 
  133.  
  134.   ibsta iberr
  135.  
  136. ibsta is the status word value. 
  137.  
  138. iberr indicates the possible error code if bit 15 of ibsta is set. 
  139.  
  140.  
  141. ΓòÉΓòÉΓòÉ 2.4. rxIBFIND ΓòÉΓòÉΓòÉ
  142.  
  143. Open and initialize a GPIB board or a user-defined device. 
  144.  
  145. The command is used as follows: 
  146.  
  147.    rc = rxIBFIND(device)
  148.  
  149. The device is the GPIB device address. If an instrument is setup at address 4, 
  150. device would be the string DEV4 
  151.  
  152. The return value rc consists of three integer values separated by spaces: 
  153.  
  154.   ibsta iberr deviceunit
  155.  
  156. ibsta is the status word value. 
  157.  
  158. iberr indicates the possible error code if bit 15 of ibsta is set. 
  159.  
  160. deviceunit is an integer value specific to the instument and must be used in 
  161. all other functions when addressing that specific instument. 
  162.  
  163.  
  164. ΓòÉΓòÉΓòÉ 2.5. rxIBLOC ΓòÉΓòÉΓòÉ
  165.  
  166. Go to Local. 
  167.  
  168. The command is used as follows: 
  169.  
  170.    rc = rxIBLOC(deviceunit)
  171.  
  172. The deviceunit is the integer value returned by the function rxIBFIND. 
  173.  
  174. The return value rc consists of two integer values separated by a space: 
  175.  
  176.   ibsta iberr
  177.  
  178. ibsta is the status word value. 
  179.  
  180. iberr indicates the possible error code if bit 15 of ibsta is set. 
  181.  
  182.  
  183. ΓòÉΓòÉΓòÉ 2.6. rxIBRD ΓòÉΓòÉΓòÉ
  184.  
  185. Read data from a device into a user buffer. 
  186.  
  187. The command is used as follows: 
  188.  
  189.    rc = rxIBRD(deviceunit, count)
  190.  
  191. The deviceunit is the integer value returned by the function rxIBFIND. 
  192.  
  193. The count is the number of characters to read. If it's unknown, then make the 
  194. value large enough to fit the data. Reading will be terminated whenever an END 
  195. or EOS is detected. 
  196.  
  197. The return value rc consists of two integer values and the data string read 
  198. separated by spaces: 
  199.  
  200.   ibsta iberr datastring
  201.  
  202. ibsta is the status word value. 
  203.  
  204. iberr indicates the possible error code if bit 15 of ibsta is set. 
  205.  
  206. datastring contains the data as reported by the instrument. No carriage return 
  207. follows the datastring. 
  208.  
  209.  
  210. ΓòÉΓòÉΓòÉ 2.7. rxIBRDF ΓòÉΓòÉΓòÉ
  211.  
  212. Read data from a device into a file. 
  213.  
  214. The command is used as follows: 
  215.  
  216.    rc = rxIBRDF(deviceunit, filename)
  217.  
  218. The deviceunit is the integer value returned by the function rxIBFIND. 
  219.  
  220. The filename is the name of the disk file to store the data i.e. 
  221. C:\DATA\DATA.TXT 
  222.  
  223. The return value rc consists of three integer values separated by spaces: 
  224.  
  225.   ibsta iberr count
  226.  
  227. ibsta is the status word value. 
  228.  
  229. iberr indicates the possible error code if bit 15 of ibsta is set. 
  230.  
  231. count is the number of characters that were stored in the file. 
  232.  
  233.  
  234. ΓòÉΓòÉΓòÉ 2.8. rxIBWRT ΓòÉΓòÉΓòÉ
  235.  
  236. Write data to a device from a user buffer. 
  237.  
  238. The command is used as follows: 
  239.  
  240.    rc = rxIBWRT(deviceunit, datastring, length)
  241.  
  242. The deviceunit is the integer value returned by the function rxIBFIND. 
  243.  
  244. The datastring is the IEEE command string as required to control the 
  245. instrument. 
  246.  
  247. The length is the length of the datastring variable. 
  248.  
  249. The return value rc consists of two integer values separated by a space: 
  250.  
  251.   ibsta iberr
  252.  
  253. ibsta is the status word value. 
  254.  
  255. iberr indicates the possible error code if bit 15 of ibsta is set. 
  256.  
  257.  
  258. ΓòÉΓòÉΓòÉ 2.9. rxIBWRTF ΓòÉΓòÉΓòÉ
  259.  
  260. Write data to a device from a file. 
  261.  
  262. The command is used as follows: 
  263.  
  264.    rc = rxIBWRTF(deviceunit, filename)
  265.  
  266. The deviceunit is the integer value returned by the function rxIBFIND. 
  267.  
  268. The filename is the name of the disk file to write to the instrument i.e. 
  269. C:\DATA\DATA.SET 
  270.  
  271. The return value rc consists of two integer values separated by a space: 
  272.  
  273.   ibsta iberr
  274.  
  275. ibsta is the status word value. 
  276.  
  277. iberr indicates the possible error code if bit 15 of ibsta is set. 
  278.  
  279.  
  280. ΓòÉΓòÉΓòÉ 3. The Legal Stuff ΓòÉΓòÉΓòÉ
  281.  
  282. rxGPIB is freeware but the source code is copyrighted by A. Schwarz. 
  283.  
  284. This program may be distributed electronically as long as all files are kept 
  285. together. 
  286.  
  287. DISCLAIMER 
  288.  
  289. The author of rxGPIB is in no way responsible for any damage this program may 
  290. cause to computer equipment or instruments. No warranty is implied or given for 
  291. rxGPIB. Use rxGPIB at your own risk. 
  292.  
  293. Any trademarks mentioned in this document belong to their respective owners and 
  294. the author of rxGPIB is not connected in any way to these products nor does he 
  295. endorse any of the products mentioned. 
  296.  
  297.  
  298. ΓòÉΓòÉΓòÉ 4. Contact ΓòÉΓòÉΓòÉ
  299.  
  300. For rxGPIB support, you can contact me directly via e-mail. 
  301.  
  302. My e-mail address: 
  303.  
  304.   ASchw@worldnet.att.net 
  305.  
  306. Visit my home page, "The Warped Code Cellar" at 
  307.  
  308.   http://home.att.net/~ASchw 
  309.  
  310. for other information and applications for OS/2 like rxPortIO, a REXX-DLL to 
  311. access port I/O, UPS Monitor for APC brand uninterruptible power supplies and 
  312. HOUSE/2, a home automation program for X-10 devices. 
  313.  
  314. This program is also available at the following internet site: 
  315.  
  316.   http://hobbes.nmsu.edu