Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

APPEND

Keyword Abbreviation Token (hex) Version(s) Classification
APPEND A{Shift+P} D4 4.x Command and Statement
INSTR IN{Shift+S} D4 3.5, 7.0 Command and Statement
APPEND A{Shift+P} FE 0E 7.0 Command and Statement

  Syntax   
APPEND # fileNumber , fileName [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
 
Parameters Type Legal Value(s) Default Value Note(s)
fileNumber Unsigned Byte 1 ~ 255 Non-literal must be enclosed in parentheses ().  Value should be less than 128.
fileName String  1~16 characters    Non-literal must be enclosed in parentheses () 
driveNumber Integer  0 or 1  Non-literal must be enclosed in parentheses ()
unitNumber Integer  8 ~ 11  Non-literal must be enclosed in parentheses () 
twoChar Char[2]  any    Must be two literal characters. 
 
 
  Purpose  
File input/output.  Open an existing (PRG, SEQ, or USR) file on disk, in "write mode" and position the file pointer to the end of the exisiting file

 
  Remarks  
APPEND is typically used with SEQ files, although it usually works with PRG and "standard" USR files (not the hacked GEOS "VLIR" files).  Most "disk drives" will give an error with a REL file, CBM "file", DEL file, or DIR "file".  It's purpose is to allow data to be added to the end of an existing file.  Once this command succeeds, but before any data can be written by BASIC, the device will position its "file data pointer" to the end of the exisiting file.
 
The fileNumber must be preceded by an octothorpe (#).  It will be needed for subsequent BASIC statements; in particular PRINT# for writing (appending) data to the file.
 
If the fileName does not already exist, the device will normally generate an error "62, FILE NOT FOUND,00,00" (a few devices might actually create a new file).  In any case, BASIC will not generate an error in this case (however if you later try to write to the file you will get an error).  The device might generate an error in other cases(like a non-disk device, or a write-protected disk).  Be sure to check the device status with DS or DS$.
 
If the fileName has more than 16 characters then STRING TO LONG ERROR will be generated instead.  If the fileName has zero characters then MISSING FILE NAME ERROR occurs.  The fileName may include wild-card characters like ? and *.  If the fileName begins with an @ character, SYNTAX ERROR occurs.
 
If a required parameter is omitted, or an expression (enclosed in parentheses) is not valid, or an expression is used without parentheses, SYNTAX ERROR occurs.  If any parameter is not the correct type (string or numeric) a TYPE MISMATCH ERROR will be generated.  Otherwise if a parameter is not a legal value (see table above), an ILLEGAL QUANTITY ERROR is usually generated (except the previosuly described fileName).
  
Like all disk commands and statements, the Syntax is more flexible than shown above.  In particular, the parameters may be given in any order.  The general restrictions are: a comma (,) must not precede the first parameter, any non-literal value (a variable name or expression) must be enclosed in parentheses (), and do not supply the same parameter more than once.  Exceptions include the U and R parameters, which may used an unlimited number of times (the R is ignored), and the twoChar parameter which must always be two literal characters (for APPEND, it is ignored too, but it may not be repeated).
 
Like all disk-based commands, APPEND restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  Like all disk-based commands, APPEND restricts the fileName to no more than 16 characters (17 if the first is @) which makes it nearly useless if you want to include a path.
 
Like all disk-based commands, APPEND will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to 8 if not given).  It also indirectly updates ST.
 
The original ROMs of the C128 (start-up message says copyright 1985) have an obscure bug.  When this command completes, it closes a "random" file, which is usually file# 199 (hexadecimal $c7); this seems to be the reading from the CIA register that controls the serial bus and VIC bank.  Unless you are using file# 199, this should not be a problem (in rare cases the file# might be different).
 
Examples:
APPEND #2, "EXISTING FILE" : REM disk unit 8, drive 0
APPEND "EXISTING FILE", #2 : REM same thing
APPEND #(F), (N$)          : REM use variables for fileNumber and fileName
APPEND #2, "EXISTING FILE", U(U) : REM variable disk unit, drive 0
 
 
  Compare With  
 
  Contrast With  
  See Also  
CMDDS, DS$, ONPRINT#ST
© H2Obsession, 2014
Comments