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

CATALOG

Keyword Abbreviation Token (hex) Version(s) Classification
CATALOG C{Shift+A} D7 4.x Command and Statement
TRAP T{Shift+R} D7 3.5, 7.0 Statement
CATALOG C{Shift+A} FE 0C 7.0 Command and Statement

  Syntax   
CATALOG [ search ] [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
 
Parameters Type Legal Value(s) Default Value Note(s)
search 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  
List a "disk directory" to the current output device.

 
  Remarks  
CATALOG is identical to DIRECTORY, except for (obviously) the name and the token used to encode the keyword.  CATALOG is not available in version 3.5 but DIRECTORY is.  Unlike the similar LOAD"$" command, CATALOG does not affect the BASIC program in memory (if any).  CATALOG will always specify driveNumber in the command sent to the device (defaults to 0 if you omit it) and so you only get a listing for one drive, while LOAD without a driveNumber will list all files in both drives (assuming the device has 2 drives).
 
The biggest problem with CATALOG is the results are only sent to the active output channel (usually the text screen), so the results are not usuable by a program!  One kludgy alternative (if you have write access to a storage medium) is to OPEN a (temporary) sequential-type file for writing.  Then use CMD to direct output to that file.  Then you can open the sequential file and parse through it... yuck!  It would be faster by the way, to OPEN the $ file (the directory listing) for reading and parse it directly, but still yucky.  Note you can use the first method (CMD) to direct the CATALOG listing to a printer; although not useful for a program, humans seem to like paper listings.
 
Attempting to supply a search parameter will cause SYNTAX ERROR in version 4.0.
 
Without a search parameter, the device will usually list all files in the current directory.  The search parameter can be used to select most subsets of filenames by using wild-cards (* and ? characters).  However, SYNTAX ERROR will be generated if the first character of search is an @.  This is a bug in my opinion because a "disk" (real or some modern equivalant) can have files which begin with an @.
 
If the search has more than 16 characters then STRING TO LONG ERROR will be generated instead.  If search has zero characters then MISSING FILE NAME ERROR occurs (this is not the same as completely omitting the search parameter).
 
Most disk devices also allow your search to restrict the listing to one type of file by appending ",type" to the end of search where type is a character "C", "D", "P", "R", "S", or "U" corresponding to CBM file types of CBM (1581-partition), DEL, PRG, REL, SEQ, or USR (respectively).  However, BASIC does not allow search to be an extra 2 characters in length in such cases (16 is still the limit).  Also DEL will only select specially hacked DEL files; files that have been normally deleted (scratched) will never show up in a directory listing.
 
If no files in the (current) directory match the search or the directory has no files at all, the device will typically report only the disk name and the number of free blocks.  A "block" is a CBM file allocation unit of 256 bytes, 254 of which are available for user data in normal files.  In other words, 4 blocks are about 1 KB and 4096 blocks are about 1 MB.  The directory format uses 2-byte binary encoding of block sizes, which means the maximum size that can be reported is 65535 blocks or about 16 MB.  Some devices (like MMD / SD2IEC) allow files larger than this, so you should be suspicious when you see the number 65535 in a listing; the real value is probably larger.
 
If the device didn't like your search parameter (or perhaps the driveNumber) then typically nothing will be listed by CATALOG.  Check the device error channel with DS$ for a message.  The device might generate an error in other cases (like a physical error attempting to read the storage medium) in which case the listing may abruptly end.  In such cases BASIC will not report an error.  The "solution" is (again) check the device status with DS or DS$.
 
If 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 search).
  
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 (however ON may), 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 (R is ignored and the last unitNumber is used), and the twoChar parameter which must always be two literal characters (for CATALOG, it is ignored too, but it may not be repeated).
 
Like all disk-based commands, CATALOG restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  Like all disk-based commands, CATALOG restricts the "command string" (typically a fileName, but search in this case) to no more than 16 characters which makes it nearly useless if you want to include a path.  However most devices do not allow you to search across multiple paths anyway (I guess the file system driver of VICE would be the only exception).
 
Like all disk-based commands, CATALOG will reset DS$ and set the secret variable "DosFA" to the unitNumber.  It also indirectly updates ST.
 
Examples:
CATALOG             : REM all files on unit 8, drive 0
CATALOG "MAP*" , D1 : REM all files with name beginning with 'MAP' on unit 8 drive 1
CATALOG (S$), U(U)  : REM use variables for search and unit on drive 0
CATALOG "*=S"       : REM all SEQ files on unit 8, drive 0
 
 
  Compare With  
 
  Contrast With  
  See Also  
CMDDS, DS$, ONPRINT#ST
© H2Obsession, 2014
Comments