The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/devtools/rxnetb/rxnetb.inf

OS/2 Help File | 1992-10-23 | 11.9 KB | 578 lines

ΓòÉΓòÉΓòÉ 1. (C) Copyright IBM Corp. 1992 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2. OS/2 REXX NETBIOS Users Guide ΓòÉΓòÉΓòÉ

This document is intended for application developers who wish to use NETBIOS
services from OS/2 REXX execs. The NETBIOS services are available in REXX as an
external function package, and are loaded only when used.


ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 3.1. Rexx Netbios Installation ΓòÉΓòÉΓòÉ

Copy REXXNETB.DLL to a LIBPATH directory

Add this following line to all NETBIOS execs to insure the function is
registered

if rxfuncquery('netbios') then call rxfuncadd 'netbios','REXXNETB','NETBIOSSRV'


ΓòÉΓòÉΓòÉ 4. REXX Netbios Programming Interface ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.1. Function parameters and return values ΓòÉΓòÉΓòÉ

The NETBIOS function package provides a single function name to be used with a
set of parameters. The function name is the first string you used when you
RXFUNDADDed the the function, and defaults to NETBIOS.

The general format of the NETBIOS function invocation is:

NETBIOS( function-string [ parameters ] )

or

call NETBIOS function-string [ parameters ]

The function strings and parameters and returned data are listed below in
alphabetical order.


ΓòÉΓòÉΓòÉ 4.1.1. AddName ΓòÉΓòÉΓòÉ

NETBIOS( 'AddName', adapter, name)

Adapter is '0' or '1'

name is a 16 byte Netbios name string

returns a string of format NN YY

nn        return code

yy        netbios name number is nn = 0


ΓòÉΓòÉΓòÉ 4.1.2. AddGroupName ΓòÉΓòÉΓòÉ

NETBIOS( 'AddGroupName', adapter, name)

Adapter is '0' or '1'

name is a 16 byte Netbios Group name string

returns a string of format NN YY

nn        return code

yy        netbios name number if nn = 0


ΓòÉΓòÉΓòÉ 4.1.3. Call ΓòÉΓòÉΓòÉ

NETBIOS( 'Call', adapter, Local_name,Remote_name, send_timeout,receive_timeout)

Call and establish a session with remote_name from local_name

Adapter is '0' or '1'

Local_name is a 16 byte Netbios Group name string

Remote_name is a 16 byte Netbios Group name string of the station to call

send_timeout, in milliseconds

receive_timeout, in milliseconds

returns a string of format NN YY

nn        return code

yy        netbios session number if nn = 0


ΓòÉΓòÉΓòÉ 4.1.4. Chain_Send ΓòÉΓòÉΓòÉ

NETBIOS( 'Chain_Send', adapter, session,buffer1, buffer2)

Sends to buffers in a single transmission over a session, up to 128k can be
sent in a single transmission

Adapter is '0' or '1'

Session is the value second returned on Call or Listen

buffer1 is the first buffer to send

buffer2 is the second buffer to send

returns the Netbios Return code


ΓòÉΓòÉΓòÉ 4.1.5. Chain_Send_NoAck ΓòÉΓòÉΓòÉ

NETBIOS( 'Chain_Send_NoAck', adapter, session,buffer1, buffer2)

Sends to buffers in a single transmission over a session, up to 128k can be
sent in a single transmission, without waiting for a data acknowledgement

Adapter is '0' or '1'

Session is the value second returned on Call or Listen

buffer1 is the first buffer to send

buffer2 is the second buffer to send

returns the Netbios Return code


ΓòÉΓòÉΓòÉ 4.1.6. Close ΓòÉΓòÉΓòÉ

NETBIOS( 'Close' ,adapter)

returns all netbios resources to the system pool.

Adapter is '0' or '1'

returns the Netbios Reset return code


ΓòÉΓòÉΓòÉ 4.1.7. Config ΓòÉΓòÉΓòÉ

NETBIOS( 'Config' ,adapter)

Returns the number of NETBIOS resources configured and available

Adapter is '0' or '1'

returns a string of format: Sessions Commands Names Asessions Acommands Anames

Sessions  configured sessions (see CM Lan Services,NETBIOS)

Commands  configured commands (see CM Lan Services,NETBIOS)

Names     configured names (see CM Lan Services,NETBIOS)

Asessions currently available sessions

Acommands currently available commands

Anames    currently available names


ΓòÉΓòÉΓòÉ 4.1.8. DeleteName ΓòÉΓòÉΓòÉ

NETBIOS( 'DeleteName',adapter,name)

deletes name from the netbios name table.

Adapter is '0' or '1'

name is the 16 byte netbios name to delete

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.9. FindName ΓòÉΓòÉΓòÉ

NETBIOS( 'FindName', adapter, name, stemname)

Adapter is '0' or '1'

name is a 16 byte Netbios name string

returns a string of format NN

nn        netbios return code

If nn is 0 then stemname. contains the following information

stemname.0 Count of systems responding the Findname request, list starts at
          stemname.2

stemname.1 either 'GroupName' or 'UniqueName'

stemname.2-n (stemname.0 count)  a binary string that contains the data
          returned from the find name request.


ΓòÉΓòÉΓòÉ 4.1.10. Hangup ΓòÉΓòÉΓòÉ

NETBIOS( 'Hangup',adapter,session)

closes the session

Adapter is '0' or '1'

session is the value returned on a CALL or LISTEN

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.11. Listen ΓòÉΓòÉΓòÉ

NETBIOS( 'Listen', adapter, Local_name,Remote_name, send_timeout,receive_timeout)

Listens for a call to local_name from remote_name

Adapter is '0' or '1'

Local_name is a 16 byte Netbios Group name string

Remote_name is a 16 byte Netbios Group name string of the station to listen for

Note:  a name of '*' means anyone

send_timeout, in milliseconds

receive_timeout, in milliseconds

returns a string of format NN YY [ NAME ]

nn        return code

yy        netbios session number if nn = 0

NAME      If Remotename starts with '*' (anyone) then NAME is the Netbios name
          of the caller


ΓòÉΓòÉΓòÉ 4.1.12. Receive ΓòÉΓòÉΓòÉ

NETBIOS( 'Receive', adapter, session, size, stemname)

receives data from session partner

Adapter is '0' or '1'

session is the value retuned from CALL or LISTEN

size is the maximum size to receive

stemname, is the rexx stem variable to place the data into, and the data will
be placed in stemname.0

Note:  The stem will be dropped prior to the receive being started

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.13. Receive_Any ΓòÉΓòÉΓòÉ

NETBIOS( 'Receive_Any', adapter, name_number, size, stemname)

receives data from ANY session partner

Adapter is '0' or '1'

session is the value retuned from ADDNAME

size is the maximum size to receive

stemname, is the rexx stem variable to place the data into, and the data will
be placed in stemname.0

stemname.1 will contain the session number if rc=0 or 6

Note:  The stem will be dropped prior to the receive being started

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.14. Receive_BroadcastDatagram ΓòÉΓòÉΓòÉ

NETBIOS( 'Receive_BroadcastDatagram', adapter, name_number, size, stemname)

receives a broadcast datagram to name_number from ANY station

Adapter is '0' or '1'

session is the value retuned from ADDNAME

size is the maximum size to receive

stemname, is the rexx stem variable to place the data into, and the data will
be placed in stemname.0

stemname.1 will contain the remote station name if rc=0 or 6

Note:  The stem will be dropped prior to the receive being started

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.15. Receive_Datagram ΓòÉΓòÉΓòÉ

NETBIOS( 'Receive_Datagram', adapter, name_number, size, stemname)

receives a datagram to name_number from ANY station

Adapter is '0' or '1'

session is the value retuned from ADDNAME

size is the maximum size to receive

stemname, is the rexx stem variable to place the data into, and the data will
be placed in stemname.0

stemname.1 will contain the remote station name if rc=0 or 6

Note:  The stem will be dropped prior to the receive being started

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.16. Reset ΓòÉΓòÉΓòÉ

NETBIOS( 'Reset', adapter, sessions, commands, names)

receives a datagram to name_number from ANY station

Adapter is '0' or '1'

Sessions is the number of sessions to allocate from the CM NETBIOS buffer pool.
(See CM, Lan Services,NETBIOS)

Commands is the number of commands to allocate from the CM NETBIOS buffer pool.
(See CM, Lan Services,NETBIOS)

Names is the number of names to allocate from the CM NETBIOS buffer pool. (See
CM, Lan Services,NETBIOS)

returns the netbios return code, 56= requested resources not available.

use of the 'Config' option will assist in avoiding this return code.


ΓòÉΓòÉΓòÉ 4.1.17. Send ΓòÉΓòÉΓòÉ

NETBIOS( 'Send', adapter, session, data)

Sends data to a session partner

Adapter is '0' or '1'

Session is the value returned from a CALL or LISTEN

Data is the data to send

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.18. Send_BroadcastDatagram ΓòÉΓòÉΓòÉ

NETBIOS( 'Send_BroadcastDatagram', adapter, name_num, data)

Sends broadcast data to ANY station with a receive_broadcastDatagram active

Adapter is '0' or '1'

name_num is the value returned from AddName

Data is the data to send

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.19. Send_Datagram ΓòÉΓòÉΓòÉ

NETBIOS( 'Send_Datagram', adapter, name_num, remote_name,data)

Sends broadcast data to remote_name using name_num with a receive_Datagram
active

Adapter is '0' or '1'

remote_name is the 16 byte netbios name of the station to receive the data

Data is the data to send

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.1.20. Send_NoAck ΓòÉΓòÉΓòÉ

NETBIOS( 'Send_NoAck', adapter, session, data)

Sends data to a session partner without waiting for a data acknowledgement

Adapter is '0' or '1'

Session is the value returned from a CALL or LISTEN

Data is the data to send

returns the netbios return code


ΓòÉΓòÉΓòÉ 4.2. Sample Programs ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.2.1. Client ΓòÉΓòÉΓòÉ

/*                                                               */
/*      REXX/NETBIOS Sample Client Pgm                           */
/*                                                               */
/*                                                               */
/*      Tell REXX there is a new function available              */
/*                                                               */

call rxfuncadd 'netbios', 'rexxnetb', 'netbiossrv'


/*                                                               */
/*      Client station name, must be 16 bytes                    */
/*                                                               */

Myname=left('Test',16,' ')
RemoteName =left('Sample',16,' ')

/*                                                               */
/*      call netbios and get resources from the global pool      */
/*      defined in PROTOCOL.INI                                  */
/*                                                               */

rc=netbios('Reset',0,1,1,1)

/*                                                               */
/* if resources available                                        */
/*                                                               */

if rc=0 then do

/*                                                               */
/* add our name to the network, and get the name number          */
/*                                                               */
  parse value netbios('AddName',0,MyName) with rc name_num .

/*                                                               */
/* If we are on the network now, call our partner                */
/*                                                               */

  parse value netbios('Call',0,MyName,RemoteName,0,0) with rc lsn .

/*                                                               */
/* If call succeeded send a message                              */
/*                                                               */
  if rc=0 then do
    rc=netbios('Send',0,lsn,'test data')
/*                                                               */
/* If send succeeded wait for a response                         */
/*                                                               */
    if rc=0 then do
/*                                                               */
/* If receive succeeded report the received message              */
/*                                                               */
      rc=netbios('Receive',0,lsn,1000,'data.')
      if rc=0 then do
        say
        say 'We received the following message from "' || strip(RemoteName) || '"'
        say data.0
      end
      else say 'Receive failed rc=' || rc
    end
    else say 'Send failed rc=' || rc
/*                                                               */
/* end session now as we are done                                */
/*                                                               */
    call netbios 'Hangup',0,lsn
  end

/*                                                               */
/* return our netbios resources to the global pool               */
/*                                                               */
  call netbios 'Close',0

end
/*                                                               */
/* oops, either no Netbios resources are available or            */
/*       Netbios is not installed                                */
/*                                                               */
else say 'Netbios resources not available rc='rc


ΓòÉΓòÉΓòÉ 4.2.2. Server ΓòÉΓòÉΓòÉ

/*                                                               */
/*      REXX/NETBIOS Sample Client Pgm                           */
/*                                                               */
/*                                                               */
/*      Tell REXX there is a new function available              */
/*                                                               */

call rxfuncadd 'netbios', 'rexxnetb', 'netbiossrv'
/*                                                               */
/*      Client station name, must be 16 bytes                    */
/*                                                               */

Myname=left('Sample',16,' ')
RemoteName =left('*',16,' ')

/*                                                               */
/*      call netbios and get resources from the global pool      */
/*      defined in PROTOCOL.INI                                  */
/*                                                               */

rc=netbios('Reset',0,1,1,1)

/*                                                               */
/* if resources available                                        */
/*                                                               */

if rc=0 then do

/*                                                               */
/* add our name to the network, and get the name number          */
/*                                                               */

  parse value netbios('AddName',0,MyName) with rc name_num .

/*                                                               */
/* If we are on the network now,                                 */
/* Listen  for a call now                                        */
/*                                                               */
  parse value netbios('Listen',0,MyName,RemoteName,0,0) with rc lsn CallerName .

/*                                                               */
/* If Listen succeeded wait for a message                        */
/*                                                               */
  if rc=0 then do
    rc=netbios('Receive',0,lsn,1000,'data.')
/*                                                               */
/* If receive succeeded report the received message              */
/*                                                               */
    if rc=0 then do
      say 'We received the following message from "' || strip(CallerName) || '"'
      say data.0
/*                                                               */
/* and send it back with some additional info                    */
/*                                                               */
      call netbios 'Send',0,lsn,data.0 'Response'
    end
/*                                                               */
/* end session now as we are done                                */
/*                                                               */
    call netbios 'Hangup',0,lsn
  end

/*                                                               */
/* return our netbios resources to the global pool               */
/*                                                               */

call netbios 'Close',0

end

/*                                                               */
/* oops, either no Netbios resources are available or            */
/*       Netbios is not installed                                */
/*                                                               */
else say 'Netbios resources not available rc='rc