Introduction:

In order to use the DocShared 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 Shared Library, the DocLib.INF file must be present in your "nsbasic\lib" directory and the DocLib.prc file must be downloaded to your device. When using NSB/Palm v4, you may alternatively include it in your compiled PRC by using "Add Resource", selecting DocLib.prc, and changing the assigned property type of "libr".

DocLib Function Reference:

Version Information

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

Version

	version = DocLib.Version()

Returns the version number of the DocLib Shared 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. The database must conform to the the de facto standard format as described at www.pyrite.org/doc_format.html

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)

With NSB v4.x, it is not necessary to prefill the return string with dummy data to the maximum expected size. In NSB v3 though, the string variable used to return the text should be pre-allocated in NSB/Palm to the maximum length expected. This is 4096 in a standard DOC pdb, but the size may be verified first using MaxTextRecordSize() in this library. size = doc.MaxTextRecordSize( "MyDocPdb" ) text = RightPad( "", size )

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)

With NSB v4.x, it is not necessary to prefill the return string with dummy data to the maximum expected size. In NSB v3 though, the string variable used to return the text should be pre-allocated in NSB/Palm to the maximum length expected. This is 4096 in a standard DOC pdb.

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 NSB/Palm.  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 NSB/Palm)

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)

With NSB v4.x, it is not necessary to prefill the return string with dummy data to the maximum expected size. In NSB v3 though, the string variable used to return the text should be pre-allocated in NSB/Palm to the maximum length expected.

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