home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / RXNETB.ZIP / RXNETB.INF (.txt) < prev    next >
OS/2 Help File  |  1992-10-23  |  12KB  |  578 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. (C) Copyright IBM Corp. 1992 ΓòÉΓòÉΓòÉ
  3.  
  4.  
  5. ΓòÉΓòÉΓòÉ 2. OS/2 REXX NETBIOS Users Guide ΓòÉΓòÉΓòÉ
  6.  
  7. This document is intended for application developers who wish to use NETBIOS 
  8. services from OS/2 REXX execs. The NETBIOS services are available in REXX as an 
  9. external function package, and are loaded only when used. 
  10.  
  11.  
  12. ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ
  13.  
  14.  
  15. ΓòÉΓòÉΓòÉ 3.1. Rexx Netbios Installation ΓòÉΓòÉΓòÉ
  16.  
  17. Copy REXXNETB.DLL to a LIBPATH directory 
  18.  
  19. Add this following line to all NETBIOS execs to insure the function is 
  20. registered 
  21.  
  22. if rxfuncquery('netbios') then call rxfuncadd 'netbios','REXXNETB','NETBIOSSRV'
  23.  
  24.  
  25. ΓòÉΓòÉΓòÉ 4. REXX Netbios Programming Interface ΓòÉΓòÉΓòÉ
  26.  
  27.  
  28. ΓòÉΓòÉΓòÉ 4.1. Function parameters and return values ΓòÉΓòÉΓòÉ
  29.  
  30. The NETBIOS function package provides a single function name to be used with a 
  31. set of parameters. The function name is the first string you used when you 
  32. RXFUNDADDed the the function, and defaults to NETBIOS. 
  33.  
  34. The general format of the NETBIOS function invocation is: 
  35.  
  36. NETBIOS( function-string [ parameters ] )
  37.  
  38. or
  39.  
  40. call NETBIOS function-string [ parameters ]
  41.  
  42. The function strings and parameters and returned data are listed below in 
  43. alphabetical order. 
  44.  
  45.  
  46. ΓòÉΓòÉΓòÉ 4.1.1. AddName ΓòÉΓòÉΓòÉ
  47.  
  48. NETBIOS( 'AddName', adapter, name)
  49.  
  50. Adapter is '0' or '1' 
  51.  
  52. name is a 16 byte Netbios name string 
  53.  
  54. returns a string of format NN YY 
  55.  
  56. nn        return code 
  57.  
  58. yy        netbios name number is nn = 0 
  59.  
  60.  
  61. ΓòÉΓòÉΓòÉ 4.1.2. AddGroupName ΓòÉΓòÉΓòÉ
  62.  
  63. NETBIOS( 'AddGroupName', adapter, name)
  64.  
  65. Adapter is '0' or '1' 
  66.  
  67. name is a 16 byte Netbios Group name string 
  68.  
  69. returns a string of format NN YY 
  70.  
  71. nn        return code 
  72.  
  73. yy        netbios name number if nn = 0 
  74.  
  75.  
  76. ΓòÉΓòÉΓòÉ 4.1.3. Call ΓòÉΓòÉΓòÉ
  77.  
  78. NETBIOS( 'Call', adapter, Local_name,Remote_name, send_timeout,receive_timeout)
  79.  
  80. Call and establish a session with remote_name from local_name 
  81.  
  82. Adapter is '0' or '1' 
  83.  
  84. Local_name is a 16 byte Netbios Group name string 
  85.  
  86. Remote_name is a 16 byte Netbios Group name string of the station to call 
  87.  
  88. send_timeout, in milliseconds 
  89.  
  90. receive_timeout, in milliseconds 
  91.  
  92. returns a string of format NN YY 
  93.  
  94. nn        return code 
  95.  
  96. yy        netbios session number if nn = 0 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 4.1.4. Chain_Send ΓòÉΓòÉΓòÉ
  100.  
  101. NETBIOS( 'Chain_Send', adapter, session,buffer1, buffer2)
  102.  
  103. Sends to buffers in a single transmission over a session, up to 128k can be 
  104. sent in a single transmission 
  105.  
  106. Adapter is '0' or '1' 
  107.  
  108. Session is the value second returned on Call or Listen 
  109.  
  110. buffer1 is the first buffer to send 
  111.  
  112. buffer2 is the second buffer to send 
  113.  
  114. returns the Netbios Return code 
  115.  
  116.  
  117. ΓòÉΓòÉΓòÉ 4.1.5. Chain_Send_NoAck ΓòÉΓòÉΓòÉ
  118.  
  119. NETBIOS( 'Chain_Send_NoAck', adapter, session,buffer1, buffer2)
  120.  
  121. Sends to buffers in a single transmission over a session, up to 128k can be 
  122. sent in a single transmission, without waiting for a data acknowledgement 
  123.  
  124. Adapter is '0' or '1' 
  125.  
  126. Session is the value second returned on Call or Listen 
  127.  
  128. buffer1 is the first buffer to send 
  129.  
  130. buffer2 is the second buffer to send 
  131.  
  132. returns the Netbios Return code 
  133.  
  134.  
  135. ΓòÉΓòÉΓòÉ 4.1.6. Close ΓòÉΓòÉΓòÉ
  136.  
  137. NETBIOS( 'Close' ,adapter)
  138.  
  139. returns all netbios resources to the system pool. 
  140.  
  141. Adapter is '0' or '1' 
  142.  
  143. returns the Netbios Reset return code 
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 4.1.7. Config ΓòÉΓòÉΓòÉ
  147.  
  148. NETBIOS( 'Config' ,adapter)
  149.  
  150. Returns the number of NETBIOS resources configured and available 
  151.  
  152. Adapter is '0' or '1' 
  153.  
  154. returns a string of format: Sessions Commands Names Asessions Acommands Anames 
  155.  
  156. Sessions  configured sessions (see CM Lan Services,NETBIOS) 
  157.  
  158. Commands  configured commands (see CM Lan Services,NETBIOS) 
  159.  
  160. Names     configured names (see CM Lan Services,NETBIOS) 
  161.  
  162. Asessions currently available sessions 
  163.  
  164. Acommands currently available commands 
  165.  
  166. Anames    currently available names 
  167.  
  168.  
  169. ΓòÉΓòÉΓòÉ 4.1.8. DeleteName ΓòÉΓòÉΓòÉ
  170.  
  171. NETBIOS( 'DeleteName',adapter,name)
  172.  
  173. deletes name from the netbios name table. 
  174.  
  175. Adapter is '0' or '1' 
  176.  
  177. name is the 16 byte netbios name to delete 
  178.  
  179. returns the netbios return code 
  180.  
  181.  
  182. ΓòÉΓòÉΓòÉ 4.1.9. FindName ΓòÉΓòÉΓòÉ
  183.  
  184. NETBIOS( 'FindName', adapter, name, stemname)
  185.  
  186. Adapter is '0' or '1' 
  187.  
  188. name is a 16 byte Netbios name string 
  189.  
  190. returns a string of format NN 
  191.  
  192. nn        netbios return code 
  193.  
  194. If nn is 0 then stemname. contains the following information 
  195.  
  196. stemname.0 Count of systems responding the Findname request, list starts at 
  197.           stemname.2 
  198.  
  199. stemname.1 either 'GroupName' or 'UniqueName' 
  200.  
  201. stemname.2-n (stemname.0 count)  a binary string that contains the data 
  202.           returned from the find name request. 
  203.  
  204.  
  205. ΓòÉΓòÉΓòÉ 4.1.10. Hangup ΓòÉΓòÉΓòÉ
  206.  
  207. NETBIOS( 'Hangup',adapter,session)
  208.  
  209. closes the session 
  210.  
  211. Adapter is '0' or '1' 
  212.  
  213. session is the value returned on a CALL or LISTEN 
  214.  
  215. returns the netbios return code 
  216.  
  217.  
  218. ΓòÉΓòÉΓòÉ 4.1.11. Listen ΓòÉΓòÉΓòÉ
  219.  
  220. NETBIOS( 'Listen', adapter, Local_name,Remote_name, send_timeout,receive_timeout)
  221.  
  222. Listens for a call to local_name from remote_name 
  223.  
  224. Adapter is '0' or '1' 
  225.  
  226. Local_name is a 16 byte Netbios Group name string 
  227.  
  228. Remote_name is a 16 byte Netbios Group name string of the station to listen for 
  229.  
  230. Note:  a name of '*' means anyone 
  231.  
  232. send_timeout, in milliseconds 
  233.  
  234. receive_timeout, in milliseconds 
  235.  
  236. returns a string of format NN YY [ NAME ] 
  237.  
  238. nn        return code 
  239.  
  240. yy        netbios session number if nn = 0 
  241.  
  242. NAME      If Remotename starts with '*' (anyone) then NAME is the Netbios name 
  243.           of the caller 
  244.  
  245.  
  246. ΓòÉΓòÉΓòÉ 4.1.12. Receive ΓòÉΓòÉΓòÉ
  247.  
  248. NETBIOS( 'Receive', adapter, session, size, stemname)
  249.  
  250. receives data from session partner 
  251.  
  252. Adapter is '0' or '1' 
  253.  
  254. session is the value retuned from CALL or LISTEN 
  255.  
  256. size is the maximum size to receive 
  257.  
  258. stemname, is the rexx stem variable to place the data into, and the data will 
  259. be placed in stemname.0 
  260.  
  261. Note:  The stem will be dropped prior to the receive being started 
  262.  
  263. returns the netbios return code 
  264.  
  265.  
  266. ΓòÉΓòÉΓòÉ 4.1.13. Receive_Any ΓòÉΓòÉΓòÉ
  267.  
  268. NETBIOS( 'Receive_Any', adapter, name_number, size, stemname)
  269.  
  270. receives data from ANY session partner 
  271.  
  272. Adapter is '0' or '1' 
  273.  
  274. session is the value retuned from ADDNAME 
  275.  
  276. size is the maximum size to receive 
  277.  
  278. stemname, is the rexx stem variable to place the data into, and the data will 
  279. be placed in stemname.0 
  280.  
  281. stemname.1 will contain the session number if rc=0 or 6 
  282.  
  283. Note:  The stem will be dropped prior to the receive being started 
  284.  
  285. returns the netbios return code 
  286.  
  287.  
  288. ΓòÉΓòÉΓòÉ 4.1.14. Receive_BroadcastDatagram ΓòÉΓòÉΓòÉ
  289.  
  290. NETBIOS( 'Receive_BroadcastDatagram', adapter, name_number, size, stemname)
  291.  
  292. receives a broadcast datagram to name_number from ANY station 
  293.  
  294. Adapter is '0' or '1' 
  295.  
  296. session is the value retuned from ADDNAME 
  297.  
  298. size is the maximum size to receive 
  299.  
  300. stemname, is the rexx stem variable to place the data into, and the data will 
  301. be placed in stemname.0 
  302.  
  303. stemname.1 will contain the remote station name if rc=0 or 6 
  304.  
  305. Note:  The stem will be dropped prior to the receive being started 
  306.  
  307. returns the netbios return code 
  308.  
  309.  
  310. ΓòÉΓòÉΓòÉ 4.1.15. Receive_Datagram ΓòÉΓòÉΓòÉ
  311.  
  312. NETBIOS( 'Receive_Datagram', adapter, name_number, size, stemname)
  313.  
  314. receives a datagram to name_number from ANY station 
  315.  
  316. Adapter is '0' or '1' 
  317.  
  318. session is the value retuned from ADDNAME 
  319.  
  320. size is the maximum size to receive 
  321.  
  322. stemname, is the rexx stem variable to place the data into, and the data will 
  323. be placed in stemname.0 
  324.  
  325. stemname.1 will contain the remote station name if rc=0 or 6 
  326.  
  327. Note:  The stem will be dropped prior to the receive being started 
  328.  
  329. returns the netbios return code 
  330.  
  331.  
  332. ΓòÉΓòÉΓòÉ 4.1.16. Reset ΓòÉΓòÉΓòÉ
  333.  
  334. NETBIOS( 'Reset', adapter, sessions, commands, names)
  335.  
  336. receives a datagram to name_number from ANY station 
  337.  
  338. Adapter is '0' or '1' 
  339.  
  340. Sessions is the number of sessions to allocate from the CM NETBIOS buffer pool. 
  341. (See CM, Lan Services,NETBIOS) 
  342.  
  343. Commands is the number of commands to allocate from the CM NETBIOS buffer pool. 
  344. (See CM, Lan Services,NETBIOS) 
  345.  
  346. Names is the number of names to allocate from the CM NETBIOS buffer pool. (See 
  347. CM, Lan Services,NETBIOS) 
  348.  
  349. returns the netbios return code, 56= requested resources not available. 
  350.  
  351. use of the 'Config' option will assist in avoiding this return code. 
  352.  
  353.  
  354. ΓòÉΓòÉΓòÉ 4.1.17. Send ΓòÉΓòÉΓòÉ
  355.  
  356. NETBIOS( 'Send', adapter, session, data)
  357.  
  358. Sends data to a session partner 
  359.  
  360. Adapter is '0' or '1' 
  361.  
  362. Session is the value returned from a CALL or LISTEN 
  363.  
  364. Data is the data to send 
  365.  
  366. returns the netbios return code 
  367.  
  368.  
  369. ΓòÉΓòÉΓòÉ 4.1.18. Send_BroadcastDatagram ΓòÉΓòÉΓòÉ
  370.  
  371. NETBIOS( 'Send_BroadcastDatagram', adapter, name_num, data)
  372.  
  373. Sends broadcast data to ANY station with a receive_broadcastDatagram active 
  374.  
  375. Adapter is '0' or '1' 
  376.  
  377. name_num is the value returned from AddName 
  378.  
  379. Data is the data to send 
  380.  
  381. returns the netbios return code 
  382.  
  383.  
  384. ΓòÉΓòÉΓòÉ 4.1.19. Send_Datagram ΓòÉΓòÉΓòÉ
  385.  
  386. NETBIOS( 'Send_Datagram', adapter, name_num, remote_name,data)
  387.  
  388. Sends broadcast data to remote_name using name_num with a receive_Datagram 
  389. active 
  390.  
  391. Adapter is '0' or '1' 
  392.  
  393. remote_name is the 16 byte netbios name of the station to receive the data 
  394.  
  395. Data is the data to send 
  396.  
  397. returns the netbios return code 
  398.  
  399.  
  400. ΓòÉΓòÉΓòÉ 4.1.20. Send_NoAck ΓòÉΓòÉΓòÉ
  401.  
  402. NETBIOS( 'Send_NoAck', adapter, session, data)
  403.  
  404. Sends data to a session partner without waiting for a data acknowledgement 
  405.  
  406. Adapter is '0' or '1' 
  407.  
  408. Session is the value returned from a CALL or LISTEN 
  409.  
  410. Data is the data to send 
  411.  
  412. returns the netbios return code 
  413.  
  414.  
  415. ΓòÉΓòÉΓòÉ 4.2. Sample Programs ΓòÉΓòÉΓòÉ
  416.  
  417.  
  418. ΓòÉΓòÉΓòÉ 4.2.1. Client ΓòÉΓòÉΓòÉ
  419.  
  420. /*                                                               */
  421. /*      REXX/NETBIOS Sample Client Pgm                           */
  422. /*                                                               */
  423. /*                                                               */
  424. /*      Tell REXX there is a new function available              */
  425. /*                                                               */
  426.  
  427. call rxfuncadd 'netbios', 'rexxnetb', 'netbiossrv'
  428.  
  429.  
  430. /*                                                               */
  431. /*      Client station name, must be 16 bytes                    */
  432. /*                                                               */
  433.  
  434. Myname=left('Test',16,' ')
  435. RemoteName =left('Sample',16,' ')
  436.  
  437. /*                                                               */
  438. /*      call netbios and get resources from the global pool      */
  439. /*      defined in PROTOCOL.INI                                  */
  440. /*                                                               */
  441.  
  442. rc=netbios('Reset',0,1,1,1)
  443.  
  444. /*                                                               */
  445. /* if resources available                                        */
  446. /*                                                               */
  447.  
  448. if rc=0 then do
  449.  
  450. /*                                                               */
  451. /* add our name to the network, and get the name number          */
  452. /*                                                               */
  453.   parse value netbios('AddName',0,MyName) with rc name_num .
  454.  
  455. /*                                                               */
  456. /* If we are on the network now, call our partner                */
  457. /*                                                               */
  458.  
  459.   parse value netbios('Call',0,MyName,RemoteName,0,0) with rc lsn .
  460.  
  461. /*                                                               */
  462. /* If call succeeded send a message                              */
  463. /*                                                               */
  464.   if rc=0 then do
  465.     rc=netbios('Send',0,lsn,'test data')
  466. /*                                                               */
  467. /* If send succeeded wait for a response                         */
  468. /*                                                               */
  469.     if rc=0 then do
  470. /*                                                               */
  471. /* If receive succeeded report the received message              */
  472. /*                                                               */
  473.       rc=netbios('Receive',0,lsn,1000,'data.')
  474.       if rc=0 then do
  475.         say
  476.         say 'We received the following message from "' || strip(RemoteName) || '"'
  477.         say data.0
  478.       end
  479.       else say 'Receive failed rc=' || rc
  480.     end
  481.     else say 'Send failed rc=' || rc
  482. /*                                                               */
  483. /* end session now as we are done                                */
  484. /*                                                               */
  485.     call netbios 'Hangup',0,lsn
  486.   end
  487.  
  488. /*                                                               */
  489. /* return our netbios resources to the global pool               */
  490. /*                                                               */
  491.   call netbios 'Close',0
  492.  
  493. end
  494. /*                                                               */
  495. /* oops, either no Netbios resources are available or            */
  496. /*       Netbios is not installed                                */
  497. /*                                                               */
  498. else say 'Netbios resources not available rc='rc
  499.  
  500.  
  501. ΓòÉΓòÉΓòÉ 4.2.2. Server ΓòÉΓòÉΓòÉ
  502.  
  503. /*                                                               */
  504. /*      REXX/NETBIOS Sample Client Pgm                           */
  505. /*                                                               */
  506. /*                                                               */
  507. /*      Tell REXX there is a new function available              */
  508. /*                                                               */
  509.  
  510. call rxfuncadd 'netbios', 'rexxnetb', 'netbiossrv'
  511. /*                                                               */
  512. /*      Client station name, must be 16 bytes                    */
  513. /*                                                               */
  514.  
  515. Myname=left('Sample',16,' ')
  516. RemoteName =left('*',16,' ')
  517.  
  518. /*                                                               */
  519. /*      call netbios and get resources from the global pool      */
  520. /*      defined in PROTOCOL.INI                                  */
  521. /*                                                               */
  522.  
  523. rc=netbios('Reset',0,1,1,1)
  524.  
  525. /*                                                               */
  526. /* if resources available                                        */
  527. /*                                                               */
  528.  
  529. if rc=0 then do
  530.  
  531. /*                                                               */
  532. /* add our name to the network, and get the name number          */
  533. /*                                                               */
  534.  
  535.   parse value netbios('AddName',0,MyName) with rc name_num .
  536.  
  537. /*                                                               */
  538. /* If we are on the network now,                                 */
  539. /* Listen  for a call now                                        */
  540. /*                                                               */
  541.   parse value netbios('Listen',0,MyName,RemoteName,0,0) with rc lsn CallerName .
  542.  
  543. /*                                                               */
  544. /* If Listen succeeded wait for a message                        */
  545. /*                                                               */
  546.   if rc=0 then do
  547.     rc=netbios('Receive',0,lsn,1000,'data.')
  548. /*                                                               */
  549. /* If receive succeeded report the received message              */
  550. /*                                                               */
  551.     if rc=0 then do
  552.       say 'We received the following message from "' || strip(CallerName) || '"'
  553.       say data.0
  554. /*                                                               */
  555. /* and send it back with some additional info                    */
  556. /*                                                               */
  557.       call netbios 'Send',0,lsn,data.0 'Response'
  558.     end
  559. /*                                                               */
  560. /* end session now as we are done                                */
  561. /*                                                               */
  562.     call netbios 'Hangup',0,lsn
  563.   end
  564.  
  565. /*                                                               */
  566. /* return our netbios resources to the global pool               */
  567. /*                                                               */
  568.  
  569. call netbios 'Close',0
  570.  
  571. end
  572.  
  573. /*                                                               */
  574. /* oops, either no Netbios resources are available or            */
  575. /*       Netbios is not installed                                */
  576. /*                                                               */
  577. else say 'Netbios resources not available rc='rc
  578.