home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / comms / x_sun_psio / code / programers.notes < prev    next >
Encoding:
Text File  |  1995-03-29  |  8.7 KB  |  156 lines
  1. Well, you've decided to try looking at the code for this little set of
  2. programs have you, Good luck, you'll need it
  3.  
  4. Outline program description
  5. There are two components, psion which is a program that runs on the
  6. sun and is composed of a number of source files under the code
  7. directory and suncom which is a program that runs on the psion and is
  8. comprised of one source code file in the suncom directory
  9.  
  10. Compilation
  11. The psion program should just compile directly on a Solaris 2.x
  12. machine and it should compile on a Solaris 1 machine, just ensure that
  13. you have all the files from the SCCS (if you have the full source) and
  14. use the Makefile provided. I haven't put any clever things in place
  15. like auto conf files etc to handle different vendors machines as I
  16. only have access to Sun machines (Well what do you expect for a Sun
  17. employe)
  18. The suncom program needs to be compiled in a different way because
  19. unix and dos have different understandings of how lines end (CR/LF vs
  20. CR) and I write the suncom program on the Sun and manage it under SCCS
  21. the first stage is to convert the end of line stuff. Suns have a
  22. program called unix2dos that does this. If your machine does not
  23. support this it should have something equivalent (assuming its a real
  24. unix machine). Once the program has been converted it needs to be
  25. compiled using the psion software development environment (Available
  26. from psion for around 300 pounds I think) I do this using SunPC a pc
  27. emulation  which runs on my workstation. to compile suncom just type
  28. tsc /m suncom (assuming the compilers, redirect files etc are
  29. correctly setup) and it will produce the file suncom.img. I then cheat
  30. a little for ease of use and transfer the suncom.img file to the psion
  31. using the psion mclink software, also running under the pc emulation,
  32. it's just quicker and easier as I already have the PC emulation up and
  33. running, certainly there are other ways, older versions of suncom or
  34. xmodem could equaly well be used
  35.  
  36. Protocols
  37. A brief description of the protocols used betweern the sun and psion
  38. (low and high level) is provided in the file protocols in the code
  39. directory.
  40.  
  41. Suncom internal structure
  42. Suncom is a very simple program it is intended to be used as a server
  43. process. The main code routine gets a line of data representing the
  44. command (a two character string) and then runs through a very large
  45. set of if statements (effectivly this is realy a switch) to determine
  46. which function to call.
  47. One critical point to note is that most commands dont have an
  48. associated path name, they rely instead on a pathname (the string is
  49. sunname internaly) that is set using another call. This should in
  50. theory reduce the data transfered is a sequence of commands are called
  51. that use the same pathname (e.g. file status, file size, get is a
  52. reasonable sequence)
  53. You should nots that some routines inside suncom are left over and
  54. don't get called by the current version of psion. They are left in
  55. there for compatibility with older versions of the same release or are
  56. just there due to me being lazy and not removing them.
  57.  
  58. Psion internal structure
  59. The internal structure of the psion program is somewhat more
  60. complicated. There are a set of routines matching the suncom routines
  61. to do the low level transfers, These are all named with the two letter
  62. command code preceded by the letters ps. There are also higher level
  63. routines that call multiple lower lefel commands, for example to send
  64. a file to the psion the file must be removed on the pasion if it
  65. exists before the transfer occurs thus the put foutines check the
  66. files existance, remove it if required and then transfer the new file.
  67. All the routines that talk directy to the psion and their immediate
  68. higher level routings are in the pslib.c file
  69. The main code section is in the psmain.c file. This consists of the
  70. command interpreter and the internal routines it calls. These routines
  71. are prefixed with the characters cm.
  72. The command interpreter is designed to be easily extensibe, The commands 
  73. are defined in a list containing the text of the command string, the 
  74. function to call, the number of arguments the function can take (max and 
  75. min) allong with information on usage and help. The interpreter recieves 
  76. a string, breaks it down into arguments, does variable substiution and 
  77. then calls the specified function. (See the man page for more information 
  78. on this process). The command interpreter uses the unix argc and argv process
  79. to transfer parameters.
  80. Variables are held in a linked list comprising of the variable name and its value
  81. There issupport for multiple levels of variables allowing scripts to have their
  82. own sets of variables. This is implemented by having a linked list of variable
  83. levels, When a script is run a new level is created and variables are copied from
  84. the previous level to act as a starting point. Once the script is completed the
  85. current level of variables is destroyed and the previous level is used.
  86. The code for variables is in the file psvar.c
  87. File filters allowing automatic file conversion are also held in a linked list
  88. This is a single linked list and does not get duplicated when a script is 
  89. started. The code for this list is held in the file psfilt.c
  90. The bacup code is held in the file psbackup.c This provides support for building
  91. a recursive list of files to backup and then operates on this list.
  92. The backup subsystem allows for the setting of excludsed files. These are also held
  93. in a linked list that does not get duplicated when scripts are run. The code to 
  94. support this is in the file psexclude.c
  95.  
  96. Programming notes
  97. If adding additional functions the existing structure should be followed. To 
  98. protect against differing versions of pson and suncom new psion functions 
  99. should have checks to compare the version number of the suncom with the 
  100. required version. Code is provided to compare these (psvsncmp etc) Examples
  101. of this are provided in the cmcs code which checks that suncom has support
  102. for checksums.
  103.  
  104. Unused code
  105. Looking at the code directory you will note that these is some code that
  106. provides functionality that is not available from the command interpreter.
  107. The best example of this is the code in psxmodem.c In most cases this is
  108. code that is is the process of being developed but has not yet been gotten
  109. working but has been integreated. Please feel free to play with this code
  110. but be warned, it may do some nasty things to either filesystem of the 
  111. internal data structures of the programs
  112.  
  113. Program Modifications
  114. The entire code is held under SCCS. If you are intending to modify or 
  115. enhance the functionality of the system you will need the SCCS directories
  116. to help manage this, I would suggest thay you create a seperate SCCS branch.
  117. If you are just going to compile the code on your machine you will only need 
  118. the smallcource distribution.
  119. If you add aditioinal functionality or fixes to the system I would be
  120. interested to know about the changes you make and integrate them into
  121. the next release. If a funcation is usefull to you it may be of use to
  122. others.
  123. One modification area I'd be very interested in is if anyone feels like 
  124. taking on the challenge of creating a decent command interpreter or
  125. integrating the code into tcl (I'm afraid that I onbly hack this code 
  126. around in my spare time, being a Sun SE it somewhat time consuming!)
  127.  
  128. Porting to other platforms
  129. This code should port to any SVR4 based system with no changes and should
  130. conmpile and run on BSD based systems. The only area that may cause 
  131. difficulties is in the psinitline code. This may contain ioctl settings 
  132. that are non portable. I know that SGI machines have some problems with these
  133. and I'm not entirly sure that these settings come from BSD or SVR4.
  134.  
  135. Support
  136. This is a unsupported product. Whilst I will try to help fix bugs and 
  137. provide limited porting support I can't guarentee it. I will definatly 
  138. try to help if people want to extend te functionality.
  139.  
  140. Future compatibility
  141. I try to guarentee that minor version changes of psion and suncom will be 
  142. compatable. I.e. if a new function is added to psion it checks that the 
  143. version of suncom supports the functionality. Major version number changes
  144. can mean that anything changes usualy the low level protocols though this is
  145. minimised if possible. For moving between V2.x and V3.x for example the low 
  146. level protocol was reved to provide limited checksum support. However
  147. it a new checksum format was implemented this would not nessiceraly require
  148. a major version number. The protocol would start using the existing protocol
  149. check that suncom supported the new checksum and then issued a command to
  150. switch to the new checksum mechanism.
  151. If you are interested the difference between V1 and V2 was that the 
  152. script language moved from setting the drive, directory and filename seperatly
  153. to settinbg them at once. This means that script files had to be changed
  154. as well as the protocol. For V2 to V3 the scripting language remained the
  155. same
  156.