home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 13 / CDA13.ISO / cdactual / demobin / share / program / Pascal / 10TLST.ZIP / TENTOOLS.DOC < prev    next >
Encoding:
Text File  |  1990-10-17  |  19.0 KB  |  365 lines
  1.       TenTools is a set of utility functions implemented in Turbo Pascal 5.5
  2.   which allows easy access to the 10Net network, including the Net Use
  3.   function (and Device Cancel function) which is actually implemented through
  4.   the DOS $5F (Redirect Device) function call (using Int $21).
  5.   All of the functions have been used in programs. Some have been tested more
  6.   rigorously than others. This set of tools is being released to the public
  7.   domain for usage as you deem possible. I hope they will be of some use to
  8.   someone. Before using any functions, PLEASE read all you can first. These
  9.   functions have been used on 10Net Plus and work fine. I'm rushing to make
  10.   these tools available as I'm soon changing companies!
  11.  
  12.        To use Tentools, the user needs only to "USE" it as a TPU and make
  13.   calls to its procedures. Certain steps need to be made to use certain
  14.   functions. These steps are explained here:
  15.  
  16.  
  17. #1  "USING NETWORK DEVICES"
  18.        To use devices (or mount drives) at a Superstation on the network,
  19.   first of all the Superstation must be on the network and the local node
  20.   must also be "Loaded" with network software. Next, the local user must
  21.   "Login" to the Superstation. Once logged into the Superstation, the user
  22.   can check on what devices are available ("GetDevices"). Finally, the user
  23.   can either "NetUse" the device(s) needed or, if the device is a drive
  24.   letter, it can be "Mounted" as a local drive letter. This sequence is
  25.   summarized below:
  26.  
  27.     TenTools Function/Procedure            Action
  28.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29.  
  30.  Attaching:
  31.  
  32.     LOADED                                 Am I on the Network?
  33.     NODES                                  Is Superstation available?
  34.     LOGIN                                  Attach to Superstation.
  35.     GETDEVICES                             What devices are available?
  36.     NETUSE (or MOUNT)                      Attach to device(s).
  37.  
  38.  Detaching:
  39.  
  40.     UNUSE (or UNMOUNT)                     Detach from a device.
  41.     LOGOFF                                 Detach from a Superstation.
  42.  
  43.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44.  
  45. #2   "SENDING CHAT MESSAGES"
  46.         To send a 10net Chat message to another node, you don't need to be
  47.    attached to the node in any way. Both nodes need to be on the network.
  48.    The Chat sequence can be started with the Function "CHAT". For more
  49.    information on using Chat, refer to the 10Net manual.
  50.         Using Chat from within TURBO Pascal allows you to send a message to
  51.    node when a process is finished, or to make them aware that your status
  52.    on the network is changing from within your program.
  53.  
  54.     TenTools Function/Procedure            Action
  55.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56.    CHAT                                    Sends a message to another node.
  57.  
  58.  
  59. #3  "SENDING/RECEIVING RECORDS"
  60.        There is a set of functions available in the 10Net $6F function calls
  61.    that allows the user to send and receive "Inter-application" messages.
  62.    These messages are limited to 457 bytes each. To make it simpler to use
  63.    this function, the toolbox contains a set of expanded Send/Receive
  64.    functions, TBSEND and TBRECEIVE. Using these functions, one can send
  65.    records of almost any size, limited more by the amount of memory available
  66.    than anything else. Read the documentation of each procedure for an in-
  67.    depth explanation of how to use them.
  68.         One thing to keep in mind when using TBSEND and TBRECEIVE is that
  69.    the "Profile" of those workstations/superstations that use Sends and
  70.    Receives should include a line to set SBUFFERS=n , where n can be from
  71.    8 to 255 (30 or more is recommended here) and DATAGRM=23 (the maximum).
  72.    This sets the number of Small Buffers that Sends and Receives use, as
  73.    well as maximizing the number of Outstanding Receive Datagrams at 10Net
  74.    initialization.
  75.         A second thing to remember is that buffers MUST BE allocated for
  76.    these functions. This is done with the Tentools function TENCONFIG.
  77.    Read the documentation at the TENCONFIG function before using it.
  78.         Finally, before using sends and receives on the network, the user
  79.    should be aware that Sends directed to a NODENAME that is no longer on
  80.    the network will go through a timeout delay waiting for an acknowledgement
  81.    that never arrives. To avoid this delay, the user can set up a sender and
  82.    receiver on different CB Channels, and messages can be sent using the
  83.    CB channel number instead of the NODENAME. Sends on CB Channels require
  84.    no acknowledgement. This has its advantages and its disadvantages. While
  85.    the timeout delay is avoided, you might still have to develop your own
  86.    check for what records were received. TBSEND/TBRECEIVE has an optional
  87.    parameter that can be used for record checking, the TRANSACTIONID. There
  88.    is also a parameter to use to distinguish between communication functions
  89.    or groups, TRANSACTIONTYPE. (There is another variable, ResponseType,
  90.    which is not yet completely implemented in this release.)
  91.  
  92.     TenTools Function/Procedure            Action
  93.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94.  
  95.    TENCONFIG                               Allocates buffers for records.
  96.    TBSEND                                  Sends an InterApp Message.
  97.    TBRECEIVE                               Receives an InterApp Message.
  98.    SETWAIT                                 Sets maximum wait time for
  99.                                            TBReceive messages.
  100.    SETCBCHANNEL                            Sets a CBChannel to receive on.
  101.  
  102. #4 STATUS/INFORMATIONAL FUNCTIONS
  103.         There are many informational functions that provide the user with
  104.    status, configuration, counts, and other information on the network. Those
  105.    provided within TenTools are listed below:
  106.  
  107.     TenTools Function/Procedure      Action
  108.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  109.    STATUS                            Returns a block of status data from a
  110.                                      node if it is on the network.
  111.    LOADED                            Am I on the network?
  112.    NODENAME                          Returns the local Nodename.
  113.    NODES                             Returns a list of Nodes on the network.
  114.    MOUNTLIST                         What am I mounted to?
  115.    LOGLIST                           Who am I logged to?
  116.    MOUNTSAVAIL                       How many total mounts can I make?
  117.    GETDEVICES                        What devices are at a node?
  118.  
  119. #5 OTHER FUNCTIONS AVAILABLE
  120.         The other functions that are available in TenTools are listed below:
  121.  
  122.     TenTools Function/Procedure      Action
  123.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  124.    TIMESTAMP/STAMPAGE                Timestamp utilities (used internally)
  125.    GETREMOTEMEMORY                   Grab a block of memory from a remote
  126.                                      node.
  127.    SETCBCHANNEL                      Sets the Channel to listen for.
  128.    GETTABLEDATA                      Used internally; see 10Net Programmer's
  129.                                      Reference Manual for details.
  130.    GET10TIME                         Returns the date/time from a remote
  131.                                      node.
  132.    SETUSERNAME                       Changes the local Username.
  133.    SUBMIT                            Submits a commandline to a Superstation
  134.                                      if Submit Permit is on at Superstation.
  135.    SETSPOOL                          Initiates a "template" for a print
  136.                                      spool.
  137.    OPENSPOOL                         Opens an initiated spool.
  138.    CLOSESPOOL                        Closes/prints an initiated spool.
  139.  
  140. _____________________________________________________________________________
  141. <10Net><10Net><10Net><10Net><10Net><10Net><10Net><10Net><10Net><10Net><10Net>
  142. -----------------------------------------------------------------------------
  143.  
  144. What follows is an alphabetical listing of the functions/procedures available
  145. in TenTools and their descriptions:
  146.  
  147. Function Chat(NodeID : S12; VAR DBuffer {:String[n]} ) : Word;
  148. { The DBuffer should be a Turbo Pascal String (length indicator in byte 0)
  149.   The string should be no more than 100 bytes long. This function sends a
  150.   10Net Chat message to the NodeID specified. }
  151.  
  152. Function CloseSpool : Word;
  153. { Calls to CloseSpool, after a spool has been started through OpenSpool and
  154.   some print has been "sent to the printer", will cause the Spoolfile to
  155.   close and printing to begin if the Print Permit is ON at the location
  156.   where the printer is mounted.
  157.      "Sending print to the printer" is done in the usual manner, from within
  158.   programs, by "Typing and Piping" (TYPE>LPT1 <filename>), by Copying from a
  159.   file to the printer, etc.}
  160.  
  161. Function GetDevices(ServerID : S12;
  162.              VAR Device : DeviceArray;
  163.              VAR DeviceCount : Integer): Word;
  164. { Returns a list of devices through the Variable parameter Devices (which is
  165.   defined as Array[1..25] of S8). Uses the Get/Set/Delete/Get User Shared
  166.   Device (Int-$6F,Service-$15) function call.
  167.   }
  168.  
  169. Function GetRemoteMemory(NodeID : S12; VAR DBuffer; VAR DLength : Integer;
  170.                          RemSeg,RemOfs : Word) : Word;
  171. {Copy a section of memory from a remote node to DBuffer
  172.  ( maximum of 470 bytes ) }
  173.  
  174. Function GetTableData(VAR TableBuffer : GetTableDataRec): Word;
  175. {A function which gets the 10Net TableData from a Remote Node}
  176.  
  177. Function Get10Time(NodeName : S15 ;VAR TenTime : DateTimeRec) : Word;
  178. {Returns the Date and Time in a DateTimeRec Record from the Node Requested)
  179. }
  180.  
  181. Function Loaded : Boolean;
  182. { Is 10Net Loaded? }
  183.  
  184. Function Login(ServerID : S12;PW10Net : S8): Word;
  185. { Logs into the requested server. }
  186.  
  187. Function LogList(VAR Logins : LogArray;VAR TableEntries : Integer): Word;
  188. {Returns a list of nodes that the local station is logged into. LogArray
  189.  is a TYPE defined as Array[0..19] of String[12] and can be used in the
  190.  calling program. }
  191.  
  192. Function Logoff(ServerID : S12): Word;
  193. { Logs off the requested server. }
  194.  
  195. Function Mount(ServerID : S12; LocalDevice,RemoteDevice : Char) : Word;
  196. { For Drive mounting, mounts drive REMOTEDRIVE at SERVERID as LOCALDRIVE
  197.  locally; for printer mounting, use "1" for LPT1, etc. }
  198.  
  199. Function MountList(VAR MountTable : DriveArray;VAR PrintTable : PrintArray;VAR TableEntries : Integer): Word;
  200. {Returns a mountlist of type DriveTable (with TableEntries as a count of
  201. actual table entries returned), and PrintTable of Printer reassignments.
  202. The caller must specify a maximum tablesize by setting table entries before
  203. calling. Returns with a value of 0 if it worked without any hitches, and the
  204. value of a 10net error if there is any problem. Will return with a value of
  205. $FFFF if not loaded. Will return names of Devices if any are currently
  206. "NetUsed".}
  207.  
  208. Function MountsAvail : Integer;
  209. {How many total Mounts is the local station configured for?}
  210.  
  211. Function NetUse(ServerID : S12; LocalDrive : Char; RemoteDevice : String;NetUsePassWord : S8) : Word;
  212. { Attaches to a Device at a Remote Server. The RemoteDevice can be an ALIAS }
  213.  
  214. Function NODEName : S12;
  215. {Returns the current nodename }
  216.  
  217. Function Nodes(VAR NodeBuffer;VAR MaxNodes : Integer;
  218.                   SuperstationsOnly : Boolean) : Word;
  219. { A call to this function should be made with NODEBUFFER being an
  220.  Array[1..MaxNodes] of S12. MaxNodes being the largest number of nodes you
  221.  expect to see on the network. If the Returncode of NODES is 0, MaxNodes will
  222.  have the actual number of nodenames returned and the array will be filled
  223.  with their names. SuperstationsOnly is a boolean which allows nodes to be
  224.  called to list only superstations. }
  225.  
  226. Function OpenSpool(NewSpoolname : S12) : Word;
  227.  {Once SetSpool has "configured" your spool, calls to OpenSpool will
  228.   create a new spoolfile with the optional Newspoolname, or with a name
  229.   automatically set by 10Net if NewSpoolName=''. }
  230.  
  231. Function Receive(VAR DBuffer; Secs : Word; VAR Available : Integer; VAR CBMessage : Boolean): Word;
  232. {Receive a data packet on the network in the structure below:
  233.          data           bytes
  234.          =====================
  235.          SenderNodeID : 12
  236.          Len          : 2
  237.          Data         : (Len)
  238.   Available is set to the number of packets available INCLUDING the
  239.   current message. Receives data sent through the SEND function, which is
  240.   limited to data structures of length 470 or less. TBSend and TBReceive
  241.   (which use Send and Receive) can be used for larger structures.
  242. }
  243.  
  244.  
  245. Function Send(NodeID : S12; VAR DBuffer; DLength :Integer): Word;
  246. {Send a data packet on the network to NODEID ( or on a CB Channel if
  247. NODEID is CB##, limited to 470 byte packets. Used within the Toolbox to
  248. accomplish TBSend, which allows large records to be sent.}
  249.  
  250. Procedure SetCBChannel(CBChannel : Byte);
  251. {      This procedure will set your "Listening" Channel to the CBCHANNEL (1
  252.  through 40 are available) specified. TBSends to this CBChannel from other
  253.  nodes will be available here through TBReceive. TBSends to other CBChannels
  254.  will not be seen here. TBSends directed specifically to this node will also
  255.  be seen here, of course.
  256.        The advantages of CB messaging are that many nodes can be setup to
  257.  receive messages on a particular channel, and the sender will not be held
  258.  up waiting for a network handshake to tell him that his Send was Received.
  259. }
  260.  
  261. Function SetSpool(Printer : Byte; SpoolName : S12; Notification : NotifySet; RDays : Byte): Word;
  262. { When SetSpool is first called, it merely sets up a "Template" for
  263.   subsequent calls to OpenSpool and CloseSpool. You must be logged into the
  264.   Superstation where you want to spool and be mounted to a printer and a
  265.   drive on that Superstation. SetSpool will determine where the Printer
  266.   (1,2, or 3 for your local LPT1:,LPT2:, or LPT3:) is mounted and a drive
  267.   letter that you are mounted to. }
  268.  
  269. Procedure SetUserName(UName : S8);
  270. {Changes the Username in the Network Table and in the Global variable
  271.   USERNAME}
  272.  
  273. Function SetWait(WaitLimit : Integer): Word;
  274. { Changes the maximum seconds to wait for receive packets in the same record,
  275.   Defaults to 30. Used in conjunction with TBReceive.}
  276.  
  277. Function StampAge(StartTime : Real): LongInt;
  278. { Returns the difference in seconds between the currenttime and the
  279. "Starttime" timestamp.}
  280.  
  281. Function Status(NodeName : S15; VAR SBlock : StatusBlock): Word;
  282. { Returns a Block of Status information from the Nodename requested if
  283.   that node is on the network.}
  284.  
  285. Function Submit(ServerID : S12; CommandLine : String): Word;
  286. { If the local User is LOGGED INTO the node SERVERID, and the submit permit
  287.  is ON at ServerID, and ServerID is currently at a DOS prompt, then the
  288.  Commandline will be SUBMITTED to ServerID. If it is not currently at a DOS
  289.  prompt, it will be SUBMITTED when it reaches a DOS prompt. }
  290.  
  291. Function TBReceive( VAR SenderID: S12;      {Sending NodeID : String12       }
  292.                     VAR DBuffer;           {Variable (record) to receive    }
  293.                     VAR DLength : Integer; {Maximum length record to receive}
  294.               VAR TransactionID : TID;     {See description of TBSend       }
  295.                   VAR TransType : Integer; {See description of TBSend       }
  296.                   VAR Available : Integer; {Number of records available
  297.                                             including the one passed back   }
  298.                                     VAR CB : Boolean)        {Was this a CB transmission?     }
  299.                          : Word;  {Return code indicates a 10Net error($XXFF)
  300.                                    or an error in a passed parameter ($FFXX)}
  301.  
  302. Function TBSend(NodeID : S12;            {Node to send to                 }
  303.            VAR DBuffer;                   {The data record                 }
  304.                 DLength : Integer;        {Length (bytes) of data          }
  305.           TransactionID : TID;            {Tag to identify record (6 bytes)}
  306.               TransType : Integer;        {Transaction Type - (external to
  307.                                           this toolbox) an integer type used
  308.                                           to maintain that one is receiving
  309.                                           only the correct type of records.}
  310.            ResponseType : Byte            { Not Implemented yet...
  311.                                 How is the TBReceive to act-
  312.                                 0 - no immediate response
  313.                                 1 - Acknowledge when total message received
  314.                                 2 - Acknowledge each packet }
  315.               ) : Word;
  316. { TBSend will send a large interapplication message (DBuffer) of length
  317. DLENGTH across the network. The TransactionID is user defineable and can be
  318. used to acknowledge the receipt or processing of a record to the originator.
  319. TransType, optional, can be used to identify the type of processing required
  320. of a record. The data in DBuffer can be of any structure.
  321.      The message is effectively broken into packets, and sent with a
  322. "packet marker" to assist in its reconstruction when received. Unique
  323. Transaction IDs is essential for records larger than 457 bytes to maintain
  324. unique record identity. Packet Data consists of a PRec (see data Type
  325. definitions) and 457 bytes of the DataRec.
  326.      The network provides handshaking with Sends and Receives if they are
  327. directed to a particular node. If CB# is used instead, there is no
  328. handshaking provided. If a node is specified, and it is not currently
  329. available or its 10Net SBuffers buffering is full, the sending node will
  330. be stuck waiting for a timeout or until the receiver or buffer space appears.
  331. For this reason, in some applications which can't be held up waiting, it is
  332. wise to use CB channel communication. (See the "SetCBChannel" function for a
  333. discussion of its usage.)
  334. }
  335.  
  336. Function TenConfig(MaxSendRec,MaxRecvRec : Integer; {Size of largest records
  337.                                                      to send/receive}
  338.                    MaxRecs : Integer)   {Maximum number of Records to recv}
  339.                           : Word;
  340. { This function allows the user to dynamically change the size of the
  341. buffers being used by TBSend and TBReceive to optimize usage.
  342. MaxSendRec is the size of the largest TBSEND record
  343. MaxRecvRec is the size of the largest TBRECEIVE record
  344. MaxRecs is the number of TBReceive records to buffer
  345. }
  346.  
  347. Function TimeStamp : Real;
  348. {Returns a timestamp of 6 bytes ordered, Year,Month,Day,Hour(24),Minute,
  349.  Second }
  350.  
  351. Function UnMount(LocalDrive : Char) : Word;
  352. { Unmounts previously mounted drive or printer }
  353.  
  354. Function UnUse(LocalDrive : Char) : Word;
  355. { Detaches from a shared device at a remote server. The attachment was made
  356. through a Net Use (or NetUse), and the local drive letter is all that is
  357. needed to detach}
  358.  
  359. Function UpCase8(Str_8 : S8): S8;
  360. {Expands and "Upcases" an 8 character string}
  361.  
  362. Function UpCase12(Str_12 : S12): S12;
  363. {Expands and "Upcases" a 12 character string}
  364.  
  365.