Docstoc

123

Document Sample
123 Powered By Docstoc
					This section lists all the OpenAPI routines in alphabetical order by name. For each
routine, you will find a brief description of the routine’s purpose, the exact syntax for
using the routine in a program, descriptions of the routine’s parameters, and (in some
cases) any necessary comments on what to keep in mind when using the routine or where
to look for more information pertaining to the routine.

See the appendices for descriptions of data structures (for example, OPI_FIELDINFO),
data types (for example, OPI_MEMBERID), TIO IDs (for example,
OPI_TIOID_LINE_END), or Visual Basic routines (for example, VBOpiSetFileAttr).

Note: In many of the routines that are described below, the name of each parameter is
followed by a type/usage designation.




                                                                         Reference  193
                  OpiAbortSubTrans
Description

                  This routine aborts a sub-transaction and rolls back any changes made since the start of
                  the sub-transaction.

Syntax

                  IDI_USHORT OpiAbortSubTrans (ConID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

                  Before calling this routine, OpiStartTransaction and OpiStartSubTrans must have been
                  called in order to establish the transaction and sub-transaction, respectively. Calling this
                  routine will abort only those operations through the point at which OpiStartSubTrans was
                  last called. The parent transaction will still be in progress until OpiFinishTransaction or
                  OpiAbortTransaction is called.

                  OpiAbortSubTrans produces the return code OPI_ERROR if a sub-transaction is not in
                  progress.

                  Note: You can have only one nested transaction active at any given time. Sub-
                  transactions cannot be nested within other sub-transactions. For more information about
                  transactions, see “Updating a BASIS Database.”




194  Reference
              OpiAbortThesTrans
Description

              This routine aborts a thesaurus transaction and rolls back any changes made since the start
              of the transaction.

Syntax

              IDI_USHORT OpiAbortThesTrans (ConID)

Parameters

              ConID                                                                  OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

              None.




                                                                                        Reference  195
                  OpiAbortTransaction
Description

                  This routine aborts a database transaction and rolls back any changes made since the start
                  of the transaction.

Syntax

                  IDI_USHORT OpiAbortTransaction (ConID)

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

                  In your transaction, for every call to OpiStartGetTextData, there must be a corresponding
                  call to OpiFinishGetTextData when you are through. The OpiAbortTransaction routine
                  produces the return code OPI_ERROR if you have not provided the corresponding
                  OpiFinishGetTextData calls for all your OpiStartGetTextData calls.

                  A call to OpiAbortTransaction will also abort any underlying sub-transactions.
                  Therefore, sub-transactions that are in progress or finished will be rolled-back when
                  OpiAbortTransaction is called.

                  For more information about transactions, see “Updating a BASIS Database.”




196  Reference
              OpiAddThesRelation
Description

              This routine adds a thesaurus relation to a specified thesaurus.

Syntax

              IDI_USHORT OpiAddThesRelation (ConID, usAddAction, ThesaurusID,
                     ThesRelationID, fWait)

Parameters

              ConID                                                                       OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              usAddAction                                                             IDI_USHORT/Read

              Specifies the type of add operation you want to use. Possible values are:


              OPI_THES_ADD                  -   Add the new term(s) to a new lead term or to one that
                                                already exists in the thesaurus.

              OPI_THES_ADD_ONLY             -   Do not add the new term(s) if the lead term already
                                                exists in the thesaurus.

              ThesaurusID                                                     OPI_THESAURUSID/Read

              Specifies the ID of the thesaurus object.

              ThesRelationID                                              OPI_THESRELATIONID/Read

              Specifies the ID of the thesaurus relation object that contains the data.




                                                                                           Reference  197
                  fWait                                                                       IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. Possible values are:
                  IDI_TRUE        -   Wait for resources if they are not available.

                  IDI_FALSE       -   Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can be
                  accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

Comments

                  This routine is used to add a relationship to a thesaurus. It will perform validation on the
                  relationship specified against the thesaurus as it currently exists, then update the
                  appropriate records in the thesaurus database to add the relationship.

                  Not only will the relationship be added, but if a reciprocal is defined for the relation to be
                  added, the reciprocal will automatically be created, validated, and added to the thesaurus
                  database also.

                  If the usAddAction parameter is set to OPI_THES_ADD and lead term records do not
                  already exist for the added relations, then they will be added.

                  This routine must be executed from within a thesaurus transaction. All validation of the
                  relationship being added (except for nonpreferred terms in a translation thesaurus) is
                  performed by this routine.




198  Reference
              OpiAllocate
Description

              This routine allocates a block of dynamic memory for use in an OpenAPI application.

Syntax

              IDI_USHORT OpiAllocate (ulNumberOfObjects, ulSizeOfObjects, ppvBuffer)

Parameters

              ulNumberOfObjects                                                       IDI_ULONG/Read

              Specifies the number of objects for which space is to be allocated.

              ulSizeOfObjects                                                         IDI_ULONG/Read

              Specifies the size of the objects for which space is to be allocated.

              ppvBuffer                                                       IDI_PVOID IDI_PTR/Write

              Specifies a pointer to the pointer which references the first byte of allocated memory.

Comments

              In order to verify that memory has been allocated, the pointer referenced by ppvBuffer
              must be checked to ensure that it is not IDI_NULL. A value of IDI_NULL indicates that
              no memory has been allocated. This will occur if either ulNumberOfObjects or
              ulSizeOfObjects is 0 or if there is insufficient memory available for allocation.




                                                                                         Reference  199
                  OpiAppInitialize
Description

                  This routine initializes an OpenAPI application.

Syntax

                  IDI_USHORT OpiAppInitialize (IDI_VOID)

Comments

                  OpiAppInitialize is always the first call made by an OpenAPI application program.




200  Reference
              OpiApplyDdl
Description

              This routine applies pending change orders for a definition database.

Syntax

              IDI_USHORT OpiApplyDdl (ConID, DdbID)

Parameters

              ConID                                                                   OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DdbID                                                                   OPI_DDBID/Read

              Specifies the ID of the definition database object created by the OpiMakeDdb routine.
              This ID represents the definition database to which you want the change orders to be
              applied.

Comments

              You can post change orders to the definition database using the OpiCompileDdl routine.
              You must use OpiApplyDdl to apply the change orders and thereby complete the update
              to the definition database.

              Because it is not always possible to apply every change order, this routine produces the
              return code OPI_WARNING and informatives in the status info list for each change order
              that could not be applied. (For example, any orders that require database restructuring
              will return informatives until the database restructure is complete.)




                                                                                       Reference  201
                  OpiAppTerminate
Description

                  This routine terminates an OpenAPI application.

Syntax

                  IDI_USHORT OpiAppTerminate (IDI_VOID)

Comments

                  OpiAppTerminate is always the last call made by an OpenAPI application program.




202  Reference
              OpiBeginDatabase
Description

              This routine begins construction of a database object in a BNF file.

Syntax

              IDI_USHORT OpiBeginDatabase (ConID, FileID, DatabaseID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              DatabaseID                                                       OPI_DATABASEID/Read

              Specifies the ID of the database object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called BNF File Construction Routines.

              For more information about BNF files, see the section called BASIS Normal Form
              (BNF).




                                                                                          Reference  203
                  OpiBeginDocument
Description

                  This routine begins construction of a document object in a BNF file.

Syntax

                  IDI_USHORT OpiBeginDocument (ConID, FileID, DocumentID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  DocumentID                                                      OPI_DOCUMENTID/Read

                  Specifies the ID of the document object to be constructed.

Comments

                  For information about the calling sequence for the routines that construct objects in BNF
                  files, see the section called “BNF File Construction Routines.”

                  For more information about BNF files, see the section called “BASIS Normal Form
                  (BNF).”




204  Reference
              OpiBeginFieldGroup
Description

              This routine begins construction of a field group object in a BNF file.

Syntax

              IDI_USHORT OpiBeginFieldGroup (ConID, FileID, FieldGroupID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                    OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              FieldGroupID                                                    OPI_FIELDGROUPID/Read

              Specifies the ID of the field group object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called “BNF File Construction Routines.”

              For more information about BNF files, see the section called “BASIS Normal Form
              (BNF).”




                                                                                          Reference  205
                  OpiBeginIndText
Description

                  This routine begins construction of an indexed text object in a BNF file.

Syntax

                  IDI_USHORT OpiBeginIndText (ConID, FileID, IndTextID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  IndTextID                                                           OPI_INDTEXTID/Read

                  Specifies the ID of the indexed text object to be constructed.

Comments

                  For information about the calling sequence for the routines that construct objects in BNF
                  files, see the section called “BNF File Construction Routines.”

                  For more information about BNF files, see the section called “BASIS Normal Form
                  (BNF).”




206  Reference
              OpiBeginSection
Description

              This routine begins construction of a section object in a BNF file.

              Note:    Sectioned records are not supported on Windows operating systems.

Syntax

              IDI_USHORT OpiBeginSection (ConID, FileID, SectionID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              SectionID                                                             OPI_SECTIONID/Read

              Specifies the ID of the section object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called “BNF File Construction Routines.”

              For more information about BNF files, see the section called “BASIS Normal Form
              (BNF).”




                                                                                          Reference  207
                  OpiBeginStndField
Description

                  This routine begins construction of a standard field object in a BNF file.

Syntax

                  IDI_USHORT OpiBeginStndField (ConID, FileID, StndFieldID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                    OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating.

                  StndFieldID                                                        OPI_STNDFIELDID/Read

                  Specifies the ID of the standard field object to be constructed.

Comments

                  For information about the calling sequence for the routines that construct objects in BNF
                  files, see the section called “BNF File Construction Routines.”

                  For more information about BNF files, see the section called “BASIS Normal Form
                  (BNF).”




208  Reference
              OpiBeginTextStream
Description

              This routine begins construction of a text stream object in a BNF file.

Syntax

              IDI_USHORT OpiBeginTextStream (ConID, FileID, TextStreamID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                    OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              TextStreamID                                                    OPI_TEXTSTREAMID/Read

              Specifies the ID of the text stream object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called “BNF File Construction Routines.”

              For more information about BNF files, see the section called “BASIS Normal Form
              (BNF).”




                                                                                          Reference  209
                  OpiBeginTxtImgField
Description

                  This routine begins construction of a text image object field in a BNF file.

Syntax

                  IDI_USHORT OpiBeginTxtImgField (ConID, FileID, TxtImgFieldID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  TxtImgFieldID                                                OPI_TXTIMGFIELDID/Read

                  Specifies the ID of the text image field object to be constructed.

Comments

                  For information about the calling sequence for the routines that construct objects in BNF
                  files, see the section called “BNF File Construction Routines.”

                  For more information about BNF files, see the section called “BASIS Normal Form
                  (BNF).”




210  Reference
              OpiBrowse
Description

              This routine returns thesaurus terms from a specified thesaurus into a databuff object.

Syntax

              IDI_USHORT OpiBrowse (ConID, ulCursor, pszLanguageName, pszFieldName,
                     pszThesaurusID, pszCriterion, fExactCase, fDropCursor, usFormat,
                     usThesaurusLevel, usPosition, usLimit, fWait, DataBuffID, pusCount)

Parameters

              ConID                                                                   OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              ulCursor                                                                IDI_ULONG/Read

              Specifies an ID for the cursor established by the call to OpiBrowse. Possible values are
              any number between 1 and OPI_MAX_UCURSORS. If you specify zero, this routine
              produces the return code OPI_ERROR.

              The cursor established by the OpiBrowse call remains until you delete it by using the
              fDropCursor parameter. For more information about cursors, see Command Procedures,
              “Modifying the Database with Procs.”

              pszLanguageName                                                             IDI_PSZ/Read

              Specifies the language of the thesaurus to browse. Your DBA defines the codes
              associated with the various languages; see your DBA for these values. If you want to use
              the current language, specify a pointer to a null string for this parameter. The maximum
              length possible for a language code or null pointer is
              OPI_MAX_LANGUAGE_NAME_LC.

              pszFieldName                                                                IDI_PSZ/Read

              Specifies the field whose thesaurus you want to browse. You must fully qualify the field
              name with the name of the database, model, and view. The syntax is:
                  <database.model>view.field




                                                                                         Reference  211
                  You do not have to specify the database and model if they are the defaults you set using
                  the OpiSetConnectionValues routine. The length of the field name can range from 1 to
                  OPI_MAX_FIELD_ID_LC.

                  For instance, if you want to return the thesaurus terms for the LOCATION field in the
                  PLACE view in the DBA model of the TOUR database, you would specify the
                  OpiBrowse routine in the following manner:
                      OpiBrowse (ConId,...,"<TOUR.DBA>PLACE.LOCATION",...)

                  If you intend to indicate a thesaurus to browse by entering its thesaurus ID for the
                  pszThesaurusID parameter, the pszFieldName parameter must point to a null string.

                  pszThesaurusID                                                               IDI_PSZ/Read

                  Set this parameter to the ID of the thesaurus you want to browse. The syntax format is:
                      thesaurus_database.thesaurus_name

                  If you already indicated a thesaurus to browse by entering the name of its related field for
                  the pszFieldName parameter, the pszThesaurusID parameter must point to a null string.

                  The length of the thesaurus ID can range from 1 to OPI_MAX_THESAURUS_ID_LC

                  pszCriterion                                                                 IDI_PSZ/Read

                  Specifies the criterion that you want the system to look for in the thesaurus and return.
                  Possible values are shown below.


                  Possible Value                                           Example

                  character string or number                               Smith, John
                                                                           salesman
                                                                           1823

                  range of character strings                               'A':'JZZZ
                  or numbers                                               24:37

                  character pattern                                        'S'*
                                                                           'pres'*
                                                                           'rec'??'ve'
                                                                           *




212  Reference
The maximum length possible for a criterion value is OPI_MAX_CRITERION_LC.

For more details about each type of criterion, see The Complete FIND Handbook, “Basic
Searches.” The criteria values (shown in the above table) for the OpiBrowse routine
follow the same rules as the search values of the same name for the FIND command.
Single quotation marks around the criteria values are required where indicated.

For example, suppose you want the system to return the terms in the LOCATION index.
You could enter the following line in your code:
    OpiBrowse (ConID,1, "ENG", "<TOUR.ALL>PLACE.LOCATION", "",
    "*",...)

The system would return to the databuff object information similar to the following:
    RELATION           TERM                  MEMBERS      HITS     LEVEL         THESAURUS

    LEAD TERM          ABC ISLANDS               0          0          1          LOCATION
    BROAD TERM         NETHERLANDS ANTILLES      0          0          2          LOCATION
    NARROW TERM        ARUBA                     1          1          2          LOCATION
    NARROW TERM        BONAIRE                   1          1          2          LOCATION
    NARROW TERM        CURACAO                   1          1          2          LOCATION

    LEAD TERM          ACAPULCO                  0          0          1          LOCATION
    BROAD TERM         MEXICO                    1          1          2          LOCATION

    LEAD TERM          AFGHANISTAN               0          0          1          LOCATION
    BROAD TERM         ASIA                      0          0          2          LOCATION

    LEAD TERM          AFRICA                    0          0          1          LOCATION
    BROAD TERM         REGIONS                   0          0          2          LOCATION
    NARROW TERM        ALGERIA                   0          0          2          LOCATION
    NARROW TERM        BENIN                     0          0          2          LOCATION
    NARROW TERM        CAMEROON                  0          0          2          LOCATION
    NARROW TERM        EGYPT                     0          0          2          LOCATION
    NARROW TERM        ETHIOPIA                  0          0          2          LOCATION
    NARROW TERM        GHANA                     0          0          2          LOCATION
    NARROW TERM        GUINEA                    0          0          2          LOCATION
    NARROW TERM        IVORY COAST               0          0          2          LOCATION
    NARROW TERM        KENYA                     0          0          2          LOCATION

fExactCase                                                                 IDI_FLAG/Read

Specifies whether data is returned in the same case as it was entered into the thesaurus.


IDI_TRUE           -     Return data in the same case as it was entered into the thesaurus.

IDI_FALSE          -     Return data in the case your DBA defined in the thesaurus.

Note:    When you specify IDI_TRUE, browsing uses a lot of CPU time and memory.




                                                                            Reference  213
                  fDropCursor                                                                IDI_FLAG/Read

                  Specifies whether you want the system to remove the cursor specified by the ulCursor
                  parameter before searching the thesaurus for the specified criterion. The possible values
                  are:


                  IDI_TRUE            -   Drop the cursor before browsing.

                  IDI_FALSE           -   Don’t drop the cursor.

                  If the fDropCursor parameter is set to IDI_TRUE, the system returns the first lead term
                  that matches the criterion and all terms that follow it up to the number specified for the
                  usLimit parameter. When fDropCursor is set to IDI_FALSE, the cursor is always
                  established at the last term returned by this routine.

                  usFormat                                                                IDI_USHORT/Read

                  Specifies the thesaurus terms to return based on their relation type and hierarchical level.
                  The possible values are:


                  OPI_BFMT_ALL                The system returns all terms on the first level below that of
                                              the specified criterion.

                  OPI_BFMT_DOWN               The system returns terms on all levels below that of the
                                              specified criterion and whose relation type is defined with the
                                              usage of $SPECIFIC (for example, narrow term relation
                                              types).

                  OPI_BFMT_UP                 The system returns terms on all levels above that of the
                                              specified criterion and whose relation type is defined with the
                                              usage of $GENERAL (for example, broad term relation
                                              types).

                  OPI_BFMT_LEAD               The system returns only lead terms.

                  For information about relation types, usages, and hierarchical levels, see Thesaurus,
                  “About Relation-Types.”




214  Reference
usThesaurusLevel                                                       IDI_USHORT/Read

Specifies the total number of hierarchical levels to return when the usFormat parameter is
set to OPI_BFMT_DOWN or OPI_BFMT_UP. Possible values range from 1 to
OPI_MAX_THES_LEVELS.

usPosition                                                             IDI_USHORT/Read

Indicates which terms you want the system to return. This parameter is effective only
when the fDropCursor parameter is set to IDI_FALSE. If the fDropCursor parameter is
set to IDI_TRUE, the system returns the first lead term that matches the criterion and all
terms that follow it up to the number specified for the usLimit parameter. When
fDropCursor is set to IDI_FALSE, the cursor is always established at the last term
returned by this routine.

The possible values are:


OPI_BROWSE_FIRST_PRIM_TERM                     The system returns the first lead term that
                                               matches the criterion and all succeeding
                                               terms up to the number specified for the
                                               usLimit parameter.

OPI_BROWSE_NEXT_PRIM_TERM                      The system returns the lead term
                                               immediately following the last lead term
                                               returned by the preceding call to
                                               OpiBrowse and all succeeding terms up to
                                               the number specified for the usLimit
                                               parameter.

OPI_BROWSE_LAST_PRIM_TERM                      The system returns the last lead term that
                                               matches the search criteria and all
                                               preceding terms, in reverse order, up to
                                               the number specified by the usLimit
                                               parameter.

OPI_BROWSE_FIRST_RELATION                      The system returns the current lead term
                                               and all succeeding terms up to the number
                                               specified for the usLimit parameter. The
                                               current lead term is either the one to
                                               which the cursor points or, if the cursor
                                               points to a relationship term, the one
                                                                                       1
                                               associated with that relationship term.

OPI_BROWSE_NEXT_RELATION                       The system returns the term immediately



                                                                           Reference  215
                                                                   following the last term returned by the
                                                                   preceding call to OpiBrowse and all
                                                                   succeeding terms up to the number
                                                                   specified by the usLimit parameter.

                  OPI_BROWSE_PRIOR_RELATION                        The system returns the previous term
                                                                   under the current lead term and all
                                                                   preceding terms, in reverse order, up to
                                                                   the number specified by the usLimit
                                                                   parameter. When the current lead term is
                                                                   the first term, a value of 0 is returned in
                                                                   usCount.

                      1
                        If the relationship term is the last one in the associated lead term’s list, the next lead
                  term is the current lead term.

                  usLimit                                                                   IDI_USHORT/Read

                  Specifies the maximum number of thesaurus terms you want the system to return per
                  execution of OpiBrowse. Possible values are 1 to 500. If you specify zero, this routine
                  produces the return code OPI_ERROR. If you specify a number greater than the number
                  of available thesaurus terms, the system does not return an error. In this case, the system
                  will just return as many terms as it can.




216  Reference
           fWait                                                                       IDI_FLAG/Read

           Specifies whether you want your application to wait for system resources if they are not
           available when you execute this routine. The possible values are:


           IDI_TRUE              -     Wait for resources if they are not available.

           IDI_FALSE             -     Do not wait for resources if not available.

           If you specify IDI_FALSE and resources are not available, this routine produces the
           return code OPI_ERROR and the detailed status code OPI_STAT_NOWAIT. The status
           code can be accessed through the pulStatus parameter of the OpiGetDetailedStatus
           routine.

           DataBuffID                                                       OPI_DATABUFFID/Read

           Specifies the ID of a databuff object created by the OpiMakeDataBuff routine. This ID
           represents the databuff into which the thesaurus term information will be returned.

           Note: The databuff object should be large enough to hold at least the number of terms
           specified by the usLimit parameter. If the specified number of terms does not fit into the
           object, the system will attempt to read as many whole thesaurus terms as it can into the
           object. If there is a large discrepancy between the size of the databuff object and the
           number of terms returned, this routine could fail.

           pusCount                                                             IDI_PUSHORT/Write

           Points to the actual number of thesaurus terms written to the databuff object.

Comments

           None




                                                                                       Reference  217
                  OpiBrowseExtended
Description

                  This routine returns thesaurus terms from a specified thesaurus into a databuff object.

Syntax

                  IDI_USHORT OpiBrowseExtended (ConID, ulCursor, pszLanguageName,
                         pszFieldName, pszThesaurusID, pszCriterion, fExactCase, fDropCursor,
                         usFormat, pszRelNames, pszHierRelNames, usThesaurusLevel, usPosition,
                         usLimit, fWait, DataBuffID, pusCount)

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  ulCursor                                                                IDI_ULONG/Read

                  Specifies an ID for the cursor established by the call to OpiBrowseExtended. Possible
                  values are any number between 1 and OPI_MAX_UCURSORS. If you specify zero, this
                  routine produces the return code OPI_ERROR.

                  The cursor established by the OpiBrowseExtended call remains until you delete it by
                  using the fDropCursor parameter. For more information about cursors, see Command
                  Procedures, “Modifying the Database with Procs.”

                  pszLanguageName                                                             IDI_PSZ/Read

                  Specifies the language of the thesaurus to browse. Your DBA defines the codes
                  associated with the various languages; see your DBA for these values. If you want to use
                  the current language, specify a pointer to a null string for this parameter. The maximum
                  length possible for a language code or null pointer is
                  OPI_MAX_LANGUAGE_NAME_LC.

                  pszFieldName                                                                IDI_PSZ/Read

                  Specifies the field whose thesaurus you want to browse. You must fully qualify the field
                  name with the name of the database, model, and view. The syntax is:
                      <database.model>view.field




218  Reference
You do not have to specify the database and model if they are the defaults you set using
the OpiSetConnectionValues routine. The length of the field name can range from 1 to
OPI_MAX_FIELD_ID_LC.

For instance, if you want to return the thesaurus terms for the LOCATION field in the
PLACE view in the DBA model of the TOUR database, you would specify the
OpiBrowseExtended routine in the following manner:
    OpiBrowseExtended (ConId,...,"<TOUR.DBA>PLACE.LOCATION",...)

If you intend to indicate a thesaurus to browse by entering its thesaurus ID for the
pszThesaurusID parameter, the pszFieldName parameter must point to a null string.

pszThesaurusID                                                               IDI_PSZ/Read

Set this parameter to the ID of the thesaurus you want to browse. The syntax format is:
    thesaurus_database.thesaurus_name

If you already indicated a thesaurus to browse by entering the name of its related field for
the pszFieldName parameter, the pszThesaurusID parameter must point to a null string.

The length of the thesaurus ID can range from 1 to OPI_MAX_THESAURUS_ID_LC.

pszCriterion                                                                 IDI_PSZ/Read

Specifies the criterion that you want the system to look for in the thesaurus and return.
Possible values are shown below.


Possible Value                                           Example

character string or number                               Smith, John
                                                         salesman
                                                         1823

range of character strings                               'A':'JZZZ'
or numbers                                               24:37

character pattern                                        'S'*
                                                         'pres'*
                                                         'rec'??'ve'
                                                         *

The maximum length possible for a criterion value is OPI_MAX_CRITERION_LC + 1.


                                                                            Reference  219
                  For more details about each type of criterion, see The Complete FIND Handbook, “Basic
                  Searches.” The criteria values (shown in the above table) for the OpiBrowseExtended
                  routine follow the same rules as the search values of the same name for the FIND
                  command. Single quotation marks around the criteria values are required where
                  indicated.

                  fExactCase                                                                   IDI_FLAG/Read

                  Specifies whether data is returned in the same case as it was entered into the thesaurus.


                  IDI_TRUE              -    Return data in the same case as it was entered into the thesaurus.

                  IDI_FALSE             -    Return data in the case your DBA defined in the thesaurus.

                  Note: When you specify IDI_FALSE, OpiBrowseExtended uses the thesaurus indexes,
                  which don’t contain information regarding annotation symbols, classification tags,
                  reciprocal annotation symbols, or reciprocal classification tags. Therefore, if you intend
                  to view or update such information, you should specify IDI_TRUE.

                  fDropCursor                                                                  IDI_FLAG/Read

                  Specifies whether you want the system to remove the cursor specified by the ulCursor
                  parameter before searching the thesaurus for the specified criterion. The possible values
                  are:


                  IDI_TRUE          -       Drop the cursor before browsing.

                  IDI_FALSE         -       Don’t drop the cursor.

                  If the fDropCursor parameter is set to IDI_TRUE, the system returns the first lead term
                  that matches the criterion and all terms that follow it up to the number specified for the
                  usLimit parameter. When fDropCursor is set to IDI_FALSE, the cursor is always
                  established at the last term returned by this routine.




220  Reference
usFormat                                                                 IDI_USHORT/Read

Specifies the thesaurus terms to return based on their relation type and hierarchical level.
The possible values are:


OPI_BFMT_ALL                   -    The system returns all terms on the first level below that
                                    of the specified criterion.

OPI_BFMT_DOWN                  -    The system returns terms on all levels below that of the
                                    specified criterion and whose relation type is defined
                                    with the usage of $SPECIFIC (for example, narrow term
                                    relation types).

OPI_BFMT_UP                    -    The system returns terms on all levels above that of the
                                    specified criterion and for which the relation type is
                                    defined with the usage of $GENERAL (for example,
                                    broad term relation types).

OPI_BFMT_LEAD                  -    The system returns only lead terms.

OPI_BFMT_ALPHA                 -    The system returns all specified relations on the first
                                    level for the specified criteria.

OPI_BFMT_HIER                  -    The system returns terms on all levels for the specified
                                    hierarchical relations and all terms on the first level for
                                    the specified relations for the specified criteria.

OPI_BFMT_TOP_ALL               -    The system returns all top terms on the first level below
                                    the specified criterion.

OPI_BFMT_TOP_DOWN              -    The system returns top terms on all levels below the
                                    specified criterion and for which the relation type is
                                    defined with the usage of $SPECIFIC (for example,
                                    narrow term relation types).

OPI_BFMT_TOP_LEAD              -    The system returns only lead top terms.

OPI_BFMT_TOP_ALPHA             -    The system returns all specified top term relations on the
                                    first level for the specified criteria.

OPI_BFMT_TOP_HIER              -    The system returns top terms on all levels for the
                                    specified hierarchical relations and all terms on the first
                                    level for the specified relations for the specified criteria.



                                                                             Reference  221
                  For information about relation types, usages, hierarchical levels, and top terms, see
                  Thesaurus, “About Relation-Types.”

                  pszRelNames                                                                  IDI_PSZ/Read

                  Points to a string which identifies the relations or relation usages to be returned in the
                  browse. This parameter is used only when usFormat is set to OPI_BFMT_ALPHA or
                  OPI_BFMT_HIER. Each relation must be a null-terminated string, and the entire string
                  should be terminated with a null.




222  Reference
pszHierRelNames                                                                 IDI_PSZ/Read

Points to a string which identifies the hierarchical relations or usages to be returned in the
browse. This parameter is used only when usFormat is set to OPI_BFMT_HIER. Each
relation must be a null-terminated string, and the entire string should be terminated with a
null.

For example, suppose you want the system to return specifically the narrow term relations
and the scope notes for terms in the LOCATION index. You could enter the following
line in your code:
    OpiBrowseExtended (ConID,1, "ENG", "<TOUR.ALL>PLACE.LOCATION",
    "", "*", IDI_FALSE, OPI_BFMT_HIER, "SN\0\0", "NT\0\0", ...)

The system would return to the databuff object information similar to the following:
    RELATION         TERM                      MEMBERS      HITS       LEVEL       THESAURUS

    LEAD TERM        ABC ISLANDS                   0          0            1        LOCATION
    NARROW TERM      ARUBA                         1          1            2        LOCATION
    SCOPE NOTE       See Also: ABC Islands,        0          0            3        LOCATION
                     Bonaire, or Curacao
    NARROW TERM      BONAIRE                       1          1            2        LOCATION
    SCOPE NOTE       See Also: ABC Islands,        0          0            3        LOCATION
                     Aruba, or Curacao
    NARROW TERM      CURACAO                       1          1            2        LOCATION
    SCOPE NOTE       See Also: ABC Islands,        0          0            3        LOCATION
                     Aruba, or Bonaire

    LEAD TERM        AFRICA                        0          0            1        LOCATION
    NARROW TERM      ALGERIA                       0          0            2        LOCATION
    NARROW TERM      BENIN                         0          0            2        LOCATION
    NARROW TERM      CAMEROON                      0          0            2        LOCATION
    NARROW TERM      EGYPT                         0          0            2        LOCATION
    NARROW TERM      ETHIOPIA                      0          0            2        LOCATION
    NARROW TERM      GHANA                         0          0            2        LOCATION
    NARROW TERM      GUINEA                        0          0            2        LOCATION
    NARROW TERM      IVORY COAST                   0          0            2        LOCATION
    NARROW TERM      KENYA                         0          0            2        LOCATION




                                                                               Reference  223
                  For information about topics mentioned in the above example, see the sections listed
                  below:


                  For This Topic             See

                  Narrow term                Thesaurus, “About Relation-Types”

                  Scope note                 Thesaurus, “About Relation-Types”

                                             Thesaurus, “Entering Thesaurus Terms”

                  usThesaurusLevel                                                      IDI_USHORT/Read

                  Specifies the total number of hierarchical levels to return when the usFormat parameter is
                  set to OPI_BFMT_DOWN or OPI_BFMT_UP. Possible values range from 1 to
                  OPI_MAX_THES_LEVELS.

                  usPosition                                                            IDI_USHORT/Read

                  Indicates which terms you want the system to return. If the fDropCursor parameter is set
                  to IDI_TRUE, the system returns the first lead term that matches the criterion and all
                  terms that follow it up to the number specified for the usLimit parameter and the specific
                  usPosition. When fDropCursor is set to IDI_FALSE, the cursor is always established at
                  the last term returned by this routine.

                  The possible values are:


                  OPI_BROWSE_FIRST_PRIM_TERM                     The system returns the first lead term that
                                                                 matches the criterion and all succeeding
                                                                 terms up to the number specified for the
                                                                 usLimit parameter.

                  OPI_BROWSE_NEXT_PRIM_TERM                      The system returns the lead term
                                                                 immediately following the last lead term
                                                                 returned by the preceding call to
                                                                 OpiBrowse and all succeeding terms up to
                                                                 the number specified for the usLimit
                                                                 parameter.

                  OPI_BROWSE_LAST_PRIM_TERM                      The system returns the last lead term that
                                                                 matches the search criteria and all
                                                                 preceding terms, in reverse order, up to


224  Reference
                                                 the number specified for the usLimit
                                                 parameter.

OPI_BROWSE_FIRST_RELATION                        The system returns the current lead term
                                                 and all succeeding terms up to the number
                                                 specified for the usLimit parameter. The
                                                 current lead term is either the one to
                                                 which the cursor points or, if the cursor
                                                 points to a relationship term, the one
                                                                                         1
                                                 associated with that relationship term.

OPI_BROWSE_NEXT_RELATION                         The system returns the term immediately
                                                 following the last term returned by the
                                                 preceding call to OpiBrowse and all
                                                 succeeding terms up to the number
                                                 specified by the usLimit parameter.

OPI_BROWSE_PRIOR_RELATION                        The system returns the previous term
                                                 under the current lead term and all
                                                 preceding terms, in reverse order, up to
                                                 the number specified by the usLimit
                                                 parameter. When the current lead term is
                                                 the first term, a value of 0 is returned in
                                                 usCount.

    1
      If the relationship term is the last one in the associated lead term’s list, the next lead
term is the current lead term.

usLimit                                                                   IDI_USHORT/Read

Specifies the maximum number of thesaurus terms you want the system to return per
execution of OpiBrowseExtended. Possible values are 1 to 500. If you specify zero, this
routine produces the return code OPI_ERROR. If you specify a number greater than the
number of available thesaurus terms, the system does not return an error. In this case, the
system will return as many terms as it can.




                                                                              Reference  225
                  fWait                                                                       IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. The possible values are:


                  IDI_TRUE           -    Wait for resources if they are not available.

                  IDI_FALSE          -    Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  return code OPI_ERROR and the detailed status code OPI_STAT_NOWAIT. This status
                  code can be accessed through the pulStatus parameter of the OpiGetDetailedStatus
                  routine.

                  DataBuffID                                                      OPI_DATABUFFID/Read

                  Specifies the ID of a databuff object created by the OpiMakeDataBuff routine. This ID
                  represents the databuff into which the thesaurus term information will be returned.

                  Note: The databuff object should be large enough to hold at least the number of terms
                  specified by the usLimit parameter. If the specified number of terms does not fit into the
                  object, the system will attempt to read as many whole thesaurus terms as it can into the
                  object. If there is a large discrepancy between the size of the databuff object and the
                  number of terms returned, this routine could fail.

                  pusCount                                                                IDI_PUSHORT/Write

                  Points to the actual number of thesaurus terms written to the databuff object.

Comment s

                  None.




226  Reference
              OpiCancel
Description

              This routine cancels the last call to an OpenAPI routine.-

              Note: The OpiCancel routine can be used for any direct OpenAPI function. However, a
              remote OpenAPI call can only be cancelled if the client is communicating with a 32-bit
              Windows server.

Syntax

              IDI_USHORT OpiCancel (ConID)

Parameters

              ConID                                                                  OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine. The
              ConID must be the same as that provided for the function being canceled.

Comments

              You can attempt to cancel any call with this routine. When a call is canceled, the value
              OPI_STAT_CANCELLED is written to the pulStatus parameter of the
              OpiGetDetailedStatusInfo routine.

              The speed at which a cancel occurs depends on the function being canceled (i.e. OpiFind
              will cancel almost immediately while an OpiImportFile may never cancel).




                                                                                        Reference  227
                  OpiClearStatusInfo
Description

                  This routine removes all the error, warning, and informative messages from the status info
                  list.

Syntax

                  IDI_USHORT OpiClearStatusInfo (ConID)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

                  Use this routine after you have processed the messages generated by a single routine that
                  produced a return code of OPI_WARNING or OPI_ERROR.




228  Reference
              OpiClearViewBuff
Description

              This routine clears a view buffer object to its default state.

Syntax

              IDI_USHORT OpiClearViewBuff (ConID, ViewBuffID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              ViewBuffID                                                        OPI_VIEWBUFFID/Read

              Specifies the ID of the view buffer object to clear.

Comments

              View buffer attributes are not affected by this call. All view field objects in the view
              buffer are removed.




                                                                                          Reference  229
                  OpiCloseDb
Description

                  This routine closes a database.

Syntax

                  IDI_USHORT OpiCloseDb (ConID, pszModelSpec)

Parameters

                  ConID                                                                OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszModelSpec                                                             IDI_PSZ/Read

                  Specifies which database to close. The syntax format is:
                      <database.model>

                  The length of the name can range from 1 to OPI_MAX_MODEL_SPEC_LC.

Comments

                  None.




230  Reference
              OpiCloseDdb
Description

              This routine closes a definition database.

Syntax

              IDI_USHORT OpiCloseDdb (ConID, DdbID)

Parameters

              ConID                                                                 OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DdbID                                                                 OPI_DDBID/Read

              Specifies the ID of the definition database object created by the OpiMakeDdb routine.
              This ID represents the definition database you want to close.

Comments

              None.




                                                                                      Reference  231
                  OpiCloseFile
Description

                  This routine closes a BNF file that you have constructed. For more information about
                  BNF files, see the section called “BASIS Normal Form (BNF).”

Syntax

                  IDI_USHORT OpiCloseFile (ConID, FileID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object, created by the OpiMakeFile routine, that represents the
                  BNF file you constructed.

Comments

                  Before closing a BNF file, you must end construction of all objects; otherwise this routine
                  will yield the failure return code of OPI_ERROR. For more information about
                  constructing objects for a BNF file, see the section called “Procedures for Building a
                  BNF File.”

                  Once a BNF file is closed, you cannot assemble any more objects for it via the
                  construction routines.

                  A BNF file must be closed before it can be imported into a BASIS database.




232  Reference
               OpiCloseThesDb
Descript ion

               This routine closes a thesaurus database.

Syntax

               IDI_USHORT OpiCloseThesDb (ConID, pszThesDBSpec)

Paramet ers

               ConID                                                                 OPI_CONID/Read

               Specifies the ID of a connection object created by the OpiMakeConnection routine.

               pszThesDBSpec                                                             IDI_PSZ/Read

               Specifies which thesaurus database to close. This parameter contains the thesaurus
               database name, and its length can be from 1 to OPI_MAX_TDB_LC.

Comment s

               None.




                                                                                       Reference  233
                  OpiCompileDdl
Description

                  This routine compiles one or more DDL statements.

Syntax

                  IDI_USHORT OpiCompileDdl (ConID, DdbID, pszDdl, fCancelOnError, usAction)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  DdbID                                                                  OPI_DDBID/Read

                  Specifies the ID of the definition database object created by the OpiMakeDdb routine.
                  This ID represents the definition database into which you want the pszDdl statements
                  compiled.

                  pszDdl                                                                     IDI_PSZ/Read

                  Specifies a buffer of the DDL statement(s) to compile. In addition to ADM, UDM, and
                  SDM definition statements, DMDBA administrative statements such as
                  PERFORM/TASK (see “Comments” below) and PERFORM/MAINT can also be issued.
                  In a single call to this routine you may submit multiple DDL statements; together they can
                  be up to a maximum of 32,767 characters. For a complete description of valid DDL
                  statements, see Database Definition and Development.

                  fCancelOnError                                                           IDI_FLAG/Read

                  If fCancelOnError is set to IDI_TRUE, OpiCompileDdl will cancel any change orders
                  produced by the DDL statements when a compile error is detected.




234  Reference
           usAction                                                              IDI_USHORT/Read

           Specifies the action to perform on the DDL statement. The possible values are:



           Use this value              When                                 Comments

           OPI_ACTION_UPD              Processing a UDM, SDM, or            The definition database
                                       ADM statement                        (DDB) must be open

           OPI_ACTION_MAINT            Performing PERFORM/MAINT             The DDB must not be
                                       operations                           open

           OPI_ACTION_ADMIN            Performing PERFORM/TASK              The DDB must be open
                                       operations


Comments

           Some changes produced by compiling a DDL statement will occur automatically;
           however, other types of changes are deferred until OpiApplyDdl is called. For more
           information about change orders, see Database Definition and Development, “Change
           Codes.”

           If you use a PERFORM/TASK SHOW/option statement and there are subsequent results
           to be seen, this routine produces a return code of OPI_WARNING, indicating that
           informative messages—which constitute the results—are available.

           When submitting a UDM, SDM, or ADM statement, you must prefix it with a
           USER_DATA_MODEL, STRUCTURAL_DATA_MODEL, or
           ACTUAL_DATA_MODEL qualifier. For example,
               ACTUAL_DATA_MODEL;RECORD=OPI2NEW,STYLE=CONTINUOUS_DOCUMENT;
                 FIELD=KEY,UNIQUE=YES ,LABEL='Info',OCCURS=1:1,PRECISION=5,
                 TYPE=EXACT_BINARY;

           In a single call to this routine, you may submit multiple DDL statements, up to a
           maximum of 32,767 characters.




                                                                                     Reference  235
                  OpiConnDBServer
Description

                  This routine connects a connection object to a DB server.

Syntax

                  IDI_USHORT OpiConnDBServer (ConID, pszUserName, pszUserPw,
                         pszProgramName)

Parameters

                  ConID                                                                OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszUserName                                                              IDI_PSZ/Read

                  Specifies the BASIS user name. The length of the name can range from 1 to
                  OPI_MAX_USER_NAME_LC.

                  pszUserPw                                                                IDI_PSZ/Read

                  Specifies the BASIS user password. The length of the password can range from 1 to
                  OPI_MAX_PASSWORD_LC.

                  pszProgramName                                                           IDI_PSZ/Read

                  Specifies the name of your application program. The length of the name can range from 1
                  to OPI_MAX_PROGRAM_NAME_LC.

Comments

                  This routine signs onto the Kernel and validates the pszUserName and pszUserPw.




236  Reference
              OpiConnRPCServer
Description

              This routine connects a connection object to an OPIRPC server.

Syntax

              IDI_USHORT OpiConnRPCServer (ConID, pszCfgName, pszUserName, pszUserPw,
                     pRPCCallback)

Parameters

              ConID                                                                 OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszCfgName                                                                 IDI_PSZ/Read

              For 32-bit Windows applications, specifies the registry section(s) under
              HKEY_LOCAL_MACHINE\SOFTWARE\Information Dimensions that contains the
              remote connection setup information. This string may be composed of two keyword-
              value pairs separated by a semicolon:
                  "cfgresource=<start key>;cfgsect=<configuration key>"

              The <start key> value is the name of a registry section under
              HKEY_LOCAL_MACHINE\SOFTWARE\Information Dimensions which contains
              registry keys describing connection information. If this keyword-value pair is not
              specified, the Client registry section becomes the default. The <configuration key> value
              is the name of a registry key under <start key> that contains entries specifying registry
              keys under which connection parameters are specified. If the cfgresource keyword-value
              pair is not specified, the semicolon and “cfgsect=” string are not needed. However, to
              make a remote connection you must specify a section—there is no default value.

              For example, to use the V9_SERVER key defined under the
              HKEY_LOCAL_MACHINE\SOFTWARE\Information Dimensions\Client key, your
              OpiConnRPCServer call would look like this:
                  usRC = OpiConnRPCServer(ConID,"V9_SERVER",…);




                                                                                       Reference  237
                  Suppose under HKEY_LOCAL_MACHINE\SOFTWARE\Information Dimensions
                  you’ve defined your own registry key called MyResource, and under MyResource you
                  want to use a configuration key called MySetup. In this case, your OpiConnRPCServer
                  call would look like this:
                      usRC = OpiConnRPCServer(ConID,"cfgresource=MyResource;
                      cfgsect=MySetup",…);

                  The length of pszCfgName can range from 1 to OPI_MAX_FILE_NAME_LC.

                  pszUserName                                                               IDI_PSZ/Read

                  Specifies the RPC Server host user name. The length of the host user name can range
                  from 1 to OPI_MAX_HOST_USER_NAME_LC. This parameter is required only if the
                  registry and/or environment does not specify a host user name and you specify the default
                  Callback function for the pRPCCallback parameter.

                  pszUserPw                                                                 IDI_PSZ/Read

                  Specifies the RPC Server host user password. The length of the host password can range
                  from 1 to OPI_MAX_HOST_PASSWORD_NAME_LC. This parameter is required only
                  if the registry and/or environment does not specify a user password and you specify the
                  default Callback function for the pRPCCallback parameter.

                  pRPCCallback                                          OPI_SERVER_CALLBACK/Read
                  Points to the OpiServerCallback function. Currently, this parameter should always be set
                  to IDI_NULL, so that the default Callback function is utilized. The default Callback
                  function will set the RPC Server host user name and RPC Server host user password to
                  the values specified within pszUserPw and pRPCCallback if they are not specified within
                  the registry or environment.

Comments

                  This routine starts an instance of the OPIRPC server on the host system when necessary.




238  Reference
              OpiConstructPhysText
Description

              This routine constructs a physical text object in a BNF file.

Syntax

              IDI_USHORT OpiConstructPhysText (ConID, FileID, PhysTextID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              PhysTextID                                                        OPI_PHYSTEXTID/Read

              Specifies the ID of the physical text object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called “BNF File Construction Routines.”

              For more information about BNF files, see the section called “BASIS Normal Form
              (BNF).”




                                                                                          Reference  239
                  OpiConstructSubfield
Description

                  This routine constructs a subfield object in a BNF file.

Syntax

                  IDI_USHORT OpiConstructSubfield (ConID, FileID, SubfieldID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  SubfieldID                                                         OPI_SUBFIELDID/Read

                  Specifies the ID of the subfield object to be constructed.

Comments

                  For information about the calling sequence for the routines that construct objects in BNF
                  files, see the section called “BNF File Construction Routines.”

                  For more information about BNF files, see the section called “BASIS Normal Form
                  (BNF).”




240  Reference
              OpiConstructTxtImgLine
Description

              This routine constructs a text image line in a BNF file.

Syntax

              IDI_USHORT OpiConstructTxtImgLine (ConID, FileID, TxtImgLineID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              TxtImgLineID                                                   OPI_TXTIMGLINEID/Read

              Specifies the ID of the text image line object to be constructed.

Comments

              For information about the calling sequence for the routines that construct objects in BNF
              files, see the section called “BNF File Construction Routines.”

              For more information about BNF files, see the section called “BASIS Normal Form
              (BNF).”




                                                                                          Reference  241
                  OpiCopyFile
Description

                  This routine will copy a source file to a destination file.

Syntax

                  IDI_USHORT OpiCopyFile (ConID, SourceFileID, DestFileID, usOpenRetryCount,
                         fUnique, fAppend, fXlatChars, fXlatEndOfLines, cbXferStatus)

Parameters

                  ConID                                                                        OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  SourceFileID                                                                 OPI_FILEID/Read

                  Specifies the ID of the file object that represents the source file.

                  DestFileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the destination file.

                  usOpenRetryCount                                                            IDI_USHORT/Read

                  Specifies the number of retries to attempt when trying to open the source file or
                  destination file. A one-second pause will occur between each attempt. This parameter is
                  useful for compensating for shared file system delays.

                  fUnique                                                                       IDI_FLAG/Read

                  Specifies whether this routine should create a unique destination file name. Possible
                  values are:


                  IDI_TRUE         -   This routine will create a unique file name using the destination file
                                       name provided in DestFileD as a template.

                  IDI_FALSE        -   This routine will not alter the file name provided in DestFileID.




242  Reference
Note: If you specify IDI_TRUE, the pszFile parameter provided to OpiMakeFile (or
set by the OPI_ATT_FILE_NAME_OR_AREA attribute of OpiSetFileAttr) will be
modified to place a unique value just prior to the file type, if one is provided. For
example, a pszFile value of
    /usr/tmp/out.tmp

may be modified to
    /usr/tmp/out12345_0.tmp.

The file name created by this routine may be obtained by a call to OpiGetFileAttr
specifying the OPI_ATT_FILE_NAME_OR_AREA attribute.

 If you specify IDI_FALSE, the pszFile value provided to OpiMakeFile (or set by the
OPI_ATT_FILE_NAME_OR_AREA attribute of OpiSetFileAttr) must contain a
complete file descriptor, including the file area, base, and type.

fAppend                                                                    IDI_FLAG/Read

Specifies whether the contents of the source file should be appended to the destination
file. Possible values are:


IDI_TRUE        -    The source file contents should be appended to the destination file. If
                     the destination file does not exist, it will be created.

IDI_FALSE       -    The source file contents should be placed into a new destination file.
                     This implies that if the destination file already exists, this routine
                     produces a return code of OPI_ERROR and a status code of
                     OPI_STAT_FILE_EXISTS, which can be accessed through the
                     pulStatus parameter of the OpiGetDetailedStatus routine.

fXlatChars                                                                 IDI_FLAG/Read

Specifies whether characters in the source file should be mapped from the character set of
the source-file system to the character set of the destination-file system before being
written to the destination file. Possible values are:


IDI_TRUE        -    Perform character set translation.

IDI_FALSE       -    Do not perform character set translation.




                                                                            Reference  243
                  Note: Regardless of the setting of this flag, no character set translation will occur if the
                  source and destination file objects were set to the same usFileType when they were
                  created with OpiMakeFile.

                  fXlatEndOfLines                                                            IDI_FLAG/Read

                  Specifies whether end-of-line translation should be performed as data is copied from the
                  source file to the destination file. The mapping of source file end-of-line terminators to
                  destination file end-of-line terminators is determined by the
                  OPI_ATT_FILE_EOL_TYPE attribute for each file object. This attribute is given a
                  default value by OpiMakeFile but may be changed by OpiSetFileAttr. Possible values
                  are:


                  IDI_TRUE        -    Change source file end-of-line terminators to destination file end-of-
                                       line terminators prior to writing the data to the destination file.

                  IDI_FALSE       -    Do not change source file end-of-line terminators.

                  cbXferStatus                                                     OPI_XFERSTATUSCB/Read

                  Specifies an optional callback routine to allow the reporting of transfer status information.
                  This parameter can be useful for implementing “gas gauge” displays that allow the user to
                  monitor the progress of transfers that take some time to complete. This routine has the
                  following parameters:


                  Parameter                         Description

                  ConID                             Connection object

                  SourceFileID                      Source file object

                  DestFileID                        Destination file object

                  ulSizeOfSourceFile                Size of source file in bytes

                  ulBytesTransferred                Number of bytes transferred




244  Reference
Comments

           The fXlatChars and fXlatEndOfLines control flags should be set only for text files.

           Since fUnique implies a nonexistent file, setting fUnique to IDI_TRUE will cause
           fAppend to be ignored.

           File objects created as file type OPI_FILE_OTHER with OpiMakeFile cannot be used as
           either a source or destination file object in OpiCopyFile.

           The fAppend control flag may be used for both text and binary files but may be
           appropriate only with text files.

           If fUnique is set to IDI_TRUE, OpiCopyFile tries up to 50 times to create a unique file
           name. If within those 50 attempts it cannot determine a unique file name, OpiCopyFile
           returns a detailed status code of OPI_STAT_FILE_EXISTS. You must call OpiMakeFile
           with a different destination file name and then call OpiCopyFile with fUnique set to
           IDI_TRUE again. You shouldn’t encounter this problem if you delete unique files
           created by OpiCopyFile that are no longer needed. You can obtain the unique file name
           with the OpiGetFileAttr command. You can perform file deletions of remote files with
           the OpiExecRemote command.

           If you set fAppend to IDI_TRUE, don’t set both the SourceFileID and the DestFileID
           parameters to point to the same physical file—doing so may cause the destination file
           device to become full.

           If the file represented by DestFileID exists and fUnique is IDI_FALSE, the destination
           file will be overwritten.

           OpiCopyFile is supported only by OpenAPI Client applications.




                                                                                    Reference  245
                  OpiDeleteDoc
Description

                  This routine deletes a document from the database.

Syntax

                  IDI_USHORT OpiDeleteDoc (ConID, pszViewRef, fWait)

Parameters

                  ConID                                                                         OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszViewRef                                                                       IDI_PSZ/Read

                  Specifies the record to delete. The syntax format is either of the following:
                       [set, member]<database.model>view

                  or
                       [key_field_name = value]<database.model>view

                  where


                       set - is the number of the result set that contains the desired record
                       member - is the number of the record’s position in the result set
                       key_field_name - is any unique field of the desired record
                       value - is the contents of the record’s unique field
                       database - is the name of the database that contains the record
                       model - is the name of the model that contains the record
                       view - is the name of the view for the desired record

                  The length of your record specification in either of the syntax formats can range from 1 to
                  OPI_MAX_VIEWREF_LC.




246  Reference
           fWait                                                                    IDI_FLAG/Read

           Specifies whether you want your application to wait for system resources if they are not
           available when you execute this routine. The possible values are:


           IDI_TRUE        -   Wait for resources if they are not available.

           IDI_FALSE       -   Do not wait for resources if not available.

           If you specify IDI_FALSE and resources are not available, this routine produces the
           failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
           be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

Comments

           This routine can be called only from within a transaction.




                                                                                     Reference  247
                  OpiDeleteFile
Description

                  This routine deletes a file.

Syntax

                  IDI_USHORT OpiDeleteFile(ConID,FileID)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                 OPI_FILEID/Read

                  Specifies the ID of a file object created by the OpiMakeFile routine. This ID represents
                  the file you want to delete.

Comments

                  None.




248  Reference
              OpiDeleteSec
Description

              This routine deletes a section of a document from the database.

              Note:    Sectioned records are not supported on Windows operating systems.

Syntax

              IDI_USHORT OpiDeleteSec(ConID,pszViewRef,pszSecName,fWait)

Parameters

              ConID                                                                       OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszViewRef                                                                     IDI_PSZ/Read

              Specifies the record that contains the section to delete. The syntax format is either of the
              following:
                   [set, member]<database.model>view

              or
                   [key_field_name = value]<database.model>view

              where


                   set is the number of the result set that contains the desired record
                   member is the number of the record’s position in the result set
                   key_field_name is any unique field of the desired record
                   value is the contents of the record’s unique field
                   database is the name of the database that contains the record
                   model is the name of the model that contains the record
                   view is the name of the view for the desired record

              The length of your record specification in either of the syntax formats can range from 1 to
              OPI_MAX_VIEWREF_LC.




                                                                                           Reference  249
                  pszSecName                                                                 IDI_PSZ/Read

                  Specifies the name of the section to delete. The length of the section name can range
                  from 1 to OPI_MAX_SECTION_NAME_LC.

                  fWait                                                                    IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. The possible values are:


                  IDI_TRUE        -   Wait for resources if they are not available.

                  IDI_FALSE       -   Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
                  be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

Comments

                  This routine can only be called from within a transaction.




250  Reference
              OpiDeleteThesRelation
Description

              This routine will delete a thesaurus relation in a specified thesaurus.

Syntax

              IDI_USHORT OpiDeleteThesRelation (ConID, usDeleteAction, ThesaurusID,
                     ThesRelationID, fWait)

Parameters

              ConID                                                                       OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              usDeleteAction                                                            IDI_USHORT/Read

              Specifies whether the lead term record associated with the relation being deleted should
              be deleted if the relation is the only relation for the lead term. Possible values are


              OPI_THES_DELETE                       -     Delete lead if the relation is the only one under
                                                          it.

              OPI_THES_DEL_KEEP_LEAD                -     Lead term is not to be deleted when the last
                                                          relation for the lead term is deleted.



              ThesaurusID                                                       OPI_THESAURUSID/Read

              Specifies the ID of the thesaurus object.

              ThesRelationID                                                OPI_THESRELATIONID/Read

              Specifies the ID of the thesaurus relation object containing the data to be deleted.




                                                                                             Reference  251
                  fWait                                                                        IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. Possible values are:


                  IDI_TRUE        -   Wait for resources if they are not available.

                  IDI_FALSE       -   Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
                  be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

Comments

                  This routine is used to delete a relationship from a thesaurus. It will delete the
                  appropriate records in the thesaurus database needed to delete the relationship.

                  This routine must be executed from within a thesaurus transaction.

                  Not only will the specified relationship be deleted, but if a reciprocal is defined for the
                  relation to be deleted, it will automatically be deleted from the thesaurus also.

                  In addition, if the relation being deleted from the thesaurus is the last relation referencing
                  that particular lead term, the lead term record will also be deleted when the delete action
                  is OPI_THES_DELETE.




252  Reference
For example, given the following relations (where LT means lead term relation, Windows
means narrow term relation, and BT means broad term relation)
 LT         A

 NT         B

 NT         C

 LT         B

 BT         A

 LT         C

 BT         A

if the LT A relation is deleted, all the relations under lead term A are deleted as well as all
of their reciprocal relations. Therefore, all of the above relations would be deleted.




                                                                             Reference  253
                  OpiDestroyBrowseTerm
Description

                  This routine destroys a browse term object.

Syntax

                  IDI_USHORT OpiDestroyBrowseTerm (ConID, BrowseTermID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  BrowseTermID                                                OPI_BROWSETERMID/Read

                  Specifies the ID of the browse term object to destroy.

Comments

                  This routine releases all resources allocated to the browse term object. Since it also frees
                  the memory for this object, the ID is no longer usable.




254  Reference
              OpiDestroyConnection
Description

              This routine destroys a connection object.

Syntax

              IDI_USHORT OpiDestroyConnection (ConID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of the connection object to destroy.

Comments

              This routine releases all resources allocated to the connection object. Since it also frees
              the memory for this object, the ID is no longer usable.




                                                                                          Reference  255
                  OpiDestroyDatabase
Description

                  This routine destroys a database object.

Syntax

                  IDI_USHORT OpiDestroyDatabase (ConID, DatabaseID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  DatabaseID                                                       OPI_DATABASEID/Read

                  Specifies the ID of the database object to destroy.

Comments

                  This routine releases all resources allocated to the database object. Since it also frees the
                  memory for this object, the ID is no longer usable.




256  Reference
              OpiDestroyDataBuff
Description

              This routine destroys a databuff object.

Syntax

              IDI_USHORT OpiDestroyDataBuff (ConID, DataBuffID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DataBuffID                                                        OPI_DATABUFFID/Read

              Specifies the ID of the databuff object to destroy.

Comments

              This routine releases all resources allocated to the databuff object. Since it also frees the
              memory for this object, the ID is no longer usable.




                                                                                           Reference  257
                  OpiDestroyDdb
Description

                  This routine destroys a definition database object.

Syntax

                  IDI_USHORT OpiDestroyDdb (ConID, DdbID)

Parameters

                  ConID                                                                 OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  DdbID                                                                 OPI_DDBID/Read

                  Specifies the ID of the definition database object created by the OpiMakeDdb routine.
                  This ID represents a definition database object to destroy.

Comments

                  None.




258  Reference
              OpiDestroyDefBnfAttrs
Description

              This routine destroys a BNF attributes object.

Syntax

              IDI_USHORT OpiDestroyDefBnfAttrs (ConID, DefBnfAttrsID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DefBnfAttrsID                                               OPI_DEFBNFATTRSID/Read

              Specifies the ID of the BNF attributes object to destroy.

Comments

              This routine releases all resources allocated to the BNF attributes object. Since it also
              frees the memory for this object, the ID is no longer usable.




                                                                                          Reference  259
                  OpiDestroyDocument
Description

                  This routine destroys a document object.

Syntax

                  IDI_USHORT OpiDestroyDocument (ConID, DocumentID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  DocumentID                                                     OPI_DOCUMENTID/Read

                  Specifies the ID of the document object to destroy.

Comments

                  This routine releases all resources allocated to the document object. Since it also frees
                  the memory for this object, the ID is no longer usable.




260  Reference
              OpiDestroyField
Description

              This routine destroys a field object.

Syntax

              IDI_USHORT OpiDestroyField (ConID, FieldID)

Parameters

              ConID                                                                      OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FieldID                                                                  OPI_FIELDID/Read

              Specifies the ID of the field object to destroy.

Comments

              This routine releases all resources allocated to the field object. Since it also frees the
              memory for this object, the ID is no longer usable.




                                                                                            Reference  261
                  OpiDestroyFieldGroup
Description

                  This routine destroys a field group object.

Syntax

                  IDI_USHORT OpiDestroyFieldGroup (ConID, FieldGroupID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FieldGroupID                                                   OPI_FIELDGROUPID/Read

                  Specifies the ID of the field group object to destroy.

Comments

                  This routine releases all resources allocated to the field group object. Since it also frees
                  the memory for this object, the ID is no longer usable.




262  Reference
              OpiDestroyFieldList
Description

              This routine destroys a fieldlist.

Syntax

              IDI_USHORT OpiDestroyFieldList (ConID, FieldListID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FieldListID                                                       OPI_FIELDLISTID/Read

              Specifies the ID of the fieldlist to destroy.

Comments

              When a fieldlist is destroyed, it is no longer accessible and can no longer be used for calls
              to OpiGetData or OpiGetTextData.




                                                                                          Reference  263
                  OpiDestroyFile
Description

                  This routine destroys a file object.

Syntax

                  IDI_USHORT OpiDestroyFile (ConID, FileID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object to destroy.

Comments

                  Destroying a file object does not delete a file. It merely releases the memory that was
                  used by the file object so that it can be used again. Once this call is complete, the ID of
                  the destroyed file object is no longer usable.




264  Reference
              OpiDestroyIndText
Description

              This routine destroys an indexed text object.

Syntax

              IDI_USHORT OpiDestroyIndText (ConID, IndTextID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              IndTextID                                                           OPI_INDTEXTID/Read

              Specifies the ID of the indexed text object to destroy.

Comments

              This routine releases all resources allocated to the indexed text object. Since it also frees
              the memory for this object, the ID is no longer usable.




                                                                                          Reference  265
                  OpiDestroyInstSpec
Description

                  This routine destroys an instance specifier object.

Syntax

                  IDI_USHORT OpiDestroyInstSpec (ConID, InstSpecID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  InstSpecID                                                          OPI_INSTSPECID/Read

                  Specifies the ID of the instance specifier object to destroy.

Comments

                  This routine releases all resources allocated to the instance specifier object. Since it also
                  frees the memory for this object, the ID is no longer usable.




266  Reference
              OpiDestroyLookTerm
Description

              This routine destroys a look term object.

Syntax

              IDI_USHORT OpiDestroyLookTerm (ConID, LookTermID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              LookTermID                                                       OPI_LOOKTERMID/Read

              Specifies the ID of the look term object to destroy.

Comments

              This routine releases all resources allocated to the look term object. Since it also frees the
              memory for this object, the ID is no longer usable.




                                                                                          Reference  267
                  OpiDestroyMember
Description

                  This routine destroys a member object.

Syntax

                  IDI_USHORT OpiDestroyMember (ConID, MemberID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  MemberID                                                           OPI_MEMBERID/Read

                  Specifies the ID of the member object to destroy.

Comments

                  This routine releases all resources allocated to the member object. Since it also frees the
                  memory for this object, the ID is no longer usable.




268  Reference
              OpiDestroyPhysText
Description

              This routine destroys a physical text object.

Syntax

              IDI_USHORT OpiDestroyPhysText (ConID, PhysTextID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              PhysTextID                                                        OPI_PHYSTEXTID/Read

              Specifies the ID of the physical text object to destroy.

Comments

              The routine releases all resources allocated to the physical text object. Since it also frees
              the memory for this object, the ID is no longer usable.




                                                                                           Reference  269
                  OpiDestroySection
Description

                  This routine destroys a section object.

                  Note:    Sectioned records are not supported on Windows operating systems.

Syntax

                  IDI_USHORT OpiDestroySection (ConID, SectionID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  SectionID                                                            OPI_SECTIONID/Read

                  Specifies the ID of the section object to destroy.

Comments

                  This routine releases all resources allocated to the section object. Since it also frees the
                  memory for this object, the ID is no longer usable.




270  Reference
              OpiDestroyStatusEntry
Description

              This routine destroys a status entry object.

Syntax

              IDI_USHORT OpiDestroyStatusEntry (ConID, StatusEntryID)

Parameters

              ConID                                                                      OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              StatusEntryID                                                OPI_STATUSENTRYID/Read

              Specifies the ID of the status entry object to destroy.

Comments

              This routine releases all resources allocated to the status entry object. Since it also frees
              the memory for this object, the ID is no longer usable.




                                                                                           Reference  271
                  OpiDestroyStndField
Description

                  This routine destroys a standard field object.

Syntax

                  IDI_USHORT OpiDestroyStndField (ConID, StndFieldID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  StndFieldID                                                      OPI_STNDFIELDID/Read

                  Specifies the ID of the standard field object to destroy.

Comments

                  This routine releases all resources allocated to the standard field object. Since it also
                  frees the memory for this object, the ID is no longer usable.




272  Reference
              OpiDestroySubfield
Description

              This routine destroys a subfield object.

Syntax

              IDI_USHORT OpiDestroySubfield (ConID, SubfieldID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              SubfieldID                                                         OPI_SUBFIELDID/Read

              Specifies the ID of the subfield object to destroy.

Comments

              This routine releases all resources allocated to the subfield object. Since it also frees the
              memory for this object, the ID is no longer usable.




                                                                                           Reference  273
                  OpiDestroyTextStream
Description

                  This routine destroys a text stream object.

Syntax

                  IDI_USHORT OpiDestroyTextStream (ConID, TextStreamID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  TextStreamID                                                  OPI_TEXTSTREAMID/Read

                  Specifies the ID of the text stream object to destroy.

Comments

                  This routine releases all resources allocated to the text stream object. Since it also frees
                  the memory for this object, the ID is no longer usable.




274  Reference
              OpiDestroyThesaurus
Description

              This routine destroys a thesaurus object created by OpiMakeThesaurus.

Syntax

              IDI_USHORT OpiDestroyThesaurus (ConID, ThesaurusID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              ThesaurusID                                                    OPI_THESAURUSID/Read

              Specifies the ID of the thesaurus object to destroy.

Comments

              This routine releases all resources allocated to the thesaurus object. Because it also frees
              the memory for this object, the ID is no longer usable.




                                                                                          Reference  275
                  OpiDestroyThesRelation
Description

                  This routine destroys a thesaurus relation ID created by OpiMakeThesRelation.

Syntax

                  IDI_USHORT OpiDestroyThesRelation (ConID, ThesRelationID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  ThesRelationID                                             OPI_THESRELATIONID/Read

                  Specifies the ID of the thesaurus relation object to destroy.

Comments

                  This routine releases all resources allocated to the thesaurus relation object. Because this
                  routine also frees the memory for this object, the ID is no longer usable.




276  Reference
              OpiDestroyTocEntry
Description

              This routine destroys a toc entry object.

Syntax

              IDI_USHORT OpiDestroyTocEntry (ConID, TocEntryID)

Parameters

              ConID                                                                      OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              TocEntryID                                                        OPI_TOCENTRYID/Read

              Specifies the ID of the toc entry object to destroy.

Comments

              This routine releases all resources allocated to the toc entry object. Since it also frees the
              memory for this object, the ID is no longer usable.




                                                                                           Reference  277
                  OpiDestroyTxtImgField
Description

                  This routine destroys a text image field object.

Syntax

                  IDI_USHORT OpiDestroyTxtImgField (ConID, TxtImgFieldID)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  TxtImgFieldID                                                 OPI_TXTIMGFIELDID/Read

                  Specifies the ID of the text image field object to destroy.

Comments

                  This routine releases all resources allocated to the text image field object. Since it also
                  frees the memory for this object, the ID is no longer usable.




278  Reference
              OpiDestroyTxtImgLine
Description

              This routine destroys a text image line object.

Syntax

              IDI_USHORT OpiDestroyTxtImgLine (ConID, TxtImgLineID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              TxtImgLineID                                                   OPI_TXTIMGLINEID/Read

              Specifies the ID of the text image line object to destroy.

Comments

              This routine releases all resources allocated to the text image line object. Since it also
              frees the memory for this object, the ID is no longer usable.




                                                                                           Reference  279
                  OpiDestroyViewBuff
Description

                  This routine destroys a view buffer object.

Syntax

                  IDI_USHORT OpiDestroyViewBuff (ConID, ViewBuffID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  ViewBuffID                                                       OPI_VIEWBUFFID/Read

                  Specifies the ID of the view buffer object to destroy.

Comments

                  This routine does not delete a view but rather releases all resources allocated to the view
                  buffer object. Since it also frees the memory for this object, the ID is no longer usable.




280  Reference
              OpiDestroyViewField
Description

              This routine destroys a view field object.

Syntax

              IDI_USHORT OpiDestroyViewField (ConID, ViewFieldID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              ViewFieldID                                                      OPI_VIEWFIELDID/Read

              Specifies the ID of the view field object to destroy.

Comments

              This routine releases all resources allocated to the view field object. Since it also frees
              the memory for this object, the ID is no longer usable.




                                                                                           Reference  281
                  OpiDestroyXformCtl
Description

                  This routine destroys a transformation control object. All resources that were allocated to
                  the transformation control object are released.

Syntax

                  IDI_USHORT OpiDestroyXformCtl (XformCtlID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  XformCtlID                                                      OPI_XFORMCTLID/Read

                  Specifies the ID of the transformation control object to destroy.

Comments

                  This routine releases all resources allocated to the transformation control object. Since it
                  also frees the memory for this object, the ID is no longer usable.




282  Reference
              OpiDiscardSets
Description

              This routine discards result sets created with the OpiFind routine.

Syntax

              IDI_USHORT OpiDiscardSets (ConID, plResultSetList, ulResultSetListLen)

Parameters

              ConID                                                                 OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              plResultSetList                                                       IDI_PLONG/Read

              Points to an array of numbers where each entry is the number of a result set you want to
              discard. The data type of the numbers in the array is IDI_LONG. If you want to discard
              all the result sets, specify zero in the array.

              ulResultSetListLen                                                    IDI_ULONG/Read

              Specifies the total number of set numbers in the array.

Comments

              None.




                                                                                       Reference  283
                  OpiDiscDBServer
Description

                  This routine disconnects a connection object from a DB server.

Syntax

                  IDI_USHORT OpiDiscDBServer (ConID)

Parameters

                  ConID                                                                OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

                  None.




284  Reference
              OpiDiscRPCServer
Description

              This routine disconnects a connection object from an OPIRPC server.

Syntax

              IDI_USHORT OpiDiscRPCServer (ConID)

Parameter

              ConID                                                                  OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

              This routine stops the instance of the OPIRPC server on the host system if necessary.




                                                                                       Reference  285
                  OpiEditThesRelation
Description

                  This routine will edit a thesaurus relation of a specified thesaurus.

Syntax

                  IDI_USHORT OpiEditThesRelation (ConID, usEditAction, ThesaurusID,
                         OldThesRelID, NewThesRelID, fWait)

Parameters

                  ConID                                                                      OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  usEditAction                                                             IDI_USHORT/Read

                  Specifies what type of editing is to take place. Based on the type of editing requested,
                  this routine expects certain parameters to be specified. The required parameters are given
                  for each type of edit.


                  OPI_THES_EDIT                          -    The edit occurs based on the information passed.

                  OPI_THES_EDIT_INFORM                   -    The informative relation contains old text and
                                                              new text that should be replaced within the
                                                              informative relation.

                  OPI_THES_EDIT_KEEP_LEAD                -    If a relation was deleted as part of the edit, the
                                                              lead term of that relation will remain when it has
                                                              no secondary terms.

                  ThesaurusID                                                      OPI_THESAURUSID/Read

                  Specifies the ID of the thesaurus object.




286  Reference
           OldThesRelID                                                OPI_THESRELATIONID/Read

           Specifies the ID of the thesaurus relation object containing data for the old relation to be
           edited.

           NewThesRelID                                                OPI_THESRELATIONID/Read

           Specifies the ID of the thesaurus relation object containing data that will replace the
           OldThesRelID.

           fWait                                                                       IDI_FLAG/Read

           Specifies whether you want your application to wait for system resources if they are not
           available when you execute this routine. Possible values are:


           IDI_TRUE        -   Wait for resources if they are not available.

           IDI_FALSE       -   Do not wait for resources if not available.

           If you specify IDI_FALSE and resources are not available, this routine produces the
           return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can be
           accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

Comments

           This routine is used to edit a relationship in a thesaurus. It will perform validation on the
           changed relationship(s) specified against the thesaurus as it currently exists, then update
           the appropriate relations.

           The edit will always modify the specified relation as well as the reciprocal relation as
           required.

           The length of the old thesaurus relation plus the length of the new thesaurus relation
           cannot exceed 15000 characters; if it does, a status of 43669 is returned.

           This routine must be executed from within a thesaurus transaction.




                                                                                        Reference  287
                  OpiEndDatabase
Description

                  This routine ends construction of a database object in a BNF file.

Syntax

                  IDI_USHORT OpiEndDatabase (ConID, FileID, DatabaseID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  DatabaseID                                                       OPI_DATABASEID/Read

                  Specifies the ID of the database object whose construction is being ended.

Comments

                  For information about BNF, see “Updating a BASIS Database.” For information about
                  the calling sequence for the routines that construct objects in BNF files, see the section
                  called “BNF File Construction Routines.” For more information about BNF files, see the
                  section called “BASIS Normal Form (BNF).”




288  Reference
              OpiEndDocument
Description

              This routine ends construction of a document object in a BNF file.

Syntax

              IDI_USHORT OpiEndDocument (ConID, FileID, DocumentID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              DocumentID                                                      OPI_DOCUMENTID/Read

              Specifies the ID of the document object whose construction is being ended.

Comments

              For information about BNF, see “Updating a BASIS Database.” For information about
              the calling sequence for the routines that construct objects in BNF files, see the section
              called “BNF File Construction Routines.” For more information about BNF files, see the
              section called “BASIS Normal Form (BNF).”




                                                                                          Reference  289
                  OpiEndFieldGroup
Description

                  This routine ends construction of a field group object in a BNF file.

Syntax

                  IDI_USHORT OpiEndFieldGroup (ConID, FileID, FieldGroupID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  FieldGroupID                                                   OPI_FIELDGROUPID/Read

                  Specifies the ID of the field group object whose construction is being ended.

Comments

                  For information about BNF, see “Updating a BASIS Database.” For information about
                  the calling sequence for the routines that construct objects in BNF files, see the section
                  called “BNF File Construction Routines.” For more information about BNF files, see the
                  section called “BASIS Normal Form (BNF).”




290  Reference
              OpiEndIndText
Description

              This routine ends construction of an indexed text object in a BNF file.

Syntax

              IDI_USHORT OpiEndIndText (ConID, FileID, IndTextID)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                    OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              IndTextID                                                           OPI_INDTEXTID/Read

              Specifies the ID of the indexed text object whose construction is being ended.

Comments

              For information about BNF, see “Updating a BASIS Database.” For information about
              the calling sequence for the routines that construct objects in BNF files, see the section
              called “BNF File Construction Routines.” For more information about BNF files, see the
              section called “BASIS Normal Form (BNF).”




                                                                                          Reference  291
                  OpiEndSection
Description

                  This routine ends construction of a section object in a BNF file.

                  Note:    Sectioned records are not supported on Windows operating systems.

Syntax

                  IDI_USHORT OpiEndSection (ConID, FileID, SectionID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  SectionID                                                           OPI_SECTIONID/Read

                  Specifies the ID of the section object whose construction is being ended.

Comments

                  For information about BNF, see “Updating a BASIS Database.” For information about
                  the calling sequence for the routines that construct objects in BNF files, see the section
                  called “BNF File Construction Routines.” For more information about BNF files, see the
                  section called “BASIS Normal Form (BNF).”




292  Reference
              OpiEndStndField
Description

              This routine ends construction of a standard field object in a BNF file.

Syntax

              IDI_USHORT OpiEndStndField (ConID, FileID, StndFieldID)

Parameters

              ConID                                                                      OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                     OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              StndFieldID                                                      OPI_STNDFIELDID/Read

              Specifies the ID of the standard field object whose construction is being ended.

Comments

              For information about BNF, see “Updating a BASIS Database.” For information about
              the calling sequence for the routines that construct objects in BNF files, see the section
              called “BNF File Construction Routines.” For more information about BNF files, see the
              section called “BASIS Normal Form (BNF).”




                                                                                          Reference  293
                  OpiEndTextStream
Description

                  This routine ends construction of a text stream object in a BNF file.

Syntax

                  IDI_USHORT OpiEndTextStream (ConID, FileID, TextStreamID)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                   OPI_FILEID/Read

                  Specifies the ID of the file object that represents the BNF file you are creating to import.

                  TextStreamID                                                  OPI_TEXTSTREAMID/Read

                  Specifies the ID of the text stream object whose construction is being ended.

Comments

                  For information about BNF, see “Updating a BASIS Database.” For information about
                  the calling sequence for the routines that construct objects in BNF files, see the section
                  called “BNF File Construction Routines.” For more information about BNF files, see the
                  section called “BASIS Normal Form (BNF).”




294  Reference
              OpiEndTxtImgField
Description

              This routine ends construction of a text image field in a BNF file.

Syntax

              IDI_USHORT OpiEndTxtImgField (ConID, FileID, TxtImgFieldID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object that represents the BNF file you are creating to import.

              TxtImgFieldID                                                OPI_TXTIMGFIELDID/Read

              Specifies the ID of the text image field object whose construction is being ended.

Comments

              For information about BNF, see “Updating a BASIS Database.” For information about
              the calling sequence for the routines that construct objects in BNF files, see the section
              called “BNF File Construction Routines.” For more information about BNF files, see the
              section called “BASIS Normal Form (BNF).”




                                                                                          Reference  295
                  OpiExecRemote
Description

                  This routine will execute a command on the server.

Syntax

                  IDI_USHORT OpiExecRemote (ConID, pszCommand)

Parameters

                  ConID                                                                OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszCommand                                                               IDI_PSZ/Read

                  Specifies the command to be executed on the server. This command must be in a syntax
                  that is compatible with the server’s command interpreter.

Comments

                  Any input and output to the command must be accomplished through the use of shared or
                  server-based files. The OpiCopyFile routine can be used to accomplish this.

                  OpiExecRemote is supported only by OpenAPI Client applications.




296  Reference
              OpiExportFile
Description

              This routine exports a record (or portions of a record) from a BASIS database to a file.

Syntax

              IDI_USHORT OpiExportFile (ConID, FileID, InstSpecID, usIntent, usExportDomain,
                     pszConverter, XformCtlID, cbExportStatus, usErrorLimit, fWait,
                     pszPhysTextFormat)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FileID                                                                   OPI_FILEID/Read

              Specifies the ID of the file object you want to receive the exported record.

              Note: The file object must represent a file which can be written to by the server
              performing the export. The only valid file types for this file object are
              OPI_FILE_OTHER and OPI_FILE_REMOTE. The file type is specified through the use
              of the OpiMakeFile routine.

              InstSpecID                                                         OPI_INSTSPECID/Read

              Specifies the ID of the instance specifier object which identifies the record section(s)
              containing the data you want to export.

              usIntent                                                                IDI_USHORT/Read

              Specifies whether you want to access the desired record from the data area or the queue
              area of the database. It also affects which locks are set when the record data is exported.

              Note: On Windows operating systems, BASIS does not store records in the queue area.
              The queue contains only Queue Status Records; all data records are stored only in the
              database.




                                                                                          Reference  297
                  The possible values are:


                  OPI_INTENT_READ                  -   The record is exported from the data area of the
                                                       database. Other users will be able to update the
                                                       record.

                  OPI_INTENT_QREAD                 -   The record is exported from the queue area if it exists
                                                       there, otherwise it is exported from the data area of the
                                                       database. Other users will be able to update the
                                                       record.

                  OPI_INTENT_CHECKOUT              -   The record is exported from the queue if it exists
                                                       there, otherwise it is exported from the data area of the
                                                       database. This intent value allows you to read or
                                                       update the record. Other users may read it, but not
                                                       update it. This lock remains until the record is re-
                                                       imported or you discard it by using the
                                                       OpiQueueDiscardDoc routine.

                                                       If you choose this intent value, then you must define a
                                                       queue area for the specified view in the instance
                                                       specifier object and you must call OpiExportFile from
                                                       within a transaction.

                  usExportDomain                                                         IDI_USHORT/Read

                  Specifies the domain of record data to be exported. If you want to export more than one
                  domain of data simultaneously, then set a variable to a list of the domain names separated
                  by plus signs (+) as follows:
                      usDomains = OPI_DOMAIN_DOCLVLFIELDGROUP +
                      OPI_DOMAIN_SECLVLINDTEXT




298  Reference
The names of possible domains are shown below.
If you specify this value                         Data in this domain is exported

OPI_DOMAIN_DOCLVLFIELDGROUP                       Document-level Field Group
                                                                                           2
OPI_DOMAIN_DOCLVLPHYSTEXTXREF                     Document-level Physical Text Stream

OPI_DOMAIN_DOCLVLINDTEXT                          Document-level Indexed Text Stream
                                                                              1
OPI_DOMAIN_SECLVLFIELDGROUP                       Section-level Field Group
                                                                                       1
OPI_DOMAIN_SECLVLPHYSTEXTXREF                     Section-level Physical Text Stream
                                                                                       1
OPI_DOMAIN_SECLVLINDTEXT                          Section-level Indexed Text Stream

OPI_DOMAIN_ALL                                    All domains

    1
        Sectioned records are not supported on Windows operating systems and do not
        apply for XML converters.
    2
        For XML converters, OPI_DOMAIN_DOCLVLINDTEXT is included in the
        domain if the requested domain contains
        OPI_DOMAIN_DOCLVLPHYSTEXTXREF.

For more information about domains, see “Updating a BASIS Database,” the section
called “The Export Process.”

pszConverter                                                             IDI_PSZ/Read

Specifies the name of the XML or indirect document interchange converter you have
defined to export the record. The length of the converter name can range from 1 to
OPI_MAX_CONV_NAME_LC.

The following are XML and indirect document interchange converters that are defined in
your default style guide:

    SYS_MS_WORD_SOFT_INDIRECT
    SYS_WP_5_HARD_INDIRECT
    SYS_TEXT_HARD_INDIRECT
    SYS_BLOB_HARD_INDIRECT
    SYS_XML_INDIRECT
    SYS_XML




                                                                       Reference  299
                  Note:    If you specify a converter that is not an XML or indirect document interchange
                           converter, then this routine produces a failure return code of OPI_ERROR.

                  For more information about document interchange and XML converters, see Database
                  Loading and Maintenance.

                  XformCtlID                                                           OPI_XFORMCTLID/Read

                  Specifies the ID of a transformation control object, which indicates how the document is
                  to be transformed during the export. If you want to use all the default attribute values for
                  the transformation information, you can do so without having to create a transformation
                  control object by specifying IDI_NULL for this parameter.

                  Note:    This parameter does not apply if you are using an XML converter.

                  cbExportStatus                                              IDI_EXPORTSTATUSCB/Read

                  Reserved for future use. For now, you must specify IDI_NULL for this parameter.

                  usErrorLimit                                                             IDI_USHORT/Read

                  Reserved for future use. For now, you must specify zero for this parameter.

                  fWait                                                                       IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. The possible values are:


                  IDI_TRUE         -   Wait for resources if they are not available.

                  IDI_FALSE        -   Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
                  be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

                  pszPhysTextFormat                                                            IDI_PSZ/Write

                  Points to the format of the last physical text object exported. Length is from 1 to
                  OPI_MAX_PHY_TEXT_FORMAT_LC. This parameter will be especially useful in
                  future releases of OpenAPI. For more information about the physical text object, see
                  “Updating a BASIS Database,” the section called “BASIS Normal Form.”

                  Note:    This parameter does not apply if you are using an XML converter.




300  Reference
Comments

           When you export a BASIS record, the system may return multiple files. Since more than
           one file may be created, the system takes the liberty of assigning its own names to the
           files. The following diagrams show the domains and the names of the files to which
           they’re exported.




                                                                                   Reference  301
                               Indirect Document Interchange Converters

                  These domains:                                      Are exported to a file called:
                  Conventional
                   doc-level field group                                  filename.ext


                  Continuous                                              filename.DPT
                   doc-level field group
                   doc-level indexed text
                   doc-level physical text
                                                                          filename.SPT
                                                                          (if a single section is exported)

                  Sectioned
                  doc-level field group                                   S #######.SPT
                  sec-level field group                                   (if multiple sections are exported,
                                                                          there will be one of these files for
                  sec-level indexed text
                                                                          each section exported)
                  sec-level physical text


                  where


                  filename and ext           are the same as the name and extension of the BNF file
                                             represented by the file object you specified in the FileID
                                             parameter of the OpiExportFile routine.

                  pound signs (#)            represent numbers; these filenames will follow an ascending
                  (in S#######.SPT)          numerical sequence (for example, S0000001.SPT,
                                             S0000002.SPT, S0000003.SPT, etc.).




302  Reference
                      XML Converters

These domains:                            Are exported to:
    Direct method

doc-level indexed text                An XML file filename.ext

    Indirect method
                                      A data file named filename.ext
doc-level field group
                                      that contains meta data and a
doc-level indexed text
                                      reference to the corresponding
                                      XML document
                                      An XML document filename.xml


   where


   filename and ext            are the same as the name and extension of the file
                               represented by the file object you specified in the FileID
                               parameter of the OpiExportFile routine.

   Note: XML documents are always stored as Continuous style records in BASIS. Also, the
        XML document is stored as a record’s indexed text; nothing is stored in the physical
        text portion of the record.




                                                                             Reference  303
                  OpiFind
Description

                  This routine searches a database for records that meet the specified criteria and returns
                  them in a result set. It also returns result set information in the OPI_FINDRESULTS data
                  structure.

Syntax

                  USHORT OpiFind (ConID, pszFindString, pszLanguage, fEnableThesaurus,
                       fKeepReferences, usThesaurusLevel, usSearchOption, ulTimeout, usLimit,
                       fWait, usIntent, DataBuffID, pusCount, pFindResults)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszFindString                                                              IDI_PSZ/Read

                  Points to a FIND command, which you supply. The maximum length possible for a FIND
                  command is OPI_MAX_FIND_STRING_LC. For information about the syntax for the
                  FIND command, see The Complete FIND Handbook.

                  Note: All the usual rules regarding syntax apply. Single quotation marks are still
                  necessary around search values where indicated.

                  pszLanguage                                                                IDI_PSZ/Read

                  Specifies the language of the thesaurus to access when you specify IDI_TRUE for the
                  fEnableThesaurus parameter. Your DBA defines the codes associated with the various
                  languages; see your DBA for these values. If you want to use the current language,
                  specify a pointer to a null string for this parameter. The maximum length possible for a
                  language code or null pointer is OPI_MAX_LANGUAGE_NAME_LC.




304  Reference
fEnableThesaurus                                                         IDI_FLAG/Read

Specifies whether you want the system to use a thesaurus to enhance the search value(s) in
your FIND command. The system can use a thesaurus only on the fields that have one
defined for them. For information about the way a thesaurus affects a search, see The
Complete FIND Handbook, “Command Parameters.” For more information about
thesauri in general, see Thesaurus.

The possible values are:


IDI_TRUE        -   Use a thesaurus if one is defined for the field.

IDI_FALSE       -   Do not use a thesaurus.

fKeepReferences                                                          IDI_FLAG/Read

Specifies whether you want the system to count and identify references in the records
retrieved by your FIND command. A reference is any term, in a record’s field, that
matches the search value in your FIND command.

The possible values are:


IDI_TRUE        -   Count and identify references.

IDI_FALSE       -   Do not count and identify references.

Note: If you select IDI_FALSE, then the system will return zero in the ulReferences
field of the OPI_FINDRESULTS data structure.

usThesaurusLevel                                                       IDI_USHORT/Read

Specifies the hierarchical levels to use when referencing a thesaurus. The system will
access levels one through the number you specify for this parameter. Possible values
range from 1 to OPI_MAX_THES_LEVELS.




                                                                          Reference  305
                  usSearchOption                                                      IDI_USHORT/Read

                  Specifies how you want the system to perform the search. Possible values are shown
                  below.


                  This value                              Tells the system to

                  OPI_SEARCH_OPT_OPTIMIZE                 Use the standard BASIS optimization strategy.

                  OPI_SEARCH_OPT_INDEX                    Always use an index when searching indexed
                                                          fields. Scan records when searching non-
                                                          indexed fields.

                                                          If you specify an indexed field and an
                                                          incompatible test operator in your FIND
                                                          command, then this routine produces a return
                                                          code of OPI_ERROR and the pulStatus
                                                          parameter in the OpiGetDetailedStatus routine
                                                          will be set to OPI_STAT_INCOMP_SEARCH.

                  OPI_SEARCH_OPT_INDEX_ONLY               Search only indexed fields and use their indexes.

                                                          If you specify a non-indexed field in your FIND
                                                          command, this routine produces a return code of
                                                          OPI_ERROR and the pulStatus parameter in the
                                                          OpiGetDetailedStatus routine will be set to
                                                          OPI_STAT_NO_INDEX_ERR.

                                                          If, in your FIND command, you specify a test
                                                          operator that is incompatible with indexed field,
                                                          then this routine produces a return code of
                                                          OPI_ERROR and the pulStatus parameter in the
                                                          OpiGetDetailedStatus routine will be set to
                                                          OPI_STAT_INCOMP_SEARCH.

                  OPI_SEARCH_OPT_SCAN                     Scan records when searching indexed or non-
                                                          indexed fields. Ignore all indexes.

                  The default is OPI_SEARCH_OPT_OPTIMIZE.




306  Reference
ulTimeout                                                               IDI_ULONG/Read

Specifies the maximum amount of CPU time to continue searching. Possible values range
from zero to OPI_MAX_FIND_TIMEOUT seconds. If you do not want a CPU time
limit, specify zero. When the CPU time limit is reached, OpiFind automatically stops
executing and produces a return code of OPI_WARNING. If you call the
OpiGetDetailedStatus routine immediately, its pulStatus parameter will be set to
OPI_STAT_FIND_TIMED_OUT (2123).

usLimit                                                                  IDI_SHORT/Read

Specifies the maximum number of thesaurus terms to return in the databuff object. This
routine may return thesaurus terms if you set the fEnableThesaurus parameter to
IDI_TRUE and your DBA has activated the NOTIFY option. If there are no thesaurus
terms, then nothing is returned in the databuff object. For information about the NOTIFY
option for the thesaurus, see The Complete FIND Handbook, “Command Parameters.”

fWait                                                                      IDI_FLAG/Read

Specifies whether you want your application to wait for system resources if they are not
available when you execute this routine. The possible values are:


IDI_TRUE        -   Wait for resources if they are not available.

IDI_FALSE       -   Do not wait for resources if not available.

If you specify IDI_FALSE and resources are not available, this routine produces the
failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

usIntent                                                               IDI_USHORT/Read

Specifies the record-level locks you want the system to activate for the records retrieved
by the FIND command. This parameter is especially important when you execute the
OpiFind routine within a transaction.

When you access records through a transaction, you can set several levels of protection
(that is, locks). These locks determine what you and other users can and can’t do to the
records during the transaction. There are four levels of protection: database, model,
view, and record. The usIntent parameter sets protection at the record level, that is, each
record retrieved by the FIND command is locked according to the value specified for
usIntent. The possible values for usIntent and their descriptions are:




                                                                           Reference  307
                  OPI_INTENT_READ                -   You may only read the records in the result set. Other
                                                     users may access these records to read or update.

                  OPI_INTENT_UPDATE              -   You may read, update, or delete the records in the
                                                     result set. Other users may only read the records in the
                                                     result set. This value is valid only when the OpiFind
                                                     routine is executed within a transaction.

                  OPI_INTENT_CURRENT             -   If the OpiFind routine is executed outside a transaction,
                                                     then this value translates to OPI_INTENT_READ,
                                                     otherwise it translates to OPI_INTENT_UPDATE.

                  For more information about transactions and intents, see Database Loading and
                  Maintenance. For more information about using transactions in your OpenAPI
                  application, see “Updating a BASIS Database.”

                  DataBuffID                                                      OPI_DATABUFFID/Read

                  Specifies the ID of a databuff object created by the OpiMakeDataBuff routine. This
                  databuff object will hold the thesaurus terms returned by this routine. This routine may
                  return thesaurus terms if you set the fEnableThesaurus parameter to IDI_TRUE and your
                  DBA has activated the NOTIFY option. If there are no thesaurus terms, then nothing is
                  returned in the databuff object. For information about the NOTIFY option for the
                  thesaurus, see The Complete FIND Handbook, “Command Parameters.” For information
                  about accessing thesaurus terms returned in the databuff object, see “Searching a
                  Database.”

                  Note: The databuff object should be large enough to hold at least the number of terms
                  specified by the usLimit parameter. If the specified number of terms does not fit into the
                  databuff object, then the system attempts to read as many whole thesaurus terms as it can
                  into the databuff object. If there is a large discrepancy between the size of the databuff
                  and the number of terms returned, this routine could fail.

                  If you do not enable a thesaurus for the search, then you do not need a databuff object and
                  should specify null for this parameter.

                  pusCount                                                             IDI_PUSHORT/Write

                  Indicates the actual number of thesaurus terms returned in the databuff object.




308  Reference
pFindResults                                                   OPI_PFINDRESULTS/Write

Points to the OPI_FINDRESULTS data structure where the system returns information
related to the result set.

The OPI_FINDRESULTS data structure contains three fields. These fields are:


ulMembers       -   the number of members (that is, records) in the result set

ulReferences    -   the total number of references (that is, hits) in the result set

ulResultSet     -   the result set number

Note: If the fKeepReferences parameter is set to IDI_FALSE, then the ulReferences
field will contain the number zero.




                                                                             Reference  309
                  OpiFinishGetTextData
Description

                  This routine frees the record selected by the OpiStartGetTextData routine. Use this
                  routine after all of the record’s text stream field data has been processed using
                  OpiGetTextData.

Syntax

                  IDI_USHORT OpiFinishGetTextData (ConID, FieldListID)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FieldListID                                                     OPI_FIELDLISTID/Read

                  Specifies the ID of a field list created by the OpiMakeFieldList routine. The FieldListID
                  should be the same as one specified for a call to the OpiStartGetTextData routine,
                  otherwise, this routine returns the failure status code 2.




310  Reference
              OpiFinishSubTrans
Description

              This routine finishes a sub-transaction.

Syntax

              IDI_USHORT OpiFinishSubTrans (ConID)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

              Before calling this routine, OpiStartTransaction and OpiStartSubTrans must have been
              called to establish the transaction and sub-transaction, respectively. Note that the parent
              transaction will still be in progress until you call OpiFinishTransaction or
              OpiAbortTransaction.

              Note: A call to OpiAbortTransaction will roll back the results of the sub-transaction,
              even if the sub-transaction was finished and not aborted. For example, if
              OpiAbortTransaction is called after finishing the sub-transaction with
              OpiFinishSubTrans, all of the work completed within the parent transaction (including the
              sub-transaction) will be rolled back.




                                                                                          Reference  311
                  OpiFinishThesTrans
Description

                  This routine finishes a transaction and commits changes to the thesaurus database.

Syntax

                  IDI_USHORT OpiFinishThesTrans (ConID)

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

                  None.




312  Reference
              OpiFinishTransaction
Description

              This routine finishes a transaction and commits the changes to the database.

Syntax

              IDI_USHORT OpiFinishTransaction (ConID)

Parameters

              ConID                                                                  OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

Comments

              In your transaction, for every call to OpiStartGetTextData, there must be a corresponding
              call to OpiFinishGetTextData when you are through. If you have not provided the
              corresponding OpiFinishGetTextData calls for all your OpiStartGetTextData calls, the
              OpiFinishTransaction routine produces the return code OPI_ERROR.

              You must abort or finish any sub-transactions using OpiAbortSubTrans or
              OpiFinishSubTrans prior to your call to OpiFinishTransaction. OpiFinishTransaction
              produces the return code OPI_ERROR if a sub-transaction has not been finished (with
              OpiFinishSubTrans) or aborted (with OpiAbortSubTrans) prior to finishing the parent
              transaction.

              For more information about transactions, see “Updating a BASIS Database.”




                                                                                        Reference  313
                  OpiFree
Description

                  This routine frees a block of dynamic memory allocated by an OpenAPI routine.

Syntax

                  IDI_USHORT OpiFree (pvBuffer)

Parameters

                  pvBuffer                                                               OPI_PVOID/Write

                  This pointer references the first byte of a dynamically allocated block of memory.

Comments

                  OpiFree must always be used to free memory allocated by OpiAllocate or allocated within
                  any other OpenAPI routine. If any other function is used to free the memory, there is no
                  guarantee that the memory will be properly freed.




314  Reference
              OpiGetAuthorizationEntry
Description

               This routine returns an authorization entry for a BASIS user and a BASIS database
              model for which the user is authorized. Subsequent calls to the routine can be used to
              obtain a related set of authorization entries. The set may consist of either 1) all database
              models for a given user, or 2) all users for a given database model.

              This routine is now deprecated. The preferred method for obtaining Authorization
              Entries is now OpiSAGetAuthorizations.

Syntax

              IDI_USHORT OpiGetAuthorizationEntry (ConID, pszUserName, pszDatabaseName,
                     pszModelName, usPositionOfEntry, pAuthorizationEntry)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszUserName                                                                   IDI_PSZ/Read

              The name of a single user or “*”. A user name of “*” indicates all user names for a
              specific database.

              Note: When the user name is specified as “*”, the database name may not be specified as
              “*”.

              pszDatabaseName                                                               IDI_PSZ/Read

              The name of a single database or “*”. A database of "*" indicates all databases for a
              specific user.

              Note: When the database name is specified as “*”, the user name may not be specified as
              “*”.

              pszModelName                                                                  IDI_PSZ/Read

              The name of a single model or "*". A model of "*" indicates all models.

              Note: When the database name is specified as “*”, the model name must be specified as
              “*” also.


                                                                                          Reference  315
                  usPositionOfEntry                                                     IDI_USHORT/Read

                  Specifies the authorization entry for which information is to be obtained. The possible
                  specifications are:

                   Value                                          Meaning

                   OPI_AUTHORIZATION_ENTRY_FIRST                  The first authorization entry fitting the
                                                                  specified criterion of User Name,
                                                                  Database Name, and Model Name is
                                                                  returned.

                   OPI_AUTHORIZATION_ENTRY_NEXT                   The next authorization entry fitting the
                                                                  specified criterion of User Name,
                                                                  Database Name, and Model Name is
                                                                  returned.

                  pAuthorizationEntry                            OPI_PAUTHORIZATION_ENTRY/Write

                  A pointer to an OPI_AUTHORIZATION_ENTRY struct. Within this structure will be
                  placed all authorization information for one user to one database model.

Comments

                  The first call to OpiGetAuthorizationEntry must always be made with usPositionOfEntry
                  set to OPI_AUTHORIZATION_ENTRY_FIRST. Subsequent calls for related to entries
                  in a set must be made with OPI_AUTHORIZATION_ENTRY_NEXT. When there are
                  no more authorization entries to be obtained for the given criterion, the value of
                  OPI_STAT_END_OF_INFO is written to the pulStatus parameter of the
                  OpiGetDetailedStatus routine.




316  Reference
              OpiGetBrowseTerm
Description

              The routine transfers a thesaurus term from a databuff object to a browse term object.

Syntax

              IDI_USHORT OpiGetBrowseTerm (ConID, DataBuffID, BrowseTermID,
                     usBrowseTermNum)

Parameters

              ConID                                                                   OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DataBuffID                                                      OPI_DATABUFFID/Read

              Specifies the ID of the databuff object containing the thesaurus terms you want to access.

              BrowseTermID                                               OPI_BROWSETERMID/Read

              Specifies the ID of the browse term object where the thesaurus term from the databuff
              object is returned.

              usBrowseTermNum                                                       IDI_USHORT/Read

              Specifies the number of the thesaurus term in the databuff object you want to return in the
              browse term object. (Items in a databuff object are numbered starting at zero.)

Comments

              None.




                                                                                        Reference  317
                  OpiGetBrowseTermAttrs
Description

                  This routine transfers thesaurus term information from a browse term object to an
                  OPI_BROWSETERMATTRS data structure.

Syntax

                  IDI_USHORT OpiGetBrowseTermAttrs (ConID, BrowseTermID, pBrowseTermAttr)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  BrowseTermID                                                OPI_BROWSETERMID/Read

                  Specifies the ID of the browse term object containing the thesaurus term information you
                  want to access.

                  pBrowseTermAttrs                                     OPI_PBROWSETERMATTRS/Write

                  Points to a OPI_BROWSETERMATTRS data structure where the thesaurus term
                  information from the browse term object is returned. This information includes: the
                  thesaurus term, its relation type, name of the thesaurus it’s from, its level number, number
                  of records containing the term, and number of references that occur in these records. For
                  more information, see “Data Structures.”

Comments

                  None.




318  Reference
              OpiGetConnectionAttr
Description

              This routine gets the attribute values of a connection object.

Syntax

              IDI_USHORT OpiGetConnectionAttr (ConID, usAttribute, pvValue)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              usAttribute                                                              IDI_USHORT/Read

              Specifies the attribute you want to get. See “Comments” below for the names of the
              possible attributes.

              pvValue                                                                    IDI_PVOID/Write

              Points to the location to which to return the attribute specified in the usAttribute
              parameter. See “Comments” below for a list of the attributes.

Comments

              The following list shows the attributes for a connection object and their corresponding
              values. For each of the attributes, the user must specify a pointer to a variable whose data
              type matches the attribute’s data type.

              OPI_ATT_CONV_BYTESTR_TO_HEX                                                        IDI_FLAG

              Specifies whether to convert the byte string field data to hexadecimal format. For more
              information, see “Accessing Record Data for Display.”


              IDI_TRUE             -       Convert the data.

              IDI_FALSE            -       Do not convert the data.

              This attribute defaults to IDI_FALSE after the execution of OpiMakeConnection.



                                                                                           Reference  319
                  OPI_ATT_DEFAULT_MODEL_SPEC                                                        IDI_PSZ

                  Specifies the default database and model being used by your application. When other
                  OpenAPI routines require a view or field name, you do not need to fully qualify them if
                  their corresponding database and model match the defaults. The syntax is:
                      <database.model>

                  The total length of the database and model name can range from 1 to
                  OPI_MAX_MODEL_SPEC_LC.

                  Note: If this attribute is requested after a call to OpiOpenDdb but prior to a call to
                  OpiSetConnectionAttr, which sets the default database, the value returned by this attribute
                  will be incorrect.

                  OPI_ATT_FORMAT_OUTPUT                                                          IDI_FLAG

                  Specifies whether the designated UDM output format is being used to format field data
                  being retrieved through OpiGetData or OpiGetViewData. (If no UDM output format is
                  designated, the ADM output format is used.)


                  IDI_TRUE         -    The data will be formatted.

                  IDI_FALSE        -    The data will not be formatted.

                  This format option attribute defaults to IDI_TRUE after the execution of
                  OpiMakeConnection.

                  OPI_ATT_IGNORE_INTERRUPTS                                                      IDI_FLAG

                  Specifies whether you want your application to ignore all events, messages and interrupts
                  in the communications code when waiting on a response to be returned from OPIRPC.


                  IDI_TRUE         -   Ignore all events, messages, and interrupts while waiting on a
                                       response from OPIRPC.

                  IDI_FALSE        -   Do not ignore events, messages, and interrupts while waiting on a
                                       response from OPIRPC.

                  The ignore interrupts attribute defaults to IDI_FALSE after the execution of
                  OpiMakeConnection.



320  Reference
OPI_ATT_MESSAGE_EOL_TYPE                                                    IDI_USHORT

Specifies the end-of-line terminator character(s) used in vocabulary file messages which
contain $B and $Sn formatting instructions. Possible values are:


This value                                 Means the end-of-line terminator is

OPI_FILE_EOL_TYPE_CR                       a carriage return.

OPI_FILE_EOL_TYPE_CRLF                     a carriage return followed by a line feed.

OPI_FILE_EOL_TYPE_LF                       a line feed.

OPI_FILE_EOL_TYPE_UNDEFINED                undefined—that is, line breaks are not marked.

The default is OPI_FILE_EOL_TYPE_UNDEFINED.

OPI_ATT_PRESENTER_NAME                                                            IDI_PSZ

Specifies the presenter being used for the data returned from OpiGetData and
OpiGetTextData calls. The length of the presenter name can range from 1 to
OPI_MAX_PRES_NAME_LC.




                                                                          Reference  321
                  OpiGetConverterInfo
Description

                  This routine returns information about the specified converter in the style guide.

Syntax

                  IDI_USHORT OpiGetConverterInfo (ConID, pszConvName, usConvNum, pConvInfo)

Parameters

                  ConID                                                                    OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszConvName                                                                  IDI_PSZ/Read

                  Specifies the name of the converter you want information about. The length of the name
                  can range from 1 to OPI_MAX_CONV_NAME_LC. If you use the usConvNum
                  parameter to specify the converter (that is, you set it to a number other than zero), then
                  specify a pointer to a null string for pszConvName.

                  usConvNum                                                              IDI_USHORT/Read

                  Specifies the number of the converter you want information about. If you use the
                  pszConvName parameter to specify the converter (that is, you set it to a value other than a
                  pointer to a null string), then specify zero for usConvNum; otherwise the pszConvName
                  parameter will be ignored.

                  pConvInfo                                                        OPI_PCONVINFO/Write

                  Points to an OPI_CONVINFO data structure where information about the specified
                  converter is returned.

Comments




322  Reference
              OpiGetData
Description

              This routine accesses the data in short text or numeric fields from specified records in a
              result set or database and writes this data into a databuff object; it does not write data
              from text stream fields.

Syntax

              IDI_USHORT OpiGetData (ConID, FieldListID, lSetNum, ulStartMemNum,
                     pszKeyValueSpec, usSecNum, usLimit, fWait, usIntent, DataBuffID, pusCount)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              FieldListID                                                       OPI_FIELDLISTID/Read

              Specifies the ID of a field list created by the OpiMakeFieldList routine. This field list
              should contain the names of the fields whose data you want to access. This routine
              accesses short text or numeric fields only. See “Comments” below for information about
              how this routine handles other types of fields that may occur in the field list.

              Note: Do not specify a field list which has also been used on a call to
              OpiStartGetTextData without first calling OpiFinishGetTextData; otherwise OpiGetData
              will return the failure status code 2 and error messages.

              lSetNum                                                                   IDI_LONG/Read

              Indicates the number of the result set that contains the records you want to display.
              Possible values are:
              Value                 Meaning

              n                     result set number n

              0                     current result set

              -n                    nth set before the current result set

              where n is any integer.


                                                                                         Reference  323
                  If you use the pszKeyValueSpec parameter to identify a record to return to the databuff
                  object, then this parameter is ignored.

                  ulStartMemNum                                                               IDI_ULONG/Read

                  Specifies the first member in the result set to return in a databuff object. The system will
                  return this member and any members that follow it up to a maximum number you set
                  using the usLimit parameter. For instance, if you specify 3 for ulStartMemNum and 7 for
                  usLimit, then the system will return members 3, 4, 5, 6, 7, 8, 9 in the databuff object.

                  Zero is not a valid value. If you specify zero, this routine will produce a failure return
                  code of OPI_ERROR. If you specify a number greater than the number of last record in
                  the set, the system does not return an error. In this case, the pusCount parameter will
                  equal zero. (This design enables you signal when to stop calling OpiGetData in your
                  application.)

                  If you use the pszKeyValueSpec parameter to identify a record to return to the databuff
                  object, then this parameter is ignored.

                  pszKeyValueSpec                                                                 IDI_PSZ/Read

                  Specifies a criterion string that identifies the record in the database to return in the
                  databuff object for display. The syntax is:

                  [key_field_name = value]

                  where key_field_name is the unique primary key field of the desired record and value is
                  the contents of this unique field. For example:

                  [ENO = 1823]

                  The length of the string is from 1 to OPI_MAX_KEYVALSPEC_LC.

                  If you use the lSetNum and ulStartMemNum parameters to identify the record to copy to
                  the databuff, then specify a pointer to a null string for this parameter, otherwise the
                  lSetNum and ulStartMemNum parameters will be ignored.

                  Note:    This parameter can be used only when the fieldlist contains fields from a single
                  view.




324  Reference
usSecNum                                                                IDI_USHORT/Read

Specifies the number of the section (also called toc sequence number) containing the data
to be displayed. The system returns the data in the specified section from each member.
If the given section does not exist for a member, then the fSecInMember field in the
OPI_MEMBERATTRS data structure is set to IDI_FALSE and, for each non-existing
section field, the system returns OPI_TIOID_TEXT_CONTENT for the TIO identifier
and a null string for its value in the OPI_TIODATA data structure. If the specified
fieldlist does not contain section-level fields, then this parameter is ignored.

Note:     Sectioned records are not supported on Windows operating systems.

usLimit                                                                 IDI_USHORT/Read

Specifies the maximum number of members in the result set to return in the databuff
object. These members include the first member you specified for the ulStartMemNum
parameter and any members that follow it up to the specified maximum number. For
instance, if you specify 3 for ulStartMemNum and 7 for us Limit, then the system will
return members 3, 4, 5, 6, 7, 8, 9 in the databuff object.

Zero is not a valid value. If you specify zero, this routine will produce a failure return
code of OPI_ERROR. If you specify a number greater than the number of available
records, the system does not return an error. In this case, the system will just return as
many records as it can.

If you use the pszKeyValueSpec parameter to identify the record to display, then the
usLimit parameter is ignored.

fWait                                                                       IDI_FLAG/Read

Specifies whether you want your application to wait for system resources if they are not
available when you execute this routine. The possible values are:


IDI_TRUE        -   Wait for resources if they are not available.

IDI_FALSE       -   Do not wait for resources if not available.

If you specify IDI_FALSE and resources are not available, this routine produces the
failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.




                                                                            Reference  325
                  usIntent                                                                IDI_USHORT/Read

                  Specifies whether you want to access the desired records in the data area or the queue
                  area of the database. It also affects which locks are set when this routine is called within a
                  transaction.

                  Note: On Windows operating systems, BASIS does not store records in the queue area.
                  The queue contains only Queue Status Records; all data records are stored only in the
                  database.

                  Possible values are:


                  OPI_INTENT_READ                -   The system attempts to access records in the data area
                                                     of the database only. This intent value allows you to
                                                     read only; the records may not be updated.

                  OPI_INTENT_QREAD               -   The system attempts to access the records in the queue
                                                     area; if the records are not there, then it attempts to
                                                     access them in the database. This intent value allows
                                                     you to read only; the records may not be updated.

                  OPI_INTENT_CURRENT             -   The system attempts to access the records in the queue
                                                     area; if the records are not there, then it attempts to
                                                     access them in the database. If this routine is called
                                                     from inside a transaction, then you may read or update
                                                     the records. If this routine is not within a truncation,
                                                     then you may only read.

                  DataBuffID                                                       OPI_DATABUFFID/Read

                  Specifies the ID of a databuff object created by the OpiMakeDataBuff routine. This
                  databuff object will hold the records returned by this routine.

                  pusCount                                                              IDI_PUSHORT/Write

                  Points to the number of records returned in the databuff object. If this number is zero and
                  OpiGetData produces a return code of OPI_OK, then there are no more records to get.




326  Reference
Comments

           Some formatting takes place when the data from each field is put into the databuff object.
           The value specified for OUTPUT_FORMAT in the definition database is used to convert
           numeric data to character data except for the justification setting. All field data is
           ALWAYS left justified when put into the databuff object.

           If a field cannot be converted to character, then the system returns
           OPI_TIOID_TEXT_CONTENT as the TIO identifier with asterisks as the TIO value in
           the databuff object.

           If the number of members requested does not fit in given databuff object, the system
           breaks the data on a member boundary.

           If a text stream field is present in the field list, the system returns
           OPI_TIOID_TEXT_CONTENT for the TIO identifier, a null string for the TIO value,
           and zero for the TIO length in the databuff object.

           If a field does not appear in a record, the system returns OPI_TIOID_TEXT_CONTENT
           for the TIO identifier, a null string for the TIO value, and zero for the TIO length in the
           databuff object.

           Sometimes when OpiGetData produces a return code of OPI_ERROR, it’s possible that
           the databuff object contains valid data despite the failure of the call. This situation is
           indicated when the returned value of pusCount is greater than zero and the
           OpiGetDetailedStatus routine returns one of the following status codes in the pulStatus
           parameter:




                                                                                      Reference  327
                  OPI_STAT_MEMBER_DELETED           -   means the member has been deleted since the
                                                        result set was created; the member’s position in
                                                        the result set can be found by adding the value
                                                        pointed to by pusCount+1+ulStartMemNum

                  OPI_STAT_NOWAIT                   -   means the member is locked by another user;
                                                        the member’s position in the result set can be
                                                        found by adding the value pointed to by
                                                        pusCount+1+ulStartMemNum

                  OPI_STAT_INVALID_RECORD           -   usually means some of the fields in the databuff
                                                        object could not be converted from a number to
                                                        a character string

                  If you get the status code OPI_STAT_MEMBER_DELETED or OPI_STAT_NOWAIT,
                  you can continue processing by incrementing your ulStartMemNumber parameter by
                  pusCount+1 to skip the member that caused the error.




328  Reference
              OpiGetDetailedStatus
Description

              This routine returns the status code and verb code for the most recent OpenAPI routine
              called.

Syntax

              IDI_USHORT OpiGetDetailedStatus (ConID, pulStatus, pulVerbCode)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pulStatus                                                              IDI_PULONG/Write

              Specifies the status code for the most recent OpenAPI routine called. The status code
              describes the reason for the failure of the routine. By using this code, you can determine
              if it is necessary to use the OpiGetStatusInfo routine to display the information to the user
              or continue processing as in the case where the most recent call failed due to an
              OpiCancel call.

              pulVerbCode                                                            IDI_PULONG/Write

              Specifies the verb code for the most recent OpenAPI routine called. The verb code is an
              integer which identifies a routine call. You can use this code in generic error handling
              modules. See the OPI_VC section of the header file for the possible verb codes. For
              more information about error handling, see “General Setup.”

Comments

              Whenever a routine call produces a return code of OPI_WARNING or OPI_ERROR, the
              previous status code is overwritten.

              Every time you call a routine the verb code is overwritten, no matter what return code the
              call produces (OPI_OK, OPI_WARNING, or OPI_ERROR).




                                                                                          Reference  329
                  OpiGetDisplayTIO
Description

                  This routine gets a text image object (TIO) from the text stream field in a field object and
                  writes it in an OPI_TIODATA data structure. For information about TIOs, see
                  “Accessing Record Data for Display.”

Syntax

                  IDI_USHORT OpiGetDisplayTIO (ConID, FieldID, usTIOToGet, pTIOData)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FieldID                                                                 OPI_FIELDID/Read

                  Specifies the ID of the field object containing the data from the text stream field.

                  usTIOToGet                                                              IDI_USHORT/Read

                  Specifies the TIO to return in relation to the last TIO returned from the preceding call to
                  OpiGetDisplayTIO. It can have the following values:


                  Value                       Meaning

                  OPI_TIO_FIRST               Get the first TIO in the field object

                  OPI_TIO_CURRENT             Get the same TIO returned by the preceding call to
                                              OpiGetDisplayTIO

                  OPI_TIO_NEXT                Get the TIO following the TIO returned by the preceding call
                                              to OpiGetDisplayTIO




330  Reference
           pTIOData                                                            OPI_PTIODATA/Write

           Points to an OPI_TIODATA data structure where the TIO from the field object is
           returned. This data structure’s fields hold each part of the TIO: identifier, length, and
           value.

Comments

           When there are no more TIOs to get, the OpiGetDisplayTIO routine will return the failure
           status code 2. The value OPI_STAT_NO_MORE_TIOS is written to the pulStatus
           parameter of the OpiGetDetailedStatus routine.

           Before you call this routine, the pvTIOValue field of the OPI_TIODATA data structure
           must point to a buffer large enough to hold the largest possible TIO value. TIO values
           can range in size from zero to OPI_MAX_TIO_LC characters in length. If the value
           returned is too big to fit into the pvTIOValue field, then this routine produces the failure
           return code OPI_ERROR.

           Note: For Visual Basic users, you must call the VBOpiSliMmAlloc routine to create
           the buffer to which the pvTIOValue field will point. For more information, see “Calling
           OpenAPI from Visual Basic.”




                                                                                       Reference  331
                  OpiGetField
Description

                  This routine transfers a field in the record from a member object to a field object.

Syntax

                  IDI_USHORT OpiGetField (ConID, MemberID, FieldID, usFieldListNum)

Parameters

                  ConID                                                                      OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  MemberID                                                                OPI_MEMBER/Read

                  Specifies the ID of the member object containing the record whose fields you want to
                  access.

                  FieldID                                                                  OPI_FIELDID/Read

                  Specifies the ID of a field object where the specified field from the member object is
                  returned.

                  usFieldListNumber                                                         IDI_USHORT/Read

                  Specifies the fieldlist position number of the field you want to access. The position
                  numbers in a fieldlist start at zero.

Comments

                  If a field in the fieldlist doesn’t exist in the specified record, then a TIO with the ID equal
                  to OPI_TIOID_TEXT_CONTENT and the length equal to zero will be returned in the
                  field object.




332  Reference
              OpiGetFieldInfoByName
Description

              This routine writes information about a specified field into the OPI_FIELDINFO data
              structure.

Syntax

              IDI_USHORT OpiGetFieldInfoByName (ConID, pszFieldId, usWordListLC,
                     usCommentLC, usCodeListLC, pFieldInfo);

Parameters

              ConID                                                                OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszFieldId                                                               IDI_PSZ/Read

              Specifies the field you want information about. The syntax is:
                  <database.model>view.field

              For example a typical string would look similar to the following:
                  <TOUR.ALL>PLACE.LOCATION

              You must specify a database and model that have already been opened by the OpiOpenDb
              routine. The length of the name can range from 1 to OPI_MAX_FIELD_ID_LC.




                                                                                     Reference  333
                  usWordListLC                                                            IDI_USHORT/Read

                  Specifies the length, in characters, of the buffer pointed to by the pszWordList field in the
                  OPI_FIELDINFO data structure. This buffer will contain the word list associated with
                  the specified field. Each word in the word list is separated by a null delimiter (\0), and
                  the end of the list is indicated by a double null.

                  If you do not make the buffer big enough, the system will truncate the list by breaking
                  between words (not in the middle of a word). If the list is truncated, the flag
                  fWordListTruncated (in the OPI_FIELDINFO data structure) will be set to IDI_TRUE.
                  If the list is not truncated, this flag will be set to IDI_FALSE.

                  If you do not want the system to return the associated word list, specify zero for this
                  parameter. This promotes better system performance.

                  usCommentLC                                                             IDI_USHORT/Read

                  Specifies the length, in characters, of the buffer pointed to by the pszComment field in the
                  OPI_FIELDINFO data structure. This buffer will contain the comment associated with
                  the specified field. The comment string is null-terminated.

                  If you do not make the buffer big enough, the system will truncate the comment. If the
                  comment is truncated, the flag fCommentTruncated (in the OPI_FIELDINFO data
                  structure) will be set to IDI_TRUE. If the comment is not truncated, this flag will be set
                  to IDI_FALSE.

                  If you do not want the system to return the associated comment, specify zero for this
                  parameter. This promotes better system performance.

                  usCodeListLC                                                            IDI_USHORT/Read

                  Specifies the length, in characters, of the buffer pointed to by the pszCodeList field in the
                  OPI_FIELDINFO data structure. This buffer will contain the code list associated with the
                  specified field. Each code in the code list is separated by a null delimiter (\0), and the end
                  of the list is indicated by a double null.

                  If you do not make the buffer big enough, the system will truncate the list by breaking
                  between codes (not in the middle of a code). If the list is truncated, the flag
                  fCodeListTruncated (in the OPI_FIELDINFO data structure) will be set to IDI_TRUE. If
                  the list is not truncated, this flag will be set to IDI_FALSE.

                  If you do not want the system to return the associated code list, specify zero for this
                  parameter. This promotes better system performance.




334  Reference
           pFieldInfo                                                       OPI_PFIELDINFO/Mod

           Points to an OPI_FIELDINFO data structure where information about the specified field
           is returned.

Comments

           Before you call this routine, the following fields in the OPI_FIELDINFO data structure
           must point to buffers: pszWordList, pszComment, and pszCodeList. The size of these
           buffers must be at least as big as the lengths specified in the parameters usWordListLC,
           usCommentLC, and usCodeListLC, respectively.

           Note for Visual Basic Users:        You must call the VBOpiSliMmAlloc routine to
           create the buffers to which the pszWordList, pszComment, and pszCodeList fields will
           point. For more information, see “Calling OpenAPI from Visual Basic.”




                                                                                     Reference  335
                  OpiGetFieldInfoByPosition
Description

                  This routine writes information about a specified field into the OPI_FIELDINFO data
                  structure.

Syntax

                  IDI_USHORT OpiGetFieldInfoByPosition (ConID, pszViewId, usFieldToGet,
                         usWordListLC, usCommentLC, usCodeListLC, pFieldInfo);

Parameters

                  ConID                                                                  OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszViewId                                                                  IDI_PSZ/Read

                  Specifies the view that contains the field(s) you want to get information about. The
                  syntax is:
                      <database.model>view

                  For example a typical string would look similar to the following:
                      <TOUR.ALL>PLACE

                  You must specify a database and model that have already been opened by the OpiOpenDb
                  routine. The length of the name can range from 1 to OPI_MAX_VIEW_ID_LC.

                  usFieldToGet                                                          IDI_USHORT/Read

                  Specifies the field you want information about. The possible values are:




336  Reference
Value                      Meaning

OPI_FIELD_FIRST            The first field in the view according to display sequence order.

OPI_FIELD_NEXT             The field after the one specified in the previous call to this
                           routine according to display sequence order.

usWordListLC                                                             IDI_USHORT/Read

Specifies the length, in characters, of the buffer pointed to by the pszWordList field in the
OPI_FIELDINFO data structure. This buffer will contain the word list associated with
the specified field. Each word in the word list is separated by a null delimiter (\0), and
the end of the list is indicated by a double null.

If you do not make the buffer big enough, the system will truncate the list by breaking
between words (not in the middle of a word). If the list is truncated, the flag
fWordListTruncated (in the OPI_FIELDINFO data structure) will be set to IDI_TRUE.
If the list is not truncated, this flag will be set to IDI_FALSE.

If you do not want the system to return the associated word list, specify zero for this
parameter. This promotes better system performance.

usCommentLC                                                              IDI_USHORT/Read

Specifies the length, in characters, of the buffer pointed to by the pszComment field in the
OPI_FIELDINFO data structure. This buffer will contain the comment associated with
the specified field. The comment string is null-terminated.

If you do not make the buffer big enough, the system will truncate the comment. If the
comment is truncated, the flag fCommentTruncated (in the OPI_FIELDINFO data
structure) will be set to IDI_TRUE. If the comment is not truncated, this flag will be set
to IDI_FALSE.

If you do not want the system to return the associated comment, specify zero for this
parameter. This promotes better system performance.




                                                                             Reference  337
                  usCodeListLC                                                            IDI_USHORT/Read

                  Specifies the length, in characters, of the buffer pointed to by the pszCodeList field in the
                  OPI_FIELDINFO data structure. This buffer will contain the code list associated with the
                  specified field. Each code in the code list is separated by a null delimiter (\0), and the end
                  of the list is indicated by a double null.

                  If you do not make the buffer big enough, the system will truncate the list by breaking
                  between codes (not in the middle of a code). If the list is truncated, the flag
                  fCodeListTruncated (in the OPI_FIELDINFO data structure) will be set to IDI_TRUE. If
                  the list is not truncated, this flag will be set to IDI_FALSE.

                  If you do not want the system to return the associated code list, specify zero for this
                  parameter. This promotes better system performance.

                  pFieldInfo                                                         OPI_PFIELDINFO/Mod

                  Points to an OPI_FIELDINFO data structure where information about the specified field
                  is returned.

Comments

                  Before you call this routine, the following fields in the OPI_FIELDINFO data structure
                  must point to buffers: pszWordList, pszComment, and pszCodeList. The size of these
                  buffers must be at least as big as the lengths specified in the parameters usWordListLC,
                  usCommentLC, and usCodeListLC, respectively.

                  This routine is the most efficient mechanism to get information for all fields in a view and
                  should always be used, rather than OpiGetFieldInfoByName, when all fields of a view are
                  to be processed. The first call to this routine should set usFieldToGet to
                  OPI_FIELD_FIRST, and then subsequent calls (in a loop) should set usFieldToGet to
                  OPI_FIELD_NEXT. When there are no more fields to process, the value
                  OPI_STAT_END_OF_INFO is written to the pulStatus parameter of the
                  OpiGetDetailedStatus routine.

                  Note for Visual Basic Users:        You must call the VBOpiSliMmAlloc routine to
                  create the buffers to which the pszWordList, pszComment, and pszCodeList fields will
                  point. For more information, see “Calling OpenAPI from Visual Basic.”




338  Reference
              OpiGetFieldListByName
Description

              This routine returns the names of fields associated with a given field list.

Syntax

              IDI_USHORT OpiGetFieldListByName (ConID, pszFieldListID, fQualifiedFieldIDs,
                     pusNumberOfFields, pusReturnedNumberOfFields, usFieldListBufferLC,
                     pszFieldListBuffer)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszFieldListID                                                                  IDI_PSZ/Read

              The identifier for the field list you wish to obtain. The format is:

                       <database.model>view.field_list

              For example, a typical string would look similar to the following:

                       <TOUR.ALL>CLIENT.COMPANY

              You must specify a database and model that have already been opened by the OpiOpenDb
              routine. The length of the name can range from 1 to OPI_MAX_FIELD_ID_LC
              characters.




                                                                                             Reference  339
                  fQualifiedFieldsIDs                                                          IDI_FLAG/Read

                  Specifies whether or not fields names placed in the field list buffer will be fully qualified.
                  The possible values are:

                  Value                      Meaning

                  IDI_TRUE                   Fields placed in the field list buffer are to be fully qualified
                                             UDM field identifiers. The format for fields in the field list
                                             buffer will be:

                                                       <database.model>view.field

                  IDI_FALSE                  Fields placed in the field list buffer are not to be fully qualied.
                                             The format for fields in the field list buffer will be:

                                                       field

                  pusNumberOfFields                                                      IDI_PUSHORT/Write

                  The number of fields in the field list.

                  pusReturnedNumberOfFields                                              IDI_PUSHORT/Write

                  The number of fields that were returned by the call to OpiGetFieldListByName (the
                  number of fields in the buffer pointed to by pszFieldListBuffer).

                  usFieldListBufferLC                                                      IDI_USHORT/Read

                  Specifies the length, in bytes, of the buffer pointed to by the pszFieldListBuffer
                  parameter. Be sure to make the buffer big enough to hold all of the field names in the
                  field list. The maximum required size of this buffer is OPI_MAX_FIELD_LIST_LC. If
                  the buffer is not big enough, the system will returns as many complete field names as
                  possible.

                  Note: You can tell whether the buffer is too small to hold all the field names by checking
                  the numbers returned in the pusReturnedNumberOfFields and pusNumberOfFields fields.
                  If the former is less than the latter, then you need to increase the size of the buffer.

                  pszFieldListBuffer                                                             IDI_PSZ/Write

                  Points to a buffer where a string of all the names of the fields included in the given field
                  list is returned. Each field name is separated by a null delimiter (zero byte).

                  Note: You must allocate a buffer of length equal to or greater than the length specified
                  by the usFieldListBufferLC parameter prior to calling this routine. Visual Basic users can
                  dimension a string instead.


340  Reference
              OpiGetFieldListByPosition
Description

              This routine returns the names of fields associated with a given field list.

Syntax

              IDI_USHORT OpiGetFieldListByPosition (ConID, pszViewID, usFieldListToGet,
                     pszFieldListID, fQualifiedFieldIDs, pusNumberOfFields,
                     pusReturnedNumberOfFields, usFieldListBufferLC, pszFieldListBuffer)

Parameters

              ConID                                                                     OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.
              pszViewID                                                                       IDI_PSZ/Read

              Specifies the view that contains the field list(s) that you wish to obtain. The format is:

                       <database.model>view

              For example, a typical string would look similar to the following:

                       <TOUR.ALL>CLIENT

              You must specify a database and model that have already been opened by the OpiOpenDb

              routine. The length of the name can range from 1 to OPI_MAX_VIEW_ID_LC

              characters.


              usFieldListToGet                                                        IDI_USHORT/Read

              Specifies the field list you want to obtain. The possible values are:

              Value                             Meaning

              OPI_FIELD_LIST_FIRST              The first field list in the view.




                                                                                             Reference  341
                  Value                              Meaning

                  OPI_FIELD_LIST_NEXT                The field list after the one specified in the previous call
                                                     to this routine.

                  pszFieldListID                                                                 IDI_PSZ/Write

                  The identifier for the field list obtained. The format is:

                           <database.model>view.field_list

                  For example, a typical string would look similar to the following:

                           <TOUR.ALL>CLIENT.COMPANY

                  Note: You must create a buffer of length OPI_MAX_FIELD_ID_LC for this parameter
                  prior to calling this routine. Visual Basic users can dimension a string instead.

                  fQualifiedFieldsIDs                                                           IDI_FLAG/Read

                  Specifies whether or not fields names placed in the field list buffer will be fully qualified.
                  The possible values are:



                  Value                      Meaning

                  IDI_TRUE                   Fields placed in the field list buffer are to be fully qualified
                                             UDM field identifiers. The format for fields in the field list
                                             buffer will be:

                                                       <database.model>view.field

                  IDI_FALSE                  Fields placed in the field list buffer are not to be fully qualified.
                                             The format for fields in the field list buffer will be:

                                                       field

                  pusNumberOfFields                                                       IDI_PUSHORT/Write

                  The number of fields in the field list.

                  pusReturnedNumberOfFields                                               IDI_PUSHORT/Write

                  The number of fields that were returned by the call to OpiGetFieldListByPosition (the
                  number of fields in the buffer pointed to by pszFieldListBuffer).



342  Reference
           usFieldListBufferLC                                                      IDI_USHORT/Read

           Specifies the length, in bytes, of the buffer pointed to by the pszFieldListBuffer
           parameter. Be sure to make the buffer big enough to hold all of the field names in the
           field list. The maximum required size of this buffer is OPI_MAX_FIELD_LIST_LC. If
           the buffer is not big enough, the system will returns as many complete field names as
           possible.

           Note: You can tell whether the buffer is too small to hold all the field names by checking
           the numbers returned in the pusReturnedNumberOfFields and pusNumberOfFields fields.
           If the former is less than the latter, then you need to increase the size of the buffer.

           pszFieldListBuffer                                                            IDI_PSZ/Write

           Points to a buffer where a string of all the names of the fields included in the given field
           list is returned. Each field name is separated by a null delimiter (zero byte).

           Note: You must allocate a buffer of length equal to or greater than the length specified
           by the usFieldListBufferLC parameter prior to calling this routine. Visual Basic users can
           dimension a string instead.

Comments

           The first call to OpiGetFieldListByPosition should always be made with
           usFieldListToGet set to OPI_FIELD_LIST_FIRST. Subsequent calls should be made
           with OPI_FIELD_LIST_NEXT. When there are no more field lists to be obtained, the
           value of OPI_STAT_END_OF_INFO is written to the pulStatus parameter of the
           OpiGetDetailedStatus routine.




                                                                                        Reference  343
                  OpiGetFileAttr
Description

                  This routine gets an attribute of a particular file object.

Syntax

                  IDI_USHORT OpiGetFileAttr (ConID, FileID, usAttribute, pvValue)

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  FileID                                                                  OPI_FILEID/Read

                  Specifies the ID of the file object whose attribute you want to get.

                  usAttribute                                                            IDI_USHORT/Read

                  Specifies the attribute you want to get. See “Comments” below for the names of the
                  possible attributes.

                  pvValue                                                                 IDI_PVOID/Write

                  Points to the location to which to return the attribute specified in the usAttribute
                  parameter. If you specify a variable which is set to the desired value for this parameter,
                  you must make sure that variable has the same type as that of the specified attribute. See
                  “Comments” below for a list of the attributes.




344  Reference
Comments

           The following list shows the attributes for a file object and their corresponding values.
           For each of the attributes, the user must specify a pointer to a variable whose data type
           matches the attribute’s data type.

           OPI_ATT_FILE_OPTIONS                                                                  IDI_PSZ

           Specifies the system-specific options to be used when creating a file. The value returned
           is dependent on the system you’re using. For VMS, one or more of the strings listed in
           the table below will be returned:


           This string              Specifies this option

           /RFM=FIX                 a fixed record format

           /RFM=VAR                 a variable record format

           /MRS=integer             the maximum record size in bytes

           where integer is a number between 1 and OPI_MAX_RECORD_LC. The strings are
           concatenated when specifying more than one option, as shown:
               "/RFM=FIX/MRS=132"

           For VMS, the defaults are /RFM=VAR/MRS=80.

           OPI_ATT_FILE_NAME_OR_AREA                                                             IDI_PSZ

           Specifies the name of the file that the file object described. This attribute’s length is from
           1 to OPI_MAX_FILE_NAME_LC.

           OPI_ATT_FILE_TYPE                                                               IDI_USHORT

           Specifies on what type of device the file object resides. Possible values are:
           OPI_FILE_REMOTE            -   File object refers to a file residing on a device that is not
                                          directly accessible by the client application but is accessible
                                          by the BASIS server.

           OPI_FILE_SHARED            -   File object refers to a file residing on a device that is
                                          accessible by the client application and the BASIS server.

           OPI_FILE_LOCAL             -   File object refers to a file residing on a device that is



                                                                                         Reference  345
                                                 accessible by the client application but not by the BASIS
                                                 server.

                  OPI_FILE_OTHER             -   Provided for compatibility with older OpenAPI
                                                 applications.

                  OPI_ATT_FILE_EOL_TYPE                                                           IDI_USHORT

                  Specifies the end-of-line terminator character(s) of the file that the file object describes.
                  Possible values are:


                  This value                              Means the end-of-line terminator is

                  OPI_FILE_EOL_TYPE_CR                    a carriage return.

                  OPI_FILE_EOL_TYPE_CRLF                  a carriage return followed by a line feed.

                  OPI_FILE_EOL_TYPE_LF                    a line feed.


Example

                  The following code segment uses the OpiGetFileAttr to retrieve a file name:
   IDI_PSZ pszFileName;
   usRC = OpiGetFileAttr(ConID, DestID, OPI_ATT_FILE_NAME_OR_AREA, pszFileName);
   if (usRC >= 2) goto error;
   printf(szMsgBuff, "Source file data copied to %s",pszFileName);




346  Reference
              OpiGetForeignKeys
Description

              This routine gets a list of foreign key relationships for all the records in a database.

Syntax

              IDI_USHORT OpiGetForeignKeys (ConID, usAction, pszModelSpec, pszKeyBuffer,
                     pusKeyBufferLC)

Parameters

              ConID                                                                       OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              pszModelSpec                                                                    IDI_PSZ/Read

              Specifies the model for which you want to obtain the foreign key relationships. The
              syntax is:
                  <database.model>

              The length of the name can range from 1 to OPI_MAX_MODEL_SPEC_LC.

              pszKeyBuffer                                                                    IDI_PSZ/Write

              Specifies the character buffer to be used to return the list of foreign keys. Each foreign
              key relationship in the buffer is separated by a null delimiter (\0), and the end of the list is
              indicated by a double null. The format of each foreign key relationship is:
                  OWNER_REC.FIELD=MEMBER_REC.FIELD

              pusKeyBufferLC                                                           IDI_PUSHORT/Mod

              Specifies the size, in characters, of the buffer pointed to by the pszKeyBuffer parameter.
              On input, this parameter specifies the size of the pszKeyBuffer buffer. On output, the
              variable is updated to reflect the actual buffer size required to return all of the foreign key
              relationships.




                                                                                            Reference  347
Comments

                  If the combined length of all the keys in the list (including the double null terminator) is
                  greater than the size of the provided pszKeyBuffer, an error does not occur; the routine
                  returns a truncated list of the available keys. Applications should test for this condition
                  by checking the value returned in pusKeyBufferLC.

                  Even though you must specify a particular model in pszModelSpec when calling this
                  routine, OpiGetForeignKeys will return foreign key relationships for all the records in the
                  database specified.

                  The database must have been opened with OpiOpenDb prior to calling this routine.

                  A foreign key relationship in a BASIS database is defined by the ADM ASSERT
                  statement. For more information, see Database Definition and Development.




348  Reference
              OpiGetLookTerm
Description

              This routine transfers an index term from a databuff object to look term object.

Syntax

              IDI_USHORT OpiGetLookTerm (ConID, DataBuffID, LookTermID, usLookTermNum)

Parameters

              ConID                                                                   OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DataBuffID                                                      OPI_DATABUFFID/Read

              Specifies the ID of the databuff object containing the index terms returned by the
              OpiLook routine.

              LookTermID                                                     OPI_LOOKTERMID/Read

              Specifies the ID of a look term object created by the OpiMakeLookTerm routine. This
              look term object will hold the index term entry from the databuff object.

              usLookTermNum                                                         IDI_USHORT/Read

              Specifies the number of the index term entry to get from the databuff object and return in
              the look term object. Items in a databuff object are numbered starting with zero.

Comments

              None.




                                                                                        Reference  349
                  OpiGetLookTermAttrs
Description

                  This routine transfers index term information from a look term object to an
                  OPI_LOOKTERMATTRS data structure.

Syntax

                  IDI_USHORT OpiGetLookTermAttrs (ConID, LookTermID, pLookTermAttr)

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  LookTermID                                                     OPI_LOOKTERMID/Read

                  Specifies the ID of the look term object containing the index term entry.

                  pLookTermAttrs                                          OPI_PLOOKTERMATTRS/Write

                  Points to an OPI_LOOKTERMATTRS data structure where the index term information
                  from the look term object is returned. This information includes: the index term, number
                  of records containing the term, and number of references that occur in these records. For
                  more information, see “Data Structures.”

Comments

                  None.




350  Reference
              OpiGetMember
Description

              GThis routine transfers a record from a databuff object to a member object.

Syntax

              IDI_USHORT OpiGetMember (ConID, DataBuffID, MemberID, usMemberNum)

Parameters

              ConID                                                                   OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              DataBuffID                                                      OPI_DATABUFFID/Read

              Specifies the ID of the databuff object containing the members that you want to access.

              MemberID                                                          OPI_MEMBERID/Read

              Specifies the ID of a member object where the record from the databuff object is returned.

              usMemberNum                                                           IDI_USHORT/Read

              Specifies the number of the record in the databuff object to return in the member object.
              Items in a databuff object are numbered starting at zero.

Comments

              None.




                                                                                        Reference  351
                  OpiGetMemberAttrs
Description

                  This routine gets the attributes for a record in a member object and writes them in an
                  OPI_MEMBERATTRS data structure.

Syntax

                  IDI_USHORT OpiGetMemberAttrs (ConID, MemberID, pMemberAttrs)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  MemberID                                                            OPI_MEMBERID/Read

                  Specifies the ID of the member object containing the record whose attributes you want to
                  obtain.

                  pMemberAttrs                                                 OPI_PMEMBERATTRS/Write

                  Points to a OPI_MEMBERATTRS structure where the attributes for the record in the
                  specified member object are returned. These attributes include: the record’s member
                  number in the result set, the number of the subfield that caused the record to be sorted in
                  its present position in the result set, the record’s weight, and an indication of whether the
                  record contained the section specified for the usSecNum parameter of the OpiGetData
                  routine.

                  Note:    Sectioned records are not supported on Windows operating systems.

Comments

                  None.




352  Reference
              OpiGetMessageText
Description

              This routine gets a message, associated with a specified status code, from the vocabulary
              file.

Syntax

              IDI_USHORT OpiGetMessageText (ConID, ulStatus, pszLanguage, pszMessageText)

Parameters

              ConID                                                                    OPI_CONID/Read

              Specifies the ID of a connection object created by the OpiMakeConnection routine.

              ulStatus                                                                IDI_ULONG/Read

              Specifies the number of the message in the vocabulary to return. You can get this number
              from the pulStatus parameter of the OpiGetDetailedStatus routine.

              pszLanguage                                                                  IDI_PSZ/Read

              Reserved for future use. For now, specify a pointer to a null string for this parameter.

              pszMessageText                                                              IDI_PSZ/Write

              Points to a string where the message is returned. This string must be at least
              OPI_MAX_MESSAGE_LC+1 characters in length.

Comments

              None.




                                                                                         Reference  353
                  OpiGetModelInfo
Description

                  This routine writes information about a specified model into an OPI_MODELINFO data
                  structure and also writes a list of the model's views into a buffer. This function returns all
                  views present in the DDB regardless of whether the views have been applied.

Syntax

                  IDI_USHORT OpiGetModelInfo (ConID, pszModelSpec, pModelInfo,
                         usViewBufferLC, pszViewBuffer)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszModelSpec                                                                   IDI_PSZ/Read

                  Specifies the model you want information about. The syntax is:
                      <database.model>

                  The length of the name can range from 1 to OPI_MAX_MODEL_SPEC_LC. You must
                  specify a database and model that have already been opened by the OpiOpenDb routine.

                  pModelInfo                                                       OPI_PMODELINFO/Write

                  Points to an OPI_MODELINFO data structure where the information about the specified
                  model is returned.

                  usViewBufferLC                                                           IDI_USHORT/Read

                  Specifies the length, in bytes, of the buffer pointed to by the pszViewBuffer parameter.
                  Be sure to make this buffer big enough to hold all of the view names in the model. The
                  maximum required size of this buffer can be computed by multiplying the number of
                  views in the model (maximum number is OPI_MAX_VIEWS_IN_MODEL) by the
                  maximum possible size of a view name (OPI_MAX_VIEW_NAME_LC). If the buffer is
                  not big enough, the system will break between view names, not in the middle of a name.




354  Reference
           Note: You can tell whether the buffer was too small to hold all the view names by
           checking the numbers in the following OPI_MODELINFO data structure fields. If the
           numbers in these fields do not match, then you need to increase the size of the buffer.


           usReturnedNumberOfViews         -    number of view names in the buffer

           usNumberOfViews                 -    actual number of views in the specified model

           If you do not want any view names returned in this buffer, then specify zero for this
           parameter. This promotes better system performance.

           pszViewBuffer                                                                IDI_PSZ/Write

           Points to a buffer where a string of all the names of the views in the specified model is
           returned. Each view name is separated by a null delimiter (\0).

           Note: You must create a buffer for this parameter before calling this routine. Visual
           Basic users can dimension a string instead.

Comments

           This routine will return all views in the model, including those that have not yet been
           applied in the DDB. If a view that has not been applied is used in a call to
           OpiGetViewInfo, OPI_ERROR is returned with a detailed status of 864 (“View Name
           translation failed. The view is not defined”).




                                                                                       Reference  355
                  OpiGetPresenterInfo
Description

                  This routine returns information about the specified presenter in the style guide.

Syntax

                  IDI_USHORT OpiGetPresenterInfo (ConID, pszPresName, usPresNum, DataBuffID,
                         pPresInfo)

Parameters

                  ConID                                                                     OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszPresName                                                                    IDI_PSZ/Read

                  Specifies the name of the presenter you want information about. The length of the name
                  can range from 1 to OPI_MAX_PRES_NAME_LC. If you use the usPresNum parameter
                  to specify the presenter (that is, you set it to a number other than zero), then specify a
                  pointer to a null string for pszPresName.

                  usPresNum                                                                IDI_USHORT/Read

                  Specifies the number of the presenter you want information about. If you use the
                  pszPresName parameter to specify the presenter (that is, you set it to a value other than a
                  pointer to a null string), then specify zero for usPresNum; otherwise the system will
                  ignore the pszPresName parameter.

                  DataBuffID                                                        OPI_DATABUFFID/Read

                  Specifies the ID of a databuff object where the initial visual of the presenter is returned.
                  If you do not want an initial visual returned, then specify zero for this parameter. This
                  promotes better system performance.




356  Reference
           Note: To process the initial visual, call the OpiGetTextField routine followed by calls
           to the OpiGetDisplayTIO routine.

           pPresInfo                                                       OPI_PPRESINFO/Write

           Points to a OPI_PRESINFO data structure where information about the specified
           presenter is returned.

Comments

           For more information about presenters, see the Markup and Style Guide.




                                                                                    Reference  357
                  OpiGetRecordPointers
Description

                  This routine returns the record pointers for a range of members from a result set.

Syntax

                  IDI_USHORT OpiGetRecordPointers (ConID, lSetNum, ulStartMemNum,
                         ulEndMemNum, pulRecordPointerList);

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  lSetNum                                                                   IDI_LONG/Read

                  Specifies the number of the result set that contains the record for which you want a record
                  pointer. Possible values are:


                  Value                  Meaning

                  n                      result set number n

                  0                      current result set

                  -n                     nth set before the current result set

                  where n is any integer.

                  ulStartMemNum                                                           IDI_ULONG/Read

                  Specifies the start member for the range of members for which you want record pointers.

                  ulEndMemNum                                                             IDI_ULONG/Read

                  Specifies the end member for the range of members for which you want record pointers.

                  pulRecordPointerList                                                 OPI_PULONG/Write




358  Reference
           Points to an array of unsigned longs within which the record pointers for the result set
           members are returned. The maximum number of record pointers that can be returned
           during a single call to OpiGetRecordPointers is OPI_MAX_NR_RECORD_POINTERS.

Comments

           This routine retrieves the “record pointers” for a range of members from a result set.
           Record pointers uniquely identify BASIS records. For a record using a direct index
           structure, the record pointer is the physical location of the record. For a record using an
           indirect index structure, the record pointer is the value of the primary key of the record.
           This routine is intended for use only with records using an indirect index structure. For
           more information regarding index structure, see Database Definition and Development,
           “Index Structure. ” Value Result Sets and result sets formed from Joins or Composite
           Views are not supported by the OpiGetRecordPointers function. For more information
           regarding Value Result Sets, see The Complete FIND Handbook, “Using Tables to
           Compile Statistics.” For more information regarding Joins, see The Complete FIND
           Handbook, “Join Operators.” For more information regarding Composite Views, see
           Database Definition and Development, “Creating Composite Views.”




                                                                                       Reference  359
                  OpiGetSectionInfo
Description

                  This routine obtains information about the sections of a record that was returned in a
                  result set; it is intended to be used to implement hit-to-hit scrolling of sections.

                  Note:    Sectioned records are not applicable on Windows.

Syntax

                  IDI_USHORT OpiGetSectionInfo (ConID, pszViewId, lSetNum, ulMemNum,
                         pszKeyValueSpec, usLimit, fWait, pSectionInfo);

Parameters

                  ConID                                                                   OPI_CONID/Read

                  Specifies the ID of a connection object created by the OpiMakeConnection routine.

                  pszViewId                                                                   IDI_PSZ/Read

                  Specifies the view of the record that you want information about. The syntax format is:
                      <database.model>view

                  For example a typical string would look similar to the following:
                      <TOUR.ALL>PLACE

                  You must specify a database and model that have already been opened by the OpiOpenDb
                  routine. The length of the name can range from 1 to OPI_MAX_VIEW_ID_LC.




360  Reference
lSetNum                                                                    IDI_LONG/Read

Specifies the number of the result set that contains the record that you want information
about. Possible values are:


Value                 Meaning

n                     result set number n

0                     current result set

-n                    nth set before the current result set

where n is any integer.

If you use the pszKeyValueSpec parameter to identify the record, then this parameter is
ignored.

ulMemNum                                                                  IDI_ULONG/Read

Specifies the member number of the record that you want information about. If you use
the pszKeyValueSpec parameter to identify the record, then this parameter is ignored.

pszKeyValueSpec                                                               IDI_PSZ/Read

Specifies a criterion string that identifies the record, in the database, you want information
about. The syntax is:

[key_field_name = value]

where key_field_name is the unique primary key field of the desired record and value is
the contents of this unique field. For example:

[ENO = 1823]

Length is from 1 to OPI_MAX_KEYVALSPEC_LC.

If you use the lSetNum and ulMemNum parmeters to identify the record to return to the
databuff, then specify a pointer to a null for this parameter.

usLimit                                                                 IDI_USHORT/Read

Specifies the maximum number of section entries to return in the plHitSecNum field of
the OPI_SECTINFO data structure per execution of OpiGetSectionInfo.



                                                                            Reference  361
                  fWait                                                                     IDI_FLAG/Read

                  Specifies whether you want your application to wait for system resources if they are not
                  available when you execute this routine. The possible values are:


                  IDI_TRUE        -   Wait for resources if they are not available.

                  IDI_FALSE       -   Do not wait for resources if not available.

                  If you specify IDI_FALSE and resources are not available, this routine produces the
                  failure return code OPI_ERROR and the status code OPI_STAT_NOWAIT, which can
                  be accessed through the pulStatus parameter of the OpiGetDetailedStatus routine.

                  pSectionInfo                                                        OPI_PSECTINFO/Write

                  Points to an OPI_SECTINFO data structure where the information about the record's
                  sections is returned. This information includes: an array holding the numbers of sections
                  containing a hit, total number of entries in the array, total number of sections in the
                  record, and total number of sections containing hits. For more information, see “Data
                  Structures.”

Comments

                  Before you call this routine, the plHitSecNum field of the OPI_SECTINFO data structure
                  must point to an array of IDI_LONGs. The array must be at least as large as the number
                  of entries specified by the usLimit parameter.

                  Note: For Visual Basic users, you must call the VBOpiSliMmAlloc routine to create
                  the array to which the plHitSecNum field points. For more information, see “Calling
                  OpenAPI from Visual Basic.”

                  If you specify a record by using the pszKeyValSpec parameter, then the system will return
                  nothing in the plHitSecNum field of the OPI_SECTINFO data structure and the usCount
                  field will contain zero.




362  Reference
Reference  363

				
DOCUMENT INFO