Difference between revisions of "GSINIT"

From BeebWiki
Jump to: navigation, search
m (Initial holding page)
 
m (zero flag sense)
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category:MOS API]]
 
[[Category:MOS API]]
 +
Initialize to read a string
 +
 +
==Specification==
 +
{| cellpadding="0" cellspacing="0"
 +
|  6502  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 +
|- align="center" valign="top"
 +
| Z || align="left" | undefined || align="left" | NE = String is non-empty or quoted<br>EQ = String is empty and unquoted
 +
|- align="center" valign="top"
 +
| Cy || align="left" | CC = Space or CR terminates unquoted string&nbsp;&nbsp;<br>CS = CR terminates unquoted string || align="left" | undefined
 +
|- align="center" valign="top"
 +
| A || align="left" | undefined || align="left" | First character of string; =&0D if string empty and unquoted
 +
|- align="center" valign="top"
 +
| X || align="left" | undefined || align="left" | preserved
 +
|- align="center" valign="top"
 +
| Y || align="left" | Offset of first character to scan || align="left" | Offset of first character of string
 +
|- align="center" valign="top"
 +
| (&F2),Y&nbsp;&nbsp; || align="left" | Points to start of string || align="left" | (&F2) preserved, Y updated
 +
|}
 +
 +
Prepares [[GSREAD]] to read a string from a character array. The string may
 +
be enclosed in double quotes (<tt>"</tt>) in which case spaces in the string
 +
are preserved. The string may also contain control codes and high-order
 +
characters encoded with an escape sequence.
 +
 +
GSINIT starts at the position given by (&F2),Y and scans forward, incrementing Y
 +
until a character other than space or [[VDU 13|CR]] is found.
 +
 +
If the string begins with <tt>"</tt> then &22 is returned in A and
 +
(&F2),Y points to the character after the <tt>"</tt>. In this case the
 +
Carry flag input to GSINIT has no effect, GSREAD will return characters
 +
until the closing <tt>"</tt> is reached. A CR encountered before the closing
 +
<tt>"</tt> causes error &FD, '''Bad string'''.
 +
 +
Otherwise (&F2),Y points to the first non-space character, which is
 +
returned in A. The Zero flag returns EQ if this is CR, indicating an empty,
 +
unquoted string. GSREAD will return characters until CR is reached, or also
 +
space if GSINIT was called with Carry Clear.
 +
 +
While processing a command line, the Zero flag set to NE on exit from GSINIT
 +
indicates that an argument is present. When the first call to GSREAD returns
 +
Carry Set, the flag from GSINIT distinguishes between an empty argument and
 +
no argument.
 +
 +
It is safe to call GSREAD at least once following GSINIT. However, after
 +
GSREAD returns Carry Set it must not be called again without an intervening
 +
GSINIT; otherwise, overshooting a closing <tt>"</tt> and reaching CR also
 +
raises a '''Bad string''' error.
 +
 +
;Note
 +
The character returned by GSINIT is ''not'' necessarily the character
 +
returned by the first call to [[GSREAD]].
 +
 +
==Entry points==
 +
* 6502 Entry Address: &FFC2 (I/O processor only)
 +
 +
[[User:Regregex|Regregex]] ([[User talk:Regregex|talk]]) 17:53, 11 January 2019 (CET)

Latest revision as of 14:07, 20 October 2020

Initialize to read a string

Specification

 6502  On entry: On exit:
Z undefined NE = String is non-empty or quoted
EQ = String is empty and unquoted
Cy CC = Space or CR terminates unquoted string  
CS = CR terminates unquoted string
undefined
A undefined First character of string; =&0D if string empty and unquoted
X undefined preserved
Y Offset of first character to scan Offset of first character of string
(&F2),Y   Points to start of string (&F2) preserved, Y updated

Prepares GSREAD to read a string from a character array. The string may be enclosed in double quotes (") in which case spaces in the string are preserved. The string may also contain control codes and high-order characters encoded with an escape sequence.

GSINIT starts at the position given by (&F2),Y and scans forward, incrementing Y until a character other than space or CR is found.

If the string begins with " then &22 is returned in A and (&F2),Y points to the character after the ". In this case the Carry flag input to GSINIT has no effect, GSREAD will return characters until the closing " is reached. A CR encountered before the closing " causes error &FD, Bad string.

Otherwise (&F2),Y points to the first non-space character, which is returned in A. The Zero flag returns EQ if this is CR, indicating an empty, unquoted string. GSREAD will return characters until CR is reached, or also space if GSINIT was called with Carry Clear.

While processing a command line, the Zero flag set to NE on exit from GSINIT indicates that an argument is present. When the first call to GSREAD returns Carry Set, the flag from GSINIT distinguishes between an empty argument and no argument.

It is safe to call GSREAD at least once following GSINIT. However, after GSREAD returns Carry Set it must not be called again without an intervening GSINIT; otherwise, overshooting a closing " and reaching CR also raises a Bad string error.

Note

The character returned by GSINIT is not necessarily the character returned by the first call to GSREAD.

Entry points

  • 6502 Entry Address: &FFC2 (I/O processor only)

Regregex (talk) 17:53, 11 January 2019 (CET)