Bulletin number: 315 Products affected: D705B Description: Documentation corrections for D705B user manual Component: Documentation Date: Tue Jun 26 14:26:52 BST 1990 ----- Documentation corrections for D705B User Manual. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 335) so.popen.read "If no file is opened full.len is set to zero." becomes "If no file is opened full.len and full.name are undefined, and result will not be spr.ok." Also, to be added: If the environment string referenced by path.variable.name is longer than 256 characters then result will be returned >= spr.operation.failed. ( In the next toolset this situation will be signalled by result being spr.buffer.overflow. ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 336) so.gets "... or all characters in data have been read." becomes "... or sp.max.readbuffer.size characters have been read." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 341) so.parse.command.line There are various possible error messages, most self-explanatory. However the one "called incorrectly" requires some clarificaton: it means that either option.strings was null, or SIZE option.exists, SIZE option.parameters or SIZE option.parameters.required does not equal SIZE option.strings. Also note that option.strings must be in upper case, but the command line itself is case insensitive ( i.e. -A and -a on the command line mean the same thing ). +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 343) so.time "If either time is unavailable then ..." becomes "If CUT is unavailable then ..." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 344) so.core Something not explained clearly: offset is an offset from the base of memory ( and so is non-negative ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg347) so.read.line Add the following: The characters read are in the first len bytes of line. A newline or carriage return is not included in line . +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 349) so.read.echo.hex.int ", or '%' which assumes the prefix #8000..." becomes "." Also note that only upper case hex characters are allowed. ( This will not be a restriction in the next toolset. ) See so.read.echo.any.int below. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 349) so.read.echo.any.int "or '%' which assumes the prefix #8000..." becomes "or '%' which means add MOSTNEG INT to the given hex using modulo arithmetic." ( This is how so.read.echo.hex.int will be fixed in the next toolset. ) Also note that only upper case hex characters are allowed. ( This will not be a restriction in the next toolset. ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 351) so.write.hex.int Add the following: A negative value for field is an error. ( This will also be made the case in the next occam 2 toolset for so.write.int . ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 352) so.write.real32 The m and n referred to should be the Ip and Dp of the procedure interface. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 356) so.fwrite.real32 The m and n referred to should be the Ip and Dp of the procedure interface. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 359) so.overlapped.buffer ".. but contains built in knowledge of host file server commands and..." becomes "... but ..." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 364) so.keystream.from.kbd Add on to the sentence "ticks.per.poll must not be zero." : ", unless keys are available, in which case they are read at full speed." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 364) so.keystream.from.file Replace the first sentence by "Reads lines from the specified text file and outputs them on keys.out ." In the next sentence replace "read from" by "output on". Also "Terminates automatically" becomes "Terminates automatically on error or". Then after that sentence insert "A '*c' is output to terminate a text line." The last sentence should be transformed into reading something like: The result returned can take any of the following values: spr.ok the operation was successful spr.bad.packet.size filename too large i.e. SIZE filename > sp.max.openname.size spr.bad.name null file name >= spr.operation.failed the open failed or reading the file failed +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 364) so.keystream.from.stdin "As so.keystream.from.kbd " becomes "As so.keystream.from.file ". Append to the end of the description: End of file from the keyboard will terminate this routine. The result returned can take any of the following values: spr.ok the operation was successful >= spr.operation.failed reading standard input failed +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 365) ks.keystream.to.scrstream Append "The value ft.terminated on keyboard terminates the procedure." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 365) ss.scrstream.sink Replace "the negative value ft.terminated " by "the stream terminator from ss.write.endstream ". +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 365) so.scrstream.to.file Replace the last sentence of the first paragraph by: The result returned can take any of the following values: spr.ok the data sent on scrn was successfully written to the file spr.bad.packet.size filename too large SIZE filename > sp.max.openname.size spr.bad.name null file name >= spr.operation.failed an error occurred +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg365) so.scrstream.to.stdout Append to the description: The result returned can take any of the following values: spr.ok the data sent on scrn was successfully written to standard out >= spr.operation.failed an error occurred +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 366) ss.scrstream.from.array After "data" in the last sentence insert "( except the stream terminator )". +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 367) so.scrstream.to.ANSI I think it appalling that the user is referred to the source code of the routine for extra information. Hence replace the sentence "Refer to the source ... supported" by " The following tags are ignored: st.ins.char, st.reset, st.terminate, st.help, st.initialise, st.key.raw, st.key.cooked, st.release, st.claim ." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 367) so.scrstream.to.TVI920 I think it appalling that the user is referred to the source code of the routine for extra information. Hence replace the sentence "Refer to the source ... supported" by " The following tags are ignored: st.reset, st.terminate, st.help, st.initialise, st.key.raw, st.key.cooked, st.release, st.claim ." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 368) ks.read.char Completely replace what is there by, "Returns in char the next word length quantity from source ." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 368) ks.read.int Change the last word in the sentence "char must be initialised" from "number" to "input". Add the following two sentences on to the end of the description: "The hexadecimal may be in upper or lower case. char is returned as ft.number.error if the number overflows the INT range." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 368) ks.read.real32 Add the following two sentences to the end of the description: " char must be initialised to the first character of the input. If there is an error in the syntax of the real, or if it is infinity, then char is returned as ft.number.error ." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 371) ss.write.text.line Replace the first of the two sentences by "Sends all of str to scrn , ensuring that, whether or not the last character of str is ` *c ', the last two characters sent are " *c*n "." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 372) ss.write.hex.int Add the following: a negative value for width is an error. ( This will also be made the case for ss.write.int in the next occam 2 toolset. ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 372) ss.write.real32 A complete re-write is necessary: "Converts number into an ASCII string formatted using Ip and Dp as described under REAL32TOSTRING. The converted number is sent to scrn . If the formatted form of number is larger than 40 characters then this procedure acts as an invalid process." ( The value of 40 here is going to be reduced to 24 in the next occam 2 toolset. ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 372) ss.write.real64 The first sentence is all right, but the second should be replaced by something like, "See REAL64TOSTRING for the formatting effect of Ip and Dp . If the formatted form of number is larger than 60 characters then this procedure acts as an invalid process." ( The value of 60 here is going to be reduced to 30 in the next occam 2 toolset. ) +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 383) next.word.from.line Skips leading spaces and horizontal tabs and reads the next word from the string line . The value of ptr is the starting point of the search. A word continues until a space or tab or the end of the string line is encountered. If the end of the string is reached without finding a word, the boolean ok is set to FALSE, and len is 0. If a word is found but is too large for word, then ok is set to FALSE, but len will be the length of the word that was found; otherwise the found word will be in the first len bytes of word . The index ptr is updated to be that of the space or tab immediately after the found word, or is SIZE line, whatever value of ok is set. The above is the case if ok passed in as TRUE ; however, if ok is passed in as FALSE , len is set to 0, ptr and ok remain unchanged, and word is undefined. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 383) next.int.from.line Skips leading spaces and horizontal tabs and reads the next integer from the string line . The value of ptr is the starting point of the search. The integer is considered to start with the first non-space, non-tab character found and continues until a space or tab or the end of the string line is encountered. If the first sequence of non-space, non-tab characters does not exist, does not form an integer, or forms an integer that overflows the INT range then ok is set to FALSE , and number is undefined; otherwise ok remains TRUE , and number is the integer read. A + or - may be the first character of the integer. The index ptr is updated to be that of the space or tab immediately after the found integer, or is SIZE line, whatever value of ok is set. The above is the case if ok passed in as TRUE ; however, if ok is passed in as FALSE , then ptr and ok remain unchanged, and number is undefined. +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 435) sp.send.packet "FALSE" becomes "TRUE; otherwise the packet is sent and error is set to FALSE" +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 435) sp.receive.packet "The value error is set to FALSE if the packet exceeds the maximum packet size." becomes "The received packet is in the first length bytes of packet. The value error is set to TRUE if the size of the packet received exceeds sp.max.packet.data.size; otherwise it is FALSE." +++++++++++++++++++++++++++++++++++++++++++++++++++++ (pg 352, 364) More information concerning some hostio.lib routines: so.fwrite.real32, so.write.real32, so.fwrite.real64 and so.write.real64. With these routines one specifies the parameters Ip and Dp in the same way as one does for REALxxTOSTRING. As such there are combinations of Ip, Dp and the real to be written that will result in potentially large strings. Inside the aforementioned routines a buffer is declared which is used to hold the output of REALxxTOSTRING before being passed to sp.fwrite. However, because the buffer cannot be dynamic, the language being occam, there is the possibility that the call to REALxxTOSTRING will result in the error flag being set due to the array bounds being exceeded. The magic numbers are 24 for the write.real32 case and 30 for the write.real64 case; any string hoped for that is longer than these numbers will cause the proccess to act as an invalid one. For workarounds note the two possibilities: 1) use free format only, that is, Ip = 0, Dp = 0, since one is then guaranteed not to obtain more than 15 | 24 characters for REAL32 | REAL64; 2) write ones own write.realxx routines: it is simply a matter of calling REALxxTOSTRING followed by so.write