|
www.riscos.com Technical Support: |
This chapter is a collection of SWIs that convert data from one form to another. Here is a summary of the conversions that can be done:
This section leads through the details of the differing conversion calls. Whilst most are mutually independent, some SWIs may use others within this chapter to give a multi-layered functionality.
The simplest option to convert a signed 32-bit integer into a string, the most common operation, is to use OS_BinaryToDecimal.
For a far greater functionality, there is a set of 24 SWIs with a common calling convention that allow a wide ranging list of conversions. Generically, these SWIs are called OS_ConvertNameNumber. The Name refers to the destination format of the string. It can be hex, signed and unsigned integer (optionally with spaces between the thousands, millions and so on), or binary. The Number is the number of bytes to use on input. For all apart from hex, this is 1, 2, 3, or 4 bytes. Hex can be 1, 2, 4, or 8 nibbles long. See the description of these SWIs for detail.
Note that OS_BinaryToDecimal is equivalent to OS_ConvertInteger4 from these SWIs.
OS_ReadUnsigned will read a number in an ASCII string and convert it into an unsigned integer. The number in the string can be specified to be in any base from 2 to 36. Base 36 has 0 - 9, A - Z as numbers. No prefix means that the number is decimal by default, while the conventional '&' is used to indicate hex. All bases can be specified by the base_number form: eg 2_1100 is 12 in binary.
The GS operations are a way of putting any characters from 0 - 255 into a string using only the printable character set. OS_GSInit and OS_GSRead work together to scan a string on a character at a time basis. OS_GSTrans performs both these functions and scans the string. Unless you need character by character control, OS_GSTrans is easier to use.
The '|' character is used by OS_GSRead and OS_GSTrans as a flag for a special character. It affects how the character following it is interpreted. Here is a list of its effects:
| ASCII code | Symbols used |
|---|---|
| 0 | |@ |
| 1 - 26 | |letter eg |A (or |a) = ASCII 1, |M (or |m) = ASCII 13 |
| 27 | |[ or |{ |
| 28 | |\ |
| 29 | |] or |} |
| 30 | |^ or |~ |
| 31 | |_ or |' (grave accent) |
| 32 - 126 | keyboard character, except for: |
| " | |" |
| | | || |
| < | |< |
| 127 | |? |
| 128 - 255 | |!coded symbol eg ASCII 128 = |!|@ ASCII 129 = |!|A |
Note that '|!' means set the top bit of the following character, even if it is set by another '|' character.
To include leading spaces in a definition, the string must be in quotation marks, '"', which are not included in the definition. To include a single " character in the string, use |" or "".
The reason why '<' must be preceded by a '|' is that you can put values and variables inside angle brackets.
You can use the form <number>, where the number between the angle brackets will be interpreted as if it was a parameter to OS_ReadUnsigned: that is, a number in any base from 2 to 36. The value returned from this SWI will be placed as a character in the output stream; bits 8 - 31 are ignored.
A string with a name enclosed in '< >' characters will be used to look up a system variable. You must have used *Set, *SetMacro or *SetEval to set the variable. The value of the variable will be substituted for the name and the angle brackets using OS_ReadVarVal; eg if the variable 'hisname' had been set to 'Fred', then the string 'My friend's name is <hisname>' would be translated to 'My friend's name is Fred'. System variables and the calls that operate on them are described in the Program Environment.
There are options which can be used to determine the way in which the string is interpreted. This is done by setting the top three bits in R2 passed to OS_GSInit or OS_GSTrans, as follows:
| Bit | Meaning |
|---|---|
| 29 | If set then a space is treated as a string terminator |
| 30 | If set control codes are not converted (ie '|' syntax is ignored) |
| 31 | Double quotation marks '"' are not to be treated specially, ie they are not stripped around strings. |
The *Echo command will pass a string through OS_GSTrans and then send it to the display.
A string containing an expression can be evaluated. An expression consists of any of the operators listed below, brackets (for grouping), strings, and numbers. It can return a result that is a number or a string. OS_EvaluateExpression is the core routine here. It is in turn called by *Eval. This allows you to perform evaluations from the command line.
The *If command also uses this call to perform a logical decision about which * Command to perform.
Any strings in the evaluation string are passed to OS_GSTrans, so all its operators will be used. This of course means that OS_ReadUnsigned and OS_ReadVarVal will in turn be called if you use a string that requires them. Note, however, that vertical bar escape sequences (eg '|G' for ASCII 7) are not recognised.
As well as passing <name> operators in strings to OS_ReadVarVal, any item which cannot immediately be treated as a string or a number is also looked up as a system variable. For example, in the expression FRED+1, FRED will be looked up as a variable.
The operators recognised by the expression evaluator are as follows:
| + | Add two integers |
| - | Subtract two integers |
| * | Multiply two integers |
| / | Integer part of division |
| MOD | Remainder of a division |
| = | Equal | -1 is TRUE |
| <> | Not equal | 0 is FALSE |
| >= | Greater than or equal | |
| <= | Less than or equal | |
| < | Less than | |
| > | Greater than |
| >> | Arithmetic shift right |
| >>> | Logical shift right |
| << | Logical shift left |
| AND | AND |
| OR | OR |
| EOR | Exclusive OR |
| NOT | NOT |
| + | Concatenate two strings eg "HI" + "LO" = "HILO" |
| RIGHT n | Take n characters from the right eg "HELLO" RIGHT 2 = "LO" |
| LEFT n | Take n characters from the left eg "HELLO" LEFT 3 = "HEL" |
| LEN | Return the length of a string eg LEN "HELLO" = 5 |
| STR | Convert a number into a string eg STR 24 = "24" |
| VAL | Take the value of a string eg VAL "12d3" = 12 |
Where appropriate, type conversions are performed automatically. For example, if an integer is subtracted from a string, then the string is evaluated and an integer result is produced ("2"-1 gives the result 1). The null string "" is converted to 0 by both the implicit and explicit (VAL) conversions.
Similarly, integers will be converted to strings if necessary: the expression 1234 LEFT 2 will yield "12".
The operators have the same relative priorities as their equivalents in BBC BASIC, eg * is higher than + which is higher than >, etc. Remember you can use brackets to override this standard precedence.
Given a list of space separated arguments, OS_SubstituteArgs will replace references to those parameters in a string: %0 refers to the first string in the argument list and so on. This is generally used when processing command lines.
For a more powerful handling of command lines, use OS_ReadArgs. This is passed a list of parameter definitions and an input string. The parameters can be described as being in any order or in a fixed order. They can handle on/off switches (ie presence is indicated), or values. The values can also be automatically passed through OS_GSTrans or OS_EvaluateExpression if required.
Two calls can be used to translate a SWI number to and from its full name as a string. OS_SWINumberToString will convert from a SWI number to a string, and OS_SWINumberFromString will convert from a string to a SWI number.
Note that having bit 17 set will result in the string being prefixed with an 'X', and vice versa.
The pair of numbers that refer to the network number and station number can be converted into a string by OS_ConvertFixedNetStation. This will pad the string with leading zeros where required. If you don't want this padding, use OS_ConvertNetStation.
There are two SWIs that will convert a file size from an integer into a string. They can decide whether to display as bytes, Kbytes or Mbytes. OS_ConvertFileSize will convert an integer into a number up to 4 digits followed by an optional 'K' if it is in kilobytes or 'M' if in megabytes, followed by the word 'bytes' and a null to terminate.
OS_ConvertFixedFileSize is exactly the same, except that it will always print the numeric field as four characters, padding with spaces if necessary.
R0 = base in the range 2 - 36 (else 10 assumed), and flags in top 3 bits
R1 = pointer to string
R2 = maximum value if R0 bit 29 set
R0 preserved
R1 = pointer to terminator character
R2 = value
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_ReadUnsigned takes a pointer to a string and tries to convert it into an integer value which is returned in R2.
Valid strings may start with a digit (where 'digits' may also be letters, depending on the base) or one of the following:
| & | The number is in hexadecimal notation |
| base_ | The number is in a given base, where base is in the range 2 to 36. For example, 2_1010 is a base two (binary) number. |
These override any base specified in R0. (If R0 contains an illegal base, 10 is assumed.) Characters following them are read until a character is reached which is not consistent with the base in use. For example, assuming R0=10 on entry, the terminator of 43AZ is A, whereas the terminator of &43AZ is Z.
In addition, R0 contains three flags which cause checks to be performed on the terminator and the range of the number obtained:
| Bit | Meaning if set |
|---|---|
| 29 | Restrict range to 0 - R2 inclusive; a 'Number too big' error is given otherwise |
| 30 | Restrict value range to 0 - 255 |
| 31 | Check terminator is a control character or space |
If either of these checks fail, a 'Bad number' error is given. This error also occurs if the first character is not a valid digit. If a base is given at the start of the number and isn't in the range 2 - 36, a 'Bad base' error is given.
None
None
R0 = pointer to string, terminated by ASCII 10 (LF) or 13 (CR) or 0 (NUL)
R2 = flags
R0 = value to pass back in to OS_GSRead
R1 = first non-blank character
R2 = value to pass back in to OS_GSRead
Interrupt state is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_GSInit is one of the string routines which are used by the operating system command line interpreter to process the strings sent to it. One of the advantages of these routines is that they enable you to use the character '|' to introduce control characters which would otherwise be difficult to enter directly from the keyboard.
See the chapter entitled GS string operations for a list of the conversions that are performed by the routines, and of the flags passed in R2.
OS_GSInit also returns the first non-blank character in the string. However, this is not necessarily the same as the output from the first OS_GSRead, since OS_GSInit doesn't perform any expansion.
None
Returns a character from a string which has been initialised by OS_GSInit
R0 from last OS_GSRead/OS_GSInit
R2 from last OS_GSRead/OS_GSInit
R0 updated for next call to OS_GSRead
R1 = next translated character
R2 updated for next call to OS_GSRead
C flag is set if end of string reached
Interrupt state is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_GSRead reads a character from a string, using registers initialised by a OS_GSInit immediately prior to this call. The next expanded character is returned in R1. The values in R0 and R2 are updated so they are set up for the next call to OS_GSRead.
The interpretation of characters which pass through OS_GSRead is described in the GS string operations. Note that this call does not correctly handle quoted termination in RISC OS 2.
An error is returned for a bad string - for example, mismatched quotation marks.
None
Equivalent to a call to OS_GSInit and repeated calls to OS_GSRead
R0 = pointer to string, terminated by ASCII 10 (LF) or 13 (CR) or 0 (NUL)
R1 = buffer pointer
R2 = buffer size (maxlen) and flags in top 3 bits
R0 = pointer to character after terminator
R1 = pointer to buffer, or 0
R2 = number of characters in buffer, or maxlen if the buffer overflowed
C flag is set if buffer overflowed
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_GSTrans is equivalent to a call to OS_GSInit followed by repeated calls to OS_GSRead until the end of the source string is reached. Each time it obtains a character and translates it, OS_GSTrans then places it in a buffer.
The flags in R2, on entry, are the same as those supplied to OS_GSInit. On exit, R0 points to the character after the terminator of the source string, and R1+R2 points to the terminator of the translated string. If the C flag is set on exit the buffer was too small for the translated string; R2 is set to the length of the buffer.
The flags and interpretation of characters which pass through OS_GSTrans are described in the GS string operations. Note that this call does not correctly handle quoted termination in RISC OS 2.
An error is returned for a bad string - for example, mismatched quotation marks.
R0 = signed 32-bit integer
R1 = pointer to buffer
R2 = maximum length
R0, R1 preserved
R2 = number of characters given
Interrupt state is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_BinaryToDecimal takes a signed 32-bit integer in R0 and converts it to a string, placing it in the buffer. R1 points to the buffer and R2 contains its maximum length. Leading zeros are suppressed and the string will start with a minus sign, '-', if R0 was negative. The number of characters given is returned in R2.
The error 'Buffer overflow' is given if the converted string is too long to fit in the buffer.
None
None
Evaluate a string expression and return an integer or string result
R0 = pointer to string
R1 = pointer to buffer
R2 = length of buffer
R0 preserved
R1 = 0 if an integer returned, else preserved
R2 = integer result, or length of string in buffer
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_EvaluateExpression takes a string pointed to by R0, evaluates it, and returns the result. The location and type of the result is given by R1 as follows:
| Value | Meaning |
|---|---|
| 0 | Integer result returned in R2 |
| Not 0 | String is returned in buffer pointed to by R1, length returned |
| in R2, R0 and R1 preserved |
See the chapter entitled Evaluation operators for a description of the operators that you can use. Note that monadic plus/minus operators are not correctly handled in RISC OS 2 (eg *Eval 50*-3 gives a 'Missing operand' error).
The resulting string is unterminated. If the buffer is not large enough to hold it, then a 'Buffer overflow' error is generated.
None
None
R0 = SWI number
R1 = pointer to buffer
R2 = buffer length
R0, R1 preserved
R2 = length of string in buffer
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_SWINumberToString converts a SWI number to a SWI name.
The returned string is null-terminated, and starts with an X if the SWI number has bit 17 set.
SWI numbers < &200 have an 'OS_' prefix to the main part, and a SWI-dependent end section (which is 'Undefined' for unknown OS SWIs).
SWI numbers in the range &100 to &1FF are converted in the form OS_WriteI+"A", or OS_WriteI+23 if the character is not a printable one.
SWI numbers 
&200 are looked for in modules. If a suitable name is found, it is given in the form module_name or module_number, eg. Wimp_Initialise, Wimp_32. If no name is found in the modules, the string 'User' is returned.
Note that this call does not correctly handle negative SWI numbers in RISC OS 2.
None
R1 = pointer to name (which is terminated by a character 
32)
R0 = SWI number
R1 preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_SWINumberFromString converts a SWI name to a SWI number. An error is given if the SWI name is not recognized.
The conversion is as follows:
See the chapter entitled Modules for more information on how modules provide the conversion.
Note that SWI names are case sensitive, so you must spell them exactly as returned by OS_SWINumberToString.
None
R0 = pointer to argument list, and flag in top bit
R1 = pointer to buffer for result string
R2 = length of buffer
R3 = pointer to template string
R4 = length of template string
R0, R1 preserved
R2 = number of characters in result string (including the terminator)
R3, R4 preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call performs the hard work involved in substituting a list of arguments into a 'template' string. Its main use is in the processing of command Alias$... variables by the system. As it is also useful in other situations, it has been made available to users. For example, FileSwitch uses it in the processing of Alias$@LoadType_TTT variables.
The argument list is a string consisting of space-separated items which will be substituted into the template string. Spaces within double quotation marks are not counted as argument separators. Typically, the argument string will just be the tail of a * Command. It is control-character terminated.
The result of substituting the arguments into the template string is placed in the buffer. The length of the buffer is given so that the call can check for buffer overflow.
The template string is copied into the result buffer character for character. However, when a '%' appears in the template string (even within quotation marks), it marks where an argument should be placed into the output buffer. The '%' is followed by a single digit from 0 to 9. %0 stands for the first argument in the argument list, and so on. %*n means all of the arguments from the nth one onwards. %% means a single '%'. Anything else following the '%' is not treated specially, ie both the '%' and the character are copied over.
The template string does not have a terminator; instead its length is given. At the end of the substitution, any arguments after the highest one mentioned in the template string are appended to the result string. This can be stopped by setting the top bit of R0 on entry.
If a non-existent argument is specified in the template string, then a null string is substituted; no error is given.
None
None
R0 = pointer to keyword definition
R1 = pointer to input string
R2 = pointer to output buffer
R3 = size of output buffer
R0 - R2 preserved
R3 = bytes left in output buffer
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This SWI processes a command string using a keyword definition for syntax. The results are written out to the output buffer using a specialised format for this command.
The keyword definition defines the parameters that can be in the command string. It is composed of a sequence of keywords, separated by commas. Each of these is made up of one or two names, followed by a sequence of qualifiers. The syntax of a keyword is:
[keyword_name[=alias_name]][/qualifier...]
The keyword_name is what you want users to identify the parameter with. This can be any string composed of alphanumerics and the '_' character. The alias name is an optional alternative name for the same keyword. You can have a keyword with no name. See the command string description below for details of how to set it.
The qualifier describes what kind of a parameter it is. There can be as many qualifiers as you like with one parameter, but some are mutually exclusive. The qualifiers can be any one of the following characters in upper or lower case:
| /A | keyword must always be given a value |
| /K | keyword must always precede its value |
| /S | the option is a switch ie presence only is reported |
| /E | OS_EvaluateExpression will be called to transform the value. This can return a number or a string. Note that numeric evaluations only can be performed. Note that in RISC OS 2 a 'Buffer full' error is generated if this argument evaluates to a string |
| /G | OS_GSTrans will be called to transform the value |
The command string contains a sequence of commands using the syntax defined by the keyword definition. A command string is made of definitions of the following syntax:
[-keyword_name] value
If the keyword name is used, then the value will be attached to the named keyword. These can appear in any arbitrary order in the command string. The name after the '-' can be the full name of the keyword or its alias, or the first letter of either. For example, if the keyword definition contains "name=title", then all of the following are valid in the command string:
"-name fred", "-title fred", "-n fred", "-t fred"
Note that if more than one keyword has the same first letter, then the single letter form will be used by the first occurrence of a given letter in the keyword definition.
Also note that case is ignored, so "-FILE" and "-file" are identical.
If a definition has no -keyword_name preceding it, then the first unused keyword that is not a switch in the definition string will be given that value. This is how nameless keywords are set. For example, if the definition string is "infile,/a,outfile" and the command string is "-infile one -outfile two three", then the first and nameless keyword will be set to three, because it was the first undefined keyword in the definition.
Keywords are marked by a preceding '-' character, but this does not disallow these characters from appearing in values anywhere but at the start. For example, if the keyword definition is "formula/e", then "-formula 6-3" will set it to the value of 3. If the command is "-formula -3+6", then this will cause an error. Furthermore, whilst some evaluated expressions can be done without spaces (1+2 for example), there are many that cannot.
A workround for these problems is to evaluate your expression in quotes, which allow leading minuses, or spaces - as in this example:
"&3F AND &17"
With GSTrans'd strings, if you want to put a quoted string inside quotes then you must use double quotes, as follows:
"This is ""IT"""
The output buffer contains the results for all of the possible keywords. For n keywords in the keyword definition, the first n words of the output buffer contain values giving the results of parsing the command line. If the keyword was a switch (with /S qualifier), then a non-zero value indicates that the switch was used. For all other kinds of result, the value is a pointer; the actual results are appended sequentially to the output buffer. A pointer of zero indicates that the parameter was not present.
The following example uses a keyword definition of "ax,bx,on/s,cx" and a command string of "one two three -on". The output buffer looks like this:
Example output buffer
The results of GSTrans'd strings and evaluated expressions are stored differently. In a GSTrans'd string, the result pointer points to a block of the following format:
| length | two byte length |
| string | length bytes of string |
In an evaluated expression, the pointer points to a block like the following:
| type | one byte result type (which at present can only be zero for an integer) |
| value | four byte integer |
For an example showing /e and /g switches, if the keyword definition was "formula/e,time/g" and the command string was "-f 6+6-1 -t ""Time is <Sys$Time>""", then the result looks like this:
Example output buffer
Keyword definition:
number=times/e,file/k/a,expandtabs/s
can be matched by any of:
-n 10 -file jeff
-times 1+7 -file jeff -expandtabs
-file thingy -e
but not by either of:
thingy -number 4
-number 20 -times 4 -file jeff
None
R0 = value to be converted
R1 = pointer to buffer for resulting string
R2 = size of buffer
R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating null in buffer
R2 = number of free bytes in buffer
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWIs are re-entrant
This range of SWIs use a common form and can convert a number into a string in a variety of ways.
R0 returns pointing to the start of the buffer. This is convenient for calling OS_Write0. R1 points to the null at the end of the buffer. This is convenient for adding further text after it.
The Name part of the SWI name can be any of the following groups:
The Number is the number of ASCII digits in the output string, either 1, 2, 4, 6 or 8. Only enough significant bits to perform the conversion are used. The string does not include an ampersand ('&') but is padded with leading zeros, so is of fixed length. The SWIs in this group are:
| SWI name | SWI number | Output for... | |
|---|---|---|---|
| zero | largest value | ||
| OS_ConvertHex1 | &D0 | '0' | 'F' |
| OS_ConvertHex2 | &D1 | '00' | 'FF' |
| OS_ConvertHex4 | &D2 | '0000' | 'FFFF' |
| OS_ConvertHex6 | &D3 | '000000' | 'FFFFFF' |
| OS_ConvertHex8 | &D4 | '00000000' | 'FFFFFFFF' |
The Number is the number of bytes to be used from the input value. The string is not padded with zeros, so is of variable length. The SWIs in this group are:
| SWI name | SWI number | Output for... | |
|---|---|---|---|
| zero | largest value | ||
| OS_ConvertCardinal1 | &D5 | '0' | '255' |
| OS_ConvertCardinal2 | &D6 | '0' | '65535' |
| OS_ConvertCardinal3 | &D7 | '0' | '16777215' |
| OS_ConvertCardinal4 | &D8 | '0' | '4294967295' |
The Number is the number of bytes to be used from the input value. If the most significant bit is set (of the number bytes used), the number is taken to be negative, and a leading '-' is produced. The string is not padded with zeros, so is of variable length. The SWIs in this group are:
| SWI name | SWI number | Output for... | |
|---|---|---|---|
| largest -ve | largest +ve | ||
| OS_ConvertInteger1 | &D9 | '-128' | '127' |
| OS_ConvertInteger2 | &DA | '-32768' | '32767' |
| OS_ConvertInteger3 | &DB | '-8388608' | '8388607' |
| OS_ConvertInteger4 | &DC | '-2147483648' | '2147483647' |
The Number is the number of bytes to be used from the input value. The string is padded with leading zeros, so is of fixed length (number × 8). The SWIs used in this group are:
| SWI name | SWI number | Output for... |
|---|---|---|
| largest value | ||
| OS_ConvertBinary1 | &DD | '11111111' |
| OS_ConvertBinary2 | &DE | '1111111111111111' |
| OS_ConvertBinary3 | &DF | '111111111111111111111111' |
| OS_ConvertBinary4 | &E0 | '11111111111111111111111111111111' |
The Number is the number of bytes to be used from the input value. The string is not padded with zeros, so is of variable length. In addition, every three digits from the right, a space is inserted. The SWIs used in this group are:
| SWI name | SWI number | Output for... | |
|---|---|---|---|
| zero | largest value | ||
| OS_ConvertSpacedCardinal1 | &E1 | '0' | '255' |
| OS_ConvertSpacedCardinal2 | &E2 | '0' | '65 535' |
| OS_ConvertSpacedCardinal3 | &E3 | '0' | '16 777 215' |
| OS_ConvertSpacedCardinal4 | &E4 | '0' | '4 294 967 295' |
The Number is the number of bytes to be used from the input value. If the most significant bit is set (of the number bytes used), the number is taken to be negative, and a leading '-' is produced. The string is not padded with zeros, so is of variable length. In addition, every three digits from the right, a space is inserted. The SWIs in this group are:
| SWI name | SWI number | Output for... | |
|---|---|---|---|
| largest -ve | largest +ve | ||
| OS_ConvertSpacedInteger1 | &D9 | '-128' | '127' |
| OS_ConvertSpacedInteger2 | &DA | '-32 768' | '32 767' |
| OS_ConvertSpacedInteger3 | &DB | '-8 388 608' | '8 388 607' |
| OS_ConvertSpacedInteger4 | &DC | '-2 147 483 648' | '2 147 483 647' |
Convert from an Econet station/network number pair to a string
R0 = pointer to two word block (value to be converted)
R1 = pointer to buffer for resulting string
R2 = size of buffer
R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating null zero in buffer
R2 = number of free bytes in buffer
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
R0 points to two words in memory. The first word contains the station number and the second word contains the network number.
This call always converts into a form nnn.sss, where nnn is the network number and sss the station number. If the network number is zero, the first four characters are spaces; if it is non-zero, leading zeros are converted to spaces. If the network number was zero, leading zeros in the station number are converted to spaces; otherwise they are left as zeros.
R0 returns pointing to the start of the buffer. This is convenient for calling OS_Write0. R1 points to the null at the end of the buffer. This is convenient for adding further text after it.
None
Convert from an Econet station/network number pair to a string
R0 = pointer to two word block (value to be converted)
R1 = pointer to buffer for resulting string
R2 = size of buffer
R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating null in buffer
R2 = number of free bytes in buffer
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
R0 points to two words in memory. The first word contains the station number and the second word contains the network number.
This call performs the same conversion as OS_ConvertFixedNetStation, but suppresses zeros and spaces wherever possible, to yield the shortest possible string.
R0 returns pointing to the start of the buffer. This is convenient for calling OS_Write0. R1 points to the null at the end of the buffer. This is convenient for adding further text after it.
R0 = filesize in bytes
R1 = pointer to buffer
R2 = length of buffer in bytes
R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating null in buffer
R2 = number of free bytes in buffer
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This SWI will convert an integer into a filesize string of a fixed length. The format of the string is:
4_digit_number M|K|spacebytesnull
The 4_digit_number at the start is padded with spaces if it is less than four digits in length; space and null are the ASCII characters 32 and 0 respectively.
R0 returns pointing to the start of the buffer. This is convenient for calling OS_Write0. R1 points to the null at the end of the buffer. This is convenient for adding further text after it.
None
Convert an integer into a filesize string
R0 = filesize in bytes
R1 = pointer to buffer
R2 = length of buffer in bytes
R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating null in buffer
R2 = number of free bytes in buffer
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This SWI will convert an integer into a filesize string. The format of the string is:
number [M|K]bytesnull
The number at the start is up to four digits in length; null is the ASCII character 0. For small sizes the optional 'M' or 'K' is omitted.
R0 returns pointing to the start of the buffer. This is convenient for calling OS_Write0. R1 points to the null at the end of the buffer. This is convenient for adding further text after it.
Displays a string on the screen (after translating it using OS_GSTrans)
*Echo string
*Echo takes the string following it, translates it using OS_GSTrans, and then displays it on the screen.
The main use for *Echo is in command scripts, where the command provides a useful way of checking the progress of a script, especially when debugging a faulty script, or when monitoring the progress of a series of operations.
*Echo |GError!|M
None
None
None
*Eval expression
expression - any combination of the operators listed earlier
*Eval evaluates an integer, logical, bit or string expression, carrying out type conversions where necessary, in a similar way to the BASIC EVAL command. It will not handle floating point numbers. You can use *Eval to do simple arithmetic (although the desktop Calculator is easier to use for four-function arithmetic), or to evaluate more complex expressions. Programmers may find the command useful for doing 'off-line' calculations (checking on remaining space, for example).
See the chapter entitled Evaluation operators for a description of the operators that you can use. Note that monadic plus/minus operators are not correctly handled in RISC OS 2 (eg *Eval 50*-3 gives a 'Missing operand' error).
*If, *SetEval
None
Conditionally executes a * Command, depending on the value of an expression
*If expression Then command [Else command]
| expression | - an integer expression |
| command | - any valid * Command |
*If conditionally executes a * Command, depending on the value of an expression. The expression can be any integer expression, including (if necessary) variable names enclosed in angled brackets.
The expression is evaluated by the operating system's expression evaluation. If the If-expression evaluates to a non-zero value, the Then-clause is executed. If the If-expression evaluates to zero, and there is an Else-clause, the Else-clause is evaluated.
If you wish to compare a variable to a string both must be enclosed in double quotes to ensure a string comparison is performed; see the first example.
See the chapter entitled Evaluation operators for a description of the operators that you can use.
*Eval
None