.TH PALMFILE 2.SH NAMEPalmfile: Categories, DBInfo, Doc, Entry, Pfile, Record \- read Palm™ file formats.SH SYNOPSIS.EXinclude "bufio.m";include "palmfile.m"; palmfile := load Palmfile Palmfile->PATH; Pfile: adt {    fname:  string;     appinfo:  array of byte;    sortinfo: array of int;     entries:  array of ref Entry;     open:   fn(name: string, mode: int): (ref Pfile, string);. #    create: fn(nil: string, mode: int, perm: int, nil: ref DBInfo): ref Pfile;    close:  fn(pf: self ref Pfile): int;    read:   fn(pf: self ref Pfile, index: int): (ref Record, string);. #    append: fn(pf: self ref Pfile, r: ref Record): int;    stat:   fn(pf: self ref Pfile): ref DBInfo;. #    wstat:  fn(pf: self ref Pfile, nil: ref DBInfo): string;. #       readid:  fn(pf: self ref Pfile, nil: int): (ref Record, string);. #       setappinfo:   fn(pf: self ref Pfile, nil: array of byte);. #       setsortinfo:  fn(pf: self ref Pfile, nil: array of int);}; DBInfo: adt {    name:    string; # database name on Palm    attr:    int;    # file attributes (defined below)    dtype:   string; # database type (byte[4])    version: int;    # version of data layout, defined by application    creator: string; # creating application (byte[4])    ctime:   int;    # creation time    mtime:   int;    # modification time    btime:   int;    # last backup    modno:   int;    # modification number    uidseed: int;    # unique record ID seed     new:     fn(name: string, attr: int, dtype: string,                   version: int, creator: string): ref DBInfo;}; Entry: adt {    id: int;        # resource: id; record: unique ID    offset: int;    # offset in file    size:   int;    # size in bytes    name:   int;    # resource entry only    attr:   int;    # record entry only}; Record: adt {    id:     int;    # resource: ID; data: unique record ID    index:  int;    # record index (origin 0)    name:   int;    # byte[4]: resource record only    attr:   int;    # attributes, defined below, data record only    cat:    int;    # category, data record only    data:   array of byte;   # content of record . #       new:    fn(size: int): ref Record;}; Categories: adt {    renamed: int;    # which categories have been renamed    labels:  array of string; # category names    uids:    array of int;    # corresponding unique IDs    lastuid: int;             # last unique ID assigned    appdata: array of byte;   # remaining application-specific data     new:     fn(labels: array of string): ref Categories;    unpack:  fn(a: array of byte): ref Categories;    pack:    fn(c: self ref Categories): array of byte;}; Doc: adt {    version:  int;    length:   int;  # uncompressed    nrec:     int;  # text records only    recsize:  int;  # uncompressed    position: int;    sizes:    array of int;   # sizes of uncompressed records     open:     fn(file: ref Pfile): (ref Doc, string);    read:     fn(doc: self ref Doc, i: int): (string, string);    iscompressed:  fn(doc: self ref Doc): int;    unpacktext: fn(doc: self ref Doc, a: array of byte):                   (string, string);    textlength: fn(doc: self ref Doc, a: array of byte): int;}; init:     fn(): string; filename: fn(s: string): string;dbname:   fn(s: string): string; gets:     fn(a: array of byte): string;puts:     fn(a: array of byte, s: string);get2:     fn(a: array of byte): int;get3:     fn(a: array of byte): int;get4:     fn(a: array of byte): int;put2:     fn(a: array of byte, v: int);put3:     fn(a: array of byte, v: int);put4:     fn(a: array of byte, v: int);.EE.SH DESCRIPTION.B Palmfileprovides read-only access to files in the Palm™ database and document formats.It currently handles three types of files:Palm Database.RB ( .pdb )files, which store data for applications;Palm Resource.RB ( .prc )files, which store code resources and user interface resource elements;andPalm Doc.RB ( .doc )files, which store compressed documents for the Palm document and e-book readers.Database and resource files have a similar structure, with slight differencesin representation, and differing mainly in how the contents are used..PP.B Initmust be called before any other function in the file.It returns a diagnostic if it cannot initialise the module..PP.B Pfilerepresents an open Palm file of any type:.TP.B open()Opens file.I namewith the given.I mode(which must currently be.BR Sys->OREAD )and returns a tuple.RI ( pf , err )..I Pfis a new.B Pfileinstance giving access to the file,or nil if the open failed, in which case the.I errstring contains a diagnostic..TP.IB pf .close()Close the file (needed only when writing to a file is eventually supported)..TP.IB pf .read( index )Returns a tuple.RI ( rec,\ err )where.I recis a.B Recordcontaining the data of the recordwith the given.I index(origin 0), ornil if no such record index exists or it cannot be read.In the latter case,.I erris a diagnostic string..TP.IB pf .stat()Return the database information for.IR pf ..TP.B entriesAn array of.B Entryvalues (see below), one per record.The length of the array is consequently the length ofthe file in records.It can be nil or empty..TP.B appinfoOptional application-specific data (see.B Categoriesbelow)..TP.B sortinfoOptional application-specific data (typicallyan array of record IDs in a chosen sorting order)..TP.B fnameFile name given to.BR Pfile.open ..PP.B DBInfogives the database information for a file:.TF creator.PD.TP.B nameDatabase name used on the Palm, maximum of 31 characters..TP.B attrA bit set of file attributes, containing the following values:.RS.TF Fappinfodirty.PD.TP.B FresourceFile is a resource file.RB ( .prc )not a database file.RB ( .pdb )..TP.B FronlyFile is read only..TP.B FappinfodirtyApplication information has changed..TP.B FbackupNo conduit program exists (the whole file must be backed up)..TP.B FoverwriteOverwrite older copy if present..TP.B FresetReset PDA after installing this file..TP.B FprivateDon't allow copy of this file to be beamed..RE.TP.B dtypeString identifying database type (up to 4 characters).It is usually the string\f5"appI"\fP for resource files..TP.B versionIdentifies the version of the data format (application specific)..TP.B creatorString identifying creating application (up to 4 characters)..TP.B ctimeFile creation time, in seconds from the Inferno epoch (see.IR daytime (2))..TP.B mtimeTime file last modified, in seconds from the epoch..TP.B btimeTime file last backed up, in seconds from the epoch..TP.B uidseedSeed for generating unique record IDs (typically set to 0 for database files,always 0 for resource files)..TP.BI new( name,\ attr,\ dtype,\ creator )Return a new.B DBInfowith the given values..PPIn some applications, it is useful to use a data base name(ie,.BR DBInfo.name )as a component of an Inferno file name.The device allows space and slash characters in names, though,which makes it hard to use the name directly..B Filenamemaps each space characterin.I sto U+00A0 (unpaddable space)and each slash character to U+2215 (`division /'),and returns the result..B Dbnamemaps the other way..SS Entries and RecordsEach record in the file is represented by an.B Entryin memory, which holds the record's essential attributes,leaving the data on file.The meaning of some of the elements depends on whetherthe file is a data file or a resource file..TF offset.PD.TP.B idResource ID, 16 bits (resource file); unique record ID, 24 bits (data file)..TP.B offsetOffset in file, in bytes..TP.B sizeSize of record in bytes..TP.B nameName of the resource (resource record only)..TP.B attrsRecord attributes (data record only):.RS.TF Rarchive.PD.TP.B RdeleteDelete the record when file next synchronised..TP.B RdirtyRecord has been modified..TP.B RinuseRecord in use (not typically used in Inferno)..TP.B RsecretRecord is secret (shown on the device only with use of a password)..TP.B RarchiveArchive this record when file next synchronised..TP.B RmcatMask for the 4-bit category field (in.B Entry.attrsonly)..RE.PPRecords read from the file are represented by a.B Recordadt containing its data and associated values.Some fields are valid only for particular classes of records..TF index.PD.TP.B idResource or record ID, as for.BR Entry ..TP.B indexIndex (origin 0) of the record in the file..TP.B nameResource name (resource record only)..TP.B attrRecord attributes, as above (data record only)..TP.B catRecord's category ID (data record only)..TP.B dataThe actual data..SS Application dataThe contents of both the ``application information'' and ``sort information'' sections of the fileare defined by an application in general.Even so, both have conventional uses with many Palm applications.The Palm software often assigns data records to particular categories (eg, ``Business'' or ``Personal''),and stores up to 16 category names and IDs in the application data in a fixed format(possibly followed by further data that is application specific).This is represented by an instance of.BR Categories ,which provides the following:.TF renamed.PD.TP.B renamedBit set indicating which categories have been renamed (for category 0, bit.BR 1<<0 ,for 1, bit.BR 1<<1 ,and so on)..TP.B labelsArray of 16 category labels..TP.B uidsArray of 16 category IDs, each in the range 0 to 255.(It is said that the Palm itself assigns 0 to 127 and desktop applications assign 128 to 255.).TP.B lastuidLast unique category ID assigned..TP.B appdataAny data that remained after unpacking the category data..TP.BI new( labels )Return a new.B Categoriesvalue for the given array of.IR labels ,assigning unique IDs to each in turn, starting from 128.There can be at most 16 labels; if there are fewer, the remaining labels will be marked as unused(empty strings)..TP.BI unpack( a )Unpack the application data in array.I a(typically.IB pf .appinfofor some.B Pfile.IR pf ),returning a reference to a new.B Categoriesinstance.A nil value is returned if the array is too short to hold valid category data..TP.IB c .pack()Pack.I cinto a form suitable for writing back to a file's application information area..PPBinary data in Palm files is typically encoded in big-endian form..B Palmfilefunctions account for that internally, but some Palm applications might usebig-endian data in their own data records.Several functions are therefore provided to decode and encode big-endian data:.BI get nretrieves an integer from the first.I nbytes of array.IR a ;.BI put nstores a big-endian representation of the value.I vin the first.I nbytes of array.IR a ..PPStrings are stored in fixed-length arrays of bytes, always terminated by a zero byte.The character encoding is (apparently) Latin-1 (ISO 8859-1), not UTF-8,so functions.B getsand.B putsare provided to convert between that representation and a Limbo string..SS Documents.B Docprovides read-only access to Palm documents and (unencrypted) e-books:.TF position.PD.TP.BI open( file )Given a.B Pfile.IR file ,return a tuple.RI ( doc,\ err )where.I docis a new.B Docinstance giving access to the document contents in.IR file .If an error occurs, in particular if.I filedoes not appear to be a valid Palm document,.I docis nil and the string.I errdiagnoses the error..TP.IB doc .iscompressed()Returns true (non-zero) if the document is compressed; returns false (zero) otherwise..TP.IB doc .read( i )Read text record with index.I i(origin 0),returning a tuple.RI ( s,\ err )where.I sis the uncompressed text for record.IR i ,or nil if the record does not exist (or there is an error reading it).On any error,.I erris a diagnostic string.Note that.I iis an index into the set of text records, and is not an index into the set of all records.It must be no greater than.IB doc .nrec ..IB doc .unpacktext( a )Returns a tuple.RI ( s,\ err )where.I sis the text in array.IR a ,after uncompressing if.I doccontains compressed records.Following Palm conventions, the text is assumed to be written in the Latin-1 encoding (ISO-8859-1).If it is compressed but the data in.I ais corrupt (cannot be uncompressed),.I sis nil and.I err

Lines 1–500 of 542. Load more