Tech Note 38: Using the DocLib Library

May 01, 2008
© NSB Corporation. All rights reserved.

This library was contributed by Douglas Handy.

Contents:

    Introduction
    Function Index and Quick Reference
    Function Reference

Introduction:

The Doc format for storing documents (also known as the PalmDoc format) was designed as an efficient way to store documents on handheld devices. Utilities on the desktop can be used to convert document to Doc format. They can then be downloaded to the device, viewed and manipulated by this library.

In order to use the Doc Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "Doc" for this reference name. Example:

Program's Startup code:

	Sub main()
	    LoadLibrary "DocLib", "Doc"
	End Sub

Also, in order to use the DocLib Library, the DocLib.INF file must be present in your "nsbasic\lib" directory and the DocLib.prc file must be downloaded to your device. Include it in your project by using "Add Resource" and selecting DocLib.prc.

Except for the functions that return version numbers, all the parameter and return data types are either "Integer" or "String". Version numbers are returned as a "Double". The compiler will take care of converting your variables or constants to match the size expected by the library.

Function Index and Quick Reference:


Version Information
    Version             version = Version()
    CompileInfo         compileDateTime = CompileInfo()
    Register            Register part1, part2

DOC database properties
    DocVersion          version = DocVersion(docName)
    HeaderSpare         value = HeaderSpare(docName)
    TotalLength         length = TotalLength(docName)
    TextRecordCount     count = TextRecordCount(docName)
    MaxTextRecordSize   size = MaxTextRecordSize(docName)
    CurrentPosition     pos = CurrentPosition(docName)

Text Block Functions
    GetRecordText       text = GetRecordText(docName, RRN)
    Decode              output = Decode(input)
    Encode              output = Encode(input, method)
    ReadDoc             ReadDoc docName, Position, Font, Options

DocLib Function Reference:

Version Information

The version information functions provide information about the version of the DocLib Library.

Version

	version = DocLib.Version()
Returns the version number of the DocLib Library.
Returns:
	version as Double
Example:
	Dim version as Double

	version = DL.Version()

CompileInfo

	compileDateTime = DocLib.CompileInfo()
Returns the date and time that the DocLib was compiled.
Returns:
	compileDateTime as String
Example:
	Dim compileDateTime as String

	compileDateTime = DL.CompileInfo()

Register

	DocLib.Register part1, part2
Validates the registration code. This function is deprecated and no longer required, though it is included for backward compatibility with previous releases.
Parameters:
	part1 as String
	       Registration Code part one (case sensitive).

	part2 as String
	       Registration Code part two (case sensitive).
Example:
	Dim part1 as String
	Dim part2 as String

	DL.Register part1, part2
This function should be called prior to attempting any other activity, or demo evaluation mode is assumed. This function is deprecated and no longer required, though it is included for backward compatibility with previous releases.

DOC database properties

This collection of routines provides information on the properties of a specific DOC database.

DocVersion

	version = DocLib.DocVersion(docName)
Determines if a doc database is compressed or not.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	version as Integer
	       One of the following values:
	          0 = Database not found or is not DOC compatible
	          1 = Uncompressed doc
	          2 = Compressed using DOC text format
Example:
	Dim version as Integer
	Dim docName as String

	version = DL.DocVersion(docName)

HeaderSpare

	value = DocLib.HeaderSpare(docName)
Determines if a doc database is compressed or not.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	value as Integer
	       One of the following values:
	          0 = Database not found or is not DOC compatible
	          1 = Uncompressed doc
	          2 = Compressed using DOC text format
Example:
	Dim value as Integer
	Dim docName as String

	value = DL.HeaderSpare(docName)
Compression format is documented at www.pyrite.org/doc_format.html

TotalLength

	length = DocLib.TotalLength(docName)
Determines the total uncompressed length of text in a document.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	length as Integer
	       Uncompressed length of all text in the document.
Example:
	Dim length as Integer
	Dim docName as String

	length = DL.TotalLength(docName)

TextRecordCount

	count = DocLib.TextRecordCount(docName)
Determines the total uncompressed length of text in a document.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	count as Integer
	       Uncompressed length of all text in the document.
Example:
	Dim count as Integer
	Dim docName as String

	count = DL.TextRecordCount(docName)

MaxTextRecordSize

	size = DocLib.MaxTextRecordSize(docName)
Determines the max uncompressed size of a record in the document.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	size as Integer
	       Maximum uncompressed size of a single doc record.
Example:
	Dim size as Integer
	Dim docName as String

	size = DL.MaxTextRecordSize(docName)
Typically, this value will be 4096 in standard DOC pdbs.

CurrentPosition

	pos = DocLib.CurrentPosition(docName)
Determines the max uncompressed size of a record in the document.
Parameter:
	docName as String
	       Name of DOC style database to be checked.
Returns:
	pos as Integer
	       Maximum uncompressed size of a single doc record.
Example:
	Dim pos as Integer
	Dim docName as String

	pos = DL.CurrentPosition(docName)
Typically, this value will be 4096 in standard DOC pdbs.

Text Block Functions

The text block functions work on discrete blocks of text, such as a specific record in a DOC database.

GetRecordText

	text = DocLib.GetRecordText(docName, RRN)
Retrieve the text of a given record in a DOC database, uncompressing if necessary.
Parameters:
	docName as String
	       Name of DOC style database.
	RRN as Integer
	       Relative record number of the text block to retrieve.
Returns:
	text as String
	       Uncompressed contents of record block.
Example:
	Dim text as String
	Dim docName as String
	Dim RRN as Integer

	text = DL.GetRecordText(docName, RRN)

Decode

	output = DocLib.Decode(input)
Decode a DOC style compressed block into plain text.
Parameter:
	input as String
	       Input string conforming to DOC compression options.  Typically
	       this will have been obtained from a previous call to Encode()
	       below, and
Returns:
	output as String
	       Uncompressed contents of string.
Example:
	Dim output as String
	Dim input as String

	output = DL.Decode(input)

Encode

	output = DocLib.Encode(input, method)
Encodes plain text into DOC style compression.
Parameters:
	input as String
	       Input string containing data to get compressed.  This can be
	       any size up to the 32K limit for strings in NS Basic.  When
	       using encoding methods other than zero, the length will have
	       a dramatic impact on performance (or lack of it) as it searches
	       for repeating sequences of characters.  The DOC de facto standard
	       is to limit blocks to 4K of text, but that is not a requirement
	       of this library.
	method as Integer
	       Method of encoding to be performed:
	          0 = Blank compression (fastest, average 15-20% reduction)
	          1 = DOC style compression but with nulls eliminated
	          2 = Full DOC compatibility (do not use from NS Basic)
Returns:
	output as String
	       Compressed version of input.  For encoding method 2, this is
	       a buffer and not a null-terminated string.
Example:
	Dim output as String
	Dim input as String
	Dim method as Integer

	output = DL.Encode(input, method)

ReadDoc

	DocLib.ReadDoc docName, Position, Font, Options
Display a DOC database using a mini DOC reader. The library provides complete control over the DOC reader while it is in use. When the user taps Done, the library call will return.
Parameters:
	docName as String
	       Name of DOC compatible database.

	Position as Integer
	       Starting byte position within document.  Special values:

	          -1 = DOC header's last known position.
	           0 = Top of the document
	         xxx = Start at approximately the byte position requested

	Font as Integer
	       Font number requested.  Should be one of the following:

	          -1 = Last known preference
	           0 = Standard font
	           1 = Bold font
	           2 = Large font
	           7 = Large bold font

	Options as Integer
	       Options desired.  Add together the appropriate values:

		   1 = Strip carriage returns
		   2 = Allow jump by percentage
		   3 = Allow font change
		   4 = Allow copy to clipboard
		   8 = Show existing bookmarks
		  16 = Scan for auto-bookmarks (not implemented yet)
	          32 = Auto scan for bookmarks
	          64 = Force scan for bookmarks
	         128 = Show long bookmark names
	         256 = No modal border
	         512 = No title bar
Example:
	Dim docName as String
	Dim Position as Integer
	Dim Font as Integer
	Dim Options as Integer

	DL.ReadDoc docName, Position, Font, Options