These commands are provided to set or manipulate the contents of
Scripta variables of type STRING. Such variables are considered to
be AsciiZ strings. That is to say, the contents are terminated by an
Ascii 0 (NUL) character, unless the contained string is exactly 200
bytes in length (this is the maximum length of a Scripta STRING).

In general, STRING handling functions are much more efficient when
used with 'proper' AsciiZ strings. Therefore, whilst it is not vital
to do so, it is best to avoid strings of exactly 200 bytes, except
when used in conjunction with the File Input/Output functions FREAD
and FWRITE.

In discussions of 'position' within a string, the first character in
the string is always character 0 (zero).

The notation <string> is used to denote a value which may be either
a STRING variable or a string literal.


$INSERT %string_variable <string> <position>

Inserts <string> at <position> within %string_variable.

e.g.,       %name := "Gale Green"
            %middles := "Norman James "
            %pos := 5
            $insert %name %middles %pos

This totally useless piece of script would give the variable %name
the value "Gale Norman James Green"


$DELETE %string_variable <position> <number_of_chars>

e.g.,       %name := "Gale Norman James Green"
            %pos := 5
            $delete %name %pos 13

would leave the value "Gale Green" in the variable %name.


$APPEND %string_variable <string>

appends the contents of <string> to the contents of
%string_variable.

e.g.,       %first := "Gale"
            %last := "Green"
            $append %first " "
            $append %first %last

would leave the value "Gale Green" in the variable %first.


$SLICE %string_variable <string> <position> <number_of_chars>

sets the contents of %string_variable equal to a slice of <string>,
<number_of_chars> in length and starting at <position> within
<string>.

e.g.,       %name := "Gale Norman James Green"
            $slice %first %name 0 4
            $slice %last %name 18 5

sets %first equal to "Gale" and sets %last equal to "Green".


$POS %int_variable <string1> <string2>

sets %int_variable to the starting position withing <string1> of the 
left-most occurrence of <string2>.

e.g.,       %rubbish := "abcdefdef"
            $pos %posn %rubbish "de"

sets %posn to the value 3.

If <string2> does not occur within <string1> then %int_variable is
set to %MAXINT.


$CHPOS %int_variable <string> <character>

This is exactly like $POS except that the search is for a single
character rather than for a substring of <string>.

e.g.,       %junk := "abcdef"
            $chpos %where %junk "e"

sets %where to the value 4.

If <character> is a string of two or more characters then only the
first character is used.

If <character> does not appear in <string> then %int_variable is set
to %MAXINT.


$RCHPOS %int_variable <string> <character>

This is exactly like $CHPOS except that the value returned in
%int_variable is the position of the right_most occurrence of
<character>, instead of the left-most.

e.g.,       %junk := "abcabcabc"
            $rchpos %pointer %junk a

sets %pointer to the value 6.

If <character> does not appear in <string> then %int_variable is set
to the value %MAXINT.


$COMPARE %int_variable <string1> <string2>

places in %int_variable the result of a comparison between <string1>
and <string2>. Comparison is character-by-character, starting with
the left-most character of each string. Comparison of characters
continues until either the end of one of the strings is reached or
an inequality is found.

If the end of one of the strings is reached with no inequality having been
found then the shorter string is deemed to be 'less than' the longer string.
i.e., "FRED" is 'less than' "FREDDIE".

%int_variable is set as follows:
-1   string1 is less than string2
+1   string2 is less than string1
0    the strings are identical

The comparison is case sensitive. That is to say, "a" is not equal to "A".


$CAPS %string_variable

Lower case alphabetic characters in %string_variable are changed to their
upper case equivalents. All other characters remain unchanged.


$GETLINE/<maximum_seconds> %string_variable <maximum_length>

This command allows you to read a string of characters transmitted
by or from the remote service into %string_variable.

Normally, all such characters are placed within Scripta's internal
buffers. When $GETLINE is being executed, characters received from
the remote computer are instead placed sequentially in
%string_variable until one of the following conditions is met:

       -  <maximum_seconds> has expired. If <maximum_seconds> is not 
          specified then no time limit is set and characters are
          placed in %string_variable until one of the other
          conditions is met.

       -  <maximum_length> characters have been received. This
          length must be supplied and must be less than 200.

       -  a Carriage Return (Ascii 13) character has been received.
          This character is NOT placed in %string_variable.

The actual number of characters received and placed in
%string_variable is set into the system variable %SYSLEN.
