home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / utils / lserial.lha / lserial / Lserial.DOC < prev    next >
Text File  |  1992-05-17  |  26KB  |  735 lines
  1. Lserial V2(3) for AMOS1.3 and above.
  2. Lserial is (C) Niklas Sjöberg 1992
  3.  
  4.  
  5.  
  6.        NOTE: Commands added since V1 is marked with *-, so just  load
  7.      you favourite textreader and search for "*-".
  8.  
  9.  
  10.        Lserial.doc is now  splitted  in  two  parts.  Part  I  covers
  11.     general    serial-commands  and  part  II  covers  all  necessary
  12.     information about the XPR-specifications.
  13.  
  14.  
  15.  
  16.     DISTRIBUTION:
  17.     -------------
  18.        Lserial no longer is freely distributable, it is  now  shipped
  19.     under the term shareware.
  20.  
  21.              Lserial is copyrighted by me, Niklas Sjöberg.
  22.  
  23.  
  24.     DISCLAIMER:
  25.     -----------
  26.        All the usual... You are using this program at your own  risk.
  27.      I can not be held responsible for any damage or whatsoever.
  28.  
  29.  
  30.     WHY?:
  31.     -----
  32.        AMOS's serial didn't work in 1.0/1.1, in  1.2/1.3  it  worked,
  33.     but  only some-times and only a little :-) The main 1.3-bug seems
  34.     to be when one tries to open the device after  closing  (this  is
  35.     NOT  a  devicebug since it is tested with serial.device from both
  36.     1.3.3 and 2.04. An old serial.device from WB1.2  causes  AMOS  to
  37.     hang  on  some occasions for some reason) it once and then trying
  38.     to open it again. Seems like François never gets  it right? I was
  39.     first to produce a working serial for 1.1/1.2 and it seems   like
  40.     I'm  first  on  1.3  to!  (boast, boast :-)) If you find any bugs
  41.     please let me know!
  42.  
  43.  
  44.     HOW TO:
  45.     -------
  46.        In the days of V1.1/1.2 I used to  supply  a  program  for  my
  47.     extensions  which  could  change  any  (of  mine) extension to be
  48.     configured as any number. This is not possible  anymore,  due  to
  49.     the  layout  of  1.3  (well it IS possible but it would slow down
  50.     every access to the data-table). Because of this you  MUST  place
  51.     LSerial as extension number eleven (11). Your manual explains all
  52.     about  adding  extensions.  If  you  MUST  or  NEED  to  have  it
  53.     configured as  another number then send me a disk  full  of  nice
  54.     programs and some international replycoupuns to cover mailing.
  55.  
  56.  
  57.  
  58.                         PART I - General serialcommands
  59.  
  60.     Before you start crashing your computer :
  61.  
  62.        It is up to  you,  the  programmer,  to  make  sure  that  the
  63.     serial.device (or another device you might have selected) is open
  64.     and  ready  for  use before you try to access any read/write/xpr-
  65.     commands. If you for instance try to call Lser Send as the  first
  66.     instruction  in  your program it will hang OR crash the computer!
  67.     Always use Lser  Open! If the device  failed  to  open  you  will
  68.     receive  an  errormessage  and the program will be aborted, or if
  69.     you have a errorhandling-routine the error will be trapped  (that
  70.     is the best solution!). It is safe to call Lser Close even though
  71.     no  device  is open, so it might be a good idea to always do this
  72.     before your program exists or if you change device.
  73.  
  74.  
  75.  
  76.     Lser Open - Open serial for use.
  77.     Lser Open BAUD,RWlen,STOP,BUF_SIZE,BRKtime,FLAGS,UNIT,"name.device"
  78.  
  79.     where
  80.  
  81.     BAUD     - Baudrate
  82.     RWlen    - number of bits when read/write (normally 8)
  83.     STOP     - Number of stop-bits (normally 1)
  84.     BUF_SIZE - Internal buffer for device. MUST be >512 bytes
  85.     BRKtime  - How long a BRK should last, in MICROseconds
  86.                (normally 250000)
  87.     FLAGS    - See Appendix B for list
  88.     UNIT     - Unit, normally 0 for external modems.
  89.     name     - Normally serial.device (located in devs:)
  90.  
  91.  
  92.  
  93.     Lser Close - Close serial.device
  94.     Lser Close
  95.  
  96.  
  97.  
  98.     Lser Send - Send data to the modem, non-multitasking
  99.     Lser Send A$
  100.  
  101.     where
  102.  
  103.        A$ contains any data. Note  that  this  instruction  does  not
  104.     return to AMOS until the whole string is sent.
  105.  
  106.  
  107.  
  108.     Lser Query - Check if there is data to read
  109.     L=Lser Query
  110.  
  111.     where
  112.  
  113.        L - Contains the number of chars available to read.
  114.  
  115.  
  116.  
  117.     Lser Read - Read all available characters.
  118.     A$=Lser Read
  119.  
  120.     where
  121.  
  122.        A$ will contain all data buffered by the  device.  WARNING  If
  123.     there  are  VERY  many  characters  to  read AMOS may crash. This
  124.     command should only be used if you often read  from  the  device,
  125.     like  in  a  comm-program which continually loops and read. Using
  126.     it when communicating with MIDI or via 0-modem can  be  dangerous
  127.     due to the very high speed!
  128.  
  129.  
  130.  
  131.     Lser Mulsend - Send a string in a multitasking manner.
  132.     Lser Mulsend A$
  133.  
  134.     where
  135.  
  136.        A$ may contain any data. If you try  to  send  any  more  data
  137.     before Mulsend has completed only garbage will be output from the
  138.     modem.  Control  will  return  to  AMOS immediately. Changing the
  139.     contents of A$ before Mulsend has completed is a stupid thing  to
  140.     do..(I  have  not had time to test and see if serial.dev actually
  141.     copies the data)
  142.  
  143.  
  144.  
  145.     Lser Mulcheck - Check if Mulsend has sent all data.
  146.     L=Lser Mulcheck
  147.  
  148.     where
  149.  
  150.        L will be true if Mulsend is ready.
  151.  
  152.  
  153.  
  154.  
  155.     Lser Get - Get a specified number of characters.
  156.     A$=Lser Get(N)
  157.  
  158.     where
  159.  
  160.        N Is the number of characters you  wish  to  read.  Note  that
  161.     control  will  not  return to AMOS until the number of characters
  162.     specified have been received.  This can cause  AMOS  to  hang  if
  163.     you  haven't any CARRIER and no data appears. A good advise is to
  164.     use Lser Query or Lcarrier before trying to read anything.
  165.  
  166.  
  167.  
  168.  
  169.     Lcarrier - Check for carrier
  170.     L=Lcarrier
  171.  
  172.     where
  173.  
  174.        L will be true if CARRIER exists.
  175.  
  176.  
  177.  
  178.  
  179.     Lser Brk - Send a BRK to modem (time specified in Lser Open)
  180.     Lser Brk
  181.  
  182.  
  183.  
  184.  
  185. *-  Linkey$ - Convert some AMOS-characters to ANSI-codes.
  186. *-  A$=Linkey$
  187.  
  188. *-  where
  189.  
  190. *-     A$   will  contain one or more characters. Linkey$ works  just
  191. *-  like  Inkey$  in  AMOS  except that it might return more than one
  192. *-  character. It always reads one character from the keyboard but if
  193. *-  for instance a cursor-key was pressed the ANSI-code will  require
  194. *-  three  characters.  Currently  Linkey$  converts  all cursor-keys
  195. *-  and all keys pressed while the CONTROL-key is held  down.  Escape
  196. *-  backspace  a-z  etc. are not converted in any way. If no keys are
  197. *-  pressed A$ will be empty. Always use this instead  of  Inkey$  if
  198. *-  you are to be able to communicate with another (ANSI/VT100) term-
  199. *-  inal.
  200.  
  201.  
  202.  
  203.  
  204.                         PART II - The XPR specs
  205.  
  206.  
  207. *-     XPR stands for eXternal PRotocol and  was  invented  by  W.G.J
  208. *-  Langevald    in    1989.  The  idea  is  that  the  author  of  a
  209. *-  communicationprogram  (or  of  any      program    involved    in
  210. *-  filetransfers)    can    use    standard    Amiga-libraries   for
  211. *-  filetransfers. The xpr*-libraries are supposed to  be  the  brain
  212. *-  of  the protcol, checking the incoming data, if necessary request
  213. *-  a re-send, save data to a file etc. etc. The (comm)program is the
  214. *-  one which supplies all the basic routines for  serial-read/write,
  215. *-  saving  files  etc.  These  routines  are  later  called  by  the
  216. *-  xpr*.library. Since the XPR  is  quite  flexible,  allowing  many
  217. *-  different  operations to be performed, you may count on that if a
  218. *-  program supports ONE xpr.library it  will  probably  support  all
  219. *-  future libraries. This means that the user may use protcols which
  220. *-  even  wasn't  invented  when  the author of the program wrote his
  221. *-  callbacks! It also means that the author of the program only need
  222. *-  to write his callback routines once (which he already  needed  in
  223. *-  his  originaly  program in the first place) in order to work with
  224. *-  any protocols. Lately some XEM*.lbrary (eXternal EMulation)  have
  225. *-  appeared. These can/could  actually  be  used  through  the  XPR-
  226. *-  standard  using  XprHostMon  and XprUserMon. Due to the layout of
  227. *-  AMOS (not using normal  intuition-screen)  these  cannot  be  run
  228. *-  under AMOS in any way.
  229.  
  230.  
  231.  
  232. *-     When all the callbacks are written (which I have done for you)
  233. *-  it  is  quite  easy to use any xpr.library. In general the 'flow'
  234. *-  when using a xpr looks something like this  :  (unecessary  setup
  235. *-  removed sine Lxpr handles this for you)
  236.  
  237.  
  238. *-  1) Open the desired library
  239. *-     (Did it open?)
  240. *-  2) Call SetUp with a proper init-string.
  241. *-     (See docs for the library in question)
  242. *-  3) Check flags returned by SetUp
  243. *-     (See below)
  244. *-  4) Wait until user requests up-/download.
  245. *-     (If  flags supported UserHostMon, download may be initiated
  246. *-     automagically)
  247. *-  5) Get appropriate filenames for up/download (if necessary, spe-
  248. *-     cified in flags)
  249. *-  6) Call Send or Receive.
  250. *-  7) When the program is quit or xpr is changed, close it and/or
  251. *-     jump to 1).
  252.  
  253. *-     APPENDIX C contains a complete example of how to use a xpr-
  254. *-  library.
  255.  
  256.  
  257. *-     Before we start dealing with the  Lxpr-syntax,  here  are  the
  258. *-  callbacks   that  are  supported  by  Lxpr  (usually  the  needed
  259. *-  callbacks for a library are stated in the library docs.)
  260.  
  261.  
  262. *-  xpr_filename  - Support for both batch and singlefile transfer.
  263. *-                 (actually this is a datafield, but always filled
  264. *-                 in by Lxpr)
  265. *-  xpr_fopen     - Opens file(s)
  266. *-  xpr_fclose    - Close file(s)
  267. *-  xpr_fread     - Read from file(s)
  268. *-  xpr_fwrite    - Write to file(s)
  269. *-  xpr_sread     - Read from serial.device (or spec. in Lser Open)
  270. *-  xpr_swrite    - Write from serial.device(or spec. in Lser Open)
  271. *-  xpr_sflush    - Clear all data in serial.device-buffer
  272. *-  xpr_update    - Print info (see below)
  273. *-  xpr_chkabort  - See if user aborted transfer
  274. *-  xpr_chkmisc   - No need for this one, yet, not one xpr require is
  275. *-                  so far.
  276. *-  xpr_gets      - Get a string from the user
  277. *-  xpr_setserial - Get and/or change serialparameters
  278. *-  xpr_ffirst    - Get the first filename during batch transfer
  279. *-  xpr_fnext     - Get the next filename during a batch transfer
  280. *-  xpr_finfo     - Obtain fileinformation (filetype not supported)
  281. *-  xpr_fseek     - Position in a file
  282. *-  xpr_extension - All four (the four below).
  283. *-  xpr_options   - Supported but currently not used (just exits)
  284. *-  xpr_unlink    - Delete file(s)
  285. *-  xpr_squery    - Return # of chars available from serial
  286. *-  xpr_getptr    - Return customscreen-pointer (WB always returned)
  287.  
  288.  
  289. *-  The xpr_update-function supports the following fields :
  290.  
  291. *-  xpru_protocol    - The name of the xpr currently used
  292. *-  xpru_filename    - The file being transferd
  293. *-  xpru_filesize    - Size of the file being transferd
  294. *-  xpru_msg         - Last messeage from library
  295. *-  xpru_errormsg    - Last errormessage
  296. *-  xpru_blocks      - Number of blocks sent
  297. *-  xpru_blocksize   - The current size of each block
  298. *-  xpru_bytes       - Number of bytes sent
  299. *-  xpru_errors      - Number of errors during transfer
  300. *-  xpru_timeouts    - Number of timeouts during transfer
  301. *-  xpru_blockcheck  - Type of error-check (usually CRC och checksum)
  302. *-  xpru_expecttime  - Expected (total) transfertime
  303. *-  xpru_elapsedtime - Time elapsed since start of transfer
  304. *-  xpru_datarate    - cps for total transfer so far
  305.  
  306. *-  more fields may be suppported in the future.
  307.  
  308.  
  309. *-     The Lxpr-part only contains one command! This is  due  to  the
  310. *-  inner workings of the AMOS compiler which treats all functions as
  311. *-  local,  as  it  datas.  Lxpr  COULD have been split up on several
  312. *-  commands, but would have meant that either all the  xpr-callbacks
  313. *-  and  data  had  been stored in the global function (ie. extension
  314. *-  init which always is linked if the extension is used) or a lot of
  315. *-  copying and unecessary space waste  between  the  functions.  For
  316. *-  those  of you who never use the xpr-functions less memory will be
  317. *-  used.  The  only  thing  added  which  occupies  memory  are  the
  318. *-  timer.device structure and its replyport.
  319.  
  320. *-  The syntax for Lxpr are as follows :
  321.  
  322. *-  A$=Lxpr("filename","setup-string","libraryname",FUNCTION)
  323.  
  324. *-  where
  325.  
  326. *-     FUNCTION is either, 0 for Send file(s), 1 for Receive file(s),
  327. *-  2  for  Openlibrary,  3  for  Closelibrary,  4  for  Setup  (send
  328. *-  parameters),  5  for  read  (works like Lser Read, but XprHostMon
  329. *-  will be called if required, se below), 6 for  Write  (works  just
  330. *-  Lser Send, but calls XprUserMon if required).
  331.  
  332. *-     I strongly suggest that you set up some global  variables  and
  333. *-  assign apropriate values to them and then use them in all further
  334. *-  xpr-calls :
  335.  
  336. *-  XPRSEND =0
  337. *-  XPRREC  =1
  338. *-  XPROPEN =2
  339. *-  XPRCLOSE=3
  340. *-  XPRSETUP=4
  341. *-  XPRREAD =5
  342. *-  XPRWRITE=6
  343.  
  344. *-     XPRREAD and XPRWRITE are always checked for first,guaranteeing
  345. *-  you as fast as possible reads and writes to/from the  device.  Of
  346. *-  course you may overrule the library's request that XprHostMon and
  347. *-  XprUserMon  should  be called, by calling Lser Read and Lser Send
  348. *-  instead. These two routines are somewhat faster than the  XPRREAD
  349. *-  and  WRITE and may safely be used if "flags" from SetUp indicates
  350. *-  that the protocol doesn't require  XprHostMon  and/or  XprUserMon
  351. *-  to be called.
  352.  
  353. Please note that it is up to your program to evaluate filepatterns requested
  354. by the user. XPRSEND and XPRREC only accepts full filenames separated by
  355. a space. If you use Ldos you can use the Lcat-commands in combination with
  356. Lmatch (Relase 2 only) in order to find matching filenames.
  357.  
  358.  
  359.  
  360. *-  XPRSEND - Send one or more files.
  361. *-  A$=Lxpr(FILENAME$,"","",XPRSEND)
  362.  
  363. *-  where
  364.  
  365. *-     A$  currently  is  undefined  (empty  string).  FILENAME$  may
  366. *-  contain  one or more filenames which are to be sent. If more than
  367. *-  one filename is specified they must be separated  with  a  single
  368. *-  space. Note that all libraries doesn't support batchtransfers.
  369.  
  370.  
  371.  
  372. *- WARNING! FILENAME$ MUST BE NULLTERMINATED! (FILENAME$=FILENAME$+Chr$(0))
  373.  
  374.  
  375.  
  376. *-  XPRREC - Receive one or more files.
  377. *-  A$=Lxpr(FILENAME$,"","",XPRREC)
  378.  
  379. *-  where
  380.  
  381. *-     A$ currently is undefined (empty  string).  FILENAME$  can  be
  382. *-  left  out  if  "flags"  specified  that  the protocol can receive
  383. *-  filenames from sender (Ymodem-batch, Zmodem etc.)  FILENAME$  may
  384. *-  contain  more  than  one  filename  but  protocols  which handles
  385. *-  batchtransfers usually  can  receive  filenames  and  if  "flags"
  386. *-  specify this you may set FILENAME$="".
  387.  
  388. *- WARNING! FILENAME$ MUST BE NULLTERMINATED! (FILENAME$=FILENAME$+Chr$(0))
  389.  
  390.  
  391.  
  392. *-  XPROPEN - Open a xpr-library for use.
  393. *-  A$=Lxpr("","",LIBRARY$,XPROPEN)
  394.  
  395. *-  where
  396.  
  397. *-     A$ will be empty if the open failed, otherwise A$ will contain
  398. *-  the string "OK" (in capitals). LIBRARY$ is the complete  name  of
  399. *-  the library, for example xprzmodem.library.
  400.  
  401.  
  402.  
  403.  
  404. *-  XPRCLOSE - Close a xpr-library.
  405. *-  A$=Lxpr("","","",XPRCLOSE)
  406.  
  407. *-  where
  408.  
  409. *-     A$ currently is undefined. Always close your  current  library
  410. *-  before opening a new library or exiting the program.
  411.  
  412.  
  413.  
  414.  
  415. *-  XPRSETUP - Initialize the xpr and customize its performance.
  416. *-  A$=Lxpr("",SETUP$,"",XPRSETUP)
  417.  
  418. *-  where
  419.  
  420. *-       SETUP$  is  a  valid  option-string,  as  specified  in  the
  421. *-  protocol's documentation. A$ will contain a bit-pattern converted
  422. *-  to  ASCII.  Please  note  that  the order of the bits are left to
  423. *-  right  and  not  right  to  left  as  usual.  In    other   terms
  424. *-  Mid$(A$,1,1)  means  bit  0 (NOT 1) and Mid$(A$,1,3) means bit 2.
  425. *-  The bits have the following meanings :
  426.  
  427. *-  Bit 0 : If set, all was successfull.
  428. *-  Bit 1 :  Protocol  requires  no  filerequester / filenames   when
  429. *-  receiving files. Note that the xpr may supply a filerequester
  430. *-  itself, which probably will appear on the workbench-screen  since
  431. *-  Lxpr  tells  the  xpr  to  use  this screen when/if xpr_getptr is
  432. *-  called.
  433. *-  Bit 2 : Protocol requires no filerequester/filanmes when sending
  434. *-  files.
  435. *-  Bit 3 : The xpr would  like you  to use   XProtocolHostMon()  for
  436. *-  all serial input. This means that you SHOULD call XPRREAD instead
  437. *-  of  using  the  normal  Lser-functions. If you don't the protocol
  438. *-  might not operate correctly and functions such as  autoactivation
  439. *-  on download might be disabled. Note that it is perfectly legal to
  440. *-  call  XPRREAD  even  if  this  bit  isn't  set.  Lxpr  only calls
  441. *-  HostMon() if suitable.
  442. *-  Bit 4 : The  xpr  would  like you to use  XProtocolUserMon()  for
  443. *-  all  user  input (ie. it wan't to check what you are sending). As
  444. *-  above, you should call XPRWRITE if this bit is set. Note that  it
  445. *-  is  perfectly  legal to call XPRWRITE even if this bit isn't set.
  446. *-  Lxpr only calls UserMon() if suitable.
  447. *-  Bit 5 : The  xpr  would  like you to use HostMon() even  when  no
  448. *-  input  from  is  received. This feature is NOT supported by Lxpr!
  449. *-  This can cause your program to be locked for an unknown time  and
  450. *-  may drain all CPU-power you have got.
  451.  
  452. *-    As  an  example  xprzmodem  returns  :  "110100"  (if  AY  was
  453. *-  requested).  The  first character ("1") says "All OK", the second
  454. *-  character ("1") indicates that the xpr doesn't need filename when
  455. *-  receiving files. The next "0"  indicates that the  protocol  need
  456. *-  filenames  (ie. you supply requester) when  sending. The last "1"
  457. *-  shows that the library want us to use XPRREAD since  it  want  to
  458. *-  check  incoming  data  (auto download). The second last zero says
  459. *-  that the library don't care what we send to the other  side  (you
  460. *-  may  still  use XPRWRITE safely) and the last zero indicates that
  461. *-  the protocol not will require a  call to HostMon() even  when  no
  462. *-  data is present (which Lxpr dosen't support)
  463.  
  464. *- WARNING! SETUP$ MUST BE NULLTERMINATED! (SETUP$=SETUP$+Chr$(0))
  465.  
  466.  
  467.  
  468.  
  469. *-  XPRREAD - Read any data that is currently available.
  470. *-  A$=Lxpr("","","",XPRREAD)
  471.  
  472. *-  where
  473.  
  474. *-     A$ will contain the data from the serial.device. Note that  if
  475. *-    the  xpr has requested HostMon() to be called the data can have
  476. *-  been modified  by the  xpr.  For  instance,  as  soon  as  zmodem
  477. *-  recognize  its  startsequence    for  download  it will start the
  478. *-  download and return an empty string and A$ will thus be empty.
  479.  
  480.  
  481.  
  482. *-  XPRWRITE - Write a string to the serial.
  483. *-  A$=Lxpr(STRING$,"","",XWRITE)
  484.  
  485. *-  where
  486.  
  487. *-     A$ always will be empty on return. Please note that if the xpr
  488. *-  has requsted XProtocolUserMon() to be called  you  can  never  be
  489. *-  sure that exactly the data you wanted to send really was sent. To
  490. *-  my knowledge there are currently no xpr available which writes to
  491. *-  your  data.  A  future  MNP-xpr however typically would need this
  492. *-  function. STRING$ is a normal textstring.
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.     BUGS:
  501.     -----
  502.        None found during my tests  against  a  few BBS's.  One  thing
  503.     could  happen  though and is nothing special to LSerial : Garbage
  504.     collection (which never happens). When using a  lot  of  strings,
  505.     AMOS once in a while need to do a garbage collection, sorting all
  506.     strings  together.  It  seems  like AMOS has very hard to see for
  507.     itself when it is time for this and strange gurus may follow.  If
  508.     this  happens  call  Free  (DUMMY=Free) once in  a while. If this
  509.     doesn't help call Free VERY often or increase the buffer  a  bit.
  510.     If  something  strange  still happens you might have found a bug,
  511.     please contact me.
  512.  
  513.        Since this is a alfa-version a lot  of  errorchecking  haven't
  514.     been put into it. It does not even check if serial.device is open
  515.     before  trying  to read (this speeds it up a bit). So if it hangs
  516.     when you try to read from a not opened device,  don't  panic  :-)
  517.     Also Lser Get doesn't check if the requested bytes are available.
  518.     This  and  more  will  be  fixed in the future. Please check your
  519.     program before reporting bugs.
  520.  
  521. *-     Also you must be warned about the Lxpr-functions which doesn't
  522. *-  bother with such trivial things like  checking  if  you  actually
  523. *-  have  a library open! Lxpr return enough "codes" for your program
  524. *-  to make sure that everything is OK before it tries  to  call  any
  525. *-  other   function.  This  is  the  way  C,  Pascal  and  assembly-
  526. *-  programmers have to work...
  527.  
  528.  
  529.  
  530.     You can reach me via : 2:203/415.3@Fidonet
  531.  
  532.     Soon available : LDOS  - A new extension with everything you ever
  533.                              wanted (well almost)
  534.                      LRexx - A new Rexx-extension making AMOS ARexx-
  535.                              compatible.
  536.  
  537.  
  538.  
  539.  
  540.  
  541.     APPENDIX A:
  542.     -----------
  543.     Errorcodes:
  544.  
  545.     0 Serial already open
  546.     1 Inavlid devicename
  547.     2 Unable to open device
  548.     3 Overflow in stringbuffer
  549.     4 Inavlid read-size
  550.  
  551.  
  552.  
  553.  
  554.     APPENDIX B:
  555.     -----------
  556.  
  557.        The FLAGS are specified when opening the device. Each funtions
  558.     is assignied to a value (or bit) and you may  add  the  different
  559.     values  together  to  select  one  or  more  options. For further
  560.     information see the docs for the serial shipped with AMOS.  NOTE:
  561.     all values are in HEX! (LISTING FROM GenAm3, edited somewhat)
  562.  
  563.     Val   Name            Meaning
  564.     ---   ----            -------
  565.     $1  = SERF_PARTY_ON  - Parity on (even if not $2)
  566.     $2  = SERF_PARTY_ODD - Odd Parity
  567.     $4  = SERF_7WIRE     - 7Wire
  568.     $8  = SERF_QUEUEDBRK - Break in background
  569.     $10 = SERF_RAD_BOOGIE- Highspeed (disables div. checks)
  570.     $20 = SERF_SHARED    - Other programs may open device
  571.     $40 = SERF_EOFMODE   - EOF recognition enabled
  572.     $80 = SERF_XDISABLED - xON/xOFF disabled
  573.  
  574.     Typically you can set FLAGS to zero.
  575.  
  576.  
  577.                                APPENDIX C:
  578.                                -----------
  579.  
  580. *-     This is sample-program which shows how to use  the  xpr's  and
  581. *-  the  serial-commands  in  general. Actually it can be used as the
  582. *-  worlds shortest communicationprogram! It supports the most common
  583. *-  ANSI-sequences via Lansi (located in  Ldos) which converts  ANSI-
  584. *-  sequences to AMOS controlcodes. The only thing we need to convert
  585. *-  before  we  send it is the cursorkey-codes which are 3 bytes long
  586. *-  in "ANSI-format"
  587.  
  588. (There are no *- in this code, so you may easily load it into AMOS)
  589.  
  590.  
  591. Set Buffer 20      : Rem 20 Kb string-space
  592. Global XSEND,XREC,XOPEN,XCLOSE,XSETUP,XREAD,XWRITE
  593. XSEND=0            : Rem These are the globals which we use
  594. XREC=1             : Rem when calling Lxpr.
  595. XOPEN=2            : Rem This way you don't have to remember which
  596. XCLOSE=3           : Rem command that belonged to which value.
  597. XSETUP=4
  598. XREAD=5
  599. XWRITE=6
  600.  
  601.  
  602. E$=Chr$($1B)+Chr$($5B) : Rem ANSI-startsequence.
  603. CU$=E$+"A"             : Rem The codes for all
  604. CD$=E$+"B"             : Rem cursormovements.
  605. CR$=E$+"C"             : Rem Up,down,left and right
  606. CL$=E$+"D"
  607. Screen Open 1,640,256,8,Hires : Rem 8 colour ANSI is enough.
  608.                               : Rem Lansi converts 16->8 automatically
  609. Flash Off
  610. Palette ,,,$FF0
  611. Paper 0
  612. Clw
  613.  
  614. Rem Open serial.device in "standard-mode" with a 8 Kb buffer
  615. Lser Open 2400,8,1,8096,250000,$20,0,"serial.device"
  616.  
  617. Rem Just shows how to use Mul Send. Try this one in 300 bps!
  618. Lser Mul Send "ATZ"+Chr$(13)
  619.  
  620.  
  621. While Not Lser Mul Check : Rem wait until all data is sent
  622.    Print "Waiting for mulsend to complete.."
  623. Wend
  624.  
  625. Centre "Press <!> to quit demo" : Print
  626. Centre "Press <?> to SEND    files with Zmodem" : Print
  627. Centre "Press <+> to RECEIVE files with Zmodem" : Print
  628.  
  629. Rem Try to open xprzmodem.library
  630. STA$=Lxpr("","","xprzmodem.library",XOPEN) : Rem open
  631. If STA$<>"OK" : Rem if STA$="OK" the call was successfull.
  632.    Print "Failed to open xprzmodem.library!"
  633.    Lser Close
  634.    End
  635. End If
  636.  
  637. Rem Initialize the library.
  638. Rem Z1=Chop files, TN=Text mode off, KY=Keep partial files
  639. Rem B4=Save buffer every 4Kb, OR=Owerwrite Resume, SN,RN=Don't send/
  640. Rem receive full paths, AY=Autoactivate (call HostMon()), E10=allow
  641. Rem 10 errors before abort.
  642. STA$=Lxpr("","Z1,TN,KY,B4,OR,SN,RN,AY,E10"+Chr$(0),"",XSETUP)
  643.  
  644. STATUS=Val(Mid$(STA$,1,1)) : Rem All OK? 0 if failed.
  645. FREQDL=Val(Mid$(STA$,2,1)) : Rem Need Freq for DL? (1 if not)
  646. FREQUL=Val(Mid$(STA$,3,1)) : Rem Need Freq for UL? (1 if not)
  647. Rem Don't care to check for User- and HostMon since we always call XREAD
  648. Rem and XWRITE and let Lxpr handle this..
  649.  
  650. If STATUS=0
  651.    Print "Failed to setup parameters..."
  652.    A$=Lxpr("","","",XCLOSE)
  653.    Lser Close
  654.    End
  655. End If
  656.  
  657. Do : Rem MainLoop
  658.    Multi Wait
  659.    A$=Inkey$
  660.    If A$="!" Then Exit 1
  661.    If A$="#" Then Clw : A$="" : Rem If the screen becomes garbled
  662.  
  663.    If A$="?"
  664.       Clw
  665.       If FREQUL=0 : Rem Do we need a filerequester?
  666.          Proc _GET_FILE : Rem If so get file(s)
  667.          A$=Param$
  668.          Print "Requested file(s): ";A$
  669.       Else
  670.          A$=""
  671.       End If
  672.       STA$=Lxpr(A$,"","",XSEND) : Rem start download
  673.       A$=""
  674.       Home : Cline : Print "Press a key!" : Wait Key : Clw
  675.    End If
  676.  
  677.    If(A$="+")
  678.       Clw
  679.       If FREQDL=0 : Rem Do we need to supply filename(s)
  680.          Proc _GET_FILE
  681.          A$=Param$
  682.          Print "Requested file(s): ";A$
  683.       Else
  684.          A$=""
  685.       End If
  686.       STA$=Lxpr(A$,"","",XREC)
  687.       Home
  688.    End If
  689.  
  690.    If A$<>"" : Rem Check for
  691.       If A$=Chr$(30) : Rem CURSOR UP
  692.          A$=CU$
  693.       End If
  694.       If A$=Chr$(31) : Rem CURSOR DOWN
  695.          A$=CD$
  696.       End If
  697.       If A$=Chr$(28) : Rem CURSOR RIGHT
  698.          A$=CR$
  699.       End If
  700.       If A$=Chr$(29) : Rem CURSOR LEFT
  701.          A$=CL$      : Rem and replace with ANSI-sequence
  702.       End If
  703.       D$=Lxpr(A$,"","",XWRITE) : Rem Send to modem
  704.    End If
  705.  
  706.    D=Free : Rem AMOS has always had problems with
  707.             Rem garbage collections. This prevents crashes
  708.             Rem when stringbuffer are use a lot.
  709.  
  710.    A$=Lxpr("","","",XREAD) : Rem is there anything to read?
  711.  
  712.    Print Lansi(A$); : Rem Convert ANSI->AMOS and print.
  713. Loop
  714.  
  715.  
  716. T$=Lxpr("","","",3) : Rem close library
  717. Lser Close          : Rem and device.
  718. Rem END OF PROGRAM
  719.  
  720. Procedure _GET_FILE
  721.    U:
  722.    Amos To Back
  723.    A$=Lfreq("Choose a file, press cancel when all are selected",$2+$4+$10+$40+$1000)
  724.    If A$="" Then Goto UT
  725.    If FILE$=""
  726.       FILE$=A$
  727.    Else
  728.       FILE$=FILE$+" "+A$
  729.    End If
  730.    Goto U
  731.    UT:
  732.    Amos To Front
  733. End Proc[FILE$+Chr$(0)]
  734.  
  735.