HiTest 1.0 Reference .0 Reference C:\NOTES\hitest.nsf Class$Collation$TITLE$ CN=Scott Prager/O=Edge Research < < L sJa}R 7qSJP tghOl F9R)" 4Q!3'$ -Default- CN=Scott Prager/O=Edge Research L]P=6>mh < ;#C ,Fl=} ihA[* L]P=6>mh ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ######################################################## ########################################################## MainSectionGlossary############# ######################################################## FunctionsCN=Scott Prager/O=Edge ResearchF Object Description Object Description of the Object" object Summary ObjectSubject$0$1$Conflict$REF Object Function Comment Object$0 ObjectObjectSubject$0NameZ Object Description $1Summaryn Object Description of the Object" object Summary 534Arial### FunctionCN=Scott Prager/O=Edge ResearchC SeeAlsoExampleReturnsParametersDescriptionSyntaxSummaryNameObject################################################### CN=Scott Prager/O=Edge Research """"""" """"""" DDDDDD DDDDDD DDDDDD ObjectCN=Scott Prager/O=Edge ResearchC DescriptionObject########################################### SectionCN=Scott Prager/O=Edge ResearchC ContentsSectionChapter########################### All DocumentsCN=Scott Prager/O=Edge Research Section Chapter Chapter MainSection Chapter Object Object" Section Section MainSection Chapter Object Description Object Description of the Object" object Summary $1Subject$0$2$Conflict$REF Section Chapter Chapter MainSection Chapter Object Object" Subject$0Title Section Section MainSection Chapter Object Description $2Summaryn Object Description of the Object" object Summary 534Arial ######################## GuideCN=Scott Prager/O=Edge Research Section Section Chapter ChapterSubject$3$Conflict$REF Section MainSection Comment Chapter$3 ChapterChapterSubject$3SectionJ Section Section Chapter 534Arial################################ CN=Scott Prager/O=Edge Research######################################################### CN=Scott Prager/O=Edge Research######################################################### CommentCN=Scott Prager/O=Edge Research BodySubjectDateComposedFrom##################### MainSectionCN=Scott Prager/O=Edge ResearchC ContentsChapter######################################## sJa}R $Modified $TITLE$FormPrivs$FormUsers$Body$Flags$Class$Modified$Comment $TITLE ################################# Section1.1 General1. Overview of HiTest############################################### Section1.2 Benefits1. Overview of HiTest############################################## Section1. Overview of HiTest1.3 Basic Structure ########### Section2.1 Installation2. Installing HiTest########################################### Section2.2 Samples2. Installing HiTest################################################ Section3.1 Requirements3. Programming to the HiTest API############################### ########################################################## ########################################################## ########################################################## Section3.3 Data Types3. Programming to the HiTest API################################# Section3. Programming to the HiTest API3.4 Context ######## Section3.5 Error Handling3. Programming to the HiTest API############################# Section3.6 Mixing HiTest with the standard Notes API3. Programming to the HiTest API## Section4.1 Overview4. HiTest Functions################################################ Object(Global)################## ObjectAddin##################### FunctionhtConvertConverts data between data types. Converts data between HiTest data types. HiTest writes the converted data into a supplied buffer, and optionally returns the new length. HiTest supports conversion between any data types, with two exceptions. First, HiTest cannot convert between any numeric type (INT, NUMBER, NUMBER_LIST) and any datetime type (DATETIME, TIME_LIST). Second, the only valid conversion involving COMPOSITE is to and from TEXT.HTSTATUS return code. Failures include: HTFAIL_INVALID_CONVERT (source type does not convert to destination type); HTFAIL_OVERFLOW (destination buffer is too small); HTFAIL_BAD_FORMAT (source data conversion to destination type failed).HTSTATUS status; HTINT newlen; HTDATETIME date; status = htConvert (HTTYPE_TEXT, 0, "Jan 29, 1966", HTTYPE_DATETIME, sizeof (HTDATETIME), &date, &newlen);htConvertLength, htSetOption(Global) ########################################################## FunctionhtConvertLengthReturns the length of data converted as indicated. Determines the length of data resulting from the indicated conversion. Used to determine the buffer length needed when converting to a variable length type. See the htConvert description for a list of invalid conversions.HTINT length of result data. Returns zero for an invalid or illegal conversion.char *string = NULL; HTINT length; double number = 3.456; HTSTATUS htstatus; length = htConvertLength (HTTYPE_NUMBER, 0, &number, HTTYPE_TEXT); if (length != 0) { string = malloc (length + 1); status = htConvert (HTTYPE_NUMBER, 0, &number, HTTYPE_TEXT, length, string, NULL); }htConvert(Global)######################################### FunctionhtGetEnvStringRetrieves the value of a Notes environment string variable. Retrieves the value of a Notes environment string variable. Notes stores environment variables in the NOTES.INI file. Use the htSetEnvString function to modify Notes environment variables. To retrieve import/export formats, which are stored in multiple environment variables, use the functions htCompImportList and htCompExportList.HTSTATUS return code. Failures include: HTFAIL_DATA_UNAVAIL (no such environment string).char env_string [HTLEN_ENV_STRING + 1]; HTSTATUS status; status = htGetEnvString ("VARNAME", 0, env_string);htSetEnvString, htCompImportList, htCompExportList(Global)################################################## FunctionhtGetInfoObtains a piece of process-level information. Fetches one of various process-level information items into a supplied buffer. Each item has a data type, and the buffer must be large enough to hold the result.HTSTATUS return code. Failures include: HTFAIL_ILLEGAL_ENUM (invalid item).char username [HTLEN_USERNAME + 1]; HTSTATUS status; status = htGetInfo (HTGLOBINFO_USERNAME, username);htInit(Global)############################################## FunctionhtInitInitializes the HiTest API. For each process or task which uses HiTest functions, htInit must be the first HiTest function called. Any other function called before htInit will fail. Note that it is crucial that every HiTest API program invoke both htInit to start and htTerm when complete.HTSTATUS return code. Failures include: HTFAIL_ALREADY_INIT (htInit already called); HTFAIL_INCORRECT_DLL (program compiled with an incompatible HiTest version).HTSTATUS status; status = htInit ();htTerm(Global)############# FunctionhtSetEnvStringAssigns the value of a Notes environment string variable. Assigns a value to a Notes environment string variable. The calling program controls whether to create a new environment variable and whether to overwrite an existing one. Notes stores environment variables in the NOTES.INI file. Use the htGetEnvString function to retrieve Notes environment variables. Use care when modifying Notes environment variables, since they affect the Notes client and server programs.HTSTATUS return code. Failures include: HTFAIL_DUPLICATE (name exists and overwrite is FALSE); HTFAIL_DATA_UNAVAIL (name does not exist and create is FALSE); HTFAIL_OVERFLOW (value is longer than the maximum environment string length).HTSTATUS status; status = htSetEnvString ("VARNAME", "Variable Value", TRUE, FALSE);htGetEnvString(Global)############################## ObjectCell###################### ObjectColumn#################### ObjectComposite################# ########################################################## HTSTATUS htInit (void);? HTSTATUS htTerm (void);? ChapterSectionContents "Arial Times New Roman 1Courier New Object: Object Summary --------------------------------------------------------------------------------------------------------------------------------------------------- Syntax:e Syntax Description: Description Parameters: Parameters Returns: Returns` Example: Example See Also: SeeAlso "Arial Times New Roman Object: Object --------------------------------------------------------------------------------------------------------------------------------------------------- Description "Arial Times New Roman Chapter Chapter Section Sectioni --------------------------------------------------------------------------------------------------------------------------------------------------- Contents About HiTest 1.0 Reference $$U$$ $IU$I $mU$m I$UI$ IIUII ImUIm m$Um$ mIUmI mmUmm copyright HiTest Enhanced Lotus Notes API Release 1.0 Edge Research Inc. One Harbour Place, Suite 455 Portsmouth, NH 03801 (USA)e Phone: (603) 431-5300g FAX: (603) 427-2541e Copyrights Copyright 1994, Edge Research Inc. All rights reserved. Neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Edge Research Inc., except in the manner described in the license.m Trademarks HiTest, htGLUE, and htVISUAL are trademarks of Edge Research Inc.U Lotus Notes is a registered trademark of Lotus Development Corporation.m OS/2 is a trademark of International Business Machines Corp. Microsoft is a registered trademark, and Windows, Word for Windows, and Visual Basic are trademarks, of Microsoft Corporation. All other trademarks are property of their respective owners. Disclaimer The information in this database is subject to change and does not represent a commitment on the part of Edge Research Inc. The sample programs are not warranted to perform any function other than providing a simple demo stration of how to make a particular API call in a program context. Using HiTest 1.0 Reference $$U$$ $IU$I $mU$m I$UI$ IIUII ImUIm m$Um$ mIUmI mmUmm copyright HiTest Enhanced Lotus Notes API Release 1.0` This database is the online reference for the HiTest API. This reference contains the information from the HiTest API documentation file. Full-Text Index In addition to using the views built into this database, we strongly encourage you also to create and use a full-text index for the database. Doing so will require about 300K of extra disk space, but will allow you to very quickly find the information you need.0 Changing the Information in the Database a comment to the database... 1) In a view, highlight the item you want to add a comment to. 2) Pull down the Compose menu. 3) Choose the "Comment" form. nV$DesignVersion$Version$Formula$FormulaClass$Collation$TITLE$Index$UpdatedBy$ViewFormat$Fonts$Info$WindowTitle$FlagsObjectNameSummarySyntaxDescriptionParametersReturnsExampleSeeAlso$Fields$BodyIconBitmapChapterSectionContentsFromDateComposedSubjectBody$Collection$ViewContainerForm$Revisions UseSubject Subject ImmediateParentSubjecth ImmediateParentSubject Subject StandardTitle Response to " UseSubject" StandardTitle StandardTitle Comment Author: FromAuthor of this document Date Composed: DateComposedDate this document was composed Subject: Trimmed Subject Trimmed Trimmed SubjectEnter an optional word or phrase describing your response. Your Comment BodyEnter the text of your response. "Arial Times New Roman Chapter --------------------------------------------------------------------------------------------------------------------------------------------------- Contents A basic HiTest API program involves reading and writing Notes data. The flowcharts on the following pages show basic program flow including opening a cursor, producing an index (result set), reading and writing data, and closing the connection. $Modified $TITLE$FormPrivs$FormUsers$Body$Flags$Class$Modified$Comment$C1$ $TITLE Functions Function Object Section All Documents Guide Comment MainSection######### ########################################################## ########################################################## MainSectionCN=Scott Prag$DesignVersion sJa}R Chapter 3. Programming to the HiTest API Chapter 3. Programming to the HiTest API Chapter 3. Programming to the HiTest API Chapter 3. Programming to the HiTest API Chapter 3. Programming to the HiTest API Chapter 3. Programming to the HiTest API Description of the (Global) object Converts data between data types. Returns the length of data converted as indicated. Retrieves the value of a Notes environment string variable. Obtains a piece of process-level information. Assigns the value of a Notes environment string variable. Assigns the value of a global option. Polls for scheduling interval events. Logs an event in the Notes log and to the Notes server console. 7qSJP Sets a Notes server console task status line. Yields processor control for a specified period. Binds a cell column to a program variable. Converts and retrieves the data for a cell into a supplied buffer. Obtains the length of a cell as converted to a specified data type. Removes the binding of a cell column. Obtains the number of columns in a view. Iterates through columns in a view. Description of the Datetime object Relatively compares two datetimes. Creates a datetime from individual components. Absolutely compares two datetimes. Obtains a piece of information from and about a datetime. Modifies a datetime to produce a new datetime. Description of the Document object Closes an open document, optionally discarding all changes. Copies a document, and optionally its hierarchy, between cursors. Deletes a document, and optionally its hierarchy. Opens the next document in the active index, and loads all bound data. Obtains a piece of information from and about an open document. Opens a document for data access or modification. Creates a new document from bound items. Updates modifications to bound items back to the last fetched document. Obtains the current error information. Sets writeback buffers to receive error information on any HiTest error. Assigns an error callback function. Obtains the number of fields in a form. 4Q!3'$ Obtains a piece of information about a form field. Iterates through fields in a form. active index, and loads all bound data. Obtains a piece of information from and about an open document. Iterates through columns in a view. Section Chapter Chapter MainSection Chapter Object Object" Section Section MainSection Chapter Object Description Object Description of the Object" object Summary $1Subject$0$2$Conflict$REF$C1$ All DocumentsCN=Scott Prager/O=Edge Research Section Chapter Chapter MainSection Chapter Object Object" Section Section MainSection Chapter Object Description Object Descript The HiTest API (Application Programming Interface) is an alternative higher level C interface to the API provided by Lotus for Lotus Notes. Program development is significantly faster and requires a fraction of the API code needed with the standard API. HiTest API programmers should have some familiarity with C programming. Also useful is some familiarity with either Lotus Notes or the standard Lotus Notes API. The glossary defines terms related to Lotus Notes and the HiTest API. This manual is organized into the following chapters:? 1. Overview of the HiTest API? 2. Instructions and requirements for installing HiTest 3. Instructions for building HiTest API applications 4. HiTest function descriptions? Some of the major benefits of the HiTest API are:? Protective API layer catches invalid handles and operations which, under the standard API, cause crashes.? Simple browsing functions for everything from servers and databases through attachments and items. Abstraction of metadata (forms and views) for quick, single function access to form and view information. Additional field and column browsing functions let developers avoid completely the internal Notes BLOBs containing the metadata. Simple data transfer -- by binding document items and view cells, a single function call will load, store, or update multiple items and cells. Automatic data conversion implicitly when fetching or storing data, or explicitly with a single conversion function. Internal handling of components that are cumbersome in the standard Notes API, such as ID tables, collections, memory blocks, and composite data.? Simple high-level creation, access, and manipulation of composite data (including single-function import and export) far above the standard API's byte level with composite data functions.? Integrated single-function support for macro execution and full text search. Support for server or client add-in programs with a built-in scheduler.? Remote server console support lets clients control server activities such as replication and program execution.? Automatic management of response hierarchies, including the ability to copy or delete an entire hierarchy of unlimited breadth and depth with a single function call, as well as easy creation and management of responses.? Advanced mail interface for sending mail from a structure, from an existing document, from bound memory, or from any combination with a single function call.? Three error handling methods so developers can use the method with which they are most comfortable.? High-level object-based HiTest API facilitates rapid program development.? HiTest offers a consistent interface to the various components of Lotus Notes. The highest level of abstraction is the set of HiTest objects, covering the various components of Lotus Notes. The following diagram shows the object containment hierarchy:? The object-based design of HiTest has two major usability benefits. First, abstraction of objects that the standard API simply considers data (form, field, view, column, macro, cell, file, and composite) often lets single function calls replace medium-sized functions. Second, HiTest was designed as a consistent high-level Notes interface, rather than a collection of low-level internal functions. Common actions, such as iterating through an object, are done through common interfaces (e.g., most objects contain a List function, which works similarly across objects).? The HiTest API is built over the standard Notes API. Therefore, any machine used to build or run programs with HiTest must have a licensed copy of the Lotus Notes software (client or server, version 3.0 or higher). In addition, the machine must satisfy the hardware and software requirements to run the Lotus Notes software.? The HiTest API consists of the following files:? HTNOTES.H Include in all programs calling HiTest HTxNOTES.LIB Import library for the HiTest DLL HTxNOTES.DLL HiTest DLL - required to run HiTest programs The import library and DLL filenames contain an 'x', which varies with the operating system. The x is replaced with 'W' for Windows 3.1, 'O' for OS/2 1.3 (16-bit), and 2 for OS/2 2.x (32-bit). The HiTest API is installed from a ZIP file. First, create a HiTest API directory (e.g., C:\HITEST) and copy the file into this directory. Next, unzip the ZIP file from either a DOS window or an OS/2 window with the HiTest directory as the current directory. Use the ? option when unzipping to extract the subdirectories as well as the files. The installation process creates the following directories and files under the HiTest installation directory: INCLUDE directory? HTNOTES.H ? HiTest API include file? LIB directory? HTWNOTES.LIB? Windows 3.1 import library HTONOTES.LIB? OS/2 1.3 16-bit import library HT2NOTES.LIB? OS/2 2.x 32-bit import library? DLL directory? HTWNOTES.DLL? Windows 3.1 DLL? HTONOTES.DLL? OS/2 1.3 16-bit DLL? HT2NOTES.DLL? OS/2 2.x 32-bit DLL? SAMPLES directory? Sample programs in subdirectories ... Each subdirectory contains one sample program? DOC directory? HITEST.RTF Microsoft RTF format HiTest reference manual HITEST? .NSF ? Notes database format HiTest reference manual? represents the version number (e.g., HITEST10.NSF for HiTest v1.0) Next, modify the INCLUDE and LIB environment variables needed by the compiler to find the HiTest files. Add the HiTest INCLUDE directory to the INCLUDE environment variable for the compiler to find the HTNOTES.H include file. Add the HiTest LIB directory to the LIB environment variable for the linker to find the proper import library. To run HiTest API programs, the HiTest DLL must be available to the operating system. For Windows, the DLL is usually placed in the WINDOWS\SYSTEM directory, but may be in the WINDOWS directory or elsewhere in the PATH. For OS/2, the DLL should be in a directory in the LIBPATH environment variable. To run HiTest API programs, the NOTES.INI file must be available in a directory in the PATH environment variable. Most Notes installations locate this file in either the Windows or Notes program directory, in which case it should already be in the PATH. Some installations, though, locate this file in the Notes data directory. If this is the case, then add this directory (or another directory if NOTES.INI is elsewhere) to the PATH if not already included. The HiTest installation includes various sample programs. These programs demonstrate common activities performed with the HiTest API. One subdirectory under the SAMPLES directory exists for each sample program. Each sample program includes the following files: README.TXT describes the sample program? MAKEFILE builds the sample program. Invoke with an operating system constant (e.g.: NMAKE WIN, NMAKE OS21, or NMAKE OS22).? HTSAMPLE.H generic sample program header file? PROGRAM? .C sample program-specific source code? PROGRAM? .H optional sample program header file? Build and run the sample program SIMPLE to test for proper installation of HiTest. The other sample programs are described below:? Program? Description? DBMETA Demonstrates database and metadata access by connecting to a database and generating all metadata for the database to a file.? VIEWDMP? Demonstrates creation and navigation of a view-based index and its cell data. The view is rendered without formatting to a file. DOCITEM? Demonstrates document item access by item binding and by direct item access. The item data for all documents in a flat index is written to a file. DOC2NSF? Converts and parses the HiTest documentation into a Notes database. The documentation is imported into a composite item, which is then parsed to produce one Notes document for each function in the HiTest API. This sample is a detailed example of creation and manipulation of composite data. This section contains requirements and instructions for writing HiTest API programs. The different HiTest platforms support different compilers. Building Windows 3.1 programs requires the Microsoft C compiler version 7.0 or greater. Building OS/2 1.3 16-bit programs requires the Microsoft C compiler version 6.0 (the last version which supported OS/2). Building OS/2 2.x 32-bit programs requires the IBM C Set++ compiler, as well as certain compiler options to interact properly with the 16-bit Notes code beneath HiTest. The options are /Gt (tiled memory to avoid crossing 64K boundaries) and /Sp1 (1-byte structure packing). The /Gs option (remove stack probes) is not required, but is recommended. Programs which call the HiTest API must be compiled as large memory model programs (on 16-bit platforms where memory model is relevant). The minimum stack size for HiTest API programs is 10K (15K for OS/2 2.x), and programs of moderate size or complexity should increase the stack size beyond 10K. The following table summarizes requirements by platform: Platform Requirements Windows 3.1? Microsoft C compiler version 7.0 or greater? large memory model (compiler option /AL) 10K or greater stack OS_WIN compilation constant? OS/2 1.3 (16-bit)? Microsoft C compiler version 6.0 large memory model (compiler option /AL) 10K or greater stack OS_OS21 compilation constant OS/2 2.x (32-bit)? IBM C Set++ compiler 15K or greater stack OS_OS22 compilation constant Compiler options /Gt and /Sp1? (The use of compiler option /Gs is recommended)? When building a program, to set the stack size in a module definition file use the following statement:? STACKSIZE 10240 To set the stack size on the linker command line use the following link option:? /ST:10240 Increase the value for larger programs.? All source code modules using HiTest must declare an operating system before including the HTNOTES.H include file. Define one of the OS constants OS_WIN, OS_OS21, or OS_OS22. To define the constant from within a C program, use the following statement:? #define OS_WIN? To define the constant during compilation, use the following compilation option: /DOS_WIN? The compilation option supports multiple compilations of the same program with different OS constants to run under multiple operating systems. Every HiTest API program must initialize and terminate the HiTest API. All other HiTest functions will fail unless preceded by a call to the initialization function htInit. Additionally, the program ? call the htTerm function after all HiTest function calls are complete and before the program terminates. Calling the termination function is crucial to avoid leaving the system in a dangerous state.? This section describes the HiTest API data types. Standard Notes data comes in three flavors:? 1. Single value data types (NUMBER, TEXT, and DATETIME) contain a single data value (e.g., 3.14).? 2. Multiple value data types (TEXT LIST, NUMBER LIST, and TIME LIST) contain one or more values of similar types (e.g., ABC, DEF is a two-element text list). For number or time lists, each individual value is either an exact value or a two-value range (e.g., 3, 5, 7-10 is a three-element number list, where the third element is a range). 3. Composite data type (COMPOSITE) is a collection of individual composite records of different subtypes. Composite data may contain multiple record types, including formatted text, images, links, etc. For a full description of composite record types, see the composite record section in the function descriptions. HiTest supports all the standard Notes data types. In addition, HiTest supports a special data type (REF) which is a responses reference to a parent document. The constant HTLEN_ITEM_DATA defines the maximum data length for all types except composite. Composite data may be of unlimited length. The following table describes the data types, with internal formats and any notes. The constant representing each datatype is constructed by prefixing HTTYPE_ (e.g., HTTYPE_INT). Standard types Description? C long integer. Although Notes stores all numbers as double-precision floating-point values, many numeric items represent integer values. In these cases it is convenient to use the integer type, which HiTest automatically converts to and from the Notes internal number format. NUMBER C double precision floating-point. This is the type used by Notes to store all numeric values. The constant HTLEN_NUMBER_TEXT defines the maximum length of a NUMBER converted to text.? Variable length text string. Although Notes stores text without null terminators, all text values transferred to and from the HiTest API use a NULL terminator? . It is crucial that all text buffers allow an extra byte for the NULL terminator. The terminator is not included in the text length (e.g., the length of ABCDE is five bytes, but a buffer supplied by the calling program must be six bytes). This is true not only for data, but for informational items (e.g., server names, error messages, etc.). The exception is functions that retrieve direct data pointers (GetPtr functions), where text values may not contain a NULL terminator. Handle these values by length rather than with standard C string functions. DATETIME 8-byte data object representing a date and time. Use the htDatetime functions to manipulate datetime values (do not directly manipulate the datetime data). The HiTest representation is the same as the standard Notes API representation. The range is from year 1 through year 32767, and the precision is one-hundredth of a second. Datetime values are time zone specific. The constant HTLEN_DATETIME_TEXT defines the maximum length of a DATETIME converted to TEXT.? TEXT_LIST? A multiple-value collection of zero or more text strings. Use the htTextList functions for easy access to the contents of a text list. The text values within a text list are not NULL terminated. The format of a text list containing N entries is:? WORD number of entries (N) WORD length of entry #1? WORD length of entry #2? WORD length of entry #N? text text of entry #1? text text of entry #2? text text of entry #N? NUMBER_LIST? A multiple-value collection of zero or more C double-precision floating-point values and ranges. The format of a number list containing N values and M ranges is:? WORD number of values (N)? WORD number of ranges (M)? double value #1 double value #2 double value #N double low value of range #1? double high value of range #1 double low value of range #M? double high value of range #M TIME_LIST? A multiple-value collection of zero or more DATETIME values and ranges. The format of a time list is the same as a number list, with HTDATETIME values in place of doubles.? COMPOSITE? A composite is an ordered list of composite records. Each composite record is of a type within the HTCOMP_xxx enumeration. Unlike other Notes types stored as a single document item, a composite may consist of multiple items. One of the benefits of the HiTest API is the abstraction of a composite object as a single object regardless of the number of document items in that composite. For more information, see the htComp and htComprec function descriptions. Nonstandard types? Description? The HiTest representation of a reference to a parent document. Notes stores response information within the child as a reference to the parent. Reference items are always of the same item name -- $REF (use the constant HTNAME_REF). In HiTest, a reference items value is the HTDOCID of the parent document (internally, Notes uses a more complex representation). Forms do not contain reference fields, so reference items are handled independently of strict binding and form fields.? HiTest supports implicit and explicit data conversion between types. Use the htConvert function to perform explicit conversion. Implicit conversion occurs in functions which fetch or put data (htDocFetch, htDocPut, htDocUpdate, htItemFetch, htItemGetPtr, htItemPut, htCellFetch). While HiTest supports most conversions, certain conversions do not make sense and are invalid. No conversions between numeric (INT, NUMBER, and NUMBER LIST) and time (DATETIME and TIME LIST) are allowed. Additionally, COMPOSITE can only be converted to and from TEXT. REF cannot be converted. If an unsupported conversion is required, perform two conversions, using type TEXT as the intermediary (e.g., convert from type X to TEXT, and then from TEXT to type Y). Certain conversions may result in a loss of information (e.g., converting a composite item to text will retain only ASCII text information).? Objects within the HiTest API are represented by either an identifier or a handle. Simple objects need only an identifier. An identifiers type depends on the object. For example, a servers identifier is a string, a documents identifier is an ID, and a view columns identifier is a number. Larger or more complex objects must be opened and closed and require a handle. Cursors, documents, and composite items use handles. Certain actions on objects are only valid within the context of other objects. The simplest example is that of an open document. Closing a cursor containing an open document closes the document and invalidates its handle. A cursor represents a single HiTest session. Each process or task can contain multiple cursors at any point in time. Multiple cursors may be open to a single database. All actions performed against a database occur through a cursor. A cursor contains a state which consists of an active form, an active view, an index, bindings, and open documents. Any operation which cancels or replaces part of a cursors state destroys the previous value. For example, producing a new index destroys the previous index.? The following table lists the HiTest functional contexts in a simplified state transition table. Each context lists objects and functions which are valid from within that context (an object name indicates that all functions of that object are valid in the context). The context ordering is from highest level to lowest. When entering a lower context from a higher context, all functions in the previous context are still valid . For example, after entering the ? Open Composite context from the Open Document? context, the htItemPut function is still valid even though it is not listed in the Open Composite . Each context also lists those functions which cause a transition to a different context. When entering a lower context from a higher context, all transitions in the previous context are still valid. For example, performing htCurClose from the ? Open Document? context causes a return to the Initialized? context. Multiple contexts may exist simultaneously. For example, calling htDocCreate when in the ? Fetched Document context will create a valid ? Open Document? context. These document contexts may operate independently, but a call to htCurClose would close them both by closing their parent context. Context? Valid? Transitions? Uninitialized? htInit (Initialized) Initialized? Global, Addin, Server, Database, TextList, Datetime, Error htCurOpen (Open Cursor)? htTerm (Uninitialized) Open Cursor? Cursor, Form, View, Field, Column, Macro, Formula, Mail? htCurClose (Initialized) htItemBind (Bound Item)? htFormulaExec (Active Index) htDocOpen, htDocCreate (Open Document) Bound Item htDocPut htCurReset (Open Cursor),? htFormulaExec (Active Index) Active Index Index, Cell* htCurReset (Open Cursor) htCellBind* (Active Index/Bound Cell)? htItemBind (Active Index/Bound Item) Active Index / Bound Cell? htDocFetch htCurReset (Open Cursor) htIndexSearch, htFormulaExec (Active Index)? htItemBind (Active Index/Bound Item) Active Index / Bound Item? htDocPut htIndexSearch, htFormulaExec (Active Index)? htDocFetch (Fetched Document)? Open Document? Document, Item, File htDocClose (Open Cursor),? htItemFetch/htItemGetPtr to type HTTYPE_COMPOSITE? (Open Composite) htCompImport, htCompCreate (Open Composite)? Fetched Document Document, Item, File, htDocUpdate? htDocClose (Active Index/Bound Item) htIndexNavigate, htIndexSetPos, htIndexSetTreePos? (Active Index/Bound Item)? htIndexSearch, htFormulaExec (Active Index)? htItemFetch/htItemGetPtr to type HTTYPE_COMPOSITE? (Open Composite) htCompImport, htCompCreate (Open Composite)? Open Composite Composite, Comprecord? * Cell functions are only valid in view-based indices. Context Transition Table In HiTest, higher contexts contain lower contexts. The following diagram shows context containment.? Context Containment Diagram? Program context affects the method of data access. Often data is accessible with either a Fetch operation or a GetPtr operation. The Fetch operation transfers data to a buffer supplied by the calling program. When the data source becomes invalid (e.g., by closing the document), this data is still valid since it is a copy into memory managed by the calling program. The GetPtr operation simply returns a pointer to memory managed by HiTest. The GetPtr operation is more efficient than the Fetch operation when retrieving the same data value repeatedly. When the data source becomes invalid in this case, the data pointer becomes invalid. The calling program can no longer access the data, and should not free the data pointer itself since HiTest manages the memory. The HiTest API supports three styles of error handling, so developers can implement error handling in the manner with which they are most familiar and comfortable. HiTest handles errors on a process level (i.e., errors in multiple cursors in a single process are stored in a single location). When an error occurs, there are three pieces of information available: the error code, the error severity, and the error string. The next HiTest API call automatically clears error information (except htError functions, which do not affect the current error information). For more detail on error functions, see the htError function descriptions.? The first style of error handling is the most basic. Most HiTest functions return an HTSTATUS value representing the error code. When this value indicates an error condition, use the htErrorFetch function to get more error information. Error return values are easily checked by comparing them against zero since successful operation (HTSUCCESS) is always equal to zero, and nonzero indicates an error condition.? The second style of error handling involves assigning writeback buffers with htErrorSetBuffer. The calling program assigns buffers to receive one or more of the error code, severity, and string when an error occurs. Just before returning, each HiTest function checks for an error condition and automatically writes any error information to the error buffers. Return values may still be used to check status.? The third style of error handling assigns a callback function with htErrorSetProc. The calling program defines a callback function to be called by HiTest when an error occurs. Declare this function to match the HTERRORPROC type. When invoked, the callback function receives as input parameters the error code, error severity, and error string pointer. In addition, HiTest passes a parameter, supplied by the calling program to htErrorSetProc, to the callback function. This supplies access to information and context from the calling program within the callback function. HiTest functions call the callback function as the last action before returning an error code. If a program uses both this method and writeback buffers (they are usually used exclusively), HiTest writes to the writeback buffers before calling the callback function. Return values may still be used to check status. A summary of HiTest errors and severities follows: Class? Error constant Description? General? htfail_notes_error Standard Notes API error htfail_program Software error -- contact Edge Research technical support? htfail_illegal_enum? An enumeration parameter value is invalid? htfail_null_parameter? A parameter is NULL when a value is required htfail_overflow? A data value cannot fit in the supplied buffer htfail_duplicate Name is already in use htfail_bad_format? A parameter value is formatted incorrectly htfail_end_of_data The last data value has been retrieved htfail_data_unavail? Requested data is unavailable? Global htfail_incorrect_dll Program compiled with an incompatible version of HiTest? htfail_already_init? htInit called when HiTest is already initialized htfail_not_init? HiTest function other than htInit called when not initialized? htfail_invalid_convert The requested conversion is not legal? htfail_invalid_database? No such database exists? Cursor htfail_invalid_cursor? The cursor is invalid? htfail_open_documents? htCurClose called without force and documents are open htfail_active_result An active result prevents the requested operation? htfail_invalid_form? No such form exists in the database? htfail_form_unavail? Strict binding is on, but no active form is set? htfail_invalid_view? No such view exists in the database? Field? htfail_invalid_field No such field exists in the form Column htfail_invalid_column? No such column exists in the view? Macro? htfail_invalid_macro No such macro exists in the database Formula? htfail_invalid_formula The formula is invalid Index? htfail_invalid_navtype View-style navigation attempted on a flat (non-view) index htfail_invalid_document? The document handle or ID is invalid htfail_invalid_item? No such item exists in the document? htfail_invalid_directory No such directory exists htfail_invalid_file_item No such file attachment exists in the document htfail_invalid_composite Invalid composite handle htfail_invalid_impexp? No such import/export format exists? htfail_invalid_font? No such font exists in the document font table Severity Description? HTSEVERITY_NOERROR No error HTSEVERITY_WARNING Warning-level error? HTSEVERITY_NONFATAL? Normal error HTSEVERITY_USAGE Error in calling program's usage HTSEVERITY_FATAL Fatal error? HTSEVERITY_PROGRAM Internal software error - contact Edge Research? The HiTest API is sufficient to perform the vast majority of Notes API programming. There are two situations, though, where a program needs some mixture of standard Notes API code and HiTest API code. The first occurs when migrating or expanding a program written against the standard Notes API to HiTest. The second occurs when an API program needs some of the more esoteric Notes API functionality not available with HiTest, such as user registration. In either case, the mixture is straightforward as long as a few guidelines are followed: 1. Replace NotesInit and NotesTerm calls with htInit and htTerm calls. These calls include embedded NotesInit and NotesTerm calls. 2. Obtain the standard Notes API database or document handle for a HiTest cursor or document with the GetInfo functions (i.e., htCurGetInfo or htDocGetInfo). With the Notes API handle programs can use the standard Notes API to manipulate an object opened with HiTest.? 3. Use care when manipulating the same object (database, document, etc.) with both APIs. For example, a document opened in HiTest can be manipulated through the standard Notes API by obtaining the NOTEHANDLE with htDocGetInfo. Using the standard Notes API to append an item is legal, but using the standard API to delete the document is not legal.? The HiTest API divides functions into functional groupings by object. The actions to perform are verbs and are generally consistent between objects. Each function name consists of four parts, describing the function with an object, a verb, and an optional modifier. The first part is always the prefix ht. The second part is the object name. Functions in the global grouping omit this part. The third part is the verb. The fourth part, only sometimes used, is the modifier. Taking htDocGetInfo as an example, the object is Doc, the verb is Get, and the modifier is Info. The following summary tables describe the objects and verbs with modifiers.? Objects? Verbs used with modifiers? (Global) Init, Term, SetOption, GetInfo, GetEnvString, SetEnvString, ConvertLength, Convert Addin? SetStatus, PutMsg, SetInterval, GetInterval, Yield Server List, GetInfo, Exec? Database List, ListCat, GetPath Cursor Open, Close, GetInfo, SetOption, Reset List, GetId, GetAttrib, Copy, Delete, Set, Template? List, GetId, GetAttrib, Copy, Delete, Set? Field? Count, List, GetInfo Column Count, List? Macro? List, GetId, Copy, Delete, Exec? Formula? Concat, Concatf, Length, Copy, Reset, Exec Index? GetInfo, Count, Navigate, GetPos, SetPos, GetTreePos, SetTreePos, Refresh, Search? Document Fetch, Put, Copy, Open, Close, Create, GetInfo, Update, Delete Bind, Unbind, Count, List, GetInfo, Length, Fetch, GetPtr, Put, Delete Bind, Unbind, Length, Fetch? List, Fetch, Put, Delete Composite? GetInfo, Merge, Create, Copy, CopySubset, ListText, ImportList, ExportList, Import, Export, GetOSFont, PutOSFont Comprec? Count, List, Insert, Update, Delete, Length, Fetch, GetPtr TextList Count, Length, Fetch, GetPtr Datetime Create, GetInfo, Compare, Diff, Update Error? Fetch, SetBuffer, SetProc? Verbs? Modifiers Used EnvString, Interval, Path, Info, Id, Attrib, Pos, TreePos, Ptr, OSFont EnvString, Option, Status, Interval, Pos, TreePos, Buffer, Proc? Cat, Text? Count? Close? Reset? Subset Create Delete Convert? Length Unbind Concat Length Fetch? OSFont, Msg? Update Merge? Insert Compare? Import Export *Init? *Term? *Yield *Template? *Concatf *Navigate? *Refresh *Search? *Send? * - While most verbs apply to multiple objects, certain objects also support actions specific to that group. Verbs marked with an asterisk are specific to one object. HiTest orders function parameters with input parameters first and output parameters last. Most functions return an HTSTATUS type return code, which is HTSUCCESS (zero) for success, and one of the nonzero HTFAIL constant values for failure. These functions put all output values into parameters passed by reference to the function. A few functions return a value when there is no significant failure information beyond a NULL or zero value. These functions return values are commonly used as input to other functions. Whenever reasonable, the same verb within different objects uses the same parameters (e.g., most GetInfo function prototypes look similar). Parameter use is also generally consistent across functions. For example, for most functions an input buffer length of zero directs HiTest to determine the length, and an output buffer length of zero indicates the buffer is sufficiently large. Some parameters are optional and allow a NULL or zero value. The function parameter descriptions describe the effects of a NULL or zero value. This section defines some of the Notes-related terms used throughout this document. In addition, some of the terminology in this document relates to database APIs in general, and some familiarity in this area is helpful, although not required. Some of these terms are also described below.? API stands for Application Programming Interface, a set of functions and supporting code and documentation which provides a clean interface to some application. HiTest is a high-level API to Lotus Notes.? attachment A file not contained within a document, but bound to a document. Any document may have any number of attachments. Although the attachment is not stored in the document, Notes stores it in the documents database.? bound dataspace? A set of memory locations related to a set of specified document items and/or view cells. Using HiTest, data can be fetched to or inserted or updated from these memory locations to the assigned document items and view cells by a single function call. category A row within a view which represents a grouping of documents with some commonality. When a column is categorized, Notes groups all documents with the same value for that column together. Notes produces an extra non-document row for each grouping, and the cells in the categorized column for those rows contains the category value. The cells for the categorized column are empty for all other rows.? child? See response.? A data value within a view-based index. Each column and row combination represents a cell. Cell contents cannot be modified -- they exist within Notes as read-only values.? column A single piece of metadata within a view. HiTest describes a column by its integer location (e.g., column 1, column 2, ...), as well as other attributes. The data value within a column for a single view row is a cell.? composite? A Lotus Notes data type constructed from some number of smaller components called composite records. Each composite record may be in any of a set of data formats (e.g., bitmap, formatted text, audio). Also called rich text or compound text. composite record A component of a composite. One or more composite records make up a composite item. Each composite record is of a specific type (e.g., formatted text, graphic, doclink, etc.).? compound text? See composite data.? context? The conditions under which an action or object is valid. Certain actions and objects are only valid within the context of another object. For example, a composite handle is only valid within the context of its containing document handle, which in turn is only valid within its containing cursor. Closing the cursor closes and invalidates the document and composite handles.? cursor A handle which indicates a single API session. Programs may open multiple cursors. A cursor contains the following components: a Notes database handle; options; a formula buffer; an active form, view, and index; and open documents and composites. database A collection of documents and metadata within a single .NSF file. Each cursor connects to exactly one database, although multiple cursors may simultaneously connect to the same database. document A collection of data items. A document is how Notes stores data. Data within a database is stored in documents.? fetch? The process of retrieving data. When fetching a document, a single function call retrieves and converts multiple bound items and cells.? field? A single piece of metadata within a form. A field consists of a data type, a name, and other attributes. When using strict binding, all items within a document must also exist within the documents form as fields. file attachment? See attachment.? formula? A statement executed against a database to perform a specific action. Currently, only selection formulas (i.e., those which produce an index) are valid through the HiTest API. The Lotus Notes formula language defines the syntax of a formula.? formula buffer A buffer used for constructing formulas for execution. Each cursor contains one formula buffer. After construction, the formula in the formula buffer may be executed. formula language The grammar specification which defines the valid syntax for formulas. The Lotus Notes application documentation defines the Lotus Notes formula language syntax.? A form is the type of metadata which defines the format for the creation or interpretation of documents. A document often, but not always, contains an item which indicates the document's form. While documents do not require a form (see strict binding), they should unless there is a good reason not to be based on a form. A single database may contain multiple forms.? full text search A search of all text within a set of documents. Lotus Notes has the ability to index a database for full text search. Programs may execute a full text search query against some or all of the documents within that database, and any documents which match the query are selected. A full text search query normally consists of one or more words or phrases. The Lotus Notes application documentation defines the Lotus Notes full text search query syntax.? handle A handle is a simple (usually integer) value used to indicate some context within the API. Operations which create open data objects (e.g., opening a cursor or document) produce a handle. An open objects handle indicates a particular open object to the API when multiple instances of that type of object may exist. For example, when multiple documents are open, the integer handle indicates which open document to use for a given operation. hierarchical A tree-based set. In HiTest, view-based indices are hierarchical since each document in them may have a parent document and/or child documents.? HiTest The name of the enhanced Notes API described in this documentation.? index? A set of documents produced by executing a selection formula within a cursor. The primary attribute of any index is an ordered collection of documents. There are two types of indices: flat and hierarchical (view-based). Flat indices are produced by a full database search or full text query, and have no hierarchy. Hierarchical indices are produced from the set of documents within a view, and contain a set of cells corresponding to the view display for each document. The process of moving through the documents within an index is navigation. Result set is another term for index. A cursor in which a formula has been executed and results are available contains an active index. insert The process of creating a new document in a Notes database. Programs usually do this with bound dataspace or by creating an empty document and adding items one at a time.? A data value within a document, on which the HiTest API supports retrieval and assignment. When strict binding is in effect, every item in a document must correspond in name and data type to a field in that documents form. macro? A stored Notes object which performs a specified action on request or on schedule. Macro execution can create, modify, or select documents, depending on the type of macro.? A message sent between e-mail users. Notes supports addressing and sending of documents as mail. metadata Data which describes data. The types of metadata relevant to the API (listed with their corresponding data object) are:? forms (corresponding to documents); fields within forms (corresponding to items within documents);? views (corresponding to the set of documents within views); columns (corresponding to cells within views).? navigation The process of moving through an index. From any point within an index, there are various navigation styles (e.g., next, first, previous parent, etc.) usable to move to other documents in the index. View-based indices support a greater range of navigation styles than flat indices.? A special undefined value for any data type. This is different from zero-values such as numeric zero and the empty string. In Notes documents, HiTest represents a NULL value by the absence of an item within a document, since Notes has no concept of a NULL value as data. parent A parent document is a document to which another document is a response (child). One parent may have multiple responses. The only way to determine a documents responses is by view-based navigation.? query? A statement executed against a database to perform an action. In Notes, a query is used to perform a full text search of some or all text within a database. The Lotus Notes application documentation defines the syntax of a query.? response A document which references another document as its parent. Programs can determine a documents parent either by view-based navigation or by the value of the documents reference item. The term response is synonymous with child. response hierarchy The set and organization of responses beneath a given document is that document's response hierarchy, and may consist of multiple levels (responses may have responses). While a document may have many responses, it may only have one parent.? rich text? See composite data.? A single horizontal entry within a view. Each row (document, category, or totals) in a view contains one cell for each column in the view. selection formula? A formula which produces an index, which consists of a subset of the documents within a database.? server A named Notes server program that receives and processes requests from clients, contains and maintains a set of Notes databases, and implements security on the databases it controls. session? One API connection, with its own internal state and data. A given process may open multiple sessions, each of which may perform independent functions at the same time. Each session is indicated by a cursor. state? Each process has a state which defines valid operations at the current time (i.e., data is not accessible from a document which is not open). Certain operations within one state result in a different state. strict binding There is no requirement in Notes that items within a document match the fields within that document's form, or even that a document have a form. Since this may cause confusion, and normally the ability to have documents differ in format from forms is unnecessary, the API enforces strict binding by default. This filters document access through the document's form, and forces a consistent structure on items in documents. Strict binding is a cursor-level option.? summary item Notes stores certain items as summary items, which may be used in computations and are usually smaller than other non-summary items. Composite items cannot be summary items. In general, most other items are summary items (up to the Notes limit of 15 K of summary data per document). update The process of modifying an existing document in a Notes database. Programs perform updates by using bound dataspace or by adding or replacing items one at a time. A view contains a sorted and indexed hierarchical set of documents within a database. The set of documents within a view are accessible as a view-based index. A view also contains metadata in the form of columns and data in the form of cells. These functions are global within a process or task. These functions have no context beneath the process level (i.e., no other functions affect their operation), and are always usable (after calling htInit). While there are other functions with no context, these functions are in the global classification because they do not apply to any object. ? Every HiTest API program must initialize and terminate the HiTest API. Until calling the HiTest initialization function htInit, all other functions will fail. Additionally, every HiTest program call the htTerm function after all HiTest function calls are complete and before the program terminates. It is crucial to call the termination function to avoid leaving the system in a dangerous state. The global group contains the following functions: htConvert Converts data between data types? htConvertLength Returns the length of data converted as indicated htGetEnvString Retrieves the value of a Notes environment string variable htGetInfo Obtains a piece of process-level information? htInit Initializes the HiTest API? htSetEnvString Assigns the value of a Notes environment string variable htSetOption Assigns the value of a global option? htTerm Terminates the HiTest API src_type The data type of the source data. src_len The length of the source data. A value of zero directs HiTest to determine the length.? src_buffer? A pointer to the source data. dest_type The data type to convert to in the destination buffer.? dest_len? The length of the destination buffer. A value of zero indicates that the buffer is large enough to hold the result data. A length which is insufficient to contain the result is only valid when the destination type is HTTYPE_TEXT and the global option TEXT_TRUNCATE is active. In this case, the resulting text is truncated to fit in the buffer. dest_buffer The destination buffer. actual_len? If given, this parameter receives the length of the result buffer data. HTSTATUS htConvert (src_type, src_len, src_buffer, dest_type, dest_len, dest_buffer,? actual_len); HTTYPE src_type; /* Input */? HTINT src_len; /* Input, Optional */ void *src_buffer; /* Input */ HTTYPE dest_type; /* Input */ HTINT dest_len; /* Input, Optional */? void *dest_buffer; /* Output */ HTINT *actual_len; /* Output, Optional */ src_type The data type of the source data. src_len The length of the source data. A value of zero directs HiTest to determine the length.? src_buffer? A pointer to the source data. dest_type The destination data type.? HTINT htConvertLength (src_type, src_len, src_buffer,? dest_type); HTTYPE src_type; /* Input */? HTINT src_len; /* Input, Optional */ void *src_buffer; /* Input */ HTTYPE dest_type; /* Input */ name ? The name of the environment variable to retrieve. In the NOTES.INI file, this is the string to the left of the equal sign. Some examples of useful standard Notes environment variables are:? Directory Notes data directory? MailServer Server name on which Notes users mailbox resides MailFile Database filename of Notes users mailbox Domain Notes users domain length? The length of the value buffer to receive the environment variable value. The constant HTLEN_ENV_STRING defines the maximum length of an environment variable string. A length of zero indicates that the buffer is large enough to hold the result.? value The buffer to receive the environment variable The constant HTLEN_ENV_STRING defines the maximum length of an environment variable string. In the NOTES.INI file, this is the string to the right of the equal sign.? HTSTATUS htGetEnvString (name, length, value); char *name; /* Input */ HTINT length; /* Input, Optional */ char *value; /* Output */ One value from an enumeration of global items. Each item corresponds to a type (and length, for variable length types). The following table lists legal items with their corresponding data types and, where relevant, lengths: constant type HTGLOBINFO_USERNAME char [HTLEN_USERNAME + 1] HTGLOBINFO_SERVERNAME char [HTLEN_SERVERNAME + 1]? HTGLOBINFO_CURRENTTIME HTDATETIME? HTGLOBINFO_TIMEZONE HTINT? HTGLOBINFO_DST HTBOOL HTGLOBINFO_HTVERSION char [HTLEN_VERSION + 1]? USERNAME obtains the Notes user name in the Notes ID file;? SERVERNAME obtains the name of the locally running Notes server, if any;? CURRENTTIME obtains the current datetime; TIMEZONE obtains the local time zone as an integer relative to GMT; DST indicates whether daylight savings time is currently in effect; VERSION returns the version of HiTest.? buffer? The buffer to receive the requested information. This buffer should be of sufficient length to handle the result. HTSTATUS htGetInfo (item, buffer); HTGLOBINFO item; /* Input */? void *buffer; /* Output */? name ? The name of the environment variable to assign. In the NOTES.INI file, this is the string to the left of the equal sign.? value The value to assign to the environment variable. The constant HTLEN_ENV_STRING defines the maximum length of an environment variable string. In the NOTES.INI file, this is the string to the right of the equal sign.? create? Whether to create the environment variable if it doesnt exist (TRUE enables creation).? overwrite Whether to overwrite the environment variable if it does exist (TRUE enables overwrite).? HTSTATUS htSetEnvString (name, value, create, overwrite);? char *name; /* Input */ char *value; /* Input */? HTBOOL create; /* Input */ HTBOOL overwrite; /* Input */? option One value from an enumeration of global options. Each option corresponds to either a string or integer value. The option value indicates whether to use the string or numeric parameter (the function ignores the other parameter). The following table lists legal options with their corresponding data types, parameters, and defaults:? constant type parameter default HTGLOBOPT_BULK_STORE HTBOOL number FALSE? HTGLOBOPT_STRICT_BIND HTBOOL number TRUE HTGLOBOPT_VIEW_POSITION HTBOOL number FALSE? HTGLOBOPT_FETCH_SUMMARY HTBOOL number FALSE? HTGLOBOPT_SUMMARY_LIMIT HTINT number 8192 HTGLOBOPT_LOCAL_SERVERNAME char * string NULL HTGLOBOPT_TEXT_TRUNCATE HTBOOL number TRUE The basic functions of the options are described below: When bulk store is active, HiTest does not commit changes in document data to disk during a document close, but rather when closing the cursor itself. When bulk store is inactive, closing a document commits all changes to disk. When strict binding is active, HiTest filters all document items through a form (i.e., HiTest uses the form metadata for type-checking). Therefore, items in a document which are either not in the documents form or are of a different data type than the corresponding field in the documents form will not be accessible. When strict binding is inactive, the items in a document are not tied to the forms metadata. This option also affects certain indices. When executing a formula to produce a flat index and strict binding is active, the index only includes documents of the active form. Strict binding has no effect on the documents included in a view-based index, although it does affect items within documents accessed from a view-based index.? When view position is active, view-based indices always keep depth-first ordinal position information. This enables functions which use index positioning (e.g., htIndexGetPos and htIndexSetPos) to find any element in a view-based index by ordinal location. This functionality may significantly reduce speed. When view position is inactive, HiTest performs view-based positioning off the top-level entries within the index and is much more efficient. This option has no effect on flat indices.? When fetch summary is active, htDocFetch operations open documents with summary data only. Use htDocFetch or the HTDOCHANDLE that it returns to access summary items only. When non-summary items (composite and some other large items) are not needed, this option increases fetch speed. When fetch summary is inactive, documents fetched always have all data available. The value of summary limit determines the maximum length of an item which will have its summary flag set. If the summary items for a single document exceed the value HTLEN_SUMMARY_DATA, then Notes may not display the document properly in views, and cell values may not be accessible. If the length of any single item exceeds HTLEN_SUMMARY_DATA, then that item is not usable by Notes in any view. The default value of this option is 8K. The constant HTLEN_SUMMARY_DATA (15K) defines the maximum value of this option).? When local servername is set, the string value assigned for the option is usable in place of NULL to indicate the local server. Also, the list of available servers from htServerList includes this string. When text truncate is active, retrieval of data as text supports truncation of results. Calls to htConvert, htDocFetch, htItemFetch, and htCellFetch with the destination type set to HTTYPE_TEXT will truncate results if necessary, and will not generate an error. Conversions to types other than text do not allow truncation. When text truncate is inactive, no conversions allow truncation.? number? The numeric or boolean value for an option. When setting the value of a boolean option, use the constants TRUE and FALSE. string? The string value for an option. HTSTATUS htSetOption (option, number, string); HTGLOBOPT option; /* Input */? HTINT number; /* Input, Optional */ char *string; /* Input, Optional */ FunctionhtSetOptionAssigns the value of a global option. Assigns a value to a global option or new cursor default. Depending on the option, the new value is supplied in either the number or string parameter. When setting the value of cursor defaults, the new value has no effect on existing cursors.HTSTATUS return code. Failures include: HTFAIL_ILLEGAL_ENUM (invalid option); HTFAIL_OVERFLOW (value out of bounds).HTSTATUS status; status = htSetOption (HTGLOBOPT_LOCAL_SERVERNAME, 0, "Local");htConvert, htServerList, htCurOpen, htCurSetOption, htIndexGetPos, htIndexSetPos, htDocFetch, htItemFetch, htCellFetch(Global) ########################################################## FunctionhtTermTerminates the HiTest API. Shuts down the HiTest API for the current process or task. Before terminating, this function closes any open cursors by calling htCurClose. After calling htTerm, no other HiTest functions may be called except htInit. It is crucial that every HiTest program call htTerm.HTSTATUS return code.HTSTATUS status; status = htTerm ();htInit, htCurClose(Global)###################### FunctionhtAddinGetIntervalPolls for scheduling interval events. Polls the HiTest scheduler to determine if any assigned intervals have occurred. Programs may set intervals with the htAddinSetInterval function. Each time an interval occurs, a call to htAddinGetInterval succeeds and returns information about the interval. Programs can either poll this function periodically or temporarily surrender program control. When a program surrenders control, HiTest waits for the next interval and then returns. HiTest can manage multiple simultaneous intervals. When giving control to this function under Windows, messages are passed through to the calling application by HiTest. A WM_QUIT message in this state causes this function to return to the calling application for a normal shutdown. A nested call to this function or htAddinYield while processing a message will fail.HTSTATUS return code. Failures include: HTFAIL_DATA_UNAVAIL (no intervals set or no interval has occurred); HTFAIL_END_OF_DATA (Windows nested callback or WM_QUIT received).HTINT interval, iteration; HTSTATUS status; status = htAddinSetInterval (60); while (!htAddinGetInterval (TRUE, &interval, &iteration)) printf ("\nAnother %ld seconds have passed", interval);htAddinSetInterval, htAddinYieldAddin################################################### FunctionhtAddinPutMsg OS/2 1.3 onlyLogs an event in the Notes log and to the Notes server console. Logs a message or error to the Notes log and server console. The message is of the format